@durable-streams/server 0.3.1 → 0.3.3

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+
 //#region src/types.d.ts
 /**
 * Types for the in-memory durable streams test server.
@@ -5,6 +7,12 @@
 /**
 * A single message in a stream.
 */
+/**
+* Types for the in-memory durable streams test server.
+*/
+/**
+* A single message in a stream.
+*/
 interface StreamMessage {
   /**
   * The raw bytes of the message.
@@ -172,6 +180,13 @@ interface TestServerOptions {
   * Default: October 9, 2024 00:00:00 UTC.
   */
   cursorEpoch?: Date;
+  /**
+  * Enable webhook subscriptions.
+  * Pull-wake subscription routes are always mounted, but type=webhook creates
+  * are rejected unless this is true.
+  * Default: false.
+  */
+  webhooks?: boolean;
 }
 /**
 * Producer state for idempotent writes.
@@ -466,7 +481,6 @@ interface FileBackedStreamStoreOptions {
 */
 declare class FileBackedStreamStore {
   private db;
-  private fileManager;
   private fileHandlePool;
   private pendingLongPolls;
   private dataDir;
@@ -475,6 +489,13 @@ declare class FileBackedStreamStore {
   * Key: "{streamPath}:{producerId}"
   */
   private producerLocks;
+  /**
+  * Per-stream append locks. Serializes the read-modify-write of currentOffset
+  * across all concurrent appenders on the same stream so the LMDB-tracked
+  * offset cannot drift behind the file's actual byte position.
+  * Key: streamPath
+  */
+  private streamAppendLocks;
   constructor(options: FileBackedStreamStoreOptions);
   /**
   * Recover streams from disk on startup.
@@ -505,6 +526,15 @@ declare class FileBackedStreamStore {
   */
   private acquireProducerLock;
   /**
+  * Acquire a per-stream append lock that serializes the read-modify-write
+  * of currentOffset across all concurrent appenders on the same stream.
+  * Without this, two concurrent appends can read the same starting
+  * currentOffset, both compute their newOffset, both write a frame to the
+  * file, but only one of their LMDB updates wins — leaving currentOffset
+  * lagging the file's actual byte position. Returns a release function.
+  */
+  private acquireStreamAppendLock;
+  /**
   * Get the current epoch for a producer on a stream.
   * Returns undefined if the producer doesn't exist or stream not found.
   */
@@ -550,9 +580,15 @@ declare class FileBackedStreamStore {
   * whose refcount drops to zero.
   */
   private deleteWithCascade;
+  /**
+  * Public append entry point. Serializes concurrent appends to the same
+  * stream so the read-modify-write of currentOffset cannot interleave —
+  * see acquireStreamAppendLock for the underlying race.
+  */
   append(streamPath: string, data: Uint8Array, options?: AppendOptions & {
     isInitialCreate?: boolean;
   }): Promise<StreamMessage | AppendResult | null>;
+  private appendInner;
   /**
   * Append with producer serialization for concurrent request handling.
   * This ensures that validation+append is atomic per producer.
@@ -673,6 +709,8 @@ declare class DurableStreamTestServer {
   private isShuttingDown;
   /** Injected faults for testing retry/resilience */
   private injectedFaults;
+  private subscriptionManager;
+  private subscriptionRoutes;
   constructor(options?: TestServerOptions);
   /**
   * Start the server.
@@ -742,6 +780,7 @@ declare class DurableStreamTestServer {
   * Handle POST - append data
   */
   private handleAppend;
+  private notifyStreamAppend;
   /**
   * Handle DELETE - delete stream
   */
@@ -864,4 +903,221 @@ declare function generateResponseCursor(clientCursor: string | undefined, option
 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 };
+//#region src/crypto.d.ts
+interface WebhookPublicJwk {
+  kty: `OKP`;
+  crv: `Ed25519`;
+  x: string;
+  kid: string;
+  use: `sig`;
+  alg: `EdDSA`;
+}
+interface WebhookJwks {
+  keys: Array<WebhookPublicJwk>;
+}
+/**
+* Generate a unique wake ID.
+*/
+
+declare function getWebhookJwks(): WebhookJwks;
+
+//#endregion
+//#region src/subscription-types.d.ts
+/**
+* Sign a webhook payload for the Webhook-Signature header.
+* Format: t=<timestamp>,kid=<key_id>,ed25519=<base64url_signature>
+*/
+type SubscriptionType = `webhook` | `pull-wake`;
+type SubscriptionStatus = `active` | `failed`;
+type SubscriptionLinkType = `glob` | `explicit`;
+interface SubscriptionStreamLink {
+  path: string;
+  link_types: Set<SubscriptionLinkType>;
+  acked_offset: string;
+}
+interface SubscriptionWebhookConfig {
+  url: string;
+}
+interface SubscriptionRecord {
+  id: string;
+  type: SubscriptionType;
+  pattern?: string;
+  webhook?: SubscriptionWebhookConfig;
+  wake_stream?: string;
+  lease_ttl_ms: number;
+  description?: string;
+  created_at: string;
+  status: SubscriptionStatus;
+  config_hash: string;
+  streams: Map<string, SubscriptionStreamLink>;
+  generation: number;
+  wake_id: string | null;
+  wake_snapshot: Map<string, string>;
+  token: string | null;
+  holder: string | null;
+  lease_timer: ReturnType<typeof setTimeout> | null;
+  retry_count: number;
+  retry_timer: ReturnType<typeof setTimeout> | null;
+  next_attempt_at: number | null;
+}
+interface SubscriptionStreamInfo {
+  path: string;
+  link_type: SubscriptionLinkType;
+  acked_offset: string;
+  tail_offset: string;
+  has_pending: boolean;
+}
+interface SubscriptionCreateInput {
+  type: SubscriptionType;
+  pattern?: string;
+  streams: Array<string>;
+  webhook?: {
+    url: string;
+  };
+  wake_stream?: string;
+  lease_ttl_ms: number;
+  description?: string;
+}
+interface SubscriptionCallbackRequest {
+  wake_id?: string;
+  generation?: number;
+  acks?: Array<{
+    stream?: string;
+    path?: string;
+    offset: string;
+  }>;
+  done?: boolean;
+}
+type SubscriptionErrorCode = `INVALID_REQUEST` | `SUBSCRIPTION_NOT_FOUND` | `SUBSCRIPTION_ALREADY_EXISTS` | `WEBHOOK_URL_REJECTED` | `TOKEN_INVALID` | `TOKEN_EXPIRED` | `FENCED` | `ALREADY_CLAIMED` | `NO_PENDING_WORK` | `INVALID_OFFSET`;
+interface SubscriptionError {
+  code: SubscriptionErrorCode;
+  message: string;
+  current_holder?: string;
+  generation?: number;
+}
+
+//#endregion
+//#region src/subscription-manager.d.ts
+interface StreamLike {
+  currentOffset: string;
+  softDeleted?: boolean;
+}
+interface SubscriptionStreamStore {
+  has: (path: string) => boolean;
+  get: (path: string) => StreamLike | undefined;
+  list: () => Array<string>;
+  append: (path: string, data: Uint8Array) => unknown;
+}
+declare function validateWebhookUrl(rawUrl: string): {
+  ok: true;
+} | {
+  ok: false;
+  message: string;
+};
+declare class SubscriptionManager {
+  private readonly subscriptions;
+  private readonly streamStore;
+  private readonly callbackBaseUrl;
+  private readonly webhooksEnabled;
+  private isShuttingDown;
+  constructor(opts: {
+    callbackBaseUrl: string;
+    streamStore: SubscriptionStreamStore;
+    webhooksEnabled?: boolean;
+  });
+  createOrConfirm(id: string, input: SubscriptionCreateInput): {
+    subscription: SubscriptionRecord;
+    created: boolean;
+  } | {
+    error: SubscriptionError;
+  };
+  get(id: string): SubscriptionRecord | undefined;
+  delete(id: string): boolean;
+  addExplicitStreams(id: string, streams: Array<string>): boolean;
+  removeExplicitStream(id: string, streamPath: string): boolean;
+  onStreamAppend(absolutePath: string): Promise<void>;
+  onStreamDeleted(absolutePath: string): void;
+  handleWebhookCallback(id: string, token: string, request: SubscriptionCallbackRequest): Promise<{
+    status: number;
+    body: Record<string, unknown>;
+  }>;
+  claim(id: string, worker: string): Promise<{
+    status: number;
+    body: Record<string, unknown>;
+  }>;
+  ack(id: string, token: string, request: SubscriptionCallbackRequest): Promise<{
+    status: number;
+    body: Record<string, unknown>;
+  }>;
+  release(id: string, token: string, request: SubscriptionCallbackRequest): Promise<{
+    status: number;
+    body?: Record<string, unknown>;
+  }>;
+  serialize(subscription: SubscriptionRecord): Record<string, unknown>;
+  getWebhookJwks(): ReturnType<typeof getWebhookJwks>;
+  shutdown(): void;
+  private maybeWake;
+  private createWake;
+  private deliverWebhook;
+  private scheduleWebhookRetry;
+  private writePullWakeEvent;
+  private autoAckWakeSnapshot;
+  private applyAcks;
+  private validateWakeToken;
+  private triggerNextWakeIfPending;
+  private hasPendingWork;
+  private firstPendingStream;
+  private streamInfos;
+  private linkStream;
+  private listStreams;
+  private getTailOffset;
+  private subscriptionActionUrl;
+  private webhookJwksUrl;
+  private webhookSigningMetadata;
+  private extendLease;
+  private clearLease;
+  private tokenSubject;
+  private errorResponse;
+}
+
+//#endregion
+//#region src/subscription-routes.d.ts
+declare class SubscriptionRoutes {
+  private readonly manager;
+  constructor(manager: SubscriptionManager);
+  handleRequest(method: string, path: string, req: IncomingMessage, res: ServerResponse): Promise<boolean>;
+  private handleBase;
+  private handleJwks;
+  private handleStreams;
+  private handleStream;
+  private handleCallback;
+  private handleClaim;
+  private handleAck;
+  private handleRelease;
+  private parseCreateInput;
+  private parseRoute;
+  private readBearerToken;
+  private readJson;
+  private writeManagerResult;
+  private writeJson;
+  private writeError;
+  private methodNotAllowed;
+}
+
+//#endregion
+//#region src/glob.d.ts
+/**
+* Glob pattern matching for webhook subscription patterns.
+*
+* Supports:
+* - `*` matches exactly one path segment
+* - `**` matches zero or more path segments (recursive)
+* - Literal segments match exactly
+*/
+/**
+* Match a stream path against a glob pattern.
+*/
+declare function globMatch(pattern: string, path: string): boolean;
+
+//#endregion
+export { CursorOptions, DEFAULT_CURSOR_EPOCH, DEFAULT_CURSOR_INTERVAL_SECONDS, DurableStreamTestServer, FileBackedStreamStore, PendingLongPoll, Stream, StreamLifecycleEvent, StreamLifecycleHook, StreamMessage, StreamStore, SubscriptionCallbackRequest, SubscriptionCreateInput, SubscriptionError, SubscriptionErrorCode, SubscriptionManager, SubscriptionRecord, SubscriptionRoutes, SubscriptionStatus, SubscriptionStreamInfo, SubscriptionStreamLink, SubscriptionType, TestServerOptions, calculateCursor, createRegistryHooks, decodeStreamPath, encodeStreamPath, generateResponseCursor, globMatch, handleCursorCollision, validateWebhookUrl };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+
 //#region src/types.d.ts
 /**
 * Types for the in-memory durable streams test server.
@@ -5,6 +7,12 @@
 /**
 * A single message in a stream.
 */
+/**
+* Types for the in-memory durable streams test server.
+*/
+/**
+* A single message in a stream.
+*/
 interface StreamMessage {
   /**
   * The raw bytes of the message.
@@ -172,6 +180,13 @@ interface TestServerOptions {
   * Default: October 9, 2024 00:00:00 UTC.
   */
   cursorEpoch?: Date;
+  /**
+  * Enable webhook subscriptions.
+  * Pull-wake subscription routes are always mounted, but type=webhook creates
+  * are rejected unless this is true.
+  * Default: false.
+  */
+  webhooks?: boolean;
 }
 /**
 * Producer state for idempotent writes.
@@ -466,7 +481,6 @@ interface FileBackedStreamStoreOptions {
 */
 declare class FileBackedStreamStore {
   private db;
-  private fileManager;
   private fileHandlePool;
   private pendingLongPolls;
   private dataDir;
@@ -475,6 +489,13 @@ declare class FileBackedStreamStore {
   * Key: "{streamPath}:{producerId}"
   */
   private producerLocks;
+  /**
+  * Per-stream append locks. Serializes the read-modify-write of currentOffset
+  * across all concurrent appenders on the same stream so the LMDB-tracked
+  * offset cannot drift behind the file's actual byte position.
+  * Key: streamPath
+  */
+  private streamAppendLocks;
   constructor(options: FileBackedStreamStoreOptions);
   /**
   * Recover streams from disk on startup.
@@ -505,6 +526,15 @@ declare class FileBackedStreamStore {
   */
   private acquireProducerLock;
   /**
+  * Acquire a per-stream append lock that serializes the read-modify-write
+  * of currentOffset across all concurrent appenders on the same stream.
+  * Without this, two concurrent appends can read the same starting
+  * currentOffset, both compute their newOffset, both write a frame to the
+  * file, but only one of their LMDB updates wins — leaving currentOffset
+  * lagging the file's actual byte position. Returns a release function.
+  */
+  private acquireStreamAppendLock;
+  /**
   * Get the current epoch for a producer on a stream.
   * Returns undefined if the producer doesn't exist or stream not found.
   */
@@ -550,9 +580,15 @@ declare class FileBackedStreamStore {
   * whose refcount drops to zero.
   */
   private deleteWithCascade;
+  /**
+  * Public append entry point. Serializes concurrent appends to the same
+  * stream so the read-modify-write of currentOffset cannot interleave —
+  * see acquireStreamAppendLock for the underlying race.
+  */
   append(streamPath: string, data: Uint8Array, options?: AppendOptions & {
     isInitialCreate?: boolean;
   }): Promise<StreamMessage | AppendResult | null>;
+  private appendInner;
   /**
   * Append with producer serialization for concurrent request handling.
   * This ensures that validation+append is atomic per producer.
@@ -673,6 +709,8 @@ declare class DurableStreamTestServer {
   private isShuttingDown;
   /** Injected faults for testing retry/resilience */
   private injectedFaults;
+  private subscriptionManager;
+  private subscriptionRoutes;
   constructor(options?: TestServerOptions);
   /**
   * Start the server.
@@ -742,6 +780,7 @@ declare class DurableStreamTestServer {
   * Handle POST - append data
   */
   private handleAppend;
+  private notifyStreamAppend;
   /**
   * Handle DELETE - delete stream
   */
@@ -864,4 +903,221 @@ declare function generateResponseCursor(clientCursor: string | undefined, option
 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 };
+//#region src/crypto.d.ts
+interface WebhookPublicJwk {
+  kty: `OKP`;
+  crv: `Ed25519`;
+  x: string;
+  kid: string;
+  use: `sig`;
+  alg: `EdDSA`;
+}
+interface WebhookJwks {
+  keys: Array<WebhookPublicJwk>;
+}
+/**
+* Generate a unique wake ID.
+*/
+
+declare function getWebhookJwks(): WebhookJwks;
+
+//#endregion
+//#region src/subscription-types.d.ts
+/**
+* Sign a webhook payload for the Webhook-Signature header.
+* Format: t=<timestamp>,kid=<key_id>,ed25519=<base64url_signature>
+*/
+type SubscriptionType = `webhook` | `pull-wake`;
+type SubscriptionStatus = `active` | `failed`;
+type SubscriptionLinkType = `glob` | `explicit`;
+interface SubscriptionStreamLink {
+  path: string;
+  link_types: Set<SubscriptionLinkType>;
+  acked_offset: string;
+}
+interface SubscriptionWebhookConfig {
+  url: string;
+}
+interface SubscriptionRecord {
+  id: string;
+  type: SubscriptionType;
+  pattern?: string;
+  webhook?: SubscriptionWebhookConfig;
+  wake_stream?: string;
+  lease_ttl_ms: number;
+  description?: string;
+  created_at: string;
+  status: SubscriptionStatus;
+  config_hash: string;
+  streams: Map<string, SubscriptionStreamLink>;
+  generation: number;
+  wake_id: string | null;
+  wake_snapshot: Map<string, string>;
+  token: string | null;
+  holder: string | null;
+  lease_timer: ReturnType<typeof setTimeout> | null;
+  retry_count: number;
+  retry_timer: ReturnType<typeof setTimeout> | null;
+  next_attempt_at: number | null;
+}
+interface SubscriptionStreamInfo {
+  path: string;
+  link_type: SubscriptionLinkType;
+  acked_offset: string;
+  tail_offset: string;
+  has_pending: boolean;
+}
+interface SubscriptionCreateInput {
+  type: SubscriptionType;
+  pattern?: string;
+  streams: Array<string>;
+  webhook?: {
+    url: string;
+  };
+  wake_stream?: string;
+  lease_ttl_ms: number;
+  description?: string;
+}
+interface SubscriptionCallbackRequest {
+  wake_id?: string;
+  generation?: number;
+  acks?: Array<{
+    stream?: string;
+    path?: string;
+    offset: string;
+  }>;
+  done?: boolean;
+}
+type SubscriptionErrorCode = `INVALID_REQUEST` | `SUBSCRIPTION_NOT_FOUND` | `SUBSCRIPTION_ALREADY_EXISTS` | `WEBHOOK_URL_REJECTED` | `TOKEN_INVALID` | `TOKEN_EXPIRED` | `FENCED` | `ALREADY_CLAIMED` | `NO_PENDING_WORK` | `INVALID_OFFSET`;
+interface SubscriptionError {
+  code: SubscriptionErrorCode;
+  message: string;
+  current_holder?: string;
+  generation?: number;
+}
+
+//#endregion
+//#region src/subscription-manager.d.ts
+interface StreamLike {
+  currentOffset: string;
+  softDeleted?: boolean;
+}
+interface SubscriptionStreamStore {
+  has: (path: string) => boolean;
+  get: (path: string) => StreamLike | undefined;
+  list: () => Array<string>;
+  append: (path: string, data: Uint8Array) => unknown;
+}
+declare function validateWebhookUrl(rawUrl: string): {
+  ok: true;
+} | {
+  ok: false;
+  message: string;
+};
+declare class SubscriptionManager {
+  private readonly subscriptions;
+  private readonly streamStore;
+  private readonly callbackBaseUrl;
+  private readonly webhooksEnabled;
+  private isShuttingDown;
+  constructor(opts: {
+    callbackBaseUrl: string;
+    streamStore: SubscriptionStreamStore;
+    webhooksEnabled?: boolean;
+  });
+  createOrConfirm(id: string, input: SubscriptionCreateInput): {
+    subscription: SubscriptionRecord;
+    created: boolean;
+  } | {
+    error: SubscriptionError;
+  };
+  get(id: string): SubscriptionRecord | undefined;
+  delete(id: string): boolean;
+  addExplicitStreams(id: string, streams: Array<string>): boolean;
+  removeExplicitStream(id: string, streamPath: string): boolean;
+  onStreamAppend(absolutePath: string): Promise<void>;
+  onStreamDeleted(absolutePath: string): void;
+  handleWebhookCallback(id: string, token: string, request: SubscriptionCallbackRequest): Promise<{
+    status: number;
+    body: Record<string, unknown>;
+  }>;
+  claim(id: string, worker: string): Promise<{
+    status: number;
+    body: Record<string, unknown>;
+  }>;
+  ack(id: string, token: string, request: SubscriptionCallbackRequest): Promise<{
+    status: number;
+    body: Record<string, unknown>;
+  }>;
+  release(id: string, token: string, request: SubscriptionCallbackRequest): Promise<{
+    status: number;
+    body?: Record<string, unknown>;
+  }>;
+  serialize(subscription: SubscriptionRecord): Record<string, unknown>;
+  getWebhookJwks(): ReturnType<typeof getWebhookJwks>;
+  shutdown(): void;
+  private maybeWake;
+  private createWake;
+  private deliverWebhook;
+  private scheduleWebhookRetry;
+  private writePullWakeEvent;
+  private autoAckWakeSnapshot;
+  private applyAcks;
+  private validateWakeToken;
+  private triggerNextWakeIfPending;
+  private hasPendingWork;
+  private firstPendingStream;
+  private streamInfos;
+  private linkStream;
+  private listStreams;
+  private getTailOffset;
+  private subscriptionActionUrl;
+  private webhookJwksUrl;
+  private webhookSigningMetadata;
+  private extendLease;
+  private clearLease;
+  private tokenSubject;
+  private errorResponse;
+}
+
+//#endregion
+//#region src/subscription-routes.d.ts
+declare class SubscriptionRoutes {
+  private readonly manager;
+  constructor(manager: SubscriptionManager);
+  handleRequest(method: string, path: string, req: IncomingMessage, res: ServerResponse): Promise<boolean>;
+  private handleBase;
+  private handleJwks;
+  private handleStreams;
+  private handleStream;
+  private handleCallback;
+  private handleClaim;
+  private handleAck;
+  private handleRelease;
+  private parseCreateInput;
+  private parseRoute;
+  private readBearerToken;
+  private readJson;
+  private writeManagerResult;
+  private writeJson;
+  private writeError;
+  private methodNotAllowed;
+}
+
+//#endregion
+//#region src/glob.d.ts
+/**
+* Glob pattern matching for webhook subscription patterns.
+*
+* Supports:
+* - `*` matches exactly one path segment
+* - `**` matches zero or more path segments (recursive)
+* - Literal segments match exactly
+*/
+/**
+* Match a stream path against a glob pattern.
+*/
+declare function globMatch(pattern: string, path: string): boolean;
+
+//#endregion
+export { CursorOptions, DEFAULT_CURSOR_EPOCH, DEFAULT_CURSOR_INTERVAL_SECONDS, DurableStreamTestServer, FileBackedStreamStore, PendingLongPoll, Stream, StreamLifecycleEvent, StreamLifecycleHook, StreamMessage, StreamStore, SubscriptionCallbackRequest, SubscriptionCreateInput, SubscriptionError, SubscriptionErrorCode, SubscriptionManager, SubscriptionRecord, SubscriptionRoutes, SubscriptionStatus, SubscriptionStreamInfo, SubscriptionStreamLink, SubscriptionType, TestServerOptions, calculateCursor, createRegistryHooks, decodeStreamPath, encodeStreamPath, generateResponseCursor, globMatch, handleCursorCollision, validateWebhookUrl };