@bett3r-dev/pv3 1.0.0 → 1.1.7

package/build/ports/endpoints/declarationSite.js

@@ -0,0 +1,126 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDeclarationSite = exports.resolveDeclarationFrame = void 0;
+const path_1 = __importDefault(require("path"));
+const modulePath_1 = require("../../libraries/modulePath");
+/**
+ * Turns a V8 stack frame into the file it points at and the function that owns it.
+ * Handles the three shapes V8 emits: `at fn (/file:1:2)`, `at /file:1:2` and
+ * `at Object.<anonymous> (/file:1:2)`.
+ */
+const parseFrame = (frame) => {
+    const trimmed = frame.trim();
+    if (!trimmed.startsWith('at '))
+        return undefined;
+    const body = trimmed.slice(3);
+    const locationStart = body.lastIndexOf('(');
+    const location = locationStart === -1 ? body : body.slice(locationStart + 1).replace(/\)$/, '');
+    const descriptor = locationStart === -1 ? '' : body.slice(0, locationStart).trim();
+    const filePath = location.replace(/:\d+:\d+$/, '');
+    // Node internals (`node:internal/modules/...`) name no source file we can use.
+    if (!filePath || filePath.startsWith('node:'))
+        return undefined;
+    // `async foo` / `new Foo` / `Object.foo` -> `foo`; `Object.<anonymous>` -> none.
+    const functionName = descriptor
+        .replace(/^(async|new)\s+/, '')
+        .split('.')
+        .pop();
+    return {
+        filePath,
+        functionName: functionName && !functionName.includes('<') ? functionName : undefined
+    };
+};
+/** `.../modules/<name>/index.ts` — the module's own composition root, in any tree. */
+const MODULE_COMPOSITION_ROOT = /[/\\]modules[/\\][^/\\]+[/\\]index\.[cm]?[jt]sx?$/;
+/** The first path segment of `filePath` below `directory`, or nothing if it is not below it. */
+const segmentUnder = (directory, filePath) => {
+    const relative = path_1.default.relative(directory, filePath);
+    if (!relative || relative.startsWith('..') || path_1.default.isAbsolute(relative))
+        return undefined;
+    return relative.split(/[/\\]/)[0];
+};
+/**
+ * Which bucket the declaring file falls in.
+ *
+ * The pv3 boundary is derived from `portDirectory` — i.e. from the stack —
+ * because `__dirname` disagrees with it (see `resolveDeclarationFrame` below).
+ * `portDirectory` is `<pv3>/{src,build}/ports/endpoints` in every tree pv3 runs
+ * from, so three levels up is the pv3 package and four is the directory its
+ * sibling packages live in: `packages/` in this monorepo,
+ * `node_modules/@bett3r-dev/` in a consumer. Those siblings matter — pv3-admin-server
+ * registers 17 routes on the real port and is not inside `packages/pv3`.
+ *
+ * The module tree is tested FIRST because a file can sit in both and only one
+ * answer places it in a deployment unit. pv3 ships no `modules/<name>/`
+ * directory of its own, so the two only overlap for the fixtures under
+ * `__tests__/fixtures/modules/`, which exist to exercise exactly this.
+ */
+const classifyDeclaration = (filePath, portDirectory) => {
+    if ((0, modulePath_1.moduleFromPath)(filePath)) {
+        return MODULE_COMPOSITION_ROOT.test(filePath) ? 'moduleIndex' : 'module';
+    }
+    const pv3Package = path_1.default.resolve(portDirectory, '..', '..', '..');
+    if (segmentUnder(pv3Package, filePath))
+        return 'framework';
+    // Anchored at the directory the pv3 package itself sits in, never matched by
+    // name anywhere in the path: a checkout at `~/development/pv3-2257` is not pv3.
+    const sibling = segmentUnder(path_1.default.dirname(pv3Package), filePath);
+    return sibling?.startsWith('pv3') ? 'framework' : 'foreign';
+};
+/**
+ * The first frame outside the endpoints port — i.e. the caller that registered
+ * the endpoint. Exported for testing: the interesting failures are all about
+ * which frame gets picked, and a real stack cannot express them.
+ *
+ * The boundary is read off the stack rather than from `__dirname`, because the
+ * two disagree. A consumer running under ts-node loads the port from `build/`
+ * (so `__dirname` is the emitted tree) while source-map-support rewrites the
+ * frames to the original `src/**.ts` — comparing the two attributed EVERY
+ * endpoint to this file. Since the Error is constructed here, the topmost frame
+ * is always this module in whichever tree the stack reports, and `index.ts`'s
+ * `registerEndpoint` is its neighbour, so one directory skips both.
+ */
+const resolveDeclarationFrame = (frames) => {
+    let portDirectory;
+    for (const frame of frames) {
+        const parsed = parseFrame(frame);
+        if (!parsed)
+            continue;
+        const filePath = path_1.default.resolve(parsed.filePath);
+        const directory = path_1.default.dirname(filePath);
+        if (portDirectory === undefined) {
+            portDirectory = directory;
+            continue;
+        }
+        if (directory === portDirectory)
+            continue;
+        return {
+            filePath,
+            exportName: parsed.functionName,
+            kind: classifyDeclaration(filePath, portDirectory)
+        };
+    }
+    return undefined;
+};
+exports.resolveDeclarationFrame = resolveDeclarationFrame;
+/**
+ * Where the caller registered the endpoint from.
+ *
+ * @param description names the endpoint in the failure message, since a
+ * declaration site that cannot be captured would otherwise drop the endpoint
+ * from the deployment manifest silently.
+ */
+const getDeclarationSite = (description) => {
+    const site = (0, exports.resolveDeclarationFrame)(Error().stack?.split('\n') || []);
+    if (!site) {
+        throw Error(`[pv3] Could not determine the file that declared ${description}. ` +
+            'Where a route was declared is what decides whether it is a manual endpoint ' +
+            'at all, and which deployment unit owns it — register it from a module source file.');
+    }
+    return site;
+};
+exports.getDeclarationSite = getDeclarationSite;
+//# sourceMappingURL=declarationSite.js.map

