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}