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

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

@@ -56,6 +56,48 @@ tests:
           status: 400
           errorCode: INVALID_OFFSET
 
+  - id: read-offset-now-nonexistent
+    name: Read with offset=now on non-existent stream
+    description: offset=now should not mask a missing stream - must return 404
+    operations:
+      - action: read
+        path: /nonexistent-offset-now-stream
+        offset: "now"
+        live: false
+        expect:
+          status: 404
+          errorCode: NOT_FOUND
+
+  - id: read-offset-now-nonexistent-longpoll
+    name: Long-poll with offset=now on non-existent stream
+    description: offset=now with long-poll should not mask a missing stream - must return 404
+    requires:
+      - longPoll
+    operations:
+      - action: read
+        path: /nonexistent-offset-now-longpoll
+        offset: "now"
+        live: long-poll
+        timeoutMs: 1000
+        expect:
+          status: 404
+          errorCode: NOT_FOUND
+
+  - id: read-offset-now-nonexistent-sse
+    name: SSE with offset=now on non-existent stream
+    description: offset=now with SSE should not mask a missing stream - must return 404
+    requires:
+      - sse
+    operations:
+      - action: read
+        path: /nonexistent-offset-now-sse
+        offset: "now"
+        live: sse
+        timeoutMs: 1000
+        expect:
+          status: 404
+          errorCode: NOT_FOUND
+
   - id: read-future-offset
     name: Read with future offset
     description: Client should handle offset beyond stream end

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

@@ -30,6 +30,215 @@ tests:
         expect:
           data: "beginningmiddleend"
 
+  - id: offset-now-skips-historical
+    name: Offset 'now' skips historical data
+    description: Using offset=now should return empty body with tail offset
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "historical"
+      - action: append
+        path: ${streamPath}
+        data: "data"
+    operations:
+      - action: read
+        path: ${streamPath}
+        offset: "now"
+        expect:
+          chunkCount: 0
+          upToDate: true
+          storeOffsetAs: nowOffset
+      # Verify we can resume from the offset
+      - action: append
+        path: ${streamPath}
+        data: "future"
+      - action: read
+        path: ${streamPath}
+        offset: ${nowOffset}
+        expect:
+          data: "future"
+
+  - id: offset-now-empty-stream
+    name: Offset 'now' on empty stream
+    description: Using offset=now on an empty stream should work correctly
+    setup:
+      - action: create
+        as: streamPath
+    operations:
+      - action: read
+        path: ${streamPath}
+        offset: "now"
+        expect:
+          chunkCount: 0
+          upToDate: true
+          storeOffsetAs: startOffset
+      # Verify the offset works for future data
+      - action: append
+        path: ${streamPath}
+        data: "firstdata"
+      - action: read
+        path: ${streamPath}
+        offset: ${startOffset}
+        expect:
+          data: "firstdata"
+
+  - id: offset-now-empty-stream-longpoll
+    name: Offset 'now' on empty stream with long-poll
+    description: Using offset=now with long-poll on an empty stream should wait for data
+    requires:
+      - longPoll
+    setup:
+      - action: create
+        as: streamPath
+    operations:
+      # Long-poll with offset=now on empty stream should timeout
+      - action: read
+        path: ${streamPath}
+        offset: "now"
+        live: long-poll
+        timeoutMs: 1000
+        expect:
+          status: 204
+          upToDate: true
+          storeOffsetAs: pollOffset
+      # Verify the offset is valid and works for future data
+      - action: append
+        path: ${streamPath}
+        data: "firstdata"
+      - action: read
+        path: ${streamPath}
+        offset: ${pollOffset}
+        expect:
+          data: "firstdata"
+
+  - id: offset-now-empty-stream-sse
+    name: Offset 'now' on empty stream with SSE
+    description: Using offset=now with SSE on an empty stream should provide valid offset
+    requires:
+      - sse
+    setup:
+      - action: create
+        as: streamPath
+    operations:
+      # SSE with offset=now on empty stream
+      - action: read
+        path: ${streamPath}
+        offset: "now"
+        live: sse
+        waitForUpToDate: true
+        expect:
+          chunkCount: 0
+          upToDate: true
+          storeOffsetAs: sseOffset
+      # Verify the offset is valid and works for future data
+      - action: append
+        path: ${streamPath}
+        data: "firstdata"
+      - action: read
+        path: ${streamPath}
+        offset: ${sseOffset}
+        expect:
+          data: "firstdata"
+
+  - id: offset-now-matches-tail
+    name: Offset 'now' returns same offset as tail
+    description: The offset from offset=now should match the stream tail offset
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "somedata"
+    operations:
+      # Get tail offset via normal read
+      - action: read
+        path: ${streamPath}
+        expect:
+          storeOffsetAs: tailOffset
+      # Get offset via offset=now
+      - action: read
+        path: ${streamPath}
+        offset: "now"
+        expect:
+          storeOffsetAs: nowOffset
+      # Append and verify both offsets work identically
+      - action: append
+        path: ${streamPath}
+        data: "newdata"
+      - action: read
+        path: ${streamPath}
+        offset: ${tailOffset}
+        expect:
+          data: "newdata"
+      - action: read
+        path: ${streamPath}
+        offset: ${nowOffset}
+        expect:
+          data: "newdata"
+
+  - id: offset-now-longpoll-waits
+    name: Offset 'now' with long-poll immediately waits for data
+    description: Using offset=now with long-poll should immediately start waiting for new data (no round trip)
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "existingdata"
+    operations:
+      # Long-poll with offset=now should timeout with 204 since no new data arrives
+      # This proves it immediately started waiting (skipping historical data)
+      - action: read
+        path: ${streamPath}
+        offset: "now"
+        live: long-poll
+        timeoutMs: 1000
+        expect:
+          status: 204
+          upToDate: true
+          storeOffsetAs: pollOffset
+      # Verify the offset works for future data
+      - action: append
+        path: ${streamPath}
+        data: "afterpoll"
+      - action: read
+        path: ${streamPath}
+        offset: ${pollOffset}
+        expect:
+          data: "afterpoll"
+
+  - id: offset-now-sse
+    name: Offset 'now' with SSE mode
+    description: Using offset=now with SSE should skip historical data and provide correct offset
+    requires:
+      - sse
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "historicalsse"
+    operations:
+      - action: read
+        path: ${streamPath}
+        offset: "now"
+        live: sse
+        waitForUpToDate: true
+        expect:
+          chunkCount: 0
+          storeOffsetAs: sseOffset
+      # Verify offset works
+      - action: append
+        path: ${streamPath}
+        data: "futuredata"
+      - action: read
+        path: ${streamPath}
+        offset: ${sseOffset}
+        expect:
+          data: "futuredata"
+
   - id: offset-empty-stream
     name: Read from empty stream
     description: Reading from an empty stream should return no data and up-to-date

