@durable-streams/client-conformance-tests 0.1.6 → 0.1.7

package/src/adapters/typescript-adapter.ts

@@ -14,6 +14,7 @@ import {
   DurableStream,
   DurableStreamError,
   FetchError,
+  IdempotentProducer,
   stream,
 } from "@durable-streams/client"
 import {
@@ -439,7 +440,7 @@ async function handleCommand(command: TestCommand): Promise<TestResult> {
         return {
           type: `read`,
           success: true,
-          status: 200,
+          status: response.status,
           chunks,
           offset: finalOffset,
           upToDate,
@@ -543,6 +544,117 @@ async function handleCommand(command: TestCommand): Promise<TestResult> {
       }
     }
 
+    case `idempotent-append`: {
+      try {
+        const url = `${serverUrl}${command.path}`
+
+        // Get content-type from cache or use default
+        const contentType =
+          streamContentTypes.get(command.path) ?? `application/octet-stream`
+
+        const ds = new DurableStream({
+          url,
+          contentType,
+        })
+
+        const producer = new IdempotentProducer(ds, command.producerId, {
+          epoch: command.epoch,
+          autoClaim: command.autoClaim,
+          maxInFlight: 1,
+          lingerMs: 0, // Send immediately for testing
+        })
+
+        // For JSON streams, parse the string data into a native object
+        // (IdempotentProducer expects native objects for JSON streams)
+        const normalizedContentType = contentType
+          .split(`;`)[0]
+          ?.trim()
+          .toLowerCase()
+        const isJson = normalizedContentType === `application/json`
+        const data = isJson ? JSON.parse(command.data) : command.data
+
+        try {
+          // append() is fire-and-forget (synchronous), then flush() sends the batch
+          producer.append(data)
+          await producer.flush()
+          await producer.close()
+
+          return {
+            type: `idempotent-append`,
+            success: true,
+            status: 200,
+          }
+        } catch (err) {
+          await producer.close()
+          throw err
+        }
+      } catch (err) {
+        return errorResult(`idempotent-append`, err)
+      }
+    }
+
+    case `idempotent-append-batch`: {
+      try {
+        const url = `${serverUrl}${command.path}`
+
+        // Get content-type from cache or use default
+        const contentType =
+          streamContentTypes.get(command.path) ?? `application/octet-stream`
+
+        const ds = new DurableStream({
+          url,
+          contentType,
+        })
+
+        // Use provided maxInFlight or default to 1 for compatibility
+        const maxInFlight = command.maxInFlight ?? 1
+
+        // When testing concurrency (maxInFlight > 1), use small batches to force
+        // multiple concurrent requests. Otherwise batch all items together.
+        const testingConcurrency = maxInFlight > 1
+        const producer = new IdempotentProducer(ds, command.producerId, {
+          epoch: command.epoch,
+          autoClaim: command.autoClaim,
+          maxInFlight,
+          lingerMs: testingConcurrency ? 0 : 1000,
+          maxBatchBytes: testingConcurrency ? 1 : 1024 * 1024,
+        })
+
+        // For JSON streams, parse string items into native objects
+        // (IdempotentProducer expects native objects for JSON streams)
+        const normalizedContentType = contentType
+          .split(`;`)[0]
+          ?.trim()
+          .toLowerCase()
+        const isJson = normalizedContentType === `application/json`
+        const items = isJson
+          ? command.items.map((item: string) => JSON.parse(item))
+          : command.items
+
+        try {
+          // append() is fire-and-forget (synchronous), adds to pending batch
+          for (const item of items) {
+            producer.append(item)
+          }
+
+          // flush() sends the batch and waits for completion
+          await producer.flush()
+          await producer.close()
+
+          return {
+            type: `idempotent-append-batch`,
+            success: true,
+            status: 200,
+          }
+        } catch (err) {
+          await producer.close()
+          throw err
+        }
+      } catch (err) {
+        return errorResult(`idempotent-append-batch`, err)
+      }
+    }
+
     default:
       return {
         type: `error`,
@@ -702,7 +814,7 @@ async function handleBenchmark(command: BenchmarkCommand): Promise<TestResult> {
 
           // Wait for data
           return new Promise<Uint8Array>((resolve) => {
-            const unsubscribe = res.subscribeBytes((chunk) => {
+            const unsubscribe = res.subscribeBytes(async (chunk) => {
               if (chunk.data.length > 0) {
                 unsubscribe()
                 res.cancel()
@@ -749,10 +861,19 @@ async function handleBenchmark(command: BenchmarkCommand): Promise<TestResult> {
         // Generate payload (using fill for speed - don't want to measure PRNG)
         const payload = new Uint8Array(operation.size).fill(42)
 
-        // Submit all messages at once - client batching will handle the rest
-        await Promise.all(
-          Array.from({ length: operation.count }, () => ds.append(payload))
-        )
+        // Use IdempotentProducer for automatic batching and pipelining
+        const producer = new IdempotentProducer(ds, `bench-producer`, {
+          lingerMs: 0, // No linger - send batches immediately when ready
+          onError: (err) => console.error(`Batch failed:`, err),
+        })
+
+        // Fire-and-forget: don't await individual appends, producer batches in background
+        for (let i = 0; i < operation.count; i++) {
+          producer.append(payload)
+        }
+
+        // Wait for all messages to be delivered
+        await producer.flush()
 
         metrics.bytesTransferred = operation.count * operation.size
         metrics.messagesProcessed = operation.count

package/src/protocol.ts

@@ -62,10 +62,54 @@ export interface AppendCommand {
   data: string
   /** Whether data is base64 encoded binary */
   binary?: boolean
-  /** Optional sequence number for ordering */
+  /** Optional sequence number for ordering (Stream-Seq header) */
   seq?: number
   /** Custom headers to include */
   headers?: Record<string, string>
+  /** Producer ID for idempotent producers */
+  producerId?: string
+  /** Producer epoch for idempotent producers */
+  producerEpoch?: number
+  /** Producer sequence for idempotent producers */
+  producerSeq?: number
+}
+
+/**
+ * Append via IdempotentProducer client (tests client-side exactly-once semantics).
+ */
+export interface IdempotentAppendCommand {
+  type: `idempotent-append`
+  path: string
+  /** Data to append (string - will be JSON parsed for JSON streams) */
+  data: string
+  /** Producer ID */
+  producerId: string
+  /** Producer epoch */
+  epoch: number
+  /** Auto-claim epoch on 403 */
+  autoClaim: boolean
+  /** Custom headers to include */
+  headers?: Record<string, string>
+}
+
+/**
+ * Batch append via IdempotentProducer client (tests client-side JSON batching).
+ */
+export interface IdempotentAppendBatchCommand {
+  type: `idempotent-append-batch`
+  path: string
+  /** Items to append - will be batched by the client */
+  items: Array<string>
+  /** Producer ID */
+  producerId: string
+  /** Producer epoch */
+  epoch: number
+  /** Auto-claim epoch on 403 */
+  autoClaim: boolean
+  /** Max concurrent batches in flight (default 1, set higher to test 409 retry) */
+  maxInFlight?: number
+  /** Custom headers to include */
+  headers?: Record<string, string>
 }
 
 /**
@@ -235,6 +279,8 @@ export type TestCommand =
   | CreateCommand
   | ConnectCommand
   | AppendCommand
+  | IdempotentAppendCommand
+  | IdempotentAppendBatchCommand
   | ReadCommand
   | HeadCommand
   | DeleteCommand
@@ -313,6 +359,42 @@ export interface AppendResult {
   headersSent?: Record<string, string>
   /** Params that were sent in the request (for dynamic param testing) */
   paramsSent?: Record<string, string>
+  /** Whether this was a duplicate (204 response) - for idempotent producers */
+  duplicate?: boolean
+  /** Current producer epoch from server (on 200 or 403) */
+  producerEpoch?: number
+  /** Server's highest accepted sequence for this (stream, producerId, epoch) - returned in Producer-Seq header on 200/204 */
+  producerSeq?: number
+  /** Expected producer sequence (on 409 sequence gap) */
+  producerExpectedSeq?: number
+  /** Received producer sequence (on 409 sequence gap) */
+  producerReceivedSeq?: number
+}
+
+/**
+ * Successful idempotent-append result.
+ */
+export interface IdempotentAppendResult {
+  type: `idempotent-append`
+  success: true
+  status: number
+  /** New offset after append */
+  offset?: string
+  /** Whether this was a duplicate */
+  duplicate?: boolean
+  /** Server's highest accepted sequence for this (stream, producerId, epoch) - returned in Producer-Seq header */
+  producerSeq?: number
+}
+
+/**
+ * Successful idempotent-append-batch result.
+ */
+export interface IdempotentAppendBatchResult {
+  type: `idempotent-append-batch`
+  success: true
+  status: number
+  /** Server's highest accepted sequence for this (stream, producerId, epoch) - returned in Producer-Seq header */
+  producerSeq?: number
 }
 
 /**
@@ -458,6 +540,8 @@ export type TestResult =
   | CreateResult
   | ConnectResult
   | AppendResult
+  | IdempotentAppendResult
+  | IdempotentAppendBatchResult
   | ReadResult
   | HeadResult
   | DeleteResult

package/src/runner.ts

@@ -366,6 +366,71 @@ async function executeOperation(
       }
     }
 
+    case `idempotent-append`: {
+      const path = resolveVariables(op.path, variables)
+      const data = resolveVariables(op.data, variables)
+
+      const result = await client.send(
+        {
+          type: `idempotent-append`,
+          path,
+          data,
+          producerId: op.producerId,
+          epoch: op.epoch ?? 0,
+          autoClaim: op.autoClaim ?? false,
+          headers: op.headers,
+        },
+        commandTimeout
+      )
+
+      if (verbose) {
+        console.log(
+          `  idempotent-append ${path}: ${result.success ? `ok` : `failed`}`
+        )
+      }
+
+      if (
+        result.success &&
+        result.type === `idempotent-append` &&
+        op.expect?.storeOffsetAs
+      ) {
+        variables.set(op.expect.storeOffsetAs, result.offset ?? ``)
+      }
+
+      return { result }
+    }
+
+    case `idempotent-append-batch`: {
+      const path = resolveVariables(op.path, variables)
+
+      // Send items to client which will batch them internally
+      const items = op.items.map((item) =>
+        resolveVariables(item.data, variables)
+      )
+
+      const result = await client.send(
+        {
+          type: `idempotent-append-batch`,
+          path,
+          items,
+          producerId: op.producerId,
+          epoch: op.epoch ?? 0,
+          autoClaim: op.autoClaim ?? false,
+          maxInFlight: op.maxInFlight,
+          headers: op.headers,
+        },
+        commandTimeout
+      )
+
+      if (verbose) {
+        console.log(
+          `  idempotent-append-batch ${path}: ${result.success ? `ok` : `failed`}`
+        )
+      }
+
+      return { result }
+    }
+
     case `read`: {
       const path = resolveVariables(op.path, variables)
       const offset = op.offset
@@ -538,7 +603,8 @@ async function executeOperation(
 
     case `server-append`: {
       // Direct HTTP append to server, bypassing client adapter
-      // Used for concurrent operations when adapter is blocked on a read
+      // Used for concurrent operations when adapter is blocked on a read,
+      // and for testing protocol-level behavior like idempotent producers
       const path = resolveVariables(op.path, variables)
       const data = resolveVariables(op.data, variables)
 
@@ -550,28 +616,72 @@ async function executeOperation(
         const contentType =
           headResponse.headers.get(`content-type`) ?? `application/octet-stream`
 
+        // Build headers, including producer headers if present
+        const headers: Record<string, string> = {
+          "content-type": contentType,
+          ...op.headers,
+        }
+        if (op.producerId !== undefined) {
+          headers[`Producer-Id`] = op.producerId
+        }
+        if (op.producerEpoch !== undefined) {
+          headers[`Producer-Epoch`] = op.producerEpoch.toString()
+        }
+        if (op.producerSeq !== undefined) {
+          headers[`Producer-Seq`] = op.producerSeq.toString()
+        }
+
         const response = await fetch(`${ctx.serverUrl}${path}`, {
           method: `POST`,
           body: data,
-          headers: {
-            "content-type": contentType,
-            ...op.headers,
-          },
+          headers,
         })
 
+        const status = response.status
+        const offset = response.headers.get(`Stream-Next-Offset`) ?? undefined
+        const duplicate = status === 204
+        const producerEpoch = response.headers.get(`Producer-Epoch`)
+        const producerSeq = response.headers.get(`Producer-Seq`)
+        const producerExpectedSeq = response.headers.get(
+          `Producer-Expected-Seq`
+        )
+        const producerReceivedSeq = response.headers.get(
+          `Producer-Received-Seq`
+        )
+
         if (verbose) {
           console.log(
-            `  server-append ${path}: ${response.ok ? `ok` : `failed (${response.status})`}`
+            `  server-append ${path}: status=${status}${duplicate ? ` (duplicate)` : ``}`
           )
         }
 
-        if (!response.ok) {
-          return {
-            error: `Server append failed with status ${response.status}`,
-          }
+        // Build result for expectation verification
+        // success: true means we got a valid protocol response (even 403/409)
+        // The status field indicates the actual operation result
+        const result: TestResult = {
+          type: `append`,
+          success: true,
+          status,
+          offset,
+          duplicate,
+          producerEpoch: producerEpoch
+            ? parseInt(producerEpoch, 10)
+            : undefined,
+          producerSeq: producerSeq ? parseInt(producerSeq, 10) : undefined,
+          producerExpectedSeq: producerExpectedSeq
+            ? parseInt(producerExpectedSeq, 10)
+            : undefined,
+          producerReceivedSeq: producerReceivedSeq
+            ? parseInt(producerReceivedSeq, 10)
+            : undefined,
         }
 
-        return {}
+        // Store offset if requested
+        if (op.expect?.storeOffsetAs && offset) {
+          variables.set(op.expect.storeOffsetAs, offset)
+        }
+
+        return { result }
       } catch (err) {
         return {
           error: `Server append failed: ${err instanceof Error ? err.message : String(err)}`,
@@ -796,6 +906,22 @@ function validateExpectation(
     }
   }
 
+  // Check dataExact - verifies exact messages in order
+  if (expect.dataExact !== undefined && isReadResult(result)) {
+    const expectedMessages = expect.dataExact as Array<string>
+    const actualMessages = result.chunks.map((c) => c.data)
+
+    if (actualMessages.length !== expectedMessages.length) {
+      return `Expected ${expectedMessages.length} messages, got ${actualMessages.length}. Expected: [${expectedMessages.join(`, `)}], got: [${actualMessages.join(`, `)}]`
+    }
+
+    for (let i = 0; i < expectedMessages.length; i++) {
+      if (actualMessages[i] !== expectedMessages[i]) {
+        return `Message ${i} mismatch: expected "${expectedMessages[i]}", got "${actualMessages[i]}"`
+      }
+    }
+  }
+
   // Check upToDate
   if (expect.upToDate !== undefined && isReadResult(result)) {
     if (result.upToDate !== expect.upToDate) {
@@ -878,6 +1004,41 @@ function validateExpectation(
     }
   }
 
+  // Check duplicate (for idempotent producer 204 responses)
+  if (expect.duplicate !== undefined && isAppendResult(result)) {
+    if (result.duplicate !== expect.duplicate) {
+      return `Expected duplicate=${expect.duplicate}, got ${result.duplicate}`
+    }
+  }
+
+  // Check producerEpoch (returned on 200/403)
+  if (expect.producerEpoch !== undefined && isAppendResult(result)) {
+    if (result.producerEpoch !== expect.producerEpoch) {
+      return `Expected producerEpoch=${expect.producerEpoch}, got ${result.producerEpoch}`
+    }
+  }
+
+  // Check producerSeq (returned on 200/204 - highest accepted sequence)
+  if (expect.producerSeq !== undefined && isAppendResult(result)) {
+    if (result.producerSeq !== expect.producerSeq) {
+      return `Expected producerSeq=${expect.producerSeq}, got ${result.producerSeq}`
+    }
+  }
+
+  // Check producerExpectedSeq (returned on 409 sequence gap)
+  if (expect.producerExpectedSeq !== undefined && isAppendResult(result)) {
+    if (result.producerExpectedSeq !== expect.producerExpectedSeq) {
+      return `Expected producerExpectedSeq=${expect.producerExpectedSeq}, got ${result.producerExpectedSeq}`
+    }
+  }
+
+  // Check producerReceivedSeq (returned on 409 sequence gap)
+  if (expect.producerReceivedSeq !== undefined && isAppendResult(result)) {
+    if (result.producerReceivedSeq !== expect.producerReceivedSeq) {
+      return `Expected producerReceivedSeq=${expect.producerReceivedSeq}, got ${result.producerReceivedSeq}`
+    }
+  }
+
   return null
 }
 
@@ -1061,8 +1222,12 @@ export async function runConformanceTests(
   const totalTests = countTests(suites)
   console.log(`\nRunning ${totalTests} client conformance tests...\n`)
 
-  // Start reference server
-  const server = new DurableStreamTestServer({ port: options.serverPort ?? 0 })
+  // Start reference server with short long-poll timeout for testing
+  // Tests use timeoutMs: 1000, so server timeout should be shorter
+  const server = new DurableStreamTestServer({
+    port: options.serverPort ?? 0,
+    longPollTimeout: 500, // 500ms timeout for testing
+  })
   await server.start()
   const serverUrl = server.url
 

package/src/test-cases.ts

@@ -118,10 +118,16 @@ export interface AppendOperation {
   data?: string
   /** Binary data (base64 encoded) */
   binaryData?: string
-  /** Sequence number for ordering */
+  /** Sequence number for ordering (Stream-Seq header) */
   seq?: number
   headers?: Record<string, string>
   expect?: AppendExpectation
+  /** Producer ID for idempotent producers */
+  producerId?: string
+  /** Producer epoch for idempotent producers */
+  producerEpoch?: number
+  /** Producer sequence for idempotent producers */
+  producerSeq?: number
 }
 
 /**
@@ -140,6 +146,64 @@ export interface AppendBatchOperation {
   expect?: AppendBatchExpectation
 }
 
+/**
+ * Append via IdempotentProducer client (tests client-side exactly-once semantics).
+ */
+export interface IdempotentAppendOperation {
+  action: `idempotent-append`
+  path: string
+  /** Producer ID */
+  producerId: string
+  /** Producer epoch */
+  epoch?: number
+  /** Data to append (string or JSON for JSON streams) */
+  data: string
+  /** Auto-claim epoch on 403 */
+  autoClaim?: boolean
+  headers?: Record<string, string>
+  expect?: IdempotentAppendExpectation
+}
+
+/**
+ * Batch append via IdempotentProducer client (tests client-side JSON batching).
+ */
+export interface IdempotentAppendBatchOperation {
+  action: `idempotent-append-batch`
+  path: string
+  /** Producer ID */
+  producerId: string
+  /** Producer epoch */
+  epoch?: number
+  /** Items to append (will be batched by the client) */
+  items: Array<{
+    data: string
+  }>
+  /** Auto-claim epoch on 403 */
+  autoClaim?: boolean
+  /** Max concurrent batches in flight (default 1, set higher to test 409 retry) */
+  maxInFlight?: number
+  headers?: Record<string, string>
+  expect?: IdempotentAppendBatchExpectation
+}
+
+/**
+ * Expectation for idempotent-append operation.
+ */
+export interface IdempotentAppendExpectation extends BaseExpectation {
+  /** Expected duplicate flag */
+  duplicate?: boolean
+  /** Store the returned offset */
+  storeOffsetAs?: string
+}
+
+/**
+ * Expectation for idempotent-append-batch operation.
+ */
+export interface IdempotentAppendBatchExpectation extends BaseExpectation {
+  /** All items should succeed */
+  allSucceed?: boolean
+}
+
 /**
  * Read from a stream.
  */
@@ -223,13 +287,42 @@ export interface AssertOperation {
 
 /**
  * Append to stream via direct server HTTP (bypasses client adapter).
- * Used for concurrent operations when adapter is blocked on a read.
+ * Used for concurrent operations when adapter is blocked on a read,
+ * and for testing protocol-level behavior like idempotent producers.
  */
 export interface ServerAppendOperation {
   action: `server-append`
   path: string
   data: string
   headers?: Record<string, string>
+  /** Producer ID for idempotent producers */
+  producerId?: string
+  /** Producer epoch for idempotent producers */
+  producerEpoch?: number
+  /** Producer sequence for idempotent producers */
+  producerSeq?: number
+  /** Expected result */
+  expect?: ServerAppendExpectation
+}
+
+/**
+ * Expectation for server-append operation.
+ */
+export interface ServerAppendExpectation {
+  /** Expected HTTP status code */
+  status?: number
+  /** Store the returned offset */
+  storeOffsetAs?: string
+  /** Expected duplicate flag (true for 204 idempotent success) */
+  duplicate?: boolean
+  /** Expected producer epoch in response */
+  producerEpoch?: number
+  /** Expected producer seq in response (highest accepted sequence) */
+  producerSeq?: number
+  /** Expected producer expected seq (on 409 sequence gap) */
+  producerExpectedSeq?: number
+  /** Expected producer received seq (on 409 sequence gap) */
+  producerReceivedSeq?: number
 }
 
 /**
@@ -320,6 +413,8 @@ export type TestOperation =
   | ConnectOperation
   | AppendOperation
   | AppendBatchOperation
+  | IdempotentAppendOperation
+  | IdempotentAppendBatchOperation
   | ReadOperation
   | HeadOperation
   | DeleteOperation
@@ -360,13 +455,23 @@ export interface ConnectExpectation extends BaseExpectation {
 }
 
 export interface AppendExpectation extends BaseExpectation {
-  status?: 200 | 404 | 409 | number
+  status?: 200 | 204 | 400 | 403 | 404 | 409 | number
   /** Store the returned offset */
   storeOffsetAs?: string
   /** Expected headers that were sent (for dynamic header testing) */
   headersSent?: Record<string, string>
   /** Expected params that were sent (for dynamic param testing) */
   paramsSent?: Record<string, string>
+  /** Expected duplicate flag (true for 204 idempotent success) */
+  duplicate?: boolean
+  /** Expected producer epoch in response */
+  producerEpoch?: number
+  /** Expected producer seq in response (highest accepted sequence) */
+  producerSeq?: number
+  /** Expected producer expected seq (on 409 sequence gap) */
+  producerExpectedSeq?: number
+  /** Expected producer received seq (on 409 sequence gap) */
+  producerReceivedSeq?: number
 }
 
 export interface AppendBatchExpectation extends BaseExpectation {
@@ -386,6 +491,8 @@ export interface ReadExpectation extends BaseExpectation {
   dataContains?: string
   /** Expected data to contain all of these substrings */
   dataContainsAll?: Array<string>
+  /** Expected exact messages in order (for JSON streams, verifies each chunk) */
+  dataExact?: Array<string>
   /** Expected number of chunks */
   chunkCount?: number
   /** Minimum number of chunks */