@procedures/client 0.52.3 → 0.54.0

package/src/server/procedure-server.ts

@@ -13,6 +13,8 @@ import type { Admission, AmbientCredentials, Credentials, Method, Principal, Pri
 import { methodName, methodToPath, pathToMethod } from "./method.js";
 import { isLocalCredentials } from "./request-auth.js";
 import { STREAM_METADATA_KEY } from "./stream-metadata.js";
+import { context as otelContext } from "@opentelemetry/api";
+import { callerContext } from "../tracing/otel.js";
 import type {
   AnyProcedure,
   ProcedurePath,
@@ -151,6 +153,20 @@ export interface ProcedureServerOptions extends ServerOptions {
    */
   token?: string | undefined;
 
+  /**
+   * Which callers can set the baggage of a call (roadmap item C10 of otel-ts). Each handler runs in
+   * the context of its caller: the remote span of the `traceparent` and `tracestate` of the
+   * metadata is its parent. The `baggage` of the metadata goes into the context only from a
+   * trusted caller. Without it, the handler runs with no baggage, so an end user cannot set the
+   * baggage of the services.
+   *
+   * A local request (`LOCAL_CREDENTIALS`) and a request with the token of the server are always
+   * trusted. This function can trust more requests, for example the requests of a principal of a
+   * service. It runs after the checks of the request, so it can read `request.principal`. An
+   * error of the function means "not trusted". The default trusts no other request.
+   */
+  trustBaggage?: ((request: ServerRequest<unknown>) => boolean) | undefined;
+
   /**
    * This function gives the principal of a request, or undefined to refuse it with
    * `UNAUTHORIZED`. It runs after the token check. The capability function can read
@@ -455,11 +471,17 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
   private readonly token: string | undefined;
   private readonly principalOf: PrincipalOf | undefined;
   private readonly authenticate: ProcedureServerOptions["authenticate"];
+  private readonly trustBaggage: ProcedureServerOptions["trustBaggage"];
+  /**
+   * The requests whose caller can set the baggage (C10): a local request, a request with the
+   * token of the server, or a request with the admission of such a request.
+   */
+  private readonly trustedCallers = new WeakSet<ServerRequest<unknown>>();
   /**
    * The admissions of this server (CLI-2b): the identity of each object of admitted credentials
    * that `admission()` gave. Only this server adds an entry, so a request cannot claim one.
    */
-  private readonly admissions = new WeakMap<Credentials, { readonly principal: Principal | undefined; readonly narrowing: ServerRequest<unknown>["narrowing"] }>();
+  private readonly admissions = new WeakMap<Credentials, { readonly principal: Principal | undefined; readonly narrowing: ServerRequest<unknown>["narrowing"]; readonly trusted: boolean }>();
   /**
    * The admission of each request object. The late lookup of a lazy registry admits a request
    * before it loads packages, and the call of the same request uses that result again.
@@ -497,6 +519,7 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
     this.token = options.token;
     this.principalOf = options.principalOf;
     this.authenticate = options.authenticate;
+    this.trustBaggage = options.trustBaggage;
     const ambient = options.ambientCredentials ?? (this.principalOf ? "always" : this.authenticate ? "cookies" : undefined);
     this.ambientCredentials = ambient === false ? undefined : ambient;
     this.debugReport =
@@ -937,6 +960,7 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
     // again. Only this server makes such credentials, so a copy or a forgery has no entry.
     const admitted = request.credentials !== undefined ? this.admissions.get(request.credentials) : undefined;
     if (admitted) {
+      if (admitted.trusted) this.trustedCallers.add(request);
       if (admitted.principal) request.principal = admitted.principal;
       if (admitted.narrowing) {
         const order = this.capabilityOptions.clearanceOrder;
@@ -953,6 +977,8 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
     // A local face (this process, MCP over stdio, a message port) sets the local marker. The
     // marker key is a symbol, so a request from the network cannot carry it (CLI-1).
     const credentials = isLocalCredentials(request.credentials) ? undefined : request.credentials;
+    // A local caller is a part of this process: it can set the baggage (C10)
+    if (isLocalCredentials(request.credentials)) this.trustedCallers.add(request);
     let identity: RequestIdentity | undefined;
     if (this.principalOf && credentials !== undefined) {
       try {
@@ -966,6 +992,8 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
       const bearer = identity?.bearer ?? credentials.bearer;
       if (!tokenMatches(this.token, bearer)) return unauthorized("Unauthorized: this server requires its token");
       request.principal = { id: "token", via: "token" };
+      // A caller with the token of the server is a service of the operator: it can set the baggage (C10)
+      this.trustedCallers.add(request);
     }
     if (identity?.principal) request.principal = identity.principal;
     if (identity?.narrowing) {
@@ -1063,7 +1091,7 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
       return { ok: false, code: "UNAUTHORIZED", message: refusal.status.type === "error" ? refusal.status.message : "Unauthorized" };
     }
     const admitted: Credentials = Object.freeze({ ...credentials });
-    this.admissions.set(admitted, { principal: request.principal, narrowing: request.narrowing });
+    this.admissions.set(admitted, { principal: request.principal, narrowing: request.narrowing, trusted: this.trustedCallers.has(request) });
     return { ok: true, credentials: admitted, ...(request.principal ? { principal: request.principal } : {}) };
   }
 
@@ -1144,6 +1172,17 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
     };
   }
 
+  /** True when the caller of `request` can set the baggage of the call (C10). */
+  private trustsCaller(request: ServerRequest<unknown>): boolean {
+    if (this.trustedCallers.has(request)) return true;
+    if (!this.trustBaggage) return false;
+    try {
+      return this.trustBaggage(request) === true;
+    } catch {
+      return false;
+    }
+  }
+
   /** Run a procedure for a request with a signal. */
   private async run(procedure: AnyProcedure, request: ServerRequest<unknown>, signal: AbortSignal | undefined): Promise<ServerResponse<unknown>> {
     // The call uses the storages that it takes until its end: the end of a stream, for a stream
@@ -1160,7 +1199,10 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
         const message = `The server cannot narrow the capability of the request: ${error instanceof Error ? error.message : String(error)}`;
         return errorResponse(request.id, Object.assign(new Error(message), { code: "INTERNAL_ERROR" }), request);
       }
-      const output = await invokeProcedure(procedure, request.payload, {
+      // The handler runs in the context of its caller (C10): its trace always, its baggage only
+      // when the caller is trusted
+      const caller = callerContext(request.metadata, this.trustsCaller(request));
+      const output = await otelContext.with(caller, () => invokeProcedure(procedure, request.payload, {
         registry: this.procedureRegistry,
         metadata: request.metadata,
         signal,
@@ -1182,7 +1224,7 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
         ...(request.principal !== undefined ? { principal: request.principal } : {}),
         // The bus of the remote events is the bus of the procedures (EVENTS.md)
         ...(this.publisher ? { bus: this.publisher.bus } : {}),
-      });
+      }));
       if (output.kind === "stream") {
         // The faces that collect a stream read this mark (roadmap R15)
         const unbounded = (procedure.metadata as { stream?: { unbounded?: boolean } } | undefined)?.stream?.unbounded === true;

package/src/tracing/otel.ts

@@ -0,0 +1,122 @@
+/**
+ * The context of OpenTelemetry for the calls of a client and the invocations of a host (roadmap
+ * item C8 of otel-ts, decisions D5 and D6). This module uses `@opentelemetry/api` only. The API
+ * does nothing until a program registers an SDK, for example with `startNodeTelemetry()` of
+ * `@mark1russell7/otel-ts/node`.
+ *
+ * - With an SDK, each call gets a span of the API, and the registered propagator writes the
+ *   context of the call into its metadata: `traceparent`, `tracestate` and `baggage`.
+ * - With no SDK, `startApiSpan` gives undefined, and the W3C code of `traceparent.ts` operates as
+ *   before (D6).
+ */
+import { context, createContextKey, isSpanContextValid, propagation, ROOT_CONTEXT, SpanStatusCode, trace } from "@opentelemetry/api";
+import type { Context, Span, SpanKind, TextMapSetter } from "@opentelemetry/api";
+
+/** The name of the tracer of the spans of this package */
+export const TRACER_NAME = "@procedures/client";
+
+/**
+ * The key of the mark `internal call`. It is the same key as the key of `withInternalCall` of
+ * `@mark1russell7/otel-ts/context`, because `createContextKey` gives `Symbol.for(description)`.
+ * The propagator of otel-ts sends the baggage only on a call with this mark. A test pins the
+ * description against otel-ts.
+ */
+export const INTERNAL_CALL_KEY: symbol = createContextKey("@mark1russell7/otel-ts/context internal call");
+
+/** This function gives `from` with the mark `internal call`. */
+export function asInternalCall(from: Context): Context {
+  return from.setValue(INTERNAL_CALL_KEY, true);
+}
+
+/**
+ * This function starts a span of the API, or gives undefined when no SDK gives the span ids of
+ * its own. With no SDK, the API gives a span with no ids, or with the ids of its parent.
+ */
+export function startApiSpan(name: string, kind: SpanKind, parent: Context): Span | undefined {
+  const parentSpan = trace.getSpanContext(parent);
+  const span = trace.getTracer(TRACER_NAME).startSpan(name, { kind }, parent);
+  const own = span.spanContext();
+  if (isSpanContextValid(own) && own.spanId !== parentSpan?.spanId) return span;
+  span.end();
+  return undefined;
+}
+
+/** This function ends `span`, with the status of `error` when the call failed. */
+export function endApiSpan(span: Span, error?: unknown): void {
+  if (error !== undefined) {
+    span.recordException(error instanceof Error ? error : String(error));
+    span.setStatus({ code: SpanStatusCode.ERROR, message: error instanceof Error ? error.message : String(error) });
+    const code = (error as { code?: unknown } | null)?.code;
+    if (typeof code === "string") span.setAttribute("procedure.error.code", code);
+  }
+  span.end();
+}
+
+const metadataSetter: TextMapSetter<Record<string, unknown>> = {
+  set: (carrier, key, value) => {
+    carrier[key] = value;
+  },
+};
+
+/** This function writes the context `from` into `metadata`, with the registered propagator. */
+export function injectContext(from: Context, metadata: Record<string, unknown>): void {
+  propagation.inject(from, metadata, metadataSetter);
+}
+
+/**
+ * This function gives the parent context of an invocation of a host: the active context, with the
+ * remote span of the `traceparent` and `tracestate` of `metadata` when they are valid. The baggage
+ * of the metadata is not read: the host reads it only from a trusted caller (`@procedures/peer`).
+ */
+export function remoteParent(metadata: Record<string, unknown>, from: Context = context.active()): Context {
+  const traceparent = metadata["traceparent"];
+  if (typeof traceparent !== "string") return from;
+  const carrier: Record<string, string> = { traceparent };
+  if (typeof metadata["tracestate"] === "string") carrier["tracestate"] = metadata["tracestate"];
+  const extracted = propagation.extract(from, carrier);
+  return isSpanContextValid(trace.getSpanContext(extracted) ?? { traceId: "", spanId: "", traceFlags: 0 }) ? extracted : from;
+}
+
+/** The trace context that the caller of a call gave in its metadata: `traceparent` and `tracestate`, strings only */
+export type CallerTrace = { readonly traceparent?: string; readonly tracestate?: string };
+
+/** This function gives the `traceparent` and `tracestate` of `metadata`, before the client writes its own. */
+export function callerTraceOf(metadata: Readonly<Record<string, unknown>>): CallerTrace {
+  const { traceparent, tracestate } = metadata;
+  return {
+    ...(typeof traceparent === "string" ? { traceparent } : {}),
+    ...(typeof tracestate === "string" ? { tracestate } : {}),
+  };
+}
+
+/**
+ * This function gives the parent context of a try of a call of a client (roadmap item C19 of
+ * otel-ts): the active context when it has a valid span, else the remote span of `caller`, the
+ * trace context that the caller gave in the metadata of the call. For example, `mark` gives the
+ * environment variables `TRACEPARENT` and `TRACESTATE` there. Without this, the span of the call
+ * started a new trace, and the propagator wrote that trace over the trace context of the caller.
+ */
+export function callParent(caller: CallerTrace, from: Context = context.active()): Context {
+  const active = trace.getSpanContext(from);
+  return active !== undefined && isSpanContextValid(active) ? from : remoteParent(caller, from);
+}
+
+/**
+ * This function gives the context of the caller of an invocation of a host (roadmap item C10 of
+ * otel-ts): the handler runs in it, so its logs, metrics, spans and nested calls carry the ids of
+ * the caller.
+ *
+ * - The remote span of the `traceparent` and `tracestate` of `metadata` is always the parent.
+ * - The `baggage` of `metadata` replaces the baggage of `from` only when the caller is trusted.
+ * - When the caller is not trusted, the context has no baggage: an end user cannot set the
+ *   baggage of the services. The baggage of `from` can come from the headers of the same request,
+ *   for example from the HTTP instrumentation of an SDK, so the function removes it too.
+ */
+export function callerContext(metadata: Record<string, unknown>, trusted: boolean, from: Context = context.active()): Context {
+  const parent = remoteParent(metadata, from);
+  if (!trusted) return propagation.getBaggage(parent) === undefined ? parent : propagation.deleteBaggage(parent);
+  const baggage = metadata["baggage"];
+  if (typeof baggage !== "string") return parent;
+  const extracted = propagation.getBaggage(propagation.extract(ROOT_CONTEXT, { baggage }));
+  return extracted === undefined ? parent : propagation.setBaggage(parent, extracted);
+}

package/src/tracing/traceparent.ts

@@ -4,16 +4,32 @@
  * the metadata of a call (and HTTP as the `traceparent` header). The tracing interceptor of a
  * server continues that trace, and gives it to the nested calls, so one trace goes from the
  * client to the last handler. Before, the client and the server made two traces.
+ *
+ * The checks of the ids are `isValidTraceId` and `isValidSpanId` of `@opentelemetry/api`
+ * (decision D7 of otel-ts). They refuse an id of only zeros.
  */
+import { isValidSpanId, isValidTraceId } from "@opentelemetry/api";
 
-/** The metadata key of the W3C trace context of a call. */
+/**
+ * The metadata key of the W3C trace context of a call.
+ *
+ * @deprecated With an SDK of OpenTelemetry, the registered propagator writes and reads the trace
+ * context (roadmap C8 of otel-ts). A later MINOR removes this export, when each app registers an SDK (D6).
+ */
 export const TRACEPARENT_METADATA_KEY = "traceparent";
 
+/** The form of version 00. The ids in it have only lowercase digits, as W3C Trace Context requires. */
 const TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
-const ZERO_TRACE = "0".repeat(32);
-const ZERO_SPAN = "0".repeat(16);
 
-/** A trace context: the trace, the span of the caller, and the sampled flag. */
+/** An uppercase hex digit. The checks of the API accept it, but W3C Trace Context does not. */
+const UPPERCASE_HEX = /[A-F]/;
+
+/**
+ * A trace context: the trace, the span of the caller, and the sampled flag.
+ *
+ * @deprecated With an SDK of OpenTelemetry, the registered propagator writes and reads the trace
+ * context (roadmap C8 of otel-ts). A later MINOR removes this export, when each app registers an SDK (D6).
+ */
 export interface TraceContext {
   readonly traceId: string;
   readonly spanId: string;
@@ -51,34 +67,59 @@ function randomHex(bytes: number): string {
   return hex;
 }
 
-/** This function makes a new trace id: 32 random hex digits. */
+/**
+ * This function makes a new trace id: 32 random hex digits.
+ *
+ * @deprecated With an SDK of OpenTelemetry, the registered propagator writes and reads the trace
+ * context (roadmap C8 of otel-ts). A later MINOR removes this export, when each app registers an SDK (D6).
+ */
 export function newTraceId(): string {
   const id = randomHex(16);
-  return id === ZERO_TRACE ? newTraceId() : id;
+  return isValidTraceId(id) ? id : newTraceId();
 }
 
-/** This function makes a new span id: 16 random hex digits. */
+/**
+ * This function makes a new span id: 16 random hex digits.
+ *
+ * @deprecated With an SDK of OpenTelemetry, the registered propagator writes and reads the trace
+ * context (roadmap C8 of otel-ts). A later MINOR removes this export, when each app registers an SDK (D6).
+ */
 export function newSpanId(): string {
   const id = randomHex(8);
-  return id === ZERO_SPAN ? newSpanId() : id;
+  return isValidSpanId(id) ? id : newSpanId();
 }
 
-/** True when the ids have the W3C form. */
+/**
+ * This function gives true when the ids have the W3C form.
+ *
+ * @deprecated With an SDK of OpenTelemetry, the registered propagator writes and reads the trace
+ * context (roadmap C8 of otel-ts). A later MINOR removes this export, when each app registers an SDK (D6).
+ */
 export function isW3cIds(traceId: string, spanId: string): boolean {
-  return /^[0-9a-f]{32}$/.test(traceId) && /^[0-9a-f]{16}$/.test(spanId) && traceId !== ZERO_TRACE && spanId !== ZERO_SPAN;
+  return isValidTraceId(traceId) && isValidSpanId(spanId) && !UPPERCASE_HEX.test(traceId) && !UPPERCASE_HEX.test(spanId);
 }
 
-/** The `traceparent` of a trace and a span. */
+/**
+ * This function gives the `traceparent` of a trace and a span.
+ *
+ * @deprecated With an SDK of OpenTelemetry, the registered propagator writes and reads the trace
+ * context (roadmap C8 of otel-ts). A later MINOR removes this export, when each app registers an SDK (D6).
+ */
 export function formatTraceparent(traceId: string, spanId: string, sampled = true): string {
   return `00-${traceId}-${spanId}-${sampled ? "01" : "00"}`;
 }
 
-/** The trace context of a `traceparent` value, or undefined when it is not valid. */
+/**
+ * This function gives the trace context of a `traceparent` value, or undefined when it is not valid.
+ *
+ * @deprecated With an SDK of OpenTelemetry, the registered propagator writes and reads the trace
+ * context (roadmap C8 of otel-ts). A later MINOR removes this export, when each app registers an SDK (D6).
+ */
 export function parseTraceparent(value: unknown): TraceContext | undefined {
   if (typeof value !== "string") return undefined;
   const match = TRACEPARENT.exec(value.trim().toLowerCase());
   if (!match) return undefined;
-  const [, traceId, spanId, flags] = match;
-  if (traceId === ZERO_TRACE || spanId === ZERO_SPAN) return undefined;
-  return { traceId: traceId!, spanId: spanId!, sampled: (parseInt(flags!, 16) & 1) === 1 };
+  const [, traceId = "", spanId = "", flags = ""] = match;
+  if (!isValidTraceId(traceId) || !isValidSpanId(spanId)) return undefined;
+  return { traceId, spanId, sampled: (parseInt(flags, 16) & 1) === 1 };
 }