package/test-cases/producer/idempotent/autoclaim.yaml

@@ -0,0 +1,214 @@
+id: idempotent-autoclaim
+name: Idempotent Producer - AutoClaim
+description: |
+  Tests for the autoClaim feature that enables ephemeral producers.
+  When autoClaim=true, the client automatically claims the next epoch
+  when fenced (403) and blocks pipelining until epoch is known.
+category: producer
+tags:
+  - idempotent
+  - autoclaim
+  - ephemeral
+
+tests:
+  - id: autoclaim-with-pipelining
+    name: autoClaim works with maxInFlight > 1
+    description: |
+      When autoClaim is true, the client should block pipelining until the first batch
+      completes and the epoch is known. After that, full pipelining should be enabled.
+      This test verifies that autoClaim + maxInFlight > 1 works correctly.
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      # Send 20 messages with autoClaim=true and maxInFlight=5
+      # The first batch should block until epoch is claimed, then pipelining kicks in
+      - action: idempotent-append-batch
+        path: ${streamPath}
+        producerId: autoclaim-producer
+        autoClaim: true
+        maxInFlight: 5
+        items:
+          - data: "ac-00"
+          - data: "ac-01"
+          - data: "ac-02"
+          - data: "ac-03"
+          - data: "ac-04"
+          - data: "ac-05"
+          - data: "ac-06"
+          - data: "ac-07"
+          - data: "ac-08"
+          - data: "ac-09"
+          - data: "ac-10"
+          - data: "ac-11"
+          - data: "ac-12"
+          - data: "ac-13"
+          - data: "ac-14"
+          - data: "ac-15"
+          - data: "ac-16"
+          - data: "ac-17"
+          - data: "ac-18"
+          - data: "ac-19"
+        expect:
+          allSucceed: true
+      # Verify all messages are in the stream
+      - action: read
+        path: ${streamPath}
+        expect:
+          dataContainsAll:
+            - "ac-00"
+            - "ac-05"
+            - "ac-10"
+            - "ac-15"
+            - "ac-19"
+          upToDate: true
+
+  - id: autoclaim-with-pipelining-json
+    name: autoClaim with pipelining works for JSON streams
+    description: Same test with JSON content type
+    setup:
+      - action: create
+        as: streamPath
+        contentType: application/json
+    operations:
+      - action: idempotent-append-batch
+        path: ${streamPath}
+        producerId: autoclaim-json-producer
+        autoClaim: true
+        maxInFlight: 5
+        items:
+          - data: '{"msg": 0}'
+          - data: '{"msg": 1}'
+          - data: '{"msg": 2}'
+          - data: '{"msg": 3}'
+          - data: '{"msg": 4}'
+          - data: '{"msg": 5}'
+          - data: '{"msg": 6}'
+          - data: '{"msg": 7}'
+          - data: '{"msg": 8}'
+          - data: '{"msg": 9}'
+        expect:
+          allSucceed: true
+      - action: read
+        path: ${streamPath}
+        expect:
+          dataContainsAll:
+            - '"msg":0'
+            - '"msg":5'
+            - '"msg":9'
+          upToDate: true
+
+  - id: autoclaim-recovers-from-stale-epoch
+    name: autoClaim recovers when fenced by newer epoch
+    description: |
+      If a producer with autoClaim gets 403 (stale epoch) because another instance
+      claimed a higher epoch, it should automatically bump its epoch and retry.
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      # Establish epoch=5 via raw server-append (simulating another producer instance)
+      - action: server-append
+        path: ${streamPath}
+        data: "from-epoch-5"
+        producerId: recovery-producer
+        producerEpoch: 5
+        producerSeq: 0
+        expect:
+          status: 200
+      # Client with autoClaim starts at epoch=0, should get 403 then recover with epoch=6
+      - action: idempotent-append
+        path: ${streamPath}
+        producerId: recovery-producer
+        epoch: 0
+        autoClaim: true
+        data: "recovered"
+        expect:
+          success: true
+      # Verify both messages are in the stream
+      - action: read
+        path: ${streamPath}
+        expect:
+          dataContainsAll:
+            - "from-epoch-5"
+            - "recovered"
+          upToDate: true
+
+  - id: autoclaim-recovers-from-403
+    name: Client with autoClaim recovers from 403 fencing
+    description: |
+      When a producer with autoClaim=true gets fenced (403), it should
+      automatically claim the next epoch and retry successfully.
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      # Another producer claims epoch=5
+      - action: server-append
+        path: ${streamPath}
+        data: "fencer"
+        producerId: autoclaim-producer
+        producerEpoch: 5
+        producerSeq: 0
+        expect:
+          status: 200
+      # Now use idempotent-append with autoClaim starting at epoch=0
+      # It should get 403, then retry with epoch=6
+      - action: idempotent-append
+        path: ${streamPath}
+        producerId: autoclaim-producer
+        epoch: 0
+        autoClaim: true
+        data: "recovered"
+        expect:
+          success: true
+      # Verify both messages are in stream
+      - action: read
+        path: ${streamPath}
+        expect:
+          dataContainsAll:
+            - "fencer"
+            - "recovered"
+          upToDate: true
+
+  - id: autoclaim-batch-recovers-from-403
+    name: Batch with autoClaim recovers from 403 fencing
+    description: Same test for batch operations
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      # Another producer claims epoch=3
+      - action: server-append
+        path: ${streamPath}
+        data: "blocker"
+        producerId: batch-autoclaim
+        producerEpoch: 3
+        producerSeq: 0
+        expect:
+          status: 200
+      # Batch with autoClaim should recover
+      - action: idempotent-append-batch
+        path: ${streamPath}
+        producerId: batch-autoclaim
+        autoClaim: true
+        maxInFlight: 1
+        items:
+          - data: "batch-msg-0"
+          - data: "batch-msg-1"
+          - data: "batch-msg-2"
+        expect:
+          allSucceed: true
+      - action: read
+        path: ${streamPath}
+        expect:
+          dataContainsAll:
+            - "blocker"
+            - "batch-msg-0"
+            - "batch-msg-1"
+            - "batch-msg-2"
+          upToDate: true

