@lib-acr/express 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Application Control Room
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @lib-acr/express
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Express middleware: one `http_request` event per request (method, route template, status, duration, body sizes), X-Request-Id correlation, W3C traceparent joining, and an error handler that reports server-side failures.
+
+## Install
+
+```bash
+npm install @lib-acr/express
+```
+
+## Quick start
+
+```ts
+import express from 'express';
+import { ACRMiddleware, ACRErrorHandler, acrTraceHeaders } from '@lib-acr/express';
+
+import { ACR } from '@lib-acr/node';
+
+const acr = new ACR({ apiKey, apiSecret, endpoint });   // one client for the whole process
+const app = express();
+app.use(ACRMiddleware({ client: acr }));
+
+app.get('/orders/:id', (req, res) => {
+  // req.acr.traceId / requestId are available for logs; acrTraceHeaders(req) for outgoing calls
+  res.json({ id: req.params.id });
+});
+
+app.use(ACRErrorHandler({ client: acr }));
+```
+
+Passing `client` is recommended. You can pass `options` instead; one client is created per options object, so give
+both handlers the **same** object (`const cfg = {…}; ACRMiddleware({ options: cfg }); ACRErrorHandler({ options: cfg })`).
+Two different objects create two clients with separate buffers.
+
+## Notes
+
+Route templates are recorded (`/orders/:id`), never concrete URLs. Unmatched paths are recorded as `(unmatched)`. Headers, query strings and bodies are never recorded. Health and readiness paths are ignored by default.
+
+## Remote control
+
+Opt-in maintenance mode. Register it before your routes:
+
+```ts
+import { maintenanceMiddleware } from '@lib-acr/express';
+
+app.use(maintenanceMiddleware({
+  client: acr,
+  getUserId: (req) => req.user?.id,            // users in allowUserIds keep access
+  exempt: (req) => req.path.startsWith('/webhooks'),
+}));
+```
+
+While maintenance is on, requests get `503` with `{ "error": "MAINTENANCE", "message": "…", "endsAt": "…" | null }`
+and `Retry-After` (seconds until `endsAt`, otherwise 300). `/health`, `/healthz`, `/ready` and `/readyz` always pass,
+including under a prefix such as `/api/health`.
+
+## Feature flags
+
+```ts
+app.get('/checkout', (req, res) => {
+  const variant = acr.flag('new-checkout', false, { userId: req.user?.id }) ? 'new' : 'old';
+  res.json({ variant });
+});
+```
+
+## Wire protocol
+
+Every SDK sends the same protocol: `POST {endpoint}/ingest/{events|logs|errors|heartbeat}` with the `X-ACR-Api-Key`
+header (and `X-ACR-Secret-Key` for server keys). The credential determines the app and environment. The body is
+`{ schemaVersion: 1, sdk, items[1..500] }`.
+Each item has a client `id`, which lets the server drop duplicates when a batch is retried.
+
+Retries use exponential backoff with jitter for network errors, 429 and 5xx responses. Other 4xx responses are not retried.
+Telemetry is buffered in a bounded in-memory queue. When it is full, the oldest items are dropped and counted in `stats()`.
+SDK code never throws into the host application.
+
+Metrics (`increment`, `gauge`, `histogram`) and traces are not yet available.

