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}