@durable-streams/client 0.2.0 → 0.2.1

package/src/constants.ts

@@ -26,6 +26,12 @@ export const STREAM_CURSOR_HEADER = `Stream-Cursor`
  */
 export const STREAM_UP_TO_DATE_HEADER = `Stream-Up-To-Date`
 
+/**
+ * Response/request header indicating stream is closed (EOF).
+ * When present with value "true", the stream is permanently closed.
+ */
+export const STREAM_CLOSED_HEADER = `Stream-Closed`
+
 // ============================================================================
 // Request Headers
 // ============================================================================
@@ -97,6 +103,11 @@ export const LIVE_QUERY_PARAM = `live`
  */
 export const CURSOR_QUERY_PARAM = `cursor`
 
+/**
+ * Response header indicating SSE data encoding (e.g., base64 for binary streams).
+ */
+export const STREAM_SSE_DATA_ENCODING_HEADER = `stream-sse-data-encoding`
+
 // ============================================================================
 // SSE Control Event Fields (camelCase per PROTOCOL.md Section 5.7)
 // ============================================================================
@@ -113,13 +124,19 @@ export const SSE_OFFSET_FIELD = `streamNextOffset`
  */
 export const SSE_CURSOR_FIELD = `streamCursor`
 
+/**
+ * SSE control event field for stream closed state.
+ * Note: Different from HTTP header name (camelCase vs Header-Case).
+ */
+export const SSE_CLOSED_FIELD = `streamClosed`
+
 // ============================================================================
 // Internal Constants
 // ============================================================================
 
 /**
- * Content types that support SSE mode.
- * SSE is only valid for text/* or application/json streams.
+ * Content types that are natively compatible with SSE (UTF-8 text).
+ * Binary content types are also supported via automatic base64 encoding.
  */
 export const SSE_COMPATIBLE_CONTENT_TYPES: ReadonlyArray<string> = [
   `text/`,

package/src/error.ts

@@ -178,6 +178,26 @@ export class MissingStreamUrlError extends Error {
   }
 }
 
+/**
+ * Error thrown when attempting to append to a closed stream.
+ */
+export class StreamClosedError extends DurableStreamError {
+  readonly code = `STREAM_CLOSED` as const
+  readonly status = 409
+  readonly streamClosed = true
+
+  /**
+   * The final offset of the stream, if available from the response.
+   */
+  readonly finalOffset?: string
+
+  constructor(url?: string, finalOffset?: string) {
+    super(`Cannot append to closed stream`, `STREAM_CLOSED`, 409, url)
+    this.name = `StreamClosedError`
+    this.finalOffset = finalOffset
+  }
+}
+
 /**
  * Error thrown when signal option is invalid.
  */

package/src/idempotent-producer.ts

@@ -17,11 +17,12 @@ import {
   PRODUCER_ID_HEADER,
   PRODUCER_RECEIVED_SEQ_HEADER,
   PRODUCER_SEQ_HEADER,
+  STREAM_CLOSED_HEADER,
   STREAM_OFFSET_HEADER,
 } from "./constants"
 import type { queueAsPromised } from "fastq"
 import type { DurableStream } from "./stream"
-import type { IdempotentProducerOptions, Offset } from "./types"
+import type { CloseResult, IdempotentProducerOptions, Offset } from "./types"
 
 /**
  * Error thrown when a producer's epoch is stale (zombie fencing).
@@ -138,6 +139,8 @@ export class IdempotentProducer {
   readonly #queue: queueAsPromised<BatchTask>
   readonly #maxInFlight: number
   #closed = false
+  #closeResult: CloseResult | null = null
+  #pendingFinalMessage?: Uint8Array | string
 
   // When autoClaim is true, we must wait for the first batch to complete
   // before allowing pipelining (to know what epoch was claimed)
@@ -318,11 +321,17 @@ export class IdempotentProducer {
   }
 
   /**
-   * Flush pending messages and close the producer.
+   * Stop the producer without closing the underlying stream.
    *
-   * After calling close(), further append() calls will throw.
+   * Use this when you want to:
+   * - Hand off writing to another producer
+   * - Keep the stream open for future writes
+   * - Stop this producer but not signal EOF to readers
+   *
+   * Flushes any pending messages before detaching.
+   * After calling detach(), further append() calls will throw.
    */
