ic_query/nns/governance/
request.rs

1//! Module: nns::governance::request
2//!
3//! Responsibility: describe one direct NNS Governance report collection.
4//! Does not own: live transport, report assembly, or persistence policy.
5//! Boundary: keeps caller intent separate from source-returned provenance.
6
7use crate::subnet_catalog::format_utc_timestamp_secs;
8use serde::{Deserialize, Serialize};
9
10///
11/// NnsGovernanceSourceSelection
12///
13/// Transport selected for one direct NNS Governance collection.
14///
15
16#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
17#[serde(tag = "source_transport", rename_all = "snake_case")]
18pub enum NnsGovernanceSourceSelection {
19    /// Submit an ordinary unreplicated query through one replica endpoint.
20    ReplicaQuery {
21        /// Replica endpoint selected by the caller.
22        endpoint: String,
23        /// Collector identity recorded in report provenance.
24        fetched_by: String,
25    },
26    /// Execute a replicated inter-canister call from the current canister.
27    ReplicatedInterCanisterCall,
28}
29
30///
31/// NnsGovernanceRequest
32///
33/// Network, timestamp, and transport selection for one Governance report.
34///
35
36#[derive(Clone, Debug, Eq, PartialEq)]
37pub struct NnsGovernanceRequest {
38    /// Network to query.
39    pub network: String,
40    /// UTC collection timestamp recorded in the report.
41    pub fetched_at: String,
42    /// Requested source transport.
43    pub source: NnsGovernanceSourceSelection,
44}
45
46impl NnsGovernanceRequest {
47    /// Create a replica-query request with an explicit UTC timestamp.
48    #[must_use]
49    pub fn replica_query(
50        network: impl Into<String>,
51        endpoint: impl Into<String>,
52        fetched_at: impl Into<String>,
53        fetched_by: impl Into<String>,
54    ) -> Self {
55        Self {
56            network: network.into(),
57            fetched_at: fetched_at.into(),
58            source: NnsGovernanceSourceSelection::ReplicaQuery {
59                endpoint: endpoint.into(),
60                fetched_by: fetched_by.into(),
61            },
62        }
63    }
64
65    /// Create a replica-query request from a Unix collection timestamp.
66    #[must_use]
67    pub fn replica_query_from_unix_secs(
68        network: impl Into<String>,
69        endpoint: impl Into<String>,
70        fetched_at_unix_secs: u64,
71        fetched_by: impl Into<String>,
72    ) -> Self {
73        Self::replica_query(
74            network,
75            endpoint,
76            format_utc_timestamp_secs(fetched_at_unix_secs),
77            fetched_by,
78        )
79    }
80
81    /// Create a replicated inter-canister-call request with an explicit UTC timestamp.
82    #[must_use]
83    pub fn replicated_inter_canister_call(
84        network: impl Into<String>,
85        fetched_at: impl Into<String>,
86    ) -> Self {
87        Self {
88            network: network.into(),
89            fetched_at: fetched_at.into(),
90            source: NnsGovernanceSourceSelection::ReplicatedInterCanisterCall,
91        }
92    }
93
94    /// Create a replicated inter-canister-call request from a Unix collection timestamp.
95    #[must_use]
96    pub fn replicated_inter_canister_call_from_unix_secs(
97        network: impl Into<String>,
98        fetched_at_unix_secs: u64,
99    ) -> Self {
100        Self::replicated_inter_canister_call(
101            network,
102            format_utc_timestamp_secs(fetched_at_unix_secs),
103        )
104    }
105}
ic_query/nns/governance/request.rs

ic_query/nns/governance/
request.rs
