From b288176ef610cf757ed59e515dff8f33a4c003f4 Mon Sep 17 00:00:00 2001 From: DontBlameMe Date: Mon, 19 Oct 2026 11:43:37 +0200 Subject: [PATCH 1/3] refactor(client): make the peer session a module directory `crates/client/src/peer.rs` becomes `crates/client/src/peer/mod.rs` with no content change. The split that follows needs somewhere to put its files, and a rename on its own is a diff with nothing to read. --- crates/client/src/{peer.rs => peer/mod.rs} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename crates/client/src/{peer.rs => peer/mod.rs} (100%) diff --git a/crates/client/src/peer.rs b/crates/client/src/peer/mod.rs similarity index 100% rename from crates/client/src/peer.rs rename to crates/client/src/peer/mod.rs From 42f49d7efcea548bce642c3481b2195916fda1fe Mon Sep 17 00:00:00 2001 From: DontBlameMe Date: Mon, 19 Oct 2026 11:43:43 +0200 Subject: [PATCH 2/3] refactor(client): split the peer session into cohesive modules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `mod.rs` keeps the `PeerSession` struct and the module wiring; one concern per file around it: invite §5.1's link, its two keys and the connection address options what a session is opened with, and the host producer half report §13.11's decisions, the two counts and the four endings plaintext the y-protocols side of a `kind = 0` frame clocks the caller's tick: the lease, the two presence windows, the census roles §13.4's attribution and §13.6's eligibility deliver one frame in: the verdict, §13's decision, the messages it carried publish everything that leaves: the seal, the gates, the announcement holds §13.7's paths, the lease and its expiry events what a driver hands in that is not a frame read what a caller reads off a session speculation §13.9's held edits and the clean baseline Every item moves unchanged: no logic, no signature, and no visibility beyond the extraction itself. --- crates/client/src/peer/clocks.rs | 144 ++ crates/client/src/peer/deliver.rs | 378 ++++ crates/client/src/peer/events.rs | 67 + crates/client/src/peer/holds.rs | 128 ++ crates/client/src/peer/invite.rs | 205 +++ crates/client/src/peer/mod.rs | 2406 ++----------------------- crates/client/src/peer/options.rs | 123 ++ crates/client/src/peer/plaintext.rs | 60 + crates/client/src/peer/publish.rs | 289 +++ crates/client/src/peer/read.rs | 353 ++++ crates/client/src/peer/report.rs | 103 ++ crates/client/src/peer/roles.rs | 116 ++ crates/client/src/peer/speculation.rs | 238 +++ 13 files changed, 2368 insertions(+), 2242 deletions(-) create mode 100644 crates/client/src/peer/clocks.rs create mode 100644 crates/client/src/peer/deliver.rs create mode 100644 crates/client/src/peer/events.rs create mode 100644 crates/client/src/peer/holds.rs create mode 100644 crates/client/src/peer/invite.rs create mode 100644 crates/client/src/peer/options.rs create mode 100644 crates/client/src/peer/plaintext.rs create mode 100644 crates/client/src/peer/publish.rs create mode 100644 crates/client/src/peer/read.rs create mode 100644 crates/client/src/peer/report.rs create mode 100644 crates/client/src/peer/roles.rs create mode 100644 crates/client/src/peer/speculation.rs diff --git a/crates/client/src/peer/clocks.rs b/crates/client/src/peer/clocks.rs new file mode 100644 index 0000000..6cdc9ab --- /dev/null +++ b/crates/client/src/peer/clocks.rs @@ -0,0 +1,144 @@ +//! The caller's tick: §13.7's lease, §8.2's awareness expiry, §13.8's host-away +//! window, §13.3's no-state window, and §13.11's mutation census. + +use super::PeerSession; +use super::report::Ending; +use crate::host::HostReason; +use crate::sealed::Guard; +use crate::sealed::SealedError; +use std::time::Duration; +use yrs::block::ClientID; + +impl PeerSession { + /// The clocks, on the caller's tick: §13.7's renewal and expiry, §8.2's awareness expiry, + /// §13.8's host-away window and §13.3's no-state window. + /// + /// The announcement of §13.1's step 4 goes out here too, at the first tick and whenever a + /// state has not committed this key since — so a driver has one path to publish it and + /// nothing has to remember to call it at the join. + pub fn tick(&mut self, clock: Duration) { + if let Some(host) = self.host.as_mut() { + host.flush_frames(clock); + } + self.expire_leases(clock); + self.expire_awareness(clock); + self.refresh_host_away(clock, false); + if self.ending.is_some() { + return; + } + if self.budget_spent() { + return; + } + if self.window_passed(clock) { + return; + } + self.publish_state(clock, HostReason::Announcement); + self.reannounce(clock); + self.resync(clock); + self.announce_holds(clock); + } + + /// Removes one of `PROTOCOL.md` §13.11's client guards, for the corpus's mutation census. + /// + /// # Errors + /// + /// Returns an error naming the guard when nothing here removes it: a subject that cannot + /// take a mutation must say so rather than pass the census silently. + pub fn mutate(&mut self, name: &str) -> Result<(), SealedError> { + match name { + "ignore-roles" => self.reader.mutations.remove(Guard::Roles), + "ignore-issued" => self.reader.mutations.remove(Guard::Issued), + "announce-once" | "no-lease" | "any-closing" | "wait-for-ever" => {} + other => { + return Err(SealedError::new(format!( + "no mutation is named {other:?}" + ))); + } + } + self.mutation = Some(name.to_string()); + Ok(()) + } + + pub(super) fn mutating(&self, name: &str) -> bool { + self.mutation.as_deref() == Some(name) + } + + /// §8.2's expiry, beside §13.7's: a remote awareness state whose last **applied** entry is + /// `awareness_expire_ms` old is forgotten. The renewal tick is where this is checked, so a + /// state is forgotten at the first tick after `last seen + awareness_expire_ms` and never + /// sooner, which is the `awareness_expire_ms + awareness_renew_ms` the text bounds it by. + /// + /// The removal is `yrs`'s own, which leaves the id a tombstone: a renewal at the clock the + /// dropped state carried and one at the clock above it are both ignored (`NOTES.md` §A.11), + /// and a renewal above both makes the peer visible again. An expiry is not a refusal and not + /// a departure — no frame is dropped, the peer is not gone — so the only observable is the + /// state going. + fn expire_awareness(&mut self, clock: Duration) { + let lapsed: Vec = self + .awareness_seen + .iter() + .filter(|(_, at)| clock.saturating_sub(**at) >= self.expire) + .map(|(id, _)| *id) + .collect(); + for id in lapsed { + let _ = self.awareness_seen.remove(&id); + self.awareness.remove_state(id); + } + } + + /// §13.8's host-away clock: armed while the applied state's `host` entry labels a seat + /// the roster does not have, disarmed when it labels one the roster has. `restart` is + /// what a new state does to a clock that is already running. + pub(super) fn refresh_host_away(&mut self, clock: Duration, restart: bool) { + // §13.4: a state that names no `host` entry leaves this client with no identified + // host connection and it MUST NOT guess one, so there is nothing to arm a clock with. + let absent = self + .host_seat() + .is_some_and(|seat| !self.roster.contains(seat)); + if !absent { + self.host_away_since = None; + } else if restart || self.host_away_since.is_none() { + self.host_away_since = Some(clock); + } + } + + /// §13.3's no-state window and §13.8's host-away window, which run in sequence. + fn window_passed(&mut self, clock: Duration) -> bool { + if let Some(since) = self.host_away_since + && clock.saturating_sub(since) >= self.expire + { + self.ending = Some(Ending::HostAway); + return true; + } + if !self.state_held() + && !self.mutating("wait-for-ever") + && clock >= self.expire + { + self.ending = Some(Ending::NoState); + return true; + } + false + } + + /// Drops the awareness state published under `client_id`, which §8.4 asks for when the + /// peer that last claimed the id has left and no seated peer still claims it. The caller + /// holds the claims (the roster's `PeerInfo`), so it is the caller that decides which id. + /// + /// The state is removed the way y-protocols removes one, with its clock moved past the + /// last one seen, so a stale copy still in flight does not bring it back. This + /// connection's own id is never dropped, and an id with no state is left as it is. + pub fn forget_awareness(&mut self, client_id: u64) { + let id = ClientID::new(client_id); + // §8.4's drop and §8.2's expiry are the same bookkeeping: with the state gone there is + // nothing left for the expiry tick to notice, and stepping the tombstone twice would + // swallow one more renewal from the same id. + let _ = self.awareness_seen.remove(&id); + let held = self + .awareness + .iter() + .any(|(client, state)| client == id && state.data.is_some()); + if held && id != self.awareness.client_id() { + self.awareness.remove_state(id); + } + } +} diff --git a/crates/client/src/peer/deliver.rs b/crates/client/src/peer/deliver.rs new file mode 100644 index 0000000..151b71e --- /dev/null +++ b/crates/client/src/peer/deliver.rs @@ -0,0 +1,378 @@ +//! One frame in: `CANONICAL.md` §6.1's verdict, §13's decision, and the stream of +//! y-protocols messages a content frame carries. + +use super::PeerSession; +use super::plaintext::encode_y_message; +use super::report::Applied; +use super::report::Dropped; +use super::report::Ending; +use super::report::Outcome; +use super::report::Published; +use crate::host::HostReason; +use crate::nesting::decode_update; +use crate::sealed::Announcement; +use crate::sealed::Payload; +use crate::sealed::PublicKey; +use crate::sealed::Verdict; +use std::time::Duration; +use yrs::Doc; +use yrs::ReadTxn; +use yrs::StateVector; +use yrs::Transact; +use yrs::sync::AwarenessUpdate; +use yrs::sync::Message as YMessage; +use yrs::sync::MessageReader; +use yrs::sync::SyncMessage; +use yrs::sync::awareness::AwarenessUpdateSummary; +use yrs::updates::decoder::DecoderV1; + +/// How many `SyncStep1` messages one `kind = 0` frame is answered for. +/// +/// A frame is a stream of messages with no count (`PROTOCOL.md` §7), and the answer to a +/// `SyncStep1` is a diff of the whole document, so a frame of them answered one by one would +/// cost the room a document per four bytes. A conforming peer asks once per frame, so past the +/// first the state vector is read and dropped and its diff is never computed. +const MAX_REPLIES_PER_FRAME: usize = 1; + +/// The replies and the readiness one frame drew, accumulated as its messages are read. +#[derive(Debug, Default)] +struct ReadState { + replies: Vec, + requested: bool, +} + +impl PeerSession { + /// One sealed frame, as the relay delivered it. + pub fn deliver(&mut self, clock: Duration, frame: &[u8]) -> Outcome { + self.frames = self.frames.saturating_add(1); + self.count_frame(); + let index = self.frames.saturating_sub(1); + // A closing folds into the receiver the moment it verifies, and §13.10 ignores one + // handed to a client holding no state. The two values it moved are put back, because + // `issued` is an order between two states and this receiver has none to compare one + // with: vector 155 delivers a closing at edition 2 and then a state at 1, and the + // state must still be the first edition this client holds. + let issued = self.reader.issued; + let ended = self.reader.ended; + let verdict = self.reader.read(frame); + if !verdict.ok { + self.note_refusal(clock, &verdict); + return self.refuse(index, &verdict); + } + let kind = verdict.kind.unwrap_or_default(); + if matches!(verdict.payload, Some(Payload::RoomState(_))) { + // §7.1: what a peer re-sends when it sees a `peer.joined` is the bytes it received, + // and those are the ones that verified. + self.held_state_frame = Some(frame.to_vec()); + } + if self.ignores(&verdict) { + self.reader.issued = issued; + self.reader.ended = ended; + self.ignored.push(index); + return Outcome::Ignored { kind }; + } + self.fold(clock, &verdict); + self.applied.push(Applied { frame: index, kind }); + Outcome::Applied { kind } + } + + /// §13.6: a refused *content* frame opens an interval this client re-syncs in. The + /// envelope's `kind` is readable before any signature is verified, so that is a claim about + /// the bytes and not about the reason the frame was refused. + fn note_refusal(&mut self, clock: Duration, verdict: &Verdict) { + if verdict.kind == Some(0) { + let _ = self.resync_from.get_or_insert(clock); + } + } + + /// One refused frame: §13.2's local report, which is never sent anywhere. + fn refuse(&mut self, frame: u64, verdict: &Verdict) -> Outcome { + // §13.3: the reason stays `stale_issued` for a second state at one edition and for an + // older one alike, and this index is the local annotation beside it that says which of + // the two the frame was. + if verdict.conflict { + self.conflicts.push(frame); + } + // Every refusal carries the step that refused it; one without a reason would be a bug + // in the byte layer and not a decision to report. + let named = verdict + .reason + .clone() + .unwrap_or_else(|| "bad_envelope".to_string()); + self.dropped.push(Dropped { + frame, + reason: named.clone(), + }); + Outcome::Dropped { reason: named } + } + + /// Whether §13.10 has this frame ignored rather than applied. + fn ignores(&self, verdict: &Verdict) -> bool { + matches!(verdict.payload, Some(Payload::Closing(_))) + && !self.state_held() + && !self.mutating("any-closing") + } + + /// Folds an applied frame into the session: §13.3's state, §13.7's lease, §13.10's + /// closing, the announcement a host answers, and the content a `kind = 0` frame carries. + fn fold(&mut self, clock: Duration, verdict: &Verdict) { + match verdict.payload.as_ref() { + Some(Payload::RoomState(state)) => { + self.after_state(clock, state.issued); + } + Some(Payload::Closing(_)) => self.ending = Some(Ending::Closing), + Some(Payload::Holds(_)) => self.renew_lease(clock, verdict.sender), + Some(Payload::Content) => { + self.apply_content(clock, &verdict.plaintext, verdict.verified); + } + Some(Payload::Announcement(announcement)) => { + self.hear_announcement(clock, announcement); + } + None => {} + } + } + + /// §7.1: a session-key announcement the receiver accepted. + /// + /// A peer that is not the host owes it nothing at all — the state is the only source of + /// the keys a receiver keeps, and an announcement is read for the host's sake (§13.3) — so + /// the host's answer is the whole of what this decision is. + fn hear_announcement( + &mut self, + clock: Duration, + announcement: &Announcement, + ) { + if self.host.is_none() { + return; + } + let Some(key) = PublicKey::parse(&announcement.key) else { + return; + }; + let declared = announcement.role.as_deref(); + if let Some(host) = self.host.as_mut() { + host.announcement(key, declared); + } + self.publish_state(clock, HostReason::Announcement); + } + + /// What §13.3, §13.1's step 6 and §13.7 owe an applied room state. + pub(super) fn after_state(&mut self, clock: Duration, issued: u64) { + self.state_issued = Some(issued); + if let Some(host) = self.host.as_mut() { + // §7.1: a host that has verified a state keeps its own series above it. + host.verified_state(issued); + } + self.refresh_host_away(clock, true); + self.drop_departed_holds(); + // §13.6: the applied state is the room's writer set, so a revoked or demoted key's + // reciprocal accounting goes with its eligibility and a later promotion may arm again. + self.prune_reciprocal(); + let role = self.role().map(String::from); + self.note_local_eligibility(role.as_deref()); + self.role_seen = role; + // §13.1's steps 6 and 4: a state that commits this key is where the handshake belongs, + // and one that does not is what a re-announcement is for — the renewal clock alone would + // wait a whole window for it. + if self.commits_ours() { + self.resolve_speculation(); + self.handshake_once(clock); + self.flush_held_back(); + } else { + self.announce(clock); + } + // §13.7: a holder's *first* holds message waits for the state that commits its key, so + // one that was open when that state landed announces here rather than a renewal late. + // Nothing goes out for a session that holds nothing and has said nothing, and nothing + // goes out until the key is committed — that test is `announce_holds`' own. + self.announce_holds(clock); + } + + /// §13.2 and §13.3: a `kind = 0` plaintext, applied to the session document and answered. + /// An awareness message inside it is stamped on `clock`, the session's own, for §8.2. + #[expect( + clippy::too_many_arguments, + reason = "the frame, the clock it is read on, the verified key and the replica are the whole of a content frame" + )] + fn apply_content( + &mut self, + clock: Duration, + plaintext: &[u8], + verified: Option, + ) { + if !self.state_held() { + return; + } + // §13.9: a `viewer` publishes its SyncStep1, its awareness and its holds, and nothing + // else — a SyncStep2 is document content (§13.5) and is not its to send. An uncommitted + // key is the same: nothing it would answer with is publishable yet. The request is still + // recognised and the rest of the frame still applies. + let answers = self.may_publish() && self.is_writer(); + // §13.9: while a speculative edit is held, the readiness and replies a peer draws must + // be computed from the clean replica and not the one carrying the speculation. + let publication = self.publication_doc().clone(); + let (replies, requested) = + self.read_stream(clock, plaintext, &publication, answers); + if self.baseline.is_some() { + // Keep the ordinary replica's local view current without computing a second reply. + let ordinary = self.awareness.doc().clone(); + let _ = self.read_stream(clock, plaintext, &ordinary, false); + } + if requested && let Some(key) = verified { + self.arm_reciprocal(key); + } + if !answers { + return; + } + for reply in replies { + let bytes = encode_y_message(&reply); + self.publish(Published::Sync, &bytes); + } + } + + /// §7's stream, read message by message and applied as it is read, with the replies it + /// owes. A message that cannot be read or applied ends the reading, and the messages + /// before it stand: a stream no replica decodes is a sender's bug, and the session goes on. + #[expect( + clippy::too_many_arguments, + reason = "the frame, the replica it is applied to and whether it may be answered are the whole of a read" + )] + fn read_stream( + &mut self, + clock: Duration, + plaintext: &[u8], + doc: &Doc, + answer: bool, + ) -> (Vec, bool) { + let mut decoder = DecoderV1::from(plaintext); + let mut state = ReadState::default(); + let _ = MessageReader::new(&mut decoder).map_while(Result::ok).all( + |message| { + self.read_message(clock, message, doc, answer, &mut state) + }, + ); + (state.replies, state.requested) + } + + /// One message of the stream. Returns whether the reading goes on. + /// + /// §8.3: an auth message is read and ignored, a denial included, and an awareness query + /// is dropped rather than answered. A `SyncStep1` is answered once per frame + /// ([`MAX_REPLIES_PER_FRAME`]), and a message type §7 does not define ends the reading. + #[expect( + clippy::too_many_arguments, + reason = "one message, its target replica, whether it may be answered and the read it accumulates into" + )] + fn read_message( + &mut self, + clock: Duration, + message: YMessage, + doc: &Doc, + answer: bool, + state: &mut ReadState, + ) -> bool { + match message { + YMessage::Sync(SyncMessage::SyncStep1(vector)) => { + // §13.6: the request is read and past whatever the reply cap or the role does + // with it, so a caller still sees the obligation a `viewer` or an uncommitted + // key may not answer. The inner state vector was decoded by the reader already, + // so a malformed one never reaches here and neither arms nor consumes anything. + state.requested = true; + Self::answer(doc, answer, &vector, &mut state.replies); + true + } + YMessage::Sync( + SyncMessage::SyncStep2(bytes) | SyncMessage::Update(bytes), + ) => Self::apply_update(doc, &bytes), + YMessage::Awareness(update) => self.apply_awareness(clock, update), + YMessage::Auth(_) | YMessage::AwarenessQuery => true, + YMessage::Custom(..) => false, + } + } + + /// §7: a `SyncStep1` is answered with the `SyncStep2` its state vector asks for, while the + /// frame has answers left and the caller permits one. `answer` is the §13.9 gate: a + /// `viewer` or an uncommitted key reads and drops the request instead of computing a diff. + #[expect( + clippy::too_many_arguments, + reason = "the replica, whether a reply is permitted, the vector and the replies are one answer" + )] + fn answer( + doc: &Doc, + permitted: bool, + vector: &StateVector, + replies: &mut Vec, + ) { + if !permitted || replies.len() >= MAX_REPLIES_PER_FRAME { + return; + } + let txn = doc.transact(); + let diff = txn.encode_state_as_update_v1(vector); + replies.push(YMessage::Sync(SyncMessage::SyncStep2(diff))); + } + + /// One update applied to the chosen replica. Returns whether it was read and applied. + /// + /// The reader has already refused a frame holding an update nested past the bound, and + /// this decode is bounded too, so no path hands `yrs` one to recurse into. + pub(super) fn apply_update(doc: &Doc, bytes: &[u8]) -> bool { + let Ok(update) = decode_update(bytes) else { + return false; + }; + let mut txn = doc.transact_mut(); + txn.apply_update(update).is_ok() + } + + /// §8.2: one awareness message, applied by its own clocks and stamped on this session's + /// clock for each id it actually applied. Returns whether it was read, which is the same + /// answer [`Awareness::apply_update`] gives. + /// + /// The stamp is the applied ids and not the message's: an entry whose clock is not above + /// the one this replica already holds for that id is ignored by y-protocols and renews + /// nothing, so a peer that stops publishing is forgotten while a stale copy of its last + /// state is still arriving. + /// + /// An entry whose clock is [`u32::MAX`] is refused rather than applied, and the rest of the + /// message is applied as usual. `yrs` steps a clock by one without checking in two places + /// this path reaches — applying §8.2's removal for the id this connection announced + /// (`Awareness::apply_update_internal`), and dropping a state the room is done with + /// (`Awareness::remove_state`, reached by §8.2's expiry and §8.4's departure) — and a clock + /// is the sender's to choose, so the one value that cannot be stepped never enters: no state + /// at the maximum is held, and no removal can step one that is. + fn apply_awareness( + &mut self, + clock: Duration, + mut update: AwarenessUpdate, + ) -> bool { + update.clients.retain(|_, entry| entry.clock != u32::MAX); + let Ok(summary) = self.awareness.apply_update_summary(update) else { + return false; + }; + if let Some(applied) = summary { + self.stamp_awareness(&applied, clock); + } + true + } + + /// §8.2: the local clock an awareness update's applied ids were last seen at. A removed id + /// is dropped from the bookkeeping with its state, so the expiry tick never steps a + /// tombstone a second time. + fn stamp_awareness( + &mut self, + summary: &AwarenessUpdateSummary, + clock: Duration, + ) { + let own = self.awareness.client_id(); + let applied = summary + .added + .iter() + .chain(summary.updated.iter()) + .copied() + .filter(|id| *id != own); + for id in applied { + let _ = self.awareness_seen.insert(id, clock); + } + for id in &summary.removed { + let _ = self.awareness_seen.remove(id); + } + } +} diff --git a/crates/client/src/peer/events.rs b/crates/client/src/peer/events.rs new file mode 100644 index 0000000..08e2818 --- /dev/null +++ b/crates/client/src/peer/events.rs @@ -0,0 +1,67 @@ +//! What a driver hands in that is not a frame: `peer.joined`, `peer.left`, and a +//! host's listing changing under it. + +use super::PeerSession; +use crate::host::HostReason; +use std::time::Duration; + +impl PeerSession { + /// A seat has joined, from `peer.joined`. + /// + /// §7.1 obliges a host to publish a state on it — which is how the joiner learns the + /// listing and the roles without asking — and asks any peer that holds a verified state to + /// re-send that state unchanged, so a joiner's state arrives while the host is away. §13.7 + /// has a holder re-announce its holds on the same event. + pub fn seat_joined(&mut self, clock: Duration, seat: &str) { + if let Some(host) = self.host.as_mut() { + host.seat_joined(seat); + } + let _ = self.departed.remove(seat); + let _ = self.roster.insert(seat.to_string()); + // §13.7: a hold is re-announced when a peer is seated, so a joiner learns the room's + // held set without asking for it — on the event itself rather than at the next renewal, + // which is a whole window the joiner would spend holding nothing from this peer. The + // state goes first: a holds message resolves against the keys the applied state commits + // (§13.4), so a joiner that has applied no state yet refuses it `uncommitted_key`. + self.holds_announced_at = None; + if self.host.is_some() { + self.publish_state(clock, HostReason::Roster); + self.announce_holds(clock); + return; + } + // §7.1: the re-send is for a room whose host is away — a joiner the host cannot answer, + // or a returning host that lost its `issued`. While the seat the `host` entry labels is + // seated, the host's own fresh state answers this join, and a copy from every peer would + // put the whole listing on every connection once per seated peer. + let host_away = self + .host_seat() + .is_none_or(|host_seat| !self.roster.contains(host_seat)); + if host_away && let Some(frame) = self.held_state_frame.clone() { + self.republish(&frame); + } + self.announce_holds(clock); + } + + /// A seat has left, from `peer.left`: §13.8's clock can arm on it and §13.7's holds go. + pub fn seat_left(&mut self, clock: Duration, seat: &str) { + if let Some(host) = self.host.as_mut() { + host.seat_left(seat); + } + let _ = self.roster.remove(seat); + let _ = self.departed.insert(seat.to_string()); + self.drop_departed_holds(); + self.refresh_host_away(clock, false); + if self.host.is_some() { + self.publish_state(clock, HostReason::Roster); + } + } + + /// The host's listing changed, from whatever watches its working tree (§7.1). + /// + /// A listing is replaced wholesale by every state, so this is the one thing a host's + /// adapter has to say about it: the state that follows names the whole tree as it now is, + /// and a shorter listing is a smaller working tree rather than a partial update (§13.3). + pub fn listing_changed(&mut self, clock: Duration) { + self.publish_state(clock, HostReason::Listing); + } +} diff --git a/crates/client/src/peer/holds.rs b/crates/client/src/peer/holds.rs new file mode 100644 index 0000000..1fd11ee --- /dev/null +++ b/crates/client/src/peer/holds.rs @@ -0,0 +1,128 @@ +//! §13.7: the paths this client offers, the lease a peer's holds live under, and the +//! expiry that forgets them. + +use super::PeerSession; +use super::plaintext::canonical; +use super::report::Published; +use crate::sealed::KeyId; +use serde_json::json; +use std::time::Duration; + +impl PeerSession { + /// §13.7: only an accepted holds message renews a lease, and nothing else from the same + /// peer does. + pub(super) fn renew_lease( + &mut self, + clock: Duration, + sender: Option, + ) { + if let Some(id) = sender { + let _ = self.leases.insert(id, clock); + } + } + + /// §13.7: the whole held set, renewed on the client's own clock and published at once + /// when it changes. Rising from the tick and from nothing a peer sends is what lets a + /// seated, idle peer keep its holds. + pub(super) fn announce_holds(&mut self, clock: Duration) { + if !self.may_publish() { + // A `viewer` keeps its edit in its own replica and never publishes it (§13.9); + // everyone else's is held back by §13.1's step 4 and sent once a state commits this + // key. + return; + } + // A holder with nothing open and nothing yet said has no frame to send; one that has + // released everything says so, because the empty set is what §13.7 asks for. + if self.held.is_empty() + && self.holds_sent.is_empty() + && self.holds_announced_at.is_none() + { + return; + } + let paths: Vec = self.held.iter().cloned().collect(); + let due = paths != self.holds_sent + || match self.holds_announced_at { + None => true, + Some(at) => clock.saturating_sub(at) >= self.renew, + }; + if !due { + return; + } + let plaintext = canonical(&json!({"holds": &paths})); + self.publish(Published::Holds, &plaintext); + self.holds_sent = paths; + self.holds_announced_at = Some(clock); + } + + /// §13.7's expiry: a peer's whole held set is forgotten once its lease has lapsed. + /// + /// The text has this checked on the renewal tick, and a client whose tick *is* its renewal + /// tick checks there; a tick that comes more often forgets sooner, which is inside the + /// `awareness_expire_ms + awareness_renew_ms` the text bounds the delay by and never + /// inside the `MUST forget ... after awareness_expire_ms` it states. An expiry is not a + /// refusal — no frame is dropped, the peer is not gone and nothing is reported anywhere — + /// which is why the only observable is the set becoming empty. + pub(super) fn expire_leases(&mut self, clock: Duration) { + if self.mutating("no-lease") { + return; + } + let lapsed: Vec = self + .leases + .iter() + .filter(|(_, at)| clock.saturating_sub(**at) >= self.expire) + .map(|(id, _)| *id) + .collect(); + for id in lapsed { + let _ = self.leases.remove(&id); + let _ = self.reader.holds.remove(&id); + } + } + + /// §13.7: the roster is the authority on who is present, so a key whose entry labels a + /// seat that has left loses its holds at once rather than with its lease. A seat the + /// roster never knew is not this rule: it is left to its lease. + pub(super) fn drop_departed_holds(&mut self) { + let gone: Vec = self + .reader + .committed + .values() + .filter(|peer| self.departed.contains(&peer.peer_id)) + .map(|peer| peer.key.id()) + .collect(); + for id in gone { + let _ = self.leases.remove(&id); + let _ = self.reader.holds.remove(&id); + } + } + + /// Opens a path: this client offers it, and its whole held set changes (§13.7). + /// + /// The change is announced here rather than left to the caller's next tick: §13.7 asks a + /// holder to re-announce at once when its set changes, and the tick's period is the room's + /// own `awareness_renew_ms` — fifteen seconds at the reference defaults, which is not + /// "at once". Nothing goes out while §13.1's step 4 withholds everything but the + /// announcement, and nothing goes out for a set that did not change. + pub fn open(&mut self, clock: Duration, path: &str) { + let _ = self.held.insert(path.to_string()); + self.announce_holds(clock); + } + + /// Releases every path. §13.7 asks for the empty set rather than for silence, so the room + /// learns in one hop instead of waiting out a lease — and it learns it here, for the reason + /// [`Self::open`] gives. + pub fn release(&mut self, clock: Duration) { + self.held.clear(); + self.announce_holds(clock); + } + + /// Holds this one path and nothing else, announced once (§13.7). + /// + /// A holds message carries the whole set and no delta, so a caller replacing the set with + /// one path cannot say so with [`Self::release`] and [`Self::open`]: each announces the + /// change it makes, and the room would see an empty set between them. + pub fn hold_only(&mut self, clock: Duration, path: &str) { + self.held.clear(); + let _ = self.held.insert(path.to_string()); + self.announce_holds(clock); + } +} diff --git a/crates/client/src/peer/invite.rs b/crates/client/src/peer/invite.rs new file mode 100644 index 0000000..c6d5af5 --- /dev/null +++ b/crates/client/src/peer/invite.rs @@ -0,0 +1,205 @@ +//! `PROTOCOL.md` §5.1's invite: the link, its two keys and the connection address +//! it names. Everything here reads a link and refuses a bad one locally, before a socket +//! is opened. + +use std::fmt; + +use crate::sealed::PublicKey; +use crate::sealed::RoomKey; +use selvage_protocol as proto; + +/// An invite as `PROTOCOL.md` §5.1 writes one and §13.1's first step reads it. +/// +/// The fragment is the only part of a link a user agent never sends, which is what makes it +/// the one place a key can travel from a host to a guest; this reads the room and the token +/// from the query and the two keys from the fragment, and the socket URL it hands back has +/// the fragment stripped. Both keys are required, and their absence is a local refusal before +/// a socket is opened: without both, a client can neither read a frame nor verify one, so +/// there is no fallback and no plaintext mode. +#[derive(Clone, PartialEq, Eq)] +pub struct PeerInvite { + /// The connection URL, without the fragment. Nothing here puts the fragment back. + pub socket_url: String, + pub room: String, + pub token: String, + pub room_key: RoomKey, + pub host_key: PublicKey, +} + +/// §5.1's two keys are not printed. A derived `Debug` would put the room key and the host key +/// in whatever log this invite is written to, +/// which is the one thing the fragment exists to prevent. Their ids are in every frame's clear +/// prefix already (`CANONICAL.md` §6.1), so those stand in for them. +impl fmt::Debug for PeerInvite { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("PeerInvite") + .field("socket_url", &self.socket_url) + .field("room", &self.room) + .field("token", &self.token) + .field("room_key", &"") + .field("host_key", &self.host_key.id().hex()) + .finish() + } +} + +impl PeerInvite { + /// Reads an invite link, or says which value is missing or malformed. + /// + /// Both of `PROTOCOL.md` §5.1's forms are links this joins: the connection URL and the page + /// link, which names the same room, token and fragment over the scheme a browser speaks and + /// is resolved to its connection address first ([`wire_address`]). + /// + /// §5.1's repeat rule is a local refusal in either form. A page link has no server in it, so + /// a `room` or `token` written twice is refused here, and the refusal names the parameter — + /// the shape [`fragment_keys`] already takes for `k` and `h`. + /// + /// # Errors + /// + /// Returns the client's own words for a link it cannot join with, which `PROTOCOL.md` + /// §5.1 fixes as a local refusal: it is not a `session.error`, it is paired with no close + /// code, and §11's vocabulary is not involved. + pub fn parse(invite: &str) -> Result { + let (address, fragment) = invite + .split_once('#') + .ok_or_else(|| MISSING_FRAGMENT.to_string())?; + let socket_url = wire_address(address); + let parsed = proto::parse_session_url(&socket_url) + .ok_or_else(|| unreadable_address(address, &socket_url))?; + let room = parsed + .join + .room + .ok_or_else(|| "the invite names no room".to_string())?; + let token = parsed + .join + .token + .ok_or_else(|| "the invite carries no token".to_string())?; + let (room_key, host_key) = fragment_keys(fragment)?; + Ok(Self { + socket_url, + room, + token, + room_key, + host_key, + }) + } +} + +/// The connection address a `PROTOCOL.md` §5.1 invite names, with any fragment left off. +/// +/// The page form names the same room, token and fragment over the scheme a browser speaks +/// (`https://h/page/?room=…&token=…`), and the connection address is derived from it by +/// reading the scheme back — `http://` as `ws://`, `https://` as `wss://` — and appending the +/// session endpoint. A link that is already a connection URL, or one this cannot read as +/// either form, is handed back as its address: what refuses it is [`PeerInvite::parse`], which +/// knows which part is missing. +/// +/// §5.1's two keys live in the fragment and a user agent never puts one in a request, so +/// nothing here keeps it — the returned address is one a socket may be dialled on, and a caller +/// that put the fragment back would put the room key in that request. A reader that needs the +/// keys splits the fragment off the link itself, which is what [`PeerInvite::parse`] does; this +/// function is the address half of that reading and nothing more. +#[must_use] +pub fn wire_address(link: &str) -> String { + let address = link + .split_once('#') + .map_or(link, |(address, _fragment)| address); + page_to_endpoint(address).unwrap_or_else(|| address.to_string()) +} + +/// Why a connection address is not one a `PROTOCOL.md` §5.1 invite reads from: the join +/// parameter it repeats, by name, or the plain fact that it addresses no session endpoint. +/// +/// §5.1 has `room` and `token` appear at most once, in either form, and a receiver **MUST NOT** +/// take a value by the order it appears. A page link has no server to refuse a repeat, so the +/// receiver refuses it, and the reason names the parameter — the shape [`fragment_keys`] already +/// takes for `k` and `h`. +fn unreadable_address(address: &str, socket_url: &str) -> String { + repeated_join_name(socket_url).map_or_else( + || format!("{address:?} does not address the session endpoint"), + |name| format!("the invite names `{name}` twice"), + ) +} + +/// The join parameter a connection address repeats, if it repeats one. +/// +/// §5.1's query rule, read through the parser the server uses: [`proto::parse_session_url`] +/// folds a repeat into `None`, and this asks [`proto::parse_join_query`] which name it refused, +/// so that a page link's refusal can say it instead of blaming the address. A genuine duplicate +/// in the `wss://` form is refused by the server, and this is only what the client says about +/// the link it was handed. +fn repeated_join_name(address: &str) -> Option<&'static str> { + let query = address.split_once('?').map_or("", |(_, query)| query); + match proto::parse_join_query(query) { + Err(proto::JoinQueryError::Duplicate(name)) => Some(name), + Ok(_) => None, + } +} + +/// The connection URL a page link names, or `None` when the address is not a page link. +fn page_to_endpoint(address: &str) -> Option { + let scheme = match address + .strip_prefix("http://") + .or_else(|| address.strip_prefix("https://")) + { + Some(rest) if address.starts_with("http://") => format!("ws://{rest}"), + Some(rest) => format!("wss://{rest}"), + None => return None, + }; + let (before_query, query) = match scheme.split_once('?') { + Some((before, query)) => (before, Some(query)), + None => (scheme.as_str(), None), + }; + let (authority, path) = match before_query.split_once('/') { + Some((authority, path)) => (authority, format!("/{path}")), + None => (before_query, String::new()), + }; + if authority.is_empty() { + return None; + } + let base = format!("{authority}{}", path.trim_end_matches('/')); + Some(query.map_or_else( + || format!("{base}{}", proto::ENDPOINT_PATH), + |rest| format!("{base}{}?{rest}", proto::ENDPOINT_PATH), + )) +} + +/// What a link without a fragment is told, which is `PROTOCOL.md` §5.1's own sentence: the +/// honest refusal asks for the whole link. +const MISSING_FRAGMENT: &str = "the invite carries no fragment, so neither its room key nor its host key is here: ask for the whole link, `#` and all"; + +/// The two keys a fragment carries: `k` and `h`, each at most once, and an unknown parameter +/// ignored as an unknown query parameter is. +fn fragment_keys(fragment: &str) -> Result<(RoomKey, PublicKey), String> { + let mut room_key = None; + let mut host_key = None; + for pair in fragment.split('&') { + let (name, value) = pair.split_once('=').unwrap_or((pair, "")); + let decoded = proto::percent_decode(value); + match name { + "k" => set_once(&mut room_key, RoomKey::parse(&decoded), "k")?, + "h" => set_once(&mut host_key, PublicKey::parse(&decoded), "h")?, + _ => {} + } + } + match (room_key, host_key) { + (Some(k), Some(h)) => Ok((k, h)), + (None, _) => Err("the invite carries no room key (`k`)".to_string()), + (_, None) => Err("the invite carries no host key (`h`)".to_string()), + } +} + +/// One fragment value, refused when it is the second of its name or spells no key. +fn set_once( + slot: &mut Option, + value: Option, + name: &str, +) -> Result<(), String> { + if slot.is_some() { + return Err(format!("the invite names `{name}` twice")); + } + let key = value.ok_or_else(|| { + format!("`{name}` is not a 32-byte key in the fragment's encoding") + })?; + *slot = Some(key); + Ok(()) +} diff --git a/crates/client/src/peer/mod.rs b/crates/client/src/peer/mod.rs index 0e3845a..7a8a23d 100644 --- a/crates/client/src/peer/mod.rs +++ b/crates/client/src/peer/mod.rs @@ -16,2180 +16,151 @@ //! own tests be about the rule rather than about how long a machine took. use std::collections::{BTreeMap, BTreeSet, VecDeque}; -use std::fmt; -use std::mem; use std::time::Duration; -use serde_json::{Value, json}; +use yrs::Doc; use yrs::block::ClientID; -use yrs::sync::awareness::AwarenessUpdateSummary; -use yrs::sync::{ - Awareness, AwarenessUpdate, Message as YMessage, MessageReader, SyncMessage, -}; -use yrs::updates::decoder::DecoderV1; -use yrs::updates::encoder::{Encode, Encoder, EncoderV1}; -use yrs::{ - Doc, GetString, OffsetKind, Options, ReadTxn, StateVector, Text, Transact, -}; - -use selvage_protocol as proto; - -use crate::host::{HostOptions, HostProducer, HostReason}; -use crate::nesting::decode_update; -use crate::sealed::{ - Announcement, FrameKey, Guard, KeyId, Payload, PublicKey, Reader, Recipe, - RoomKey, SealedError, SessionKey, Verdict, fresh_nonce, read_varuint, seal, -}; - -/// An invite as `PROTOCOL.md` §5.1 writes one and §13.1's first step reads it. -/// -/// The fragment is the only part of a link a user agent never sends, which is what makes it -/// the one place a key can travel from a host to a guest; this reads the room and the token -/// from the query and the two keys from the fragment, and the socket URL it hands back has -/// the fragment stripped. Both keys are required, and their absence is a local refusal before -/// a socket is opened: without both, a client can neither read a frame nor verify one, so -/// there is no fallback and no plaintext mode. -#[derive(Clone, PartialEq, Eq)] -pub struct PeerInvite { - /// The connection URL, without the fragment. Nothing here puts the fragment back. - pub socket_url: String, - pub room: String, - pub token: String, - pub room_key: RoomKey, - pub host_key: PublicKey, -} - -/// §5.1's two keys are not printed. A derived `Debug` would put the room key and the host key -/// in whatever log this invite is written to, -/// which is the one thing the fragment exists to prevent. Their ids are in every frame's clear -/// prefix already (`CANONICAL.md` §6.1), so those stand in for them. -impl fmt::Debug for PeerInvite { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("PeerInvite") - .field("socket_url", &self.socket_url) - .field("room", &self.room) - .field("token", &self.token) - .field("room_key", &"") - .field("host_key", &self.host_key.id().hex()) - .finish() - } -} - -impl PeerInvite { - /// Reads an invite link, or says which value is missing or malformed. - /// - /// Both of `PROTOCOL.md` §5.1's forms are links this joins: the connection URL and the page - /// link, which names the same room, token and fragment over the scheme a browser speaks and - /// is resolved to its connection address first ([`wire_address`]). - /// - /// §5.1's repeat rule is a local refusal in either form. A page link has no server in it, so - /// a `room` or `token` written twice is refused here, and the refusal names the parameter — - /// the shape [`fragment_keys`] already takes for `k` and `h`. - /// - /// # Errors - /// - /// Returns the client's own words for a link it cannot join with, which `PROTOCOL.md` - /// §5.1 fixes as a local refusal: it is not a `session.error`, it is paired with no close - /// code, and §11's vocabulary is not involved. - pub fn parse(invite: &str) -> Result { - let (address, fragment) = invite - .split_once('#') - .ok_or_else(|| MISSING_FRAGMENT.to_string())?; - let socket_url = wire_address(address); - let parsed = proto::parse_session_url(&socket_url) - .ok_or_else(|| unreadable_address(address, &socket_url))?; - let room = parsed - .join - .room - .ok_or_else(|| "the invite names no room".to_string())?; - let token = parsed - .join - .token - .ok_or_else(|| "the invite carries no token".to_string())?; - let (room_key, host_key) = fragment_keys(fragment)?; - Ok(Self { - socket_url, - room, - token, - room_key, - host_key, - }) - } -} - -/// The connection address a `PROTOCOL.md` §5.1 invite names, with any fragment left off. -/// -/// The page form names the same room, token and fragment over the scheme a browser speaks -/// (`https://h/page/?room=…&token=…`), and the connection address is derived from it by -/// reading the scheme back — `http://` as `ws://`, `https://` as `wss://` — and appending the -/// session endpoint. A link that is already a connection URL, or one this cannot read as -/// either form, is handed back as its address: what refuses it is [`PeerInvite::parse`], which -/// knows which part is missing. -/// -/// §5.1's two keys live in the fragment and a user agent never puts one in a request, so -/// nothing here keeps it — the returned address is one a socket may be dialled on, and a caller -/// that put the fragment back would put the room key in that request. A reader that needs the -/// keys splits the fragment off the link itself, which is what [`PeerInvite::parse`] does; this -/// function is the address half of that reading and nothing more. -#[must_use] -pub fn wire_address(link: &str) -> String { - let address = link - .split_once('#') - .map_or(link, |(address, _fragment)| address); - page_to_endpoint(address).unwrap_or_else(|| address.to_string()) -} - -/// Why a connection address is not one a `PROTOCOL.md` §5.1 invite reads from: the join -/// parameter it repeats, by name, or the plain fact that it addresses no session endpoint. -/// -/// §5.1 has `room` and `token` appear at most once, in either form, and a receiver **MUST NOT** -/// take a value by the order it appears. A page link has no server to refuse a repeat, so the -/// receiver refuses it, and the reason names the parameter — the shape [`fragment_keys`] already -/// takes for `k` and `h`. -fn unreadable_address(address: &str, socket_url: &str) -> String { - repeated_join_name(socket_url).map_or_else( - || format!("{address:?} does not address the session endpoint"), - |name| format!("the invite names `{name}` twice"), - ) -} - -/// The join parameter a connection address repeats, if it repeats one. -/// -/// §5.1's query rule, read through the parser the server uses: [`proto::parse_session_url`] -/// folds a repeat into `None`, and this asks [`proto::parse_join_query`] which name it refused, -/// so that a page link's refusal can say it instead of blaming the address. A genuine duplicate -/// in the `wss://` form is refused by the server, and this is only what the client says about -/// the link it was handed. -fn repeated_join_name(address: &str) -> Option<&'static str> { - let query = address.split_once('?').map_or("", |(_, query)| query); - match proto::parse_join_query(query) { - Err(proto::JoinQueryError::Duplicate(name)) => Some(name), - Ok(_) => None, - } -} - -/// The connection URL a page link names, or `None` when the address is not a page link. -fn page_to_endpoint(address: &str) -> Option { - let scheme = match address - .strip_prefix("http://") - .or_else(|| address.strip_prefix("https://")) - { - Some(rest) if address.starts_with("http://") => format!("ws://{rest}"), - Some(rest) => format!("wss://{rest}"), - None => return None, - }; - let (before_query, query) = match scheme.split_once('?') { - Some((before, query)) => (before, Some(query)), - None => (scheme.as_str(), None), - }; - let (authority, path) = match before_query.split_once('/') { - Some((authority, path)) => (authority, format!("/{path}")), - None => (before_query, String::new()), - }; - if authority.is_empty() { - return None; - } - let base = format!("{authority}{}", path.trim_end_matches('/')); - Some(query.map_or_else( - || format!("{base}{}", proto::ENDPOINT_PATH), - |rest| format!("{base}{}?{rest}", proto::ENDPOINT_PATH), - )) -} - -/// What a link without a fragment is told, which is `PROTOCOL.md` §5.1's own sentence: the -/// honest refusal asks for the whole link. -const MISSING_FRAGMENT: &str = "the invite carries no fragment, so neither its room key nor its host key is here: ask for the whole link, `#` and all"; - -/// What a session built to be a host is told when the handshake gave it no seat: §7.1's state -/// labels its own connection's seat, and there is nothing to write without one. -const HOST_NEEDS_SEAT: &str = - "a host session publishes its own seat, and the handshake gave it none"; - -/// What a host is told when §7.1's closing could not be sealed: a host cannot refuse to close -/// without somewhere to say so, and a driver that never looks is a driver closing nothing. -const CLOSING_UNSEALED: &str = "the closing could not be sealed"; - -/// The two keys a fragment carries: `k` and `h`, each at most once, and an unknown parameter -/// ignored as an unknown query parameter is. -fn fragment_keys(fragment: &str) -> Result<(RoomKey, PublicKey), String> { - let mut room_key = None; - let mut host_key = None; - for pair in fragment.split('&') { - let (name, value) = pair.split_once('=').unwrap_or((pair, "")); - let decoded = proto::percent_decode(value); - match name { - "k" => set_once(&mut room_key, RoomKey::parse(&decoded), "k")?, - "h" => set_once(&mut host_key, PublicKey::parse(&decoded), "h")?, - _ => {} - } - } - match (room_key, host_key) { - (Some(k), Some(h)) => Ok((k, h)), - (None, _) => Err("the invite carries no room key (`k`)".to_string()), - (_, None) => Err("the invite carries no host key (`h`)".to_string()), - } -} - -/// One fragment value, refused when it is the second of its name or spells no key. -fn set_once( - slot: &mut Option, - value: Option, - name: &str, -) -> Result<(), String> { - if slot.is_some() { - return Err(format!("the invite names `{name}` twice")); - } - let key = value.ok_or_else(|| { - format!("`{name}` is not a 32-byte key in the fragment's encoding") - })?; - *slot = Some(key); - Ok(()) -} - -/// What a session is opened with: the invite's two keys, the session's clock, and the seats -/// the server has shown. -#[derive(Clone)] -pub struct PeerOptions { - pub room_id: String, - pub room_key: RoomKey, - /// The host key the invite's `h` carries: the room's root of trust, and the only key that - /// verifies a `kind = 1` state or a `kind = 2` closing. - pub host_key: PublicKey, - /// `awareness_renew_ms` (`PROTOCOL.md` §8.2): the clock an uncommitted announcement is - /// re-sent on and a held set is renewed on, and the tick a lease (§13.7) and an expired - /// remote awareness state (§8.2) are checked on. - pub renew: Duration, - /// `awareness_expire_ms`: the window a remote awareness state is forgotten after - /// (§8.2), the host-away window (§13.8) and, read from the seat, the no-state window - /// (§13.3). - pub expire: Duration, - /// The seat this connection is shown under, from `room.created`/`room.joined`. It decides - /// no attribution (§13.4) and is carried only because a person is shown it. - pub seat: Option, - /// The seats the roster has, which is what §13.8 reads a state's `host` entry against. - pub roster: BTreeSet, - /// A fixed session keypair, as its 32-byte Ed25519 seed. - /// - /// **A test seam, and not production surface.** §13.1 mints the session keypair in memory - /// for the connection and never persists it, and no frame carries a private key to a - /// client, so nothing in the protocol lets a caller choose one. It exists because the - /// corpus's decision layer drives a *fixture* keypair: the state a decision vector - /// delivers commits that fixture key's public half, so a client that minted its own key - /// could not be the peer the vector is about. `None` mints one, which is what a session - /// does. - pub fixed_session_key: Option<[u8; 32]>, - /// The role this client believes it has been given — `guest` or `viewer`, never `host` — - /// declared in its announcement. A host **SHOULD** honour it (§7.1). - pub declared_role: Option, - /// The awareness client id the handshake announced, so that the states this connection - /// publishes and the seat the room attributes them to agree (§8.4). `None` mints one from - /// the replica, which is what a session with no handshake does. - pub awareness_client_id: Option, - /// The host's producer half (§7.1), which makes this session the room's authority rather - /// than one of its peers. The host key's private half lives here, so a session given one - /// can sign a state and a session without one cannot; the room's host publishes the state - /// that every peer's key and role come from, and a session with no state produces none. - pub host: Option, - /// The room's frame budget (`CANONICAL.md` §6.1), [`FRAME_BUDGET`] when `None`. **A test - /// seam**: a live session has no reason to set it, and a smaller one only ends a room sooner. - pub frame_budget: Option, -} - -/// `CANONICAL.md` §6.1's frame budget: half of SP 800-38D's 2³² bound on one key with random -/// nonces, which is the room's and not one sender's, so that a client that missed frames the -/// relay dropped still stops well short of it. -pub const FRAME_BUDGET: u64 = 1 << 31; - -/// How many `SyncStep1` messages one `kind = 0` frame is answered for. -/// -/// A frame is a stream of messages with no count (`PROTOCOL.md` §7), and the answer to a -/// `SyncStep1` is a diff of the whole document, so a frame of them answered one by one would -/// cost the room a document per four bytes. A conforming peer asks once per frame, so past the -/// first the state vector is read and dropped and its diff is never computed. -const MAX_REPLIES_PER_FRAME: usize = 1; - -/// The same rule as [`PeerInvite`]'s: the room key, the host key and the two private seeds are -/// not printed. A session's options are built from an invite, and §5.1 forbids what they carry -/// from reaching a log as much as it forbids it reaching a request. -impl fmt::Debug for PeerOptions { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("PeerOptions") - .field("room_id", &self.room_id) - .field("room_key", &"") - .field("host_key", &self.host_key.id().hex()) - .field("renew", &self.renew) - .field("expire", &self.expire) - .field("seat", &self.seat) - .field("roster", &self.roster) - .field( - "fixed_session_key", - &self.fixed_session_key.map(|_| ""), - ) - .field("declared_role", &self.declared_role) - .field("awareness_client_id", &self.awareness_client_id) - .field("host", &self.host.as_ref().map(|_| "")) - .field("frame_budget", &self.frame_budget) - .finish() - } -} - -/// What a session did with one frame: the decision `PROTOCOL.md` §13.11 observes. -#[derive(Debug, Clone, PartialEq, Eq)] -pub enum Outcome { - /// It verified and what it carried was applied. - Applied { kind: u64 }, - /// It was refused, at the first of `CANONICAL.md` §6.1's ten steps that refused it. - Dropped { reason: String }, - /// It verified and applied nothing: §13.10's closing handed to a receiver that holds no - /// verified state. Not a refusal — nothing was refused — and in neither list a vector - /// asserts, which is what vector 155 pins. - Ignored { kind: u64 }, -} - -/// What a session is about to publish: the kind of envelope it is, and whether `PROTOCOL.md` -/// §13.11's report counts it as a **publication** or as a §7 sync-handshake frame. -/// -/// The two counts are apart because a vector asserts one of them: §13.1's step 6 obliges a -/// client that applies a state committing its own key to send a `SyncStep1`, so a single -/// number could not tell a republished request from a publication. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum Published { - /// The session-key announcement, `kind = 4`. - Announcement, - /// A holds message, `kind = 3`. - Holds, - /// Document content, `kind = 0`. - Content, - /// A `SyncStep1` or a `SyncStep2`, `kind = 0`. - Sync, -} - -impl Published { - const fn kind(self) -> u64 { - match self { - Self::Holds => 3, - Self::Announcement => 4, - Self::Content | Self::Sync => 0, - } - } - - const fn counted(self) -> Counted { - match self { - Self::Content | Self::Holds | Self::Announcement => { - Counted::Publication - } - Self::Sync => Counted::Handshake, - } - } -} - -/// Which of the two counts a published frame moves (§13.11). -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -enum Counted { - Publication, - Handshake, -} - -/// One locally authored edit §13.1's step 4 is holding back, and whether it was made while no -/// applied state had given this connection's key a role yet. -/// -/// The deltas themselves and not a diff over the replica: a state that does not commit this key -/// still lets its peers' content be applied (§13.2), so a vector taken at the first held-back -/// edit would carry their changes out again under this connection's key. -#[derive(Debug, Clone)] -struct Unsent { - update: Vec, - speculative: bool, -} - -/// The replies and the readiness one frame drew, accumulated as its messages are read. -#[derive(Debug, Default)] -struct ReadState { - replies: Vec, - requested: bool, -} - -/// One frame a session applied, with the index of the frame it was handed as. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub struct Applied { - pub frame: u64, - pub kind: u64, -} - -/// One frame a session refused, and the reason `CANONICAL.md` §6.1's vocabulary gives. -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct Dropped { - pub frame: u64, - pub reason: String, -} - -/// The four endings a session reaches on its own. What §13.10 calls "the room is destroyed" -/// is the fifth and has no frame: a client learns it as `room_unknown` or close 4001 when it -/// names the id, which is the socket's business and not this module's. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum Ending { - /// A `kind = 2` closing that verified and was above the mark, with a verified state - /// below it (§13.10). - Closing, - /// The host-away clock passed its window (§13.8). - HostAway, - /// The no-state window passed with nothing applied (§13.3). - NoState, - /// The room's frame count reached `CANONICAL.md` §6.1's frame budget. - FrameBudget, -} - -/// One connection's `selvage/2` session. -pub struct PeerSession { - room_id: String, - frame_key: FrameKey, - session: SessionKey, - declared_role: Option, - /// The host's producer half, when this connection holds the host key (§7.1). - host: Option, - /// The bytes of the last room state this connection **applied** (§7.1). - /// - /// §7.1 has a peer that holds a verified state re-send it, unchanged, when it sees a - /// `peer.joined`, so a joiner's state arrives while the host is away. The bytes are the - /// ones it received: only the host key signs a state, and a peer that re-sealed or - /// re-signed one would hand the room a frame every other peer refuses. - held_state_frame: Option>, - counter: u64, - renew: Duration, - expire: Duration, - seat: Option, - roster: BTreeSet, - reader: Reader, - awareness: Awareness, - /// §8.2's receiver bookkeeping: the local monotone clock, the one every argument named - /// `clock` carries, at which each **remote** awareness client id's state was last - /// actually applied. A tick forgets an id whose stamp is `awareness_expire_ms` old, and an - /// entry that was ignored because its clock was not above the one held does not stamp. - /// - /// This connection's own id is never here: §8.2 has a client never expire itself. - awareness_seen: BTreeMap, - outbound: VecDeque>, - /// The paths this client has open: the whole set every holds message carries (§13.7). - held: BTreeSet, - /// The set the last holds message carried, so that a changed set is published at once and - /// an unchanged one waits for the renewal clock. - holds_sent: Vec, - holds_announced_at: Option, - /// When the last holds message from each key was accepted, which is its lease. - leases: BTreeMap, - /// The seats that have left, from `peer.left`: what §13.7 drops holds on and what tells - /// a seat the roster never knew from one that departed. - departed: BTreeSet, - announced_at: Option, - /// The local edits this client made while §13.1's step 4 held its content back, in the - /// order it made them: the deltas themselves, so that flushing them cannot carry a peer's - /// changes out under this connection's key. `speculative` marks an edit made while no - /// applied state gave this key a role yet, which a `viewer` resolution discards. - unsent: Vec, - /// A clean replica, present only while UNKNOWN-role local edits need a rollback (§13.9). - /// - /// A genuine second document built from an encoded update, never `Doc::clone` (which is a - /// handle to the same store): this is what a `viewer` resolution adopts in place of the - /// replica that holds the speculative edits. - baseline: Option, - /// A typed effect of the owned replica, for the relay's §13.5 text surface: bumped whenever - /// this session replaces the document a consumer was reading text from (§13.9's `viewer` - /// resolution adopting the clean baseline). A state-driven rollback can then be reported - /// even when the path set and listing are unchanged, without re-reading or comparing text. - replica_epoch: u64, - /// The committed writer keys whose first accepted `SyncStep1` this connection has served - /// with its own request (§13.6), by the full key that verified. - reciprocal_served: BTreeSet, - /// The committed writer keys whose reciprocal request is owed and not yet sealed and queued. - reciprocal_pending: BTreeSet, - /// Readiness owed for this local key's renewed continuous writer eligibility (§13.6). - local_readiness_pending: bool, - /// The role the last applied state gave this connection's own key, for continuous - /// eligibility: an already-handshaken key that re-enters writer eligibility owes one request. - role_seen: Option, - /// The clock of the first content frame this client refused since its last `SyncStep1`, - /// which is §13.6's interval. `None` means there is nothing to re-sync about. - resync_from: Option, - /// The clock of the last `SyncStep1` this client sent, which is what the re-sync is - /// bounded by: one is sent per renewal interval however many frames were refused. - handshaken_at: Option, - /// The edition of the state this client holds, or `None` before one has been applied - /// (§13.3's waiting rules and §13.10's closing both turn on it). - state_issued: Option, - host_away_since: Option, - published: u64, - handshake: u64, - frames: u64, - /// `CANONICAL.md` §6.1's count: every binary frame this session was delivered and every - /// frame it sealed, across reconnects, because the frame key it is counted against outlives - /// a socket. - room_frames: u64, - frame_budget: u64, - applied: Vec, - dropped: Vec, - ignored: Vec, - /// The frames refused because they were a second state at an edition this client already - /// holds (§13.3). The reason is `stale_issued` like any other stale state; this is the - /// local annotation that says which of the two it was. - conflicts: Vec, - ending: Option, - mutation: Option, - /// The first thing that went wrong on the way *out* — a CSPRNG that would not read, an - /// AEAD that refused its own inputs. A session cannot refuse to publish without somewhere - /// to say so, and a driver that never looks is a driver publishing nothing. - fault: Option, -} - -impl PeerSession { - /// A connection's session: §13.1's steps 1 and 2, and nothing sent yet. - /// - /// The clock this session reads starts at zero and every argument named `clock` is that - /// many units past the seat, so a caller passes `start.elapsed()` and a test passes a - /// number. Nothing here reads a platform clock. - /// - /// # Errors - /// - /// Returns an error when the platform's CSPRNG cannot be read, which is the one thing - /// minting a session keypair needs, and when a host session's first state cannot be sealed: - /// §7.1's mint state is what brings the room's listing into existence and commits this - /// connection's key, so a host that could not publish one is a host no peer can see. - pub fn new(options: &PeerOptions) -> Result { - let session = match options.fixed_session_key { - Some(seed) => SessionKey::from_seed(seed), - None => SessionKey::generate()?, - }; - let reader = - Reader::new(&options.room_id, options.room_key, options.host_key); - let frame_key = reader.frame_key; - let own_key = session.public(); - let host = match &options.host { - None => None, - Some(host_options) => { - Some(host_producer(options, frame_key, host_options, own_key)?) - } - }; - // `CANONICAL.md` §6.1: the host's count is the room's, so a host continues the one it - // saved. - let room_frames = host.as_ref().map_or(0, HostProducer::room_frames); - let mut roster = options.roster.clone(); - if let (Some(seat), true) = (options.seat.as_ref(), host.is_some()) { - // §9: a host is seated in the room it minted, whether or not the roster it was - // handed names it. Without this its own state's `host` entry labels a seat the - // session believes is absent, and §13.8's clock then ends its own session. - let _ = roster.insert(seat.clone()); - } - let mut peer = Self { - room_id: options.room_id.clone(), - frame_key, - session, - declared_role: options.declared_role.clone(), - host, - held_state_frame: None, - counter: 0, - renew: options.renew, - expire: options.expire, - seat: options.seat.clone(), - roster, - reader, - awareness: Awareness::new(peer_doc(options.awareness_client_id)), - awareness_seen: BTreeMap::new(), - outbound: VecDeque::new(), - held: BTreeSet::new(), - holds_sent: Vec::new(), - holds_announced_at: None, - leases: BTreeMap::new(), - departed: BTreeSet::new(), - announced_at: None, - unsent: Vec::new(), - baseline: None, - replica_epoch: 0, - reciprocal_served: BTreeSet::new(), - reciprocal_pending: BTreeSet::new(), - local_readiness_pending: false, - role_seen: None, - resync_from: None, - handshaken_at: None, - state_issued: None, - host_away_since: None, - published: 0, - handshake: 0, - frames: 0, - room_frames, - frame_budget: options.frame_budget.unwrap_or(FRAME_BUDGET), - applied: Vec::new(), - dropped: Vec::new(), - ignored: Vec::new(), - conflicts: Vec::new(), - ending: None, - mutation: None, - fault: None, - }; - if peer.host.is_some() { - // §13.1: a host's order is a peer's with one difference — it publishes a state at - // mint, so its own state may precede any it verifies. That state is also what - // commits its own connection's key, which is why a host has nothing to announce. - peer.publish_state(Duration::ZERO, HostReason::Mint); - } - let failed = peer.fault.take(); - if let Some(fault) = failed { - return Err(SealedError::new(fault)); - } - Ok(peer) - } - - // --- what a caller reads -------------------------------------------------- - - /// This connection's session public key, which the announcement names. - #[must_use] - pub fn session_key(&self) -> PublicKey { - self.session.public() - } - - /// The generation of the document this connection currently owns text in, for a caller that - /// watches the replica rather than its contents: it moves when §13.9's `viewer` resolution - /// replaces the replica, which is the one state-driven way text can change without a content - /// frame. Comparing it is how the relay reports that change without reading any text. - #[must_use] - pub const fn replica_epoch(&self) -> u64 { - self.replica_epoch - } - - /// This connection's own seat, as a caller that needs to show it reads it. - #[must_use] - pub fn seat(&self) -> Option<&str> { - self.seat.as_deref() - } - - /// Whether a verified room state has been applied, which §13.3's waiting rules turn on. - #[must_use] - pub const fn state_held(&self) -> bool { - self.state_issued.is_some() - } - - /// Whether this connection holds the host key, which is the whole of what being the host is - /// in this version (§7.1). - #[must_use] - pub const fn is_host(&self) -> bool { - self.host.is_some() - } - - /// The awareness client id this connection announced, which is the one its replica speaks - /// under (§8.4): the id the room records for this seat, so a peer's caret is attributed to - /// the seat that published it. - #[must_use] - pub fn awareness_client_id(&self) -> u64 { - self.awareness.client_id().get() - } - - /// The awareness client ids this replica holds a state for, ascending: the ones a peer - /// published and nothing has removed since. - #[must_use] - pub fn awareness_clients(&self) -> Vec { - let mut ids: Vec = self - .awareness - .iter() - .filter(|(_, state)| state.data.is_some()) - .map(|(id, _)| id.get()) - .collect(); - ids.sort_unstable(); - ids - } - - /// The role the applied state gives this connection's own key (§13.4), or `None` while no - /// state commits it — the state is the only source of a role in this version. - #[must_use] - pub fn own_role(&self) -> Option<&str> { - self.role() - } - - /// The seat the applied state's `host` entry labels, or `None` while no state names one - /// (§13.4: a client with none **MUST NOT** guess one). - #[must_use] - pub fn named_host_seat(&self) -> Option<&str> { - self.host_seat() - } - - /// The roles the applied state assigns, by the seat each committed key is labelled. - #[must_use] - pub fn roles_by_seat(&self) -> BTreeMap { - self.reader - .committed - .values() - .map(|peer| (peer.peer_id.clone(), peer.role.clone())) - .collect() - } - - /// The edition of the last state this connection published, or `0` before it has published - /// one. This is §7.1's `issued` series, which a host that keeps hosting continues. - #[must_use] - pub fn published_issued(&self) -> u64 { - self.host.as_ref().map_or(0, HostProducer::published_issued) - } - - /// The edition of the state this client holds, or `None` before one is applied. - #[must_use] - pub const fn state_issued(&self) -> Option { - self.state_issued - } - - /// The listing of the last state applied, with §5's refused paths dropped. - #[must_use] - pub fn listing(&self) -> &[String] { - &self.reader.listing - } - - /// How many frames this client **published** under §13's rules (§13.11). - #[must_use] - pub const fn published(&self) -> u64 { - self.published - } - - /// How many §7 handshake frames it sent, counted apart from its publications. - #[must_use] - pub const fn handshake(&self) -> u64 { - self.handshake - } - - #[must_use] - pub const fn frames(&self) -> u64 { - self.frames - } - - #[must_use] - pub fn applied(&self) -> &[Applied] { - &self.applied - } - - #[must_use] - pub fn dropped(&self) -> &[Dropped] { - &self.dropped - } - - /// The frames that verified and applied nothing, by the index they were handed as. - #[must_use] - pub fn ignored(&self) -> &[u64] { - &self.ignored - } - - /// The frames refused as a second publication at an edition this client already holds - /// (§13.3), by the index they were handed as. They are in `dropped` too, with the reason - /// `stale_issued`: §13.3 keeps the reason and asks for the divergence to be visible beside - /// it, because two receivers can hold different listings at one edition and nothing on the - /// wire says which of the two is the host's latest. - #[must_use] - pub fn conflicts(&self) -> &[u64] { - &self.conflicts - } - - /// Why the session ended, if it has. - #[must_use] - pub const fn ending(&self) -> Option { - self.ending - } - - #[must_use] - pub fn mutation(&self) -> Option<&str> { - self.mutation.as_deref() - } - - /// The first frame this session could not produce, if any. A driver reads it and fails - /// loudly: publishing fails silently otherwise, and a subject that publishes nothing looks - /// like a client with nothing to say. - #[must_use] - pub fn fault(&self) -> Option<&str> { - self.fault.as_deref() - } - - /// The paths this client has open: what its own holds message carries. - #[must_use] - pub const fn held(&self) -> &BTreeSet { - &self.held - } - - /// What each peer is held to, by the key's canonical spelling where the applied state - /// names it and by its id where nothing does (§13.4). A key whose lease has lapsed is not - /// here at all: §13.7 has the receiver forget the whole set. - #[must_use] - pub fn peer_holds(&self) -> BTreeMap> { - self.reader - .holds - .iter() - .map(|(id, paths)| (self.spelling(*id), paths.clone())) - .collect() - } - - /// The length of a document's text in UTF-16 code units, the unit yjs, every editor's - /// `offsetAt` and every peer on the wire count an offset in (`PROTOCOL.md` §8.1). - #[must_use] - pub fn length(&self, path: &str) -> u32 { - let doc = self.awareness.doc(); - let text = doc.get_or_insert_text(path); - text.len(&doc.transact()) - } - - /// The text this replica holds at a path, which is what a decision vector reads. - #[must_use] - pub fn text(&self, path: &str) -> String { - let doc = self.awareness.doc(); - let text = doc.get_or_insert_text(path); - text.get_string(&doc.transact()) - } - - /// The CRDT state vector, as `(client id, clock)` pairs: what a sync handshake exchanges, - /// and what two fully synced replicas agree on. - #[must_use] - pub fn state_vector(&self) -> Vec<(u64, u32)> { - let doc = self.publication_doc(); - let txn = doc.transact(); - let mut entries: Vec<(u64, u32)> = txn - .state_vector() - .iter() - .map(|(client, clock)| (client.get(), *clock)) - .collect(); - entries.sort_unstable(); - entries - } - - /// The paths this replica holds any text for: the documents that have arrived. - #[must_use] - pub fn documents(&self) -> Vec { - let doc = self.awareness.doc(); - let txn = doc.transact(); - let mut paths: Vec = txn - .root_refs() - .filter(|(name, _)| txn.get_text(*name).is_some()) - .map(|(name, _)| name.to_string()) - .collect(); - paths.sort(); - paths - } - - // --- what the caller hands in --------------------------------------------- - - /// One sealed frame, as the relay delivered it. - pub fn deliver(&mut self, clock: Duration, frame: &[u8]) -> Outcome { - self.frames = self.frames.saturating_add(1); - self.count_frame(); - let index = self.frames.saturating_sub(1); - // A closing folds into the receiver the moment it verifies, and §13.10 ignores one - // handed to a client holding no state. The two values it moved are put back, because - // `issued` is an order between two states and this receiver has none to compare one - // with: vector 155 delivers a closing at edition 2 and then a state at 1, and the - // state must still be the first edition this client holds. - let issued = self.reader.issued; - let ended = self.reader.ended; - let verdict = self.reader.read(frame); - if !verdict.ok { - self.note_refusal(clock, &verdict); - return self.refuse(index, &verdict); - } - let kind = verdict.kind.unwrap_or_default(); - if matches!(verdict.payload, Some(Payload::RoomState(_))) { - // §7.1: what a peer re-sends when it sees a `peer.joined` is the bytes it received, - // and those are the ones that verified. - self.held_state_frame = Some(frame.to_vec()); - } - if self.ignores(&verdict) { - self.reader.issued = issued; - self.reader.ended = ended; - self.ignored.push(index); - return Outcome::Ignored { kind }; - } - self.fold(clock, &verdict); - self.applied.push(Applied { frame: index, kind }); - Outcome::Applied { kind } - } - - /// The clocks, on the caller's tick: §13.7's renewal and expiry, §8.2's awareness expiry, - /// §13.8's host-away window and §13.3's no-state window. - /// - /// The announcement of §13.1's step 4 goes out here too, at the first tick and whenever a - /// state has not committed this key since — so a driver has one path to publish it and - /// nothing has to remember to call it at the join. - pub fn tick(&mut self, clock: Duration) { - if let Some(host) = self.host.as_mut() { - host.flush_frames(clock); - } - self.expire_leases(clock); - self.expire_awareness(clock); - self.refresh_host_away(clock, false); - if self.ending.is_some() { - return; - } - if self.budget_spent() { - return; - } - if self.window_passed(clock) { - return; - } - self.publish_state(clock, HostReason::Announcement); - self.reannounce(clock); - self.resync(clock); - self.announce_holds(clock); - } - - /// Takes what this session has published, in the order it published it. - pub fn take_outbound(&mut self) -> Vec> { - self.outbound.drain(..).collect() - } - - // --- the guard a census removes ------------------------------------------- - - /// Removes one of `PROTOCOL.md` §13.11's client guards, for the corpus's mutation census. - /// - /// # Errors - /// - /// Returns an error naming the guard when nothing here removes it: a subject that cannot - /// take a mutation must say so rather than pass the census silently. - pub fn mutate(&mut self, name: &str) -> Result<(), SealedError> { - match name { - "ignore-roles" => self.reader.mutations.remove(Guard::Roles), - "ignore-issued" => self.reader.mutations.remove(Guard::Issued), - "announce-once" | "no-lease" | "any-closing" | "wait-for-ever" => {} - other => { - return Err(SealedError::new(format!( - "no mutation is named {other:?}" - ))); - } - } - self.mutation = Some(name.to_string()); - Ok(()) - } - - fn mutating(&self, name: &str) -> bool { - self.mutation.as_deref() == Some(name) - } -} - -/// The host's producer half for a session handed the host key (§7.1). -/// -/// §7.1's own entry labels this connection's seat, and a state whose `host` entry labels no seat -/// of the roster leaves every peer with no identified host connection at all (§13.4), so a host -/// session needs the seat the handshake gave it. -#[expect( - clippy::too_many_arguments, - reason = "the session's options, its frame key, the host's own and the key it signs with" -)] -fn host_producer( - options: &PeerOptions, - frame_key: FrameKey, - host_options: &HostOptions, - own_key: PublicKey, -) -> Result { - let Some(seat) = options.seat.as_deref() else { - return Err(SealedError::new(HOST_NEEDS_SEAT)); - }; - HostProducer::new( - &options.room_id, - frame_key, - options.renew, - host_options, - seat, - own_key, - ) -} - -/// The session document §7 fixes: one `Y.Doc`, one `Y.Text` per document. -/// -/// A text offset is a UTF-16 code unit, which is what `yjs`, every editor's `offsetAt` and -/// every peer on the wire use (`PROTOCOL.md` §8.1); `yrs` defaults to UTF-8 byte offsets. -/// -/// `awareness_client_id` is the id the handshake announced (§8.4): y-protocols seeds one of its -/// own, and a session that published under a second id would have every peer draw this client's -/// caret under a stranger's. `ClientID` is a 53-bit value, which is the width every id on this -/// wire is read in. -fn peer_doc(awareness_client_id: Option) -> Doc { - const YJS_ID_BITS: u64 = 53; - let client_id = awareness_client_id.map_or_else(ClientID::random, |id| { - ClientID::new(id & ((1u64 << YJS_ID_BITS) - 1)) - }); - Doc::with_options(Options { - offset_kind: OffsetKind::Utf16, - client_id, - ..Options::default() - }) -} - -/// One y-protocols message as a `kind = 0` plaintext. -fn encode_y_message(message: &YMessage) -> Vec { - let mut encoder = EncoderV1::new(); - message.encode(&mut encoder); - encoder.to_vec() -} - -/// Whether a `kind = 0` plaintext carries document content: a sync `Update` or `SyncStep2`, as -/// opposed to the `SyncStep1` of §13.1's step 6, which shares the envelope's kind. -/// -/// §13.5: content is a writer's to publish, and a `viewer` answers a request with nothing. -fn is_content(plaintext: &[u8]) -> bool { - plaintext.first() == Some(&0) - && read_varuint(plaintext, 1).is_ok_and(|(tag, _)| tag == 1 || tag == 2) -} - -/// A JSON value's canonical bytes. `CANONICAL.md` §2 writes an object with its members -/// ascending, which `serde_json`'s own map does (it is a `BTreeMap`). -/// -/// The values this is handed are objects of strings and arrays of strings, and encoding one -/// cannot fail; an empty plaintext would be a frame no peer reads, which is `bad_payload` at -/// every receiver and a sender's bug here. -fn canonical(value: &Value) -> Vec { - serde_json::to_vec(value).unwrap_or_default() -} - -impl Ending { - /// The words a client says when it ends a session (§13.10 requires it to say why). - #[must_use] - pub const fn as_str(self) -> &'static str { - match self { - Self::Closing => "the room closed", - Self::HostAway => "the host has been away past its window", - Self::NoState => "no state arrived within the no-state window", - Self::FrameBudget => { - "the room has sealed as many frames as its key allows; start a new room" - } - } - } -} - -// --- the rules, in the order §13 states them ------------------------------------ - -impl PeerSession { - /// §13.6: a refused *content* frame opens an interval this client re-syncs in. The - /// envelope's `kind` is readable before any signature is verified, so that is a claim about - /// the bytes and not about the reason the frame was refused. - fn note_refusal(&mut self, clock: Duration, verdict: &Verdict) { - if verdict.kind == Some(0) { - let _ = self.resync_from.get_or_insert(clock); - } - } - - /// One refused frame: §13.2's local report, which is never sent anywhere. - fn refuse(&mut self, frame: u64, verdict: &Verdict) -> Outcome { - // §13.3: the reason stays `stale_issued` for a second state at one edition and for an - // older one alike, and this index is the local annotation beside it that says which of - // the two the frame was. - if verdict.conflict { - self.conflicts.push(frame); - } - // Every refusal carries the step that refused it; one without a reason would be a bug - // in the byte layer and not a decision to report. - let named = verdict - .reason - .clone() - .unwrap_or_else(|| "bad_envelope".to_string()); - self.dropped.push(Dropped { - frame, - reason: named.clone(), - }); - Outcome::Dropped { reason: named } - } - - /// Whether §13.10 has this frame ignored rather than applied. - fn ignores(&self, verdict: &Verdict) -> bool { - matches!(verdict.payload, Some(Payload::Closing(_))) - && !self.state_held() - && !self.mutating("any-closing") - } - - /// Folds an applied frame into the session: §13.3's state, §13.7's lease, §13.10's - /// closing, the announcement a host answers, and the content a `kind = 0` frame carries. - fn fold(&mut self, clock: Duration, verdict: &Verdict) { - match verdict.payload.as_ref() { - Some(Payload::RoomState(state)) => { - self.after_state(clock, state.issued); - } - Some(Payload::Closing(_)) => self.ending = Some(Ending::Closing), - Some(Payload::Holds(_)) => self.renew_lease(clock, verdict.sender), - Some(Payload::Content) => { - self.apply_content(clock, &verdict.plaintext, verdict.verified); - } - Some(Payload::Announcement(announcement)) => { - self.hear_announcement(clock, announcement); - } - None => {} - } - } - - /// §7.1: a session-key announcement the receiver accepted. - /// - /// A peer that is not the host owes it nothing at all — the state is the only source of - /// the keys a receiver keeps, and an announcement is read for the host's sake (§13.3) — so - /// the host's answer is the whole of what this decision is. - fn hear_announcement( - &mut self, - clock: Duration, - announcement: &Announcement, - ) { - if self.host.is_none() { - return; - } - let Some(key) = PublicKey::parse(&announcement.key) else { - return; - }; - let declared = announcement.role.as_deref(); - if let Some(host) = self.host.as_mut() { - host.announcement(key, declared); - } - self.publish_state(clock, HostReason::Announcement); - } - - /// The state §7.1 has this host publish now, if it is due: sealed by the host key, counted - /// as a publication, and folded into this session's own receiver. - /// - /// A host never receives the state it writes — the relay sends a frame to the room's - /// *other* connections — so the receiver is folded from the value rather than from the - /// bytes, and before anything that follows the frame (`after_state`) so that a `SyncStep1` - /// goes out only once a state commits this connection's key (§13.1's steps 4 and 6). - fn publish_state(&mut self, clock: Duration, reason: HostReason) { - if self.room_frames >= self.frame_budget { - return; - } - let Some(host) = self.host.as_mut() else { - return; - }; - let owed = host.publish(clock, reason); - if let Some(fault) = host.failure() { - let _ = self.fault.get_or_insert_with(|| fault.to_string()); - } - let Some(publication) = owed else { - return; - }; - if publication.fresh { - self.count_frame(); - } - self.outbound.push_back(publication.frame); - self.published = self.published.saturating_add(1); - let fresh = publication.state.as_ref().filter(|_| publication.fresh); - let Some(state) = fresh else { - return; - }; - self.reader.apply_own(state); - self.after_state(clock, publication.issued); - } - - /// One frame this connection did not author, put on the wire as the bytes it arrived as: - /// §7.1's re-send of a state the room holds, when a peer is seated. A frame at the edition - /// every peer already holds is refused `stale_issued` and changes nothing; the one this - /// re-send is for is the peer that holds none. - fn republish(&mut self, frame: &[u8]) { - if self.ending.is_some() { - return; - } - self.outbound.push_back(frame.to_vec()); - self.published = self.published.saturating_add(1); - } - - /// What §13.3, §13.1's step 6 and §13.7 owe an applied room state. - fn after_state(&mut self, clock: Duration, issued: u64) { - self.state_issued = Some(issued); - if let Some(host) = self.host.as_mut() { - // §7.1: a host that has verified a state keeps its own series above it. - host.verified_state(issued); - } - self.refresh_host_away(clock, true); - self.drop_departed_holds(); - // §13.6: the applied state is the room's writer set, so a revoked or demoted key's - // reciprocal accounting goes with its eligibility and a later promotion may arm again. - self.prune_reciprocal(); - let role = self.role().map(String::from); - self.note_local_eligibility(role.as_deref()); - self.role_seen = role; - // §13.1's steps 6 and 4: a state that commits this key is where the handshake belongs, - // and one that does not is what a re-announcement is for — the renewal clock alone would - // wait a whole window for it. - if self.commits_ours() { - self.resolve_speculation(); - self.handshake_once(clock); - self.flush_held_back(); - } else { - self.announce(clock); - } - // §13.7: a holder's *first* holds message waits for the state that commits its key, so - // one that was open when that state landed announces here rather than a renewal late. - // Nothing goes out for a session that holds nothing and has said nothing, and nothing - // goes out until the key is committed — that test is `announce_holds`' own. - self.announce_holds(clock); - } - - /// §13.2 and §13.3: a `kind = 0` plaintext, applied to the session document and answered. - /// An awareness message inside it is stamped on `clock`, the session's own, for §8.2. - #[expect( - clippy::too_many_arguments, - reason = "the frame, the clock it is read on, the verified key and the replica are the whole of a content frame" - )] - fn apply_content( - &mut self, - clock: Duration, - plaintext: &[u8], - verified: Option, - ) { - if !self.state_held() { - return; - } - // §13.9: a `viewer` publishes its SyncStep1, its awareness and its holds, and nothing - // else — a SyncStep2 is document content (§13.5) and is not its to send. An uncommitted - // key is the same: nothing it would answer with is publishable yet. The request is still - // recognised and the rest of the frame still applies. - let answers = self.may_publish() && self.is_writer(); - // §13.9: while a speculative edit is held, the readiness and replies a peer draws must - // be computed from the clean replica and not the one carrying the speculation. - let publication = self.publication_doc().clone(); - let (replies, requested) = - self.read_stream(clock, plaintext, &publication, answers); - if self.baseline.is_some() { - // Keep the ordinary replica's local view current without computing a second reply. - let ordinary = self.awareness.doc().clone(); - let _ = self.read_stream(clock, plaintext, &ordinary, false); - } - if requested && let Some(key) = verified { - self.arm_reciprocal(key); - } - if !answers { - return; - } - for reply in replies { - let bytes = encode_y_message(&reply); - self.publish(Published::Sync, &bytes); - } - } - - /// §7's stream, read message by message and applied as it is read, with the replies it - /// owes. A message that cannot be read or applied ends the reading, and the messages - /// before it stand: a stream no replica decodes is a sender's bug, and the session goes on. - #[expect( - clippy::too_many_arguments, - reason = "the frame, the replica it is applied to and whether it may be answered are the whole of a read" - )] - fn read_stream( - &mut self, - clock: Duration, - plaintext: &[u8], - doc: &Doc, - answer: bool, - ) -> (Vec, bool) { - let mut decoder = DecoderV1::from(plaintext); - let mut state = ReadState::default(); - let _ = MessageReader::new(&mut decoder).map_while(Result::ok).all( - |message| { - self.read_message(clock, message, doc, answer, &mut state) - }, - ); - (state.replies, state.requested) - } - - /// One message of the stream. Returns whether the reading goes on. - /// - /// §8.3: an auth message is read and ignored, a denial included, and an awareness query - /// is dropped rather than answered. A `SyncStep1` is answered once per frame - /// ([`MAX_REPLIES_PER_FRAME`]), and a message type §7 does not define ends the reading. - #[expect( - clippy::too_many_arguments, - reason = "one message, its target replica, whether it may be answered and the read it accumulates into" - )] - fn read_message( - &mut self, - clock: Duration, - message: YMessage, - doc: &Doc, - answer: bool, - state: &mut ReadState, - ) -> bool { - match message { - YMessage::Sync(SyncMessage::SyncStep1(vector)) => { - // §13.6: the request is read and past whatever the reply cap or the role does - // with it, so a caller still sees the obligation a `viewer` or an uncommitted - // key may not answer. The inner state vector was decoded by the reader already, - // so a malformed one never reaches here and neither arms nor consumes anything. - state.requested = true; - Self::answer(doc, answer, &vector, &mut state.replies); - true - } - YMessage::Sync( - SyncMessage::SyncStep2(bytes) | SyncMessage::Update(bytes), - ) => Self::apply_update(doc, &bytes), - YMessage::Awareness(update) => self.apply_awareness(clock, update), - YMessage::Auth(_) | YMessage::AwarenessQuery => true, - YMessage::Custom(..) => false, - } - } - - /// §7: a `SyncStep1` is answered with the `SyncStep2` its state vector asks for, while the - /// frame has answers left and the caller permits one. `answer` is the §13.9 gate: a - /// `viewer` or an uncommitted key reads and drops the request instead of computing a diff. - #[expect( - clippy::too_many_arguments, - reason = "the replica, whether a reply is permitted, the vector and the replies are one answer" - )] - fn answer( - doc: &Doc, - permitted: bool, - vector: &StateVector, - replies: &mut Vec, - ) { - if !permitted || replies.len() >= MAX_REPLIES_PER_FRAME { - return; - } - let txn = doc.transact(); - let diff = txn.encode_state_as_update_v1(vector); - replies.push(YMessage::Sync(SyncMessage::SyncStep2(diff))); - } - - /// One update applied to the chosen replica. Returns whether it was read and applied. - /// - /// The reader has already refused a frame holding an update nested past the bound, and - /// this decode is bounded too, so no path hands `yrs` one to recurse into. - fn apply_update(doc: &Doc, bytes: &[u8]) -> bool { - let Ok(update) = decode_update(bytes) else { - return false; - }; - let mut txn = doc.transact_mut(); - txn.apply_update(update).is_ok() - } - - /// §8.2: one awareness message, applied by its own clocks and stamped on this session's - /// clock for each id it actually applied. Returns whether it was read, which is the same - /// answer [`Awareness::apply_update`] gives. - /// - /// The stamp is the applied ids and not the message's: an entry whose clock is not above - /// the one this replica already holds for that id is ignored by y-protocols and renews - /// nothing, so a peer that stops publishing is forgotten while a stale copy of its last - /// state is still arriving. - /// - /// An entry whose clock is [`u32::MAX`] is refused rather than applied, and the rest of the - /// message is applied as usual. `yrs` steps a clock by one without checking in two places - /// this path reaches — applying §8.2's removal for the id this connection announced - /// (`Awareness::apply_update_internal`), and dropping a state the room is done with - /// (`Awareness::remove_state`, reached by §8.2's expiry and §8.4's departure) — and a clock - /// is the sender's to choose, so the one value that cannot be stepped never enters: no state - /// at the maximum is held, and no removal can step one that is. - fn apply_awareness( - &mut self, - clock: Duration, - mut update: AwarenessUpdate, - ) -> bool { - update.clients.retain(|_, entry| entry.clock != u32::MAX); - let Ok(summary) = self.awareness.apply_update_summary(update) else { - return false; - }; - if let Some(applied) = summary { - self.stamp_awareness(&applied, clock); - } - true - } - - /// §8.2: the local clock an awareness update's applied ids were last seen at. A removed id - /// is dropped from the bookkeeping with its state, so the expiry tick never steps a - /// tombstone a second time. - fn stamp_awareness( - &mut self, - summary: &AwarenessUpdateSummary, - clock: Duration, - ) { - let own = self.awareness.client_id(); - let applied = summary - .added - .iter() - .chain(summary.updated.iter()) - .copied() - .filter(|id| *id != own); - for id in applied { - let _ = self.awareness_seen.insert(id, clock); - } - for id in &summary.removed { - let _ = self.awareness_seen.remove(id); - } - } - - /// §13.7: only an accepted holds message renews a lease, and nothing else from the same - /// peer does. - fn renew_lease(&mut self, clock: Duration, sender: Option) { - if let Some(id) = sender { - let _ = self.leases.insert(id, clock); - } - } - - /// Whether an applied state commits this connection's own session key. - fn commits_ours(&self) -> bool { - self.reader - .committed - .values() - .any(|peer| peer.key == self.session.public()) - } - - /// The role the applied state gives this connection's own key (§13.4). - fn role(&self) -> Option<&str> { - self.reader.role_of_key(self.session.public()) - } - - /// Whether §13.1's step 4 lets this client publish anything but its announcement. - /// - /// §13.10: a session that has ended publishes nothing, whichever ending reached it, so - /// the ending is checked here rather than at each caller. - fn may_publish(&self) -> bool { - self.ending.is_none() && self.state_held() && self.commits_ours() - } - - /// §13.6: whether the applied state begins a new continuous writer eligibility for this - /// connection's own key, which owes one coalesced readiness request. - /// - /// An already-handshaken key that re-enters writer eligibility — a `viewer` promotion or an - /// absent interval — owes one. The first commitment owes §13.1's immediate initial request - /// instead, which `handshake_once` sends, and an uninterrupted eligibility owes nothing. - /// Eligibility ending before the request is queued retires it, leaving unrelated remote - /// reciprocal and refusal obligations alone. - fn note_local_eligibility(&mut self, role: Option<&str>) { - if !matches!(role, Some("host" | "guest")) { - self.local_readiness_pending = false; - return; - } - if self.handshaken_at.is_some() - && !matches!(self.role_seen.as_deref(), Some("host" | "guest")) - { - self.local_readiness_pending = true; - } - } - - /// §13.9: resolves UNKNOWN-role history before any request or reply is encoded, so a `viewer` - /// resolution never exports the speculation and a writer never answers from it. A writer - /// adopts it as room history; a `viewer` discards it outright. - fn resolve_speculation(&mut self) { - if self.role() == Some("viewer") { - self.discard_speculative(); - } else if self.is_writer() { - self.accept_speculation(); - } - } - - /// Whether the applied state gives this connection's own key a publishing role (§13.4). - fn is_writer(&self) -> bool { - matches!(self.role(), Some("host" | "guest")) - } - - /// Whether the applied state commits `key` as a writer (§13.6's eligibility). - fn is_writer_key(&self, key: PublicKey) -> bool { - matches!(self.reader.role_of_key(key), Some("host" | "guest")) - } - - /// The replica publication is built from: the clean baseline while a speculative edit is - /// held, and this connection's own document otherwise (§13.9). - fn publication_doc(&self) -> &Doc { - self.baseline - .as_ref() - .unwrap_or_else(|| self.awareness.doc()) - } - - /// §13.6: arms one reciprocal request for the first accepted `SyncStep1` from a continuously - /// committed writer key. - /// - /// The identity is the full key whose signature verified, never its id (§6.1). A request - /// from a `viewer` is not one — a viewer sends no content, so reciprocating would solicit - /// nothing — and a key already served keeps its mark until its eligibility ends, which is - /// what stops the request from echoing for ever between two peers. - /// - /// Activation is the **remote** writer's eligibility and nothing local: a connection that is - /// itself uncommitted, or committed only as a `viewer`, still records the obligation, and the - /// publication gate withholds the request until it may publish. Gating activation on local - /// commitment would drop the obligation outright, which is not a delay. - fn arm_reciprocal(&mut self, verified: PublicKey) { - if !self.is_writer_key(verified) { - return; - } - if self.reciprocal_served.insert(verified) { - let _ = self.reciprocal_pending.insert(verified); - } - } - - /// §13.6: retires the reciprocal accounting for keys the applied state no longer commits as - /// writers, so a later promotion of one may arm once more while a continuously committed key - /// keeps its served mark. - fn prune_reciprocal(&mut self) { - let writers: BTreeSet = self - .reader - .committed - .values() - .filter(|peer| peer.role == "host" || peer.role == "guest") - .map(|peer| peer.key) - .collect(); - self.reciprocal_served.retain(|key| writers.contains(key)); - self.reciprocal_pending.retain(|key| writers.contains(key)); - } - - /// §13.9: captures a clean replica before the first UNKNOWN-role local mutation, so a later - /// `viewer` resolution can adopt history without the speculation. - /// - /// A genuinely separate `Doc` built from an encoded update, never `Doc::clone` (which is a - /// handle to the same store). The whole-doc update carries every pending struct and the - /// delete set, so the baseline is faithful. - fn begin_speculation(&mut self) { - if self.baseline.is_some() { - return; - } - let baseline = peer_doc(Some(self.awareness.client_id().get())); - let whole = { - let txn = self.awareness.doc().transact(); - txn.encode_state_as_update_v1(&StateVector::default()) - }; - let Ok(update) = decode_update(&whole) else { - return; - }; - let mut txn = baseline.transact_mut(); - let _ = txn.apply_update(update); - drop(txn); - self.baseline = Some(baseline); - } - - /// §13.9: the speculative edits are room history after all — the state resolved the key as a - /// writer — so the clean baseline is dropped and the deltas are publishable. - fn accept_speculation(&mut self) { - self.baseline = None; - for entry in &mut self.unsent { - entry.speculative = false; - } - } - - /// §13.9: adopts the clean baseline in place of the replica that holds the speculative edits. - /// - /// The replica is replaced rather than inverse-deleted, so no tombstone or dependency from - /// the disallowed history survives. The remote awareness states and their clocks are carried - /// onto the new owner, and this connection's announced awareness id is unchanged. - fn discard_speculative(&mut self) { - self.unsent.retain(|entry| !entry.speculative); - let Some(next) = self.baseline.take() else { - return; - }; - // §8.2/§8.4: the removal clocks are as much a part of the inventory as the live states. - // `update()` would drop every tombstone, letting a stale entry resurrect a peer the room - // has forgotten, so the whole tracked set is carried by id — `update_with_clients` writes - // a removed id's clock with a null state — and reapplied, which preserves both. - let tracked: Vec = - self.awareness.iter().map(|(id, _)| id).collect(); - let inventory = self.awareness.update_with_clients(tracked); - let mut adopted = Awareness::new(next); - if let Ok(carried) = inventory { - let _ = adopted.apply_update(carried); - } - self.awareness = adopted; - self.replica_epoch = self.replica_epoch.saturating_add(1); - } - - /// §13.1's step 4: the session-key announcement, `kind = 4`, signed by the key it names. - fn announce(&mut self, clock: Duration) { - let mut members = serde_json::Map::new(); - let _ = members - .insert("key".to_string(), json!(self.session.public().encode())); - if let Some(role) = &self.declared_role { - let _ = members.insert("role".to_string(), json!(role)); - } - let plaintext = canonical(&Value::Object(members)); - self.publish(Published::Announcement, &plaintext); - self.announced_at = Some(clock); - } - - /// §13.1's step 4: re-announce on the session's renewal clock for as long as no applied - /// state commits this key, which is how an announcement the relay dropped is recovered. - fn reannounce(&mut self, clock: Duration) { - if self.commits_ours() || self.mutating("announce-once") { - return; - } - let due = match self.announced_at { - None => true, - Some(at) => clock.saturating_sub(at) >= self.renew, - }; - if due { - self.announce(clock); - } - } - - /// §13.7: the whole held set, renewed on the client's own clock and published at once - /// when it changes. Rising from the tick and from nothing a peer sends is what lets a - /// seated, idle peer keep its holds. - fn announce_holds(&mut self, clock: Duration) { - if !self.may_publish() { - // A `viewer` keeps its edit in its own replica and never publishes it (§13.9); - // everyone else's is held back by §13.1's step 4 and sent once a state commits this - // key. - return; - } - // A holder with nothing open and nothing yet said has no frame to send; one that has - // released everything says so, because the empty set is what §13.7 asks for. - if self.held.is_empty() - && self.holds_sent.is_empty() - && self.holds_announced_at.is_none() - { - return; - } - let paths: Vec = self.held.iter().cloned().collect(); - let due = paths != self.holds_sent - || match self.holds_announced_at { - None => true, - Some(at) => clock.saturating_sub(at) >= self.renew, - }; - if !due { - return; - } - let plaintext = canonical(&json!({"holds": &paths})); - self.publish(Published::Holds, &plaintext); - self.holds_sent = paths; - self.holds_announced_at = Some(clock); - } -} - -// --- the clocks, the seats and what leaves the session -------------------------- - -impl PeerSession { - /// §13.7's expiry: a peer's whole held set is forgotten once its lease has lapsed. - /// - /// The text has this checked on the renewal tick, and a client whose tick *is* its renewal - /// tick checks there; a tick that comes more often forgets sooner, which is inside the - /// `awareness_expire_ms + awareness_renew_ms` the text bounds the delay by and never - /// inside the `MUST forget ... after awareness_expire_ms` it states. An expiry is not a - /// refusal — no frame is dropped, the peer is not gone and nothing is reported anywhere — - /// which is why the only observable is the set becoming empty. - fn expire_leases(&mut self, clock: Duration) { - if self.mutating("no-lease") { - return; - } - let lapsed: Vec = self - .leases - .iter() - .filter(|(_, at)| clock.saturating_sub(**at) >= self.expire) - .map(|(id, _)| *id) - .collect(); - for id in lapsed { - let _ = self.leases.remove(&id); - let _ = self.reader.holds.remove(&id); - } - } - - /// §8.2's expiry, beside §13.7's: a remote awareness state whose last **applied** entry is - /// `awareness_expire_ms` old is forgotten. The renewal tick is where this is checked, so a - /// state is forgotten at the first tick after `last seen + awareness_expire_ms` and never - /// sooner, which is the `awareness_expire_ms + awareness_renew_ms` the text bounds it by. - /// - /// The removal is `yrs`'s own, which leaves the id a tombstone: a renewal at the clock the - /// dropped state carried and one at the clock above it are both ignored (`NOTES.md` §A.11), - /// and a renewal above both makes the peer visible again. An expiry is not a refusal and not - /// a departure — no frame is dropped, the peer is not gone — so the only observable is the - /// state going. - fn expire_awareness(&mut self, clock: Duration) { - let lapsed: Vec = self - .awareness_seen - .iter() - .filter(|(_, at)| clock.saturating_sub(**at) >= self.expire) - .map(|(id, _)| *id) - .collect(); - for id in lapsed { - let _ = self.awareness_seen.remove(&id); - self.awareness.remove_state(id); - } - } - - /// §13.8's host-away clock: armed while the applied state's `host` entry labels a seat - /// the roster does not have, disarmed when it labels one the roster has. `restart` is - /// what a new state does to a clock that is already running. - fn refresh_host_away(&mut self, clock: Duration, restart: bool) { - // §13.4: a state that names no `host` entry leaves this client with no identified - // host connection and it MUST NOT guess one, so there is nothing to arm a clock with. - let absent = self - .host_seat() - .is_some_and(|seat| !self.roster.contains(seat)); - if !absent { - self.host_away_since = None; - } else if restart || self.host_away_since.is_none() { - self.host_away_since = Some(clock); - } - } - - /// The seat the applied state's `host` entry labels, in the order §6.1 reads two `host` - /// keys: the one whose key comes first in UTF-16 code-unit order. - fn host_seat(&self) -> Option<&str> { - self.reader - .committed - .values() - .find(|peer| peer.role == "host") - .map(|peer| peer.peer_id.as_str()) - } - - /// §13.7: the roster is the authority on who is present, so a key whose entry labels a - /// seat that has left loses its holds at once rather than with its lease. A seat the - /// roster never knew is not this rule: it is left to its lease. - fn drop_departed_holds(&mut self) { - let gone: Vec = self - .reader - .committed - .values() - .filter(|peer| self.departed.contains(&peer.peer_id)) - .map(|peer| peer.key.id()) - .collect(); - for id in gone { - let _ = self.leases.remove(&id); - let _ = self.reader.holds.remove(&id); - } - } - - /// §13.3's no-state window and §13.8's host-away window, which run in sequence. - fn window_passed(&mut self, clock: Duration) -> bool { - if let Some(since) = self.host_away_since - && clock.saturating_sub(since) >= self.expire - { - self.ending = Some(Ending::HostAway); - return true; - } - if !self.state_held() - && !self.mutating("wait-for-ever") - && clock >= self.expire - { - self.ending = Some(Ending::NoState); - return true; - } - false - } - - /// §13.1's step 6's handshake, run when this connection's own key *becomes* committed and - /// not for every state that commits it: a host republishes its state on every `peer.joined` - /// and on every announcement it accepts, so a handshake per state would be a frame per - /// republish. - fn handshake_once(&mut self, clock: Duration) { - if self.handshaken_at.is_none() { - // §13.6: only an actual seal-and-queue discharges a request. A failed attempt is not - // a publication, so the clock is not moved and the next due tick retries it. - let _ = self.sync_step1(clock); - } - } - - /// §13.1's step 6: a `SyncStep1` with this replica's state vector, so the room can tell a - /// client that has been refusing frames from one that has been applying them. - /// - /// The vector is the publication replica's: §13.9 keeps a `viewer`'s own history out of it, - /// so the room is asked for what the room-safe history lacks. The shared clock and the - /// coalesced obligations move only when the frame was actually sealed and queued. - fn sync_step1(&mut self, clock: Duration) -> bool { - let vector = { - let txn = self.publication_doc().transact(); - txn.state_vector() - }; - let message = - encode_y_message(&YMessage::Sync(SyncMessage::SyncStep1(vector))); - if !self.publish(Published::Sync, &message) { - return false; - } - self.handshaken_at = Some(clock); - self.resync_from = None; - self.reciprocal_pending.clear(); - self.local_readiness_pending = false; - true - } - - /// §13.6: refusal, reciprocal and local readiness obligations share one clock — at most one - /// locally generated `SyncStep1` per renewal interval, measured from the last request - /// actually sealed and queued, whichever obligation asked for it. The initial request is - /// always due; an obligation too early to send is retained and served at the first due tick. - fn resync(&mut self, clock: Duration) { - if !self.may_publish() { - return; - } - let Some(at) = self.handshaken_at else { - let _ = self.sync_step1(clock); - return; - }; - if self.resync_from.is_none() - && self.reciprocal_pending.is_empty() - && !self.local_readiness_pending - { - return; - } - if clock.saturating_sub(at) >= self.renew { - let _ = self.sync_step1(clock); - } - } - - /// One frame sealed under the frame key and signed by this connection's session key. - /// - /// Returns whether the frame was sealed and put on this session's own outbound queue: the - /// §13.6 clock moves on that and never on an attempt. The socket's own queue is the relay's - /// ([`crate::relay`]), so a successful seal is not a claim of delivery. - fn publish(&mut self, what: Published, plaintext: &[u8]) -> bool { - if !self.may_queue(what, plaintext) - || self.room_frames >= self.frame_budget - { - return false; - } - let Ok(bytes) = self.sealed_frame(what.kind(), plaintext) else { - // A CSPRNG that will not read, or an AEAD that refuses its own inputs. Neither - // happens in practice, and a session that kept quiet about one would look like a - // client with nothing to say. - self.fault = Some(format!("a {what:?} frame could not be sealed")); - return false; - }; - self.count_frame(); - self.outbound.push_back(bytes); - let tally = match what.counted() { - Counted::Publication => &mut self.published, - Counted::Handshake => &mut self.handshake, - }; - *tally = tally.saturating_add(1); - true - } - - /// §13.6's publication gates, checked at the moment of queueing: an ended session publishes - /// nothing, a key no state commits publishes only its announcement, and document content is - /// a writer's alone (§13.5). The announcement keeps its deliberate precommit exception. - fn may_queue(&self, what: Published, plaintext: &[u8]) -> bool { - if self.ending.is_some() { - return false; - } - what == Published::Announcement - || (self.may_publish() - && (!is_content(plaintext) || self.is_writer())) - } - - fn sealed_frame( - &mut self, - kind: u64, - plaintext: &[u8], - ) -> Result, SealedError> { - self.counter = self.counter.saturating_add(1); - let nonce = fresh_nonce()?; - let recipe = Recipe { - room_id: &self.room_id, - frame_key: &self.frame_key, - kind, - epoch: 0, - counter: self.counter, - nonce, - signer: &self.session, - }; - Ok(seal(&recipe, plaintext)?.bytes()) - } - - /// The canonical spelling of a key id where an applied state names one, and its id where - /// nothing does (§13.4). - fn spelling(&self, id: KeyId) -> String { - self.reader - .committed - .values() - .find(|peer| peer.key.id() == id) - .map_or_else(|| id.hex(), |peer| peer.key.encode()) - } -} - -// --- what a driver hands in ----------------------------------------------------- - -impl PeerSession { - /// A seat has joined, from `peer.joined`. - /// - /// §7.1 obliges a host to publish a state on it — which is how the joiner learns the - /// listing and the roles without asking — and asks any peer that holds a verified state to - /// re-send that state unchanged, so a joiner's state arrives while the host is away. §13.7 - /// has a holder re-announce its holds on the same event. - pub fn seat_joined(&mut self, clock: Duration, seat: &str) { - if let Some(host) = self.host.as_mut() { - host.seat_joined(seat); - } - let _ = self.departed.remove(seat); - let _ = self.roster.insert(seat.to_string()); - // §13.7: a hold is re-announced when a peer is seated, so a joiner learns the room's - // held set without asking for it — on the event itself rather than at the next renewal, - // which is a whole window the joiner would spend holding nothing from this peer. The - // state goes first: a holds message resolves against the keys the applied state commits - // (§13.4), so a joiner that has applied no state yet refuses it `uncommitted_key`. - self.holds_announced_at = None; - if self.host.is_some() { - self.publish_state(clock, HostReason::Roster); - self.announce_holds(clock); - return; - } - // §7.1: the re-send is for a room whose host is away — a joiner the host cannot answer, - // or a returning host that lost its `issued`. While the seat the `host` entry labels is - // seated, the host's own fresh state answers this join, and a copy from every peer would - // put the whole listing on every connection once per seated peer. - let host_away = self - .host_seat() - .is_none_or(|host_seat| !self.roster.contains(host_seat)); - if host_away && let Some(frame) = self.held_state_frame.clone() { - self.republish(&frame); - } - self.announce_holds(clock); - } - - /// A seat has left, from `peer.left`: §13.8's clock can arm on it and §13.7's holds go. - pub fn seat_left(&mut self, clock: Duration, seat: &str) { - if let Some(host) = self.host.as_mut() { - host.seat_left(seat); - } - let _ = self.roster.remove(seat); - let _ = self.departed.insert(seat.to_string()); - self.drop_departed_holds(); - self.refresh_host_away(clock, false); - if self.host.is_some() { - self.publish_state(clock, HostReason::Roster); - } - } - - /// Drops the awareness state published under `client_id`, which §8.4 asks for when the - /// peer that last claimed the id has left and no seated peer still claims it. The caller - /// holds the claims (the roster's `PeerInfo`), so it is the caller that decides which id. - /// - /// The state is removed the way y-protocols removes one, with its clock moved past the - /// last one seen, so a stale copy still in flight does not bring it back. This - /// connection's own id is never dropped, and an id with no state is left as it is. - pub fn forget_awareness(&mut self, client_id: u64) { - let id = ClientID::new(client_id); - // §8.4's drop and §8.2's expiry are the same bookkeeping: with the state gone there is - // nothing left for the expiry tick to notice, and stepping the tombstone twice would - // swallow one more renewal from the same id. - let _ = self.awareness_seen.remove(&id); - let held = self - .awareness - .iter() - .any(|(client, state)| client == id && state.data.is_some()); - if held && id != self.awareness.client_id() { - self.awareness.remove_state(id); - } - } - - /// The host's listing changed, from whatever watches its working tree (§7.1). - /// - /// A listing is replaced wholesale by every state, so this is the one thing a host's - /// adapter has to say about it: the state that follows names the whole tree as it now is, - /// and a shorter listing is a smaller working tree rather than a partial update (§13.3). - pub fn listing_changed(&mut self, clock: Duration) { - self.publish_state(clock, HostReason::Listing); - } - - /// §7.1's closing: the host's statement that the room is over, above every state it - /// published. - /// - /// A host that publishes one stops publishing; every peer that already holds a verified - /// state below its `issued` applies it and ends, and §9's room dies when its last - /// connection ends. The session that published it ends with them, which is what §13.10 - /// gives a receiver that applies one and what keeps a host from publishing content into a - /// room it has just declared over. - pub fn close_room(&mut self) -> bool { - let Some(host) = self.host.as_mut() else { - return false; - }; - let closing = host.closing(); - let failure = host.failure().map(ToString::to_string); - let failed = failure.unwrap_or_else(|| CLOSING_UNSEALED.to_string()); - let Some(publication) = closing else { - self.fault.get_or_insert(failed); - return false; - }; - self.count_frame(); - if let Some(host) = self.host.as_mut() { - host.save_frames(); - } - self.outbound.push_back(publication.frame); - self.published = self.published.saturating_add(1); - self.ending = Some(Ending::Closing); - true - } - - /// `CANONICAL.md` §6.1's frame budget: once the room's count reaches it, nothing more is - /// sealed under the frame key. A host publishes its one closing first — the frame that ends - /// the room for every peer holding its state — and every session, the host's included, ends - /// and says why. - /// One more frame against the room's count, handed to the host's producer to persist. - const fn count_frame(&mut self) { - self.room_frames = self.room_frames.saturating_add(1); - if let Some(host) = self.host.as_mut() { - host.count_frames(self.room_frames); - } - } - - fn budget_spent(&mut self) -> bool { - if self.room_frames < self.frame_budget { - return false; - } - if let Some(publication) = - self.host.as_mut().and_then(HostProducer::closing) - { - self.count_frame(); - self.outbound.push_back(publication.frame); - self.published = self.published.saturating_add(1); - } - // The session ends here, so the count is written now rather than on a tick that will not - // come. - if let Some(host) = self.host.as_mut() { - host.save_frames(); - } - self.ending = Some(Ending::FrameBudget); - true - } - - /// Opens a path: this client offers it, and its whole held set changes (§13.7). - /// - /// The change is announced here rather than left to the caller's next tick: §13.7 asks a - /// holder to re-announce at once when its set changes, and the tick's period is the room's - /// own `awareness_renew_ms` — fifteen seconds at the reference defaults, which is not - /// "at once". Nothing goes out while §13.1's step 4 withholds everything but the - /// announcement, and nothing goes out for a set that did not change. - pub fn open(&mut self, clock: Duration, path: &str) { - let _ = self.held.insert(path.to_string()); - self.announce_holds(clock); - } - - /// Releases every path. §13.7 asks for the empty set rather than for silence, so the room - /// learns in one hop instead of waiting out a lease — and it learns it here, for the reason - /// [`Self::open`] gives. - pub fn release(&mut self, clock: Duration) { - self.held.clear(); - self.announce_holds(clock); - } - - /// Holds this one path and nothing else, announced once (§13.7). - /// - /// A holds message carries the whole set and no delta, so a caller replacing the set with - /// one path cannot say so with [`Self::release`] and [`Self::open`]: each announces the - /// change it makes, and the room would see an empty set between them. - pub fn hold_only(&mut self, clock: Duration, path: &str) { - self.held.clear(); - let _ = self.held.insert(path.to_string()); - self.announce_holds(clock); - } +use yrs::sync::Awareness; + +use crate::host::HostProducer; +use crate::sealed::{FrameKey, KeyId, PublicKey, Reader, SessionKey}; + +mod clocks; +mod deliver; +mod events; +mod holds; +mod invite; +mod options; +mod plaintext; +mod publish; +mod read; +mod report; +mod roles; +mod speculation; + +pub use invite::{PeerInvite, wire_address}; +pub use options::{FRAME_BUDGET, PeerOptions}; +pub use report::{Applied, Dropped, Ending, Outcome, Published}; + +use speculation::Unsent; - /// A local edit, published as the delta it produced and never as the whole document. - /// - /// Returns whether the delta was queued. A known `viewer` refuses the mutation outright and - /// an UNKNOWN-role edit is held until a state resolves its eligibility (§13.1's step 4, - /// §13.9). +/// One connection's `selvage/2` session. +pub struct PeerSession { + room_id: String, + frame_key: FrameKey, + session: SessionKey, + declared_role: Option, + /// The host's producer half, when this connection holds the host key (§7.1). + host: Option, + /// The bytes of the last room state this connection **applied** (§7.1). /// - /// # Errors + /// §7.1 has a peer that holds a verified state re-send it, unchanged, when it sees a + /// `peer.joined`, so a joiner's state arrives while the host is away. The bytes are the + /// ones it received: only the host key signs a state, and a peer that re-sealed or + /// re-signed one would hand the room a frame every other peer refuses. + held_state_frame: Option>, + counter: u64, + renew: Duration, + expire: Duration, + seat: Option, + roster: BTreeSet, + reader: Reader, + awareness: Awareness, + /// §8.2's receiver bookkeeping: the local monotone clock, the one every argument named + /// `clock` carries, at which each **remote** awareness client id's state was last + /// actually applied. A tick forgets an id whose stamp is `awareness_expire_ms` old, and an + /// entry that was ignored because its clock was not above the one held does not stamp. /// - /// Returns an error when `index` is past the end of the text, and when the platform's - /// CSPRNG cannot be read. - #[expect( - clippy::too_many_arguments, - reason = "the path, the offset and the text are the three members of one edit" - )] - pub fn insert( - &mut self, - path: &str, - index: u32, - text: &str, - ) -> Result { - // §13.5 and §13.9: a known `viewer` never creates the CRDT history a later promotion - // could export, so the mutation is refused before it touches the replica. - if self.role() == Some("viewer") { - return Ok(false); - } - // §13.9: before any state gives this key a role, an edit is speculative — it goes into - // the replica for the local view, and a clean baseline is captured so a later `viewer` - // resolution can drop it without leaving a tombstone or a dependency behind. - let speculative = !self.is_writer(); - if speculative { - self.begin_speculation(); - } - let before = { - let txn = self.awareness.doc().transact(); - txn.state_vector() - }; - // An index past the end of the text is the caller's bug, and `yrs` answers one by - // panicking — the type is not there. A client any caller can kill with an offset is not - // one a decision vector can drive, so it is refused as an error like any other. - if index > self.length(path) { - return Err(SealedError::new(format!( - "there is no offset {index} in {path:?}" - ))); - } - { - let doc = self.awareness.doc_mut(); - let handle = doc.get_or_insert_text(path); - let mut txn = doc.transact_mut(); - handle.insert(&mut txn, index, text); - } - let update = { - let txn = self.awareness.doc().transact(); - txn.encode_state_as_update_v1(&before) - }; - if update.is_empty() { - return Ok(false); - } - if !self.may_publish() || !self.is_writer() { - // §13.1's step 4 holds content back until a state commits this key, and a client - // that dropped what it held back would leave the room without that edit for good. - // What is kept is this edit's own delta and not a diff over the document: another - // peer's content can have arrived in the meantime, and a client that re-sent it - // would publish under its own key changes it did not make. - self.hold_back(update, speculative); - return Ok(false); - } - // The state resolved this key as a writer: the edit is room history, not speculation. - self.accept_speculation(); - if self.send_update(&update) { - Ok(true) - } else { - // A failed seal is not a publication: keep the delta for the next flush. - self.hold_back(update, false); - Ok(false) - } - } - - /// Keeps one edit this connection may not publish yet (§13.1's step 4). §13.9's `viewer` - /// keeps no such edit — its mutation is refused — and §13.10's ended session will publish - /// nothing later either: keeping it would grow a buffer nothing drains for as long as the - /// session lives. - fn hold_back(&mut self, update: Vec, speculative: bool) { - if self.role() != Some("viewer") && self.ending.is_none() { - self.unsent.push(Unsent { - update, - speculative, - }); - } - } - - fn send_update(&mut self, update: &[u8]) -> bool { - let plaintext = encode_y_message(&YMessage::Sync(SyncMessage::Update( - update.to_vec(), - ))); - self.publish(Published::Content, &plaintext) - } - - /// Publishes the edits this connection made before a state committed its key (§13.1's step - /// 4), in the order they were made. + /// This connection's own id is never here: §8.2 has a client never expire itself. + awareness_seen: BTreeMap, + outbound: VecDeque>, + /// The paths this client has open: the whole set every holds message carries (§13.7). + held: BTreeSet, + /// The set the last holds message carried, so that a changed set is published at once and + /// an unchanged one waits for the renewal clock. + holds_sent: Vec, + holds_announced_at: Option, + /// When the last holds message from each key was accepted, which is its lease. + leases: BTreeMap, + /// The seats that have left, from `peer.left`: what §13.7 drops holds on and what tells + /// a seat the roster never knew from one that departed. + departed: BTreeSet, + announced_at: Option, + /// The local edits this client made while §13.1's step 4 held its content back, in the + /// order it made them: the deltas themselves, so that flushing them cannot carry a peer's + /// changes out under this connection's key. `speculative` marks an edit made while no + /// applied state gave this key a role yet, which a `viewer` resolution discards. + unsent: Vec, + /// A clean replica, present only while UNKNOWN-role local edits need a rollback (§13.9). /// - /// §13.10 reaches this path too: a state that arrives after the session ended would - /// otherwise flush the whole held set into a room this connection has left, so an ended - /// session drops the buffer rather than growing it. - fn flush_held_back(&mut self) { - if self.unsent.is_empty() { - return; - } - if self.ending.is_some() { - self.unsent.clear(); - return; - } - if !self.is_writer() { - return; - } - self.accept_speculation(); - let held: Vec = mem::take(&mut self.unsent); - if !self.may_publish() { - self.unsent = held; - return; - } - // A failed seal is not a publication: keep that delta for the next flush. - let retained: Vec = held - .into_iter() - .filter(|entry| !self.send_update(&entry.update)) - .collect(); - self.unsent = retained; - } + /// A genuine second document built from an encoded update, never `Doc::clone` (which is a + /// handle to the same store): this is what a `viewer` resolution adopts in place of the + /// replica that holds the speculative edits. + baseline: Option, + /// A typed effect of the owned replica, for the relay's §13.5 text surface: bumped whenever + /// this session replaces the document a consumer was reading text from (§13.9's `viewer` + /// resolution adopting the clean baseline). A state-driven rollback can then be reported + /// even when the path set and listing are unchanged, without re-reading or comparing text. + replica_epoch: u64, + /// The committed writer keys whose first accepted `SyncStep1` this connection has served + /// with its own request (§13.6), by the full key that verified. + reciprocal_served: BTreeSet, + /// The committed writer keys whose reciprocal request is owed and not yet sealed and queued. + reciprocal_pending: BTreeSet, + /// Readiness owed for this local key's renewed continuous writer eligibility (§13.6). + local_readiness_pending: bool, + /// The role the last applied state gave this connection's own key, for continuous + /// eligibility: an already-handshaken key that re-enters writer eligibility owes one request. + role_seen: Option, + /// The clock of the first content frame this client refused since its last `SyncStep1`, + /// which is §13.6's interval. `None` means there is nothing to re-sync about. + resync_from: Option, + /// The clock of the last `SyncStep1` this client sent, which is what the re-sync is + /// bounded by: one is sent per renewal interval however many frames were refused. + handshaken_at: Option, + /// The edition of the state this client holds, or `None` before one has been applied + /// (§13.3's waiting rules and §13.10's closing both turn on it). + state_issued: Option, + host_away_since: Option, + published: u64, + handshake: u64, + frames: u64, + /// `CANONICAL.md` §6.1's count: every binary frame this session was delivered and every + /// frame it sealed, across reconnects, because the frame key it is counted against outlives + /// a socket. + room_frames: u64, + frame_budget: u64, + applied: Vec, + dropped: Vec, + ignored: Vec, + /// The frames refused because they were a second state at an edition this client already + /// holds (§13.3). The reason is `stale_issued` like any other stale state; this is the + /// local annotation that says which of the two it was. + conflicts: Vec, + ending: Option, + mutation: Option, + /// The first thing that went wrong on the way *out* — a CSPRNG that would not read, an + /// AEAD that refused its own inputs. A session cannot refuse to publish without somewhere + /// to say so, and a driver that never looks is a driver publishing nothing. + fault: Option, } #[cfg(test)] mod tests { + use super::plaintext::encode_y_message; use super::*; use crate::host::{ - ABSENCE_CHARGE, HostStore, ListingSource, PersistedHost, + ABSENCE_CHARGE, HostOptions, HostStore, ListingSource, PersistedHost, }; - use crate::nesting::MAX_ANY_DEPTH; - use crate::sealed::{Envelope, RoomKey, encode_key, opens, read_varuint}; - use serde_json::json; + use crate::nesting::{MAX_ANY_DEPTH, decode_update}; + use crate::sealed::{Envelope, Recipe, RoomKey, encode_key, opens, read_varuint, seal}; + use selvage_protocol as proto; + use serde_json::{Value, json}; use std::sync::{Arc, Mutex}; use yrs::sync::awareness::{AwarenessUpdate, AwarenessUpdateEntry}; - use yrs::{Doc, Text, Transact}; + use yrs::sync::{Message as YMessage, MessageReader, SyncMessage}; + use yrs::updates::decoder::DecoderV1; + use yrs::{Doc, GetString, ReadTxn, StateVector, Text, Transact}; /// A room, a host keypair and a session keypair, all derived from constants: these are /// unit tests of §13's rules and they need no fixture to be one. @@ -2256,7 +227,8 @@ mod tests { ) }) .collect(); - let payload = json!({"issued": issued, "listing": ["README.md"], "peers": members}); + let payload = + json!({"issued": issued, "listing": ["README.md"], "peers": members}); frame(signer, 1, 1, &serde_json::to_vec(&payload).unwrap()) } @@ -2452,8 +424,7 @@ mod tests { if envelope.kind != 0 { return None; } - let plaintext = - opens(&room_key().frame_key(ROOM), ROOM, &envelope).ok()?; + let plaintext = opens(&room_key().frame_key(ROOM), ROOM, &envelope).ok()?; if plaintext.first() != Some(&0) { return None; } @@ -2540,8 +511,7 @@ mod tests { } #[test] - fn a_committing_state_answers_with_the_handshake_and_moves_no_publication() - { + fn a_committing_state_answers_with_the_handshake_and_moves_no_publication() { let mut session = session(&[]); session.tick(Duration::ZERO); let _ = session.take_outbound(); @@ -2669,8 +639,7 @@ mod tests { } #[test] - fn a_committed_viewers_content_is_refused_and_its_own_edit_is_not_published() - { + fn a_committed_viewers_content_is_refused_and_its_own_edit_is_not_published() { let mut session = session(&[]); session.tick(Duration::ZERO); // Both keys: ours is committed, so §13.1's step 4 has nothing to re-announce, and @@ -2959,8 +928,7 @@ mod tests { session.tick(millis(2 + 899)); let renewed = awareness_message(&[41], 2, "{}"); - let _ = - session.deliver(millis(2 + 899), &frame(&peer(), 0, 2, &renewed)); + let _ = session.deliver(millis(2 + 899), &frame(&peer(), 0, 2, &renewed)); session.tick(millis(2 + 899 + 899)); assert_eq!( session.awareness_clients(), @@ -2983,8 +951,7 @@ mod tests { // §8.2: an entry whose clock is not above the one held is ignored, and does not renew // the state. A stale copy of a live peer's state must not hold its cursor open. let replay = awareness_message(&[41], 4, "{}"); - let _ = - session.deliver(millis(2 + 899), &frame(&peer(), 0, 2, &replay)); + let _ = session.deliver(millis(2 + 899), &frame(&peer(), 0, 2, &replay)); session.tick(millis(2 + 900)); assert!( session.awareness_clients().is_empty(), @@ -3004,8 +971,7 @@ mod tests { // (`NOTES.md` §A.11), so the publication at the dropped clock and the one above it are // both ignored... let dropped = awareness_message(&[41], 5, "{}"); - let _ = - session.deliver(millis(2 + 900), &frame(&peer(), 0, 2, &dropped)); + let _ = session.deliver(millis(2 + 900), &frame(&peer(), 0, 2, &dropped)); assert!( session.awareness_clients().is_empty(), "the dropped clock is a tombstone" @@ -3037,8 +1003,7 @@ mod tests { // is past 41's window and short of 42's. Stamped together they would both lapse there, // and the tick would then test the window rather than the departure's own bookkeeping. let neighbour = awareness_message(&[42], 1, "{}"); - let _ = - session.deliver(millis(2 + 899), &frame(&peer(), 0, 2, &neighbour)); + let _ = session.deliver(millis(2 + 899), &frame(&peer(), 0, 2, &neighbour)); assert_eq!(session.awareness_clients(), [41, 42]); session.forget_awareness(41); @@ -3104,10 +1069,7 @@ mod tests { &state( &host(), 2, - &[ - (&ours(), "viewer", "p-self"), - (&peer(), "guest", "p-other") - ] + &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")] ) ), Outcome::Applied { kind: 1 } @@ -3172,10 +1134,7 @@ mod tests { &state( &host(), 2, - &[ - (&ours(), "viewer", "p-self"), - (&peer(), "guest", "p-other") - ] + &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")] ) ), Outcome::Applied { kind: 1 } @@ -3201,8 +1160,7 @@ mod tests { /// The tombstone routes that are not `forget_awareness` — §8.2's expiry and an incoming /// removal — must survive adoption too, or a stale copy resurrects a peer through the swap. #[test] - fn an_adopted_baseline_keeps_tombstones_from_expiry_and_an_incoming_removal() - { + fn an_adopted_baseline_keeps_tombstones_from_expiry_and_an_incoming_removal() { let mut session = session(&[]); session.tick(Duration::ZERO); let _ = session.take_outbound(); @@ -3291,11 +1249,7 @@ mod tests { "no state, renewal or query goes out at {clock}" ); } - assert_eq!( - session.published(), - published, - "no tick published anything" - ); + assert_eq!(session.published(), published, "no tick published anything"); } #[test] @@ -3580,10 +1534,8 @@ mod tests { frames: Some(10), }); // A reload is a return, so the saved count is continued with the absence charge on it. - let mut session = budgeted( - ABSENCE_CHARGE.saturating_add(11), - Some(stored_host(&store)), - ); + let mut session = + budgeted(ABSENCE_CHARGE.saturating_add(11), Some(stored_host(&store))); session.tick(Duration::ZERO); session.tick(millis(1)); assert_eq!( @@ -3610,8 +1562,7 @@ mod tests { first > 0, "the frames the host sealed are written on the tick" ); - let _ = - session.deliver(millis(301), &holds(&peer(), 1, &["README.md"])); + let _ = session.deliver(millis(301), &holds(&peer(), 1, &["README.md"])); session.tick(millis(600)); let saved = store.load().unwrap(); assert!( @@ -3676,8 +1627,7 @@ mod tests { } #[test] - fn a_state_published_after_a_flush_counts_as_a_write_for_the_renewal_window() - { + fn a_state_published_after_a_flush_counts_as_a_write_for_the_renewal_window() { let store = Arc::new(Counted::default()); let listing: ListingSource = Arc::new(|| vec!["README.md".to_string()]); let options = HostOptions { @@ -3693,8 +1643,8 @@ mod tests { // for the next window rather than being written on the next tick. session.seat_joined(millis(600), "p-alice"); let named = json!({ "key": peer().public().encode() }).to_string(); - let _ = session - .deliver(millis(600), &frame(&peer(), 4, 1, named.as_bytes())); + let _ = + session.deliver(millis(600), &frame(&peer(), 4, 1, named.as_bytes())); let after_state = *store.saves.lock().unwrap(); let _ = session.deliver(millis(601), &[1, 2, 3]); session.tick(millis(602)); @@ -3819,8 +1769,7 @@ mod tests { let answers = session.take_outbound(); assert_eq!(answers.len(), 1, "one SyncStep2 for the whole frame"); let envelope = Envelope::parse(&answers[0]).unwrap(); - let answer = - opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); + let answer = opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); assert_eq!(answer.first(), Some(&0), "message type 0: sync"); assert_eq!(read_varuint(&answer, 1).unwrap().0, 1, "SyncStep2"); } @@ -4031,8 +1980,7 @@ mod tests { } #[test] - fn the_invite_carries_the_room_and_both_keys_and_the_fragment_is_stripped() - { + fn the_invite_carries_the_room_and_both_keys_and_the_fragment_is_stripped() { let link = invite(room_key(), "k=$k&h=$h"); let parsed = PeerInvite::parse(&link).unwrap(); assert_eq!(parsed.room, ROOM); @@ -4122,14 +2070,13 @@ mod tests { #[test] fn the_page_link_is_the_same_room_token_and_fragment_over_the_browsers_scheme() - { + { // `PROTOCOL.md` §5.1's second form: the page the room's server serves, over the scheme // a browser speaks, with the same host, port and path prefix and nothing else in it. let room = encode_key(&room_key().0); let host_key = host().public().encode(); - let page = format!( - "http://h:8080/?room={ROOM}&token=t-1#k={room}&h={host_key}" - ); + let page = + format!("http://h:8080/?room={ROOM}&token=t-1#k={room}&h={host_key}"); let wire = format!("ws://h:8080/session?room={ROOM}&token=t-1"); assert_eq!( wire_address(&page), @@ -4168,9 +2115,8 @@ mod tests { // A path prefix survives the reading: the page is served under it and the endpoint is // under it too. - let mounted = format!( - "https://h/page/?room={ROOM}&token=t-1#k={room}&h={host_key}" - ); + let mounted = + format!("https://h/page/?room={ROOM}&token=t-1#k={room}&h={host_key}"); assert_eq!( PeerInvite::parse(&mounted).unwrap().socket_url, format!("wss://h/page/session?room={ROOM}&token=t-1") @@ -4183,10 +2129,7 @@ mod tests { "a connection URL still carries no fragment" ); // And one this cannot read as either form is not silently rewritten. - assert_eq!( - wire_address("wss://h/other?room=r"), - "wss://h/other?room=r" - ); + assert_eq!(wire_address("wss://h/other?room=r"), "wss://h/other?room=r"); } /// §5.1: `room` and `token` each appear at most once, in either form. A page link has no @@ -4232,8 +2175,7 @@ mod tests { // --- §13.6: the bounded reciprocal request, the shared clock and local readiness ----- #[test] - fn a_committed_writers_first_request_arms_one_coalesced_reciprocal_request() - { + fn a_committed_writers_first_request_arms_one_coalesced_reciprocal_request() { let mut session = session(&[]); session.tick(Duration::ZERO); let _ = session.take_outbound(); @@ -4308,11 +2250,7 @@ mod tests { ); let answer = session.take_outbound(); assert_eq!(answer.len(), 1); - assert_eq!( - sync_subtype(&answer[0]), - Some(1), - "the request is answered" - ); + assert_eq!(sync_subtype(&answer[0]), Some(1), "the request is answered"); session.tick(millis(302)); session.tick(millis(602)); assert!( @@ -4659,8 +2597,7 @@ mod tests { /// this connection is uncommitted and may not publish; the shared clock then serves it once /// the local key can publish again. Gating activation on local commitment would drop it. #[test] - fn a_remote_request_arms_while_uncommitted_and_is_served_after_recommitment() - { + fn a_remote_request_arms_while_uncommitted_and_is_served_after_recommitment() { let mut session = session(&[]); session.tick(Duration::ZERO); let _ = session.take_outbound(); @@ -4739,10 +2676,7 @@ mod tests { &state( &host(), 1, - &[ - (&ours(), "viewer", "p-self"), - (&peer(), "guest", "p-other") - ] + &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")] ) ), Outcome::Applied { kind: 1 } @@ -4800,10 +2734,7 @@ mod tests { &state( &host(), 1, - &[ - (&ours(), "guest", "p-self"), - (&peer(), "guest", "p-other") - ] + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")] ) ), Outcome::Applied { kind: 1 } @@ -4838,10 +2769,7 @@ mod tests { &state( &host(), 3, - &[ - (&ours(), "guest", "p-self"), - (&peer(), "viewer", "p-other") - ] + &[(&ours(), "guest", "p-self"), (&peer(), "viewer", "p-other")] ) ), Outcome::Applied { kind: 1 } @@ -5074,14 +3002,8 @@ mod tests { heard: [Heard<'_>; 3], ) { for (peer, [first, second]) in trio.into_iter().zip(heard) { - assert_eq!( - peer.deliver(clock, first), - Outcome::Applied { kind: 0 } - ); - assert_eq!( - peer.deliver(clock, second), - Outcome::Applied { kind: 0 } - ); + assert_eq!(peer.deliver(clock, first), Outcome::Applied { kind: 0 }); + assert_eq!(peer.deliver(clock, second), Outcome::Applied { kind: 0 }); let answers = peer.take_outbound(); assert_eq!(answers.len(), 2, "each request draws one Step2"); assert!(answers.iter().all(|frame| sync_subtype(frame) == Some(1))); diff --git a/crates/client/src/peer/options.rs b/crates/client/src/peer/options.rs new file mode 100644 index 0000000..691f459 --- /dev/null +++ b/crates/client/src/peer/options.rs @@ -0,0 +1,123 @@ +//! What a session is opened with, and the host's producer half built from it (§7.1). + +use crate::host::HostOptions; +use crate::host::HostProducer; +use crate::sealed::FrameKey; +use crate::sealed::PublicKey; +use crate::sealed::RoomKey; +use crate::sealed::SealedError; +use std::collections::BTreeSet; +use std::fmt; +use std::time::Duration; + +/// What a session built to be a host is told when the handshake gave it no seat: §7.1's state +/// labels its own connection's seat, and there is nothing to write without one. +const HOST_NEEDS_SEAT: &str = + "a host session publishes its own seat, and the handshake gave it none"; + +/// What a session is opened with: the invite's two keys, the session's clock, and the seats +/// the server has shown. +#[derive(Clone)] +pub struct PeerOptions { + pub room_id: String, + pub room_key: RoomKey, + /// The host key the invite's `h` carries: the room's root of trust, and the only key that + /// verifies a `kind = 1` state or a `kind = 2` closing. + pub host_key: PublicKey, + /// `awareness_renew_ms` (`PROTOCOL.md` §8.2): the clock an uncommitted announcement is + /// re-sent on and a held set is renewed on, and the tick a lease (§13.7) and an expired + /// remote awareness state (§8.2) are checked on. + pub renew: Duration, + /// `awareness_expire_ms`: the window a remote awareness state is forgotten after + /// (§8.2), the host-away window (§13.8) and, read from the seat, the no-state window + /// (§13.3). + pub expire: Duration, + /// The seat this connection is shown under, from `room.created`/`room.joined`. It decides + /// no attribution (§13.4) and is carried only because a person is shown it. + pub seat: Option, + /// The seats the roster has, which is what §13.8 reads a state's `host` entry against. + pub roster: BTreeSet, + /// A fixed session keypair, as its 32-byte Ed25519 seed. + /// + /// **A test seam, and not production surface.** §13.1 mints the session keypair in memory + /// for the connection and never persists it, and no frame carries a private key to a + /// client, so nothing in the protocol lets a caller choose one. It exists because the + /// corpus's decision layer drives a *fixture* keypair: the state a decision vector + /// delivers commits that fixture key's public half, so a client that minted its own key + /// could not be the peer the vector is about. `None` mints one, which is what a session + /// does. + pub fixed_session_key: Option<[u8; 32]>, + /// The role this client believes it has been given — `guest` or `viewer`, never `host` — + /// declared in its announcement. A host **SHOULD** honour it (§7.1). + pub declared_role: Option, + /// The awareness client id the handshake announced, so that the states this connection + /// publishes and the seat the room attributes them to agree (§8.4). `None` mints one from + /// the replica, which is what a session with no handshake does. + pub awareness_client_id: Option, + /// The host's producer half (§7.1), which makes this session the room's authority rather + /// than one of its peers. The host key's private half lives here, so a session given one + /// can sign a state and a session without one cannot; the room's host publishes the state + /// that every peer's key and role come from, and a session with no state produces none. + pub host: Option, + /// The room's frame budget (`CANONICAL.md` §6.1), [`FRAME_BUDGET`] when `None`. **A test + /// seam**: a live session has no reason to set it, and a smaller one only ends a room sooner. + pub frame_budget: Option, +} + +/// `CANONICAL.md` §6.1's frame budget: half of SP 800-38D's 2³² bound on one key with random +/// nonces, which is the room's and not one sender's, so that a client that missed frames the +/// relay dropped still stops well short of it. +pub const FRAME_BUDGET: u64 = 1 << 31; + +/// The same rule as [`PeerInvite`]'s: the room key, the host key and the two private seeds are +/// not printed. A session's options are built from an invite, and §5.1 forbids what they carry +/// from reaching a log as much as it forbids it reaching a request. +impl fmt::Debug for PeerOptions { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("PeerOptions") + .field("room_id", &self.room_id) + .field("room_key", &"") + .field("host_key", &self.host_key.id().hex()) + .field("renew", &self.renew) + .field("expire", &self.expire) + .field("seat", &self.seat) + .field("roster", &self.roster) + .field( + "fixed_session_key", + &self.fixed_session_key.map(|_| ""), + ) + .field("declared_role", &self.declared_role) + .field("awareness_client_id", &self.awareness_client_id) + .field("host", &self.host.as_ref().map(|_| "")) + .field("frame_budget", &self.frame_budget) + .finish() + } +} + +/// The host's producer half for a session handed the host key (§7.1). +/// +/// §7.1's own entry labels this connection's seat, and a state whose `host` entry labels no seat +/// of the roster leaves every peer with no identified host connection at all (§13.4), so a host +/// session needs the seat the handshake gave it. +#[expect( + clippy::too_many_arguments, + reason = "the session's options, its frame key, the host's own and the key it signs with" +)] +pub(super) fn host_producer( + options: &PeerOptions, + frame_key: FrameKey, + host_options: &HostOptions, + own_key: PublicKey, +) -> Result { + let Some(seat) = options.seat.as_deref() else { + return Err(SealedError::new(HOST_NEEDS_SEAT)); + }; + HostProducer::new( + &options.room_id, + frame_key, + options.renew, + host_options, + seat, + own_key, + ) +} diff --git a/crates/client/src/peer/plaintext.rs b/crates/client/src/peer/plaintext.rs new file mode 100644 index 0000000..8dee61d --- /dev/null +++ b/crates/client/src/peer/plaintext.rs @@ -0,0 +1,60 @@ +//! The y-protocols side of a `kind = 0` frame: the session document, one message's +//! bytes, and whether a plaintext is document content or a handshake. + +use crate::sealed::read_varuint; +use serde_json::Value; +use yrs::Doc; +use yrs::OffsetKind; +use yrs::Options; +use yrs::block::ClientID; +use yrs::sync::Message as YMessage; +use yrs::updates::encoder::Encode; +use yrs::updates::encoder::Encoder; +use yrs::updates::encoder::EncoderV1; + +/// The session document §7 fixes: one `Y.Doc`, one `Y.Text` per document. +/// +/// A text offset is a UTF-16 code unit, which is what `yjs`, every editor's `offsetAt` and +/// every peer on the wire use (`PROTOCOL.md` §8.1); `yrs` defaults to UTF-8 byte offsets. +/// +/// `awareness_client_id` is the id the handshake announced (§8.4): y-protocols seeds one of its +/// own, and a session that published under a second id would have every peer draw this client's +/// caret under a stranger's. `ClientID` is a 53-bit value, which is the width every id on this +/// wire is read in. +pub(super) fn peer_doc(awareness_client_id: Option) -> Doc { + const YJS_ID_BITS: u64 = 53; + let client_id = awareness_client_id.map_or_else(ClientID::random, |id| { + ClientID::new(id & ((1u64 << YJS_ID_BITS) - 1)) + }); + Doc::with_options(Options { + offset_kind: OffsetKind::Utf16, + client_id, + ..Options::default() + }) +} + +/// One y-protocols message as a `kind = 0` plaintext. +pub(super) fn encode_y_message(message: &YMessage) -> Vec { + let mut encoder = EncoderV1::new(); + message.encode(&mut encoder); + encoder.to_vec() +} + +/// Whether a `kind = 0` plaintext carries document content: a sync `Update` or `SyncStep2`, as +/// opposed to the `SyncStep1` of §13.1's step 6, which shares the envelope's kind. +/// +/// §13.5: content is a writer's to publish, and a `viewer` answers a request with nothing. +pub(super) fn is_content(plaintext: &[u8]) -> bool { + plaintext.first() == Some(&0) + && read_varuint(plaintext, 1).is_ok_and(|(tag, _)| tag == 1 || tag == 2) +} + +/// A JSON value's canonical bytes. `CANONICAL.md` §2 writes an object with its members +/// ascending, which `serde_json`'s own map does (it is a `BTreeMap`). +/// +/// The values this is handed are objects of strings and arrays of strings, and encoding one +/// cannot fail; an empty plaintext would be a frame no peer reads, which is `bad_payload` at +/// every receiver and a sender's bug here. +pub(super) fn canonical(value: &Value) -> Vec { + serde_json::to_vec(value).unwrap_or_default() +} diff --git a/crates/client/src/peer/publish.rs b/crates/client/src/peer/publish.rs new file mode 100644 index 0000000..278e425 --- /dev/null +++ b/crates/client/src/peer/publish.rs @@ -0,0 +1,289 @@ +//! Everything that leaves a session: the seal, §13.6's publication gates, the +//! announcement and its renewal, the handshake, and the two ways a host's publishing ends. + +use super::PeerSession; +use super::plaintext::canonical; +use super::plaintext::encode_y_message; +use super::plaintext::is_content; +use super::report::Counted; +use super::report::Ending; +use super::report::Published; +use crate::host::HostProducer; +use crate::host::HostReason; +use crate::sealed::Recipe; +use crate::sealed::SealedError; +use crate::sealed::fresh_nonce; +use crate::sealed::seal; +use serde_json::Value; +use serde_json::json; +use std::time::Duration; +use yrs::ReadTxn; +use yrs::Transact; +use yrs::sync::Message as YMessage; +use yrs::sync::SyncMessage; + +/// What a host is told when §7.1's closing could not be sealed: a host cannot refuse to close +/// without somewhere to say so, and a driver that never looks is a driver closing nothing. +const CLOSING_UNSEALED: &str = "the closing could not be sealed"; + +impl PeerSession { + /// The state §7.1 has this host publish now, if it is due: sealed by the host key, counted + /// as a publication, and folded into this session's own receiver. + /// + /// A host never receives the state it writes — the relay sends a frame to the room's + /// *other* connections — so the receiver is folded from the value rather than from the + /// bytes, and before anything that follows the frame (`after_state`) so that a `SyncStep1` + /// goes out only once a state commits this connection's key (§13.1's steps 4 and 6). + pub(super) fn publish_state( + &mut self, + clock: Duration, + reason: HostReason, + ) { + if self.room_frames >= self.frame_budget { + return; + } + let Some(host) = self.host.as_mut() else { + return; + }; + let owed = host.publish(clock, reason); + if let Some(fault) = host.failure() { + let _ = self.fault.get_or_insert_with(|| fault.to_string()); + } + let Some(publication) = owed else { + return; + }; + if publication.fresh { + self.count_frame(); + } + self.outbound.push_back(publication.frame); + self.published = self.published.saturating_add(1); + let fresh = publication.state.as_ref().filter(|_| publication.fresh); + let Some(state) = fresh else { + return; + }; + self.reader.apply_own(state); + self.after_state(clock, publication.issued); + } + + /// One frame this connection did not author, put on the wire as the bytes it arrived as: + /// §7.1's re-send of a state the room holds, when a peer is seated. A frame at the edition + /// every peer already holds is refused `stale_issued` and changes nothing; the one this + /// re-send is for is the peer that holds none. + pub(super) fn republish(&mut self, frame: &[u8]) { + if self.ending.is_some() { + return; + } + self.outbound.push_back(frame.to_vec()); + self.published = self.published.saturating_add(1); + } + + /// §13.1's step 4: the session-key announcement, `kind = 4`, signed by the key it names. + pub(super) fn announce(&mut self, clock: Duration) { + let mut members = serde_json::Map::new(); + let _ = members + .insert("key".to_string(), json!(self.session.public().encode())); + if let Some(role) = &self.declared_role { + let _ = members.insert("role".to_string(), json!(role)); + } + let plaintext = canonical(&Value::Object(members)); + self.publish(Published::Announcement, &plaintext); + self.announced_at = Some(clock); + } + + /// §13.1's step 4: re-announce on the session's renewal clock for as long as no applied + /// state commits this key, which is how an announcement the relay dropped is recovered. + pub(super) fn reannounce(&mut self, clock: Duration) { + if self.commits_ours() || self.mutating("announce-once") { + return; + } + let due = match self.announced_at { + None => true, + Some(at) => clock.saturating_sub(at) >= self.renew, + }; + if due { + self.announce(clock); + } + } + + /// §13.1's step 6's handshake, run when this connection's own key *becomes* committed and + /// not for every state that commits it: a host republishes its state on every `peer.joined` + /// and on every announcement it accepts, so a handshake per state would be a frame per + /// republish. + pub(super) fn handshake_once(&mut self, clock: Duration) { + if self.handshaken_at.is_none() { + // §13.6: only an actual seal-and-queue discharges a request. A failed attempt is not + // a publication, so the clock is not moved and the next due tick retries it. + let _ = self.sync_step1(clock); + } + } + + /// §13.1's step 6: a `SyncStep1` with this replica's state vector, so the room can tell a + /// client that has been refusing frames from one that has been applying them. + /// + /// The vector is the publication replica's: §13.9 keeps a `viewer`'s own history out of it, + /// so the room is asked for what the room-safe history lacks. The shared clock and the + /// coalesced obligations move only when the frame was actually sealed and queued. + fn sync_step1(&mut self, clock: Duration) -> bool { + let vector = { + let txn = self.publication_doc().transact(); + txn.state_vector() + }; + let message = + encode_y_message(&YMessage::Sync(SyncMessage::SyncStep1(vector))); + if !self.publish(Published::Sync, &message) { + return false; + } + self.handshaken_at = Some(clock); + self.resync_from = None; + self.reciprocal_pending.clear(); + self.local_readiness_pending = false; + true + } + + /// §13.6: refusal, reciprocal and local readiness obligations share one clock — at most one + /// locally generated `SyncStep1` per renewal interval, measured from the last request + /// actually sealed and queued, whichever obligation asked for it. The initial request is + /// always due; an obligation too early to send is retained and served at the first due tick. + pub(super) fn resync(&mut self, clock: Duration) { + if !self.may_publish() { + return; + } + let Some(at) = self.handshaken_at else { + let _ = self.sync_step1(clock); + return; + }; + if self.resync_from.is_none() + && self.reciprocal_pending.is_empty() + && !self.local_readiness_pending + { + return; + } + if clock.saturating_sub(at) >= self.renew { + let _ = self.sync_step1(clock); + } + } + + /// One frame sealed under the frame key and signed by this connection's session key. + /// + /// Returns whether the frame was sealed and put on this session's own outbound queue: the + /// §13.6 clock moves on that and never on an attempt. The socket's own queue is the relay's + /// ([`crate::relay`]), so a successful seal is not a claim of delivery. + pub(super) fn publish( + &mut self, + what: Published, + plaintext: &[u8], + ) -> bool { + if !self.may_queue(what, plaintext) + || self.room_frames >= self.frame_budget + { + return false; + } + let Ok(bytes) = self.sealed_frame(what.kind(), plaintext) else { + // A CSPRNG that will not read, or an AEAD that refuses its own inputs. Neither + // happens in practice, and a session that kept quiet about one would look like a + // client with nothing to say. + self.fault = Some(format!("a {what:?} frame could not be sealed")); + return false; + }; + self.count_frame(); + self.outbound.push_back(bytes); + let tally = match what.counted() { + Counted::Publication => &mut self.published, + Counted::Handshake => &mut self.handshake, + }; + *tally = tally.saturating_add(1); + true + } + + /// §13.6's publication gates, checked at the moment of queueing: an ended session publishes + /// nothing, a key no state commits publishes only its announcement, and document content is + /// a writer's alone (§13.5). The announcement keeps its deliberate precommit exception. + fn may_queue(&self, what: Published, plaintext: &[u8]) -> bool { + if self.ending.is_some() { + return false; + } + what == Published::Announcement + || (self.may_publish() + && (!is_content(plaintext) || self.is_writer())) + } + + fn sealed_frame( + &mut self, + kind: u64, + plaintext: &[u8], + ) -> Result, SealedError> { + self.counter = self.counter.saturating_add(1); + let nonce = fresh_nonce()?; + let recipe = Recipe { + room_id: &self.room_id, + frame_key: &self.frame_key, + kind, + epoch: 0, + counter: self.counter, + nonce, + signer: &self.session, + }; + Ok(seal(&recipe, plaintext)?.bytes()) + } + + /// §7.1's closing: the host's statement that the room is over, above every state it + /// published. + /// + /// A host that publishes one stops publishing; every peer that already holds a verified + /// state below its `issued` applies it and ends, and §9's room dies when its last + /// connection ends. The session that published it ends with them, which is what §13.10 + /// gives a receiver that applies one and what keeps a host from publishing content into a + /// room it has just declared over. + pub fn close_room(&mut self) -> bool { + let Some(host) = self.host.as_mut() else { + return false; + }; + let closing = host.closing(); + let failure = host.failure().map(ToString::to_string); + let failed = failure.unwrap_or_else(|| CLOSING_UNSEALED.to_string()); + let Some(publication) = closing else { + self.fault.get_or_insert(failed); + return false; + }; + self.count_frame(); + if let Some(host) = self.host.as_mut() { + host.save_frames(); + } + self.outbound.push_back(publication.frame); + self.published = self.published.saturating_add(1); + self.ending = Some(Ending::Closing); + true + } + + /// `CANONICAL.md` §6.1's frame budget: once the room's count reaches it, nothing more is + /// sealed under the frame key. A host publishes its one closing first — the frame that ends + /// the room for every peer holding its state — and every session, the host's included, ends + /// and says why. + /// One more frame against the room's count, handed to the host's producer to persist. + pub(super) const fn count_frame(&mut self) { + self.room_frames = self.room_frames.saturating_add(1); + if let Some(host) = self.host.as_mut() { + host.count_frames(self.room_frames); + } + } + + pub(super) fn budget_spent(&mut self) -> bool { + if self.room_frames < self.frame_budget { + return false; + } + if let Some(publication) = + self.host.as_mut().and_then(HostProducer::closing) + { + self.count_frame(); + self.outbound.push_back(publication.frame); + self.published = self.published.saturating_add(1); + } + // The session ends here, so the count is written now rather than on a tick that will not + // come. + if let Some(host) = self.host.as_mut() { + host.save_frames(); + } + self.ending = Some(Ending::FrameBudget); + true + } +} diff --git a/crates/client/src/peer/read.rs b/crates/client/src/peer/read.rs new file mode 100644 index 0000000..92087f0 --- /dev/null +++ b/crates/client/src/peer/read.rs @@ -0,0 +1,353 @@ +//! What a caller reads off a session: its keys, its roles, its counts and its replica. + +use super::PeerSession; +use super::options::FRAME_BUDGET; +use super::options::PeerOptions; +use super::options::host_producer; +use super::plaintext::peer_doc; +use super::report::Applied; +use super::report::Dropped; +use super::report::Ending; +use crate::host::HostProducer; +use crate::host::HostReason; +use crate::sealed::PublicKey; +use crate::sealed::Reader; +use crate::sealed::SealedError; +use crate::sealed::SessionKey; +use std::collections::BTreeMap; +use std::collections::BTreeSet; +use std::collections::VecDeque; +use std::time::Duration; +use yrs::GetString; +use yrs::ReadTxn; +use yrs::Text; +use yrs::Transact; +use yrs::sync::Awareness; + +impl PeerSession { + /// A connection's session: §13.1's steps 1 and 2, and nothing sent yet. + /// + /// The clock this session reads starts at zero and every argument named `clock` is that + /// many units past the seat, so a caller passes `start.elapsed()` and a test passes a + /// number. Nothing here reads a platform clock. + /// + /// # Errors + /// + /// Returns an error when the platform's CSPRNG cannot be read, which is the one thing + /// minting a session keypair needs, and when a host session's first state cannot be sealed: + /// §7.1's mint state is what brings the room's listing into existence and commits this + /// connection's key, so a host that could not publish one is a host no peer can see. + pub fn new(options: &PeerOptions) -> Result { + let session = match options.fixed_session_key { + Some(seed) => SessionKey::from_seed(seed), + None => SessionKey::generate()?, + }; + let reader = + Reader::new(&options.room_id, options.room_key, options.host_key); + let frame_key = reader.frame_key; + let own_key = session.public(); + let host = match &options.host { + None => None, + Some(host_options) => { + Some(host_producer(options, frame_key, host_options, own_key)?) + } + }; + // `CANONICAL.md` §6.1: the host's count is the room's, so a host continues the one it + // saved. + let room_frames = host.as_ref().map_or(0, HostProducer::room_frames); + let mut roster = options.roster.clone(); + if let (Some(seat), true) = (options.seat.as_ref(), host.is_some()) { + // §9: a host is seated in the room it minted, whether or not the roster it was + // handed names it. Without this its own state's `host` entry labels a seat the + // session believes is absent, and §13.8's clock then ends its own session. + let _ = roster.insert(seat.clone()); + } + let mut peer = Self { + room_id: options.room_id.clone(), + frame_key, + session, + declared_role: options.declared_role.clone(), + host, + held_state_frame: None, + counter: 0, + renew: options.renew, + expire: options.expire, + seat: options.seat.clone(), + roster, + reader, + awareness: Awareness::new(peer_doc(options.awareness_client_id)), + awareness_seen: BTreeMap::new(), + outbound: VecDeque::new(), + held: BTreeSet::new(), + holds_sent: Vec::new(), + holds_announced_at: None, + leases: BTreeMap::new(), + departed: BTreeSet::new(), + announced_at: None, + unsent: Vec::new(), + baseline: None, + replica_epoch: 0, + reciprocal_served: BTreeSet::new(), + reciprocal_pending: BTreeSet::new(), + local_readiness_pending: false, + role_seen: None, + resync_from: None, + handshaken_at: None, + state_issued: None, + host_away_since: None, + published: 0, + handshake: 0, + frames: 0, + room_frames, + frame_budget: options.frame_budget.unwrap_or(FRAME_BUDGET), + applied: Vec::new(), + dropped: Vec::new(), + ignored: Vec::new(), + conflicts: Vec::new(), + ending: None, + mutation: None, + fault: None, + }; + if peer.host.is_some() { + // §13.1: a host's order is a peer's with one difference — it publishes a state at + // mint, so its own state may precede any it verifies. That state is also what + // commits its own connection's key, which is why a host has nothing to announce. + peer.publish_state(Duration::ZERO, HostReason::Mint); + } + let failed = peer.fault.take(); + if let Some(fault) = failed { + return Err(SealedError::new(fault)); + } + Ok(peer) + } + + /// This connection's session public key, which the announcement names. + #[must_use] + pub fn session_key(&self) -> PublicKey { + self.session.public() + } + + /// The generation of the document this connection currently owns text in, for a caller that + /// watches the replica rather than its contents: it moves when §13.9's `viewer` resolution + /// replaces the replica, which is the one state-driven way text can change without a content + /// frame. Comparing it is how the relay reports that change without reading any text. + #[must_use] + pub const fn replica_epoch(&self) -> u64 { + self.replica_epoch + } + + /// This connection's own seat, as a caller that needs to show it reads it. + #[must_use] + pub fn seat(&self) -> Option<&str> { + self.seat.as_deref() + } + + /// Whether a verified room state has been applied, which §13.3's waiting rules turn on. + #[must_use] + pub const fn state_held(&self) -> bool { + self.state_issued.is_some() + } + + /// Whether this connection holds the host key, which is the whole of what being the host is + /// in this version (§7.1). + #[must_use] + pub const fn is_host(&self) -> bool { + self.host.is_some() + } + + /// The awareness client id this connection announced, which is the one its replica speaks + /// under (§8.4): the id the room records for this seat, so a peer's caret is attributed to + /// the seat that published it. + #[must_use] + pub fn awareness_client_id(&self) -> u64 { + self.awareness.client_id().get() + } + + /// The awareness client ids this replica holds a state for, ascending: the ones a peer + /// published and nothing has removed since. + #[must_use] + pub fn awareness_clients(&self) -> Vec { + let mut ids: Vec = self + .awareness + .iter() + .filter(|(_, state)| state.data.is_some()) + .map(|(id, _)| id.get()) + .collect(); + ids.sort_unstable(); + ids + } + + /// The role the applied state gives this connection's own key (§13.4), or `None` while no + /// state commits it — the state is the only source of a role in this version. + #[must_use] + pub fn own_role(&self) -> Option<&str> { + self.role() + } + + /// The seat the applied state's `host` entry labels, or `None` while no state names one + /// (§13.4: a client with none **MUST NOT** guess one). + #[must_use] + pub fn named_host_seat(&self) -> Option<&str> { + self.host_seat() + } + + /// The roles the applied state assigns, by the seat each committed key is labelled. + #[must_use] + pub fn roles_by_seat(&self) -> BTreeMap { + self.reader + .committed + .values() + .map(|peer| (peer.peer_id.clone(), peer.role.clone())) + .collect() + } + + /// The edition of the last state this connection published, or `0` before it has published + /// one. This is §7.1's `issued` series, which a host that keeps hosting continues. + #[must_use] + pub fn published_issued(&self) -> u64 { + self.host.as_ref().map_or(0, HostProducer::published_issued) + } + + /// The edition of the state this client holds, or `None` before one is applied. + #[must_use] + pub const fn state_issued(&self) -> Option { + self.state_issued + } + + /// The listing of the last state applied, with §5's refused paths dropped. + #[must_use] + pub fn listing(&self) -> &[String] { + &self.reader.listing + } + + /// How many frames this client **published** under §13's rules (§13.11). + #[must_use] + pub const fn published(&self) -> u64 { + self.published + } + + /// How many §7 handshake frames it sent, counted apart from its publications. + #[must_use] + pub const fn handshake(&self) -> u64 { + self.handshake + } + + #[must_use] + pub const fn frames(&self) -> u64 { + self.frames + } + + #[must_use] + pub fn applied(&self) -> &[Applied] { + &self.applied + } + + #[must_use] + pub fn dropped(&self) -> &[Dropped] { + &self.dropped + } + + /// The frames that verified and applied nothing, by the index they were handed as. + #[must_use] + pub fn ignored(&self) -> &[u64] { + &self.ignored + } + + /// The frames refused as a second publication at an edition this client already holds + /// (§13.3), by the index they were handed as. They are in `dropped` too, with the reason + /// `stale_issued`: §13.3 keeps the reason and asks for the divergence to be visible beside + /// it, because two receivers can hold different listings at one edition and nothing on the + /// wire says which of the two is the host's latest. + #[must_use] + pub fn conflicts(&self) -> &[u64] { + &self.conflicts + } + + /// Why the session ended, if it has. + #[must_use] + pub const fn ending(&self) -> Option { + self.ending + } + + #[must_use] + pub fn mutation(&self) -> Option<&str> { + self.mutation.as_deref() + } + + /// The first frame this session could not produce, if any. A driver reads it and fails + /// loudly: publishing fails silently otherwise, and a subject that publishes nothing looks + /// like a client with nothing to say. + #[must_use] + pub fn fault(&self) -> Option<&str> { + self.fault.as_deref() + } + + /// The paths this client has open: what its own holds message carries. + #[must_use] + pub const fn held(&self) -> &BTreeSet { + &self.held + } + + /// What each peer is held to, by the key's canonical spelling where the applied state + /// names it and by its id where nothing does (§13.4). A key whose lease has lapsed is not + /// here at all: §13.7 has the receiver forget the whole set. + #[must_use] + pub fn peer_holds(&self) -> BTreeMap> { + self.reader + .holds + .iter() + .map(|(id, paths)| (self.spelling(*id), paths.clone())) + .collect() + } + + /// The length of a document's text in UTF-16 code units, the unit yjs, every editor's + /// `offsetAt` and every peer on the wire count an offset in (`PROTOCOL.md` §8.1). + #[must_use] + pub fn length(&self, path: &str) -> u32 { + let doc = self.awareness.doc(); + let text = doc.get_or_insert_text(path); + text.len(&doc.transact()) + } + + /// The text this replica holds at a path, which is what a decision vector reads. + #[must_use] + pub fn text(&self, path: &str) -> String { + let doc = self.awareness.doc(); + let text = doc.get_or_insert_text(path); + text.get_string(&doc.transact()) + } + + /// The CRDT state vector, as `(client id, clock)` pairs: what a sync handshake exchanges, + /// and what two fully synced replicas agree on. + #[must_use] + pub fn state_vector(&self) -> Vec<(u64, u32)> { + let doc = self.publication_doc(); + let txn = doc.transact(); + let mut entries: Vec<(u64, u32)> = txn + .state_vector() + .iter() + .map(|(client, clock)| (client.get(), *clock)) + .collect(); + entries.sort_unstable(); + entries + } + + /// The paths this replica holds any text for: the documents that have arrived. + #[must_use] + pub fn documents(&self) -> Vec { + let doc = self.awareness.doc(); + let txn = doc.transact(); + let mut paths: Vec = txn + .root_refs() + .filter(|(name, _)| txn.get_text(*name).is_some()) + .map(|(name, _)| name.to_string()) + .collect(); + paths.sort(); + paths + } + + /// Takes what this session has published, in the order it published it. + pub fn take_outbound(&mut self) -> Vec> { + self.outbound.drain(..).collect() + } +} diff --git a/crates/client/src/peer/report.rs b/crates/client/src/peer/report.rs new file mode 100644 index 0000000..0f8ba4c --- /dev/null +++ b/crates/client/src/peer/report.rs @@ -0,0 +1,103 @@ +//! What a session says it did: §13.11's decisions and counts, and the four endings. + +/// What a session did with one frame: the decision `PROTOCOL.md` §13.11 observes. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Outcome { + /// It verified and what it carried was applied. + Applied { kind: u64 }, + /// It was refused, at the first of `CANONICAL.md` §6.1's ten steps that refused it. + Dropped { reason: String }, + /// It verified and applied nothing: §13.10's closing handed to a receiver that holds no + /// verified state. Not a refusal — nothing was refused — and in neither list a vector + /// asserts, which is what vector 155 pins. + Ignored { kind: u64 }, +} + +/// What a session is about to publish: the kind of envelope it is, and whether `PROTOCOL.md` +/// §13.11's report counts it as a **publication** or as a §7 sync-handshake frame. +/// +/// The two counts are apart because a vector asserts one of them: §13.1's step 6 obliges a +/// client that applies a state committing its own key to send a `SyncStep1`, so a single +/// number could not tell a republished request from a publication. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Published { + /// The session-key announcement, `kind = 4`. + Announcement, + /// A holds message, `kind = 3`. + Holds, + /// Document content, `kind = 0`. + Content, + /// A `SyncStep1` or a `SyncStep2`, `kind = 0`. + Sync, +} + +impl Published { + pub(super) const fn kind(self) -> u64 { + match self { + Self::Holds => 3, + Self::Announcement => 4, + Self::Content | Self::Sync => 0, + } + } + + pub(super) const fn counted(self) -> Counted { + match self { + Self::Content | Self::Holds | Self::Announcement => { + Counted::Publication + } + Self::Sync => Counted::Handshake, + } + } +} + +/// Which of the two counts a published frame moves (§13.11). +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(super) enum Counted { + Publication, + Handshake, +} + +/// One frame a session applied, with the index of the frame it was handed as. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct Applied { + pub frame: u64, + pub kind: u64, +} + +/// One frame a session refused, and the reason `CANONICAL.md` §6.1's vocabulary gives. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Dropped { + pub frame: u64, + pub reason: String, +} + +/// The four endings a session reaches on its own. What §13.10 calls "the room is destroyed" +/// is the fifth and has no frame: a client learns it as `room_unknown` or close 4001 when it +/// names the id, which is the socket's business and not this module's. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Ending { + /// A `kind = 2` closing that verified and was above the mark, with a verified state + /// below it (§13.10). + Closing, + /// The host-away clock passed its window (§13.8). + HostAway, + /// The no-state window passed with nothing applied (§13.3). + NoState, + /// The room's frame count reached `CANONICAL.md` §6.1's frame budget. + FrameBudget, +} + +impl Ending { + /// The words a client says when it ends a session (§13.10 requires it to say why). + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Closing => "the room closed", + Self::HostAway => "the host has been away past its window", + Self::NoState => "no state arrived within the no-state window", + Self::FrameBudget => { + "the room has sealed as many frames as its key allows; start a new room" + } + } + } +} diff --git a/crates/client/src/peer/roles.rs b/crates/client/src/peer/roles.rs new file mode 100644 index 0000000..f3bf888 --- /dev/null +++ b/crates/client/src/peer/roles.rs @@ -0,0 +1,116 @@ +//! §13.4's attribution read back: the role an applied state gives a key, and the +//! eligibility §13.6's reciprocal and readiness accounting turns on. + +use super::PeerSession; +use crate::sealed::KeyId; +use crate::sealed::PublicKey; +use std::collections::BTreeSet; + +impl PeerSession { + /// Whether an applied state commits this connection's own session key. + pub(super) fn commits_ours(&self) -> bool { + self.reader + .committed + .values() + .any(|peer| peer.key == self.session.public()) + } + + /// The role the applied state gives this connection's own key (§13.4). + pub(super) fn role(&self) -> Option<&str> { + self.reader.role_of_key(self.session.public()) + } + + /// Whether §13.1's step 4 lets this client publish anything but its announcement. + /// + /// §13.10: a session that has ended publishes nothing, whichever ending reached it, so + /// the ending is checked here rather than at each caller. + pub(super) fn may_publish(&self) -> bool { + self.ending.is_none() && self.state_held() && self.commits_ours() + } + + /// §13.6: whether the applied state begins a new continuous writer eligibility for this + /// connection's own key, which owes one coalesced readiness request. + /// + /// An already-handshaken key that re-enters writer eligibility — a `viewer` promotion or an + /// absent interval — owes one. The first commitment owes §13.1's immediate initial request + /// instead, which `handshake_once` sends, and an uninterrupted eligibility owes nothing. + /// Eligibility ending before the request is queued retires it, leaving unrelated remote + /// reciprocal and refusal obligations alone. + pub(super) fn note_local_eligibility(&mut self, role: Option<&str>) { + if !matches!(role, Some("host" | "guest")) { + self.local_readiness_pending = false; + return; + } + if self.handshaken_at.is_some() + && !matches!(self.role_seen.as_deref(), Some("host" | "guest")) + { + self.local_readiness_pending = true; + } + } + + /// Whether the applied state gives this connection's own key a publishing role (§13.4). + pub(super) fn is_writer(&self) -> bool { + matches!(self.role(), Some("host" | "guest")) + } + + /// Whether the applied state commits `key` as a writer (§13.6's eligibility). + fn is_writer_key(&self, key: PublicKey) -> bool { + matches!(self.reader.role_of_key(key), Some("host" | "guest")) + } + + /// §13.6: arms one reciprocal request for the first accepted `SyncStep1` from a continuously + /// committed writer key. + /// + /// The identity is the full key whose signature verified, never its id (§6.1). A request + /// from a `viewer` is not one — a viewer sends no content, so reciprocating would solicit + /// nothing — and a key already served keeps its mark until its eligibility ends, which is + /// what stops the request from echoing for ever between two peers. + /// + /// Activation is the **remote** writer's eligibility and nothing local: a connection that is + /// itself uncommitted, or committed only as a `viewer`, still records the obligation, and the + /// publication gate withholds the request until it may publish. Gating activation on local + /// commitment would drop the obligation outright, which is not a delay. + pub(super) fn arm_reciprocal(&mut self, verified: PublicKey) { + if !self.is_writer_key(verified) { + return; + } + if self.reciprocal_served.insert(verified) { + let _ = self.reciprocal_pending.insert(verified); + } + } + + /// §13.6: retires the reciprocal accounting for keys the applied state no longer commits as + /// writers, so a later promotion of one may arm once more while a continuously committed key + /// keeps its served mark. + pub(super) fn prune_reciprocal(&mut self) { + let writers: BTreeSet = self + .reader + .committed + .values() + .filter(|peer| peer.role == "host" || peer.role == "guest") + .map(|peer| peer.key) + .collect(); + self.reciprocal_served.retain(|key| writers.contains(key)); + self.reciprocal_pending.retain(|key| writers.contains(key)); + } + + /// The seat the applied state's `host` entry labels, in the order §6.1 reads two `host` + /// keys: the one whose key comes first in UTF-16 code-unit order. + pub(super) fn host_seat(&self) -> Option<&str> { + self.reader + .committed + .values() + .find(|peer| peer.role == "host") + .map(|peer| peer.peer_id.as_str()) + } + + /// The canonical spelling of a key id where an applied state names one, and its id where + /// nothing does (§13.4). + pub(super) fn spelling(&self, id: KeyId) -> String { + self.reader + .committed + .values() + .find(|peer| peer.key.id() == id) + .map_or_else(|| id.hex(), |peer| peer.key.encode()) + } +} diff --git a/crates/client/src/peer/speculation.rs b/crates/client/src/peer/speculation.rs new file mode 100644 index 0000000..95da217 --- /dev/null +++ b/crates/client/src/peer/speculation.rs @@ -0,0 +1,238 @@ +//! §13.9: the local edits a session may not publish yet, the clean baseline they are +//! held apart from, and what a resolved role does with them. + +use super::PeerSession; +use super::plaintext::encode_y_message; +use super::plaintext::peer_doc; +use super::report::Published; +use crate::nesting::decode_update; +use crate::sealed::SealedError; +use std::mem; +use yrs::Doc; +use yrs::ReadTxn; +use yrs::StateVector; +use yrs::Text; +use yrs::Transact; +use yrs::block::ClientID; +use yrs::sync::Awareness; +use yrs::sync::Message as YMessage; +use yrs::sync::SyncMessage; + +/// One locally authored edit §13.1's step 4 is holding back, and whether it was made while no +/// applied state had given this connection's key a role yet. +/// +/// The deltas themselves and not a diff over the replica: a state that does not commit this key +/// still lets its peers' content be applied (§13.2), so a vector taken at the first held-back +/// edit would carry their changes out again under this connection's key. +#[derive(Debug, Clone)] +pub(super) struct Unsent { + update: Vec, + speculative: bool, +} + +impl PeerSession { + /// §13.9: resolves UNKNOWN-role history before any request or reply is encoded, so a `viewer` + /// resolution never exports the speculation and a writer never answers from it. A writer + /// adopts it as room history; a `viewer` discards it outright. + pub(super) fn resolve_speculation(&mut self) { + if self.role() == Some("viewer") { + self.discard_speculative(); + } else if self.is_writer() { + self.accept_speculation(); + } + } + + /// The replica publication is built from: the clean baseline while a speculative edit is + /// held, and this connection's own document otherwise (§13.9). + pub(super) fn publication_doc(&self) -> &Doc { + self.baseline + .as_ref() + .unwrap_or_else(|| self.awareness.doc()) + } + + /// §13.9: captures a clean replica before the first UNKNOWN-role local mutation, so a later + /// `viewer` resolution can adopt history without the speculation. + /// + /// A genuinely separate `Doc` built from an encoded update, never `Doc::clone` (which is a + /// handle to the same store). The whole-doc update carries every pending struct and the + /// delete set, so the baseline is faithful. + fn begin_speculation(&mut self) { + if self.baseline.is_some() { + return; + } + let baseline = peer_doc(Some(self.awareness.client_id().get())); + let whole = { + let txn = self.awareness.doc().transact(); + txn.encode_state_as_update_v1(&StateVector::default()) + }; + let Ok(update) = decode_update(&whole) else { + return; + }; + let mut txn = baseline.transact_mut(); + let _ = txn.apply_update(update); + drop(txn); + self.baseline = Some(baseline); + } + + /// §13.9: the speculative edits are room history after all — the state resolved the key as a + /// writer — so the clean baseline is dropped and the deltas are publishable. + fn accept_speculation(&mut self) { + self.baseline = None; + for entry in &mut self.unsent { + entry.speculative = false; + } + } + + /// §13.9: adopts the clean baseline in place of the replica that holds the speculative edits. + /// + /// The replica is replaced rather than inverse-deleted, so no tombstone or dependency from + /// the disallowed history survives. The remote awareness states and their clocks are carried + /// onto the new owner, and this connection's announced awareness id is unchanged. + fn discard_speculative(&mut self) { + self.unsent.retain(|entry| !entry.speculative); + let Some(next) = self.baseline.take() else { + return; + }; + // §8.2/§8.4: the removal clocks are as much a part of the inventory as the live states. + // `update()` would drop every tombstone, letting a stale entry resurrect a peer the room + // has forgotten, so the whole tracked set is carried by id — `update_with_clients` writes + // a removed id's clock with a null state — and reapplied, which preserves both. + let tracked: Vec = + self.awareness.iter().map(|(id, _)| id).collect(); + let inventory = self.awareness.update_with_clients(tracked); + let mut adopted = Awareness::new(next); + if let Ok(carried) = inventory { + let _ = adopted.apply_update(carried); + } + self.awareness = adopted; + self.replica_epoch = self.replica_epoch.saturating_add(1); + } + + /// A local edit, published as the delta it produced and never as the whole document. + /// + /// Returns whether the delta was queued. A known `viewer` refuses the mutation outright and + /// an UNKNOWN-role edit is held until a state resolves its eligibility (§13.1's step 4, + /// §13.9). + /// + /// # Errors + /// + /// Returns an error when `index` is past the end of the text, and when the platform's + /// CSPRNG cannot be read. + #[expect( + clippy::too_many_arguments, + reason = "the path, the offset and the text are the three members of one edit" + )] + pub fn insert( + &mut self, + path: &str, + index: u32, + text: &str, + ) -> Result { + // §13.5 and §13.9: a known `viewer` never creates the CRDT history a later promotion + // could export, so the mutation is refused before it touches the replica. + if self.role() == Some("viewer") { + return Ok(false); + } + // §13.9: before any state gives this key a role, an edit is speculative — it goes into + // the replica for the local view, and a clean baseline is captured so a later `viewer` + // resolution can drop it without leaving a tombstone or a dependency behind. + let speculative = !self.is_writer(); + if speculative { + self.begin_speculation(); + } + let before = { + let txn = self.awareness.doc().transact(); + txn.state_vector() + }; + // An index past the end of the text is the caller's bug, and `yrs` answers one by + // panicking — the type is not there. A client any caller can kill with an offset is not + // one a decision vector can drive, so it is refused as an error like any other. + if index > self.length(path) { + return Err(SealedError::new(format!( + "there is no offset {index} in {path:?}" + ))); + } + { + let doc = self.awareness.doc_mut(); + let handle = doc.get_or_insert_text(path); + let mut txn = doc.transact_mut(); + handle.insert(&mut txn, index, text); + } + let update = { + let txn = self.awareness.doc().transact(); + txn.encode_state_as_update_v1(&before) + }; + if update.is_empty() { + return Ok(false); + } + if !self.may_publish() || !self.is_writer() { + // §13.1's step 4 holds content back until a state commits this key, and a client + // that dropped what it held back would leave the room without that edit for good. + // What is kept is this edit's own delta and not a diff over the document: another + // peer's content can have arrived in the meantime, and a client that re-sent it + // would publish under its own key changes it did not make. + self.hold_back(update, speculative); + return Ok(false); + } + // The state resolved this key as a writer: the edit is room history, not speculation. + self.accept_speculation(); + if self.send_update(&update) { + Ok(true) + } else { + // A failed seal is not a publication: keep the delta for the next flush. + self.hold_back(update, false); + Ok(false) + } + } + + /// Keeps one edit this connection may not publish yet (§13.1's step 4). §13.9's `viewer` + /// keeps no such edit — its mutation is refused — and §13.10's ended session will publish + /// nothing later either: keeping it would grow a buffer nothing drains for as long as the + /// session lives. + fn hold_back(&mut self, update: Vec, speculative: bool) { + if self.role() != Some("viewer") && self.ending.is_none() { + self.unsent.push(Unsent { + update, + speculative, + }); + } + } + + fn send_update(&mut self, update: &[u8]) -> bool { + let plaintext = encode_y_message(&YMessage::Sync(SyncMessage::Update( + update.to_vec(), + ))); + self.publish(Published::Content, &plaintext) + } + + /// Publishes the edits this connection made before a state committed its key (§13.1's step + /// 4), in the order they were made. + /// + /// §13.10 reaches this path too: a state that arrives after the session ended would + /// otherwise flush the whole held set into a room this connection has left, so an ended + /// session drops the buffer rather than growing it. + pub(super) fn flush_held_back(&mut self) { + if self.unsent.is_empty() { + return; + } + if self.ending.is_some() { + self.unsent.clear(); + return; + } + if !self.is_writer() { + return; + } + self.accept_speculation(); + let held: Vec = mem::take(&mut self.unsent); + if !self.may_publish() { + self.unsent = held; + return; + } + // A failed seal is not a publication: keep that delta for the next flush. + let retained: Vec = held + .into_iter() + .filter(|entry| !self.send_update(&entry.update)) + .collect(); + self.unsent = retained; + } +} From a76c15f09e6688e7e72ded8069db3d06a559e65f Mon Sep 17 00:00:00 2001 From: DontBlameMe Date: Mon, 19 Oct 2026 11:43:51 +0200 Subject: [PATCH 3/3] test(client): move the peer session's tests beside the modules they cover The inline `mod tests` becomes `peer/tests.rs`, and the imports it was getting from `use super::*` -- which reached whatever `peer.rs` imported -- are restated from the modules that now hold them. The tests themselves are unchanged. --- crates/client/src/peer/mod.rs | 3408 +------------------------------ crates/client/src/peer/tests.rs | 3407 ++++++++++++++++++++++++++++++ 2 files changed, 3408 insertions(+), 3407 deletions(-) create mode 100644 crates/client/src/peer/tests.rs diff --git a/crates/client/src/peer/mod.rs b/crates/client/src/peer/mod.rs index 7a8a23d..45515c4 100644 --- a/crates/client/src/peer/mod.rs +++ b/crates/client/src/peer/mod.rs @@ -146,3410 +146,4 @@ pub struct PeerSession { } #[cfg(test)] -mod tests { - use super::plaintext::encode_y_message; - use super::*; - use crate::host::{ - ABSENCE_CHARGE, HostOptions, HostStore, ListingSource, PersistedHost, - }; - use crate::nesting::{MAX_ANY_DEPTH, decode_update}; - use crate::sealed::{Envelope, Recipe, RoomKey, encode_key, opens, read_varuint, seal}; - use selvage_protocol as proto; - use serde_json::{Value, json}; - use std::sync::{Arc, Mutex}; - use yrs::sync::awareness::{AwarenessUpdate, AwarenessUpdateEntry}; - use yrs::sync::{Message as YMessage, MessageReader, SyncMessage}; - use yrs::updates::decoder::DecoderV1; - use yrs::{Doc, GetString, ReadTxn, StateVector, Text, Transact}; - - /// A room, a host keypair and a session keypair, all derived from constants: these are - /// unit tests of §13's rules and they need no fixture to be one. - const ROOM: &str = "R7f3a2c19"; - const MILLIS: u64 = 1; - - fn room_key() -> RoomKey { - RoomKey([7; 32]) - } - - fn host() -> SessionKey { - SessionKey::from_seed([3; 32]) - } - - /// This connection's session keypair, fixed so that a state can commit it. - fn ours() -> SessionKey { - SessionKey::from_seed([5; 32]) - } - - /// A second peer's, committed as `guest` or `viewer` beside ours. - fn peer() -> SessionKey { - SessionKey::from_seed([11; 32]) - } - - /// A third peer's, so all three real sessions can be driven at once. - fn third() -> SessionKey { - SessionKey::from_seed([17; 32]) - } - - #[expect( - clippy::too_many_arguments, - reason = "what a test seals with: the signer, the kind, the counter and the plaintext" - )] - fn frame( - signer: &SessionKey, - kind: u64, - counter: u64, - plaintext: &[u8], - ) -> Vec { - let key = room_key().frame_key(ROOM); - let recipe = Recipe { - room_id: ROOM, - frame_key: &key, - kind, - epoch: 0, - counter, - nonce: [9; 12], - signer, - }; - seal(&recipe, plaintext).unwrap().bytes() - } - - fn state( - signer: &SessionKey, - issued: u64, - peers: &[(&SessionKey, &str, &str)], - ) -> Vec { - let members: serde_json::Map = peers - .iter() - .map(|(key, role, seat)| { - ( - key.public().encode(), - json!({"peer_id": seat, "role": role}), - ) - }) - .collect(); - let payload = - json!({"issued": issued, "listing": ["README.md"], "peers": members}); - frame(signer, 1, 1, &serde_json::to_vec(&payload).unwrap()) - } - - /// A state committing this connection's own key as a `viewer` beside a committed writer. - fn viewer_beside_writer(issued: u64) -> Vec { - state( - &host(), - issued, - &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")], - ) - } - - fn holds(signer: &SessionKey, counter: u64, paths: &[&str]) -> Vec { - let payload = json!({"holds": paths}); - frame(signer, 3, counter, &serde_json::to_vec(&payload).unwrap()) - } - - fn closing(signer: &SessionKey, issued: u64) -> Vec { - let payload = json!({"closing": true, "issued": issued}); - frame(signer, 2, 1, &serde_json::to_vec(&payload).unwrap()) - } - - /// A `kind = 0` frame carrying a real Update, which is document content. - fn content(signer: &SessionKey, counter: u64, text: &str) -> Vec { - frame(signer, 0, counter, &update_message(text)) - } - - /// One sync Update message inserting `text` at the start of `README.md`. - fn update_message(text: &str) -> Vec { - let doc = Doc::new(); - let handle = doc.get_or_insert_text("README.md"); - { - let mut txn = doc.transact_mut(); - handle.insert(&mut txn, 0, text); - } - let update = { - let txn = doc.transact(); - txn.encode_state_as_update_v1(&yrs::StateVector::default()) - }; - encode_y_message(&YMessage::Sync(SyncMessage::Update(update))) - } - - /// A guest session whose state commits its own key and `peer()`'s, both as `guest`, with - /// the handshake that state draws already taken off its queue. - fn beside_a_guest() -> PeerSession { - let mut session = session(&["p-peer"]); - session.tick(Duration::ZERO); - let committing = state( - &host(), - 1, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-peer")], - ); - assert_eq!( - session.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - session - } - - /// Whether a published frame carries document content: a `kind = 0` plaintext whose - /// y-protocols message is a sync `Update` rather than the `SyncStep1` of §13.1's step 6, - /// which shares the envelope's kind (`CANONICAL.md` §6.1). - fn carries_an_update(frame: &[u8]) -> bool { - let Ok(envelope) = Envelope::parse(frame) else { - return false; - }; - if envelope.kind != 0 { - return false; - } - let Ok(plaintext) = opens(&room_key().frame_key(ROOM), ROOM, &envelope) - else { - return false; - }; - plaintext.first() == Some(&0) - && read_varuint(&plaintext, 1).is_ok_and(|(tag, _)| tag == 2) - } - - /// Whether a published frame carries any y-protocols awareness message at all: §8.2's - /// renewal and §8.3's step 2 are the two ways this session would send one. - fn carries_awareness(frame: &[u8]) -> bool { - let Ok(envelope) = Envelope::parse(frame) else { - return false; - }; - if envelope.kind != 0 { - return false; - } - let Ok(plaintext) = opens(&room_key().frame_key(ROOM), ROOM, &envelope) - else { - return false; - }; - let mut decoder = DecoderV1::from(plaintext.as_slice()); - MessageReader::new(&mut decoder) - .map_while(Result::ok) - .any(|message| matches!(message, YMessage::Awareness(_))) - } - - fn session(roster: &[&str]) -> PeerSession { - let options = PeerOptions { - room_id: ROOM.to_string(), - room_key: room_key(), - host_key: host().public(), - renew: Duration::from_millis(300), - expire: Duration::from_millis(900), - seat: Some("p-self".to_string()), - roster: roster.iter().map(|seat| (*seat).to_string()).collect(), - fixed_session_key: Some([5; 32]), - declared_role: None, - awareness_client_id: None, - host: None, - frame_budget: None, - }; - PeerSession::new(&options).unwrap() - } - - fn millis(count: u64) -> Duration { - Duration::from_millis(count) - } - - /// A second connection's session, fixed so a state can commit it beside ours. - fn second_session(roster: &[&str]) -> PeerSession { - let options = PeerOptions { - room_id: ROOM.to_string(), - room_key: room_key(), - host_key: host().public(), - renew: Duration::from_millis(300), - expire: Duration::from_millis(900), - seat: Some("p-other".to_string()), - roster: roster.iter().map(|seat| (*seat).to_string()).collect(), - fixed_session_key: Some([11; 32]), - declared_role: None, - awareness_client_id: None, - host: None, - frame_budget: None, - }; - PeerSession::new(&options).unwrap() - } - - /// A third connection's session, fixed so three real peers can be driven at once. - fn third_session(roster: &[&str]) -> PeerSession { - let options = PeerOptions { - room_id: ROOM.to_string(), - room_key: room_key(), - host_key: host().public(), - renew: Duration::from_millis(300), - expire: Duration::from_millis(900), - seat: Some("p-third".to_string()), - roster: roster.iter().map(|seat| (*seat).to_string()).collect(), - fixed_session_key: Some([17; 32]), - declared_role: None, - awareness_client_id: None, - host: None, - frame_budget: None, - }; - PeerSession::new(&options).unwrap() - } - - /// A room state with a chosen listing, which a listing-only edition needs. - #[expect( - clippy::too_many_arguments, - reason = "a signer, an edition, the peers and the listing are the whole of a state" - )] - fn state_listing( - signer: &SessionKey, - issued: u64, - peers: &[(&SessionKey, &str, &str)], - listing: &[&str], - ) -> Vec { - let members: serde_json::Map = peers - .iter() - .map(|(key, role, seat)| { - ( - key.public().encode(), - json!({"peer_id": seat, "role": role}), - ) - }) - .collect(); - let payload = - json!({"issued": issued, "listing": listing, "peers": members}); - frame(signer, 1, 1, &serde_json::to_vec(&payload).unwrap()) - } - - /// One sync `SyncStep1` message with an empty state vector: what a peer asks with. - fn step1() -> Vec { - encode_y_message(&YMessage::Sync(SyncMessage::SyncStep1( - StateVector::default(), - ))) - } - - /// The sync subtype of a published `kind = 0` frame: 0 is a `SyncStep1`, 1 a `SyncStep2`. - fn sync_subtype(frame: &[u8]) -> Option { - let envelope = Envelope::parse(frame).ok()?; - if envelope.kind != 0 { - return None; - } - let plaintext = opens(&room_key().frame_key(ROOM), ROOM, &envelope).ok()?; - if plaintext.first() != Some(&0) { - return None; - } - read_varuint(&plaintext, 1).ok().map(|(tag, _)| tag) - } - - /// The `README.md` text a published `SyncStep2` carries, applied to a fresh replica. - fn step2_text(frame: &[u8]) -> String { - let envelope = Envelope::parse(frame).unwrap(); - let plaintext = - opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); - let mut decoder = DecoderV1::from(plaintext.as_slice()); - let Some(Ok(YMessage::Sync(SyncMessage::SyncStep2(update)))) = - MessageReader::new(&mut decoder).next() - else { - return String::new(); - }; - let doc = Doc::new(); - let handle = doc.get_or_insert_text("README.md"); - let mut txn = doc.transact_mut(); - txn.apply_update(decode_update(&update).unwrap()).unwrap(); - handle.get_string(&txn) - } - - #[test] - fn the_announcement_goes_out_first_and_nothing_else_before_a_state() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let published = session.take_outbound(); - assert_eq!( - published.len(), - 1, - "§13.1's step 4 is the first binary frame" - ); - assert_eq!(session.published(), 1); - assert_eq!(session.handshake(), 0); - - let envelope = Envelope::parse(&published[0]).unwrap(); - assert_eq!(envelope.kind, 4); - assert_eq!(envelope.counter, 1); - let plaintext = - opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); - let announcement: Value = serde_json::from_slice(&plaintext).unwrap(); - assert_eq!(announcement["key"], json!(ours().public().encode())); - } - - #[test] - fn an_uncommitted_key_is_re_announced_on_the_renewal_clock_and_stops_once_committed() - { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - - // A state that commits another peer and not this connection: §13.1's step 4 announces - // again at once, because the renewal clock alone would wait a whole window. - let other = state(&host(), 1, &[(&peer(), "guest", "p-other")]); - assert_eq!( - session.deliver(millis(MILLIS), &other), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert_eq!(session.published(), 2); - - session.tick(millis(MILLIS + 299)); - assert!( - session.take_outbound().is_empty(), - "the clock has not passed" - ); - session.tick(millis(MILLIS + 300)); - assert_eq!(session.take_outbound().len(), 1, "§13.1's renewal clock"); - assert_eq!(session.published(), 3); - - // A state that commits this connection's key ends the recovery. - let committing = state(&host(), 2, &[(&ours(), "guest", "p-self")]); - assert_eq!( - session.deliver(millis(MILLIS + 301), &committing), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - session.tick(millis(MILLIS + 900)); - session.tick(millis(MILLIS + 1200)); - assert!(session.take_outbound().is_empty()); - assert_eq!(session.published(), 3); - } - - #[test] - fn a_committing_state_answers_with_the_handshake_and_moves_no_publication() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - - let committing = state(&host(), 1, &[(&ours(), "guest", "p-self")]); - assert_eq!( - session.deliver(millis(MILLIS), &committing), - Outcome::Applied { kind: 1 } - ); - let after = session.take_outbound(); - assert_eq!(after.len(), 1, "§13.1's step 6, once"); - assert_eq!(session.handshake(), 1); - assert_eq!( - session.published(), - 1, - "a handshake frame is not a publication" - ); - - let envelope = Envelope::parse(&after[0]).unwrap(); - assert_eq!(envelope.kind, 0); - let plaintext = - opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); - assert_eq!(plaintext.first(), Some(&0), "message type 0: sync"); - assert_eq!(read_varuint(&plaintext, 1).unwrap().0, 0, "SyncStep1"); - assert_eq!(session.listing(), ["README.md"]); - assert!(session.state_held()); - } - - #[test] - fn a_second_state_that_commits_our_key_sends_no_second_handshake() { - // §13.1's step 6 is a handshake *once*, and a host republishes its state on every - // `peer.joined` and on every announcement it accepts: a handshake per state would be a - // frame per republish. - let mut session = session(&[]); - session.tick(Duration::ZERO); - let first = state(&host(), 1, &[(&ours(), "guest", "p-self")]); - assert_eq!( - session.deliver(millis(1), &first), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert_eq!(session.handshake(), 1); - - let republished = state(&host(), 2, &[(&ours(), "guest", "p-self")]); - assert_eq!( - session.deliver(millis(2), &republished), - Outcome::Applied { kind: 1 } - ); - session.tick(millis(2 + 300)); - assert!(session.take_outbound().is_empty()); - assert_eq!(session.handshake(), 1, "one handshake per connection"); - } - - #[test] - fn an_edit_past_the_end_of_the_text_is_refused_and_not_a_panic() { - // `yrs` answers an offset that is not there by panicking, and a client a caller can - // kill with an index is not one a decision vector can drive. - let mut session = session(&[]); - session.tick(Duration::ZERO); - let state = state(&host(), 1, &[(&ours(), "guest", "p-self")]); - let _ = session.deliver(millis(1), &state); - assert!(session.insert("README.md", 0, "hello").unwrap()); - assert!(session.insert("README.md", 5, "!").unwrap()); - assert_eq!(session.length("README.md"), 6); - let refused = session.insert("README.md", 7, "!"); - assert!(refused.is_err(), "past the end is refused"); - assert_eq!(session.length("README.md"), 6, "and nothing was applied"); - } - - #[test] - fn two_states_at_one_edition_leave_the_first_applied() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let first = state(&host(), 2, &[(&ours(), "guest", "p-self")]); - let second = state(&host(), 2, &[(&peer(), "guest", "p-other")]); - assert_eq!( - session.deliver(millis(1), &first), - Outcome::Applied { kind: 1 } - ); - assert_eq!( - session.deliver(millis(2), &second), - Outcome::Dropped { - reason: "stale_issued".to_string() - } - ); - assert_eq!(session.applied().len(), 1); - assert_eq!(session.dropped().len(), 1); - // §13.3's `SHOULD` — the second state at one edition is the divergence, and a - // state *below* the mark is an ordinary stale state. The reason is the same for both. - assert_eq!(session.conflicts(), [1]); - } - - #[test] - fn a_state_below_the_mark_is_stale_and_not_a_conflict() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let first = state(&host(), 5, &[(&ours(), "guest", "p-self")]); - let old = state(&host(), 4, &[(&peer(), "guest", "p-other")]); - let _ = session.deliver(millis(1), &first); - assert_eq!( - session.deliver(millis(2), &old), - Outcome::Dropped { - reason: "stale_issued".to_string() - } - ); - assert_eq!(session.dropped().len(), 1, "still refused, still named"); - assert!( - session.conflicts().is_empty(), - "an edition below the mark is not two publications at one edition" - ); - } - - #[test] - fn the_same_state_is_still_refused_under_the_ignore_issued_mutation() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let first = state(&host(), 2, &[(&ours(), "guest", "p-self")]); - let second = state(&host(), 2, &[(&peer(), "guest", "p-other")]); - let _ = session.deliver(millis(1), &first); - session.mutate("ignore-issued").unwrap(); - assert_eq!( - session.deliver(millis(2), &second), - Outcome::Applied { kind: 1 } - ); - } - - #[test] - fn a_committed_viewers_content_is_refused_and_its_own_edit_is_not_published() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - // Both keys: ours is committed, so §13.1's step 4 has nothing to re-announce, and - // the peer's is the `viewer` whose frame is refused. - let state = state( - &host(), - 1, - &[ - (&ours(), "guest", "p-self"), - (&peer(), "viewer", "p-viewer"), - ], - ); - assert_eq!( - session.deliver(millis(1), &state), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - let edit = content(&peer(), 1, "hello"); - assert_eq!( - session.deliver(millis(2), &edit), - Outcome::Dropped { - reason: "unauthorised_content".to_string() - } - ); - assert_eq!(session.published(), 1, "nothing was published in answer"); - assert_eq!(session.text("README.md"), "", "and nothing was applied"); - - // §13.6: the refusal opens an interval, and the client re-syncs in it — once per - // renewal interval, however many content frames it refused. - assert!(session.take_outbound().is_empty()); - session.tick(millis(2 + 300)); - let after = session.take_outbound(); - assert_eq!(after.len(), 1, "§13.6's re-sync"); - assert_eq!(session.handshake(), 2, "§13.1's step 6, then §13.6's"); - assert_eq!( - session.published(), - 1, - "a handshake frame is not a publication" - ); - assert_eq!( - Envelope::parse(&after[0]).unwrap().kind, - 0, - "a `kind = 0` frame carrying the SyncStep1" - ); - session.tick(millis(2 + 301)); - session.tick(millis(2 + 302)); - assert!(session.take_outbound().is_empty(), "once per interval"); - } - - #[test] - fn an_edit_made_before_a_committing_state_goes_out_when_it_arrives() { - // §13.1's step 4 holds content back until a state commits this key, and a client that - // dropped what it held back would leave the room without that edit: nothing asks the - // room for what this replica lacks, only for what it has. - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - assert!( - !session.insert("README.md", 0, "held back").unwrap(), - "nothing may be published before a state commits this key" - ); - assert_eq!(session.published(), 1, "the announcement, and no content"); - - let committing = state(&host(), 1, &[(&ours(), "guest", "p-self")]); - assert_eq!( - session.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - let out = session.take_outbound(); - assert_eq!(out.len(), 2, "§13.1's step 6, then the held-back edit"); - assert_eq!(session.handshake(), 1); - assert_eq!(session.published(), 2, "the edit is a publication"); - assert_eq!(Envelope::parse(&out[1]).unwrap().kind, 0); - } - - #[test] - fn a_viewer_discards_its_own_edit_and_publishes_nothing() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let state = state(&host(), 1, &[(&ours(), "viewer", "p-self")]); - let _ = session.deliver(millis(1), &state); - let _ = session.take_outbound(); - assert!(!session.insert("README.md", 0, "hello").unwrap()); - assert_eq!(session.published(), 1); - assert_eq!( - session.text("README.md"), - "", - "the disallowed edit is not even locally visible" - ); - } - - #[test] - fn a_guest_publishes_its_edit_as_a_delta() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let state = state(&host(), 1, &[(&ours(), "guest", "p-self")]); - let _ = session.deliver(millis(1), &state); - let _ = session.take_outbound(); - assert!(session.insert("README.md", 0, "hello").unwrap()); - let out = session.take_outbound(); - assert_eq!(out.len(), 1); - assert_eq!(session.published(), 2); - let envelope = Envelope::parse(&out[0]).unwrap(); - assert_eq!(envelope.kind, 0); - } - - /// §13.10: a session that has ended publishes nothing, whichever ending reached it. A - /// guest whose ending is the host's closing keeps a later edit in its own replica and - /// sends none of it. - #[test] - fn an_ended_session_publishes_no_edit() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let state = state(&host(), 1, &[(&ours(), "guest", "p-self")]); - assert_eq!( - session.deliver(millis(1), &state), - Outcome::Applied { kind: 1 } - ); - assert_eq!( - session.deliver(millis(2), &closing(&host(), 2)), - Outcome::Applied { kind: 2 } - ); - assert_eq!(session.ending(), Some(Ending::Closing)); - let _ = session.take_outbound(); - let published = session.published(); - assert!( - !session.insert("README.md", 0, "after the closing").unwrap(), - "an ended session publishes nothing" - ); - assert!( - session.unsent.is_empty(), - "and keeps nothing back: §13.10 publishes nothing later either, so a held set \ - would only grow for as long as the session lives" - ); - assert!(session.take_outbound().is_empty()); - assert_eq!(session.published(), published); - assert_eq!( - session.text("README.md"), - "after the closing", - "and its own replica still holds the edit" - ); - - // The buffer stays empty however many edits follow, which is the whole of what an - // ended session does with one. - for _ in 0..64 { - assert!(!session.insert("README.md", 0, "x").unwrap()); - } - assert!(session.unsent.is_empty()); - assert!(session.take_outbound().is_empty()); - assert_eq!(session.published(), published); - } - - /// §13.10: an ended session publishes nothing, and the path that could still have done it - /// is the flush §13.1's step 4 owes a state that commits this connection's key. An edit held - /// back before the ending must not be published by a state arriving after it. - #[test] - fn a_state_after_the_ending_publishes_none_of_what_was_held_back() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - - // No state commits this key yet, so §13.1's step 4 holds the edit back. - assert!(!session.insert("README.md", 0, "held").unwrap()); - assert_eq!(session.unsent.len(), 1, "the edit is held, not published"); - - // §13.10's no-state window ends the session while the edit is still held. - session.tick(millis(900)); - assert_eq!(session.ending(), Some(Ending::NoState)); - - let committing = state(&host(), 1, &[(&ours(), "guest", "p-self")]); - assert_eq!( - session.deliver(millis(901), &committing), - Outcome::Applied { kind: 1 } - ); - assert!( - !session - .take_outbound() - .iter() - .any(|frame| carries_an_update(frame)), - "the state that commits this key is the flush's own trigger, and the flush of an \ - ended session is nothing" - ); - assert!(session.unsent.is_empty()); - } - - #[test] - fn a_closing_handed_to_a_state_less_client_is_ignored_and_the_state_below_it_still_applies() - { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - assert_eq!( - session.deliver(millis(1), &closing(&host(), 2)), - Outcome::Ignored { kind: 2 } - ); - assert_eq!(session.applied().len(), 0); - assert_eq!(session.dropped().len(), 0); - assert_eq!(session.ignored(), [0]); - assert_eq!(session.ending(), None); - - let state = state(&host(), 1, &[(&ours(), "guest", "p-self")]); - assert_eq!( - session.deliver(millis(2), &state), - Outcome::Applied { kind: 1 } - ); - let again = closing(&host(), 2); - assert_eq!( - session.deliver(millis(3), &again), - Outcome::Applied { kind: 2 } - ); - assert_eq!(session.ending(), Some(Ending::Closing)); - } - - #[test] - fn the_same_closing_ends_a_client_that_holds_no_state_under_the_any_closing_mutation() - { - let mut session = session(&[]); - session.tick(Duration::ZERO); - session.mutate("any-closing").unwrap(); - assert_eq!( - session.deliver(millis(1), &closing(&host(), 2)), - Outcome::Applied { kind: 2 } - ); - assert_eq!(session.ending(), Some(Ending::Closing)); - } - - #[test] - fn a_lease_lapses_a_window_after_the_last_message_and_drops_no_frame() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let state = state(&host(), 1, &[(&peer(), "guest", "p-other")]); - let _ = session.deliver(millis(1), &state); - let set = holds(&peer(), 1, &["README.md"]); - assert_eq!( - session.deliver(millis(2), &set), - Outcome::Applied { kind: 3 } - ); - assert_eq!( - session.peer_holds()[&peer().public().encode()], - ["README.md"] - ); - - session.tick(millis(2 + 899)); - assert_eq!(session.peer_holds().len(), 1, "the lease has not lapsed"); - session.tick(millis(2 + 900)); - assert!(session.peer_holds().is_empty()); - assert_eq!(session.dropped().len(), 0, "an expiry is not a refusal"); - assert_eq!(session.ending(), None, "and it is not a departure"); - } - - #[test] - fn a_lease_never_lapses_under_the_no_lease_mutation() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let state = state(&host(), 1, &[(&peer(), "guest", "p-other")]); - let _ = session.deliver(millis(1), &state); - let _ = session.deliver(millis(2), &holds(&peer(), 1, &["README.md"])); - session.mutate("no-lease").unwrap(); - session.tick(millis(10_000)); - assert_eq!(session.peer_holds().len(), 1); - } - - #[test] - fn a_silent_peers_awareness_state_lapses_a_window_after_it_was_applied() { - let mut session = beside_a_guest(); - let states = awareness_message(&[41], 1, "{\"cursor\":null}"); - let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &states)); - assert_eq!(session.awareness_clients(), [41]); - - session.tick(millis(2 + 899)); - assert_eq!(session.awareness_clients(), [41], "not before the window"); - session.tick(millis(2 + 900)); - assert!( - session.awareness_clients().is_empty(), - "§8.2: a remote state not renewed inside `awareness_expire_ms` is forgotten" - ); - assert_eq!(session.dropped().len(), 0, "an expiry is not a refusal"); - assert_eq!(session.ending(), None, "and it is not a departure"); - } - - #[test] - fn a_renewed_awareness_state_is_not_forgotten() { - let mut session = beside_a_guest(); - let first = awareness_message(&[41], 1, "{}"); - let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &first)); - session.tick(millis(2 + 899)); - - let renewed = awareness_message(&[41], 2, "{}"); - let _ = session.deliver(millis(2 + 899), &frame(&peer(), 0, 2, &renewed)); - session.tick(millis(2 + 899 + 899)); - assert_eq!( - session.awareness_clients(), - [41], - "the renewal moved the window it is measured from" - ); - session.tick(millis(2 + 899 + 900)); - assert!( - session.awareness_clients().is_empty(), - "and it lapses from there" - ); - } - - #[test] - fn an_awareness_entry_below_the_clock_held_does_not_renew_it() { - let mut session = beside_a_guest(); - let current = awareness_message(&[41], 7, "{}"); - let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, ¤t)); - - // §8.2: an entry whose clock is not above the one held is ignored, and does not renew - // the state. A stale copy of a live peer's state must not hold its cursor open. - let replay = awareness_message(&[41], 4, "{}"); - let _ = session.deliver(millis(2 + 899), &frame(&peer(), 0, 2, &replay)); - session.tick(millis(2 + 900)); - assert!( - session.awareness_clients().is_empty(), - "the replay renewed nothing" - ); - } - - #[test] - fn a_peer_that_expired_is_visible_again_above_its_tombstone() { - let mut session = beside_a_guest(); - let states = awareness_message(&[41], 5, "{}"); - let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &states)); - session.tick(millis(2 + 900)); - assert!(session.awareness_clients().is_empty(), "forgotten"); - - // `yrs`'s removal leaves the id a tombstone one above the state it dropped - // (`NOTES.md` §A.11), so the publication at the dropped clock and the one above it are - // both ignored... - let dropped = awareness_message(&[41], 5, "{}"); - let _ = session.deliver(millis(2 + 900), &frame(&peer(), 0, 2, &dropped)); - assert!( - session.awareness_clients().is_empty(), - "the dropped clock is a tombstone" - ); - let next = awareness_message(&[41], 6, "{}"); - let _ = session.deliver(millis(2 + 900), &frame(&peer(), 0, 3, &next)); - assert!( - session.awareness_clients().is_empty(), - "and so is the one above it" - ); - - // ...and the renewal above both makes the peer visible again, with its window moved. - let above = awareness_message(&[41], 7, "{}"); - let _ = session.deliver(millis(2 + 901), &frame(&peer(), 0, 4, &above)); - assert_eq!(session.awareness_clients(), [41], "visible again"); - session.tick(millis(2 + 901 + 900)); - assert!( - session.awareness_clients().is_empty(), - "and it lapses from the renewal" - ); - } - - #[test] - fn a_departed_peers_awareness_state_goes_at_once_and_stays_gone() { - let mut session = beside_a_guest(); - let states = awareness_message(&[41], 1, "{}"); - let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &states)); - // 42's state arrives a window later, so the two stamps do not coincide: the tick below - // is past 41's window and short of 42's. Stamped together they would both lapse there, - // and the tick would then test the window rather than the departure's own bookkeeping. - let neighbour = awareness_message(&[42], 1, "{}"); - let _ = session.deliver(millis(2 + 899), &frame(&peer(), 0, 2, &neighbour)); - assert_eq!(session.awareness_clients(), [41, 42]); - - session.forget_awareness(41); - assert_eq!( - session.awareness_clients(), - [42], - "§8.4: a departed seat's state goes at once, not at the window" - ); - - // The first tick at or after 41's window. `forget_awareness` cleared its stamp, so - // there is nothing for the expiry to act on; without that clear this is the tick that - // steps 41's tombstone a second time. - session.tick(millis(2 + 900)); - assert_eq!( - session.awareness_clients(), - [42], - "the expiry tick left the tombstone alone" - ); - - // If the expiry tick had stepped 41's tombstone a second time, this renewal would be - // swallowed and the id would stay gone. - let again = awareness_message(&[41], 3, "{}"); - let _ = session.deliver(millis(2 + 900), &frame(&peer(), 0, 3, &again)); - assert_eq!( - session.awareness_clients(), - [41, 42], - "the id is welcome back" - ); - } - /// A clean replica adopted by §13.9's `viewer` resolution must carry the removal clocks as - /// well as the live states: `Awareness::update()` alone would drop every tombstone and let a - /// stale entry resurrect a peer the room has forgotten. - #[test] - fn an_adopted_baseline_keeps_a_forgotten_ids_tombstone() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - // A state committing only the peer leaves this connection's own key UNKNOWN, so the - // local edit is speculative and captures the clean baseline a later resolution adopts. - assert_eq!( - session.deliver( - millis(1), - &state(&host(), 1, &[(&peer(), "guest", "p-other")]) - ), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert!(!session.insert("README.md", 0, "spec").unwrap()); - assert_eq!(session.text("README.md"), "spec"); - - // An awareness state, then §8.4's departure: the removal leaves a tombstone one above - // the state it dropped. - let states = awareness_message(&[41], 5, "{}"); - let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &states)); - assert_eq!(session.awareness_clients(), [41]); - session.forget_awareness(41); - assert!(session.awareness_clients().is_empty()); - - // The viewer state replaces the replica; the tombstone must move onto the new owner. - assert_eq!( - session.deliver( - millis(3), - &state( - &host(), - 2, - &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")] - ) - ), - Outcome::Applied { kind: 1 } - ); - assert_eq!( - session.text("README.md"), - "", - "the speculative edit is discarded" - ); - - // The dropped clock and the one above it stay absent; a higher one renews. - let dropped = awareness_message(&[41], 5, "{}"); - let _ = session.deliver(millis(4), &frame(&peer(), 0, 2, &dropped)); - assert!( - session.awareness_clients().is_empty(), - "the dropped clock stays a tombstone across adoption" - ); - let equal = awareness_message(&[41], 6, "{}"); - let _ = session.deliver(millis(5), &frame(&peer(), 0, 3, &equal)); - assert!( - session.awareness_clients().is_empty(), - "and so does the clock above it" - ); - let above = awareness_message(&[41], 7, "{}"); - let _ = session.deliver(millis(6), &frame(&peer(), 0, 4, &above)); - assert_eq!( - session.awareness_clients(), - [41], - "a renewal above the tombstone makes the peer visible again" - ); - } - - /// Adoption replaces the replica but must not disturb an unrelated live state's expiry: the - /// local stamp is this session's and survives the swap untouched. - #[test] - fn an_adopted_baseline_leaves_an_unrelated_state_on_its_own_schedule() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - assert_eq!( - session.deliver( - millis(1), - &state(&host(), 1, &[(&peer(), "guest", "p-other")]) - ), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert!(!session.insert("README.md", 0, "spec").unwrap()); - - // Two peers' states, stamped a window apart: 41 is forgotten, 42 stays live. - let fortyone = awareness_message(&[41], 5, "{}"); - let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &fortyone)); - let fortytwo = awareness_message(&[42], 1, "{}"); - let _ = session.deliver(millis(3), &frame(&peer(), 0, 2, &fortytwo)); - assert_eq!(session.awareness_clients(), [41, 42]); - session.forget_awareness(41); - assert_eq!(session.awareness_clients(), [42]); - - assert_eq!( - session.deliver( - millis(4), - &state( - &host(), - 2, - &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")] - ) - ), - Outcome::Applied { kind: 1 } - ); - assert_eq!( - session.awareness_clients(), - [42], - "an unrelated live state survives adoption" - ); - session.tick(millis(3 + 899)); - assert_eq!( - session.awareness_clients(), - [42], - "not before its own window" - ); - session.tick(millis(3 + 900)); - assert!( - session.awareness_clients().is_empty(), - "and it lapses on the schedule it was stamped on" - ); - } - - /// The tombstone routes that are not `forget_awareness` — §8.2's expiry and an incoming - /// removal — must survive adoption too, or a stale copy resurrects a peer through the swap. - #[test] - fn an_adopted_baseline_keeps_tombstones_from_expiry_and_an_incoming_removal() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - assert_eq!( - session.deliver( - millis(1), - &state(&host(), 1, &[(&peer(), "guest", "p-other")]) - ), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert!(!session.insert("README.md", 0, "spec").unwrap()); - - // 41 lives, then §8.2's expiry tick leaves it a tombstone one above its state. - let fortyone = awareness_message(&[41], 5, "{}"); - let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &fortyone)); - session.tick(millis(902)); - assert!(session.awareness_clients().is_empty(), "41 expired"); - - // 42 is removed by an incoming null state, which leaves its own tombstone. - let fortytwo = awareness_message(&[42], 1, "{}"); - let _ = session.deliver(millis(3), &frame(&peer(), 0, 2, &fortytwo)); - assert_eq!(session.awareness_clients(), [42]); - let removal = awareness_message(&[42], 2, "null"); - let _ = session.deliver(millis(4), &frame(&peer(), 0, 3, &removal)); - assert!(session.awareness_clients().is_empty(), "42 removed"); - - // Adoption replaces the replica; both tombstones must move onto the new owner. - assert_eq!( - session.deliver(millis(5), &viewer_beside_writer(2)), - Outcome::Applied { kind: 1 } - ); - let stale = awareness_message(&[41], 5, "{}"); - let _ = session.deliver(millis(6), &frame(&peer(), 0, 4, &stale)); - assert!( - session.awareness_clients().is_empty(), - "41's expiry clock stays gone" - ); - let equal = awareness_message(&[41], 6, "{}"); - let _ = session.deliver(millis(7), &frame(&peer(), 0, 5, &equal)); - assert!( - session.awareness_clients().is_empty(), - "41's clock above the tombstone stays gone" - ); - let above = awareness_message(&[41], 7, "{}"); - let _ = session.deliver(millis(8), &frame(&peer(), 0, 6, &above)); - assert_eq!( - session.awareness_clients(), - [41], - "41 renews above its tombstone" - ); - - let stale42 = awareness_message(&[42], 1, "{}"); - let _ = session.deliver(millis(9), &frame(&peer(), 0, 7, &stale42)); - assert!( - !session.awareness_clients().contains(&42), - "42's removal clock stays gone" - ); - let above42 = awareness_message(&[42], 3, "{}"); - let _ = session.deliver(millis(10), &frame(&peer(), 0, 8, &above42)); - assert!( - session.awareness_clients().contains(&42), - "42 renews above its removal" - ); - } - - #[test] - fn this_client_publishes_no_awareness_state_of_its_own() { - let mut session = beside_a_guest(); - let states = awareness_message(&[41], 1, "{}"); - let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &states)); - let _ = session.take_outbound(); - let published = session.published(); - assert!( - !session - .awareness_clients() - .contains(&session.awareness_client_id()), - "§8.2: a client that publishes no state holds none of its own" - ); - - for clock in [302, 902, 1802, 1803] { - session.tick(millis(clock)); - let sent = session.take_outbound(); - assert!( - sent.iter().all(|frame| !carries_awareness(frame)), - "no state, renewal or query goes out at {clock}" - ); - } - assert_eq!(session.published(), published, "no tick published anything"); - } - - #[test] - fn a_seated_client_with_no_state_ends_at_the_no_state_window() { - let mut session = session(&[]); - session.tick(millis(899)); - assert_eq!(session.ending(), None, "not before the window"); - session.tick(millis(900)); - assert_eq!(session.ending(), Some(Ending::NoState)); - } - - #[test] - fn the_same_client_stays_for_ever_under_the_wait_for_ever_mutation() { - let mut session = session(&[]); - session.mutate("wait-for-ever").unwrap(); - session.tick(millis(60_000)); - assert_eq!(session.ending(), None); - } - - #[test] - fn a_state_whose_host_entry_is_unseated_ends_the_session_a_window_later() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - // The roster names no seat, and the state's `host` entry labels one: §13.8's clock. - let state = state(&host(), 1, &[(&peer(), "host", "p-absent")]); - assert_eq!( - session.deliver(millis(1), &state), - Outcome::Applied { kind: 1 } - ); - session.tick(millis(900)); - assert_eq!( - session.ending(), - None, - "one millisecond short of the window" - ); - session.tick(millis(901)); - assert_eq!(session.ending(), Some(Ending::HostAway)); - } - - #[test] - fn a_peer_left_for_the_seat_the_host_entry_labels_arms_the_clock() { - // §13.11's fixture for the host-away clock, which no decision vector carries: the - // state labels a seat the roster has, and the roster then loses it. - let mut session = session(&["p-host"]); - session.tick(Duration::ZERO); - let state = state(&host(), 1, &[(&peer(), "host", "p-host")]); - let _ = session.deliver(millis(1), &state); - session.tick(millis(500)); - assert_eq!(session.ending(), None, "the host is seated"); - - session.seat_left(millis(600), "p-host"); - session.tick(millis(600 + 899)); - assert_eq!(session.ending(), None); - session.tick(millis(600 + 900)); - assert_eq!(session.ending(), Some(Ending::HostAway)); - } - - #[test] - fn a_state_that_does_not_name_a_host_arms_nothing() { - // §13.4: a client MUST NOT guess which connection is the host's. - let mut session = session(&[]); - session.tick(Duration::ZERO); - let state = state(&host(), 1, &[(&peer(), "guest", "p-other")]); - let _ = session.deliver(millis(1), &state); - session.tick(millis(5_000)); - assert_eq!(session.ending(), None); - } - - #[test] - fn a_held_set_is_announced_wholesale_and_an_empty_one_is_a_release() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let state = state(&host(), 1, &[(&ours(), "guest", "p-self")]); - let _ = session.deliver(millis(1), &state); - let _ = session.take_outbound(); - - // §13.7: a set that changed goes out with the change, and not at the next renewal — - // no `tick` between the two, so nothing else can have published it. - session.open(millis(2), "README.md"); - let out = session.take_outbound(); - assert_eq!(out.len(), 1, "a changed set goes out at once"); - let envelope = Envelope::parse(&out[0]).unwrap(); - assert_eq!(envelope.kind, 3); - let plaintext = - opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); - let payload: Value = serde_json::from_slice(&plaintext).unwrap(); - assert_eq!(payload["holds"], json!(["README.md"])); - - // The whole set and no delta, so the second open carries both paths. - session.open(millis(3), "src/main.rs"); - let out = session.take_outbound(); - assert_eq!(out.len(), 1); - let envelope = Envelope::parse(&out[0]).unwrap(); - let plaintext = - opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); - let payload: Value = serde_json::from_slice(&plaintext).unwrap(); - assert_eq!(payload["holds"], json!(["README.md", "src/main.rs"])); - - // Opening a path that is already held changes nothing, so nothing is published. - session.open(millis(4), "README.md"); - assert!(session.take_outbound().is_empty()); - - session.release(millis(5)); - let out = session.take_outbound(); - assert_eq!(out.len(), 1, "the empty set is a change like any other"); - assert_eq!(session.held().len(), 0); - let envelope = Envelope::parse(&out[0]).unwrap(); - let plaintext = - opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); - let payload: Value = serde_json::from_slice(&plaintext).unwrap(); - assert_eq!(payload["holds"], json!([] as [&str; 0])); - - // The whole set replaced by one path is one message: `release` and `open` would put an - // empty set on the wire between them, which is a release no caller asked for. - session.open(millis(6), "README.md"); - let _ = session.take_outbound(); - session.hold_only(millis(7), "src/main.rs"); - let out = session.take_outbound(); - assert_eq!(out.len(), 1, "a set replaced in one step is one message"); - let envelope = Envelope::parse(&out[0]).unwrap(); - let plaintext = - opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); - let payload: Value = serde_json::from_slice(&plaintext).unwrap(); - assert_eq!(payload["holds"], json!(["src/main.rs"])); - } - - /// §13.7's two "at once" moments, which the tick alone does not honour: the state that - /// commits this key is where a holder's *first* holds message belongs, and a `peer.joined` - /// is where a joiner learns the room's holds. - #[test] - fn a_first_holds_message_and_a_joiner_are_answered_on_the_event() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - session.open(millis(1), "README.md"); - assert!( - session.take_outbound().is_empty(), - "§13.1's step 4 withholds it until a state commits this key" - ); - - let committing = state(&host(), 1, &[(&ours(), "guest", "p-self")]); - let _ = session.deliver(millis(2), &committing); - let out = session.take_outbound(); - let kinds: Vec = out - .iter() - .map(|frame| Envelope::parse(frame).unwrap().kind) - .collect(); - assert_eq!( - kinds, - [0, 3], - "§13.1's step 6 handshake, then the first holds message: no tick between them" - ); - assert_eq!(session.handshake(), 1); - assert_eq!( - session.published(), - 2, - "the announcement and the holds message; the handshake is counted apart" - ); - - // A seat is seated: the state that will commit the joiner's key goes out with the event, - // and the room's holds behind it — a holds message resolves against the keys the applied - // state commits (§13.4), so one that arrives before the state is refused. - session.seat_joined(millis(3), "p-other"); - let out = session.take_outbound(); - let kinds: Vec = out - .iter() - .map(|frame| Envelope::parse(frame).unwrap().kind) - .collect(); - assert_eq!(kinds, [1, 3], "the state the room holds, then the holds"); - } - - #[test] - fn a_state_is_re_sent_on_a_join_only_while_the_host_is_away() { - // `PROTOCOL.md` §7.1: while the seat the `host` entry labels is seated, the host's own - // fresh state answers a join, so this peer sends none; once that seat has gone, a new - // seat — a returning host among them — is sent the held state, unchanged. - let mut session = session(&["p-host"]); - session.tick(Duration::ZERO); - let held = state( - &host(), - 1, - &[(&peer(), "host", "p-host"), (&ours(), "guest", "p-self")], - ); - let _ = session.deliver(millis(1), &held); - let _ = session.take_outbound(); - - session.seat_joined(millis(2), "p-new"); - let kinds: Vec = session - .take_outbound() - .iter() - .map(|frame| Envelope::parse(frame).unwrap().kind) - .collect(); - assert!( - !kinds.contains(&1), - "no state goes back while the host is seated: {kinds:?}" - ); - - session.seat_left(millis(3), "p-host"); - let _ = session.take_outbound(); - session.seat_joined(millis(4), "p-host-again"); - let out = session.take_outbound(); - assert_eq!( - out.first().map(Vec::as_slice), - Some(held.as_slice()), - "the held state goes back first, unchanged" - ); - } - - fn budgeted(budget: u64, host: Option) -> PeerSession { - let options = PeerOptions { - room_id: ROOM.to_string(), - room_key: room_key(), - host_key: self::host().public(), - renew: Duration::from_millis(300), - expire: Duration::from_millis(900), - seat: Some("p-self".to_string()), - roster: BTreeSet::new(), - fixed_session_key: Some([5; 32]), - declared_role: None, - awareness_client_id: None, - host, - frame_budget: Some(budget), - }; - PeerSession::new(&options).unwrap() - } - - #[test] - fn a_session_that_reaches_the_frame_budget_seals_nothing_more_and_ends() { - // `CANONICAL.md` §6.1: the announcement is the first frame the room counts and the - // state the second, so the handshake the state would be answered with is not sealed, - // and the next tick ends the session and says why. - let mut session = budgeted(2, None); - session.tick(Duration::ZERO); - assert_eq!(session.take_outbound().len(), 1, "the announcement"); - let _ = session.deliver( - millis(1), - &state(&host(), 1, &[(&ours(), "guest", "p-self")]), - ); - assert!( - session.take_outbound().is_empty(), - "nothing is sealed past the budget" - ); - session.tick(millis(2)); - assert_eq!(session.ending(), Some(Ending::FrameBudget)); - assert!(Ending::FrameBudget.as_str().contains("new room")); - session.open(millis(3), "README.md"); - session.tick(millis(400)); - assert!(session.take_outbound().is_empty(), "and nothing after it"); - assert_eq!(FRAME_BUDGET, 1 << 31); - } - - #[derive(Default)] - struct Saved(Mutex>); - - impl HostStore for Saved { - fn load(&self) -> Option { - *self.0.lock().unwrap() - } - - fn save(&self, persisted: PersistedHost) { - *self.0.lock().unwrap() = Some(persisted); - } - } - - fn stored_host(store: &Arc) -> HostOptions { - let listing: ListingSource = Arc::new(|| vec!["README.md".to_string()]); - HostOptions { - host_seed: [3; 32], - listing, - store: Some(Arc::clone(store) as Arc), - } - } - - #[test] - fn a_host_continues_the_frame_count_it_saved() { - // `CANONICAL.md` §6.1: the host's count is the room's, so a reload continues it rather - // than starting at 0, and the budget is reached from there. - let store = Arc::new(Saved::default()); - store.save(PersistedHost { - host_seed: [3; 32], - issued: 5, - frames: Some(10), - }); - // A reload is a return, so the saved count is continued with the absence charge on it. - let mut session = - budgeted(ABSENCE_CHARGE.saturating_add(11), Some(stored_host(&store))); - session.tick(Duration::ZERO); - session.tick(millis(1)); - assert_eq!( - session.ending(), - Some(Ending::FrameBudget), - "from the saved count" - ); - } - - #[test] - fn a_host_writes_its_moving_frame_count_once_a_renewal_interval() { - let store = Arc::new(Saved::default()); - let mut session = budgeted(FRAME_BUDGET, Some(stored_host(&store))); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - // The mint state's own write opened the window at 0, so the count it could not yet carry - // is written on the first tick a window later. - session.tick(millis(300)); - let first = store - .load() - .and_then(|saved| saved.frames) - .unwrap_or_default(); - assert!( - first > 0, - "the frames the host sealed are written on the tick" - ); - let _ = session.deliver(millis(301), &holds(&peer(), 1, &["README.md"])); - session.tick(millis(600)); - let saved = store.load().unwrap(); - assert!( - saved.frames.unwrap_or_default() > first, - "a delivered frame is in the next write" - ); - assert!(saved.issued > 0, "written beside `issued`"); - } - - #[test] - fn a_host_record_without_a_count_reads_as_a_spent_budget() { - // `CANONICAL.md` §6.1: a record written before the count existed cannot say what the - // room has sealed, so the host closes the room at its first tick rather than continue it. - let store = Arc::new(Saved::default()); - store.save(PersistedHost { - host_seed: [3; 32], - issued: 3, - frames: None, - }); - let mut session = budgeted(FRAME_BUDGET, Some(stored_host(&store))); - session.tick(Duration::ZERO); - let kinds: Vec = session - .take_outbound() - .iter() - .map(|frame| Envelope::parse(frame).unwrap().kind) - .collect(); - assert_eq!(kinds, [2], "the closing, and nothing sealed before it"); - assert_eq!(session.ending(), Some(Ending::FrameBudget)); - assert_eq!(store.load().map(|saved| saved.issued), Some(4)); - } - - #[test] - fn a_host_that_closes_its_room_saves_the_count_with_the_closing_in_it() { - let store = Arc::new(Saved::default()); - let mut session = budgeted(FRAME_BUDGET, Some(stored_host(&store))); - session.tick(Duration::ZERO); - let sealed = u64::try_from(session.take_outbound().len()).unwrap(); - assert!(session.close_room()); - assert_eq!( - store.load().and_then(|saved| saved.frames), - Some(sealed.saturating_add(1)), - "a reload continues from the frame that ended the room" - ); - } - - #[derive(Default)] - struct Counted { - saved: Saved, - saves: Mutex, - } - - impl HostStore for Counted { - fn load(&self) -> Option { - self.saved.load() - } - - fn save(&self, persisted: PersistedHost) { - let mut saves = self.saves.lock().unwrap(); - *saves = saves.saturating_add(1); - self.saved.save(persisted); - } - } - - #[test] - fn a_state_published_after_a_flush_counts_as_a_write_for_the_renewal_window() { - let store = Arc::new(Counted::default()); - let listing: ListingSource = Arc::new(|| vec!["README.md".to_string()]); - let options = HostOptions { - host_seed: [3; 32], - listing, - store: Some(Arc::clone(&store) as Arc), - }; - let mut session = budgeted(FRAME_BUDGET, Some(options)); - session.tick(Duration::ZERO); - session.tick(millis(300)); - // An announcement commits a key, so the host publishes a fresh state, and that write - // carries the count at its own clock: a frame that moves the count right after it waits - // for the next window rather than being written on the next tick. - session.seat_joined(millis(600), "p-alice"); - let named = json!({ "key": peer().public().encode() }).to_string(); - let _ = - session.deliver(millis(600), &frame(&peer(), 4, 1, named.as_bytes())); - let after_state = *store.saves.lock().unwrap(); - let _ = session.deliver(millis(601), &[1, 2, 3]); - session.tick(millis(602)); - assert_eq!( - *store.saves.lock().unwrap(), - after_state, - "no write inside the window" - ); - session.tick(millis(900)); - assert_eq!( - *store.saves.lock().unwrap(), - after_state.saturating_add(1), - "one once it has passed" - ); - } - - #[test] - fn a_host_that_reaches_the_frame_budget_publishes_its_closing_and_ends() { - let listing: ListingSource = Arc::new(|| vec!["README.md".to_string()]); - let mut session = budgeted( - 1, - Some(HostOptions { - host_seed: [3; 32], - listing, - store: None, - }), - ); - session.tick(Duration::ZERO); - let out = session.take_outbound(); - let kinds: Vec = out - .iter() - .map(|frame| Envelope::parse(frame).unwrap().kind) - .collect(); - session.tick(millis(1)); - let closing: Vec = session - .take_outbound() - .iter() - .map(|frame| Envelope::parse(frame).unwrap().kind) - .collect(); - assert_eq!( - [kinds, closing].concat().last(), - Some(&2), - "the last frame this host seals is its closing" - ); - assert_eq!(session.ending(), Some(Ending::FrameBudget)); - } - - #[test] - fn a_hold_message_from_a_key_no_state_commits_is_refused() { - // `PROTOCOL.md` §13.4 and `CANONICAL.md` §6.1's step 4: a `kind = 3` frame resolves - // against the keys the applied state commits, and this one commits only ours. - let mut session = session(&[]); - session.tick(Duration::ZERO); - let state = state(&host(), 1, &[(&ours(), "guest", "p-self")]); - let _ = session.deliver(millis(1), &state); - let _ = session.take_outbound(); - assert_eq!( - session.deliver(millis(2), &holds(&peer(), 1, &["README.md"])), - Outcome::Dropped { - reason: "uncommitted_key".to_string() - } - ); - assert!(session.peer_holds().is_empty()); - } - - #[test] - fn a_frame_is_refused_without_ending_the_session() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - assert_eq!( - session.deliver(millis(1), &frame(&peer(), 3, 1, b"{}")), - Outcome::Dropped { - reason: "uncommitted_key".to_string() - } - ); - assert_eq!(session.ending(), None); - } - - #[test] - fn a_denied_auth_message_costs_the_frame_its_other_messages_nothing() { - // §8.3: an auth message is read and ignored, a denial included, and the Update behind - // it in the same frame is applied. - let mut session = beside_a_guest(); - let mut plaintext = - encode_y_message(&YMessage::Auth(Some("denied".to_string()))); - plaintext.extend(update_message("hello")); - assert_eq!( - session.deliver(millis(2), &frame(&peer(), 0, 1, &plaintext)), - Outcome::Applied { kind: 0 } - ); - assert_eq!(session.text("README.md"), "hello"); - } - - #[test] - fn a_frame_of_awareness_queries_draws_no_answer() { - // §8.3: a query message is one byte, so a frame of them would otherwise draw one - // reply each. This client answers none. - let mut session = beside_a_guest(); - let published = session.published(); - let plaintext = vec![3u8; 4096]; - assert_eq!( - session.deliver(millis(2), &frame(&peer(), 0, 1, &plaintext)), - Outcome::Applied { kind: 0 } - ); - assert_eq!(session.take_outbound().len(), 0, "no answer at all"); - assert_eq!(session.published(), published); - } - - #[test] - fn a_frame_of_sync_step1_messages_draws_one_answer() { - // The answer to a SyncStep1 is a whole diff of the document, so one frame is answered - // once however many it carries. - let mut session = beside_a_guest(); - let ask = encode_y_message(&YMessage::Sync(SyncMessage::SyncStep1( - yrs::StateVector::default(), - ))); - let plaintext = ask.repeat(64); - assert_eq!( - session.deliver(millis(2), &frame(&peer(), 0, 1, &plaintext)), - Outcome::Applied { kind: 0 } - ); - let answers = session.take_outbound(); - assert_eq!(answers.len(), 1, "one SyncStep2 for the whole frame"); - let envelope = Envelope::parse(&answers[0]).unwrap(); - let answer = opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); - assert_eq!(answer.first(), Some(&0), "message type 0: sync"); - assert_eq!(read_varuint(&answer, 1).unwrap().0, 1, "SyncStep2"); - } - - /// One awareness message carrying `json` for each client id, at `clock`. - fn awareness_message(ids: &[u64], clock: u32, json: &str) -> Vec { - let entries: Vec<(u64, u32, &str)> = - ids.iter().map(|id| (*id, clock, json)).collect(); - awareness_entries(&entries) - } - - /// One awareness message carrying each `(client id, clock, json)` entry as it stands. - fn awareness_entries(entries: &[(u64, u32, &str)]) -> Vec { - let clients = entries - .iter() - .map(|(id, clock, json)| { - let entry = AwarenessUpdateEntry { - clock: *clock, - json: Arc::from(*json), - }; - (ClientID::new(*id), entry) - }) - .collect(); - encode_y_message(&YMessage::Awareness(AwarenessUpdate { clients })) - } - - #[test] - fn an_awareness_entry_at_the_maximum_clock_is_refused() { - let mut session = beside_a_guest(); - let states = awareness_entries(&[(41, u32::MAX, "{}"), (42, 1, "{}")]); - assert_eq!( - session.deliver(millis(2), &frame(&peer(), 0, 1, &states)), - Outcome::Applied { kind: 0 } - ); - assert_eq!( - session.awareness_clients(), - [42], - "the entry at the maximum is refused and the rest of the message applies" - ); - - // Nothing is held for 41, so its next publication is a first state whatever clock it - // carries, and the expiry has no clock at the maximum to step. - let first = awareness_entries(&[(41, 1, "{}")]); - let _ = session.deliver(millis(3), &frame(&peer(), 0, 2, &first)); - assert_eq!(session.awareness_clients(), [41, 42]); - session.tick(millis(3 + 900)); - assert!( - session.awareness_clients().is_empty(), - "the refused entry left no state and no stamp behind" - ); - } - - #[test] - fn the_messages_after_a_maximum_clock_entry_still_apply() { - let mut session = beside_a_guest(); - let mut plaintext = awareness_entries(&[(41, u32::MAX, "{}")]); - plaintext.extend(update_message("hello")); - assert_eq!( - session.deliver(millis(2), &frame(&peer(), 0, 1, &plaintext)), - Outcome::Applied { kind: 0 } - ); - assert_eq!(session.text("README.md"), "hello", "the stream went on"); - assert!( - session.awareness_clients().is_empty(), - "41 was not entered at the maximum" - ); - } - - #[test] - fn a_state_at_the_maximum_clock_never_reaches_the_expiry_tick() { - let mut session = beside_a_guest(); - let hostile = awareness_entries(&[(41, u32::MAX, "{}")]); - let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &hostile)); - - // `Awareness::remove_state` steps the clock of the state it drops, unchecked, so a state - // entered at the maximum would step past it here. Refused, there is nothing to step. - session.tick(millis(2 + 900)); - assert!(session.awareness_clients().is_empty(), "not held"); - assert_eq!(session.ending(), None, "the session goes on"); - } - - #[test] - fn a_removal_of_this_connections_own_id_at_the_maximum_clock_is_refused() { - let mut session = beside_a_guest(); - let own = session.awareness_client_id(); - // A peer publishes a state under the id this connection announced (§8.4). - let claimed = awareness_entries(&[(own, 1, "{}")]); - let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &claimed)); - assert_eq!(session.awareness_clients(), [own]); - - // §8.2: a removal for the receiver's own id is not applied, and the receiver takes the - // removal's clock plus one. At the maximum that step is the unchecked one, so the entry - // is refused instead and the state it named stands. - let hostile = awareness_entries(&[(own, u32::MAX, "null")]); - assert_eq!( - session.deliver(millis(3), &frame(&peer(), 0, 2, &hostile)), - Outcome::Applied { kind: 0 } - ); - assert_eq!(session.awareness_clients(), [own], "the state stands"); - - // The session goes on: a renewal above the clock the state actually holds is applied. - let renewed = awareness_entries(&[(own, 2, "{}")]); - let _ = session.deliver(millis(4), &frame(&peer(), 0, 3, &renewed)); - assert_eq!(session.awareness_clients(), [own]); - } - - #[test] - fn a_forgotten_awareness_state_stays_gone_and_its_neighbours_stay() { - let mut session = beside_a_guest(); - let states = awareness_message(&[41, 42], 1, "{\"cursor\":null}"); - let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &states)); - assert_eq!(session.awareness_clients(), [41, 42]); - - session.forget_awareness(41); - assert_eq!(session.awareness_clients(), [42]); - - // A copy of the old state still in flight is older than the removal. - let stale = awareness_message(&[41], 1, "{\"cursor\":null}"); - let _ = session.deliver(millis(3), &frame(&peer(), 0, 2, &stale)); - assert_eq!(session.awareness_clients(), [42], "no resurrection"); - } - - #[test] - fn forgetting_an_id_with_no_state_leaves_its_first_state_welcome() { - let mut session = beside_a_guest(); - session.forget_awareness(43); - let first = awareness_message(&[43], 1, "{}"); - let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &first)); - assert_eq!(session.awareness_clients(), [43]); - } - - #[test] - fn this_connections_own_awareness_id_is_never_forgotten() { - let mut session = beside_a_guest(); - let own = session.awareness_client_id(); - let states = awareness_message(&[own], 1, "{}"); - let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &states)); - assert_eq!(session.awareness_clients(), [own]); - session.forget_awareness(own); - assert_eq!(session.awareness_clients(), [own]); - } - - /// A sync Update whose one item is an `Any` opening `depth` one-element arrays inside one - /// another around a `null`. It is built by hand because no document holds such a value: - /// one client's group of one struct, client 1 at clock 0, an `Any` item (info 8) under the - /// root named `x` carrying one value, then an empty delete set. - fn nested_any_update(depth: usize) -> Vec { - let mut update = vec![1, 1, 1, 0, 8, 1, 1, b'x', 1]; - for _ in 0..depth { - update.extend([117, 1]); - } - update.extend([126, 0]); - encode_y_message(&YMessage::Sync(SyncMessage::Update(update))) - } - - #[test] - fn an_update_nested_past_any_stack_is_refused_and_the_session_goes_on() { - // Two bytes a level: a million levels is two megabytes, and no thread's stack holds a - // recursive reader that deep. - let mut session = beside_a_guest(); - let hostile = frame(&peer(), 0, 1, &nested_any_update(1 << 20)); - assert_eq!( - session.deliver(millis(2), &hostile), - Outcome::Dropped { - reason: "bad_payload".to_string() - } - ); - assert_eq!( - session.deliver(millis(3), &content(&peer(), 2, "after")), - Outcome::Applied { kind: 0 } - ); - assert_eq!(session.text("README.md"), "after"); - } - - #[test] - fn a_frame_carrying_a_nested_update_is_refused_whole() { - // The refusal is the frame's, before anything in it is applied: an edit ahead of the - // hostile update in the same stream is not applied either. - let mut session = beside_a_guest(); - let mut plaintext = update_message("hello"); - plaintext.extend(nested_any_update(MAX_ANY_DEPTH + 1)); - assert_eq!( - session.deliver(millis(2), &frame(&peer(), 0, 1, &plaintext)), - Outcome::Dropped { - reason: "bad_payload".to_string() - } - ); - assert_eq!(session.text("README.md"), ""); - } - - #[test] - fn an_update_nested_to_the_bound_is_applied() { - let mut session = beside_a_guest(); - let mut plaintext = nested_any_update(MAX_ANY_DEPTH); - plaintext.extend(update_message("hello")); - assert_eq!( - session.deliver(millis(2), &frame(&peer(), 0, 1, &plaintext)), - Outcome::Applied { kind: 0 } - ); - assert_eq!(session.text("README.md"), "hello"); - } - - fn invite(room: RoomKey, fragment: &str) -> String { - format!("/session?room={ROOM}&token=t-1#{fragment}") - .replace("$k", &encode_key(&[7; 32])) - .replace("$h", &host().public().encode()) - .replace("$room", &encode_key(&room.0)) - } - - #[test] - fn the_invite_carries_the_room_and_both_keys_and_the_fragment_is_stripped() { - let link = invite(room_key(), "k=$k&h=$h"); - let parsed = PeerInvite::parse(&link).unwrap(); - assert_eq!(parsed.room, ROOM); - assert_eq!(parsed.token, "t-1"); - assert_eq!(parsed.room_key, RoomKey([7; 32])); - assert_eq!(parsed.host_key, host().public()); - assert!(!parsed.socket_url.contains('#')); - } - - #[test] - fn an_invite_with_no_fragment_or_with_a_value_that_is_not_a_key_is_refused_locally() - { - let missing = format!("/session?room={ROOM}&token=t-1"); - assert!( - PeerInvite::parse(&missing) - .unwrap_err() - .contains("fragment") - ); - - let short = invite(room_key(), "k=AAAA&h=$h"); - assert!(PeerInvite::parse(&short).unwrap_err().contains("`k`")); - - let twice = invite(room_key(), "k=$k&k=$k&h=$h"); - assert!(PeerInvite::parse(&twice).unwrap_err().contains("twice")); - - // §6.1: the final character of a 32-byte value carries two zero bits, so a spelling - // whose last character is any other spells no key. - let uncanonical = invite(room_key(), "k=$kB&h=$h"); - assert!(PeerInvite::parse(&uncanonical).unwrap_err().contains("`k`")); - - let no_host = invite(room_key(), "k=$k"); - assert!(PeerInvite::parse(&no_host).unwrap_err().contains("`h`")); - } - - /// §5.1: the fragment's two keys are read to be used, never repeated. A `Debug` that - /// printed them would put both in whatever log an invite — or the options a session is - /// built from — is written to, which is the one thing the fragment exists to prevent. - #[test] - fn the_invites_keys_are_not_printed_by_debug() { - let room_key = room_key(); - let host_key = host().public(); - let parsed = PeerInvite::parse(&invite(room_key, "k=$k&h=$h")).unwrap(); - let printed = format!("{parsed:?}"); - assert!( - !printed.contains(&format!("{room_key:?}")), - "the room key was printed: {printed}" - ); - assert!( - !printed.contains(&format!("{host_key:?}")), - "the host key was printed: {printed}" - ); - // A `Debug` that printed a key in the encoding §5.1's fragment carries it in is a key - // printed, and neither `Debug` spelling above is that string: the value itself is the - // needle that reaches it. - assert!( - !printed.contains(&encode_key(&room_key.0)) - && !printed.contains(&host_key.encode()), - "the encoded form of a key the invite holds was printed: {printed}" - ); - - let options = PeerOptions { - room_id: ROOM.to_string(), - room_key, - host_key, - renew: Duration::from_millis(300), - expire: Duration::from_millis(900), - seat: Some("p-self".to_string()), - roster: BTreeSet::new(), - fixed_session_key: Some([5; 32]), - declared_role: None, - awareness_client_id: None, - host: None, - frame_budget: None, - }; - let printed = format!("{options:?}"); - assert!( - !printed.contains(&format!("{room_key:?}")) - && !printed.contains(&format!("{host_key:?}")), - "a key the options hold was printed: {printed}" - ); - assert!( - !printed.contains(&encode_key(&room_key.0)) - && !printed.contains(&host_key.encode()), - "the encoded form of a key the options hold was printed: {printed}" - ); - } - - #[test] - fn the_page_link_is_the_same_room_token_and_fragment_over_the_browsers_scheme() - { - // `PROTOCOL.md` §5.1's second form: the page the room's server serves, over the scheme - // a browser speaks, with the same host, port and path prefix and nothing else in it. - let room = encode_key(&room_key().0); - let host_key = host().public().encode(); - let page = - format!("http://h:8080/?room={ROOM}&token=t-1#k={room}&h={host_key}"); - let wire = format!("ws://h:8080/session?room={ROOM}&token=t-1"); - assert_eq!( - wire_address(&page), - wire, - "the page reads back as the same connection address, fragment left off" - ); - // §5.1: the fragment is the one part a request never carries, so the address is the - // whole of what `wire_address` hands back however it is called. Re-appending the - // fragment and handing the result to `parse_session_url` would glue `k` onto `token` - // and put the room key in the URL a socket is dialled on. - let door = wire_address(&page); - assert!( - !door.contains('#') - && !door.contains(&room) - && !door.contains(&host_key), - "no key byte and no fragment survives the address reading: {door}" - ); - assert_eq!( - proto::parse_session_url(&door) - .unwrap() - .join - .token - .as_deref(), - Some("t-1"), - "the token stays the query's own, nothing glued onto it" - ); - let parsed = PeerInvite::parse(&page).unwrap(); - assert_eq!( - parsed.socket_url, wire, - "and the address a socket is opened on carries no fragment" - ); - assert_eq!(parsed.room, ROOM); - assert_eq!(parsed.token, "t-1"); - assert_eq!(parsed.room_key, room_key()); - assert_eq!(parsed.host_key, host().public()); - - // A path prefix survives the reading: the page is served under it and the endpoint is - // under it too. - let mounted = - format!("https://h/page/?room={ROOM}&token=t-1#k={room}&h={host_key}"); - assert_eq!( - PeerInvite::parse(&mounted).unwrap().socket_url, - format!("wss://h/page/session?room={ROOM}&token=t-1") - ); - - // A link that is already a connection URL is handed back exactly as it stands. - assert_eq!(wire_address(&wire), wire); - assert!( - PeerInvite::parse(&wire).unwrap_err().contains("fragment"), - "a connection URL still carries no fragment" - ); - // And one this cannot read as either form is not silently rewritten. - assert_eq!(wire_address("wss://h/other?room=r"), "wss://h/other?room=r"); - } - - /// §5.1: `room` and `token` each appear at most once, in either form. A page link has no - /// server in it, so the receiver refuses a repeat itself and names the parameter — the shape - /// the fragment's rule already takes for `k` and `h` — rather than reporting that the address - /// names no endpoint, which is what the reader of the old message was told. - #[test] - fn a_page_link_that_repeats_a_join_key_is_refused_by_name() { - let room = encode_key(&room_key().0); - let host_key = host().public().encode(); - let twice_room = format!( - "https://h/?room=r-1&room=r-other&token=t-1#k={room}&h={host_key}" - ); - assert_eq!( - PeerInvite::parse(&twice_room).unwrap_err(), - "the invite names `room` twice" - ); - let twice_token = format!( - "https://h/?room=r-1&token=t-1&token=t-other#k={room}&h={host_key}" - ); - assert_eq!( - PeerInvite::parse(&twice_token).unwrap_err(), - "the invite names `token` twice" - ); - // The `wss://` form is read through the same query rule and names the repeat too. - let wire_repeat = format!( - "wss://h/session?room=r-1&room=r-other&token=t-1#k={room}&h={host_key}" - ); - assert_eq!( - PeerInvite::parse(&wire_repeat).unwrap_err(), - "the invite names `room` twice" - ); - // A link that genuinely names no endpoint keeps the generic refusal: a repeat is not - // what is wrong with it. - let elsewhere = - format!("wss://h/other?room=r-1&token=t-1#k={room}&h={host_key}"); - assert_eq!( - PeerInvite::parse(&elsewhere).unwrap_err(), - "\"wss://h/other?room=r-1&token=t-1\" does not address the session endpoint" - ); - } - - // --- §13.6: the bounded reciprocal request, the shared clock and local readiness ----- - - #[test] - fn a_committed_writers_first_request_arms_one_coalesced_reciprocal_request() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - let committing = state( - &host(), - 1, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - session.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - // The immediate initial request: the clock every later request is measured from. - let initial = session.take_outbound(); - assert_eq!(initial.len(), 1); - assert_eq!(sync_subtype(&initial[0]), Some(0)); - - // The first `SyncStep1` from a committed writer is answered and remembered. - assert_eq!( - session.deliver(millis(2), &frame(&peer(), 0, 1, &step1())), - Outcome::Applied { kind: 0 } - ); - let answer = session.take_outbound(); - assert_eq!(answer.len(), 1, "one Step2 for the request"); - assert_eq!(sync_subtype(&answer[0]), Some(1)); - - // The request clock is 1, so the window opens at 301. - session.tick(millis(300)); - assert!(session.take_outbound().is_empty(), "not before the clock"); - session.tick(millis(301)); - let reciprocal = session.take_outbound(); - assert_eq!(reciprocal.len(), 1, "one coalesced reciprocal request"); - assert_eq!(sync_subtype(&reciprocal[0]), Some(0)); - - // A later request from the same continuously eligible key draws its Step2 only. - assert_eq!( - session.deliver(millis(302), &frame(&peer(), 0, 2, &step1())), - Outcome::Applied { kind: 0 } - ); - let again = session.take_outbound(); - assert_eq!(again.len(), 1, "one Step2 per inbound frame"); - assert_eq!(sync_subtype(&again[0]), Some(1)); - session.tick(millis(601)); - session.tick(millis(901)); - assert!( - session.take_outbound().is_empty(), - "the served census stops the echo" - ); - } - - #[test] - fn a_viewers_request_does_not_arm_a_reciprocal_request() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - let committing = state( - &host(), - 1, - &[ - (&ours(), "guest", "p-self"), - (&peer(), "viewer", "p-viewer"), - ], - ); - assert_eq!( - session.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert_eq!( - session.deliver(millis(2), &frame(&peer(), 0, 1, &step1())), - Outcome::Applied { kind: 0 } - ); - let answer = session.take_outbound(); - assert_eq!(answer.len(), 1); - assert_eq!(sync_subtype(&answer[0]), Some(1), "the request is answered"); - session.tick(millis(302)); - session.tick(millis(602)); - assert!( - session.take_outbound().is_empty(), - "a viewer sends no content, so there is nothing to ask for" - ); - } - - #[test] - fn a_step2_or_update_never_arms_a_reciprocal_request() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - let committing = state( - &host(), - 1, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - session.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert_eq!( - session.deliver(millis(2), &content(&peer(), 1, "theirs")), - Outcome::Applied { kind: 0 } - ); - assert_eq!( - session.deliver(millis(3), &content(&peer(), 2, "more")), - Outcome::Applied { kind: 0 } - ); - session.tick(millis(303)); - session.tick(millis(603)); - assert!( - session.take_outbound().is_empty(), - "content never asks for a request" - ); - } - - #[test] - fn several_new_writer_keys_in_one_window_draw_one_broadcast_request() { - let mut session = session(&[]); - let third = SessionKey::from_seed([17; 32]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - let committing = state( - &host(), - 1, - &[ - (&ours(), "guest", "p-self"), - (&peer(), "guest", "p-other"), - (&third, "guest", "p-third"), - ], - ); - assert_eq!( - session.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert_eq!( - session.deliver(millis(2), &frame(&peer(), 0, 1, &step1())), - Outcome::Applied { kind: 0 } - ); - assert_eq!( - session.deliver(millis(3), &frame(&third, 0, 1, &step1())), - Outcome::Applied { kind: 0 } - ); - let answers = session.take_outbound(); - assert_eq!(answers.len(), 2, "each request is answered"); - session.tick(millis(303)); - let requests = session.take_outbound(); - assert_eq!(requests.len(), 1, "the two new keys coalesce"); - assert_eq!(sync_subtype(&requests[0]), Some(0)); - } - - #[test] - fn a_valid_request_prefix_survives_a_malformed_suffix() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - let committing = state( - &host(), - 1, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - session.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - let mut plaintext = step1(); - plaintext.extend_from_slice(&[0, 0, 1, 128]); - assert_eq!( - session.deliver(millis(2), &frame(&peer(), 0, 1, &plaintext)), - Outcome::Applied { kind: 0 } - ); - let answer = session.take_outbound(); - assert_eq!(answer.len(), 1, "the valid prefix is answered"); - assert_eq!(sync_subtype(&answer[0]), Some(1)); - session.tick(millis(301)); - let request = session.take_outbound(); - assert_eq!(request.len(), 1, "the valid prefix still owes readiness"); - assert_eq!(sync_subtype(&request[0]), Some(0)); - } - - #[test] - fn a_malformed_first_message_arms_nothing_and_a_later_valid_request_does() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - let committing = state( - &host(), - 1, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - session.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert_eq!( - session.deliver(millis(2), &frame(&peer(), 0, 1, &[0, 0, 1, 128])), - Outcome::Applied { kind: 0 } - ); - assert!( - session.take_outbound().is_empty(), - "an invalid first message is not answered" - ); - session.tick(millis(300)); - assert!( - session.take_outbound().is_empty(), - "a malformed request must not arm readiness" - ); - assert_eq!( - session.deliver(millis(301), &frame(&peer(), 0, 2, &step1())), - Outcome::Applied { kind: 0 } - ); - let answer = session.take_outbound(); - assert_eq!(answer.len(), 1); - assert_eq!(sync_subtype(&answer[0]), Some(1)); - session.tick(millis(601)); - let request = session.take_outbound(); - assert_eq!(request.len(), 1, "the valid request armed the obligation"); - assert_eq!(sync_subtype(&request[0]), Some(0)); - } - - #[test] - fn a_local_reentry_after_absence_owes_one_coalesced_readiness_request() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - let first = state(&host(), 1, &[(&ours(), "guest", "p-self")]); - assert_eq!( - session.deliver(millis(1), &first), - Outcome::Applied { kind: 1 } - ); - let initial = session.take_outbound(); - assert_eq!( - initial.len(), - 1, - "the first commitment owes the initial request" - ); - assert_eq!(sync_subtype(&initial[0]), Some(0)); - session.tick(millis(2)); - assert!( - session.take_outbound().is_empty(), - "the first commitment adds no readiness" - ); - - // The key is dropped, then recommitted as a writer: a new continuous eligibility. - assert_eq!( - session.deliver(millis(3), &state(&host(), 2, &[])), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert_eq!( - session.deliver( - millis(4), - &state(&host(), 3, &[(&ours(), "guest", "p-self")]) - ), - Outcome::Applied { kind: 1 } - ); - assert!( - session.take_outbound().is_empty(), - "a state cannot send renewed readiness immediately" - ); - session.tick(millis(300)); - assert!(session.take_outbound().is_empty(), "not before the clock"); - session.tick(millis(301)); - let readiness = session.take_outbound(); - assert_eq!(readiness.len(), 1); - assert_eq!(sync_subtype(&readiness[0]), Some(0)); - session.tick(millis(601)); - session.tick(millis(901)); - assert!( - session.take_outbound().is_empty(), - "readiness is served once per eligibility" - ); - } - - #[test] - fn an_uninterrupted_writer_eligibility_and_listing_editions_never_rearm() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - let first = state( - &host(), - 1, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - session.deliver(millis(1), &first), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - let changed = state( - &host(), - 2, - &[(&ours(), "host", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - session.deliver(millis(2), &changed), - Outcome::Applied { kind: 1 } - ); - let listing = state_listing( - &host(), - 3, - &[(&ours(), "host", "p-self"), (&peer(), "guest", "p-other")], - &["README.md", "other.md"], - ); - assert_eq!( - session.deliver(millis(3), &listing), - Outcome::Applied { kind: 1 } - ); - assert!( - session.take_outbound().is_empty(), - "a host/guest change and a listing edition owe nothing" - ); - session.tick(millis(301)); - assert!( - session.take_outbound().is_empty(), - "uninterrupted eligibility never rearms" - ); - } - - #[test] - fn local_readiness_retires_when_writer_eligibility_ends_before_service() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - assert_eq!( - session.deliver( - millis(1), - &state(&host(), 1, &[(&ours(), "guest", "p-self")]) - ), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - // Re-entry arms readiness, then eligibility ends before the window opens. - assert_eq!( - session.deliver(millis(2), &state(&host(), 2, &[])), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert_eq!( - session.deliver( - millis(3), - &state(&host(), 3, &[(&ours(), "guest", "p-self")]) - ), - Outcome::Applied { kind: 1 } - ); - assert_eq!( - session.deliver( - millis(4), - &state(&host(), 4, &[(&ours(), "viewer", "p-self")]) - ), - Outcome::Applied { kind: 1 } - ); - assert!(session.take_outbound().is_empty()); - session.tick(millis(301)); - assert!( - session.take_outbound().is_empty(), - "retired readiness must not be served" - ); - } - - #[test] - fn a_remote_demotion_and_re_promotion_rearms_exactly_one_request() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - let first = state( - &host(), - 1, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - session.deliver(millis(1), &first), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert_eq!( - session.deliver(millis(2), &frame(&peer(), 0, 1, &step1())), - Outcome::Applied { kind: 0 } - ); - let _ = session.take_outbound(); - session.tick(millis(301)); - let armed = session.take_outbound(); - assert_eq!(armed.len(), 1, "the first eligibility armed once"); - assert_eq!(sync_subtype(&armed[0]), Some(0)); - - // The peer is demoted, so its census entry goes; re-promotion arms once more. - let demoted = state( - &host(), - 2, - &[(&ours(), "guest", "p-self"), (&peer(), "viewer", "p-other")], - ); - assert_eq!( - session.deliver(millis(302), &demoted), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - let promoted = state( - &host(), - 3, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - session.deliver(millis(303), &promoted), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert_eq!( - session.deliver(millis(304), &frame(&peer(), 0, 2, &step1())), - Outcome::Applied { kind: 0 } - ); - let _ = session.take_outbound(); - session.tick(millis(601)); - let rearmed = session.take_outbound(); - assert_eq!(rearmed.len(), 1, "the new eligibility armed once"); - assert_eq!(sync_subtype(&rearmed[0]), Some(0)); - } - /// §13.6: activation is the remote writer's eligibility, so a request is recorded even while - /// this connection is uncommitted and may not publish; the shared clock then serves it once - /// the local key can publish again. Gating activation on local commitment would drop it. - #[test] - fn a_remote_request_arms_while_uncommitted_and_is_served_after_recommitment() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - // L is committed as a viewer and takes the initial request: the clock later ones use. - assert_eq!( - session.deliver(millis(1), &viewer_beside_writer(1)), - Outcome::Applied { kind: 1 } - ); - let initial = session.take_outbound(); - assert_eq!( - initial.len(), - 1, - "a committed viewer still takes the initial request" - ); - assert_eq!(sync_subtype(&initial[0]), Some(0)); - - // A newer state drops L while W stays a committed writer, so L cannot publish at all. - assert_eq!( - session.deliver( - millis(2), - &state(&host(), 2, &[(&peer(), "guest", "p-other")]) - ), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - - // W's first valid request in this eligibility is recognised though L is uncommitted. - assert_eq!( - session.deliver(millis(3), &frame(&peer(), 0, 1, &step1())), - Outcome::Applied { kind: 0 } - ); - assert!( - session.take_outbound().is_empty(), - "an uncommitted receiver answers nothing" - ); - - // L is recommitted as a viewer with W retained: the remote cause survives the local gate. - assert_eq!( - session.deliver(millis(4), &viewer_beside_writer(3)), - Outcome::Applied { kind: 1 } - ); - assert!( - session.take_outbound().is_empty(), - "a state cannot send the request immediately" - ); - session.tick(millis(300)); - assert!(session.take_outbound().is_empty(), "not before the clock"); - session.tick(millis(301)); - let served = session.take_outbound(); - assert_eq!( - served.len(), - 1, - "the remote request is served once at the due tick" - ); - assert_eq!(sync_subtype(&served[0]), Some(0)); - - // Served once: a continuously committed key does not rearm over later windows. - session.tick(millis(601)); - session.tick(millis(901)); - assert!( - session.take_outbound().is_empty(), - "a served remote eligibility does not rearm" - ); - } - - /// The companion: a request whose writer is removed or demoted before the local key returns - /// is retired with that writer's eligibility, so no request is owed. - #[test] - fn a_remote_request_for_a_key_that_leaves_before_the_return_owes_nothing() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - assert_eq!( - session.deliver( - millis(1), - &state( - &host(), - 1, - &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")] - ) - ), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert_eq!( - session.deliver( - millis(2), - &state(&host(), 2, &[(&peer(), "guest", "p-other")]) - ), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert_eq!( - session.deliver(millis(3), &frame(&peer(), 0, 1, &step1())), - Outcome::Applied { kind: 0 } - ); - let _ = session.take_outbound(); - - // W is demoted before L comes back: the obligation retires with its eligibility. - assert_eq!( - session.deliver( - millis(4), - &state( - &host(), - 3, - &[ - (&ours(), "viewer", "p-self"), - (&peer(), "viewer", "p-other") - ] - ) - ), - Outcome::Applied { kind: 1 } - ); - assert!(session.take_outbound().is_empty()); - session.tick(millis(301)); - session.tick(millis(601)); - assert!( - session.take_outbound().is_empty(), - "a retired request owes nothing" - ); - } - - /// Retiring a remote cause must not erase the refusal interval or local readiness sharing the - /// same clock: one request serves every remaining obligation. - #[test] - fn a_retired_remote_request_leaves_the_refusal_and_readiness_causes() { - let mut session = session(&[]); - let unmoved = SessionKey::from_seed([23; 32]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - assert_eq!( - session.deliver( - millis(1), - &state( - &host(), - 1, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")] - ) - ), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert_eq!( - session.deliver( - millis(2), - &state(&host(), 2, &[(&peer(), "guest", "p-other")]) - ), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - // W's request arms the remote cause. - assert_eq!( - session.deliver(millis(3), &frame(&peer(), 0, 1, &step1())), - Outcome::Applied { kind: 0 } - ); - let _ = session.take_outbound(); - // A content frame from a key no state commits opens §13.6's refusal interval. - assert_eq!( - session.deliver(millis(4), &content(&unmoved, 1, "theirs")), - Outcome::Dropped { - reason: "uncommitted_key".to_string() - } - ); - // L returns as a writer and W is demoted: the remote cause retires, a new eligibility - // begins for L, and the refusal interval is still open. - assert_eq!( - session.deliver( - millis(5), - &state( - &host(), - 3, - &[(&ours(), "guest", "p-self"), (&peer(), "viewer", "p-other")] - ) - ), - Outcome::Applied { kind: 1 } - ); - assert!(session.take_outbound().is_empty()); - session.tick(millis(300)); - assert!(session.take_outbound().is_empty(), "not before the clock"); - session.tick(millis(301)); - let served = session.take_outbound(); - assert_eq!( - served.len(), - 1, - "refusal and readiness survive the retired remote cause" - ); - assert_eq!(sync_subtype(&served[0]), Some(0)); - } - - #[test] - fn a_viewers_local_edits_never_enter_room_history() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - let as_viewer = state( - &host(), - 1, - &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - session.deliver(millis(1), &as_viewer), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert!(!session.insert("README.md", 0, "secret").unwrap()); - assert_eq!( - session.text("README.md"), - "", - "the disallowed edit is not even locally visible" - ); - assert!(session.take_outbound().is_empty()); - - // Promotion with the same key: the request is answered from room-safe history alone. - let as_writer = state( - &host(), - 2, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - session.deliver(millis(2), &as_writer), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert_eq!( - session.deliver(millis(3), &frame(&peer(), 0, 1, &step1())), - Outcome::Applied { kind: 0 } - ); - let answer = session.take_outbound(); - assert_eq!(answer.len(), 1); - assert_eq!(sync_subtype(&answer[0]), Some(1)); - assert_eq!( - step2_text(&answer[0]), - "", - "no viewer history is exported on promotion" - ); - } - - #[test] - fn an_unknown_role_edit_is_discarded_when_a_viewer_state_arrives() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - assert!( - !session.insert("README.md", 0, "spec").unwrap(), - "held while the role is unknown" - ); - assert_eq!( - session.text("README.md"), - "spec", - "held locally while unknown" - ); - let as_viewer = state( - &host(), - 1, - &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - session.deliver(millis(1), &as_viewer), - Outcome::Applied { kind: 1 } - ); - assert_eq!( - session.text("README.md"), - "", - "the viewer state discards the speculative edit" - ); - let _ = session.take_outbound(); - - // Re-promotion: the discarded edit never returns. - let as_writer = state( - &host(), - 2, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - session.deliver(millis(2), &as_writer), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert_eq!( - session.deliver(millis(3), &frame(&peer(), 0, 1, &step1())), - Outcome::Applied { kind: 0 } - ); - let answer = session.take_outbound(); - assert_eq!(answer.len(), 1); - assert_eq!( - step2_text(&answer[0]), - "", - "the discarded edit never returns" - ); - } - - #[test] - fn a_demoted_writer_keeps_its_history_and_exports_no_viewer_edit() { - let mut session = session(&[]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - let as_writer = state( - &host(), - 1, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - session.deliver(millis(1), &as_writer), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert!(session.insert("README.md", 0, "legit").unwrap()); - let _ = session.take_outbound(); - - let as_viewer = state( - &host(), - 2, - &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - session.deliver(millis(2), &as_viewer), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert!(!session.insert("README.md", 5, "bad").unwrap()); - assert_eq!( - session.text("README.md"), - "legit", - "the viewer edit is discarded" - ); - - // Promotion: the writer history survives and is exported. - let promoted = state( - &host(), - 3, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - session.deliver(millis(3), &promoted), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert_eq!( - session.deliver(millis(4), &frame(&peer(), 0, 1, &step1())), - Outcome::Applied { kind: 0 } - ); - let answer = session.take_outbound(); - assert_eq!(answer.len(), 1); - assert_eq!( - step2_text(&answer[0]), - "legit", - "the writer history is preserved" - ); - } - - #[test] - fn three_writer_requests_coalesce_and_the_room_quiesces() { - let mut session = session(&[]); - let third = SessionKey::from_seed([17; 32]); - session.tick(Duration::ZERO); - let _ = session.take_outbound(); - let committing = state( - &host(), - 1, - &[ - (&ours(), "guest", "p-self"), - (&peer(), "guest", "p-other"), - (&third, "guest", "p-third"), - ], - ); - assert_eq!( - session.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - let _ = session.take_outbound(); - assert_eq!( - session.deliver(millis(2), &frame(&peer(), 0, 1, &step1())), - Outcome::Applied { kind: 0 } - ); - assert_eq!( - session.deliver(millis(3), &frame(&third, 0, 1, &step1())), - Outcome::Applied { kind: 0 } - ); - let answers = session.take_outbound(); - assert_eq!(answers.len(), 2, "each request draws its own Step2"); - session.tick(millis(303)); - let request = session.take_outbound(); - assert_eq!(request.len(), 1, "one coalesced request for both keys"); - assert_eq!(sync_subtype(&request[0]), Some(0)); - // No obligation left, so later windows are silent. - session.tick(millis(603)); - session.tick(millis(903)); - session.tick(millis(1203)); - assert!( - session.take_outbound().is_empty(), - "no periodic full sync without an obligation" - ); - } - /// One round of a three-peer room: each session hears the other two's frames, answers each - /// with exactly one Step2, and arms nothing new. - /// The two frames one session hears in a three-peer round. - type Heard<'a> = [&'a [u8]; 2]; - - fn three_way_round( - trio: [&mut PeerSession; 3], - clock: Duration, - heard: [Heard<'_>; 3], - ) { - for (peer, [first, second]) in trio.into_iter().zip(heard) { - assert_eq!(peer.deliver(clock, first), Outcome::Applied { kind: 0 }); - assert_eq!(peer.deliver(clock, second), Outcome::Applied { kind: 0 }); - let answers = peer.take_outbound(); - assert_eq!(answers.len(), 2, "each request draws one Step2"); - assert!(answers.iter().all(|frame| sync_subtype(frame) == Some(1))); - } - } - - /// Three real sessions, each with its own replica and key: every pair's reciprocal exchange - /// is bounded, one coalesced request per session per window, and the room falls quiet. The - /// older three-writer test drives one receiver and two signers, which is a census bound and - /// not an all-room one. - #[test] - #[expect( - clippy::too_many_lines, - reason = "the three-peer exchange, its bounded counts and the quiet windows are one sequence" - )] - fn three_real_sessions_exchange_reciprocally_and_then_quiesce() { - let mut alpha = session(&["p-other", "p-third"]); - let mut beta = second_session(&["p-self", "p-third"]); - let mut gamma = third_session(&["p-self", "p-other"]); - for peer in [&mut alpha, &mut beta, &mut gamma] { - peer.tick(Duration::ZERO); - let _ = peer.take_outbound(); - } - let committing = state( - &host(), - 1, - &[ - (&ours(), "guest", "p-self"), - (&peer(), "guest", "p-other"), - (&third(), "guest", "p-third"), - ], - ); - let mut initial = Vec::new(); - for peer in [&mut alpha, &mut beta, &mut gamma] { - assert_eq!( - peer.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - let frames = peer.take_outbound(); - assert_eq!( - frames.len(), - 1, - "the first commitment owes one initial request" - ); - assert_eq!(sync_subtype(&frames[0]), Some(0)); - initial.push(frames[0].clone()); - } - three_way_round( - [&mut alpha, &mut beta, &mut gamma], - millis(2), - [ - [initial[1].as_slice(), initial[2].as_slice()], - [initial[0].as_slice(), initial[2].as_slice()], - [initial[0].as_slice(), initial[1].as_slice()], - ], - ); - // One coalesced request per session at the shared clock, not one per writer key. - let mut requests = Vec::new(); - for peer in [&mut alpha, &mut beta, &mut gamma] { - peer.tick(millis(300)); - assert!(peer.take_outbound().is_empty(), "not before the clock"); - peer.tick(millis(301)); - let frames = peer.take_outbound(); - assert_eq!( - frames.len(), - 1, - "the two obligations coalesce into one request" - ); - assert_eq!(sync_subtype(&frames[0]), Some(0)); - requests.push(frames[0].clone()); - } - three_way_round( - [&mut alpha, &mut beta, &mut gamma], - millis(302), - [ - [requests[1].as_slice(), requests[2].as_slice()], - [requests[0].as_slice(), requests[2].as_slice()], - [requests[0].as_slice(), requests[1].as_slice()], - ], - ); - // One session's edit reaches the other two; all three replicas agree and nothing replies. - assert!(alpha.insert("README.md", 0, "x").unwrap()); - let edit = alpha.take_outbound(); - assert_eq!(edit.len(), 1, "the edit publishes"); - assert_eq!( - beta.deliver(millis(303), &edit[0]), - Outcome::Applied { kind: 0 } - ); - assert_eq!( - gamma.deliver(millis(303), &edit[0]), - Outcome::Applied { kind: 0 } - ); - assert!( - beta.take_outbound().is_empty() && gamma.take_outbound().is_empty(), - "content draws no reply" - ); - assert_eq!(alpha.state_vector(), beta.state_vector()); - assert_eq!(beta.state_vector(), gamma.state_vector()); - - for peer in [&mut alpha, &mut beta, &mut gamma] { - peer.tick(millis(601)); - peer.tick(millis(901)); - peer.tick(millis(1201)); - assert!( - peer.take_outbound().is_empty(), - "no periodic full sync without an obligation" - ); - } - } - - /// A retained same-key session keeps its replica through an omission and recommitment, owes - /// one renewed readiness request, and keeps editing on that same replica. - #[test] - fn a_recommitted_same_key_retains_its_replica_and_keeps_editing() { - let mut writer = session(&["p-other"]); - let mut receiver = second_session(&["p-self"]); - writer.tick(Duration::ZERO); - receiver.tick(Duration::ZERO); - let _ = writer.take_outbound(); - let _ = receiver.take_outbound(); - let committing = state( - &host(), - 1, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - writer.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - assert_eq!( - receiver.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - let _ = writer.take_outbound(); - let _ = receiver.take_outbound(); - - // The receiver edits as a committed writer; the writer applies that history. - assert!(receiver.insert("README.md", 0, "abc").unwrap()); - let edit = receiver.take_outbound(); - assert_eq!(edit.len(), 1); - assert_eq!( - writer.deliver(millis(2), &edit[0]), - Outcome::Applied { kind: 0 } - ); - assert_eq!(receiver.state_vector(), writer.state_vector()); - let vector = receiver.state_vector(); - - // The receiver's key is dropped, then recommitted under the same key. - let omitted = state(&host(), 2, &[(&ours(), "guest", "p-self")]); - assert_eq!( - receiver.deliver(millis(3), &omitted), - Outcome::Applied { kind: 1 } - ); - let _ = receiver.take_outbound(); - let recommitted = state( - &host(), - 3, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - receiver.deliver(millis(4), &recommitted), - Outcome::Applied { kind: 1 } - ); - assert!( - receiver.take_outbound().is_empty(), - "a state cannot send the renewed readiness immediately" - ); - // The retained replica is untouched by the omission and recommitment. - assert_eq!(receiver.text("README.md"), "abc"); - assert_eq!(receiver.state_vector(), vector); - - receiver.tick(millis(300)); - assert!(receiver.take_outbound().is_empty(), "not before the clock"); - receiver.tick(millis(301)); - let readiness = receiver.take_outbound(); - assert_eq!( - readiness.len(), - 1, - "recommitment owes one readiness request" - ); - assert_eq!(sync_subtype(&readiness[0]), Some(0)); - assert!(receiver.insert("README.md", 3, "d").unwrap()); - assert_eq!( - receiver.take_outbound().len(), - 1, - "the continued edit publishes" - ); - assert_eq!(receiver.text("README.md"), "abcd"); - } - - /// Two real sessions, one lost `Update`: the reciprocal request carries the missing struct - /// back and the replicas converge with no further edit, no new key and no refusal. - #[test] - fn a_lost_update_is_recovered_by_the_reciprocal_request() { - let mut writer = session(&["p-other"]); - let mut receiver = second_session(&["p-self"]); - writer.tick(Duration::ZERO); - receiver.tick(Duration::ZERO); - let _ = writer.take_outbound(); - let _ = receiver.take_outbound(); - let committing = state( - &host(), - 1, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - writer.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - assert_eq!( - receiver.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - let writer_initial = writer.take_outbound(); - let _ = receiver.take_outbound(); - assert_eq!(writer_initial.len(), 1); - - // The receiver sees the writer's request and arms one reciprocal obligation. - assert_eq!( - receiver.deliver(millis(2), &writer_initial[0]), - Outcome::Applied { kind: 0 } - ); - let _ = receiver.take_outbound(); - - // The writer inserts, and the frame carrying the first insertion is lost on the way. - assert!(writer.insert("README.md", 0, "off ").unwrap()); - let lost = writer.take_outbound(); - assert_eq!(lost.len(), 1); - // A second, dependent insertion is delivered: the receiver holds it pending. - assert!(writer.insert("README.md", 0, "on ").unwrap()); - let dependent = writer.take_outbound(); - assert_eq!(dependent.len(), 1); - assert_eq!( - receiver.deliver(millis(3), &dependent[0]), - Outcome::Applied { kind: 0 } - ); - assert_eq!( - receiver.text("README.md"), - "", - "the dependent insertion waits for its dependency" - ); - - // The reciprocal request recovers the missing history without a new edit or key. - receiver.tick(millis(302)); - let request = receiver.take_outbound(); - assert_eq!(request.len(), 1, "one coalesced reciprocal request"); - assert_eq!(sync_subtype(&request[0]), Some(0)); - assert_eq!( - writer.deliver(millis(303), &request[0]), - Outcome::Applied { kind: 0 } - ); - let repair = writer.take_outbound(); - let step2 = repair - .iter() - .find(|frame| sync_subtype(frame.as_slice()) == Some(1)) - .expect("the writer answers the request with a Step2"); - assert_eq!( - receiver.deliver(millis(304), step2), - Outcome::Applied { kind: 0 } - ); - assert_eq!( - receiver.text("README.md"), - "on off ", - "the lost insertion returns" - ); - assert_eq!(writer.text("README.md"), "on off "); - assert_eq!( - writer.state_vector(), - receiver.state_vector(), - "the replicas converge" - ); - } - - /// The same two sessions, one lost deletion: a deletion is not a struct, so the state - /// vectors already agree while the texts differ; the reciprocal request carries the whole - /// delete set back and the texts converge. - #[test] - #[expect( - clippy::too_many_lines, - reason = "the whole loss and repair is one sequence and is clearer unsplit" - )] - fn a_lost_deletion_is_recovered_by_the_reciprocal_request() { - let mut writer = session(&[]); - let mut receiver = second_session(&[]); - let third = SessionKey::from_seed([19; 32]); - writer.tick(Duration::ZERO); - receiver.tick(Duration::ZERO); - let _ = writer.take_outbound(); - let _ = receiver.take_outbound(); - let committing = state( - &host(), - 1, - &[ - (&ours(), "guest", "p-self"), - (&peer(), "guest", "p-other"), - (&third, "guest", "p-third"), - ], - ); - assert_eq!( - writer.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - assert_eq!( - receiver.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - let writer_initial = writer.take_outbound(); - let _ = receiver.take_outbound(); - // Arm the receiver's reciprocal obligation. - assert_eq!( - receiver.deliver(millis(2), &writer_initial[0]), - Outcome::Applied { kind: 0 } - ); - let _ = receiver.take_outbound(); - - // A third key inserts "abc"; both replicas apply it. - let source = Doc::new(); - let handle = source.get_or_insert_text("README.md"); - { - let mut txn = source.transact_mut(); - handle.insert(&mut txn, 0, "abc"); - } - let inserted = { - let txn = source.transact(); - txn.encode_state_as_update_v1(&StateVector::default()) - }; - let insert_frame = frame( - &third, - 0, - 1, - &encode_y_message(&YMessage::Sync(SyncMessage::Update(inserted))), - ); - assert_eq!( - writer.deliver(millis(3), &insert_frame), - Outcome::Applied { kind: 0 } - ); - assert_eq!( - receiver.deliver(millis(3), &insert_frame), - Outcome::Applied { kind: 0 } - ); - assert_eq!(writer.text("README.md"), "abc"); - assert_eq!(receiver.text("README.md"), "abc"); - - // The third key deletes `b`; only the writer receives that update. - let before = { - let txn = source.transact(); - txn.state_vector() - }; - { - let mut txn = source.transact_mut(); - handle.remove_range(&mut txn, 1, 1); - } - let deletion = { - let txn = source.transact(); - txn.encode_state_as_update_v1(&before) - }; - let delete_frame = frame( - &third, - 0, - 2, - &encode_y_message(&YMessage::Sync(SyncMessage::Update(deletion))), - ); - assert_eq!( - writer.deliver(millis(4), &delete_frame), - Outcome::Applied { kind: 0 } - ); - assert_eq!(writer.text("README.md"), "ac"); - assert_eq!(receiver.text("README.md"), "abc", "the deletion was lost"); - // A deletion is not a struct, so the vectors agree before the repair. - assert_eq!(writer.state_vector(), receiver.state_vector()); - - // The reciprocal request carries the whole delete set back. - receiver.tick(millis(302)); - let request = receiver.take_outbound(); - assert_eq!(request.len(), 1, "one coalesced reciprocal request"); - assert_eq!(sync_subtype(&request[0]), Some(0)); - assert_eq!( - writer.deliver(millis(303), &request[0]), - Outcome::Applied { kind: 0 } - ); - let repair = writer.take_outbound(); - let step2 = repair - .iter() - .find(|frame| sync_subtype(frame.as_slice()) == Some(1)) - .expect("the writer answers the request with a Step2"); - assert_eq!( - receiver.deliver(millis(304), step2), - Outcome::Applied { kind: 0 } - ); - assert_eq!( - receiver.text("README.md"), - "ac", - "the lost deletion returns" - ); - assert_eq!( - writer.state_vector(), - receiver.state_vector(), - "the replicas converge" - ); - } - - /// After a lost update is repaired and the room has gone quiet, a fresh writer eligibility - /// lets a second lost update be repaired with the same two retained replicas and no new API: - /// the demotion and re-promotion are signed states, and the renewed request is what a fresh - /// continuous eligibility owes. - #[test] - #[expect( - clippy::too_many_lines, - reason = "the two loss-and-repair rounds and the fresh eligibility between them are one sequence" - )] - fn a_second_lost_update_is_repaired_after_a_fresh_writer_eligibility() { - let mut writer = session(&["p-other"]); - let mut receiver = second_session(&["p-self"]); - writer.tick(Duration::ZERO); - receiver.tick(Duration::ZERO); - let _ = writer.take_outbound(); - let _ = receiver.take_outbound(); - let committing = state( - &host(), - 1, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - writer.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - assert_eq!( - receiver.deliver(millis(1), &committing), - Outcome::Applied { kind: 1 } - ); - let writer_initial = writer.take_outbound(); - let _ = receiver.take_outbound(); - assert_eq!( - receiver.deliver(millis(2), &writer_initial[0]), - Outcome::Applied { kind: 0 } - ); - let _ = receiver.take_outbound(); - - // First loss: the independent insertion is dropped, the dependent one arrives pending. - assert!(writer.insert("README.md", 0, "off ").unwrap()); - let _ = writer.take_outbound(); - assert!(writer.insert("README.md", 0, "on ").unwrap()); - let dependent = writer.take_outbound(); - assert_eq!( - receiver.deliver(millis(3), &dependent[0]), - Outcome::Applied { kind: 0 } - ); - receiver.tick(millis(302)); - let request = receiver.take_outbound(); - assert_eq!(request.len(), 1, "one reciprocal request"); - assert_eq!( - writer.deliver(millis(303), &request[0]), - Outcome::Applied { kind: 0 } - ); - let repair = writer.take_outbound(); - let step2 = repair - .iter() - .find(|frame| sync_subtype(frame.as_slice()) == Some(1)) - .expect("the writer answers with a Step2"); - assert_eq!( - receiver.deliver(millis(304), step2), - Outcome::Applied { kind: 0 } - ); - assert_eq!(receiver.text("README.md"), "on off "); - assert_eq!(writer.state_vector(), receiver.state_vector()); - - // A quiet interval: the receiver owes nothing. - receiver.tick(millis(601)); - receiver.tick(millis(901)); - assert!( - receiver.take_outbound().is_empty(), - "the repaired window is silent" - ); - - // The writer is demoted and re-promoted under the same key: a fresh eligibility. - let demoted = state( - &host(), - 2, - &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - writer.deliver(millis(902), &demoted), - Outcome::Applied { kind: 1 } - ); - assert_eq!( - receiver.deliver(millis(902), &demoted), - Outcome::Applied { kind: 1 } - ); - let promoted = state( - &host(), - 3, - &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], - ); - assert_eq!( - writer.deliver(millis(903), &promoted), - Outcome::Applied { kind: 1 } - ); - assert_eq!( - receiver.deliver(millis(903), &promoted), - Outcome::Applied { kind: 1 } - ); - - // The renewed writer eligibility sends one request; the receiver arms from it. - writer.tick(millis(1201)); - let renewed = writer.take_outbound(); - assert_eq!(renewed.len(), 1, "the fresh eligibility owes one request"); - assert_eq!(sync_subtype(&renewed[0]), Some(0)); - assert_eq!( - receiver.deliver(millis(1202), &renewed[0]), - Outcome::Applied { kind: 0 } - ); - let _ = receiver.take_outbound(); - - // Second loss: the same shape, repaired by the receiver's renewed reciprocal request. - assert!(writer.insert("README.md", 0, "z").unwrap()); - let _ = writer.take_outbound(); - assert!(writer.insert("README.md", 0, "y").unwrap()); - let dependent = writer.take_outbound(); - assert_eq!( - receiver.deliver(millis(1203), &dependent[0]), - Outcome::Applied { kind: 0 } - ); - assert_eq!( - receiver.text("README.md"), - "on off ", - "the second dependency waits" - ); - receiver.tick(millis(1502)); - let request = receiver.take_outbound(); - assert_eq!(request.len(), 1, "the fresh eligibility re-armed once"); - assert_eq!(sync_subtype(&request[0]), Some(0)); - assert_eq!( - writer.deliver(millis(1503), &request[0]), - Outcome::Applied { kind: 0 } - ); - let repair = writer.take_outbound(); - let step2 = repair - .iter() - .find(|frame| sync_subtype(frame.as_slice()) == Some(1)) - .expect("the writer answers the second request with a Step2"); - assert_eq!( - receiver.deliver(millis(1504), step2), - Outcome::Applied { kind: 0 } - ); - assert_eq!(receiver.text("README.md"), "yzon off "); - assert_eq!(writer.text("README.md"), "yzon off "); - assert_eq!(writer.state_vector(), receiver.state_vector()); - } -} +mod tests; diff --git a/crates/client/src/peer/tests.rs b/crates/client/src/peer/tests.rs new file mode 100644 index 0000000..ed0418c --- /dev/null +++ b/crates/client/src/peer/tests.rs @@ -0,0 +1,3407 @@ +use super::plaintext::encode_y_message; +use super::*; +use crate::host::{ + ABSENCE_CHARGE, HostOptions, HostStore, ListingSource, PersistedHost, +}; +use crate::nesting::{MAX_ANY_DEPTH, decode_update}; +use crate::sealed::{ + Envelope, Recipe, RoomKey, encode_key, opens, read_varuint, seal, +}; +use selvage_protocol as proto; +use serde_json::{Value, json}; +use std::sync::{Arc, Mutex}; +use yrs::sync::awareness::{AwarenessUpdate, AwarenessUpdateEntry}; +use yrs::sync::{Message as YMessage, MessageReader, SyncMessage}; +use yrs::updates::decoder::DecoderV1; +use yrs::{Doc, GetString, ReadTxn, StateVector, Text, Transact}; + +/// A room, a host keypair and a session keypair, all derived from constants: these are +/// unit tests of §13's rules and they need no fixture to be one. +const ROOM: &str = "R7f3a2c19"; +const MILLIS: u64 = 1; + +fn room_key() -> RoomKey { + RoomKey([7; 32]) +} + +fn host() -> SessionKey { + SessionKey::from_seed([3; 32]) +} + +/// This connection's session keypair, fixed so that a state can commit it. +fn ours() -> SessionKey { + SessionKey::from_seed([5; 32]) +} + +/// A second peer's, committed as `guest` or `viewer` beside ours. +fn peer() -> SessionKey { + SessionKey::from_seed([11; 32]) +} + +/// A third peer's, so all three real sessions can be driven at once. +fn third() -> SessionKey { + SessionKey::from_seed([17; 32]) +} + +#[expect( + clippy::too_many_arguments, + reason = "what a test seals with: the signer, the kind, the counter and the plaintext" +)] +fn frame( + signer: &SessionKey, + kind: u64, + counter: u64, + plaintext: &[u8], +) -> Vec { + let key = room_key().frame_key(ROOM); + let recipe = Recipe { + room_id: ROOM, + frame_key: &key, + kind, + epoch: 0, + counter, + nonce: [9; 12], + signer, + }; + seal(&recipe, plaintext).unwrap().bytes() +} + +fn state( + signer: &SessionKey, + issued: u64, + peers: &[(&SessionKey, &str, &str)], +) -> Vec { + let members: serde_json::Map = peers + .iter() + .map(|(key, role, seat)| { + ( + key.public().encode(), + json!({"peer_id": seat, "role": role}), + ) + }) + .collect(); + let payload = + json!({"issued": issued, "listing": ["README.md"], "peers": members}); + frame(signer, 1, 1, &serde_json::to_vec(&payload).unwrap()) +} + +/// A state committing this connection's own key as a `viewer` beside a committed writer. +fn viewer_beside_writer(issued: u64) -> Vec { + state( + &host(), + issued, + &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")], + ) +} + +fn holds(signer: &SessionKey, counter: u64, paths: &[&str]) -> Vec { + let payload = json!({"holds": paths}); + frame(signer, 3, counter, &serde_json::to_vec(&payload).unwrap()) +} + +fn closing(signer: &SessionKey, issued: u64) -> Vec { + let payload = json!({"closing": true, "issued": issued}); + frame(signer, 2, 1, &serde_json::to_vec(&payload).unwrap()) +} + +/// A `kind = 0` frame carrying a real Update, which is document content. +fn content(signer: &SessionKey, counter: u64, text: &str) -> Vec { + frame(signer, 0, counter, &update_message(text)) +} + +/// One sync Update message inserting `text` at the start of `README.md`. +fn update_message(text: &str) -> Vec { + let doc = Doc::new(); + let handle = doc.get_or_insert_text("README.md"); + { + let mut txn = doc.transact_mut(); + handle.insert(&mut txn, 0, text); + } + let update = { + let txn = doc.transact(); + txn.encode_state_as_update_v1(&yrs::StateVector::default()) + }; + encode_y_message(&YMessage::Sync(SyncMessage::Update(update))) +} + +/// A guest session whose state commits its own key and `peer()`'s, both as `guest`, with +/// the handshake that state draws already taken off its queue. +fn beside_a_guest() -> PeerSession { + let mut session = session(&["p-peer"]); + session.tick(Duration::ZERO); + let committing = state( + &host(), + 1, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-peer")], + ); + assert_eq!( + session.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + session +} + +/// Whether a published frame carries document content: a `kind = 0` plaintext whose +/// y-protocols message is a sync `Update` rather than the `SyncStep1` of §13.1's step 6, +/// which shares the envelope's kind (`CANONICAL.md` §6.1). +fn carries_an_update(frame: &[u8]) -> bool { + let Ok(envelope) = Envelope::parse(frame) else { + return false; + }; + if envelope.kind != 0 { + return false; + } + let Ok(plaintext) = opens(&room_key().frame_key(ROOM), ROOM, &envelope) + else { + return false; + }; + plaintext.first() == Some(&0) + && read_varuint(&plaintext, 1).is_ok_and(|(tag, _)| tag == 2) +} + +/// Whether a published frame carries any y-protocols awareness message at all: §8.2's +/// renewal and §8.3's step 2 are the two ways this session would send one. +fn carries_awareness(frame: &[u8]) -> bool { + let Ok(envelope) = Envelope::parse(frame) else { + return false; + }; + if envelope.kind != 0 { + return false; + } + let Ok(plaintext) = opens(&room_key().frame_key(ROOM), ROOM, &envelope) + else { + return false; + }; + let mut decoder = DecoderV1::from(plaintext.as_slice()); + MessageReader::new(&mut decoder) + .map_while(Result::ok) + .any(|message| matches!(message, YMessage::Awareness(_))) +} + +fn session(roster: &[&str]) -> PeerSession { + let options = PeerOptions { + room_id: ROOM.to_string(), + room_key: room_key(), + host_key: host().public(), + renew: Duration::from_millis(300), + expire: Duration::from_millis(900), + seat: Some("p-self".to_string()), + roster: roster.iter().map(|seat| (*seat).to_string()).collect(), + fixed_session_key: Some([5; 32]), + declared_role: None, + awareness_client_id: None, + host: None, + frame_budget: None, + }; + PeerSession::new(&options).unwrap() +} + +fn millis(count: u64) -> Duration { + Duration::from_millis(count) +} + +/// A second connection's session, fixed so a state can commit it beside ours. +fn second_session(roster: &[&str]) -> PeerSession { + let options = PeerOptions { + room_id: ROOM.to_string(), + room_key: room_key(), + host_key: host().public(), + renew: Duration::from_millis(300), + expire: Duration::from_millis(900), + seat: Some("p-other".to_string()), + roster: roster.iter().map(|seat| (*seat).to_string()).collect(), + fixed_session_key: Some([11; 32]), + declared_role: None, + awareness_client_id: None, + host: None, + frame_budget: None, + }; + PeerSession::new(&options).unwrap() +} + +/// A third connection's session, fixed so three real peers can be driven at once. +fn third_session(roster: &[&str]) -> PeerSession { + let options = PeerOptions { + room_id: ROOM.to_string(), + room_key: room_key(), + host_key: host().public(), + renew: Duration::from_millis(300), + expire: Duration::from_millis(900), + seat: Some("p-third".to_string()), + roster: roster.iter().map(|seat| (*seat).to_string()).collect(), + fixed_session_key: Some([17; 32]), + declared_role: None, + awareness_client_id: None, + host: None, + frame_budget: None, + }; + PeerSession::new(&options).unwrap() +} + +/// A room state with a chosen listing, which a listing-only edition needs. +#[expect( + clippy::too_many_arguments, + reason = "a signer, an edition, the peers and the listing are the whole of a state" +)] +fn state_listing( + signer: &SessionKey, + issued: u64, + peers: &[(&SessionKey, &str, &str)], + listing: &[&str], +) -> Vec { + let members: serde_json::Map = peers + .iter() + .map(|(key, role, seat)| { + ( + key.public().encode(), + json!({"peer_id": seat, "role": role}), + ) + }) + .collect(); + let payload = + json!({"issued": issued, "listing": listing, "peers": members}); + frame(signer, 1, 1, &serde_json::to_vec(&payload).unwrap()) +} + +/// One sync `SyncStep1` message with an empty state vector: what a peer asks with. +fn step1() -> Vec { + encode_y_message(&YMessage::Sync(SyncMessage::SyncStep1( + StateVector::default(), + ))) +} + +/// The sync subtype of a published `kind = 0` frame: 0 is a `SyncStep1`, 1 a `SyncStep2`. +fn sync_subtype(frame: &[u8]) -> Option { + let envelope = Envelope::parse(frame).ok()?; + if envelope.kind != 0 { + return None; + } + let plaintext = opens(&room_key().frame_key(ROOM), ROOM, &envelope).ok()?; + if plaintext.first() != Some(&0) { + return None; + } + read_varuint(&plaintext, 1).ok().map(|(tag, _)| tag) +} + +/// The `README.md` text a published `SyncStep2` carries, applied to a fresh replica. +fn step2_text(frame: &[u8]) -> String { + let envelope = Envelope::parse(frame).unwrap(); + let plaintext = + opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); + let mut decoder = DecoderV1::from(plaintext.as_slice()); + let Some(Ok(YMessage::Sync(SyncMessage::SyncStep2(update)))) = + MessageReader::new(&mut decoder).next() + else { + return String::new(); + }; + let doc = Doc::new(); + let handle = doc.get_or_insert_text("README.md"); + let mut txn = doc.transact_mut(); + txn.apply_update(decode_update(&update).unwrap()).unwrap(); + handle.get_string(&txn) +} + +#[test] +fn the_announcement_goes_out_first_and_nothing_else_before_a_state() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let published = session.take_outbound(); + assert_eq!( + published.len(), + 1, + "§13.1's step 4 is the first binary frame" + ); + assert_eq!(session.published(), 1); + assert_eq!(session.handshake(), 0); + + let envelope = Envelope::parse(&published[0]).unwrap(); + assert_eq!(envelope.kind, 4); + assert_eq!(envelope.counter, 1); + let plaintext = + opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); + let announcement: Value = serde_json::from_slice(&plaintext).unwrap(); + assert_eq!(announcement["key"], json!(ours().public().encode())); +} + +#[test] +fn an_uncommitted_key_is_re_announced_on_the_renewal_clock_and_stops_once_committed() + { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + + // A state that commits another peer and not this connection: §13.1's step 4 announces + // again at once, because the renewal clock alone would wait a whole window. + let other = state(&host(), 1, &[(&peer(), "guest", "p-other")]); + assert_eq!( + session.deliver(millis(MILLIS), &other), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert_eq!(session.published(), 2); + + session.tick(millis(MILLIS + 299)); + assert!( + session.take_outbound().is_empty(), + "the clock has not passed" + ); + session.tick(millis(MILLIS + 300)); + assert_eq!(session.take_outbound().len(), 1, "§13.1's renewal clock"); + assert_eq!(session.published(), 3); + + // A state that commits this connection's key ends the recovery. + let committing = state(&host(), 2, &[(&ours(), "guest", "p-self")]); + assert_eq!( + session.deliver(millis(MILLIS + 301), &committing), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + session.tick(millis(MILLIS + 900)); + session.tick(millis(MILLIS + 1200)); + assert!(session.take_outbound().is_empty()); + assert_eq!(session.published(), 3); +} + +#[test] +fn a_committing_state_answers_with_the_handshake_and_moves_no_publication() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + + let committing = state(&host(), 1, &[(&ours(), "guest", "p-self")]); + assert_eq!( + session.deliver(millis(MILLIS), &committing), + Outcome::Applied { kind: 1 } + ); + let after = session.take_outbound(); + assert_eq!(after.len(), 1, "§13.1's step 6, once"); + assert_eq!(session.handshake(), 1); + assert_eq!( + session.published(), + 1, + "a handshake frame is not a publication" + ); + + let envelope = Envelope::parse(&after[0]).unwrap(); + assert_eq!(envelope.kind, 0); + let plaintext = + opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); + assert_eq!(plaintext.first(), Some(&0), "message type 0: sync"); + assert_eq!(read_varuint(&plaintext, 1).unwrap().0, 0, "SyncStep1"); + assert_eq!(session.listing(), ["README.md"]); + assert!(session.state_held()); +} + +#[test] +fn a_second_state_that_commits_our_key_sends_no_second_handshake() { + // §13.1's step 6 is a handshake *once*, and a host republishes its state on every + // `peer.joined` and on every announcement it accepts: a handshake per state would be a + // frame per republish. + let mut session = session(&[]); + session.tick(Duration::ZERO); + let first = state(&host(), 1, &[(&ours(), "guest", "p-self")]); + assert_eq!( + session.deliver(millis(1), &first), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert_eq!(session.handshake(), 1); + + let republished = state(&host(), 2, &[(&ours(), "guest", "p-self")]); + assert_eq!( + session.deliver(millis(2), &republished), + Outcome::Applied { kind: 1 } + ); + session.tick(millis(2 + 300)); + assert!(session.take_outbound().is_empty()); + assert_eq!(session.handshake(), 1, "one handshake per connection"); +} + +#[test] +fn an_edit_past_the_end_of_the_text_is_refused_and_not_a_panic() { + // `yrs` answers an offset that is not there by panicking, and a client a caller can + // kill with an index is not one a decision vector can drive. + let mut session = session(&[]); + session.tick(Duration::ZERO); + let state = state(&host(), 1, &[(&ours(), "guest", "p-self")]); + let _ = session.deliver(millis(1), &state); + assert!(session.insert("README.md", 0, "hello").unwrap()); + assert!(session.insert("README.md", 5, "!").unwrap()); + assert_eq!(session.length("README.md"), 6); + let refused = session.insert("README.md", 7, "!"); + assert!(refused.is_err(), "past the end is refused"); + assert_eq!(session.length("README.md"), 6, "and nothing was applied"); +} + +#[test] +fn two_states_at_one_edition_leave_the_first_applied() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let first = state(&host(), 2, &[(&ours(), "guest", "p-self")]); + let second = state(&host(), 2, &[(&peer(), "guest", "p-other")]); + assert_eq!( + session.deliver(millis(1), &first), + Outcome::Applied { kind: 1 } + ); + assert_eq!( + session.deliver(millis(2), &second), + Outcome::Dropped { + reason: "stale_issued".to_string() + } + ); + assert_eq!(session.applied().len(), 1); + assert_eq!(session.dropped().len(), 1); + // §13.3's `SHOULD` — the second state at one edition is the divergence, and a + // state *below* the mark is an ordinary stale state. The reason is the same for both. + assert_eq!(session.conflicts(), [1]); +} + +#[test] +fn a_state_below_the_mark_is_stale_and_not_a_conflict() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let first = state(&host(), 5, &[(&ours(), "guest", "p-self")]); + let old = state(&host(), 4, &[(&peer(), "guest", "p-other")]); + let _ = session.deliver(millis(1), &first); + assert_eq!( + session.deliver(millis(2), &old), + Outcome::Dropped { + reason: "stale_issued".to_string() + } + ); + assert_eq!(session.dropped().len(), 1, "still refused, still named"); + assert!( + session.conflicts().is_empty(), + "an edition below the mark is not two publications at one edition" + ); +} + +#[test] +fn the_same_state_is_still_refused_under_the_ignore_issued_mutation() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let first = state(&host(), 2, &[(&ours(), "guest", "p-self")]); + let second = state(&host(), 2, &[(&peer(), "guest", "p-other")]); + let _ = session.deliver(millis(1), &first); + session.mutate("ignore-issued").unwrap(); + assert_eq!( + session.deliver(millis(2), &second), + Outcome::Applied { kind: 1 } + ); +} + +#[test] +fn a_committed_viewers_content_is_refused_and_its_own_edit_is_not_published() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + // Both keys: ours is committed, so §13.1's step 4 has nothing to re-announce, and + // the peer's is the `viewer` whose frame is refused. + let state = state( + &host(), + 1, + &[ + (&ours(), "guest", "p-self"), + (&peer(), "viewer", "p-viewer"), + ], + ); + assert_eq!( + session.deliver(millis(1), &state), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + let edit = content(&peer(), 1, "hello"); + assert_eq!( + session.deliver(millis(2), &edit), + Outcome::Dropped { + reason: "unauthorised_content".to_string() + } + ); + assert_eq!(session.published(), 1, "nothing was published in answer"); + assert_eq!(session.text("README.md"), "", "and nothing was applied"); + + // §13.6: the refusal opens an interval, and the client re-syncs in it — once per + // renewal interval, however many content frames it refused. + assert!(session.take_outbound().is_empty()); + session.tick(millis(2 + 300)); + let after = session.take_outbound(); + assert_eq!(after.len(), 1, "§13.6's re-sync"); + assert_eq!(session.handshake(), 2, "§13.1's step 6, then §13.6's"); + assert_eq!( + session.published(), + 1, + "a handshake frame is not a publication" + ); + assert_eq!( + Envelope::parse(&after[0]).unwrap().kind, + 0, + "a `kind = 0` frame carrying the SyncStep1" + ); + session.tick(millis(2 + 301)); + session.tick(millis(2 + 302)); + assert!(session.take_outbound().is_empty(), "once per interval"); +} + +#[test] +fn an_edit_made_before_a_committing_state_goes_out_when_it_arrives() { + // §13.1's step 4 holds content back until a state commits this key, and a client that + // dropped what it held back would leave the room without that edit: nothing asks the + // room for what this replica lacks, only for what it has. + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + assert!( + !session.insert("README.md", 0, "held back").unwrap(), + "nothing may be published before a state commits this key" + ); + assert_eq!(session.published(), 1, "the announcement, and no content"); + + let committing = state(&host(), 1, &[(&ours(), "guest", "p-self")]); + assert_eq!( + session.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + let out = session.take_outbound(); + assert_eq!(out.len(), 2, "§13.1's step 6, then the held-back edit"); + assert_eq!(session.handshake(), 1); + assert_eq!(session.published(), 2, "the edit is a publication"); + assert_eq!(Envelope::parse(&out[1]).unwrap().kind, 0); +} + +#[test] +fn a_viewer_discards_its_own_edit_and_publishes_nothing() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let state = state(&host(), 1, &[(&ours(), "viewer", "p-self")]); + let _ = session.deliver(millis(1), &state); + let _ = session.take_outbound(); + assert!(!session.insert("README.md", 0, "hello").unwrap()); + assert_eq!(session.published(), 1); + assert_eq!( + session.text("README.md"), + "", + "the disallowed edit is not even locally visible" + ); +} + +#[test] +fn a_guest_publishes_its_edit_as_a_delta() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let state = state(&host(), 1, &[(&ours(), "guest", "p-self")]); + let _ = session.deliver(millis(1), &state); + let _ = session.take_outbound(); + assert!(session.insert("README.md", 0, "hello").unwrap()); + let out = session.take_outbound(); + assert_eq!(out.len(), 1); + assert_eq!(session.published(), 2); + let envelope = Envelope::parse(&out[0]).unwrap(); + assert_eq!(envelope.kind, 0); +} + +/// §13.10: a session that has ended publishes nothing, whichever ending reached it. A +/// guest whose ending is the host's closing keeps a later edit in its own replica and +/// sends none of it. +#[test] +fn an_ended_session_publishes_no_edit() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let state = state(&host(), 1, &[(&ours(), "guest", "p-self")]); + assert_eq!( + session.deliver(millis(1), &state), + Outcome::Applied { kind: 1 } + ); + assert_eq!( + session.deliver(millis(2), &closing(&host(), 2)), + Outcome::Applied { kind: 2 } + ); + assert_eq!(session.ending(), Some(Ending::Closing)); + let _ = session.take_outbound(); + let published = session.published(); + assert!( + !session.insert("README.md", 0, "after the closing").unwrap(), + "an ended session publishes nothing" + ); + assert!( + session.unsent.is_empty(), + "and keeps nothing back: §13.10 publishes nothing later either, so a held set \ + would only grow for as long as the session lives" + ); + assert!(session.take_outbound().is_empty()); + assert_eq!(session.published(), published); + assert_eq!( + session.text("README.md"), + "after the closing", + "and its own replica still holds the edit" + ); + + // The buffer stays empty however many edits follow, which is the whole of what an + // ended session does with one. + for _ in 0..64 { + assert!(!session.insert("README.md", 0, "x").unwrap()); + } + assert!(session.unsent.is_empty()); + assert!(session.take_outbound().is_empty()); + assert_eq!(session.published(), published); +} + +/// §13.10: an ended session publishes nothing, and the path that could still have done it +/// is the flush §13.1's step 4 owes a state that commits this connection's key. An edit held +/// back before the ending must not be published by a state arriving after it. +#[test] +fn a_state_after_the_ending_publishes_none_of_what_was_held_back() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + + // No state commits this key yet, so §13.1's step 4 holds the edit back. + assert!(!session.insert("README.md", 0, "held").unwrap()); + assert_eq!(session.unsent.len(), 1, "the edit is held, not published"); + + // §13.10's no-state window ends the session while the edit is still held. + session.tick(millis(900)); + assert_eq!(session.ending(), Some(Ending::NoState)); + + let committing = state(&host(), 1, &[(&ours(), "guest", "p-self")]); + assert_eq!( + session.deliver(millis(901), &committing), + Outcome::Applied { kind: 1 } + ); + assert!( + !session + .take_outbound() + .iter() + .any(|frame| carries_an_update(frame)), + "the state that commits this key is the flush's own trigger, and the flush of an \ + ended session is nothing" + ); + assert!(session.unsent.is_empty()); +} + +#[test] +fn a_closing_handed_to_a_state_less_client_is_ignored_and_the_state_below_it_still_applies() + { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + assert_eq!( + session.deliver(millis(1), &closing(&host(), 2)), + Outcome::Ignored { kind: 2 } + ); + assert_eq!(session.applied().len(), 0); + assert_eq!(session.dropped().len(), 0); + assert_eq!(session.ignored(), [0]); + assert_eq!(session.ending(), None); + + let state = state(&host(), 1, &[(&ours(), "guest", "p-self")]); + assert_eq!( + session.deliver(millis(2), &state), + Outcome::Applied { kind: 1 } + ); + let again = closing(&host(), 2); + assert_eq!( + session.deliver(millis(3), &again), + Outcome::Applied { kind: 2 } + ); + assert_eq!(session.ending(), Some(Ending::Closing)); +} + +#[test] +fn the_same_closing_ends_a_client_that_holds_no_state_under_the_any_closing_mutation() + { + let mut session = session(&[]); + session.tick(Duration::ZERO); + session.mutate("any-closing").unwrap(); + assert_eq!( + session.deliver(millis(1), &closing(&host(), 2)), + Outcome::Applied { kind: 2 } + ); + assert_eq!(session.ending(), Some(Ending::Closing)); +} + +#[test] +fn a_lease_lapses_a_window_after_the_last_message_and_drops_no_frame() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let state = state(&host(), 1, &[(&peer(), "guest", "p-other")]); + let _ = session.deliver(millis(1), &state); + let set = holds(&peer(), 1, &["README.md"]); + assert_eq!( + session.deliver(millis(2), &set), + Outcome::Applied { kind: 3 } + ); + assert_eq!( + session.peer_holds()[&peer().public().encode()], + ["README.md"] + ); + + session.tick(millis(2 + 899)); + assert_eq!(session.peer_holds().len(), 1, "the lease has not lapsed"); + session.tick(millis(2 + 900)); + assert!(session.peer_holds().is_empty()); + assert_eq!(session.dropped().len(), 0, "an expiry is not a refusal"); + assert_eq!(session.ending(), None, "and it is not a departure"); +} + +#[test] +fn a_lease_never_lapses_under_the_no_lease_mutation() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let state = state(&host(), 1, &[(&peer(), "guest", "p-other")]); + let _ = session.deliver(millis(1), &state); + let _ = session.deliver(millis(2), &holds(&peer(), 1, &["README.md"])); + session.mutate("no-lease").unwrap(); + session.tick(millis(10_000)); + assert_eq!(session.peer_holds().len(), 1); +} + +#[test] +fn a_silent_peers_awareness_state_lapses_a_window_after_it_was_applied() { + let mut session = beside_a_guest(); + let states = awareness_message(&[41], 1, "{\"cursor\":null}"); + let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &states)); + assert_eq!(session.awareness_clients(), [41]); + + session.tick(millis(2 + 899)); + assert_eq!(session.awareness_clients(), [41], "not before the window"); + session.tick(millis(2 + 900)); + assert!( + session.awareness_clients().is_empty(), + "§8.2: a remote state not renewed inside `awareness_expire_ms` is forgotten" + ); + assert_eq!(session.dropped().len(), 0, "an expiry is not a refusal"); + assert_eq!(session.ending(), None, "and it is not a departure"); +} + +#[test] +fn a_renewed_awareness_state_is_not_forgotten() { + let mut session = beside_a_guest(); + let first = awareness_message(&[41], 1, "{}"); + let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &first)); + session.tick(millis(2 + 899)); + + let renewed = awareness_message(&[41], 2, "{}"); + let _ = session.deliver(millis(2 + 899), &frame(&peer(), 0, 2, &renewed)); + session.tick(millis(2 + 899 + 899)); + assert_eq!( + session.awareness_clients(), + [41], + "the renewal moved the window it is measured from" + ); + session.tick(millis(2 + 899 + 900)); + assert!( + session.awareness_clients().is_empty(), + "and it lapses from there" + ); +} + +#[test] +fn an_awareness_entry_below_the_clock_held_does_not_renew_it() { + let mut session = beside_a_guest(); + let current = awareness_message(&[41], 7, "{}"); + let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, ¤t)); + + // §8.2: an entry whose clock is not above the one held is ignored, and does not renew + // the state. A stale copy of a live peer's state must not hold its cursor open. + let replay = awareness_message(&[41], 4, "{}"); + let _ = session.deliver(millis(2 + 899), &frame(&peer(), 0, 2, &replay)); + session.tick(millis(2 + 900)); + assert!( + session.awareness_clients().is_empty(), + "the replay renewed nothing" + ); +} + +#[test] +fn a_peer_that_expired_is_visible_again_above_its_tombstone() { + let mut session = beside_a_guest(); + let states = awareness_message(&[41], 5, "{}"); + let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &states)); + session.tick(millis(2 + 900)); + assert!(session.awareness_clients().is_empty(), "forgotten"); + + // `yrs`'s removal leaves the id a tombstone one above the state it dropped + // (`NOTES.md` §A.11), so the publication at the dropped clock and the one above it are + // both ignored... + let dropped = awareness_message(&[41], 5, "{}"); + let _ = session.deliver(millis(2 + 900), &frame(&peer(), 0, 2, &dropped)); + assert!( + session.awareness_clients().is_empty(), + "the dropped clock is a tombstone" + ); + let next = awareness_message(&[41], 6, "{}"); + let _ = session.deliver(millis(2 + 900), &frame(&peer(), 0, 3, &next)); + assert!( + session.awareness_clients().is_empty(), + "and so is the one above it" + ); + + // ...and the renewal above both makes the peer visible again, with its window moved. + let above = awareness_message(&[41], 7, "{}"); + let _ = session.deliver(millis(2 + 901), &frame(&peer(), 0, 4, &above)); + assert_eq!(session.awareness_clients(), [41], "visible again"); + session.tick(millis(2 + 901 + 900)); + assert!( + session.awareness_clients().is_empty(), + "and it lapses from the renewal" + ); +} + +#[test] +fn a_departed_peers_awareness_state_goes_at_once_and_stays_gone() { + let mut session = beside_a_guest(); + let states = awareness_message(&[41], 1, "{}"); + let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &states)); + // 42's state arrives a window later, so the two stamps do not coincide: the tick below + // is past 41's window and short of 42's. Stamped together they would both lapse there, + // and the tick would then test the window rather than the departure's own bookkeeping. + let neighbour = awareness_message(&[42], 1, "{}"); + let _ = session.deliver(millis(2 + 899), &frame(&peer(), 0, 2, &neighbour)); + assert_eq!(session.awareness_clients(), [41, 42]); + + session.forget_awareness(41); + assert_eq!( + session.awareness_clients(), + [42], + "§8.4: a departed seat's state goes at once, not at the window" + ); + + // The first tick at or after 41's window. `forget_awareness` cleared its stamp, so + // there is nothing for the expiry to act on; without that clear this is the tick that + // steps 41's tombstone a second time. + session.tick(millis(2 + 900)); + assert_eq!( + session.awareness_clients(), + [42], + "the expiry tick left the tombstone alone" + ); + + // If the expiry tick had stepped 41's tombstone a second time, this renewal would be + // swallowed and the id would stay gone. + let again = awareness_message(&[41], 3, "{}"); + let _ = session.deliver(millis(2 + 900), &frame(&peer(), 0, 3, &again)); + assert_eq!( + session.awareness_clients(), + [41, 42], + "the id is welcome back" + ); +} +/// A clean replica adopted by §13.9's `viewer` resolution must carry the removal clocks as +/// well as the live states: `Awareness::update()` alone would drop every tombstone and let a +/// stale entry resurrect a peer the room has forgotten. +#[test] +fn an_adopted_baseline_keeps_a_forgotten_ids_tombstone() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + // A state committing only the peer leaves this connection's own key UNKNOWN, so the + // local edit is speculative and captures the clean baseline a later resolution adopts. + assert_eq!( + session.deliver( + millis(1), + &state(&host(), 1, &[(&peer(), "guest", "p-other")]) + ), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert!(!session.insert("README.md", 0, "spec").unwrap()); + assert_eq!(session.text("README.md"), "spec"); + + // An awareness state, then §8.4's departure: the removal leaves a tombstone one above + // the state it dropped. + let states = awareness_message(&[41], 5, "{}"); + let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &states)); + assert_eq!(session.awareness_clients(), [41]); + session.forget_awareness(41); + assert!(session.awareness_clients().is_empty()); + + // The viewer state replaces the replica; the tombstone must move onto the new owner. + assert_eq!( + session.deliver( + millis(3), + &state( + &host(), + 2, + &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")] + ) + ), + Outcome::Applied { kind: 1 } + ); + assert_eq!( + session.text("README.md"), + "", + "the speculative edit is discarded" + ); + + // The dropped clock and the one above it stay absent; a higher one renews. + let dropped = awareness_message(&[41], 5, "{}"); + let _ = session.deliver(millis(4), &frame(&peer(), 0, 2, &dropped)); + assert!( + session.awareness_clients().is_empty(), + "the dropped clock stays a tombstone across adoption" + ); + let equal = awareness_message(&[41], 6, "{}"); + let _ = session.deliver(millis(5), &frame(&peer(), 0, 3, &equal)); + assert!( + session.awareness_clients().is_empty(), + "and so does the clock above it" + ); + let above = awareness_message(&[41], 7, "{}"); + let _ = session.deliver(millis(6), &frame(&peer(), 0, 4, &above)); + assert_eq!( + session.awareness_clients(), + [41], + "a renewal above the tombstone makes the peer visible again" + ); +} + +/// Adoption replaces the replica but must not disturb an unrelated live state's expiry: the +/// local stamp is this session's and survives the swap untouched. +#[test] +fn an_adopted_baseline_leaves_an_unrelated_state_on_its_own_schedule() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + assert_eq!( + session.deliver( + millis(1), + &state(&host(), 1, &[(&peer(), "guest", "p-other")]) + ), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert!(!session.insert("README.md", 0, "spec").unwrap()); + + // Two peers' states, stamped a window apart: 41 is forgotten, 42 stays live. + let fortyone = awareness_message(&[41], 5, "{}"); + let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &fortyone)); + let fortytwo = awareness_message(&[42], 1, "{}"); + let _ = session.deliver(millis(3), &frame(&peer(), 0, 2, &fortytwo)); + assert_eq!(session.awareness_clients(), [41, 42]); + session.forget_awareness(41); + assert_eq!(session.awareness_clients(), [42]); + + assert_eq!( + session.deliver( + millis(4), + &state( + &host(), + 2, + &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")] + ) + ), + Outcome::Applied { kind: 1 } + ); + assert_eq!( + session.awareness_clients(), + [42], + "an unrelated live state survives adoption" + ); + session.tick(millis(3 + 899)); + assert_eq!( + session.awareness_clients(), + [42], + "not before its own window" + ); + session.tick(millis(3 + 900)); + assert!( + session.awareness_clients().is_empty(), + "and it lapses on the schedule it was stamped on" + ); +} + +/// The tombstone routes that are not `forget_awareness` — §8.2's expiry and an incoming +/// removal — must survive adoption too, or a stale copy resurrects a peer through the swap. +#[test] +fn an_adopted_baseline_keeps_tombstones_from_expiry_and_an_incoming_removal() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + assert_eq!( + session.deliver( + millis(1), + &state(&host(), 1, &[(&peer(), "guest", "p-other")]) + ), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert!(!session.insert("README.md", 0, "spec").unwrap()); + + // 41 lives, then §8.2's expiry tick leaves it a tombstone one above its state. + let fortyone = awareness_message(&[41], 5, "{}"); + let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &fortyone)); + session.tick(millis(902)); + assert!(session.awareness_clients().is_empty(), "41 expired"); + + // 42 is removed by an incoming null state, which leaves its own tombstone. + let fortytwo = awareness_message(&[42], 1, "{}"); + let _ = session.deliver(millis(3), &frame(&peer(), 0, 2, &fortytwo)); + assert_eq!(session.awareness_clients(), [42]); + let removal = awareness_message(&[42], 2, "null"); + let _ = session.deliver(millis(4), &frame(&peer(), 0, 3, &removal)); + assert!(session.awareness_clients().is_empty(), "42 removed"); + + // Adoption replaces the replica; both tombstones must move onto the new owner. + assert_eq!( + session.deliver(millis(5), &viewer_beside_writer(2)), + Outcome::Applied { kind: 1 } + ); + let stale = awareness_message(&[41], 5, "{}"); + let _ = session.deliver(millis(6), &frame(&peer(), 0, 4, &stale)); + assert!( + session.awareness_clients().is_empty(), + "41's expiry clock stays gone" + ); + let equal = awareness_message(&[41], 6, "{}"); + let _ = session.deliver(millis(7), &frame(&peer(), 0, 5, &equal)); + assert!( + session.awareness_clients().is_empty(), + "41's clock above the tombstone stays gone" + ); + let above = awareness_message(&[41], 7, "{}"); + let _ = session.deliver(millis(8), &frame(&peer(), 0, 6, &above)); + assert_eq!( + session.awareness_clients(), + [41], + "41 renews above its tombstone" + ); + + let stale42 = awareness_message(&[42], 1, "{}"); + let _ = session.deliver(millis(9), &frame(&peer(), 0, 7, &stale42)); + assert!( + !session.awareness_clients().contains(&42), + "42's removal clock stays gone" + ); + let above42 = awareness_message(&[42], 3, "{}"); + let _ = session.deliver(millis(10), &frame(&peer(), 0, 8, &above42)); + assert!( + session.awareness_clients().contains(&42), + "42 renews above its removal" + ); +} + +#[test] +fn this_client_publishes_no_awareness_state_of_its_own() { + let mut session = beside_a_guest(); + let states = awareness_message(&[41], 1, "{}"); + let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &states)); + let _ = session.take_outbound(); + let published = session.published(); + assert!( + !session + .awareness_clients() + .contains(&session.awareness_client_id()), + "§8.2: a client that publishes no state holds none of its own" + ); + + for clock in [302, 902, 1802, 1803] { + session.tick(millis(clock)); + let sent = session.take_outbound(); + assert!( + sent.iter().all(|frame| !carries_awareness(frame)), + "no state, renewal or query goes out at {clock}" + ); + } + assert_eq!(session.published(), published, "no tick published anything"); +} + +#[test] +fn a_seated_client_with_no_state_ends_at_the_no_state_window() { + let mut session = session(&[]); + session.tick(millis(899)); + assert_eq!(session.ending(), None, "not before the window"); + session.tick(millis(900)); + assert_eq!(session.ending(), Some(Ending::NoState)); +} + +#[test] +fn the_same_client_stays_for_ever_under_the_wait_for_ever_mutation() { + let mut session = session(&[]); + session.mutate("wait-for-ever").unwrap(); + session.tick(millis(60_000)); + assert_eq!(session.ending(), None); +} + +#[test] +fn a_state_whose_host_entry_is_unseated_ends_the_session_a_window_later() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + // The roster names no seat, and the state's `host` entry labels one: §13.8's clock. + let state = state(&host(), 1, &[(&peer(), "host", "p-absent")]); + assert_eq!( + session.deliver(millis(1), &state), + Outcome::Applied { kind: 1 } + ); + session.tick(millis(900)); + assert_eq!( + session.ending(), + None, + "one millisecond short of the window" + ); + session.tick(millis(901)); + assert_eq!(session.ending(), Some(Ending::HostAway)); +} + +#[test] +fn a_peer_left_for_the_seat_the_host_entry_labels_arms_the_clock() { + // §13.11's fixture for the host-away clock, which no decision vector carries: the + // state labels a seat the roster has, and the roster then loses it. + let mut session = session(&["p-host"]); + session.tick(Duration::ZERO); + let state = state(&host(), 1, &[(&peer(), "host", "p-host")]); + let _ = session.deliver(millis(1), &state); + session.tick(millis(500)); + assert_eq!(session.ending(), None, "the host is seated"); + + session.seat_left(millis(600), "p-host"); + session.tick(millis(600 + 899)); + assert_eq!(session.ending(), None); + session.tick(millis(600 + 900)); + assert_eq!(session.ending(), Some(Ending::HostAway)); +} + +#[test] +fn a_state_that_does_not_name_a_host_arms_nothing() { + // §13.4: a client MUST NOT guess which connection is the host's. + let mut session = session(&[]); + session.tick(Duration::ZERO); + let state = state(&host(), 1, &[(&peer(), "guest", "p-other")]); + let _ = session.deliver(millis(1), &state); + session.tick(millis(5_000)); + assert_eq!(session.ending(), None); +} + +#[test] +fn a_held_set_is_announced_wholesale_and_an_empty_one_is_a_release() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let state = state(&host(), 1, &[(&ours(), "guest", "p-self")]); + let _ = session.deliver(millis(1), &state); + let _ = session.take_outbound(); + + // §13.7: a set that changed goes out with the change, and not at the next renewal — + // no `tick` between the two, so nothing else can have published it. + session.open(millis(2), "README.md"); + let out = session.take_outbound(); + assert_eq!(out.len(), 1, "a changed set goes out at once"); + let envelope = Envelope::parse(&out[0]).unwrap(); + assert_eq!(envelope.kind, 3); + let plaintext = + opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); + let payload: Value = serde_json::from_slice(&plaintext).unwrap(); + assert_eq!(payload["holds"], json!(["README.md"])); + + // The whole set and no delta, so the second open carries both paths. + session.open(millis(3), "src/main.rs"); + let out = session.take_outbound(); + assert_eq!(out.len(), 1); + let envelope = Envelope::parse(&out[0]).unwrap(); + let plaintext = + opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); + let payload: Value = serde_json::from_slice(&plaintext).unwrap(); + assert_eq!(payload["holds"], json!(["README.md", "src/main.rs"])); + + // Opening a path that is already held changes nothing, so nothing is published. + session.open(millis(4), "README.md"); + assert!(session.take_outbound().is_empty()); + + session.release(millis(5)); + let out = session.take_outbound(); + assert_eq!(out.len(), 1, "the empty set is a change like any other"); + assert_eq!(session.held().len(), 0); + let envelope = Envelope::parse(&out[0]).unwrap(); + let plaintext = + opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); + let payload: Value = serde_json::from_slice(&plaintext).unwrap(); + assert_eq!(payload["holds"], json!([] as [&str; 0])); + + // The whole set replaced by one path is one message: `release` and `open` would put an + // empty set on the wire between them, which is a release no caller asked for. + session.open(millis(6), "README.md"); + let _ = session.take_outbound(); + session.hold_only(millis(7), "src/main.rs"); + let out = session.take_outbound(); + assert_eq!(out.len(), 1, "a set replaced in one step is one message"); + let envelope = Envelope::parse(&out[0]).unwrap(); + let plaintext = + opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); + let payload: Value = serde_json::from_slice(&plaintext).unwrap(); + assert_eq!(payload["holds"], json!(["src/main.rs"])); +} + +/// §13.7's two "at once" moments, which the tick alone does not honour: the state that +/// commits this key is where a holder's *first* holds message belongs, and a `peer.joined` +/// is where a joiner learns the room's holds. +#[test] +fn a_first_holds_message_and_a_joiner_are_answered_on_the_event() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + session.open(millis(1), "README.md"); + assert!( + session.take_outbound().is_empty(), + "§13.1's step 4 withholds it until a state commits this key" + ); + + let committing = state(&host(), 1, &[(&ours(), "guest", "p-self")]); + let _ = session.deliver(millis(2), &committing); + let out = session.take_outbound(); + let kinds: Vec = out + .iter() + .map(|frame| Envelope::parse(frame).unwrap().kind) + .collect(); + assert_eq!( + kinds, + [0, 3], + "§13.1's step 6 handshake, then the first holds message: no tick between them" + ); + assert_eq!(session.handshake(), 1); + assert_eq!( + session.published(), + 2, + "the announcement and the holds message; the handshake is counted apart" + ); + + // A seat is seated: the state that will commit the joiner's key goes out with the event, + // and the room's holds behind it — a holds message resolves against the keys the applied + // state commits (§13.4), so one that arrives before the state is refused. + session.seat_joined(millis(3), "p-other"); + let out = session.take_outbound(); + let kinds: Vec = out + .iter() + .map(|frame| Envelope::parse(frame).unwrap().kind) + .collect(); + assert_eq!(kinds, [1, 3], "the state the room holds, then the holds"); +} + +#[test] +fn a_state_is_re_sent_on_a_join_only_while_the_host_is_away() { + // `PROTOCOL.md` §7.1: while the seat the `host` entry labels is seated, the host's own + // fresh state answers a join, so this peer sends none; once that seat has gone, a new + // seat — a returning host among them — is sent the held state, unchanged. + let mut session = session(&["p-host"]); + session.tick(Duration::ZERO); + let held = state( + &host(), + 1, + &[(&peer(), "host", "p-host"), (&ours(), "guest", "p-self")], + ); + let _ = session.deliver(millis(1), &held); + let _ = session.take_outbound(); + + session.seat_joined(millis(2), "p-new"); + let kinds: Vec = session + .take_outbound() + .iter() + .map(|frame| Envelope::parse(frame).unwrap().kind) + .collect(); + assert!( + !kinds.contains(&1), + "no state goes back while the host is seated: {kinds:?}" + ); + + session.seat_left(millis(3), "p-host"); + let _ = session.take_outbound(); + session.seat_joined(millis(4), "p-host-again"); + let out = session.take_outbound(); + assert_eq!( + out.first().map(Vec::as_slice), + Some(held.as_slice()), + "the held state goes back first, unchanged" + ); +} + +fn budgeted(budget: u64, host: Option) -> PeerSession { + let options = PeerOptions { + room_id: ROOM.to_string(), + room_key: room_key(), + host_key: self::host().public(), + renew: Duration::from_millis(300), + expire: Duration::from_millis(900), + seat: Some("p-self".to_string()), + roster: BTreeSet::new(), + fixed_session_key: Some([5; 32]), + declared_role: None, + awareness_client_id: None, + host, + frame_budget: Some(budget), + }; + PeerSession::new(&options).unwrap() +} + +#[test] +fn a_session_that_reaches_the_frame_budget_seals_nothing_more_and_ends() { + // `CANONICAL.md` §6.1: the announcement is the first frame the room counts and the + // state the second, so the handshake the state would be answered with is not sealed, + // and the next tick ends the session and says why. + let mut session = budgeted(2, None); + session.tick(Duration::ZERO); + assert_eq!(session.take_outbound().len(), 1, "the announcement"); + let _ = session.deliver( + millis(1), + &state(&host(), 1, &[(&ours(), "guest", "p-self")]), + ); + assert!( + session.take_outbound().is_empty(), + "nothing is sealed past the budget" + ); + session.tick(millis(2)); + assert_eq!(session.ending(), Some(Ending::FrameBudget)); + assert!(Ending::FrameBudget.as_str().contains("new room")); + session.open(millis(3), "README.md"); + session.tick(millis(400)); + assert!(session.take_outbound().is_empty(), "and nothing after it"); + assert_eq!(FRAME_BUDGET, 1 << 31); +} + +#[derive(Default)] +struct Saved(Mutex>); + +impl HostStore for Saved { + fn load(&self) -> Option { + *self.0.lock().unwrap() + } + + fn save(&self, persisted: PersistedHost) { + *self.0.lock().unwrap() = Some(persisted); + } +} + +fn stored_host(store: &Arc) -> HostOptions { + let listing: ListingSource = Arc::new(|| vec!["README.md".to_string()]); + HostOptions { + host_seed: [3; 32], + listing, + store: Some(Arc::clone(store) as Arc), + } +} + +#[test] +fn a_host_continues_the_frame_count_it_saved() { + // `CANONICAL.md` §6.1: the host's count is the room's, so a reload continues it rather + // than starting at 0, and the budget is reached from there. + let store = Arc::new(Saved::default()); + store.save(PersistedHost { + host_seed: [3; 32], + issued: 5, + frames: Some(10), + }); + // A reload is a return, so the saved count is continued with the absence charge on it. + let mut session = + budgeted(ABSENCE_CHARGE.saturating_add(11), Some(stored_host(&store))); + session.tick(Duration::ZERO); + session.tick(millis(1)); + assert_eq!( + session.ending(), + Some(Ending::FrameBudget), + "from the saved count" + ); +} + +#[test] +fn a_host_writes_its_moving_frame_count_once_a_renewal_interval() { + let store = Arc::new(Saved::default()); + let mut session = budgeted(FRAME_BUDGET, Some(stored_host(&store))); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + // The mint state's own write opened the window at 0, so the count it could not yet carry + // is written on the first tick a window later. + session.tick(millis(300)); + let first = store + .load() + .and_then(|saved| saved.frames) + .unwrap_or_default(); + assert!( + first > 0, + "the frames the host sealed are written on the tick" + ); + let _ = session.deliver(millis(301), &holds(&peer(), 1, &["README.md"])); + session.tick(millis(600)); + let saved = store.load().unwrap(); + assert!( + saved.frames.unwrap_or_default() > first, + "a delivered frame is in the next write" + ); + assert!(saved.issued > 0, "written beside `issued`"); +} + +#[test] +fn a_host_record_without_a_count_reads_as_a_spent_budget() { + // `CANONICAL.md` §6.1: a record written before the count existed cannot say what the + // room has sealed, so the host closes the room at its first tick rather than continue it. + let store = Arc::new(Saved::default()); + store.save(PersistedHost { + host_seed: [3; 32], + issued: 3, + frames: None, + }); + let mut session = budgeted(FRAME_BUDGET, Some(stored_host(&store))); + session.tick(Duration::ZERO); + let kinds: Vec = session + .take_outbound() + .iter() + .map(|frame| Envelope::parse(frame).unwrap().kind) + .collect(); + assert_eq!(kinds, [2], "the closing, and nothing sealed before it"); + assert_eq!(session.ending(), Some(Ending::FrameBudget)); + assert_eq!(store.load().map(|saved| saved.issued), Some(4)); +} + +#[test] +fn a_host_that_closes_its_room_saves_the_count_with_the_closing_in_it() { + let store = Arc::new(Saved::default()); + let mut session = budgeted(FRAME_BUDGET, Some(stored_host(&store))); + session.tick(Duration::ZERO); + let sealed = u64::try_from(session.take_outbound().len()).unwrap(); + assert!(session.close_room()); + assert_eq!( + store.load().and_then(|saved| saved.frames), + Some(sealed.saturating_add(1)), + "a reload continues from the frame that ended the room" + ); +} + +#[derive(Default)] +struct Counted { + saved: Saved, + saves: Mutex, +} + +impl HostStore for Counted { + fn load(&self) -> Option { + self.saved.load() + } + + fn save(&self, persisted: PersistedHost) { + let mut saves = self.saves.lock().unwrap(); + *saves = saves.saturating_add(1); + self.saved.save(persisted); + } +} + +#[test] +fn a_state_published_after_a_flush_counts_as_a_write_for_the_renewal_window() { + let store = Arc::new(Counted::default()); + let listing: ListingSource = Arc::new(|| vec!["README.md".to_string()]); + let options = HostOptions { + host_seed: [3; 32], + listing, + store: Some(Arc::clone(&store) as Arc), + }; + let mut session = budgeted(FRAME_BUDGET, Some(options)); + session.tick(Duration::ZERO); + session.tick(millis(300)); + // An announcement commits a key, so the host publishes a fresh state, and that write + // carries the count at its own clock: a frame that moves the count right after it waits + // for the next window rather than being written on the next tick. + session.seat_joined(millis(600), "p-alice"); + let named = json!({ "key": peer().public().encode() }).to_string(); + let _ = + session.deliver(millis(600), &frame(&peer(), 4, 1, named.as_bytes())); + let after_state = *store.saves.lock().unwrap(); + let _ = session.deliver(millis(601), &[1, 2, 3]); + session.tick(millis(602)); + assert_eq!( + *store.saves.lock().unwrap(), + after_state, + "no write inside the window" + ); + session.tick(millis(900)); + assert_eq!( + *store.saves.lock().unwrap(), + after_state.saturating_add(1), + "one once it has passed" + ); +} + +#[test] +fn a_host_that_reaches_the_frame_budget_publishes_its_closing_and_ends() { + let listing: ListingSource = Arc::new(|| vec!["README.md".to_string()]); + let mut session = budgeted( + 1, + Some(HostOptions { + host_seed: [3; 32], + listing, + store: None, + }), + ); + session.tick(Duration::ZERO); + let out = session.take_outbound(); + let kinds: Vec = out + .iter() + .map(|frame| Envelope::parse(frame).unwrap().kind) + .collect(); + session.tick(millis(1)); + let closing: Vec = session + .take_outbound() + .iter() + .map(|frame| Envelope::parse(frame).unwrap().kind) + .collect(); + assert_eq!( + [kinds, closing].concat().last(), + Some(&2), + "the last frame this host seals is its closing" + ); + assert_eq!(session.ending(), Some(Ending::FrameBudget)); +} + +#[test] +fn a_hold_message_from_a_key_no_state_commits_is_refused() { + // `PROTOCOL.md` §13.4 and `CANONICAL.md` §6.1's step 4: a `kind = 3` frame resolves + // against the keys the applied state commits, and this one commits only ours. + let mut session = session(&[]); + session.tick(Duration::ZERO); + let state = state(&host(), 1, &[(&ours(), "guest", "p-self")]); + let _ = session.deliver(millis(1), &state); + let _ = session.take_outbound(); + assert_eq!( + session.deliver(millis(2), &holds(&peer(), 1, &["README.md"])), + Outcome::Dropped { + reason: "uncommitted_key".to_string() + } + ); + assert!(session.peer_holds().is_empty()); +} + +#[test] +fn a_frame_is_refused_without_ending_the_session() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + assert_eq!( + session.deliver(millis(1), &frame(&peer(), 3, 1, b"{}")), + Outcome::Dropped { + reason: "uncommitted_key".to_string() + } + ); + assert_eq!(session.ending(), None); +} + +#[test] +fn a_denied_auth_message_costs_the_frame_its_other_messages_nothing() { + // §8.3: an auth message is read and ignored, a denial included, and the Update behind + // it in the same frame is applied. + let mut session = beside_a_guest(); + let mut plaintext = + encode_y_message(&YMessage::Auth(Some("denied".to_string()))); + plaintext.extend(update_message("hello")); + assert_eq!( + session.deliver(millis(2), &frame(&peer(), 0, 1, &plaintext)), + Outcome::Applied { kind: 0 } + ); + assert_eq!(session.text("README.md"), "hello"); +} + +#[test] +fn a_frame_of_awareness_queries_draws_no_answer() { + // §8.3: a query message is one byte, so a frame of them would otherwise draw one + // reply each. This client answers none. + let mut session = beside_a_guest(); + let published = session.published(); + let plaintext = vec![3u8; 4096]; + assert_eq!( + session.deliver(millis(2), &frame(&peer(), 0, 1, &plaintext)), + Outcome::Applied { kind: 0 } + ); + assert_eq!(session.take_outbound().len(), 0, "no answer at all"); + assert_eq!(session.published(), published); +} + +#[test] +fn a_frame_of_sync_step1_messages_draws_one_answer() { + // The answer to a SyncStep1 is a whole diff of the document, so one frame is answered + // once however many it carries. + let mut session = beside_a_guest(); + let ask = encode_y_message(&YMessage::Sync(SyncMessage::SyncStep1( + yrs::StateVector::default(), + ))); + let plaintext = ask.repeat(64); + assert_eq!( + session.deliver(millis(2), &frame(&peer(), 0, 1, &plaintext)), + Outcome::Applied { kind: 0 } + ); + let answers = session.take_outbound(); + assert_eq!(answers.len(), 1, "one SyncStep2 for the whole frame"); + let envelope = Envelope::parse(&answers[0]).unwrap(); + let answer = opens(&room_key().frame_key(ROOM), ROOM, &envelope).unwrap(); + assert_eq!(answer.first(), Some(&0), "message type 0: sync"); + assert_eq!(read_varuint(&answer, 1).unwrap().0, 1, "SyncStep2"); +} + +/// One awareness message carrying `json` for each client id, at `clock`. +fn awareness_message(ids: &[u64], clock: u32, json: &str) -> Vec { + let entries: Vec<(u64, u32, &str)> = + ids.iter().map(|id| (*id, clock, json)).collect(); + awareness_entries(&entries) +} + +/// One awareness message carrying each `(client id, clock, json)` entry as it stands. +fn awareness_entries(entries: &[(u64, u32, &str)]) -> Vec { + let clients = entries + .iter() + .map(|(id, clock, json)| { + let entry = AwarenessUpdateEntry { + clock: *clock, + json: Arc::from(*json), + }; + (ClientID::new(*id), entry) + }) + .collect(); + encode_y_message(&YMessage::Awareness(AwarenessUpdate { clients })) +} + +#[test] +fn an_awareness_entry_at_the_maximum_clock_is_refused() { + let mut session = beside_a_guest(); + let states = awareness_entries(&[(41, u32::MAX, "{}"), (42, 1, "{}")]); + assert_eq!( + session.deliver(millis(2), &frame(&peer(), 0, 1, &states)), + Outcome::Applied { kind: 0 } + ); + assert_eq!( + session.awareness_clients(), + [42], + "the entry at the maximum is refused and the rest of the message applies" + ); + + // Nothing is held for 41, so its next publication is a first state whatever clock it + // carries, and the expiry has no clock at the maximum to step. + let first = awareness_entries(&[(41, 1, "{}")]); + let _ = session.deliver(millis(3), &frame(&peer(), 0, 2, &first)); + assert_eq!(session.awareness_clients(), [41, 42]); + session.tick(millis(3 + 900)); + assert!( + session.awareness_clients().is_empty(), + "the refused entry left no state and no stamp behind" + ); +} + +#[test] +fn the_messages_after_a_maximum_clock_entry_still_apply() { + let mut session = beside_a_guest(); + let mut plaintext = awareness_entries(&[(41, u32::MAX, "{}")]); + plaintext.extend(update_message("hello")); + assert_eq!( + session.deliver(millis(2), &frame(&peer(), 0, 1, &plaintext)), + Outcome::Applied { kind: 0 } + ); + assert_eq!(session.text("README.md"), "hello", "the stream went on"); + assert!( + session.awareness_clients().is_empty(), + "41 was not entered at the maximum" + ); +} + +#[test] +fn a_state_at_the_maximum_clock_never_reaches_the_expiry_tick() { + let mut session = beside_a_guest(); + let hostile = awareness_entries(&[(41, u32::MAX, "{}")]); + let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &hostile)); + + // `Awareness::remove_state` steps the clock of the state it drops, unchecked, so a state + // entered at the maximum would step past it here. Refused, there is nothing to step. + session.tick(millis(2 + 900)); + assert!(session.awareness_clients().is_empty(), "not held"); + assert_eq!(session.ending(), None, "the session goes on"); +} + +#[test] +fn a_removal_of_this_connections_own_id_at_the_maximum_clock_is_refused() { + let mut session = beside_a_guest(); + let own = session.awareness_client_id(); + // A peer publishes a state under the id this connection announced (§8.4). + let claimed = awareness_entries(&[(own, 1, "{}")]); + let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &claimed)); + assert_eq!(session.awareness_clients(), [own]); + + // §8.2: a removal for the receiver's own id is not applied, and the receiver takes the + // removal's clock plus one. At the maximum that step is the unchecked one, so the entry + // is refused instead and the state it named stands. + let hostile = awareness_entries(&[(own, u32::MAX, "null")]); + assert_eq!( + session.deliver(millis(3), &frame(&peer(), 0, 2, &hostile)), + Outcome::Applied { kind: 0 } + ); + assert_eq!(session.awareness_clients(), [own], "the state stands"); + + // The session goes on: a renewal above the clock the state actually holds is applied. + let renewed = awareness_entries(&[(own, 2, "{}")]); + let _ = session.deliver(millis(4), &frame(&peer(), 0, 3, &renewed)); + assert_eq!(session.awareness_clients(), [own]); +} + +#[test] +fn a_forgotten_awareness_state_stays_gone_and_its_neighbours_stay() { + let mut session = beside_a_guest(); + let states = awareness_message(&[41, 42], 1, "{\"cursor\":null}"); + let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &states)); + assert_eq!(session.awareness_clients(), [41, 42]); + + session.forget_awareness(41); + assert_eq!(session.awareness_clients(), [42]); + + // A copy of the old state still in flight is older than the removal. + let stale = awareness_message(&[41], 1, "{\"cursor\":null}"); + let _ = session.deliver(millis(3), &frame(&peer(), 0, 2, &stale)); + assert_eq!(session.awareness_clients(), [42], "no resurrection"); +} + +#[test] +fn forgetting_an_id_with_no_state_leaves_its_first_state_welcome() { + let mut session = beside_a_guest(); + session.forget_awareness(43); + let first = awareness_message(&[43], 1, "{}"); + let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &first)); + assert_eq!(session.awareness_clients(), [43]); +} + +#[test] +fn this_connections_own_awareness_id_is_never_forgotten() { + let mut session = beside_a_guest(); + let own = session.awareness_client_id(); + let states = awareness_message(&[own], 1, "{}"); + let _ = session.deliver(millis(2), &frame(&peer(), 0, 1, &states)); + assert_eq!(session.awareness_clients(), [own]); + session.forget_awareness(own); + assert_eq!(session.awareness_clients(), [own]); +} + +/// A sync Update whose one item is an `Any` opening `depth` one-element arrays inside one +/// another around a `null`. It is built by hand because no document holds such a value: +/// one client's group of one struct, client 1 at clock 0, an `Any` item (info 8) under the +/// root named `x` carrying one value, then an empty delete set. +fn nested_any_update(depth: usize) -> Vec { + let mut update = vec![1, 1, 1, 0, 8, 1, 1, b'x', 1]; + for _ in 0..depth { + update.extend([117, 1]); + } + update.extend([126, 0]); + encode_y_message(&YMessage::Sync(SyncMessage::Update(update))) +} + +#[test] +fn an_update_nested_past_any_stack_is_refused_and_the_session_goes_on() { + // Two bytes a level: a million levels is two megabytes, and no thread's stack holds a + // recursive reader that deep. + let mut session = beside_a_guest(); + let hostile = frame(&peer(), 0, 1, &nested_any_update(1 << 20)); + assert_eq!( + session.deliver(millis(2), &hostile), + Outcome::Dropped { + reason: "bad_payload".to_string() + } + ); + assert_eq!( + session.deliver(millis(3), &content(&peer(), 2, "after")), + Outcome::Applied { kind: 0 } + ); + assert_eq!(session.text("README.md"), "after"); +} + +#[test] +fn a_frame_carrying_a_nested_update_is_refused_whole() { + // The refusal is the frame's, before anything in it is applied: an edit ahead of the + // hostile update in the same stream is not applied either. + let mut session = beside_a_guest(); + let mut plaintext = update_message("hello"); + plaintext.extend(nested_any_update(MAX_ANY_DEPTH + 1)); + assert_eq!( + session.deliver(millis(2), &frame(&peer(), 0, 1, &plaintext)), + Outcome::Dropped { + reason: "bad_payload".to_string() + } + ); + assert_eq!(session.text("README.md"), ""); +} + +#[test] +fn an_update_nested_to_the_bound_is_applied() { + let mut session = beside_a_guest(); + let mut plaintext = nested_any_update(MAX_ANY_DEPTH); + plaintext.extend(update_message("hello")); + assert_eq!( + session.deliver(millis(2), &frame(&peer(), 0, 1, &plaintext)), + Outcome::Applied { kind: 0 } + ); + assert_eq!(session.text("README.md"), "hello"); +} + +fn invite(room: RoomKey, fragment: &str) -> String { + format!("/session?room={ROOM}&token=t-1#{fragment}") + .replace("$k", &encode_key(&[7; 32])) + .replace("$h", &host().public().encode()) + .replace("$room", &encode_key(&room.0)) +} + +#[test] +fn the_invite_carries_the_room_and_both_keys_and_the_fragment_is_stripped() { + let link = invite(room_key(), "k=$k&h=$h"); + let parsed = PeerInvite::parse(&link).unwrap(); + assert_eq!(parsed.room, ROOM); + assert_eq!(parsed.token, "t-1"); + assert_eq!(parsed.room_key, RoomKey([7; 32])); + assert_eq!(parsed.host_key, host().public()); + assert!(!parsed.socket_url.contains('#')); +} + +#[test] +fn an_invite_with_no_fragment_or_with_a_value_that_is_not_a_key_is_refused_locally() + { + let missing = format!("/session?room={ROOM}&token=t-1"); + assert!( + PeerInvite::parse(&missing) + .unwrap_err() + .contains("fragment") + ); + + let short = invite(room_key(), "k=AAAA&h=$h"); + assert!(PeerInvite::parse(&short).unwrap_err().contains("`k`")); + + let twice = invite(room_key(), "k=$k&k=$k&h=$h"); + assert!(PeerInvite::parse(&twice).unwrap_err().contains("twice")); + + // §6.1: the final character of a 32-byte value carries two zero bits, so a spelling + // whose last character is any other spells no key. + let uncanonical = invite(room_key(), "k=$kB&h=$h"); + assert!(PeerInvite::parse(&uncanonical).unwrap_err().contains("`k`")); + + let no_host = invite(room_key(), "k=$k"); + assert!(PeerInvite::parse(&no_host).unwrap_err().contains("`h`")); +} + +/// §5.1: the fragment's two keys are read to be used, never repeated. A `Debug` that +/// printed them would put both in whatever log an invite — or the options a session is +/// built from — is written to, which is the one thing the fragment exists to prevent. +#[test] +fn the_invites_keys_are_not_printed_by_debug() { + let room_key = room_key(); + let host_key = host().public(); + let parsed = PeerInvite::parse(&invite(room_key, "k=$k&h=$h")).unwrap(); + let printed = format!("{parsed:?}"); + assert!( + !printed.contains(&format!("{room_key:?}")), + "the room key was printed: {printed}" + ); + assert!( + !printed.contains(&format!("{host_key:?}")), + "the host key was printed: {printed}" + ); + // A `Debug` that printed a key in the encoding §5.1's fragment carries it in is a key + // printed, and neither `Debug` spelling above is that string: the value itself is the + // needle that reaches it. + assert!( + !printed.contains(&encode_key(&room_key.0)) + && !printed.contains(&host_key.encode()), + "the encoded form of a key the invite holds was printed: {printed}" + ); + + let options = PeerOptions { + room_id: ROOM.to_string(), + room_key, + host_key, + renew: Duration::from_millis(300), + expire: Duration::from_millis(900), + seat: Some("p-self".to_string()), + roster: BTreeSet::new(), + fixed_session_key: Some([5; 32]), + declared_role: None, + awareness_client_id: None, + host: None, + frame_budget: None, + }; + let printed = format!("{options:?}"); + assert!( + !printed.contains(&format!("{room_key:?}")) + && !printed.contains(&format!("{host_key:?}")), + "a key the options hold was printed: {printed}" + ); + assert!( + !printed.contains(&encode_key(&room_key.0)) + && !printed.contains(&host_key.encode()), + "the encoded form of a key the options hold was printed: {printed}" + ); +} + +#[test] +fn the_page_link_is_the_same_room_token_and_fragment_over_the_browsers_scheme() +{ + // `PROTOCOL.md` §5.1's second form: the page the room's server serves, over the scheme + // a browser speaks, with the same host, port and path prefix and nothing else in it. + let room = encode_key(&room_key().0); + let host_key = host().public().encode(); + let page = + format!("http://h:8080/?room={ROOM}&token=t-1#k={room}&h={host_key}"); + let wire = format!("ws://h:8080/session?room={ROOM}&token=t-1"); + assert_eq!( + wire_address(&page), + wire, + "the page reads back as the same connection address, fragment left off" + ); + // §5.1: the fragment is the one part a request never carries, so the address is the + // whole of what `wire_address` hands back however it is called. Re-appending the + // fragment and handing the result to `parse_session_url` would glue `k` onto `token` + // and put the room key in the URL a socket is dialled on. + let door = wire_address(&page); + assert!( + !door.contains('#') + && !door.contains(&room) + && !door.contains(&host_key), + "no key byte and no fragment survives the address reading: {door}" + ); + assert_eq!( + proto::parse_session_url(&door) + .unwrap() + .join + .token + .as_deref(), + Some("t-1"), + "the token stays the query's own, nothing glued onto it" + ); + let parsed = PeerInvite::parse(&page).unwrap(); + assert_eq!( + parsed.socket_url, wire, + "and the address a socket is opened on carries no fragment" + ); + assert_eq!(parsed.room, ROOM); + assert_eq!(parsed.token, "t-1"); + assert_eq!(parsed.room_key, room_key()); + assert_eq!(parsed.host_key, host().public()); + + // A path prefix survives the reading: the page is served under it and the endpoint is + // under it too. + let mounted = + format!("https://h/page/?room={ROOM}&token=t-1#k={room}&h={host_key}"); + assert_eq!( + PeerInvite::parse(&mounted).unwrap().socket_url, + format!("wss://h/page/session?room={ROOM}&token=t-1") + ); + + // A link that is already a connection URL is handed back exactly as it stands. + assert_eq!(wire_address(&wire), wire); + assert!( + PeerInvite::parse(&wire).unwrap_err().contains("fragment"), + "a connection URL still carries no fragment" + ); + // And one this cannot read as either form is not silently rewritten. + assert_eq!(wire_address("wss://h/other?room=r"), "wss://h/other?room=r"); +} + +/// §5.1: `room` and `token` each appear at most once, in either form. A page link has no +/// server in it, so the receiver refuses a repeat itself and names the parameter — the shape +/// the fragment's rule already takes for `k` and `h` — rather than reporting that the address +/// names no endpoint, which is what the reader of the old message was told. +#[test] +fn a_page_link_that_repeats_a_join_key_is_refused_by_name() { + let room = encode_key(&room_key().0); + let host_key = host().public().encode(); + let twice_room = format!( + "https://h/?room=r-1&room=r-other&token=t-1#k={room}&h={host_key}" + ); + assert_eq!( + PeerInvite::parse(&twice_room).unwrap_err(), + "the invite names `room` twice" + ); + let twice_token = format!( + "https://h/?room=r-1&token=t-1&token=t-other#k={room}&h={host_key}" + ); + assert_eq!( + PeerInvite::parse(&twice_token).unwrap_err(), + "the invite names `token` twice" + ); + // The `wss://` form is read through the same query rule and names the repeat too. + let wire_repeat = format!( + "wss://h/session?room=r-1&room=r-other&token=t-1#k={room}&h={host_key}" + ); + assert_eq!( + PeerInvite::parse(&wire_repeat).unwrap_err(), + "the invite names `room` twice" + ); + // A link that genuinely names no endpoint keeps the generic refusal: a repeat is not + // what is wrong with it. + let elsewhere = + format!("wss://h/other?room=r-1&token=t-1#k={room}&h={host_key}"); + assert_eq!( + PeerInvite::parse(&elsewhere).unwrap_err(), + "\"wss://h/other?room=r-1&token=t-1\" does not address the session endpoint" + ); +} + +// --- §13.6: the bounded reciprocal request, the shared clock and local readiness ----- + +#[test] +fn a_committed_writers_first_request_arms_one_coalesced_reciprocal_request() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + let committing = state( + &host(), + 1, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + session.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + // The immediate initial request: the clock every later request is measured from. + let initial = session.take_outbound(); + assert_eq!(initial.len(), 1); + assert_eq!(sync_subtype(&initial[0]), Some(0)); + + // The first `SyncStep1` from a committed writer is answered and remembered. + assert_eq!( + session.deliver(millis(2), &frame(&peer(), 0, 1, &step1())), + Outcome::Applied { kind: 0 } + ); + let answer = session.take_outbound(); + assert_eq!(answer.len(), 1, "one Step2 for the request"); + assert_eq!(sync_subtype(&answer[0]), Some(1)); + + // The request clock is 1, so the window opens at 301. + session.tick(millis(300)); + assert!(session.take_outbound().is_empty(), "not before the clock"); + session.tick(millis(301)); + let reciprocal = session.take_outbound(); + assert_eq!(reciprocal.len(), 1, "one coalesced reciprocal request"); + assert_eq!(sync_subtype(&reciprocal[0]), Some(0)); + + // A later request from the same continuously eligible key draws its Step2 only. + assert_eq!( + session.deliver(millis(302), &frame(&peer(), 0, 2, &step1())), + Outcome::Applied { kind: 0 } + ); + let again = session.take_outbound(); + assert_eq!(again.len(), 1, "one Step2 per inbound frame"); + assert_eq!(sync_subtype(&again[0]), Some(1)); + session.tick(millis(601)); + session.tick(millis(901)); + assert!( + session.take_outbound().is_empty(), + "the served census stops the echo" + ); +} + +#[test] +fn a_viewers_request_does_not_arm_a_reciprocal_request() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + let committing = state( + &host(), + 1, + &[ + (&ours(), "guest", "p-self"), + (&peer(), "viewer", "p-viewer"), + ], + ); + assert_eq!( + session.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert_eq!( + session.deliver(millis(2), &frame(&peer(), 0, 1, &step1())), + Outcome::Applied { kind: 0 } + ); + let answer = session.take_outbound(); + assert_eq!(answer.len(), 1); + assert_eq!(sync_subtype(&answer[0]), Some(1), "the request is answered"); + session.tick(millis(302)); + session.tick(millis(602)); + assert!( + session.take_outbound().is_empty(), + "a viewer sends no content, so there is nothing to ask for" + ); +} + +#[test] +fn a_step2_or_update_never_arms_a_reciprocal_request() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + let committing = state( + &host(), + 1, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + session.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert_eq!( + session.deliver(millis(2), &content(&peer(), 1, "theirs")), + Outcome::Applied { kind: 0 } + ); + assert_eq!( + session.deliver(millis(3), &content(&peer(), 2, "more")), + Outcome::Applied { kind: 0 } + ); + session.tick(millis(303)); + session.tick(millis(603)); + assert!( + session.take_outbound().is_empty(), + "content never asks for a request" + ); +} + +#[test] +fn several_new_writer_keys_in_one_window_draw_one_broadcast_request() { + let mut session = session(&[]); + let third = SessionKey::from_seed([17; 32]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + let committing = state( + &host(), + 1, + &[ + (&ours(), "guest", "p-self"), + (&peer(), "guest", "p-other"), + (&third, "guest", "p-third"), + ], + ); + assert_eq!( + session.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert_eq!( + session.deliver(millis(2), &frame(&peer(), 0, 1, &step1())), + Outcome::Applied { kind: 0 } + ); + assert_eq!( + session.deliver(millis(3), &frame(&third, 0, 1, &step1())), + Outcome::Applied { kind: 0 } + ); + let answers = session.take_outbound(); + assert_eq!(answers.len(), 2, "each request is answered"); + session.tick(millis(303)); + let requests = session.take_outbound(); + assert_eq!(requests.len(), 1, "the two new keys coalesce"); + assert_eq!(sync_subtype(&requests[0]), Some(0)); +} + +#[test] +fn a_valid_request_prefix_survives_a_malformed_suffix() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + let committing = state( + &host(), + 1, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + session.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + let mut plaintext = step1(); + plaintext.extend_from_slice(&[0, 0, 1, 128]); + assert_eq!( + session.deliver(millis(2), &frame(&peer(), 0, 1, &plaintext)), + Outcome::Applied { kind: 0 } + ); + let answer = session.take_outbound(); + assert_eq!(answer.len(), 1, "the valid prefix is answered"); + assert_eq!(sync_subtype(&answer[0]), Some(1)); + session.tick(millis(301)); + let request = session.take_outbound(); + assert_eq!(request.len(), 1, "the valid prefix still owes readiness"); + assert_eq!(sync_subtype(&request[0]), Some(0)); +} + +#[test] +fn a_malformed_first_message_arms_nothing_and_a_later_valid_request_does() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + let committing = state( + &host(), + 1, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + session.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert_eq!( + session.deliver(millis(2), &frame(&peer(), 0, 1, &[0, 0, 1, 128])), + Outcome::Applied { kind: 0 } + ); + assert!( + session.take_outbound().is_empty(), + "an invalid first message is not answered" + ); + session.tick(millis(300)); + assert!( + session.take_outbound().is_empty(), + "a malformed request must not arm readiness" + ); + assert_eq!( + session.deliver(millis(301), &frame(&peer(), 0, 2, &step1())), + Outcome::Applied { kind: 0 } + ); + let answer = session.take_outbound(); + assert_eq!(answer.len(), 1); + assert_eq!(sync_subtype(&answer[0]), Some(1)); + session.tick(millis(601)); + let request = session.take_outbound(); + assert_eq!(request.len(), 1, "the valid request armed the obligation"); + assert_eq!(sync_subtype(&request[0]), Some(0)); +} + +#[test] +fn a_local_reentry_after_absence_owes_one_coalesced_readiness_request() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + let first = state(&host(), 1, &[(&ours(), "guest", "p-self")]); + assert_eq!( + session.deliver(millis(1), &first), + Outcome::Applied { kind: 1 } + ); + let initial = session.take_outbound(); + assert_eq!( + initial.len(), + 1, + "the first commitment owes the initial request" + ); + assert_eq!(sync_subtype(&initial[0]), Some(0)); + session.tick(millis(2)); + assert!( + session.take_outbound().is_empty(), + "the first commitment adds no readiness" + ); + + // The key is dropped, then recommitted as a writer: a new continuous eligibility. + assert_eq!( + session.deliver(millis(3), &state(&host(), 2, &[])), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert_eq!( + session.deliver( + millis(4), + &state(&host(), 3, &[(&ours(), "guest", "p-self")]) + ), + Outcome::Applied { kind: 1 } + ); + assert!( + session.take_outbound().is_empty(), + "a state cannot send renewed readiness immediately" + ); + session.tick(millis(300)); + assert!(session.take_outbound().is_empty(), "not before the clock"); + session.tick(millis(301)); + let readiness = session.take_outbound(); + assert_eq!(readiness.len(), 1); + assert_eq!(sync_subtype(&readiness[0]), Some(0)); + session.tick(millis(601)); + session.tick(millis(901)); + assert!( + session.take_outbound().is_empty(), + "readiness is served once per eligibility" + ); +} + +#[test] +fn an_uninterrupted_writer_eligibility_and_listing_editions_never_rearm() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + let first = state( + &host(), + 1, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + session.deliver(millis(1), &first), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + let changed = state( + &host(), + 2, + &[(&ours(), "host", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + session.deliver(millis(2), &changed), + Outcome::Applied { kind: 1 } + ); + let listing = state_listing( + &host(), + 3, + &[(&ours(), "host", "p-self"), (&peer(), "guest", "p-other")], + &["README.md", "other.md"], + ); + assert_eq!( + session.deliver(millis(3), &listing), + Outcome::Applied { kind: 1 } + ); + assert!( + session.take_outbound().is_empty(), + "a host/guest change and a listing edition owe nothing" + ); + session.tick(millis(301)); + assert!( + session.take_outbound().is_empty(), + "uninterrupted eligibility never rearms" + ); +} + +#[test] +fn local_readiness_retires_when_writer_eligibility_ends_before_service() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + assert_eq!( + session.deliver( + millis(1), + &state(&host(), 1, &[(&ours(), "guest", "p-self")]) + ), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + // Re-entry arms readiness, then eligibility ends before the window opens. + assert_eq!( + session.deliver(millis(2), &state(&host(), 2, &[])), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert_eq!( + session.deliver( + millis(3), + &state(&host(), 3, &[(&ours(), "guest", "p-self")]) + ), + Outcome::Applied { kind: 1 } + ); + assert_eq!( + session.deliver( + millis(4), + &state(&host(), 4, &[(&ours(), "viewer", "p-self")]) + ), + Outcome::Applied { kind: 1 } + ); + assert!(session.take_outbound().is_empty()); + session.tick(millis(301)); + assert!( + session.take_outbound().is_empty(), + "retired readiness must not be served" + ); +} + +#[test] +fn a_remote_demotion_and_re_promotion_rearms_exactly_one_request() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + let first = state( + &host(), + 1, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + session.deliver(millis(1), &first), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert_eq!( + session.deliver(millis(2), &frame(&peer(), 0, 1, &step1())), + Outcome::Applied { kind: 0 } + ); + let _ = session.take_outbound(); + session.tick(millis(301)); + let armed = session.take_outbound(); + assert_eq!(armed.len(), 1, "the first eligibility armed once"); + assert_eq!(sync_subtype(&armed[0]), Some(0)); + + // The peer is demoted, so its census entry goes; re-promotion arms once more. + let demoted = state( + &host(), + 2, + &[(&ours(), "guest", "p-self"), (&peer(), "viewer", "p-other")], + ); + assert_eq!( + session.deliver(millis(302), &demoted), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + let promoted = state( + &host(), + 3, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + session.deliver(millis(303), &promoted), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert_eq!( + session.deliver(millis(304), &frame(&peer(), 0, 2, &step1())), + Outcome::Applied { kind: 0 } + ); + let _ = session.take_outbound(); + session.tick(millis(601)); + let rearmed = session.take_outbound(); + assert_eq!(rearmed.len(), 1, "the new eligibility armed once"); + assert_eq!(sync_subtype(&rearmed[0]), Some(0)); +} +/// §13.6: activation is the remote writer's eligibility, so a request is recorded even while +/// this connection is uncommitted and may not publish; the shared clock then serves it once +/// the local key can publish again. Gating activation on local commitment would drop it. +#[test] +fn a_remote_request_arms_while_uncommitted_and_is_served_after_recommitment() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + // L is committed as a viewer and takes the initial request: the clock later ones use. + assert_eq!( + session.deliver(millis(1), &viewer_beside_writer(1)), + Outcome::Applied { kind: 1 } + ); + let initial = session.take_outbound(); + assert_eq!( + initial.len(), + 1, + "a committed viewer still takes the initial request" + ); + assert_eq!(sync_subtype(&initial[0]), Some(0)); + + // A newer state drops L while W stays a committed writer, so L cannot publish at all. + assert_eq!( + session.deliver( + millis(2), + &state(&host(), 2, &[(&peer(), "guest", "p-other")]) + ), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + + // W's first valid request in this eligibility is recognised though L is uncommitted. + assert_eq!( + session.deliver(millis(3), &frame(&peer(), 0, 1, &step1())), + Outcome::Applied { kind: 0 } + ); + assert!( + session.take_outbound().is_empty(), + "an uncommitted receiver answers nothing" + ); + + // L is recommitted as a viewer with W retained: the remote cause survives the local gate. + assert_eq!( + session.deliver(millis(4), &viewer_beside_writer(3)), + Outcome::Applied { kind: 1 } + ); + assert!( + session.take_outbound().is_empty(), + "a state cannot send the request immediately" + ); + session.tick(millis(300)); + assert!(session.take_outbound().is_empty(), "not before the clock"); + session.tick(millis(301)); + let served = session.take_outbound(); + assert_eq!( + served.len(), + 1, + "the remote request is served once at the due tick" + ); + assert_eq!(sync_subtype(&served[0]), Some(0)); + + // Served once: a continuously committed key does not rearm over later windows. + session.tick(millis(601)); + session.tick(millis(901)); + assert!( + session.take_outbound().is_empty(), + "a served remote eligibility does not rearm" + ); +} + +/// The companion: a request whose writer is removed or demoted before the local key returns +/// is retired with that writer's eligibility, so no request is owed. +#[test] +fn a_remote_request_for_a_key_that_leaves_before_the_return_owes_nothing() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + assert_eq!( + session.deliver( + millis(1), + &state( + &host(), + 1, + &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")] + ) + ), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert_eq!( + session.deliver( + millis(2), + &state(&host(), 2, &[(&peer(), "guest", "p-other")]) + ), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert_eq!( + session.deliver(millis(3), &frame(&peer(), 0, 1, &step1())), + Outcome::Applied { kind: 0 } + ); + let _ = session.take_outbound(); + + // W is demoted before L comes back: the obligation retires with its eligibility. + assert_eq!( + session.deliver( + millis(4), + &state( + &host(), + 3, + &[ + (&ours(), "viewer", "p-self"), + (&peer(), "viewer", "p-other") + ] + ) + ), + Outcome::Applied { kind: 1 } + ); + assert!(session.take_outbound().is_empty()); + session.tick(millis(301)); + session.tick(millis(601)); + assert!( + session.take_outbound().is_empty(), + "a retired request owes nothing" + ); +} + +/// Retiring a remote cause must not erase the refusal interval or local readiness sharing the +/// same clock: one request serves every remaining obligation. +#[test] +fn a_retired_remote_request_leaves_the_refusal_and_readiness_causes() { + let mut session = session(&[]); + let unmoved = SessionKey::from_seed([23; 32]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + assert_eq!( + session.deliver( + millis(1), + &state( + &host(), + 1, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")] + ) + ), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert_eq!( + session.deliver( + millis(2), + &state(&host(), 2, &[(&peer(), "guest", "p-other")]) + ), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + // W's request arms the remote cause. + assert_eq!( + session.deliver(millis(3), &frame(&peer(), 0, 1, &step1())), + Outcome::Applied { kind: 0 } + ); + let _ = session.take_outbound(); + // A content frame from a key no state commits opens §13.6's refusal interval. + assert_eq!( + session.deliver(millis(4), &content(&unmoved, 1, "theirs")), + Outcome::Dropped { + reason: "uncommitted_key".to_string() + } + ); + // L returns as a writer and W is demoted: the remote cause retires, a new eligibility + // begins for L, and the refusal interval is still open. + assert_eq!( + session.deliver( + millis(5), + &state( + &host(), + 3, + &[(&ours(), "guest", "p-self"), (&peer(), "viewer", "p-other")] + ) + ), + Outcome::Applied { kind: 1 } + ); + assert!(session.take_outbound().is_empty()); + session.tick(millis(300)); + assert!(session.take_outbound().is_empty(), "not before the clock"); + session.tick(millis(301)); + let served = session.take_outbound(); + assert_eq!( + served.len(), + 1, + "refusal and readiness survive the retired remote cause" + ); + assert_eq!(sync_subtype(&served[0]), Some(0)); +} + +#[test] +fn a_viewers_local_edits_never_enter_room_history() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + let as_viewer = state( + &host(), + 1, + &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + session.deliver(millis(1), &as_viewer), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert!(!session.insert("README.md", 0, "secret").unwrap()); + assert_eq!( + session.text("README.md"), + "", + "the disallowed edit is not even locally visible" + ); + assert!(session.take_outbound().is_empty()); + + // Promotion with the same key: the request is answered from room-safe history alone. + let as_writer = state( + &host(), + 2, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + session.deliver(millis(2), &as_writer), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert_eq!( + session.deliver(millis(3), &frame(&peer(), 0, 1, &step1())), + Outcome::Applied { kind: 0 } + ); + let answer = session.take_outbound(); + assert_eq!(answer.len(), 1); + assert_eq!(sync_subtype(&answer[0]), Some(1)); + assert_eq!( + step2_text(&answer[0]), + "", + "no viewer history is exported on promotion" + ); +} + +#[test] +fn an_unknown_role_edit_is_discarded_when_a_viewer_state_arrives() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + assert!( + !session.insert("README.md", 0, "spec").unwrap(), + "held while the role is unknown" + ); + assert_eq!( + session.text("README.md"), + "spec", + "held locally while unknown" + ); + let as_viewer = state( + &host(), + 1, + &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + session.deliver(millis(1), &as_viewer), + Outcome::Applied { kind: 1 } + ); + assert_eq!( + session.text("README.md"), + "", + "the viewer state discards the speculative edit" + ); + let _ = session.take_outbound(); + + // Re-promotion: the discarded edit never returns. + let as_writer = state( + &host(), + 2, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + session.deliver(millis(2), &as_writer), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert_eq!( + session.deliver(millis(3), &frame(&peer(), 0, 1, &step1())), + Outcome::Applied { kind: 0 } + ); + let answer = session.take_outbound(); + assert_eq!(answer.len(), 1); + assert_eq!( + step2_text(&answer[0]), + "", + "the discarded edit never returns" + ); +} + +#[test] +fn a_demoted_writer_keeps_its_history_and_exports_no_viewer_edit() { + let mut session = session(&[]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + let as_writer = state( + &host(), + 1, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + session.deliver(millis(1), &as_writer), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert!(session.insert("README.md", 0, "legit").unwrap()); + let _ = session.take_outbound(); + + let as_viewer = state( + &host(), + 2, + &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + session.deliver(millis(2), &as_viewer), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert!(!session.insert("README.md", 5, "bad").unwrap()); + assert_eq!( + session.text("README.md"), + "legit", + "the viewer edit is discarded" + ); + + // Promotion: the writer history survives and is exported. + let promoted = state( + &host(), + 3, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + session.deliver(millis(3), &promoted), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert_eq!( + session.deliver(millis(4), &frame(&peer(), 0, 1, &step1())), + Outcome::Applied { kind: 0 } + ); + let answer = session.take_outbound(); + assert_eq!(answer.len(), 1); + assert_eq!( + step2_text(&answer[0]), + "legit", + "the writer history is preserved" + ); +} + +#[test] +fn three_writer_requests_coalesce_and_the_room_quiesces() { + let mut session = session(&[]); + let third = SessionKey::from_seed([17; 32]); + session.tick(Duration::ZERO); + let _ = session.take_outbound(); + let committing = state( + &host(), + 1, + &[ + (&ours(), "guest", "p-self"), + (&peer(), "guest", "p-other"), + (&third, "guest", "p-third"), + ], + ); + assert_eq!( + session.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + let _ = session.take_outbound(); + assert_eq!( + session.deliver(millis(2), &frame(&peer(), 0, 1, &step1())), + Outcome::Applied { kind: 0 } + ); + assert_eq!( + session.deliver(millis(3), &frame(&third, 0, 1, &step1())), + Outcome::Applied { kind: 0 } + ); + let answers = session.take_outbound(); + assert_eq!(answers.len(), 2, "each request draws its own Step2"); + session.tick(millis(303)); + let request = session.take_outbound(); + assert_eq!(request.len(), 1, "one coalesced request for both keys"); + assert_eq!(sync_subtype(&request[0]), Some(0)); + // No obligation left, so later windows are silent. + session.tick(millis(603)); + session.tick(millis(903)); + session.tick(millis(1203)); + assert!( + session.take_outbound().is_empty(), + "no periodic full sync without an obligation" + ); +} +/// One round of a three-peer room: each session hears the other two's frames, answers each +/// with exactly one Step2, and arms nothing new. +/// The two frames one session hears in a three-peer round. +type Heard<'a> = [&'a [u8]; 2]; + +fn three_way_round( + trio: [&mut PeerSession; 3], + clock: Duration, + heard: [Heard<'_>; 3], +) { + for (peer, [first, second]) in trio.into_iter().zip(heard) { + assert_eq!(peer.deliver(clock, first), Outcome::Applied { kind: 0 }); + assert_eq!(peer.deliver(clock, second), Outcome::Applied { kind: 0 }); + let answers = peer.take_outbound(); + assert_eq!(answers.len(), 2, "each request draws one Step2"); + assert!(answers.iter().all(|frame| sync_subtype(frame) == Some(1))); + } +} + +/// Three real sessions, each with its own replica and key: every pair's reciprocal exchange +/// is bounded, one coalesced request per session per window, and the room falls quiet. The +/// older three-writer test drives one receiver and two signers, which is a census bound and +/// not an all-room one. +#[test] +#[expect( + clippy::too_many_lines, + reason = "the three-peer exchange, its bounded counts and the quiet windows are one sequence" +)] +fn three_real_sessions_exchange_reciprocally_and_then_quiesce() { + let mut alpha = session(&["p-other", "p-third"]); + let mut beta = second_session(&["p-self", "p-third"]); + let mut gamma = third_session(&["p-self", "p-other"]); + for peer in [&mut alpha, &mut beta, &mut gamma] { + peer.tick(Duration::ZERO); + let _ = peer.take_outbound(); + } + let committing = state( + &host(), + 1, + &[ + (&ours(), "guest", "p-self"), + (&peer(), "guest", "p-other"), + (&third(), "guest", "p-third"), + ], + ); + let mut initial = Vec::new(); + for peer in [&mut alpha, &mut beta, &mut gamma] { + assert_eq!( + peer.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + let frames = peer.take_outbound(); + assert_eq!( + frames.len(), + 1, + "the first commitment owes one initial request" + ); + assert_eq!(sync_subtype(&frames[0]), Some(0)); + initial.push(frames[0].clone()); + } + three_way_round( + [&mut alpha, &mut beta, &mut gamma], + millis(2), + [ + [initial[1].as_slice(), initial[2].as_slice()], + [initial[0].as_slice(), initial[2].as_slice()], + [initial[0].as_slice(), initial[1].as_slice()], + ], + ); + // One coalesced request per session at the shared clock, not one per writer key. + let mut requests = Vec::new(); + for peer in [&mut alpha, &mut beta, &mut gamma] { + peer.tick(millis(300)); + assert!(peer.take_outbound().is_empty(), "not before the clock"); + peer.tick(millis(301)); + let frames = peer.take_outbound(); + assert_eq!( + frames.len(), + 1, + "the two obligations coalesce into one request" + ); + assert_eq!(sync_subtype(&frames[0]), Some(0)); + requests.push(frames[0].clone()); + } + three_way_round( + [&mut alpha, &mut beta, &mut gamma], + millis(302), + [ + [requests[1].as_slice(), requests[2].as_slice()], + [requests[0].as_slice(), requests[2].as_slice()], + [requests[0].as_slice(), requests[1].as_slice()], + ], + ); + // One session's edit reaches the other two; all three replicas agree and nothing replies. + assert!(alpha.insert("README.md", 0, "x").unwrap()); + let edit = alpha.take_outbound(); + assert_eq!(edit.len(), 1, "the edit publishes"); + assert_eq!( + beta.deliver(millis(303), &edit[0]), + Outcome::Applied { kind: 0 } + ); + assert_eq!( + gamma.deliver(millis(303), &edit[0]), + Outcome::Applied { kind: 0 } + ); + assert!( + beta.take_outbound().is_empty() && gamma.take_outbound().is_empty(), + "content draws no reply" + ); + assert_eq!(alpha.state_vector(), beta.state_vector()); + assert_eq!(beta.state_vector(), gamma.state_vector()); + + for peer in [&mut alpha, &mut beta, &mut gamma] { + peer.tick(millis(601)); + peer.tick(millis(901)); + peer.tick(millis(1201)); + assert!( + peer.take_outbound().is_empty(), + "no periodic full sync without an obligation" + ); + } +} + +/// A retained same-key session keeps its replica through an omission and recommitment, owes +/// one renewed readiness request, and keeps editing on that same replica. +#[test] +fn a_recommitted_same_key_retains_its_replica_and_keeps_editing() { + let mut writer = session(&["p-other"]); + let mut receiver = second_session(&["p-self"]); + writer.tick(Duration::ZERO); + receiver.tick(Duration::ZERO); + let _ = writer.take_outbound(); + let _ = receiver.take_outbound(); + let committing = state( + &host(), + 1, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + writer.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + assert_eq!( + receiver.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + let _ = writer.take_outbound(); + let _ = receiver.take_outbound(); + + // The receiver edits as a committed writer; the writer applies that history. + assert!(receiver.insert("README.md", 0, "abc").unwrap()); + let edit = receiver.take_outbound(); + assert_eq!(edit.len(), 1); + assert_eq!( + writer.deliver(millis(2), &edit[0]), + Outcome::Applied { kind: 0 } + ); + assert_eq!(receiver.state_vector(), writer.state_vector()); + let vector = receiver.state_vector(); + + // The receiver's key is dropped, then recommitted under the same key. + let omitted = state(&host(), 2, &[(&ours(), "guest", "p-self")]); + assert_eq!( + receiver.deliver(millis(3), &omitted), + Outcome::Applied { kind: 1 } + ); + let _ = receiver.take_outbound(); + let recommitted = state( + &host(), + 3, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + receiver.deliver(millis(4), &recommitted), + Outcome::Applied { kind: 1 } + ); + assert!( + receiver.take_outbound().is_empty(), + "a state cannot send the renewed readiness immediately" + ); + // The retained replica is untouched by the omission and recommitment. + assert_eq!(receiver.text("README.md"), "abc"); + assert_eq!(receiver.state_vector(), vector); + + receiver.tick(millis(300)); + assert!(receiver.take_outbound().is_empty(), "not before the clock"); + receiver.tick(millis(301)); + let readiness = receiver.take_outbound(); + assert_eq!( + readiness.len(), + 1, + "recommitment owes one readiness request" + ); + assert_eq!(sync_subtype(&readiness[0]), Some(0)); + assert!(receiver.insert("README.md", 3, "d").unwrap()); + assert_eq!( + receiver.take_outbound().len(), + 1, + "the continued edit publishes" + ); + assert_eq!(receiver.text("README.md"), "abcd"); +} + +/// Two real sessions, one lost `Update`: the reciprocal request carries the missing struct +/// back and the replicas converge with no further edit, no new key and no refusal. +#[test] +fn a_lost_update_is_recovered_by_the_reciprocal_request() { + let mut writer = session(&["p-other"]); + let mut receiver = second_session(&["p-self"]); + writer.tick(Duration::ZERO); + receiver.tick(Duration::ZERO); + let _ = writer.take_outbound(); + let _ = receiver.take_outbound(); + let committing = state( + &host(), + 1, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + writer.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + assert_eq!( + receiver.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + let writer_initial = writer.take_outbound(); + let _ = receiver.take_outbound(); + assert_eq!(writer_initial.len(), 1); + + // The receiver sees the writer's request and arms one reciprocal obligation. + assert_eq!( + receiver.deliver(millis(2), &writer_initial[0]), + Outcome::Applied { kind: 0 } + ); + let _ = receiver.take_outbound(); + + // The writer inserts, and the frame carrying the first insertion is lost on the way. + assert!(writer.insert("README.md", 0, "off ").unwrap()); + let lost = writer.take_outbound(); + assert_eq!(lost.len(), 1); + // A second, dependent insertion is delivered: the receiver holds it pending. + assert!(writer.insert("README.md", 0, "on ").unwrap()); + let dependent = writer.take_outbound(); + assert_eq!(dependent.len(), 1); + assert_eq!( + receiver.deliver(millis(3), &dependent[0]), + Outcome::Applied { kind: 0 } + ); + assert_eq!( + receiver.text("README.md"), + "", + "the dependent insertion waits for its dependency" + ); + + // The reciprocal request recovers the missing history without a new edit or key. + receiver.tick(millis(302)); + let request = receiver.take_outbound(); + assert_eq!(request.len(), 1, "one coalesced reciprocal request"); + assert_eq!(sync_subtype(&request[0]), Some(0)); + assert_eq!( + writer.deliver(millis(303), &request[0]), + Outcome::Applied { kind: 0 } + ); + let repair = writer.take_outbound(); + let step2 = repair + .iter() + .find(|frame| sync_subtype(frame.as_slice()) == Some(1)) + .expect("the writer answers the request with a Step2"); + assert_eq!( + receiver.deliver(millis(304), step2), + Outcome::Applied { kind: 0 } + ); + assert_eq!( + receiver.text("README.md"), + "on off ", + "the lost insertion returns" + ); + assert_eq!(writer.text("README.md"), "on off "); + assert_eq!( + writer.state_vector(), + receiver.state_vector(), + "the replicas converge" + ); +} + +/// The same two sessions, one lost deletion: a deletion is not a struct, so the state +/// vectors already agree while the texts differ; the reciprocal request carries the whole +/// delete set back and the texts converge. +#[test] +#[expect( + clippy::too_many_lines, + reason = "the whole loss and repair is one sequence and is clearer unsplit" +)] +fn a_lost_deletion_is_recovered_by_the_reciprocal_request() { + let mut writer = session(&[]); + let mut receiver = second_session(&[]); + let third = SessionKey::from_seed([19; 32]); + writer.tick(Duration::ZERO); + receiver.tick(Duration::ZERO); + let _ = writer.take_outbound(); + let _ = receiver.take_outbound(); + let committing = state( + &host(), + 1, + &[ + (&ours(), "guest", "p-self"), + (&peer(), "guest", "p-other"), + (&third, "guest", "p-third"), + ], + ); + assert_eq!( + writer.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + assert_eq!( + receiver.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + let writer_initial = writer.take_outbound(); + let _ = receiver.take_outbound(); + // Arm the receiver's reciprocal obligation. + assert_eq!( + receiver.deliver(millis(2), &writer_initial[0]), + Outcome::Applied { kind: 0 } + ); + let _ = receiver.take_outbound(); + + // A third key inserts "abc"; both replicas apply it. + let source = Doc::new(); + let handle = source.get_or_insert_text("README.md"); + { + let mut txn = source.transact_mut(); + handle.insert(&mut txn, 0, "abc"); + } + let inserted = { + let txn = source.transact(); + txn.encode_state_as_update_v1(&StateVector::default()) + }; + let insert_frame = frame( + &third, + 0, + 1, + &encode_y_message(&YMessage::Sync(SyncMessage::Update(inserted))), + ); + assert_eq!( + writer.deliver(millis(3), &insert_frame), + Outcome::Applied { kind: 0 } + ); + assert_eq!( + receiver.deliver(millis(3), &insert_frame), + Outcome::Applied { kind: 0 } + ); + assert_eq!(writer.text("README.md"), "abc"); + assert_eq!(receiver.text("README.md"), "abc"); + + // The third key deletes `b`; only the writer receives that update. + let before = { + let txn = source.transact(); + txn.state_vector() + }; + { + let mut txn = source.transact_mut(); + handle.remove_range(&mut txn, 1, 1); + } + let deletion = { + let txn = source.transact(); + txn.encode_state_as_update_v1(&before) + }; + let delete_frame = frame( + &third, + 0, + 2, + &encode_y_message(&YMessage::Sync(SyncMessage::Update(deletion))), + ); + assert_eq!( + writer.deliver(millis(4), &delete_frame), + Outcome::Applied { kind: 0 } + ); + assert_eq!(writer.text("README.md"), "ac"); + assert_eq!(receiver.text("README.md"), "abc", "the deletion was lost"); + // A deletion is not a struct, so the vectors agree before the repair. + assert_eq!(writer.state_vector(), receiver.state_vector()); + + // The reciprocal request carries the whole delete set back. + receiver.tick(millis(302)); + let request = receiver.take_outbound(); + assert_eq!(request.len(), 1, "one coalesced reciprocal request"); + assert_eq!(sync_subtype(&request[0]), Some(0)); + assert_eq!( + writer.deliver(millis(303), &request[0]), + Outcome::Applied { kind: 0 } + ); + let repair = writer.take_outbound(); + let step2 = repair + .iter() + .find(|frame| sync_subtype(frame.as_slice()) == Some(1)) + .expect("the writer answers the request with a Step2"); + assert_eq!( + receiver.deliver(millis(304), step2), + Outcome::Applied { kind: 0 } + ); + assert_eq!( + receiver.text("README.md"), + "ac", + "the lost deletion returns" + ); + assert_eq!( + writer.state_vector(), + receiver.state_vector(), + "the replicas converge" + ); +} + +/// After a lost update is repaired and the room has gone quiet, a fresh writer eligibility +/// lets a second lost update be repaired with the same two retained replicas and no new API: +/// the demotion and re-promotion are signed states, and the renewed request is what a fresh +/// continuous eligibility owes. +#[test] +#[expect( + clippy::too_many_lines, + reason = "the two loss-and-repair rounds and the fresh eligibility between them are one sequence" +)] +fn a_second_lost_update_is_repaired_after_a_fresh_writer_eligibility() { + let mut writer = session(&["p-other"]); + let mut receiver = second_session(&["p-self"]); + writer.tick(Duration::ZERO); + receiver.tick(Duration::ZERO); + let _ = writer.take_outbound(); + let _ = receiver.take_outbound(); + let committing = state( + &host(), + 1, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + writer.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + assert_eq!( + receiver.deliver(millis(1), &committing), + Outcome::Applied { kind: 1 } + ); + let writer_initial = writer.take_outbound(); + let _ = receiver.take_outbound(); + assert_eq!( + receiver.deliver(millis(2), &writer_initial[0]), + Outcome::Applied { kind: 0 } + ); + let _ = receiver.take_outbound(); + + // First loss: the independent insertion is dropped, the dependent one arrives pending. + assert!(writer.insert("README.md", 0, "off ").unwrap()); + let _ = writer.take_outbound(); + assert!(writer.insert("README.md", 0, "on ").unwrap()); + let dependent = writer.take_outbound(); + assert_eq!( + receiver.deliver(millis(3), &dependent[0]), + Outcome::Applied { kind: 0 } + ); + receiver.tick(millis(302)); + let request = receiver.take_outbound(); + assert_eq!(request.len(), 1, "one reciprocal request"); + assert_eq!( + writer.deliver(millis(303), &request[0]), + Outcome::Applied { kind: 0 } + ); + let repair = writer.take_outbound(); + let step2 = repair + .iter() + .find(|frame| sync_subtype(frame.as_slice()) == Some(1)) + .expect("the writer answers with a Step2"); + assert_eq!( + receiver.deliver(millis(304), step2), + Outcome::Applied { kind: 0 } + ); + assert_eq!(receiver.text("README.md"), "on off "); + assert_eq!(writer.state_vector(), receiver.state_vector()); + + // A quiet interval: the receiver owes nothing. + receiver.tick(millis(601)); + receiver.tick(millis(901)); + assert!( + receiver.take_outbound().is_empty(), + "the repaired window is silent" + ); + + // The writer is demoted and re-promoted under the same key: a fresh eligibility. + let demoted = state( + &host(), + 2, + &[(&ours(), "viewer", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + writer.deliver(millis(902), &demoted), + Outcome::Applied { kind: 1 } + ); + assert_eq!( + receiver.deliver(millis(902), &demoted), + Outcome::Applied { kind: 1 } + ); + let promoted = state( + &host(), + 3, + &[(&ours(), "guest", "p-self"), (&peer(), "guest", "p-other")], + ); + assert_eq!( + writer.deliver(millis(903), &promoted), + Outcome::Applied { kind: 1 } + ); + assert_eq!( + receiver.deliver(millis(903), &promoted), + Outcome::Applied { kind: 1 } + ); + + // The renewed writer eligibility sends one request; the receiver arms from it. + writer.tick(millis(1201)); + let renewed = writer.take_outbound(); + assert_eq!(renewed.len(), 1, "the fresh eligibility owes one request"); + assert_eq!(sync_subtype(&renewed[0]), Some(0)); + assert_eq!( + receiver.deliver(millis(1202), &renewed[0]), + Outcome::Applied { kind: 0 } + ); + let _ = receiver.take_outbound(); + + // Second loss: the same shape, repaired by the receiver's renewed reciprocal request. + assert!(writer.insert("README.md", 0, "z").unwrap()); + let _ = writer.take_outbound(); + assert!(writer.insert("README.md", 0, "y").unwrap()); + let dependent = writer.take_outbound(); + assert_eq!( + receiver.deliver(millis(1203), &dependent[0]), + Outcome::Applied { kind: 0 } + ); + assert_eq!( + receiver.text("README.md"), + "on off ", + "the second dependency waits" + ); + receiver.tick(millis(1502)); + let request = receiver.take_outbound(); + assert_eq!(request.len(), 1, "the fresh eligibility re-armed once"); + assert_eq!(sync_subtype(&request[0]), Some(0)); + assert_eq!( + writer.deliver(millis(1503), &request[0]), + Outcome::Applied { kind: 0 } + ); + let repair = writer.take_outbound(); + let step2 = repair + .iter() + .find(|frame| sync_subtype(frame.as_slice()) == Some(1)) + .expect("the writer answers the second request with a Step2"); + assert_eq!( + receiver.deliver(millis(1504), step2), + Outcome::Applied { kind: 0 } + ); + assert_eq!(receiver.text("README.md"), "yzon off "); + assert_eq!(writer.text("README.md"), "yzon off "); + assert_eq!(writer.state_vector(), receiver.state_vector()); +}