@durable-streams/server 0.1.3 → 0.1.5

package/src/server.ts

@@ -19,6 +19,13 @@ const STREAM_SEQ_HEADER = `Stream-Seq`
 const STREAM_TTL_HEADER = `Stream-TTL`
 const STREAM_EXPIRES_AT_HEADER = `Stream-Expires-At`
 
+// Idempotent producer headers
+const PRODUCER_ID_HEADER = `Producer-Id`
+const PRODUCER_EPOCH_HEADER = `Producer-Epoch`
+const PRODUCER_SEQ_HEADER = `Producer-Seq`
+const PRODUCER_EXPECTED_SEQ_HEADER = `Producer-Expected-Seq`
+const PRODUCER_RECEIVED_SEQ_HEADER = `Producer-Received-Seq`
+
 // SSE control event fields (Protocol Section 5.7)
 const SSE_OFFSET_FIELD = `streamNextOffset`
 const SSE_CURSOR_FIELD = `streamCursor`
@@ -32,10 +39,14 @@ const CURSOR_QUERY_PARAM = `cursor`
 /**
  * Encode data for SSE format.
  * Per SSE spec, each line in the payload needs its own "data:" prefix.
- * Newlines in the payload become separate data: lines.
+ * Line terminators in the payload (CR, LF, or CRLF) become separate data: lines.
+ * This prevents CRLF injection attacks where malicious payloads could inject
+ * fake SSE events using CR-only line terminators.
  */
 function encodeSSEData(payload: string): string {
-  const lines = payload.split(`\n`)
+  // Split on all SSE-valid line terminators: CRLF, CR, or LF
+  // Order matters: \r\n must be matched before \r alone
+  const lines = payload.split(/\r\n|\r|\n/)
   return lines.map((line) => `data: ${line}`).join(`\n`) + `\n\n`
 }
 
