@durable-streams/server 0.1.1 → 0.1.3

package/dist/index.d.cts

@@ -0,0 +1,518 @@
+//#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;
+  /**
+  * Check if a stream is expired based on TTL or Expires-At.
+  */
+  private isExpired;
+  /**
+  * Get a stream, deleting it if expired.
+  * Returns undefined if stream doesn't exist or is expired.
+  */
+  private getIfNotExpired;
+  /**
+  * 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.
+  * Returns undefined if stream doesn't exist or is expired.
+  */
+  get(path: string): Stream | undefined;
+  /**
+  * Check if a stream exists (and is not expired).
+  */
+  has(path: string): boolean;
+  /**
+  * Delete a stream.
+  */
+  delete(path: string): boolean;
+  /**
+  * Append data to a stream.
+  * @throws Error if stream doesn't exist or is expired
+  * @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.
+  * @throws Error if stream doesn't exist or is expired
+  */
+  read(path: string, offset?: string): {
+    messages: Array<StreamMessage>;
+    upToDate: boolean;
+  };
+  /**
+  * Format messages for response.
+  * For JSON mode, wraps concatenated data in array brackets.
+  * @throws Error if stream doesn't exist or is expired
+  */
+  formatResponse(path: string, messages: Array<StreamMessage>): Uint8Array;
+  /**
+  * Wait for new messages (long-poll).
+  * @throws Error if stream doesn't exist or is expired
+  */
+  waitForMessages(path: string, offset: string, timeoutMs: number): Promise<{
+    messages: Array<StreamMessage>;
+    timedOut: boolean;
+  }>;
+  /**
+  * Get the current offset for a stream.
+  * Returns undefined if stream doesn't exist or is expired.
+  */
+  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;
+  /**
+  * Check if a stream is expired based on TTL or Expires-At.
+  */
+  private isExpired;
+  /**
+  * Get stream metadata, deleting it if expired.
+  * Returns undefined if stream doesn't exist or is expired.
+  */
+  private getMetaIfNotExpired;
+  /**
+  * 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.
+  * @throws Error if stream doesn't exist or is expired
+  */
+  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/dist/index.d.ts

@@ -159,6 +159,15 @@ declare class StreamStore {
   private streams;
   private pendingLongPolls;
   /**
+  * Check if a stream is expired based on TTL or Expires-At.
+  */
+  private isExpired;
+  /**
+  * Get a stream, deleting it if expired.
+  * Returns undefined if stream doesn't exist or is expired.
+  */
+  private getIfNotExpired;
+  /**
   * Create a new stream.
   * @throws Error if stream already exists with different config
   * @returns existing stream if config matches (idempotent)
@@ -171,10 +180,11 @@ declare class StreamStore {
   }): Stream;
   /**
   * Get a stream by path.
+  * Returns undefined if stream doesn't exist or is expired.
   */
   get(path: string): Stream | undefined;
   /**
-  * Check if a stream exists.
+  * Check if a stream exists (and is not expired).
   */
   has(path: string): boolean;
   /**
@@ -183,7 +193,7 @@ declare class StreamStore {
   delete(path: string): boolean;
   /**
   * Append data to a stream.
-  * @throws Error if stream doesn't exist
+  * @throws Error if stream doesn't exist or is expired
   * @throws Error if seq is lower than lastSeq
   * @throws Error if JSON mode and array is empty
   */
@@ -193,6 +203,7 @@ declare class StreamStore {
   }): StreamMessage;
   /**
   * Read messages from a stream starting at the given offset.
+  * @throws Error if stream doesn't exist or is expired
   */
   read(path: string, offset?: string): {
     messages: Array<StreamMessage>;
@@ -201,10 +212,12 @@ declare class StreamStore {
   /**
   * Format messages for response.
   * For JSON mode, wraps concatenated data in array brackets.
+  * @throws Error if stream doesn't exist or is expired
   */
   formatResponse(path: string, messages: Array<StreamMessage>): Uint8Array;
   /**
   * Wait for new messages (long-poll).
+  * @throws Error if stream doesn't exist or is expired
   */
   waitForMessages(path: string, offset: string, timeoutMs: number): Promise<{
     messages: Array<StreamMessage>;
@@ -212,6 +225,7 @@ declare class StreamStore {
   }>;
   /**
   * Get the current offset for a stream.
+  * Returns undefined if stream doesn't exist or is expired.
   */
   getCurrentOffset(path: string): string | undefined;
   /**
@@ -263,6 +277,15 @@ declare class FileBackedStreamStore {
   */
   private streamMetaToStream;
   /**
+  * Check if a stream is expired based on TTL or Expires-At.
+  */
+  private isExpired;
+  /**
+  * Get stream metadata, deleting it if expired.
+  * Returns undefined if stream doesn't exist or is expired.
+  */
+  private getMetaIfNotExpired;
+  /**
   * Close the store, closing all file handles and database.
   * All data is already fsynced on each append, so no final flush needed.
   */
@@ -292,6 +315,7 @@ declare class FileBackedStreamStore {
   /**
   * Format messages for response.
   * For JSON mode, wraps concatenated data in array brackets.
+  * @throws Error if stream doesn't exist or is expired
   */
   formatResponse(streamPath: string, messages: Array<StreamMessage>): Uint8Array;
   getCurrentOffset(streamPath: string): string | undefined;