phoxal 0.26.0

Phoxal - production-oriented autonomous robot framework: the runtime engine and model (the api contract tree lives in phoxal-api, the typed bus in phoxal-bus).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

//! The `emit-apis` metadata (D50/D57).
//!
//! Every service, driver, tool, and simulator binary exposes a top-level
//! `emit-apis` subcommand that serializes its compiled-in static metadata to
//! stdout as exactly one JSON document and exits - before loading robot config,
//! `.env`, tracing, Zenoh, or running `#[setup]`. `phoxal-cli check`/`deploy
//! build` run it on the resolved artifacts; there is no release descriptor or
//! sidecar file (D57).
//!
//! The emitted JSON schema is **frozen** (fields below). Adding a field is
//! backward-compatible; renaming/removing one is a `bus_abi`/schema change.

use std::collections::BTreeSet;

use serde::Serialize;

use crate::bus::BUS_ABI;
use crate::participant::spec::{ContractUse, Direction, ParticipantBehavior};

/// The frozen emitted-metadata schema id.
pub const EMIT_SCHEMA: &str = "phoxal.emit-apis/v0";

/// The single JSON document `emit-apis` prints (frozen field set).
#[derive(Debug, Serialize)]
pub struct ParticipantMetadata {
    /// The emitted-schema id.
    pub schema: &'static str,
    /// What this artifact is.
    pub artifact: Artifact,
    /// The framework version that built it.
    pub framework: Framework,
    /// The one API version the artifact runs against.
    pub api_version: String,
    /// Whether normal graph topology applies to this participant.
    pub participant_class: &'static str,
    /// The framework-owned wire-envelope id.
    pub bus_abi: String,
    /// The union of field-side + server-side contracts.
    pub required_contracts: Vec<ContractView>,
    /// The participant's JSON Schema config contract.
    pub config_schema: serde_json::Value,
}

/// Artifact identity.
#[derive(Debug, Serialize)]
pub struct Artifact {
    /// `service` | `driver` | `tool` | `simulator`.
    pub kind: &'static str,
    /// The artifact id (the participant id).
    pub id: String,
}

/// Framework provenance.
#[derive(Debug, Serialize)]
pub struct Framework {
    /// The phoxal framework version.
    pub version: String,
}

/// One contract in the emitted document.
#[derive(Debug, Serialize)]
pub struct ContractView {
    /// API version this contract body belongs to.
    pub api_version: String,
    /// Transitive wire-shape id for this contract body.
    pub schema_id: String,
    /// Contract family id.
    pub family: String,
    /// Versionless topic key.
    pub topic: String,
    /// Direction of use.
    pub direction: Direction,
}

impl From<&ContractUse> for ContractView {
    fn from(c: &ContractUse) -> Self {
        ContractView {
            api_version: c.api_version.to_string(),
            schema_id: c.schema_id.to_string(),
            family: c.family.to_string(),
            topic: c.topic.to_string(),
            direction: c.direction,
        }
    }
}

/// Build the metadata document for a participant `R`.
pub fn participant_metadata<R: ParticipantBehavior>() -> ParticipantMetadata {
    let mut seen = BTreeSet::new();
    let required_contracts = R::FIELD_CONTRACTS
        .iter()
        .chain(R::SERVER_CONTRACTS.iter())
        .filter(|contract| {
            seen.insert((
                contract.api_version.to_string(),
                contract.schema_id.to_string(),
                contract.family.to_string(),
                contract.topic.to_string(),
                contract.direction,
            ))
        })
        .map(ContractView::from)
        .collect();

    ParticipantMetadata {
        schema: EMIT_SCHEMA,
        artifact: Artifact {
            kind: R::KIND,
            id: R::ID.to_string(),
        },
        framework: Framework {
            version: env!("CARGO_PKG_VERSION").to_string(),
        },
        api_version: R::API_VERSION.to_string(),
        participant_class: R::PARTICIPANT_CLASS,
        bus_abi: BUS_ABI.id().to_string(),
        required_contracts,
        config_schema: serde_json::to_value(schemars::schema_for!(R::Config))
            .expect("config JSON schema is always serializable"),
    }
}

/// Serialize a participant's metadata to a pretty JSON string.
pub fn emit_apis_json<R: ParticipantBehavior>() -> String {
    serde_json::to_string_pretty(&participant_metadata::<R>())
        .expect("ParticipantMetadata is always serializable")
}

/// Print a participant's metadata as one JSON document to stdout.
pub fn print_emit_apis<R: ParticipantBehavior>() {
    println!("{}", emit_apis_json::<R>());
}