package/test-cases/producer/idempotent/batching.yaml

@@ -0,0 +1,98 @@
+id: idempotent-batching
+name: Idempotent Producer - Batching
+description: |
+  Tests for producer batching behavior and header interactions.
+  Batches are atomic - the entire batch shares a single sequence number.
+category: producer
+tags:
+  - idempotent
+  - batching
+
+tests:
+  - id: batch-retry-deduplication
+    name: Retrying entire batch returns 204 for all
+    description: If client retries an entire JSON batch, server should deduplicate
+    setup:
+      - action: create
+        as: streamPath
+        contentType: application/json
+    operations:
+      # Send a batch of 3 items
+      - action: server-append
+        path: ${streamPath}
+        data: '[{"id":1},{"id":2},{"id":3}]'
+        producerId: batch-retry-producer
+        producerEpoch: 0
+        producerSeq: 0
+        expect:
+          status: 200
+      # Retry the exact same batch - should get 204
+      - action: server-append
+        path: ${streamPath}
+        data: '[{"id":1},{"id":2},{"id":3}]'
+        producerId: batch-retry-producer
+        producerEpoch: 0
+        producerSeq: 0
+        expect:
+          status: 204
+          duplicate: true
+      # Verify only 3 items in stream (not 6)
+      - action: read
+        path: ${streamPath}
+        expect:
+          upToDate: true
+      # Next seq should still work
+      - action: server-append
+        path: ${streamPath}
+        data: '[{"id":4}]'
+        producerId: batch-retry-producer
+        producerEpoch: 0
+        producerSeq: 1
+        expect:
+          status: 200
+
+  - id: producer-with-stream-seq
+    name: Producer headers work with Stream-Seq header
+    description: Both producer deduplication and writer coordination should work together
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      - action: server-append
+        path: ${streamPath}
+        data: "msg"
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 0
+        headers:
+          Stream-Seq: "app-seq-001"
+        expect:
+          status: 200
+
+  - id: duplicate-json-different-payload
+    name: Duplicate JSON with different payload returns 204
+    description: Same test for JSON content type - dedup is by headers only
+    setup:
+      - action: create
+        as: streamPath
+        contentType: application/json
+    operations:
+      - action: server-append
+        path: ${streamPath}
+        data: '{"key": "original"}'
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 0
+        expect:
+          status: 200
+      # Retry with different JSON payload
+      - action: server-append
+        path: ${streamPath}
+        data: '{"key": "different", "extra": true}'
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 0
+        expect:
+          status: 204
+          duplicate: true

