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
21//
22// CanisterPoolResponse
23// Read-only pool snapshot for endpoints.
24//
25
26#[derive(CandidType, Clone, Debug, Deserialize)]
27pub struct CanisterPoolResponse {
28    pub entries: Vec<CanisterPoolEntry>,
29}
30
31//
32// CanisterPoolEntry
33//
34
35#[derive(CandidType, Clone, Debug, Deserialize)]
36pub struct CanisterPoolEntry {
37    pub pid: Principal,
38    pub created_at: u64,
39    pub cycles: Cycles,
40    pub status: CanisterPoolStatus,
41    pub role: Option<CanisterRole>,
42    pub parent: Option<Principal>,
43    pub module_hash: Option<Vec<u8>>,
44}
45
46//
47// CanisterPoolStatus
48//
49
50#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
51pub enum CanisterPoolStatus {
52    PendingReset,
53    Ready,
54    Failed { reason: String },
55}
56
57//
58// PoolAdminCommand
59//
60// These represent *intent*, not execution.
61// Validation and authorization are handled elsewhere.
62//
63
64#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
65pub enum PoolAdminCommand {
66    // Create a fresh empty pool canister.
67    CreateEmpty(CreateEmptyPoolRequest),
68
69    // Recycle an existing canister back into the pool.
70    Recycle { pid: Principal },
71
72    // Import a canister into the pool immediately (synchronous).
73    ImportImmediate { pid: Principal },
74
75    // Queue one or more canisters for pool import.
76    ImportQueued { pids: Vec<Principal> },
77}
78
79//
80// CreateEmptyPoolRequest
81//
82
83#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
84pub struct CreateEmptyPoolRequest {
85    #[serde(default)]
86    pub metadata: Option<RootRequestMetadata>,
87}
88
89//
90// PoolAdminResponse
91// These describe *what happened*, not *how* it happened.
92//
93
94#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
95pub enum PoolAdminResponse {
96    // A new pool canister was created.
97    Created { pid: Principal },
98
99    // A canister was successfully recycled into the pool.
100    Recycled,
101
102    // A canister was imported immediately.
103    Imported,
104
105    // One or more canisters were queued for import.
106    QueuedImported { result: PoolBatchResult },
107
108    // Failed pool entries were requeued.
109    FailedRequeued { result: PoolBatchResult },
110}
111
112//
113// PoolBatchResult
114//
115
116#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
117pub struct PoolBatchResult {
118    pub total: u64,
119    pub added: u64,
120    pub requeued: u64,
121    pub skipped: u64,
122}
canic_core/dto/pool.rs

canic_core/dto/
pool.rs
