@beignet/core 0.0.3 → 0.0.4

package/dist/server/hooks/rate-limit.js

@@ -1,10 +1,26 @@
 /**
  * Rate limit hooks for @beignet/core/server
  */
-import { AppError, httpErrors } from "../../errors";
-function defaultGetClientIp(req) {
-    const xfwd = req.headers.get("x-forwarded-for") ?? "";
-    return xfwd.split(",")[0].trim() || undefined;
+import { AppError, httpErrors } from "../../errors/index.js";
+import { createProviderInstrumentation, } from "../../providers/index.js";
+function parseForwardedFor(req) {
+    const header = req.headers.get("x-forwarded-for") ?? "";
+    return header
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
+function resolveClientIp(req, ipSource) {
+    if (typeof ipSource === "function") {
+        return ipSource(req) || undefined;
+    }
+    const entries = parseForwardedFor(req);
+    if (entries.length === 0) {
+        return undefined;
+    }
+    return ipSource === "x-forwarded-for-first"
+        ? entries[0]
+        : entries[entries.length - 1];
 }
 function emitUserKey(userId) {
     return `user:${userId}`;
@@ -30,8 +46,8 @@ function defaultEarlyRateLimitKey(args, getClientIp) {
     }
     return "global";
 }
-async function enforceRateLimit(rateLimit, args) {
-    const result = await rateLimit.hit({
+async function enforceRateLimit(ports, args) {
+    const result = await ports.rateLimit.hit({
         key: args.key,
         limit: args.limit,
         windowSec: args.windowSec,
@@ -39,8 +55,24 @@ async function enforceRateLimit(rateLimit, args) {
     if (result.allowed) {
         return;
     }
+    // App ports may carry an `instrumentation` or `devtools` sink alongside the
+    // typed rate-limit port; the helper resolves them at runtime.
+    const instrumentation = createProviderInstrumentation(ports, {
+        providerName: "rate-limit",
+        watcher: "rateLimit",
+    });
+    instrumentation.custom({
+        name: "rateLimit.denied",
+        label: "Rate limit denied",
+        summary: `Rate limit denied for ${args.key}`,
+        details: {
+            key: args.key,
+            scope: args.scope,
+            limit: args.limit,
+            windowSec: args.windowSec,
+        },
+    });
     throw new AppError(httpErrors.TooManyRequests, {
-        key: args.key,
         scope: args.scope,
         retryAfterSeconds: result.retryAfterSeconds,
         resetAt: result.resetAt?.toISOString() ?? null,
@@ -52,13 +84,16 @@ async function enforceRateLimit(rateLimit, args) {
  * The hook reads `contract.metadata.rateLimit`. Global and IP-scoped limits run
  * in `onRequest` before context creation; user-scoped limits run in
  * `beforeHandle` after `ctx.actor` is available. Exceeded limits throw the
- * framework `TooManyRequests` app error.
+ * framework `TooManyRequests` app error with `scope`, `retryAfterSeconds`, and
+ * `resetAt` details. The bucket key is never sent to clients; denials emit a
+ * `rateLimit.denied` instrumentation event that carries the key for operators.
  *
- * @param options - Optional key builders and client-IP resolver.
+ * @param options - Optional key builders and client-IP source.
  * @returns A server hook backed by `ctx.ports.rateLimit`.
  */
 export function createRateLimitHooks(options = {}) {
-    const getClientIp = options.getClientIp ?? defaultGetClientIp;
+    const ipSource = options.ipSource ?? "x-forwarded-for-last";
+    const getClientIp = (req) => resolveClientIp(req, ipSource);
     return {
         name: "rate-limit",
         onRequest: async ({ contract, ports, req }) => {
@@ -72,7 +107,7 @@ export function createRateLimitHooks(options = {}) {
             }
             const key = options.earlyKey?.({ req, scope }) ??
                 defaultEarlyRateLimitKey({ req, scope }, getClientIp);
-            await enforceRateLimit(ports.rateLimit, {
+            await enforceRateLimit(ports, {
                 key,
                 limit: rlMeta.max,
                 windowSec: rlMeta.windowSec,
@@ -91,7 +126,7 @@ export function createRateLimitHooks(options = {}) {
             }
             const key = options.key?.({ ctx, req, scope }) ??
                 defaultRateLimitKey({ ctx, req, scope }, getClientIp);
-            await enforceRateLimit(ctx.ports.rateLimit, {
+            await enforceRateLimit(ctx.ports, {
                 key,
                 limit: rlMeta.max,
                 windowSec: rlMeta.windowSec,

package/dist/server/hooks/rate-limit.js.map

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

package/dist/server/hooks.d.ts

@@ -1,2 +1,2 @@
-export * from "./hooks/index";
+export * from "./hooks/index.js";
 //# sourceMappingURL=hooks.d.ts.map

package/dist/server/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/server/hooks.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/server/hooks.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/server/hooks.js

@@ -1,2 +1,2 @@
-export * from "./hooks/index";
+export * from "./hooks/index.js";
 //# sourceMappingURL=hooks.js.map

package/dist/server/hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/server/hooks.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC"}
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/server/hooks.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/server/http.d.ts

@@ -1,5 +1,5 @@
-import type { HttpContractConfig, InferHeaderSchemaOutput, InferOutput, StandardSchema } from "../contracts";
-import type { AnyPorts } from "../ports";
+import type { HttpContractConfig, InferHeaderSchemaOutput, InferOutput, StandardSchema } from "../contracts/index.js";
+import type { AnyPorts } from "../ports/index.js";
 /**
  * Framework-neutral request shape consumed by Beignet server adapters.
  *
@@ -75,6 +75,41 @@ export interface HttpResponseLike {
  * `Response` only when the current adapter can pass it through unchanged.
  */
 export type HttpResponse = HttpResponseLike | Response;
+/**
+ * Framework-neutral Beignet API handler consumed by HTTP adapters.
+ */
+export type HttpAdapterApiHandler = (req: HttpRequestLike) => Promise<HttpResponse>;
+/**
+ * Native handler shape produced by an HTTP adapter.
+ */
+export type HttpAdapterHandler<NativeRequest, NativeResponse> = (req: NativeRequest) => Promise<NativeResponse>;
+/**
+ * Contract implemented by packages that adapt Beignet's framework-neutral
+ * server runtime to a platform HTTP API.
+ *
+ * Core owns request parsing, hooks, route matching, validation, error mapping,
+ * response ownership, and provider lifecycle. Adapters own only the conversion
+ * between the platform request/response types and Beignet's `HttpRequestLike`
+ * / `HttpResponse` boundary.
+ */
+export interface HttpAdapter<NativeRequest, NativeResponse> {
+    /**
+     * Human-readable adapter name for diagnostics and documentation.
+     */
+    name: string;
+    /**
+     * Convert a platform request into Beignet's framework-neutral request shape.
+     */
+    toRequestLike(req: NativeRequest): HttpRequestLike;
+    /**
+     * Convert a Beignet response into the platform response type.
+     */
+    toNativeResponse(res: HttpResponse): NativeResponse | Promise<NativeResponse>;
+    /**
+     * Wrap a Beignet API handler in the platform's native handler shape.
+     */
+    createHandler(handler: HttpAdapterApiHandler): HttpAdapterHandler<NativeRequest, NativeResponse>;
+}
 type InferSchemaOrFallback<T extends StandardSchema | null, Fallback> = T extends StandardSchema ? InferOutput<T> : Fallback;
 /**
  * Infer the handler path parameter type for a contract.
@@ -101,7 +136,7 @@ export interface HandlerArgs<Ctx, C extends HttpContractConfig> {
      */
     req: HttpRequestLike;
     /**
-     * Application context returned by `createContext`.
+     * Application context assembled by the server context blueprint.
      */
     ctx: Ctx;
     /**
@@ -144,8 +179,14 @@ export type RouteHookArgs<Ctx, C extends HttpContractConfig = HttpContractConfig
  * Route hooks are for scoped policy and context enrichment such as
  * authentication, tenant resolution, feature gates, and idempotency. They add
  * fields to the handler context instead of replacing the app context.
+ *
+ * Hook additions must not include `gate`: the server re-attaches the gate
+ * declared by the context blueprint after every hook, so identity changes are
+ * picked up automatically.
  */
-export interface RouteHook<Ctx, AddedCtx extends object = Record<string, never>> {
+export interface RouteHook<Ctx, AddedCtx extends object & {
+    gate?: never;
+} = Record<string, never>> {
     /**
      * Optional name used in diagnostics and devtools.
      */
@@ -155,36 +196,12 @@ export interface RouteHook<Ctx, AddedCtx extends object = Record<string, never>>
      */
     resolve: (args: RouteHookArgs<Ctx>) => MaybePromise<AddedCtx | undefined>;
 }
+type AddedCtxFromHook<Hook> = Hook extends RouteHook<infer _Ctx, infer AddedCtx> ? AddedCtx : unknown;
+type UnionToIntersection<Union> = (Union extends unknown ? (value: Union) => void : never) extends (value: infer Intersection) => void ? Intersection : never;
 /**
- * Builder for route-scoped hooks.
- */
-export type RouteHookBuilder<Ctx> = {
-    /**
-     * Assign a diagnostic name to the hook.
-     */
-    name: (name: string) => RouteHookNamedBuilder<Ctx>;
-    /**
-     * Define the hook resolver.
-     */
-    resolve: <AddedCtx extends object>(resolve: RouteHook<Ctx, AddedCtx>["resolve"]) => RouteHook<Ctx, AddedCtx>;
-};
-/**
- * Named builder for route-scoped hooks.
+ * Intersection of the context fields added by a route hook list.
  */
-export type RouteHookNamedBuilder<Ctx> = {
-    /**
-     * Define the hook resolver.
-     */
-    resolve: <AddedCtx extends object>(resolve: RouteHook<Ctx, AddedCtx>["resolve"]) => RouteHook<Ctx, AddedCtx>;
-};
-/**
- * Define a route-scoped hook.
- *
- * Route hooks enrich handler context for one route or route group. They should
- * throw application/framework errors for denials instead of returning HTTP
- * responses directly.
- */
-export declare function defineRouteHook<Ctx>(): RouteHookBuilder<Ctx>;
+export type AddedCtxFromHooks<Hooks extends readonly unknown[]> = Hooks extends readonly [] ? unknown : UnionToIntersection<AddedCtxFromHook<Hooks[number]>>;
 /**
  * Hook that runs after a route is matched but before request parsing and
  * context creation.
@@ -220,10 +237,11 @@ export type BeforeHandleHook<Ctx, C extends HttpContractConfig = HttpContractCon
     body: InferBody<C>;
 }) => MaybePromise<BeforeHandleResult<Ctx>>;
 /**
- * Hook that runs before a framework-neutral response is returned.
+ * Hook that runs before the response is returned.
  *
  * Return a response to replace or decorate the outgoing response. Hooks run in
- * declaration order.
+ * declaration order. For native web `Response` results the hook receives a
+ * headers-only view and only header changes are applied.
  */
 export type BeforeSendHook<Ctx, C extends HttpContractConfig = HttpContractConfig> = (args: {
     req: HttpRequestLike;
@@ -235,6 +253,13 @@ export type BeforeSendHook<Ctx, C extends HttpContractConfig = HttpContractConfi
     body?: InferBody<C>;
     response: HttpResponseLike;
     error?: unknown;
+    /**
+     * True when the route returned a native web Response. The response argument
+     * is a headers-only view ({ status, headers }); the body is not readable and
+     * returned body/status changes are ignored. Header changes are merged onto
+     * the native Response.
+     */
+    native?: boolean;
 }) => MaybePromise<HttpResponseLike | undefined>;
 /**
  * Hook that runs after the response has been prepared.
@@ -305,7 +330,8 @@ export interface ServerHook<Ctx, Ports extends AnyPorts = AnyPorts> {
      */
     beforeHandle?: BeforeHandleHook<Ctx>;
     /**
-     * Runs before a framework-neutral response is returned.
+     * Runs before the response is returned. Native web `Response` results get a
+     * headers-only view with `native: true`.
      */
     beforeSend?: BeforeSendHook<Ctx>;
     /**

package/dist/server/http.d.ts.map

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

package/dist/server/http.js

@@ -1,21 +1,2 @@
-/**
- * Define a route-scoped hook.
- *
- * Route hooks enrich handler context for one route or route group. They should
- * throw application/framework errors for denials instead of returning HTTP
- * responses directly.
- */
-export function defineRouteHook() {
-    return {
-        name: (name) => ({
-            resolve: (resolve) => ({
-                name,
-                resolve,
-            }),
-        }),
-        resolve: (resolve) => ({
-            resolve,
-        }),
-    };
-}
+export {};
 //# sourceMappingURL=http.js.map

package/dist/server/http.js.map

@@ -1 +1 @@
-{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/server/http.ts"],"names":[],"mappings":"AAoOA;;;;;;GAMG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO;QACL,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACf,OAAO,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;gBACrB,IAAI;gBACJ,OAAO;aACR,CAAC;SACH,CAAC;QACF,OAAO,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACrB,OAAO;SACR,CAAC;KACH,CAAC;AACJ,CAAC"}
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/server/http.ts"],"names":[],"mappings":""}

package/dist/server/index.d.ts

@@ -7,31 +7,55 @@
 /**
  * Contract and schema types re-exported for server users.
  */
-export type { HttpContractConfig, InferOutput, StandardSchema, StandardSchemaV1, } from "../contracts";
+export type { HttpContractConfig, InferOutput, StandardSchema, StandardSchemaV1, } from "../contracts/index.js";
 /**
  * Application error base class re-exported for server users.
  */
-export { AppError } from "../errors";
+export { AppError } from "../errors/index.js";
 /**
  * Any-ports helper type re-exported for server users.
  */
-export type { AnyPorts } from "../ports";
+export type { AnyPorts } from "../ports/index.js";
 /**
  * Provider type re-exported for server users.
  */
-export type { ServiceProvider } from "../providers";
-export * from "./health";
-export * from "./hooks";
-export * from "./http";
-export * from "./openapi";
-export * from "./providers";
+export type { ServiceProvider } from "../providers/index.js";
+/**
+ * Ambient audit enrichment for app audit ports.
+ */
+export { createAmbientAuditLog } from "./audit-context.js";
+/**
+ * Server context blueprint types.
+ */
+export type { ContextSeed, RequestContextArgs, ServerContextConfig, ServerContextOptions, ServiceContextArgs, ServiceContextInputArgs, } from "./context.js";
+export * from "./health.js";
+export * from "./hooks.js";
+export * from "./http.js";
+/**
+ * Server-owned request instrumentation types.
+ */
+export type { RequestCorrelation, ServerInstrumentationOptions, } from "./instrumentation.js";
+export * from "./openapi.js";
+export * from "./providers/index.js";
+/**
+ * Ambient request correlation context shared with instrumentation sinks.
+ */
+export { type ActiveRequestContext, clearActiveRequestContext, enterActiveRequestContext, getActiveRequestContext, inheritActiveRequestContext, } from "./request-context.js";
 /**
  * Server configuration and route types.
  */
-export type { CreateServerOptions, RouteDef, RouteGroup, ServerInstance, } from "./server";
+export type { CreateServerOptions, HandlerRouteDef, RouteDef, RouteGroup, ServerInstance, } from "./server.js";
 /**
  * Server runtime helpers.
  */
-export { contractsFromRoutes, createServer, defineRoute, defineRouteGroup, defineRoutes, } from "./server";
-export * from "./types";
+export { contractsFromRoutes, createServer, defineRoute, defineRouteGroup, defineRoutes, } from "./server.js";
+/**
+ * Server context blueprint declaration helper.
+ */
+export { defineServerContext } from "./server-context.js";
+export * from "./types.js";
+/**
+ * Contract-aware route binder types and helpers.
+ */
+export { type AnyUseCaseLike, type AnyUseCaseRouteDef, type BinderStatusOption, defaultBinderInput, type UseCaseFitsRoute, type UseCaseRouteDef, type UseCaseRouteInput, type UseCaseRouteInputParts, } from "./use-case-route.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,YAAY,EACV,kBAAkB,EAClB,WAAW,EACX,cAAc,EACd,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB;;GAEG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC;;GAEG;AACH,YAAY,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC;;GAEG;AACH,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B;;GAEG;AACH,YAAY,EACV,mBAAmB,EACnB,QAAQ,EACR,UAAU,EACV,cAAc,GACf,MAAM,UAAU,CAAC;AAClB;;GAEG;AACH,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,YAAY,EACV,kBAAkB,EAClB,WAAW,EACX,cAAc,EACd,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B;;GAEG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C;;GAEG;AACH,YAAY,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD;;GAEG;AACH,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D;;GAEG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D;;GAEG;AACH,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,cAAc,CAAC;AACtB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B;;GAEG;AACH,YAAY,EACV,kBAAkB,EAClB,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC;;GAEG;AACH,OAAO,EACL,KAAK,oBAAoB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,sBAAsB,CAAC;AAC9B;;GAEG;AACH,YAAY,EACV,mBAAmB,EACnB,eAAe,EACf,QAAQ,EACR,UAAU,EACV,cAAc,GACf,MAAM,aAAa,CAAC;AACrB;;GAEG;AACH,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,YAAY,GACb,MAAM,aAAa,CAAC;AACrB;;GAEG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,cAAc,YAAY,CAAC;AAC3B;;GAEG;AACH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,qBAAqB,CAAC"}

package/dist/server/index.js

@@ -7,15 +7,31 @@
 /**
  * Application error base class re-exported for server users.
  */
-export { AppError } from "../errors";
-export * from "./health";
-export * from "./hooks";
-export * from "./http";
-export * from "./openapi";
-export * from "./providers";
+export { AppError } from "../errors/index.js";
+/**
+ * Ambient audit enrichment for app audit ports.
+ */
+export { createAmbientAuditLog } from "./audit-context.js";
+export * from "./health.js";
+export * from "./hooks.js";
+export * from "./http.js";
+export * from "./openapi.js";
+export * from "./providers/index.js";
+/**
+ * Ambient request correlation context shared with instrumentation sinks.
+ */
+export { clearActiveRequestContext, enterActiveRequestContext, getActiveRequestContext, inheritActiveRequestContext, } from "./request-context.js";
 /**
  * Server runtime helpers.
  */
-export { contractsFromRoutes, createServer, defineRoute, defineRouteGroup, defineRoutes, } from "./server";
-export * from "./types";
+export { contractsFromRoutes, createServer, defineRoute, defineRouteGroup, defineRoutes, } from "./server.js";
+/**
+ * Server context blueprint declaration helper.
+ */
+export { defineServerContext } from "./server-context.js";
+export * from "./types.js";
+/**
+ * Contract-aware route binder types and helpers.
+ */
+export { defaultBinderInput, } from "./use-case-route.js";
 //# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH;;GAEG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AASrC,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAU5B;;GAEG;AACH,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH;;GAEG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAS9C;;GAEG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAY3D,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAQ1B,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC;;GAEG;AACH,OAAO,EAEL,yBAAyB,EACzB,yBAAyB,EACzB,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,sBAAsB,CAAC;AAW9B;;GAEG;AACH,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,YAAY,GACb,MAAM,aAAa,CAAC;AACrB;;GAEG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,cAAc,YAAY,CAAC;AAC3B;;GAEG;AACH,OAAO,EAIL,kBAAkB,GAKnB,MAAM,qBAAqB,CAAC"}

package/dist/server/instrumentation.d.ts

@@ -0,0 +1,108 @@
+import { type HttpContractConfig } from "../contracts/index.js";
+import type { AnyPorts } from "../ports/index.js";
+import { type ProviderInstrumentationEventInput } from "../providers/instrumentation.js";
+import { type TraceContext } from "../tracing/index.js";
+import type { HttpRequestLike, HttpResponseLike, ServerHook } from "./http.js";
+/**
+ * Options for the server-owned request instrumentation pipeline.
+ *
+ * The server resolves request IDs and W3C trace context before user hooks and
+ * context creation run, writes them to response headers, and records request
+ * and error events into the resolved provider instrumentation port
+ * (`ports.instrumentation`, then `ports.devtools`) after responses are sent.
+ *
+ * Pass `instrumentation: false` to `createServer(...)` to disable headers and
+ * event recording entirely.
+ */
+export interface ServerInstrumentationOptions<Ctx = unknown> {
+    /**
+     * Request/response header used for the request correlation ID.
+     *
+     * Pass `false` to avoid reading or writing a request ID header.
+     *
+     * @default "x-request-id"
+     */
+    requestIdHeader?: string | false;
+    /**
+     * W3C trace context header used to correlate events with distributed
+     * traces.
+     *
+     * Pass `false` to avoid reading or writing a trace context header.
+     *
+     * @default "traceparent"
+     */
+    traceContextHeader?: string | false;
+    /**
+     * Request path prefixes that should not enter ambient correlation or record
+     * events. Response headers are still written.
+     *
+     * Defaults to the devtools dashboard prefix so its polling traffic does not
+     * fill the event timeline.
+     *
+     * @default ["/api/devtools"]
+     */
+    ignorePaths?: readonly string[];
+    /**
+     * Apply a custom redactor to events produced by the server. Sink-level
+     * redaction (such as the devtools redactor) still runs when events are
+     * stored.
+     */
+    redact?: (event: ProviderInstrumentationEventInput) => ProviderInstrumentationEventInput;
+    /**
+     * Decide whether to capture a completed request event.
+     */
+    shouldCapture?: (args: {
+        req: HttpRequestLike;
+        ctx?: Ctx;
+        contract: HttpContractConfig;
+        response: HttpResponseLike;
+        error?: unknown;
+    }) => boolean;
+}
+/**
+ * Correlation values resolved by the server for one request or service
+ * context.
+ */
+export interface RequestCorrelation {
+    /**
+     * Request correlation ID.
+     */
+    requestId: string;
+    /**
+     * W3C trace context.
+     */
+    trace: TraceContext;
+}
+/**
+ * Internal runtime created by `createServer(...)` from its `instrumentation`
+ * option.
+ */
+export interface ServerInstrumentationRuntime<Ctx> {
+    /**
+     * Resolve the instrumentation sink once final ports are known.
+     */
+    attachPorts(ports: AnyPorts): void;
+    /**
+     * Resolve (and cache per request) the request ID and trace context.
+     */
+    prepareRequest(req: HttpRequestLike): RequestCorrelation;
+    /**
+     * Create fresh correlation values for a service context.
+     */
+    createServiceCorrelation(): RequestCorrelation;
+    /**
+     * Pipeline hook installed before user hooks, when instrumentation is
+     * enabled.
+     */
+    hook?: ServerHook<Ctx, AnyPorts>;
+}
+/**
+ * Create the server-owned instrumentation runtime for `createServer(...)`.
+ *
+ * Correlation values (request ID and trace context) are always resolved so
+ * context factories receive stable `requestId`/`trace` arguments, even when
+ * instrumentation is disabled. Headers and event recording only run when
+ * instrumentation is enabled.
+ */
+export declare function createServerInstrumentation<Ctx>(options: ServerInstrumentationOptions<Ctx> | false | undefined): ServerInstrumentationRuntime<Ctx>;
+//# sourceMappingURL=instrumentation.d.ts.map

package/dist/server/instrumentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../../src/server/instrumentation.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,EACL,KAAK,iCAAiC,EAGvC,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAQ/E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,4BAA4B,CAAC,GAAG,GAAG,OAAO;IACzD;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAEjC;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAEpC;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEhC;;;;OAIG;IACH,MAAM,CAAC,EAAE,CACP,KAAK,EAAE,iCAAiC,KACrC,iCAAiC,CAAC;IAEvC;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE;QACrB,GAAG,EAAE,eAAe,CAAC;QACrB,GAAG,CAAC,EAAE,GAAG,CAAC;QACV,QAAQ,EAAE,kBAAkB,CAAC;QAC7B,QAAQ,EAAE,gBAAgB,CAAC;QAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,KAAK,OAAO,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,4BAA4B,CAAC,GAAG;IAC/C;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IACnC;;OAEG;IACH,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,kBAAkB,CAAC;IACzD;;OAEG;IACH,wBAAwB,IAAI,kBAAkB,CAAC;IAC/C;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;CAClC;AA2GD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAC7C,OAAO,EAAE,4BAA4B,CAAC,GAAG,CAAC,GAAG,KAAK,GAAG,SAAS,GAC7D,4BAA4B,CAAC,GAAG,CAAC,CAoOnC"}