Skip to main content

nk_core/message/
mod.rs

1//! Client and relay wire messages —
2//! [NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md),
3//! [NIP-42](https://github.com/nostr-protocol/nips/blob/master/42.md),
4//! [NIP-45](https://github.com/nostr-protocol/nips/blob/master/45.md),
5//! [NIP-77](https://github.com/nostr-protocol/nips/blob/master/77.md).
6//!
7//! `to_json` writes the byte-exact wire form (filters and events go through
8//! the canonical writer); `from_json` validates subscription ids in both
9//! directions (1..=64 Unicode scalar values) and requires the `OK` event id
10//! to be 64 lowercase hex.
11
12mod client;
13mod count;
14mod relay;
15mod subscription;
16
17pub use client::ClientMessage;
18pub use count::{CountResult, Hll};
19pub use relay::RelayMessage;
20pub use subscription::SubscriptionId;
21
22use alloc::string::String;
23
24use serde::de::{Error as DeError, SeqAccess};
25
26use crate::json::JsonError;
27
28/// The result type for this module.
29pub type Result<T, E = Error> = core::result::Result<T, E>;
30
31/// Why a wire message could not be parsed.
32#[derive(Debug, thiserror::Error)]
33#[non_exhaustive]
34pub enum Error {
35    /// The wire text is not valid JSON.
36    #[error("invalid JSON")]
37    InvalidJson {
38        /// The serde parse failure.
39        #[source]
40        source: JsonError,
41    },
42    /// The wire value is not a non-empty JSON array whose first element is
43    /// the message type string.
44    #[error("message must be a non-empty JSON array")]
45    NotAMessageArray,
46    /// The message type string is not a known NIP-01/42/45/77 type.
47    #[error("unknown message type {ty}")]
48    UnknownType {
49        /// The unrecognized type string.
50        ty: String,
51    },
52    /// A known message type has the wrong arity or field types.
53    #[error("invalid {ty} message")]
54    InvalidMessage {
55        /// The message type (`EVENT`, `REQ`, `OK`, …).
56        ty: &'static str,
57    },
58    /// An embedded event or filter failed wire validation.
59    #[error("invalid {ty} payload")]
60    InvalidPayload {
61        /// The containing message type.
62        ty: &'static str,
63        /// The error describing the offending field.
64        #[source]
65        source: JsonError,
66    },
67    /// The subscription id length is outside `1..=64` scalar values.
68    #[error("subscription id length {len} is outside 1..=64")]
69    InvalidSubscriptionId {
70        /// The length in Unicode scalar values.
71        len: usize,
72    },
73    /// A NIP-45 sketch is not a 512-character hex string.
74    #[error("invalid NIP-45 HLL sketch: expected 512-char hex")]
75    InvalidHll,
76    /// The obsolete 5-element `NEG-OPEN` wire form.
77    #[error("obsolete 5-element NEG-OPEN; expected [NEG-OPEN, id, filter, hex]")]
78    ObsoleteNegOpen,
79    /// A NIP-77 negentropy message is not non-empty even-length hex.
80    #[error("invalid negentropy message: expected non-empty even-length hex")]
81    InvalidNegMessage,
82    /// The caller-provided random source failed.
83    #[error("random source failed")]
84    Rng,
85}
86
87/// Reads the `["<TYPE>", ...]` head of a message seq; the first element
88/// must be a string naming a type in `known`.
89pub(crate) fn read_type<'de, A: SeqAccess<'de>>(
90    seq: &mut A,
91    known: &'static [&'static str],
92) -> Result<&'static str, A::Error> {
93    let label = seq
94        .next_element::<String>()?
95        .ok_or_else(|| DeError::custom(Error::NotAMessageArray))?;
96    known
97        .iter()
98        .copied()
99        .find(|known| *known == label)
100        .ok_or_else(|| DeError::custom(Error::UnknownType { ty: label.clone() }))
101}
102
103/// A non-empty, even-length lowercase hex string.
104pub(crate) fn parse_neg_hex(raw: &str) -> Result<String, Error> {
105    if raw.is_empty()
106        || !raw.len().is_multiple_of(2)
107        || !raw
108            .bytes()
109            .all(|b| b.is_ascii_hexdigit() && !b.is_ascii_uppercase())
110    {
111        return Err(Error::InvalidNegMessage);
112    }
113    Ok(String::from(raw))
114}
115
116/// Reads a subscription id element; the element must be a string.
117pub(crate) fn sub_id<'de, A: SeqAccess<'de>>(
118    seq: &mut A,
119    ty: &'static str,
120) -> Result<SubscriptionId, A::Error> {
121    seq.next_element::<SubscriptionId>()?
122        .ok_or_else(|| DeError::custom(Error::InvalidMessage { ty }))
123}
124
125/// Reads a string element; the element must be a string.
126pub(crate) fn string_item<'de, A: SeqAccess<'de>>(
127    seq: &mut A,
128    ty: &'static str,
129) -> Result<String, A::Error> {
130    seq.next_element::<String>()?
131        .ok_or_else(|| DeError::custom(Error::InvalidMessage { ty }))
132}
133
134/// Reads an event element.
135pub(crate) fn event_item<'de, A: SeqAccess<'de>>(
136    seq: &mut A,
137    ty: &'static str,
138) -> Result<crate::event::Event, A::Error> {
139    seq.next_element::<crate::event::Event>()?
140        .ok_or_else(|| DeError::custom(Error::InvalidMessage { ty }))
141}
142
143/// Reads a filter element.
144pub(crate) fn filter_item<'de, A: SeqAccess<'de>>(
145    seq: &mut A,
146    ty: &'static str,
147) -> Result<crate::filter::Filter, A::Error> {
148    seq.next_element::<crate::filter::Filter>()?
149        .ok_or_else(|| DeError::custom(Error::InvalidMessage { ty }))
150}
151
152/// Expects the seq to be exhausted.
153pub(crate) fn end<'de, A: SeqAccess<'de>>(seq: &mut A, ty: &'static str) -> Result<(), A::Error> {
154    if seq.next_element::<serde::de::IgnoredAny>()?.is_some() {
155        return Err(DeError::custom(Error::InvalidMessage { ty }));
156    }
157    Ok(())
158}
159
160#[cfg(test)]
161mod tests {
162    #![allow(clippy::unwrap_used, clippy::panic, reason = "tests fail by panicking")]
163
164    use alloc::borrow::Cow;
165    use alloc::string::ToString;
166    use core::str::FromStr;
167
168    use super::*;
169    use crate::event::{Event, Kind};
170    use crate::filter::Filter;
171
172    fn signed_event() -> Event {
173        let keys =
174            crate::key::Keys::new(crate::key::SecretKey::from_bytes([3; 32]).expect("scalar"));
175        let unsigned = crate::event::UnsignedEvent::new(
176            keys.public_key(),
177            crate::time::Timestamp::from_secs(1_700_000_000),
178            Kind::TEXT_NOTE,
179            crate::event::Tags::new(),
180            "gm",
181        );
182        crate::testutil::sign_with_aux(&keys, unsigned, [1; 32])
183    }
184
185    #[test]
186    fn subscription_id_bounds_count_scalar_values() {
187        assert!(SubscriptionId::new("").is_err());
188        assert!(SubscriptionId::new("a").is_ok());
189        assert_eq!(
190            SubscriptionId::new("a".repeat(64))
191                .expect("64 chars")
192                .as_str()
193                .chars()
194                .count(),
195            64
196        );
197        assert!(SubscriptionId::new("a".repeat(65)).is_err());
198        // Astral characters count once each, not per UTF-16 unit.
199        assert!(SubscriptionId::new("\u{1F600}".repeat(64)).is_ok());
200        assert!(SubscriptionId::new("\u{1F600}".repeat(65)).is_err());
201        assert!(matches!(
202            SubscriptionId::new("x".repeat(65)).unwrap_err(),
203            Error::InvalidSubscriptionId { len: 65 }
204        ));
205    }
206
207    #[test]
208    fn subscription_id_traits_and_serde() {
209        let id = SubscriptionId::new("sub").expect("valid");
210        assert_eq!(id.to_string(), "sub");
211        assert_eq!(id.as_ref(), "sub");
212        assert_eq!(serde_json::to_string(&id).expect("ser"), "\"sub\"");
213        let back: SubscriptionId = serde_json::from_str("\"sub\"").expect("de");
214        assert_eq!(back, id);
215        assert!(serde_json::from_str::<SubscriptionId>("\"\"").is_err());
216        assert!(serde_json::from_str::<SubscriptionId>("123").is_err());
217    }
218
219    #[test]
220    fn subscription_id_from_rng_is_16_lower_hex() {
221        struct Zero;
222        impl rand_core::TryRng for Zero {
223            type Error = core::convert::Infallible;
224            fn try_next_u32(&mut self) -> Result<u32, Self::Error> {
225                Ok(0)
226            }
227            fn try_next_u64(&mut self) -> Result<u64, Self::Error> {
228                Ok(0)
229            }
230            fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Self::Error> {
231                dest.fill(0);
232                Ok(())
233            }
234        }
235        impl rand_core::TryCryptoRng for Zero {}
236        let id = SubscriptionId::from_rng(&mut Zero).expect("rng");
237        assert_eq!(id.as_str(), "0000000000000000");
238    }
239
240    #[test]
241    fn count_hll_zero_merge_and_hex() {
242        let mut a = Hll::zero();
243        assert_eq!(a.to_string(), "00".repeat(256));
244        let b = Hll::from_str(&"ab".repeat(256)).expect("lowercase parses");
245        a.merge(&b);
246        assert_eq!(a.to_string(), "ab".repeat(256));
247        // `from_str` is caller input — uppercase normalizes to lowercase.
248        assert_eq!(
249            Hll::from_str(&"AB".repeat(256)).unwrap().to_string(),
250            "ab".repeat(256)
251        );
252        assert!(Hll::from_str("ab").is_err());
253        assert!(Hll::from_str(&"zz".repeat(256)).is_err());
254        assert!(matches!(
255            Hll::from_str("ab").unwrap_err(),
256            Error::InvalidHll
257        ));
258    }
259
260    #[test]
261    fn client_encode_matches_ts() {
262        let id = SubscriptionId::new("sub").expect("id");
263        let filter = Filter::new().kinds([Kind::TEXT_NOTE]).expect("filter");
264        assert_eq!(
265            ClientMessage::Req {
266                subscription_id: Cow::Borrowed(&id),
267                filters: Cow::Borrowed(core::slice::from_ref(&filter)),
268            }
269            .to_json(),
270            "[\"REQ\",\"sub\",{\"kinds\":[1]}]"
271        );
272        // An empty filter slice encodes as `["REQ","sub"]` per the design table.
273        assert_eq!(
274            ClientMessage::Req {
275                subscription_id: Cow::Borrowed(&id),
276                filters: Cow::Borrowed(&[][..]),
277            }
278            .to_json(),
279            "[\"REQ\",\"sub\"]"
280        );
281        assert_eq!(
282            ClientMessage::Close(Cow::Borrowed(&id)).to_json(),
283            "[\"CLOSE\",\"sub\"]"
284        );
285        assert_eq!(
286            ClientMessage::NegMsg {
287                subscription_id: Cow::Borrowed(&id),
288                message: Cow::Borrowed("deadbeef"),
289            }
290            .to_json(),
291            "[\"NEG-MSG\",\"sub\",\"deadbeef\"]"
292        );
293        assert_eq!(
294            ClientMessage::NegClose(Cow::Borrowed(&id)).to_json(),
295            "[\"NEG-CLOSE\",\"sub\"]"
296        );
297        let event = signed_event();
298        let wire = ClientMessage::Event(Cow::Borrowed(&event)).to_json();
299        assert!(wire.starts_with("[\"EVENT\",{\"id\":\""));
300        // Round-trip: parse(encode(x)) reproduces an equivalent message.
301        assert_eq!(
302            ClientMessage::from_json(&wire).expect("parse"),
303            ClientMessage::Event(Cow::Owned(event))
304        );
305    }
306
307    #[test]
308    fn client_parse_rules() {
309        let event = signed_event();
310        let event_json = serde_json::to_string(&event).expect("ser");
311        assert!(matches!(
312            ClientMessage::from_json(&alloc::format!("[\"EVENT\",{event_json}]")).expect("event"),
313            ClientMessage::Event(_)
314        ));
315        for bad in [
316            "not json",
317            "{}",
318            "[]",
319            "[42]",
320            "[\"REQ\"]",
321            "[\"REQ\",\"sub\"]",
322            "[\"REQ\",1,{\"kinds\":[1]}]",
323            "[\"REQ\",\"sub\",42]",
324            "[\"REQ\",\"s\",{\"kinds\":[65536]}]",
325            "[\"NEG-OPEN\",\"s\",{\"kinds\":[1]}]",
326            "[\"NEG-OPEN\",\"s\",{\"kinds\":[1]},\"aabb\",\"extra\"]",
327            "[\"NEG-OPEN\",\"s\",{\"kinds\":[1]},\"abc\"]",
328            "[\"NEG-OPEN\",\"s\",{\"kinds\":[1]},\"zz\"]",
329            "[\"NEG-MSG\",\"s\",\"\"]",
330            "[\"NEG-MSG\",\"s\",\"a\"]",
331            "[\"UNKNOWN\",\"s\"]",
332            "[\"CLOSE\",\"\"]",
333            "[\"CLOSE\",\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"]",
334        ] {
335            assert!(ClientMessage::from_json(bad).is_err(), "{bad}");
336        }
337        // Uppercase NEG hex is invalid protocol text.
338        assert!(ClientMessage::from_json("[\"NEG-MSG\",\"s\",\"FF00\"]").is_err());
339        let ClientMessage::NegMsg { message, .. } =
340            ClientMessage::from_json("[\"NEG-MSG\",\"s\",\"ff00\"]").expect("neg-msg")
341        else {
342            panic!("expected NegMsg");
343        };
344        assert_eq!(message.as_ref(), "ff00");
345    }
346
347    #[test]
348    fn relay_parse_rules() {
349        let event = signed_event();
350        let event_json = serde_json::to_string(&event).expect("ser");
351        let ok = RelayMessage::from_json(&alloc::format!(
352            "[\"OK\",\"{}\",true,\"saved\"]",
353            event.id().to_hex()
354        ))
355        .expect("ok");
356        assert!(matches!(ok, RelayMessage::Ok { accepted: true, .. }));
357        // Ruling 5: uppercase or short ids are rejected.
358        for bad in [
359            "not json",
360            "[\"OK\",\"id\",true,\"\"]",
361            "[\"OK\",\"AAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",true,\"\"]",
362            "[\"OK\",\"aaaa\",true,\"\"]",
363            "[\"EOSE\",\"\"]",
364            "[\"EVENT\",\"s\",{}]",
365            "[\"COUNT\",\"s\",{\"count\":-1}]",
366            "[\"COUNT\",\"s\",{\"count\":1.5}]",
367            "[\"COUNT\",\"s\",\"x\"]",
368            "[\"NEG-ERR\",\"s\"]",
369        ] {
370            assert!(RelayMessage::from_json(bad).is_err(), "{bad}");
371        }
372        let relay_event =
373            RelayMessage::from_json(&alloc::format!("[\"EVENT\",\"s\",{event_json}]"))
374                .expect("event");
375        assert!(matches!(relay_event, RelayMessage::Event { .. }));
376    }
377
378    #[test]
379    fn relay_count_result_parsing() {
380        // approximate/hll wrong types are ignored, not errors; an
381        // uppercase hll is invalid protocol text — the field drops.
382        let RelayMessage::Count { result, .. } = RelayMessage::from_json(
383            "[\"COUNT\",\"s\",{\"count\":7,\"approximate\":\"yes\",\"hll\":\"zz\"}]",
384        )
385        .expect("count") else {
386            panic!("expected Count");
387        };
388        assert_eq!(
389            result,
390            CountResult {
391                count: 7,
392                approximate: None,
393                hll: None,
394            }
395        );
396        let RelayMessage::Count {
397            result: max_result, ..
398        } = RelayMessage::from_json(&alloc::format!(
399            "[\"COUNT\",\"s\",{{\"count\":{},\"approximate\":true,\"hll\":\"{}\"}}]",
400            9_007_199_254_740_991u64,
401            "ab".repeat(256)
402        ))
403        .expect("max safe")
404        else {
405            panic!("expected Count");
406        };
407        assert_eq!(max_result.count, 9_007_199_254_740_991);
408        assert_eq!(max_result.approximate, Some(true));
409        assert_eq!(max_result.hll.expect("hll").to_string(), "ab".repeat(256));
410        // 2^53 is rejected.
411        assert!(RelayMessage::from_json("[\"COUNT\",\"s\",{\"count\":9007199254740992}]").is_err());
412    }
413
414    #[test]
415    fn relay_encode_matches_ts() {
416        let id = SubscriptionId::new("sub").expect("id");
417        let event = signed_event();
418        assert_eq!(
419            RelayMessage::Ok {
420                event_id: event.id(),
421                accepted: true,
422                message: Cow::Borrowed(""),
423            }
424            .to_json(),
425            alloc::format!("[\"OK\",\"{}\",true,\"\"]", event.id().to_hex())
426        );
427        assert_eq!(
428            RelayMessage::Eose(Cow::Borrowed(&id)).to_json(),
429            "[\"EOSE\",\"sub\"]"
430        );
431        assert_eq!(
432            RelayMessage::Count {
433                subscription_id: Cow::Borrowed(&id),
434                result: CountResult {
435                    count: 7,
436                    approximate: Some(true),
437                    hll: Some(Hll::from_str(&"ab".repeat(256)).expect("hll")),
438                },
439            }
440            .to_json(),
441            alloc::format!(
442                "[\"COUNT\",\"sub\",{{\"count\":7,\"approximate\":true,\"hll\":\"{}\"}}]",
443                "ab".repeat(256)
444            )
445        );
446    }
447
448    #[test]
449    fn into_owned_gives_static() {
450        let id = SubscriptionId::new("sub").expect("id");
451        let msg = ClientMessage::Close(Cow::Borrowed(&id));
452        let owned_msg: ClientMessage<'static> = msg.into_owned();
453        assert_eq!(owned_msg, ClientMessage::Close(Cow::Owned(id.clone())));
454        let relay = RelayMessage::Eose(Cow::Owned(id));
455        let owned_relay: RelayMessage<'static> = relay.into_owned();
456        assert!(matches!(owned_relay, RelayMessage::Eose(_)));
457    }
458
459    #[test]
460    #[cfg(feature = "os-rng")]
461    fn subscription_id_generate_is_16_lower_hex() {
462        let id = SubscriptionId::generate().expect("os rng");
463        assert_eq!(id.as_str().len(), 16);
464        assert!(
465            id.as_str()
466                .bytes()
467                .all(|b| b.is_ascii_hexdigit() && !b.is_ascii_uppercase())
468        );
469    }
470
471    #[test]
472    fn count_hll_serde_round_trip() {
473        let hll = Hll::from_str(&"ab".repeat(256)).expect("hll");
474        let json = serde_json::to_string(&hll).expect("ser");
475        assert_eq!(json, alloc::format!("\"{}\"", "ab".repeat(256)));
476        let back: Hll = serde_json::from_str(&json).expect("de");
477        assert_eq!(back, hll);
478        // Lowercase only; wrong lengths, case, non-hex, non-strings fail.
479        assert!(serde_json::from_str::<Hll>(&alloc::format!("\"{}\"", "AB".repeat(256))).is_err());
480        assert!(serde_json::from_str::<Hll>("\"ab\"").is_err());
481        assert!(serde_json::from_str::<Hll>(&alloc::format!("\"{}\"", "zz".repeat(256))).is_err());
482        assert!(serde_json::from_str::<Hll>("5").is_err());
483    }
484
485    #[test]
486    fn into_owned_covers_every_variant() {
487        let id = SubscriptionId::new("sub").expect("id");
488        let filter = Filter::new().kinds([Kind::TEXT_NOTE]).expect("filter");
489        let event = signed_event();
490        let event_id = event.id();
491        let clients: [ClientMessage<'_>; 8] = [
492            ClientMessage::Event(Cow::Borrowed(&event)),
493            ClientMessage::Req {
494                subscription_id: Cow::Borrowed(&id),
495                filters: Cow::Borrowed(core::slice::from_ref(&filter)),
496            },
497            ClientMessage::Count {
498                subscription_id: Cow::Borrowed(&id),
499                filters: Cow::Borrowed(core::slice::from_ref(&filter)),
500            },
501            ClientMessage::Close(Cow::Borrowed(&id)),
502            ClientMessage::Auth(Cow::Borrowed(&event)),
503            ClientMessage::NegOpen {
504                subscription_id: Cow::Borrowed(&id),
505                filter: Cow::Borrowed(&filter),
506                message: Cow::Borrowed("aabb"),
507            },
508            ClientMessage::NegMsg {
509                subscription_id: Cow::Borrowed(&id),
510                message: Cow::Borrowed("aabb"),
511            },
512            ClientMessage::NegClose(Cow::Borrowed(&id)),
513        ];
514        for message in clients {
515            let encoded = message.to_json();
516            let owned: ClientMessage<'static> = message.into_owned();
517            assert_eq!(owned.to_json(), encoded);
518        }
519        let relays: [RelayMessage<'_>; 9] = [
520            RelayMessage::Event {
521                subscription_id: Cow::Borrowed(&id),
522                event: Cow::Borrowed(&event),
523            },
524            RelayMessage::Ok {
525                event_id,
526                accepted: true,
527                message: Cow::Borrowed("m"),
528            },
529            RelayMessage::Eose(Cow::Borrowed(&id)),
530            RelayMessage::Closed {
531                subscription_id: Cow::Borrowed(&id),
532                message: Cow::Borrowed("m"),
533            },
534            RelayMessage::Notice(Cow::Borrowed("n")),
535            RelayMessage::Auth {
536                challenge: Cow::Borrowed("c"),
537            },
538            RelayMessage::Count {
539                subscription_id: Cow::Borrowed(&id),
540                result: CountResult {
541                    count: 1,
542                    approximate: Some(true),
543                    hll: Some(Hll::zero()),
544                },
545            },
546            RelayMessage::NegMsg {
547                subscription_id: Cow::Borrowed(&id),
548                message: Cow::Borrowed("aabb"),
549            },
550            RelayMessage::NegErr {
551                subscription_id: Cow::Borrowed(&id),
552                message: Cow::Borrowed("aabb"),
553            },
554        ];
555        for message in relays {
556            let encoded = message.to_json();
557            let owned: RelayMessage<'static> = message.into_owned();
558            assert_eq!(owned.to_json(), encoded);
559        }
560    }
561
562    #[test]
563    fn types_are_send_and_sync() {
564        fn assert_send_sync<T: Send + Sync>() {}
565        assert_send_sync::<SubscriptionId>();
566        assert_send_sync::<Hll>();
567        assert_send_sync::<CountResult>();
568        assert_send_sync::<ClientMessage<'static>>();
569        assert_send_sync::<RelayMessage<'static>>();
570    }
571}