@procedures/client 0.0.0-stage → 0.2.0

package/src/adapters/http/shared/constants.ts

@@ -0,0 +1,108 @@
+/**
+ * HTTP Constants
+ *
+ * Shared HTTP enums and constants used by both client and server adapters.
+ */
+
+/**
+ * HTTP Methods
+ */
+export enum HTTPMethod {
+  GET = "GET",
+  POST = "POST",
+  PUT = "PUT",
+  PATCH = "PATCH",
+  DELETE = "DELETE",
+  OPTIONS = "OPTIONS",
+  HEAD = "HEAD",
+}
+
+/**
+ * HTTP Status Codes
+ *
+ * Comprehensive enum of all standard HTTP status codes.
+ */
+export enum HTTPStatus {
+  // Unknown
+  UNKNOWN = 0,
+
+  // 1xx Informational
+  CONTINUE = 100,
+  SWITCHING_PROTOCOLS = 101,
+  PROCESSING = 102,
+  EARLY_HINTS = 103,
+  RESPONSE_IS_TOO_LARGE = 104,
+
+  // 2xx Success
+  OK = 200,
+  CREATED = 201,
+  ACCEPTED = 202,
+  NON_AUTHORITATIVE_INFORMATION = 203,
+  NO_CONTENT = 204,
+  RESET_CONTENT = 205,
+  PARTIAL_CONTENT = 206,
+  MULTI_STATUS = 207,
+  ALREADY_REPORTED = 208,
+  IM_USED = 226,
+
+  // 3xx Redirection
+  MULTIPLE_CHOICES = 300,
+  MOVED_PERMANENTLY = 301,
+  FOUND = 302,
+  SEE_OTHER = 303,
+  NOT_MODIFIED = 304,
+  USE_PROXY = 305,
+  TEMPORARY_REDIRECT = 307,
+  PERMANENT_REDIRECT = 308,
+
+  // 4xx Client Errors
+  BAD_REQUEST = 400,
+  UNAUTHORIZED = 401,
+  FORBIDDEN = 403,
+  NOT_FOUND = 404,
+  METHOD_NOT_ALLOWED = 405,
+  NOT_ACCEPTABLE = 406,
+  PROXY_AUTHENTICATION_REQUIRED = 407,
+  REQUEST_TIMEOUT = 408,
+  CONFLICT = 409,
+  GONE = 410,
+  LENGTH_REQUIRED = 411,
+  PRECONDITION_FAILED = 412,
+  PAYLOAD_TOO_LARGE = 413,
+  URI_TOO_LONG = 414,
+  UNSUPPORTED_MEDIA_TYPE = 415,
+  RANGE_NOT_SATISFIABLE = 416,
+  EXPECTATION_FAILED = 417,
+  IM_A_TEAPOT = 418,
+  MISDIRECTED_REQUEST = 421,
+  UNPROCESSABLE_ENTITY = 422,
+  LOCKED = 423,
+  FAILED_DEPENDENCY = 424,
+  TOO_EARLY = 425,
+  UPGRADE_REQUIRED = 426,
+  PRECONDITION_REQUIRED = 428,
+  TOO_MANY_REQUESTS = 429,
+  REQUEST_HEADER_FIELDS_TOO_LARGE = 431,
+  UNAVAILABLE_FOR_LEGAL_REASONS = 451,
+  CLIENT_CLOSED_REQUEST = 499,
+
+  // 5xx Server Errors
+  INTERNAL_SERVER_ERROR = 500,
+  NOT_IMPLEMENTED = 501,
+  BAD_GATEWAY = 502,
+  SERVICE_UNAVAILABLE = 503,
+  GATEWAY_TIMEOUT = 504,
+  HTTP_VERSION_NOT_SUPPORTED = 505,
+  VARIANT_ALSO_NEGOTIATES = 506,
+  INSUFFICIENT_STORAGE = 507,
+  LOOP_DETECTED = 508,
+  NOT_EXTENDED = 510,
+  NETWORK_AUTHENTICATION_REQUIRED = 511,
+  HTTP_NETWORK_CONNECT_TIMEOUT_ERROR = 599,
+}
+
+/**
+ * HTTP Transport Protocol Name
+ */
+export const HTTP = "HTTP" as const;
+export type HTTP = typeof HTTP;

package/src/adapters/http/shared/errors.ts

