@durable-streams/client-conformance-tests 0.1.8 → 0.1.9

package/test-cases/consumer/read-auto.yaml

@@ -0,0 +1,155 @@
+id: consumer-auto
+name: Auto Live Mode
+description: Tests for auto live mode that catches up first then transitions to live tailing
+category: consumer
+tags:
+  - core
+  - read
+  - auto
+  - live
+requires:
+  - auto
+
+tests:
+  - id: auto-catches-up-with-existing-data
+    name: Auto mode catches up with existing data first
+    description: Auto mode should read all existing data before entering live mode
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "data1"
+      - action: append
+        path: ${streamPath}
+        data: "data2"
+      - action: append
+        path: ${streamPath}
+        data: "data3"
+    operations:
+      - action: read
+        path: ${streamPath}
+        live: true
+        timeoutMs: 2000
+        waitForUpToDate: true
+        expect:
+          data: "data1data2data3"
+          upToDate: true
+
+  - id: auto-waits-for-new-data
+    name: Auto mode waits for new data after catching up
+    description: After catching up, auto mode should wait for new data
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "initial"
+        expect:
+          storeOffsetAs: initialOffset
+    operations:
+      # Start auto read in background (will catch up then wait)
+      - action: read
+        path: ${streamPath}
+        offset: ${initialOffset}
+        live: true
+        timeoutMs: 10000
+        background: true
+        as: readOp
+      # Wait for the read to start and catch up
+      - action: wait
+        ms: 300
+      # Append new data
+      - action: server-append
+        path: ${streamPath}
+        data: "new-data"
+      # Wait for the background read to receive the data
+      - action: await
+        ref: readOp
+        expect:
+          dataContains: "new-data"
+
+  - id: auto-returns-immediately-on-existing-data
+    name: Auto mode returns immediately with existing data
+    description: Auto mode should not delay when there's data to return
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "existing"
+    operations:
+      - action: read
+        path: ${streamPath}
+        live: true
+        timeoutMs: 1000
+        waitForUpToDate: true
+        expect:
+          data: "existing"
+          upToDate: true
+
+  - id: auto-resumes-from-offset
+    name: Auto mode resumes from provided offset
+    description: Auto mode should start from the given offset, not beginning
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "old-data"
+        expect:
+          storeOffsetAs: offset
+      - action: append
+        path: ${streamPath}
+        data: "new-data"
+    operations:
+      - action: read
+        path: ${streamPath}
+        offset: ${offset}
+        live: true
+        timeoutMs: 1000
+        waitForUpToDate: true
+        expect:
+          data: "new-data"
+          upToDate: true
+
+  - id: auto-empty-stream
+    name: Auto mode handles empty stream
+    description: Auto mode should handle empty streams gracefully
+    setup:
+      - action: create
+        as: streamPath
+    operations:
+      - action: read
+        path: ${streamPath}
+        live: true
+        timeoutMs: 500
+        waitForUpToDate: true
+        expect:
+          chunkCount: 0
+          upToDate: true
+
+  - id: auto-multiple-chunks
+    name: Auto mode collects multiple chunks
+    description: Auto mode should receive multiple data chunks
+    setup:
+      - action: create
+        as: streamPath
+    operations:
+      - action: append
+        path: ${streamPath}
+        data: "chunk1"
+      - action: append
+        path: ${streamPath}
+        data: "chunk2"
+      - action: append
+        path: ${streamPath}
+        data: "chunk3"
+      - action: read
+        path: ${streamPath}
+        live: true
+        timeoutMs: 2000
+        waitForUpToDate: true
+        expect:
+          data: "chunk1chunk2chunk3"
+          upToDate: true

package/test-cases/consumer/read-sse.yaml

@@ -230,3 +230,27 @@ tests:
         expect:
           data: "a\u0085b\u2028c\u2029d"
           minChunks: 1
+
+  - id: sse-strips-single-leading-space
+    name: SSE strips only single leading space
+    description: |
+      Per EventSource spec section 9.2.4: "If value starts with a
+      U+0020 SPACE character, remove it from value."
+      Only ONE space should be removed, preserving any additional spaces.
+      This prevents parsers from using trim() or similar which would
+      incorrectly strip all leading/trailing whitespace.
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+      - action: append
+        path: ${streamPath}
+        data: "  two leading spaces"
+    operations:
+      - action: read
+        path: ${streamPath}
+        live: sse
+        waitForUpToDate: true
+        expect:
+          data: " two leading spaces"
+          minChunks: 1

