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 / persist / expose
10//!
11//! They must NOT:
12//! - perform validation
13//! - call ops or workflow
14//! - embed policy or orchestration logic
15
16use crate::{cdk::types::Cycles, dto::prelude::*};
17
18///
19/// CanisterPoolView
20/// Read-only pool snapshot for endpoints.
21///
22
23#[derive(CandidType, Clone, Debug, Deserialize, Serialize)]
24pub struct CanisterPoolView(pub Vec<(Principal, CanisterPoolEntryView)>);
25
26///
27/// CanisterPoolStatusView
28///
29
30#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
31pub enum CanisterPoolStatusView {
32    PendingReset,
33    Ready,
34    Failed { reason: String },
35}
36
37///
38/// CanisterPoolEntryView
39///
40
41#[derive(CandidType, Clone, Debug, Deserialize, Serialize)]
42pub struct CanisterPoolEntryView {
43    pub created_at: u64,
44    pub cycles: Cycles,
45    pub status: CanisterPoolStatusView,
46    pub role: Option<CanisterRole>,
47    pub parent: Option<Principal>,
48    pub module_hash: Option<Vec<u8>>,
49}
50
51///
52/// PoolAdminCommand
53///
54/// These represent *intent*, not execution.
55/// Validation and authorization are handled elsewhere.
56///
57
58#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
59pub enum PoolAdminCommand {
60    /// Create a fresh empty pool canister.
61    CreateEmpty,
62
63    /// Recycle an existing canister back into the pool.
64    Recycle { pid: Principal },
65
66    /// Import a canister into the pool immediately (synchronous).
67    ImportImmediate { pid: Principal },
68
69    /// Queue one or more canisters for pool import.
70    ImportQueued { pids: Vec<Principal> },
71}
72
73///
74/// PoolAdminResponse
75/// These describe *what happened*, not *how* it happened.
76///
77
78#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
79pub enum PoolAdminResponse {
80    /// A new pool canister was created.
81    Created { pid: Principal },
82
83    /// A canister was successfully recycled into the pool.
84    Recycled,
85
86    /// A canister was imported immediately.
87    Imported,
88
89    /// One or more canisters were queued for import.
90    QueuedImported { result: PoolBatchResult },
91
92    /// Failed pool entries were requeued.
93    FailedRequeued { result: PoolBatchResult },
94}
95
96///
97/// PoolBatchResult
98///
99
100#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
101pub struct PoolBatchResult {
102    pub total: u64,
103    pub added: u64,
104    pub requeued: u64,
105    pub skipped: u64,
106}
canic_core/dto/pool.rs

canic_core/dto/
pool.rs
