@glasstrace/sdk 1.7.0 → 1.9.0

package/dist/middleware/index.d.cts

@@ -0,0 +1,183 @@
+import { AttributeValue } from './common/Attributes';
+
+/**
+ * Request-middleware-ownership instrumentation for Glasstrace.
+ *
+ * Subpath: `@glasstrace/sdk/middleware`
+ *
+ * This module exposes {@link tracedRequestMiddleware}, a wrapper that
+ * turns a Next.js `middleware.ts` function (or any generic
+ * `Request → Response`-shaped handler) into a span-emitting middleware
+ * function. Each invocation opens a child span and tags it with the
+ * `glasstrace.causal.middleware_for_request` causal-evidence attribute
+ * carrying the originating request's normalized path so the
+ * product-side trace-summary transform can link the middleware span
+ * to the owning HTTP request trace (DISC-1537 / SDK-046).
+ *
+ * Edge-runtime safety
+ * -------------------
+ * The wrapper is included in the SDK's edge bundle
+ * (`packages/sdk/src/edge-entry.ts`). Its closure imports only the
+ * OTel API, the protocol constants, and the
+ * `./optional-lifecycle.js` bridge — none of which reach into
+ * `node:*` built-ins or the `process` global. The F003 closure scan
+ * (`packages/sdk/scripts/check-edge-bundle.mjs`) enforces this on
+ * every build.
+ *
+ * Causal-evidence form
+ * --------------------
+ * The wrapper attaches the originating request path as a span
+ * attribute (`glasstrace.causal.middleware_for_request`). It does NOT
+ * emit an OTel `Link`. Reasons:
+ *
+ *   1. The Next.js Edge runtime does not propagate AsyncLocalStorage
+ *      into `middleware.ts`, so there is no in-process
+ *      `SpanContext` to link to in that environment. Attribute-only
+ *      causality works in both Node and Edge runtimes; a Link would
+ *      degrade to a no-op (no parent context) on Edge.
+ *   2. The product-side trace-summary transform reconstructs
+ *      ownership from `glasstrace.causal.*` attributes per
+ *      DISC-1539 §51-58; it does not require a Link.
+ *
+ * Invariants
+ * ----------
+ *
+ *   - The wrapped function preserves the user's call-site type so
+ *     Next.js's `middleware` export contract (`(req: NextRequest) =>
+ *     NextResponse | Response`) flows through unchanged.
+ *   - The middleware span MUST NOT overwrite `glasstrace.route`,
+ *     `glasstrace.http.status_code`, or `glasstrace.http.duration_ms`
+ *     on the parent HTTP span — root-request semantics are owned by
+ *     the enriching exporter (`packages/sdk/src/enriching-exporter.ts`).
+ *   - On a thrown handler error: span ends with `ERROR` status +
+ *     `recordException`; rethrows. The exception is normalized to
+ *     `Error | string` first so non-Error throwables (number, plain
+ *     object) do not crash `recordException`.
+ *   - Always ends the span (`finally`), even on `throw`.
+ *
+ * @module @glasstrace/sdk/middleware
+ */
+
+/**
+ * INTERNAL — clears the once-flag for the
+ * `middleware:skipped_uninstalled` lifecycle event. Invoked by
+ * Vitest fixtures only; not part of the public surface.
+ */
+declare function _resetForTesting(): void;
+/**
+ * Permissive structural bound for a request-middleware function. The
+ * shape is the intersection of Next.js's `middleware.ts` export
+ * (`(req: NextRequest, event?: NextFetchEvent) => NextResponse |
+ * Response | Promise<NextResponse | Response> | undefined`) and the
+ * generic Web Fetch API (`(req: Request, ...rest: any[]) => Response
+ * | Promise<Response>`). The parameter list is typed with `any[]` for
+ * the rest position so any caller-narrowed signature is assignable
+ * without the wrapper having to import `next/server` types.
+ *
+ * Exported so consumers can reference it for type-inference assertions
+ * (e.g., proving a strongly-typed handler fits the bound). The
+ * runtime contract is fixed by the Web Fetch API: the first argument
+ * is a `Request`-shaped object and the return is a `Response`-shaped
+ * value (or a Promise of one).
+ */
+type RequestMiddlewareFunction = (req: any, ...rest: any[]) => unknown;
+/**
+ * Options for {@link tracedRequestMiddleware}.
+ *
+ * @example
+ * ```ts
+ * import { tracedRequestMiddleware } from "@glasstrace/sdk/middleware";
+ * import type { NextRequest } from "next/server";
+ *
+ * export const middleware = tracedRequestMiddleware(
+ *   { name: "auth-middleware", attributes: { "auth.required": true } },
+ *   async (req: NextRequest) => {
+ *     // … your auth logic here …
+ *     return NextResponse.next();
+ *   },
+ * );
+ * ```
+ */
+interface TracedRequestMiddlewareOptions {
+    /**
+     * Span name. Required, non-empty string. Used as the OTel span name
+     * and appears in trace timelines. Names should be stable across
+     * runs so the product-side transform can reason about middleware
+     * identity (e.g., "auth-middleware", "rate-limiter"); avoid
+     * embedding request data in the name.
+     */
+    name: string;
+    /**
+     * Optional attributes attached to the span before the wrapped
+     * handler runs. Forwarded to OTel as-is via `span.setAttributes()`.
+     * The SDK does not redact, sanitize, or scan values here — callers
+     * MUST avoid placing tokens, credentials, or other sensitive data
+     * in `attributes`.
+     *
+     * Sensitive request/response data is captured through gated SDK
+     * paths (e.g., `glasstrace.error.response_body`), not through this
+     * surface.
+     */
+    attributes?: Record<string, AttributeValue>;
+}
+/**
+ * Wrap a Next.js / generic-fetch request-middleware function in an
+ * OTel span tagged with `glasstrace.causal.middleware_for_request`.
+ *
+ * Each call to the returned function:
+ *
+ *   1. Detects the SDK's registration state. When the OTel API is
+ *      still on the noop tracer (SDK not registered, or
+ *      `OtelState.UNCONFIGURED`), runs the wrapped handler directly
+ *      and emits a `middleware:skipped_uninstalled` lifecycle event
+ *      (at most once per process). No span is opened.
+ *   2. Otherwise opens a span named `options.name` under the active
+ *      OTel context (typically the HTTP server span on Node;
+ *      detached on Edge where AsyncLocalStorage is not available).
+ *      Sets `options.attributes` first, then attaches the originating
+ *      request's path (via {@link extractRequestPath}) as
+ *      `glasstrace.causal.middleware_for_request`. The path is
+ *      omitted when extraction returns `undefined` so absent evidence
+ *      is preferred over guessed evidence.
+ *   3. Awaits the wrapped handler.
+ *   4. On a thrown error: normalizes the throwable to `Error | string`
+ *      so `recordException` does not throw on non-Error values; sets
+ *      `span.status` to `ERROR` with the error's message; rethrows the
+ *      original (un-normalized) error verbatim.
+ *   5. On a successful return: leaves the span status `UNSET` per OTel
+ *      instrumentation-library guidance (explicit `OK` would shadow
+ *      downstream consumers' error transitions).
+ *   6. Always ends the span, even on `throw` or `return`.
+ *
+ * Type-inference: the returned function preserves the input function's
+ * type `H`, so caller-narrowed signatures (e.g., `(req: NextRequest)
+ * => NextResponse`) flow through unchanged.
+ *
+ * @param options - Span name and optional pre-start attributes.
+ * @param handler - The user's middleware handler. Must accept a
+ *   request-shaped object as its first argument and return (or
+ *   resolve to) a response-shaped value.
+ * @returns The wrapped handler with the same call signature and
+ *   return type as `handler`.
+ *
+ * @example Next.js middleware.ts
+ * ```ts
+ * import { tracedRequestMiddleware } from "@glasstrace/sdk/middleware";
+ * import { NextResponse, type NextRequest } from "next/server";
+ *
+ * export const middleware = tracedRequestMiddleware(
+ *   { name: "auth-middleware" },
+ *   async (req: NextRequest) => {
+ *     if (!req.cookies.get("session")) {
+ *       return NextResponse.redirect(new URL("/login", req.url));
+ *     }
+ *     return NextResponse.next();
+ *   },
+ * );
+ *
+ * export const config = { matcher: ["/dashboard/:path*"] };
+ * ```
+ */
+declare function tracedRequestMiddleware<H extends RequestMiddlewareFunction>(options: TracedRequestMiddlewareOptions, handler: H): H;
+
+export { type RequestMiddlewareFunction, type TracedRequestMiddlewareOptions, _resetForTesting, tracedRequestMiddleware };

