@entifix/service-shell 0.10.2 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/README.md +1 -4
  2. package/dist/auth/index.d.ts +1 -0
  3. package/dist/auth/index.d.ts.map +1 -1
  4. package/dist/auth/index.js +1 -0
  5. package/dist/auth/index.js.map +1 -1
  6. package/dist/auth/require-organization.d.ts +1 -1
  7. package/dist/auth/require-organization.d.ts.map +1 -1
  8. package/dist/auth/require-organization.js.map +1 -1
  9. package/dist/auth/require-principal.d.ts +9 -49
  10. package/dist/auth/require-principal.d.ts.map +1 -1
  11. package/dist/auth/require-principal.js +21 -15
  12. package/dist/auth/require-principal.js.map +1 -1
  13. package/dist/auth/require-service-crossing.d.ts.map +1 -1
  14. package/dist/auth/require-service-crossing.js +3 -13
  15. package/dist/auth/require-service-crossing.js.map +1 -1
  16. package/dist/auth/shared-token.d.ts +2 -0
  17. package/dist/auth/shared-token.d.ts.map +1 -1
  18. package/dist/auth/shared-token.js +2 -2
  19. package/dist/auth/shared-token.js.map +1 -1
  20. package/dist/auth/verified-context.d.ts +24 -0
  21. package/dist/auth/verified-context.d.ts.map +1 -0
  22. package/dist/auth/verified-context.js +40 -0
  23. package/dist/auth/verified-context.js.map +1 -0
  24. package/dist/entity-facet-routes.d.ts +7 -1
  25. package/dist/entity-facet-routes.d.ts.map +1 -1
  26. package/dist/entity-facet-routes.js +8 -5
  27. package/dist/entity-facet-routes.js.map +1 -1
  28. package/dist/entity-metadata-route.d.ts +2 -1
  29. package/dist/entity-metadata-route.d.ts.map +1 -1
  30. package/dist/entity-metadata-route.js +20 -3
  31. package/dist/entity-metadata-route.js.map +1 -1
  32. package/dist/entity-route-guard.d.ts +5 -3
  33. package/dist/entity-route-guard.d.ts.map +1 -1
  34. package/dist/entity-route-guard.js +12 -6
  35. package/dist/entity-route-guard.js.map +1 -1
  36. package/dist/entity-routes.d.ts +13 -1
  37. package/dist/entity-routes.d.ts.map +1 -1
  38. package/dist/entity-routes.js +20 -6
  39. package/dist/entity-routes.js.map +1 -1
  40. package/dist/http-api/build-api.d.ts +78 -0
  41. package/dist/http-api/build-api.d.ts.map +1 -0
  42. package/dist/http-api/build-api.js +189 -0
  43. package/dist/http-api/build-api.js.map +1 -0
  44. package/dist/http-api/entity-api.d.ts +69 -0
  45. package/dist/http-api/entity-api.d.ts.map +1 -0
  46. package/dist/http-api/entity-api.js +522 -0
  47. package/dist/http-api/entity-api.js.map +1 -0
  48. package/dist/http-api/guards.d.ts +92 -0
  49. package/dist/http-api/guards.d.ts.map +1 -0
  50. package/dist/http-api/guards.js +131 -0
  51. package/dist/http-api/guards.js.map +1 -0
  52. package/dist/http-api/index.d.ts +6 -0
  53. package/dist/http-api/index.d.ts.map +1 -0
  54. package/dist/http-api/index.js +7 -0
  55. package/dist/http-api/index.js.map +1 -0
  56. package/dist/http-api/problem-codec.d.ts +14 -0
  57. package/dist/http-api/problem-codec.d.ts.map +1 -0
  58. package/dist/http-api/problem-codec.js +26 -0
  59. package/dist/http-api/problem-codec.js.map +1 -0
  60. package/dist/http-api/service-group.d.ts +74 -0
  61. package/dist/http-api/service-group.d.ts.map +1 -0
  62. package/dist/http-api/service-group.js +168 -0
  63. package/dist/http-api/service-group.js.map +1 -0
  64. package/dist/idempotency.d.ts +64 -0
  65. package/dist/idempotency.d.ts.map +1 -0
  66. package/dist/idempotency.js +112 -0
  67. package/dist/idempotency.js.map +1 -0
  68. package/dist/index.d.ts +4 -2
  69. package/dist/index.d.ts.map +1 -1
  70. package/dist/index.js +4 -2
  71. package/dist/index.js.map +1 -1
  72. package/dist/make-service.d.ts +39 -6
  73. package/dist/make-service.d.ts.map +1 -1
  74. package/dist/make-service.js +54 -16
  75. package/dist/make-service.js.map +1 -1
  76. package/dist/metadata-composition.d.ts +28 -0
  77. package/dist/metadata-composition.d.ts.map +1 -0
  78. package/dist/metadata-composition.js +68 -0
  79. package/dist/metadata-composition.js.map +1 -0
  80. package/dist/narrowing.d.ts +13 -0
  81. package/dist/narrowing.d.ts.map +1 -0
  82. package/dist/narrowing.js +34 -0
  83. package/dist/narrowing.js.map +1 -0
  84. package/dist/respond.d.ts +6 -4
  85. package/dist/respond.d.ts.map +1 -1
  86. package/dist/respond.js +11 -7
  87. package/dist/respond.js.map +1 -1
  88. package/dist/serve-test-service.d.ts +2 -1
  89. package/dist/serve-test-service.d.ts.map +1 -1
  90. package/dist/serve-test-service.js.map +1 -1
  91. package/dist/sse.d.ts +7 -4
  92. package/dist/sse.d.ts.map +1 -1
  93. package/dist/sse.js +21 -5
  94. package/dist/sse.js.map +1 -1
  95. package/package.json +7 -6
  96. package/dist/health-routes.d.ts +0 -24
  97. package/dist/health-routes.d.ts.map +0 -1
  98. package/dist/health-routes.js +0 -86
  99. package/dist/health-routes.js.map +0 -1
  100. package/dist/service-description-route.d.ts +0 -66
  101. package/dist/service-description-route.d.ts.map +0 -1
  102. package/dist/service-description-route.js +0 -60
  103. package/dist/service-description-route.js.map +0 -1
