switchback_protocols/
traits.rs

1//! Protocol trait seams.
2
3use switchback_traits::{ResponseSeverity, Result};
4
5/// Stable protocol slug plus metadata.
6pub trait Protocol: Send + Sync + 'static {
7    /// Protocol slug (for example `"http"`, `"grpc"`).
8    fn id(&self) -> &'static str;
9}
10
11/// Encode/decode the typed payload inside [`ProtocolAttachment`](switchback_traits::ProtocolAttachment).
12pub trait ProtocolWire: Sized {
13    /// Protocol slug this wire type belongs to.
14    const PROTOCOL_ID: &'static str;
15
16    /// Serialize this payload to bytes for attachment storage.
17    fn encode_to_vec(&self) -> Vec<u8>;
18
19    /// Deserialize bytes produced by [`Self::encode_to_vec`].
20    fn decode_from_bytes(bytes: &[u8]) -> Result<Self>;
21}
22
23/// Operation documentation aspects.
24pub trait OperationProtocol: Protocol {
25    /// Typed operation metadata payload.
26    type OperationMeta: ProtocolWire;
27
28    /// Human-facing operation signature line.
29    fn format_signature(&self, meta: &Self::OperationMeta) -> String;
30
31    /// Optional title hint derived from operation metadata.
32    fn operation_title_hint(&self, meta: &Self::OperationMeta) -> Option<String> {
33        let _ = meta;
34        None
35    }
36}
37
38/// Response outcome mapping.
39pub trait ResponseProtocol: Protocol {
40    /// Map a family-specific status key to [`ResponseSeverity`].
41    fn response_severity(&self, status_key: &str) -> ResponseSeverity;
42}
43
44/// Error / fault documentation aspects.
45pub trait ErrorProtocol: Protocol {
46    /// Typed error metadata payload.
47    type ErrorMeta: ProtocolWire;
48
49    /// Map an error key to [`ResponseSeverity`].
50    fn error_severity(&self, error_key: &str) -> ResponseSeverity;
51
52    /// Human-readable error label for documentation.
53    fn format_error_label(&self, error_key: &str) -> String;
54}
55
56/// Named fields carried outside the message body.
57pub trait FieldCarrierProtocol: Protocol {
58    /// Valid carrier kinds for this protocol.
59    fn field_carrier_kinds(&self) -> &'static [&'static str];
60
61    /// Valid parameter locations for this protocol.
62    fn valid_parameter_locations(&self) -> &'static [&'static str];
63}
switchback_protocols/traits.rs

switchback_protocols/
traits.rs
