Skip to main content

jmap_types/
push.rs

1//! RFC 8620 §7 push wire types: [`StateChange`], [`PushSubscription`],
2//! [`PushKeys`], and [`PushVerification`], plus the RFC 8030 §5.3 Web Push
3//! [`Urgency`].
4//!
5//! These are shared by servers (which build and send them) and clients
6//! (which receive them over SSE, WebSocket, or a push endpoint).
7//!
8//! # The `@type` discriminant
9//!
10//! [`StateChange`] and [`PushVerification`] carry an `@type` property that
11//! "MUST be the string" naming the object (RFC 8620 §7.1, §7.2.2). Their
12//! (De)Serialize impls are hand-written rather than derived: serialize always
13//! emits the `@type` string; deserialize consumes it, rejects any other value,
14//! and never leaves it in `extra`. An absent `@type` is accepted, because a
15//! receiver that dispatched on `@type` (or on an SSE event name) has already
16//! established what the object is.
17
18use std::collections::BTreeMap;
19use std::fmt;
20
21use serde::de::DeserializeOwned;
22use serde::ser::SerializeMap;
23use serde::{Deserialize, Deserializer, Serialize, Serializer};
24
25use crate::id::{Id, State, UTCDate};
26
27/// The Web Push `Urgency` header (RFC 8030 §5.3), shared by every crate
28/// that sends or classifies a push: `urgency-option = ("very-low" / "low"
29/// / "normal" / "high")`. Variants order "in order of increasing
30/// urgency", so `max` picks the most urgent. "A push message without the
31/// Urgency header field defaults to a value of "normal"."
32#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
33pub enum Urgency {
34    /// `very-low`
35    VeryLow,
36    /// `low`
37    Low,
38    /// `normal`, the default when the header is absent.
39    Normal,
40    /// `high`
41    High,
42}
43
44impl Urgency {
45    /// The header value.
46    pub const fn as_str(self) -> &'static str {
47        match self {
48            Self::VeryLow => "very-low",
49            Self::Low => "low",
50            Self::Normal => "normal",
51            Self::High => "high",
52        }
53    }
54}
55
56impl Serialize for Urgency {
57    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
58        serializer.serialize_str(self.as_str())
59    }
60}
61
62/// Accepts only the four `urgency-option` strings: RFC 8030 §5.3 closes
63/// the set, so any other string is an error rather than an `Other` value.
64impl<'de> Deserialize<'de> for Urgency {
65    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
66        const VARIANTS: &[&str] = &["very-low", "low", "normal", "high"];
67        let s = String::deserialize(deserializer)?;
68        match s.as_str() {
69            "very-low" => Ok(Self::VeryLow),
70            "low" => Ok(Self::Low),
71            "normal" => Ok(Self::Normal),
72            "high" => Ok(Self::High),
73            other => Err(serde::de::Error::unknown_variant(other, VARIANTS)),
74        }
75    }
76}
77
78/// `@type` value of a [`StateChange`] (RFC 8620 §7.1).
79const STATE_CHANGE_TYPE: &str = "StateChange";
80
81/// `@type` value of a [`PushVerification`] (RFC 8620 §7.2.2).
82const PUSH_VERIFICATION_TYPE: &str = "PushVerification";
83
84/// Placeholder printed by the `Debug` impls in place of secret values.
85const REDACTED: &str = "[REDACTED]";
86
87/// A state change push notification (RFC 8620 §7.1).
88///
89/// Sent by the server over SSE, WebSocket, or to a [`PushSubscription`] URL.
90/// The wire form always carries `"@type": "StateChange"` (RFC 8620 §7.1):
91/// serialize always emits it; deserialize rejects any other value, accepts
92/// its absence and never leaves it in `extra`.
93///
94/// # `extra` equality is feature-flag-dependent (bd:JMAP-6r7c.43)
95///
96/// The derived `PartialEq` / `Eq` impl compares `extra` as a
97/// `serde_json::Map`, which is order-insensitive under the workspace default
98/// (BTreeMap-backed) and order-sensitive if any crate in the dependency graph
99/// enables `serde_json/preserve_order`.
100#[non_exhaustive]
101#[derive(Debug, Clone, PartialEq, Eq)]
102pub struct StateChange {
103    /// For each account that changed: maps data-type name to the new [`State`] token.
104    ///
105    /// Outer key: account [`Id`].  Inner key: JMAP data-type name (e.g. `"Email"`).
106    /// Inner value: new opaque state string; pass to `Email/changes` etc. as `sinceState`.
107    pub changed: BTreeMap<Id, BTreeMap<String, State>>,
108
109    /// Catch-all for vendor / site / private extension fields not covered
110    /// by the typed fields above. Preserves unknown fields across
111    /// deserialize/serialize round-trip per workspace extras-preservation
112    /// policy (see workspace AGENTS.md). Never contains `@type`.
113    pub extra: serde_json::Map<String, serde_json::Value>,
114}
115
116impl StateChange {
117    /// A `StateChange` with the given `changed` map and no extension fields.
118    pub fn new(changed: BTreeMap<Id, BTreeMap<String, State>>) -> Self {
119        Self {
120            changed,
121            extra: serde_json::Map::new(),
122        }
123    }
124}
125
126impl Serialize for StateChange {
127    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
128        let mut map = s.serialize_map(None)?;
129        map.serialize_entry("@type", STATE_CHANGE_TYPE)?;
130        map.serialize_entry("changed", &self.changed)?;
131        for (k, v) in &self.extra {
132            map.serialize_entry(k, v)?;
133        }
134        map.end()
135    }
136}
137
138impl<'de> Deserialize<'de> for StateChange {
139    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
140        let mut extra = serde_json::Map::deserialize(d)?;
141        take_type(&mut extra, STATE_CHANGE_TYPE)?;
142        let changed = take_field(&mut extra, "changed")?;
143        Ok(StateChange { changed, extra })
144    }
145}
146
147/// A push subscription (RFC 8620 §7.2).
148///
149/// Every property other than `deviceClientId` is optional here because the
150/// same type carries a create request (no `id`, `verificationCode` or
151/// `expires`), a `PushSubscription/get` result (`url` and `keys` are never
152/// returned, RFC 8620 §7.2.1), and the server's stored record. `None` fields
153/// are omitted on serialize; a JSON `null` deserializes to `None`.
154///
155/// Extension properties, such as `chatPush` from
156/// draft-atwood-jmap-chat-push-00, are carried in [`extra`](Self::extra).
157///
158/// The `Debug` impl redacts `url`, `keys.auth` and `verificationCode`.
159#[non_exhaustive]
160#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
161#[serde(rename_all = "camelCase")]
162pub struct PushSubscription {
163    /// The `id` property: server-set and immutable.
164    #[serde(default, skip_serializing_if = "Option::is_none")]
165    pub id: Option<Id>,
166    /// The `deviceClientId` property: identifies the client and device.
167    pub device_client_id: String,
168    /// The `url` property: absolute URL the server POSTs pushes to. The RFC
169    /// requires it to begin with `"https://"`; this type does not check that.
170    #[serde(default, skip_serializing_if = "Option::is_none")]
171    pub url: Option<String>,
172    /// The `keys` property: RFC 8291 encryption keys, or `None` for none.
173    #[serde(default, skip_serializing_if = "Option::is_none")]
174    pub keys: Option<PushKeys>,
175    /// The `verificationCode` property: `None` until the client echoes the
176    /// code from the [`PushVerification`].
177    #[serde(default, skip_serializing_if = "Option::is_none")]
178    pub verification_code: Option<String>,
179    /// The `expires` property: the server sends nothing after this time.
180    #[serde(default, skip_serializing_if = "Option::is_none")]
181    pub expires: Option<UTCDate>,
182    /// The `types` property: data types to push; `None` means all types.
183    #[serde(default, skip_serializing_if = "Option::is_none")]
184    pub types: Option<Vec<String>>,
185    /// Catch-all for extension properties (e.g. `chatPush`) and vendor /
186    /// site / private fields not covered by the typed fields above, per
187    /// workspace extras-preservation policy (see workspace AGENTS.md).
188    #[serde(flatten, default, skip_serializing_if = "serde_json::Map::is_empty")]
189    pub extra: serde_json::Map<String, serde_json::Value>,
190}
191
192impl fmt::Debug for PushSubscription {
193    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
194        f.debug_struct("PushSubscription")
195            .field("id", &self.id)
196            .field("device_client_id", &self.device_client_id)
197            .field("url", &self.url.as_ref().map(|_| REDACTED))
198            .field("keys", &self.keys)
199            .field(
200                "verification_code",
201                &self.verification_code.as_ref().map(|_| REDACTED),
202            )
203            .field("expires", &self.expires)
204            .field("types", &self.types)
205            .field("extra", &self.extra)
206            .finish()
207    }
208}
209
210/// `PushSubscription` has no property selector enum; `PushSubscription/get`
211/// takes property names directly.
212impl crate::JmapObject for PushSubscription {
213    const TYPE_NAME: &'static str = "PushSubscription";
214    type Property = ();
215}
216
217/// Property attributes from RFC 8620 §7.2 (rfc8620.txt:3593, 3597, 3618,
218/// 3623): `id` is "(immutable; server-set)"; `deviceClientId`, `url` and
219/// `keys` are "(immutable)"; `verificationCode`, `expires` and `types`
220/// carry no attribute.
221impl crate::SetObject for PushSubscription {
222    type Patch = crate::PatchObject;
223    const SERVER_SET: &'static [&'static str] = &["id"];
224    const CLIENT_SETTABLE: &'static [&'static str] = &[
225        "deviceClientId",
226        "url",
227        "keys",
228        "verificationCode",
229        "expires",
230        "types",
231    ];
232    const IMMUTABLE: &'static [&'static str] = &["deviceClientId", "url", "keys"];
233}
234
235/// The `keys` object of a [`PushSubscription`] (RFC 8620 §7.2).
236///
237/// "The object MUST have the following properties: p256dh ... auth", so both
238/// are required on deserialize. The `Debug` impl redacts `auth`.
239#[non_exhaustive]
240#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
241pub struct PushKeys {
242    /// The `p256dh` property: the client's P-256 ECDH public key (RFC 8291),
243    /// URL-safe base64.
244    pub p256dh: String,
245    /// The `auth` property: the RFC 8291 authentication secret, URL-safe
246    /// base64.
247    pub auth: String,
248    /// Catch-all for vendor / site / private extension fields, per
249    /// workspace extras-preservation policy (see workspace AGENTS.md).
250    #[serde(flatten, default, skip_serializing_if = "serde_json::Map::is_empty")]
251    pub extra: serde_json::Map<String, serde_json::Value>,
252}
253
254impl fmt::Debug for PushKeys {
255    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
256        f.debug_struct("PushKeys")
257            .field("p256dh", &self.p256dh)
258            .field("auth", &REDACTED)
259            .field("extra", &self.extra)
260            .finish()
261    }
262}
263
264/// The object pushed to a new subscription's URL (RFC 8620 §7.2.2).
265///
266/// The wire form always carries `"@type": "PushVerification"` (RFC 8620
267/// §7.2.2): serialize always emits it; deserialize rejects any other value,
268/// accepts its absence and never leaves it in `extra`. The `Debug` impl
269/// redacts `verificationCode`.
270#[non_exhaustive]
271#[derive(Clone, PartialEq, Eq)]
272pub struct PushVerification {
273    /// The `pushSubscriptionId` property: the id of the new subscription.
274    ///
275    /// RFC 8620 §7.2.2 types this property as `String`; RFC 8620 erratum
276    /// 9268 (<https://www.rfc-editor.org/errata/eid9268>, reported, not yet
277    /// verified) corrects it to `Id`, matching the PushSubscription `id` it
278    /// names. It is an [`Id`], so deserializing a value outside the RFC 8620
279    /// §1.2 `Id` syntax fails.
280    pub push_subscription_id: Id,
281    /// The `verificationCode` property: the code the client must set on the
282    /// subscription before the server sends it anything else.
283    pub verification_code: String,
284    /// Catch-all for vendor / site / private extension fields, per
285    /// workspace extras-preservation policy (see workspace AGENTS.md).
286    /// Never contains `@type`.
287    pub extra: serde_json::Map<String, serde_json::Value>,
288}
289
290impl PushVerification {
291    /// A PushVerification for subscription `push_subscription_id` carrying
292    /// `verification_code`, with no extension fields.
293    pub fn new(push_subscription_id: Id, verification_code: impl Into<String>) -> Self {
294        Self {
295            push_subscription_id,
296            verification_code: verification_code.into(),
297            extra: serde_json::Map::new(),
298        }
299    }
300}
301
302impl fmt::Debug for PushVerification {
303    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
304        f.debug_struct("PushVerification")
305            .field("push_subscription_id", &self.push_subscription_id)
306            .field("verification_code", &REDACTED)
307            .field("extra", &self.extra)
308            .finish()
309    }
310}
311
312impl Serialize for PushVerification {
313    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
314        let mut map = s.serialize_map(None)?;
315        map.serialize_entry("@type", PUSH_VERIFICATION_TYPE)?;
316        map.serialize_entry("pushSubscriptionId", &self.push_subscription_id)?;
317        map.serialize_entry("verificationCode", &self.verification_code)?;
318        for (k, v) in &self.extra {
319            map.serialize_entry(k, v)?;
320        }
321        map.end()
322    }
323}
324
325impl<'de> Deserialize<'de> for PushVerification {
326    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
327        let mut extra = serde_json::Map::deserialize(d)?;
328        take_type(&mut extra, PUSH_VERIFICATION_TYPE)?;
329        let push_subscription_id = take_field(&mut extra, "pushSubscriptionId")?;
330        let verification_code = take_field(&mut extra, "verificationCode")?;
331        Ok(PushVerification {
332            push_subscription_id,
333            verification_code,
334            extra,
335        })
336    }
337}
338
339/// Removes `@type` from `map`, failing if it is present and not `expected`.
340fn take_type<E: serde::de::Error>(
341    map: &mut serde_json::Map<String, serde_json::Value>,
342    expected: &str,
343) -> Result<(), E> {
344    match map.remove("@type") {
345        None => Ok(()),
346        Some(serde_json::Value::String(s)) if s == expected => Ok(()),
347        Some(serde_json::Value::String(_)) => {
348            Err(E::custom(format!("@type must be \"{expected}\"")))
349        }
350        Some(other) => Err(E::custom(format!(
351            "@type must be a string, found {}",
352            crate::json_type_name(&other)
353        ))),
354    }
355}
356
357/// Removes the required property `key` from `map` and deserializes it.
358fn take_field<T: DeserializeOwned, E: serde::de::Error>(
359    map: &mut serde_json::Map<String, serde_json::Value>,
360    key: &'static str,
361) -> Result<T, E> {
362    let value = map.remove(key).ok_or_else(|| E::missing_field(key))?;
363    serde_json::from_value(value).map_err(E::custom)
364}
365
366#[cfg(test)]
367mod tests {
368    use super::*;
369
370    /// Oracle: hand-written JSON whose `@type` carries a canary. RFC 8620
371    /// §3.6.1 makes an error `description` "unstructured English text
372    /// suitable for displaying to a developer", so the client value must not
373    /// be echoed; only its JSON type (RFC 8259 §3 "object") is named.
374    #[test]
375    fn push_verification_type_error_does_not_echo_value() {
376        for (raw, want) in [
377            (
378                r#"{"@type":{"note":"CANARY-kwqn"},"pushSubscriptionId":"p","verificationCode":"c"}"#,
379                "@type must be a string, found object",
380            ),
381            (
382                r#"{"@type":"CANARY-kwqn","pushSubscriptionId":"p","verificationCode":"c"}"#,
383                "@type must be \"PushVerification\"",
384            ),
385        ] {
386            let err = serde_json::from_str::<PushVerification>(raw)
387                .unwrap_err()
388                .to_string();
389            assert!(!err.contains("CANARY-kwqn"), "{err}");
390            assert!(err.contains(want), "{err}");
391        }
392    }
393
394    /// Every `PushSubscription` property RFC 8620 §7.2 defines is classified
395    /// once. The struct literal makes a new field a compile error here.
396    #[test]
397    fn push_subscription_properties_are_classified() {
398        let sub = PushSubscription {
399            id: Some(Id::from("ps1")),
400            device_client_id: "dev".into(),
401            url: Some("https://push.example.com/x".into()),
402            keys: Some(PushKeys {
403                p256dh: "p".into(),
404                auth: "a".into(),
405                extra: serde_json::Map::new(),
406            }),
407            verification_code: Some("code".into()),
408            expires: Some(UTCDate::from("2026-01-01T00:00:00Z")),
409            types: Some(vec!["Email".into()]),
410            extra: serde_json::Map::new(),
411        };
412        assert_eq!(crate::check_property_classification(&sub), Ok(()));
413    }
414    use serde_json::json;
415
416    /// `StateChange.extra` captures unknown fields on deserialize and
417    /// flattens them on serialize (round-trip).
418    #[test]
419    fn state_change_preserves_vendor_extras() {
420        let raw = json!({
421            "changed": {
422                "acc1": { "Email": "s42" }
423            },
424            "acmeCorpSequence": 17
425        });
426        let obj: StateChange = serde_json::from_value(raw).expect("StateChange must deserialize");
427        assert_eq!(
428            obj.extra.get("acmeCorpSequence").and_then(|v| v.as_u64()),
429            Some(17)
430        );
431
432        // Round-trip: serializing back must reproduce the vendor field.
433        let v = serde_json::to_value(&obj).expect("StateChange must serialize");
434        assert_eq!(v["acmeCorpSequence"], json!(17));
435    }
436
437    /// bd:JMAP-6r7c.43 — regression-guard for the workspace's
438    /// serde_json/preserve_order posture. Two StateChange values with the
439    /// same `extra` keys inserted in different orders MUST compare equal
440    /// under the workspace's default configuration (BTreeMap-backed
441    /// serde_json::Map). If a future Cargo.lock or workspace-level feature
442    /// change accidentally enables `preserve_order`, this assertion fails
443    /// loudly and surfaces the SemVer-policy break before downstream
444    /// consumers hit silently-different equality semantics.
445    ///
446    /// Both values are deserialized from JSON (the wire path) so the test
447    /// exercises the same construction code path consumers use.
448    #[test]
449    fn extra_equality_is_order_insensitive_under_workspace_flags() {
450        // Two equivalent JSON payloads with different key-insertion orders
451        // for the vendor extras. Under BTreeMap-backed Map the keys are
452        // re-sorted lexicographically on deserialize, so the resulting
453        // structures compare equal.
454        let raw_a = json!({
455            "changed": {"acc1": {"Email": "s1"}},
456            "vendorA": 1,
457            "vendorB": 2
458        });
459        let raw_b = json!({
460            "changed": {"acc1": {"Email": "s1"}},
461            "vendorB": 2,
462            "vendorA": 1
463        });
464
465        let a: StateChange = serde_json::from_value(raw_a).expect("a must deserialize");
466        let b: StateChange = serde_json::from_value(raw_b).expect("b must deserialize");
467
468        assert_eq!(
469            a, b,
470            "extra-map equality is order-insensitive under the workspace's \
471             default serde_json::Map (BTreeMap-backed); if this fails, \
472             check whether preserve_order has been enabled in the dep graph"
473        );
474    }
475
476    /// Oracle: RFC 8030 §5.3 grammar `urgency-option = ("very-low" / "low"
477    /// / "normal" / "high")`, listed "In order of increasing urgency".
478    #[test]
479    fn urgency_wire_values_in_increasing_order() {
480        let ordered = [
481            Urgency::VeryLow,
482            Urgency::Low,
483            Urgency::Normal,
484            Urgency::High,
485        ];
486        let wire: Vec<&str> = ordered.iter().map(|u| u.as_str()).collect();
487        assert_eq!(wire, ["very-low", "low", "normal", "high"]);
488        assert!(ordered.windows(2).all(|w| w[0] < w[1]));
489    }
490
491    /// Oracle: RFC 8030 §5.3 `urgency-option = ("very-low" / "low" /
492    /// "normal" / "high")`. Each string round-trips as a JSON string; a
493    /// string outside the grammar, or another case, is rejected.
494    #[test]
495    fn urgency_serde_accepts_only_rfc8030_values() {
496        for (wire, urgency) in [
497            ("very-low", Urgency::VeryLow),
498            ("low", Urgency::Low),
499            ("normal", Urgency::Normal),
500            ("high", Urgency::High),
501        ] {
502            let parsed: Urgency = serde_json::from_value(json!(wire)).expect(wire);
503            assert_eq!(parsed, urgency);
504            assert_eq!(serde_json::to_value(urgency).expect(wire), json!(wire));
505        }
506        for bad in ["urgent", "High", "very_low", ""] {
507            assert!(
508                serde_json::from_value::<Urgency>(json!(bad)).is_err(),
509                "{bad:?}"
510            );
511        }
512    }
513}