@durable-streams/server 0.1.3 → 0.1.5

package/dist/index.d.cts

@@ -56,6 +56,11 @@ interface Stream {
   * Timestamp when the stream was created.
   */
   createdAt: number;
+  /**
+  * Producer states for idempotent writes.
+  * Maps producer ID to their epoch and sequence state.
+  */
+  producers?: Map<string, ProducerState>;
 }
 /**
 * Event data for stream lifecycle hooks.
@@ -131,6 +136,49 @@ interface TestServerOptions {
   cursorEpoch?: Date;
 }
 /**
+* Producer state for idempotent writes.
+* Tracks epoch and sequence number per producer ID for deduplication.
+*/
+interface ProducerState {
+  /**
+  * Current epoch for this producer.
+  * Client-declared, server-validated monotonically increasing.
+  */
+  epoch: number;
+  /**
+  * Last sequence number received in this epoch.
+  */
+  lastSeq: number;
+  /**
+  * Timestamp when this producer state was last updated.
+  * Used for TTL-based cleanup.
+  */
+  lastUpdated: number;
+}
+/**
+* Result of producer validation for append operations.
+* For 'accepted' status, includes proposedState to commit after successful append.
+*/
+type ProducerValidationResult = {
+  status: `accepted`;
+  isNew: boolean;
+  /** State to commit after successful append (deferred mutation) */
+  proposedState: ProducerState;
+  producerId: string;
+} | {
+  status: `duplicate`;
+  lastSeq: number;
+} | {
+  status: `stale_epoch`;
+  currentEpoch: number;
+} | {
+  status: `invalid_epoch_seq`;
+} | {
+  status: `sequence_gap`;
+  expectedSeq: number;
+  receivedSeq: number;
+};
+/**
 * Pending long-poll request.
 */
 interface PendingLongPoll {
@@ -155,10 +203,32 @@ interface PendingLongPoll {
 /**
 * In-memory store for durable streams.
 */
+/**
+* Options for append operations.
+*/
+interface AppendOptions {
+  seq?: string;
+  contentType?: string;
+  producerId?: string;
+  producerEpoch?: number;
+  producerSeq?: number;
+}
+/**
+* Result of an append operation.
+*/
+interface AppendResult {
+  message: StreamMessage | null;
+  producerResult?: ProducerValidationResult;
+}
 declare class StreamStore {
   private streams;
   private pendingLongPolls;
   /**
+  * Per-producer locks for serializing validation+append operations.
+  * Key: "{streamPath}:{producerId}"
+  */
+  private producerLocks;
+  /**
   * Check if a stream is expired based on TTL or Expires-At.
   */
   private isExpired;
@@ -192,15 +262,47 @@ declare class StreamStore {
   */
   delete(path: string): boolean;
   /**
+  * Validate producer state WITHOUT mutating.
+  * Returns proposed state to commit after successful append.
+  * Implements Kafka-style idempotent producer validation.
+  *
+  * IMPORTANT: This function does NOT mutate producer state. The caller must
+  * call commitProducerState() after successful append to apply the mutation.
+  * This ensures atomicity: if append fails (e.g., JSON validation), producer
+  * state is not incorrectly advanced.
+  */
+  private validateProducer;
+  /**
+  * Commit producer state after successful append.
+  * This is the only place where producer state is mutated.
+  */
+  private commitProducerState;
+  /**
+  * Clean up expired producer states from a stream.
+  */
+  private cleanupExpiredProducers;
+  /**
+  * Acquire a lock for serialized producer operations.
+  * Returns a release function.
+  */
+  private acquireProducerLock;
+  /**
   * 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;
+  append(path: string, data: Uint8Array, options?: AppendOptions): StreamMessage | AppendResult;
+  /**
+  * Append with producer serialization for concurrent request handling.
+  * This ensures that validation+append is atomic per producer.
+  */
+  appendWithProducer(path: string, data: Uint8Array, options: AppendOptions): Promise<AppendResult>;
+  /**
+  * Get the current epoch for a producer on a stream.
+  * Returns undefined if the producer doesn't exist or stream not found.
+  */
+  getProducerEpoch(path: string, producerId: string): number | undefined;
   /**
   * Read messages from a stream starting at the given offset.
   * @throws Error if stream doesn't exist or is expired
@@ -261,6 +363,11 @@ declare class FileBackedStreamStore {
   private fileHandlePool;
   private pendingLongPolls;
   private dataDir;
+  /**
+  * Per-producer locks for serializing validation+append operations.
+  * Key: "{streamPath}:{producerId}"
+  */
+  private producerLocks;
   constructor(options: FileBackedStreamStoreOptions);
   /**
   * Recover streams from disk on startup.
@@ -277,6 +384,25 @@ declare class FileBackedStreamStore {
   */
   private streamMetaToStream;
   /**
+  * Validate producer state WITHOUT mutating.
+  * Returns proposed state to commit after successful append.
+  *
+  * IMPORTANT: This function does NOT mutate producer state. The caller must
+  * commit the proposedState after successful append (file write + fsync + LMDB).
+  * This ensures atomicity: if any step fails, producer state is not advanced.
+  */
+  private validateProducer;
+  /**
+  * Acquire a lock for serialized producer operations.
+  * Returns a release function.
+  */
+  private acquireProducerLock;
+  /**
+  * Get the current epoch for a producer on a stream.
+  * Returns undefined if the producer doesn't exist or stream not found.
+  */
+  getProducerEpoch(streamPath: string, producerId: string): number | undefined;
+  /**
   * Check if a stream is expired based on TTL or Expires-At.
   */
   private isExpired;
@@ -299,11 +425,14 @@ declare class FileBackedStreamStore {
   get(streamPath: string): Stream | undefined;
   has(streamPath: string): boolean;
   delete(streamPath: string): boolean;
-  append(streamPath: string, data: Uint8Array, options?: {
-    seq?: string;
-    contentType?: string;
+  append(streamPath: string, data: Uint8Array, options?: AppendOptions & {
     isInitialCreate?: boolean;
-  }): Promise<StreamMessage | null>;
+  }): Promise<StreamMessage | AppendResult | null>;
+  /**
+  * Append with producer serialization for concurrent request handling.
+  * This ensures that validation+append is atomic per producer.
+  */
+  appendWithProducer(streamPath: string, data: Uint8Array, options: AppendOptions): Promise<AppendResult>;
   read(streamPath: string, offset?: string): {
     messages: Array<StreamMessage>;
     upToDate: boolean;
@@ -332,6 +461,36 @@ declare class FileBackedStreamStore {
 
 //#endregion
 //#region src/server.d.ts
+/**
+* HTTP server for testing durable streams.
+* Supports both in-memory and file-backed storage modes.
+*/
+/**
+* Configuration for injected faults (for testing retry/resilience).
+* Supports various fault types beyond simple HTTP errors.
+*/
+interface InjectedFault {
+  /** HTTP status code to return (if set, returns error response) */
+  status?: number;
+  /** Number of times to trigger this fault (decremented on each use) */
+  count: number;
+  /** Optional Retry-After header value (seconds) */
+  retryAfter?: number;
+  /** Delay in milliseconds before responding */
+  delayMs?: number;
+  /** Drop the connection after sending headers (simulates network failure) */
+  dropConnection?: boolean;
+  /** Truncate response body to this many bytes */
+  truncateBodyBytes?: number;
+  /** Probability of triggering fault (0-1, default 1.0 = always) */
+  probability?: number;
+  /** Only match specific HTTP method (GET, POST, PUT, DELETE) */
+  method?: string;
+  /** Corrupt the response body by flipping random bits */
+  corruptBody?: boolean;
+  /** Add jitter to delay (random 0-jitterMs added to delayMs) */
+  jitterMs?: number;
+}
 declare class DurableStreamTestServer {
   readonly store: StreamStore | FileBackedStreamStore;
   private server;
@@ -339,8 +498,8 @@ declare class DurableStreamTestServer {
   private _url;
   private activeSSEResponses;
   private isShuttingDown;
-  /** Injected errors for testing retry/resilience */
-  private injectedErrors;
+  /** Injected faults for testing retry/resilience */
+  private injectedFaults;
   constructor(options?: TestServerOptions);
   /**
   * Start the server.
@@ -361,17 +520,34 @@ declare class DurableStreamTestServer {
   /**
   * Inject an error to be returned on the next N requests to a path.
   * Used for testing retry/resilience behavior.
+  * @deprecated Use injectFault for full fault injection capabilities
   */
   injectError(path: string, status: number, count?: number, retryAfter?: number): void;
   /**
-  * Clear all injected errors.
+  * Inject a fault to be triggered on the next N requests to a path.
+  * Supports various fault types: delays, connection drops, body corruption, etc.
+  */
+  injectFault(path: string, fault: Omit<InjectedFault, `count`> & {
+    count?: number;
+  }): void;
+  /**
+  * Clear all injected faults.
+  */
+  clearInjectedFaults(): void;
+  /**
+  * Check if there's an injected fault for this path/method and consume it.
+  * Returns the fault config if one should be triggered, null otherwise.
+  */
+  private consumeInjectedFault;
+  /**
+  * Apply delay from fault config (including jitter).
   */
-  clearInjectedErrors(): void;
+  private applyFaultDelay;
   /**
-  * Check if there's an injected error for this path and consume it.
-  * Returns the error config if one should be returned, null otherwise.
+  * Apply body modifications from stored fault (truncation, corruption).
+  * Returns modified body, or original if no modifications needed.
   */
-  private consumeInjectedError;
+  private applyFaultBodyModification;
   private handleRequest;
   /**
   * Handle PUT - create stream

package/dist/index.d.ts

@@ -56,6 +56,11 @@ interface Stream {
   * Timestamp when the stream was created.
   */
   createdAt: number;
+  /**
+  * Producer states for idempotent writes.
+  * Maps producer ID to their epoch and sequence state.
+  */
+  producers?: Map<string, ProducerState>;
 }
 /**
 * Event data for stream lifecycle hooks.
@@ -131,6 +136,49 @@ interface TestServerOptions {
   cursorEpoch?: Date;
 }
 /**
+* Producer state for idempotent writes.
+* Tracks epoch and sequence number per producer ID for deduplication.
+*/
+interface ProducerState {
+  /**
+  * Current epoch for this producer.
+  * Client-declared, server-validated monotonically increasing.
+  */
+  epoch: number;
+  /**
+  * Last sequence number received in this epoch.
+  */
+  lastSeq: number;
+  /**
+  * Timestamp when this producer state was last updated.
+  * Used for TTL-based cleanup.
+  */
+  lastUpdated: number;
+}
+/**
+* Result of producer validation for append operations.
+* For 'accepted' status, includes proposedState to commit after successful append.
+*/
+type ProducerValidationResult = {
+  status: `accepted`;
+  isNew: boolean;
+  /** State to commit after successful append (deferred mutation) */
+  proposedState: ProducerState;
+  producerId: string;
+} | {
+  status: `duplicate`;
+  lastSeq: number;
+} | {
+  status: `stale_epoch`;
+  currentEpoch: number;
+} | {
+  status: `invalid_epoch_seq`;
+} | {
+  status: `sequence_gap`;
+  expectedSeq: number;
+  receivedSeq: number;
+};
+/**
 * Pending long-poll request.
 */
 interface PendingLongPoll {
@@ -155,10 +203,32 @@ interface PendingLongPoll {
 /**
 * In-memory store for durable streams.
 */
+/**
+* Options for append operations.
+*/
+interface AppendOptions {
+  seq?: string;
+  contentType?: string;
+  producerId?: string;
+  producerEpoch?: number;
+  producerSeq?: number;
+}
+/**
+* Result of an append operation.
+*/
+interface AppendResult {
+  message: StreamMessage | null;
+  producerResult?: ProducerValidationResult;
+}
 declare class StreamStore {
   private streams;
   private pendingLongPolls;
   /**
+  * Per-producer locks for serializing validation+append operations.
+  * Key: "{streamPath}:{producerId}"
+  */
+  private producerLocks;
+  /**
   * Check if a stream is expired based on TTL or Expires-At.
   */
   private isExpired;
@@ -192,15 +262,47 @@ declare class StreamStore {
   */
   delete(path: string): boolean;
   /**
+  * Validate producer state WITHOUT mutating.
+  * Returns proposed state to commit after successful append.
+  * Implements Kafka-style idempotent producer validation.
+  *
+  * IMPORTANT: This function does NOT mutate producer state. The caller must
+  * call commitProducerState() after successful append to apply the mutation.
+  * This ensures atomicity: if append fails (e.g., JSON validation), producer
+  * state is not incorrectly advanced.
+  */
+  private validateProducer;
+  /**
+  * Commit producer state after successful append.
+  * This is the only place where producer state is mutated.
+  */
+  private commitProducerState;
+  /**
+  * Clean up expired producer states from a stream.
+  */
+  private cleanupExpiredProducers;
+  /**
+  * Acquire a lock for serialized producer operations.
+  * Returns a release function.
+  */
+  private acquireProducerLock;
+  /**
   * 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;
+  append(path: string, data: Uint8Array, options?: AppendOptions): StreamMessage | AppendResult;
+  /**
+  * Append with producer serialization for concurrent request handling.
+  * This ensures that validation+append is atomic per producer.
+  */
+  appendWithProducer(path: string, data: Uint8Array, options: AppendOptions): Promise<AppendResult>;
+  /**
+  * Get the current epoch for a producer on a stream.
+  * Returns undefined if the producer doesn't exist or stream not found.
+  */
+  getProducerEpoch(path: string, producerId: string): number | undefined;
   /**
   * Read messages from a stream starting at the given offset.
   * @throws Error if stream doesn't exist or is expired
@@ -261,6 +363,11 @@ declare class FileBackedStreamStore {
   private fileHandlePool;
   private pendingLongPolls;
   private dataDir;
+  /**
+  * Per-producer locks for serializing validation+append operations.
+  * Key: "{streamPath}:{producerId}"
+  */
+  private producerLocks;
   constructor(options: FileBackedStreamStoreOptions);
   /**
   * Recover streams from disk on startup.
@@ -277,6 +384,25 @@ declare class FileBackedStreamStore {
   */
   private streamMetaToStream;
   /**
+  * Validate producer state WITHOUT mutating.
+  * Returns proposed state to commit after successful append.
+  *
+  * IMPORTANT: This function does NOT mutate producer state. The caller must
+  * commit the proposedState after successful append (file write + fsync + LMDB).
+  * This ensures atomicity: if any step fails, producer state is not advanced.
+  */
+  private validateProducer;
+  /**
+  * Acquire a lock for serialized producer operations.
+  * Returns a release function.
+  */
+  private acquireProducerLock;
+  /**
+  * Get the current epoch for a producer on a stream.
+  * Returns undefined if the producer doesn't exist or stream not found.
+  */
+  getProducerEpoch(streamPath: string, producerId: string): number | undefined;
+  /**
   * Check if a stream is expired based on TTL or Expires-At.
   */
   private isExpired;
@@ -299,11 +425,14 @@ declare class FileBackedStreamStore {
   get(streamPath: string): Stream | undefined;
   has(streamPath: string): boolean;
   delete(streamPath: string): boolean;
-  append(streamPath: string, data: Uint8Array, options?: {
-    seq?: string;
-    contentType?: string;
+  append(streamPath: string, data: Uint8Array, options?: AppendOptions & {
     isInitialCreate?: boolean;
-  }): Promise<StreamMessage | null>;
+  }): Promise<StreamMessage | AppendResult | null>;
+  /**
+  * Append with producer serialization for concurrent request handling.
+  * This ensures that validation+append is atomic per producer.
+  */
+  appendWithProducer(streamPath: string, data: Uint8Array, options: AppendOptions): Promise<AppendResult>;
   read(streamPath: string, offset?: string): {
     messages: Array<StreamMessage>;
     upToDate: boolean;
@@ -332,6 +461,36 @@ declare class FileBackedStreamStore {
 
 //#endregion
 //#region src/server.d.ts
+/**
+* HTTP server for testing durable streams.
+* Supports both in-memory and file-backed storage modes.
+*/
+/**
+* Configuration for injected faults (for testing retry/resilience).
+* Supports various fault types beyond simple HTTP errors.
+*/
+interface InjectedFault {
+  /** HTTP status code to return (if set, returns error response) */
+  status?: number;
+  /** Number of times to trigger this fault (decremented on each use) */
+  count: number;
+  /** Optional Retry-After header value (seconds) */
+  retryAfter?: number;
+  /** Delay in milliseconds before responding */
+  delayMs?: number;
+  /** Drop the connection after sending headers (simulates network failure) */
+  dropConnection?: boolean;
+  /** Truncate response body to this many bytes */
+  truncateBodyBytes?: number;
+  /** Probability of triggering fault (0-1, default 1.0 = always) */
+  probability?: number;
+  /** Only match specific HTTP method (GET, POST, PUT, DELETE) */
+  method?: string;
+  /** Corrupt the response body by flipping random bits */
+  corruptBody?: boolean;
+  /** Add jitter to delay (random 0-jitterMs added to delayMs) */
+  jitterMs?: number;
+}
 declare class DurableStreamTestServer {
   readonly store: StreamStore | FileBackedStreamStore;
   private server;
@@ -339,8 +498,8 @@ declare class DurableStreamTestServer {
   private _url;
   private activeSSEResponses;
   private isShuttingDown;
-  /** Injected errors for testing retry/resilience */
-  private injectedErrors;
+  /** Injected faults for testing retry/resilience */
+  private injectedFaults;
   constructor(options?: TestServerOptions);
   /**
   * Start the server.
@@ -361,17 +520,34 @@ declare class DurableStreamTestServer {
   /**
   * Inject an error to be returned on the next N requests to a path.
   * Used for testing retry/resilience behavior.
+  * @deprecated Use injectFault for full fault injection capabilities
   */
   injectError(path: string, status: number, count?: number, retryAfter?: number): void;
   /**
-  * Clear all injected errors.
+  * Inject a fault to be triggered on the next N requests to a path.
+  * Supports various fault types: delays, connection drops, body corruption, etc.
+  */
+  injectFault(path: string, fault: Omit<InjectedFault, `count`> & {
+    count?: number;
+  }): void;
+  /**
+  * Clear all injected faults.
+  */
+  clearInjectedFaults(): void;
+  /**
+  * Check if there's an injected fault for this path/method and consume it.
+  * Returns the fault config if one should be triggered, null otherwise.
+  */
+  private consumeInjectedFault;
+  /**
+  * Apply delay from fault config (including jitter).
   */
-  clearInjectedErrors(): void;
+  private applyFaultDelay;
   /**
-  * Check if there's an injected error for this path and consume it.
-  * Returns the error config if one should be returned, null otherwise.
+  * Apply body modifications from stored fault (truncation, corruption).
+  * Returns modified body, or original if no modifications needed.
   */
-  private consumeInjectedError;
+  private applyFaultBodyModification;
   private handleRequest;
   /**
   * Handle PUT - create stream