switchback-codec-pb

[!WARNING] Early prototype while exploring design and aiming for equivalence with protobuf-mdbook, while expanding scope through traits and intermediary on-disk representation.

This is not ready for adoption, nor even stable at a v1alpha1 yet. You'll want to keep eyes on the repository for development.

A lot of this is clanker driven, so vetting a good human read through pass hasn't been completed yet.

Reference binary codec for the switchback artifact in the switchback-rs toolchain.

Every parser emits a ReferenceManual through a SwitchbackCodec implementation; this crate provides the protobuf wire encoding using buffa types generated from switchback.proto (canardleteer.switchback.v1alpha1; repo-root proto/ symlinks here).

The default on-disk filename is switchback.binpb (DEFAULT_SWITCHBACK_FILENAME).

Usage

use switchback_codec_pb::ProtobufCodec;
use switchback_traits::{ReferenceManual, SyncSwitchbackCodec};

let manual = ReferenceManual {
    switchback_version: "v1alpha1".into(),
    title: "My API".into(),
    ..Default::default()
};

let codec = ProtobufCodec;
let bytes = codec.serialize(&manual)?;
let restored = codec.deserialize(&bytes)?;

For async callers, use the same methods on SwitchbackCodec with .await.

Schema status

canardleteer.switchback.v1alpha1 is unstable and in active development. Expect wire-format changes until the schema graduates to v1. See ADR 0003.

Protocol attachments

Transport semantics live outside the core contract graph in a ProtocolAttachment envelope (protocol_id + opaque payload bytes) on contract and entity nodes. This crate compiles four protobuf schemas from proto/:

Decode payload by protocol_id: built-in ids "http" and "grpc" map to HttpPayload and GrpcPayload. See the entity attachment matrix in ADR 0011. HTTP streaming inference and gRPC call metadata authoring are in ADR 0012.

Generated Rust types:

• canardleteer::switchback::v1alpha1::* — core wire messages
• canardleteer::switchback::protocol::http::v1alpha1::*
• canardleteer::switchback::protocol::grpc::v1alpha1::*

Use switchback-protocols ProtocolRegistry for encode/decode in application code.

Build

Protoc is vendored via protoc-bin-vendored in build.rs; no system protoc install is required. The wire schema lives in this crate's proto/ tree and is checked with buf lint / buf format in CI.