Gateway actor ops

This page is the precise op reference for every actor in the gateway package.

system.gateway (SystemGatewayActor)

static accepts = {
  'gateway.status':   { description: 'Report gateway child readiness', options: 'object?' },
  'gateway.children': { description: 'List mounted gateway children', options: 'object?' },
};

Op	Returns
gateway.status	{ ok, mount, children: [{ id, mount, type, status, error? }] }
gateway.children	same as gateway.status (alias)

Today the only child is http (SystemGatewayHttpActor).

system.gateway.http (SystemGatewayHttpActor)

static accepts = {
  'gateway.http.status': {
    description: 'List Host-visible webapp route records for this system runtime',
    options: 'object?',
  },
  'gateway.http.resolve': {
    description: 'Resolve an HTTP pathname to a Matrix asset endpoint or Host runtime origin',
    pathname: 'string',
    appName: 'string?',
  },
  'gateway.http.request': {
    description: 'Relay a GET or HEAD request through Matrix asset endpoints',
    pathname: 'string',
    appName: 'string?',
    method: 'string?',
    headers: 'object?',
  },
};

gateway.http.status

Returns the current set of webapp routes:

{
  "ok": true,
  "mount": "system.gateway.http",
  "routeCount": 5,
  "routes": [/* IWebappRoute[] */]
}

gateway.http.resolve

Resolves a pathname (and optional appName hint) to a route plan:

{
  "ok": true,
  "pathname": "/apps/chat/index.html",
  "resolution": {
    "routeKind": "matrix-asset-endpoint",
    "appName": "chat",
    "assetPath": "index.html",
    "runtimeId": "RUNTIME-HOST-CHAT",
    "assetMount": "chat.http",
    "source": "host-runtime-record"
  }
}

If no route matches, resolution: null and error: "No Host runtime webapp route matched the request".

gateway.http.request

Performs the relay. Method must be GET or HEAD; otherwise 405.

{
  "ok": true,
  "statusCode": 200,
  "statusText": "OK",
  "headers": { "content-type": "text/javascript", ... },
  "bodyEncoding": "base64",
  "bodyBase64": "...",
  "resolution": { /* IHttpRouteResolution */ }
}

Errors:

Error	Cause
405 / "gateway.http.request only supports GET and HEAD"	Wrong method
400 / "gateway.http.request requires a non-empty pathname"	Missing pathname
404 / "No Host runtime webapp route matched the request"	No route
502 / "Matched webapp route has no Matrix asset endpoint"	Route record had neither assetMount nor origin
503 / "Gateway actor has no Matrix context"	Internal — actor not ready

<appName>.http (MatrixHttpAssetEndpointActor)

Mounted in each package's runtime, not in the gateway runtime. The mount path is <appName>.http (e.g. chat.http) or, when a runtime ID is provided, system.runtimes.<runtimeId>.http.

static accepts = {
  'http.asset.status': {
    description: 'Report the configured package asset endpoint',
    options: 'object?',
  },
  'http.asset.resolve': {
    description: 'Resolve an HTTP pathname to a package dist asset',
    pathname: 'string',
    appName: 'string?',
  },
  'http.asset.request': {
    description: 'Read a package dist asset and return an HTTP-shaped response',
    pathname: 'string',
    appName: 'string?',
    method: 'string?',
    headers: 'object?',
  },
};

http.asset.status

Returns the endpoint's config:

{
  "ok": true,
  "mount": "chat.http",
  "packageName": "@open-matrix/chat",
  "appName": "chat",
  "distDir": "/.../node_modules/@open-matrix/chat/dist/browser",
  "entryFile": "index.html"
}

http.asset.resolve

Resolves an HTTP pathname to the on-disk file path:

{
  "ok": true,
  "packageName": "@open-matrix/chat",
  "appName": "chat",
  "pathname": "/apps/chat/assets/index.js",
  "assetPath": "assets/index.js",
  "filePath": "/.../assets/index.js"
}

If the path does not resolve, ok: false with error: 'No package asset matched the request'.

http.asset.request

Reads the file and returns its contents (base64-encoded for binary safety):

{
  "ok": true,
  "statusCode": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "text/javascript; charset=utf-8",
    "content-length": "1234",
    "cache-control": "no-cache"
  },
  "bodyEncoding": "base64",
  "bodyBase64": "...",
  "packageName": "@open-matrix/chat",
  "appName": "chat",
  "assetPath": "assets/index.js"
}

For HEAD requests, the same response shape minus bodyEncoding / bodyBase64.

Errors:

Error	Cause
405 / "http.asset.request only supports GET and HEAD"	Wrong method
400 / "http.asset.request requires a non-empty pathname"	Missing pathname
404 / "No package asset matched the request"	File doesn't exist or path-traversal rejected
502 / "Asset response exceeded relay limit of 10485760 bytes"	File >10 MB

See also

• Route schema
• Overview / Gateway actor surface

Source: projects/matrix-3/packages/system-gateway-http/src/index.ts:80-383.