@durable-streams/client-conformance-tests 0.2.0 → 0.2.2

package/src/protocol.ts

@@ -41,6 +41,10 @@ export interface CreateCommand {
   expiresAt?: string
   /** Custom headers to include */
   headers?: Record<string, string>
+  /** Create the stream in closed state */
+  closed?: boolean
+  /** Initial body data to include on creation */
+  data?: string
 }
 
 /**
@@ -112,6 +116,38 @@ export interface IdempotentAppendBatchCommand {
   headers?: Record<string, string>
 }
 
+/**
+ * Close a stream via IdempotentProducer (uses producer headers for idempotency).
+ */
+export interface IdempotentCloseCommand {
+  type: `idempotent-close`
+  path: string
+  /** Producer ID */
+  producerId: string
+  /** Producer epoch */
+  epoch: number
+  /** Optional final message to append atomically with close */
+  data?: string
+  /** Auto-claim epoch on 403 */
+  autoClaim: boolean
+  /** Custom headers to include */
+  headers?: Record<string, string>
+}
+
+/**
+ * Detach an IdempotentProducer (stop without closing stream).
+ */
+export interface IdempotentDetachCommand {
+  type: `idempotent-detach`
+  path: string
+  /** Producer ID */
+  producerId: string
+  /** Producer epoch */
+  epoch: number
+  /** Custom headers to include */
+  headers?: Record<string, string>
+}
+
 /**
  * Read from a stream (GET request).
  */
@@ -150,6 +186,35 @@ export interface DeleteCommand {
   headers?: Record<string, string>
 }
 
+/**
+ * Close a stream (no more appends allowed).
+ */
+export interface CloseCommand {
+  type: `close`
+  /** Stream path */
+  path: string
+  /** Optional final message to append */
+  data?: string
+  /** Content type for the final message */
+  contentType?: string
+}
+
+/**
+ * Close a stream via direct HTTP (bypasses client adapter).
+ * Used for testing server-side stream closure behavior.
+ */
+export interface ServerCloseCommand {
+  type: `server-close`
+  /** Stream path */
+  path: string
+  /** Whether stream should be closed (always true for this command) */
+  streamClosed: true
+  /** Optional body data */
+  data?: string
+  /** Content type for the body */
+  contentType?: string
+}
+
 /**
  * Shutdown the client adapter gracefully.
  */
@@ -334,9 +399,13 @@ export type TestCommand =
   | AppendCommand
   | IdempotentAppendCommand
   | IdempotentAppendBatchCommand
+  | IdempotentCloseCommand
+  | IdempotentDetachCommand
   | ReadCommand
   | HeadCommand
   | DeleteCommand
+  | CloseCommand
+  | ServerCloseCommand
   | ShutdownCommand
   | SetDynamicHeaderCommand
   | SetDynamicParamCommand
@@ -459,6 +528,26 @@ export interface IdempotentAppendBatchResult {
   producerSeq?: number
 }
 
+/**
+ * Successful idempotent-close result.
+ */
+export interface IdempotentCloseResult {
+  type: `idempotent-close`
+  success: true
+  status: number
+  /** Final stream offset after close */
+  finalOffset?: string
+}
+
+/**
+ * Successful idempotent-detach result.
+ */
+export interface IdempotentDetachResult {
+  type: `idempotent-detach`
+  success: true
+  status: number
+}
+
 /**
  * A chunk of data read from the stream.
  */