@@ -0,0 +1,199 @@
+/**
+ * HTTP Error Types
+ *
+ * Type-safe error codes and utilities for HTTP adapter errors.
+ * No more magic strings!
+ */
+
+import { HTTPStatus } from "./constants.js";
+import { formatHTTPError, getStatusCode, isRetryableStatus } from "./status-codes.js";
+
+/**
+ * HTTP Error Codes (Type-safe)
+ *
+ * Categorizes errors into semantic codes instead of magic strings.
+ */
+export enum HTTPErrorCode {
+  // Network errors
+  NETWORK_ERROR = "NETWORK_ERROR",
+  CONNECTION_REFUSED = "CONNECTION_REFUSED",
+  TIMEOUT = "TIMEOUT",
+  ABORTED = "ABORTED",
+
+  // HTTP errors (mapped from status codes)
+  HTTP_ERROR = "HTTP_ERROR",
+
+  // Parse/serialization errors
+  INVALID_RESPONSE = "INVALID_RESPONSE",
+  PARSE_ERROR = "PARSE_ERROR",
+  SERIALIZE_ERROR = "SERIALIZE_ERROR",
+
+  // Configuration errors
+  INVALID_URL = "INVALID_URL",
+  INVALID_METHOD = "INVALID_METHOD",
+
+  // Unknown
+  UNKNOWN = "UNKNOWN",
+}
+
+export const HTTPErrorMessage : Record<HTTPErrorCode, string> = {
+  [HTTPErrorCode.PARSE_ERROR] : "Failed to parse response",
+  [HTTPErrorCode.SERIALIZE_ERROR] : "Failed to serialize request",
+  [HTTPErrorCode.NETWORK_ERROR] : "Network error occurred",
+  [HTTPErrorCode.CONNECTION_REFUSED] : "Connection was refused by the server",
+  [HTTPErrorCode.TIMEOUT] : "Request timed out",
+  [HTTPErrorCode.ABORTED] : "Request was aborted",
+  [HTTPErrorCode.HTTP_ERROR] : "HTTP error occurred",
+  [HTTPErrorCode.INVALID_RESPONSE] : "Received invalid response from server",
+  [HTTPErrorCode.INVALID_URL] : "The provided URL is invalid",
+  [HTTPErrorCode.INVALID_METHOD] : "The provided HTTP method is invalid",
+  [HTTPErrorCode.UNKNOWN] : "An unknown error occurred",
+} as const satisfies Record<HTTPErrorCode, string>;
+
+/**
+ * HTTP Error Details
+ *
+ * Structured error information for HTTP transport errors.
+ */
+export interface HTTPErrorDetails {
+  /** Semantic error code */
+  code: HTTPErrorCode | string;
+
+  /** Human-readable error message */
+  message: string;
+
+  /** Whether this error is retryable */
+  retryable: boolean;
+
+  /** Optional HTTP status code (if applicable) */
+  status?: HTTPStatus;
+
+  /** Optional underlying cause */
+  cause?: Error | undefined;
+}
+
+/**
+ * Create HTTP error details from status code
+ */
+export function createHTTPStatusError(status: HTTPStatus): HTTPErrorDetails {
+  return {
+    code: getStatusCode(status),
+    message: formatHTTPError(status),
+    retryable: isRetryableStatus(status),
+    status,
+  };
+}
+
+/**
+ * Create network error details
+ */
+export function createNetworkError(
+  message: string,
+  cause?: Error
+): HTTPErrorDetails {
+  return {
+    code: HTTPErrorCode.NETWORK_ERROR,
+    message,
+    retryable: true,
+    ...(cause && { cause }),
+  };
+}
+
+/**
+ * Create timeout error details
+ */
+export function createTimeoutError(timeoutMs: number): HTTPErrorDetails {
+  return {
+    code: HTTPErrorCode.TIMEOUT,
+    message: `Request timed out after ${timeoutMs}ms`,
+    retryable: true,
+  };
+}
+
+/**
+ * Create abort error details: the caller aborted the request, so a retry must not repeat it.
+ * Before, an abort was a non-retryable HTTP_ERROR (deep dive TRN-7).
+ */
+export function createAbortError(): HTTPErrorDetails {
+  return {
+    code: HTTPErrorCode.ABORTED,
+    message: HTTPErrorMessage[HTTPErrorCode.ABORTED],
+    retryable: false,
+  };
+}
+
+// needs fixing
+export function createHTTPError(cause?: Error): HTTPErrorDetails {
+  return {
+    code: HTTPErrorCode.HTTP_ERROR,
+    message: cause?.message ?? HTTPErrorMessage[HTTPErrorCode.HTTP_ERROR],
+    retryable: false,
+    cause
+  };
+}
+
+/**
+ * Detect error type from Error object
+ *
+ * Inspects error name/message to categorize fetch errors.
+ *
+ * needs fixing
+ */
+export function categorizeError(error: Error): HTTPErrorCode {
+  const name = error.name?.toLowerCase() || "";
+  const message = error.message?.toLowerCase() || "";
+
+  if (name === "aborterror" || message.includes("abort")) {
+    return HTTPErrorCode.ABORTED;
+  }
+
+  if (
+    name === "timeouterror" ||
+    message.includes("timeout") ||
+    message.includes("timed out")
+  ) {
+    return HTTPErrorCode.TIMEOUT;
+  }
+
+  if (
+    message.includes("fetch") ||
+    message.includes("network") ||
+    message.includes("connection")
+  ) {
+    return HTTPErrorCode.NETWORK_ERROR;
+  }
+
+  if (message.includes("parse") || message.includes("json")) {
+    return HTTPErrorCode.PARSE_ERROR;
+  }
+
+  return HTTPErrorCode.UNKNOWN;
+}
+
+/**
+ * Create error details from generic Error
+ */
+export function createErrorFromException(error: Error): HTTPErrorDetails {
+  const code = categorizeError(error);
+
+  return {
+    code,
+    message: error.message,
+    retryable: code === HTTPErrorCode.NETWORK_ERROR || code === HTTPErrorCode.TIMEOUT,
+    cause: error,
+  };
+}
+
+/**
+ * Check if error code represents a retryable error
+ */
+export function isRetryableError(code: HTTPErrorCode | string): boolean {
+  switch (code) {
+    case HTTPErrorCode.NETWORK_ERROR:
+    case HTTPErrorCode.CONNECTION_REFUSED:
+    case HTTPErrorCode.TIMEOUT:
+      return true;
+    default:
+      return false;
+  }
+}

