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 {
25    pub entries: Vec<CanisterPoolEntryView>,
26}
27
28///
29/// CanisterPoolEntryView
30///
31
32#[derive(CandidType, Clone, Debug, Deserialize, Serialize)]
33pub struct CanisterPoolEntryView {
34    pub pid: Principal,
35    pub created_at: u64,
36    pub cycles: Cycles,
37    pub status: CanisterPoolStatusView,
38    pub role: Option<CanisterRole>,
39    pub parent: Option<Principal>,
40    pub module_hash: Option<Vec<u8>>,
41}
42
43///
44/// CanisterPoolStatusView
45///
46
47#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
48pub enum CanisterPoolStatusView {
49    PendingReset,
50    Ready,
51    Failed { reason: String },
52}
53
54///
55/// PoolAdminCommand
56///
57/// These represent *intent*, not execution.
58/// Validation and authorization are handled elsewhere.
59///
60
61#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
62pub enum PoolAdminCommand {
63    /// Create a fresh empty pool canister.
64    CreateEmpty,
65
66    /// Recycle an existing canister back into the pool.
67    Recycle { pid: Principal },
68
69    /// Import a canister into the pool immediately (synchronous).
70    ImportImmediate { pid: Principal },
71
72    /// Queue one or more canisters for pool import.
73    ImportQueued { pids: Vec<Principal> },
74}
75
76///
77/// PoolAdminResponse
78/// These describe *what happened*, not *how* it happened.
79///
80
81#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
82pub enum PoolAdminResponse {
83    /// A new pool canister was created.
84    Created { pid: Principal },
85
86    /// A canister was successfully recycled into the pool.
87    Recycled,
88
89    /// A canister was imported immediately.
90    Imported,
91
92    /// One or more canisters were queued for import.
93    QueuedImported { result: PoolBatchResult },
94
95    /// Failed pool entries were requeued.
96    FailedRequeued { 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}
canic_core/dto/pool.rs

canic_core/dto/
pool.rs
