@entifix/service-shell 0.12.1 → 0.14.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.
- package/README.md +7 -7
- package/dist/auth/failures.d.ts +0 -12
- package/dist/auth/failures.d.ts.map +1 -1
- package/dist/auth/failures.js +0 -10
- package/dist/auth/failures.js.map +1 -1
- package/dist/auth/index.d.ts +0 -1
- package/dist/auth/index.d.ts.map +1 -1
- package/dist/auth/index.js +0 -1
- package/dist/auth/index.js.map +1 -1
- package/dist/auth/require-principal.d.ts +0 -16
- package/dist/auth/require-principal.d.ts.map +1 -1
- package/dist/auth/require-principal.js +1 -38
- package/dist/auth/require-principal.js.map +1 -1
- package/dist/auth/require-service-crossing.d.ts +2 -73
- package/dist/auth/require-service-crossing.d.ts.map +1 -1
- package/dist/auth/require-service-crossing.js +2 -117
- package/dist/auth/require-service-crossing.js.map +1 -1
- package/dist/auth/shared-token.d.ts +0 -15
- package/dist/auth/shared-token.d.ts.map +1 -1
- package/dist/auth/shared-token.js +0 -25
- package/dist/auth/shared-token.js.map +1 -1
- package/dist/index.d.ts +0 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +0 -3
- package/dist/index.js.map +1 -1
- package/dist/load-remote-configuration.d.ts +4 -4
- package/dist/load-remote-configuration.d.ts.map +1 -1
- package/dist/load-remote-configuration.js +7 -14
- package/dist/load-remote-configuration.js.map +1 -1
- package/dist/observability.d.ts +2 -2
- package/dist/observability.d.ts.map +1 -1
- package/dist/observability.js +1 -1
- package/dist/observability.js.map +1 -1
- package/dist/push/index.d.ts +9 -0
- package/dist/push/index.d.ts.map +1 -0
- package/dist/push/index.js +9 -0
- package/dist/push/index.js.map +1 -0
- package/dist/push/server-push.d.ts +82 -0
- package/dist/push/server-push.d.ts.map +1 -0
- package/dist/push/server-push.js +48 -0
- package/dist/push/server-push.js.map +1 -0
- package/dist/push/sse.d.ts +62 -0
- package/dist/push/sse.d.ts.map +1 -0
- package/dist/push/sse.js +120 -0
- package/dist/push/sse.js.map +1 -0
- package/dist/respond.d.ts +1 -7
- package/dist/respond.d.ts.map +1 -1
- package/dist/respond.js +1 -8
- package/dist/respond.js.map +1 -1
- package/package.json +23 -13
- package/dist/auth/require-organization.d.ts +0 -32
- package/dist/auth/require-organization.d.ts.map +0 -1
- package/dist/auth/require-organization.js +0 -52
- package/dist/auth/require-organization.js.map +0 -1
- package/dist/entity-facet-routes.d.ts +0 -44
- package/dist/entity-facet-routes.d.ts.map +0 -1
- package/dist/entity-facet-routes.js +0 -70
- package/dist/entity-facet-routes.js.map +0 -1
- package/dist/entity-metadata-route.d.ts +0 -25
- package/dist/entity-metadata-route.d.ts.map +0 -1
- package/dist/entity-metadata-route.js +0 -102
- package/dist/entity-metadata-route.js.map +0 -1
- package/dist/entity-route-guard.d.ts +0 -62
- package/dist/entity-route-guard.d.ts.map +0 -1
- package/dist/entity-route-guard.js +0 -35
- package/dist/entity-route-guard.js.map +0 -1
- package/dist/entity-routes.d.ts +0 -76
- package/dist/entity-routes.d.ts.map +0 -1
- package/dist/entity-routes.js +0 -267
- package/dist/entity-routes.js.map +0 -1
- package/dist/route-responses.d.ts +0 -44
- package/dist/route-responses.d.ts.map +0 -1
- package/dist/route-responses.js +0 -104
- package/dist/route-responses.js.map +0 -1
package/dist/index.js
CHANGED
|
@@ -1,7 +1,4 @@
|
|
|
1
1
|
export * from './auth/index.js';
|
|
2
|
-
export * from './entity-facet-routes.js';
|
|
3
|
-
export * from './entity-metadata-route.js';
|
|
4
|
-
export * from './entity-routes.js';
|
|
5
2
|
export * from './http-api/index.js';
|
|
6
3
|
export * from './idempotency.js';
|
|
7
4
|
export * from './metadata-composition.js';
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './auth/index.js';\nexport * from './
|
|
1
|
+
{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './auth/index.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,sBAAsB;AACpC,cAAc,mBAAmB;AACjC,cAAc,4BAA4B;AAC1C,cAAc,iBAAiB;AAC/B,cAAc,4BAA4B;AAC1C,cAAc,eAAe;AAC7B,cAAc,WAAW"}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { ConfigurationClientInMemory, ConfigurationPlain,
|
|
1
|
+
import { ConfigurationClientInMemory, ConfigurationPlain, Unavailable } from '@entifix/core';
|
|
2
2
|
import { Context, Effect, Schedule } from 'effect';
|
|
3
3
|
declare const LoadedConfigurationTag_base: Context.ServiceClass<LoadedConfigurationTag, "LoadedConfigurationTag", ConfigurationPlain>;
|
|
4
4
|
/**
|
|
@@ -72,18 +72,18 @@ export interface RemoteConfigurationSource {
|
|
|
72
72
|
* their own parameters (e.g. `mongo.uri`) instead of hardcoding them.
|
|
73
73
|
*
|
|
74
74
|
* Uses Node's global `fetch` (same transport approach as the REST client); any
|
|
75
|
-
* network/parse/non-2xx failure becomes an {@link
|
|
75
|
+
* network/parse/non-2xx failure becomes an {@link Unavailable}. Each
|
|
76
76
|
* attempt is deadlined ({@link defaultConfigAttemptTimeoutMs}) and the fetch is
|
|
77
77
|
* retried on a bounded schedule ({@link defaultConfigRetrySchedule}), so a
|
|
78
78
|
* dependent that boots before config-service is HTTP-ready waits it out — and
|
|
79
79
|
* one that reaches a socket nobody is answering gives up rather than hanging.
|
|
80
80
|
*/
|
|
81
|
-
export declare const loadRemoteConfiguration: (source: RemoteConfigurationSource, options?: LoadRemoteConfigurationOptions) => Effect.Effect<ConfigurationPlain,
|
|
81
|
+
export declare const loadRemoteConfiguration: (source: RemoteConfigurationSource, options?: LoadRemoteConfigurationOptions) => Effect.Effect<ConfigurationPlain, Unavailable>;
|
|
82
82
|
/**
|
|
83
83
|
* Convenience: load the remote configuration and wrap it in a
|
|
84
84
|
* {@link ConfigurationClientInMemory}, to read the service's own parameters via
|
|
85
85
|
* `.in(group).getString(key)` or to hand to an adapter that is built with one.
|
|
86
86
|
*/
|
|
87
|
-
export declare const loadRemoteConfigurationClient: (source: RemoteConfigurationSource, options?: LoadRemoteConfigurationOptions) => Effect.Effect<ConfigurationClientInMemory,
|
|
87
|
+
export declare const loadRemoteConfigurationClient: (source: RemoteConfigurationSource, options?: LoadRemoteConfigurationOptions) => Effect.Effect<ConfigurationClientInMemory, Unavailable>;
|
|
88
88
|
export {};
|
|
89
89
|
//# sourceMappingURL=load-remote-configuration.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"load-remote-configuration.d.ts","sourceRoot":"","sources":["../src/load-remote-configuration.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,
|
|
1
|
+
{"version":3,"file":"load-remote-configuration.d.ts","sourceRoot":"","sources":["../src/load-remote-configuration.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,WAAW,EACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;;AAEnD;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,2BAGf;CAAG;AAEhC;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CACR,CAAC;AAEpE;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,6BAA6B,OAAQ,CAAC;AAEnD,mDAAmD;AACnD,MAAM,WAAW,8BAA8B;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7D;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,GAClC,QAAQ,yBAAyB,EACjC,UAAS,8BAAmC,KAC3C,MAAM,CAAC,MAAM,CAAC,kBAAkB,EAAE,WAAW,CAwB/C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,GACxC,QAAQ,yBAAyB,EACjC,UAAS,8BAAmC,KAC3C,MAAM,CAAC,MAAM,CAAC,2BAA2B,EAAE,WAAW,CAGtD,CAAC"}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { ConfigurationClientInMemory,
|
|
1
|
+
import { ConfigurationClientInMemory, Unavailable } from '@entifix/core';
|
|
2
2
|
import { Context, Effect, Schedule } from 'effect';
|
|
3
3
|
/**
|
|
4
4
|
* DI tag carrying the raw {@link ConfigurationPlain} a service loaded at boot,
|
|
@@ -42,7 +42,7 @@ import { Context, Effect, Schedule } from 'effect';
|
|
|
42
42
|
* their own parameters (e.g. `mongo.uri`) instead of hardcoding them.
|
|
43
43
|
*
|
|
44
44
|
* Uses Node's global `fetch` (same transport approach as the REST client); any
|
|
45
|
-
* network/parse/non-2xx failure becomes an {@link
|
|
45
|
+
* network/parse/non-2xx failure becomes an {@link Unavailable}. Each
|
|
46
46
|
* attempt is deadlined ({@link defaultConfigAttemptTimeoutMs}) and the fetch is
|
|
47
47
|
* retried on a bounded schedule ({@link defaultConfigRetrySchedule}), so a
|
|
48
48
|
* dependent that boots before config-service is HTTP-ready waits it out — and
|
|
@@ -57,21 +57,14 @@ import { Context, Effect, Schedule } from 'effect';
|
|
|
57
57
|
cache: 'no-store',
|
|
58
58
|
headers: source.headers,
|
|
59
59
|
signal: AbortSignal.timeout(attemptTimeoutMs)
|
|
60
|
-
}).catch((error)=>{
|
|
61
|
-
// Rewritten because the raw abort says `This operation was aborted`,
|
|
62
|
-
// which reads like a bug in the caller rather than a silent peer.
|
|
63
|
-
if (error instanceof Error && error.name === 'TimeoutError') {
|
|
64
|
-
throw new Error(`the configuration source did not answer within ${attemptTimeoutMs}ms at ${url}`);
|
|
65
|
-
}
|
|
66
|
-
throw error;
|
|
67
60
|
});
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
}
|
|
61
|
+
// Any answer but a success is the source failing to serve, the same as
|
|
62
|
+
// a timeout or a dropped connection: one `Unavailable`, retried.
|
|
63
|
+
if (!response.ok) throw new Error(`status ${response.status}`);
|
|
71
64
|
return await response.json();
|
|
72
65
|
},
|
|
73
|
-
catch: (
|
|
74
|
-
url
|
|
66
|
+
catch: ()=>new Unavailable({
|
|
67
|
+
dependency: url
|
|
75
68
|
})
|
|
76
69
|
});
|
|
77
70
|
return Effect.retry(fetchOnce, (_options_retrySchedule = options.retrySchedule) != null ? _options_retrySchedule : defaultConfigRetrySchedule);
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/load-remote-configuration.ts"],"sourcesContent":["import {\n ConfigurationClientInMemory,\n ConfigurationPlain,\n
|
|
1
|
+
{"version":3,"sources":["../src/load-remote-configuration.ts"],"sourcesContent":["import {\n ConfigurationClientInMemory,\n ConfigurationPlain,\n Unavailable,\n} from '@entifix/core';\nimport { Context, Effect, Schedule } from 'effect';\n\n/**\n * DI tag carrying the raw {@link ConfigurationPlain} a service loaded at boot,\n * so a `GET /api/config` introspection route can expose it (redacted).\n */\nexport class LoadedConfigurationTag extends Context.Service<\n LoadedConfigurationTag,\n ConfigurationPlain\n>()('LoadedConfigurationTag') {}\n\n/**\n * Default boot-fetch retry policy: 20 attempts spaced 1s apart (~20s window).\n *\n * A dependent service `dev` target `dependsOn config-service:dev`, but Nx\n * considers a *continuous* dependency \"ready\" the moment its process starts —\n * not when its HTTP server is listening and its table is seeded. So a fast\n * backend can fire its boot fetch before config-service answers and, without a\n * retry, would crash with `fetch failed` (connection refused). Retrying a\n * bounded window lets the fleet come up in any order.\n */\nexport const defaultConfigRetrySchedule: Schedule.Schedule<unknown, unknown> =\n Schedule.max([Schedule.spaced('1 seconds'), Schedule.recurs(20)]);\n\n/**\n * Deadline for a single boot-fetch attempt.\n *\n * **The retry above only helps if an attempt can fail.** `fetch` has no timeout\n * of its own, so a connection that is accepted but never answered — a previous\n * listener dying mid-flight, a half-open socket — leaves it waiting forever.\n * The schedule never sees a failure, never retries, and the service hangs in its\n * boot layer with its port bound and nothing served: measured twice on\n * 2026-08-14, on two different services, and recovered only by recreating the\n * datastores.\n *\n * So an attempt is deadlined, for the same reason a readiness probe is: a check\n * that hangs is a check that failed. The ordinary race this retry was written\n * for — config-service not listening yet — still fails instantly with\n * `ECONNREFUSED` and costs nothing, so this bounds the pathological case only:\n * 20 retries × (5s deadline + 1s spacing) ≈ 2 minutes before the service exits\n * loudly instead of hanging silently.\n */\nexport const defaultConfigAttemptTimeoutMs = 5_000;\n\n/** Options for {@link loadRemoteConfiguration}. */\nexport interface LoadRemoteConfigurationOptions {\n /**\n * Retry policy for the boot fetch. Defaults to\n * {@link defaultConfigRetrySchedule}. Pass `Schedule.stop` to fail fast (a\n * single attempt, no retry) — used by tests and callers that want the error\n * immediately.\n */\n readonly retrySchedule?: Schedule.Schedule<unknown, unknown>;\n /**\n * Deadline for one attempt, in milliseconds. Defaults to\n * {@link defaultConfigAttemptTimeoutMs}. There is deliberately no way to\n * disable it — an attempt that cannot time out is the bug this exists for.\n */\n readonly attemptTimeoutMs?: number;\n}\n\n/**\n * Where a service's configuration is fetched from, and what the request\n * carries.\n *\n * Both are the host's: the path a configuration service answers on and the\n * credential it asks for are that deployment's protocol, so the framework takes\n * the finished URL and headers rather than composing either.\n */\nexport interface RemoteConfigurationSource {\n /** The full URL, e.g. `http://config:3190/api/config/order-service`. */\n readonly url: string;\n readonly headers?: Readonly<Record<string, string>>;\n}\n\n/**\n * Fetches a service's configuration from a configuration service and returns\n * it as a {@link ConfigurationPlain}. Backends call this at boot to resolve\n * their own parameters (e.g. `mongo.uri`) instead of hardcoding them.\n *\n * Uses Node's global `fetch` (same transport approach as the REST client); any\n * network/parse/non-2xx failure becomes an {@link Unavailable}. Each\n * attempt is deadlined ({@link defaultConfigAttemptTimeoutMs}) and the fetch is\n * retried on a bounded schedule ({@link defaultConfigRetrySchedule}), so a\n * dependent that boots before config-service is HTTP-ready waits it out — and\n * one that reaches a socket nobody is answering gives up rather than hanging.\n */\nexport const loadRemoteConfiguration = (\n source: RemoteConfigurationSource,\n options: LoadRemoteConfigurationOptions = {},\n): Effect.Effect<ConfigurationPlain, Unavailable> => {\n const { url } = source;\n const attemptTimeoutMs =\n options.attemptTimeoutMs ?? defaultConfigAttemptTimeoutMs;\n\n const fetchOnce = Effect.tryPromise({\n try: async () => {\n const response = await fetch(url, {\n cache: 'no-store',\n headers: source.headers,\n signal: AbortSignal.timeout(attemptTimeoutMs),\n });\n // Any answer but a success is the source failing to serve, the same as\n // a timeout or a dropped connection: one `Unavailable`, retried.\n if (!response.ok) throw new Error(`status ${response.status}`);\n return (await response.json()) as ConfigurationPlain;\n },\n catch: () => new Unavailable({ dependency: url }),\n });\n\n return Effect.retry(\n fetchOnce,\n options.retrySchedule ?? defaultConfigRetrySchedule,\n );\n};\n\n/**\n * Convenience: load the remote configuration and wrap it in a\n * {@link ConfigurationClientInMemory}, to read the service's own parameters via\n * `.in(group).getString(key)` or to hand to an adapter that is built with one.\n */\nexport const loadRemoteConfigurationClient = (\n source: RemoteConfigurationSource,\n options: LoadRemoteConfigurationOptions = {},\n): Effect.Effect<ConfigurationClientInMemory, Unavailable> =>\n loadRemoteConfiguration(source, options).pipe(\n Effect.map(plain => new ConfigurationClientInMemory(plain)),\n );\n"],"names":["ConfigurationClientInMemory","Unavailable","Context","Effect","Schedule","LoadedConfigurationTag","Service","defaultConfigRetrySchedule","max","spaced","recurs","defaultConfigAttemptTimeoutMs","loadRemoteConfiguration","source","options","url","attemptTimeoutMs","fetchOnce","tryPromise","try","response","fetch","cache","headers","signal","AbortSignal","timeout","ok","Error","status","json","catch","dependency","retry","retrySchedule","loadRemoteConfigurationClient","pipe","map","plain"],"mappings":"AAAA,SACEA,2BAA2B,EAE3BC,WAAW,QACN,gBAAgB;AACvB,SAASC,OAAO,EAAEC,MAAM,EAAEC,QAAQ,QAAQ,SAAS;AAEnD;;;CAGC,GACD,OAAO,MAAMC,+BAA+BH,QAAQI,OAAO,GAGvD;AAA2B;AAE/B;;;;;;;;;CASC,GACD,OAAO,MAAMC,6BACXH,SAASI,GAAG,CAAC;IAACJ,SAASK,MAAM,CAAC;IAAcL,SAASM,MAAM,CAAC;CAAI,EAAE;AAEpE;;;;;;;;;;;;;;;;;CAiBC,GACD,OAAO,MAAMC,gCAAgC,KAAM;AAiCnD;;;;;;;;;;;CAWC,GACD,OAAO,MAAMC,0BAA0B,CACrCC,QACAC,UAA0C,CAAC,CAAC;QAI1CA,2BAmBAA;IArBF,MAAM,EAAEC,GAAG,EAAE,GAAGF;IAChB,MAAMG,oBACJF,4BAAAA,QAAQE,gBAAgB,YAAxBF,4BAA4BH;IAE9B,MAAMM,YAAYd,OAAOe,UAAU,CAAC;QAClCC,KAAK;YACH,MAAMC,WAAW,MAAMC,MAAMN,KAAK;gBAChCO,OAAO;gBACPC,SAASV,OAAOU,OAAO;gBACvBC,QAAQC,YAAYC,OAAO,CAACV;YAC9B;YACA,uEAAuE;YACvE,iEAAiE;YACjE,IAAI,CAACI,SAASO,EAAE,EAAE,MAAM,IAAIC,MAAM,CAAC,OAAO,EAAER,SAASS,MAAM,EAAE;YAC7D,OAAQ,MAAMT,SAASU,IAAI;QAC7B;QACAC,OAAO,IAAM,IAAI9B,YAAY;gBAAE+B,YAAYjB;YAAI;IACjD;IAEA,OAAOZ,OAAO8B,KAAK,CACjBhB,YACAH,yBAAAA,QAAQoB,aAAa,YAArBpB,yBAAyBP;AAE7B,EAAE;AAEF;;;;CAIC,GACD,OAAO,MAAM4B,gCAAgC,CAC3CtB,QACAC,UAA0C,CAAC,CAAC,GAE5CF,wBAAwBC,QAAQC,SAASsB,IAAI,CAC3CjC,OAAOkC,GAAG,CAACC,CAAAA,QAAS,IAAItC,4BAA4BsC,SACpD"}
|
package/dist/observability.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { ConfigurationClient,
|
|
1
|
+
import type { ConfigurationClient, Unavailable } from '@entifix/core';
|
|
2
2
|
import { type LogLevel, type LogRecord, type LogSink } from '@entifix/tooling/logging';
|
|
3
3
|
import { type MetricReader, type ResourceMetrics } from '@opentelemetry/sdk-metrics';
|
|
4
4
|
import { type ReadableSpan, type SpanProcessor } from '@opentelemetry/sdk-trace-base';
|
|
@@ -114,5 +114,5 @@ export declare const makeInMemoryObservabilityLayer: (serviceName: string) => In
|
|
|
114
114
|
* the one service that cannot fetch its configuration over HTTP, because it is
|
|
115
115
|
* the thing being fetched from.
|
|
116
116
|
*/
|
|
117
|
-
export declare const observabilityFromConfiguration: (store: ConfigurationClient, serviceName: string) => Effect.Effect<ReturnType<typeof makeObservabilityLayer>,
|
|
117
|
+
export declare const observabilityFromConfiguration: (store: ConfigurationClient, serviceName: string) => Effect.Effect<ReturnType<typeof makeObservabilityLayer>, Unavailable>;
|
|
118
118
|
//# sourceMappingURL=observability.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,
|
|
1
|
+
{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACtE,OAAO,EAIL,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,OAAO,EAGb,MAAM,0BAA0B,CAAC;AAKlC,OAAO,EAGL,KAAK,YAAY,EAEjB,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,YAAY,EAEjB,KAAK,aAAa,EACnB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAsB,MAAM,QAAQ,CAAC;AAG3D,kFAAkF;AAClF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IACjC;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C;;;;;;;;;OASG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChD;AA0JD,gEAAgE;AAChE,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACnD;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAClD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,GACrC,SAAS,yBAAyB,iFA8BnC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GAAI,QAAQ,mBAAmB,iFAuBjE,CAAC;AAEF,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,0BAA0B,CAAC,CAAC;IAC9D,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,aAAa,CAAC,YAAY,CAAC,CAAC;IACrD;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC;CACxE;AAED;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,GACzC,aAAa,MAAM,KAClB,qBA6BF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,8BAA8B,GACzC,OAAO,mBAAmB,EAC1B,aAAa,MAAM,KAClB,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,sBAAsB,CAAC,EAAE,WAAW,CAkBnE,CAAC"}
|
package/dist/observability.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import
|
|
1
|
+
import * as NodeSdk from '@effect/opentelemetry/NodeSdk';
|
|
2
2
|
import { createLogger, makeOtlpHttpLogSink, makeStdoutJsonSink } from '@entifix/tooling/logging';
|
|
3
3
|
import { context } from '@opentelemetry/api';
|
|
4
4
|
import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/observability.ts"],"sourcesContent":["import { NodeSdk } from '@effect/opentelemetry';\nimport type { ConfigurationClient, EntifixBuildError } from '@entifix/core';\nimport {\n type Attributes,\n createLogger,\n type Logger as ToolingLogger,\n type LogLevel,\n type LogRecord,\n type LogSink,\n makeOtlpHttpLogSink,\n makeStdoutJsonSink,\n} from '@entifix/tooling/logging';\nimport { context } from '@opentelemetry/api';\nimport { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';\nimport { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';\nimport { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';\nimport {\n AggregationTemporality,\n InMemoryMetricExporter,\n type MetricReader,\n PeriodicExportingMetricReader,\n type ResourceMetrics,\n} from '@opentelemetry/sdk-metrics';\nimport {\n BatchSpanProcessor,\n InMemorySpanExporter,\n type ReadableSpan,\n SimpleSpanProcessor,\n type SpanProcessor,\n} from '@opentelemetry/sdk-trace-base';\nimport { Effect, Layer, Logger, References } from 'effect';\nimport type * as EffectLogLevel from 'effect/LogLevel';\n\n/** Resolved observability settings (from config-service `logging.*`/`otel.*`). */\nexport interface ObservabilityConfig {\n readonly serviceName: string;\n readonly level: LogLevel;\n /** `otlp` in dev (ship straight to otel-lgtm), `stdout` in a cluster (filelog). */\n readonly sink: 'stdout' | 'otlp';\n /**\n * OTLP base URL; `/v1/traces`, `/v1/logs` and `/v1/metrics` are appended.\n *\n * **Optional, and that is the boot guarantee**: with no endpoint the service\n * still starts — logs fall back to the stdout sink and neither exporter is\n * built. It used to be a required `getString`, so a fleet whose\n * `otel.endpoint` row was missing failed to boot at all rather than running\n * without telemetry, which is the wrong trade for a signal that is not on the\n * request path.\n */\n readonly otelEndpoint?: string | undefined;\n /**\n * How often the metric reader exports, in milliseconds. Config rather than a\n * constant because it is a real operational dial (a shorter interval buys\n * resolution with cardinality-independent request volume), and optional\n * because a fleet whose seed predates the key should not fail to boot over an\n * export interval. (Optional for that reason alone: config-service reconciles\n * `SEED_ROWS` per row on every boot, so a *new* key does reach an existing\n * Postgres — `ON CONFLICT DO NOTHING` declines to overwrite an operator's\n * changed *value*, which is the case that needs a `dev:reset`.)\n */\n readonly metricIntervalMs?: number | undefined;\n}\n\n/** Export interval used when `otel.metricIntervalMs` is unset. */\nconst DEFAULT_METRIC_INTERVAL_MS = 60_000;\n\n/** The in-memory reader's interval — long enough that only `forceFlush` collects. */\nconst ONE_HOUR_MS = 3_600_000;\n\n/**\n * `@effect/opentelemetry` manages its own span tree but does not register an\n * OpenTelemetry context manager, so `@opentelemetry/api`'s active-span lookup\n * (which the tooling logger uses to stamp `trace_id`) would stay empty. Register\n * the AsyncLocalStorage manager once so the active span propagates and logs\n * correlate to their traces. Idempotent — `setGlobalContextManager` no-ops if a\n * manager is already registered (e.g. across test boots in one process).\n */\nlet contextManagerReady = false;\nconst ensureContextManager = (): void => {\n if (!contextManagerReady) {\n context.setGlobalContextManager(\n new AsyncLocalStorageContextManager().enable(),\n );\n contextManagerReady = true;\n }\n};\n\n/**\n * The OTLP base URL, or `undefined` when there is nowhere to export.\n *\n * A **blank** endpoint counts as absent, not as a base URL. config-service's\n * operator CRUD writes empty strings, so `''` is reachable in practice — and\n * taken literally it builds exporters aimed at the relative `/v1/traces` and\n * `/v1/metrics`, which resolve against nothing, fail every export, and look\n * from the call site exactly like a service that is simply quiet.\n */\nconst resolveEndpoint = (raw: string | undefined): string | undefined => {\n const trimmed = raw?.trim();\n return trimmed === undefined || trimmed === '' ? undefined : trimmed;\n};\n\nconst makeSink = (\n config: ObservabilityConfig,\n endpoint: string | undefined,\n): LogSink =>\n config.sink === 'otlp' && endpoint !== undefined\n ? makeOtlpHttpLogSink({\n endpoint,\n serviceName: config.serviceName,\n // Flush on a short interval too, so a quiet service's logs reach the\n // Collector promptly instead of waiting for a full batch.\n flushIntervalMs: 2000,\n onError: error =>\n process.stderr.write(\n `[otlp-log-sink] export failed: ${String(error)}\\n`,\n ),\n })\n : makeStdoutJsonSink();\n\n/**\n * Effect's `LogLevel` mapped onto the four levels the tooling logger has.\n *\n * ⚠️ **Match the spelling `effect/LogLevel` declares, and let the compiler\n * hold you to it.** Effect 4's level is the string union `\"All\" | \"Fatal\" |\n * \"Error\" | \"Warn\" | \"Info\" | \"Debug\" | \"Trace\" | \"None\"`. Under Effect 3 this\n * switch read the level's `label`, which was upper case (`\"ERROR\"`), against\n * mixed-case spellings (`'Error'`, `'Warning'`) typed as a plain `string` — so\n * **no case could ever match** and every log in the service fell through to\n * `default` and was emitted at `info`. Measured in Loki: an `Effect.logError`\n * arrived as `severity_text: INFO`, `severity_number: 9`, which makes an error\n * invisible to every level-based alert and dashboard while still appearing in\n * the log — the failure mode that reads as \"we have no errors\". Typing the\n * parameter as Effect's own union is what makes a misspelt case a compile\n * error now: `'Warning'` would not compile.\n */\nconst toToolingLevel = (level: EffectLogLevel.LogLevel): LogLevel => {\n switch (level) {\n case 'Trace':\n case 'Debug':\n return 'debug';\n case 'Warn':\n return 'warn';\n case 'Error':\n case 'Fatal':\n return 'error';\n default:\n return 'info';\n }\n};\n\n/**\n * `Effect.annotateLogs`' entries flattened into tooling `Attributes`.\n *\n * The annotations are a record read off the fiber, and the attribute values are\n * a closed scalar set, so anything else is stringified rather than dropped — an\n * annotation that reaches a sink as `[object Object]` is still more use than one\n * that silently is not there.\n */\nconst toAttributes = (\n annotations: Readonly<Record<string, unknown>>,\n): Attributes =>\n Object.fromEntries(\n Object.entries(annotations).map(([key, value]) => [\n key,\n typeof value === 'string' ||\n typeof value === 'number' ||\n typeof value === 'boolean' ||\n value === null\n ? value\n : String(value),\n ]),\n );\n\nconst messageToString = (message: unknown): string =>\n Array.isArray(message)\n ? message.map(part => String(part)).join(' ')\n : String(message);\n\n/**\n * An Effect `Logger` that forwards every Effect log (including the request logs\n * `HttpRouter.serve` writes) to the tooling logger — so the whole service logs\n * through one structured, trace-correlated pipeline.\n *\n * **Annotations are forwarded**, and used not to be: they were destructured\n * away, so every `Effect.annotateLogs` in every service was discarded before it\n * reached a sink. That made the annotated fields the outbox relay and the\n * transaction engine attach — the tenant database, the event id, the\n * transaction id, the rollback's own error — unqueryable, while the comments\n * beside them said they were structured fields in Loki. Measured: the records\n * arrived carrying the message and nothing else. Effect 4 no longer hands them\n * to a logger at all; they live on the fiber, as\n * `References.CurrentLogAnnotations`, and are read from there.\n *\n * `error` is called through its own arm because the tooling `Logger` gives it a\n * different signature — `(message, error?, attributes?)` — so passing the\n * attributes positionally as the second argument would file them as the *cause*\n * and lose them again.\n */\nconst makeEffectLogger = (\n logger: ToolingLogger,\n): Logger.Logger<unknown, void> =>\n Logger.make(({ logLevel, message, fiber }) => {\n const level = toToolingLevel(logLevel);\n const text = messageToString(message);\n const attributes = toAttributes(\n fiber.getRef(References.CurrentLogAnnotations),\n );\n\n if (level === 'error') {\n logger.error(text, undefined, attributes);\n return;\n }\n logger[level](text, attributes);\n });\n\n/** Lower-level inputs to {@link makeObservabilityLayerWith}. */\nexport interface ObservabilityLayerOptions {\n readonly serviceName: string;\n readonly level: LogLevel;\n /** Where log records go (a real sink in prod, an in-memory double in tests). */\n readonly sink: LogSink;\n /**\n * How spans are exported (batch→OTLP in prod, in-memory in tests).\n * Omitted when there is no OTLP endpoint to export to.\n */\n readonly spanProcessor?: SpanProcessor | undefined;\n /**\n * How metrics are exported (periodic→OTLP in prod, in-memory in tests).\n *\n * Injectable for the same reason `spanProcessor` is: a test drives the exact\n * wiring that ships, so — unlike a double that reimplements the composition —\n * it can see `Metrics.layer` failing to register a producer at all.\n */\n readonly metricReader?: MetricReader | undefined;\n}\n\n/**\n * The observability composition over explicit sink + span processor: replace\n * Effect's default logger with the tooling-backed one, and stand up the OTel\n * tracer so requests produce spans. Keeping sink/processor injectable lets a\n * test drive the exact same wiring with in-memory exporters (see\n * {@link makeInMemoryObservabilityLayer}), so the correlation the e2e asserts is\n * the correlation that ships.\n */\nexport const makeObservabilityLayerWith = (\n options: ObservabilityLayerOptions,\n) => {\n ensureContextManager();\n const toolingLogger = createLogger({\n service: options.serviceName,\n level: options.level,\n sink: options.sink,\n });\n // Replace Effect's loggers with the tooling logger. `Logger.layer` sets the\n // fiber's current loggers outright rather than adding to them, and neither\n // the service boot (`runMain`) nor the e2e boot (`Effect.runFork`) installs a\n // logger of its own, so this single layer takes effect in either runtime.\n const effectLogger = makeEffectLogger(toolingLogger);\n const LoggingLayer = Logger.layer([effectLogger]);\n // One `NodeSdk.layer` for both signals: it builds the OTel `Resource` once,\n // so the spans and the metrics carry the same `service.name` rather than two\n // resources that can disagree. `NodeSdk` degrades an absent `spanProcessor`\n // or `metricReader` to `Layer.empty` on its own (its `isNonEmpty` guard), so\n // the no-endpoint case needs no branch here — it simply exports nothing.\n //\n // The metric half needs no producer of its own: `NodeSdk` wires the reader\n // through `Metrics.layer`, whose `MetricProducer` reads **Effect's own metric\n // registry**. So `Metric.counter(…)` at any call site is exported, and a\n // domain counter stays one line where it is incremented.\n const TelemetryLayer = NodeSdk.layer(() => ({\n resource: { serviceName: options.serviceName },\n spanProcessor: options.spanProcessor,\n metricReader: options.metricReader,\n }));\n return Layer.merge(LoggingLayer, TelemetryLayer);\n};\n\n/**\n * The production/dev observability layer: log level + sink and OTLP endpoint\n * come from config-service. Merged into the service `AppLayer`.\n */\nexport const makeObservabilityLayer = (config: ObservabilityConfig) => {\n const endpoint = resolveEndpoint(config.otelEndpoint);\n return makeObservabilityLayerWith({\n serviceName: config.serviceName,\n level: config.level,\n sink: makeSink(config, endpoint),\n spanProcessor:\n endpoint === undefined\n ? undefined\n : new BatchSpanProcessor(\n new OTLPTraceExporter({ url: `${endpoint}/v1/traces` }),\n ),\n metricReader:\n endpoint === undefined\n ? undefined\n : new PeriodicExportingMetricReader({\n exporter: new OTLPMetricExporter({\n url: `${endpoint}/v1/metrics`,\n }),\n exportIntervalMillis:\n config.metricIntervalMs ?? DEFAULT_METRIC_INTERVAL_MS,\n }),\n });\n};\n\n/** Captured telemetry from {@link makeInMemoryObservabilityLayer}. */\nexport interface InMemoryObservability {\n readonly layer: ReturnType<typeof makeObservabilityLayerWith>;\n /** Records the (replaced) logger emitted — the e2e asserts on these. */\n readonly logRecords: readonly LogRecord[];\n /** The spans exported so far (used to confirm requests produced traces). */\n readonly getSpans: () => ReadonlyArray<ReadableSpan>;\n /**\n * Forces a metric collection and returns what the exporter then holds.\n *\n * A push reader only exports on its interval, so a test that merely read the\n * exporter would find it empty and could not tell \"the producer is not\n * registered\" from \"the interval has not elapsed\".\n */\n readonly collectMetrics: () => Promise<ReadonlyArray<ResourceMetrics>>;\n}\n\n/**\n * Test-support: the real observability wiring with in-memory exporters, so an\n * e2e can boot the service and assert that logs are structured and carry the\n * `trace_id` of the request span that produced them.\n */\nexport const makeInMemoryObservabilityLayer = (\n serviceName: string,\n): InMemoryObservability => {\n const logRecords: LogRecord[] = [];\n const spanExporter = new InMemorySpanExporter();\n const metricExporter = new InMemoryMetricExporter(\n AggregationTemporality.CUMULATIVE,\n );\n // A long interval, because the test drives collection explicitly through\n // `collectMetrics`. A short one would export on a timer as well and make the\n // assertions depend on how long the surrounding effect happened to take.\n const metricReader = new PeriodicExportingMetricReader({\n exporter: metricExporter,\n exportIntervalMillis: ONE_HOUR_MS,\n });\n const layer = makeObservabilityLayerWith({\n serviceName,\n level: 'debug',\n sink: { emit: record => logRecords.push(record) },\n spanProcessor: new SimpleSpanProcessor(spanExporter),\n metricReader,\n });\n return {\n layer,\n logRecords,\n getSpans: () => spanExporter.getFinishedSpans(),\n collectMetrics: async () => {\n await metricReader.forceFlush();\n return metricExporter.getMetrics();\n },\n };\n};\n\n/**\n * The observability layer for a service, read from its own configuration.\n *\n * This is the whole per-service wiring: a composition root yields it and merges\n * the result into its `AppLayer`. It exists because the four reads below were\n * byte-identical in every service that had them, sitting directly above a\n * `makeObservabilityLayer` call that mapped them one-for-one — the same\n * duplication the module itself carried, one level up.\n *\n * `logging.level` and `logging.sink` are **required**: the rows are seeded for\n * every service and reach an existing table on config-service's next boot (the\n * seed reconciles per row and only declines to overwrite a value that is already\n * there), so a missing one is a real misconfiguration and should be loud.\n *\n * `otel.endpoint` and `otel.metricIntervalMs` are **optional**, for two\n * different reasons. The endpoint is what makes telemetry a *degradable*\n * dependency — with none, the service boots and serves, logs to stdout and\n * exports nothing, rather than an unreachable telemetry destination taking the\n * service down. The interval is a dial with a sane default, and requiring it\n * would fail the boot on any fleet whose seed predates it.\n *\n * Takes the {@link ConfigurationClient} port rather than a concrete client, so\n * config-service can pass the store it builds from its **own** SQL rows: it is\n * the one service that cannot fetch its configuration over HTTP, because it is\n * the thing being fetched from.\n */\nexport const observabilityFromConfiguration = (\n store: ConfigurationClient,\n serviceName: string,\n): Effect.Effect<\n ReturnType<typeof makeObservabilityLayer>,\n EntifixBuildError\n> =>\n Effect.gen(function* () {\n const level = yield* store.in('logging').getString('level');\n const sink = yield* store.in('logging').getString('sink');\n const otelEndpoint = yield* store.in('otel').getOptionalString('endpoint');\n const metricIntervalMs = yield* store\n .in('otel')\n .getOptionalNumber('metricIntervalMs');\n\n return makeObservabilityLayer({\n serviceName,\n level: level as LogLevel,\n // Anything but the explicit `stdout` is the OTLP sink, which is what makes\n // a mistyped value degrade to shipping rather than to silence.\n sink: sink === 'stdout' ? 'stdout' : 'otlp',\n otelEndpoint,\n metricIntervalMs,\n });\n });\n"],"names":["NodeSdk","createLogger","makeOtlpHttpLogSink","makeStdoutJsonSink","context","AsyncLocalStorageContextManager","OTLPMetricExporter","OTLPTraceExporter","AggregationTemporality","InMemoryMetricExporter","PeriodicExportingMetricReader","BatchSpanProcessor","InMemorySpanExporter","SimpleSpanProcessor","Effect","Layer","Logger","References","DEFAULT_METRIC_INTERVAL_MS","ONE_HOUR_MS","contextManagerReady","ensureContextManager","setGlobalContextManager","enable","resolveEndpoint","raw","trimmed","trim","undefined","makeSink","config","endpoint","sink","serviceName","flushIntervalMs","onError","error","process","stderr","write","String","toToolingLevel","level","toAttributes","annotations","Object","fromEntries","entries","map","key","value","messageToString","message","Array","isArray","part","join","makeEffectLogger","logger","make","logLevel","fiber","text","attributes","getRef","CurrentLogAnnotations","makeObservabilityLayerWith","options","toolingLogger","service","effectLogger","LoggingLayer","layer","TelemetryLayer","resource","spanProcessor","metricReader","merge","makeObservabilityLayer","otelEndpoint","url","exporter","exportIntervalMillis","metricIntervalMs","makeInMemoryObservabilityLayer","logRecords","spanExporter","metricExporter","CUMULATIVE","emit","record","push","getSpans","getFinishedSpans","collectMetrics","forceFlush","getMetrics","observabilityFromConfiguration","store","gen","in","getString","getOptionalString","getOptionalNumber"],"mappings":"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"}
|
|
1
|
+
{"version":3,"sources":["../src/observability.ts"],"sourcesContent":["import * as NodeSdk from '@effect/opentelemetry/NodeSdk';\nimport type { ConfigurationClient, Unavailable } from '@entifix/core';\nimport {\n type Attributes,\n createLogger,\n type Logger as ToolingLogger,\n type LogLevel,\n type LogRecord,\n type LogSink,\n makeOtlpHttpLogSink,\n makeStdoutJsonSink,\n} from '@entifix/tooling/logging';\nimport { context } from '@opentelemetry/api';\nimport { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';\nimport { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';\nimport { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';\nimport {\n AggregationTemporality,\n InMemoryMetricExporter,\n type MetricReader,\n PeriodicExportingMetricReader,\n type ResourceMetrics,\n} from '@opentelemetry/sdk-metrics';\nimport {\n BatchSpanProcessor,\n InMemorySpanExporter,\n type ReadableSpan,\n SimpleSpanProcessor,\n type SpanProcessor,\n} from '@opentelemetry/sdk-trace-base';\nimport { Effect, Layer, Logger, References } from 'effect';\nimport type * as EffectLogLevel from 'effect/LogLevel';\n\n/** Resolved observability settings (from config-service `logging.*`/`otel.*`). */\nexport interface ObservabilityConfig {\n readonly serviceName: string;\n readonly level: LogLevel;\n /** `otlp` in dev (ship straight to otel-lgtm), `stdout` in a cluster (filelog). */\n readonly sink: 'stdout' | 'otlp';\n /**\n * OTLP base URL; `/v1/traces`, `/v1/logs` and `/v1/metrics` are appended.\n *\n * **Optional, and that is the boot guarantee**: with no endpoint the service\n * still starts — logs fall back to the stdout sink and neither exporter is\n * built. It used to be a required `getString`, so a fleet whose\n * `otel.endpoint` row was missing failed to boot at all rather than running\n * without telemetry, which is the wrong trade for a signal that is not on the\n * request path.\n */\n readonly otelEndpoint?: string | undefined;\n /**\n * How often the metric reader exports, in milliseconds. Config rather than a\n * constant because it is a real operational dial (a shorter interval buys\n * resolution with cardinality-independent request volume), and optional\n * because a fleet whose seed predates the key should not fail to boot over an\n * export interval. (Optional for that reason alone: config-service reconciles\n * `SEED_ROWS` per row on every boot, so a *new* key does reach an existing\n * Postgres — `ON CONFLICT DO NOTHING` declines to overwrite an operator's\n * changed *value*, which is the case that needs a `dev:reset`.)\n */\n readonly metricIntervalMs?: number | undefined;\n}\n\n/** Export interval used when `otel.metricIntervalMs` is unset. */\nconst DEFAULT_METRIC_INTERVAL_MS = 60_000;\n\n/** The in-memory reader's interval — long enough that only `forceFlush` collects. */\nconst ONE_HOUR_MS = 3_600_000;\n\n/**\n * `@effect/opentelemetry` manages its own span tree but does not register an\n * OpenTelemetry context manager, so `@opentelemetry/api`'s active-span lookup\n * (which the tooling logger uses to stamp `trace_id`) would stay empty. Register\n * the AsyncLocalStorage manager once so the active span propagates and logs\n * correlate to their traces. Idempotent — `setGlobalContextManager` no-ops if a\n * manager is already registered (e.g. across test boots in one process).\n */\nlet contextManagerReady = false;\nconst ensureContextManager = (): void => {\n if (!contextManagerReady) {\n context.setGlobalContextManager(\n new AsyncLocalStorageContextManager().enable(),\n );\n contextManagerReady = true;\n }\n};\n\n/**\n * The OTLP base URL, or `undefined` when there is nowhere to export.\n *\n * A **blank** endpoint counts as absent, not as a base URL. config-service's\n * operator CRUD writes empty strings, so `''` is reachable in practice — and\n * taken literally it builds exporters aimed at the relative `/v1/traces` and\n * `/v1/metrics`, which resolve against nothing, fail every export, and look\n * from the call site exactly like a service that is simply quiet.\n */\nconst resolveEndpoint = (raw: string | undefined): string | undefined => {\n const trimmed = raw?.trim();\n return trimmed === undefined || trimmed === '' ? undefined : trimmed;\n};\n\nconst makeSink = (\n config: ObservabilityConfig,\n endpoint: string | undefined,\n): LogSink =>\n config.sink === 'otlp' && endpoint !== undefined\n ? makeOtlpHttpLogSink({\n endpoint,\n serviceName: config.serviceName,\n // Flush on a short interval too, so a quiet service's logs reach the\n // Collector promptly instead of waiting for a full batch.\n flushIntervalMs: 2000,\n onError: error =>\n process.stderr.write(\n `[otlp-log-sink] export failed: ${String(error)}\\n`,\n ),\n })\n : makeStdoutJsonSink();\n\n/**\n * Effect's `LogLevel` mapped onto the four levels the tooling logger has.\n *\n * ⚠️ **Match the spelling `effect/LogLevel` declares, and let the compiler\n * hold you to it.** Effect 4's level is the string union `\"All\" | \"Fatal\" |\n * \"Error\" | \"Warn\" | \"Info\" | \"Debug\" | \"Trace\" | \"None\"`. Under Effect 3 this\n * switch read the level's `label`, which was upper case (`\"ERROR\"`), against\n * mixed-case spellings (`'Error'`, `'Warning'`) typed as a plain `string` — so\n * **no case could ever match** and every log in the service fell through to\n * `default` and was emitted at `info`. Measured in Loki: an `Effect.logError`\n * arrived as `severity_text: INFO`, `severity_number: 9`, which makes an error\n * invisible to every level-based alert and dashboard while still appearing in\n * the log — the failure mode that reads as \"we have no errors\". Typing the\n * parameter as Effect's own union is what makes a misspelt case a compile\n * error now: `'Warning'` would not compile.\n */\nconst toToolingLevel = (level: EffectLogLevel.LogLevel): LogLevel => {\n switch (level) {\n case 'Trace':\n case 'Debug':\n return 'debug';\n case 'Warn':\n return 'warn';\n case 'Error':\n case 'Fatal':\n return 'error';\n default:\n return 'info';\n }\n};\n\n/**\n * `Effect.annotateLogs`' entries flattened into tooling `Attributes`.\n *\n * The annotations are a record read off the fiber, and the attribute values are\n * a closed scalar set, so anything else is stringified rather than dropped — an\n * annotation that reaches a sink as `[object Object]` is still more use than one\n * that silently is not there.\n */\nconst toAttributes = (\n annotations: Readonly<Record<string, unknown>>,\n): Attributes =>\n Object.fromEntries(\n Object.entries(annotations).map(([key, value]) => [\n key,\n typeof value === 'string' ||\n typeof value === 'number' ||\n typeof value === 'boolean' ||\n value === null\n ? value\n : String(value),\n ]),\n );\n\nconst messageToString = (message: unknown): string =>\n Array.isArray(message)\n ? message.map(part => String(part)).join(' ')\n : String(message);\n\n/**\n * An Effect `Logger` that forwards every Effect log (including the request logs\n * `HttpRouter.serve` writes) to the tooling logger — so the whole service logs\n * through one structured, trace-correlated pipeline.\n *\n * **Annotations are forwarded**, and used not to be: they were destructured\n * away, so every `Effect.annotateLogs` in every service was discarded before it\n * reached a sink. That made the annotated fields the outbox relay and the\n * transaction engine attach — the tenant database, the event id, the\n * transaction id, the rollback's own error — unqueryable, while the comments\n * beside them said they were structured fields in Loki. Measured: the records\n * arrived carrying the message and nothing else. Effect 4 no longer hands them\n * to a logger at all; they live on the fiber, as\n * `References.CurrentLogAnnotations`, and are read from there.\n *\n * `error` is called through its own arm because the tooling `Logger` gives it a\n * different signature — `(message, error?, attributes?)` — so passing the\n * attributes positionally as the second argument would file them as the *cause*\n * and lose them again.\n */\nconst makeEffectLogger = (\n logger: ToolingLogger,\n): Logger.Logger<unknown, void> =>\n Logger.make(({ logLevel, message, fiber }) => {\n const level = toToolingLevel(logLevel);\n const text = messageToString(message);\n const attributes = toAttributes(\n fiber.getRef(References.CurrentLogAnnotations),\n );\n\n if (level === 'error') {\n logger.error(text, undefined, attributes);\n return;\n }\n logger[level](text, attributes);\n });\n\n/** Lower-level inputs to {@link makeObservabilityLayerWith}. */\nexport interface ObservabilityLayerOptions {\n readonly serviceName: string;\n readonly level: LogLevel;\n /** Where log records go (a real sink in prod, an in-memory double in tests). */\n readonly sink: LogSink;\n /**\n * How spans are exported (batch→OTLP in prod, in-memory in tests).\n * Omitted when there is no OTLP endpoint to export to.\n */\n readonly spanProcessor?: SpanProcessor | undefined;\n /**\n * How metrics are exported (periodic→OTLP in prod, in-memory in tests).\n *\n * Injectable for the same reason `spanProcessor` is: a test drives the exact\n * wiring that ships, so — unlike a double that reimplements the composition —\n * it can see `Metrics.layer` failing to register a producer at all.\n */\n readonly metricReader?: MetricReader | undefined;\n}\n\n/**\n * The observability composition over explicit sink + span processor: replace\n * Effect's default logger with the tooling-backed one, and stand up the OTel\n * tracer so requests produce spans. Keeping sink/processor injectable lets a\n * test drive the exact same wiring with in-memory exporters (see\n * {@link makeInMemoryObservabilityLayer}), so the correlation the e2e asserts is\n * the correlation that ships.\n */\nexport const makeObservabilityLayerWith = (\n options: ObservabilityLayerOptions,\n) => {\n ensureContextManager();\n const toolingLogger = createLogger({\n service: options.serviceName,\n level: options.level,\n sink: options.sink,\n });\n // Replace Effect's loggers with the tooling logger. `Logger.layer` sets the\n // fiber's current loggers outright rather than adding to them, and neither\n // the service boot (`runMain`) nor the e2e boot (`Effect.runFork`) installs a\n // logger of its own, so this single layer takes effect in either runtime.\n const effectLogger = makeEffectLogger(toolingLogger);\n const LoggingLayer = Logger.layer([effectLogger]);\n // One `NodeSdk.layer` for both signals: it builds the OTel `Resource` once,\n // so the spans and the metrics carry the same `service.name` rather than two\n // resources that can disagree. `NodeSdk` degrades an absent `spanProcessor`\n // or `metricReader` to `Layer.empty` on its own (its `isNonEmpty` guard), so\n // the no-endpoint case needs no branch here — it simply exports nothing.\n //\n // The metric half needs no producer of its own: `NodeSdk` wires the reader\n // through `Metrics.layer`, whose `MetricProducer` reads **Effect's own metric\n // registry**. So `Metric.counter(…)` at any call site is exported, and a\n // domain counter stays one line where it is incremented.\n const TelemetryLayer = NodeSdk.layer(() => ({\n resource: { serviceName: options.serviceName },\n spanProcessor: options.spanProcessor,\n metricReader: options.metricReader,\n }));\n return Layer.merge(LoggingLayer, TelemetryLayer);\n};\n\n/**\n * The production/dev observability layer: log level + sink and OTLP endpoint\n * come from config-service. Merged into the service `AppLayer`.\n */\nexport const makeObservabilityLayer = (config: ObservabilityConfig) => {\n const endpoint = resolveEndpoint(config.otelEndpoint);\n return makeObservabilityLayerWith({\n serviceName: config.serviceName,\n level: config.level,\n sink: makeSink(config, endpoint),\n spanProcessor:\n endpoint === undefined\n ? undefined\n : new BatchSpanProcessor(\n new OTLPTraceExporter({ url: `${endpoint}/v1/traces` }),\n ),\n metricReader:\n endpoint === undefined\n ? undefined\n : new PeriodicExportingMetricReader({\n exporter: new OTLPMetricExporter({\n url: `${endpoint}/v1/metrics`,\n }),\n exportIntervalMillis:\n config.metricIntervalMs ?? DEFAULT_METRIC_INTERVAL_MS,\n }),\n });\n};\n\n/** Captured telemetry from {@link makeInMemoryObservabilityLayer}. */\nexport interface InMemoryObservability {\n readonly layer: ReturnType<typeof makeObservabilityLayerWith>;\n /** Records the (replaced) logger emitted — the e2e asserts on these. */\n readonly logRecords: readonly LogRecord[];\n /** The spans exported so far (used to confirm requests produced traces). */\n readonly getSpans: () => ReadonlyArray<ReadableSpan>;\n /**\n * Forces a metric collection and returns what the exporter then holds.\n *\n * A push reader only exports on its interval, so a test that merely read the\n * exporter would find it empty and could not tell \"the producer is not\n * registered\" from \"the interval has not elapsed\".\n */\n readonly collectMetrics: () => Promise<ReadonlyArray<ResourceMetrics>>;\n}\n\n/**\n * Test-support: the real observability wiring with in-memory exporters, so an\n * e2e can boot the service and assert that logs are structured and carry the\n * `trace_id` of the request span that produced them.\n */\nexport const makeInMemoryObservabilityLayer = (\n serviceName: string,\n): InMemoryObservability => {\n const logRecords: LogRecord[] = [];\n const spanExporter = new InMemorySpanExporter();\n const metricExporter = new InMemoryMetricExporter(\n AggregationTemporality.CUMULATIVE,\n );\n // A long interval, because the test drives collection explicitly through\n // `collectMetrics`. A short one would export on a timer as well and make the\n // assertions depend on how long the surrounding effect happened to take.\n const metricReader = new PeriodicExportingMetricReader({\n exporter: metricExporter,\n exportIntervalMillis: ONE_HOUR_MS,\n });\n const layer = makeObservabilityLayerWith({\n serviceName,\n level: 'debug',\n sink: { emit: record => logRecords.push(record) },\n spanProcessor: new SimpleSpanProcessor(spanExporter),\n metricReader,\n });\n return {\n layer,\n logRecords,\n getSpans: () => spanExporter.getFinishedSpans(),\n collectMetrics: async () => {\n await metricReader.forceFlush();\n return metricExporter.getMetrics();\n },\n };\n};\n\n/**\n * The observability layer for a service, read from its own configuration.\n *\n * This is the whole per-service wiring: a composition root yields it and merges\n * the result into its `AppLayer`. It exists because the four reads below were\n * byte-identical in every service that had them, sitting directly above a\n * `makeObservabilityLayer` call that mapped them one-for-one — the same\n * duplication the module itself carried, one level up.\n *\n * `logging.level` and `logging.sink` are **required**: the rows are seeded for\n * every service and reach an existing table on config-service's next boot (the\n * seed reconciles per row and only declines to overwrite a value that is already\n * there), so a missing one is a real misconfiguration and should be loud.\n *\n * `otel.endpoint` and `otel.metricIntervalMs` are **optional**, for two\n * different reasons. The endpoint is what makes telemetry a *degradable*\n * dependency — with none, the service boots and serves, logs to stdout and\n * exports nothing, rather than an unreachable telemetry destination taking the\n * service down. The interval is a dial with a sane default, and requiring it\n * would fail the boot on any fleet whose seed predates it.\n *\n * Takes the {@link ConfigurationClient} port rather than a concrete client, so\n * config-service can pass the store it builds from its **own** SQL rows: it is\n * the one service that cannot fetch its configuration over HTTP, because it is\n * the thing being fetched from.\n */\nexport const observabilityFromConfiguration = (\n store: ConfigurationClient,\n serviceName: string,\n): Effect.Effect<ReturnType<typeof makeObservabilityLayer>, Unavailable> =>\n Effect.gen(function* () {\n const level = yield* store.in('logging').getString('level');\n const sink = yield* store.in('logging').getString('sink');\n const otelEndpoint = yield* store.in('otel').getOptionalString('endpoint');\n const metricIntervalMs = yield* store\n .in('otel')\n .getOptionalNumber('metricIntervalMs');\n\n return makeObservabilityLayer({\n serviceName,\n level: level as LogLevel,\n // Anything but the explicit `stdout` is the OTLP sink, which is what makes\n // a mistyped value degrade to shipping rather than to silence.\n sink: sink === 'stdout' ? 'stdout' : 'otlp',\n otelEndpoint,\n metricIntervalMs,\n });\n });\n"],"names":["NodeSdk","createLogger","makeOtlpHttpLogSink","makeStdoutJsonSink","context","AsyncLocalStorageContextManager","OTLPMetricExporter","OTLPTraceExporter","AggregationTemporality","InMemoryMetricExporter","PeriodicExportingMetricReader","BatchSpanProcessor","InMemorySpanExporter","SimpleSpanProcessor","Effect","Layer","Logger","References","DEFAULT_METRIC_INTERVAL_MS","ONE_HOUR_MS","contextManagerReady","ensureContextManager","setGlobalContextManager","enable","resolveEndpoint","raw","trimmed","trim","undefined","makeSink","config","endpoint","sink","serviceName","flushIntervalMs","onError","error","process","stderr","write","String","toToolingLevel","level","toAttributes","annotations","Object","fromEntries","entries","map","key","value","messageToString","message","Array","isArray","part","join","makeEffectLogger","logger","make","logLevel","fiber","text","attributes","getRef","CurrentLogAnnotations","makeObservabilityLayerWith","options","toolingLogger","service","effectLogger","LoggingLayer","layer","TelemetryLayer","resource","spanProcessor","metricReader","merge","makeObservabilityLayer","otelEndpoint","url","exporter","exportIntervalMillis","metricIntervalMs","makeInMemoryObservabilityLayer","logRecords","spanExporter","metricExporter","CUMULATIVE","emit","record","push","getSpans","getFinishedSpans","collectMetrics","forceFlush","getMetrics","observabilityFromConfiguration","store","gen","in","getString","getOptionalString","getOptionalNumber"],"mappings":"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"}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Server push: the port a host publishes to and a connection reads from
|
|
3
|
+
* ([ADR 0021](../../../../../docs/adr/0021-server-push-and-the-multiplexed-channel.md)).
|
|
4
|
+
*
|
|
5
|
+
* A subpath rather than part of `.`, so a host can ban it from every package
|
|
6
|
+
* that must not know a browser exists. The SSE adapter is at `./push/sse`.
|
|
7
|
+
*/
|
|
8
|
+
export * from './server-push.js';
|
|
9
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/push/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,kBAAkB,CAAC"}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Server push: the port a host publishes to and a connection reads from
|
|
3
|
+
* ([ADR 0021](../../../../../docs/adr/0021-server-push-and-the-multiplexed-channel.md)).
|
|
4
|
+
*
|
|
5
|
+
* A subpath rather than part of `.`, so a host can ban it from every package
|
|
6
|
+
* that must not know a browser exists. The SSE adapter is at `./push/sse`.
|
|
7
|
+
*/ export * from './server-push.js';
|
|
8
|
+
|
|
9
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../../src/push/index.ts"],"sourcesContent":["/**\n * Server push: the port a host publishes to and a connection reads from\n * ([ADR 0021](../../../../../docs/adr/0021-server-push-and-the-multiplexed-channel.md)).\n *\n * A subpath rather than part of `.`, so a host can ban it from every package\n * that must not know a browser exists. The SSE adapter is at `./push/sse`.\n */\nexport * from './server-push.js';\n"],"names":[],"mappings":"AAAA;;;;;;CAMC,GACD,cAAc,mBAAmB"}
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import { type AudienceRecipient, type DomainEvent } from '@entifix/core';
|
|
2
|
+
import { Context, Effect, Metric, type Scope, Stream } from 'effect';
|
|
3
|
+
/**
|
|
4
|
+
* One open push connection: who holds it, what it asked for, and where it
|
|
5
|
+
* left off.
|
|
6
|
+
*
|
|
7
|
+
* Every field comes from the request that opened it — the topics and the
|
|
8
|
+
* cursor from its URL and `Last-Event-ID`, the recipient from the verified
|
|
9
|
+
* session or the flow capabilities it presented. Nothing about a connection is
|
|
10
|
+
* kept anywhere else, so any replica can answer its reconnect
|
|
11
|
+
* ([ADR 0021](../../../../../docs/adr/0021-server-push-and-the-multiplexed-channel.md)).
|
|
12
|
+
*/
|
|
13
|
+
export interface PushConnection {
|
|
14
|
+
readonly recipient: AudienceRecipient;
|
|
15
|
+
/** `entity:<key>`, `record:<key>:<id>` or `flow:<id>`. */
|
|
16
|
+
readonly topics: readonly string[];
|
|
17
|
+
/** The `Last-Event-ID` the client reconnected with, if any. */
|
|
18
|
+
readonly cursor?: string;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* What a connection receives: an event, with the topics of this connection it
|
|
22
|
+
* matched, or a request to re-read some of its topics because what it missed
|
|
23
|
+
* cannot be replayed.
|
|
24
|
+
*
|
|
25
|
+
* The matched topics travel with the event so the browser routes it to the
|
|
26
|
+
* listeners that asked, without knowing the host's topic vocabulary.
|
|
27
|
+
*/
|
|
28
|
+
export type PushMessage = {
|
|
29
|
+
readonly _tag: 'event';
|
|
30
|
+
readonly event: DomainEvent;
|
|
31
|
+
readonly topics: readonly string[];
|
|
32
|
+
} | {
|
|
33
|
+
readonly _tag: 'resync';
|
|
34
|
+
readonly topics: readonly string[];
|
|
35
|
+
};
|
|
36
|
+
/** The server half of push: what a publisher feeds and what a connection reads. */
|
|
37
|
+
export interface ServerPush {
|
|
38
|
+
/** Offers one event to every open connection that subscribed and is admitted. */
|
|
39
|
+
readonly publish: (event: DomainEvent) => Effect.Effect<void>;
|
|
40
|
+
/**
|
|
41
|
+
* The messages for one connection: the resume hook's catch-up first, then
|
|
42
|
+
* every live event matching its topics and its audience, until the
|
|
43
|
+
* connection's scope closes.
|
|
44
|
+
*/
|
|
45
|
+
readonly open: (connection: PushConnection) => Stream.Stream<PushMessage>;
|
|
46
|
+
}
|
|
47
|
+
declare const ServerPushTag_base: Context.ServiceClass<ServerPushTag, "@entifix/service-shell/ServerPush", ServerPush>;
|
|
48
|
+
export declare class ServerPushTag extends ServerPushTag_base {
|
|
49
|
+
}
|
|
50
|
+
export interface ServerPushOptions {
|
|
51
|
+
/**
|
|
52
|
+
* The topics an event belongs to. An event in no topic reaches nobody.
|
|
53
|
+
*
|
|
54
|
+
* Host vocabulary: an entity change might be `entity:<key>` and
|
|
55
|
+
* `record:<key>:<id>`, a flow outcome `flow:<id>`.
|
|
56
|
+
*/
|
|
57
|
+
readonly topicsOf: (event: DomainEvent) => readonly string[];
|
|
58
|
+
/**
|
|
59
|
+
* Whether a connection may receive an event it subscribed to. Defaults to
|
|
60
|
+
* the event's own audience, which fails closed: an event naming no audience
|
|
61
|
+
* reaches no connection.
|
|
62
|
+
*/
|
|
63
|
+
readonly admits?: (event: DomainEvent, connection: PushConnection) => boolean;
|
|
64
|
+
/**
|
|
65
|
+
* What a reconnecting connection missed, answered from a read model the host
|
|
66
|
+
* already has. Omitted, a connection with a cursor is told to re-read every
|
|
67
|
+
* topic it holds.
|
|
68
|
+
*/
|
|
69
|
+
readonly resume?: (cursor: string, topics: readonly string[]) => Stream.Stream<PushMessage>;
|
|
70
|
+
}
|
|
71
|
+
/** Events a connection subscribed to but its audience did not admit. */
|
|
72
|
+
export declare const pushFiltered: Metric.Counter<number>;
|
|
73
|
+
/**
|
|
74
|
+
* The in-process hub every connection on this replica reads from.
|
|
75
|
+
*
|
|
76
|
+
* One per process, fed by the host's broadcast subscription. It holds no
|
|
77
|
+
* backlog: a connection that was not open when an event was published learns
|
|
78
|
+
* of it through `resume`, never from here.
|
|
79
|
+
*/
|
|
80
|
+
export declare const makeServerPush: ({ topicsOf, admits, resume, }: ServerPushOptions) => Effect.Effect<ServerPush, never, Scope.Scope>;
|
|
81
|
+
export {};
|
|
82
|
+
//# sourceMappingURL=server-push.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"server-push.d.ts","sourceRoot":"","sources":["../../src/push/server-push.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAU,KAAK,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAE7E;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GACnB;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAEpE,mFAAmF;AACnF,MAAM,WAAW,UAAU;IACzB,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9D;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,UAAU,EAAE,cAAc,KAAK,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;CAC3E;;AAED,qBAAa,aAAc,SAAQ,kBAElC;CAAG;AAEJ,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,SAAS,MAAM,EAAE,CAAC;IAC7D;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,KAAK,OAAO,CAAC;IAC9E;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,SAAS,MAAM,EAAE,KACtB,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;CACjC;AAED,wEAAwE;AACxE,eAAO,MAAM,YAAY,wBAGvB,CAAC;AAUH;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,+BAI5B,iBAAiB,KAAG,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CA4C/D,CAAC"}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { audienceAdmits } from '@entifix/core';
|
|
2
|
+
import { Context, Effect, Metric, PubSub, Stream } from 'effect';
|
|
3
|
+
export class ServerPushTag extends Context.Service()('@entifix/service-shell/ServerPush') {
|
|
4
|
+
}
|
|
5
|
+
/** Events a connection subscribed to but its audience did not admit. */ export const pushFiltered = Metric.counter('entifix_push_filtered_total', {
|
|
6
|
+
description: 'Pushed events withheld from a subscribed connection by its audience.'
|
|
7
|
+
});
|
|
8
|
+
const defaultAdmits = (event, connection)=>audienceAdmits(event.audience, connection.recipient);
|
|
9
|
+
const resyncAll = (_cursor, topics)=>Stream.make({
|
|
10
|
+
_tag: 'resync',
|
|
11
|
+
topics
|
|
12
|
+
});
|
|
13
|
+
/**
|
|
14
|
+
* The in-process hub every connection on this replica reads from.
|
|
15
|
+
*
|
|
16
|
+
* One per process, fed by the host's broadcast subscription. It holds no
|
|
17
|
+
* backlog: a connection that was not open when an event was published learns
|
|
18
|
+
* of it through `resume`, never from here.
|
|
19
|
+
*/ export const makeServerPush = ({ topicsOf, admits = defaultAdmits, resume = resyncAll })=>Effect.gen(function*() {
|
|
20
|
+
const hub = yield* Effect.acquireRelease(PubSub.unbounded(), PubSub.shutdown);
|
|
21
|
+
// The event as this connection receives it, or `undefined` when it asked
|
|
22
|
+
// for none of the event's topics or its audience does not admit it.
|
|
23
|
+
const delivered = (connection)=>{
|
|
24
|
+
const wanted = new Set(connection.topics);
|
|
25
|
+
return (event)=>{
|
|
26
|
+
const topics = topicsOf(event).filter((topic)=>wanted.has(topic));
|
|
27
|
+
if (topics.length === 0) return Effect.succeed(undefined);
|
|
28
|
+
if (admits(event, connection)) return Effect.succeed({
|
|
29
|
+
_tag: 'event',
|
|
30
|
+
event,
|
|
31
|
+
topics
|
|
32
|
+
});
|
|
33
|
+
return Effect.as(Metric.update(pushFiltered, 1), undefined);
|
|
34
|
+
};
|
|
35
|
+
};
|
|
36
|
+
return {
|
|
37
|
+
publish: (event)=>Effect.asVoid(PubSub.publish(hub, event)),
|
|
38
|
+
// Subscribed before the catch-up runs, so an event published while
|
|
39
|
+
// `resume` is still reading is queued rather than falling in the gap
|
|
40
|
+
// between the two.
|
|
41
|
+
open: (connection)=>Stream.unwrap(Effect.map(PubSub.subscribe(hub), (subscription)=>{
|
|
42
|
+
const live = Stream.filter(Stream.mapEffect(Stream.fromSubscription(subscription), delivered(connection)), (message)=>message !== undefined);
|
|
43
|
+
return connection.cursor === undefined ? live : Stream.concat(resume(connection.cursor, connection.topics), live);
|
|
44
|
+
}))
|
|
45
|
+
};
|
|
46
|
+
});
|
|
47
|
+
|
|
48
|
+
//# sourceMappingURL=server-push.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../../src/push/server-push.ts"],"sourcesContent":["import {\n audienceAdmits,\n type AudienceRecipient,\n type DomainEvent,\n} from '@entifix/core';\nimport { Context, Effect, Metric, PubSub, type Scope, Stream } from 'effect';\n\n/**\n * One open push connection: who holds it, what it asked for, and where it\n * left off.\n *\n * Every field comes from the request that opened it — the topics and the\n * cursor from its URL and `Last-Event-ID`, the recipient from the verified\n * session or the flow capabilities it presented. Nothing about a connection is\n * kept anywhere else, so any replica can answer its reconnect\n * ([ADR 0021](../../../../../docs/adr/0021-server-push-and-the-multiplexed-channel.md)).\n */\nexport interface PushConnection {\n readonly recipient: AudienceRecipient;\n /** `entity:<key>`, `record:<key>:<id>` or `flow:<id>`. */\n readonly topics: readonly string[];\n /** The `Last-Event-ID` the client reconnected with, if any. */\n readonly cursor?: string;\n}\n\n/**\n * What a connection receives: an event, with the topics of this connection it\n * matched, or a request to re-read some of its topics because what it missed\n * cannot be replayed.\n *\n * The matched topics travel with the event so the browser routes it to the\n * listeners that asked, without knowing the host's topic vocabulary.\n */\nexport type PushMessage =\n | {\n readonly _tag: 'event';\n readonly event: DomainEvent;\n readonly topics: readonly string[];\n }\n | { readonly _tag: 'resync'; readonly topics: readonly string[] };\n\n/** The server half of push: what a publisher feeds and what a connection reads. */\nexport interface ServerPush {\n /** Offers one event to every open connection that subscribed and is admitted. */\n readonly publish: (event: DomainEvent) => Effect.Effect<void>;\n /**\n * The messages for one connection: the resume hook's catch-up first, then\n * every live event matching its topics and its audience, until the\n * connection's scope closes.\n */\n readonly open: (connection: PushConnection) => Stream.Stream<PushMessage>;\n}\n\nexport class ServerPushTag extends Context.Service<ServerPushTag, ServerPush>()(\n '@entifix/service-shell/ServerPush',\n) {}\n\nexport interface ServerPushOptions {\n /**\n * The topics an event belongs to. An event in no topic reaches nobody.\n *\n * Host vocabulary: an entity change might be `entity:<key>` and\n * `record:<key>:<id>`, a flow outcome `flow:<id>`.\n */\n readonly topicsOf: (event: DomainEvent) => readonly string[];\n /**\n * Whether a connection may receive an event it subscribed to. Defaults to\n * the event's own audience, which fails closed: an event naming no audience\n * reaches no connection.\n */\n readonly admits?: (event: DomainEvent, connection: PushConnection) => boolean;\n /**\n * What a reconnecting connection missed, answered from a read model the host\n * already has. Omitted, a connection with a cursor is told to re-read every\n * topic it holds.\n */\n readonly resume?: (\n cursor: string,\n topics: readonly string[],\n ) => Stream.Stream<PushMessage>;\n}\n\n/** Events a connection subscribed to but its audience did not admit. */\nexport const pushFiltered = Metric.counter('entifix_push_filtered_total', {\n description:\n 'Pushed events withheld from a subscribed connection by its audience.',\n});\n\nconst defaultAdmits = (event: DomainEvent, connection: PushConnection) =>\n audienceAdmits(event.audience, connection.recipient);\n\nconst resyncAll = (\n _cursor: string,\n topics: readonly string[],\n): Stream.Stream<PushMessage> => Stream.make({ _tag: 'resync', topics });\n\n/**\n * The in-process hub every connection on this replica reads from.\n *\n * One per process, fed by the host's broadcast subscription. It holds no\n * backlog: a connection that was not open when an event was published learns\n * of it through `resume`, never from here.\n */\nexport const makeServerPush = ({\n topicsOf,\n admits = defaultAdmits,\n resume = resyncAll,\n}: ServerPushOptions): Effect.Effect<ServerPush, never, Scope.Scope> =>\n Effect.gen(function* () {\n const hub = yield* Effect.acquireRelease(\n PubSub.unbounded<DomainEvent>(),\n PubSub.shutdown,\n );\n\n // The event as this connection receives it, or `undefined` when it asked\n // for none of the event's topics or its audience does not admit it.\n const delivered = (connection: PushConnection) => {\n const wanted = new Set(connection.topics);\n return (event: DomainEvent): Effect.Effect<PushMessage | undefined> => {\n const topics = topicsOf(event).filter(topic => wanted.has(topic));\n if (topics.length === 0) return Effect.succeed(undefined);\n if (admits(event, connection))\n return Effect.succeed({ _tag: 'event', event, topics });\n return Effect.as(Metric.update(pushFiltered, 1), undefined);\n };\n };\n\n return {\n publish: event => Effect.asVoid(PubSub.publish(hub, event)),\n // Subscribed before the catch-up runs, so an event published while\n // `resume` is still reading is queued rather than falling in the gap\n // between the two.\n open: connection =>\n Stream.unwrap(\n Effect.map(PubSub.subscribe(hub), subscription => {\n const live = Stream.filter(\n Stream.mapEffect(\n Stream.fromSubscription(subscription),\n delivered(connection),\n ),\n (message): message is PushMessage => message !== undefined,\n );\n return connection.cursor === undefined\n ? live\n : Stream.concat(\n resume(connection.cursor, connection.topics),\n live,\n );\n }),\n ),\n };\n });\n"],"names":["audienceAdmits","Context","Effect","Metric","PubSub","Stream","ServerPushTag","Service","pushFiltered","counter","description","defaultAdmits","event","connection","audience","recipient","resyncAll","_cursor","topics","make","_tag","makeServerPush","topicsOf","admits","resume","gen","hub","acquireRelease","unbounded","shutdown","delivered","wanted","Set","filter","topic","has","length","succeed","undefined","as","update","publish","asVoid","open","unwrap","map","subscribe","subscription","live","mapEffect","fromSubscription","message","cursor","concat"],"mappings":"AAAA,SACEA,cAAc,QAGT,gBAAgB;AACvB,SAASC,OAAO,EAAEC,MAAM,EAAEC,MAAM,EAAEC,MAAM,EAAcC,MAAM,QAAQ,SAAS;AAgD7E,OAAO,MAAMC,sBAAsBL,QAAQM,OAAO,GAChD;AACC;AA2BH,sEAAsE,GACtE,OAAO,MAAMC,eAAeL,OAAOM,OAAO,CAAC,+BAA+B;IACxEC,aACE;AACJ,GAAG;AAEH,MAAMC,gBAAgB,CAACC,OAAoBC,aACzCb,eAAeY,MAAME,QAAQ,EAAED,WAAWE,SAAS;AAErD,MAAMC,YAAY,CAChBC,SACAC,SAC+Bb,OAAOc,IAAI,CAAC;QAAEC,MAAM;QAAUF;IAAO;AAEtE;;;;;;CAMC,GACD,OAAO,MAAMG,iBAAiB,CAAC,EAC7BC,QAAQ,EACRC,SAASZ,aAAa,EACtBa,SAASR,SAAS,EACA,GAClBd,OAAOuB,GAAG,CAAC;QACT,MAAMC,MAAM,OAAOxB,OAAOyB,cAAc,CACtCvB,OAAOwB,SAAS,IAChBxB,OAAOyB,QAAQ;QAGjB,yEAAyE;QACzE,oEAAoE;QACpE,MAAMC,YAAY,CAACjB;YACjB,MAAMkB,SAAS,IAAIC,IAAInB,WAAWK,MAAM;YACxC,OAAO,CAACN;gBACN,MAAMM,SAASI,SAASV,OAAOqB,MAAM,CAACC,CAAAA,QAASH,OAAOI,GAAG,CAACD;gBAC1D,IAAIhB,OAAOkB,MAAM,KAAK,GAAG,OAAOlC,OAAOmC,OAAO,CAACC;gBAC/C,IAAIf,OAAOX,OAAOC,aAChB,OAAOX,OAAOmC,OAAO,CAAC;oBAAEjB,MAAM;oBAASR;oBAAOM;gBAAO;gBACvD,OAAOhB,OAAOqC,EAAE,CAACpC,OAAOqC,MAAM,CAAChC,cAAc,IAAI8B;YACnD;QACF;QAEA,OAAO;YACLG,SAAS7B,CAAAA,QAASV,OAAOwC,MAAM,CAACtC,OAAOqC,OAAO,CAACf,KAAKd;YACpD,mEAAmE;YACnE,qEAAqE;YACrE,mBAAmB;YACnB+B,MAAM9B,CAAAA,aACJR,OAAOuC,MAAM,CACX1C,OAAO2C,GAAG,CAACzC,OAAO0C,SAAS,CAACpB,MAAMqB,CAAAA;oBAChC,MAAMC,OAAO3C,OAAO4B,MAAM,CACxB5B,OAAO4C,SAAS,CACd5C,OAAO6C,gBAAgB,CAACH,eACxBjB,UAAUjB,cAEZ,CAACsC,UAAoCA,YAAYb;oBAEnD,OAAOzB,WAAWuC,MAAM,KAAKd,YACzBU,OACA3C,OAAOgD,MAAM,CACX7B,OAAOX,WAAWuC,MAAM,EAAEvC,WAAWK,MAAM,GAC3C8B;gBAER;QAEN;IACF,GAAG"}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import { Duration, Effect, Metric, type Scope } from 'effect';
|
|
2
|
+
import { HttpServerResponse } from 'effect/http';
|
|
3
|
+
import { type PushConnection, ServerPushTag } from './server-push.js';
|
|
4
|
+
/**
|
|
5
|
+
* How often an idle push connection sends a comment frame.
|
|
6
|
+
*
|
|
7
|
+
* 15 s sits under the common 30 s idle timeout with room for one lost frame.
|
|
8
|
+
* An edge in front of the stream must hold an idle connection for more than
|
|
9
|
+
* twice this, or it closes healthy streams
|
|
10
|
+
* ([ADR 0021](../../../../../docs/adr/0021-server-push-and-the-multiplexed-channel.md)).
|
|
11
|
+
*/
|
|
12
|
+
export declare const PUSH_HEARTBEAT: Duration.Duration;
|
|
13
|
+
export interface SsePushDials {
|
|
14
|
+
/**
|
|
15
|
+
* The range a connection's `retry:` is drawn from, in milliseconds.
|
|
16
|
+
*
|
|
17
|
+
* Drawn per connection, so a redeploy that closes every stream at once does
|
|
18
|
+
* not have every browser reconnect in the same instant.
|
|
19
|
+
*/
|
|
20
|
+
readonly retryMs: {
|
|
21
|
+
readonly min: number;
|
|
22
|
+
readonly max: number;
|
|
23
|
+
};
|
|
24
|
+
/** How long before the token's `exp` the connection asks for a reauth. */
|
|
25
|
+
readonly reauthMarginMs: number;
|
|
26
|
+
/**
|
|
27
|
+
* How long a shutdown waits for its drained connections to send their last
|
|
28
|
+
* frame, in milliseconds. Defaults to 5 000.
|
|
29
|
+
*/
|
|
30
|
+
readonly drainWindowMs?: number;
|
|
31
|
+
/** Injectable for tests; `[0, 1)`, defaults to `Math.random`. */
|
|
32
|
+
readonly random?: () => number;
|
|
33
|
+
}
|
|
34
|
+
export interface SsePushConnection extends PushConnection {
|
|
35
|
+
/**
|
|
36
|
+
* Unix seconds at which the credential that opened the stream expires — the
|
|
37
|
+
* verified token's `exp`. Omitted for a connection with no expiring
|
|
38
|
+
* credential, such as one opened with flow capabilities only.
|
|
39
|
+
*/
|
|
40
|
+
readonly expiresAt?: number;
|
|
41
|
+
}
|
|
42
|
+
export interface SsePush {
|
|
43
|
+
/** Serves one connection as `text/event-stream`. */
|
|
44
|
+
readonly respond: (connection: SsePushConnection) => HttpServerResponse.HttpServerResponse;
|
|
45
|
+
}
|
|
46
|
+
/** Open push connections on this process. */
|
|
47
|
+
export declare const pushConnections: Metric.Gauge<number>;
|
|
48
|
+
export declare const pushOpened: Metric.Counter<number>;
|
|
49
|
+
export declare const pushClosed: Metric.Counter<number>;
|
|
50
|
+
export declare const pushDrained: Metric.Counter<number>;
|
|
51
|
+
export declare const pushReauth: Metric.Counter<number>;
|
|
52
|
+
export declare const pushUnencodable: Metric.Counter<number>;
|
|
53
|
+
/**
|
|
54
|
+
* The SSE adapter of the push port.
|
|
55
|
+
*
|
|
56
|
+
* Every connection opens with its own randomized `retry:`, sends a comment
|
|
57
|
+
* every {@link PUSH_HEARTBEAT}, asks for a reauth at `exp − margin` and closes
|
|
58
|
+
* cleanly instead of failing a reconnect with a 401, and is drained — a fresh
|
|
59
|
+
* `retry:` and then EOF — when this adapter's scope closes.
|
|
60
|
+
*/
|
|
61
|
+
export declare const makeSsePush: ({ retryMs, reauthMarginMs, drainWindowMs, random, }: SsePushDials) => Effect.Effect<SsePush, never, ServerPushTag | Scope.Scope>;
|
|
62
|
+
//# sourceMappingURL=sse.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/push/sse.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,QAAQ,EACR,MAAM,EAEN,MAAM,EAEN,KAAK,KAAK,EAEX,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EACL,KAAK,cAAc,EAEnB,aAAa,EACd,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,mBAAuB,CAAC;AAEnD,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,0EAA0E;IAC1E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,OAAO;IACtB,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,CAChB,UAAU,EAAE,iBAAiB,KAC1B,kBAAkB,CAAC,kBAAkB,CAAC;CAC5C;AAED,6CAA6C;AAC7C,eAAO,MAAM,eAAe,sBAE1B,CAAC;AACH,eAAO,MAAM,UAAU,wBAErB,CAAC;AACH,eAAO,MAAM,UAAU,wBAErB,CAAC;AACH,eAAO,MAAM,WAAW,wBAEtB,CAAC;AACH,eAAO,MAAM,UAAU,wBAErB,CAAC;AACH,eAAO,MAAM,eAAe,wBAG3B,CAAC;AA6BF;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,qDAKzB,YAAY,KAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,aAAa,GAAG,KAAK,CAAC,KAAK,CAyIvE,CAAC"}
|