Skip to main content

ic_query/subnet_catalog/resolver/
model.rs

1//! Module: subnet_catalog::resolver::model
2//!
3//! Defines resolver options and outputs for subnet catalog lookups.
4
5use crate::subnet_catalog::{RoutingRange, SubnetCatalogProvenance, SubnetInfo};
6use ic_platform_types::Principal;
7use serde::{Deserialize, Serialize};
8use std::str::FromStr;
9
10///
11/// ResolveAs
12///
13/// Principal interpretation requested by a caller or selected by the resolver.
14///
15
16#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
17#[serde(rename_all = "snake_case")]
18pub enum ResolveAs {
19    /// Resolve the input as a subnet principal.
20    Subnet,
21    /// Resolve the input as a canister principal.
22    Canister,
23}
24
25impl ResolveAs {
26    /// Returns the stable snake_case value used in CLI options and reports.
27    #[must_use]
28    pub const fn as_str(self) -> &'static str {
29        match self {
30            Self::Subnet => "subnet",
31            Self::Canister => "canister",
32        }
33    }
34}
35
36impl FromStr for ResolveAs {
37    type Err = String;
38
39    fn from_str(value: &str) -> Result<Self, Self::Err> {
40        match value {
41            "subnet" => Ok(Self::Subnet),
42            "canister" => Ok(Self::Canister),
43            other => Err(format!("invalid value {other}; use subnet or canister")),
44        }
45    }
46}
47
48///
49/// ResolvedSubnet
50///
51/// Resolved subnet match and the evidence used to produce it.
52///
53
54#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
55pub struct ResolvedSubnet {
56    /// Canonical principal resolved from the supplied subject.
57    pub input_principal: String,
58    /// Whether resolution treated the subject as a Subnet or a canister.
59    pub resolved_as: ResolveAs,
60    /// Resolution evidence label: a Subnet principal match or a routing range.
61    pub resolved_from: String,
62    /// Resolved Subnet record with its Registry type and classification annotations.
63    pub subnet: SubnetInfo,
64    /// Exact canonical canister principal for a canister subject; absent for a Subnet subject.
65    pub matched_canister_principal: Option<String>,
66    /// Inclusive routing authority range used for a canister subject.
67    pub matched_routing_range: Option<RoutingRange>,
68    /// Lowercase SHA-256 digest of the raw catalog supplying the match.
69    pub catalog_digest: String,
70    /// Complete provenance supplied by the raw catalog.
71    pub provenance: SubnetCatalogProvenance,
72}
73
74///
75/// ResolvedCanisterRoute
76///
77/// Authority-bearing route tied to the exact validated catalog that proved it.
78///
79
80#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
81pub struct ResolvedCanisterRoute {
82    /// Canonical canister principal resolved through the routing table.
83    pub canister: Principal,
84    /// Canonical target Subnet principal.
85    pub subnet: Principal,
86    /// Complete validated Subnet classification matched by the route.
87    pub subnet_info: SubnetInfo,
88    /// Inclusive validated range containing the canister principal.
89    pub matched_range: RoutingRange,
90    /// Exact Registry version of the validated catalog.
91    pub registry_version: u64,
92    /// Binary SHA-256 digest of the validated catalog authority payload.
93    pub catalog_digest: [u8; 32],
94    /// Complete provenance of the validated catalog.
95    pub provenance: SubnetCatalogProvenance,
96}