Dispatcher schema — API Protocol reference

Defines how the ObjectStack HttpDispatcher routes incoming API requests to the correct kernel service based on URL prefix matching.

HttpDispatcher Protocol

Defines how the ObjectStack HttpDispatcher routes incoming API requests to the correct kernel service based on URL prefix matching.

The dispatcher is the central routing component that:

Matches incoming request URLs against registered route prefixes
Delegates to the corresponding CoreService implementation
Returns 503 Service Unavailable when a service is not registered
Serves prefixes registered by the kernel services above. Plugins that need a code handler mount it imperatively on the http.server service (resolve it from the plugin context on kernel:ready) — the manifest's contributes.routes key was removed in @objectstack/spec 17 (commit bc56e1881): nothing ever read it, and authoring it is now a tsc error and a parse error carrying that prescription.

Architecture alignment:

Kubernetes: API server aggregation layer
Eclipse: Extension registry routing
VS Code: Command palette routing

Source: packages/spec/src/api/dispatcher.zod.ts

TypeScript Usage

import { DispatcherConfigSchema, DispatcherErrorCode, DispatcherErrorResponseSchema, DispatcherRouteSchema } from '@objectstack/spec/api';
import type { DispatcherConfig, DispatcherErrorCode, DispatcherErrorResponse, DispatcherRoute } from '@objectstack/spec/api';

// Validate data
const result = DispatcherConfigSchema.parse(data);

DispatcherConfig

Properties

Property	Type	Required	Description
routes	`{ prefix: string; service: Enum<'metadata' \| 'data' \| 'auth' \| 'storage' \| 'file-storage' \| 'search' \| 'cache' \| …>; authRequired?: boolean; criticality?: Enum<'required' \| 'core' \| 'optional'>; … }[]`	✅	Route-to-service mappings
fallback	`Enum<'404' \| 'proxy' \| 'custom'>`	optional (default: `"404"`)	Behavior when no route matches
proxyTarget	`string`	optional	Proxy target URL when fallback is "proxy"

Nested Shape: `DispatcherConfig.routes[number]`

Property	Type	Required	Description
prefix	`string`	✅	URL path prefix for routing (e.g. /api/v1/data)
service	`Enum<'metadata' \| 'data' \| 'auth' \| 'storage' \| 'file-storage' \| 'search' \| 'cache' \| …>`	✅	Target core service name
authRequired	`boolean`	optional (default: `true`)	Whether authentication is required
criticality	`Enum<'required' \| 'core' \| 'optional'>`	optional (default: `"optional"`)	Service criticality level for unavailability handling
permissions	`string[]`	optional	Required permissions for this route namespace

DispatcherErrorCode

Route-resolution failure mode emitted in error.code

Allowed Values

ROUTE_NOT_FOUND
METHOD_NOT_ALLOWED
NOT_IMPLEMENTED
SERVICE_UNAVAILABLE

DispatcherErrorResponse

Properties

Property	Type	Required	Description
success	`false`	✅
error	`{ code: string; message: string; httpStatus?: integer; route?: string; … }`	✅

Nested Shape: `DispatcherErrorResponse.error`

Property	Type	Required	Description
code	`string`	✅	Machine-readable error code (e.g. ROUTE_NOT_FOUND, permission_denied)
message	`string`	✅	Human-readable error message
httpStatus	`integer`	optional	HTTP status code (404, 405, 501, 503, …)
route	`string`	optional	Requested route path
service	`string`	optional	Target service name, if resolvable
hint	`string`	optional	Actionable hint for the developer (e.g., "Install plugin-workflow")
details	`any`	optional	Additional error context

DispatcherRoute

Properties

Property	Type	Required	Description
prefix	`string`	✅	URL path prefix for routing (e.g. /api/v1/data)
service	`Enum<'metadata' \| 'data' \| 'auth' \| 'storage' \| 'file-storage' \| 'search' \| 'cache' \| 'queue' \| 'automation' \| 'analytics' \| 'realtime' \| 'job' \| 'notification' \| 'ai' \| 'i18n' \| 'ui'>`	✅	Target core service name
authRequired	`boolean`	optional (default: `true`)	Whether authentication is required
criticality	`Enum<'required' \| 'core' \| 'optional'>`	optional (default: `"optional"`)	Service criticality level for unavailability handling
permissions	`string[]`	optional	Required permissions for this route namespace

Dispatcher schema — API Protocol reference

On this page