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

package/test-cases/producer/idempotent/epoch-management.yaml

@@ -0,0 +1,333 @@
+id: idempotent-epoch-management
+name: Idempotent Producer - Epoch Management
+description: |
+  Tests for producer epoch validation and zombie fencing.
+  Epochs enable split-brain protection - only the latest instance can write.
+category: producer
+tags:
+  - idempotent
+  - epoch
+  - fencing
+
+tests:
+  - id: epoch-upgrade-accepted
+    name: Epoch upgrade resets sequence to 0
+    description: New epoch must start at seq=0 and should be accepted
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      - action: server-append
+        path: ${streamPath}
+        data: "epoch0-msg0"
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 0
+        expect:
+          status: 200
+      - action: server-append
+        path: ${streamPath}
+        data: "epoch0-msg1"
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 1
+        expect:
+          status: 200
+      # Upgrade to epoch=1
+      - action: server-append
+        path: ${streamPath}
+        data: "epoch1-msg0"
+        producerId: test-producer
+        producerEpoch: 1
+        producerSeq: 0
+        expect:
+          status: 200
+          producerEpoch: 1
+
+  - id: stale-epoch-rejected
+    name: Stale epoch returns 403 (zombie fencing)
+    description: Old epoch should be rejected with 403 and current epoch in response
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      # Establish epoch=1
+      - action: server-append
+        path: ${streamPath}
+        data: "msg"
+        producerId: test-producer
+        producerEpoch: 1
+        producerSeq: 0
+        expect:
+          status: 200
+      # Try to write with stale epoch=0
+      - action: server-append
+        path: ${streamPath}
+        data: "zombie"
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 0
+        expect:
+          status: 403
+          producerEpoch: 1
+
+  - id: epoch-rollback-rejected
+    name: Epoch rollback is rejected
+    description: Cannot go back to a lower epoch
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      # Establish epoch=2
+      - action: server-append
+        path: ${streamPath}
+        data: "msg"
+        producerId: test-producer
+        producerEpoch: 2
+        producerSeq: 0
+        expect:
+          status: 200
+      # Try epoch=1 (rollback)
+      - action: server-append
+        path: ${streamPath}
+        data: "rollback"
+        producerId: test-producer
+        producerEpoch: 1
+        producerSeq: 0
+        expect:
+          status: 403
+
+  - id: epoch-increase-requires-seq-zero
+    name: Epoch increase with seq != 0 is rejected
+    description: New epoch must start at seq=0
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      - action: server-append
+        path: ${streamPath}
+        data: "msg"
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 0
+        expect:
+          status: 200
+      # Try epoch=1 with seq=5
+      - action: server-append
+        path: ${streamPath}
+        data: "bad"
+        producerId: test-producer
+        producerEpoch: 1
+        producerSeq: 5
+        expect:
+          status: 400
+
+  - id: epoch-gap-allowed
+    name: Epoch can skip values (gap allowed)
+    description: |
+      Epochs don't need to be sequential. Jumping from epoch=0 to epoch=10
+      should be allowed (unlike sequences which must be sequential).
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      - action: server-append
+        path: ${streamPath}
+        data: "epoch0"
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 0
+        expect:
+          status: 200
+      # Jump to epoch=10 (skipping 1-9)
+      - action: server-append
+        path: ${streamPath}
+        data: "epoch10"
+        producerId: test-producer
+        producerEpoch: 10
+        producerSeq: 0
+        expect:
+          status: 200
+      # Previous epochs now fenced
+      - action: server-append
+        path: ${streamPath}
+        data: "epoch5"
+        producerId: test-producer
+        producerEpoch: 5
+        producerSeq: 0
+        expect:
+          status: 403
+          producerEpoch: 10
+
+  - id: epoch-zero-after-higher-epoch
+    name: Epoch 0 rejected after higher epoch established
+    description: |
+      Once a higher epoch is established, epoch=0 should be rejected.
+      This is critical for zombie fencing.
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      # Establish epoch=5
+      - action: server-append
+        path: ${streamPath}
+        data: "epoch5"
+        producerId: test-producer
+        producerEpoch: 5
+        producerSeq: 0
+        expect:
+          status: 200
+      # Epoch 0 should be fenced
+      - action: server-append
+        path: ${streamPath}
+        data: "epoch0-zombie"
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 0
+        expect:
+          status: 403
+          producerEpoch: 5
+      # Epoch 4 should also be fenced
+      - action: server-append
+        path: ${streamPath}
+        data: "epoch4-zombie"
+        producerId: test-producer
+        producerEpoch: 4
+        producerSeq: 0
+        expect:
+          status: 403
+          producerEpoch: 5
+
+  - id: split-brain-fencing
+    name: Split-brain fencing scenario
+    description: Old producer instance (zombie) should be fenced when new instance claims higher epoch
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      # Producer A (original): epoch=0
+      - action: server-append
+        path: ${streamPath}
+        data: "A0"
+        producerId: shared-producer
+        producerEpoch: 0
+        producerSeq: 0
+        expect:
+          status: 200
+      # Producer B (new instance): claims epoch=1
+      - action: server-append
+        path: ${streamPath}
+        data: "B0"
+        producerId: shared-producer
+        producerEpoch: 1
+        producerSeq: 0
+        expect:
+          status: 200
+      # Producer A (zombie): tries epoch=0, seq=1 - should be fenced
+      - action: server-append
+        path: ${streamPath}
+        data: "A1"
+        producerId: shared-producer
+        producerEpoch: 0
+        producerSeq: 1
+        expect:
+          status: 403
+          producerEpoch: 1
+
+  - id: large-epoch-numbers
+    name: Large epoch numbers handled correctly
+    description: Test that large epoch values work correctly
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      - action: server-append
+        path: ${streamPath}
+        data: "large-epoch"
+        producerId: test-producer
+        producerEpoch: 2147483640
+        producerSeq: 0
+        expect:
+          status: 200
+      # Stale epoch should still be rejected
+      - action: server-append
+        path: ${streamPath}
+        data: "stale"
+        producerId: test-producer
+        producerEpoch: 100
+        producerSeq: 0
+        expect:
+          status: 403
+          producerEpoch: 2147483640
+
+  - id: sequence-resets-on-epoch-upgrade
+    name: Each epoch has independent sequence space
+    description: |
+      Sequence numbers reset to 0 with each epoch upgrade.
+      The old epoch's sequences don't affect the new epoch.
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      # Epoch 0: sequences 0, 1, 2
+      - action: server-append
+        path: ${streamPath}
+        data: "e0s0"
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 0
+        expect:
+          status: 200
+      - action: server-append
+        path: ${streamPath}
+        data: "e0s1"
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 1
+        expect:
+          status: 200
+      - action: server-append
+        path: ${streamPath}
+        data: "e0s2"
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 2
+        expect:
+          status: 200
+      # Epoch 1: starts fresh at seq=0
+      - action: server-append
+        path: ${streamPath}
+        data: "e1s0"
+        producerId: test-producer
+        producerEpoch: 1
+        producerSeq: 0
+        expect:
+          status: 200
+      - action: server-append
+        path: ${streamPath}
+        data: "e1s1"
+        producerId: test-producer
+        producerEpoch: 1
+        producerSeq: 1
+        expect:
+          status: 200
+      # Verify all 5 messages present
+      - action: read
+        path: ${streamPath}
+        expect:
+          dataContainsAll:
+            - "e0s0"
+            - "e0s1"
+            - "e0s2"
+            - "e1s0"
+            - "e1s1"
+          upToDate: true

