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//! | `protocol/kafka/v1alpha1/kafka.proto` | [`canardleteer::switchback::protocol::kafka::v1alpha1`] |
26//! | `protocol/amqp/v1alpha1/amqp.proto` | [`canardleteer::switchback::protocol::amqp::v1alpha1`] |
27//! | `protocol/mqtt/v1alpha1/mqtt.proto` | [`canardleteer::switchback::protocol::mqtt::v1alpha1`] |
28//!
29//! 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).
30//! 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).
31//! Application code should prefer the
32//! [`switchback-protocols`](https://github.com/canardleteer/switchback-rs/tree/main/crates/switchback-protocols)
33//! `ProtocolRegistry` for encode/decode.
34//!
35//! # Example
36//!
37//! ```
38//! use switchback_codec_pb::ProtobufCodec;
39//! use switchback_traits::{ReferenceManual, SyncSwitchbackCodec};
40//!
41//! let manual = ReferenceManual {
42//!     switchback_version: "v1alpha1".into(),
43//!     title: "Example".into(),
44//!     ..Default::default()
45//! };
46//! let codec = ProtobufCodec;
47//! let bytes = codec.serialize(&manual).unwrap();
48//! let round_trip = codec.deserialize(&bytes).unwrap();
49//! assert_eq!(round_trip.title, "Example");
50//! ```
51//!
52//! Wire message types live under [`canardleteer::switchback::v1alpha1`].
53
54mod codec;
55mod protobuf;
56
57/// Low-level protobuf conversion between seam model types and wire messages.
58pub mod convert;
59
60/// Buffa-generated protobuf types, namespaced by protobuf package path.
61pub use protobuf::canardleteer;
62
63/// Codec-internal alias for the active protobuf schema; prefer
64/// [`canardleteer::switchback::v1alpha1`] in external tools.
65pub(crate) mod pb {
66    pub use crate::protobuf::generated::canardleteer::switchback::v1alpha1::*;
67}
68
69pub use codec::{DEFAULT_SWITCHBACK_FILENAME, ProtobufCodec};
70pub use convert::WIRE_VERSION;
switchback_codec_pb/lib.rs

switchback_codec_pb/
lib.rs
