Hosting Gateway

Appearance

Route schema ​

This page is the type reference for everything the gateway carries about a route — from URL parsing through resolution to the asset endpoint.

IWebappRoute ​

Returned by gateway.http.status. Built from runtime metadata.

typescript
// system-gateway-http/src/index.ts:33-46
interface IWebappRoute {
  appName: string;
  runtimeId: string;
  packageName?: string;
  routePrefix: string;          // typically '/apps/<appName>/'
  displayName?: string;
  icon?: string;
  navOrder?: number;
  description?: string;
  shells?: readonly string[];
  source: 'host-runtime-record' | 'runtime-registry';
  assetMount?: string;          // e.g. 'chat.http'
  origin?: string;              // e.g. 'http://127.0.0.1:5173'
}

Either assetMount or origin (or both) must be set. A record with neither is dropped during construction — see _routeFromWebappRecord.

IHttpRouteResolution ​

Returned by gateway.http.resolve. Built by _resolveRoute.

typescript
// system-gateway-http/src/index.ts:54-63
interface IHttpRouteResolution {
  routeKind: 'matrix-asset-endpoint' | 'origin-backed-webapp';
  pathname: string;             // original request pathname
  appName: string;
  assetPath: string;            // pathname stripped of '/apps/<appName>/'
  runtimeId: string;
  source: IWebappRoute['source'];
  assetMount?: string;
  origin?: string;
}

routeKind:

  • matrix-asset-endpoint: route uses a <appName>.httpMatrixHttpAssetEndpointActor over Matrix RR.
  • origin-backed-webapp: route uses an HTTP origin and the gateway fetch()-es.

URL grammar parsed types ​

Three parsed types come from http-routing.ts. Each represents a different URL grammar.

IExplicitAuthorityWebappRoute ​

typescript
interface IExplicitAuthorityWebappRoute {
  email: string;
  authorityRoot: string;        // derived from email via deriveAddressRootFromEmail
  appName: string;
  remotePathname: string;       // '/apps/<appName>/<remainder>'
  publicAppPrefix: string;      // '/<email>/<appName>/'
  requiresTrailingSlashRedirect: boolean;
}

Produced by parseExplicitAuthorityWebappRoute(pathname). URL form:

/<email>/<appName>/<remainder>

IPublicNamespaceWebappRoute ​

typescript
interface IPublicNamespaceWebappRoute {
  publicNamespace: string;      // 'space.foo', 'domain.bar'
  appName: string;
  remotePathname: string;
  publicAppPrefix: string;
  requiresTrailingSlashRedirect: boolean;
}

Produced by parsePublicNamespaceWebappRoute(pathname). URL form:

/<publicNamespace>/<appName>/<remainder>
/<publicNamespace>/apps/<appName>/<remainder>

IRouteKeyWebappRoute ​

typescript
interface IRouteKeyWebappRoute {
  routeKey: string;             // 'alt.stories.ghost-stories.funny'
  appName: string;
  remotePathname: string;
  publicAppPrefix: string;
  requiresTrailingSlashRedirect: boolean;
}

Produced by parseRouteKeyWebappRoute(pathname). URL form:

/<routeKey>/<appName>/<remainder>

Asset endpoint config ​

typescript
// system-gateway-http/src/index.ts:26-31
interface IMatrixHttpAssetEndpointConfig {
  packageName: string;
  appName: string;
  distDir: string;              // absolute path resolved at mount
  entryFile: string;            // typically 'index.html'
}

This is what's set on the actor instance at mount time (via MatrixHttpAssetEndpointActor.assetEndpoint). The runtime fills it from the package's matrix.json.webapp block plus its install path.

Gateway HTTP response shape ​

IMatrixGatewayHttpResponse in http-routing.ts:38-48:

typescript
interface IMatrixGatewayHttpResponse {
  ok?: boolean;
  statusCode: number;
  statusText?: string;
  headers?: Record<string, unknown>;
  body?: string;
  bodyBase64?: string;
  bodyEncoding?: string;
  error?: string;
  resolution?: unknown;
}

This is the shape returned by gateway.http.request, http.asset.request, and the platform request handlers when they speak HTTP-shaped responses over Matrix.

Validators / patterns ​

typescript
// http-routing.ts:350-352
const PUBLIC_NAMESPACE_PATTERN =
  /^(space|domain|system)\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/;

const ROUTE_KEY_PATTERN =
  /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/;

const RESERVED_ROUTE_KEYS = new Set([
  'api', 'auth', 'login', 'logout', 'signup', 'setup', 'settings',
  'apps', 'app', 'assets', 'static', 'branding', 'nats-ws', 'matrix',
  'system', 'admin', 'root', 'support', 'docs', 'help', 'billing',
  'status', 'healthz', 'well-known', 'favicon.ico', 'manifest.json',
  'hivecast', 'open-matrix', 'me',
]);

A path's first segment must match the right pattern AND not be in RESERVED_ROUTE_KEYS (for routeKey routes specifically) for the parser to match.

See also ​

Source: projects/matrix-3/packages/system-gateway-http/src/index.ts:33-63, projects/matrix-3/packages/system-gateway-http/src/http-routing.ts:1-392.