@@ -0,0 +1,64 @@
1
+ import { IdempotencyStoreTag } from '@entifix/business';
2
+ import { Effect } from 'effect';
3
+ import { HttpServerRequest, HttpServerResponse } from 'effect/http';
4
+ /** Set on a response replayed from the store, so a caller can tell. */
5
+ export declare const IDEMPOTENT_REPLAY_HEADER = "idempotent-replayed";
6
+ /** Marks a handler as guarded, for {@link assertRetriedRoutesIdempotent}. */
7
+ declare const IDEMPOTENT: unique symbol;
8
+ /**
9
+ * The fingerprint of a request: SHA-256 over its concrete target and its body
10
+ * as canonical JSON, or as raw text when it is not JSON. It is what tells a
11
+ * retry from a different request that reused a key.
12
+ *
13
+ * The target is the **concrete** method and path, not the route's template:
14
+ * one key reused on `/api/order/o1` and `/api/order/o2` is two requests, and
15
+ * hashing only the template would replay the first order's answer for the
16
+ * second.
17
+ */
18
+ export declare const requestFingerprint: (target: string, body: string) => string;
19
+ export interface IdempotencyKeyOptions {
20
+ /** The route's identity in the dedup key: `POST /api/payment`. */
21
+ readonly route: string;
22
+ /**
23
+ * Who is calling: the principal's id on a session route, the crossing caller
24
+ * on a participant route. Two callers choosing one key never collide.
25
+ */
26
+ readonly caller: string;
27
+ }
28
+ /**
29
+ * Makes a write route idempotent on its `Idempotency-Key`
30
+ * (draft-ietf-httpapi-idempotency-key-header), with the store the composition
31
+ * root provides as {@link IdempotencyStoreTag}.
32
+ *
33
+ * - no key, or one that is not an RFC 9651 String → `400 idempotencyKeyMissing`;
34
+ * - a key in use with another body → `422 idempotencyKeyReused`;
35
+ * - a key whose first request has not finished → `409 idempotencyKeyInFlight`;
36
+ * - a key whose first request finished → that response, replayed.
37
+ *
38
+ * An answer — any response below `500` — is remembered. A `5xx`, a failure or a
39
+ * defect gives the key back, because none of them is an answer and the retry
40
+ * the key exists for must be allowed to try again.
41
+ */
42
+ export declare const requireIdempotencyKey: (options: IdempotencyKeyOptions) => <E, R>(handler: Effect.Effect<HttpServerResponse.HttpServerResponse, E, R>) => Effect.Effect<HttpServerResponse.HttpServerResponse, import("@entifix/core").StoreFailure | import("effect/http/HttpServerError").HttpServerError | E, IdempotencyStoreTag | HttpServerRequest.HttpServerRequest | R> & {
43
+ [IDEMPOTENT]: true;
44
+ };
45
+ /** Whether a handler was built through {@link requireIdempotencyKey}. */
46
+ export declare const isIdempotentHandler: (handler: unknown) => boolean;
47
+ /** One route a service mounts, as the mount check sees it. */
48
+ export interface MountedRoute {
49
+ readonly method: string;
50
+ readonly path: string;
51
+ readonly handler: unknown;
52
+ }
53
+ /**
54
+ * Fails the build — throws at mount — when a route a flow Activity retries is
55
+ * not guarded by {@link requireIdempotencyKey}. A retried write without a key
56
+ * is a write that runs twice; finding that out from a duplicate capture is the
57
+ * outcome this check exists to prevent.
58
+ */
59
+ export declare const assertRetriedRoutesIdempotent: (routes: readonly MountedRoute[], retried: readonly {
60
+ readonly method: string;
61
+ readonly path: string;
62
+ }[]) => void;
63
+ export {};
64
+ //# sourceMappingURL=idempotency.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,mBAAmB,CAAC;AAQ7E,OAAO,EAAE,MAAM,EAAQ,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAIpE,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAE9D,6EAA6E;AAC7E,QAAA,MAAM,UAAU,eAAkD,CAAC;AAiBnE;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,KAAG,MAQjE,CAAC;AAgBF,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,GAC/B,SAAS,qBAAqB,MAC9B,CAAC,EAAE,CAAC,EACH,SAAS,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,kBAAkB,EAAE,CAAC,EAAE,CAAC,CAAC;;CA+CpE,CAAC;AAEJ,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,GAAI,SAAS,OAAO,KAAG,OAGI,CAAC;AAE5D,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,GACxC,QAAQ,SAAS,YAAY,EAAE,EAC/B,SAAS,SAAS;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,KACrE,IAcF,CAAC"}
@@ -0,0 +1,112 @@
1
+ import { _ as _extends } from "@swc/helpers/_/_extends";
2
+ import { createHash } from 'node:crypto';
3
+ import { IdempotencyStoreTag } from '@entifix/business';
4
+ import { IDEMPOTENCY_KEY_HEADER, IdempotencyKeyInFlight, IdempotencyKeyMissing, IdempotencyKeyReused, parseIdempotencyKey } from '@entifix/core';
5
+ import { Effect, Exit } from 'effect';
6
+ import { HttpServerRequest, HttpServerResponse } from 'effect/http';
7
+ import { problemResponse } from './respond.js';
8
+ /** Set on a response replayed from the store, so a caller can tell. */ export const IDEMPOTENT_REPLAY_HEADER = 'idempotent-replayed';
9
+ /** Marks a handler as guarded, for {@link assertRetriedRoutesIdempotent}. */ const IDEMPOTENT = Symbol.for('@entifix/service-shell/idempotent');
10
+ /** Sorted keys at every depth, so two equal bodies hash equally whatever their key order. */ const canonical = (value)=>Array.isArray(value) ? value.map(canonical) : value !== null && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map((key)=>[
11
+ key,
12
+ canonical(value[key])
13
+ ])) : value;
14
+ /**
15
+ * The fingerprint of a request: SHA-256 over its concrete target and its body
16
+ * as canonical JSON, or as raw text when it is not JSON. It is what tells a
17
+ * retry from a different request that reused a key.
18
+ *
19
+ * The target is the **concrete** method and path, not the route's template:
20
+ * one key reused on `/api/order/o1` and `/api/order/o2` is two requests, and
21
+ * hashing only the template would replay the first order's answer for the
22
+ * second.
23
+ */ export const requestFingerprint = (target, body)=>{
24
+ let text = body;
25
+ try {
26
+ text = JSON.stringify(canonical(JSON.parse(body)));
27
+ } catch (unused) {
28
+ // Not JSON: the bytes are the request.
29
+ }
30
+ return createHash('sha256').update(`${target}\n${text}`).digest('hex');
31
+ };
32
+ /** A response as it can be stored; `undefined` for a body that cannot be replayed. */ const storable = (response)=>{
33
+ const { body } = response;
34
+ if (body._tag === 'Empty') return {
35
+ status: response.status,
36
+ body: ''
37
+ };
38
+ if (body._tag !== 'Uint8Array') return undefined;
39
+ return {
40
+ status: response.status,
41
+ contentType: body.contentType,
42
+ body: new TextDecoder().decode(body.body)
43
+ };
44
+ };
45
+ /**
46
+ * Makes a write route idempotent on its `Idempotency-Key`
47
+ * (draft-ietf-httpapi-idempotency-key-header), with the store the composition
48
+ * root provides as {@link IdempotencyStoreTag}.
49
+ *
50
+ * - no key, or one that is not an RFC 9651 String → `400 idempotencyKeyMissing`;
51
+ * - a key in use with another body → `422 idempotencyKeyReused`;
52
+ * - a key whose first request has not finished → `409 idempotencyKeyInFlight`;
53
+ * - a key whose first request finished → that response, replayed.
54
+ *
55
+ * An answer — any response below `500` — is remembered. A `5xx`, a failure or a
56
+ * defect gives the key back, because none of them is an answer and the retry
57
+ * the key exists for must be allowed to try again.
58
+ */ export const requireIdempotencyKey = (options)=>(handler)=>{
59
+ const guarded = Effect.gen(function*() {
60
+ const request = yield* HttpServerRequest.HttpServerRequest;
61
+ const key = parseIdempotencyKey(request.headers[IDEMPOTENCY_KEY_HEADER]);
62
+ if (key === undefined) return problemResponse(new IdempotencyKeyMissing());
63
+ // The body is cached by the request, so the handler reads it again.
64
+ // A body that cannot be read cannot be fingerprinted: that failure is the
65
+ // transport's, and it travels as one.
66
+ const body = yield* request.text;
67
+ const fingerprint = requestFingerprint(`${request.method} ${request.url.split('?')[0]}`, body);
68
+ const dedupKey = `${options.caller}|${options.route}|${key}`;
69
+ const store = yield* IdempotencyStoreTag;
70
+ const claim = yield* store.claim(dedupKey, fingerprint);
71
+ if (claim._tag === 'existing') {
72
+ const { record } = claim;
73
+ if (record.fingerprint !== fingerprint) return problemResponse(new IdempotencyKeyReused());
74
+ if (record.state === 'inFlight' || record.response === undefined) return problemResponse(new IdempotencyKeyInFlight());
75
+ return HttpServerResponse.text(record.response.body, _extends({
76
+ status: record.response.status
77
+ }, record.response.contentType === undefined ? {} : {
78
+ contentType: record.response.contentType
79
+ }, {
80
+ headers: {
81
+ [IDEMPOTENT_REPLAY_HEADER]: 'true'
82
+ }
83
+ }));
84
+ }
85
+ const exit = yield* Effect.exit(handler);
86
+ if (Exit.isSuccess(exit)) {
87
+ const stored = storable(exit.value);
88
+ yield* stored === undefined || stored.status >= 500 ? store.release(dedupKey) : store.complete(dedupKey, stored);
89
+ return exit.value;
90
+ }
91
+ yield* store.release(dedupKey);
92
+ return yield* exit;
93
+ });
94
+ return Object.assign(guarded, {
95
+ [IDEMPOTENT]: true
96
+ });
97
+ };
98
+ /** Whether a handler was built through {@link requireIdempotencyKey}. */ export const isIdempotentHandler = (handler)=>typeof handler === 'object' && handler !== null && handler[IDEMPOTENT] === true;
99
+ /**
100
+ * Fails the build — throws at mount — when a route a flow Activity retries is
101
+ * not guarded by {@link requireIdempotencyKey}. A retried write without a key
102
+ * is a write that runs twice; finding that out from a duplicate capture is the
103
+ * outcome this check exists to prevent.
104
+ */ export const assertRetriedRoutesIdempotent = (routes, retried)=>{
105
+ const unguarded = retried.filter((target)=>{
106
+ const route = routes.find((candidate)=>candidate.method.toUpperCase() === target.method.toUpperCase() && candidate.path === target.path);
107
+ return route === undefined || !isIdempotentHandler(route.handler);
108
+ });
109
+ if (unguarded.length > 0) throw new Error('these routes are retried by a flow and are not idempotent on an Idempotency-Key: ' + unguarded.map((route)=>`${route.method} ${route.path}`).join(', '));
110
+ };
111
+
112
+ //# sourceMappingURL=idempotency.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/idempotency.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\n\nimport { IdempotencyStoreTag, type StoredResponse } from '@entifix/business';\nimport {\n IDEMPOTENCY_KEY_HEADER,\n IdempotencyKeyInFlight,\n IdempotencyKeyMissing,\n IdempotencyKeyReused,\n parseIdempotencyKey,\n} from '@entifix/core';\nimport { Effect, Exit } from 'effect';\nimport { HttpServerRequest, HttpServerResponse } from 'effect/http';\n\nimport { problemResponse } from './respond.js';\n\n/** Set on a response replayed from the store, so a caller can tell. */\nexport const IDEMPOTENT_REPLAY_HEADER = 'idempotent-replayed';\n\n/** Marks a handler as guarded, for {@link assertRetriedRoutesIdempotent}. */\nconst IDEMPOTENT = Symbol.for('@entifix/service-shell/idempotent');\n\n/** Sorted keys at every depth, so two equal bodies hash equally whatever their key order. */\nconst canonical = (value: unknown): unknown =>\n Array.isArray(value)\n ? value.map(canonical)\n : value !== null && typeof value === 'object'\n ? Object.fromEntries(\n Object.keys(value)\n .sort()\n .map(key => [\n key,\n canonical((value as Record<string, unknown>)[key]),\n ]),\n )\n : value;\n\n/**\n * The fingerprint of a request: SHA-256 over its concrete target and its body\n * as canonical JSON, or as raw text when it is not JSON. It is what tells a\n * retry from a different request that reused a key.\n *\n * The target is the **concrete** method and path, not the route's template:\n * one key reused on `/api/order/o1` and `/api/order/o2` is two requests, and\n * hashing only the template would replay the first order's answer for the\n * second.\n */\nexport const requestFingerprint = (target: string, body: string): string => {\n let text = body;\n try {\n text = JSON.stringify(canonical(JSON.parse(body)));\n } catch {\n // Not JSON: the bytes are the request.\n }\n return createHash('sha256').update(`${target}\\n${text}`).digest('hex');\n};\n\n/** A response as it can be stored; `undefined` for a body that cannot be replayed. */\nconst storable = (\n response: HttpServerResponse.HttpServerResponse,\n): StoredResponse | undefined => {\n const { body } = response;\n if (body._tag === 'Empty') return { status: response.status, body: '' };\n if (body._tag !== 'Uint8Array') return undefined;\n return {\n status: response.status,\n contentType: body.contentType,\n body: new TextDecoder().decode(body.body),\n };\n};\n\nexport interface IdempotencyKeyOptions {\n /** The route's identity in the dedup key: `POST /api/payment`. */\n readonly route: string;\n /**\n * Who is calling: the principal's id on a session route, the crossing caller\n * on a participant route. Two callers choosing one key never collide.\n */\n readonly caller: string;\n}\n\n/**\n * Makes a write route idempotent on its `Idempotency-Key`\n * (draft-ietf-httpapi-idempotency-key-header), with the store the composition\n * root provides as {@link IdempotencyStoreTag}.\n *\n * - no key, or one that is not an RFC 9651 String → `400 idempotencyKeyMissing`;\n * - a key in use with another body → `422 idempotencyKeyReused`;\n * - a key whose first request has not finished → `409 idempotencyKeyInFlight`;\n * - a key whose first request finished → that response, replayed.\n *\n * An answer — any response below `500` — is remembered. A `5xx`, a failure or a\n * defect gives the key back, because none of them is an answer and the retry\n * the key exists for must be allowed to try again.\n */\nexport const requireIdempotencyKey =\n (options: IdempotencyKeyOptions) =>\n <E, R>(\n handler: Effect.Effect<HttpServerResponse.HttpServerResponse, E, R>,\n ) => {\n const guarded = Effect.gen(function* () {\n const request = yield* HttpServerRequest.HttpServerRequest;\n const key = parseIdempotencyKey(request.headers[IDEMPOTENCY_KEY_HEADER]);\n if (key === undefined)\n return problemResponse(new IdempotencyKeyMissing());\n\n // The body is cached by the request, so the handler reads it again.\n // A body that cannot be read cannot be fingerprinted: that failure is the\n // transport's, and it travels as one.\n const body = yield* request.text;\n const fingerprint = requestFingerprint(\n `${request.method} ${request.url.split('?')[0]}`,\n body,\n );\n const dedupKey = `${options.caller}|${options.route}|${key}`;\n const store = yield* IdempotencyStoreTag;\n\n const claim = yield* store.claim(dedupKey, fingerprint);\n if (claim._tag === 'existing') {\n const { record } = claim;\n if (record.fingerprint !== fingerprint)\n return problemResponse(new IdempotencyKeyReused());\n if (record.state === 'inFlight' || record.response === undefined)\n return problemResponse(new IdempotencyKeyInFlight());\n return HttpServerResponse.text(record.response.body, {\n status: record.response.status,\n ...(record.response.contentType === undefined\n ? {}\n : { contentType: record.response.contentType }),\n headers: { [IDEMPOTENT_REPLAY_HEADER]: 'true' },\n });\n }\n\n const exit = yield* Effect.exit(handler);\n if (Exit.isSuccess(exit)) {\n const stored = storable(exit.value);\n yield* stored === undefined || stored.status >= 500\n ? store.release(dedupKey)\n : store.complete(dedupKey, stored);\n return exit.value;\n }\n yield* store.release(dedupKey);\n return yield* exit;\n });\n return Object.assign(guarded, { [IDEMPOTENT]: true as const });\n };\n\n/** Whether a handler was built through {@link requireIdempotencyKey}. */\nexport const isIdempotentHandler = (handler: unknown): boolean =>\n typeof handler === 'object' &&\n handler !== null &&\n (handler as Record<symbol, unknown>)[IDEMPOTENT] === true;\n\n/** One route a service mounts, as the mount check sees it. */\nexport interface MountedRoute {\n readonly method: string;\n readonly path: string;\n readonly handler: unknown;\n}\n\n/**\n * Fails the build — throws at mount — when a route a flow Activity retries is\n * not guarded by {@link requireIdempotencyKey}. A retried write without a key\n * is a write that runs twice; finding that out from a duplicate capture is the\n * outcome this check exists to prevent.\n */\nexport const assertRetriedRoutesIdempotent = (\n routes: readonly MountedRoute[],\n retried: readonly { readonly method: string; readonly path: string }[],\n): void => {\n const unguarded = retried.filter(target => {\n const route = routes.find(\n candidate =>\n candidate.method.toUpperCase() === target.method.toUpperCase() &&\n candidate.path === target.path,\n );\n return route === undefined || !isIdempotentHandler(route.handler);\n });\n if (unguarded.length > 0)\n throw new Error(\n 'these routes are retried by a flow and are not idempotent on an Idempotency-Key: ' +\n unguarded.map(route => `${route.method} ${route.path}`).join(', '),\n );\n};\n"],"names":["createHash","IdempotencyStoreTag","IDEMPOTENCY_KEY_HEADER","IdempotencyKeyInFlight","IdempotencyKeyMissing","IdempotencyKeyReused","parseIdempotencyKey","Effect","Exit","HttpServerRequest","HttpServerResponse","problemResponse","IDEMPOTENT_REPLAY_HEADER","IDEMPOTENT","Symbol","for","canonical","value","Array","isArray","map","Object","fromEntries","keys","sort","key","requestFingerprint","target","body","text","JSON","stringify","parse","update","digest","storable","response","_tag","status","undefined","contentType","TextDecoder","decode","requireIdempotencyKey","options","handler","guarded","gen","request","headers","fingerprint","method","url","split","dedupKey","caller","route","store","claim","record","state","exit","isSuccess","stored","release","complete","assign","isIdempotentHandler","assertRetriedRoutesIdempotent","routes","retried","unguarded","filter","find","candidate","toUpperCase","path","length","Error","join"],"mappings":"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"}
package/dist/index.d.ts CHANGED
@@ -2,9 +2,11 @@ export * from './auth/index.js';
2
2
  export * from './entity-facet-routes.js';
