@procedures/client 0.0.0-stage → 0.1.0

package/src/adapters/websocket/server/types.ts

@@ -0,0 +1,169 @@
+/**
+ * WebSocket Server Transport Types
+ *
+ * Type definitions for WebSocket server adapter.
+ */
+
+import type { IncomingMessage } from "http";
+import type { Server as HttpServer } from "http";
+import type { WebSocket } from "ws";
+import type { BrowserGuardOptions } from "../../../server/browser-guard.js";
+
+/**
+ * WebSocket authentication handler.
+ * Called during WebSocket upgrade to authenticate the connection.
+ */
+export type WebSocketAuthHandler = (
+  req: IncomingMessage
+) => Promise<boolean> | boolean;
+
+/**
+ * WebSocket connection handler.
+ * Called when a new WebSocket connection is established.
+ */
+export type WebSocketConnectionHandler = (ws: WebSocket, req: IncomingMessage) => void;
+
+/**
+ * WebSocket server transport options.
+ */
+export interface WebSocketServerTransportOptions extends Omit<BrowserGuardOptions, "allowGet"> {
+  /**
+   * HTTP server to attach WebSocket server to.
+   * Required - WebSocket upgrades HTTP connections.
+   */
+  server: HttpServer;
+
+  /**
+   * Path for WebSocket connections.
+   * @default "/ws"
+   */
+  path?: string;
+
+  /**
+   * Authentication handler for WebSocket upgrade.
+   * Return true to allow connection, false to reject. It runs after the browser checks of the
+   * host and the origin (`allowedHosts`, `allowedOrigins`), which are always on.
+   */
+  authenticate?: WebSocketAuthHandler;
+
+  /**
+   * Connection handler called when client connects.
+   */
+  onConnection?: WebSocketConnectionHandler;
+
+  /**
+   * Enable per-message compression.
+   * @default false
+   */
+  perMessageDeflate?: boolean;
+
+  /**
+   * Maximum message size in bytes.
+   * @default 1MB
+   */
+  maxPayload?: number;
+
+  /**
+   * Client tracking - track connected clients.
+   * @default true
+   */
+  clientTracking?: boolean;
+
+  /**
+   * The number of bytes that a connection can hold in its send buffer before a stream waits
+   * (deep dive TRN-3: before, a stream ran to its end whatever the reader did).
+   * @default 1 MiB
+   */
+  highWaterMark?: number;
+}
+
+/**
+ * WebSocket message format for RPC.
+ */
+export interface WebSocketMessage<TReq = unknown> {
+  /** Message ID for request/response matching */
+  id: string;
+
+  /** Message type */
+  type: "request" | "response" | "error" | "stream" | "cancel" | "credit" | "ping" | "pong" | "server-request" | "server-response" | "event";
+
+  /** RPC method (for requests) */
+  method?: {
+    service: string;
+    operation: string;
+    version?: string;
+  };
+
+  /** Procedure path (for server-request) */
+  path?: string[];
+
+  /** Input data (for server-request) */
+  input?: unknown;
+
+  /** Result data (for server-response) */
+  result?: unknown;
+
+  /** Message payload */
+  payload?: TReq;
+
+  /** Metadata (headers, auth, etc.) */
+  metadata?: Record<string, unknown>;
+
+  /** Status (for responses) */
+  status?: {
+    type: "success" | "error";
+    code: string | number;
+    message?: string;
+    retryable?: boolean;
+  };
+
+  /** Error details (for error messages) */
+  error?: {
+    code: string | number;
+    message: string;
+    retryable?: boolean;
+  };
+
+  /**
+   * Flow control of a stream (deep dive TRN-3). In a request: the number of stream items that
+   * the client can take before it sends more credit. In a "credit" message: the number of more
+   * items. A request without credit gets its stream with no limit (the old protocol).
+   */
+  credit?: number;
+
+  /** Stream indicator (for streaming responses) */
+  stream?: {
+    /** Is this the last message in the stream? */
+    done: boolean;
+  };
+
+  /** Topic (for event messages) */
+  topic?: string;
+
+  /** Data (for event messages) */
+  data?: unknown;
+
+  /** Subscription ID (for event messages) */
+  subscriptionId?: string;
+}
+
+/**
+ * Tracked connection with ID for bidirectional communication.
+ */
+export interface TrackedConnection {
+  /** Unique connection ID */
+  id: string;
+  /** WebSocket instance */
+  socket: WebSocket;
+  /** When the connection was established */
+  connectedAt: Date;
+  /** Connection metadata */
+  metadata: Record<string, unknown>;
+  /** Available procedures on this connection (discovered) */
+  procedures?: string[];
+}
+
+/**
+ * Connection event handler.
+ */
+export type ConnectionEventHandler = (connection: TrackedConnection) => void;