-  async close(): Promise<void> {
+  async detach(): Promise<void> {
     if (this.#closed) return
 
     this.#closed = true
@@ -330,8 +339,138 @@ export class IdempotentProducer {
     try {
       await this.flush()
     } catch {
-      // Ignore errors during close
+      // Ignore errors during detach
+    }
+  }
+
+  /**
+   * Flush pending messages and close the underlying stream (EOF).
+   *
+   * This is the typical way to end a producer session. It:
+   * 1. Flushes all pending messages
+   * 2. Optionally appends a final message
+   * 3. Closes the stream (no further appends permitted)
+   *
+   * **Idempotent**: Unlike `DurableStream.close({ body })`, this method is
+   * idempotent even with a final message because it uses producer headers
+   * for deduplication. Safe to retry on network failures.
+   *
+   * @param finalMessage - Optional final message to append atomically with close
+   * @returns CloseResult with the final offset
+   */
+  async close(finalMessage?: Uint8Array | string): Promise<CloseResult> {
+    if (this.#closed) {
+      // Already closed - return cached result for idempotency
+      if (this.#closeResult) {
+        return this.#closeResult
+      }
+      // Retry path: flush() threw on a previous attempt, so we need to re-run
+      // the entire close sequence with the stored finalMessage
+      await this.flush()
+      const result = await this.#doClose(this.#pendingFinalMessage)
+      this.#closeResult = result
+      return result
+    }
+
+    this.#closed = true
+
+    // Store finalMessage for retry safety (if flush() throws, we can retry)
+    this.#pendingFinalMessage = finalMessage
+
+    // Flush pending messages first
+    await this.flush()
+
+    // Close the stream with optional final message
+    const result = await this.#doClose(finalMessage)
+    this.#closeResult = result
+    return result
+  }
+
+  /**
+   * Actually close the stream with optional final message.
+   * Uses producer headers for idempotency.
+   */
+  async #doClose(finalMessage?: Uint8Array | string): Promise<CloseResult> {
+    const contentType = this.#stream.contentType ?? `application/octet-stream`
+    const isJson = normalizeContentType(contentType) === `application/json`
+
+    // Build body if final message is provided
+    let body: BodyInit | undefined
+    if (finalMessage !== undefined) {
+      const bodyBytes =
+        typeof finalMessage === `string`
+          ? new TextEncoder().encode(finalMessage)
+          : finalMessage
+
+      if (isJson) {
+        // For JSON mode, wrap in array
+        const jsonStr = new TextDecoder().decode(bodyBytes)
+        body = `[${jsonStr}]`
+      } else {
+        body = bodyBytes as unknown as BodyInit
+      }
+    }
+
+    // Capture the sequence number for this request (for retry safety)
+    // We only increment #nextSeq after a successful response
+    const seqForThisRequest = this.#nextSeq
+
+    // Build headers with producer info and Stream-Closed
+    const headers: Record<string, string> = {
+      "content-type": contentType,
+      [PRODUCER_ID_HEADER]: this.#producerId,
+      [PRODUCER_EPOCH_HEADER]: this.#epoch.toString(),
+      [PRODUCER_SEQ_HEADER]: seqForThisRequest.toString(),
+      [STREAM_CLOSED_HEADER]: `true`,
+    }
+
+    const response = await this.#fetchClient(this.#stream.url, {
+      method: `POST`,
+      headers,
+      body,
+      signal: this.#signal,
+    })
+
+    // Handle 204 (duplicate close - idempotent success)
+    if (response.status === 204) {
+      // Only increment seq on success (retry-safe)
+      this.#nextSeq = seqForThisRequest + 1
+      const finalOffset = response.headers.get(STREAM_OFFSET_HEADER) ?? ``
+      return { finalOffset }
+    }
+
+    // Handle success
+    if (response.status === 200) {
+      // Only increment seq on success (retry-safe)
+      this.#nextSeq = seqForThisRequest + 1
+      const finalOffset = response.headers.get(STREAM_OFFSET_HEADER) ?? ``
+      return { finalOffset }
     }
+
+    // Handle errors
+    if (response.status === 403) {
+      // Stale epoch
+      const currentEpochStr = response.headers.get(PRODUCER_EPOCH_HEADER)
+      const currentEpoch = currentEpochStr
+        ? parseInt(currentEpochStr, 10)
+        : this.#epoch
+
+      if (this.#autoClaim) {
+        // Auto-claim: retry with epoch+1
+        const newEpoch = currentEpoch + 1
+        this.#epoch = newEpoch
+        // Reset sequence for new epoch - set to 0 so the recursive call uses seq 0
+        // (the first operation in a new epoch should be seq 0)
+        this.#nextSeq = 0
+        return this.#doClose(finalMessage)
+      }
+
+      throw new StaleEpochError(currentEpoch)
+    }
+
+    // Other errors
+    const error = await FetchError.fromResponse(response, this.#stream.url)
+    throw error
   }
 
   /**

package/src/index.ts

@@ -65,6 +65,10 @@ export type {
   HeadResult,
   LegacyLiveMode,
 
+  // Close types
+  CloseResult,
+  CloseOptions,
+
   // Idempotent producer types
   IdempotentProducerOptions,
   IdempotentAppendResult,
@@ -89,6 +93,7 @@ export {
   DurableStreamError,
   MissingStreamUrlError,
   InvalidSignalError,
+  StreamClosedError,
 } from "./error"
 
 // ============================================================================
@@ -110,6 +115,7 @@ export {
   STREAM_OFFSET_HEADER,
   STREAM_CURSOR_HEADER,
   STREAM_UP_TO_DATE_HEADER,
+  STREAM_CLOSED_HEADER,
   STREAM_SEQ_HEADER,
   STREAM_TTL_HEADER,
   STREAM_EXPIRES_AT_HEADER,
@@ -117,6 +123,7 @@ export {
   LIVE_QUERY_PARAM,
   CURSOR_QUERY_PARAM,
   SSE_COMPATIBLE_CONTENT_TYPES,
+  SSE_CLOSED_FIELD,
   DURABLE_STREAM_PROTOCOL_QUERY_PARAMS,
   // Idempotent producer headers
   PRODUCER_ID_HEADER,

package/src/response.ts

@@ -7,6 +7,7 @@
 
 import { asAsyncIterableReadableStream } from "./asyncIterableReadableStream"
 import {
+  STREAM_CLOSED_HEADER,
   STREAM_CURSOR_HEADER,
   STREAM_OFFSET_HEADER,
   STREAM_UP_TO_DATE_HEADER,
@@ -55,6 +56,8 @@ export interface StreamResponseConfig {
   initialCursor?: string
   /** Initial upToDate from first response headers */
   initialUpToDate: boolean
+  /** Initial streamClosed from first response headers */
+  initialStreamClosed: boolean
   /** The held first Response object */
   firstResponse: Response
   /** Abort controller for the session */
@@ -74,6 +77,8 @@ export interface StreamResponseConfig {
   ) => Promise<Response>
   /** SSE resilience options */
   sseResilience?: SSEResilienceOptions
+  /** Encoding for SSE data events */
+  encoding?: `base64`
 }
 
 /**
@@ -99,6 +104,7 @@ export class StreamResponseImpl<
   #offset: Offset
   #cursor?: string
   #upToDate: boolean
+  #streamClosed: boolean
 
   // --- Internal state ---
   #isJsonMode: boolean
@@ -125,6 +131,9 @@ export class StreamResponseImpl<
   #consecutiveShortSSEConnections = 0
   #sseFallbackToLongPoll = false
 
+  // --- SSE Encoding State ---
+  #encoding?: `base64`
+
   // Core primitive: a ReadableStream of Response objects
   #responseStream: ReadableStream<Response>
 
@@ -136,6 +145,7 @@ export class StreamResponseImpl<
     this.#offset = config.initialOffset
     this.#cursor = config.initialCursor
     this.#upToDate = config.initialUpToDate
+    this.#streamClosed = config.initialStreamClosed
 
     // Initialize response metadata from first response
     this.#headers = config.firstResponse.headers
@@ -162,6 +172,9 @@ export class StreamResponseImpl<
       logWarnings: config.sseResilience?.logWarnings ?? true,
     }
 
+    // Initialize SSE encoding
+    this.#encoding = config.encoding
+
     this.#closed = new Promise((resolve, reject) => {
       this.#closedResolve = resolve
       this.#closedReject = reject
@@ -298,6 +311,10 @@ export class StreamResponseImpl<
     return this.#upToDate
   }
 
+  get streamClosed(): boolean {
+    return this.#streamClosed
+  }
+
   // =================================
   // Internal helpers
   // =================================
@@ -338,13 +355,15 @@ export class StreamResponseImpl<
 
   /**
    * Determine if we should continue with live updates based on live mode
-   * and whether we've received upToDate.
+   * and whether we've received upToDate or streamClosed.
    */
   #shouldContinueLive(): boolean {
     // Stop if we've received upToDate and a consumption method wants to stop after upToDate
     if (this.#stopAfterUpToDate && this.upToDate) return false
     // Stop if live mode is explicitly disabled
     if (this.live === false) return false
+    // Stop if stream is closed (EOF) - no more data will ever be appended
+    if (this.#streamClosed) return false
     return true
   }
 
@@ -358,6 +377,10 @@ export class StreamResponseImpl<
     const cursor = response.headers.get(STREAM_CURSOR_HEADER)
     if (cursor) this.#cursor = cursor
     this.#upToDate = response.headers.has(STREAM_UP_TO_DATE_HEADER)
+    const streamClosedHeader = response.headers.get(STREAM_CLOSED_HEADER)
+    if (streamClosedHeader?.toLowerCase() === `true`) {
+      this.#streamClosed = true
+    }
 
     // Update response metadata to reflect latest server response
     this.#headers = response.headers
@@ -368,7 +391,7 @@ export class StreamResponseImpl<
 
   /**
    * Extract stream metadata from Response headers.
-   * Used by subscriber APIs to get the correct offset/cursor/upToDate for each
+   * Used by subscriber APIs to get the correct offset/cursor/upToDate/streamClosed for each
    * specific Response, rather than reading from `this` which may be stale due to
    * ReadableStream prefetching or timing issues.
    */
@@ -376,26 +399,94 @@ export class StreamResponseImpl<
     offset: Offset
     cursor: string | undefined
     upToDate: boolean
+    streamClosed: boolean
   } {
     const offset = response.headers.get(STREAM_OFFSET_HEADER)
     const cursor = response.headers.get(STREAM_CURSOR_HEADER)
     const upToDate = response.headers.has(STREAM_UP_TO_DATE_HEADER)
+    const streamClosed =
+      response.headers.get(STREAM_CLOSED_HEADER)?.toLowerCase() === `true`
     return {
       offset: offset ?? this.offset, // Fall back to instance state if no header
       cursor: cursor ?? this.cursor,
       upToDate,
+      streamClosed: streamClosed || this.streamClosed, // Once closed, always closed
+    }
+  }
+
+  /**
+   * Decode base64 string to Uint8Array.
+   * Per protocol: concatenate data lines, remove \n and \r, then decode.
+   */
+  #decodeBase64(base64Str: string): Uint8Array {
+    // Remove all newlines and carriage returns per protocol
+    const cleaned = base64Str.replace(/[\n\r]/g, ``)
+
+    // Empty string is valid
+    if (cleaned.length === 0) {
+      return new Uint8Array(0)
+    }
+
+    // Validate length is multiple of 4
+    if (cleaned.length % 4 !== 0) {
+      throw new DurableStreamError(
+        `Invalid base64 data: length ${cleaned.length} is not a multiple of 4`,
+        `PARSE_ERROR`
+      )
+    }
+
+    try {
+      // Prefer Buffer (native C++ in Node) over atob (requires JS charCodeAt loop)
+      if (typeof Buffer !== `undefined`) {
+        return new Uint8Array(Buffer.from(cleaned, `base64`))
+      } else {
+        const binaryStr = atob(cleaned)
+        const bytes = new Uint8Array(binaryStr.length)
+        for (let i = 0; i < binaryStr.length; i++) {
+          bytes[i] = binaryStr.charCodeAt(i)
+        }
+        return bytes
+      }
+    } catch (err) {
+      throw new DurableStreamError(
+        `Failed to decode base64 data: ${err instanceof Error ? err.message : String(err)}`,
+        `PARSE_ERROR`
+      )
     }
   }
 
   /**
    * Create a synthetic Response from SSE data with proper headers.
-   * Includes offset/cursor/upToDate in headers so subscribers can read them.
+   * Includes offset/cursor/upToDate/streamClosed in headers so subscribers can read them.
    */
   #createSSESyntheticResponse(
     data: string,
     offset: Offset,
     cursor: string | undefined,
