Hosting Gateway

Appearance

Gateway actor surface ​

The gateway's actor side is two classes:

ClassMountPurpose
SystemGatewayActorsystem.gatewayParent actor; reports child status.
SystemGatewayHttpActorsystem.gateway.httpThe HTTP-side resolver and request relay.

Both are in projects/matrix-3/packages/system-gateway-http/src/index.ts.

SystemGatewayActor (parent) ​

typescript
// system-gateway-http/src/index.ts:221-260
class SystemGatewayActor extends MatrixActor {
  static description = 'System gateway parent actor.';

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

  protected async onBootstrap() {
    await this.addChild('http', SystemGatewayHttpActor);
  }
}

It exists to:

  • Mount the HTTP child actor under itself.
  • Provide a single status read-out covering all gateway children (today, just one).

If a future gateway adds non-HTTP children (e.g. WebRTC, gRPC), they would mount as siblings of http under the same parent.

SystemGatewayHttpActor ​

This is where the action is.

typescript
// system-gateway-http/src/index.ts:262-383
class SystemGatewayHttpActor extends MatrixActor {
  static description = 'Matrix HTTP gateway actor for package webapp routes.';

  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 the gateway knows about:

typescript
{
  ok: true,
  mount: 'system.gateway.http',
  routeCount: number,
  routes: IWebappRoute[]
}

Each IWebappRoute carries appName, runtimeId, routePrefix, optional assetMount or origin, and the route's source ('host-runtime-record' or 'runtime-registry').

gateway.http.resolve ​

Given a URL pathname (and optional appName), returns the route plan that would be selected:

typescript
{
  ok: true,
  pathname: string,
  resolution: {
    routeKind: 'matrix-asset-endpoint' | 'origin-backed-webapp',
    pathname: string,
    appName: string,
    assetPath: string,
    runtimeId: string,
    source: 'host-runtime-record' | 'runtime-registry',
    assetMount?: string,
    origin?: string,
  } | null
}

This is the read-only inspection op. Useful for debugging "why isn't /apps/foo/ working?" — the resolution tells you exactly which route, if any, matched.

gateway.http.request ​

Performs the actual relay. Same response shape as the asset-endpoint actor's http.asset.request, plus a resolution field showing which route was chosen.

This is what the HTTP listener calls when a request comes in for /apps/<appName>/.... It is also callable directly by other actors that want to introspect the byte response without going through HTTP.

MatrixHttpAssetEndpointActor (per-package) ​

Lives in the same package source file but mounts in each package's runtime, not in the gateway runtime. See Static assets for detail.

typescript
static accepts = {
  'http.asset.status':  { ... },
  'http.asset.resolve': { pathname, appName? },
  'http.asset.request': { pathname, appName?, method?, headers? },
};

The gateway calls http.asset.request on this mount during route relay.

Emissions ​

Neither SystemGatewayActor nor SystemGatewayHttpActor declares emissions today. They are pure request/reply actors. Webapp route changes happen implicitly through system.runtimes changes; the gateway re-reads on each request rather than emitting events.

Adding gateway.routes.changed is plausible target state but not in code today.

See also ​

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