@procedures/client 0.0.0-stage → 0.2.0

package/src/client/middleware/tracing.ts

@@ -0,0 +1,191 @@
+/**
+ * Tracing Middleware
+ *
+ * Adds distributed tracing metadata to requests.
+ * Works with ALL transports (HTTP, WebSocket, Local, Mock).
+ *
+ * Each transport converts metadata.tracing to its protocol format:
+ * - HTTP: X-Trace-Id, X-Span-Id, X-Parent-Span-Id headers
+ * - WebSocket: Frame metadata
+ * - Local: Passed directly to handler
+ *
+ * Compatible with OpenTelemetry, Jaeger, and custom tracing systems.
+ */
+
+import type { TypedClientMiddleware } from "../types.js";
+import type { TracingContext } from "./contexts.js";
+
+/**
+ * Tracing Configuration
+ */
+export interface TracingOptions {
+  /** Generate trace ID (default: auto-generate UUID) */
+  generateTraceId?: () => string;
+
+  /** Generate span ID (default: auto-generate UUID) */
+  generateSpanId?: () => string;
+
+  /** Get current trace context (for continuing existing traces) */
+  getCurrentTrace?: () => { traceId: string; spanId: string } | null;
+
+  /** Service name for tracing */
+  serviceName?: string;
+}
+
+/**
+ * Generate a simple unique ID (UUID v4 subset)
+ */
+function generateId(): string {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
+}
+
+/**
+ * Create tracing middleware
+ *
+ * Automatically adds tracing metadata to all requests.
+ * Supports both new traces and continuing existing traces.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const client = new Client({
+ *   transport: new HttpTransport({ baseUrl: "https://api.example.com" }),
+ *   middleware: [
+ *     createTracingMiddleware(),  // Auto-generates trace/span IDs
+ *     createRetryMiddleware({ maxAttempts: 3 }),
+ *   ]
+ * });
+ * ```
+ *
+ * @example Custom ID Generation
+ * ```typescript
+ * createTracingMiddleware({
+ *   generateTraceId: () => uuid.v4(),
+ *   generateSpanId: () => uuid.v4(),
+ * })
+ * ```
+ *
+ * @example Continuing Existing Trace
+ * ```typescript
+ * createTracingMiddleware({
+ *   getCurrentTrace: () => {
+ *     const trace = getActiveTrace();  // From your tracing library
+ *     return trace ? {
+ *       traceId: trace.traceId,
+ *       spanId: trace.spanId,
+ *     } : null;
+ *   }
+ * })
+ * ```
+ *
+ * @example OpenTelemetry Integration
+ * ```typescript
+ * import { trace } from "@opentelemetry/api";
+ *
+ * createTracingMiddleware({
+ *   getCurrentTrace: () => {
+ *     const span = trace.getActiveSpan();
+ *     if (!span) return null;
+ *
+ *     const spanContext = span.spanContext();
+ *     return {
+ *       traceId: spanContext.traceId,
+ *       spanId: spanContext.spanId,
+ *     };
+ *   }
+ * })
+ * ```
+ */
+export function createTracingMiddleware(
+  options: TracingOptions = {}
+): TypedClientMiddleware<TracingContext, {}> {
+  const {
+    generateTraceId = generateId,
+    generateSpanId = generateId,
+    getCurrentTrace,
+    serviceName,
+  } = options;
+
+  return (next) => async function* (context) {
+    // Check if there's already tracing metadata
+    if (!context.message.metadata.tracing) {
+      // Try to get current trace context
+      const currentTrace = getCurrentTrace?.();
+
+      if (currentTrace) {
+        // Continue existing trace (create child span)
+        context.message.metadata.tracing = {
+          traceId: currentTrace.traceId,
+          spanId: generateSpanId(),
+          parentSpanId: currentTrace.spanId,
+        };
+      } else {
+        // Start new trace
+        context.message.metadata.tracing = {
+          traceId: generateTraceId(),
+          spanId: generateSpanId(),
+        };
+      }
+
+      // Add service name if provided
+      if (serviceName) {
+        context.message.metadata["serviceName"] = serviceName;
+      }
+    }
+
+    // Continue middleware chain
+    yield* next(context);
+  };
+}
+
+/**
+ * Create simple tracing middleware with UUID generation
+ *
+ * Convenience wrapper that uses crypto.randomUUID() if available.
+ *
+ * @example
+ * ```typescript
+ * createSimpleTracingMiddleware()
+ * // Generates: traceId and spanId using crypto.randomUUID() or fallback
+ * ```
+ */
+export function createSimpleTracingMiddleware(): TypedClientMiddleware<TracingContext, {}> {
+  const hasRandomUUID = typeof crypto !== "undefined" && "randomUUID" in crypto;
+
+  return createTracingMiddleware({
+    generateTraceId: hasRandomUUID
+      ? () => crypto.randomUUID()
+      : generateId,
+    generateSpanId: hasRandomUUID
+      ? () => crypto.randomUUID()
+      : generateId,
+  });
+}
+
+/**
+ * Extract tracing info from response metadata
+ *
+ * Useful for logging or passing to other systems.
+ *
+ * @example
+ * ```typescript
+ * const response = await client.call(...);
+ * const tracing = extractTracingInfo(response.metadata);
+ * console.log(`Request completed: ${tracing.traceId}`);
+ * ```
+ */
+export function extractTracingInfo(metadata: Record<string, unknown>): {
+  traceId?: string;
+  spanId?: string;
+  parentSpanId?: string;
+} | null {
+  if (!metadata["tracing"] || typeof metadata["tracing"] !== "object") {
+    return null;
+  }
+
+  const tracing = metadata["tracing"] as Record<string, unknown>;
+  return {
+    ...(typeof tracing["traceId"] === "string" && { traceId: tracing["traceId"] }),
+    ...(typeof tracing["spanId"] === "string" && { spanId: tracing["spanId"] }),
+    ...(typeof tracing["parentSpanId"] === "string" && { parentSpanId: tracing["parentSpanId"] }),
+  };
+}