-    upToDate: boolean
+    upToDate: boolean,
+    streamClosed: boolean
+  ): Response {
+    return this.#createSSESyntheticResponseFromParts(
+      [data],
+      offset,
+      cursor,
+      upToDate,
+      streamClosed
+    )
+  }
+
+  /**
+   * Create a synthetic Response from multiple SSE data parts.
+   * For base64 mode, each part is independently encoded, so we decode each
+   * separately and concatenate the binary results.
+   * For text mode, parts are simply concatenated as strings.
+   */
+  #createSSESyntheticResponseFromParts(
+    dataParts: Array<string>,
+    offset: Offset,
+    cursor: string | undefined,
+    upToDate: boolean,
+    streamClosed: boolean
   ): Response {
     const headers: Record<string, string> = {
       "content-type": this.contentType ?? `application/json`,
@@ -407,7 +498,47 @@ export class StreamResponseImpl<
     if (upToDate) {
       headers[STREAM_UP_TO_DATE_HEADER] = `true`
     }
-    return new Response(data, { status: 200, headers })
+    if (streamClosed) {
+      headers[STREAM_CLOSED_HEADER] = `true`
+    }
+
+    // Decode base64 if encoding is used
+    let body: BodyInit
+    if (this.#encoding === `base64`) {
+      // Each data part is independently base64 encoded, decode each separately
+      const decodedParts = dataParts
+        .filter((part) => part.length > 0)
+        .map((part) => this.#decodeBase64(part))
+
+      if (decodedParts.length === 0) {
+        // No data - return empty body
+        body = new ArrayBuffer(0)
+      } else if (decodedParts.length === 1) {
+        // Single part - use directly
+        const decoded = decodedParts[0]!
+        body = decoded.buffer.slice(
+          decoded.byteOffset,
+          decoded.byteOffset + decoded.byteLength
+        ) as ArrayBuffer
+      } else {
+        // Multiple parts - concatenate binary data
+        const totalLength = decodedParts.reduce(
+          (sum, part) => sum + part.length,
+          0
+        )
+        const combined = new Uint8Array(totalLength)
+        let offset = 0
+        for (const part of decodedParts) {
+          combined.set(part, offset)
+          offset += part.length
+        }
+        body = combined.buffer
+      }
+    } else {
+      body = dataParts.join(``)
+    }
+
+    return new Response(body, { status: 200, headers })
   }
 
   /**
@@ -421,6 +552,11 @@ export class StreamResponseImpl<
     if (controlEvent.upToDate !== undefined) {
       this.#upToDate = controlEvent.upToDate
     }
+    if (controlEvent.streamClosed) {
+      this.#streamClosed = true
+      // A closed stream is definitionally up-to-date - no more data will ever be appended
+      this.#upToDate = true
+    }
   }
 
   /**
@@ -578,8 +714,22 @@ export class StreamResponseImpl<
       return this.#processSSEDataEvent(event.data, sseEventIterator)
     }
 
-    // Control event without preceding data - update state and continue
+    // Control event without preceding data - update state
     this.#updateStateFromSSEControl(event)
+
+    // If upToDate is signaled, yield an empty response so subscribers receive the signal
+    // This is important for empty streams and for subscribers waiting for catch-up completion
+    if (event.upToDate) {
+      const response = this.#createSSESyntheticResponse(
+        ``,
+        event.streamNextOffset,
+        event.streamCursor,
+        true,
+        event.streamClosed ?? false
+      )
+      return { type: `response`, response }
+    }
+
     return { type: `continue` }
   }
 
@@ -587,6 +737,9 @@ export class StreamResponseImpl<
    * Process an SSE data event by waiting for its corresponding control event.
    * In SSE protocol, control events come AFTER data events.
    * Multiple data events may arrive before a single control event - we buffer them.
+   *
+   * For base64 mode, each data event is independently base64 encoded, so we
+   * collect them as an array and decode each separately.
    */
   async #processSSEDataEvent(
     pendingData: string,
@@ -600,7 +753,8 @@ export class StreamResponseImpl<
     | { type: `error`; error: Error }
   > {
     // Buffer to accumulate data from multiple consecutive data events
-    let bufferedData = pendingData
+    // For base64 mode, we collect as array since each event is independently encoded
+    const bufferedDataParts: Array<string> = [pendingData]
 
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     while (true) {
@@ -609,11 +763,12 @@ export class StreamResponseImpl<
 
       if (controlDone) {
         // Stream ended without control event - yield buffered data with current state
-        const response = this.#createSSESyntheticResponse(
-          bufferedData,
+        const response = this.#createSSESyntheticResponseFromParts(
+          bufferedDataParts,
           this.offset,
           this.cursor,
-          this.upToDate
+          this.upToDate,
+          this.streamClosed
         )
 
         // Try to reconnect
@@ -636,18 +791,19 @@ export class StreamResponseImpl<
       if (controlEvent.type === `control`) {
         // Update state and create response with correct metadata
         this.#updateStateFromSSEControl(controlEvent)
-        const response = this.#createSSESyntheticResponse(
-          bufferedData,
+        const response = this.#createSSESyntheticResponseFromParts(
+          bufferedDataParts,
           controlEvent.streamNextOffset,
           controlEvent.streamCursor,
-          controlEvent.upToDate ?? false
+          controlEvent.upToDate ?? false,
+          controlEvent.streamClosed ?? false
         )
         return { type: `response`, response }
       }
 
       // Got another data event before control - buffer it
       // Server sends multiple data events followed by one control event
-      bufferedData += controlEvent.data
+      bufferedDataParts.push(controlEvent.data)
     }
   }
 
@@ -1114,7 +1270,7 @@ export class StreamResponseImpl<
 
           // Get metadata from Response headers (not from `this` which may be stale)
           const response = result.value
-          const { offset, cursor, upToDate } =
+          const { offset, cursor, upToDate, streamClosed } =
             this.#getMetadataFromResponse(response)
 
           // Get response text first (handles empty responses gracefully)
@@ -1139,6 +1295,7 @@ export class StreamResponseImpl<
             offset,
             cursor,
             upToDate,
+            streamClosed,
           })
 
           result = await reader.read()
@@ -1181,7 +1338,7 @@ export class StreamResponseImpl<
 
           // Get metadata from Response headers (not from `this` which may be stale)
           const response = result.value
-          const { offset, cursor, upToDate } =
+          const { offset, cursor, upToDate, streamClosed } =
             this.#getMetadataFromResponse(response)
 
           const buffer = await response.arrayBuffer()
@@ -1192,6 +1349,7 @@ export class StreamResponseImpl<
             offset,
             cursor,
             upToDate,
+            streamClosed,
           })
 
           result = await reader.read()
@@ -1234,7 +1392,7 @@ export class StreamResponseImpl<
 
           // Get metadata from Response headers (not from `this` which may be stale)
           const response = result.value
-          const { offset, cursor, upToDate } =
+          const { offset, cursor, upToDate, streamClosed } =
             this.#getMetadataFromResponse(response)
 
           const text = await response.text()
@@ -1245,6 +1403,7 @@ export class StreamResponseImpl<
             offset,
             cursor,
             upToDate,
+            streamClosed,
           })
 
           result = await reader.read()