@procedures/client 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,235 @@
+/**
+ * WebSocket Client Transport Types
+ *
+ * Type definitions for WebSocket client adapter.
+ */
+
+/**
+ * WebSocket client transport options.
+ */
+export interface WebSocketTransportOptions {
+  /**
+   * WebSocket URL to connect to.
+   * @example "ws://localhost:3000/ws" or "wss://api.example.com/ws"
+   */
+  url: string;
+
+  /**
+   * Reconnection options.
+   */
+  reconnect?: {
+    /**
+     * Enable automatic reconnection.
+     * @default true
+     */
+    enabled?: boolean;
+
+    /**
+     * Maximum number of reconnection attempts.
+     * @default Infinity
+     */
+    maxAttempts?: number;
+
+    /**
+     * Initial delay before reconnecting (ms).
+     * @default 1000
+     */
+    initialDelay?: number;
+
+    /**
+     * Maximum delay between reconnection attempts (ms).
+     * @default 30000
+     */
+    maxDelay?: number;
+
+    /**
+     * Backoff multiplier for reconnection delay.
+     * @default 1.5
+     */
+    backoffMultiplier?: number;
+  };
+
+  /**
+   * Connection timeout (ms): how long to wait for the WebSocket to open.
+   * @default 10000
+   */
+  connectionTimeout?: number;
+
+  /**
+   * Request timeout (ms): how long to wait for the response to one request.
+   * (Before, requests used connectionTimeout, so every call was capped at 10s.)
+   * @default 30000
+   */
+  requestTimeout?: number;
+
+  /**
+   * The number of stream items that the transport holds for a reader that has not taken them.
+   * The server sends no more items until the reader takes some (deep dive TRN-3).
+   * @default 64
+   */
+  streamWindow?: number;
+
+  /**
+   * Heartbeat options for keeping connection alive.
+   */
+  heartbeat?: {
+    /**
+     * Enable heartbeat.
+     * @default true
+     */
+    enabled?: boolean;
+
+    /**
+     * Heartbeat interval (ms).
+     * @default 30000
+     */
+    interval?: number;
+
+    /**
+     * Heartbeat timeout (ms).
+     * @default 5000
+     */
+    timeout?: number;
+  };
+
+  /**
+   * Callback when connection is established.
+   */
+  onConnect?: () => void;
+
+  /**
+   * Callback when connection is lost.
+   */
+  onDisconnect?: (reason?: string) => void;
+
+  /**
+   * Callback when reconnecting.
+   */
+  onReconnecting?: (attempt: number) => void;
+
+  /**
+   * Callback on connection error.
+   */
+  onError?: (error: Error) => void;
+
+  /**
+   * Handler for server-initiated procedure calls.
+   * Called when the server wants to call a procedure on this client.
+   */
+  onServerRequest?: ServerRequestHandler;
+
+  /**
+   * Handler for subscription events.
+   * Called when the server pushes an event to a subscribed topic.
+   */
+  onEvent?: EventHandler;
+}
+
+/**
+ * WebSocket connection state.
+ */
+export enum WebSocketState {
+  CONNECTING = "CONNECTING",
+  CONNECTED = "CONNECTED",
+  DISCONNECTING = "DISCONNECTING",
+  DISCONNECTED = "DISCONNECTED",
+  RECONNECTING = "RECONNECTING",
+}
+
+/**
+ * WebSocket message format for RPC.
+ */
+export interface WebSocketMessage<T = 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?: T;
+
+  /** Metadata (headers, auth, etc.) */
+  metadata?: Record<string, unknown>;
+
+  /** Error details (for error messages) */
+  error?: {
+    code: string | number;
+    message: string;
+    retryable?: boolean;
+  };
+
+  /** Status (for responses) */
+  status?: {
+    type: "success" | "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;
+}
+
+/**
+ * Server request message (server-initiated procedure call).
+ */
+export interface ServerRequestMessage {
+  id: string;
+  type: "server-request";
+  path: string[];
+  input?: unknown;
+}
+
+/**
+ * Handler for server-initiated procedure calls.
+ * Should return the result of executing the procedure.
+ */
+export type ServerRequestHandler = (
+  path: string[],
+  input: unknown
+) => Promise<unknown>;
+
+/**
+ * Handler for subscription events.
+ */
+export type EventHandler = (
+  topic: string,
+  data: unknown,
+  subscriptionId: string
+) => void;

package/src/adapters/websocket/index.ts

@@ -0,0 +1,24 @@
+/**
+ * WebSocket Adapter - Complete WebSocket transport layer
+ */
+
+// Client
+export { WebSocketTransport, WebSocketState } from "./client/index.js";
+export type {
+  WebSocketTransportOptions,
+  WebSocketMessage as ClientWebSocketMessage,
+  ServerRequestMessage,
+  ServerRequestHandler,
+  EventHandler,
+} from "./client/index.js";
+
+// Server
+export { WebSocketServerTransport } from "./server/index.js";
+export type {
+  WebSocketServerTransportOptions,
+  WebSocketAuthHandler,
+  WebSocketConnectionHandler,
+  WebSocketMessage as ServerWebSocketMessage,
+  TrackedConnection,
+  ConnectionEventHandler,
+} from "./server/index.js";

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

@@ -0,0 +1,18 @@
+/**
+ * WebSocket Server Transport Adapter
+ *
+ * Public API for WebSocket server adapter.
+ */
+
+// Types
+export type {
+  WebSocketAuthHandler,
+  WebSocketConnectionHandler,
+  WebSocketServerTransportOptions,
+  WebSocketMessage,
+  TrackedConnection,
+  ConnectionEventHandler,
+} from "./types.js";
+
+// Transport
+export { WebSocketServerTransport } from "./transport.js";