🔒 Idempotency & Durable Objects
How Hoox utilizes Cloudflare Durable Objects to guarantee exactly-once execution and prevent catastrophic duplicate orders during network dropouts.
⚠️ The Danger: How Webhook Retries Lead to Double-Ordering
Without idempotency, a typical signal failure sequence looks like this:
🛡️ The Hoox Solution: Durable Objects Mutex Locking
To enforce exactly-once execution, Hoox implements an atomic dedup lock inside workers/hoox utilizing Cloudflare Durable Objects.
A Durable Object is a unique, single-threaded compute isolate managed by Cloudflare that maintains its own highly optimized, in-memory state and persistent on-disk SQLite storage. Because access to a specific Durable Object instance is single-threaded, it acts as an absolute distributed lock (mutex).
The Idempotency Workflow
🔍 The Dedup & Cleanup Algorithm
1. Trace ID Generation
When a trade signal is fired, it must include a unique transaction signature.
- For TradingView webhooks, this is automatically generated as a combination of alert parameters and timestamps.
- If a client does not supply a transaction ID, the Hoox Gateway dynamically hashes the symbol, exchange, action, and timestamp to create a unique Idempotency Key.
2. Atomic Evaluation
Before executing any order routing:
- The gateway routes the request to the namespace-mapped Durable Object using
the transaction ID as the binding key.
- The Durable Object checks its internal state. Since DOs are single-threaded,
there is zero risk of race conditions—if two identical HTTP
requests hit Cloudflare simultaneously, they are processed sequentially
inside the DO.
- If the ID exists in the DO’s SQLite log, the DO immediately intercepts the
request and throws a
409 Conflict exception, stopping the
pipeline before hitting exchange APIs. - If unique, it registers the ID, saves the current timestamp, and returns a
lock approval.
3. Automatic TTL & Storage Alarms
To prevent the Durable Object’s persistent storage from growing indefinitely and consuming unnecessary memory:
- The DO registers an atomic alarm scheduled for 24 hours in the future.
- When the alarm fires, the DO runs an automatic garbage collection script that purges old IDs from its local storage.
- This ensures that while you are 100% protected against duplicates during network dropouts, your storage footprint remains lightweight.
4. Cold-Start Resilience
When a DO instance has been idle (no requests for the TTL period), Cloudflare may evict it from memory. Upon the next request:
- The DO is reconstructed from its persisted SQLite state on
disk.
- All previously recorded trace IDs are loaded back into memory.
- The dedup check continues seamlessly — no data loss, no duplicate risk.
This means idempotency protection survives worker restarts, cold starts, and infrastructure failovers without any manual intervention.
Never disable idempotency check bindings in your wrangler.jsonc file in
production. The performance cost of pinging the DO is less than 2
milliseconds, while the cost of a duplicate order could be catastrophic.
🔗 Next Steps
