@durable-streams/server 0.1.1 → 0.1.2

package/dist/index.d.cts

@@ -0,0 +1,494 @@
+//#region src/types.d.ts
+/**
+* Types for the in-memory durable streams test server.
+*/
+/**
+* A single message in a stream.
+*/
+interface StreamMessage {
+  /**
+  * The raw bytes of the message.
+  */
+  data: Uint8Array;
+  /**
+  * The offset after this message.
+  * Format: "<read-seq>_<byte-offset>"
+  */
+  offset: string;
+  /**
+  * Timestamp when the message was appended.
+  */
+  timestamp: number;
+}
+/**
+* Stream metadata and data.
+*/
+interface Stream {
+  /**
+  * The stream URL path (key).
+  */
+  path: string;
+  /**
+  * Content type of the stream.
+  */
+  contentType?: string;
+  /**
+  * Messages in the stream.
+  */
+  messages: Array<StreamMessage>;
+  /**
+  * Current offset (next offset to write to).
+  */
+  currentOffset: string;
+  /**
+  * Last sequence number for writer coordination.
+  */
+  lastSeq?: string;
+  /**
+  * TTL in seconds.
+  */
+  ttlSeconds?: number;
+  /**
+  * Absolute expiry time (ISO 8601).
+  */
+  expiresAt?: string;
+  /**
+  * Timestamp when the stream was created.
+  */
+  createdAt: number;
+}
+/**
+* Event data for stream lifecycle hooks.
+*/
+interface StreamLifecycleEvent {
+  /**
+  * Type of event.
+  */
+  type: `created` | `deleted`;
+  /**
+  * Stream path.
+  */
+  path: string;
+  /**
+  * Content type (only for 'created' events).
+  */
+  contentType?: string;
+  /**
+  * Timestamp of the event.
+  */
+  timestamp: number;
+}
+/**
+* Hook function called when a stream is created or deleted.
+*/
+type StreamLifecycleHook = (event: StreamLifecycleEvent) => void | Promise<void>;
+/**
+* Options for creating the test server.
+*/
+interface TestServerOptions {
+  /**
+  * Port to listen on. Default: 0 (auto-assign).
+  */
+  port?: number;
+  /**
+  * Host to bind to. Default: "127.0.0.1".
+  */
+  host?: string;
+  /**
+  * Default long-poll timeout in milliseconds.
+  * Default: 30000 (30 seconds).
+  */
+  longPollTimeout?: number;
+  /**
+  * Data directory for file-backed storage.
+  * If provided, enables file-backed mode using LMDB and append-only logs.
+  * If omitted, uses in-memory storage.
+  */
+  dataDir?: string;
+  /**
+  * Hook called when a stream is created.
+  */
+  onStreamCreated?: StreamLifecycleHook;
+  /**
+  * Hook called when a stream is deleted.
+  */
+  onStreamDeleted?: StreamLifecycleHook;
+  /**
+  * Enable gzip/deflate compression for responses.
+  * Default: true.
+  */
+  compression?: boolean;
+  /**
+  * Interval in seconds for cursor calculation.
+  * Used for CDN cache collapsing to prevent infinite cache loops.
+  * Default: 20 seconds.
+  */
+  cursorIntervalSeconds?: number;
+  /**
+  * Epoch timestamp for cursor interval calculation.
+  * Default: October 9, 2024 00:00:00 UTC.
+  */
+  cursorEpoch?: Date;
+}
+/**
+* Pending long-poll request.
+*/
+interface PendingLongPoll {
+  /**
+  * Stream path.
+  */
+  path: string;
+  /**
+  * Offset to wait for.
+  */
+  offset: string;
+  /**
+  * Resolve function.
+  */
+  resolve: (messages: Array<StreamMessage>) => void;
+  /**
+  * Timeout ID.
+  */
+  timeoutId: ReturnType<typeof setTimeout>;
+} //#endregion
+//#region src/store.d.ts
+/**
+* In-memory store for durable streams.
+*/
+declare class StreamStore {
+  private streams;
+  private pendingLongPolls;
+  /**
+  * Create a new stream.
+  * @throws Error if stream already exists with different config
+  * @returns existing stream if config matches (idempotent)
+  */
+  create(path: string, options?: {
+    contentType?: string;
+    ttlSeconds?: number;
+    expiresAt?: string;
+    initialData?: Uint8Array;
+  }): Stream;
+  /**
+  * Get a stream by path.
+  */
+  get(path: string): Stream | undefined;
+  /**
+  * Check if a stream exists.
+  */
+  has(path: string): boolean;
+  /**
+  * Delete a stream.
+  */
+  delete(path: string): boolean;
+  /**
+  * Append data to a stream.
+  * @throws Error if stream doesn't exist
+  * @throws Error if seq is lower than lastSeq
+  * @throws Error if JSON mode and array is empty
+  */
+  append(path: string, data: Uint8Array, options?: {
+    seq?: string;
+    contentType?: string;
+  }): StreamMessage;
+  /**
+  * Read messages from a stream starting at the given offset.
+  */
+  read(path: string, offset?: string): {
+    messages: Array<StreamMessage>;
+    upToDate: boolean;
+  };
+  /**
+  * Format messages for response.
+  * For JSON mode, wraps concatenated data in array brackets.
+  */
+  formatResponse(path: string, messages: Array<StreamMessage>): Uint8Array;
+  /**
+  * Wait for new messages (long-poll).
+  */
+  waitForMessages(path: string, offset: string, timeoutMs: number): Promise<{
+    messages: Array<StreamMessage>;
+    timedOut: boolean;
+  }>;
+  /**
+  * Get the current offset for a stream.
+  */
+  getCurrentOffset(path: string): string | undefined;
+  /**
+  * Clear all streams.
+  */
+  clear(): void;
+  /**
+  * Cancel all pending long-polls (used during shutdown).
+  */
+  cancelAllWaits(): void;
+  /**
+  * Get all stream paths.
+  */
+  list(): Array<string>;
+  private appendToStream;
+  private findOffsetIndex;
+  private notifyLongPolls;
+  private cancelLongPollsForStream;
+  private removePendingLongPoll;
+} //#endregion
+//#region src/file-store.d.ts
+interface FileBackedStreamStoreOptions {
+  dataDir: string;
+  maxFileHandles?: number;
+}
+/**
+* File-backed implementation of StreamStore.
+* Maintains the same interface as the in-memory StreamStore for drop-in compatibility.
+*/
+declare class FileBackedStreamStore {
+  private db;
+  private fileManager;
+  private fileHandlePool;
+  private pendingLongPolls;
+  private dataDir;
+  constructor(options: FileBackedStreamStoreOptions);
+  /**
+  * Recover streams from disk on startup.
+  * Validates that LMDB metadata matches actual file contents and reconciles any mismatches.
+  */
+  private recover;
+  /**
+  * Scan a segment file to compute the true last offset.
+  * Handles partial/truncated messages at the end.
+  */
+  private scanFileForTrueOffset;
+  /**
+  * Convert LMDB metadata to Stream object.
+  */
+  private streamMetaToStream;
+  /**
+  * Close the store, closing all file handles and database.
+  * All data is already fsynced on each append, so no final flush needed.
+  */
+  close(): Promise<void>;
+  create(streamPath: string, options?: {
+    contentType?: string;
+    ttlSeconds?: number;
+    expiresAt?: string;
+    initialData?: Uint8Array;
+  }): Promise<Stream>;
+  get(streamPath: string): Stream | undefined;
+  has(streamPath: string): boolean;
+  delete(streamPath: string): boolean;
+  append(streamPath: string, data: Uint8Array, options?: {
+    seq?: string;
+    contentType?: string;
+    isInitialCreate?: boolean;
+  }): Promise<StreamMessage | null>;
+  read(streamPath: string, offset?: string): {
+    messages: Array<StreamMessage>;
+    upToDate: boolean;
+  };
+  waitForMessages(streamPath: string, offset: string, timeoutMs: number): Promise<{
+    messages: Array<StreamMessage>;
+    timedOut: boolean;
+  }>;
+  /**
+  * Format messages for response.
+  * For JSON mode, wraps concatenated data in array brackets.
+  */
+  formatResponse(streamPath: string, messages: Array<StreamMessage>): Uint8Array;
+  getCurrentOffset(streamPath: string): string | undefined;
+  clear(): void;
+  /**
+  * Cancel all pending long-polls (used during shutdown).
+  */
+  cancelAllWaits(): void;
+  list(): Array<string>;
+  private notifyLongPolls;
+  private cancelLongPollsForStream;
+  private removePendingLongPoll;
+}
+
+//#endregion
+//#region src/server.d.ts
+declare class DurableStreamTestServer {
+  readonly store: StreamStore | FileBackedStreamStore;
+  private server;
+  private options;
+  private _url;
+  private activeSSEResponses;
+  private isShuttingDown;
+  /** Injected errors for testing retry/resilience */
+  private injectedErrors;
+  constructor(options?: TestServerOptions);
+  /**
+  * Start the server.
+  */
+  start(): Promise<string>;
+  /**
+  * Stop the server.
+  */
+  stop(): Promise<void>;
+  /**
+  * Get the server URL.
+  */
+  get url(): string;
+  /**
+  * Clear all streams.
+  */
+  clear(): void;
+  /**
+  * Inject an error to be returned on the next N requests to a path.
+  * Used for testing retry/resilience behavior.
+  */
+  injectError(path: string, status: number, count?: number, retryAfter?: number): void;
+  /**
+  * Clear all injected errors.
+  */
+  clearInjectedErrors(): void;
+  /**
+  * Check if there's an injected error for this path and consume it.
+  * Returns the error config if one should be returned, null otherwise.
+  */
+  private consumeInjectedError;
+  private handleRequest;
+  /**
+  * Handle PUT - create stream
+  */
+  private handleCreate;
+  /**
+  * Handle HEAD - get metadata
+  */
+  private handleHead;
+  /**
+  * Handle GET - read data
+  */
+  private handleRead;
+  /**
+  * Handle SSE (Server-Sent Events) mode
+  */
+  private handleSSE;
+  /**
+  * Handle POST - append data
+  */
+  private handleAppend;
+  /**
+  * Handle DELETE - delete stream
+  */
+  private handleDelete;
+  /**
+  * Handle test control endpoints for error injection.
+  * POST /_test/inject-error - inject an error
+  * DELETE /_test/inject-error - clear all injected errors
+  */
+  private handleTestInjectError;
+  private readBody;
+}
+
+//#endregion
+//#region src/path-encoding.d.ts
+/**
+* Encode a stream path to a filesystem-safe directory name using base64url encoding.
+* Long paths (>200 chars) are hashed to keep directory names manageable.
+*
+* @example
+* encodeStreamPath("/stream/users:created") → "L3N0cmVhbS91c2VyczpjcmVhdGVk"
+*/
+declare function encodeStreamPath(path: string): string;
+/**
+* Decode a filesystem-safe directory name back to the original stream path.
+*
+* @example
+* decodeStreamPath("L3N0cmVhbS91c2VyczpjcmVhdGVk") → "/stream/users:created"
+*/
+declare function decodeStreamPath(encoded: string): string;
+
+//#endregion
+//#region src/registry-hook.d.ts
+/**
+* Creates lifecycle hooks that write to a __registry__ stream.
+* Any client can read this stream to discover all streams and their lifecycle events.
+*/
+declare function createRegistryHooks(store: StreamStore | FileBackedStreamStore, serverUrl: string): {
+  onStreamCreated: StreamLifecycleHook;
+  onStreamDeleted: StreamLifecycleHook;
+};
+
+//#endregion
+//#region src/cursor.d.ts
+/**
+* Stream cursor calculation for CDN cache collapsing.
+*
+* This module implements interval-based cursor generation to prevent
+* infinite CDN cache loops while enabling request collapsing.
+*
+* The mechanism works by:
+* 1. Dividing time into fixed intervals (default 20 seconds)
+* 2. Computing interval number from an epoch (October 9, 2024)
+* 3. Returning cursor values that change at interval boundaries
+* 4. Ensuring monotonic cursor progression (never going backwards)
+*/
+/**
+* Default epoch for cursor calculation: October 9, 2024 00:00:00 UTC.
+* This is the reference point from which intervals are counted.
+* Using a past date ensures cursors are always positive.
+*/
+declare const DEFAULT_CURSOR_EPOCH: Date;
+/**
+* Default interval duration in seconds.
+*/
+declare const DEFAULT_CURSOR_INTERVAL_SECONDS = 20;
+/**
+* Configuration options for cursor calculation.
+*/
+interface CursorOptions {
+  /**
+  * Interval duration in seconds.
+  * Default: 20 seconds.
+  */
+  intervalSeconds?: number;
+  /**
+  * Epoch timestamp for interval calculation.
+  * Default: October 9, 2024 00:00:00 UTC.
+  */
+  epoch?: Date;
+}
+/**
+* Calculate the current cursor value based on time intervals.
+*
+* @param options - Configuration for cursor calculation
+* @returns The current cursor value as a string
+*/
+declare function calculateCursor(options?: CursorOptions): string;
+/**
+* Generate a cursor for a response, ensuring monotonic progression.
+*
+* This function ensures the returned cursor is always greater than or equal
+* to the current time interval, and strictly greater than any client-provided
+* cursor. This prevents cache loops where a client could cycle between
+* cursor values.
+*
+* Algorithm:
+* - If no client cursor: return current interval
+* - If client cursor < current interval: return current interval
+* - If client cursor >= current interval: return client cursor + jitter
+*
+* This guarantees monotonic cursor progression and prevents A→B→A cycles.
+*
+* @param clientCursor - The cursor provided by the client (if any)
+* @param options - Configuration for cursor calculation
+* @returns The cursor value to include in the response
+*/
+declare function generateResponseCursor(clientCursor: string | undefined, options?: CursorOptions): string;
+/**
+* Handle cursor collision by adding random jitter.
+*
+* @deprecated Use generateResponseCursor instead, which handles all cases
+* including monotonicity guarantees.
+*
+* @param currentCursor - The newly calculated cursor value
+* @param previousCursor - The cursor provided by the client (if any)
+* @param options - Configuration for cursor calculation
+* @returns The cursor value to return, with jitter applied if there's a collision
+*/
+declare function handleCursorCollision(currentCursor: string, previousCursor: string | undefined, options?: CursorOptions): string;
+
+//#endregion
+export { CursorOptions, DEFAULT_CURSOR_EPOCH, DEFAULT_CURSOR_INTERVAL_SECONDS, DurableStreamTestServer, FileBackedStreamStore, PendingLongPoll, Stream, StreamLifecycleEvent, StreamLifecycleHook, StreamMessage, StreamStore, TestServerOptions, calculateCursor, createRegistryHooks, decodeStreamPath, encodeStreamPath, generateResponseCursor, handleCursorCollision };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@durable-streams/server",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Node.js reference server implementation for Durable Streams",
   "author": "Durable Stream contributors",
   "license": "Apache-2.0",
@@ -39,15 +39,15 @@
   "dependencies": {
     "@neophi/sieve-cache": "^1.0.0",
     "lmdb": "^3.3.0",
-    "@durable-streams/client": "0.1.1",
-    "@durable-streams/state": "0.1.1"
+    "@durable-streams/client": "0.1.2",
+    "@durable-streams/state": "0.1.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsdown": "^0.9.0",
     "typescript": "^5.0.0",
     "vitest": "^3.2.4",
-    "@durable-streams/server-conformance-tests": "0.1.1"
+    "@durable-streams/server-conformance-tests": "0.1.2"
   },
   "files": [
     "dist",