package/src/browser.ts

@@ -0,0 +1,373 @@
+/**
+ * Universal Client Library: the browser-safe entry point.
+ *
+ * This module exports everything of the package except the Node server transports
+ * (`HttpServerTransport` and `WebSocketServerTransport`, which use `http` and `ws`).
+ * A browser bundle imports "@procedures/client/browser". The root entry point
+ * re-exports this module and adds the server transports.
+ *
+ * Collections (maps, caches, collection storage) are in @procedures/collections.
+ * The program store, the storage backends that need a Client (ApiStorage, HybridStorage) and the
+ * synced registry are in @procedures/store (roadmap 3.2).
+ */
+
+// ============================================================================
+// Universal Client (protocol-agnostic RPC)
+// Core client and transports
+// Import client middleware explicitly: import { createRetryMiddleware } from "@procedures/client/client"
+// ============================================================================
+export { Client, ClientError } from "./client/index.js";
+export {
+  HttpTransport,
+  LocalTransport,
+  WebSocketTransport,
+  MockTransport,
+  mockBuilder,
+} from "./client/index.js";
+export {
+  defaultUrlPattern,
+  restfulHttpMethodStrategy,
+  postOnlyStrategy,
+} from "./client/index.js";
+export type {
+  Transport,
+  Method,
+  Metadata,
+  Message,
+  ResponseItem,
+  Status,
+  ClientContext,
+  ClientRunner,
+  ClientMiddleware,
+  ClientOptions,
+  HttpTransportOptions,
+  UrlStrategy,
+  HttpMethodStrategy,
+  LocalTransportOptions,
+  Handler,
+  WebSocketTransportOptions,
+  MockTransportOptions,
+  MockResponse,
+  ResponseMatcher,
+  CallHistoryEntry,
+} from "./client/index.js";
+
+// WebSocketState is a runtime enum, not just a type — export as a value so consumers can compare
+// against WebSocketState.CONNECTED etc. See documentation/BUGS-2026-07.md (L1).
+export { WebSocketState } from "./client/index.js";
+
+// Error system
+export type { ErrorMetadata, ErrorRegistry, ErrorContext, RichError } from "./client/index.js";
+export { ErrorSeverity, ErrorCategory } from "./client/index.js";
+export {
+  ERROR_REGISTRY,
+  getErrorMetadata,
+  isKnownError,
+  createError,
+  createErrorFromHTTPStatus,
+  createErrorFromException,
+  formatError,
+} from "./client/index.js";
+
+// ============================================================================
+// Universal Server (protocol-agnostic RPC)
+// The server transports are Node only: the root entry point exports them.
+// ============================================================================
+export { Server } from "./server/server.js";
+export type { ServerOptions } from "./server/server.js";
+export { ProcedureServer, createProcedureServer } from "./server/procedure-server.js";
+export type { ProcedureServerOptions, StorageConfig } from "./server/procedure-server.js";
+export {
+  HandlerNotFoundError,
+  ServerError,
+} from "./server/types.js";
+export { pathToMethod, methodToPath } from "./server/method.js";
+export type {
+  ServerRequest,
+  ServerResponse,
+  ServerHandler,
+  ServerMiddleware,
+  ServerContext,
+  ServerRunner,
+  ServerTransport,
+} from "./server/types.js";
+
+// ============================================================================
+// Procedure System - Type-safe RPC with auto-discovery
+// ============================================================================
+export {
+  defineProcedure,
+  defineStub,
+  createProcedure,
+  ProcedureBuilder,
+  namespace,
+  validateProcedure,
+  ProcedureRegistry,
+  RegistryError,
+  PROCEDURE_REGISTRY,
+  assertValidPath,
+  pathToKey,
+  keyToPath,
+  createCollectionProcedures,
+  // Manual registration helpers
+  registerModule,
+  registerProcedures,
+  createAndRegister,
+  // Modules and explicit registries (roadmap 3.1)
+  clientModule,
+  defineModule,
+  moduleClosure,
+  registerModules,
+  createRegistry,
+  // Procedure reference system (procedure-as-data)
+  PROCEDURE_SYMBOL,
+  PROCEDURE_JSON_KEY,
+  PROCEDURE_WHEN_KEY,
+  PROCEDURE_NAME_KEY,
+  WHEN_IMMEDIATE,
+  WHEN_NEVER,
+  WHEN_PARENT,
+  isProcedureRef,
+  isProcedureRefJson,
+  isAnyProcedureRef,
+  getRefWhen,
+  getRefName,
+  shouldExecuteRef,
+  proc,
+  ProcedureRefBuilder,
+  fromJson,
+  toJson,
+  normalizeRef,
+  hydrateInput,
+  prepareRootCall,
+  observeHydration,
+  isControlFlowPath,
+  isDataDriven,
+  markDataDriven,
+  RUNS_REFS_TAG,
+  RAW_INPUT_TAG,
+  takesRawInput,
+  rawInputRule,
+  MAX_DATA_DEPTH,
+  LITERAL_KEY,
+  isLiteral,
+  isPlainObject,
+  createRefScope,
+  lookupOutputRef,
+  resolveOutputRef,
+  withScope,
+  scopeOf,
+  executeRef,
+  extractTemplate,
+  parseProcedureJson,
+  stringifyProcedureJson,
+  // Core language procedures
+  coreProcedures,
+  coreModule,
+  // Every core procedure (math, comparison, string, type, object, array, meta too). Not registered by default.
+  allCoreProcedures,
+  allCoreModules,
+  chainProcedure,
+  parallelProcedure,
+  conditionalProcedure,
+  andProcedure,
+  orProcedure,
+  notProcedure,
+  allProcedure,
+  anyProcedure,
+  noneProcedure,
+  mapProcedure,
+  reduceProcedure,
+  identityProcedure,
+  constantProcedure,
+  throwProcedure,
+  tryCatchProcedure,
+  // Common schemas
+  anySchema,
+  typedAnySchema,
+  zodAdapter,
+  outputSchema,
+  // Meta-procedures for runtime definition
+  defineProcedureProcedure,
+  getProcedureProcedure,
+  listProceduresProcedure,
+  deleteProcedureProcedure,
+  metaProcedures,
+  getRuntimeProcedure,
+  hasRuntimeProcedure,
+  getAllRuntimeProcedures,
+  clearRuntimeProcedures,
+  isRuntimeDefined,
+  runtimeProgramOf,
+} from "./procedures/index.js";
+
+export type {
+  Procedure,
+  AnyProcedure,
+  ProcedurePath,
+  ProcedureMetadata,
+  ProcedureHandler,
+  ProcedureContext,
+  ProcedureResult,
+  ProcedureError,
+  RepositoryProvider,
+  CollectionStorage,
+  StorageMetadata,
+  ProcedureModule,
+  ModuleInput,
+  RegistrationOptions,
+  ProcedureRegistryLike,
+  ProcedureDefinition,
+  ProcedureStub,
+  InferProcedureInput,
+  InferProcedureOutput,
+  InferProcedureMetadata,
+  RegistryEventType,
+  RegistryListener,
+  // Procedure reference types (procedure-as-data)
+  ProcedureWhen,
+  ProcedureRef,
+  ProcedureRefJson,
+  AnyProcedureRef,
+  RefExecutor,
+  HydrateOptions,
+  HydrationEvent,
+  StepResultInfo,
+  ContinueDecision,
+  OutputRef,
+  RefScope,
+  // Schema types
+  ZodLikeSchema,
+  // Meta-procedure types
+  AggregationDefinition,
+  DefineProcedureInput,
+  DefineProcedureOutput,
+} from "./procedures/index.js";
+
+// ============================================================================
+// Invocation: the one path, the call policy and the interceptors
+// (ARCHITECTURE-PROPOSALS P1, deep dive MCP-3, roadmap 1.2)
+// ============================================================================
+export {
+  invokeProcedure,
+  invokePath,
+  outputValue,
+  outputItems,
+  streamOutput,
+  InvocationError,
+  isAsyncIterable,
+} from "./procedures/invoke.js";
+export type {
+  InvokeOptions,
+  ProcedureOutput,
+  InvocationErrorCode,
+  Invocation,
+  InvocationChanges,
+  InvocationNext,
+  Interceptor,
+} from "./procedures/invoke.js";
+export { callMatches, validateCalls, declaredCalls, nestedCallRefusal, hasCallPolicy, hiddenReach } from "./procedures/policy.js";
+export type { CallPolicy, CallRefusal, HiddenCall } from "./procedures/policy.js";
+export { timeoutInterceptor, tracingInterceptor, metricsInterceptor } from "./procedures/interceptors.js";
+export type {
+  TimeoutInterceptorOptions,
+  TracingInterceptorOptions,
+  InvocationSpan,
+  ProcedureMetrics,
+  MetricsInterceptor,
+} from "./procedures/interceptors.js";
+
+// The policy of a host (roadmap 2.3): one builder for the MCP server, the server CLI and mark
+export { hostPolicy, procedureServerOptions, exposePatterns, surfaceRule } from "./server/host-policy.js";
+export type { HostPolicy, HostPolicyOptions, ToolSurface } from "./server/host-policy.js";
+
+// ============================================================================
+// Nested Route API - Batch calls with per-call middleware overrides
+// ============================================================================
+export type {
+  Route,
+  RouteNode,
+  RouteLeaf,
+  CallRequest,
+  SingleCallRequest,
+  CallResponse,
+  ProcedureCallResult,
+  StreamingCallResponse,
+  BatchConfig,
+  BatchStrategy,
+  StreamConfig,
+  MiddlewareOverrides,
+  RetryOverride,
+  TimeoutOverride,
+  CacheOverride,
+} from "./client/call-types.js";
+
+export {
+  flattenRoute,
+  buildResponse,
+  createRoute,
+  mergeRoutes,
+  isBatchRoute,
+} from "./client/call-types.js";
+
+export { RouteResolver, createRouteResolver, isValidRoute, getMissingPaths, matchPath } from "./client/route-resolver.js";
+export type { ResolvedRoute, RouteResolutionResult, RouteResolutionError } from "./client/route-resolver.js";
+
+export { BatchExecutor, createBatchExecutor, Semaphore, executeWithConcurrency } from "./client/batch-executor.js";
+export type { ProcedureExecutor, ExecutionContext, BatchExecutionResult, BatchItem } from "./client/batch-executor.js";
+
+// ============================================================================
+// Events System - Pub/sub messaging and streaming coordination
+// ============================================================================
+export {
+  DefaultEventBus as EventBus,
+  createEventBus,
+  createTypedEventBus,
+  getGlobalEventBus,
+  withEventBusSignal,
+} from "./events/index.js";
+export type {
+  EventBus as IEventBus,
+  TypedEventBus,
+  EventHandler,
+  EventBusOptions,
+  EventWaitOptions,
+  ChannelMap,
+} from "./events/index.js";
+
+// ============================================================================
+// Components (serializable UI descriptors) moved to @procedures/splay, the UI package
+// of the ecosystem (roadmap 3.4).
+// ============================================================================
+
+// ============================================================================
+// Note: The unified middleware system (./middleware) is a foundation used by both
+// collections and universal client. Access it directly:
+// import { AsyncMiddleware, SyncMiddleware } from "client/middleware"
+//
+// Note: Universal client middleware is available for explicit import:
+// import { createRetryMiddleware } from "client/client"
+// import { createCacheMiddleware } from "client/client"
+// etc.
+// ============================================================================
+
+// ============================================================================
+// Schemas: Standard Schema v1, validation and JSON Schema (roadmap 2.1)
+// ============================================================================
+export {
+  validateSchema,
+  validateSchemaAsync,
+  jsonSchemaOf,
+  isStandardSchema,
+  describeIssues,
+} from "./procedures/index.js";
+export type {
+  StandardSchemaV1,
+  StandardJSONSchemaConverter,
+  ProcedureSchema,
+  InferSchema,
+  SchemaResult,
+  JsonSchema,
+  JsonSchemaTarget,
+  JsonSchemaSource,
+} from "./procedures/index.js";