PicoMQ reconnect checklist: test replay before real work

The connection is back. That does not mean your app has caught up. A live activity feed can look healthy while it skips the events that arrived during a disconnect, or repeats an action it already completed.

If you are evaluating PicoMQ for a workflow log, chat history or an agent’s progress feed, use this small recovery drill before connecting real work. It separates three questions: did the client receive an event, did the application apply it, and did it remember where to resume? The checklist is an original test-planning aid, not a claim that we installed or benchmarked PicoMQ.

Why look at this now?

PicoMQ’s October 1, 2026 change added a PostgreSQL write-ahead-log backend and PostgreSQL extension. That expands its deployment choices; it does not remove the need to test recovery at the application boundary. This guide focuses on that boundary rather than comparing infrastructure costs or promising a particular latency.

The project’s protocol documentation describes resumable reads and deduplication when appends use a producer identity and sequence. Plain append has no deduplication key and is not automatically retried by the TypeScript SDK. These are useful distinctions. They are not, by themselves, proof that your email sender, task updater or notification handler will perform each action only once.

Give the three milestones different names

For the drill, use a disposable stream and harmless synthetic events. Do not send customer messages or trigger purchases. Keep a separate little observation log with the following columns:

A log message saying “received” must not masquerade as a completed effect. Likewise, a checkpoint held only in a component’s memory will disappear when that component restarts. Decide where your application stores recovery state and who owns updates to it.

Do not simply save a later position before doing the work: a crash can then leave the work skipped. Saving afterward can leave a replay window. Where an effect and checkpoint cannot be committed together, design the effect to tolerate a repeat and test that behavior. This is application design advice, not a PicoMQ configuration switch.

Resume from a returned position, not from a guess

The TypeScript client reference says position tokens vary by protocol: reuse the returned next value rather than constructing one or assuming a record’s own position is the next position. It also documents automatic subscription reconnection with backoff. Reconnection is a transport behavior; separately verify what state survives an application restart.

The native HTTP API distinguishes reading from a position from starting at seq=now. Starting at the current tail is appropriate for future-only observation, but it is the wrong recovery choice when you promised to show missed events. The API also distinguishes reaching the present tail from a stream being closed. “Caught up” need not mean “no more events will ever arrive.”

• Write down whether the feature needs history, future-only events, or both.
• Keep the stream identity alongside the checkpoint. A position from one stream is not a universal bookmark.
• Use the protocol and client version you actually selected; do not mix similarly named headers or position formats.
• Check retention before promising recovery. A bookmark cannot restore records that have expired or been removed.

Test the awkward gap after success

In your test harness, apply demo-A and then interrupt the process before its recovery state is saved. Restart it. If demo-A is delivered again, does your visible list show it twice? Does the counter increase twice? Record the effect, not just the number of network deliveries.

The connector delivery documentation explicitly describes at-least-once delivery and duplicate windows between a confirmed write and its checkpoint. Destination behavior matters: an operation that updates the same stable record can differ from one that appends a fresh row every time. Do not generalize producer-side append deduplication into an end-to-end exactly-once guarantee.

For a harmless test list, a stable event identity can help prevent duplicate entries. For other effects, select a supported idempotency mechanism appropriate to that destination. If none exists, document the limitation rather than hiding it behind a green “connected” indicator.

Run a bounded disconnect drill

1. Establish a baseline. Create a disposable test stream. Send demo-A and demo-B, and confirm both appear in the observation log and the test interface.
2. Interrupt the reader. Disconnect only the test client. Keep the producer running and append demo-C and demo-D. Note which events were accepted; do not assume a timed-out write failed.
3. Reconnect. Resume through the chosen client using its supported saved state. Confirm C and D are recovered in the expected stream order.
4. Restart the application. Repeat with a full process restart. This catches state that survived a socket reconnect but not a process exit.
5. Exercise the replay window. Use the controlled interruption after an applied effect described above. Check both missing work and repeated effects.
6. Stop cleanly. Cancel the test subscription using the supported cancellation mechanism. Confirm it stops receiving events and does not quietly reconnect after you leave the screen.

Also test a stale or unusable checkpoint against the retention policy. The acceptable result may be a clear “history unavailable” state and a deliberate refresh path. Silently jumping forward and calling the history complete is not an acceptable substitute.

Keep one recovery receipt

Copy these fields into the issue or review request for the feature:

• Client version and protocol:
• Disposable stream and retention settings:
• Expected event identities:
• Connection interruption and process restart tested:
• Missing events, repeated deliveries, repeated effects:
• Checkpoint storage and update point:
• Cancellation result:
• Known gaps and evidence link:

Call the feature ready only for the cases that passed. A successful reconnect in a toy stream does not establish production throughput, authentication safety, disaster recovery or total operating cost. This drill gives a small team a concrete starting point: a feed that can explain what it missed and what it already did.

If your real need is simply watching changes on a public page, start with our public-page watch checklist instead. Choosing a stream server is a different commitment from configuring a page watcher. The potato would prefer one fewer server to babysit.