@@ -484,6 +573,8 @@ export interface ReadResult {
   offset?: string
   /** Whether stream is up-to-date (caught up to head) */
   upToDate?: boolean
+  /** Whether the stream has been permanently closed (no more appends) */
+  streamClosed?: boolean
   /** Cursor value if provided */
   cursor?: string
   /** Response headers */
@@ -509,6 +600,8 @@ export interface HeadResult {
   ttlSeconds?: number
   /** Absolute expiry (ISO 8601) */
   expiresAt?: string
+  /** Whether the stream has been permanently closed (no more appends) */
+  streamClosed?: boolean
   headers?: Record<string, string>
 }
 
@@ -522,6 +615,16 @@ export interface DeleteResult {
   headers?: Record<string, string>
 }
 
+/**
+ * Successful close result.
+ */
+export interface CloseResult {
+  type: `close`
+  success: true
+  /** Final offset after closing (may include final message) */
+  finalOffset: string
+}
+
 /**
  * Successful shutdown result.
  */
@@ -612,9 +715,12 @@ export type TestResult =
   | AppendResult
   | IdempotentAppendResult
   | IdempotentAppendBatchResult
+  | IdempotentCloseResult
+  | IdempotentDetachResult
   | ReadResult
   | HeadResult
   | DeleteResult
+  | CloseResult
   | ShutdownResult
   | SetDynamicHeaderResult
   | SetDynamicParamResult
@@ -683,6 +789,8 @@ export const ErrorCodes = {
   NOT_FOUND: `NOT_FOUND`,
   /** Sequence number conflict (409) */
   SEQUENCE_CONFLICT: `SEQUENCE_CONFLICT`,
+  /** Stream is closed (409 with Stream-Closed header) */
+  STREAM_CLOSED: `STREAM_CLOSED`,
   /** Invalid offset format */
   INVALID_OFFSET: `INVALID_OFFSET`,
   /** Server returned unexpected status */

package/src/runner.ts

@@ -21,6 +21,7 @@ import {
 import type { Interface as ReadlineInterface } from "node:readline"
 import type {
   AppendResult,
+  CloseResult,
   ErrorResult,
   HeadResult,
   ReadResult,
@@ -273,6 +274,8 @@ async function executeOperation(
           ttlSeconds: op.ttlSeconds,
           expiresAt: op.expiresAt,
           headers: op.headers,
+          closed: op.closed,
+          data: op.data,
         },
         commandTimeout
       )
@@ -441,6 +444,55 @@ async function executeOperation(
       return { result }
     }
 
+    case `idempotent-close`: {
+      const path = resolveVariables(op.path, variables)
+      const data = op.data ? resolveVariables(op.data, variables) : undefined
+
+      const result = await client.send(
+        {
+          type: `idempotent-close`,
+          path,
+          producerId: op.producerId,
+          epoch: op.epoch ?? 0,
+          data,
+          autoClaim: op.autoClaim ?? false,
+          headers: op.headers,
+        },
+        commandTimeout
+      )
+
+      if (verbose) {
+        console.log(
+          `  idempotent-close ${path}: ${result.success ? `ok` : `failed`}`
+        )
+      }
+
+      return { result }
+    }
+
+    case `idempotent-detach`: {
+      const path = resolveVariables(op.path, variables)
+
+      const result = await client.send(
+        {
+          type: `idempotent-detach`,
+          path,
+          producerId: op.producerId,
+          epoch: op.epoch ?? 0,
+          headers: op.headers,
+        },
+        commandTimeout
+      )
+
+      if (verbose) {
+        console.log(
+          `  idempotent-detach ${path}: ${result.success ? `ok` : `failed`}`
+        )
+      }
+
+      return { result }
+    }
+
     case `read`: {
       const path = resolveVariables(op.path, variables)
       const offset = op.offset
@@ -546,6 +598,72 @@ async function executeOperation(
       return { result }
     }
 
+    case `close`: {
+      const path = resolveVariables(op.path, variables)
+
+      const result = await client.send(
+        {
+          type: `close`,
+          path,
+          data: op.data,
+          contentType: op.contentType,
+        },
+        commandTimeout
+      )
+
+      if (verbose) {
+        console.log(`  close ${path}: ${result.success ? `ok` : `failed`}`)
+      }
+
+      return { result }
+    }
+
+    case `server-close`: {
+      // Direct HTTP POST to server with Stream-Closed: true header
+      // Used for testing server-side stream closure behavior
+      const path = resolveVariables(op.path, variables)
+
+      try {
+        // Build headers including Stream-Closed
+        const headers: Record<string, string> = {
+          "Stream-Closed": `true`,
+          ...op.headers,
+        }
+
+        // Set content-type if body is provided
+        if (op.data && op.contentType) {
+          headers[`content-type`] = op.contentType
+        }
+
+        const response = await fetch(`${ctx.serverUrl}${path}`, {
+          method: `POST`,
+          body: op.data,
+          headers,
+        })
+
+        const status = response.status
+        const finalOffset =
+          response.headers.get(`Stream-Next-Offset`) ?? undefined
+
+        if (verbose) {
+          console.log(`  server-close ${path}: status=${status}`)
+        }
+
+        // Build result for expectation verification
+        const result: TestResult = {
+          type: `close`,
+          success: true,
+          finalOffset: finalOffset ?? ``,
+        }
+
+        return { result }
+      } catch (err) {
+        return {
+          error: `Server close failed: ${err instanceof Error ? err.message : String(err)}`,
+        }
+      }
+    }
+
     case `wait`: {
       await new Promise((resolve) => setTimeout(resolve, op.ms))
       return {}
@@ -884,6 +1002,10 @@ function isHeadResult(result: TestResult): result is HeadResult {
   return result.type === `head` && result.success
 }
 
+function isCloseResult(result: TestResult): result is CloseResult {
+  return result.type === `close` && result.success
+}
+
 function isErrorResult(result: TestResult): result is ErrorResult {
   return result.type === `error` && !result.success
 }
@@ -976,6 +1098,27 @@ function validateExpectation(
     }
   }
 
+  // Check streamClosed (for read results)
+  if (expect.streamClosed !== undefined && isReadResult(result)) {
+    if (result.streamClosed !== expect.streamClosed) {
+      return `Expected streamClosed=${expect.streamClosed}, got ${result.streamClosed}`
+    }
+  }
+
+  // Check streamClosed (for head results)
+  if (expect.streamClosed !== undefined && isHeadResult(result)) {
+    if (result.streamClosed !== expect.streamClosed) {
+      return `Expected streamClosed=${expect.streamClosed}, got ${result.streamClosed}`
+    }
+  }
+
+  // Check finalOffset (for close results)
+  if (expect.finalOffset !== undefined && isCloseResult(result)) {
+    if (result.finalOffset !== expect.finalOffset) {
+      return `Expected finalOffset=${expect.finalOffset}, got ${result.finalOffset}`
+    }
+  }
+
   // Check chunkCount
   if (expect.chunkCount !== undefined && isReadResult(result)) {
     if (result.chunks.length !== expect.chunkCount) {

package/src/test-cases.ts

@@ -92,6 +92,10 @@ export interface CreateOperation {
   expiresAt?: string
   /** Custom headers */
   headers?: Record<string, string>
+  /** Create stream in closed state */
+  closed?: boolean
+  /** Initial body data to include on creation */
+  data?: string
   /** Expected result */
   expect?: CreateExpectation
 }
@@ -206,6 +210,55 @@ export interface IdempotentAppendBatchExpectation extends BaseExpectation {
   allSucceed?: boolean
 }
 
+/**
+ * Close a stream via IdempotentProducer (uses producer headers for idempotency).
+ */
+export interface IdempotentCloseOperation {
+  action: `idempotent-close`
+  path: string
+  /** Producer ID */
+  producerId: string
+  /** Producer epoch */
+  epoch?: number
+  /** Optional final message to append atomically with close */
+  data?: string
+  /** Auto-claim epoch on 403 */
+  autoClaim?: boolean
+  headers?: Record<string, string>
+  expect?: IdempotentCloseExpectation
+}
+
+/**
+ * Expectation for idempotent-close operation.
+ */
+export interface IdempotentCloseExpectation extends BaseExpectation {
+  /** Store the final offset */
+  storeOffsetAs?: string
+  /** Expected finalOffset */
+  finalOffset?: string
+}
+
+/**
+ * Detach an IdempotentProducer (stop without closing stream).
+ */
+export interface IdempotentDetachOperation {
+  action: `idempotent-detach`
+  path: string
+  /** Producer ID */
+  producerId: string
+  /** Producer epoch */
+  epoch?: number
+  headers?: Record<string, string>
+  expect?: IdempotentDetachExpectation
+}
+
+/**
+ * Expectation for idempotent-detach operation.
+ */
+export interface IdempotentDetachExpectation extends BaseExpectation {
+  // No specific expectations beyond status
+}
+
 /**
  * Read from a stream.
  */
@@ -250,6 +303,35 @@ export interface DeleteOperation {
   expect?: DeleteExpectation
 }
 
+/**
+ * Close a stream (no more appends allowed).
+ */
+export interface CloseOperation {
+  action: `close`
+  path: string
+  /** Optional final message to append */
+  data?: string
+  /** Content type for the final message */
+  contentType?: string
+  headers?: Record<string, string>
+  expect?: CloseExpectation
+}
+
+/**
+ * Close a stream via direct HTTP (bypasses client adapter).
+ * Used for testing server-side stream closure behavior.
+ */
+export interface ServerCloseOperation {
+  action: `server-close`
+  path: string
+  /** Optional body data */
+  data?: string
+  /** Content type for the body */
+  contentType?: string
+  headers?: Record<string, string>
+  expect?: ServerCloseExpectation
+}
+
 /**
  * Wait for a duration (for timing-sensitive tests).
  */
@@ -467,9 +549,13 @@ export type TestOperation =
   | AppendBatchOperation
   | IdempotentAppendOperation
   | IdempotentAppendBatchOperation
+  | IdempotentCloseOperation
+  | IdempotentDetachOperation
   | ReadOperation
   | HeadOperation
   | DeleteOperation
+  | CloseOperation
+  | ServerCloseOperation
   | WaitOperation
   | SetOperation
   | AssertOperation
@@ -556,6 +642,8 @@ export interface ReadExpectation extends BaseExpectation {
   maxChunks?: number
   /** Should be up-to-date after read */
   upToDate?: boolean
+  /** Whether the stream has been permanently closed */
+  streamClosed?: boolean
   /** Store final offset */
   storeOffsetAs?: string
   /** Store all data concatenated */
@@ -572,12 +660,26 @@ export interface HeadExpectation extends BaseExpectation {
   contentType?: string
   /** Should have an offset */
   hasOffset?: boolean
+  /** Whether the stream has been permanently closed */
+  streamClosed?: boolean
 }
 
 export interface DeleteExpectation extends BaseExpectation {
   status?: 200 | 204 | 404 | number
 }
 
+export interface CloseExpectation extends BaseExpectation {
+  /** Expected final offset after closing */
+  finalOffset?: string
+}
+
+export interface ServerCloseExpectation {
+  /** Expected HTTP status code */
+  status?: number
+  /** Expected final offset after closing */
+  finalOffset?: string
+}
+
 /**
  * Load all test suites from a directory.
  */

package/test-cases/consumer/message-ordering.yaml

@@ -66,6 +66,7 @@ tests:
     setup:
       - action: create
         as: streamPath
+        contentType: text/plain
       - action: append
         path: ${streamPath}
         data: "x"

package/test-cases/consumer/offset-handling.yaml

@@ -121,6 +121,7 @@ tests:
     setup:
       - action: create
         as: streamPath
+        contentType: text/plain
     operations:
       # SSE with offset=now on empty stream
       - action: read
@@ -217,6 +218,7 @@ tests:
     setup:
       - action: create
         as: streamPath
+        contentType: text/plain
       - action: append
         path: ${streamPath}
         data: "historicalsse"
@@ -366,6 +368,7 @@ tests:
     setup:
       - action: create
         as: streamPath
+        contentType: text/plain
       - action: append
         path: ${streamPath}
         data: "old"