Skip to content

feat(dialog): add opt-in durable signaling checkpoints - #244

Open
FedorKiselev76 wants to merge 10 commits into
restsend:mainfrom
FedorKiselev76:codex/dialog-persistence-checkpoints
Open

FedorKiselev76 wants to merge 10 commits into
restsend:mainfrom
FedorKiselev76:codex/dialog-persistence-checkpoints

Conversation

@FedorKiselev76

@FedorKiselev76 FedorKiselev76 commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Adds opt-in, application-owned persistence checkpoints around dialog signaling. Protected operations wait for a coherent snapshot to be committed before continuing.

Checkpoints cover outgoing requests, authentication retries, successful INVITE responses before ACK, final responses before transmission, local termination intent, signaling completion, and terminal state.

Each dialog uses a serial persistence worker. Storage callbacks run without internal dialog locks. Lifecycle notifications are released only after a covering checkpoint commits.

Storage errors and timeouts prevent subsequent protected operations and are exposed through persistence_status(). Recovery remains application-owned: a timeout may leave the commit outcome unknown, and the stack does not replay interrupted SIP transactions.

Persistence is disabled by default. Existing DialogState notifications remain protocol notifications, independent of durable commit completion.

This PR depends on #245 and its proposed 0.9.0 breaking-change plan, pending maintainer approval. It includes the snapshot builder and lifecycle-record constructor. See MIGRATING-0.9.md for migration details.

Rebased onto upstream main at 895d443, preserving the merged re-INVITE controls, negotiation tracking, persistence binding, and signaling-completion checkpoints.

Validation:

  • 654 library tests passed, including 14 persistence regressions.
  • 7 downstream reconstruction tests, 7 harness tests, and 71 documentation tests passed; one documentation test remains ignored.
  • New regressions cover incoming re-INVITE response/ACK checkpoints and successful or failed storage before a deferred ACK handler.
  • 173 interop regression scenarios passed with the checkpoint switch enabled.
  • The default-mode run exposed an ACK/BYE race in the lost-response fixture. After adding an ACK-received barrier, both affected proxy/B2BUA scenarios passed three consecutive reruns.
  • All-targets and Embassy builds, plus formatting checks, passed.

Run checkpoint interoperability tests with:

RSIPSTACK_INTEROP_CHECKPOINTS=1 bash scripts/interop/run.sh regression

The switch configures in-process dialog-peer fixtures. Standalone proxy/B2BUA applications also run but use their own layers and are not configured by this switch.

@shenjinti

Copy link
Copy Markdown
Contributor

Review: the checkpoint design is sound, opt-in, and default behavior is unchanged. cargo test/CI are green on the branch. I am holding this PR because it depends on #245, which currently has a public API break under review.

Notes for the rebase:

Add a public constructor for non-exhaustive lifecycle records so applications can reconstruct persisted history. Keep restore-time history validation unchanged.

Exercise the API from an external integration test across two restores, including absent timestamps and invalid history. Verify the constructor documentation and Embassy build.
Make DialogSnapshot non-exhaustive and require explicit state, CSeq counters and recovery metadata through its public builder. Preserve optional stored values and validate confirmed lifecycle history without discarding pending work.

Document the proposed 0.9.0 release gate, legacy storage migration and changed restore behavior. Exercise downstream reconstruction and snapshot admission around the upstream re-INVITE handlers.
Verify that incoming re-INVITE responses wait for storage and that ACK completion produces a quiescent checkpoint. Exercise successful and failed commits before a deferred outgoing ACK handler.

Clarify that the interop checkpoint switch configures in-process dialog peers, not the standalone proxy and B2BUA applications.
@FedorKiselev76
FedorKiselev76 force-pushed the codex/dialog-persistence-checkpoints branch from 8020bbe to 580189e Compare November 6, 2026 10:17
The caller can report CONFIRMED before the proxy forwards ACK. Wait for a SIPp receive marker before requesting hangup, so this scenario tests retransmission of BYE instead of racing it with the initial ACK.
Check persistence before recording and sending a per-fork ACK. Keep the proposed 0.9 migration notes alongside the released changelog.
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.

2 participants