- Order subscription and share registers by a per-podcast Lamport generation before hlc_ms (next_podcast_generation), so clock skew cannot undo an observed unsubscribe or share decision. - share=false is register state, not a compactable tombstone. - Add podcast_feed_aliases_added so refreshes can sync aliases without touching the registers; SubscriptionRecord::feed_urls keeps the current feed URL resolvable beyond the alias bound. - Carry progress_generation on queue items for handoff. - Distinguish self-reported and relayed peer versions, and gate PairRequest by an optional inviter version in InviteWire. - Give each podcast snapshot section its own byte budget, drop channel descriptions from snapshots and allow a caller-provided budget. - Reject one-slash http(s) typos in FeedUrl::from_user_input. - Pin that malformed ids and feed URLs reject the whole message. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2552 lines
96 KiB
Rust
2552 lines
96 KiB
Rust
//! Wire protocol shared by furumi personal-device synchronization clients.
|
||
//!
|
||
//! The storage and UI policy live in applications. This module only defines
|
||
//! the stable JSON-lines messages spoken over the auxiliary iroh stream ALPN,
|
||
//! plus small helpers for opaque `frid://i/...` invites.
|
||
//!
|
||
//! # Versions
|
||
//!
|
||
//! | Profile `protocol_version` | Adds |
|
||
//! | --- | --- |
|
||
//! | 1 | likes, playlists, membership (`furumi/sync/1`) |
|
||
//! | 2 | [`SyncOpPayload::ListenRecorded`] (`furumi/sync/2`) |
|
||
//! | 3 | fenced personal playback coordination |
|
||
//! | 4 | podcasts: five `podcast_*` operations, podcast snapshot sections, [`PlaybackSource`] on queue items, reserved `playback_rate` |
|
||
//!
|
||
//! The ALPN stays `furumi/sync/2` for v3 and v4. [`SyncOpPayload`] is a
|
||
//! closed serde enum: a peer that does not know an operation `kind` fails to
|
||
//! deserialize the **whole** message that contains it, not just one
|
||
//! operation. Peers before v4 ignore [`PlaybackTrack::source`] and would treat
|
||
//! episodes as broken music items. Senders must therefore filter by the
|
||
//! peer's version ([`profile_protocol_version`], [`relayed_protocol_version`],
|
||
//! [`InviteWire::inviter_protocol_version`]) with [`op_allowed_for_peer`],
|
||
//! [`playback_allowed_for_peer`] and [`SyncSnapshot::for_peer`]. See the
|
||
//! workspace `PODCASTS.md` for the podcast contract.
|
||
|
||
use std::collections::BTreeMap;
|
||
use std::str::FromStr;
|
||
|
||
use federation_net::{ByteStream, NetworkId, PeerTicket, SecretKey};
|
||
use serde::{Deserialize, Serialize};
|
||
use tokio::io::{AsyncRead, AsyncReadExt};
|
||
|
||
use crate::error::{MusicDhtError, Result};
|
||
use crate::podcast::{
|
||
EpisodeId, FeedUrl, ListenSession, MAX_FEED_ALIASES, MAX_PODCAST_SNAPSHOT_BYTES,
|
||
MAX_SNAPSHOT_LISTEN_SESSIONS, MAX_SNAPSHOT_PROGRESS, MAX_SNAPSHOT_SHARES,
|
||
MAX_SNAPSHOT_SUBSCRIPTIONS, PodcastEpisodeRef, PodcastError, PodcastId, PodcastMeta,
|
||
PodcastResult, ProgressRecord, ProgressStatus, ShareRecord, SubscriptionRecord,
|
||
};
|
||
|
||
/// Legacy ALPN used by personal-device sync v1.
|
||
pub const SYNC_ALPN_V1: &[u8] = b"furumi/sync/1";
|
||
|
||
/// Current ALPN used by personal-device sync v2.
|
||
///
|
||
/// Version 2 adds content-addressed, append-only listening history. Clients
|
||
/// should accept both v1 and v2 while older devices remain in a sync group,
|
||
/// but must only send [`SyncOpPayload::ListenRecorded`] to v2 peers.
|
||
pub const SYNC_ALPN_V2: &[u8] = b"furumi/sync/2";
|
||
|
||
/// Auxiliary ALPN used by current personal-device sync streams.
|
||
pub const SYNC_ALPN: &[u8] = SYNC_ALPN_V2;
|
||
|
||
/// Version of the personal-device sync wire protocol.
|
||
///
|
||
/// Version 4 adds podcasts. Always advertise the constant of the running
|
||
/// client for **this** device only; for other devices keep the version they
|
||
/// reported themselves (see [`profile_protocol_version`]).
|
||
pub const DEVICE_SYNC_PROTOCOL_VERSION: u16 = 4;
|
||
|
||
/// First protocol version that understands podcast operations, podcast
|
||
/// snapshot sections and [`PlaybackSource`].
|
||
pub const PODCAST_PROTOCOL_VERSION: u16 = 4;
|
||
|
||
/// Version assumed for a device whose profile never reported one.
|
||
///
|
||
/// Profiles written by clients before v4 carry no version in
|
||
/// [`SyncOpPayload::DeviceProfileSet`]. Treat such a device as the oldest
|
||
/// protocol: it will be upgraded as soon as it reports its own version.
|
||
pub const UNREPORTED_PROTOCOL_VERSION: u16 = 1;
|
||
|
||
/// Minimum actual listening time retained for an interrupted listen.
|
||
pub const MIN_RECORDED_LISTEN_MS: i64 = 5_000;
|
||
|
||
/// Maximum listening time required to qualify a listen as a play.
|
||
pub const MAX_QUALIFYING_LISTEN_MS: i64 = 4 * 60 * 1_000;
|
||
|
||
/// Returns whether a peer may receive listening-history operations.
|
||
pub const fn supports_listen_history(protocol_version: u16) -> bool {
|
||
protocol_version >= 2
|
||
}
|
||
|
||
/// Returns whether a peer may receive podcast operations, podcast snapshot
|
||
/// sections and playback state that contains podcast episodes.
|
||
pub const fn supports_podcasts(protocol_version: u16) -> bool {
|
||
protocol_version >= PODCAST_PROTOCOL_VERSION
|
||
}
|
||
|
||
/// Protocol version to store for a device after reading **its own** report.
|
||
///
|
||
/// Self-reports are: the `profile` of a `Hello`, `PairRequest` or
|
||
/// `PairResponse` sent by that device; the entry of a `devices` list whose
|
||
/// `device_id` is the authenticated sender of the message (a `SyncResponse`
|
||
/// has no `profile` field, so this is how an initiator learns the responder's
|
||
/// version); and a [`SyncOpPayload::DeviceProfileSet`] whose
|
||
/// `origin_device_id` is that device. `reported` is the version in the report
|
||
/// (`None` when an older client left it out) and `previously_known` the
|
||
/// stored value. A self-report replaces the stored value, so a downgrade is
|
||
/// noticed.
|
||
///
|
||
/// Profiles of **other** devices relayed by a peer are not self-reports: use
|
||
/// [`relayed_protocol_version`] for them. Receivers and relays must never
|
||
/// substitute their own [`DEVICE_SYNC_PROTOCOL_VERSION`] for another device:
|
||
/// doing so would make version gating send podcast state to old clients.
|
||
pub fn profile_protocol_version(reported: Option<u16>, previously_known: Option<u16>) -> u16 {
|
||
reported
|
||
.or(previously_known)
|
||
.unwrap_or(UNREPORTED_PROTOCOL_VERSION)
|
||
}
|
||
|
||
/// Protocol version to store for a device after reading a profile of it
|
||
/// relayed by **another** device (an entry of a `devices` list).
|
||
///
|
||
/// Deployed v1–v3 clients relay every device with their own protocol
|
||
/// constant, so a relayed value can understate a device's version. A relayed
|
||
/// value therefore only raises the stored version (`max(stored, relayed)`)
|
||
/// and is taken as is only when nothing is stored. Lowering requires a
|
||
/// self-report ([`profile_protocol_version`]).
|
||
pub fn relayed_protocol_version(relayed: u16, previously_known: Option<u16>) -> u16 {
|
||
previously_known.map_or(relayed, |stored| stored.max(relayed))
|
||
}
|
||
|
||
/// Default invite lifetime used by applications unless they need a custom TTL.
|
||
pub const DEFAULT_INVITE_TTL_MS: i64 = 10 * 60 * 1000;
|
||
|
||
/// Maximum JSON line accepted by the protocol.
|
||
pub const MAX_SYNC_LINE: usize = 8 * 1024 * 1024;
|
||
|
||
/// Opaque invite payload encoded into `frid://i/<base64url-json>`.
|
||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub struct InviteWire {
|
||
/// Invite schema version.
|
||
pub v: u16,
|
||
/// Transport ticket for the inviting endpoint.
|
||
#[serde(rename = "t")]
|
||
pub ticket: String,
|
||
/// Device id of the inviter.
|
||
#[serde(rename = "d")]
|
||
pub device_id: String,
|
||
/// Short invite id stored by the inviter.
|
||
#[serde(rename = "i")]
|
||
pub invite_id: String,
|
||
/// Runtime pairing secret.
|
||
#[serde(rename = "s")]
|
||
pub secret: String,
|
||
/// Expiration timestamp in unix milliseconds.
|
||
#[serde(rename = "e")]
|
||
pub expires_at_ms: i64,
|
||
/// Device-sync protocol version of the inviter (v4+).
|
||
///
|
||
/// `None` in invites created by older clients. The invite consumer sends
|
||
/// its `PairRequest` before it hears from the inviter, so it gates the
|
||
/// operations, snapshot sections and playback state of that request by
|
||
/// [`InviteWire::inviter_protocol_version`].
|
||
#[serde(rename = "p", default, skip_serializing_if = "Option::is_none")]
|
||
pub protocol_version: Option<u16>,
|
||
}
|
||
|
||
impl InviteWire {
|
||
/// Protocol version to assume for the inviter while building a
|
||
/// `PairRequest`: the version in the invite, or
|
||
/// [`UNREPORTED_PROTOCOL_VERSION`] for invites from older clients, which
|
||
/// strips all podcast state from the request. Podcast state then catches
|
||
/// up through the snapshot of the next regular sync.
|
||
pub fn inviter_protocol_version(&self) -> u16 {
|
||
self.protocol_version.unwrap_or(UNREPORTED_PROTOCOL_VERSION)
|
||
}
|
||
}
|
||
|
||
/// Public device profile exchanged inside a trusted sync group.
|
||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub struct DeviceProfileWire {
|
||
/// Stable device id.
|
||
pub device_id: String,
|
||
/// User-visible device name.
|
||
pub name: String,
|
||
/// Application version.
|
||
pub client_version: String,
|
||
/// Wire protocol version reported by **this** device.
|
||
///
|
||
/// When relaying other devices' profiles, send the version stored for
|
||
/// them, never the relay's own constant.
|
||
pub protocol_version: u16,
|
||
/// Transport endpoint id, as string.
|
||
pub endpoint_id: String,
|
||
/// Transport ticket used for direct reconnects.
|
||
pub endpoint_ticket: String,
|
||
/// Whether the device has been revoked.
|
||
#[serde(default)]
|
||
pub revoked: bool,
|
||
/// Last accepted seq from this device after revocation.
|
||
#[serde(default)]
|
||
pub revoke_cutoff_seq: Option<i64>,
|
||
/// Profile update timestamp in unix milliseconds.
|
||
#[serde(default)]
|
||
pub updated_at_ms: i64,
|
||
}
|
||
|
||
/// Portable track reference embedded into sync payloads for unresolved tracks.
|
||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub struct SyncedFedTrack {
|
||
/// DHT item id, when known.
|
||
pub item_id: String,
|
||
/// DHT owner endpoint id, when known.
|
||
pub owner: String,
|
||
/// Track title.
|
||
pub title: String,
|
||
/// Main artist names.
|
||
#[serde(default)]
|
||
pub artist_names: Vec<String>,
|
||
/// Featured artist names.
|
||
#[serde(default)]
|
||
pub featured_artist_names: Vec<String>,
|
||
/// Release or track year.
|
||
pub year: Option<i32>,
|
||
/// Duration in seconds.
|
||
pub duration_seconds: Option<i64>,
|
||
/// Stable content id (`b3:<hex>`).
|
||
pub content_id: String,
|
||
/// Release title, when known.
|
||
pub release_title: Option<String>,
|
||
/// Track number.
|
||
pub track_number: Option<i32>,
|
||
/// Disc number.
|
||
pub disc_number: Option<i32>,
|
||
}
|
||
|
||
/// Why a listening session ended.
|
||
///
|
||
/// This is deliberately factual rather than a client-specific `completed`
|
||
/// flag. All clients use [`ListenEvent::qualifies_as_play`] to derive the
|
||
/// shared play-count meaning.
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||
#[serde(rename_all = "snake_case")]
|
||
pub enum ListenEndReason {
|
||
/// Playback reached the natural end of the track.
|
||
Finished,
|
||
/// The listener explicitly moved to another track.
|
||
Skipped,
|
||
/// Playback was stopped without selecting a replacement.
|
||
Stopped,
|
||
/// Another queue item or playback session replaced this one.
|
||
Replaced,
|
||
/// The client cannot determine why playback ended.
|
||
Unknown,
|
||
}
|
||
|
||
/// Portable metadata kept with a listening event.
|
||
///
|
||
/// Metadata is a snapshot, not identity: [`ListenEvent::content_id`] is the
|
||
/// stable track identity. Keeping the snapshot lets a device display and
|
||
/// scrobble a listen even when it does not have that track in its own catalog.
|
||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub struct ListenTrackMetadata {
|
||
/// Track title.
|
||
pub title: String,
|
||
/// Main artist names.
|
||
#[serde(default)]
|
||
pub artist_names: Vec<String>,
|
||
/// Featured artist names.
|
||
#[serde(default)]
|
||
pub featured_artist_names: Vec<String>,
|
||
/// Release title, when known.
|
||
#[serde(default)]
|
||
pub release_title: Option<String>,
|
||
}
|
||
|
||
/// One immutable, content-addressed listening-history event.
|
||
///
|
||
/// `listen_id` is generated when playback starts and must be reused for every
|
||
/// retry of the same report. Receivers materialize it under a unique key, so
|
||
/// browser retries and repeated sync delivery never duplicate history.
|
||
///
|
||
/// Events are append-only and belong to one trusted-device sync group. They
|
||
/// must never be published through the public music DHT.
|
||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub struct ListenEvent {
|
||
/// Stable id for this playback session, normally a UUID.
|
||
pub listen_id: String,
|
||
/// Stable audio content id (`b3:<hex>`).
|
||
pub content_id: String,
|
||
/// Playback start time as Unix milliseconds.
|
||
pub started_at_ms: i64,
|
||
/// Actual accumulated listening time in milliseconds.
|
||
pub listened_ms: i64,
|
||
/// Track duration in milliseconds, when known.
|
||
#[serde(default)]
|
||
pub track_duration_ms: Option<i64>,
|
||
/// Factual reason the session ended.
|
||
pub ended_reason: ListenEndReason,
|
||
/// Portable display and scrobbling metadata.
|
||
pub track: ListenTrackMetadata,
|
||
}
|
||
|
||
impl ListenEvent {
|
||
/// Returns whether the event contains the minimum portable identity.
|
||
pub fn is_valid(&self) -> bool {
|
||
!self.listen_id.trim().is_empty()
|
||
&& crate::normalize_content_id(&self.content_id).is_some()
|
||
&& self.started_at_ms >= 0
|
||
&& self.listened_ms >= 0
|
||
&& self.track_duration_ms.is_none_or(|duration| duration > 0)
|
||
&& !self.track.title.trim().is_empty()
|
||
&& self
|
||
.track
|
||
.artist_names
|
||
.iter()
|
||
.any(|artist| !artist.trim().is_empty())
|
||
}
|
||
|
||
/// Returns whether this event should be retained in listening history.
|
||
///
|
||
/// Natural track completion is always retained. Interrupted sessions are
|
||
/// retained after five seconds of actual listening.
|
||
pub fn should_record(&self) -> bool {
|
||
self.is_valid()
|
||
&& (self.ended_reason == ListenEndReason::Finished
|
||
|| self.listened_ms >= MIN_RECORDED_LISTEN_MS)
|
||
}
|
||
|
||
/// Returns whether this event contributes to play counts.
|
||
///
|
||
/// A natural finish qualifies immediately. Otherwise a listen qualifies
|
||
/// after the smaller of half the known track duration and four minutes.
|
||
/// Without a known duration only the four-minute threshold applies.
|
||
pub fn qualifies_as_play(&self) -> bool {
|
||
if !self.should_record() {
|
||
return false;
|
||
}
|
||
if self.ended_reason == ListenEndReason::Finished {
|
||
return true;
|
||
}
|
||
self.listened_ms >= self.qualifying_threshold_ms()
|
||
}
|
||
|
||
/// Returns the shared listening threshold for this event.
|
||
pub fn qualifying_threshold_ms(&self) -> i64 {
|
||
self.track_duration_ms
|
||
.map(|duration| (duration / 2 + duration % 2).min(MAX_QUALIFYING_LISTEN_MS))
|
||
.unwrap_or(MAX_QUALIFYING_LISTEN_MS)
|
||
}
|
||
}
|
||
|
||
/// Explicit source of a queue item (protocol v4).
|
||
///
|
||
/// Absent on music items from older clients, which are music. Podcast
|
||
/// episodes are identified only by this field: never by a negative id, a
|
||
/// placeholder release or a URL in `file_path`.
|
||
///
|
||
/// Clients before v4 do not know [`PlaybackTrack::source`] at all and ignore
|
||
/// it: they would take an episode for a broken music item (id 0, no content
|
||
/// id) and forward it that way, losing the episode for every device. That is
|
||
/// why podcast-bearing playback state is gated by version. This enum is
|
||
/// closed for v4 clients: a new variant needs a protocol bump, because a v4
|
||
/// client fails to parse the whole message on an unknown `kind`.
|
||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||
#[serde(tag = "kind", rename_all = "snake_case")]
|
||
pub enum PlaybackSource {
|
||
/// Music track resolved by `content_id` / `fed`.
|
||
Music,
|
||
/// Podcast episode streamed from the publisher (boxed: music items stay small).
|
||
PodcastEpisode(Box<PodcastEpisodeRef>),
|
||
/// Opaque placeholder that replaces a private item in Jam snapshots
|
||
/// (see [`redact_for_jam`]). It is never playable and carries no title,
|
||
/// URL or id.
|
||
Private,
|
||
}
|
||
|
||
/// Display title of [`PlaybackTrack::private_placeholder`].
|
||
pub const PRIVATE_ITEM_TITLE: &str = "Private item";
|
||
|
||
/// Portable playback queue track.
|
||
///
|
||
/// For podcast items [`PlaybackTrack::source`] is authoritative; the legacy
|
||
/// display fields mirror it (see [`PlaybackTrack::podcast_episode`]).
|
||
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
|
||
pub struct PlaybackTrack {
|
||
/// Local or placeholder id on the sending device.
|
||
pub id: i64,
|
||
/// Track title.
|
||
pub title: String,
|
||
/// Track number.
|
||
pub track_number: Option<i32>,
|
||
/// Disc number.
|
||
pub disc_number: Option<i32>,
|
||
/// Duration in seconds.
|
||
pub duration_seconds: f64,
|
||
/// Main artist names.
|
||
#[serde(default)]
|
||
pub artist_names: Vec<String>,
|
||
/// Featured artist names.
|
||
#[serde(default)]
|
||
pub featured_artist_names: Vec<String>,
|
||
/// Local or placeholder release id.
|
||
pub release_id: i64,
|
||
/// Release title.
|
||
pub release_title: String,
|
||
/// Release year.
|
||
pub release_year: Option<i32>,
|
||
/// Legacy compatibility only. Paths are device-local and should be empty.
|
||
#[serde(default)]
|
||
pub file_path: String,
|
||
/// Stable content id.
|
||
pub content_id: Option<String>,
|
||
/// Audio format label.
|
||
pub audio_format: Option<String>,
|
||
/// Audio bitrate.
|
||
pub audio_bitrate: Option<i32>,
|
||
/// Audio sample rate.
|
||
pub audio_sample_rate: Option<i32>,
|
||
/// Audio bit depth.
|
||
pub audio_bit_depth: Option<i32>,
|
||
/// File size in bytes.
|
||
pub file_size_bytes: Option<i64>,
|
||
/// Sender-side play count.
|
||
#[serde(default)]
|
||
pub play_count: i64,
|
||
/// Federation metadata for unresolved tracks.
|
||
#[serde(default)]
|
||
pub fed: Option<SyncedFedTrack>,
|
||
/// Explicit item source (protocol v4). `None` means music.
|
||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||
pub source: Option<PlaybackSource>,
|
||
}
|
||
|
||
impl PlaybackTrack {
|
||
/// Queue item for a podcast episode.
|
||
///
|
||
/// Legacy display fields are filled for presentation only: `title` is the
|
||
/// episode title, `artist_names` and `release_title` the podcast title,
|
||
/// `id`/`release_id` are `0`, `file_path` is empty and `content_id` is
|
||
/// `None`.
|
||
pub fn podcast_episode(episode: PodcastEpisodeRef) -> Self {
|
||
Self {
|
||
id: 0,
|
||
title: episode.episode_title.clone(),
|
||
track_number: None,
|
||
disc_number: None,
|
||
duration_seconds: episode.duration_ms.unwrap_or(0) as f64 / 1_000.0,
|
||
artist_names: vec![episode.podcast_title.clone()],
|
||
featured_artist_names: Vec::new(),
|
||
release_id: 0,
|
||
release_title: episode.podcast_title.clone(),
|
||
release_year: None,
|
||
file_path: String::new(),
|
||
content_id: None,
|
||
audio_format: episode.mime.clone(),
|
||
audio_bitrate: None,
|
||
audio_sample_rate: None,
|
||
audio_bit_depth: None,
|
||
file_size_bytes: None,
|
||
play_count: 0,
|
||
fed: None,
|
||
source: Some(PlaybackSource::PodcastEpisode(Box::new(episode))),
|
||
}
|
||
}
|
||
|
||
/// Opaque, unplayable placeholder for a private item.
|
||
pub fn private_placeholder() -> Self {
|
||
Self {
|
||
id: 0,
|
||
title: PRIVATE_ITEM_TITLE.to_string(),
|
||
track_number: None,
|
||
disc_number: None,
|
||
duration_seconds: 0.0,
|
||
artist_names: Vec::new(),
|
||
featured_artist_names: Vec::new(),
|
||
release_id: 0,
|
||
release_title: String::new(),
|
||
release_year: None,
|
||
file_path: String::new(),
|
||
content_id: None,
|
||
audio_format: None,
|
||
audio_bitrate: None,
|
||
audio_sample_rate: None,
|
||
audio_bit_depth: None,
|
||
file_size_bytes: None,
|
||
play_count: 0,
|
||
fed: None,
|
||
source: Some(PlaybackSource::Private),
|
||
}
|
||
}
|
||
|
||
/// The podcast episode of this item, if it is one.
|
||
pub fn podcast_episode_ref(&self) -> Option<&PodcastEpisodeRef> {
|
||
match &self.source {
|
||
Some(PlaybackSource::PodcastEpisode(episode)) => Some(episode),
|
||
_ => None,
|
||
}
|
||
}
|
||
|
||
/// Whether this item is a Jam private placeholder.
|
||
pub fn is_private_placeholder(&self) -> bool {
|
||
matches!(self.source, Some(PlaybackSource::Private))
|
||
}
|
||
|
||
/// Whether this item needs protocol v4 (podcast episode or placeholder).
|
||
pub fn requires_podcast_support(&self) -> bool {
|
||
matches!(
|
||
self.source,
|
||
Some(PlaybackSource::PodcastEpisode(_) | PlaybackSource::Private)
|
||
)
|
||
}
|
||
}
|
||
|
||
/// Playback repeat mode.
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
|
||
#[serde(rename_all = "snake_case")]
|
||
pub enum PlaybackRepeat {
|
||
/// Repeat disabled.
|
||
#[default]
|
||
Off,
|
||
/// Repeat current track.
|
||
One,
|
||
/// Repeat the whole queue.
|
||
All,
|
||
}
|
||
|
||
/// Portable playback state.
|
||
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
|
||
pub struct PlaybackStateWire {
|
||
/// Queue tracks.
|
||
#[serde(default)]
|
||
pub queue: Vec<PlaybackTrack>,
|
||
/// Current queue index.
|
||
#[serde(default)]
|
||
pub queue_pos: usize,
|
||
/// Whether playback is active.
|
||
pub playing: bool,
|
||
/// Whether playback is paused.
|
||
pub paused: bool,
|
||
/// Active device idle timestamp, when paused/stopped.
|
||
#[serde(default)]
|
||
pub idle_since_ms: Option<i64>,
|
||
/// Current position in seconds.
|
||
pub position_secs: f64,
|
||
/// Volume 0..100.
|
||
#[serde(default)]
|
||
pub volume: u8,
|
||
/// Shuffle mode.
|
||
pub shuffle: bool,
|
||
/// Repeat mode.
|
||
pub repeat: PlaybackRepeat,
|
||
/// Reserved playback rate (1.0 = normal speed); no client uses it yet.
|
||
///
|
||
/// When implemented, position extrapolation and handoff must account for
|
||
/// it. Receivers that do not support rates treat it as 1.0.
|
||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||
pub playback_rate: Option<f32>,
|
||
}
|
||
|
||
/// Playback snapshot with the common coordination envelope.
|
||
pub type PlaybackSnapshot = crate::playback::Snapshot<PlaybackStateWire>;
|
||
/// Shared command vocabulary with the portable music queue DTO.
|
||
pub type PlaybackCommand = crate::playback::Command<PlaybackStateWire>;
|
||
|
||
/// One operation in the device-sync log.
|
||
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
|
||
pub struct SyncOpWire {
|
||
/// Unique op id, usually `<origin_device_id>:<seq>`.
|
||
pub op_id: String,
|
||
/// Origin device id.
|
||
pub origin_device_id: String,
|
||
/// Monotonic sequence inside the origin device log.
|
||
pub seq: i64,
|
||
/// Hybrid/logical timestamp in unix milliseconds.
|
||
pub hlc_ms: i64,
|
||
/// Operation payload.
|
||
pub payload: SyncOpPayload,
|
||
}
|
||
|
||
/// Personal-device sync operation payload.
|
||
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
|
||
#[serde(tag = "kind", rename_all = "snake_case")]
|
||
pub enum SyncOpPayload {
|
||
/// Set like state for a content id.
|
||
TrackLikeSet {
|
||
/// Content id.
|
||
content_id: String,
|
||
/// Desired like state.
|
||
liked: bool,
|
||
/// Optional unresolved federated metadata.
|
||
#[serde(default)]
|
||
fed: Option<SyncedFedTrack>,
|
||
},
|
||
/// Create playlist.
|
||
PlaylistCreated {
|
||
/// Stable playlist sync id.
|
||
playlist_id: String,
|
||
/// Playlist title.
|
||
title: String,
|
||
},
|
||
/// Rename playlist.
|
||
PlaylistRenamed {
|
||
/// Stable playlist sync id.
|
||
playlist_id: String,
|
||
/// Playlist title.
|
||
title: String,
|
||
},
|
||
/// Delete playlist.
|
||
PlaylistDeleted {
|
||
/// Stable playlist sync id.
|
||
playlist_id: String,
|
||
},
|
||
/// Add track to playlist.
|
||
PlaylistTrackAdded {
|
||
/// Stable playlist sync id.
|
||
playlist_id: String,
|
||
/// Content id.
|
||
content_id: String,
|
||
/// Playlist position.
|
||
position: i64,
|
||
/// Optional unresolved federated metadata.
|
||
#[serde(default)]
|
||
fed: Option<SyncedFedTrack>,
|
||
},
|
||
/// Remove track from playlist.
|
||
PlaylistTrackRemoved {
|
||
/// Stable playlist sync id.
|
||
playlist_id: String,
|
||
/// Content id.
|
||
content_id: String,
|
||
},
|
||
/// Update origin device profile.
|
||
DeviceProfileSet {
|
||
/// Display name.
|
||
name: String,
|
||
/// Client version.
|
||
client_version: String,
|
||
/// Endpoint ticket.
|
||
endpoint_ticket: String,
|
||
/// Endpoint id.
|
||
endpoint_id: String,
|
||
/// Protocol version of the origin device (v4+).
|
||
///
|
||
/// `None` from older clients. Receivers store
|
||
/// [`profile_protocol_version`]`(protocol_version, stored)` and must
|
||
/// never substitute their own constant.
|
||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||
protocol_version: Option<u16>,
|
||
},
|
||
/// Trust a device.
|
||
DeviceTrusted {
|
||
/// Trusted device id.
|
||
target_device_id: String,
|
||
},
|
||
/// Revoke a device.
|
||
DeviceRevoked {
|
||
/// Revoked device id.
|
||
target_device_id: String,
|
||
/// Max seq seen from the target at revoke time.
|
||
target_max_seq_seen: i64,
|
||
},
|
||
/// Playback command for a target device.
|
||
PlaybackCommand {
|
||
/// Target device id.
|
||
target_device_id: String,
|
||
/// Command.
|
||
command: PlaybackCommand,
|
||
/// Ownership and ordering fence. Legacy commands cannot change v3 playback.
|
||
#[serde(default)]
|
||
authority: Option<crate::playback::CommandStamp>,
|
||
},
|
||
/// Append one immutable listening-history event.
|
||
///
|
||
/// This operation is valid only on device-sync protocol v2. The event is
|
||
/// deduplicated by `event.listen_id`, independently of transport `op_id`.
|
||
ListenRecorded {
|
||
/// Portable listening event.
|
||
event: ListenEvent,
|
||
},
|
||
/// Subscribe to or unsubscribe from a podcast (protocol v4).
|
||
///
|
||
/// Last-writer-wins by `(generation, hlc_ms, op_id)`; see
|
||
/// [`SubscriptionRecord`]. Unsubscribing is state, not a tombstone. Only
|
||
/// explicit user actions emit it; RSS refreshes never do. Materialize with
|
||
/// [`SyncOpWire::podcast_subscription`].
|
||
PodcastSubscriptionSet {
|
||
/// Podcast.
|
||
podcast_id: PodcastId,
|
||
/// Desired subscription state.
|
||
subscribed: bool,
|
||
/// Channel metadata, so other devices subscribe without the URL.
|
||
podcast: PodcastMeta,
|
||
/// Known feed URLs (grow-only, bounded).
|
||
#[serde(default)]
|
||
feed_aliases: Vec<FeedUrl>,
|
||
/// Per-podcast Lamport generation
|
||
/// ([`crate::podcast::next_podcast_generation`]).
|
||
#[serde(default)]
|
||
generation: u64,
|
||
},
|
||
/// Share or stop sharing a podcast card with the federation (protocol v4).
|
||
///
|
||
/// Last-writer-wins by `(generation, hlc_ms, op_id)`; see [`ShareRecord`].
|
||
/// `shared = false` is privacy-protecting state and **not** a tombstone:
|
||
/// it is never compacted. Unsubscribing also emits `shared = false`.
|
||
PodcastShareSet {
|
||
/// Podcast.
|
||
podcast_id: PodcastId,
|
||
/// Desired share state.
|
||
shared: bool,
|
||
/// Per-podcast Lamport generation, shared with the subscription.
|
||
#[serde(default)]
|
||
generation: u64,
|
||
},
|
||
/// Record feed URLs of a podcast learned by any device (protocol v4).
|
||
///
|
||
/// Grow-only: merged into the bounded alias set with
|
||
/// [`crate::podcast::merge_feed_aliases`]; it never touches the
|
||
/// subscription or share register, so RSS refreshes may emit it (after a
|
||
/// permanent redirect or an `itunes:new-feed-url`), but only when merging
|
||
/// the new URLs changes the stored set.
|
||
PodcastFeedAliasesAdded {
|
||
/// Podcast.
|
||
podcast_id: PodcastId,
|
||
/// Canonical feed URLs to add (at most `MAX_FEED_ALIASES + 1`).
|
||
feed_aliases: Vec<FeedUrl>,
|
||
},
|
||
/// Write the durable resume register of an episode (protocol v4).
|
||
///
|
||
/// Ordered by `(generation, hlc_ms, origin_device_id, op_id)`; see
|
||
/// [`ProgressRecord`]. Clients coalesce periodic checkpoints in their
|
||
/// outgoing log: only the latest per episode needs to stay pending.
|
||
PodcastProgressSet {
|
||
/// Episode.
|
||
episode_id: EpisodeId,
|
||
/// Owning podcast.
|
||
podcast_id: PodcastId,
|
||
/// Resume position in milliseconds.
|
||
position_ms: i64,
|
||
/// Listening status.
|
||
status: ProgressStatus,
|
||
/// Lamport generation (see [`ProgressRecord`]).
|
||
generation: u64,
|
||
/// Session or explicit action id.
|
||
session_id: String,
|
||
/// Display reference, so a device without the feed can show and
|
||
/// resume the episode.
|
||
#[serde(default)]
|
||
episode: Option<PodcastEpisodeRef>,
|
||
},
|
||
/// Record or update one listening session (protocol v4).
|
||
///
|
||
/// Grow-only set keyed by `session.session_id`; see [`ListenSession`].
|
||
/// `session.device_id` must equal the operation origin.
|
||
PodcastListenRecorded {
|
||
/// Listening session.
|
||
session: ListenSession,
|
||
/// Display reference for history on devices without the feed.
|
||
#[serde(default)]
|
||
episode: Option<PodcastEpisodeRef>,
|
||
},
|
||
}
|
||
|
||
impl SyncOpPayload {
|
||
/// Returns true for operations that remove state and may eventually compact.
|
||
///
|
||
/// No podcast operation is a tombstone. Unsubscribing
|
||
/// (`podcast_subscription_set { subscribed: false }`) and revoking a share
|
||
/// (`podcast_share_set { shared: false }`) are last-writer-wins state that
|
||
/// must keep beating stale `true` writes delivered again later; compacting
|
||
/// them (and deleting the state row, as like tombstones do) would let an
|
||
/// older operation still in some log resubscribe or republish the podcast.
|
||
pub fn is_tombstone(&self) -> bool {
|
||
matches!(
|
||
self,
|
||
SyncOpPayload::TrackLikeSet { liked: false, .. }
|
||
| SyncOpPayload::PlaylistDeleted { .. }
|
||
| SyncOpPayload::PlaylistTrackRemoved { .. }
|
||
| SyncOpPayload::DeviceRevoked { .. }
|
||
)
|
||
}
|
||
|
||
/// Returns true for the protocol v4 podcast operation kinds.
|
||
pub fn is_podcast(&self) -> bool {
|
||
matches!(
|
||
self,
|
||
SyncOpPayload::PodcastSubscriptionSet { .. }
|
||
| SyncOpPayload::PodcastShareSet { .. }
|
||
| SyncOpPayload::PodcastFeedAliasesAdded { .. }
|
||
| SyncOpPayload::PodcastProgressSet { .. }
|
||
| SyncOpPayload::PodcastListenRecorded { .. }
|
||
)
|
||
}
|
||
}
|
||
|
||
impl SyncOpWire {
|
||
/// Subscription record written by a `podcast_subscription_set` operation.
|
||
///
|
||
/// The register stamp is the payload `generation` and the operation's
|
||
/// `(hlc_ms, op_id)`.
|
||
pub fn podcast_subscription(&self) -> Option<SubscriptionRecord> {
|
||
let SyncOpPayload::PodcastSubscriptionSet {
|
||
podcast_id,
|
||
subscribed,
|
||
podcast,
|
||
feed_aliases,
|
||
generation,
|
||
} = &self.payload
|
||
else {
|
||
return None;
|
||
};
|
||
let mut record = SubscriptionRecord {
|
||
podcast_id: podcast_id.clone(),
|
||
subscribed: *subscribed,
|
||
podcast: podcast.clone(),
|
||
feed_aliases: feed_aliases.clone(),
|
||
generation: *generation,
|
||
hlc_ms: self.hlc_ms,
|
||
op_id: self.op_id.clone(),
|
||
};
|
||
record.normalize();
|
||
Some(record)
|
||
}
|
||
|
||
/// Share record written by a `podcast_share_set` operation.
|
||
pub fn podcast_share(&self) -> Option<ShareRecord> {
|
||
let SyncOpPayload::PodcastShareSet {
|
||
podcast_id,
|
||
shared,
|
||
generation,
|
||
} = &self.payload
|
||
else {
|
||
return None;
|
||
};
|
||
Some(ShareRecord {
|
||
podcast_id: podcast_id.clone(),
|
||
shared: *shared,
|
||
generation: *generation,
|
||
hlc_ms: self.hlc_ms,
|
||
op_id: self.op_id.clone(),
|
||
})
|
||
}
|
||
|
||
/// Podcast and feed URLs of a `podcast_feed_aliases_added` operation.
|
||
///
|
||
/// Merge them with [`crate::podcast::merge_feed_aliases`] (or
|
||
/// [`SubscriptionRecord::add_feed_aliases`]); the registers are untouched.
|
||
pub fn podcast_feed_aliases(&self) -> Option<(&PodcastId, &[FeedUrl])> {
|
||
match &self.payload {
|
||
SyncOpPayload::PodcastFeedAliasesAdded {
|
||
podcast_id,
|
||
feed_aliases,
|
||
} => Some((podcast_id, feed_aliases)),
|
||
_ => None,
|
||
}
|
||
}
|
||
|
||
/// Progress register written by a `podcast_progress_set` operation.
|
||
///
|
||
/// `device_id` is the operation origin.
|
||
pub fn podcast_progress(&self) -> Option<ProgressRecord> {
|
||
let SyncOpPayload::PodcastProgressSet {
|
||
episode_id,
|
||
podcast_id,
|
||
position_ms,
|
||
status,
|
||
generation,
|
||
session_id,
|
||
..
|
||
} = &self.payload
|
||
else {
|
||
return None;
|
||
};
|
||
Some(ProgressRecord {
|
||
episode_id: episode_id.clone(),
|
||
podcast_id: podcast_id.clone(),
|
||
position_ms: *position_ms,
|
||
status: *status,
|
||
generation: *generation,
|
||
session_id: session_id.clone(),
|
||
hlc_ms: self.hlc_ms,
|
||
device_id: self.origin_device_id.clone(),
|
||
op_id: self.op_id.clone(),
|
||
})
|
||
}
|
||
|
||
/// Listening session carried by a `podcast_listen_recorded` operation.
|
||
pub fn podcast_listen_session(&self) -> Option<&ListenSession> {
|
||
match &self.payload {
|
||
SyncOpPayload::PodcastListenRecorded { session, .. } => Some(session),
|
||
_ => None,
|
||
}
|
||
}
|
||
|
||
/// Validates a podcast operation against the contract.
|
||
///
|
||
/// Non-podcast operations are accepted unchanged. Receivers must skip
|
||
/// (but still acknowledge) podcast operations that fail this check
|
||
/// (bounds, stamps, mismatched references).
|
||
///
|
||
/// Ids ([`PodcastId`], [`EpisodeId`]) and feed URLs ([`FeedUrl`]) are
|
||
/// checked earlier, while the message is deserialized: a non-canonical id
|
||
/// or URL is a schema violation like a wrong JSON type, and the whole
|
||
/// message fails to parse. Conforming clients cannot produce one, because
|
||
/// these types only serialize canonical values and their rules are frozen
|
||
/// with the `v1` derivation domains; changing them requires a new protocol
|
||
/// version.
|
||
pub fn validate_podcast(&self) -> PodcastResult<()> {
|
||
let check_ref = |episode: &Option<PodcastEpisodeRef>,
|
||
episode_id: &EpisodeId,
|
||
podcast_id: &PodcastId| {
|
||
match episode {
|
||
Some(episode)
|
||
if &episode.episode_id != episode_id || &episode.podcast_id != podcast_id =>
|
||
{
|
||
Err(PodcastError::Mismatch("episode reference"))
|
||
}
|
||
Some(episode) => episode.validate(),
|
||
None => Ok(()),
|
||
}
|
||
};
|
||
match &self.payload {
|
||
SyncOpPayload::PodcastSubscriptionSet { .. } => self
|
||
.podcast_subscription()
|
||
.expect("subscription payload")
|
||
.validate(),
|
||
SyncOpPayload::PodcastShareSet { .. } => {
|
||
self.podcast_share().expect("share payload").validate()
|
||
}
|
||
SyncOpPayload::PodcastFeedAliasesAdded { feed_aliases, .. } => {
|
||
if feed_aliases.is_empty() || feed_aliases.len() > MAX_FEED_ALIASES + 1 {
|
||
return Err(PodcastError::InvalidField {
|
||
field: "feed_aliases",
|
||
reason: "must hold 1 to MAX_FEED_ALIASES + 1 URLs",
|
||
});
|
||
}
|
||
Ok(())
|
||
}
|
||
SyncOpPayload::PodcastProgressSet {
|
||
episode_id,
|
||
podcast_id,
|
||
episode,
|
||
..
|
||
} => {
|
||
self.podcast_progress()
|
||
.expect("progress payload")
|
||
.validate()?;
|
||
check_ref(episode, episode_id, podcast_id)
|
||
}
|
||
SyncOpPayload::PodcastListenRecorded { session, episode } => {
|
||
session.validate()?;
|
||
if session.device_id != self.origin_device_id {
|
||
return Err(PodcastError::Mismatch(
|
||
"session device and operation origin",
|
||
));
|
||
}
|
||
check_ref(episode, &session.episode_id, &session.podcast_id)
|
||
}
|
||
_ => Ok(()),
|
||
}
|
||
}
|
||
}
|
||
|
||
/// Returns whether `payload` may be sent to a peer with `peer_version`.
|
||
///
|
||
/// * `listen_recorded` needs v2;
|
||
/// * every `podcast_*` operation needs v4;
|
||
/// * a `playback_command` whose state contains podcast items needs v4;
|
||
/// * everything else is accepted by every version.
|
||
///
|
||
/// Gating is mandatory: an older peer cannot deserialize an unknown `kind`
|
||
/// and would reject the entire message, stalling all synchronization.
|
||
pub fn op_allowed_for_peer(payload: &SyncOpPayload, peer_version: u16) -> bool {
|
||
match payload {
|
||
SyncOpPayload::ListenRecorded { .. } => supports_listen_history(peer_version),
|
||
SyncOpPayload::PlaybackCommand { command, .. } => {
|
||
!playback_command_has_podcasts(command) || supports_podcasts(peer_version)
|
||
}
|
||
payload if payload.is_podcast() => supports_podcasts(peer_version),
|
||
_ => true,
|
||
}
|
||
}
|
||
|
||
/// Returns whether the queue contains podcast episodes or Jam placeholders.
|
||
pub fn playback_state_has_podcasts(state: &PlaybackStateWire) -> bool {
|
||
state
|
||
.queue
|
||
.iter()
|
||
.any(PlaybackTrack::requires_podcast_support)
|
||
}
|
||
|
||
/// Returns whether a playback command carries podcast items.
|
||
pub fn playback_command_has_podcasts(command: &PlaybackCommand) -> bool {
|
||
match command {
|
||
crate::playback::Command::SetState { state, .. }
|
||
| crate::playback::Command::ActiveChanged { state, .. } => {
|
||
playback_state_has_podcasts(state)
|
||
}
|
||
}
|
||
}
|
||
|
||
/// Returns whether `state` may be sent to (or handed off to) a peer.
|
||
///
|
||
/// For a peer below v4 with podcast items in the queue, do not send the
|
||
/// playback snapshot and refuse the handoff with an "update required" message.
|
||
/// Never strip the episodes to make the state fit: an old client would then
|
||
/// forward a queue without them and lose them for every device.
|
||
pub fn playback_allowed_for_peer(state: &PlaybackStateWire, peer_version: u16) -> bool {
|
||
!playback_state_has_podcasts(state) || supports_podcasts(peer_version)
|
||
}
|
||
|
||
/// Returns whether a `SetState`/`ActiveChanged` command from a peer may be
|
||
/// applied to the local playback state.
|
||
///
|
||
/// While the local queue contains podcast items, commands from peers below
|
||
/// v4 are rejected: such a peer does not know the items and its state would
|
||
/// silently drop them.
|
||
pub fn playback_command_allowed_from_peer(local: &PlaybackStateWire, peer_version: u16) -> bool {
|
||
supports_podcasts(peer_version) || !playback_state_has_podcasts(local)
|
||
}
|
||
|
||
/// Returns a copy of `state` safe to show to Jam participants.
|
||
///
|
||
/// Every podcast episode (and any existing placeholder) is replaced by
|
||
/// [`PlaybackTrack::private_placeholder`]: no title, URL, feed or id leaves
|
||
/// the host. Queue order, position and transport state are kept.
|
||
pub fn redact_for_jam(mut state: PlaybackStateWire) -> PlaybackStateWire {
|
||
for track in &mut state.queue {
|
||
if track.requires_podcast_support() {
|
||
*track = PlaybackTrack::private_placeholder();
|
||
}
|
||
}
|
||
state
|
||
}
|
||
|
||
/// Returns whether a Jam participant command may be considered at all.
|
||
///
|
||
/// Commands that contain real podcast episodes are rejected: participants
|
||
/// cannot add episodes to the host queue. Placeholders are allowed here and
|
||
/// must be mapped back with [`restore_jam_private_items`].
|
||
pub fn jam_command_allowed(command: &PlaybackCommand) -> bool {
|
||
match command {
|
||
crate::playback::Command::SetState { state, .. }
|
||
| crate::playback::Command::ActiveChanged { state, .. } => !state
|
||
.queue
|
||
.iter()
|
||
.any(|track| track.podcast_episode_ref().is_some()),
|
||
}
|
||
}
|
||
|
||
/// Maps the placeholders of a participant's state back to the host's items.
|
||
///
|
||
/// The k-th placeholder of `participant` becomes the k-th private item of
|
||
/// `host`. Returns `None` (reject the command) when the participant state
|
||
/// contains real podcast episodes or a different number of placeholders, so a
|
||
/// participant can reorder music and move placeholders but cannot drop,
|
||
/// duplicate or inject private items.
|
||
pub fn restore_jam_private_items(
|
||
host: &PlaybackStateWire,
|
||
mut participant: PlaybackStateWire,
|
||
) -> Option<PlaybackStateWire> {
|
||
let mut private = host
|
||
.queue
|
||
.iter()
|
||
.filter(|track| track.requires_podcast_support());
|
||
for track in &mut participant.queue {
|
||
if track.podcast_episode_ref().is_some() {
|
||
return None;
|
||
}
|
||
if track.is_private_placeholder() {
|
||
*track = private.next()?.clone();
|
||
}
|
||
}
|
||
private.next().is_none().then_some(participant)
|
||
}
|
||
|
||
/// Materialized sync snapshot sent with every handshake.
|
||
///
|
||
/// Music listening history is intentionally absent: it is an unbounded
|
||
/// append-only log, not last-write-wins state. New devices catch it up from
|
||
/// missing [`SyncOpPayload::ListenRecorded`] operations using the existing
|
||
/// per-origin vector and bounded operation batches.
|
||
///
|
||
/// Podcast state (protocol v4) **is** included, bounded by
|
||
/// [`SyncSnapshot::bound_podcast_state`]. Operations hidden from a peer while
|
||
/// it ran an older version are never re-requested after it upgrades, because
|
||
/// sync vectors only grow, so snapshots are the only recovery path for such a
|
||
/// peer, and only for the records that fit the snapshot bounds. Send podcast
|
||
/// sections only to v4 peers ([`SyncSnapshot::for_peer`]).
|
||
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
|
||
pub struct SyncSnapshot {
|
||
/// Current likes.
|
||
#[serde(default)]
|
||
pub likes: Vec<SnapshotLike>,
|
||
/// Like tombstones.
|
||
#[serde(default)]
|
||
pub unlikes: Vec<SnapshotLikeTombstone>,
|
||
/// Current playlists.
|
||
#[serde(default)]
|
||
pub playlists: Vec<SnapshotPlaylist>,
|
||
/// Deleted playlists.
|
||
#[serde(default)]
|
||
pub deleted_playlists: Vec<SnapshotPlaylistTombstone>,
|
||
/// Removed playlist items.
|
||
#[serde(default)]
|
||
pub removed_playlist_items: Vec<SnapshotPlaylistItemTombstone>,
|
||
/// Podcast subscription registers, including unsubscribed ones (v4).
|
||
#[serde(default, skip_serializing_if = "Vec::is_empty")]
|
||
pub podcast_subscriptions: Vec<SubscriptionRecord>,
|
||
/// Podcast share registers, including `shared = false` tombstones (v4).
|
||
#[serde(default, skip_serializing_if = "Vec::is_empty")]
|
||
pub podcast_shares: Vec<ShareRecord>,
|
||
/// Episode progress registers (v4).
|
||
#[serde(default, skip_serializing_if = "Vec::is_empty")]
|
||
pub podcast_progress: Vec<ProgressRecord>,
|
||
/// Most recent podcast listening sessions (v4).
|
||
#[serde(default, skip_serializing_if = "Vec::is_empty")]
|
||
pub podcast_listen_sessions: Vec<ListenSession>,
|
||
}
|
||
|
||
impl SyncSnapshot {
|
||
/// Whether any podcast section is non-empty.
|
||
pub fn has_podcast_state(&self) -> bool {
|
||
!self.podcast_subscriptions.is_empty()
|
||
|| !self.podcast_shares.is_empty()
|
||
|| !self.podcast_progress.is_empty()
|
||
|| !self.podcast_listen_sessions.is_empty()
|
||
}
|
||
|
||
/// Removes all podcast sections.
|
||
pub fn strip_podcast_state(&mut self) {
|
||
self.podcast_subscriptions.clear();
|
||
self.podcast_shares.clear();
|
||
self.podcast_progress.clear();
|
||
self.podcast_listen_sessions.clear();
|
||
}
|
||
|
||
/// Copy of the snapshot for a peer: podcast sections only for v4+.
|
||
pub fn for_peer(&self, peer_version: u16) -> Self {
|
||
let mut snapshot = self.clone();
|
||
if !supports_podcasts(peer_version) {
|
||
snapshot.strip_podcast_state();
|
||
}
|
||
snapshot
|
||
}
|
||
|
||
/// Bounds the podcast sections with the default budget
|
||
/// [`MAX_PODCAST_SNAPSHOT_BYTES`]; see
|
||
/// [`SyncSnapshot::bound_podcast_state_to`].
|
||
pub fn bound_podcast_state(&mut self) {
|
||
self.bound_podcast_state_to(MAX_PODCAST_SNAPSHOT_BYTES);
|
||
}
|
||
|
||
/// Sorts and truncates the podcast sections to the snapshot limits and to
|
||
/// `budget_bytes` of serialized JSON.
|
||
///
|
||
/// * Subscription records lose `podcast.description`: it is the largest
|
||
/// field and every device refreshes channel metadata from the feed. The
|
||
/// register (`subscribed`, stamps) and feed aliases are kept whole.
|
||
/// * Each section is ordered newest first (subscriptions and shares by
|
||
/// `(generation, hlc_ms)`, progress by `(generation, hlc_ms)`, sessions
|
||
/// by `ended_at_ms`; ties by id) and capped by its `MAX_SNAPSHOT_*`
|
||
/// count.
|
||
/// * Each section has its own share of the budget (subscriptions 25 %,
|
||
/// shares 5 %, progress 45 %, sessions 25 %), so large subscription
|
||
/// records cannot crowd out progress. Unused budget passes on to the
|
||
/// following sections in that order.
|
||
///
|
||
/// Callers pass [`MAX_PODCAST_SNAPSHOT_BYTES`], or less when the rest of
|
||
/// the message (music snapshot, operations, playback) leaves less room
|
||
/// under [`MAX_SYNC_LINE`]; see [`podcast_snapshot_budget`].
|
||
///
|
||
/// Records cut here reach a peer only through operations it has not
|
||
/// acknowledged yet. A peer that skipped podcast operations while it ran
|
||
/// an older version never receives the cut records: it recovers the newest
|
||
/// records only, and its play counts can differ from other devices.
|
||
pub fn bound_podcast_state_to(&mut self, budget_bytes: usize) {
|
||
let share = |percent: usize| budget_bytes / 100 * percent;
|
||
let mut budget = 0usize;
|
||
for record in &mut self.podcast_subscriptions {
|
||
record.podcast.description = None;
|
||
}
|
||
self.podcast_subscriptions.sort_by(|a, b| {
|
||
(b.generation, b.hlc_ms, &b.op_id, &b.podcast_id).cmp(&(
|
||
a.generation,
|
||
a.hlc_ms,
|
||
&a.op_id,
|
||
&a.podcast_id,
|
||
))
|
||
});
|
||
budget += share(25);
|
||
bound_section(
|
||
&mut self.podcast_subscriptions,
|
||
MAX_SNAPSHOT_SUBSCRIPTIONS,
|
||
&mut budget,
|
||
);
|
||
self.podcast_shares.sort_by(|a, b| {
|
||
(b.generation, b.hlc_ms, &b.op_id, &b.podcast_id).cmp(&(
|
||
a.generation,
|
||
a.hlc_ms,
|
||
&a.op_id,
|
||
&a.podcast_id,
|
||
))
|
||
});
|
||
budget += share(5);
|
||
bound_section(&mut self.podcast_shares, MAX_SNAPSHOT_SHARES, &mut budget);
|
||
self.podcast_progress.sort_by(|a, b| {
|
||
(b.generation, b.hlc_ms, &b.op_id, &b.episode_id).cmp(&(
|
||
a.generation,
|
||
a.hlc_ms,
|
||
&a.op_id,
|
||
&a.episode_id,
|
||
))
|
||
});
|
||
budget += share(45);
|
||
bound_section(
|
||
&mut self.podcast_progress,
|
||
MAX_SNAPSHOT_PROGRESS,
|
||
&mut budget,
|
||
);
|
||
self.podcast_listen_sessions
|
||
.sort_by(|a, b| (b.ended_at_ms, &b.session_id).cmp(&(a.ended_at_ms, &a.session_id)));
|
||
budget += budget_bytes - share(25) - share(5) - share(45);
|
||
bound_section(
|
||
&mut self.podcast_listen_sessions,
|
||
MAX_SNAPSHOT_LISTEN_SESSIONS,
|
||
&mut budget,
|
||
);
|
||
}
|
||
|
||
/// Whether the podcast sections respect the per-section count limits.
|
||
///
|
||
/// Receivers should ignore the podcast sections of a snapshot that
|
||
/// violates them and validate every record before merging it.
|
||
pub fn podcast_state_within_limits(&self) -> bool {
|
||
self.podcast_subscriptions.len() <= MAX_SNAPSHOT_SUBSCRIPTIONS
|
||
&& self.podcast_shares.len() <= MAX_SNAPSHOT_SHARES
|
||
&& self.podcast_progress.len() <= MAX_SNAPSHOT_PROGRESS
|
||
&& self.podcast_listen_sessions.len() <= MAX_SNAPSHOT_LISTEN_SESSIONS
|
||
}
|
||
}
|
||
|
||
/// Byte budget for the podcast snapshot sections of one message.
|
||
///
|
||
/// `other_bytes` is the serialized size of the message without podcast
|
||
/// sections. The result keeps the whole line under [`MAX_SYNC_LINE`] with a
|
||
/// 64 KiB margin and never exceeds [`MAX_PODCAST_SNAPSHOT_BYTES`].
|
||
pub fn podcast_snapshot_budget(other_bytes: usize) -> usize {
|
||
MAX_SYNC_LINE
|
||
.saturating_sub(other_bytes.saturating_add(64 * 1024))
|
||
.min(MAX_PODCAST_SNAPSHOT_BYTES)
|
||
}
|
||
|
||
fn bound_section<T: Serialize>(items: &mut Vec<T>, max_items: usize, budget: &mut usize) {
|
||
let mut keep = 0;
|
||
for item in items.iter().take(max_items) {
|
||
let size = serde_json::to_vec(item).map_or(usize::MAX, |bytes| bytes.len() + 1);
|
||
if size > *budget {
|
||
break;
|
||
}
|
||
*budget -= size;
|
||
keep += 1;
|
||
}
|
||
items.truncate(keep);
|
||
}
|
||
|
||
/// Snapshot like row.
|
||
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
|
||
pub struct SnapshotLike {
|
||
/// Content id.
|
||
pub content_id: String,
|
||
/// Last write timestamp.
|
||
pub hlc_ms: i64,
|
||
/// Last write op id.
|
||
pub op_id: String,
|
||
/// Optional unresolved federated metadata.
|
||
#[serde(default)]
|
||
pub fed: Option<SyncedFedTrack>,
|
||
}
|
||
|
||
/// Snapshot unlike tombstone.
|
||
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
|
||
pub struct SnapshotLikeTombstone {
|
||
/// Content id.
|
||
pub content_id: String,
|
||
/// Last write timestamp.
|
||
pub hlc_ms: i64,
|
||
/// Last write op id.
|
||
pub op_id: String,
|
||
}
|
||
|
||
/// Snapshot playlist.
|
||
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
|
||
pub struct SnapshotPlaylist {
|
||
/// Stable playlist sync id.
|
||
pub playlist_id: String,
|
||
/// Title.
|
||
pub title: String,
|
||
/// Last write timestamp.
|
||
pub hlc_ms: i64,
|
||
/// Last write op id.
|
||
pub op_id: String,
|
||
/// Current items.
|
||
#[serde(default)]
|
||
pub items: Vec<SnapshotPlaylistItem>,
|
||
}
|
||
|
||
/// Snapshot deleted playlist tombstone.
|
||
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
|
||
pub struct SnapshotPlaylistTombstone {
|
||
/// Stable playlist sync id.
|
||
pub playlist_id: String,
|
||
/// Last write timestamp.
|
||
pub hlc_ms: i64,
|
||
/// Last write op id.
|
||
pub op_id: String,
|
||
}
|
||
|
||
/// Snapshot playlist item.
|
||
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
|
||
pub struct SnapshotPlaylistItem {
|
||
/// Content id.
|
||
pub content_id: String,
|
||
/// Playlist position.
|
||
pub position: i64,
|
||
/// Last write timestamp.
|
||
pub hlc_ms: i64,
|
||
/// Last write op id.
|
||
pub op_id: String,
|
||
/// Optional unresolved federated metadata.
|
||
#[serde(default)]
|
||
pub fed: Option<SyncedFedTrack>,
|
||
}
|
||
|
||
/// Snapshot removed playlist item tombstone.
|
||
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
|
||
pub struct SnapshotPlaylistItemTombstone {
|
||
/// Stable playlist sync id.
|
||
pub playlist_id: String,
|
||
/// Content id.
|
||
pub content_id: String,
|
||
/// Last write timestamp.
|
||
pub hlc_ms: i64,
|
||
/// Last write op id.
|
||
pub op_id: String,
|
||
}
|
||
|
||
/// Top-level message spoken on [`SYNC_ALPN`].
|
||
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
|
||
#[serde(tag = "type", rename_all = "snake_case")]
|
||
pub enum WireMessage {
|
||
/// Pairing request sent by the invite consumer.
|
||
PairRequest {
|
||
/// Invite id.
|
||
invite_id: String,
|
||
/// Invite secret.
|
||
secret: String,
|
||
/// Requester device profile.
|
||
profile: DeviceProfileWire,
|
||
/// Requester sync group id.
|
||
#[serde(default)]
|
||
group_id: Option<String>,
|
||
/// Number of active devices in requester group.
|
||
#[serde(default)]
|
||
group_active_devices: usize,
|
||
/// Requester trusted devices.
|
||
#[serde(default)]
|
||
devices: Vec<DeviceProfileWire>,
|
||
/// Requester vector clock.
|
||
vector: BTreeMap<String, i64>,
|
||
/// Requester pending operations.
|
||
ops: Vec<SyncOpWire>,
|
||
/// Requester materialized snapshot.
|
||
snapshot: SyncSnapshot,
|
||
/// Requester playback snapshot.
|
||
#[serde(default)]
|
||
playback: Option<PlaybackSnapshot>,
|
||
},
|
||
/// Pairing response sent by the inviter.
|
||
PairResponse {
|
||
/// Whether pairing was accepted.
|
||
accepted: bool,
|
||
/// Whether the request is waiting for user confirmation.
|
||
#[serde(default)]
|
||
pending: bool,
|
||
/// Optional rejection error.
|
||
#[serde(default)]
|
||
error: Option<String>,
|
||
/// Accepted group id.
|
||
#[serde(default)]
|
||
group_id: Option<String>,
|
||
/// Inviter profile.
|
||
#[serde(default)]
|
||
profile: Option<DeviceProfileWire>,
|
||
/// Inviter trusted devices.
|
||
#[serde(default)]
|
||
devices: Vec<DeviceProfileWire>,
|
||
/// Inviter vector clock.
|
||
#[serde(default)]
|
||
vector: BTreeMap<String, i64>,
|
||
/// Inviter pending operations.
|
||
#[serde(default)]
|
||
ops: Vec<SyncOpWire>,
|
||
/// Inviter materialized snapshot.
|
||
#[serde(default)]
|
||
snapshot: SyncSnapshot,
|
||
/// Inviter playback snapshot.
|
||
#[serde(default)]
|
||
playback: Option<PlaybackSnapshot>,
|
||
},
|
||
/// Regular sync hello.
|
||
Hello {
|
||
/// Sync group id.
|
||
group_id: String,
|
||
/// Sender profile.
|
||
profile: DeviceProfileWire,
|
||
/// Sender trusted devices.
|
||
devices: Vec<DeviceProfileWire>,
|
||
/// Sender vector clock.
|
||
vector: BTreeMap<String, i64>,
|
||
/// Sender pending operations.
|
||
ops: Vec<SyncOpWire>,
|
||
/// Sender materialized snapshot.
|
||
snapshot: SyncSnapshot,
|
||
/// Sender playback snapshot.
|
||
#[serde(default)]
|
||
playback: Option<PlaybackSnapshot>,
|
||
},
|
||
/// Regular sync response.
|
||
SyncResponse {
|
||
/// Whether sync was accepted.
|
||
accepted: bool,
|
||
/// Optional rejection error.
|
||
#[serde(default)]
|
||
error: Option<String>,
|
||
/// Receiver trusted devices.
|
||
#[serde(default)]
|
||
devices: Vec<DeviceProfileWire>,
|
||
/// Receiver vector clock.
|
||
#[serde(default)]
|
||
vector: BTreeMap<String, i64>,
|
||
/// Receiver pending operations.
|
||
#[serde(default)]
|
||
ops: Vec<SyncOpWire>,
|
||
/// Receiver materialized snapshot.
|
||
#[serde(default)]
|
||
snapshot: SyncSnapshot,
|
||
/// Receiver playback snapshot.
|
||
#[serde(default)]
|
||
playback: Option<PlaybackSnapshot>,
|
||
},
|
||
}
|
||
|
||
/// Encodes an invite as a compact `frid://i/...` link.
|
||
pub fn encode_invite(invite: &InviteWire) -> Result<String> {
|
||
let bytes = serde_json::to_vec(invite).map_err(protocol_err)?;
|
||
Ok(format!("frid://i/{}", base64url_encode(&bytes)))
|
||
}
|
||
|
||
/// Parses a `frid://i/...` invite.
|
||
pub fn parse_invite(value: &str) -> Result<InviteWire> {
|
||
let Some(token) = value.trim().strip_prefix("frid://i/") else {
|
||
return Err(MusicDhtError::Protocol(
|
||
"usage: frid://i/<invite>".to_string(),
|
||
));
|
||
};
|
||
let bytes = base64url_decode(token)?;
|
||
let invite: InviteWire = serde_json::from_slice(&bytes).map_err(protocol_err)?;
|
||
if invite.v != 1 {
|
||
return Err(MusicDhtError::Protocol(
|
||
"unsupported invite version".to_string(),
|
||
));
|
||
}
|
||
Ok(invite)
|
||
}
|
||
|
||
/// Extracts the network id carried by an invite's endpoint ticket.
|
||
pub fn invite_network_id(value: &str) -> Result<NetworkId> {
|
||
let invite = parse_invite(value)?;
|
||
let ticket = PeerTicket::from_str(&invite.ticket).map_err(protocol_err)?;
|
||
Ok(ticket.network_id)
|
||
}
|
||
|
||
/// Hashes an invite secret for durable storage.
|
||
pub fn hash_secret(secret: &str) -> String {
|
||
blake3::hash(secret.as_bytes()).to_hex().to_string()
|
||
}
|
||
|
||
/// Generates a random lowercase hex token.
|
||
pub fn random_hex(bytes: usize) -> String {
|
||
let key = SecretKey::generate();
|
||
let mut seed = key.to_bytes().to_vec();
|
||
while seed.len() < bytes {
|
||
seed.extend_from_slice(blake3::hash(&seed).as_bytes());
|
||
}
|
||
hex_encode(&seed[..bytes])
|
||
}
|
||
|
||
/// Extracts endpoint id from a ticket string.
|
||
pub fn ticket_endpoint_id(ticket: &str) -> Option<String> {
|
||
let ticket = PeerTicket::from_str(ticket).ok()?;
|
||
Some(ticket.endpoint_id().to_string())
|
||
}
|
||
|
||
/// Writes a JSON-lines sync message.
|
||
pub async fn write_msg(stream: &mut ByteStream, message: &WireMessage) -> Result<()> {
|
||
let mut payload = serde_json::to_vec(message).map_err(protocol_err)?;
|
||
payload.push(b'\n');
|
||
stream.send.write_all(&payload).await.map_err(network_err)?;
|
||
Ok(())
|
||
}
|
||
|
||
/// Finishes the sending side.
|
||
pub async fn finish_send(stream: &mut ByteStream) -> Result<()> {
|
||
stream.send.finish().map_err(network_err)?;
|
||
Ok(())
|
||
}
|
||
|
||
/// Finishes the response side and waits briefly for peer acknowledgement.
|
||
pub async fn finish_response(
|
||
stream: &mut ByteStream,
|
||
drain_timeout: std::time::Duration,
|
||
) -> Result<()> {
|
||
stream.send.finish().map_err(network_err)?;
|
||
let _ = tokio::time::timeout(drain_timeout, stream.send.stopped()).await;
|
||
Ok(())
|
||
}
|
||
|
||
/// Reads a JSON-lines sync message.
|
||
pub async fn read_msg(stream: &mut ByteStream) -> Result<WireMessage> {
|
||
let line = read_line(&mut stream.recv).await?;
|
||
serde_json::from_slice(&line).map_err(protocol_err)
|
||
}
|
||
|
||
/// Reads one newline-terminated protocol line.
|
||
pub async fn read_line<R: AsyncRead + Unpin>(reader: &mut R) -> Result<Vec<u8>> {
|
||
read_line_limited(reader, MAX_SYNC_LINE).await
|
||
}
|
||
|
||
/// Reads one newline-terminated protocol line with a custom size limit.
|
||
pub async fn read_line_limited<R: AsyncRead + Unpin>(
|
||
reader: &mut R,
|
||
max_line: usize,
|
||
) -> Result<Vec<u8>> {
|
||
let mut out = Vec::new();
|
||
loop {
|
||
let mut byte = [0u8; 1];
|
||
let read = reader.read(&mut byte).await.map_err(network_err)?;
|
||
if read == 0 {
|
||
break;
|
||
}
|
||
if byte[0] == b'\n' {
|
||
break;
|
||
}
|
||
out.push(byte[0]);
|
||
if out.len() > max_line {
|
||
return Err(MusicDhtError::Protocol(
|
||
"protocol line is too large".to_string(),
|
||
));
|
||
}
|
||
}
|
||
Ok(out)
|
||
}
|
||
|
||
/// Reads one sync message from any async reader.
|
||
pub async fn read_msg_from<R: AsyncRead + Unpin>(reader: &mut R) -> Result<WireMessage> {
|
||
let line = read_line(reader).await?;
|
||
serde_json::from_slice(&line).map_err(protocol_err)
|
||
}
|
||
|
||
fn base64url_encode(bytes: &[u8]) -> String {
|
||
const TABLE: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
|
||
let mut out = String::new();
|
||
let mut i = 0;
|
||
while i < bytes.len() {
|
||
let b0 = bytes[i];
|
||
let b1 = bytes.get(i + 1).copied().unwrap_or(0);
|
||
let b2 = bytes.get(i + 2).copied().unwrap_or(0);
|
||
out.push(TABLE[(b0 >> 2) as usize] as char);
|
||
out.push(TABLE[(((b0 & 0b0000_0011) << 4) | (b1 >> 4)) as usize] as char);
|
||
if i + 1 < bytes.len() {
|
||
out.push(TABLE[(((b1 & 0b0000_1111) << 2) | (b2 >> 6)) as usize] as char);
|
||
}
|
||
if i + 2 < bytes.len() {
|
||
out.push(TABLE[(b2 & 0b0011_1111) as usize] as char);
|
||
}
|
||
i += 3;
|
||
}
|
||
out
|
||
}
|
||
|
||
fn base64url_decode(value: &str) -> Result<Vec<u8>> {
|
||
fn val(byte: u8) -> Option<u8> {
|
||
match byte {
|
||
b'A'..=b'Z' => Some(byte - b'A'),
|
||
b'a'..=b'z' => Some(byte - b'a' + 26),
|
||
b'0'..=b'9' => Some(byte - b'0' + 52),
|
||
b'-' => Some(62),
|
||
b'_' => Some(63),
|
||
_ => None,
|
||
}
|
||
}
|
||
let bytes = value.as_bytes();
|
||
let mut out = Vec::with_capacity(bytes.len() * 3 / 4);
|
||
let mut i = 0;
|
||
while i < bytes.len() {
|
||
let a = val(bytes[i])
|
||
.ok_or_else(|| MusicDhtError::Protocol("invalid base64url invite".to_string()))?;
|
||
let b = val(*bytes
|
||
.get(i + 1)
|
||
.ok_or_else(|| MusicDhtError::Protocol("truncated base64url invite".to_string()))?)
|
||
.ok_or_else(|| MusicDhtError::Protocol("invalid base64url invite".to_string()))?;
|
||
let c = bytes.get(i + 2).and_then(|byte| val(*byte));
|
||
let d = bytes.get(i + 3).and_then(|byte| val(*byte));
|
||
out.push((a << 2) | (b >> 4));
|
||
if let Some(c) = c {
|
||
out.push((b << 4) | (c >> 2));
|
||
if let Some(d) = d {
|
||
out.push((c << 6) | d);
|
||
}
|
||
}
|
||
i += 4;
|
||
}
|
||
Ok(out)
|
||
}
|
||
|
||
fn hex_encode(bytes: &[u8]) -> String {
|
||
bytes.iter().map(|byte| format!("{byte:02x}")).collect()
|
||
}
|
||
|
||
fn protocol_err(err: impl std::fmt::Display) -> MusicDhtError {
|
||
MusicDhtError::Protocol(err.to_string())
|
||
}
|
||
|
||
fn network_err(err: impl std::fmt::Display) -> MusicDhtError {
|
||
MusicDhtError::Network(err.to_string())
|
||
}
|
||
|
||
#[cfg(test)]
|
||
mod tests {
|
||
use super::*;
|
||
|
||
fn listen(
|
||
listened_ms: i64,
|
||
duration_ms: Option<i64>,
|
||
ended_reason: ListenEndReason,
|
||
) -> ListenEvent {
|
||
ListenEvent {
|
||
listen_id: "018f-test-listen".to_string(),
|
||
content_id: format!("b3:{}", "a".repeat(64)),
|
||
started_at_ms: 1_700_000_000_000,
|
||
listened_ms,
|
||
track_duration_ms: duration_ms,
|
||
ended_reason,
|
||
track: ListenTrackMetadata {
|
||
title: "Teardrop".to_string(),
|
||
artist_names: vec!["Massive Attack".to_string()],
|
||
featured_artist_names: Vec::new(),
|
||
release_title: Some("Mezzanine".to_string()),
|
||
},
|
||
}
|
||
}
|
||
|
||
#[test]
|
||
fn finished_track_is_recorded_and_qualifies() {
|
||
let event = listen(1_000, Some(300_000), ListenEndReason::Finished);
|
||
assert!(event.should_record());
|
||
assert!(event.qualifies_as_play());
|
||
}
|
||
|
||
#[test]
|
||
fn interrupted_listens_under_five_seconds_are_noise() {
|
||
let event = listen(4_999, Some(300_000), ListenEndReason::Skipped);
|
||
assert!(!event.should_record());
|
||
assert!(!event.qualifies_as_play());
|
||
}
|
||
|
||
#[test]
|
||
fn half_duration_qualifies_for_tracks_under_eight_minutes() {
|
||
let before = listen(149_999, Some(300_000), ListenEndReason::Skipped);
|
||
let at = listen(150_000, Some(300_000), ListenEndReason::Skipped);
|
||
assert!(!before.qualifies_as_play());
|
||
assert!(at.qualifies_as_play());
|
||
}
|
||
|
||
#[test]
|
||
fn qualifying_threshold_is_capped_at_four_minutes() {
|
||
let event = listen(240_000, Some(900_000), ListenEndReason::Stopped);
|
||
assert_eq!(event.qualifying_threshold_ms(), 240_000);
|
||
assert!(event.qualifies_as_play());
|
||
}
|
||
|
||
#[test]
|
||
fn listen_payload_round_trips_with_portable_metadata() {
|
||
let payload = SyncOpPayload::ListenRecorded {
|
||
event: listen(150_000, Some(300_000), ListenEndReason::Replaced),
|
||
};
|
||
let json = serde_json::to_string(&payload).unwrap();
|
||
assert!(json.contains(r#""kind":"listen_recorded""#));
|
||
assert_eq!(
|
||
serde_json::from_str::<SyncOpPayload>(&json).unwrap(),
|
||
payload
|
||
);
|
||
}
|
||
|
||
#[test]
|
||
fn v1_peers_do_not_support_listening_history() {
|
||
assert!(!supports_listen_history(1));
|
||
assert!(supports_listen_history(2));
|
||
}
|
||
|
||
mod podcasts {
|
||
use super::*;
|
||
use crate::playback::Command;
|
||
use crate::podcast::{FeedUrl, MAX_SNAPSHOT_SHARES};
|
||
|
||
fn feed() -> FeedUrl {
|
||
FeedUrl::parse("https://private.example.test/feed?token=s3cr3t").unwrap()
|
||
}
|
||
|
||
fn podcast_id() -> PodcastId {
|
||
PodcastId::from_feed_url(&feed())
|
||
}
|
||
|
||
fn episode_id() -> EpisodeId {
|
||
EpisodeId::from_guid(&podcast_id(), "ep-1").unwrap()
|
||
}
|
||
|
||
fn episode() -> PodcastEpisodeRef {
|
||
PodcastEpisodeRef {
|
||
podcast_id: podcast_id(),
|
||
episode_id: episode_id(),
|
||
feed_url: feed(),
|
||
podcast_title: "Secret Show".to_string(),
|
||
episode_title: "Private Episode".to_string(),
|
||
audio_url: "https://cdn.example.test/private.mp3?sig=xyz".to_string(),
|
||
mime: Some("audio/mpeg".to_string()),
|
||
duration_ms: Some(3_600_000),
|
||
published_at_ms: Some(1_700_000_000_000),
|
||
season: Some(1),
|
||
episode_number: Some(3),
|
||
image_url: None,
|
||
progress_generation: Some(4),
|
||
}
|
||
}
|
||
|
||
fn music(id: i64) -> PlaybackTrack {
|
||
PlaybackTrack {
|
||
id,
|
||
title: format!("Song {id}"),
|
||
track_number: Some(1),
|
||
disc_number: None,
|
||
duration_seconds: 200.0,
|
||
artist_names: vec!["Artist".to_string()],
|
||
featured_artist_names: Vec::new(),
|
||
release_id: 7,
|
||
release_title: "Album".to_string(),
|
||
release_year: Some(2020),
|
||
file_path: String::new(),
|
||
content_id: Some(format!("b3:{}", "a".repeat(64))),
|
||
audio_format: None,
|
||
audio_bitrate: None,
|
||
audio_sample_rate: None,
|
||
audio_bit_depth: None,
|
||
file_size_bytes: None,
|
||
play_count: 0,
|
||
fed: None,
|
||
source: None,
|
||
}
|
||
}
|
||
|
||
fn state(queue: Vec<PlaybackTrack>) -> PlaybackStateWire {
|
||
PlaybackStateWire {
|
||
queue,
|
||
queue_pos: 1,
|
||
playing: true,
|
||
paused: false,
|
||
idle_since_ms: None,
|
||
position_secs: 42.5,
|
||
volume: 80,
|
||
shuffle: false,
|
||
repeat: PlaybackRepeat::Off,
|
||
playback_rate: None,
|
||
}
|
||
}
|
||
|
||
fn mixed() -> PlaybackStateWire {
|
||
state(vec![
|
||
music(1),
|
||
PlaybackTrack::podcast_episode(episode()),
|
||
music(2),
|
||
])
|
||
}
|
||
|
||
fn op(seq: i64, payload: SyncOpPayload) -> SyncOpWire {
|
||
SyncOpWire {
|
||
op_id: format!("dev-a:{seq}"),
|
||
origin_device_id: "dev-a".to_string(),
|
||
seq,
|
||
hlc_ms: 1_000 + seq,
|
||
payload,
|
||
}
|
||
}
|
||
|
||
fn session() -> ListenSession {
|
||
ListenSession {
|
||
session_id: "s-1".to_string(),
|
||
episode_id: episode_id(),
|
||
podcast_id: podcast_id(),
|
||
device_id: "dev-a".to_string(),
|
||
started_at_ms: 10,
|
||
ended_at_ms: 20,
|
||
start_position_ms: 0,
|
||
end_position_ms: 60_000,
|
||
listened_ms: 60_000,
|
||
completed: false,
|
||
}
|
||
}
|
||
|
||
fn podcast_ops() -> Vec<SyncOpPayload> {
|
||
vec![
|
||
SyncOpPayload::PodcastSubscriptionSet {
|
||
podcast_id: podcast_id(),
|
||
subscribed: true,
|
||
podcast: PodcastMeta {
|
||
feed_url: feed(),
|
||
title: "Secret Show".to_string(),
|
||
author: None,
|
||
description: Some("About things".to_string()),
|
||
link: None,
|
||
image_url: None,
|
||
},
|
||
feed_aliases: vec![feed()],
|
||
generation: 1,
|
||
},
|
||
SyncOpPayload::PodcastShareSet {
|
||
podcast_id: podcast_id(),
|
||
shared: false,
|
||
generation: 2,
|
||
},
|
||
SyncOpPayload::PodcastFeedAliasesAdded {
|
||
podcast_id: podcast_id(),
|
||
feed_aliases: vec![FeedUrl::parse("https://moved.example.test/feed").unwrap()],
|
||
},
|
||
SyncOpPayload::PodcastProgressSet {
|
||
episode_id: episode_id(),
|
||
podcast_id: podcast_id(),
|
||
position_ms: 120_000,
|
||
status: ProgressStatus::InProgress,
|
||
generation: 3,
|
||
session_id: "s-1".to_string(),
|
||
episode: Some(episode()),
|
||
},
|
||
SyncOpPayload::PodcastListenRecorded {
|
||
session: session(),
|
||
episode: None,
|
||
},
|
||
]
|
||
}
|
||
|
||
#[test]
|
||
fn podcast_ops_round_trip_and_materialize() {
|
||
let kinds = [
|
||
"podcast_subscription_set",
|
||
"podcast_share_set",
|
||
"podcast_feed_aliases_added",
|
||
"podcast_progress_set",
|
||
"podcast_listen_recorded",
|
||
];
|
||
for (seq, (payload, kind)) in podcast_ops().into_iter().zip(kinds).enumerate() {
|
||
let op = op(seq as i64 + 1, payload);
|
||
let json = serde_json::to_string(&op).unwrap();
|
||
assert!(json.contains(&format!(r#""kind":"{kind}""#)), "{json}");
|
||
let back: SyncOpWire = serde_json::from_str(&json).unwrap();
|
||
assert_eq!(back, op);
|
||
assert!(op.payload.is_podcast());
|
||
op.validate_podcast().unwrap();
|
||
}
|
||
let ops: Vec<SyncOpWire> = podcast_ops()
|
||
.into_iter()
|
||
.enumerate()
|
||
.map(|(i, payload)| op(i as i64 + 1, payload))
|
||
.collect();
|
||
let subscription = ops[0].podcast_subscription().unwrap();
|
||
assert_eq!(
|
||
(subscription.hlc_ms, subscription.op_id.as_str()),
|
||
(1_001, "dev-a:1")
|
||
);
|
||
assert!(subscription.subscribed);
|
||
assert_eq!(subscription.generation, 1);
|
||
let share = ops[1].podcast_share().unwrap();
|
||
assert!(!share.shared);
|
||
assert_eq!(share.generation, 2);
|
||
let (alias_podcast, aliases) = ops[2].podcast_feed_aliases().unwrap();
|
||
assert_eq!(alias_podcast, &podcast_id());
|
||
let mut with_alias = subscription.clone();
|
||
with_alias.add_feed_aliases(aliases);
|
||
assert!(with_alias.feed_aliases.contains(&aliases[0]));
|
||
// The alias operation never touches the register.
|
||
assert_eq!(with_alias.order_key(), subscription.order_key());
|
||
assert_eq!(with_alias.subscribed, subscription.subscribed);
|
||
let progress = ops[3].podcast_progress().unwrap();
|
||
assert_eq!(progress.device_id, "dev-a");
|
||
assert_eq!(progress.op_id, "dev-a:4");
|
||
assert_eq!(progress.generation, 3);
|
||
assert_eq!(ops[4].podcast_listen_session(), Some(&session()));
|
||
assert!(ops[0].podcast_share().is_none());
|
||
assert!(ops[0].podcast_feed_aliases().is_none());
|
||
}
|
||
|
||
#[test]
|
||
fn tombstone_rules() {
|
||
let ops = podcast_ops();
|
||
let unsubscribe = SyncOpPayload::PodcastSubscriptionSet {
|
||
podcast_id: podcast_id(),
|
||
subscribed: false,
|
||
podcast: match &ops[0] {
|
||
SyncOpPayload::PodcastSubscriptionSet { podcast, .. } => podcast.clone(),
|
||
_ => unreachable!(),
|
||
},
|
||
feed_aliases: Vec::new(),
|
||
generation: 3,
|
||
};
|
||
assert!(!unsubscribe.is_tombstone(), "unsubscribe is LWW state");
|
||
// share=false protects privacy: compacting it would let a stale
|
||
// share=true delivered again republish the podcast.
|
||
assert!(!ops[1].is_tombstone(), "share=false is LWW state");
|
||
let share = SyncOpPayload::PodcastShareSet {
|
||
podcast_id: podcast_id(),
|
||
shared: true,
|
||
generation: 4,
|
||
};
|
||
assert!(!share.is_tombstone());
|
||
for payload in &ops {
|
||
assert!(!payload.is_tombstone(), "{payload:?}");
|
||
}
|
||
}
|
||
|
||
#[test]
|
||
fn invalid_podcast_ops_are_detected() {
|
||
let mut foreign = session();
|
||
foreign.device_id = "dev-b".to_string();
|
||
let op1 = op(
|
||
1,
|
||
SyncOpPayload::PodcastListenRecorded {
|
||
session: foreign,
|
||
episode: None,
|
||
},
|
||
);
|
||
assert!(op1.validate_podcast().is_err());
|
||
let mut wrong = episode();
|
||
wrong.episode_id = EpisodeId::from_guid(&podcast_id(), "other").unwrap();
|
||
let op2 = op(
|
||
2,
|
||
SyncOpPayload::PodcastProgressSet {
|
||
episode_id: episode_id(),
|
||
podcast_id: podcast_id(),
|
||
position_ms: 1,
|
||
status: ProgressStatus::InProgress,
|
||
generation: 1,
|
||
session_id: "s".to_string(),
|
||
episode: Some(wrong),
|
||
},
|
||
);
|
||
assert!(op2.validate_podcast().is_err());
|
||
let op3 = op(
|
||
3,
|
||
SyncOpPayload::PodcastProgressSet {
|
||
episode_id: episode_id(),
|
||
podcast_id: podcast_id(),
|
||
position_ms: -5,
|
||
status: ProgressStatus::InProgress,
|
||
generation: 1,
|
||
session_id: "s".to_string(),
|
||
episode: None,
|
||
},
|
||
);
|
||
assert!(op3.validate_podcast().is_err());
|
||
// Music operations are not affected.
|
||
let like = op(
|
||
4,
|
||
SyncOpPayload::TrackLikeSet {
|
||
content_id: "b3:x".to_string(),
|
||
liked: true,
|
||
fed: None,
|
||
},
|
||
);
|
||
like.validate_podcast().unwrap();
|
||
let empty_aliases = op(
|
||
5,
|
||
SyncOpPayload::PodcastFeedAliasesAdded {
|
||
podcast_id: podcast_id(),
|
||
feed_aliases: Vec::new(),
|
||
},
|
||
);
|
||
assert!(empty_aliases.validate_podcast().is_err());
|
||
}
|
||
|
||
#[test]
|
||
fn malformed_ids_and_feed_urls_reject_the_whole_message() {
|
||
// Pins the documented behaviour: ids and feed URLs are validated
|
||
// while deserializing, so a non-canonical value is a schema
|
||
// violation of the whole message, not a skippable operation.
|
||
let like = op(
|
||
1,
|
||
SyncOpPayload::TrackLikeSet {
|
||
content_id: "b3:x".to_string(),
|
||
liked: true,
|
||
fed: None,
|
||
},
|
||
);
|
||
let share = op(
|
||
2,
|
||
SyncOpPayload::PodcastShareSet {
|
||
podcast_id: podcast_id(),
|
||
shared: true,
|
||
generation: 1,
|
||
},
|
||
);
|
||
let batch = serde_json::to_string(&vec![like, share]).unwrap();
|
||
serde_json::from_str::<Vec<SyncOpWire>>(&batch).unwrap();
|
||
let upper = batch.replace(podcast_id().as_str(), &podcast_id().as_str().to_uppercase());
|
||
assert!(serde_json::from_str::<Vec<SyncOpWire>>(&upper).is_err());
|
||
let subscription = op(3, podcast_ops().remove(0));
|
||
let json = serde_json::to_string(&subscription).unwrap();
|
||
let non_canonical = json.replace(
|
||
"https://private.example.test/feed",
|
||
"HTTPS://private.example.test:443/feed",
|
||
);
|
||
assert_ne!(json, non_canonical);
|
||
assert!(serde_json::from_str::<SyncOpWire>(&non_canonical).is_err());
|
||
}
|
||
|
||
#[test]
|
||
fn legacy_v3_json_still_parses() {
|
||
let track = r#"{"id":5,"title":"T","track_number":null,"disc_number":null,
|
||
"duration_seconds":1.0,"release_id":1,"release_title":"R","release_year":null,
|
||
"content_id":null,"audio_format":null,"audio_bitrate":null,
|
||
"audio_sample_rate":null,"audio_bit_depth":null,"file_size_bytes":null}"#;
|
||
let track: PlaybackTrack = serde_json::from_str(track).unwrap();
|
||
assert_eq!(track.source, None);
|
||
let state = r#"{"queue":[],"playing":false,"paused":true,"position_secs":0.0,
|
||
"shuffle":false,"repeat":"off"}"#;
|
||
let state: PlaybackStateWire = serde_json::from_str(state).unwrap();
|
||
assert_eq!(state.playback_rate, None);
|
||
let profile = r#"{"kind":"device_profile_set","name":"n","client_version":"1",
|
||
"endpoint_ticket":"t","endpoint_id":"e"}"#;
|
||
match serde_json::from_str::<SyncOpPayload>(profile).unwrap() {
|
||
SyncOpPayload::DeviceProfileSet {
|
||
protocol_version, ..
|
||
} => {
|
||
assert_eq!(protocol_version, None)
|
||
}
|
||
other => panic!("{other:?}"),
|
||
}
|
||
let snapshot: SyncSnapshot =
|
||
serde_json::from_str(r#"{"likes":[],"playlists":[]}"#).unwrap();
|
||
assert!(!snapshot.has_podcast_state());
|
||
}
|
||
|
||
#[test]
|
||
fn music_only_messages_keep_the_v3_shape() {
|
||
let json = serde_json::to_value(state(vec![music(1)])).unwrap();
|
||
assert!(json.get("playback_rate").is_none());
|
||
assert!(json["queue"][0].get("source").is_none());
|
||
let snapshot = serde_json::to_value(SyncSnapshot::default()).unwrap();
|
||
assert!(snapshot.get("podcast_progress").is_none());
|
||
let profile = serde_json::to_value(SyncOpPayload::DeviceProfileSet {
|
||
name: "n".to_string(),
|
||
client_version: "1".to_string(),
|
||
endpoint_ticket: "t".to_string(),
|
||
endpoint_id: "e".to_string(),
|
||
protocol_version: None,
|
||
})
|
||
.unwrap();
|
||
assert!(profile.get("protocol_version").is_none());
|
||
}
|
||
|
||
#[test]
|
||
fn podcast_queue_items_round_trip() {
|
||
let mut state = mixed();
|
||
state.playback_rate = Some(1.5);
|
||
let json = serde_json::to_string(&state).unwrap();
|
||
assert!(json.contains(r#""kind":"podcast_episode""#));
|
||
let back: PlaybackStateWire = serde_json::from_str(&json).unwrap();
|
||
assert_eq!(back, state);
|
||
let item = &back.queue[1];
|
||
assert_eq!(item.podcast_episode_ref(), Some(&episode()));
|
||
assert_eq!(item.file_path, "");
|
||
assert_eq!(item.id, 0);
|
||
assert_eq!(item.content_id, None);
|
||
assert_eq!(item.duration_seconds, 3_600.0);
|
||
let explicit_music = PlaybackTrack {
|
||
source: Some(PlaybackSource::Music),
|
||
..music(3)
|
||
};
|
||
let json = serde_json::to_string(&explicit_music).unwrap();
|
||
assert!(json.contains(r#""source":{"kind":"music"}"#), "{json}");
|
||
assert_eq!(
|
||
serde_json::from_str::<PlaybackTrack>(&json).unwrap(),
|
||
explicit_music
|
||
);
|
||
}
|
||
|
||
/// The v3 operation enum, as compiled into deployed v3 clients.
|
||
mod v3 {
|
||
use serde::Deserialize;
|
||
|
||
#[derive(Debug, Deserialize)]
|
||
#[serde(tag = "kind", rename_all = "snake_case")]
|
||
#[allow(dead_code)]
|
||
pub enum SyncOpPayload {
|
||
TrackLikeSet {
|
||
content_id: String,
|
||
liked: bool,
|
||
},
|
||
PlaylistCreated {
|
||
playlist_id: String,
|
||
title: String,
|
||
},
|
||
PlaylistRenamed {
|
||
playlist_id: String,
|
||
title: String,
|
||
},
|
||
PlaylistDeleted {
|
||
playlist_id: String,
|
||
},
|
||
PlaylistTrackAdded {
|
||
playlist_id: String,
|
||
content_id: String,
|
||
position: i64,
|
||
},
|
||
PlaylistTrackRemoved {
|
||
playlist_id: String,
|
||
content_id: String,
|
||
},
|
||
DeviceProfileSet {
|
||
name: String,
|
||
client_version: String,
|
||
endpoint_ticket: String,
|
||
endpoint_id: String,
|
||
},
|
||
DeviceTrusted {
|
||
target_device_id: String,
|
||
},
|
||
DeviceRevoked {
|
||
target_device_id: String,
|
||
target_max_seq_seen: i64,
|
||
},
|
||
PlaybackCommand {
|
||
target_device_id: String,
|
||
},
|
||
ListenRecorded {
|
||
event: serde_json::Value,
|
||
},
|
||
}
|
||
|
||
#[derive(Debug, Deserialize)]
|
||
#[allow(dead_code)]
|
||
pub struct SyncOpWire {
|
||
pub op_id: String,
|
||
pub origin_device_id: String,
|
||
pub seq: i64,
|
||
pub hlc_ms: i64,
|
||
pub payload: SyncOpPayload,
|
||
}
|
||
}
|
||
|
||
#[test]
|
||
fn v3_peers_cannot_parse_new_kinds_so_gating_is_mandatory() {
|
||
let like = op(
|
||
1,
|
||
SyncOpPayload::TrackLikeSet {
|
||
content_id: "b3:x".to_string(),
|
||
liked: true,
|
||
fed: None,
|
||
},
|
||
);
|
||
let profile = op(
|
||
2,
|
||
SyncOpPayload::DeviceProfileSet {
|
||
name: "n".to_string(),
|
||
client_version: "2".to_string(),
|
||
endpoint_ticket: "t".to_string(),
|
||
endpoint_id: "e".to_string(),
|
||
protocol_version: Some(DEVICE_SYNC_PROTOCOL_VERSION),
|
||
},
|
||
);
|
||
// Additive fields are fine for v3.
|
||
for compatible in [&like, &profile] {
|
||
let json = serde_json::to_string(compatible).unwrap();
|
||
serde_json::from_str::<v3::SyncOpWire>(&json).unwrap();
|
||
}
|
||
for (seq, payload) in podcast_ops().into_iter().enumerate() {
|
||
let podcast = op(seq as i64 + 10, payload);
|
||
let json = serde_json::to_string(&podcast).unwrap();
|
||
assert!(serde_json::from_str::<v3::SyncOpWire>(&json).is_err());
|
||
// One unknown op poisons the whole batch of a Hello message.
|
||
let batch = serde_json::to_string(&vec![like.clone(), podcast.clone()]).unwrap();
|
||
assert!(serde_json::from_str::<Vec<v3::SyncOpWire>>(&batch).is_err());
|
||
assert!(!op_allowed_for_peer(&podcast.payload, 3));
|
||
assert!(op_allowed_for_peer(&podcast.payload, 4));
|
||
}
|
||
}
|
||
|
||
#[test]
|
||
fn gating_boundaries() {
|
||
assert!(!supports_podcasts(3));
|
||
assert!(supports_podcasts(4));
|
||
assert!(supports_podcasts(5));
|
||
let listen = SyncOpPayload::ListenRecorded {
|
||
event: listen(150_000, Some(300_000), ListenEndReason::Finished),
|
||
};
|
||
assert!(!op_allowed_for_peer(&listen, 1));
|
||
assert!(op_allowed_for_peer(&listen, 2));
|
||
for payload in podcast_ops() {
|
||
for version in 0..=3 {
|
||
assert!(!op_allowed_for_peer(&payload, version));
|
||
}
|
||
assert!(op_allowed_for_peer(&payload, 4));
|
||
}
|
||
let like = SyncOpPayload::TrackLikeSet {
|
||
content_id: "b3:x".to_string(),
|
||
liked: false,
|
||
fed: None,
|
||
};
|
||
assert!(op_allowed_for_peer(&like, 1));
|
||
|
||
let command = |state| SyncOpPayload::PlaybackCommand {
|
||
target_device_id: "dev-b".to_string(),
|
||
command: Command::ActiveChanged {
|
||
active_device_id: "dev-b".to_string(),
|
||
active_device_name: "B".to_string(),
|
||
state,
|
||
},
|
||
authority: None,
|
||
};
|
||
assert!(op_allowed_for_peer(&command(state(vec![music(1)])), 3));
|
||
assert!(!op_allowed_for_peer(&command(mixed()), 3));
|
||
assert!(op_allowed_for_peer(&command(mixed()), 4));
|
||
|
||
assert!(playback_allowed_for_peer(&state(vec![music(1)]), 1));
|
||
assert!(!playback_allowed_for_peer(&mixed(), 3));
|
||
assert!(playback_allowed_for_peer(&mixed(), 4));
|
||
let redacted = redact_for_jam(mixed());
|
||
assert!(!playback_allowed_for_peer(&redacted, 3));
|
||
|
||
assert!(playback_command_allowed_from_peer(
|
||
&state(vec![music(1)]),
|
||
3
|
||
));
|
||
assert!(!playback_command_allowed_from_peer(&mixed(), 3));
|
||
assert!(playback_command_allowed_from_peer(&mixed(), 4));
|
||
}
|
||
|
||
#[test]
|
||
fn profile_versions_are_never_substituted() {
|
||
assert_eq!(profile_protocol_version(Some(4), Some(3)), 4);
|
||
assert_eq!(profile_protocol_version(None, Some(3)), 3);
|
||
assert_eq!(
|
||
profile_protocol_version(None, None),
|
||
UNREPORTED_PROTOCOL_VERSION
|
||
);
|
||
assert!(!supports_podcasts(profile_protocol_version(None, None)));
|
||
// A self-report may lower the version (downgrade).
|
||
assert_eq!(profile_protocol_version(Some(3), Some(4)), 3);
|
||
}
|
||
|
||
#[test]
|
||
fn relayed_versions_only_raise_the_stored_version() {
|
||
// A deployed v3 relay forwards every device with its own constant.
|
||
assert_eq!(relayed_protocol_version(3, Some(4)), 4);
|
||
assert!(supports_podcasts(relayed_protocol_version(3, Some(4))));
|
||
assert_eq!(relayed_protocol_version(4, Some(3)), 4);
|
||
assert_eq!(relayed_protocol_version(3, None), 3);
|
||
assert_eq!(relayed_protocol_version(1, Some(2)), 2);
|
||
}
|
||
|
||
#[test]
|
||
fn pair_requests_gate_by_the_invite_version() {
|
||
let invite = InviteWire {
|
||
v: 1,
|
||
ticket: "t".to_string(),
|
||
device_id: "inviter".to_string(),
|
||
invite_id: "i".to_string(),
|
||
secret: "s".to_string(),
|
||
expires_at_ms: 1,
|
||
protocol_version: None,
|
||
};
|
||
// Invites of older clients carry no version: assume the oldest.
|
||
let legacy = r#"{"v":1,"t":"t","d":"inviter","i":"i","s":"s","e":1}"#;
|
||
let parsed: InviteWire = serde_json::from_str(legacy).unwrap();
|
||
assert_eq!(parsed, invite);
|
||
assert_eq!(serde_json::to_string(&invite).unwrap(), legacy);
|
||
assert_eq!(
|
||
parsed.inviter_protocol_version(),
|
||
UNREPORTED_PROTOCOL_VERSION
|
||
);
|
||
let snapshot = SyncSnapshot {
|
||
podcast_listen_sessions: vec![session()],
|
||
..SyncSnapshot::default()
|
||
};
|
||
assert!(
|
||
!snapshot
|
||
.for_peer(parsed.inviter_protocol_version())
|
||
.has_podcast_state()
|
||
);
|
||
for payload in podcast_ops() {
|
||
assert!(!op_allowed_for_peer(
|
||
&payload,
|
||
parsed.inviter_protocol_version()
|
||
));
|
||
}
|
||
assert!(!playback_allowed_for_peer(
|
||
&mixed(),
|
||
parsed.inviter_protocol_version()
|
||
));
|
||
let current = InviteWire {
|
||
protocol_version: Some(DEVICE_SYNC_PROTOCOL_VERSION),
|
||
..invite
|
||
};
|
||
let link = encode_invite(¤t).unwrap();
|
||
let back = parse_invite(&link).unwrap();
|
||
assert_eq!(back, current);
|
||
assert!(supports_podcasts(back.inviter_protocol_version()));
|
||
}
|
||
|
||
#[test]
|
||
fn jam_redaction_hides_private_items() {
|
||
let original = mixed();
|
||
let redacted = redact_for_jam(original.clone());
|
||
assert_eq!(redacted.queue.len(), 3);
|
||
assert_eq!(redacted.queue[0], original.queue[0]);
|
||
assert_eq!(redacted.queue[2], original.queue[2]);
|
||
assert!(redacted.queue[1].is_private_placeholder());
|
||
assert_eq!(redacted.queue[1].title, PRIVATE_ITEM_TITLE);
|
||
assert_eq!(redacted.queue_pos, original.queue_pos);
|
||
assert_eq!(redacted.position_secs, original.position_secs);
|
||
let json = serde_json::to_string(&redacted).unwrap();
|
||
for secret in [
|
||
"Secret Show",
|
||
"Private Episode",
|
||
"private.mp3",
|
||
"s3cr3t",
|
||
"private.example.test",
|
||
podcast_id().as_str(),
|
||
episode_id().as_str(),
|
||
] {
|
||
assert!(!json.contains(secret), "{secret} leaked: {json}");
|
||
}
|
||
assert!(json.contains(r#""source":{"kind":"private"}"#));
|
||
// Redaction is idempotent.
|
||
assert_eq!(redact_for_jam(redacted.clone()), redacted);
|
||
}
|
||
|
||
#[test]
|
||
fn jam_commands_cannot_inject_or_drop_private_items() {
|
||
let host = mixed();
|
||
let set = |state| Command::SetState { state, seek: false };
|
||
// Participants see placeholders; echoing them back is allowed
|
||
// and maps to the host's episodes.
|
||
let mut seen = redact_for_jam(host.clone());
|
||
seen.paused = true;
|
||
assert!(jam_command_allowed(&set(seen.clone())));
|
||
let restored = restore_jam_private_items(&host, seen.clone()).unwrap();
|
||
assert_eq!(restored.queue, host.queue);
|
||
assert!(restored.paused);
|
||
// Reordering music around the placeholder keeps the episode.
|
||
let mut reordered = seen.clone();
|
||
reordered.queue.swap(0, 2);
|
||
let restored = restore_jam_private_items(&host, reordered).unwrap();
|
||
assert_eq!(restored.queue[1].podcast_episode_ref(), Some(&episode()));
|
||
// Injecting a real episode is rejected.
|
||
let injected = state(vec![music(1), PlaybackTrack::podcast_episode(episode())]);
|
||
assert!(!jam_command_allowed(&set(injected.clone())));
|
||
assert!(restore_jam_private_items(&host, injected).is_none());
|
||
// Dropping or duplicating placeholders is rejected.
|
||
let mut dropped = seen.clone();
|
||
dropped.queue.remove(1);
|
||
assert!(restore_jam_private_items(&host, dropped).is_none());
|
||
let mut duplicated = seen;
|
||
duplicated.queue.push(PlaybackTrack::private_placeholder());
|
||
assert!(restore_jam_private_items(&host, duplicated).is_none());
|
||
// Music-only Jam is unaffected.
|
||
let music_only = state(vec![music(1)]);
|
||
assert!(jam_command_allowed(&set(music_only.clone())));
|
||
assert_eq!(
|
||
restore_jam_private_items(&music_only, music_only.clone()),
|
||
Some(music_only)
|
||
);
|
||
}
|
||
|
||
#[test]
|
||
fn snapshot_sections_round_trip_and_are_gated() {
|
||
let ops: Vec<SyncOpWire> = podcast_ops()
|
||
.into_iter()
|
||
.enumerate()
|
||
.map(|(i, payload)| op(i as i64 + 1, payload))
|
||
.collect();
|
||
let snapshot = SyncSnapshot {
|
||
podcast_subscriptions: vec![ops[0].podcast_subscription().unwrap()],
|
||
podcast_shares: vec![ops[1].podcast_share().unwrap()],
|
||
podcast_progress: vec![ops[3].podcast_progress().unwrap()],
|
||
podcast_listen_sessions: vec![session()],
|
||
..SyncSnapshot::default()
|
||
};
|
||
let message = WireMessage::Hello {
|
||
group_id: "g".to_string(),
|
||
profile: DeviceProfileWire {
|
||
device_id: "dev-a".to_string(),
|
||
name: "A".to_string(),
|
||
client_version: "1".to_string(),
|
||
protocol_version: DEVICE_SYNC_PROTOCOL_VERSION,
|
||
endpoint_id: "e".to_string(),
|
||
endpoint_ticket: "t".to_string(),
|
||
revoked: false,
|
||
revoke_cutoff_seq: None,
|
||
updated_at_ms: 0,
|
||
},
|
||
devices: Vec::new(),
|
||
vector: BTreeMap::new(),
|
||
ops,
|
||
snapshot: snapshot.clone(),
|
||
playback: None,
|
||
};
|
||
let json = serde_json::to_string(&message).unwrap();
|
||
assert_eq!(serde_json::from_str::<WireMessage>(&json).unwrap(), message);
|
||
assert!(snapshot.has_podcast_state());
|
||
assert!(!snapshot.for_peer(3).has_podcast_state());
|
||
assert_eq!(snapshot.for_peer(4), snapshot);
|
||
}
|
||
|
||
#[test]
|
||
fn snapshot_bounds_accept_the_limit_and_cut_the_next_record() {
|
||
let shares = |count: usize| -> Vec<ShareRecord> {
|
||
(0..count)
|
||
.map(|i| ShareRecord {
|
||
podcast_id: PodcastId::from_feed_url(
|
||
&FeedUrl::parse(&format!("https://a.test/{i}")).unwrap(),
|
||
),
|
||
shared: i % 2 == 0,
|
||
generation: 1,
|
||
hlc_ms: i as i64,
|
||
op_id: format!("dev:{i}"),
|
||
})
|
||
.collect()
|
||
};
|
||
let mut at = SyncSnapshot {
|
||
podcast_shares: shares(MAX_SNAPSHOT_SHARES),
|
||
..SyncSnapshot::default()
|
||
};
|
||
assert!(at.podcast_state_within_limits());
|
||
at.bound_podcast_state();
|
||
assert_eq!(at.podcast_shares.len(), MAX_SNAPSHOT_SHARES);
|
||
let mut over = SyncSnapshot {
|
||
podcast_shares: shares(MAX_SNAPSHOT_SHARES + 1),
|
||
..SyncSnapshot::default()
|
||
};
|
||
assert!(!over.podcast_state_within_limits());
|
||
over.bound_podcast_state();
|
||
assert_eq!(over.podcast_shares.len(), MAX_SNAPSHOT_SHARES);
|
||
// Newest first: the oldest record is the one cut.
|
||
assert_eq!(over.podcast_shares[0].hlc_ms, MAX_SNAPSHOT_SHARES as i64);
|
||
assert!(over.podcast_shares.iter().all(|share| share.hlc_ms > 0));
|
||
}
|
||
|
||
#[test]
|
||
fn snapshot_byte_budget_is_enforced() {
|
||
// Worst-case subscription records: long Cyrillic title, author and
|
||
// description, plus a few progress registers.
|
||
let big: String = "я".repeat(crate::podcast::MAX_DESCRIPTION_CHARS);
|
||
let title: String = big.chars().take(crate::podcast::MAX_TITLE_CHARS).collect();
|
||
let subscriptions: Vec<SubscriptionRecord> = (0..MAX_SNAPSHOT_SUBSCRIPTIONS)
|
||
.map(|i| {
|
||
let url = FeedUrl::parse(&format!("https://a.test/{i}")).unwrap();
|
||
SubscriptionRecord {
|
||
podcast_id: PodcastId::from_feed_url(&url),
|
||
subscribed: true,
|
||
podcast: PodcastMeta {
|
||
feed_url: url,
|
||
title: title.clone(),
|
||
author: Some(title.clone()),
|
||
description: Some(big.clone()),
|
||
link: None,
|
||
image_url: None,
|
||
},
|
||
feed_aliases: Vec::new(),
|
||
generation: 1,
|
||
hlc_ms: i as i64,
|
||
op_id: format!("dev:{i}"),
|
||
}
|
||
})
|
||
.collect();
|
||
let progress: Vec<ProgressRecord> = (0..10)
|
||
.map(|i| {
|
||
op(
|
||
i + 1,
|
||
SyncOpPayload::PodcastProgressSet {
|
||
episode_id: EpisodeId::from_guid(&podcast_id(), &format!("e{i}"))
|
||
.unwrap(),
|
||
podcast_id: podcast_id(),
|
||
position_ms: 1_000,
|
||
status: ProgressStatus::InProgress,
|
||
generation: 1,
|
||
session_id: "s".to_string(),
|
||
episode: None,
|
||
},
|
||
)
|
||
.podcast_progress()
|
||
.unwrap()
|
||
})
|
||
.collect();
|
||
let original = SyncSnapshot {
|
||
podcast_subscriptions: subscriptions,
|
||
podcast_progress: progress,
|
||
podcast_listen_sessions: vec![session()],
|
||
..SyncSnapshot::default()
|
||
};
|
||
let section_bytes = |snapshot: &SyncSnapshot| -> usize {
|
||
fn sum<T: Serialize>(items: &[T]) -> usize {
|
||
items
|
||
.iter()
|
||
.map(|item| serde_json::to_vec(item).unwrap().len() + 1)
|
||
.sum()
|
||
}
|
||
sum(&snapshot.podcast_subscriptions)
|
||
+ sum(&snapshot.podcast_shares)
|
||
+ sum(&snapshot.podcast_progress)
|
||
+ sum(&snapshot.podcast_listen_sessions)
|
||
};
|
||
let mut snapshot = original.clone();
|
||
snapshot.bound_podcast_state();
|
||
assert!(section_bytes(&snapshot) <= MAX_PODCAST_SNAPSHOT_BYTES);
|
||
assert!(
|
||
snapshot
|
||
.podcast_subscriptions
|
||
.iter()
|
||
.all(|record| record.podcast.description.is_none()),
|
||
"descriptions are refreshed from RSS, not snapshotted"
|
||
);
|
||
assert!(snapshot.podcast_subscriptions.len() < MAX_SNAPSHOT_SUBSCRIPTIONS);
|
||
assert!(!snapshot.podcast_subscriptions.is_empty());
|
||
// Subscriptions cannot crowd out progress and sessions.
|
||
assert_eq!(snapshot.podcast_progress.len(), 10);
|
||
assert_eq!(snapshot.podcast_listen_sessions.len(), 1);
|
||
assert!(serde_json::to_vec(&snapshot).unwrap().len() < MAX_SYNC_LINE);
|
||
|
||
// A smaller budget, for a message whose other parts are large.
|
||
let budget = podcast_snapshot_budget(6 * 1024 * 1024);
|
||
assert!(budget < MAX_PODCAST_SNAPSHOT_BYTES);
|
||
let mut small = original;
|
||
small.bound_podcast_state_to(budget);
|
||
assert!(section_bytes(&small) <= budget);
|
||
assert_eq!(small.podcast_progress.len(), 10);
|
||
assert_eq!(podcast_snapshot_budget(0), MAX_PODCAST_SNAPSHOT_BYTES);
|
||
assert_eq!(podcast_snapshot_budget(MAX_SYNC_LINE), 0);
|
||
}
|
||
}
|
||
}
|