bloop-protocol 1.1.0

Core implementation of the Bloop wire protocol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

//! Core implementation of the Bloop wire protocol (version 3).
//!
//! The Bloop protocol is a binary, synchronous request-response protocol
//! layered over a TLS stream, used between clients (e.g. Bloop Boxes) and a
//! Bloop server. This crate is the single source of truth for its wire
//! format; the written specification lives in the `protocol-spec` repository.
//!
//! The crate is layered:
//!
//! - [`frame`] reads and writes raw frames (`message_type` + length-prefixed
//!   payload) from async streams.
//! - [`codec`] maps values onto the packed payload byte layout via the
//!   [`Encode`] and [`Decode`] traits, usually through their derives.
//! - [`set`] dispatches raw frames into typed message enums via
//!   [`MessageSet`], with [`message`] providing the standard protocol
//!   messages and the extensible [`ClientMessage`] / [`ServerMessage`] sets.
//!
//! # Examples
//!
//! Custom protocol extensions define their messages as derived structs and
//! group them into a message set. Extension opcodes must be `0x80` or above;
//! the range below is reserved for the standard protocol.
//!
//! ```
//! use bloop_protocol::{Decode, Encode, MessageSet, Payload};
//!
//! #[derive(Debug, Encode, Decode, Payload, PartialEq)]
//! #[bloop(opcode = 0x80)]
//! struct SetVolume {
//!     volume: u8,
//! }
//!
//! #[derive(Debug, MessageSet, PartialEq)]
//! enum CustomRequest {
//!     SetVolume(SetVolume),
//! }
//!
//! let raw = CustomRequest::SetVolume(SetVolume { volume: 5 }).encode()?;
//! assert_eq!(raw.message_type, 0x80);
//!
//! let decoded = CustomRequest::decode(&raw)?;
//! assert_eq!(decoded, CustomRequest::SetVolume(SetVolume { volume: 5 }));
//! # Ok::<_, Box<dyn std::error::Error>>(())
//! ```

#![cfg_attr(docsrs, feature(doc_auto_cfg))]

// Lets the derive macros refer to this crate as `::bloop_protocol` from
// within the crate itself.
extern crate self as bloop_protocol;

pub mod capabilities;
pub mod codec;
pub mod data_hash;
pub mod frame;
pub mod message;
pub mod nfc_uid;
pub mod set;

pub use bloop_protocol_derive::{Decode, Encode, MessageSet, Payload};

pub use capabilities::Capabilities;
pub use codec::{Decode, DecodeError, Encode, EncodeError, decode_payload, encode_payload};
pub use data_hash::DataHash;
pub use frame::{FrameError, RawMessage, read_frame, write_frame};
pub use message::{ClientMessage, ErrorResponse, ServerMessage};
pub use nfc_uid::NfcUid;
pub use set::{
    MessageSet, MessageSetError, NoExtension, Payload, Request, decode_message, encode_message,
};