shep_core/protocol/
frame.rs

1//! Anything the daemon writes to a connected client
2//!
3//! The server sends two kinds of frames on one socket: [`Reply`] (answers to
4//! requests) and [`BusEvent`] (broadcast events). This type decodes either,
5//! untagged, because their JSON key sets are disjoint (`id`/`result` vs
6//! `event`), at zero cost to the wire.
7//!
8//! Deserialization needs `serde/std` for buffered content semantics, available
9//! via `serde_json`'s `std` feature (already enabled workspace-wide).
10
11use serde::{Deserialize, Serialize};
12
13use crate::protocol::{BusEvent, Reply};
14
15/// Anything the daemon writes to a connected client
16///
17/// Round-trips to byte-identical output, since the daemon serializes
18/// `Reply`/`BusEvent` directly (pinned by `server_frame_is_byte_identical`).
19// wire format: changing existing variants is a breaking change
20#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
21#[serde(untagged)]
22// Growth is anticipated: a future frame kind (progress, flow control) is
23// additive here and stays additive on the wire.
24#[non_exhaustive]
25pub enum ServerFrame {
26    /// An answer to one request (from [`Envelope`](crate::protocol::Envelope))
27    Reply(Reply),
28    /// One subscribed bus event
29    Event(BusEvent),
30}
31
32#[cfg(test)]
33mod tests {
34    use super::*;
35    use crate::protocol::{
36        BusEvent, ProcessEventKind, ProcessInfo, Reply, Response, RpcError, RpcErrorCode,
37        encode_frame,
38    };
39    use crate::status::ProcStatus;
40
41    fn sample_reply() -> Reply {
42        Reply {
43            id: 7,
44            result: Ok(Response::Pong),
45        }
46    }
47
48    fn sample_event() -> BusEvent {
49        BusEvent::Process {
50            event: ProcessEventKind::Online,
51            info: ProcessInfo {
52                id: 3,
53                name: "web".to_string(),
54                status: ProcStatus::Online,
55                pid: Some(4242),
56                restarts: 0,
57                uptime_ms: 0,
58                fold: None,
59                out_file: Some("/home/ada/.shep/logs/web-0-out.log".to_string()),
60                err_file: Some("/home/ada/.shep/logs/web-0-err.log".to_string()),
61                cpu_percent: None,
62                memory_bytes: None,
63                dog: None,
64                lambs: None,
65                last_exit: None,
66                smit: None,
67                instance: None,
68                handshook: None,
69                dog_stale: None,
70                pending: None,
71                overridden: None,
72                max_memory: None,
73            },
74            manually: false,
75            at_ms: 1_700_000_000_000,
76        }
77    }
78
79    #[test]
80    fn server_frame_decodes_both_directions_of_the_stream() {
81        // The two shapes are disjoint: a Reply has no `event` key and an
82        // event has no `id`/`result` pair, so untagged never guesses wrong.
83        let reply = r#"{"id":1,"result":{"Ok":{"kind":"pong"}}}"#;
84        assert!(matches!(
85            serde_json::from_str::<ServerFrame>(reply).unwrap(),
86            ServerFrame::Reply(Reply { id: 1, .. })
87        ));
88        let event = r#"{"event":"log_out","data":{"id":3,"line":"ready"}}"#;
89        assert!(matches!(
90            serde_json::from_str::<ServerFrame>(event).unwrap(),
91            ServerFrame::Event(BusEvent::LogOut { id: 3, .. })
92        ));
93    }
94
95    #[test]
96    fn server_frame_is_byte_identical_to_its_payload() {
97        // The daemon encodes Reply/BusEvent directly; if wrapping ever
98        // started adding bytes, every client would break at once.
99        let reply = sample_reply();
100        assert_eq!(
101            encode_frame(&ServerFrame::Reply(reply.clone())).unwrap(),
102            encode_frame(&reply).unwrap()
103        );
104        let event = sample_event();
105        assert_eq!(
106            encode_frame(&ServerFrame::Event(event.clone())).unwrap(),
107            encode_frame(&event).unwrap()
108        );
109    }
110
111    #[test]
112    fn an_error_reply_still_decodes_as_a_reply_frame() {
113        let err = Reply {
114            id: 2,
115            result: Err(RpcError {
116                code: RpcErrorCode::DeadlineExceeded,
117                message: "request deadline of 5000 ms expired".to_string(),
118                daemon_version: None,
119            }),
120        };
121        let json = serde_json::to_string(&err).unwrap();
122        assert_eq!(
123            serde_json::from_str::<ServerFrame>(&json).unwrap(),
124            ServerFrame::Reply(err)
125        );
126    }
127}
shep_core/protocol/frame.rs

shep_core/protocol/
frame.rs
