@pikku/core 0.12.150 → 0.12.151

package/dist/wirings/channel/channel-common.js

@@ -2,7 +2,8 @@ import { combineMiddleware, runMiddleware } from '../../middleware-runner.js';
 import { runPikkuFunc } from '../../function/function-runner.js';
 import { createMiddlewareSessionWireProps, } from '../../services/user-session-service.js';
 import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../../channel-middleware-runner.js';
-export const runChannelLifecycleWithMiddleware = async ({ channelConfig, meta, lifecycleConfig, lifecycleType, services, channel, data, channelMiddlewareMeta, userSession, wireServices, }) => {
+import { childTraceWire } from '../../trace.js';
+export const runChannelLifecycleWithMiddleware = async ({ channelConfig, meta, lifecycleConfig, lifecycleType, services, channel, data, channelMiddlewareMeta, userSession, wireServices, trace, }) => {
     const lifecycleMiddleware = typeof lifecycleConfig === 'object' && 'middleware' in lifecycleConfig
         ? lifecycleConfig.middleware || []
         : [];
@@ -17,6 +18,7 @@ export const runChannelLifecycleWithMiddleware = async ({ channelConfig, meta, l
     });
     let wire = {
         channel,
+        ...childTraceWire(trace),
         ...(userSession ? createMiddlewareSessionWireProps(userSession) : {}),
     };
     if (allChannelMiddleware.length > 0) {

package/dist/wirings/channel/channel-handler.js

@@ -3,6 +3,7 @@ import { runPikkuFunc } from '../../function/function-runner.js';
 import { isChannelRPCPending, isChannelRPCResponse } from './channel-rpc.js';
 import { handleChannelRPCResponse } from './channel-host-rpc.js';
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js';
+import { childTraceWire } from '../../trace.js';
 const getChannelMeta = (channelName) => {
     return pikkuState(null, 'channel', 'meta')[channelName];
 };
@@ -88,6 +89,7 @@ export const processMessageHandlers = (services, channelConfig, channelHandler,
             sessionService: userSession,
             wire: {
                 channel: channelHandler.getChannel(),
+                ...childTraceWire(channelHandler.trace),
                 ...(userSession && createMiddlewareSessionWireProps(userSession)),
             },
             packageName,

package/dist/wirings/channel/channel-host-rpc.d.ts

@@ -15,7 +15,7 @@ export declare const getChannelHostRPC: (channel: PikkuChannel<unknown, any>, op
  * Kept out of the channel handler so a channel nobody calls back on pays for no
  * registry, and because a handler has no services to build a validator with.
  */
-export declare const channelRemote: (channel: PikkuChannel<unknown, any, any>, funcName: string, data?: unknown) => Promise<unknown>;
+export declare const channelRemote: (channel: PikkuChannel<unknown, any, any>, funcName: string, data?: unknown, traceparent?: string) => Promise<unknown>;
 /** False for an unknown connection or id, so a stray frame is dropped. */
 export declare const handleChannelRPCResponse: (channelId: string, message: unknown) => boolean;
 /**

package/dist/wirings/channel/channel-host-rpc.js

@@ -19,10 +19,10 @@ export const getChannelHostRPC = (channel, options = {}) => {
  * Kept out of the channel handler so a channel nobody calls back on pays for no
  * registry, and because a handler has no services to build a validator with.
  */
-export const channelRemote = async (channel, funcName, data) => getChannelHostRPC(channel, {
+export const channelRemote = async (channel, funcName, data, traceparent) => getChannelHostRPC(channel, {
     validateInput: createChannelRPCInputValidator(getSingletonServices()),
     validateResult: createChannelRPCResultValidator(getSingletonServices()),
-}).invoke(funcName, data);
+}).invoke(funcName, data, undefined, traceparent);
 /** False for an unknown connection or id, so a stray frame is dropped. */
 export const handleChannelRPCResponse = (channelId, message) => hostRPCByChannel.get(channelId)?.handleResponse(message) ?? false;
 /**

package/dist/wirings/channel/channel-rpc-responder.d.ts

@@ -7,9 +7,15 @@ import { type ApprovalRequester, type Capabilities } from './channel-rpc.types.j
  * name is refused exactly like an unknown one, so the caller cannot probe for
  * what this end can do.
  */
-export declare const createChannelRPCResponder: ({ capabilities, send, approve, }: {
+export declare const createChannelRPCResponder: ({ capabilities, send, approve, trustInboundTraceparent, }: {
     capabilities: Capabilities;
     send: (data: unknown) => Promise<void> | void;
     /** Omitted means there is nobody to ask, which refuses rather than runs. */
     approve?: ApprovalRequester;
+    /**
+     * Hands a capability the peer's `traceparent`. Off by default, like public
+     * HTTP: the caller may turn it on only for a channel whose peer it has
+     * authenticated.
+     */
+    trustInboundTraceparent?: boolean;
 }) => (message: unknown) => Promise<boolean>;

package/dist/wirings/channel/channel-rpc-responder.js

@@ -7,7 +7,7 @@ import { CHANNEL_RPC_PENDING, CHANNEL_RPC_RESPONSE, isCapabilityDef, isChannelRP
  * name is refused exactly like an unknown one, so the caller cannot probe for
  * what this end can do.
  */
-export const createChannelRPCResponder = ({ capabilities, send, approve, }) => {
+export const createChannelRPCResponder = ({ capabilities, send, approve, trustInboundTraceparent = false, }) => {
     return async (message) => {
         if (!isChannelRPCRequest(message)) {
             return false;
@@ -58,7 +58,7 @@ export const createChannelRPCResponder = ({ capabilities, send, approve, }) => {
                 action: CHANNEL_RPC_RESPONSE,
                 id: message.id,
                 ok: true,
-                result: await execute(message.data),
+                result: await execute(message.data, trustInboundTraceparent ? { traceparent: message.traceparent } : {}),
             };
         }
         catch (e) {

package/dist/wirings/channel/channel-rpc-service.d.ts

@@ -30,5 +30,5 @@ export declare class ChannelDeploymentService implements DeploymentService {
      * session on the wire would carry the caller's credentials while authorising
      * nothing.
      */
-    invoke(funcName: string, data: unknown, _session?: unknown, traceId?: string): Promise<unknown>;
+    invoke(funcName: string, data: unknown, _session?: unknown, traceparent?: string): Promise<unknown>;
 }

package/dist/wirings/channel/channel-rpc-service.js

@@ -37,7 +37,7 @@ export class ChannelDeploymentService {
      * session on the wire would carry the caller's credentials while authorising
      * nothing.
      */
-    async invoke(funcName, data, _session, traceId) {
+    async invoke(funcName, data, _session, traceparent) {
         // Not a security control — the peer must check what it is handed, and a
         // hostile caller would send arguments that pass. It catches version drift
         // and fails it here rather than inside the peer's process.
@@ -60,7 +60,7 @@ export class ChannelDeploymentService {
             id,
             funcName,
             data,
-            traceId,
+            traceparent,
         };
         try {
             await this.send(request);

package/dist/wirings/channel/channel-rpc.types.d.ts

@@ -12,7 +12,8 @@ export interface ChannelRPCRequest {
     id: string;
     funcName: string;
     data: unknown;
-    traceId?: string;
+    /** A claim by the peer. See `trustInboundTraceparent` on the responder. */
+    traceparent?: string;
 }
 /** The answer to a {@link ChannelRPCRequest} with the same `id`: a result when `ok`, an error name and message otherwise. */
 export interface ChannelRPCResponse {
@@ -63,7 +64,9 @@ export interface ApprovalPolicy {
     approvalDescriptionFn?: (input: unknown) => Promise<string> | string;
 }
 /** A function one end of a channel offers for the peer to call through `channel.remote`. */
-export type CapabilityHandler = (data: any) => Promise<unknown> | unknown;
+export type CapabilityHandler = (data: any, context?: {
+    traceparent?: string;
+}) => Promise<unknown> | unknown;
 /**
  * `needsApproval` is required here on purpose. On `AgentToolDef` the same
  * field is optional and absence means "do not ask"; here absence means the

package/dist/wirings/channel/channel-rpc.types.js

@@ -18,7 +18,7 @@ export const isChannelRPCRequest = (message) => isRecord(message) &&
     message.id.length > 0 &&
     typeof message.funcName === 'string' &&
     message.funcName.length > 0 &&
-    (message.traceId === undefined || typeof message.traceId === 'string');
+    (message.traceparent === undefined || typeof message.traceparent === 'string');
 export const isChannelRPCResponse = (message) => isRecord(message) &&
     message.action === CHANNEL_RPC_RESPONSE &&
     typeof message.id === 'string' &&

package/dist/wirings/channel/channel-store.d.ts

@@ -4,12 +4,14 @@ export type Channel<ChannelType = unknown, OpeningData = unknown> = {
     channelName: string;
     channelObject?: ChannelType;
     openingData?: OpeningData;
+    /** The connection's W3C trace, so every frame continues it. */
+    traceparent?: string;
 };
 /**
  * Persists open channels for serverless runtimes, where each connect, message and disconnect runs in a separate invocation.
  *
- * It keeps the channel's opening data, its state, and the `pikkuUserId` of the
- * session established on connect. The session itself is not stored: each
+ * It keeps the channel's opening data, its trace, its state, and the
+ * `pikkuUserId` of the session established on connect. The session itself is not stored: each
  * message reloads it from the `sessionStore` by that id.
  */
 export declare abstract class ChannelStore<ChannelType = unknown, OpeningData = unknown, TypedChannel = Channel<ChannelType, OpeningData>> {

package/dist/wirings/channel/channel-store.js

@@ -1,8 +1,8 @@
 /**
  * Persists open channels for serverless runtimes, where each connect, message and disconnect runs in a separate invocation.
  *
- * It keeps the channel's opening data, its state, and the `pikkuUserId` of the
- * session established on connect. The session itself is not stored: each
+ * It keeps the channel's opening data, its trace, its state, and the
+ * `pikkuUserId` of the session established on connect. The session itself is not stored: each
  * message reloads it from the `sessionStore` by that id.
  */
 export class ChannelStore {

package/dist/wirings/channel/channel.types.d.ts

@@ -7,6 +7,7 @@ export type CorePikkuChannelMiddleware<Services = any, Event = unknown> = (servi
 /** Builds a {@link CorePikkuChannelMiddleware} from configuration, so the same middleware can be reused with different settings. */
 export type CorePikkuChannelMiddlewareFactory<In = any, Services = any, Event = unknown> = (input: In) => CorePikkuChannelMiddleware<Services, Event>;
 import type { CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
+import type { TraceContext } from '../../trace.js';
 /** Options for running a channel connection. They mean the same as the matching {@link RunHTTPWiringOptions}. */
 export type RunChannelOptions = Partial<{
     skipUserSession: boolean;
@@ -134,6 +135,8 @@ export interface PikkuChannel<OpeningData, out Out, Remote extends (...args: any
 }
 /** The runtime side of one connection: how a channel's sends reach the actual socket. */
 export interface PikkuChannelHandler<OpeningData = unknown, Out = unknown> {
+    /** The connection's trace. Each message and reverse RPC is a span in it. */
+    trace?: TraceContext;
     send(message: Out, isBinary?: boolean): Promise<void> | void;
     sendBinary(data: BinaryData): Promise<void> | void;
     getChannel(): PikkuChannel<OpeningData, Out>;

package/dist/wirings/channel/local/local-channel-runner.js

@@ -10,6 +10,7 @@ import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../..
 import { combineMiddleware, runMiddleware } from '../../../middleware-runner.js';
 import { runChannelLifecycleWithMiddleware } from '../channel-common.js';
 import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../../pikku-state.js';
+import { childTraceWire, createTrace, tracedLogger } from '../../../trace.js';
 const runUpgradeMiddleware = async (singletonServices, request, response, userSession) => {
     const http = createHTTPWire(request, response);
     const httpGroups = pikkuState(null, 'middleware', 'httpGroup');
@@ -73,9 +74,14 @@ export const runLocalChannel = async ({ channelId, request, response, route, ski
     const main = async () => {
         try {
             channelHandler = new PikkuLocalChannelHandler(channelId, channelConfig.name, openingData, singletonServices.logger);
+            // knowledge: decisions/internals/a-channel-connection-is-one-trace.md
+            channelHandler.trace = createTrace();
+            const { traceId } = channelHandler.trace;
+            const logger = tracedLogger(singletonServices.logger, traceId);
             const channel = channelHandler.getChannel();
             const wire = {
                 channel,
+                ...childTraceWire(channelHandler.trace),
                 ...createMiddlewareSessionWireProps(userSession),
             };
             if (createWireServices) {
@@ -103,17 +109,19 @@ export const runLocalChannel = async ({ channelId, request, response, route, ski
                             channelMiddlewareMeta: meta.channelMiddleware,
                             userSession,
                             wireServices,
+                            trace: channelHandler?.trace,
                         });
                         if (result !== undefined) {
                             await channel.send(result);
                         }
                     }
                     catch (e) {
-                        singletonServices.logger.error(`Error handling onConnect: ${e}`);
+                        logger.error(`Error handling onConnect: ${e}`);
                         const errorResponse = getErrorResponse(e);
                         await channel.send({
                             error: errorResponse?.message ??
                                 (isProduction() ? 'Internal server error' : e.message),
+                            errorId: traceId,
                             ...(!isProduction() && { errorName: e.constructor?.name }),
                         });
                     }
@@ -132,14 +140,16 @@ export const runLocalChannel = async ({ channelId, request, response, route, ski
                             channelMiddlewareMeta: meta.channelMiddleware,
                             userSession,
                             wireServices,
+                            trace: channelHandler?.trace,
                         });
                     }
                     catch (e) {
-                        singletonServices.logger.error(`Error handling onDisconnect: ${e}`);
+                        logger.error(`Error handling onDisconnect: ${e}`);
                         const errorResponse = getErrorResponse(e);
                         await channel.send({
                             error: errorResponse?.message ??
                                 (isProduction() ? 'Internal server error' : e.message),
+                            errorId: traceId,
                             ...(!isProduction() && { errorName: e.constructor?.name }),
                         });
                     }
@@ -160,15 +170,16 @@ export const runLocalChannel = async ({ channelId, request, response, route, ski
                     }
                 }
                 catch (e) {
-                    singletonServices.logger.error(e);
+                    logger.error(e);
                     const errorResponse = getErrorResponse(e);
                     await channel.send({
                         error: errorResponse?.message ??
                             (isProduction() ? 'Internal server error' : e.message),
+                        errorId: traceId,
                         ...(!isProduction() && { errorName: e.constructor?.name }),
                     });
                     setTimeout(() => {
-                        Promise.resolve(channel.close()).catch((closeError) => singletonServices.logger.error(closeError));
+                        Promise.resolve(channel.close()).catch((closeError) => logger.error(closeError));
                     }, 200);
                 }
             });
@@ -181,7 +192,7 @@ export const runLocalChannel = async ({ channelId, request, response, route, ski
                         }
                     }
                     catch (e) {
-                        singletonServices.logger.error(`Error handling binary message: ${e.message}`);
+                        logger.error(`Error handling binary message: ${e.message}`);
                     }
                 });
             }

package/dist/wirings/channel/pikku-abstract-channel-handler.d.ts

@@ -1,4 +1,5 @@
 import type { BinaryData, PikkuChannel, PikkuChannelHandler } from './channel.types.js';
+import { type TraceContext } from '../../trace.js';
 /**
  * Base class for a runtime's {@link PikkuChannelHandler}. A runtime implements `send` and `sendBinary`; this builds the {@link PikkuChannel} on top, with in-memory state and `remote`.
  *
@@ -10,6 +11,7 @@ export declare abstract class PikkuAbstractChannelHandler<OpeningData = unknown,
     protected openingData: OpeningData;
     protected channel?: PikkuChannel<OpeningData, Out>;
     constructor(channelId: string, channelName: string, openingData: OpeningData);
+    trace?: TraceContext;
     abstract send(message: Out, isBinary?: boolean): Promise<void> | void;
     abstract sendBinary(data: BinaryData): Promise<void> | void;
     getChannel(): PikkuChannel<OpeningData, Out>;

package/dist/wirings/channel/pikku-abstract-channel-handler.js

@@ -1,4 +1,5 @@
 import { channelRemote, releaseChannelHostRPC } from './channel-host-rpc.js';
+import { outgoingTraceparent } from '../../trace.js';
 /**
  * Base class for a runtime's {@link PikkuChannelHandler}. A runtime implements `send` and `sendBinary`; this builds the {@link PikkuChannel} on top, with in-memory state and `remote`.
  *
@@ -14,6 +15,7 @@ export class PikkuAbstractChannelHandler {
         this.channelName = channelName;
         this.openingData = openingData;
     }
+    trace;
     getChannel() {
         if (!this.channel) {
             let channelState;
@@ -32,7 +34,7 @@ export class PikkuAbstractChannelHandler {
                 clearState: () => {
                     channelState = undefined;
                 },
-                remote: (funcName, data) => channelRemote(this.getChannel(), funcName, data),
+                remote: (funcName, data) => channelRemote(this.getChannel(), funcName, data, outgoingTraceparent(this)),
             };
         }
         return this.channel;

package/dist/wirings/channel/serverless/serverless-channel-runner.js

@@ -7,6 +7,7 @@ import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../..
 import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../../pikku-state.js';
 import { PikkuFetchHTTPRequest } from '../../http/pikku-fetch-http-request.js';
 import { runChannelLifecycleWithMiddleware } from '../channel-common.js';
+import { createTrace, formatTraceparent, parseTraceparent, tracedLogger, } from '../../../trace.js';
 const getVariablesForChannel = ({ channelId, channelName, channelHandlerFactory, openingData, }) => {
     const channels = pikkuState(null, 'channel', 'channels');
     const channelConfig = channels.get(channelName);
@@ -26,6 +27,21 @@ const getVariablesForChannel = ({ channelId, channelName, channelHandlerFactory,
         meta,
     };
 };
+/**
+ * The connection's trace as connect stored it. A frame is a span in it, so this
+ * is the connection's own span and not a new one.
+ */
+// knowledge: decisions/internals/a-channel-connection-is-one-trace.md
+const storedTrace = (traceparent) => {
+    const stored = parseTraceparent(traceparent);
+    return stored
+        ? {
+            traceId: stored.traceId,
+            spanId: stored.parentSpanId,
+            sampled: stored.sampled,
+        }
+        : createTrace();
+};
 /**
  * Handles a serverless connect event: opens the channel, stores it, and runs `onConnect`.
  *
@@ -56,18 +72,21 @@ export const runChannelConnect = async ({ channelId, channelObject, request, res
         coerceDataFromSchema,
         userSession,
     });
+    const trace = createTrace();
     try {
         await channelStore.addChannel({
             channelId,
             channelName: channelConfig.name,
             openingData,
             channelObject,
+            traceparent: formatTraceparent(trace),
         });
-        const { channel } = getVariablesForChannel({
+        const { channel, channelHandler } = getVariablesForChannel({
             channelId,
             channelHandlerFactory,
             channelName: channelConfig.name,
         });
+        channelHandler.trace = trace;
         channel.setState = (state) => channelStore.setState(channelId, state);
         // knowledge: decisions/internals/channel-state-accessors-are-unsound-generics-that-every-implementation-asserts.md
         channel.getState = () => channelStore.getState(channelId);
@@ -95,6 +114,7 @@ export const runChannelConnect = async ({ channelId, channelObject, request, res
                 channelMiddlewareMeta: meta.channelMiddleware,
                 userSession,
                 wireServices,
+                trace: channelHandler.trace,
             });
         }
         const pikkuUserId = userSession.getPikkuUserId();
@@ -131,7 +151,7 @@ export const runChannelDisconnect = async ({ channelId, channelStore, channelHan
         singletonServices.logger.info(`Channel ${channelId} not found during disconnect - already cleaned up`);
         return;
     }
-    const { openingData, channelName, pikkuUserId } = channelData;
+    const { openingData, channelName, pikkuUserId, traceparent } = channelData;
     const { channel, channelConfig, meta } = getVariablesForChannel({
         channelId,
         channelHandlerFactory,
@@ -173,6 +193,7 @@ export const runChannelDisconnect = async ({ channelId, channelStore, channelHan
                 channelMiddlewareMeta: meta.channelMiddleware,
                 userSession,
                 wireServices,
+                trace: storedTrace(traceparent),
             });
         }
         catch (e) {
@@ -198,13 +219,14 @@ export const runChannelMessage = async ({ channelId, channelStore, channelHandle
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();
     let wireServices;
-    const { openingData, channelName, pikkuUserId } = await channelStore.getChannel(channelId);
+    const { openingData, channelName, pikkuUserId, traceparent } = await channelStore.getChannel(channelId);
     const { channel, channelHandler, channelConfig } = getVariablesForChannel({
         channelId,
         channelHandlerFactory,
         openingData,
         channelName,
     });
+    channelHandler.trace = storedTrace(traceparent);
     channel.setState = (state) => channelStore.setState(channelId, state);
     // knowledge: decisions/internals/channel-state-accessors-are-unsound-generics-that-every-implementation-asserts.md
     channel.getState = () => channelStore.getState(channelId);
@@ -234,10 +256,11 @@ export const runChannelMessage = async ({ channelId, channelStore, channelHandle
         response = await onMessage(data);
     }
     catch (e) {
-        singletonServices.logger.error(`Error processing message: ${e.message || e}`);
+        tracedLogger(singletonServices.logger, channelHandler.trace.traceId).error(`Error processing message: ${e.message || e}`);
         return {
             error: e.message || 'Unknown error',
             errorName: e.constructor?.name,
+            errorId: channelHandler.trace.traceId,
         };
     }
     finally {

package/dist/wirings/gateway/gateway-runner.js

@@ -66,6 +66,7 @@ export const resolveGatewayAdapter = (config, services) => {
     }
     return resolved;
 };
+import { traceWire } from '../../trace.js';
 /**
  * Wires a messaging gateway (Slack, WhatsApp, a web chat, ...) so each inbound message runs `func`
  * with the adapter-normalised message.
@@ -318,7 +319,8 @@ export const createListenerMessageHandler = (name, config, singletonServices) =>
         const parsed = adapter.parse(rawData);
         if (!parsed)
             return;
-        const wire = {};
+        // Here rather than left to the function runner: middleware runs first.
+        const wire = traceWire();
         const gateway = {
             gatewayName: name,
             senderId: parsed.senderId,

package/dist/wirings/http/http-runner.d.ts

@@ -62,9 +62,9 @@ export declare const pikkuFetch: <In, Out>(request: Request | PikkuHTTPRequest,
  *
  * The lower-level form of {@link fetch} for adapters that bring their own
  * request and response objects (Express, Fastify, uWS). A web `Request` is
- * wrapped with the `maxBodySize` limit. The trace ID is taken from `traceId`,
- * then the `x-request-id` header, then `generateRequestId`, and is returned to
- * the client as `errorId` on failures.
+ * wrapped with the `maxBodySize` limit. The trace comes from a valid `traceId`,
+ * then `traceparent` when `trustInboundTraceparent` is set, and is otherwise new.
+ * Its id is returned to the client as `errorId` on failures.
  *
  * Errors are written to `response`: a 4xx keeps its message and payload, while a
  * 5xx or an unknown error hides its message unless `exposeErrors` is set outside
@@ -78,4 +78,4 @@ export declare const pikkuFetch: <In, Out>(request: Request | PikkuHTTPRequest,
  * @throws The original error when `bubbleErrors` is set, after the error response has been written.
  * @throws {Error} When `skipUserSession` is set on a route that requires auth.
  */
-export declare const fetchData: <In, Out>(request: Request | PikkuHTTPRequest, response: PikkuHTTPResponse, { skipUserSession, respondWith404, logWarningsForStatusCodes, coerceDataFromSchema, bubbleErrors, exposeErrors, generateRequestId, traceId: externalTraceId, maxBodySize, }?: RunHTTPWiringOptions) => Promise<Out | void>;
+export declare const fetchData: <In, Out>(request: Request | PikkuHTTPRequest, response: PikkuHTTPResponse, { skipUserSession, respondWith404, logWarningsForStatusCodes, coerceDataFromSchema, bubbleErrors, exposeErrors, traceId, trustInboundTraceparent, maxBodySize, }?: RunHTTPWiringOptions) => Promise<Out | void>;

package/dist/wirings/http/http-runner.js

@@ -1,5 +1,6 @@
 import { NotFoundError } from '../../errors/errors.js';
 import { createWeakUID, isSerializable } from '../../utils.js';
+import { resolveHTTPTrace } from '../../trace.js';
 import { getSingletonServices, getCreateWireServices, } from '../../pikku-state.js';
 import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../services/user-session-service.js';
 import { getErrorResponse } from '../../errors/error-handler.js';
@@ -120,7 +121,7 @@ export const createHTTPWire = (request, response) => {
 };
 const executeRoute = async (services, matchedRoute, http, options) => {
     const { params, route, meta } = matchedRoute;
-    const { singletonServices, createWireServices, skipUserSession, requestId } = services;
+    const { singletonServices, createWireServices, skipUserSession, trace } = services;
     const userSession = new PikkuSessionService(singletonServices.sessionStore);
     http?.request?.setParams(params);
     if (meta.headersSchemaName && http.request && singletonServices.schema) {
@@ -206,7 +207,8 @@ const executeRoute = async (services, matchedRoute, http, options) => {
         });
     }
     const wire = {
-        traceId: requestId,
+        traceId: trace.traceId,
+        trace,
         http,
         channel,
         ...createMiddlewareSessionWireProps(userSession),
@@ -295,9 +297,9 @@ export const pikkuFetch = async (request, params = {}) => {
  *
  * The lower-level form of {@link fetch} for adapters that bring their own
  * request and response objects (Express, Fastify, uWS). A web `Request` is
- * wrapped with the `maxBodySize` limit. The trace ID is taken from `traceId`,
- * then the `x-request-id` header, then `generateRequestId`, and is returned to
- * the client as `errorId` on failures.
+ * wrapped with the `maxBodySize` limit. The trace comes from a valid `traceId`,
+ * then `traceparent` when `trustInboundTraceparent` is set, and is otherwise new.
+ * Its id is returned to the client as `errorId` on failures.
  *
  * Errors are written to `response`: a 4xx keeps its message and payload, while a
  * 5xx or an unknown error hides its message unless `exposeErrors` is set outside
@@ -311,22 +313,16 @@ export const pikkuFetch = async (request, params = {}) => {
  * @throws The original error when `bubbleErrors` is set, after the error response has been written.
  * @throws {Error} When `skipUserSession` is set on a route that requires auth.
  */
-export const fetchData = async (request, response, { skipUserSession = false, respondWith404 = true, logWarningsForStatusCodes = [], coerceDataFromSchema = true, bubbleErrors = false, exposeErrors = !isProduction(), generateRequestId, traceId: externalTraceId, maxBodySize, } = {}) => {
+export const fetchData = async (request, response, { skipUserSession = false, respondWith404 = true, logWarningsForStatusCodes = [], coerceDataFromSchema = true, bubbleErrors = false, exposeErrors = !isProduction(), traceId, trustInboundTraceparent, maxBodySize, } = {}) => {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();
     let result;
     const pikkuRequest = request instanceof Request
         ? new PikkuFetchHTTPRequest(request, { maxBodySize })
         : request;
-    let requestId = externalTraceId ?? null;
-    if (!requestId) {
-        try {
-            requestId = pikkuRequest.header('x-request-id');
-        }
-        catch { }
-    }
-    requestId = requestId || generateRequestId?.() || createWeakUID();
-    const scopedLogger = singletonServices.logger.scope?.(requestId) ?? singletonServices.logger;
+    const trace = resolveHTTPTrace(() => pikkuRequest.header('traceparent'), singletonServices.logger, { traceId, trustInboundTraceparent });
+    // Read at the point of logging: mesh auth can continue the caller's trace.
+    const scopedLogger = () => singletonServices.logger.scope?.(trace.traceId) ?? singletonServices.logger;
     const http = createHTTPWire(pikkuRequest, response);
     const apiType = http.request.method();
     const apiRoute = http.request.path();
@@ -344,7 +340,7 @@ export const fetchData = async (request, response, { skipUserSession = false, re
                 response.status(204).json(undefined);
                 return;
             }
-            scopedLogger.info({
+            scopedLogger().info({
                 message: 'Route not found',
                 apiRoute,
                 apiType,
@@ -356,11 +352,11 @@ export const fetchData = async (request, response, { skipUserSession = false, re
             singletonServices,
             createWireServices,
             skipUserSession,
-            requestId,
+            trace,
         }, matchedRoute, http, { coerceDataFromSchema }));
         return result;
     }
     catch (e) {
-        handleHTTPError(e, http, requestId, scopedLogger, logWarningsForStatusCodes, respondWith404, bubbleErrors, exposeErrors);
+        handleHTTPError(e, http, trace.traceId, scopedLogger(), logWarningsForStatusCodes, respondWith404, bubbleErrors, exposeErrors);
     }
 };

package/dist/wirings/http/http.types.d.ts

@@ -20,7 +20,7 @@ export type AssertHTTPWiringParams<In, HTTPWiring extends string> = ExtractHTTPW
  * - `coerceDataFromSchema` – coerce query and path strings to the schema's types (default `true`).
  * - `bubbleErrors` – rethrow after writing the error response.
  * - `exposeErrors` – include messages and stacks of 5xx errors; ignored in production.
- * - `generateRequestId` – produce a trace ID when neither `traceId` nor `x-request-id` is present.
+ * - `trustInboundTraceparent` – continue the trace named by `traceparent` on every request. Off by default, because the header is caller-supplied.
  */
 export type RunHTTPWiringOptions = Partial<{
     skipUserSession: boolean;
@@ -29,8 +29,8 @@ export type RunHTTPWiringOptions = Partial<{
     coerceDataFromSchema: boolean;
     bubbleErrors: boolean;
     exposeErrors: boolean;
-    generateRequestId: () => string;
-    /** Pre-resolved trace ID (e.g. CF-Ray). Falls back to x-request-id header or generated ID. */
+    trustInboundTraceparent: boolean;
+    /** A trace ID the runtime already holds: 32 lowercase hex, anything else is ignored. */
     traceId: string;
     /** Maximum request body size in bytes, applied when pikku wraps a fetch `Request`. */
     maxBodySize: number;