Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,23 @@
# Changelog

## Unreleased — proposed 0.9.0

- Opt-in persistence now saves every INVITE final response before its ACK,
including rejection and authentication challenges. A successful re-INVITE
checkpoint contains the accepted Contact and the observed response in one
coherent snapshot boundary. Failed writes continue to block protected sends.

- **Breaking (requires maintainer approval for 0.9.0):** `DialogSnapshot` adds
coherent `runtime` metadata and becomes `#[non_exhaustive]`. External callers
must use `DialogSnapshot::builder(...)` and include `..` in destructuring
patterns. State, both CSeq values and runtime metadata must be explicit.
- **Recovery behavior:** confirmed snapshots with unfinished signaling or invalid
lifecycle history are rejected. Stored transactions and handlers are not
replayed. Lifecycle records can be reconstructed with `DialogLifecycleRecord::new`.
- See [the migration guide](MIGRATING-0.9.md) for storage defaults, legacy-record
handling, and the release compatibility plan. The release target is proposed;
this change does not itself bump or publish the package version.

## 0.8.5

- Client INVITE transactions retain exact ACKs separately for each dialog
Expand Down
101 changes: 101 additions & 0 deletions MIGRATING-0.9.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
# Snapshot migration for the proposed 0.9.0 release

These changes require a breaking release. The proposed target is **0.9.0**,
subject to maintainer approval; this document does not announce a release or
change the package version. Do not backport this API change into 0.8.x.

## Constructing and reading snapshots

`DialogSnapshot` now includes coherent runtime metadata and is
`#[non_exhaustive]`. Adding `runtime` breaks old struct literals and exhaustive
patterns. The attribute also prevents external struct literals, even if they
include `runtime`. Replace them with `DialogSnapshot::builder(...)`; adding
`runtime: DialogSnapshotRuntime::default()` to a literal is not sufficient.

Supply the stored identity, role, From/To headers, remote URI, state, both CSeq
counters, and runtime metadata. The builder requires state, counters and runtime
explicitly: it never assumes a stored dialog was confirmed or quiescent. Copy
optional stored contacts, routes, 100rel support and Session-ID through their
builder methods too. Omitting those optional settings yields `None`, no routes,
`false`, and `None`, respectively; it does not recover their persisted values.

This example illustrates an application-approved migration of a legacy,
confirmed record known to have been captured with no signaling in flight:

```rust
use rsipstack::{
dialog::{
dialog::{DialogSnapshot, DialogSnapshotState},
snapshot::DialogSnapshotRuntime,
DialogId,
},
sip::{headers, prelude::ToTypedHeader},
transaction::key::TransactionRole,
};

let snapshot = DialogSnapshot::builder(
DialogId {
call_id: "stored-call".into(),
local_tag: "local".into(),
remote_tag: "remote".into(),
},
TransactionRole::Client,
headers::From::from("<sip:alice@example.com>;tag=local").typed()?,
headers::To::from("<sip:bob@example.com>;tag=remote").typed()?,
"sip:bob@example.com".try_into()?,
)
.state(DialogSnapshotState::Confirmed)
.local_cseq(42)
.remote_cseq(7)
.local_contact(Some("sip:alice@example.com".try_into()?))
// The application has established that this legacy record was quiescent.
.runtime(DialogSnapshotRuntime::default())
.build()?;

// Field access is unchanged. Patterns must allow future fields.
let DialogSnapshot { id, runtime, .. } = snapshot;
assert_eq!(id.call_id, "stored-call");
assert!(runtime.lifecycle.is_empty());
# Ok::<(), Box<dyn std::error::Error>>(())
```

The builder checks required inputs and the lifecycle history of confirmed
snapshots. It also represents pending and non-confirmed snapshots so applications
can inspect or store them. `build()` succeeding does **not** guarantee that
restore will resume the dialog. Public fields remain mutable, so restore retains
its own validation.

## Storage and recovery behavior

