phoxal_bus/contract.rs
1//! The contract primitive traits (D60/D61): the API-version marker and the
2//! version-local wire body.
3//!
4//! These are the two traits the bus client is generic over - the ABI floor every
5//! contract body and api-version marker implements. The concrete versioned API
6//! versions (`phoxal::api`, …) and the `phoxal_api_tree!` macro that
7//! generates their `ApiVersion` / `ContractBody` impls live in the `phoxal-api`
8//! crate, which re-exports these traits - so they are reachable as
9//! `phoxal_api::ApiVersion` / `phoxal_api::ContractBody`. The `phoxal` engine
10//! re-exports this bus crate at `phoxal::bus`, so they are also reachable as
11//! `phoxal::bus::ApiVersion` / `phoxal::bus::ContractBody`.
12
13/// Marker trait identifying one API version (D60).
14///
15/// Implemented only by the zero-variant `enum Api {}` that
16/// [`phoxal_api_tree!`] generates inside each revision module. The [`ID`] is the
17/// dotted wire revision (`"v0.1"`) and is carried in bus metadata as
18/// informational provenance, never in the wire body or the topic key (D62).
19///
20/// [`ID`]: ApiVersion::ID
21/// [`phoxal_api_tree!`]: https://docs.rs/phoxal
22pub trait ApiVersion: 'static {
23 /// The dotted wire-revision identifier, e.g. `"v0.1"` (the corresponding
24 /// Rust module is `v0_1`).
25 const ID: &'static str;
26}
27
28/// The semantic role a topic plays in its owning service's contract.
29///
30/// Every topic in a [`phoxal_api_tree!`] declares one of these (D63, plan #00).
31/// The role records *intent*, separate from the wire shape: a `Command` and a
32/// `State` topic are both pub/sub on the wire, but the owner subscribes a
33/// `Command` (it is the service's control input) and publishes a `State` (it is
34/// the service's telemetry output). `Query` is the request/response role.
35///
36/// The role drives the side branding (L1): the api tree's builders read it to pick
37/// each leaf's side-branded topic kind (`Publish`/`Subscribe`/`AskQuery`/`ServeQuery`),
38/// so taking the wrong side of a topic is a compile error. The role also rides
39/// alongside each generated contract body as a `ROLE` const; that const is not yet
40/// emitted by `emit-apis` (a later increment of plan #00).
41///
42/// [`phoxal_api_tree!`]: https://docs.rs/phoxal
43#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
44pub enum TopicRole {
45 /// A control input the owning service subscribes (e.g. `drive/target`).
46 Command,
47 /// A telemetry/output the owning service publishes (e.g. `drive/state`).
48 State,
49 /// A request/response topic the owning service answers (e.g. `map/submap`).
50 Query,
51}
52
53impl TopicRole {
54 /// The lowercase grammar keyword for this role (`"command"` / `"state"` /
55 /// `"query"`), matching how it is written in `phoxal_api_tree!`.
56 pub const fn as_str(self) -> &'static str {
57 match self {
58 TopicRole::Command => "command",
59 TopicRole::State => "state",
60 TopicRole::Query => "query",
61 }
62 }
63}
64
65/// A version-local wire body: a plain serde type bound to exactly one
66/// [`ApiVersion`] and one contract topic (D61/D1).
67///
68/// Every body declared inside a `phoxal_api_tree!` node gets a generated impl.
69/// Each body carries its own [`Api`](ContractBody::Api) version marker and
70/// version-qualified [`TOPIC`](ContractBody::TOPIC).
71/// Participant `Api` derives record contract bodies field by field, and setup
72/// builders require the requested handle body to be declared by that struct.
73///
74/// The serde encoding of an implementor *is* the wire payload; there is no version
75/// envelope (D62).
76///
77/// **Wire identity is the key, not a hash (D1).** The version is folded into
78/// [`TOPIC`](ContractBody::TOPIC), so `v0.1::drive::Target` and a
79/// hypothetically re-minted `v0.2::drive::Target` publish on different Zenoh
80/// keys and physically cannot collide. There is therefore no `SCHEMA_ID`/`FAMILY`
81/// axis: two participants interoperate on a contract iff they use the exact same
82/// version-qualified name, which is realized on the wire by the key.
83/// A receiver's per-key Zenoh subscription is the
84/// whole fast-reject; the bus decode path validates only the codec.
85pub trait ContractBody:
86 serde::Serialize + serde::de::DeserializeOwned + Clone + Send + Sync + 'static
87{
88 /// The single API version this body belongs to. Two bodies from different
89 /// versions have different `Api`, so the type system keeps them apart.
90 type Api: ApiVersion;
91 /// The version-qualified type identity: the dotted wire revision, then the `::`-joined node path
92 /// (dynamic-node vars are topic params, never type-path segments), then
93 /// the PascalCase type leaf, e.g. `"v0.1::drive::Target"` or
94 /// `"v0.1::component::motor::Command"`. This is the contract's source
95 /// identity (D1) - two contracts interoperate iff they share this exact
96 /// name - as distinct from [`TOPIC`](ContractBody::TOPIC), the resolved
97 /// wire key derived from it. `NAME` is exactly the `"::"`-join of
98 /// [`VERSION`](ContractBody::VERSION) and
99 /// [`CONTRACT`](ContractBody::CONTRACT); it stays available for callers
100 /// that want the whole identity as one string (e.g. display), while
101 /// metadata recording splices the two split consts instead (coherence-gate
102 /// design doc §2 - a joined name is not machine-parseable without
103 /// assuming the version naming scheme).
104 const NAME: &'static str;
105 /// This body's dotted wire revision alone, e.g. `"v0.1"` - equal to
106 /// `<Self::Api as ApiVersion>::ID`, but exposed directly on the body so a
107 /// metadata recorder (`#[derive(phoxal::Api)]`'s linker-section
108 /// splicing) can const-splice it without routing through `Self::Api`.
109 /// Split from [`CONTRACT`](ContractBody::CONTRACT) so consumers (the
110 /// coherence gate and suite generator) record revision and contract as two
111 /// separate fields rather than parsing a joined name.
112 const VERSION: &'static str;
113 /// This body's contract path within its own version: the `::`-joined
114 /// node path (dynamic-node vars excluded, as with `NAME`) plus the
115 /// PascalCase type leaf, e.g. `"drive::Target"`. The **logical
116 /// contract** - stable across a version bump - is this value alone;
117 /// pairing it with [`VERSION`](ContractBody::VERSION) recovers the
118 /// full version-qualified identity (`NAME`).
119 const CONTRACT: &'static str;
120 /// The version-qualified wire key: the dotted wire revision, then the
121 /// `/`-joined node path plus the topic leaf, with each dynamic node
122 /// contributing a `{var}` placeholder, e.g. `"v0.1/drive/state"` or
123 /// `"v0.1/component/{instance}/motor/{capability}/command"`. The concrete
124 /// key is produced by the api-local `topic` builder, which fills the
125 /// placeholders.
126 const TOPIC: &'static str;
127}