package/test-cases/consumer/retry-resilience.yaml

@@ -158,3 +158,31 @@ tests:
           data: "retry-data"
     cleanup:
       - action: clear-errors
+
+  - id: retry-exhaustion-fails
+    name: Client fails after retry limit exhaustion
+    description: |
+      Client should eventually fail when transient errors persist beyond
+      the retry limit. This prevents infinite retry loops and ensures
+      clients surface errors to callers rather than hanging forever.
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "test-data"
+    operations:
+      # Inject many 500 errors - more than any reasonable retry limit
+      - action: inject-error
+        path: ${streamPath}
+        status: 500
+        count: 20
+      # Client should eventually give up and return an error
+      - action: read
+        path: ${streamPath}
+        expect:
+          error: true
+          # The error could be 500 (last failed attempt) or a client-specific
+          # retry exhaustion error - either is acceptable
+    cleanup:
+      - action: clear-errors

package/test-cases/consumer/sse-parsing-errors.yaml

@@ -0,0 +1,121 @@
+id: consumer-sse-parsing-errors
+name: SSE Parsing Error Handling
+description: Tests that clients properly handle malformed SSE events instead of silently failing
+category: consumer
+requires:
+  - sse
+tags:
+  - sse
+  - error-handling
+  - resilience
+  - fault-injection
+
+tests:
+  - id: unknown-sse-event-type
+    name: Client gracefully handles unknown SSE event type
+    description: Client should ignore unknown event types and continue processing
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "test-data"
+    operations:
+      # Inject an unknown SSE event type before the stream starts
+      - action: inject-error
+        path: ${streamPath}
+        injectSseEvent:
+          eventType: "unknown-future-type"
+          data: '{"some":"future-data"}'
+        count: 1
+      # Client should skip the unknown event and still read the actual data
+      - action: read
+        path: ${streamPath}
+        live: sse
+        maxChunks: 1
+        expect:
+          data: "test-data"
+    cleanup:
+      - action: clear-errors
+
+  - id: malformed-control-event-json
+    name: Client throws on malformed control event JSON
+    description: Control events contain critical offset data - malformed JSON should throw
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "data-before-error"
+    operations:
+      # Inject a control event with invalid JSON
+      - action: inject-error
+        path: ${streamPath}
+        injectSseEvent:
+          eventType: "control"
+          data: "{invalid json here"
+        count: 1
+      # Client should throw a parse error
+      - action: read
+        path: ${streamPath}
+        live: sse
+        maxChunks: 1
+        expect:
+          errorCode: PARSE_ERROR
+    cleanup:
+      - action: clear-errors
+
+  - id: empty-control-event-data
+    name: Client handles empty control event data
+    description: Empty control event should be handled gracefully
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "actual-data"
+    operations:
+      # Inject a control event with empty data
+      - action: inject-error
+        path: ${streamPath}
+        injectSseEvent:
+          eventType: "control"
+          data: ""
+        count: 1
+      # Client should throw because empty is not valid JSON
+      - action: read
+        path: ${streamPath}
+        live: sse
+        maxChunks: 1
+        expect:
+          errorCode: PARSE_ERROR
+    cleanup:
+      - action: clear-errors
+
+  - id: multiple-unknown-events
+    name: Client handles multiple unknown event types
+    description: Client should skip all unknown events and process valid ones
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "expected-data"
+    operations:
+      # Inject first unknown event
+      - action: inject-error
+        path: ${streamPath}
+        injectSseEvent:
+          eventType: "future-event-v2"
+          data: '{"version":2}'
+        count: 1
+      # Note: Only one injection per fault, so this tests single unknown event
+      # Client should still read the actual data
+      - action: read
+        path: ${streamPath}
+        live: sse
+        maxChunks: 1
+        expect:
+          data: "expected-data"
+    cleanup:
+      - action: clear-errors

package/test-cases/producer/error-context.yaml