package/dist/cjs/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_INFO = exports.resolveClient = exports.maintenanceMiddleware = exports.contextFromRequest = exports.acrTraceHeaders = exports.ACRErrorHandler = exports.ACRMiddleware = void 0;
+var middleware_js_1 = require("./middleware.js");
+Object.defineProperty(exports, "ACRMiddleware", { enumerable: true, get: function () { return middleware_js_1.ACRMiddleware; } });
+Object.defineProperty(exports, "ACRErrorHandler", { enumerable: true, get: function () { return middleware_js_1.ACRErrorHandler; } });
+Object.defineProperty(exports, "acrTraceHeaders", { enumerable: true, get: function () { return middleware_js_1.acrTraceHeaders; } });
+Object.defineProperty(exports, "contextFromRequest", { enumerable: true, get: function () { return middleware_js_1.contextFromRequest; } });
+Object.defineProperty(exports, "maintenanceMiddleware", { enumerable: true, get: function () { return middleware_js_1.maintenanceMiddleware; } });
+Object.defineProperty(exports, "resolveClient", { enumerable: true, get: function () { return middleware_js_1.resolveClient; } });
+__exportStar(require("@lib-acr/node"), exports);
+var sdk_info_js_1 = require("./sdk-info.js");
+Object.defineProperty(exports, "SDK_INFO", { enumerable: true, get: function () { return sdk_info_js_1.SDK_INFO; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,iDAA4I;AAAnI,8GAAA,aAAa,OAAA;AAAE,gHAAA,eAAe,OAAA;AAAE,gHAAA,eAAe,OAAA;AAAE,mHAAA,kBAAkB,OAAA;AAAE,sHAAA,qBAAqB,OAAA;AAAE,8GAAA,aAAa,OAAA;AAElH,gDAA8B;AAC9B,6CAAyC;AAAhC,uGAAA,QAAQ,OAAA"}

package/dist/cjs/middleware.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveClient = resolveClient;
+exports.contextFromRequest = contextFromRequest;
+exports.ACRMiddleware = ACRMiddleware;
+exports.ACRErrorHandler = ACRErrorHandler;
+exports.acrTraceHeaders = acrTraceHeaders;
+exports.maintenanceMiddleware = maintenanceMiddleware;
+const core_1 = require("@lib-acr/core");
+const node_1 = require("@lib-acr/node");
+const sdk_info_js_1 = require("./sdk-info.js");
+const DEFAULT_IGNORED = ['/health', '/healthz', '/ready', '/readyz', '/favicon.ico'];
+const REQUEST_ID_RE = /^[\w.-]{1,64}$/;
+/** Clients created from `options`, keyed by the options object, so the middleware and the error handler share one. */
+const clientsByOptions = new WeakMap();
+/**
+ * Returns `options.client`, or the client created for `options.options`. The same options object always yields the
+ * same client, so ACRMiddleware and ACRErrorHandler configured with it share one buffer and one flush timer.
+ */
+function resolveClient(options) {
+    if (options.client)
+        return options.client;
+    if (!options.options)
+        throw new Error('[acr] ExpressAcrOptions needs either client or options');
+    const existing = clientsByOptions.get(options.options);
+    if (existing)
+        return existing;
+    const created = new node_1.ACR(options.options, sdk_info_js_1.SDK_INFO);
+    clientsByOptions.set(options.options, created);
+    return created;
+}
+function isIgnored(path, ignored) {
+    return ignored.some((p) => (typeof p === 'string' ? p === path : p.test(path)));
+}
+/** Reads trace headers. The rest of the request headers are never kept. */
+function contextFromRequest(req) {
+    const parsed = (0, core_1.parseTraceparent)(req.get('traceparent'));
+    const incomingRequestId = req.get('x-request-id');
+    const requestId = incomingRequestId && REQUEST_ID_RE.test(incomingRequestId) ? incomingRequestId : (0, core_1.generateId)();
+    return {
+        traceId: parsed?.traceId ?? (0, core_1.generateTraceId)(),
+        spanId: (0, core_1.generateSpanId)(),
+        parentSpanId: parsed?.spanId ?? null,
+        requestId,
+    };
+}
+/** Route template only (for example /orders/:id), never the concrete URL, so cardinality stays bounded. */
+function routeOf(req) {
+    if (!req.route)
+        return '(unmatched)';
+    const path = typeof req.route.path === 'string' ? req.route.path : '';
+    return `${req.baseUrl ?? ''}${path}` || '/';
+}
+/**
+ * Records one `http_request` event per request: method, route template, status, duration and body sizes. It sets
+ * X-Request-Id on the response and exposes req.acr for logs and errors. Headers, query strings and bodies are not
+ * recorded.
+ */
+function ACRMiddleware(options) {
+    const client = resolveClient(options);
+    const ignored = [...DEFAULT_IGNORED, ...(options.ignorePaths ?? [])];
+    const eventName = options.eventName ?? 'http_request';
+    return function acrRequestTracing(req, res, next) {
+        if (isIgnored(req.path, ignored)) {
+            next();
+            return;
+        }
+        const ctx = contextFromRequest(req);
+        req.acr = ctx;
+        res.locals.acr = ctx;
+        res.setHeader('X-Request-Id', ctx.requestId);
+        const started = process.hrtime.bigint();
+        let recorded = false;
+        const record = (aborted) => {
+            if (recorded)
+                return;
+            recorded = true;
+            const durationMs = Number(process.hrtime.bigint() - started) / 1e6;
+            const status = aborted ? 499 : res.statusCode;
+            const requestBytes = Number(req.get('content-length') ?? 0) || 0;
+            const responseBytes = Number(res.getHeader('content-length') ?? 0) || 0;
+            client.trackEvent(eventName, {
+                method: req.method,
+                route: routeOf(req),
+                status,
+                statusClass: `${Math.floor(status / 100)}xx`,
+                durationMs: Math.round(durationMs * 100) / 100,
+                requestBytes,
+                responseBytes,
+                aborted,
+                parentSpanId: ctx.parentSpanId ?? undefined,
+            }, {
+                traceId: ctx.traceId,
+                spanId: ctx.spanId,
+                requestId: ctx.requestId,
+                userId: options.getUserId?.(req),
+            });
+        };
+        res.once('finish', () => record(false));
+        res.once('close', () => record(!res.writableEnded));
+        next();
+    };
+}
+/**
+ * Error handler to register after your routes. It reports server-side failures (5xx or an error without a status)
+ * and always passes the error on, so the normal Express error response is unchanged. Client errors such as 400 or 404
+ * are not reported.
+ */
+function ACRErrorHandler(options) {
+    const client = resolveClient(options);
+    return function acrErrorReporter(err, req, _res, next) {
+        const status = statusOf(err);
+        if (status === null || status >= 500) {
+            client.captureError(err, {
+                handled: false,
+                source: 'backend',
+                route: routeOf(req),
+                traceId: req.acr?.traceId,
+                spanId: req.acr?.spanId,
+                requestId: req.acr?.requestId,
+                userId: options.getUserId?.(req),
+                attributes: { method: req.method, status: status ?? 500, framework: 'express' },
+            });
+        }
+        next(err);
+    };
+}
+function statusOf(err) {
+    const candidate = err;
+    const value = candidate?.status ?? candidate?.statusCode;
+    return typeof value === 'number' ? value : null;
+}
+/** Headers to add to outgoing calls so downstream services join the same trace. */
+function acrTraceHeaders(req) {
+    const ctx = req.acr;
+    if (!ctx)
+        return {};
+    return {
+        traceparent: (0, core_1.formatTraceparent)({ traceId: ctx.traceId, spanId: ctx.spanId }),
+        'x-request-id': ctx.requestId,
+    };
+}
+/**
+ * Opt-in maintenance mode for APIs. While the control snapshot has maintenance enabled, requests get `503` with
+ * `{ error: 'MAINTENANCE', message, endsAt }` and `Retry-After` (seconds until `endsAt`, else 300). Health and
+ * readiness probes (/health, /healthz, /ready, /readyz) always pass, as do users in `allowUserIds` (via `getUserId`)
+ * and requests for which `exempt` returns true. Register it before your routes.
+ */
+function maintenanceMiddleware(options) {
+    const client = resolveClient(options);
+    return function acrMaintenance(req, res, next) {
+        if ((0, core_1.isMaintenanceExemptPath)(req.path)) {
+            next();
+            return;
+        }
+        let blocked = null;
+        try {
+            blocked = (0, core_1.maintenanceResponse)(client.getControlState(), { userId: options.getUserId?.(req) });
+            if (blocked && options.exempt?.(req))
+                blocked = null;
+        }
+        catch {
+            blocked = null; // a failing exempt/getUserId callback must not take the API down
+        }
+        if (!blocked) {
+            next();
+            return;
+        }
+        res.setHeader('Retry-After', String(blocked.retryAfterSeconds));
+        res.setHeader('Cache-Control', 'no-store');
+        res.status(blocked.status).json(blocked.body);
+    };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/cjs/middleware.js.map

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

package/dist/cjs/sdk-info.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_INFO = void 0;
+// Generated by scripts/sync-sdk-info.mjs from package.json. Do not edit by hand.
+exports.SDK_INFO = { name: '@lib-acr/express', version: '0.0.1' };
+//# sourceMappingURL=sdk-info.js.map

package/dist/cjs/sdk-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-info.js","sourceRoot":"","sources":["../../src/sdk-info.ts"],"names":[],"mappings":";;;AAAA,iFAAiF;AACpE,QAAA,QAAQ,GAAG,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,OAAO,EAAW,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+export { ACRMiddleware, ACRErrorHandler, acrTraceHeaders, contextFromRequest, maintenanceMiddleware, resolveClient } from './middleware.js';
+export * from '@lib-acr/node';
+export { SDK_INFO } from './sdk-info.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,eAAe,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE5I,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/esm/middleware.js

@@ -0,0 +1,166 @@
+import { formatTraceparent, generateId, generateSpanId, generateTraceId, isMaintenanceExemptPath, maintenanceResponse, parseTraceparent, } from '@lib-acr/core';
+import { ACR } from '@lib-acr/node';
+import { SDK_INFO } from './sdk-info.js';
+const DEFAULT_IGNORED = ['/health', '/healthz', '/ready', '/readyz', '/favicon.ico'];
+const REQUEST_ID_RE = /^[\w.-]{1,64}$/;
+/** Clients created from `options`, keyed by the options object, so the middleware and the error handler share one. */
+const clientsByOptions = new WeakMap();
+/**
+ * Returns `options.client`, or the client created for `options.options`. The same options object always yields the
+ * same client, so ACRMiddleware and ACRErrorHandler configured with it share one buffer and one flush timer.
+ */
+export function resolveClient(options) {
+    if (options.client)
+        return options.client;
+    if (!options.options)
+        throw new Error('[acr] ExpressAcrOptions needs either client or options');
+    const existing = clientsByOptions.get(options.options);
+    if (existing)
+        return existing;
+    const created = new ACR(options.options, SDK_INFO);
+    clientsByOptions.set(options.options, created);
+    return created;
+}
+function isIgnored(path, ignored) {
+    return ignored.some((p) => (typeof p === 'string' ? p === path : p.test(path)));
+}
+/** Reads trace headers. The rest of the request headers are never kept. */
+export function contextFromRequest(req) {
+    const parsed = parseTraceparent(req.get('traceparent'));
+    const incomingRequestId = req.get('x-request-id');
+    const requestId = incomingRequestId && REQUEST_ID_RE.test(incomingRequestId) ? incomingRequestId : generateId();
+    return {
+        traceId: parsed?.traceId ?? generateTraceId(),
+        spanId: generateSpanId(),
+        parentSpanId: parsed?.spanId ?? null,
+        requestId,
+    };
+}
+/** Route template only (for example /orders/:id), never the concrete URL, so cardinality stays bounded. */
+function routeOf(req) {
+    if (!req.route)
+        return '(unmatched)';
+    const path = typeof req.route.path === 'string' ? req.route.path : '';
+    return `${req.baseUrl ?? ''}${path}` || '/';
+}
+/**
+ * Records one `http_request` event per request: method, route template, status, duration and body sizes. It sets
+ * X-Request-Id on the response and exposes req.acr for logs and errors. Headers, query strings and bodies are not
+ * recorded.
+ */
+export function ACRMiddleware(options) {
+    const client = resolveClient(options);
+    const ignored = [...DEFAULT_IGNORED, ...(options.ignorePaths ?? [])];
+    const eventName = options.eventName ?? 'http_request';
+    return function acrRequestTracing(req, res, next) {
+        if (isIgnored(req.path, ignored)) {
+            next();
+            return;
+        }
+        const ctx = contextFromRequest(req);
+        req.acr = ctx;
+        res.locals.acr = ctx;
+        res.setHeader('X-Request-Id', ctx.requestId);
+        const started = process.hrtime.bigint();
+        let recorded = false;
+        const record = (aborted) => {
+            if (recorded)
+                return;
+            recorded = true;
+            const durationMs = Number(process.hrtime.bigint() - started) / 1e6;
+            const status = aborted ? 499 : res.statusCode;
+            const requestBytes = Number(req.get('content-length') ?? 0) || 0;
+            const responseBytes = Number(res.getHeader('content-length') ?? 0) || 0;
+            client.trackEvent(eventName, {
+                method: req.method,
+                route: routeOf(req),
+                status,
+                statusClass: `${Math.floor(status / 100)}xx`,
+                durationMs: Math.round(durationMs * 100) / 100,
+                requestBytes,
+                responseBytes,
+                aborted,
+                parentSpanId: ctx.parentSpanId ?? undefined,
+            }, {
+                traceId: ctx.traceId,
+                spanId: ctx.spanId,
+                requestId: ctx.requestId,
+                userId: options.getUserId?.(req),
+            });
+        };
+        res.once('finish', () => record(false));
+        res.once('close', () => record(!res.writableEnded));
+        next();
+    };
+}
+/**
+ * Error handler to register after your routes. It reports server-side failures (5xx or an error without a status)
+ * and always passes the error on, so the normal Express error response is unchanged. Client errors such as 400 or 404
+ * are not reported.
+ */
+export function ACRErrorHandler(options) {
+    const client = resolveClient(options);
+    return function acrErrorReporter(err, req, _res, next) {
+        const status = statusOf(err);
+        if (status === null || status >= 500) {
+            client.captureError(err, {
+                handled: false,
+                source: 'backend',
+                route: routeOf(req),
+                traceId: req.acr?.traceId,
+                spanId: req.acr?.spanId,
+                requestId: req.acr?.requestId,
+                userId: options.getUserId?.(req),
+                attributes: { method: req.method, status: status ?? 500, framework: 'express' },
+            });
+        }
+        next(err);
+    };
+}
+function statusOf(err) {
+    const candidate = err;
+    const value = candidate?.status ?? candidate?.statusCode;
+    return typeof value === 'number' ? value : null;
+}
+/** Headers to add to outgoing calls so downstream services join the same trace. */
+export function acrTraceHeaders(req) {
+    const ctx = req.acr;
+    if (!ctx)
+        return {};
+    return {
+        traceparent: formatTraceparent({ traceId: ctx.traceId, spanId: ctx.spanId }),
+        'x-request-id': ctx.requestId,
+    };
+}
+/**
+ * Opt-in maintenance mode for APIs. While the control snapshot has maintenance enabled, requests get `503` with
+ * `{ error: 'MAINTENANCE', message, endsAt }` and `Retry-After` (seconds until `endsAt`, else 300). Health and
+ * readiness probes (/health, /healthz, /ready, /readyz) always pass, as do users in `allowUserIds` (via `getUserId`)
+ * and requests for which `exempt` returns true. Register it before your routes.
+ */
+export function maintenanceMiddleware(options) {
+    const client = resolveClient(options);
+    return function acrMaintenance(req, res, next) {
+        if (isMaintenanceExemptPath(req.path)) {
+            next();
+            return;
+        }
+        let blocked = null;
+        try {
+            blocked = maintenanceResponse(client.getControlState(), { userId: options.getUserId?.(req) });
+            if (blocked && options.exempt?.(req))
+                blocked = null;
+        }
+        catch {
+            blocked = null; // a failing exempt/getUserId callback must not take the API down
+        }
+        if (!blocked) {
+            next();
+            return;
+        }
+        res.setHeader('Retry-After', String(blocked.retryAfterSeconds));
+        res.setHeader('Cache-Control', 'no-store');
+        res.status(blocked.status).json(blocked.body);
+    };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/esm/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAEpC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAwCzC,MAAM,eAAe,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;AACrF,MAAM,aAAa,GAAG,gBAAgB,CAAC;AAEvC,sHAAsH;AACtH,MAAM,gBAAgB,GAAG,IAAI,OAAO,EAAyB,CAAC;AAE9D;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAA0B;IACtD,IAAI,OAAO,CAAC,MAAM;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC;IAC1C,IAAI,CAAC,OAAO,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAChG,MAAM,QAAQ,GAAG,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAgB,EAAE,QAAQ,CAAC,CAAC;IAC5D,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC/C,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,SAAS,CAAC,IAAY,EAAE,OAA+B;IAC9D,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClF,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;IACxD,MAAM,iBAAiB,GAAG,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,iBAAiB,IAAI,aAAa,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;IAChH,OAAO;QACL,OAAO,EAAE,MAAM,EAAE,OAAO,IAAI,eAAe,EAAE;QAC7C,MAAM,EAAE,cAAc,EAAE;QACxB,YAAY,EAAE,MAAM,EAAE,MAAM,IAAI,IAAI;QACpC,SAAS;KACV,CAAC;AACJ,CAAC;AAED,2GAA2G;AAC3G,SAAS,OAAO,CAAC,GAAY;IAC3B,IAAI,CAAC,GAAG,CAAC,KAAK;QAAE,OAAO,aAAa,CAAC;IACrC,MAAM,IAAI,GAAG,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IACtE,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,GAAG,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,OAA0B;IACtD,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,CAAC,GAAG,eAAe,EAAE,GAAG,CAAC,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,CAAC;IACrE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,cAAc,CAAC;IAEtD,OAAO,SAAS,iBAAiB,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB;QAC/E,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;YACjC,IAAI,EAAE,CAAC;YACP,OAAO;QACT,CAAC;QACD,MAAM,GAAG,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;QACpC,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC;QACd,GAAG,CAAC,MAAM,CAAC,GAAG,GAAG,GAAG,CAAC;QACrB,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;QAE7C,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACxC,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,MAAM,MAAM,GAAG,CAAC,OAAgB,EAAE,EAAE;YAClC,IAAI,QAAQ;gBAAE,OAAO;YACrB,QAAQ,GAAG,IAAI,CAAC;YAChB,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,GAAG,CAAC;YACnE,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC;YAC9C,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;YACjE,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;YACxE,MAAM,CAAC,UAAU,CACf,SAAS,EACT;gBACE,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC;gBACnB,MAAM;gBACN,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,IAAI;gBAC5C,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,GAAG,CAAC,GAAG,GAAG;gBAC9C,YAAY;gBACZ,aAAa;gBACb,OAAO;gBACP,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,SAAS;aAC5C,EACD;gBACE,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,MAAM,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,GAAG,CAAC;aACjC,CACF,CAAC;QACJ,CAAC,CAAC;QACF,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACxC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;QACpD,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAA0B;IACxD,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACtC,OAAO,SAAS,gBAAgB,CAAC,GAAY,EAAE,GAAY,EAAE,IAAc,EAAE,IAAkB;QAC7F,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;YACrC,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE;gBACvB,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,SAAS;gBACjB,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC;gBACnB,OAAO,EAAE,GAAG,CAAC,GAAG,EAAE,OAAO;gBACzB,MAAM,EAAE,GAAG,CAAC,GAAG,EAAE,MAAM;gBACvB,SAAS,EAAE,GAAG,CAAC,GAAG,EAAE,SAAS;gBAC7B,MAAM,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,GAAG,CAAC;gBAChC,UAAU,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE;aAChF,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,CAAC;IACZ,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,GAAY;IAC5B,MAAM,SAAS,GAAG,GAAwD,CAAC;IAC3E,MAAM,KAAK,GAAG,SAAS,EAAE,MAAM,IAAI,SAAS,EAAE,UAAU,CAAC;IACzD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;IACpB,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IACpB,OAAO;QACL,WAAW,EAAE,iBAAiB,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;QAC5E,cAAc,EAAE,GAAG,CAAC,SAAS;KAC9B,CAAC;AACJ,CAAC;AAOD;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAqC;IACzE,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACtC,OAAO,SAAS,cAAc,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB;QAC5E,IAAI,uBAAuB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACtC,IAAI,EAAE,CAAC;YACP,OAAO;QACT,CAAC;QACD,IAAI,OAAO,GAA2C,IAAI,CAAC;QAC3D,IAAI,CAAC;YACH,OAAO,GAAG,mBAAmB,CAAC,MAAM,CAAC,eAAe,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC9F,IAAI,OAAO,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC;gBAAE,OAAO,GAAG,IAAI,CAAC;QACvD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,GAAG,IAAI,CAAC,CAAC,iEAAiE;QACnF,CAAC;QACD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,IAAI,EAAE,CAAC;YACP,OAAO;QACT,CAAC;QACD,GAAG,CAAC,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC;QAChE,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;QAC3C,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,CAAC,CAAC;AACJ,CAAC"}

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/sdk-info.js

@@ -0,0 +1,3 @@
+// Generated by scripts/sync-sdk-info.mjs from package.json. Do not edit by hand.
+export const SDK_INFO = { name: '@lib-acr/express', version: '0.0.1' };
+//# sourceMappingURL=sdk-info.js.map

package/dist/esm/sdk-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-info.js","sourceRoot":"","sources":["../../src/sdk-info.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,CAAC,MAAM,QAAQ,GAAG,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,OAAO,EAAW,CAAC"}

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export { ACRMiddleware, ACRErrorHandler, acrTraceHeaders, contextFromRequest, maintenanceMiddleware, resolveClient } from './middleware.js';
+export type { AcrRequestContext, ExpressAcrOptions, MaintenanceMiddlewareOptions } from './middleware.js';
+export * from '@lib-acr/node';
+export { SDK_INFO } from './sdk-info.js';

package/dist/types/middleware.d.ts

@@ -0,0 +1,68 @@
+import { AcrClient, type AcrOptions } from '@lib-acr/core';
+import type { NextFunction, Request, Response } from 'express';
+/** Trace and request identifiers for one incoming request. Available as req.acr and res.locals.acr. */
+export interface AcrRequestContext {
+    traceId: string;
+    /** Span id of this server operation. */
+    spanId: string;
+    /** Span id of the caller, when a traceparent header arrived. */
+    parentSpanId: string | null;
+    requestId: string;
+}
+declare global {
+    namespace Express {
+        interface Request {
+            acr?: AcrRequestContext;
+        }
+    }
+}
+export interface ExpressAcrOptions {
+    /**
+     * Use an existing client (for example one shared with a NestJS or background-job setup). Recommended: create one
+     * `ACR` and pass it to both ACRMiddleware and ACRErrorHandler.
+     */
+    client?: AcrClient;
+    /**
+     * Options used to create a client when `client` is not given. One client is created per options object, so pass
+     * the same object to ACRMiddleware and ACRErrorHandler to share it.
+     */
+    options?: AcrOptions;
+    /** Exact paths or patterns that are not recorded. Default: health and readiness probes. */
+    ignorePaths?: Array<string | RegExp>;
+    /** Event name for request telemetry. Default `http_request`. */
+    eventName?: string;
+    /** Returns the authenticated user id for a request, if any. Keep it an opaque id. */
+    getUserId?: (req: Request) => string | undefined;
+}
+/**
+ * Returns `options.client`, or the client created for `options.options`. The same options object always yields the
+ * same client, so ACRMiddleware and ACRErrorHandler configured with it share one buffer and one flush timer.
+ */
+export declare function resolveClient(options: ExpressAcrOptions): AcrClient;
+/** Reads trace headers. The rest of the request headers are never kept. */
+export declare function contextFromRequest(req: Request): AcrRequestContext;
+/**
+ * Records one `http_request` event per request: method, route template, status, duration and body sizes. It sets
+ * X-Request-Id on the response and exposes req.acr for logs and errors. Headers, query strings and bodies are not
+ * recorded.
+ */
+export declare function ACRMiddleware(options: ExpressAcrOptions): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Error handler to register after your routes. It reports server-side failures (5xx or an error without a status)
+ * and always passes the error on, so the normal Express error response is unchanged. Client errors such as 400 or 404
+ * are not reported.
+ */
+export declare function ACRErrorHandler(options: ExpressAcrOptions): (err: unknown, req: Request, _res: Response, next: NextFunction) => void;
+/** Headers to add to outgoing calls so downstream services join the same trace. */
+export declare function acrTraceHeaders(req: Request): Record<string, string>;
+export interface MaintenanceMiddlewareOptions extends Pick<ExpressAcrOptions, 'client' | 'options' | 'getUserId'> {
+    /** Return true to let a request through during maintenance (for example admin or webhook routes). */
+    exempt?: (req: Request) => boolean;
+}
+/**
+ * Opt-in maintenance mode for APIs. While the control snapshot has maintenance enabled, requests get `503` with
+ * `{ error: 'MAINTENANCE', message, endsAt }` and `Retry-After` (seconds until `endsAt`, else 300). Health and
+ * readiness probes (/health, /healthz, /ready, /readyz) always pass, as do users in `allowUserIds` (via `getUserId`)
+ * and requests for which `exempt` returns true. Register it before your routes.
+ */
+export declare function maintenanceMiddleware(options: MaintenanceMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => void;

package/dist/types/sdk-info.d.ts

@@ -0,0 +1,4 @@
+export declare const SDK_INFO: {
+    readonly name: "@lib-acr/express";
+    readonly version: "0.0.1";
+};

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@lib-acr/express",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "ACR middleware for Express: request events with trace correlation, error capture and W3C trace context.",
+  "license": "MIT",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "@lib-acr/core": "0.0.1",
+    "@lib-acr/node": "0.0.1"
+  },
+  "peerDependencies": {
+    "express": ">=4.18.0 <6"
+  },
+  "devDependencies": {
+    "express": "^5.1.0",
+    "@types/express": "^5.0.6"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/application-control-room/application.git",
+    "directory": "packages/express"
+  },
+  "homepage": "https://github.com/application-control-room/application/tree/main/packages/express#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}