ic_query/subnet_catalog/
mod.rs

1//! Cached NNS subnet catalog models, resolution helpers, builders.
2
3mod error;
4#[cfg(feature = "subnet-catalog-host")]
5mod host;
6mod json;
7mod model;
8mod principal;
9#[cfg(feature = "subnet-catalog-host")]
10mod report;
11mod resolver;
12#[cfg(feature = "subnet-catalog-host")]
13mod time;
14
15#[cfg(feature = "subnet-catalog-host")]
16pub use crate::ic_registry::RegistryHistoryCacheDisposition;
17#[cfg(feature = "subnet-catalog-host")]
18pub use crate::ic_registry::{SubnetCatalogProgress, SubnetCatalogProgressPhase};
19pub use error::CatalogError;
20#[cfg(feature = "subnet-catalog-host")]
21pub(crate) use host::subject_from_catalog_error;
22#[cfg(feature = "subnet-catalog-host")]
23pub use host::{
24    CacheDisposition, CatalogLoadOutcome, CatalogReadPolicy, CatalogSourceSelection,
25    LiveSubnetCatalogSource, SubnetCatalogCacheRequest, SubnetCatalogDetailedSourceFuture,
26    SubnetCatalogErrorCategory, SubnetCatalogErrorCode, SubnetCatalogFailureCacheDisposition,
27    SubnetCatalogFailureEvidence, SubnetCatalogField, SubnetCatalogHostError,
28    SubnetCatalogLoadFailure, SubnetCatalogLoadFailureRequest, SubnetCatalogLoadRequest,
29    SubnetCatalogLoadStage, SubnetCatalogRefreshRequest, SubnetCatalogRefreshTrigger,
30    SubnetCatalogRemediation, SubnetCatalogRetryability, SubnetCatalogSource,
31    SubnetCatalogSourceFailure, SubnetCatalogSourceFuture, SubnetCatalogSubject,
32    SubnetCatalogUnknownRetryReason, fetch_subnet_catalog_async, load_cached_subnet_catalog,
33    load_subnet_catalog, load_subnet_catalog_with_source,
34    load_subnet_catalog_with_source_and_progress, refresh_subnet_catalog,
35    refresh_subnet_catalog_with_source, subnet_catalog_path, subnet_catalog_refresh_lock_path,
36};
37#[cfg(feature = "subnet-catalog-host")]
38pub(crate) use host::{subnet_catalog_history_lock_path, subnet_catalog_history_path};
39
40pub use json::{catalog_to_pretty_json, parse_catalog_json};
41#[cfg(feature = "subnet-catalog-host")]
42pub use model::UncertifiedCatalogCollection;
43#[cfg(feature = "certified-subnet-catalog-host")]
44pub(crate) use model::canonicalize_subnet_catalog_content;
45#[cfg(feature = "subnet-catalog-host")]
46pub(in crate::subnet_catalog) use model::catalog_agreement_digest;
47pub use model::{
48    CANISTER_RANGES_KEY_PREFIX, CLASSIFICATION_SCHEMA_VERSION, CatalogAssurance,
49    CatalogSnapshotAuthorityEvidence, CatalogValidationContext, CertifiedRegistryCatalogEvidence,
50    ClassificationSource, GeographicScope, RESOLVER_SCHEMA_VERSION, ROUTING_TABLE_KEY,
51    RawSubnetCatalog, RoutingRange, SUBNET_LIST_KEY, SUBNET_RECORD_KEY_PREFIX,
52    SubnetCatalogProvenance, SubnetCatalogRegistryRecordEvidence, SubnetCatalogRegistryRecordKind,
53    SubnetCatalogRegistryRecordSubject, SubnetCatalogRegistryValueEncoding,
54    SubnetCatalogRoutingSource, SubnetClassification, SubnetInfo, SubnetKind, SubnetSpecialization,
55    ValidatedSubnetCatalog,
56};
57pub use principal::canonical_principal_text;
58pub(crate) use principal::{parse_principal, principal_bytes};
59#[cfg(feature = "subnet-catalog-host")]
60pub use report::{
61    CatalogStaleStatus, SubnetCatalogFilters, SubnetCatalogInfoReport, SubnetCatalogInfoRequest,
62    SubnetCatalogListReport, SubnetCatalogListRequest, SubnetCatalogRefreshReport,
63    SubnetCatalogReportMetadata, SubnetCatalogSubnetRow, build_subnet_catalog_info_report,
64    build_subnet_catalog_info_report_with_progress, build_subnet_catalog_info_report_with_source,
65    build_subnet_catalog_info_report_with_source_and_progress, build_subnet_catalog_list_report,
66    build_subnet_catalog_list_report_with_progress, build_subnet_catalog_list_report_with_source,
67    build_subnet_catalog_list_report_with_source_and_progress,
68};
69pub use resolver::{ResolveAs, ResolvedCanisterRoute, ResolvedSubnet, ResolvedSubnetSubject};
70#[cfg(feature = "subnet-catalog-host")]
71pub use time::catalog_stale_status;
72
73/// Current persisted Subnet Catalog schema identifier; remains `1` before package 1.0.
74pub const CATALOG_SCHEMA_VERSION: u32 = 1;
75/// Network identity used by all mainnet catalog requests and snapshots.
76pub const MAINNET_NETWORK: &str = "ic";
77/// Canonical principal of the mainnet Registry canister.
78pub const MAINNET_REGISTRY_CANISTER_ID: &str = "rwlgt-iiaaa-aaaaa-aaaaa-cai";
79#[cfg(feature = "subnet-catalog-host")]
80/// Maximum future timestamp skew accepted by default during catalog validation.
81pub const DEFAULT_CATALOG_MAX_FUTURE_SKEW_SECONDS: u64 = 5 * 60;
82/// Default snapshot age threshold in seconds for reporting stale catalog data.
83#[cfg(feature = "subnet-catalog-host")]
84pub const DEFAULT_STALE_AFTER_SECONDS: u64 = 7 * 24 * 60 * 60;
85/// Default replica endpoint used for live Registry catalog collection.
86#[cfg(feature = "subnet-catalog-host")]
87pub const DEFAULT_SUBNET_CATALOG_SOURCE_ENDPOINT: &str = "https://icp-api.io";
88#[cfg(feature = "subnet-catalog-host")]
89/// Minimum number of independent hosts required for endpoint agreement.
90pub const MIN_SUBNET_CATALOG_AGREEMENT_ENDPOINTS: usize = 2;
91#[cfg(feature = "subnet-catalog-host")]
92/// Maximum number of endpoints accepted by one bounded agreement collection.
93pub const MAX_SUBNET_CATALOG_AGREEMENT_ENDPOINTS: usize = 3;
94#[cfg(feature = "subnet-catalog-host")]
95pub(crate) const SUBNET_CATALOG_LIST_REPORT_SCHEMA_VERSION: u32 = 1;
96#[cfg(feature = "subnet-catalog-host")]
97pub(crate) const SUBNET_CATALOG_INFO_REPORT_SCHEMA_VERSION: u32 = 1;
98#[cfg(feature = "subnet-catalog-host")]
99pub(crate) const SUBNET_CATALOG_REFRESH_REPORT_SCHEMA_VERSION: u32 = 1;
100
101#[cfg(test)]
102mod core_tests;
103#[cfg(all(test, feature = "subnet-catalog-host"))]
104mod tests;
ic_query/subnet_catalog/mod.rs

ic_query/subnet_catalog/
mod.rs
