Skip to main content

weirdnet_push/
relaywake.rs

1//! The relay wake path: the wire protocol between a device, its home relay and senders.
2//!
3//! For builds without APNs or FCM (F-Droid, sideloaded Android), the device opts in to keep
4//! a stream of [`PROTOCOL`] open to its home relay (on Android, from a foreground service)
5//! and subscribes with its wake handles. Wakes reach the relay in two ways:
6//!
7//! - a sender (a trusted peer that holds the device's [`crate::WakeCard`]) opens a stream to
8//!   the relay and sends [`ToRelay::Deliver`];
9//! - the relay follows a push service's announcements
10//!   ([`crate::PushClient::announcements`]) for devices that registered
11//!   [`crate::api::Transport::Relay`] there, so wakes originating from WeirdBrains reach
12//!   devices behind NAT.
13//!
14//! The relay passes the sealed payload on unchanged ([`FromRelay::Wake`]); only the device
15//! can open it. Frames are JSON, each after a 2-byte big-endian length, at most
16//! [`MAX_FRAME`] bytes. This module is transport-neutral: it works on any
17//! `futures` `AsyncRead + AsyncWrite`, such as a `weirdnet-net` stream.
18
19use crate::error::{Error, Result};
20use crate::handle::WakeHandle;
21use crate::wake::Payload96;
22use futures_util::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
23use serde::{Deserialize, Serialize};
24
25/// The stream protocol id.
26pub const PROTOCOL: &str = "/weirdnet/wake/1";
27/// The largest frame.
28pub const MAX_FRAME: usize = 2048;
29/// The most handles one subscription may carry.
30pub const MAX_HANDLES: usize = 8;
31
32/// From a device or sender to the relay. The first frame of a stream decides its kind.
33#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
34#[serde(rename_all = "snake_case", tag = "t")]
35pub enum ToRelay {
36    /// A device: deliver wakes for these handles on this stream while it stays open.
37    Subscribe {
38        /// At most [`MAX_HANDLES`].
39        handles: Vec<WakeHandle>,
40    },
41    /// A sender: pass this payload on to the device with this handle.
42    Deliver {
43        /// Whom.
44        handle: WakeHandle,
45        /// The sealed payload.
46        payload: Payload96,
47    },
48}
49
50/// What happened to a delivery.
51#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
52#[serde(rename_all = "snake_case")]
53pub enum Delivery {
54    /// Passed to a connected device.
55    Delivered,
56    /// The device was connected recently; it is held briefly for its reconnect.
57    Held,
58    /// No device with that handle is connected here.
59    Offline,
60    /// Too many wakes for this handle just now; dropped.
61    TooMany,
62}
63
64/// From the relay.
65#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
66#[serde(rename_all = "snake_case", tag = "t")]
67pub enum FromRelay {
68    /// The subscription is in place.
69    Subscribed {
70        /// How many handles.
71        handles: usize,
72        /// The relay sends [`FromRelay::Keepalive`] at least this often; treat twice this
73        /// without a frame as a lost connection and reconnect.
74        keepalive_s: u32,
75    },
76    /// A wake for one of the subscribed handles.
77    Wake {
78        /// Which handle.
79        handle: WakeHandle,
80        /// The sealed payload (open it with [`crate::PushKey::open`]).
81        payload: Payload96,
82    },
83    /// Nothing to say.
84    Keepalive,
85    /// The answer to [`ToRelay::Deliver`].
86    Delivered {
87        /// What happened.
88        status: Delivery,
89    },
90    /// The request was refused.
91    Error {
92        /// Why.
93        error: String,
94    },
95}
96
97/// Writes one frame.
98pub async fn write<W: AsyncWrite + Unpin, T: Serialize>(w: &mut W, msg: &T) -> Result<()> {
99    let body = serde_json::to_vec(msg).map_err(|e| Error::Invalid(e.to_string()))?;
100    if body.len() > MAX_FRAME {
101        return Err(Error::Invalid("frame too large".into()));
102    }
103    let mut b = (body.len() as u16).to_be_bytes().to_vec();
104    b.extend(body);
105    w.write_all(&b).await?;
106    w.flush().await?;
107    Ok(())
108}
109
110/// Reads one frame; `None` at a clean end of stream.
111pub async fn read<R: AsyncRead + Unpin, T: for<'de> Deserialize<'de>>(r: &mut R) -> Result<Option<T>> {
112    let mut len = [0u8; 2];
113    match r.read_exact(&mut len).await {
114        Ok(()) => {}
115        Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => return Ok(None),
116        Err(e) => return Err(e.into()),
117    }
118    let n = u16::from_be_bytes(len) as usize;
119    if n == 0 || n > MAX_FRAME {
120        return Err(Error::Invalid("bad frame length".into()));
121    }
122    let mut body = vec![0u8; n];
123    r.read_exact(&mut body).await?;
124    serde_json::from_slice(&body).map(Some).map_err(|e| Error::Invalid(format!("bad frame: {e}")))
125}
126
127/// A device's open subscription.
128pub struct Subscription<S> {
129    io: S,
130    /// The relay's keepalive interval.
131    pub keepalive_s: u32,
132}
133
134impl<S: AsyncRead + AsyncWrite + Unpin> Subscription<S> {
135    /// Subscribes `handles` on a fresh stream to the home relay.
136    pub async fn start(mut io: S, handles: &[WakeHandle]) -> Result<Self> {
137        if handles.is_empty() || handles.len() > MAX_HANDLES {
138            return Err(Error::Invalid(format!("subscribe 1 to {MAX_HANDLES} handles")));
139        }
140        write(&mut io, &ToRelay::Subscribe { handles: handles.to_vec() }).await?;
141        match read(&mut io).await? {
142            Some(FromRelay::Subscribed { keepalive_s, .. }) => Ok(Self { io, keepalive_s }),
143            Some(FromRelay::Error { error }) => Err(Error::Delivery(error)),
144            _ => Err(Error::Invalid("unexpected answer to subscribe".into())),
145        }
146    }
147
148    /// The next wake. Keepalives are skipped; `None` when the relay closed the stream. Wrap
149    /// it in a timeout of twice [`Subscription::keepalive_s`] to notice a dead connection.
150    pub async fn next(&mut self) -> Result<Option<(WakeHandle, Payload96)>> {
151        loop {
152            match read(&mut self.io).await? {
153                None => return Ok(None),
154                Some(FromRelay::Wake { handle, payload }) => return Ok(Some((handle, payload))),
155                Some(FromRelay::Keepalive) => continue,
156                Some(FromRelay::Error { error }) => return Err(Error::Delivery(error)),
157                Some(_) => return Err(Error::Invalid("unexpected frame".into())),
158            }
159        }
160    }
161
162    /// The next frame, keepalives included (to reset an idle timer on each).
163    pub async fn next_frame(&mut self) -> Result<Option<FromRelay>> {
164        read(&mut self.io).await
165    }
166}
167
168/// A sender: passes a sealed payload to the device's home relay over a fresh stream.
169pub async fn deliver<S: AsyncRead + AsyncWrite + Unpin>(mut io: S, handle: &WakeHandle, payload: Payload96) -> Result<Delivery> {
170    write(&mut io, &ToRelay::Deliver { handle: handle.clone(), payload }).await?;
171    let r = read(&mut io).await?;
172    let _ = io.close().await;
173    match r {
174        Some(FromRelay::Delivered { status }) => Ok(status),
175        Some(FromRelay::Error { error }) => Err(Error::Delivery(error)),
176        _ => Err(Error::Invalid("unexpected answer to deliver".into())),
177    }
178}
179
180#[cfg(test)]
181mod tests {
182    use super::*;
183
184    #[test]
185    fn frames_round_trip_and_are_bounded() {
186        futures_util::FutureExt::now_or_never(async {
187            let h = WakeHandle::generate();
188            let p = Payload96::from_slice(&[[1u8].as_slice(), &[7u8; 95]].concat()).unwrap();
189            let mut buf = Vec::new();
190            write(&mut buf, &ToRelay::Deliver { handle: h.clone(), payload: p }).await.unwrap();
191            write(&mut buf, &FromRelay::Keepalive).await.unwrap();
192            let mut r = futures_util::io::Cursor::new(buf);
193            assert_eq!(read::<_, ToRelay>(&mut r).await.unwrap(), Some(ToRelay::Deliver { handle: h, payload: p }));
194            assert_eq!(read::<_, FromRelay>(&mut r).await.unwrap(), Some(FromRelay::Keepalive));
195            assert_eq!(read::<_, FromRelay>(&mut r).await.unwrap(), None);
196            let mut big = futures_util::io::Cursor::new([0xffu8, 0xff].to_vec());
197            assert!(read::<_, FromRelay>(&mut big).await.is_err());
198            let mut zero = futures_util::io::Cursor::new([0u8, 0].to_vec());
199            assert!(read::<_, FromRelay>(&mut zero).await.is_err());
200            // A payload must be a valid version-1 payload of the exact size.
201            let bad = br#"{"t":"deliver","handle":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA","payload":"AA"}"#;
202            let mut b = (bad.len() as u16).to_be_bytes().to_vec();
203            b.extend(bad);
204            assert!(read::<_, ToRelay>(&mut futures_util::io::Cursor::new(b)).await.is_err());
205        })
206        .unwrap();
207    }
208}