ic_query/ic/api_boundary_node/
model.rs

1//! Module: ic::api_boundary_node::model
2//!
3//! Responsibility: certified API boundary-node requests, evidence, reports, and host errors.
4//! Does not own: state-tree collection, validation, command parsing, or text rendering.
5//! Boundary: preserves authenticated node identities, domains, addresses, and certificate time.
6
7#[cfg(feature = "ic-state-host")]
8use crate::runtime::RuntimeError;
9use serde::Serialize;
10#[cfg(feature = "ic-state-host")]
11use thiserror::Error as ThisError;
12
13///
14/// IcApiBoundaryNodeRequest
15///
16/// Caller request for the complete certified API boundary-node state-tree collection.
17///
18
19#[derive(Clone, Debug, Eq, PartialEq)]
20pub struct IcApiBoundaryNodeRequest {
21    /// Mainnet IC API endpoint used for the certified `read_state` request.
22    pub source_endpoint: String,
23    /// Caller observation time as Unix seconds.
24    pub now_unix_secs: u64,
25}
26
27impl IcApiBoundaryNodeRequest {
28    /// Construct one live certified API boundary-node request.
29    #[must_use]
30    pub fn new(source_endpoint: impl Into<String>, now_unix_secs: u64) -> Self {
31        Self {
32            source_endpoint: source_endpoint.into(),
33            now_unix_secs,
34        }
35    }
36}
37
38///
39/// IcCertifiedStateProvenance
40///
41/// Certificate and retrieval provenance for one authenticated IC state-tree report.
42///
43
44#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
45pub struct IcCertifiedStateProvenance {
46    /// Emitted report schema version.
47    pub schema_version: u32,
48    /// Network identity authenticated by the built-in mainnet root key.
49    pub network: String,
50    /// Stable authority label for certified IC state-tree evidence.
51    pub authority: String,
52    /// IC API endpoint that returned the certificate.
53    pub source_endpoint: String,
54    /// Canister principal used only to route the `read_state` request.
55    pub effective_canister_id: String,
56    /// Caller observation time as Unix seconds.
57    pub fetched_at_unix_seconds: u64,
58    /// Caller observation time formatted in UTC.
59    pub fetched_at: String,
60    /// Collector identity.
61    pub fetched_by: String,
62    /// Raw certified state-tree time as Unix nanoseconds.
63    pub certificate_time_unix_nanos: u64,
64    /// Certified state-tree time rounded down to Unix seconds.
65    pub certificate_time_unix_seconds: u64,
66    /// Certified state-tree time formatted in UTC at second precision.
67    pub certificate_time: String,
68    /// Whether the report rows are authenticated by an IC certificate.
69    pub certified: bool,
70    /// Whether the returned rows belong to one certified state-tree time.
71    pub point_in_time_guaranteed: bool,
72}
73
74///
75/// IcApiBoundaryNodeRow
76///
77/// One API boundary node authenticated by the certified IC state tree.
78///
79
80#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
81pub struct IcApiBoundaryNodeRow {
82    /// Canonical API boundary-node principal.
83    pub node_id: String,
84    /// Certified DNS domain.
85    pub domain: String,
86    /// Optional certified IPv4 address.
87    pub ipv4_address: Option<String>,
88    /// Certified IPv6 address.
89    pub ipv6_address: String,
90}
91
92///
93/// IcApiBoundaryNodeReport
94///
95/// Complete API boundary-node collection from one authenticated IC state tree.
96///
97
98#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
99pub struct IcApiBoundaryNodeReport {
100    /// Certificate and retrieval provenance, flattened in serialized report JSON.
101    #[serde(flatten)]
102    pub provenance: IcCertifiedStateProvenance,
103    /// Number of authenticated API boundary-node rows.
104    pub node_count: usize,
105    /// Rows in canonical node-principal order.
106    pub rows: Vec<IcApiBoundaryNodeRow>,
107}
108
109///
110/// IcApiBoundaryNodeSourceRequest
111///
112/// Exact state-tree request and collection provenance supplied to a host source.
113///
114
115#[cfg(feature = "ic-state-host")]
116#[derive(Clone, Debug, Eq, PartialEq)]
117pub struct IcApiBoundaryNodeSourceRequest {
118    /// Fixed mainnet network identity.
119    pub network: String,
120    /// IC API endpoint used for `read_state`.
121    pub endpoint: String,
122    /// Canister principal used only to route the request.
123    pub effective_canister_id: String,
124    /// Caller observation time as Unix seconds.
125    pub observed_at_unix_seconds: u64,
126    /// Caller observation time formatted in UTC.
127    pub fetched_at: String,
128    /// Collector identity.
129    pub fetched_by: String,
130}
131
132///
133/// IcApiBoundaryNodeSourceData
134///
135/// Authenticated state-tree evidence returned by an API boundary-node source.
136///
137
138#[cfg(feature = "ic-state-host")]
139#[derive(Clone, Debug, Eq, PartialEq)]
140pub struct IcApiBoundaryNodeSourceData {
141    /// Exact source request echoed by the source.
142    pub source: IcApiBoundaryNodeSourceRequest,
143    /// Raw certified state-tree time as Unix nanoseconds.
144    pub certificate_time_unix_nanos: u64,
145    /// Authenticated API boundary-node rows.
146    pub rows: Vec<IcApiBoundaryNodeRow>,
147}
148
149///
150/// IcApiBoundaryNodeHostError
151///
152/// Failure while collecting or projecting certified API boundary-node evidence.
153///
154
155#[cfg(feature = "ic-state-host")]
156#[derive(Debug, ThisError)]
157pub enum IcApiBoundaryNodeHostError {
158    /// The synchronous adapter could not create its local async runtime.
159    #[error("failed to run certified IC state query: {0}")]
160    Runtime(#[from] RuntimeError),
161
162    /// The response-bounded IC agent could not be constructed.
163    #[error("failed to build IC state agent for {endpoint}: {reason}")]
164    AgentBuild {
165        /// Rejected endpoint.
166        endpoint: String,
167        /// Agent or endpoint diagnostic.
168        reason: String,
169    },
170
171    /// The certified `read_state` request or certificate authentication failed.
172    #[error("certified IC state read through {endpoint} failed: {reason}")]
173    CertifiedReadState {
174        /// Endpoint used for the request.
175        endpoint: String,
176        /// Transport, decoding, delegation, signature, or age diagnostic.
177        reason: String,
178    },
179
180    /// The authenticated state tree did not match the specified boundary-node contract.
181    #[error("invalid certified IC state-tree data: {reason}")]
182    InvalidCertifiedState {
183        /// Deterministic state-tree validation diagnostic.
184        reason: String,
185    },
186
187    /// A source capability returned inconsistent request or report data.
188    #[error("invalid API boundary-node source data: {reason}")]
189    InvalidSourceData {
190        /// Deterministic source-contract diagnostic.
191        reason: String,
192    },
193}
ic_query/ic/api_boundary_node/model.rs

ic_query/ic/api_boundary_node/
model.rs
