Trait ContractBody

Source

pub trait ContractBody:
    Serialize
    + DeserializeOwned
    + Clone
    + Send
    + Sync
    + 'static {
    type Api: ApiVersion;

    const NAME: &'static str;
    const VERSION: &'static str;
    const CONTRACT: &'static str;
    const TOPIC: &'static str;
}

Expand description

The contract primitive traits, re-exported from the phoxal-bus crate (the ABI floor) so they stay addressable at phoxal_api::ApiVersion / phoxal_api::ContractBody.

ApiVersion is the marker trait identifying one API version (D60), implemented only by the zero-variant enum Api {} that phoxal_api_tree! generates inside each revision module; its ID is the concrete dotted wire identity (for example "v0.1").
ContractBody is a version-local wire body (D61): a plain serde type bound to exactly one ApiVersion and one contract topic. Every body declared inside a phoxal_api_tree! node gets a generated impl; handles, SetupContext builders, and the Service/Driver derive assertions key off its Api/TOPIC. TOPIC is version-qualified (D1) and is the compatibility key - there is no SCHEMA_ID/FAMILY; its serde encoding is the wire payload, with no version envelope (D62). A version-local wire body: a plain serde type bound to exactly one ApiVersion and one contract topic (D61/D1).

Every body declared inside a phoxal_api_tree! node gets a generated impl. Each body carries its own Api version marker and version-qualified TOPIC. Participant Api derives record contract bodies field by field, and setup builders require the requested handle body to be declared by that struct.

The serde encoding of an implementor is the wire payload; there is no version envelope (D62).

Wire identity is the key, not a hash (D1). The version is folded into TOPIC, so v0.1::drive::Target and a hypothetically re-minted v0.2::drive::Target publish on different Zenoh keys and physically cannot collide. There is therefore no SCHEMA_ID/FAMILY axis: two participants interoperate on a contract iff they use the exact same version-qualified name, which is realized on the wire by the key. A receiver’s per-key Zenoh subscription is the whole fast-reject; the bus decode path validates only the codec.

Required Associated Constants§

Source

const NAME: &'static str

The version-qualified type identity: the dotted wire revision, then the ::-joined node path (dynamic-node vars are topic params, never type-path segments), then the PascalCase type leaf, e.g. "v0.1::drive::Target" or "v0.1::component::motor::Command". This is the contract’s source identity (D1) - two contracts interoperate iff they share this exact name - as distinct from TOPIC, the resolved wire key derived from it. NAME is exactly the "::"-join of VERSION and CONTRACT; it stays available for callers that want the whole identity as one string (e.g. display), while metadata recording splices the two split consts instead (coherence-gate design doc §2 - a joined name is not machine-parseable without assuming the version naming scheme).

Source

const VERSION: &'static str

