ObjectStackDispatcher
Dispatcher protocol schemas
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.serverservice (resolve it from the plugin context onkernel:ready), NOT through the manifest'scontributes.routeskey — nothing reads that key, so an entry there parses cleanly and serves nothing.
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" |
DispatcherErrorCode
Route-resolution failure mode emitted in error.code
Allowed Values
ROUTE_NOT_FOUNDMETHOD_NOT_ALLOWEDNOT_IMPLEMENTEDSERVICE_UNAVAILABLE
DispatcherErrorResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | false | ✅ | |
| error | { code: string; message: string; httpStatus?: integer; route?: string; … } | ✅ |
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 |