Pro and above; channel access varies · Compare plans and subscribe
Build reliable MadeOnSol WebSocket recovery
Handle reconnects, replay completion, duplicate events and current-state refreshes without claiming missing trade history was recovered.
By MadeOnSol · Updated
Integration choice
Treat connection health, current state and historical completeness as separate concerns. A reconnected socket can be healthy while an earlier interval still needs reconciliation. Keep one owner for reconnects and persist processing checkpoints where restart recovery matters.
Before you start
- A working standard WebSocket subscription and a backend event handler.
- A durable event store if processing must survive your own process restarting.
Implementation steps
- Start with the standard stream client in the WebSocket guide. Add durable processing and observability before adding more named subscriptions.
- Use the stream token returned by POST /api/v1/stream/token. Normal calls reuse the token; do not schedule periodic rotation. Protect the token as a credential.
- For replayable event frames, persist an event identity and processing result before advancing the resume checkpoint. Restore subscriptions and their exact filters on reconnect.
- Inspect replay_end for each subscription, including complete, reason and per-channel details. Record affected intervals and choose a channel-specific repair.
- For state streams, take the documented fresh snapshot. For historical events, reconcile with the matching historical API only where its scope and retention cover the missing interval.
Track three independent states
Connected means the transport is open; subscribed means the server acknowledged the requested subscription. Neither alone means your application has processed its backlog. Record the last successful handler time and queue depth as well as socket status.
Replay is bounded. Its result reports what the service recovered, and per-channel details can carry limitations. A gap between global sequence numbers is not sufficient proof that your filtered subscription missed events. Do not describe replay as unlimited archival recovery.
Commit effects before checkpoints
For named subscriptions, the same event may appear once under each matching sub_id. Use sub_id plus event id for delivery-level deduplication. If several subscriptions trigger the same business action, use a second key for that action so it happens once.
Persist the action, deduplication record and checkpoint transactionally where possible. An in-memory Set disappears on restart. For an external notification, use an outbox and the destination’s idempotency mechanism when available; a local database alone cannot guarantee exactly-once delivery to another service.
Repair the right kind of data
Robinhood Chain price ticks are state updates without seq/id replay; a new subscription supplies a current snapshot. Holder-state recovery has its own cursor contract. Do not reuse one generic event cursor for every channel.
The terminal helper refreshes current state after reconnect. Its incomplete flag is not cleared by pretending that a new snapshot recovered old trades. Call acknowledgeHistoricalRecovery() only after your application has reconciled the missing history. Use backoff and jitter when reconnecting multiple processes.
Code examples
Reconnect jitter policy (standalone JavaScript)
// Backoff policy to integrate into your reconnect controller.
// Demo only: no socket is opened here. Keep a single reconnect owner.
function reconnectDelay(attempt, random = Math.random) {
if (!Number.isInteger(attempt) || attempt < 0) throw new Error("Invalid attempt");
const cap = Math.min(30000, 1000 * 2 ** Math.min(attempt, 5));
return Math.floor(cap / 2 + random() * cap / 2);
}
console.log(reconnectDelay(0, () => 0)); // 500 ms
console.log(reconnectDelay(20, () => 0)); // 15000 ms
// These delays are client policy. Respect a longer server-directed wait.
// Reset attempts after a stable, acknowledged session, not on every open.
// Inspect replay_end separately; transport recovery is not historical repair.
Common mistakes and fixes
| Mistake | Recommended fix |
|---|---|
| Mark the cursor before the event handler finishes. | Commit processing first; a failed handler must leave the prior checkpoint intact. |
| Treat replay_end as proof of unlimited complete history. | Read complete, reason and each channel’s recovery limitations. |
| Rotate the stream token every hour. | Reuse the normal token; explicit rotation is a credential-management action. |
Verify your integration
Disconnect a test client during traffic, restart it after a processed event and inject a handler failure. Verify applied events are not duplicated, a failed event cannot advance the checkpoint, and an incomplete replay remains unresolved until its interval is actually reconciled.
Production checklist
- One reconnect controller per upstream connection.
- Durable checkpoints tested across process restarts.
- Replay outcome tracked per subscription.
- Separate repair policies for state and event history.
Frequently asked questions
Does reconnecting recover every missed trade?
No. Recovery is bounded and channel-specific. Inspect replay_end and use supported historical reads for intervals you can reconcile.
Can I refresh a snapshot and mark historical recovery complete?
No. A snapshot restores current state. It does not reconstruct the sequence of trades or alerts that occurred while disconnected.