The application owns serialization, storage schema versions and migrations.
`runtime.revision` identifies a dialog state revision, **not a storage schema**.
Persist the complete runtime metadata, including pending operations and lifecycle
records. Reconstruct individual facts with
`DialogLifecycleRecord::new(sequence, since_unix_epoch, kind)`. Preserve their
sequence and optional wall-clock time; do not invent timestamps or acceptance
events during migration. Restoring retains the history without replaying it to
notification consumers. Monotonic timestamps are process-local and not stored.

For a pre-0.9 record without runtime metadata, explicitly passing
`DialogSnapshotRuntime::default()` represents revision zero, no recorded history,
and no pending operations. This is appropriate only when the application's
existing capture contract or other reliable evidence establishes that signaling
was quiescent. Missing metadata alone does not establish that fact. Empty history
means no history was retained; it is not evidence that the call was never answered.
If quiescence cannot be established, apply an explicit application recovery policy
instead of silently resuming the call. Never discard known pending work or use a
default to hide corrupt metadata.

Calls to `dialog.snapshot()` and `layer.restore_from_snapshot(snapshot, sender)`
keep their signatures. The restore behavior changes as follows:

- A confirmed snapshot with non-empty `runtime.pending` returns an error. SIP
transactions, outstanding ACKs and application handlers are not replayed.
- Invalid confirmed lifecycle history or revision returns an error.
- Non-confirmed snapshots are still skipped with `Ok(false)`.
- An already registered dialog is still retained and restore returns `Ok(false)`.

Future optional fields may have safe defaults without breaking builder callers.
New data required for safe recovery must instead have an explicit migration or
compatibility plan. `#[non_exhaustive]` protects source construction and matching;
it is not a promise that every future persisted record can be silently migrated.
24 changes: 15 additions & 9 deletions src/dialog/client_dialog.rs
Original file line number Diff line number Diff line change
Expand Up @@ -558,6 +558,7 @@ impl ClientInviteDialog {
/// * `UPDATE` - Handles session updates
/// * `INVITE` - Handles re-INVITE (when confirmed)
pub async fn handle(&mut self, tx: &mut Transaction) -> Result<()> {
self.inner.bind_persistence(tx);
trace!(
id = %self.id(),
method = %tx.original.method,
Expand All @@ -579,10 +580,7 @@ impl ClientInviteDialog {
return Ok(());
}

self.inner
.remote_seq
.compare_exchange(remote_seq, cseq, Ordering::Relaxed, Ordering::Relaxed)
.ok();
self.inner.admit_remote_seq(cseq, &tx.original.method).ok();

if self.inner.is_confirmed() {
match tx.original.method {
Expand Down Expand Up @@ -615,13 +613,12 @@ impl ClientInviteDialog {
}

async fn handle_bye(&mut self, tx: &mut Transaction) -> Result<()> {
self.inner.record_remote_bye(
debug!(id = %self.id(), uri = %tx.original.uri, "received bye");
self.inner.terminate_remote_bye(
TerminatedReason::UasBye,
tx.original_received_at
.unwrap_or_else(super::lifecycle::LifecycleTime::now),
);
debug!(id = %self.id(), uri = %tx.original.uri, "received bye");
self.inner
.transition(DialogState::Terminated(self.id(), TerminatedReason::UasBye));
tx.reply(crate::sip::StatusCode::OK).await?;
Ok(())
}
Expand Down Expand Up @@ -665,7 +662,16 @@ impl ClientInviteDialog {
}

async fn handle_reinvite(&mut self, tx: &mut Transaction) -> Result<()> {
self.inner.process_reinvite(tx, false).await
self.inner.begin_negotiation();
let result = self.inner.process_reinvite(tx, false).await;
self.inner.finish_negotiation();
self.inner
.checkpoint(
super::persistence::DialogCheckpointReason::SignalingCompleted,
None,
)
.await?;
result
}

async fn handle_refer(&mut self, tx: &mut Transaction) -> Result<()> {
Expand Down
Loading
Loading