Skip to content

Commit 7e90ad5

Browse files
Copilothotlong
Copilot
and
hotlong
committed
docs: Update PROTOCOL_MAP.md to document dispatcher and promote discovery
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent 903b900 commit 7e90ad5

27 files changed

Lines changed: 820 additions & 29 deletions

‎packages/spec/PROTOCOL_MAP.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,8 @@ This document serves as the **Grand Map** of the ObjectStack specification. It l
155155
| File | Status | Description |
156156
| :--- | :--- | :--- |
157157
| [`protocol.zod.ts`](src/api/protocol.zod.ts) | ⭐ | **Stack Protocol**. valid requests and responses for the platform. |
158+
| [`dispatcher.zod.ts`](src/api/dispatcher.zod.ts) | ⭐ | **HttpDispatcher**. Route-to-service mapping for API routing. |
159+
| [`discovery.zod.ts`](src/api/discovery.zod.ts) | ⭐ | **Service Discovery**. Service registration and API routes discovery. |
158160
| [`endpoint.zod.ts`](src/api/endpoint.zod.ts) | | **API Endpoints**. REST API route definitions. |
159161
| [`graphql.zod.ts`](src/api/graphql.zod.ts) | | **GraphQL**. Schema and resolver configuration. |
160162
| [`rest-server.zod.ts`](src/api/rest-server.zod.ts) | | **REST Server**. REST-specific server settings. |
@@ -166,7 +168,6 @@ This document serves as the **Grand Map** of the ObjectStack specification. It l
166168
| [`router.zod.ts`](src/api/router.zod.ts) | | **Routing**. API Gateway routing rules. |
167169
| [`http-cache.zod.ts`](src/api/http-cache.zod.ts) | | **HTTP Cache**. Cache-Control headers and CDNs. |
168170
| [`errors.zod.ts`](src/api/errors.zod.ts) | | **Error Handling**. Standard error response formats. |
169-
| [`discovery.zod.ts`](src/api/discovery.zod.ts) | | **Service Discovery**. Service registration for microservices. |
170171
| [`metadata.zod.ts`](src/api/metadata.zod.ts) | | **Metadata API**. Endpoints for schema retrieval. |
171172
| [`odata.zod.ts`](src/api/odata.zod.ts) | | **OData**. OData protocol support. |
172173
| [`batch.zod.ts`](src/api/batch.zod.ts) | | **Batch API**. Bulk request processing. |

‎packages/spec/json-schema/api/ApiCapabilities.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,26 @@
2929
"type": "boolean",
3030
"default": false,
3131
"description": "Is Hub management enabled?"
32+
},
33+
"ai": {
34+
"type": "boolean",
35+
"default": false,
36+
"description": "Is the AI engine enabled?"
37+
},
38+
"workflow": {
39+
"type": "boolean",
40+
"default": false,
41+
"description": "Is the Workflow engine enabled?"
42+
},
43+
"notifications": {
44+
"type": "boolean",
45+
"default": false,
46+
"description": "Is the Notification service enabled?"
47+
},
48+
"i18n": {
49+
"type": "boolean",
50+
"default": false,
51+
"description": "Is the i18n service enabled?"
3252
}
3353
},
3454
"additionalProperties": false

‎packages/spec/json-schema/api/ApiRoutes.json‎

