1mod 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
28pub type Result<T, E = Error> = core::result::Result<T, E>;
30
31#[derive(Debug, thiserror::Error)]
33#[non_exhaustive]
34pub enum Error {
35 #[error("invalid JSON")]
37 InvalidJson {
38 #[source]
40 source: JsonError,
41 },
42 #[error("message must be a non-empty JSON array")]
45 NotAMessageArray,
46 #[error("unknown message type {ty}")]
48 UnknownType {
49 ty: String,
51 },
52 #[error("invalid {ty} message")]
54 InvalidMessage {
55 ty: &'static str,
57 },
58 #[error("invalid {ty} payload")]
60 InvalidPayload {
61 ty: &'static str,
63 #[source]
65 source: JsonError,
66 },
67 #[error("subscription id length {len} is outside 1..=64")]
69 InvalidSubscriptionId {
70 len: usize,
72 },
73 #[error("invalid NIP-45 HLL sketch: expected 512-char hex")]
75 InvalidHll,
76 #[error("obsolete 5-element NEG-OPEN; expected [NEG-OPEN, id, filter, hex]")]
78 ObsoleteNegOpen,
79 #[error("invalid negentropy message: expected non-empty even-length hex")]
81 InvalidNegMessage,
82 #[error("random source failed")]
84 Rng,
85}
86
87pub(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
103pub(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
116pub(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
125pub(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
134pub(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
143pub(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
152pub(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 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 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 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 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 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 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 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 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 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}