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
-
Supports dynamic route registration from plugins via contributes.routes
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 { DispatcherConfig, DispatcherRoute } from '@objectstack/spec/api';
import type { DispatcherConfig, DispatcherRoute } from '@objectstack/spec/api';
// Validate data
const result = DispatcherConfig.parse(data);DispatcherConfig
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| routes | Object[] | ✅ | Route-to-service mappings |
| fallback | Enum<'404' | 'proxy' | 'custom'> | ✅ | Behavior when no route matches |
| proxyTarget | string | optional | Proxy target URL when fallback is "proxy" |
DispatcherRoute
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| prefix | string | ✅ | URL path prefix for routing (e.g. /api/v1/data) |
| service | Enum<'metadata' | 'data' | 'auth' | 'file-storage' | 'search' | 'cache' | 'queue' | 'automation' | 'graphql' | 'analytics' | 'realtime' | 'job' | 'notification' | 'ai' | 'i18n' | 'ui' | 'workflow'> | ✅ | Target core service name |
| authRequired | boolean | ✅ | Whether authentication is required |
| criticality | Enum<'required' | 'core' | 'optional'> | ✅ | Service criticality level for unavailability handling |
| permissions | string[] | optional | Required permissions for this route namespace |