switchback_codec_pb/
lib.rs

1#![forbid(unsafe_code)]
2#![warn(missing_docs)]
3#![allow(async_fn_in_trait)]
4
5//! Reference binary codec for the switchback artifact.
6//!
7//! `switchback-codec-pb` implements [`SwitchbackCodec`] and
8//! [`SyncSwitchbackCodec`] from `switchback-traits` using
9//! [buffa](https://github.com/anthropics/buffa)-generated types compiled from
10//! [`switchback.proto`](https://github.com/canardleteer/switchback-rs/blob/main/crates/switchback-codec-pb/proto/canardleteer/switchback/v1alpha1/switchback.proto)
11//! (`canardleteer.switchback.v1alpha1`). See [ADR 0003](https://github.com/canardleteer/switchback-rs/blob/main/docs/adr/0003-protobuf-switchback-wire-format-with-buffa-in-switchback-codec-pb.md)
12//! for wire-format policy.
13//!
14//! # Protocol sub-schemas
15//!
16//! Transport metadata uses [`ProtocolAttachment`](switchback_traits::ProtocolAttachment)
17//! envelopes on contract and entity nodes. Payload bytes encode one arm of a
18//! protocol-package oneof; the core schema does not import those packages.
19//!
20//! | Compiled proto | Generated Rust module |
21//! | --- | --- |
22//! | `protocol/http/v1alpha1/http.proto` | [`canardleteer::switchback::protocol::http::v1alpha1`] |
23//! | `protocol/grpc/v1alpha1/grpc.proto` | [`canardleteer::switchback::protocol::grpc::v1alpha1`] |
24//! | `protocol/grpc/v1alpha1/metadata_options.proto` | same gRPC module (MethodOptions extension) |
25//!
26//! Entity attachment matrix and decode steps: [ADR 0011](https://github.com/canardleteer/switchback-rs/blob/main/docs/adr/0011-protocol-layer-and-contract-family-binding.md).
27//! HTTP streaming and gRPC metadata authoring: [ADR 0012](https://github.com/canardleteer/switchback-rs/blob/main/docs/adr/0012-http-streaming-inference-and-grpc-metadata-from-protobuf-options.md).
28//! Application code should prefer the
29//! [`switchback-protocols`](https://github.com/canardleteer/switchback-rs/tree/main/crates/switchback-protocols)
30//! `ProtocolRegistry` for encode/decode.
31//!
32//! # Example
33//!
34//! ```
35//! use switchback_codec_pb::ProtobufCodec;
36//! use switchback_traits::{ReferenceManual, SyncSwitchbackCodec};
37//!
38//! let manual = ReferenceManual {
39//!     switchback_version: "v1alpha1".into(),
40//!     title: "Example".into(),
41//!     ..Default::default()
42//! };
43//! let codec = ProtobufCodec;
44//! let bytes = codec.serialize(&manual).unwrap();
45//! let round_trip = codec.deserialize(&bytes).unwrap();
46//! assert_eq!(round_trip.title, "Example");
47//! ```
48//!
49//! Wire message types live under [`canardleteer::switchback::v1alpha1`].
50
51mod codec;
52mod protobuf;
53
54/// Low-level protobuf conversion between seam model types and wire messages.
55pub mod convert;
56
57/// Buffa-generated protobuf types, namespaced by protobuf package path.
58pub use protobuf::canardleteer;
59
60/// Codec-internal alias for the active protobuf schema; prefer
61/// [`canardleteer::switchback::v1alpha1`] in external tools.
62pub(crate) mod pb {
63    pub use crate::protobuf::generated::canardleteer::switchback::v1alpha1::*;
64}
65
66pub use codec::{DEFAULT_SWITCHBACK_FILENAME, ProtobufCodec};
67pub use convert::WIRE_VERSION;
switchback_codec_pb/lib.rs

switchback_codec_pb/
lib.rs