This body’s dotted wire revision alone, e.g. "v0.1" - equal to <Self::Api as ApiVersion>::ID, but exposed directly on the body so a metadata recorder (#[derive(phoxal::Api)]’s linker-section splicing) can const-splice it without routing through Self::Api. Split from CONTRACT so consumers (the coherence gate and suite generator) record revision and contract as two separate fields rather than parsing a joined name.

Source

const CONTRACT: &'static str

This body’s contract path within its own version: the ::-joined node path (dynamic-node vars excluded, as with NAME) plus the PascalCase type leaf, e.g. "drive::Target". The logical contract - stable across a version bump - is this value alone; pairing it with VERSION recovers the full version-qualified identity (NAME).

Source

const TOPIC: &'static str

The version-qualified wire key: the dotted wire revision, then the /-joined node path plus the topic leaf, with each dynamic node contributing a {var} placeholder, e.g. "v0.1/drive/state" or "v0.1/component/{instance}/motor/{capability}/command". The concrete key is produced by the api-local topic builder, which fills the placeholders.

Required Associated Types§

Source

type Api: ApiVersion

The single API version this body belongs to. Two bodies from different versions have different Api, so the type system keeps them apart.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

ContractBody

Trait ContractBody Copy item path

Required Associated Constants§

const NAME: &'static str

const VERSION: &'static str

const CONTRACT: &'static str

const TOPIC: &'static str

Required Associated Types§

type Api: ApiVersion

Dyn Compatibility§

Implementors§

impl ContractBody for phoxal_api::v0_1::navigation::Candidate

const NAME: &'static str = "v0.1::navigation::Candidate"

const VERSION: &'static str = "v0.1"

const CONTRACT: &'static str = "navigation::Candidate"

const TOPIC: &'static str = "v0.1/navigation/candidate"

type Api = Api

impl ContractBody for phoxal_api::v0_2::navigation::Candidate

const NAME: &'static str = "v0.2::navigation::Candidate"

const VERSION: &'static str = "v0.2"

const CONTRACT: &'static str = "navigation::Candidate"

const TOPIC: &'static str = "v0.2/navigation/candidate"

type Api = Api

impl ContractBody for phoxal_api::v0_1::simulation::Clock

const NAME: &'static str = "v0.1::simulation::Clock"

const VERSION: &'static str = "v0.1"

const CONTRACT: &'static str = "simulation::Clock"

const TOPIC: &'static str = "v0.1/simulation/clock"

type Api = Api

impl ContractBody for phoxal_api::v0_2::simulation::Clock

const NAME: &'static str = "v0.2::simulation::Clock"

const VERSION: &'static str = "v0.2"

const CONTRACT: &'static str = "simulation::Clock"

const TOPIC: &'static str = "v0.2/simulation/clock"

type Api = Api

impl ContractBody for phoxal_api::v0_1::power::Command

const NAME: &'static str = "v0.1::power::Command"

const VERSION: &'static str = "v0.1"

const CONTRACT: &'static str = "power::Command"

const TOPIC: &'static str = "v0.1/power/command"

type Api = Api

impl ContractBody for phoxal_api::v0_1::behavior::Command

const NAME: &'static str = "v0.1::behavior::Command"

const VERSION: &'static str = "v0.1"

const CONTRACT: &'static str = "behavior::Command"

const TOPIC: &'static str = "v0.1/behavior/command"

type Api = Api

impl ContractBody for phoxal_api::v0_1::component::motor::Command

const NAME: &'static str = "v0.1::component::motor::Command"

const VERSION: &'static str = "v0.1"

const CONTRACT: &'static str = "component::motor::Command"

const TOPIC: &'static str = "v0.1/component/{instance}/motor/{capability}/command"

type Api = Api

impl ContractBody for phoxal_api::v0_1::component::led::Command

const NAME: &'static str = "v0.1::component::led::Command"

const VERSION: &'static str = "v0.1"

const CONTRACT: &'static str = "component::led::Command"

const TOPIC: &'static str = "v0.1/component/{instance}/led/{capability}/command"

type Api = Api

impl ContractBody for phoxal_api::v0_2::power::Command

const NAME: &'static str = "v0.2::power::Command"

const VERSION: &'static str = "v0.2"

const CONTRACT: &'static str = "power::Command"

const TOPIC: &'static str = "v0.2/power/command"

type Api = Api

impl ContractBody for phoxal_api::v0_2::behavior::Command

const NAME: &'static str = "v0.2::behavior::Command"

const VERSION: &'static str = "v0.2"

const CONTRACT: &'static str = "behavior::Command"

const TOPIC: &'static str = "v0.2/behavior/command"

type Api = Api

impl ContractBody for phoxal_api::v0_2::component::motor::Command

const NAME: &'static str = "v0.2::component::motor::Command"

const VERSION: &'static str = "v0.2"

const CONTRACT: &'static str = "component::motor::Command"

const TOPIC: &'static str = "v0.2/component/{instance}/motor/{capability}/command"

type Api = Api

impl ContractBody for phoxal_api::v0_2::component::led::Command

const NAME: &'static str = "v0.2::component::led::Command"

const VERSION: &'static str = "v0.2"

Trait ContractBody