package/src/client/route-resolver.ts

@@ -0,0 +1,407 @@
+/**
+ * Route Resolver
+ *
+ * Resolves nested route structures to procedure definitions.
+ * Validates routes against the procedure registry.
+ */
+
+import type { AnyProcedure, ProcedurePath } from "../procedures/types.js";
+import type { ProcedureRegistry } from "../procedures/registry.js";
+import type { Route, RouteNode } from "./call-types.js";
+import type { OutputConfig } from "./consumption.js";
+import { flattenRoute } from "./call-types.js";
+import { validateSchema } from "../procedures/schema.js";
+
+// =============================================================================
+// Resolution Types
+// =============================================================================
+
+/**
+ * Resolved route entry with procedure and input.
+ */
+export interface ResolvedRoute {
+  /** Path to the procedure */
+  path: ProcedurePath;
+  /** The procedure definition */
+  procedure: AnyProcedure;
+  /** Input payload for the procedure handler (validated, with schema defaults) */
+  input: unknown;
+
+  /** How the caller reads the output: sponge (the default), stream or handlers (the `out` of the leaf) */
+  outputConfig: OutputConfig;
+
+  /**
+   * True when the resolver validated the input. A schema that validates asynchronously cannot
+   * be checked by the synchronous resolver: the invocation validates that input.
+   */
+  inputValidated?: boolean;
+}
+
+/**
+ * Resolution error for a specific path.
+ */
+export interface RouteResolutionError {
+  /** Path that failed to resolve */
+  path: ProcedurePath;
+  /** Error type */
+  type: "not_found" | "invalid_input" | "validation_error";
+  /** Error message */
+  message: string;
+}
+
+/**
+ * Result of route resolution.
+ */
+export interface RouteResolutionResult {
+  /** Successfully resolved routes */
+  resolved: ResolvedRoute[];
+  /** Errors encountered during resolution */
+  errors: RouteResolutionError[];
+  /**
+   * The routes that the resolver did not examine: it stopped at the first error. A caller
+   * reports each of them, so no leaf of the route is missing from the response (deep dive CORE-14).
+   */
+  skipped: ProcedurePath[];
+  /** Whether all routes resolved successfully */
+  success: boolean;
+}
+
+// =============================================================================
+// Route Resolver Class
+// =============================================================================
+
+/**
+ * Resolves nested route structures to procedures.
+ *
+ * Features:
+ * - Path-based procedure lookup
+ * - Input validation against schemas
+ * - Batch resolution for multi-route calls
+ * - Detailed error reporting
+ *
+ * @example
+ * ```typescript
+ * const resolver = new RouteResolver(registry);
+ *
+ * const result = resolver.resolve({
+ *   collections: {
+ *     users: {
+ *       get: { id: '123' }
+ *     }
+ *   }
+ * });
+ *
+ * if (result.success) {
+ *   for (const { path, procedure, input } of result.resolved) {
+ *     // Execute procedure with input
+ *   }
+ * }
+ * ```
+ */
+export class RouteResolver {
+  constructor(private readonly registry: ProcedureRegistry) {}
+
+  /**
+   * Resolve a route structure to procedures.
+   *
+   * @param route - Nested route object
+   * @param options - Resolution options
+   * @returns Resolution result with procedures or errors
+   */
+  resolve(
+    route: Route,
+    options: RouteResolverOptions = {}
+  ): RouteResolutionResult {
+    const flattened = flattenRoute(route);
+    const resolved: ResolvedRoute[] = [];
+    const errors: RouteResolutionError[] = [];
+    const skipped: ProcedurePath[] = [];
+
+    for (const [index, entry] of flattened.entries()) {
+      const { path, input, outputConfig } = entry;
+      const procedure = this.registry.get(path);
+
+      if (!procedure) {
+        errors.push({
+          path,
+          type: "not_found",
+          message: `No procedure registered at path: ${path.join(".")}`,
+        });
+        continue;
+      }
+
+      // Validate input if schema validation is enabled. The handler gets the validated data
+      // (with schema defaults), as in exec() and on the server - not the raw leaf, which for
+      // an { in, out } leaf is the whole wrapper (BUGS-2026-07 H31).
+      let handlerInput: unknown = input;
+      let inputValidated = false;
+      const validationResult = options.validateInput !== false ? validateSchema(procedure.input, input) : undefined;
+      if (validationResult && !(validationResult instanceof Promise)) {
+        if (!validationResult.ok) {
+          errors.push({
+            path,
+            type: "validation_error",
+            message: `Input validation failed: ${validationResult.message}`,
+          });
+
+          if (!options.continueOnError) {
+            skipped.push(...flattened.slice(index + 1).map((rest) => rest.path));
+            break;
+          }
+          continue;
+        }
+        handlerInput = validationResult.value;
+        inputValidated = true;
+      }
+
+      resolved.push({
+        path,
+        procedure,
+        input: handlerInput,
+        outputConfig,
+        inputValidated,
+      });
+    }
+
+    return {
+      resolved,
+      errors,
+      skipped,
+      success: errors.length === 0,
+    };
+  }
+
+  /**
+   * Resolve a single path to a procedure.
+   *
+   * @param path - Procedure path
+   * @returns Procedure or undefined if not found
+   */
+  getProcedure(path: ProcedurePath): AnyProcedure | undefined {
+    return this.registry.get(path);
+  }
+
+  /**
+   * Check if a path resolves to a valid procedure.
+   *
+   * @param path - Procedure path
+   * @returns true if procedure exists at path
+   */
+  hasProcedure(path: ProcedurePath): boolean {
+    return this.registry.has(path);
+  }
+
+  /**
+   * Validate route structure without resolving.
+   * Useful for compile-time or early validation.
+   *
+   * @param route - Route to validate
+   * @returns Validation errors or empty array if valid
+   */
+  validate(route: Route): RouteResolutionError[] {
+    const flattened = flattenRoute(route);
+    const errors: RouteResolutionError[] = [];
+
+    for (const entry of flattened) {
+      const { path, input } = entry;
+      const procedure = this.registry.get(path);
+
+      if (!procedure) {
+        errors.push({
+          path,
+          type: "not_found",
+          message: `No procedure registered at path: ${path.join(".")}`,
+        });
+        continue;
+      }
+
+      const validationResult = validateSchema(procedure.input, input);
+      // An asynchronous schema is checked when the procedure runs
+      if (!(validationResult instanceof Promise) && !validationResult.ok) {
+        errors.push({
+          path,
+          type: "validation_error",
+          message: `Input validation failed: ${validationResult.message}`,
+        });
+      }
+    }
+
+    return errors;
+  }
+
+  /**
+   * Get all procedures that would be invoked by a route.
+   * Does not validate inputs.
+   *
+   * @param route - Route structure
+   * @returns Array of [path, procedure] tuples for found procedures
+   */
+  getProceduresForRoute(route: Route): Array<[ProcedurePath, AnyProcedure]> {
+    const flattened = flattenRoute(route);
+    const results: Array<[ProcedurePath, AnyProcedure]> = [];
+
+    for (const entry of flattened) {
+      const procedure = this.registry.get(entry.path);
+      if (procedure) {
+        results.push([entry.path, procedure]);
+      }
+    }
+
+    return results;
+  }
+}
+
+/**
+ * Options for route resolution.
+ */
+export interface RouteResolverOptions {
+  /** Whether to validate input against schemas (default: true) */
+  validateInput?: boolean;
+  /** Continue resolving even if some routes fail (default: false) */
+  continueOnError?: boolean;
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Create a route resolver for a registry.
+ *
+ * @param registry - Procedure registry
+ * @returns Route resolver instance
+ */
+export function createRouteResolver(registry: ProcedureRegistry): RouteResolver {
+  return new RouteResolver(registry);
+}
+
+/**
+ * Quickly validate a route against a registry.
+ *
+ * @param route - Route to validate
+ * @param registry - Procedure registry
+ * @returns true if all paths in route are valid procedures
+ */
+export function isValidRoute(route: Route, registry: ProcedureRegistry): boolean {
+  const flattened = flattenRoute(route);
+
+  for (const entry of flattened) {
+    if (!registry.has(entry.path)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Get missing paths from a route.
+ *
+ * @param route - Route to check
+ * @param registry - Procedure registry
+ * @returns Array of paths not found in registry
+ */
+export function getMissingPaths(
+  route: Route,
+  registry: ProcedureRegistry
+): ProcedurePath[] {
+  const flattened = flattenRoute(route);
+  const missing: ProcedurePath[] = [];
+
+  for (const entry of flattened) {
+    if (!registry.has(entry.path)) {
+      missing.push(entry.path);
+    }
+  }
+
+  return missing;
+}
+
+// =============================================================================
+// Path Matching Utilities
+// =============================================================================
+
+/**
+ * Check if a path matches a pattern with wildcards.
+ * Supports '*' for single segment and '**' for multiple segments.
+ *
+ * @param path - Path to check
+ * @param pattern - Pattern to match against
+ * @returns true if path matches pattern
+ *
+ * @example
+ * ```typescript
+ * matchPath(['users', 'get'], ['users', '*']);     // true
+ * matchPath(['users', 'orders', 'list'], ['users', '**']); // true
+ * ```
+ */
+export function matchPath(path: ProcedurePath, pattern: ProcedurePath): boolean {
+  let pathIndex = 0;
+  let patternIndex = 0;
+
+  while (patternIndex < pattern.length) {
+    const segment = pattern[patternIndex];
+
+    if (segment === "**") {
+      // Match rest of path
+      if (patternIndex === pattern.length - 1) {
+        return true;
+      }
+      // Try to match remaining pattern at each position
+      for (let i = pathIndex; i <= path.length; i++) {
+        if (matchPath(path.slice(i), pattern.slice(patternIndex + 1))) {
+          return true;
+        }
+      }
+      return false;
+    }
+
+    if (pathIndex >= path.length) {
+      return false;
+    }
+
+    if (segment === "*" || segment === path[pathIndex]) {
+      pathIndex++;
+      patternIndex++;
+    } else {
+      return false;
+    }
+  }
+
+  return pathIndex === path.length;
+}
+
+/**
+ * Filter routes by path pattern.
+ *
+ * @param route - Route to filter
+ * @param pattern - Pattern to match
+ * @returns Route with only matching paths
+ */
+export function filterRouteByPattern(route: Route, pattern: ProcedurePath): Route {
+  const flattened = flattenRoute(route);
+  const filtered: Route = {};
+
+  for (const entry of flattened) {
+    if (matchPath(entry.path, pattern)) {
+      // Rebuild nested structure for this path
+      let current: RouteNode = filtered;
+      for (let i = 0; i < entry.path.length; i++) {
+        const segment = entry.path[i]!;
+        const isLast = i === entry.path.length - 1;
+
+        if (isLast) {
+          current[segment] = entry.leaf;
+        } else {
+          // An own key only (deep dive CORE-6). flattenRoute rejected the prototype keys.
+          if (!Object.hasOwn(current, segment)) {
+            current[segment] = {};
+          }
+          current = current[segment] as RouteNode;
+        }
+      }
+    }
+  }
+
+  return filtered;
+}

package/src/client/typed-method.ts

@@ -0,0 +1,65 @@
+/**
+ * Type-safe Method construction from procedure registry
+ *
+ * This ensures that Method objects can only be created with valid
+ * service/operation combinations that exist in the registry.
+ */
+
+import type { Method } from './types.js';
+
+/**
+ * Generic typed method that constrains service and operation
+ * to values that exist in a procedure registry
+ */
+export interface TypedMethod<
+  TRegistry extends Record<string, Record<string, any>>,
+  TService extends keyof TRegistry & string = keyof TRegistry & string,
+  TOperation extends keyof TRegistry[TService] & string = keyof TRegistry[TService] & string
+> extends Method {
+  service: TService;
+  operation: TOperation;
+}
+
+/**
+ * Create a type-safe method object
+ *
+ * Usage:
+ * const method = createMethod<ProcedureRegistry>('collections', 'getDocuments');
+ * // Autocomplete for both service and operation!
+ * // Compile error if service or operation doesn't exist
+ */
+export function createMethod<
+  TRegistry extends Record<string, Record<string, any>>,
+  TService extends keyof TRegistry & string,
+  TOperation extends keyof TRegistry[TService] & string
+>(
+  service: TService,
+  operation: TOperation,
+  version?: string
+): TypedMethod<TRegistry, TService, TOperation> {
+  const method: TypedMethod<TRegistry, TService, TOperation> = {
+    service,
+    operation,
+  };
+  if (version !== undefined) {
+    method.version = version;
+  }
+  return method;
+}
+
+/**
+ * Type guard to check if a Method matches the registry
+ */
+export function isValidMethod<TRegistry extends Record<string, Record<string, any>>>(
+  method: Method,
+  registry: TRegistry
+): method is TypedMethod<TRegistry> {
+  const service = registry[method.service];
+  return (
+    typeof method.service === 'string' &&
+    method.service in registry &&
+    typeof method.operation === 'string' &&
+    service !== undefined &&
+    method.operation in service
+  );
+}