Skip to main content

laser_wire/
content.rs

1use serde::{Deserialize, Serialize};
2
3/// The wire codec tag stamped on `agdx.ct`.
4#[derive(
5    Clone,
6    Copy,
7    Debug,
8    Default,
9    PartialEq,
10    Eq,
11    Serialize,
12    Deserialize,
13    strum::Display,
14    strum::EnumString,
15    strum::VariantArray,
16)]
17#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
18#[strum(serialize_all = "snake_case")]
19#[serde(rename_all = "snake_case")]
20#[non_exhaustive]
21pub enum ContentType {
22    /// "Best-effort decode": the projector tries JSON first, else
23    /// raw. Useful when a projection is content-agnostic. Lands on the wire
24    /// as the `any` variant so consumers can distinguish "unknown" from "raw".
25    Any,
26    #[default]
27    Raw,
28    Json,
29    Avro,
30    Protobuf,
31    Msgpack,
32    Cbor,
33    Bson,
34    Arrow,
35    /// The body is a CBOR [`BodyRef`](crate::agent::BodyRef) capsule
36    /// pointing at content stored elsewhere (object storage, KV, another
37    /// topic), not the content itself: the claim-check form for payloads too
38    /// large or sensitive to inline.
39    Ref,
40}
41
42impl ContentType {
43    /// Whether this is the default `Raw` codec (omitted on the wire when a
44    /// field defaults to it).
45    pub const fn is_raw(&self) -> bool {
46        matches!(self, ContentType::Raw)
47    }
48
49    /// The compact `u8` wire code stamped as the `agdx.ct` header value. A fixed
50    /// dictionary shared with LaserData Cloud and its display layers (and the
51    /// shape planned for Iggy's native reserved content-type field): raw=0,
52    /// json=1, msgpack=2, cbor=3, bson=4, avro=5, protobuf=6, arrow=7,
53    /// ref=8 (claim-check body reference), any=255 (best-effort sentinel).
54    pub const fn code(self) -> u8 {
55        match self {
56            ContentType::Raw => 0,
57            ContentType::Json => 1,
58            ContentType::Msgpack => 2,
59            ContentType::Cbor => 3,
60            ContentType::Bson => 4,
61            ContentType::Avro => 5,
62            ContentType::Protobuf => 6,
63            ContentType::Arrow => 7,
64            ContentType::Ref => 8,
65            ContentType::Any => 255,
66        }
67    }
68
69    /// Decode a compact `agdx.ct` code, or `None` for a code this build does
70    /// not name. The codes are a growable dictionary, so a server MUST treat an
71    /// unknown code as opaque (pass it through, decode the body best-effort)
72    /// and never reject the record on it. A newer peer may stamp a code this
73    /// build has not learned yet.
74    pub const fn from_code(code: u8) -> Option<Self> {
75        match code {
76            0 => Some(ContentType::Raw),
77            1 => Some(ContentType::Json),
78            2 => Some(ContentType::Msgpack),
79            3 => Some(ContentType::Cbor),
80            4 => Some(ContentType::Bson),
81            5 => Some(ContentType::Avro),
82            6 => Some(ContentType::Protobuf),
83            7 => Some(ContentType::Arrow),
84            8 => Some(ContentType::Ref),
85            255 => Some(ContentType::Any),
86            _ => None,
87        }
88    }
89}
90
91#[cfg(test)]
92mod tests {
93    use super::*;
94
95    #[test]
96    fn given_content_type_codes_when_mapped_then_should_match_the_fixed_dictionary() {
97        // The compact `agdx.ct` dictionary is a fixed wire contract: the
98        // `ContentType::code` mapping must not drift.
99        let expected = [
100            (ContentType::Raw, 0u8),
101            (ContentType::Json, 1),
102            (ContentType::Msgpack, 2),
103            (ContentType::Cbor, 3),
104            (ContentType::Bson, 4),
105            (ContentType::Avro, 5),
106            (ContentType::Protobuf, 6),
107            (ContentType::Arrow, 7),
108            (ContentType::Ref, 8),
109            (ContentType::Any, 255),
110        ];
111        for (content_type, code) in expected {
112            assert_eq!(content_type.code(), code);
113            assert_eq!(ContentType::from_code(code), Some(content_type));
114        }
115        assert_eq!(ContentType::from_code(9), None);
116    }
117
118    #[test]
119    fn given_content_types_when_displayed_then_should_match_the_wire_names() {
120        assert_eq!(ContentType::Raw.to_string(), "raw");
121        assert_eq!(ContentType::Json.to_string(), "json");
122        assert_eq!(ContentType::Msgpack.to_string(), "msgpack");
123        assert_eq!(
124            "protobuf".parse::<ContentType>().expect("protobuf parses"),
125            ContentType::Protobuf
126        );
127        assert_eq!(ContentType::default(), ContentType::Raw);
128    }
129}