@durable-streams/client 0.2.0 → 0.2.2

package/src/sse.ts

@@ -22,6 +22,7 @@ export interface SSEControlEvent {
   streamNextOffset: Offset
   streamCursor?: string
   upToDate?: boolean
+  streamClosed?: boolean
 }
 
 export type SSEEvent = SSEDataEvent | SSEControlEvent
@@ -73,12 +74,14 @@ export async function* parseSSEStream(
                   streamNextOffset: Offset
                   streamCursor?: string
                   upToDate?: boolean
+                  streamClosed?: boolean
                 }
                 yield {
                   type: `control`,
                   streamNextOffset: control.streamNextOffset,
                   streamCursor: control.streamCursor,
                   upToDate: control.upToDate,
+                  streamClosed: control.streamClosed,
                 }
               } catch (err) {
                 // Control events contain critical offset data - don't silently ignore
@@ -94,7 +97,11 @@ export async function* parseSSEStream(
           }
           currentEvent = { data: [] }
         } else if (line.startsWith(`event:`)) {
-          currentEvent.type = line.slice(6).trim()
+          // Per SSE spec, strip only one optional space after "event:"
+          const eventType = line.slice(6)
+          currentEvent.type = eventType.startsWith(` `)
+            ? eventType.slice(1)
+            : eventType
         } else if (line.startsWith(`data:`)) {
           // Per SSE spec, strip the optional space after "data:"
           const content = line.slice(5)
@@ -123,12 +130,14 @@ export async function* parseSSEStream(
             streamNextOffset: Offset
             streamCursor?: string
             upToDate?: boolean
+            streamClosed?: boolean
           }
           yield {
             type: `control`,
             streamNextOffset: control.streamNextOffset,
             streamCursor: control.streamCursor,
             upToDate: control.upToDate,
+            streamClosed: control.streamClosed,
           }
         } catch (err) {
           const preview =

package/src/stream-api.ts

@@ -7,8 +7,10 @@
 import {
   LIVE_QUERY_PARAM,
   OFFSET_QUERY_PARAM,
+  STREAM_CLOSED_HEADER,
   STREAM_CURSOR_HEADER,
   STREAM_OFFSET_HEADER,
+  STREAM_SSE_DATA_ENCODING_HEADER,
   STREAM_UP_TO_DATE_HEADER,
 } from "./constants"
 import { DurableStreamError, FetchBackoffAbortError } from "./error"
@@ -190,12 +192,21 @@ async function streamInternal<TJson = unknown>(
   const initialCursor =
     firstResponse.headers.get(STREAM_CURSOR_HEADER) ?? undefined
   const initialUpToDate = firstResponse.headers.has(STREAM_UP_TO_DATE_HEADER)
+  const initialStreamClosed =
+    firstResponse.headers.get(STREAM_CLOSED_HEADER)?.toLowerCase() === `true`
 
   // Determine if JSON mode
   const isJsonMode =
     options.json === true ||
     (contentType?.includes(`application/json`) ?? false)
 
+  // Detect SSE data encoding from response header (server auto-sets for binary streams)
+  const sseDataEncoding = firstResponse.headers.get(
+    STREAM_SSE_DATA_ENCODING_HEADER
+  )
+  const encoding =
+    sseDataEncoding === `base64` ? (`base64` as const) : undefined
+
   // Create the fetch function for subsequent requests
   const fetchNext = async (
     offset: Offset,
@@ -288,10 +299,12 @@ async function streamInternal<TJson = unknown>(
     initialOffset,
     initialCursor,
     initialUpToDate,
+    initialStreamClosed,
     firstResponse,
     abortController,
     fetchNext,
     startSSE,
     sseResilience: options.sseResilience,
+    encoding,
   })
 }

package/src/stream-response-state.ts

@@ -0,0 +1,306 @@
+/**
+ * Explicit state machine for StreamResponseImpl.
+ *
+ * Every transition returns a new state — no mutation.
+ *
+ * Hierarchy:
+ *   StreamResponseState (abstract)
+ *   ├── LongPollState         shouldUseSse() → false
+ *   ├── SSEState              shouldUseSse() → true
+ *   └── PausedState           delegates to wrapped inner state
+ */
+
+import type { SSEControlEvent } from "./sse"
+import type { LiveMode, Offset, SSEResilienceOptions } from "./types"
+
+/**
+ * Shared sync fields across all state types.
+ */
+export interface SyncFields {
+  readonly offset: Offset
+  readonly cursor: string | undefined
+  readonly upToDate: boolean
+  readonly streamClosed: boolean
+}
+
+/**
+ * Extracted metadata from an HTTP response for state transitions.
+ * undefined values mean "not present in response, preserve current value".
+ */
+export interface ResponseMetadataUpdate {
+  readonly offset?: string
+  readonly cursor?: string
+  readonly upToDate: boolean
+  readonly streamClosed: boolean
+}
+
+/**
+ * Result of SSEState.handleConnectionEnd().
+ */
+export type SSEConnectionEndResult =
+  | {
+      readonly action: `reconnect`
+      readonly state: SSEState
+      readonly backoffAttempt: number
+    }
+  | { readonly action: `fallback`; readonly state: LongPollState }
+  | { readonly action: `healthy`; readonly state: SSEState }
+
+/**
+ * Abstract base class for stream response state.
+ * All state transitions return new immutable state objects.
+ */
+export abstract class StreamResponseState implements SyncFields {
+  abstract readonly offset: Offset
+  abstract readonly cursor: string | undefined
+  abstract readonly upToDate: boolean
+  abstract readonly streamClosed: boolean
+
+  abstract shouldUseSse(): boolean
+  abstract withResponseMetadata(
+    update: ResponseMetadataUpdate
+  ): StreamResponseState
+  abstract withSSEControl(event: SSEControlEvent): StreamResponseState
+  abstract pause(): StreamResponseState
+
+  shouldContinueLive(stopAfterUpToDate: boolean, liveMode: LiveMode): boolean {
+    if (stopAfterUpToDate && this.upToDate) return false
+    if (liveMode === false) return false
+    if (this.streamClosed) return false
+    return true
+  }
+}
+
+/**
+ * State for long-poll mode. shouldUseSse() returns false.
+ */
+export class LongPollState extends StreamResponseState {
+  readonly offset: Offset
+  readonly cursor: string | undefined
+  readonly upToDate: boolean
+  readonly streamClosed: boolean
+
+  constructor(fields: SyncFields) {
+    super()
+    this.offset = fields.offset
+    this.cursor = fields.cursor
+    this.upToDate = fields.upToDate
+    this.streamClosed = fields.streamClosed
+  }
+
+  shouldUseSse(): boolean {
+    return false
+  }
+
+  withResponseMetadata(update: ResponseMetadataUpdate): LongPollState {
+    return new LongPollState({
+      offset: update.offset ?? this.offset,
+      cursor: update.cursor ?? this.cursor,
+      upToDate: update.upToDate,
+      streamClosed: this.streamClosed || update.streamClosed,
+    })
+  }
+
+  withSSEControl(event: SSEControlEvent): LongPollState {
+    const streamClosed = this.streamClosed || (event.streamClosed ?? false)
+    return new LongPollState({
+      offset: event.streamNextOffset,
+      cursor: event.streamCursor || this.cursor,
+      upToDate:
+        (event.streamClosed ?? false)
+          ? true
+          : (event.upToDate ?? this.upToDate),
+      streamClosed,
+    })
+  }
+
+  pause(): PausedState {
+    return new PausedState(this)
+  }
+}
+
+/**
+ * State for SSE mode. shouldUseSse() returns true.
+ * Tracks SSE connection resilience (short connection detection).
+ */
+export class SSEState extends StreamResponseState {
+  readonly offset: Offset
+  readonly cursor: string | undefined
+  readonly upToDate: boolean
+  readonly streamClosed: boolean
+  readonly consecutiveShortConnections: number
+  readonly connectionStartTime: number | undefined
+
+  constructor(
+    fields: SyncFields & {
+      consecutiveShortConnections?: number
+      connectionStartTime?: number
+    }
+  ) {
+    super()
+    this.offset = fields.offset
+    this.cursor = fields.cursor
+    this.upToDate = fields.upToDate
+    this.streamClosed = fields.streamClosed
+    this.consecutiveShortConnections = fields.consecutiveShortConnections ?? 0
+    this.connectionStartTime = fields.connectionStartTime
+  }
+
+  shouldUseSse(): boolean {
+    return true
+  }
+
+  withResponseMetadata(update: ResponseMetadataUpdate): SSEState {
+    return new SSEState({
+      offset: update.offset ?? this.offset,
+      cursor: update.cursor ?? this.cursor,
+      upToDate: update.upToDate,
+      streamClosed: this.streamClosed || update.streamClosed,
+      consecutiveShortConnections: this.consecutiveShortConnections,
+      connectionStartTime: this.connectionStartTime,
+    })
+  }
+
+  withSSEControl(event: SSEControlEvent): SSEState {
+    const streamClosed = this.streamClosed || (event.streamClosed ?? false)
+    return new SSEState({
+      offset: event.streamNextOffset,
+      cursor: event.streamCursor || this.cursor,
+      upToDate:
+        (event.streamClosed ?? false)
+          ? true
+          : (event.upToDate ?? this.upToDate),
+      streamClosed,
+      consecutiveShortConnections: this.consecutiveShortConnections,
+      connectionStartTime: this.connectionStartTime,
+    })
+  }
+
+  startConnection(now: number): SSEState {
+    return new SSEState({
+      offset: this.offset,
+      cursor: this.cursor,
+      upToDate: this.upToDate,
+      streamClosed: this.streamClosed,
+      consecutiveShortConnections: this.consecutiveShortConnections,
+      connectionStartTime: now,
+    })
+  }
+
+  handleConnectionEnd(
+    now: number,
+    wasAborted: boolean,
+    config: Required<SSEResilienceOptions>
+  ): SSEConnectionEndResult {
+    if (this.connectionStartTime === undefined) {
+      return { action: `healthy`, state: this }
+    }
+
+    const duration = now - this.connectionStartTime
+
+    if (duration < config.minConnectionDuration && !wasAborted) {
+      // Connection was too short — likely proxy buffering or misconfiguration
+      const newCount = this.consecutiveShortConnections + 1
+
+      if (newCount >= config.maxShortConnections) {
+        // Threshold reached → permanent fallback to long-poll
+        return {
+          action: `fallback`,
+          state: new LongPollState({
+            offset: this.offset,
+            cursor: this.cursor,
+            upToDate: this.upToDate,
+            streamClosed: this.streamClosed,
+          }),
+        }
+      }
+
+      // Reconnect with backoff
+      return {
+        action: `reconnect`,
+        state: new SSEState({
+          offset: this.offset,
+          cursor: this.cursor,
+          upToDate: this.upToDate,
+          streamClosed: this.streamClosed,
+          consecutiveShortConnections: newCount,
+          connectionStartTime: this.connectionStartTime,
+        }),
+        backoffAttempt: newCount,
+      }
+    }
+
+    if (duration >= config.minConnectionDuration) {
+      // Healthy connection — reset counter
+      return {
+        action: `healthy`,
+        state: new SSEState({
+          offset: this.offset,
+          cursor: this.cursor,
+          upToDate: this.upToDate,
+          streamClosed: this.streamClosed,
+          consecutiveShortConnections: 0,
+          connectionStartTime: this.connectionStartTime,
+        }),
+      }
+    }
+
+    // Aborted connection — don't change counter
+    return { action: `healthy`, state: this }
+  }
+
+  pause(): PausedState {
+    return new PausedState(this)
+  }
+}
+
+/**
+ * Paused state wrapper. Delegates all sync field access to the inner state.
+ * resume() returns the wrapped state unchanged (identity preserved).
+ */
+export class PausedState extends StreamResponseState {
+  readonly #inner: LongPollState | SSEState
+
+  constructor(inner: LongPollState | SSEState) {
+    super()
+    this.#inner = inner
+  }
+
+  get offset(): Offset {
+    return this.#inner.offset
+  }
+
+  get cursor(): string | undefined {
+    return this.#inner.cursor
+  }
+
+  get upToDate(): boolean {
+    return this.#inner.upToDate
+  }
+
+  get streamClosed(): boolean {
+    return this.#inner.streamClosed
+  }
+
+  shouldUseSse(): boolean {
+    return this.#inner.shouldUseSse()
+  }
+
+  withResponseMetadata(update: ResponseMetadataUpdate): PausedState {
+    const newInner = this.#inner.withResponseMetadata(update)
+    return new PausedState(newInner)
+  }
+
+  withSSEControl(event: SSEControlEvent): PausedState {
+    const newInner = this.#inner.withSSEControl(event)
+    return new PausedState(newInner)
+  }
+
+  pause(): PausedState {
+    return this
+  }
+
+  resume(): { state: LongPollState | SSEState; justResumed: true } {
+    return { state: this.#inner, justResumed: true }
+  }
+}

package/src/stream.ts

@@ -7,13 +7,13 @@
 import fastq from "fastq"
 
 import {
-  DurableStreamError,
   InvalidSignalError,
   MissingStreamUrlError,
+  StreamClosedError,
 } from "./error"
 import { IdempotentProducer } from "./idempotent-producer"
 import {
-  SSE_COMPATIBLE_CONTENT_TYPES,
+  STREAM_CLOSED_HEADER,
   STREAM_EXPIRES_AT_HEADER,
   STREAM_OFFSET_HEADER,
   STREAM_SEQ_HEADER,
@@ -35,6 +35,8 @@ import type { BackoffOptions } from "./fetch"
 import type { queueAsPromised } from "fastq"
 import type {
   AppendOptions,
+  CloseOptions,
+  CloseResult,
   CreateOptions,
   HeadResult,
   HeadersRecord,
@@ -204,6 +206,7 @@ export class DurableStream {
       ttlSeconds: opts.ttlSeconds,
       expiresAt: opts.expiresAt,
       body: opts.body,
+      closed: opts.closed,
     })
     return stream
   }
@@ -269,6 +272,8 @@ export class DurableStream {
     const offset = response.headers.get(STREAM_OFFSET_HEADER) ?? undefined
     const etag = response.headers.get(`etag`) ?? undefined
     const cacheControl = response.headers.get(`cache-control`) ?? undefined
+    const streamClosed =
+      response.headers.get(STREAM_CLOSED_HEADER)?.toLowerCase() === `true`
 
     // Update instance contentType
     if (contentType) {
@@ -281,6 +286,7 @@ export class DurableStream {
       offset,
       etag,
       cacheControl,
+      streamClosed,
     }
   }
 
@@ -300,6 +306,9 @@ export class DurableStream {
     if (opts?.expiresAt) {
       requestHeaders[STREAM_EXPIRES_AT_HEADER] = opts.expiresAt
     }
+    if (opts?.closed) {
+      requestHeaders[STREAM_CLOSED_HEADER] = `true`
+    }
 
     const body = encodeBody(opts?.body)
 
@@ -342,6 +351,84 @@ export class DurableStream {
     }
   }
 
+  /**
+   * Close the stream, optionally with a final message.
+   *
+   * After closing:
+   * - No further appends are permitted (server returns 409)
+   * - Readers can observe the closed state and treat it as EOF
+   * - The stream's data remains fully readable
+   *
+   * Closing is:
+   * - **Durable**: The closed state is persisted
+   * - **Monotonic**: Once closed, a stream cannot be reopened
+   *
+   * **Idempotency:**
+   * - `close()` without body: Idempotent — safe to call multiple times
+   * - `close({ body })` with body: NOT idempotent — throws `StreamClosedError`
+   *   if stream is already closed (use `IdempotentProducer.close()` for
+   *   idempotent close-with-body semantics)
+   *
+   * @returns CloseResult with the final offset
+   * @throws StreamClosedError if called with body on an already-closed stream
+   */
+  async close(opts?: CloseOptions): Promise<CloseResult> {
+    const { requestHeaders, fetchUrl } = await this.#buildRequest()
+
+    const contentType =
+      opts?.contentType ?? this.#options.contentType ?? this.contentType
+    if (contentType) {
+      requestHeaders[`content-type`] = contentType
+    }
+
+    // Always send Stream-Closed: true header for close operation
+    requestHeaders[STREAM_CLOSED_HEADER] = `true`
+
+    // For JSON mode with body, wrap in array
+    let body: BodyInit | undefined
+    if (opts?.body !== undefined) {
+      const isJson = normalizeContentType(contentType) === `application/json`
+      if (isJson) {
+        const bodyStr =
+          typeof opts.body === `string`
+            ? opts.body
+            : new TextDecoder().decode(opts.body)
+        body = `[${bodyStr}]`
+      } else {
+        body =
+          typeof opts.body === `string`
+            ? opts.body
+            : (opts.body as unknown as BodyInit)
+      }
+    }
+
+    const response = await this.#fetchClient(fetchUrl.toString(), {
+      method: `POST`,
+      headers: requestHeaders,
+      body,
+      signal: opts?.signal ?? this.#options.signal,
+    })
+
+    // Check for 409 Conflict with Stream-Closed header
+    if (response.status === 409) {
+      const isClosed =
+        response.headers.get(STREAM_CLOSED_HEADER)?.toLowerCase() === `true`
+      if (isClosed) {
+        const finalOffset =
+          response.headers.get(STREAM_OFFSET_HEADER) ?? undefined
+        throw new StreamClosedError(this.url, finalOffset)
+      }
+    }
+
+    if (!response.ok) {
+      await handleErrorResponse(response, this.url)
+    }
+
+    const finalOffset = response.headers.get(STREAM_OFFSET_HEADER) ?? ``
+
+    return { finalOffset }
+  }
+
   /**
    * Append a single payload to the stream.
    *
@@ -403,9 +490,24 @@ export class DurableStream {
     // For JSON mode, wrap body in array to match protocol (server flattens one level)
     // Input is pre-serialized JSON string
     const isJson = normalizeContentType(contentType) === `application/json`
-    const bodyStr =
-      typeof body === `string` ? body : new TextDecoder().decode(body)
-    const encodedBody: BodyInit = isJson ? `[${bodyStr}]` : bodyStr
+    let encodedBody: BodyInit
+    if (isJson) {
+      // JSON mode: decode as UTF-8 string and wrap in array
+      const bodyStr =
+        typeof body === `string` ? body : new TextDecoder().decode(body)
+      encodedBody = `[${bodyStr}]`
+    } else {
+      // Binary mode: preserve raw bytes
+      // Use ArrayBuffer for cross-platform BodyInit compatibility
+      if (typeof body === `string`) {
+        encodedBody = body
+      } else {
+        encodedBody = body.buffer.slice(
+          body.byteOffset,
+          body.byteOffset + body.byteLength
+        ) as ArrayBuffer
+      }
+    }
 
     const response = await this.#fetchClient(fetchUrl.toString(), {
       method: `POST`,
@@ -522,11 +624,43 @@ export class DurableStream {
       )
       batchedBody = `[${jsonStrings.join(`,`)}]`
     } else {
-      // For byte mode: concatenate all chunks as a string
-      const strings = batch.map((m) =>
-        typeof m.data === `string` ? m.data : new TextDecoder().decode(m.data)
-      )
-      batchedBody = strings.join(``)
+      // For byte mode: preserve original data types
+      // - Strings are concatenated as strings (for text/* content types)
+      // - Uint8Arrays are concatenated as binary (for application/octet-stream)
+      // - Mixed types: convert all to binary to avoid data corruption
+      const hasUint8Array = batch.some((m) => m.data instanceof Uint8Array)
+      const hasString = batch.some((m) => typeof m.data === `string`)
+
+      if (hasUint8Array && !hasString) {
+        // All binary: concatenate Uint8Arrays
+        const chunks = batch.map((m) => m.data as Uint8Array)
+        const totalLength = chunks.reduce((sum, c) => sum + c.length, 0)
+        const combined = new Uint8Array(totalLength)
+        let offset = 0
+        for (const chunk of chunks) {
+          combined.set(chunk, offset)
+          offset += chunk.length
+        }
+        batchedBody = combined
+      } else if (hasString && !hasUint8Array) {
+        // All strings: concatenate as string
+        batchedBody = batch.map((m) => m.data as string).join(``)
+      } else {
+        // Mixed types: convert strings to binary and concatenate
+        // This preserves binary data integrity
+        const encoder = new TextEncoder()
+        const chunks = batch.map((m) =>
+          typeof m.data === `string` ? encoder.encode(m.data) : m.data
+        )
+        const totalLength = chunks.reduce((sum, c) => sum + c.length, 0)
+        const combined = new Uint8Array(totalLength)
+        let offset = 0
+        for (const chunk of chunks) {
+          combined.set(chunk, offset)
+          offset += chunk.length
+        }
+        batchedBody = combined
+      }
     }
 
     // Combine signals: stream-level signal + any per-message signals
@@ -682,12 +816,13 @@ export class DurableStream {
         producer.append(chunk)
       },
       async close() {
-        await producer.flush()
+        // close() flushes pending and closes the stream (EOF)
         await producer.close()
         if (writeError) throw writeError // Causes pipeTo() to reject
       },
       abort(_reason) {
-        producer.close().catch((err) => {
+        // detach() stops the producer without closing the stream
+        producer.detach().catch((err) => {
           opts?.onError?.(err) // Report instead of swallowing
         })
       },
@@ -736,20 +871,6 @@ export class DurableStream {
   async stream<TJson = unknown>(
     options?: Omit<StreamOptions, `url`>
   ): Promise<StreamResponse<TJson>> {
-    // Check SSE compatibility if SSE mode is requested
-    if (options?.live === `sse` && this.contentType) {
-      const isSSECompatible = SSE_COMPATIBLE_CONTENT_TYPES.some((prefix) =>
-        this.contentType!.startsWith(prefix)
-      )
-      if (!isSSECompatible) {
-        throw new DurableStreamError(
-          `SSE is not supported for content-type: ${this.contentType}`,
-          `SSE_NOT_SUPPORTED`,
-          400
-        )
-      }
-    }
-
     // Merge handle-level and call-specific headers
     const mergedHeaders: HeadersRecord = {
       ...this.#options.headers,