package/dist/middleware/index.d.ts

@@ -0,0 +1,183 @@
+import { AttributeValue } from './common/Attributes';
+
+/**
+ * Request-middleware-ownership instrumentation for Glasstrace.
+ *
+ * Subpath: `@glasstrace/sdk/middleware`
+ *
+ * This module exposes {@link tracedRequestMiddleware}, a wrapper that
+ * turns a Next.js `middleware.ts` function (or any generic
+ * `Request → Response`-shaped handler) into a span-emitting middleware
+ * function. Each invocation opens a child span and tags it with the
+ * `glasstrace.causal.middleware_for_request` causal-evidence attribute
+ * carrying the originating request's normalized path so the
+ * product-side trace-summary transform can link the middleware span
+ * to the owning HTTP request trace (DISC-1537 / SDK-046).
+ *
+ * Edge-runtime safety
+ * -------------------
+ * The wrapper is included in the SDK's edge bundle
+ * (`packages/sdk/src/edge-entry.ts`). Its closure imports only the
+ * OTel API, the protocol constants, and the
+ * `./optional-lifecycle.js` bridge — none of which reach into
+ * `node:*` built-ins or the `process` global. The F003 closure scan
+ * (`packages/sdk/scripts/check-edge-bundle.mjs`) enforces this on
+ * every build.
+ *
+ * Causal-evidence form
+ * --------------------
+ * The wrapper attaches the originating request path as a span
+ * attribute (`glasstrace.causal.middleware_for_request`). It does NOT
+ * emit an OTel `Link`. Reasons:
+ *
+ *   1. The Next.js Edge runtime does not propagate AsyncLocalStorage
+ *      into `middleware.ts`, so there is no in-process
+ *      `SpanContext` to link to in that environment. Attribute-only
+ *      causality works in both Node and Edge runtimes; a Link would
+ *      degrade to a no-op (no parent context) on Edge.
+ *   2. The product-side trace-summary transform reconstructs
+ *      ownership from `glasstrace.causal.*` attributes per
+ *      DISC-1539 §51-58; it does not require a Link.
+ *
+ * Invariants
+ * ----------
+ *
+ *   - The wrapped function preserves the user's call-site type so
+ *     Next.js's `middleware` export contract (`(req: NextRequest) =>
+ *     NextResponse | Response`) flows through unchanged.
+ *   - The middleware span MUST NOT overwrite `glasstrace.route`,
+ *     `glasstrace.http.status_code`, or `glasstrace.http.duration_ms`
+ *     on the parent HTTP span — root-request semantics are owned by
+ *     the enriching exporter (`packages/sdk/src/enriching-exporter.ts`).
+ *   - On a thrown handler error: span ends with `ERROR` status +
+ *     `recordException`; rethrows. The exception is normalized to
+ *     `Error | string` first so non-Error throwables (number, plain
+ *     object) do not crash `recordException`.
+ *   - Always ends the span (`finally`), even on `throw`.
+ *
+ * @module @glasstrace/sdk/middleware
+ */
+
+/**
+ * INTERNAL — clears the once-flag for the
+ * `middleware:skipped_uninstalled` lifecycle event. Invoked by
+ * Vitest fixtures only; not part of the public surface.
+ */
+declare function _resetForTesting(): void;
+/**
+ * Permissive structural bound for a request-middleware function. The
+ * shape is the intersection of Next.js's `middleware.ts` export
+ * (`(req: NextRequest, event?: NextFetchEvent) => NextResponse |
+ * Response | Promise<NextResponse | Response> | undefined`) and the
+ * generic Web Fetch API (`(req: Request, ...rest: any[]) => Response
+ * | Promise<Response>`). The parameter list is typed with `any[]` for
+ * the rest position so any caller-narrowed signature is assignable
+ * without the wrapper having to import `next/server` types.
+ *
+ * Exported so consumers can reference it for type-inference assertions
+ * (e.g., proving a strongly-typed handler fits the bound). The
+ * runtime contract is fixed by the Web Fetch API: the first argument
+ * is a `Request`-shaped object and the return is a `Response`-shaped
+ * value (or a Promise of one).
+ */
+type RequestMiddlewareFunction = (req: any, ...rest: any[]) => unknown;
+/**
+ * Options for {@link tracedRequestMiddleware}.
+ *
+ * @example
+ * ```ts
+ * import { tracedRequestMiddleware } from "@glasstrace/sdk/middleware";
+ * import type { NextRequest } from "next/server";
+ *
+ * export const middleware = tracedRequestMiddleware(
+ *   { name: "auth-middleware", attributes: { "auth.required": true } },
+ *   async (req: NextRequest) => {
+ *     // … your auth logic here …
+ *     return NextResponse.next();
+ *   },
+ * );
+ * ```
+ */
+interface TracedRequestMiddlewareOptions {
+    /**
+     * Span name. Required, non-empty string. Used as the OTel span name
+     * and appears in trace timelines. Names should be stable across
+     * runs so the product-side transform can reason about middleware
+     * identity (e.g., "auth-middleware", "rate-limiter"); avoid
+     * embedding request data in the name.
+     */
+    name: string;
+    /**
+     * Optional attributes attached to the span before the wrapped
+     * handler runs. Forwarded to OTel as-is via `span.setAttributes()`.
+     * The SDK does not redact, sanitize, or scan values here — callers
+     * MUST avoid placing tokens, credentials, or other sensitive data
+     * in `attributes`.
+     *
+     * Sensitive request/response data is captured through gated SDK
+     * paths (e.g., `glasstrace.error.response_body`), not through this
+     * surface.
+     */
+    attributes?: Record<string, AttributeValue>;
+}
+/**
+ * Wrap a Next.js / generic-fetch request-middleware function in an
+ * OTel span tagged with `glasstrace.causal.middleware_for_request`.
+ *
+ * Each call to the returned function:
+ *
+ *   1. Detects the SDK's registration state. When the OTel API is
+ *      still on the noop tracer (SDK not registered, or
+ *      `OtelState.UNCONFIGURED`), runs the wrapped handler directly
+ *      and emits a `middleware:skipped_uninstalled` lifecycle event
+ *      (at most once per process). No span is opened.
+ *   2. Otherwise opens a span named `options.name` under the active
+ *      OTel context (typically the HTTP server span on Node;
+ *      detached on Edge where AsyncLocalStorage is not available).
+ *      Sets `options.attributes` first, then attaches the originating
+ *      request's path (via {@link extractRequestPath}) as
+ *      `glasstrace.causal.middleware_for_request`. The path is
+ *      omitted when extraction returns `undefined` so absent evidence
+ *      is preferred over guessed evidence.
+ *   3. Awaits the wrapped handler.
+ *   4. On a thrown error: normalizes the throwable to `Error | string`
+ *      so `recordException` does not throw on non-Error values; sets
+ *      `span.status` to `ERROR` with the error's message; rethrows the
+ *      original (un-normalized) error verbatim.
+ *   5. On a successful return: leaves the span status `UNSET` per OTel
+ *      instrumentation-library guidance (explicit `OK` would shadow
+ *      downstream consumers' error transitions).
+ *   6. Always ends the span, even on `throw` or `return`.
+ *
+ * Type-inference: the returned function preserves the input function's
+ * type `H`, so caller-narrowed signatures (e.g., `(req: NextRequest)
+ * => NextResponse`) flow through unchanged.
+ *
+ * @param options - Span name and optional pre-start attributes.
+ * @param handler - The user's middleware handler. Must accept a
+ *   request-shaped object as its first argument and return (or
+ *   resolve to) a response-shaped value.
+ * @returns The wrapped handler with the same call signature and
+ *   return type as `handler`.
+ *
+ * @example Next.js middleware.ts
+ * ```ts
+ * import { tracedRequestMiddleware } from "@glasstrace/sdk/middleware";
+ * import { NextResponse, type NextRequest } from "next/server";
+ *
+ * export const middleware = tracedRequestMiddleware(
+ *   { name: "auth-middleware" },
+ *   async (req: NextRequest) => {
+ *     if (!req.cookies.get("session")) {
+ *       return NextResponse.redirect(new URL("/login", req.url));
+ *     }
+ *     return NextResponse.next();
+ *   },
+ * );
+ *
+ * export const config = { matcher: ["/dashboard/:path*"] };
+ * ```
+ */
+declare function tracedRequestMiddleware<H extends RequestMiddlewareFunction>(options: TracedRequestMiddlewareOptions, handler: H): H;
+
+export { type RequestMiddlewareFunction, type TracedRequestMiddlewareOptions, _resetForTesting, tracedRequestMiddleware };

package/dist/middleware/index.js

@@ -0,0 +1,13 @@
+import {
+  _resetForTesting,
+  tracedRequestMiddleware
+} from "../chunk-QHV7NFON.js";
+import "../chunk-CL3OVHPO.js";
+import "../chunk-DQ25VOKK.js";
+import "../chunk-JHUNLPSS.js";
+import "../chunk-NSBPE2FW.js";
+export {
+  _resetForTesting,
+  tracedRequestMiddleware
+};
+//# sourceMappingURL=index.js.map

package/dist/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}