canic_core/dto/
pool.rs

1//! Pool admin DTOs.
2//!
3//! This module defines the command and response types used at the
4//! boundary of the pool workflow (endpoints, admin APIs).
5//!
6//! These types:
7//! - are pure data
8//! - contain no logic
9//! - are safe to serialize / expose
10//!
11//! They must NOT:
12//! - perform validation
13//! - call ops or workflow
14//! - embed policy or orchestration logic
15
16use crate::{
17    cdk::types::Cycles,
18    dto::{prelude::*, rpc::RootRequestMetadata},
19};
20
21pub use crate::domain::pool::CanisterPoolStatus;
22
23//
24// CanisterPoolResponse
25// Read-only pool snapshot for endpoints.
26//
27
28#[derive(CandidType, Clone, Debug, Deserialize)]
29pub struct CanisterPoolResponse {
30    pub entries: Vec<CanisterPoolEntry>,
31}
32
33//
34// CanisterPoolEntry
35//
36
37#[derive(CandidType, Clone, Debug, Deserialize)]
38pub struct CanisterPoolEntry {
39    pub pid: Principal,
40    pub created_at: u64,
41    pub cycles: Cycles,
42    pub status: CanisterPoolStatus,
43    pub role: Option<CanisterRole>,
44    pub parent: Option<Principal>,
45    pub module_hash: Option<Vec<u8>>,
46}
47
48//
49// PoolAdminCommand
50//
51// These represent *intent*, not execution.
52// Validation and authorization are handled elsewhere.
53//
54
55#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
56pub enum PoolAdminCommand {
57    // Create a fresh empty pool canister.
58    CreateEmpty(CreateEmptyPoolRequest),
59
60    // Recycle an existing canister back into the pool.
61    Recycle { pid: Principal },
62
63    // Import a canister into the pool immediately (synchronous).
64    ImportImmediate { pid: Principal },
65
66    // Queue one or more canisters for pool import.
67    ImportQueued { pids: Vec<Principal> },
68}
69
70//
71// CreateEmptyPoolRequest
72//
73
74#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
75pub struct CreateEmptyPoolRequest {
76    pub metadata: Option<RootRequestMetadata>,
77}
78
79//
80// PoolAdminResponse
81// These describe *what happened*, not *how* it happened.
82//
83
84#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
85pub enum PoolAdminResponse {
86    // A new pool canister was created.
87    Created { pid: Principal },
88
89    // A canister was successfully recycled into the pool.
90    Recycled,
91
92    // A canister was imported immediately.
93    Imported,
94
95    // One or more canisters were queued for import.
96    QueuedImported { result: PoolBatchResult },
97}
98
99//
100// PoolBatchResult
101//
102
103#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
104pub struct PoolBatchResult {
105    pub total: u64,
106    pub added: u64,
107    pub requeued: u64,
108    pub skipped: u64,
109}
110
111#[cfg(test)]
112mod tests {
113    use super::*;
114
115    #[test]
116    fn reexported_pool_status_roundtrips_through_candid() {
117        let entry = CanisterPoolEntry {
118            pid: Principal::from_slice(&[3; 29]),
119            created_at: 42,
120            cycles: Cycles::new(10_000),
121            status: crate::domain::pool::CanisterPoolStatus::Failed {
122                reason: "bounded reset failure".to_string(),
123            },
124            role: Some(CanisterRole::new("worker")),
125            parent: None,
126            module_hash: Some(vec![1, 2, 3]),
127        };
128
129        let bytes = candid::encode_one(&entry).expect("encode pool entry");
130        let decoded: CanisterPoolEntry = candid::decode_one(&bytes).expect("decode pool entry");
131
132        let dto_status: CanisterPoolStatus = crate::domain::pool::CanisterPoolStatus::Failed {
133            reason: "bounded reset failure".to_string(),
134        };
135
136        assert_eq!(decoded.pid, Principal::from_slice(&[3; 29]));
137        assert_eq!(decoded.created_at, 42);
138        assert_eq!(decoded.cycles, Cycles::new(10_000));
139        assert_eq!(decoded.status, dto_status);
140        assert_eq!(decoded.role, Some(CanisterRole::new("worker")));
141        assert_eq!(decoded.parent, None);
142        assert_eq!(decoded.module_hash, Some(vec![1, 2, 3]));
143    }
144}
canic_core/dto/pool.rs

canic_core/dto/
pool.rs