package/build/ports/endpoints/declarationSite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declarationSite.js","sourceRoot":"","sources":["../../../src/ports/endpoints/declarationSite.ts"],"names":[],"mappings":"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"}

package/build/ports/endpoints/health.d.ts

@@ -0,0 +1,26 @@
+import { EndpointsAdapter } from '@bett3r-dev/pv3-types';
+/**
+ * Kind of health probe. `liveness` probes gate `GET /health` (a red one makes K8s
+ * restart the pod). `readiness` probes additionally gate `GET /ready` (a red one
+ * makes K8s depool the pod without restarting it). Readiness is strictly stronger
+ * than liveness: `/ready` ANDs all liveness AND all readiness probes.
+ */
+export type HealthProbeKind = 'liveness' | 'readiness';
+/** A health probe. May be sync or async; anything other than `true` is unhealthy. */
+export type HealthProbe = () => boolean | Promise<boolean>;
+export type RegisterHealthProbeOptions = {
+    kind?: HealthProbeKind;
+};
+export type HealthState = {
+    registerHealthProbe: (name: string, probe: HealthProbe, opts?: RegisterHealthProbeOptions) => void;
+    markServiceAsHealthy: () => void;
+    markServiceAsUnhealthy: (reason?: string) => void;
+    registerHealthRoutes: (adapter: EndpointsAdapter) => void;
+};
+export declare const createHealthState: (params: {
+    packageJson: {
+        name: string;
+        version: string;
+    };
+}) => HealthState;
+//# sourceMappingURL=health.d.ts.map