Lines changed: 32 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,39 +6,63 @@
66
"properties": {
77
"data": {
88
"type": "string",
9-
"description": "e.g. /api/data"
9+
"description": "e.g. /api/v1/data"
1010
},
1111
"metadata": {
1212
"type": "string",
13-
"description": "e.g. /api/meta"
13+
"description": "e.g. /api/v1/meta"
1414
},
1515
"ui": {
1616
"type": "string",
17-
"description": "e.g. /api/ui"
17+
"description": "e.g. /api/v1/ui"
1818
},
1919
"auth": {
2020
"type": "string",
21-
"description": "e.g. /api/auth"
21+
"description": "e.g. /api/v1/auth"
2222
},
2323
"automation": {
2424
"type": "string",
25-
"description": "e.g. /api/automation"
25+
"description": "e.g. /api/v1/automation"
2626
},
2727
"storage": {
2828
"type": "string",
29-
"description": "e.g. /api/storage"
29+
"description": "e.g. /api/v1/storage"
3030
},
3131
"analytics": {
3232
"type": "string",
33-
"description": "e.g. /api/analytics"
33+
"description": "e.g. /api/v1/analytics"
3434
},
3535
"hub": {
3636
"type": "string",
37-
"description": "e.g. /api/hub"
37+
"description": "e.g. /api/v1/hub"
3838
},
3939
"graphql": {
4040
"type": "string",
4141
"description": "e.g. /graphql"
42+
},
43+
"packages": {
44+
"type": "string",
45+
"description": "e.g. /api/v1/packages"
46+
},
47+
"workflow": {
48+
"type": "string",
49+
"description": "e.g. /api/v1/workflow"
50+
},
51+
"realtime": {
52+
"type": "string",
53+
"description": "e.g. /api/v1/realtime"
54+
},
55+
"notifications": {
56+
"type": "string",
57+
"description": "e.g. /api/v1/notifications"
58+
},
59+
"ai": {
60+
"type": "string",
61+
"description": "e.g. /api/v1/ai"
62+
},
63+
"i18n": {
64+
"type": "string",
65+
"description": "e.g. /api/v1/i18n"
4266
}
4367
},
4468
"required": [

‎packages/spec/json-schema/api/CompileManifestResponse.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -412,6 +412,36 @@
412412
"additionalProperties": false
413413
},
414414
"description": "Query Function contributions"
415+
},
416+
"routes": {
417+
"type": "array",
418+
"items": {
419+
"type": "object",
420+
"properties": {
421+
"prefix": {
422+
"type": "string",
423+
"pattern": "^\\/",
424+
"description": "API path prefix"
425+
},
426+
"service": {
427+
"type": "string",
428+
"description": "Service name this plugin provides"
429+
},
430+
"methods": {
431+
"type": "array",
432+
"items": {
433+
"type": "string"
434+
},
435+
"description": "Protocol method names implemented (e.g. [\"aiNlq\", \"aiChat\"])"
436+
}
437+
},
438+
"required": [
439+
"prefix",
440+
"service"
441+
],
442+
"additionalProperties": false
443+
},
444+
"description": "API route contributions to HttpDispatcher"
415445
}
416446
},
417447
"additionalProperties": false,

‎packages/spec/json-schema/api/DisablePackageResponse.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -353,6 +353,36 @@
353353
"additionalProperties": false
354354
},
355355
"description": "Query Function contributions"
356+
},
357+
"routes": {
358+
"type": "array",
359+
"items": {
360+
"type": "object",
361+
"properties": {
362+
"prefix": {
363+
"type": "string",
364+
"pattern": "^\\/",
365+
"description": "API path prefix"
366+
},
367+
"service": {
368+
"type": "string",
369+
"description": "Service name this plugin provides"
370+
},
371+
"methods": {
372+
"type": "array",
373+
"items": {
374+
"type": "string"
375+
},
376+
"description": "Protocol method names implemented (e.g. [\"aiNlq\", \"aiChat\"])"
377+
}
378+
},
379+
"required": [
380+
"prefix",
381+
"service"
382+
],
383+
"additionalProperties": false
384+
},
385+
"description": "API route contributions to HttpDispatcher"
356386
}
357387
},
358388
"additionalProperties": false,

‎packages/spec/json-schema/api/Discovery.json‎