3
3
  export * from './entity-metadata-route.js';
4
4
  export * from './entity-routes.js';
5
- export * from './health-routes.js';
5
+ export * from './http-api/index.js';
6
+ export * from './idempotency.js';
7
+ export * from './metadata-composition.js';
8
+ export * from './narrowing.js';
6
9
  export * from './redact-configuration.js';
7
10
  export * from './respond.js';
8
- export * from './service-description-route.js';
9
11
  export * from './sse.js';
10
12
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,cAAc,CAAC;AAC7B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,UAAU,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC"}
package/dist/index.js CHANGED
@@ -2,10 +2,12 @@ export * from './auth/index.js';
2
2
  export * from './entity-facet-routes.js';
3
3
  export * from './entity-metadata-route.js';
4
4
  export * from './entity-routes.js';
5
- export * from './health-routes.js';
5
+ export * from './http-api/index.js';
6
+ export * from './idempotency.js';
7
+ export * from './metadata-composition.js';
8
+ export * from './narrowing.js';
6
9
  export * from './redact-configuration.js';
7
10
  export * from './respond.js';
8
- export * from './service-description-route.js';
9
11
  export * from './sse.js';
10
12
 
11
13
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './auth/index.js';\nexport * from './entity-facet-routes.js';\nexport * from './entity-metadata-route.js';\nexport * from './entity-routes.js';\nexport * from './health-routes.js';\nexport * from './redact-configuration.js';\nexport * from './respond.js';\nexport * from './service-description-route.js';\nexport * from './sse.js';\n"],"names":[],"mappings":"AAAA,cAAc,kBAAkB;AAChC,cAAc,2BAA2B;AACzC,cAAc,6BAA6B;AAC3C,cAAc,qBAAqB;AACnC,cAAc,qBAAqB;AACnC,cAAc,4BAA4B;AAC1C,cAAc,eAAe;AAC7B,cAAc,iCAAiC;AAC/C,cAAc,WAAW"}
1
+ {"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './auth/index.js';\nexport * from './entity-facet-routes.js';\nexport * from './entity-metadata-route.js';\nexport * from './entity-routes.js';\nexport * from './http-api/index.js';\nexport * from './idempotency.js';\nexport * from './metadata-composition.js';\nexport * from './narrowing.js';\nexport * from './redact-configuration.js';\nexport * from './respond.js';\nexport * from './sse.js';\n"],"names":[],"mappings":"AAAA,cAAc,kBAAkB;AAChC,cAAc,2BAA2B;AACzC,cAAc,6BAA6B;AAC3C,cAAc,qBAAqB;AACnC,cAAc,sBAAsB;AACpC,cAAc,mBAAmB;AACjC,cAAc,4BAA4B;AAC1C,cAAc,iBAAiB;AAC/B,cAAc,4BAA4B;AAC1C,cAAc,eAAe;AAC7B,cAAc,WAAW"}
@@ -2,6 +2,9 @@ import { HealthRegistryTag, type ShutdownRegistry, ShutdownRegistryTag, WiringRe
2
2
  import { Layer } from 'effect';
3
3
  import { HttpRouter } from 'effect/http';
4
4
  import type { SharedToken } from './auth/shared-token.js';
5
+ import { type AnyEndpointGroup, type ServedRequirements } from './http-api/build-api.js';
6
+ import { FleetTokenTag } from './http-api/guards.js';
7
+ import { type FailurePolicy } from './respond.js';
5
8
  /**
6
9
  * A service's routes: `HttpRouter.add` / `HttpRouter.addAll` layers, merged
7
10
  * with `Layer.mergeAll`. Its requirements carry, as `HttpRouter` request
@@ -27,7 +30,7 @@ export type ServiceRegistries = HealthRegistryTag | ShutdownRegistryTag | Wiring
27
30
  * skeleton every `*-service` composes; the HTTP server, logging,
28
31
  * `/api/health`, and graceful shutdown live here so services stay thin.
29
32
  */
30
- export interface ServiceDefinition<RRoutes> {
33
+ export interface ServiceDefinition<RRoutes, Groups extends ReadonlyArray<AnyEndpointGroup> = readonly []> {
31
34
  /** Service name, surfaced on `/api/health`. */
32
35
  readonly name: string;
33
36
  /** Port to bind. Convention: 310N for domain services, 319x for platform. */
@@ -50,8 +53,19 @@ export interface ServiceDefinition<RRoutes> {
50
53
  * has, and an unguarded reconnaissance map is worse than none.
51
54
  */
52
55
  readonly description?: SharedToken;
53
- /** The service's routes; their requirements are satisfied by `appLayer`. */
54
- readonly router: ServiceRoutes<RRoutes>;
56
+ /**
57
+ * The service's endpoints, served as one `HttpApi` beside the health and
58
+ * description endpoints every service has
59
+ * ([ADR 0020](../../../../docs/adr/0020-endpoints-are-descriptors-and-the-shell-builds-an-httpapi.md)).
60
+ */
61
+ readonly endpoints?: Groups;
62
+ /** The status and log table the endpoints answer by. */
63
+ readonly policy?: FailurePolicy;
64
+ /**
65
+ * Routes that are not endpoints — a held-open stream, which an `HttpApi`
66
+ * does not describe. Their requirements are satisfied by `appLayer`.
67
+ */
68
+ readonly router?: ServiceRoutes<RRoutes>;
55
69
  /**
56
70
  * Composition root providing everything `router` requires.
57
71
  *
@@ -62,7 +76,7 @@ export interface ServiceDefinition<RRoutes> {
62
76
  * provided here, once, so the probes, the bus, the drain and the routes that
63
77
  * read them share one apiece.
64
78
  */
65
- readonly appLayer: Layer.Layer<RoutesRequirements<RRoutes>, never, ServiceRegistries>;
79
+ readonly appLayer: Layer.Layer<RoutesRequirements<RRoutes> | Exclude<ServedRequirements<Groups>, FleetTokenTag>, never, ServiceRegistries>;
66
80
  }
67
81
  /**
68
82
  * The service as a `Layer`: `/api/health` mounted, `router` served over an
@@ -80,7 +94,7 @@ export interface ServiceDefinition<RRoutes> {
80
94
  * only a real process boot has a SIGTERM to latch, and an in-process e2e boot
81
95
  * that installed one would leave a process listener per service it started.
82
96
  */
83
- export declare const makeServerLayer: <RRoutes>(def: ServiceDefinition<RRoutes>, port?: number, shutdown?: ShutdownRegistry) => Layer.Layer<Layer.Success<Layer.Layer<never, import("effect/http/HttpServerError").ServeError, Exclude<Exclude<HealthRegistryTag, HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag | RoutesRequirements<RRoutes>>, import("effect/http/HttpServer").HttpServer | import("@effect/platform-node/NodeServices").NodeServices | import("effect/http/HttpPlatform").HttpPlatform | import("effect/http/Etag").Generator> | Exclude<Exclude<ShutdownRegistryTag, HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag | RoutesRequirements<RRoutes>>, import("effect/http/HttpServer").HttpServer | import("@effect/platform-node/NodeServices").NodeServices | import("effect/http/HttpPlatform").HttpPlatform | import("effect/http/Etag").Generator> | Exclude<Exclude<WiringRegistryTag, HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag | RoutesRequirements<RRoutes>>, import("effect/http/HttpServer").HttpServer | import("@effect/platform-node/NodeServices").NodeServices | import("effect/http/HttpPlatform").HttpPlatform | import("effect/http/Etag").Generator> | Exclude<Exclude<import("effect/http/HttpServer").HttpServer, HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag | RoutesRequirements<RRoutes>>, import("effect/http/HttpServer").HttpServer | import("@effect/platform-node/NodeServices").NodeServices | import("effect/http/HttpPlatform").HttpPlatform | import("effect/http/Etag").Generator> | Exclude<Exclude<Exclude<HttpRouter.Request.Without<RRoutes>, HttpRouter.HttpRouter>, HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag | RoutesRequirements<RRoutes>>, import("effect/http/HttpServer").HttpServer | import("@effect/platform-node/NodeServices").NodeServices | import("effect/http/HttpPlatform").HttpPlatform | import("effect/http/Etag").Generator> | Exclude<Exclude<Exclude<Exclude<HttpRouter.Request.Only<"Requires", RRoutes>, HttpRouter.GlobalProvided>, HttpRouter.HttpRouter>, HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag | RoutesRequirements<RRoutes>>, import("effect/http/HttpServer").HttpServer | import("@effect/platform-node/NodeServices").NodeServices | import("effect/http/HttpPlatform").HttpPlatform | import("effect/http/Etag").Generator> | Exclude<Exclude<Exclude<Exclude<HttpRouter.Request.Only<"GlobalRequires", RRoutes>, HttpRouter.GlobalProvided>, HttpRouter.HttpRouter>, HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag | RoutesRequirements<RRoutes>>, import("effect/http/HttpServer").HttpServer | import("@effect/platform-node/NodeServices").NodeServices | import("effect/http/HttpPlatform").HttpPlatform | import("effect/http/Etag").Generator>>>, Layer.Error<Layer.Layer<never, import("effect/http/HttpServerError").ServeError, Exclude<Exclude<HealthRegistryTag, HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag | RoutesRequirements<RRoutes>>, import("effect/http/HttpServer").HttpServer | import("@effect/platform-node/NodeServices").NodeServices | import("effect/http/HttpPlatform").HttpPlatform | import("effect/http/Etag").Generator> | Exclude<Exclude<ShutdownRegistryTag, HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag | RoutesRequirements<RRoutes>>, import("effect/http/HttpServer").HttpServer | import("@effect/platform-node/NodeServices").NodeServices | import("effect/http/HttpPlatform").HttpPlatform | import("effect/http/Etag").Generator> | Exclude<Exclude<WiringRegistryTag, HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag | RoutesRequirements<RRoutes>>, import("effect/http/HttpServer").HttpServer | import("@effect/platform-node/NodeServices").NodeServices | import("effect/http/HttpPlatform").HttpPlatform | import("effect/http/Etag").Generator> | Exclude<Exclude<import("effect/http/HttpServer").HttpServer, HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag | RoutesRequirements<RRoutes>>, import("effect/http/HttpServer").HttpServer | import("@effect/platform-node/NodeServices").NodeServices | import("effect/http/HttpPlatform").HttpPlatform | import("effect/http/Etag").Generator> | Exclude<Exclude<Exclude<HttpRouter.Request.Without<RRoutes>, HttpRouter.HttpRouter>, HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag | RoutesRequirements<RRoutes>>, import("effect/http/HttpServer").HttpServer | import("@effect/platform-node/NodeServices").NodeServices | import("effect/http/HttpPlatform").HttpPlatform | import("effect/http/Etag").Generator> | Exclude<Exclude<Exclude<Exclude<HttpRouter.Request.Only<"Requires", RRoutes>, HttpRouter.GlobalProvided>, HttpRouter.HttpRouter>, HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag | RoutesRequirements<RRoutes>>, import("effect/http/HttpServer").HttpServer | import("@effect/platform-node/NodeServices").NodeServices | import("effect/http/HttpPlatform").HttpPlatform | import("effect/http/Etag").Generator> | Exclude<Exclude<Exclude<Exclude<HttpRouter.Request.Only<"GlobalRequires", RRoutes>, HttpRouter.GlobalProvided>, HttpRouter.HttpRouter>, HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag | RoutesRequirements<RRoutes>>, import("effect/http/HttpServer").HttpServer | import("@effect/platform-node/NodeServices").NodeServices | import("effect/http/HttpPlatform").HttpPlatform | import("effect/http/Etag").Generator>>>>;
97
+ export declare const makeServerLayer: <RRoutes, const Groups extends ReadonlyArray<AnyEndpointGroup> = readonly []>(def: ServiceDefinition<RRoutes, Groups>, port?: number, shutdown?: ShutdownRegistry) => Layer.Layer<Layer.Success<Layer.Layer<never, import("effect/http/HttpServerError").ServeError, Exclude<Exclude<any, HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag | RoutesRequirements<RRoutes> | Exclude<Groups[number] extends infer T ? T extends Groups[number] ? T extends import("./index.js").EndpointGroup<infer Endpoint extends import("@entifix/core").AnyEndpoint, infer R> ? Exclude<R, import("./index.js").ProvidedToHandlers> | import("./index.js").GuardServices<Endpoint["guard"]["kind"]> | import("./index.js").IdempotencyServices<Endpoint["idempotent"]> : never : never : never, FleetTokenTag>>, import("effect/http/Etag").Generator | import("effect/http/HttpPlatform").HttpPlatform | import("effect/http/HttpServer").HttpServer | import("@effect/platform-node/NodeServices").NodeServices>>>, Layer.Error<Layer.Layer<never, import("effect/http/HttpServerError").ServeError, Exclude<Exclude<any, HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag | RoutesRequirements<RRoutes> | Exclude<Groups[number] extends infer T_1 ? T_1 extends Groups[number] ? T_1 extends import("./index.js").EndpointGroup<infer Endpoint extends import("@entifix/core").AnyEndpoint, infer R> ? Exclude<R, import("./index.js").ProvidedToHandlers> | import("./index.js").GuardServices<Endpoint["guard"]["kind"]> | import("./index.js").IdempotencyServices<Endpoint["idempotent"]> : never : never : never, FleetTokenTag>>, import("effect/http/Etag").Generator | import("effect/http/HttpPlatform").HttpPlatform | import("effect/http/HttpServer").HttpServer | import("@effect/platform-node/NodeServices").NodeServices>>>>;
84
98
  /**
85
99
  * Boot an Effect service: build {@link makeServerLayer} and launch it under
86
100
  * `runMain` (SIGINT/SIGTERM interrupt the fiber, so Layer finalizers — the
@@ -97,5 +111,24 @@ export declare const makeServerLayer: <RRoutes>(def: ServiceDefinition<RRoutes>,
97
111
  * be: Kubernetes runs it before it sends SIGTERM, and this repo declares no
98
112
  * Deployment for a service. It lands with the first one.
99
113
  */
100
- export declare const makeService: <RRoutes>(def: ServiceDefinition<RRoutes>) => void;
114
+ export declare const makeService: <RRoutes, const Groups extends ReadonlyArray<AnyEndpointGroup> = readonly []>(def: ServiceDefinition<RRoutes, Groups>) => void;
115
+ /**
116
+ * A process that serves nothing over HTTP: its work reaches it through a
117
+ * datastore it shares with a service — a second runner of a flow engine,
118
+ * whose shards are assigned in the database the first one registered in.
119
+ */
120
+ export interface WorkerDefinition<A> {
121
+ /**
122
+ * Composition root. It may require the same three registries a service's
123
+ * `appLayer` may, provided here once each, so a client's probe, the bus's
124
+ * wiring and the drain behave as they would in a service.
125
+ */
126
+ readonly appLayer: Layer.Layer<A, never, ServiceRegistries>;
127
+ }
128
+ /**
129
+ * Boot a worker: `appLayer` under the registries and the shutdown drain a
130
+ * service has, launched under `runMain` with the same signal handling as
131
+ * {@link makeService}, and no HTTP server.
132
+ */
133
+ export declare const makeWorker: <A>(def: WorkerDefinition<A>) => void;
101
134
  //# sourceMappingURL=make-service.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"make-service.d.ts","sourceRoot":"","sources":["../src/make-service.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,iBAAiB,EAEjB,KAAK,gBAAgB,EACrB,mBAAmB,EAEnB,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAU,KAAK,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAK1D;;;;GAIG;AAEH,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;AAElE;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAC5B,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,GACtC,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;AAElE,2EAA2E;AAC3E,MAAM,MAAM,iBAAiB,GAC3B,iBAAiB,GAAG,mBAAmB,GAAG,iBAAiB,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB,CAAC,OAAO;IACxC,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACxC;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAC5B,kBAAkB,CAAC,OAAO,CAAC,EAC3B,KAAK,EACL,iBAAiB,CAClB,CAAC;CACH;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,EACrC,KAAK,iBAAiB,CAAC,OAAO,CAAC,EAC/B,OAAM,MAAiB,EACvB,WAAU,gBAAkD,KAkD3C,KAAK,CAAC,KAAK,CAC1B,KAAK,CAAC,OAAO,4iFAAe,EAC5B,KAAK,CAAC,KAAK,4iFAAe,CAE7B,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,EAAE,KAAK,iBAAiB,CAAC,OAAO,CAAC,KAAG,IAQtE,CAAC"}
1
+ {"version":3,"file":"make-service.d.ts","sourceRoot":"","sources":["../src/make-service.ts"],"names":[],"mappings":"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"}
@@ -3,9 +3,26 @@ import { NodeHttpServer, NodeRuntime } from '@effect/platform-node';
3
3
  import { HealthRegistryLayer, makeShutdownRegistry, ShutdownRegistryTag, WiringRegistryLayer } from '@entifix/business';
4
4
  import { Effect, Layer } from 'effect';
5
5
  import { HttpRouter } from 'effect/http';
6
- import { healthRoutes } from './health-routes.js';
6
+ import { buildApi, endpointsOf, serveApi } from './http-api/build-api.js';
7
+ import { FleetTokenTag } from './http-api/guards.js';
8
+ import { serviceGroup } from './http-api/service-group.js';
7
9
  import { logMechanismOutcome, problemNet } from './respond.js';
8
- import { serviceDescriptionRoute } from './service-description-route.js';
10
+ /**
11
+ * `appLayer` under the registries every process shares and the drain that
12
+ * shuts it down — one assembly, so a service and a worker cannot drift apart
13
+ * on either.
14
+ *
15
+ * `provideMerge` (not `provide`) so the registries the client layers
16
+ * registered into are the same instances the readiness and description routes
17
+ * read.
18
+ *
19
+ * The graceful shutdown, and its **position** is the mechanism. Build order is
20
+ * `appLayer` → the drain → whatever is built on top, so release order is the
21
+ * reverse: the drain runs after the server has stopped taking requests and
22
+ * *before* the connections it needs are closed. A signal handler could not
23
+ * give that ordering — `runMain` interrupts the fiber on SIGTERM, and a
24
+ * handler racing that interrupt would drain against a closing client.
25
+ */ const underRegistries = (appLayer, shutdown)=>Layer.provideMerge(Layer.effectDiscard(Effect.acquireRelease(Effect.void, ()=>shutdown.drain)), appLayer.pipe(Layer.provideMerge(Layer.mergeAll(HealthRegistryLayer, WiringRegistryLayer, Layer.succeed(ShutdownRegistryTag, shutdown)))));
9
26
  /**
10
27
  * The service as a `Layer`: `/api/health` mounted, `router` served over an
11
28
  * `@effect/platform-node` HTTP server with request logging, `appLayer`
@@ -22,30 +39,41 @@ import { serviceDescriptionRoute } from './service-description-route.js';
22
39
  * only a real process boot has a SIGTERM to latch, and an in-process e2e boot
23
40
  * that installed one would leave a process listener per service it started.
24
41
  */ export const makeServerLayer = (def, port = def.port, shutdown = makeShutdownRegistry().registry)=>{
25
- const routes = Layer.mergeAll(def.router, healthRoutes(def.name), def.description === undefined ? Layer.empty : serviceDescriptionRoute(def.name, def.slices, def.description), // Permissive CORS (frontends call these services cross-origin from their
42
+ var _def_endpoints, _def_router;
43
+ const hosted = (_def_endpoints = def.endpoints) != null ? _def_endpoints : [];
44
+ const fleetGuarded = hosted.flatMap((group)=>group.endpoints.filter(({ descriptor })=>descriptor.guard.kind === 'fleet'));
45
+ if (fleetGuarded.length > 0 && def.description === undefined) throw new Error(`'${def.name}' serves ${fleetGuarded.map(({ descriptor })=>`${descriptor.method} ${descriptor.path}`).join(', ')} behind the fleet token and names no \`description\` to check it against`);
46
+ const base = serviceGroup({
47
+ service: def.name,
48
+ slices: def.slices,
49
+ described: def.description !== undefined,
50
+ endpoints: ()=>endpointsOf(groups),
51
+ api: ()=>api
52
+ });
53
+ const groups = [
54
+ base,
55
+ ...hosted
56
+ ];
57
+ const options = def.policy === undefined ? {} : {
58
+ policy: def.policy
59
+ };
60
+ // One API per service: one encoder, one guard implementation, one OpenAPI.
61
+ const api = buildApi(def.name, groups, options);
62
+ const served = serveApi(api, groups, options).pipe(Layer.provide(def.description === undefined ? Layer.empty : Layer.succeed(FleetTokenTag, def.description)));
63
+ const routes = Layer.mergeAll(served, (_def_router = def.router) != null ? _def_router : Layer.empty, // Permissive CORS (frontends call these services cross-origin from their
26
64
  // dev ports). Tighten per-environment later.
27
65
  HttpRouter.cors(), // The last net: a defect no route answered is still a problem body.
28
66
  problemNet);
29
- // `provideMerge` (not `provide`) so the registries the client layers
30
- // registered into are the same instances the readiness and description routes
31
- // read.
32
- const appLayer = def.appLayer.pipe(Layer.provideMerge(Layer.mergeAll(HealthRegistryLayer, WiringRegistryLayer, Layer.succeed(ShutdownRegistryTag, shutdown))));
33
- // The graceful shutdown, and its **position** is the mechanism.
34
- // Build order is `appLayer` → this → `serve`, so release order is the
35
- // reverse: the drain runs after the server has stopped taking requests and
36
- // *before* the connections it needs are closed. A signal handler could not
37
- // give that ordering — `runMain` interrupts the fiber on SIGTERM, and a
38
- // handler racing that interrupt would drain against a closing client.
39
- const drained = Layer.provideMerge(Layer.effectDiscard(Effect.acquireRelease(Effect.void, ()=>shutdown.drain)), appLayer);
67
+ const drained = underRegistries(def.appLayer, shutdown);
40
68
  // `HttpRouter.serve` logs every request unless told not to, which is the
41
69
  // request logging `HttpMiddleware.logger` used to add here.
42
- const served = HttpRouter.serve(routes).pipe(Layer.provide(drained), Layer.provide(NodeHttpServer.layer(()=>createServer(), {
70
+ const server = HttpRouter.serve(routes).pipe(Layer.provide(drained), Layer.provide(NodeHttpServer.layer(()=>createServer(), {
43
71
  port
44
72
  })));
45
73
  // `ServiceDefinition` already proved `appLayer` covers what the routes need;
46
74
  // TypeScript cannot carry that proof through `Exclude` on a type parameter,
47
75
  // so the closed requirement set is stated here rather than re-derived.
48
- return served;
76
+ return server;
49
77
  };
50
78
  /**
51
79
  * Boot an Effect service: build {@link makeServerLayer} and launch it under
@@ -68,5 +96,15 @@ import { serviceDescriptionRoute } from './service-description-route.js';
68
96
  process.once('SIGINT', shutdown.begin);
69
97
  NodeRuntime.runMain(Layer.launch(makeServerLayer(def, def.port, shutdown.registry)));
70
98
  };
99
+ /**
100
+ * Boot a worker: `appLayer` under the registries and the shutdown drain a
101
+ * service has, launched under `runMain` with the same signal handling as
102
+ * {@link makeService}, and no HTTP server.
103
+ */ export const makeWorker = (def)=>{
104
+ const shutdown = makeShutdownRegistry(logMechanismOutcome);
105
+ process.once('SIGTERM', shutdown.begin);
106
+ process.once('SIGINT', shutdown.begin);
107
+ NodeRuntime.runMain(Layer.launch(underRegistries(def.appLayer, shutdown.registry)));
108
+ };
71
109
 
72
110
  //# sourceMappingURL=make-service.js.map
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/make-service.ts"],"sourcesContent":["import { createServer } from 'node:http';\n\nimport { NodeHttpServer, NodeRuntime } from '@effect/platform-node';\nimport {\n HealthRegistryLayer,\n HealthRegistryTag,\n makeShutdownRegistry,\n type ShutdownRegistry,\n ShutdownRegistryTag,\n WiringRegistryLayer,\n WiringRegistryTag,\n} from '@entifix/business';\nimport { Effect, Layer } from 'effect';\nimport { HttpRouter } from 'effect/http';\n\nimport type { SharedToken } from './auth/shared-token.js';\nimport { healthRoutes } from './health-routes.js';\nimport { logMechanismOutcome, problemNet } from './respond.js';\nimport { serviceDescriptionRoute } from './service-description-route.js';\n\n/**\n * A service's routes: `HttpRouter.add` / `HttpRouter.addAll` layers, merged\n * with `Layer.mergeAll`. Its requirements carry, as `HttpRouter` request\n * markers, the domain services the handlers need.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type ServiceRoutes<R = any> = Layer.Layer<never, never, R>;\n\n/**\n * What a service's `appLayer` must provide for routes requiring `R`: the\n * services their handlers read per request, plus anything building the route\n * layers themselves needs.\n */\nexport type RoutesRequirements<R> =\n | HttpRouter.Request.Only<'Requires', R>\n | HttpRouter.Request.Without<Exclude<R, HttpRouter.HttpRouter>>;\n\n/** The registries {@link makeServerLayer} provides to every `appLayer`. */\nexport type ServiceRegistries =\n HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag;\n\n/**\n * Definition of an Effect-native backend service.\n *\n * `router` carries the service's routes and, in its requirements, the exact set\n * of domain services those routes need. `appLayer` must provide them — the\n * composition root. Because the requirements are tracked in the type, a\n * missing dependency is a COMPILE error at `makeService`, not a runtime\n * surprise: the launched layer must require nothing. This is the uniform\n * skeleton every `*-service` composes; the HTTP server, logging,\n * `/api/health`, and graceful shutdown live here so services stay thin.\n */\nexport interface ServiceDefinition<RRoutes> {\n /** Service name, surfaced on `/api/health`. */\n readonly name: string;\n /** Port to bind. Convention: 310N for domain services, 319x for platform. */\n readonly port: number;\n /**\n * The slices this process hosts, by their `tools/slices/` name.\n *\n * It cannot be derived. `EventSourceTag` names only the *emitting* slice, and\n * one deployment may host several, and a host that co-deploys two slices in\n * one process names both. A host that registers its deployments can check\n * each name against that register, so a wrong one fails the diff rather than\n * quietly mislabelling the fleet.\n */\n readonly slices: readonly string[];\n /**\n * The token that gates `GET /api/$service`, the service's wiring document.\n *\n * Optional, and **absent means the route is not mounted** rather than served\n * open: the document names every store, exchange and upstream the service\n * has, and an unguarded reconnaissance map is worse than none.\n */\n readonly description?: SharedToken;\n /** The service's routes; their requirements are satisfied by `appLayer`. */\n readonly router: ServiceRoutes<RRoutes>;\n /**\n * Composition root providing everything `router` requires.\n *\n * It may also *require* {@link HealthRegistryTag} — that is how a client\n * layer's readiness probe registers itself — {@link WiringRegistryTag}, which\n * is how the bus records what it bound, and {@link ShutdownRegistryTag},\n * which is how it registers what draining it means. All three instances are\n * provided here, once, so the probes, the bus, the drain and the routes that\n * read them share one apiece.\n */\n readonly appLayer: Layer.Layer<\n RoutesRequirements<RRoutes>,\n never,\n ServiceRegistries\n >;\n}\n\n/**\n * The service as a `Layer`: `/api/health` mounted, `router` served over an\n * `@effect/platform-node` HTTP server with request logging, `appLayer`\n * provided.\n *\n * Split out of {@link makeService} so the same wiring can be launched more than\n * one way. `makeService` runs it under `runMain` for production; the e2e mock\n * profile launches it in-process on an ephemeral port (see `serveTestService`).\n * Sharing this function is the point — a second assembly of router + health +\n * middleware would let the thing under test drift from the thing that ships.\n *\n * `port` overrides `def.port`, which is what an in-process boot needs.\n * `shutdown` overrides the registry, which is what {@link makeService} needs:\n * only a real process boot has a SIGTERM to latch, and an in-process e2e boot\n * that installed one would leave a process listener per service it started.\n */\nexport const makeServerLayer = <RRoutes>(\n def: ServiceDefinition<RRoutes>,\n port: number = def.port,\n shutdown: ShutdownRegistry = makeShutdownRegistry().registry,\n) => {\n const routes = Layer.mergeAll(\n def.router,\n healthRoutes(def.name),\n def.description === undefined\n ? Layer.empty\n : serviceDescriptionRoute(def.name, def.slices, def.description),\n // Permissive CORS (frontends call these services cross-origin from their\n // dev ports). Tighten per-environment later.\n HttpRouter.cors(),\n // The last net: a defect no route answered is still a problem body.\n problemNet,\n );\n\n // `provideMerge` (not `provide`) so the registries the client layers\n // registered into are the same instances the readiness and description routes\n // read.\n const appLayer = def.appLayer.pipe(\n Layer.provideMerge(\n Layer.mergeAll(\n HealthRegistryLayer,\n WiringRegistryLayer,\n Layer.succeed(ShutdownRegistryTag, shutdown),\n ),\n ),\n );\n\n // The graceful shutdown, and its **position** is the mechanism.\n // Build order is `appLayer` → this → `serve`, so release order is the\n // reverse: the drain runs after the server has stopped taking requests and\n // *before* the connections it needs are closed. A signal handler could not\n // give that ordering — `runMain` interrupts the fiber on SIGTERM, and a\n // handler racing that interrupt would drain against a closing client.\n const drained = Layer.provideMerge(\n Layer.effectDiscard(\n Effect.acquireRelease(Effect.void, () => shutdown.drain),\n ),\n appLayer,\n );\n\n // `HttpRouter.serve` logs every request unless told not to, which is the\n // request logging `HttpMiddleware.logger` used to add here.\n const served = HttpRouter.serve(routes).pipe(\n Layer.provide(drained),\n Layer.provide(NodeHttpServer.layer(() => createServer(), { port })),\n );\n // `ServiceDefinition` already proved `appLayer` covers what the routes need;\n // TypeScript cannot carry that proof through `Exclude` on a type parameter,\n // so the closed requirement set is stated here rather than re-derived.\n return served as Layer.Layer<\n Layer.Success<typeof served>,\n Layer.Error<typeof served>\n >;\n};\n\n/**\n * Boot an Effect service: build {@link makeServerLayer} and launch it under\n * `runMain` (SIGINT/SIGTERM interrupt the fiber, so Layer finalizers — the\n * shutdown drain, then the db pools — release deterministically).\n *\n * The signal listeners here do **one** thing: flip the readiness latch, in the\n * same tick `runMain`'s own listener starts the interrupt, so\n * `GET /api/health/ready` stops claiming to be ready immediately rather than\n * when the finalizers get around to running. The draining itself is the\n * finalizer's, because only layer ordering can guarantee the connections are\n * still open while it happens.\n *\n * A `preStop` grace period is **not** here and could not\n * be: Kubernetes runs it before it sends SIGTERM, and this repo declares no\n * Deployment for a service. It lands with the first one.\n */\nexport const makeService = <RRoutes>(def: ServiceDefinition<RRoutes>): void => {\n const shutdown = makeShutdownRegistry(logMechanismOutcome);\n process.once('SIGTERM', shutdown.begin);\n process.once('SIGINT', shutdown.begin);\n\n NodeRuntime.runMain(\n Layer.launch(makeServerLayer(def, def.port, shutdown.registry)),\n );\n};\n"],"names":["createServer","NodeHttpServer","NodeRuntime","HealthRegistryLayer","makeShutdownRegistry","ShutdownRegistryTag","WiringRegistryLayer","Effect","Layer","HttpRouter","healthRoutes","logMechanismOutcome","problemNet","serviceDescriptionRoute","makeServerLayer","def","port","shutdown","registry","routes","mergeAll","router","name","description","undefined","empty","slices","cors","appLayer","pipe","provideMerge","succeed","drained","effectDiscard","acquireRelease","void","drain","served","serve","provide","layer","makeService","process","once","begin","runMain","launch"],"mappings":"AAAA,SAASA,YAAY,QAAQ,YAAY;AAEzC,SAASC,cAAc,EAAEC,WAAW,QAAQ,wBAAwB;AACpE,SACEC,mBAAmB,EAEnBC,oBAAoB,EAEpBC,mBAAmB,EACnBC,mBAAmB,QAEd,oBAAoB;AAC3B,SAASC,MAAM,EAAEC,KAAK,QAAQ,SAAS;AACvC,SAASC,UAAU,QAAQ,cAAc;AAGzC,SAASC,YAAY,QAAQ,qBAAqB;AAClD,SAASC,mBAAmB,EAAEC,UAAU,QAAQ,eAAe;AAC/D,SAASC,uBAAuB,QAAQ,iCAAiC;AA4EzE;;;;;;;;;;;;;;;CAeC,GACD,OAAO,MAAMC,kBAAkB,CAC7BC,KACAC,OAAeD,IAAIC,IAAI,EACvBC,WAA6Bb,uBAAuBc,QAAQ;IAE5D,MAAMC,SAASX,MAAMY,QAAQ,CAC3BL,IAAIM,MAAM,EACVX,aAAaK,IAAIO,IAAI,GACrBP,IAAIQ,WAAW,KAAKC,YAChBhB,MAAMiB,KAAK,GACXZ,wBAAwBE,IAAIO,IAAI,EAAEP,IAAIW,MAAM,EAAEX,IAAIQ,WAAW,GACjE,yEAAyE;IACzE,6CAA6C;IAC7Cd,WAAWkB,IAAI,IACf,oEAAoE;IACpEf;IAGF,qEAAqE;IACrE,8EAA8E;IAC9E,QAAQ;IACR,MAAMgB,WAAWb,IAAIa,QAAQ,CAACC,IAAI,CAChCrB,MAAMsB,YAAY,CAChBtB,MAAMY,QAAQ,CACZjB,qBACAG,qBACAE,MAAMuB,OAAO,CAAC1B,qBAAqBY;IAKzC,gEAAgE;IAChE,sEAAsE;IACtE,2EAA2E;IAC3E,2EAA2E;IAC3E,wEAAwE;IACxE,sEAAsE;IACtE,MAAMe,UAAUxB,MAAMsB,YAAY,CAChCtB,MAAMyB,aAAa,CACjB1B,OAAO2B,cAAc,CAAC3B,OAAO4B,IAAI,EAAE,IAAMlB,SAASmB,KAAK,IAEzDR;IAGF,yEAAyE;IACzE,4DAA4D;IAC5D,MAAMS,SAAS5B,WAAW6B,KAAK,CAACnB,QAAQU,IAAI,CAC1CrB,MAAM+B,OAAO,CAACP,UACdxB,MAAM+B,OAAO,CAACtC,eAAeuC,KAAK,CAAC,IAAMxC,gBAAgB;QAAEgB;IAAK;IAElE,6EAA6E;IAC7E,4EAA4E;IAC5E,uEAAuE;IACvE,OAAOqB;AAIT,EAAE;AAEF;;;;;;;;;;;;;;;CAeC,GACD,OAAO,MAAMI,cAAc,CAAU1B;IACnC,MAAME,WAAWb,qBAAqBO;IACtC+B,QAAQC,IAAI,CAAC,WAAW1B,SAAS2B,KAAK;IACtCF,QAAQC,IAAI,CAAC,UAAU1B,SAAS2B,KAAK;IAErC1C,YAAY2C,OAAO,CACjBrC,MAAMsC,MAAM,CAAChC,gBAAgBC,KAAKA,IAAIC,IAAI,EAAEC,SAASC,QAAQ;AAEjE,EAAE"}
1
+ {"version":3,"sources":["../src/make-service.ts"],"sourcesContent":["import { createServer } from 'node:http';\n\nimport { NodeHttpServer, NodeRuntime } from '@effect/platform-node';\nimport {\n HealthRegistryLayer,\n HealthRegistryTag,\n makeShutdownRegistry,\n type ShutdownRegistry,\n ShutdownRegistryTag,\n WiringRegistryLayer,\n WiringRegistryTag,\n} from '@entifix/business';\nimport { Effect, Layer } from 'effect';\nimport { HttpRouter } from 'effect/http';\n\nimport type { SharedToken } from './auth/shared-token.js';\nimport {\n type AnyEndpointGroup,\n buildApi,\n endpointsOf,\n serveApi,\n type ServedRequirements,\n} from './http-api/build-api.js';\nimport { FleetTokenTag } from './http-api/guards.js';\nimport { serviceGroup } from './http-api/service-group.js';\nimport {\n type FailurePolicy,\n logMechanismOutcome,\n problemNet,\n} from './respond.js';\n\n/**\n * A service's routes: `HttpRouter.add` / `HttpRouter.addAll` layers, merged\n * with `Layer.mergeAll`. Its requirements carry, as `HttpRouter` request\n * markers, the domain services the handlers need.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type ServiceRoutes<R = any> = Layer.Layer<never, never, R>;\n\n/**\n * What a service's `appLayer` must provide for routes requiring `R`: the\n * services their handlers read per request, plus anything building the route\n * layers themselves needs.\n */\nexport type RoutesRequirements<R> =\n | HttpRouter.Request.Only<'Requires', R>\n | HttpRouter.Request.Without<Exclude<R, HttpRouter.HttpRouter>>;\n\n/** The registries {@link makeServerLayer} provides to every `appLayer`. */\nexport type ServiceRegistries =\n HealthRegistryTag | ShutdownRegistryTag | WiringRegistryTag;\n\n/**\n * Definition of an Effect-native backend service.\n *\n * `router` carries the service's routes and, in its requirements, the exact set\n * of domain services those routes need. `appLayer` must provide them — the\n * composition root. Because the requirements are tracked in the type, a\n * missing dependency is a COMPILE error at `makeService`, not a runtime\n * surprise: the launched layer must require nothing. This is the uniform\n * skeleton every `*-service` composes; the HTTP server, logging,\n * `/api/health`, and graceful shutdown live here so services stay thin.\n */\nexport interface ServiceDefinition<\n RRoutes,\n Groups extends ReadonlyArray<AnyEndpointGroup> = readonly [],\n> {\n /** Service name, surfaced on `/api/health`. */\n readonly name: string;\n /** Port to bind. Convention: 310N for domain services, 319x for platform. */\n readonly port: number;\n /**\n * The slices this process hosts, by their `tools/slices/` name.\n *\n * It cannot be derived. `EventSourceTag` names only the *emitting* slice, and\n * one deployment may host several, and a host that co-deploys two slices in\n * one process names both. A host that registers its deployments can check\n * each name against that register, so a wrong one fails the diff rather than\n * quietly mislabelling the fleet.\n */\n readonly slices: readonly string[];\n /**\n * The token that gates `GET /api/$service`, the service's wiring document.\n *\n * Optional, and **absent means the route is not mounted** rather than served\n * open: the document names every store, exchange and upstream the service\n * has, and an unguarded reconnaissance map is worse than none.\n */\n readonly description?: SharedToken;\n /**\n * The service's endpoints, served as one `HttpApi` beside the health and\n * description endpoints every service has\n * ([ADR 0020](../../../../docs/adr/0020-endpoints-are-descriptors-and-the-shell-builds-an-httpapi.md)).\n */\n readonly endpoints?: Groups;\n /** The status and log table the endpoints answer by. */\n readonly policy?: FailurePolicy;\n /**\n * Routes that are not endpoints — a held-open stream, which an `HttpApi`\n * does not describe. Their requirements are satisfied by `appLayer`.\n */\n readonly router?: ServiceRoutes<RRoutes>;\n /**\n * Composition root providing everything `router` requires.\n *\n * It may also *require* {@link HealthRegistryTag} — that is how a client\n * layer's readiness probe registers itself — {@link WiringRegistryTag}, which\n * is how the bus records what it bound, and {@link ShutdownRegistryTag},\n * which is how it registers what draining it means. All three instances are\n * provided here, once, so the probes, the bus, the drain and the routes that\n * read them share one apiece.\n */\n readonly appLayer: Layer.Layer<\n | RoutesRequirements<RRoutes>\n // The fleet token is `description`'s, provided here — never the host's.\n | Exclude<ServedRequirements<Groups>, FleetTokenTag>,\n never,\n ServiceRegistries\n >;\n}\n\n/**\n * `appLayer` under the registries every process shares and the drain that\n * shuts it down — one assembly, so a service and a worker cannot drift apart\n * on either.\n *\n * `provideMerge` (not `provide`) so the registries the client layers\n * registered into are the same instances the readiness and description routes\n * read.\n *\n * The graceful shutdown, and its **position** is the mechanism. Build order is\n * `appLayer` → the drain → whatever is built on top, so release order is the\n * reverse: the drain runs after the server has stopped taking requests and\n * *before* the connections it needs are closed. A signal handler could not\n * give that ordering — `runMain` interrupts the fiber on SIGTERM, and a\n * handler racing that interrupt would drain against a closing client.\n */\nconst underRegistries = <A>(\n appLayer: Layer.Layer<A, never, ServiceRegistries>,\n shutdown: ShutdownRegistry,\n) =>\n Layer.provideMerge(\n Layer.effectDiscard(\n Effect.acquireRelease(Effect.void, () => shutdown.drain),\n ),\n appLayer.pipe(\n Layer.provideMerge(\n Layer.mergeAll(\n HealthRegistryLayer,\n WiringRegistryLayer,\n Layer.succeed(ShutdownRegistryTag, shutdown),\n ),\n ),\n ),\n );\n\n/**\n * The service as a `Layer`: `/api/health` mounted, `router` served over an\n * `@effect/platform-node` HTTP server with request logging, `appLayer`\n * provided.\n *\n * Split out of {@link makeService} so the same wiring can be launched more than\n * one way. `makeService` runs it under `runMain` for production; the e2e mock\n * profile launches it in-process on an ephemeral port (see `serveTestService`).\n * Sharing this function is the point — a second assembly of router + health +\n * middleware would let the thing under test drift from the thing that ships.\n *\n * `port` overrides `def.port`, which is what an in-process boot needs.\n * `shutdown` overrides the registry, which is what {@link makeService} needs:\n * only a real process boot has a SIGTERM to latch, and an in-process e2e boot\n * that installed one would leave a process listener per service it started.\n */\nexport const makeServerLayer = <\n RRoutes,\n const Groups extends ReadonlyArray<AnyEndpointGroup> = readonly [],\n>(\n def: ServiceDefinition<RRoutes, Groups>,\n port: number = def.port,\n shutdown: ShutdownRegistry = makeShutdownRegistry().registry,\n) => {\n const hosted = def.endpoints ?? [];\n const fleetGuarded = hosted.flatMap(group =>\n group.endpoints.filter(\n ({ descriptor }) => descriptor.guard.kind === 'fleet',\n ),\n );\n if (fleetGuarded.length > 0 && def.description === undefined)\n throw new Error(\n `'${def.name}' serves ${fleetGuarded\n .map(({ descriptor }) => `${descriptor.method} ${descriptor.path}`)\n .join(\n ', ',\n )} behind the fleet token and names no \\`description\\` to check it against`,\n );\n const base = serviceGroup({\n service: def.name,\n slices: def.slices,\n described: def.description !== undefined,\n endpoints: () => endpointsOf(groups),\n api: () => api,\n });\n const groups: ReadonlyArray<AnyEndpointGroup> = [base, ...hosted];\n const options = def.policy === undefined ? {} : { policy: def.policy };\n // One API per service: one encoder, one guard implementation, one OpenAPI.\n const api = buildApi(def.name, groups, options);\n const served = serveApi(api, groups, options).pipe(\n Layer.provide(\n def.description === undefined\n ? Layer.empty\n : Layer.succeed(FleetTokenTag, def.description),\n ),\n );\n\n const routes = Layer.mergeAll(\n served,\n def.router ?? Layer.empty,\n // Permissive CORS (frontends call these services cross-origin from their\n // dev ports). Tighten per-environment later.\n HttpRouter.cors(),\n // The last net: a defect no route answered is still a problem body.\n problemNet,\n );\n\n const drained = underRegistries(def.appLayer, shutdown);\n\n // `HttpRouter.serve` logs every request unless told not to, which is the\n // request logging `HttpMiddleware.logger` used to add here.\n const server = HttpRouter.serve(routes as ServiceRoutes).pipe(\n Layer.provide(drained),\n Layer.provide(NodeHttpServer.layer(() => createServer(), { port })),\n );\n // `ServiceDefinition` already proved `appLayer` covers what the routes need;\n // TypeScript cannot carry that proof through `Exclude` on a type parameter,\n // so the closed requirement set is stated here rather than re-derived.\n return server as Layer.Layer<\n Layer.Success<typeof server>,\n Layer.Error<typeof server>\n >;\n};\n\n/**\n * Boot an Effect service: build {@link makeServerLayer} and launch it under\n * `runMain` (SIGINT/SIGTERM interrupt the fiber, so Layer finalizers — the\n * shutdown drain, then the db pools — release deterministically).\n *\n * The signal listeners here do **one** thing: flip the readiness latch, in the\n * same tick `runMain`'s own listener starts the interrupt, so\n * `GET /api/health/ready` stops claiming to be ready immediately rather than\n * when the finalizers get around to running. The draining itself is the\n * finalizer's, because only layer ordering can guarantee the connections are\n * still open while it happens.\n *\n * A `preStop` grace period is **not** here and could not\n * be: Kubernetes runs it before it sends SIGTERM, and this repo declares no\n * Deployment for a service. It lands with the first one.\n */\nexport const makeService = <\n RRoutes,\n const Groups extends ReadonlyArray<AnyEndpointGroup> = readonly [],\n>(\n def: ServiceDefinition<RRoutes, Groups>,\n): void => {\n const shutdown = makeShutdownRegistry(logMechanismOutcome);\n process.once('SIGTERM', shutdown.begin);\n process.once('SIGINT', shutdown.begin);\n\n NodeRuntime.runMain(\n Layer.launch(makeServerLayer(def, def.port, shutdown.registry)),\n );\n};\n\n/**\n * A process that serves nothing over HTTP: its work reaches it through a\n * datastore it shares with a service — a second runner of a flow engine,\n * whose shards are assigned in the database the first one registered in.\n */\nexport interface WorkerDefinition<A> {\n /**\n * Composition root. It may require the same three registries a service's\n * `appLayer` may, provided here once each, so a client's probe, the bus's\n * wiring and the drain behave as they would in a service.\n */\n readonly appLayer: Layer.Layer<A, never, ServiceRegistries>;\n}\n\n/**\n * Boot a worker: `appLayer` under the registries and the shutdown drain a\n * service has, launched under `runMain` with the same signal handling as\n * {@link makeService}, and no HTTP server.\n */\nexport const makeWorker = <A>(def: WorkerDefinition<A>): void => {\n const shutdown = makeShutdownRegistry(logMechanismOutcome);\n process.once('SIGTERM', shutdown.begin);\n process.once('SIGINT', shutdown.begin);\n\n NodeRuntime.runMain(\n Layer.launch(underRegistries(def.appLayer, shutdown.registry)),\n );\n};\n"],"names":["createServer","NodeHttpServer","NodeRuntime","HealthRegistryLayer","makeShutdownRegistry","ShutdownRegistryTag","WiringRegistryLayer","Effect","Layer","HttpRouter","buildApi","endpointsOf","serveApi","FleetTokenTag","serviceGroup","logMechanismOutcome","problemNet","underRegistries","appLayer","shutdown","provideMerge","effectDiscard","acquireRelease","void","drain","pipe","mergeAll","succeed","makeServerLayer","def","port","registry","hosted","endpoints","fleetGuarded","flatMap","group","filter","descriptor","guard","kind","length","description","undefined","Error","name","map","method","path","join","base","service","slices","described","groups","api","options","policy","served","provide","empty","routes","router","cors","drained","server","serve","layer","makeService","process","once","begin","runMain","launch","makeWorker"],"mappings":"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"}
@@ -0,0 +1,28 @@
1
+ import { type ResolutionRule, type VerifiedContext } from '@entifix/business';
2
+ import type { Recipe } from '@entifix/business/compose';
3
+ import { type FragmentCatalog } from '@entifix/business/flow';
4
+ import type { UseCaseComposition, UseCaseDescriptor } from '@entifix/core';
5
+ /**
6
+ * What a service can resolve its verbs against, by the names `@useCase()`
7
+ * gives: variant rules, recipes, and the catalog their fragments come from.
8
+ */
9
+ export interface MetadataCompositions {
10
+ readonly variants?: Readonly<Record<string, readonly ResolutionRule<unknown>[]>>;
11
+ readonly recipes?: Readonly<Record<string, Recipe<any>>>;
12
+ readonly catalog?: FragmentCatalog;
13
+ }
14
+ /**
15
+ * Throws at mount when a descriptor names a variant set or a recipe the
16
+ * service was not given: a verb that cannot be resolved would otherwise be
17
+ * silently missing from every caller's document.
18
+ */
19
+ export declare const assertCompositionsDeclared: (descriptors: readonly UseCaseDescriptor[], compositions: MetadataCompositions) => void;
20
+ /**
21
+ * What a verb resolves to for one caller: its composition, `undefined` for a
22
+ * verb that resolves nothing (no variants, no recipe), or `'unreachable'` when
23
+ * the caller is offered no variant — or the recipe needs a fragment whose
24
+ * requirements the caller does not meet, in a stage no gate can skip. An
25
+ * unreachable verb is omitted from the document.
26
+ */
27
+ export declare const compositionFor: (descriptor: UseCaseDescriptor, context: VerifiedContext, compositions: MetadataCompositions) => UseCaseComposition | "unreachable" | undefined;
28
+ //# sourceMappingURL=metadata-composition.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"metadata-composition.d.ts","sourceRoot":"","sources":["../src/metadata-composition.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE3E;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAC1B,MAAM,CAAC,MAAM,EAAE,SAAS,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC,CACnD,CAAC;IAGF,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC;CACpC;AAED;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,GACrC,aAAa,SAAS,iBAAiB,EAAE,EACzC,cAAc,oBAAoB,KACjC,IAeF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GACzB,YAAY,iBAAiB,EAC7B,SAAS,eAAe,EACxB,cAAc,oBAAoB,KACjC,kBAAkB,GAAG,aAAa,GAAG,SA+CvC,CAAC"}