package/src/adapters/http/shared/headers.ts

@@ -0,0 +1,291 @@
+/**
+ * HTTP Header Utilities
+ *
+ * Provides constants for standard HTTP headers and utilities for
+ * converting between universal metadata and HTTP headers.
+ */
+
+import type { Metadata } from "../../../client/types.js";
+
+/**
+ * Standard HTTP Header Names
+ *
+ * Type-safe constants for commonly used HTTP headers.
+ * No more magic strings!
+ */
+export const HTTPHeaders = {
+  // Standard HTTP headers
+  CONTENT_TYPE: "Content-Type",
+  CONTENT_LENGTH: "Content-Length",
+  AUTHORIZATION: "Authorization",
+  USER_AGENT: "User-Agent",
+  ACCEPT: "Accept",
+  ACCEPT_ENCODING: "Accept-Encoding",
+  ACCEPT_LANGUAGE: "Accept-Language",
+  CACHE_CONTROL: "Cache-Control",
+  CONNECTION: "Connection",
+  HOST: "Host",
+  ORIGIN: "Origin",
+  REFERER: "Referer",
+
+  // Custom RPC headers
+  REQUEST_ID: "X-Request-Id",
+
+  // Authentication headers
+  API_KEY: "X-API-Key",
+
+  // Tracing headers (OpenTelemetry/Jaeger compatible)
+  TRACE_ID: "X-Trace-Id",
+  SPAN_ID: "X-Span-Id",
+  PARENT_SPAN_ID: "X-Parent-Span-Id",
+
+  // Timeout headers
+  TIMEOUT: "X-Timeout",
+
+  // The custom metadata of a request, as URI-encoded JSON (deep dive TRN-11)
+  METADATA: "X-Metadata",
+
+  // Server timing
+  SERVER_TIMING: "Server-Timing",
+} as const;
+
+/**
+ * Type for HTTP header names
+ */
+export type HTTPHeader = (typeof HTTPHeaders)[keyof typeof HTTPHeaders];
+
+/**
+ * Type for HTTP headers object
+ */
+export type HTTPHeadersMap = Record<string, string>;
+
+/**
+ * Header Converter Interface
+ *
+ * Defines the contract for converting between universal Metadata
+ * and protocol-specific HTTP headers.
+ *
+ * This abstraction allows:
+ * - Custom header naming conventions
+ * - Different authentication schemes
+ * - Multiple tracing formats
+ * - Extensible serialization strategies
+ */
+export interface HeaderConverter {
+  /**
+   * Convert universal metadata to HTTP headers
+   *
+   * @param metadata - Universal metadata
+   * @returns HTTP headers map
+   */
+  metadataToHeaders(metadata: Metadata): HTTPHeadersMap;
+
+  /**
+   * Convert HTTP headers to universal metadata
+   *
+   * @param headers - HTTP headers (Headers or plain object)
+   * @returns Universal metadata
+   */
+  headersToMetadata(headers: Headers | HTTPHeadersMap): Metadata;
+}
+
+/**
+ * Default Header Converter Implementation
+ *
+ * Implements standard conventions for converting metadata to headers:
+ * - Auth: Bearer token, API key
+ * - Tracing: X-Trace-Id, X-Span-Id format
+ * - Timeouts: X-Timeout header
+ * - Custom fields: Pass through as-is
+ */
+export class DefaultHeaderConverter implements HeaderConverter {
+  /**
+   * Custom fields: a string value with a header-safe key and a Latin-1 value also goes as its
+   * own header (for servers that read headers). Every custom field, of any JSON type, goes in
+   * the `X-Metadata` header. Before, only string values got through, and a non-Latin-1 value
+   * or a key with a space failed the call (deep dive TRN-11). Keys that start with "__" are
+   * internal to the process and never go.
+   *
+   * @throws an error with code METADATA_TOO_LARGE when `X-Metadata` is longer than
+   *   METADATA_HEADER_LIMIT characters
+   */
+  metadataToHeaders(metadata: Metadata): HTTPHeadersMap {
+    const headers: HTTPHeadersMap = {};
+
+    // Authentication
+    if (metadata.auth?.token) {
+      headers[HTTPHeaders.AUTHORIZATION] = `Bearer ${metadata.auth.token}`;
+    }
+    if (metadata.auth?.apiKey) {
+      headers[HTTPHeaders.API_KEY] = metadata.auth.apiKey;
+    }
+
+    // Distributed Tracing
+    if (metadata.tracing?.traceId) {
+      headers[HTTPHeaders.TRACE_ID] = metadata.tracing.traceId;
+    }
+    if (metadata.tracing?.spanId) {
+      headers[HTTPHeaders.SPAN_ID] = metadata.tracing.spanId;
+    }
+    if (metadata.tracing?.parentSpanId) {
+      headers[HTTPHeaders.PARENT_SPAN_ID] = metadata.tracing.parentSpanId;
+    }
+
+    // Timeouts
+    if (metadata.timeout?.overall) {
+      headers[HTTPHeaders.TIMEOUT] = String(metadata.timeout.overall);
+    }
+
+    const custom: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(metadata)) {
+      // Skip known structured fields and the internal keys
+      if (STRUCTURED_FIELDS.has(key) || key.startsWith("__") || value === undefined) {
+        continue;
+      }
+      custom[key] = value;
+      if (typeof value === "string" && HEADER_TOKEN.test(key) && LATIN1.test(value)) {
+        headers[key] = value;
+      }
+    }
+
+    if (Object.keys(custom).length > 0) {
+      const encoded = encodeURIComponent(JSON.stringify(custom));
+      if (encoded.length > METADATA_HEADER_LIMIT) {
+        throw Object.assign(
+          new Error(`The request metadata is too large for a header (${encoded.length} > ${METADATA_HEADER_LIMIT} characters)`),
+          { code: "METADATA_TOO_LARGE" },
+        );
+      }
+      headers[HTTPHeaders.METADATA] = encoded;
+    }
+
+    return headers;
+  }
+
+  headersToMetadata(headers: Headers | HTTPHeadersMap): Metadata {
+    const metadata: Metadata = {};
+
+    // Normalize to getter function
+    const get = (name: string): string | null => {
+      if (headers instanceof Headers) {
+        return headers.get(name);
+      }
+      return headers[name] ?? headers[name.toLowerCase()] ?? null;
+    };
+
+    // Extract tracing headers
+    const traceId = get(HTTPHeaders.TRACE_ID);
+    const spanId = get(HTTPHeaders.SPAN_ID);
+    const parentSpanId = get(HTTPHeaders.PARENT_SPAN_ID);
+
+    if (traceId || spanId) {
+      metadata.tracing = {
+        traceId: traceId || "",
+        spanId: spanId || "",
+        ...(parentSpanId && { parentSpanId }),
+      };
+    }
+
+    // Extract timing headers
+    const serverTiming = get(HTTPHeaders.SERVER_TIMING);
+    if (serverTiming) {
+      metadata["timing"] = serverTiming;
+    }
+
+    // Extract timeout
+    const timeout = get(HTTPHeaders.TIMEOUT);
+    if (timeout) {
+      const timeoutMs = parseInt(timeout, 10);
+      if (!isNaN(timeoutMs)) {
+        metadata.timeout = { overall: timeoutMs };
+      }
+    }
+
+    // Extract API key (but not Authorization - that's sensitive)
+    const apiKey = get(HTTPHeaders.API_KEY);
+    if (apiKey) {
+      metadata.auth = { apiKey };
+    }
+
+    return metadata;
+  }
+}
+
+/** The metadata fields that have their own headers, and the middleware state: not custom fields. */
+const STRUCTURED_FIELDS = new Set(["tracing", "auth", "timeout", "retry"]);
+
+/** A header name: the "token" characters of RFC 9110. */
+const HEADER_TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+
+/** A header value that fetch accepts: Latin-1, with no control characters but tab. */
+const LATIN1 = /^[\t\x20-\x7e\x80-\xff]*$/;
+
+/** The longest `X-Metadata` value, in characters. */
+export const METADATA_HEADER_LIMIT = 8192;
+
+/**
+ * This function reads the `X-Metadata` header: the custom metadata as an object, or undefined
+ * when the value is not URI-encoded JSON of an object.
+ */
+export function decodeMetadataHeader(value: string | undefined | null): Record<string, unknown> | undefined {
+  if (!value || value.length > METADATA_HEADER_LIMIT) return undefined;
+  try {
+    const decoded = JSON.parse(decodeURIComponent(value)) as unknown;
+    if (decoded === null || typeof decoded !== "object" || Array.isArray(decoded)) return undefined;
+    return decoded as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Create a default header converter instance
+ */
+export function createDefaultHeaderConverter(): HeaderConverter {
+  return new DefaultHeaderConverter();
+}
+
+/**
+ * Utility: Check if headers contain authentication
+ */
+export function hasAuthHeaders(headers: Headers | HTTPHeadersMap): boolean {
+  const get = (name: string): string | null => {
+    if (headers instanceof Headers) {
+      return headers.get(name);
+    }
+    return headers[name] ?? headers[name.toLowerCase()] ?? null;
+  };
+
+  return !!(get(HTTPHeaders.AUTHORIZATION) || get(HTTPHeaders.API_KEY));
+}
+
+/**
+ * Utility: Check if headers contain tracing information
+ */
+export function hasTracingHeaders(headers: Headers | HTTPHeadersMap): boolean {
+  const get = (name: string): string | null => {
+    if (headers instanceof Headers) {
+      return headers.get(name);
+    }
+    return headers[name] ?? headers[name.toLowerCase()] ?? null;
+  };
+
+  return !!(get(HTTPHeaders.TRACE_ID) || get(HTTPHeaders.SPAN_ID));
+}
+
+/**
+ * Utility: Extract request ID from headers
+ */
+export function getRequestId(headers: Headers | HTTPHeadersMap): string | null {
+  if (headers instanceof Headers) {
+    return headers.get(HTTPHeaders.REQUEST_ID);
+  }
+  return headers[HTTPHeaders.REQUEST_ID] ?? headers[HTTPHeaders.REQUEST_ID.toLowerCase()] ?? null;
+}
+
+/**
+ * Utility: Set request ID in headers
+ */
+export function setRequestId(headers: HTTPHeadersMap, requestId: string): void {
+  headers[HTTPHeaders.REQUEST_ID] = requestId;
+}

package/src/adapters/http/shared/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared HTTP Utilities
+ *
+ * Common constants, types, and utilities shared between
+ * client and server HTTP adapters.
+ */
+
+// Constants
+export * from "./constants.js";
+
+// Status Codes
+export * from "./status-codes.js";
+
+// Headers
+export * from "./headers.js";
+
+// Strategies
+export * from "./strategies.js";
+
+// Errors
+export * from "./errors.js";