@@ -0,0 +1,72 @@
+id: producer-error-context
+name: Producer Error Context
+description: |
+  Tests that producer error messages include helpful context.
+  Ensures errors provide enough information for debugging.
+  Note: These tests validate server-level responses (status codes).
+  Client-level error message validation requires idempotent-append tests.
+category: producer
+tags:
+  - errors
+  - context
+  - messages
+
+tests:
+  - id: sequence-conflict-returns-expected-seq
+    name: Sequence conflict returns expected sequence info
+    description: 409 sequence conflict should return expected/received seq headers
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      # First append succeeds
+      - action: server-append
+        path: ${streamPath}
+        data: "msg0"
+        producerId: error-context-producer
+        producerEpoch: 0
+        producerSeq: 0
+        expect:
+          status: 200
+      # Skip seq=1, try seq=2 -> 409 gap
+      - action: server-append
+        path: ${streamPath}
+        data: "msg2"
+        producerId: error-context-producer
+        producerEpoch: 0
+        producerSeq: 2
+        expect:
+          status: 409
+          # Server returns expected/received seq in headers
+          producerExpectedSeq: 1
+          producerReceivedSeq: 2
+
+  - id: stale-epoch-returns-current-epoch
+    name: Stale epoch returns current epoch info
+    description: 403 stale epoch should return current epoch in header
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain
+    operations:
+      # Establish epoch 1
+      - action: server-append
+        path: ${streamPath}
+        data: "epoch1"
+        producerId: epoch-context-producer
+        producerEpoch: 1
+        producerSeq: 0
+        expect:
+          status: 200
+      # Try with stale epoch 0
+      - action: server-append
+        path: ${streamPath}
+        data: "stale"
+        producerId: epoch-context-producer
+        producerEpoch: 0
+        producerSeq: 0
+        expect:
+          status: 403
+          # Server returns current epoch in header
+          producerEpoch: 1

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

@@ -132,3 +132,43 @@ tests:
         expect:
           data: "Hello World"
           upToDate: true
+
+  - id: client-deduplication-works
+    name: Client IdempotentProducer correctly deduplicates
+    description: |
+      This test verifies that the CLIENT's IdempotentProducer implementation
+      correctly sends Producer-Id/Epoch/Seq headers so server-side deduplication
+      actually works. Without correct headers, retries would create duplicates.
+    setup:
+      - action: create
+        as: streamPath
+        contentType: application/json
+    operations:
+      # Send a batch of items - this creates epoch=0, seq=0
+      - action: idempotent-append-batch
+        path: ${streamPath}
+        producerId: dedup-test-producer
+        epoch: 0
+        items:
+          - data: '{"msg": "first"}'
+          - data: '{"msg": "second"}'
+        expect:
+          allSucceed: true
+      # Send the SAME batch again with a NEW producer instance at epoch=0
+      # If client sends correct headers, server should deduplicate
+      # If client sends wrong headers, this would create duplicate data
+      - action: idempotent-append-batch
+        path: ${streamPath}
+        producerId: dedup-test-producer
+        epoch: 0
+        items:
+          - data: '{"msg": "first"}'
+          - data: '{"msg": "second"}'
+        expect:
+          allSucceed: true
+      # Verify NO duplicates - should only have 2 messages, not 4
+      - action: read
+        path: ${streamPath}
+        expect:
+          data: '[{"msg":"first"},{"msg":"second"}]'
+          upToDate: true

package/test-cases/validation/input-validation.yaml

