---
title: Dispatcher
description: Dispatcher protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

# 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:

1. Matches incoming request URLs against registered route prefixes

2. Delegates to the corresponding CoreService implementation

3. Returns 503 Service Unavailable when a service is not registered

4. 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

<Callout type="info">
**Source:** `packages/spec/src/api/dispatcher.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { DispatcherConfig, DispatcherErrorCode, DispatcherErrorResponse, DispatcherRoute } from '@objectstack/spec/api';
import type { DispatcherConfig, DispatcherErrorCode, DispatcherErrorResponse, 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" |


---

## DispatcherErrorCode

404 = route not found, 405 = method not allowed, 501 = not implemented (stub), 503 = service unavailable

### Allowed Values

* `404`
* `405`
* `501`
* `503`


---

## DispatcherErrorResponse

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ |  |
| **error** | `Object` | ✅ |  |


---

## 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 |


---

