@durable-streams/client 0.1.5 → 0.2.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@durable-streams/client",
   "description": "TypeScript client for the Durable Streams protocol",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "author": "Durable Stream contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -47,7 +47,7 @@
   "devDependencies": {
     "fast-check": "^4.4.0",
     "tsdown": "^0.9.0",
-    "@durable-streams/server": "0.1.6"
+    "@durable-streams/server": "0.2.1"
   },
   "engines": {
     "node": ">=18.0.0"

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).
@@ -76,12 +77,9 @@ function normalizeContentType(contentType: string | undefined): string {
 
 /**
  * Internal type for pending batch entries.
- * Stores original data for proper JSON batching.
  */
 interface PendingEntry {
-  /** Original data - parsed for JSON mode batching */
-  data: unknown
-  /** Encoded bytes for byte-stream mode */
+  /** Encoded bytes */
   body: Uint8Array
 }
 
@@ -141,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)
@@ -173,18 +173,37 @@ export class IdempotentProducer {
     producerId: string,
     opts?: IdempotentProducerOptions
   ) {
+    // Validate inputs
+    const epoch = opts?.epoch ?? 0
+    const maxBatchBytes = opts?.maxBatchBytes ?? 1024 * 1024 // 1MB
+    const maxInFlight = opts?.maxInFlight ?? 5
+    const lingerMs = opts?.lingerMs ?? 5
+
+    if (epoch < 0) {
+      throw new Error(`epoch must be >= 0`)
+    }
+    if (maxBatchBytes <= 0) {
+      throw new Error(`maxBatchBytes must be > 0`)
+    }
+    if (maxInFlight <= 0) {
+      throw new Error(`maxInFlight must be > 0`)
+    }
+    if (lingerMs < 0) {
+      throw new Error(`lingerMs must be >= 0`)
+    }
+
     this.#stream = stream
     this.#producerId = producerId
-    this.#epoch = opts?.epoch ?? 0
+    this.#epoch = epoch
     this.#autoClaim = opts?.autoClaim ?? false
-    this.#maxBatchBytes = opts?.maxBatchBytes ?? 1024 * 1024 // 1MB
-    this.#lingerMs = opts?.lingerMs ?? 5
+    this.#maxBatchBytes = maxBatchBytes
+    this.#lingerMs = lingerMs
     this.#signal = opts?.signal
     this.#onError = opts?.onError
     this.#fetchClient =
       opts?.fetch ?? ((...args: Parameters<typeof fetch>) => fetch(...args))
 
-    this.#maxInFlight = opts?.maxInFlight ?? 5
+    this.#maxInFlight = maxInFlight
 
     // When autoClaim is true, epoch is not yet known until first batch completes
     // We block pipelining until then to avoid racing with the claim
@@ -224,12 +243,22 @@ export class IdempotentProducer {
    * Errors are reported via onError callback if configured. Use flush() to
    * wait for all pending messages to be sent.
    *
-   * For JSON streams, pass native objects (which will be serialized internally).
+   * For JSON streams, pass pre-serialized JSON strings.
    * For byte streams, pass string or Uint8Array.
    *
-   * @param body - Data to append (object for JSON streams, string or Uint8Array for byte streams)
+   * @param body - Data to append (string or Uint8Array)
+   *
+   * @example
+   * ```typescript
+   * // JSON stream
+   * producer.append(JSON.stringify({ message: "hello" }));
+   *
+   * // Byte stream
+   * producer.append("raw text data");
+   * producer.append(new Uint8Array([1, 2, 3]));
+   * ```
    */
-  append(body: Uint8Array | string | unknown): void {
+  append(body: Uint8Array | string): void {
     if (this.#closed) {
       throw new DurableStreamError(
         `Producer is closed`,
@@ -239,35 +268,21 @@ export class IdempotentProducer {
       )
     }
 
-    const isJson =
-      normalizeContentType(this.#stream.contentType) === `application/json`
-
     let bytes: Uint8Array
-    let data: unknown
-
-    if (isJson) {
-      // For JSON streams: accept native objects, serialize internally
-      const json = JSON.stringify(body)
-      bytes = new TextEncoder().encode(json)
-      data = body
+    if (typeof body === `string`) {
+      bytes = new TextEncoder().encode(body)
+    } else if (body instanceof Uint8Array) {
+      bytes = body
     } else {
-      // For byte streams, require string or Uint8Array
-      if (typeof body === `string`) {
-        bytes = new TextEncoder().encode(body)
-      } else if (body instanceof Uint8Array) {
-        bytes = body
-      } else {
-        throw new DurableStreamError(
-          `Non-JSON streams require string or Uint8Array`,
-          `BAD_REQUEST`,
-          400,
-          undefined
-        )
-      }
-      data = bytes
+      throw new DurableStreamError(
+        `append() requires string or Uint8Array. For objects, use JSON.stringify().`,
+        `BAD_REQUEST`,
+        400,
+        undefined
+      )
     }
 
-    this.#pendingBatch.push({ data, body: bytes })
+    this.#pendingBatch.push({ body: bytes })
     this.#batchBytes += bytes.length
 
     // Check if batch should be sent immediately
@@ -306,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
@@ -318,10 +339,140 @@ 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
+  }
+
   /**
    * Increment epoch and reset sequence.
    *
@@ -523,8 +674,9 @@ export class IdempotentProducer {
       // For JSON mode: always send as array (server flattens one level)
       // Single append: [value] → server stores value
       // Multiple appends: [val1, val2] → server stores val1, val2
-      const values = batch.map((e) => e.data)
-      batchedBody = JSON.stringify(values)
+      // Input is pre-serialized JSON strings, join them into an array
+      const jsonStrings = batch.map((e) => new TextDecoder().decode(e.body))
+      batchedBody = `[${jsonStrings.join(`,`)}]`
     } else {
       // For byte mode: concatenate all chunks
       const totalSize = batch.reduce((sum, e) => sum + e.body.length, 0)

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,