shep_core/protocol/
mod.rs

1//! The client<->daemon wire protocol (version 6).
2//!
3//! Typed request/response enums plus bus events. Framing lives in
4//! [`wire`]; a serialized shape change bumps [`PROTOCOL_VERSION`].
5//! Version 4 bumped on an addition. Version 5 bumped on a new `AppConfig`
6//! field: that struct is `deny_unknown_fields`, so the additive rule below
7//! does not cover it and an older daemon cannot decode `depends_on`.
8//! Version 6 bumped on a retype: [`Response::Reloading`] became a struct
9//! variant to carry the apps a staged reload refused, so it serializes as
10//! an object where an older peer reads an array.
11//!
12//! A `*_wire_v6` test pins today's shape. A
13//! `v1_*_fixture_still_deserializes` test pins an old peer's payload and
14//! never renames.
15
16pub mod events;
17pub mod frame;
18pub mod request;
19/// Frame encoding shared by daemon and client
20pub mod wire;
21
22pub use events::{BusEvent, ProcessEventKind};
23pub use frame::ServerFrame;
24pub use request::{
25    ActionOutcome, ActionReply, DogSectionToml, DogSource, EnvValue, Envelope, ExitInfo, Hello,
26    HelloAck, HelloReply, Lamb, LineOutcome, LineReply, ProcessInfo, ProcessInfoBuilder, Reply,
27    Request, Response, RpcError, RpcErrorCode, SelectorSpec, SheepApplied, SheepConfigView,
28    SheepDrift, SheepRefusal, SignalOutcome, SignalReply, Smit, SmitError, sort_flock,
29};
30pub use shep_channel::{CHANNEL_VERSION, ChildMessage, ShepherdMessage};
31pub use wire::{MAX_FRAME_BYTES, WireError, codec, decode_frame, encode_frame};
32
33/// The shepherd channel's wire types. Moved to the `shep-channel` crate;
34/// this path is kept so consumers of 0.1.x do not break. Use
35/// `shep_core::protocol` directly instead.
36#[deprecated(note = "use `shep_core::protocol` directly")]
37pub mod channel {
38    pub use shep_channel::{CHANNEL_VERSION, ChildMessage, ShepherdMessage};
39}
40
41/// Wire protocol version.
42///
43/// Additive optional fields (new serde-defaulted `Option<T>` fields, new
44/// variants behind `#[non_exhaustive]`) keep the version. Removing,
45/// renaming, or retyping anything serialized bumps it, recorded in the
46/// CHANGELOG. Byte fixtures in each protocol module pin the deserialize
47/// direction.
48pub const PROTOCOL_VERSION: u32 = 6;
49
50#[cfg(test)]
51mod tests {
52    use super::PROTOCOL_VERSION;
53
54    #[test]
55    fn a_retyped_reloading_forced_the_protocol_version_up() {
56        // fails if `Response::Reloading` becomes a struct variant without
57        // the bump. The variant serializes as an object now where it used
58        // to serialize as an array, so an older peer decodes neither, and
59        // the handshake is the only place that can say so.
60        assert_eq!(PROTOCOL_VERSION, 6);
61    }
62}
shep_core/protocol/mod.rs

shep_core/protocol/
mod.rs