Lines changed: 52 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -23,39 +23,63 @@
2323
"properties": {
2424
"data": {
2525
"type": "string",
26-
"description": "e.g. /api/data"
26+
"description": "e.g. /api/v1/data"
2727
},
2828
"metadata": {
2929
"type": "string",
30-
"description": "e.g. /api/meta"
30+
"description": "e.g. /api/v1/meta"
3131
},
3232
"ui": {
3333
"type": "string",
34-
"description": "e.g. /api/ui"
34+
"description": "e.g. /api/v1/ui"
3535
},
3636
"auth": {
3737
"type": "string",
38-
"description": "e.g. /api/auth"
38+
"description": "e.g. /api/v1/auth"
3939
},
4040
"automation": {
4141
"type": "string",
42-
"description": "e.g. /api/automation"
42+
"description": "e.g. /api/v1/automation"
4343
},
4444
"storage": {
4545
"type": "string",
46-
"description": "e.g. /api/storage"
46+
"description": "e.g. /api/v1/storage"
4747
},
4848
"analytics": {
4949
"type": "string",
50-
"description": "e.g. /api/analytics"
50+
"description": "e.g. /api/v1/analytics"
5151
},
5252
"hub": {
5353
"type": "string",
54-
"description": "e.g. /api/hub"
54+
"description": "e.g. /api/v1/hub"
5555
},
5656
"graphql": {
5757
"type": "string",
5858
"description": "e.g. /graphql"
59+
},
60+
"packages": {
61+
"type": "string",
62+
"description": "e.g. /api/v1/packages"
63+
},
64+
"workflow": {
65+
"type": "string",
66+
"description": "e.g. /api/v1/workflow"
67+
},
68+
"realtime": {
69+
"type": "string",
70+
"description": "e.g. /api/v1/realtime"
71+
},
72+
"notifications": {
73+
"type": "string",
74+
"description": "e.g. /api/v1/notifications"
75+
},
76+
"ai": {
77+
"type": "string",
78+
"description": "e.g. /api/v1/ai"
79+
},
80+
"i18n": {
81+
"type": "string",
82+
"description": "e.g. /api/v1/i18n"
5983
}
6084
},
6185
"required": [
@@ -93,6 +117,26 @@
93117
"type": "boolean",
94118
"default": false,
95119
"description": "Is Hub management enabled?"
120+
},
121+
"ai": {
122+
"type": "boolean",
123+
"default": false,
124+
"description": "Is the AI engine enabled?"
125+
},
126+
"workflow": {
127+
"type": "boolean",
128+
"default": false,
129+
"description": "Is the Workflow engine enabled?"
130+
},
131+
"notifications": {
132+
"type": "boolean",
133+
"default": false,
134+
"description": "Is the Notification service enabled?"
135+
},
136+
"i18n": {
137+
"type": "boolean",
138+
"default": false,
139+
"description": "Is the i18n service enabled?"
96140
}
97141
},
98142
"additionalProperties": false

‎packages/spec/json-schema/api/DispatcherConfig.json‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
{
2+
"$ref": "#/definitions/DispatcherConfig",
3+
"definitions": {
4+
"DispatcherConfig": {
5+
"type": "object",
6+
"properties": {
7+
"routes": {
8+
"type": "array",
9+
"items": {
10+
"type": "object",
11+
"properties": {
12+
"prefix": {
13+
"type": "string",
14+
"pattern": "^\\/",
15+
"description": "URL path prefix for routing (e.g. /api/v1/data)"
16+
},
17+
"service": {
18+
"type": "string",
19+
"enum": [
20+
"metadata",
21+
"data",
22+
"auth",
23+
"file-storage",
24+
"search",
25+
"cache",
26+
"queue",
27+
"automation",
28+
"graphql",
29+
"analytics",
30+
"hub",
31+
"realtime",
32+
"job",
33+
"notification",
34+
"ai",
35+
"i18n",
36+
"ui",
37+
"workflow"
38+
],
39+
"description": "Target core service name"
40+
},
41+
"authRequired": {
42+
"type": "boolean",
43+
"default": true,
44+
"description": "Whether authentication is required"
45+
},
46+
"criticality": {
47+
"type": "string",
48+
"enum": [
49+
"required",
50+
"core",
51+
"optional"
52+
],
53+
"default": "optional",
54+
"description": "Service criticality level for unavailability handling"
55+
},
56+
"permissions": {
57+
"type": "array",
58+
"items": {
59+
"type": "string"
60+
},
61+
"description": "Required permissions for this route namespace"
62+
}
63+
},
64+
"required": [
65+
"prefix",
66+
"service"
67+
],
68+
"additionalProperties": false
69+
},
70+
"description": "Route-to-service mappings"
71+
},
72+
"fallback": {
73+
"type": "string",
74+
"enum": [
75+
"404",
76+
"proxy",
77+
"custom"
78+
],
79+
"default": "404",
80+
"description": "Behavior when no route matches"
81+
},
82+
"proxyTarget": {
83+
"type": "string",
84+
"format": "uri",
85+
"description": "Proxy target URL when fallback is \"proxy\""
86+
}
87+
},
88+
"required": [
89+
"routes"
90+
],
91+
"additionalProperties": false
92+
}
93+
},
94+
"$schema": "http://json-schema.org/draft-07/schema#"
95+
}

0 commit comments

Comments
 (0)