package/build/ports/endpoints/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../../src/ports/endpoints/health.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAA2B,MAAM,uBAAuB,CAAC;AAElF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,WAAW,CAAC;AAEvD,qFAAqF;AACrF,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAE3D,MAAM,MAAM,0BAA0B,GAAG;IAAE,IAAI,CAAC,EAAE,eAAe,CAAA;CAAE,CAAC;AAEpE,MAAM,MAAM,WAAW,GAAG;IACxB,mBAAmB,EAAE,CAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,0BAA0B,KAAM,IAAI,CAAC;IACrG,oBAAoB,EAAE,MAAM,IAAI,CAAC;IACjC,sBAAsB,EAAE,CAAE,MAAM,CAAC,EAAE,MAAM,KAAM,IAAI,CAAC;IACpD,oBAAoB,EAAE,CAAE,OAAO,EAAE,gBAAgB,KAAM,IAAI,CAAC;CAC7D,CAAC;AAoBF,eAAO,MAAM,iBAAiB,WAAa;IAAE,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAC,KAAG,WA4E9F,CAAC"}

package/build/ports/endpoints/health.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHealthState = void 0;
+const pv3_types_1 = require("@bett3r-dev/pv3-types");
+/**
+ * Owns the endpoints port's health-gating state and mounts the health routes on an
+ * httpAdapter. Routes are registered **directly on the adapter** (not via the port's
+ * `registerEndpoint`) so they stay out of the OpenAPI spec + MDU/deployment-unit list.
+ *
+ * Default state (no probes, manual = healthy) reports 200, preserving today's always-green
+ * `/healthcheck`. The named-probe registry (S3) plugs into `evaluate` without changing the
+ * route wiring.
+ */
+const DEFAULT_MANUAL_REASON = 'Service marked unhealthy';
+/**
+ * Per-probe evaluation budget. A probe that does not resolve within this window is treated as
+ * unhealthy (fail-closed) — a probe that cannot answer promptly is a probe that is unhealthy.
+ * Kept short (K8s probe timeouts default to 1s) so a wedged probe is caught quickly.
+ */
+const HEALTH_PROBE_TIMEOUT_MS = 1000;
+const createHealthState = (params) => {
+    const { packageJson } = params;
+    const okBody = () => ({
+        status: 'ok',
+        timestamp: new Date().toISOString(),
+        service: packageJson.name,
+        version: packageJson.version
+    });
+    // Built-in `manual` liveness gate, toggled by markServiceAsHealthy / markServiceAsUnhealthy.
+    // It applies to both /health (liveness) and /ready (readiness), since readiness ANDs liveness.
+    const manual = { healthy: true, reason: undefined };
+    // Named probes, AND-ed per kind. Insertion order is preserved so the 503 reason names the
+    // first (in registration order) failing probe.
+    const probes = new Map();
+    // Fail-closed: a probe returning anything but `true`, throwing, or exceeding the timeout is unhealthy.
+    const evaluateProbe = async (name, probe) => {
+        let timer;
+        try {
+            const timeout = new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error(`timed out after ${HEALTH_PROBE_TIMEOUT_MS}ms`)), HEALTH_PROBE_TIMEOUT_MS);
+            });
+            const result = await Promise.race([Promise.resolve().then(probe), timeout]);
+            if (result === true)
+                return { name, ok: true };
+            return { name, ok: false, reason: `Health probe '${name}' reported unhealthy` };
+        }
+        catch (error) {
+            return { name, ok: false, reason: `Health probe '${name}' failed: ${error.message}` };
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    };
+    const evaluate = async (kind) => {
+        // Manual gate is a liveness probe — it applies to both /health and /ready, and is checked first.
+        if (!manual.healthy)
+            return { ok: false, reason: manual.reason || DEFAULT_MANUAL_REASON };
+        // /health = liveness probes; /ready = liveness AND readiness probes (readiness is strictly stronger).
+        const kinds = kind === 'readiness' ? ['liveness', 'readiness'] : ['liveness'];
+        const entries = [...probes.entries()].filter(([, entry]) => kinds.includes(entry.kind));
+        const results = await Promise.all(entries.map(([name, { probe }]) => evaluateProbe(name, probe)));
+        const failing = results.find(result => !result.ok);
+        if (failing)
+            return { ok: false, reason: failing.reason };
+        return { ok: true };
+    };
+    const guard = async (kind) => {
+        const result = await evaluate(kind);
+        if (!result.ok)
+            throw new pv3_types_1.ServiceUnavailableError(result.reason, 'SERVICE_UNAVAILABLE_ERROR', result.reason);
+        return okBody();
+    };
+    const livenessHandler = () => guard('liveness');
+    const readinessHandler = () => guard('readiness');
+    const registerHealthProbe = (name, probe, opts) => {
+        probes.set(name, { probe, kind: opts?.kind || 'liveness' });
+    };
+    const markServiceAsHealthy = () => {
+        manual.healthy = true;
+        manual.reason = undefined;
+    };
+    const markServiceAsUnhealthy = (reason) => {
+        manual.healthy = false;
+        manual.reason = reason;
+    };
+    const registerHealthRoutes = (adapter) => {
+        adapter.registerEndpoint({ name: 'health', loggingModule: 'server', method: 'GET', route: '/health', action: livenessHandler });
+        adapter.registerEndpoint({ name: 'ready', loggingModule: 'server', method: 'GET', route: '/ready', action: readinessHandler });
+        // Deprecated alias of /health (liveness) — retained so an unknown existing helm probe path keeps working.
+        adapter.registerEndpoint({ name: 'healthcheck', loggingModule: 'server', method: 'GET', route: '/healthcheck', action: livenessHandler });
+    };
+    return { registerHealthProbe, markServiceAsHealthy, markServiceAsUnhealthy, registerHealthRoutes };
+};
+exports.createHealthState = createHealthState;
+//# sourceMappingURL=health.js.map

