Skip to content

feat: make idempotency response persistence reliable with defined replay states#499

Merged
mikewheeleer merged 1 commit into
Liquifact:mainfrom
christy-dev4:enhancement/idempotency-reliable-response-storage
Jun 28, 2026
Merged

feat: make idempotency response persistence reliable with defined replay states#499
mikewheeleer merged 1 commit into
Liquifact:mainfrom
christy-dev4:enhancement/idempotency-reliable-response-storage

Conversation

@christy-dev4

Copy link
Copy Markdown
Contributor

This PR addresses issue #428 by implementing reliable idempotency response persistence.

Changes

Idempotency State Machine

The middleware now defines explicit states for idempotency keys:

  • COMPLETED (response_status > 0): Returns cached response on replay
  • IN_PROGRESS (response_status IS NULL): Re-executes handler safely
  • FAILED_STORAGE (response_status = -1): Re-executes handler to recover from storage failure

Reliability Improvements

  1. Retry-with-backoff: Response storage now retries up to 5 attempts with exponential backoff (100ms - 2000ms) and jitter before giving up
  2. Failure marking: When all retries fail, the key is marked with to indicate incomplete state
  3. Safe replay: Keys with incomplete responses (-1 or NULL) cause the handler to re-execute instead of returning broken data

Metrics

Added counter to track storage failures after max retries (labels: for first 8 chars of key)

Tests

Comprehensive test suite covers:

  • Normal operation (missing header, invalid key, first call, replay, conflict)
  • Storage failure scenarios (failed persistence, retry recovery, in-progress replay)
  • Concurrent replay handling
  • Security (no cross-key data leakage)

Closes #428

@drips-wave

drips-wave Bot commented Jun 27, 2026

Copy link
Copy Markdown

@christy-dev4 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

…lay states

- Add retry-with-backoff for response storage (max 5 attempts, exponential backoff)
- Mark keys with response_status=-1 when storage fails to indicate incomplete state
- Re-execute handler on replay when key has incomplete response (safe recovery)
- Add idempotency_storage_failure_total metric for storage failures
- Add comprehensive tests for storage failure and replay scenarios
- Document idempotency state machine in JSDoc comments

Closes Liquifact#428
@christy-dev4 christy-dev4 force-pushed the enhancement/idempotency-reliable-response-storage branch from 528d688 to 7e7d10a Compare June 27, 2026 18:10
@mikewheeleer

Copy link
Copy Markdown
Contributor

nice work — merging this 🙌

@mikewheeleer mikewheeleer merged commit 2850621 into Liquifact:main Jun 28, 2026
0 of 2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Make idempotency response persistence reliable so storage failures do not break replays

2 participants