package/test-cases/producer/idempotent/error-handling.yaml

@@ -0,0 +1,194 @@
+id: idempotent-error-handling
+name: Idempotent Producer - Error Handling
+description: |
+  Tests for producer header validation and error conditions.
+  Includes atomicity guarantees when appends fail.
+category: producer
+tags:
+  - idempotent
+  - validation
+  - errors
+
+tests:
+  - id: partial-headers-rejected
+    name: Partial producer headers are rejected
+    description: All three producer headers must be provided together
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      # Only Producer-Id
+      - action: server-append
+        path: ${streamPath}
+        data: "msg"
+        headers:
+          Producer-Id: test-producer
+        expect:
+          status: 400
+      # Missing Producer-Seq
+      - action: server-append
+        path: ${streamPath}
+        data: "msg"
+        headers:
+          Producer-Id: test-producer
+          Producer-Epoch: "0"
+        expect:
+          status: 400
+
+  - id: invalid-integer-formats-rejected
+    name: Invalid integer formats in producer headers are rejected
+    description: Server should reject non-integer values like "1abc" or "1e3"
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      # Trailing junk in Producer-Seq
+      - action: server-append
+        path: ${streamPath}
+        data: "msg"
+        headers:
+          Producer-Id: test-producer
+          Producer-Epoch: "0"
+          Producer-Seq: "1abc"
+        expect:
+          status: 400
+      # Scientific notation
+      - action: server-append
+        path: ${streamPath}
+        data: "msg"
+        headers:
+          Producer-Id: test-producer
+          Producer-Epoch: "1e3"
+          Producer-Seq: "0"
+        expect:
+          status: 400
+      # Negative value
+      - action: server-append
+        path: ${streamPath}
+        data: "msg"
+        headers:
+          Producer-Id: test-producer
+          Producer-Epoch: "-1"
+          Producer-Seq: "0"
+        expect:
+          status: 400
+
+  - id: empty-producer-id-rejected
+    name: Empty producer ID is rejected
+    description: Producer-Id header with empty string should be rejected
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      - action: server-append
+        path: ${streamPath}
+        data: "msg"
+        headers:
+          Producer-Id: ""
+          Producer-Epoch: "0"
+          Producer-Seq: "0"
+        expect:
+          status: 400
+
+  - id: failed-append-does-not-advance-producer-state
+    name: Failed append does not advance producer state (atomicity)
+    description: If append fails after producer validation (e.g., invalid JSON), producer seq should not advance
+    setup:
+      - action: create
+        as: streamPath
+        contentType: application/json
+    operations:
+      # First append succeeds
+      - action: server-append
+        path: ${streamPath}
+        data: '{"msg": 1}'
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 0
+        expect:
+          status: 200
+      # Second append with invalid JSON - should fail
+      - action: server-append
+        path: ${streamPath}
+        data: "not valid json"
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 1
+        expect:
+          status: 400
+      # Retry seq=1 with valid JSON - should succeed (not be rejected as duplicate or gap)
+      # If producer state was incorrectly advanced, this would fail
+      - action: server-append
+        path: ${streamPath}
+        data: '{"msg": 2}'
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 1
+        expect:
+          status: 200
+      # seq=2 should also work
+      - action: server-append
+        path: ${streamPath}
+        data: '{"msg": 3}'
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 2
+        expect:
+          status: 200
+
+  - id: gap-fill-resume
+    name: Gap can be filled and producer can resume
+    description: |
+      After a 409 gap error, the producer should be able to fill the gap
+      and then continue. Some implementations accidentally "lock out" a
+      sequence once a gap was observed, or mutate state on the 409 path.
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      # seq=0 succeeds
+      - action: server-append
+        path: ${streamPath}
+        data: "msg0"
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 0
+        expect:
+          status: 200
+      # seq=2 creates a gap -> 409
+      - action: server-append
+        path: ${streamPath}
+        data: "msg2"
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 2
+        expect:
+          status: 409
+      # Fill the gap with seq=1
+      - action: server-append
+        path: ${streamPath}
+        data: "msg1"
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 1
+        expect:
+          status: 200
+      # Now seq=2 should succeed
+      - action: server-append
+        path: ${streamPath}
+        data: "msg2"
+        producerId: test-producer
+        producerEpoch: 0
+        producerSeq: 2
+        expect:
+          status: 200
+      # Verify correct order in stream (text/plain concatenates all data)
+      - action: read
+        path: ${streamPath}
+        expect:
+          data: "msg0msg1msg2"
+          upToDate: true