@@ -0,0 +1,192 @@
+id: input-validation
+name: Client Input Validation
+description: Tests for client-side input parameter validation
+category: lifecycle
+tags:
+  - validation
+  - core
+
+tests:
+  # RetryOptions validation tests (PHP-specific - TS uses BackoffOptions)
+  - id: retry-options-valid
+    name: Valid RetryOptions passes validation
+    description: Default retry options should be accepted
+    requires:
+      - retryOptions
+    operations:
+      - action: validate
+        target:
+          target: retry-options
+          maxRetries: 3
+          initialDelayMs: 100
+          maxDelayMs: 5000
+          multiplier: 2.0
+        expect:
+          valid: true
+
+  - id: retry-options-negative-max-retries
+    name: Negative maxRetries rejected
+    description: Client should reject negative maxRetries
+    requires:
+      - retryOptions
+    operations:
+      - action: validate
+        target:
+          target: retry-options
+          maxRetries: -1
+        expect:
+          valid: false
+          errorCode: INVALID_ARGUMENT
+          errorContains: maxRetries
+
+  - id: retry-options-zero-initial-delay
+    name: Zero initialDelayMs rejected
+    description: Client should reject zero or negative initialDelayMs
+    requires:
+      - retryOptions
+    operations:
+      - action: validate
+        target:
+          target: retry-options
+          initialDelayMs: 0
+        expect:
+          valid: false
+          errorCode: INVALID_ARGUMENT
+          errorContains: initialDelayMs
+
+  - id: retry-options-negative-initial-delay
+    name: Negative initialDelayMs rejected
+    description: Client should reject negative initialDelayMs
+    requires:
+      - retryOptions
+    operations:
+      - action: validate
+        target:
+          target: retry-options
+          initialDelayMs: -100
+        expect:
+          valid: false
+          errorCode: INVALID_ARGUMENT
+          errorContains: initialDelayMs
+
+  - id: retry-options-max-less-than-initial
+    name: maxDelayMs less than initialDelayMs rejected
+    description: Client should reject maxDelayMs < initialDelayMs
+    requires:
+      - retryOptions
+    operations:
+      - action: validate
+        target:
+          target: retry-options
+          initialDelayMs: 1000
+          maxDelayMs: 500
+        expect:
+          valid: false
+          errorCode: INVALID_ARGUMENT
+          errorContains: maxDelayMs
+
+  - id: retry-options-multiplier-less-than-one
+    name: Multiplier less than 1.0 rejected
+    description: Client should reject multiplier < 1.0
+    requires:
+      - retryOptions
+    operations:
+      - action: validate
+        target:
+          target: retry-options
+          multiplier: 0.5
+        expect:
+          valid: false
+          errorCode: INVALID_ARGUMENT
+          errorContains: multiplier
+
+  # IdempotentProducer validation tests (shared across clients)
+  - id: producer-valid
+    name: Valid IdempotentProducer passes validation
+    description: Default producer options should be accepted
+    operations:
+      - action: validate
+        target:
+          target: idempotent-producer
+          producerId: test-producer
+          epoch: 0
+          maxBatchBytes: 1048576
+        expect:
+          valid: true
+
+  - id: producer-negative-epoch
+    name: Negative epoch rejected
+    description: Client should reject negative epoch
+    operations:
+      - action: validate
+        target:
+          target: idempotent-producer
+          producerId: test-producer
+          epoch: -1
+        expect:
+          valid: false
+          errorCode: INVALID_ARGUMENT
+          errorContains: epoch
+
+  - id: producer-zero-max-batch-bytes
+    name: Zero maxBatchBytes rejected
+    description: Client should reject zero maxBatchBytes (Go treats 0 as default)
+    requires:
+      - strictZeroValidation
+    operations:
+      - action: validate
+        target:
+          target: idempotent-producer
+          producerId: test-producer
+          maxBatchBytes: 0
+        expect:
+          valid: false
+          errorCode: INVALID_ARGUMENT
+          errorContains: maxBatchBytes
+
+  - id: producer-negative-max-batch-bytes
+    name: Negative maxBatchBytes rejected
+    description: Client should reject negative maxBatchBytes
+    operations:
+      - action: validate
+        target:
+          target: idempotent-producer
+          producerId: test-producer
+          maxBatchBytes: -1
+        expect:
+          valid: false
+          errorCode: INVALID_ARGUMENT
+          errorContains: maxBatchBytes
+
+  # maxBatchItems validation (PHP-specific - TS doesn't have this option)
+  - id: producer-zero-max-batch-items
+    name: Zero maxBatchItems rejected
+    description: Client should reject zero maxBatchItems
+    requires:
+      - batchItems
+    operations:
+      - action: validate
+        target:
+          target: idempotent-producer
+          producerId: test-producer
+          maxBatchItems: 0
+        expect:
+          valid: false
+          errorCode: INVALID_ARGUMENT
+          errorContains: maxBatchItems
+
+  - id: producer-negative-max-batch-items
+    name: Negative maxBatchItems rejected
+    description: Client should reject negative maxBatchItems
+    requires:
+      - batchItems
+    operations:
+      - action: validate
+        target:
+          target: idempotent-producer
+          producerId: test-producer
+          maxBatchItems: -1
+        expect:
+          valid: false
+          errorCode: INVALID_ARGUMENT
+          errorContains: maxBatchItems