package/build/ports/endpoints/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../../src/ports/endpoints/health.ts"],"names":[],"mappings":"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"}

package/build/ports/endpoints/index.d.ts

@@ -1,9 +1,9 @@
-/// <reference types="node" />
 import { ConfigurationPort, EndpointsAdapter, EndpointsPort } from '@bett3r-dev/pv3-types';
 import querystring from 'querystring';
+export { generateOpenApiDocument, getDefaultReadmodelQuerySchemaOpenApi } from './openApi';
 export * from './utils';
 export declare const optionalParamRegexp: RegExp;
-export declare const pathRegex: RegExp;
+export declare const pathRegexp: RegExp;
 export declare const getPathInfo: (path: string) => {
     original: string;
     base: string;
@@ -11,19 +11,55 @@ export declare const getPathInfo: (path: string) => {
     query: "" | querystring.ParsedUrlQuery;
 } | null;
 export declare const PackageJsonSchema: import("@bett3r-dev/jsonschema-definer").ObjectSchema<{
-    host?: string | undefined;
-    version: string;
     name: string;
+    version: string;
+    host?: string | undefined;
 }, true>;
 export type PackageJsonType = typeof PackageJsonSchema.type;
 export declare const EndpointsConfigSchema: import("@bett3r-dev/jsonschema-definer").ObjectSchema<{
     outOpenApiFileFilePath?: string | undefined;
     serviceDiscoveryUrl?: string | undefined;
+    internalGatewayUrl: string;
+    keepAliveTimeoutMs?: number | undefined;
+    keepAliveConnectionsPerOrigin?: number | undefined;
 }, true>;
 export type EndpointsConfigType = typeof EndpointsConfigSchema.type;
-export declare const Endpoints: (params: {
+/**
+ * Host-supplied credential minter for OUT-OF-PROCESS calls.
+ *
+ * Invoked once per `call()` that leaves the process, with the call's context, and its
+ * headers are merged onto the outbound request LAST — after `context.headers` — so a
+ * caller cannot forge the credential by passing the same header name in `context.headers`.
+ *
+ * This is the ONLY thing the port attaches to an outbound call beyond the caller's own
+ * headers. It replaced `contextToHeadersMap`, a config that projected `context.user` onto
+ * `X-Auth-*` headers and that no consumer ever set, so the branch that leaves the process
+ * silently attached an empty bag while reading as if identity were handled.
+ *
+ * Both layers are lower-cased before the merge, which is what makes "last wins" hold:
+ * HTTP header names are case-insensitive, but object keys are not, and `fetch` COMBINES
+ * differently-cased duplicates into one comma-joined value rather than dropping the
+ * earlier one. Un-normalized, a caller passing `X-Teselly-Authz` against a hook returning
+ * `x-teselly-authz` would prepend its own value to the credential the receiving service
+ * parses. Consequence to be aware of: outbound header names are always emitted
+ * lower-case, whatever case the caller used.
+ *
+ * If the hook throws, `call()` rejects and no request is issued — a call that should carry
+ * a credential and cannot mint one fails closed rather than leaving unauthenticated.
+ *
+ * pv3 ships no policy: what the credential is, and whether a given call gets one at all,
+ * is entirely the host app's decision. Returning `undefined` attaches nothing.
+ *
+ * Deliberately NOT invoked on the in-process branch: a locally registered route is a
+ * direct function call in the same async context, so there is no request to authorize
+ * and minting a credential there would be pure cost.
+ */
+export type OutboundCredentialHook = (params: {
+    context?: unknown;
+}) => Record<string, string> | undefined | Promise<Record<string, string> | undefined>;
+export declare const Endpoints: <USER = any>(params: {
     packageJson: PackageJsonType;
     configuration: ConfigurationPort;
-    supportedModules?: Record<string, string[]>;
-}, ...adapters: EndpointsAdapter[]) => EndpointsPort;
+    outboundCredential?: OutboundCredentialHook;
+}, ...adapters: EndpointsAdapter[]) => EndpointsPort<USER>;
 //# sourceMappingURL=index.d.ts.map

package/build/ports/endpoints/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ports/endpoints/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,iBAAiB,EAAkC,gBAAgB,EAAmC,aAAa,EAA4C,MAAM,uBAAuB,CAAC;AAMtM,OAAO,WAAW,MAAM,aAAa,CAAC;AAGtC,cAAc,SAAS,CAAC;AAExB,eAAO,MAAM,mBAAmB,QAAyB,CAAC;AAC1D,eAAO,MAAM,SAAS,QAA+C,CAAC;AAEtE,eAAO,MAAM,WAAW,SAAW,MAAM;;;;;QAQxC,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;QAI5B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAC;AAE5D,eAAO,MAAM,qBAAqB;;;QAGhC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,qBAAqB,CAAC,IAAI,CAAC;AAEpE,eAAO,MAAM,SAAS,WAAa;IAAC,WAAW,EAAE,eAAe,CAAC;IAAC,aAAa,EAAE,iBAAiB,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,MAAM,EAAC,MAAM,EAAE,CAAC,CAAA;CAAC,eAAe,gBAAgB,EAAE,KAAG,aAwOlL,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ports/endpoints/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAkC,gBAAgB,EAAmC,aAAa,EAA8E,MAAM,uBAAuB,CAAC;AAOxO,OAAO,WAAW,MAAM,aAAa,CAAC;AAStC,OAAO,EAAE,uBAAuB,EAAE,qCAAqC,EAAE,MAAM,WAAW,CAAC;AAC3F,cAAc,SAAS,CAAC;AAExB,eAAO,MAAM,mBAAmB,QAAyB,CAAC;AAC1D,eAAO,MAAM,UAAU,QAA+C,CAAC;AAEvE,eAAO,MAAM,WAAW,SAAW,MAAM;;;;;QAQxC,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;QAI5B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAC;AAE5D,eAAO,MAAM,qBAAqB;;;;;;QAmChC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,qBAAqB,CAAC,IAAI,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,sBAAsB,GAAG,CACnC,MAAM,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,KAC1B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC;AAEtF,eAAO,MAAM,SAAS,GAAI,IAAI,GAAG,GAAG,UAAW;IAAE,WAAW,EAAE,eAAe,CAAC;IAAC,aAAa,EAAE,iBAAiB,CAAC;IAAC,kBAAkB,CAAC,EAAE,sBAAsB,CAAA;CAAE,eAAe,gBAAgB,EAAE,KAAG,aAAa,CAAC,IAAI,CAmenN,CAAC"}