package/test-cases/producer/idempotent/concurrent-requests.yaml

@@ -0,0 +1,100 @@
+id: idempotent-concurrent-requests
+name: Idempotent Producer - Concurrent Requests
+description: |
+  Tests for client handling of concurrent HTTP requests (pipelining).
+  When maxInFlight > 1, requests may arrive out of order causing 409 errors.
+  The client must retry and ensure all messages are delivered.
+category: producer
+tags:
+  - idempotent
+  - concurrent
+  - pipelining
+  - retry
+
+tests:
+  - id: concurrent-batches-all-delivered
+    name: All messages delivered with high concurrency
+    description: |
+      When using maxInFlight > 1, HTTP requests may arrive out of order causing 409 errors.
+      The client should retry and ensure all messages are delivered.
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      # Send 20 messages with maxInFlight=5
+      # This forces concurrent batches that may arrive out of order
+      - action: idempotent-append-batch
+        path: ${streamPath}
+        producerId: test-producer
+        epoch: 0
+        maxInFlight: 5
+        items:
+          - data: "msg-00"
+          - data: "msg-01"
+          - data: "msg-02"
+          - data: "msg-03"
+          - data: "msg-04"
+          - data: "msg-05"
+          - data: "msg-06"
+          - data: "msg-07"
+          - data: "msg-08"
+          - data: "msg-09"
+          - data: "msg-10"
+          - data: "msg-11"
+          - data: "msg-12"
+          - data: "msg-13"
+          - data: "msg-14"
+          - data: "msg-15"
+          - data: "msg-16"
+          - data: "msg-17"
+          - data: "msg-18"
+          - data: "msg-19"
+        expect:
+          allSucceed: true
+      # Verify all messages are in the stream
+      - action: read
+        path: ${streamPath}
+        expect:
+          dataContainsAll:
+            - "msg-00"
+            - "msg-05"
+            - "msg-10"
+            - "msg-15"
+            - "msg-19"
+          upToDate: true
+
+  - id: concurrent-json-batches-all-delivered
+    name: All JSON messages delivered with high concurrency
+    description: Same test with JSON content type to verify JSON batching works with concurrency
+    setup:
+      - action: create
+        as: streamPath
+        contentType: application/json
+    operations:
+      - action: idempotent-append-batch
+        path: ${streamPath}
+        producerId: test-producer
+        epoch: 0
+        maxInFlight: 5
+        items:
+          - data: '{"id": 0}'
+          - data: '{"id": 1}'
+          - data: '{"id": 2}'
+          - data: '{"id": 3}'
+          - data: '{"id": 4}'
+          - data: '{"id": 5}'
+          - data: '{"id": 6}'
+          - data: '{"id": 7}'
+          - data: '{"id": 8}'
+          - data: '{"id": 9}'
+        expect:
+          allSucceed: true
+      - action: read
+        path: ${streamPath}
+        expect:
+          dataContainsAll:
+            - '"id":0'
+            - '"id":5'
+            - '"id":9'
+          upToDate: true