pushwire-core 0.1.1

Shared types and codecs for push-wire multiplexed push protocol
Documentation 
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
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

use serde::{Serialize, de::DeserializeOwned};
use std::fmt::Debug;
use std::hash::Hash;

/// Trait for defining multiplexed channel types.
///
/// Consumers implement this trait to define their own channel taxonomy.
/// Each channel has a priority, a wire ID for binary encoding, and
/// string representations for JSON/SSE serialization.
///
/// # Example
///
/// ```rust
/// use pushwire_core::ChannelKind;
///
/// #[derive(Debug, Clone, Copy, Hash, Eq, PartialEq, serde::Serialize, serde::Deserialize)]
/// #[serde(rename_all = "lowercase")]
/// enum MyChannel { Events, Control, System }
///
/// impl ChannelKind for MyChannel {
///     fn priority(&self) -> u8 {
///         match self {
///             MyChannel::System | MyChannel::Events => 0,
///             MyChannel::Control => 1,
///         }
///     }
///     fn wire_id(&self) -> u8 {
///         match self {
///             MyChannel::Events => 0x01,
///             MyChannel::Control => 0x02,
///             MyChannel::System => 0x05,
///         }
///     }
///     fn from_wire_id(id: u8) -> Option<Self> {
///         match id {
///             0x01 => Some(MyChannel::Events),
///             0x02 => Some(MyChannel::Control),
///             0x05 => Some(MyChannel::System),
///             _ => None,
///         }
///     }
///     fn from_name(s: &str) -> Option<Self> {
///         match s {
///             "events" => Some(MyChannel::Events),
///             "control" => Some(MyChannel::Control),
///             "system" => Some(MyChannel::System),
///             _ => None,
///         }
///     }
///     fn name(&self) -> &'static str {
///         match self {
///             MyChannel::Events => "events",
///             MyChannel::Control => "control",
///             MyChannel::System => "system",
///         }
///     }
///     fn is_system(&self) -> bool { matches!(self, MyChannel::System) }
///     fn all() -> &'static [Self] { &[Self::Events, Self::Control, Self::System] }
/// }
/// ```
pub trait ChannelKind:
    Debug + Clone + Copy + Hash + Eq + Send + Sync + Serialize + DeserializeOwned + 'static
{
    /// Priority for outbound queue ordering. Lower values = higher priority.
    /// Typical mapping: 0 = high (system, critical UI), 1 = normal, 2 = low (telemetry).
    fn priority(&self) -> u8;

    /// Numeric ID for the binary wire format. Must be unique per channel.
    fn wire_id(&self) -> u8;

    /// Decode from binary wire ID. Returns `None` for unknown IDs.
    fn from_wire_id(id: u8) -> Option<Self>;

    /// Parse from canonical string name (for SSE query params, JSON fields).
    fn from_name(s: &str) -> Option<Self>;

    /// Canonical string name for this channel.
    fn name(&self) -> &'static str;

    /// Whether this channel is the system/control channel.
    /// The system channel handles auth, ping/pong, ACK, and subscription management.
    /// Exactly one channel should return `true`.
    fn is_system(&self) -> bool;

    /// All valid channel variants. Used for cursor initialization and enumeration.
    fn all() -> &'static [Self];
}

/// Parse a comma-separated channel list (e.g. from SSE query params).
pub fn parse_channels<C: ChannelKind>(raw: Option<&str>) -> Vec<C> {
    raw.map(|list| {
        list.split(',')
            .filter_map(|s| C::from_name(s.trim()))
            .collect()
    })
    .unwrap_or_default()
}