Skip to main content

weirdnet_push/
api.rs

1//! The push service's HTTP API (JSON).
2//!
3//! | Method and path | Body | Answer |
4//! | --- | --- | --- |
5//! | `POST /v1/register` | [`Register`] | [`Registered`] |
6//! | `POST /v1/rotate` | [`Control`] | [`Registered`] (the old handle is revoked) |
7//! | `POST /v1/unregister` | [`Control`] | 204 |
8//! | `POST /v1/wake` | [`WakeRequest`] | 202, or 410 if the handle is unknown or revoked |
9//! | `GET /v1/relay/announcements` | bearer relay token | NDJSON stream of [`Announcement`] |
10//! | `GET /v1/health` | | 200 `ok` |
11
12use crate::handle::{ControlSecret, WakeHandle};
13use crate::wake::Payload96;
14use serde::{Deserialize, Serialize};
15
16/// How the service reaches a device.
17#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
18#[serde(rename_all = "snake_case")]
19pub enum Transport {
20    /// Apple Push Notification service (iOS; required for background wake there).
21    Apns {
22        /// The APNs device token, hex.
23        token: String,
24        /// The app's bundle id (the APNs topic).
25        topic: String,
26        /// Use the APNs development environment.
27        #[serde(default)]
28        sandbox: bool,
29    },
30    /// Firebase Cloud Messaging (Android Play builds).
31    Fcm {
32        /// The FCM registration token.
33        token: String,
34    },
35    /// Wake announcements carried by Weirdnet relays (opt-in; F-Droid and builds without
36    /// Google services). The device's home relay delivers over the connection it keeps.
37    Relay,
38}
39
40impl Transport {
41    /// "apns", "fcm" or "relay".
42    pub fn kind(&self) -> &'static str {
43        match self {
44            Transport::Apns { .. } => "apns",
45            Transport::Fcm { .. } => "fcm",
46            Transport::Relay => "relay",
47        }
48    }
49}
50
51/// `POST /v1/register`.
52#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
53pub struct Register {
54    /// How to reach the device.
55    pub transport: Transport,
56}
57
58/// A new handle and its control secret.
59#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
60pub struct Registered {
61    /// Share (sealed) with the home relay and trusted peers.
62    pub handle: WakeHandle,
63    /// Keep on the device.
64    pub control: ControlSecret,
65}
66
67/// `POST /v1/rotate` and `POST /v1/unregister`.
68#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
69pub struct Control {
70    /// The handle.
71    pub handle: WakeHandle,
72    /// Its control secret.
73    pub control: ControlSecret,
74    /// For rotate: a new transport (such as a refreshed APNs token); `None` keeps it.
75    #[serde(default, skip_serializing_if = "Option::is_none")]
76    pub transport: Option<Transport>,
77}
78
79/// `POST /v1/wake`.
80#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
81pub struct WakeRequest {
82    /// Whom to wake.
83    pub handle: WakeHandle,
84    /// The sealed payload.
85    pub payload: Payload96,
86}
87
88/// One line of `GET /v1/relay/announcements`.
89#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
90pub struct Announcement {
91    /// The handle the device told its home relay.
92    pub handle: WakeHandle,
93    /// The sealed payload to pass on.
94    pub payload: Payload96,
95}
96
97/// An error body.
98#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
99pub struct ErrorBody {
100    /// What went wrong.
101    pub error: String,
102}