@@ -92,15 +103,30 @@ function compressData(
  * Supports both in-memory and file-backed storage modes.
  */
 /**
- * Configuration for injected errors (for testing retry/resilience).
+ * Configuration for injected faults (for testing retry/resilience).
+ * Supports various fault types beyond simple HTTP errors.
  */
-interface InjectedError {
-  /** HTTP status code to return */
-  status: number
-  /** Number of times to return this error (decremented on each use) */
+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
 }
 
 export class DurableStreamTestServer {
@@ -126,8 +152,8 @@ export class DurableStreamTestServer {
   private _url: string | null = null
   private activeSSEResponses = new Set<ServerResponse>()
   private isShuttingDown = false
-  /** Injected errors for testing retry/resilience */
-  private injectedErrors = new Map<string, InjectedError>()
+  /** Injected faults for testing retry/resilience */
+  private injectedFaults = new Map<string, InjectedFault>()
 
   constructor(options: TestServerOptions = {}) {
     // Choose store based on dataDir option
@@ -253,6 +279,7 @@ export 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,
@@ -260,30 +287,102 @@ export class DurableStreamTestServer {
     count: number = 1,
     retryAfter?: number
   ): void {
-    this.injectedErrors.set(path, { status, count, retryAfter })
+    this.injectedFaults.set(path, { status, count, retryAfter })
+  }
+
+  /**
+   * 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 {
+    this.injectedFaults.set(path, { count: 1, ...fault })
+  }
+
+  /**
+   * Clear all injected faults.
+   */
+  clearInjectedFaults(): void {
+    this.injectedFaults.clear()
+  }
+
+  /**
+   * 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(
+    path: string,
+    method: string
+  ): InjectedFault | null {
+    const fault = this.injectedFaults.get(path)
+    if (!fault) return null
+
+    // Check method filter
+    if (fault.method && fault.method.toUpperCase() !== method.toUpperCase()) {
+      return null
+    }
+
+    // Check probability
+    if (fault.probability !== undefined && Math.random() > fault.probability) {
+      return null
+    }
+
+    fault.count--
+    if (fault.count <= 0) {
+      this.injectedFaults.delete(path)
+    }
+
+    return fault
   }
 
   /**
-   * Clear all injected errors.
+   * Apply delay from fault config (including jitter).
    */
-  clearInjectedErrors(): void {
-    this.injectedErrors.clear()
+  private async applyFaultDelay(fault: InjectedFault): Promise<void> {
+    if (fault.delayMs !== undefined && fault.delayMs > 0) {
+      const jitter = fault.jitterMs ? Math.random() * fault.jitterMs : 0
+      await new Promise((resolve) =>
+        setTimeout(resolve, fault.delayMs! + jitter)
+      )
+    }
   }
 
   /**
-   * 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(path: string): InjectedError | null {
-    const error = this.injectedErrors.get(path)
-    if (!error) return null
+  private applyFaultBodyModification(
+    res: ServerResponse,
+    body: Uint8Array
+  ): Uint8Array {
+    const fault = (res as ServerResponse & { _injectedFault?: InjectedFault })
+      ._injectedFault
+    if (!fault) return body
+
+    let modified = body
 
-    error.count--
-    if (error.count <= 0) {
-      this.injectedErrors.delete(path)
+    // Truncate body if configured
+    if (
+      fault.truncateBodyBytes !== undefined &&
+      modified.length > fault.truncateBodyBytes
+    ) {
+      modified = modified.slice(0, fault.truncateBodyBytes)
+    }
+
+    // Corrupt body if configured (flip random bits)
+    if (fault.corruptBody && modified.length > 0) {
+      modified = new Uint8Array(modified) // Make a copy to avoid mutating original
+      // Flip 1-5% of bytes
+      const numCorrupt = Math.max(1, Math.floor(modified.length * 0.03))
+      for (let i = 0; i < numCorrupt; i++) {
+        const pos = Math.floor(Math.random() * modified.length)
+        modified[pos] = modified[pos]! ^ (1 << Math.floor(Math.random() * 8))
+      }
     }
 
-    return error
+    return modified
   }
 
   // ============================================================================
@@ -306,13 +405,17 @@ export class DurableStreamTestServer {
     )
     res.setHeader(
       `access-control-allow-headers`,
-      `content-type, authorization, Stream-Seq, Stream-TTL, Stream-Expires-At`
+      `content-type, authorization, Stream-Seq, Stream-TTL, Stream-Expires-At, Producer-Id, Producer-Epoch, Producer-Seq`
     )
     res.setHeader(
       `access-control-expose-headers`,
-      `Stream-Next-Offset, Stream-Cursor, Stream-Up-To-Date, etag, content-type, content-encoding, vary`
+      `Stream-Next-Offset, Stream-Cursor, Stream-Up-To-Date, Producer-Epoch, Producer-Seq, Producer-Expected-Seq, Producer-Received-Seq, etag, content-type, content-encoding, vary`
     )
 
+    // Browser security headers (Protocol Section 10.7)
+    res.setHeader(`x-content-type-options`, `nosniff`)
+    res.setHeader(`cross-origin-resource-policy`, `cross-origin`)
+
     // Handle CORS preflight
     if (method === `OPTIONS`) {
       res.writeHead(204)
@@ -326,18 +429,37 @@ export class DurableStreamTestServer {
       return
     }
 
-    // Check for injected errors (for testing retry/resilience)
-    const injectedError = this.consumeInjectedError(path)
-    if (injectedError) {
-      const headers: Record<string, string> = {
-        "content-type": `text/plain`,
+    // Check for injected faults (for testing retry/resilience)
+    const fault = this.consumeInjectedFault(path, method ?? `GET`)
+    if (fault) {
+      // Apply delay if configured
+      await this.applyFaultDelay(fault)
+
+      // Drop connection if configured (simulates network failure)
+      if (fault.dropConnection) {
+        res.socket?.destroy()
+        return
       }
-      if (injectedError.retryAfter !== undefined) {
-        headers[`retry-after`] = injectedError.retryAfter.toString()
+
+      // If status is set, return an error response
+      if (fault.status !== undefined) {
+        const headers: Record<string, string> = {
+          "content-type": `text/plain`,
+        }
+        if (fault.retryAfter !== undefined) {
+          headers[`retry-after`] = fault.retryAfter.toString()
+        }
+        res.writeHead(fault.status, headers)
+        res.end(`Injected error for testing`)
+        return
+      }
+
+      // Store fault for response modification (truncation, corruption)
+      if (fault.truncateBodyBytes !== undefined || fault.corruptBody) {
+        ;(
+          res as ServerResponse & { _injectedFault?: InjectedFault }
+        )._injectedFault = fault
       }
-      res.writeHead(injectedError.status, headers)
-      res.end(`Injected error for testing`)
-      return
     }
 
     try {
@@ -511,6 +633,8 @@ export class DurableStreamTestServer {
 
     const headers: Record<string, string> = {
       [STREAM_OFFSET_HEADER]: stream.currentOffset,
+      // HEAD responses should not be cached to avoid stale tail offsets (Protocol Section 5.4)
+      "cache-control": `no-store`,
     }
 
     if (stream.contentType) {
@@ -562,9 +686,9 @@ export class DurableStreamTestServer {
         return
       }
 
-      // Validate offset format: must be "-1" or match our offset format (digits_digits)
+      // Validate offset format: must be "-1", "now", or match our offset format (digits_digits)
       // This prevents path traversal, injection attacks, and invalid characters
-      const validOffsetPattern = /^(-1|\d+_\d+)$/
+      const validOffsetPattern = /^(-1|now|\d+_\d+)$/
       if (!validOffsetPattern.test(offset)) {
         res.writeHead(400, { "content-type": `text/plain` })
         res.end(`Invalid offset format`)
@@ -583,23 +707,57 @@ export class DurableStreamTestServer {
 
     // Handle SSE mode
     if (live === `sse`) {
-      await this.handleSSE(path, stream, offset!, cursor, res)
+      // For SSE with offset=now, convert to actual tail offset
+      const sseOffset = offset === `now` ? stream.currentOffset : offset!
+      await this.handleSSE(path, stream, sseOffset, cursor, res)
+      return
+    }
+
+    // For offset=now, convert to actual tail offset
+    // This allows long-poll to immediately start waiting for new data
+    const effectiveOffset = offset === `now` ? stream.currentOffset : offset
+
+    // Handle catch-up mode offset=now: return empty response with tail offset
+    // For long-poll mode, we fall through to wait for new data instead
+    if (offset === `now` && live !== `long-poll`) {
+      const headers: Record<string, string> = {
+        [STREAM_OFFSET_HEADER]: stream.currentOffset,
+        [STREAM_UP_TO_DATE_HEADER]: `true`,
+        // Prevent caching - tail offset changes with each append
+        [`cache-control`]: `no-store`,
+      }
+
+      if (stream.contentType) {
+        headers[`content-type`] = stream.contentType
+      }
+
+      // No ETag for offset=now responses - Cache-Control: no-store makes ETag unnecessary
+      // and some CDNs may behave unexpectedly with both headers
+
+      // For JSON mode, return empty array; otherwise empty body
+      const isJsonMode = stream.contentType?.includes(`application/json`)
+      const responseBody = isJsonMode ? `[]` : ``
+
+      res.writeHead(200, headers)
+      res.end(responseBody)
       return
     }
 
     // Read current messages
-    let { messages, upToDate } = this.store.read(path, offset)
+    let { messages, upToDate } = this.store.read(path, effectiveOffset)
 
     // Only wait in long-poll if:
     // 1. long-poll mode is enabled
-    // 2. Client provided an offset (not first request)
+    // 2. Client provided an offset (not first request) OR used offset=now
     // 3. Client's offset matches current offset (already caught up)
     // 4. No new messages
-    const clientIsCaughtUp = offset && offset === stream.currentOffset
+    const clientIsCaughtUp =
+      (effectiveOffset && effectiveOffset === stream.currentOffset) ||
+      offset === `now`
     if (live === `long-poll` && clientIsCaughtUp && messages.length === 0) {
       const result = await this.store.waitForMessages(
         path,
-        offset,
+        effectiveOffset ?? stream.currentOffset,
         this.options.longPollTimeout
       )
 
@@ -611,7 +769,7 @@ export class DurableStreamTestServer {
           this.options.cursorOptions
         )
         res.writeHead(204, {
-          [STREAM_OFFSET_HEADER]: offset,
+          [STREAM_OFFSET_HEADER]: effectiveOffset ?? stream.currentOffset,
           [STREAM_UP_TO_DATE_HEADER]: `true`,
           [STREAM_CURSOR_HEADER]: responseCursor,
         })
@@ -680,6 +838,9 @@ export class DurableStreamTestServer {
       }
     }
 
+    // Apply fault body modifications (truncation, corruption) if configured
+    finalData = this.applyFaultBodyModification(res, finalData)
+
     res.writeHead(200, headers)
     res.end(Buffer.from(finalData))
   }
@@ -697,12 +858,14 @@ export class DurableStreamTestServer {
     // Track this SSE connection
     this.activeSSEResponses.add(res)
 
-    // Set SSE headers
+    // Set SSE headers (explicitly including security headers for clarity)
     res.writeHead(200, {
       "content-type": `text/event-stream`,
       "cache-control": `no-cache`,
       connection: `keep-alive`,
       "access-control-allow-origin": `*`,
+      "x-content-type-options": `nosniff`,
+      "cross-origin-resource-policy": `cross-origin`,
     })
 
     let currentOffset = initialOffset
@@ -819,6 +982,17 @@ export class DurableStreamTestServer {
       | string
       | undefined
 
+    // Extract producer headers
+    const producerId = req.headers[PRODUCER_ID_HEADER.toLowerCase()] as
+      | string
+      | undefined
+    const producerEpochStr = req.headers[
+      PRODUCER_EPOCH_HEADER.toLowerCase()
+    ] as string | undefined
+    const producerSeqStr = req.headers[PRODUCER_SEQ_HEADER.toLowerCase()] as
+      | string
+      | undefined
+
     const body = await this.readBody(req)
 
     if (body.length === 0) {
@@ -834,15 +1008,148 @@ export class DurableStreamTestServer {
       return
     }
 
-    // Support both sync (StreamStore) and async (FileBackedStreamStore) append
-    // Note: append returns null only for empty arrays with isInitialCreate=true,
-    // which doesn't apply to POST requests (those throw on empty arrays)
-    const message = await Promise.resolve(
-      this.store.append(path, body, { seq, contentType })
-    )
+    // Validate producer headers - all three must be present together or none
+    // Also reject empty producer ID
+    const hasProducerHeaders =
+      producerId !== undefined ||
+      producerEpochStr !== undefined ||
+      producerSeqStr !== undefined
+    const hasAllProducerHeaders =
+      producerId !== undefined &&
+      producerEpochStr !== undefined &&
+      producerSeqStr !== undefined
+
+    if (hasProducerHeaders && !hasAllProducerHeaders) {
+      res.writeHead(400, { "content-type": `text/plain` })
+      res.end(
+        `All producer headers (Producer-Id, Producer-Epoch, Producer-Seq) must be provided together`
+      )
+      return
+    }
 
-    res.writeHead(200, {
-      [STREAM_OFFSET_HEADER]: message!.offset,
+    if (hasAllProducerHeaders && producerId === ``) {
+      res.writeHead(400, { "content-type": `text/plain` })
+      res.end(`Invalid Producer-Id: must not be empty`)
+      return
+    }
+
+    // Parse and validate producer epoch and seq as integers
+    // Use strict digit-only validation to reject values like "1abc" or "1e3"
+    const STRICT_INTEGER_REGEX = /^\d+$/
+    let producerEpoch: number | undefined
+    let producerSeq: number | undefined
+    if (hasAllProducerHeaders) {
+      if (!STRICT_INTEGER_REGEX.test(producerEpochStr)) {
+        res.writeHead(400, { "content-type": `text/plain` })
+        res.end(`Invalid Producer-Epoch: must be a non-negative integer`)
+        return
+      }
+      producerEpoch = Number(producerEpochStr)
+      if (!Number.isSafeInteger(producerEpoch)) {
+        res.writeHead(400, { "content-type": `text/plain` })
+        res.end(`Invalid Producer-Epoch: must be a non-negative integer`)
+        return
+      }
+
+      if (!STRICT_INTEGER_REGEX.test(producerSeqStr)) {
+        res.writeHead(400, { "content-type": `text/plain` })
+        res.end(`Invalid Producer-Seq: must be a non-negative integer`)
+        return
+      }
+      producerSeq = Number(producerSeqStr)
+      if (!Number.isSafeInteger(producerSeq)) {
+        res.writeHead(400, { "content-type": `text/plain` })
+        res.end(`Invalid Producer-Seq: must be a non-negative integer`)
+        return
+      }
+    }
+
+    // Build append options
+    const appendOptions = {
+      seq,
+      contentType,
+      producerId,
+      producerEpoch,
+      producerSeq,
+    }
+
+    // Use appendWithProducer for serialized producer operations
+    let result
+    if (producerId !== undefined) {
+      result = await this.store.appendWithProducer(path, body, appendOptions)
+    } else {
+      result = await Promise.resolve(
+        this.store.append(path, body, appendOptions)
+      )
+    }
+
+    // Handle AppendResult with producer validation
+    if (result && typeof result === `object` && `producerResult` in result) {
+      const { message, producerResult } = result
+
+      if (!producerResult || producerResult.status === `accepted`) {
+        // Success - return offset
+        const responseHeaders: Record<string, string> = {
+          [STREAM_OFFSET_HEADER]: message!.offset,
+        }
+        // Echo back the producer epoch and seq (highest accepted)
+        if (producerEpoch !== undefined) {
+          responseHeaders[PRODUCER_EPOCH_HEADER] = producerEpoch.toString()
+        }
+        if (producerSeq !== undefined) {
+          responseHeaders[PRODUCER_SEQ_HEADER] = producerSeq.toString()
+        }
+        res.writeHead(200, responseHeaders)
+        res.end()
+        return
+      }
+
+      // Handle producer validation failures
+      switch (producerResult.status) {
+        case `duplicate`:
+          // 204 No Content for duplicates (idempotent success)
+          // Return Producer-Seq as highest accepted (per PROTOCOL.md)
+          res.writeHead(204, {
+            [PRODUCER_EPOCH_HEADER]: producerEpoch!.toString(),
+            [PRODUCER_SEQ_HEADER]: producerResult.lastSeq.toString(),
+          })
+          res.end()
+          return
+
+        case `stale_epoch`: {
+          // 403 Forbidden for stale epochs (zombie fencing)
+          res.writeHead(403, {
+            "content-type": `text/plain`,
+            [PRODUCER_EPOCH_HEADER]: producerResult.currentEpoch.toString(),
+          })
+          res.end(`Stale producer epoch`)
+          return
+        }
+
+        case `invalid_epoch_seq`:
+          // 400 Bad Request for epoch increase with seq != 0
+          res.writeHead(400, { "content-type": `text/plain` })
+          res.end(`New epoch must start with sequence 0`)
+          return
+
+        case `sequence_gap`:
+          // 409 Conflict for sequence gaps
+          res.writeHead(409, {
+            "content-type": `text/plain`,
+            [PRODUCER_EXPECTED_SEQ_HEADER]:
+              producerResult.expectedSeq.toString(),
+            [PRODUCER_RECEIVED_SEQ_HEADER]:
+              producerResult.receivedSeq.toString(),
+          })
+          res.end(`Producer sequence gap`)
+          return
+      }
+    }
+
+    // Standard append (no producer) - result is StreamMessage
+    const message = result as { offset: string }
+    res.writeHead(204, {
+      [STREAM_OFFSET_HEADER]: message.offset,
     })
     res.end()
   }
@@ -889,23 +1196,53 @@ export class DurableStreamTestServer {
       try {
         const config = JSON.parse(new TextDecoder().decode(body)) as {
           path: string
-          status: number
+          // Legacy fields (still supported)
+          status?: number
           count?: number
           retryAfter?: number
+          // New fault injection fields
+          delayMs?: number
+          dropConnection?: boolean
+          truncateBodyBytes?: number
+          probability?: number
+          method?: string
+          corruptBody?: boolean
+          jitterMs?: number
         }
 
-        if (!config.path || !config.status) {
+        if (!config.path) {
           res.writeHead(400, { "content-type": `text/plain` })
-          res.end(`Missing required fields: path, status`)
+          res.end(`Missing required field: path`)
           return
         }
 
-        this.injectError(
-          config.path,
-          config.status,
-          config.count ?? 1,
-          config.retryAfter
-        )
+        // Must have at least one fault type specified
+        const hasFaultType =
+          config.status !== undefined ||
+          config.delayMs !== undefined ||
+          config.dropConnection ||
+          config.truncateBodyBytes !== undefined ||
+          config.corruptBody
+        if (!hasFaultType) {
+          res.writeHead(400, { "content-type": `text/plain` })
+          res.end(
+            `Must specify at least one fault type: status, delayMs, dropConnection, truncateBodyBytes, or corruptBody`
+          )
+          return
+        }
+
+        this.injectFault(config.path, {
+          status: config.status,
+          count: config.count ?? 1,
+          retryAfter: config.retryAfter,
+          delayMs: config.delayMs,
+          dropConnection: config.dropConnection,
+          truncateBodyBytes: config.truncateBodyBytes,
+          probability: config.probability,
+          method: config.method,
+          corruptBody: config.corruptBody,
+          jitterMs: config.jitterMs,
+        })
 
         res.writeHead(200, { "content-type": `application/json` })
         res.end(JSON.stringify({ ok: true }))
@@ -914,7 +1251,7 @@ export class DurableStreamTestServer {
         res.end(`Invalid JSON body`)
       }
     } else if (method === `DELETE`) {
-      this.clearInjectedErrors()
+      this.clearInjectedFaults()
       res.writeHead(200, { "content-type": `application/json` })
       res.end(JSON.stringify({ ok: true }))
     } else {