canic-core 0.110.54

Canic — a canister orchestration and management toolkit for the Internet Computer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

//! Module: workflow::placement::index::classification
//!
//! Responsibility: classify index entries for resolve and recovery flows.
//! Does not own: storage mutation, child creation, or recovery side effects.
//! Boundary: maps registry state into workflow-only classification outcomes.

use crate::{
    config::schema::IndexPool,
    ops::{
        runtime::metrics::{
            placement_index::{
                PlacementIndexMetricOperation as MetricOperation,
                PlacementIndexMetricReason as MetricReason,
            },
            recording::PlacementIndexMetricEvent as MetricEvent,
        },
        storage::placement::index::{PlacementIndexEntryState, PlacementIndexRegistryOps},
    },
    workflow::placement::index::{
        PlacementIndexWorkflow,
        state::{
            PlacementIndexEntryClassification, pending_is_stale, validate_bind_target_with_reason,
        },
    },
};

impl PlacementIndexWorkflow {
    // Classify the current entry once so resolve and recovery follow the same stale/repair rules.
    pub(super) fn classify_entry(
        pool: &str,
        key_value: &str,
        pool_cfg: &IndexPool,
        now: u64,
    ) -> Option<PlacementIndexEntryClassification> {
        let Some(state) = PlacementIndexRegistryOps::lookup_state(pool, key_value) else {
            MetricEvent::completed(MetricOperation::Classify, MetricReason::Missing);
            return None;
        };

        if matches!(&state, PlacementIndexEntryState::Bound { .. })
            && !PlacementIndexRegistryOps::binding_is_current(pool, key_value)
        {
            return Some(PlacementIndexEntryClassification::Unavailable);
        }
        let classification = match state {
            PlacementIndexEntryState::Bound {
                instance_pid,
                bound_at,
            } => PlacementIndexEntryClassification::Bound {
                instance_pid,
                bound_at,
            },

            PlacementIndexEntryState::Pending {
                claim_id,
                owner_pid,
                created_at,
                provisional_pid,
            } if !pending_is_stale(now, created_at) => {
                PlacementIndexEntryClassification::PendingFresh {
                    claim_id,
                    owner_pid,
                    created_at,
                    provisional_pid,
                }
            }

            PlacementIndexEntryState::Pending {
                claim_id,
                owner_pid,
                created_at,
                provisional_pid: None,
            } => PlacementIndexEntryClassification::Resumable {
                claim_id,
                owner_pid,
                created_at,
            },

            PlacementIndexEntryState::Pending {
                claim_id,
                owner_pid,
                provisional_pid: Some(pid),
                ..
            } if validate_bind_target_with_reason(pid, &pool_cfg.canister_role).is_ok()
                && crate::ops::storage::children::CanisterChildrenOps::matches_allocation(
                    pid,
                    crate::model::placement::allocation::PlacementAllocationIdentity::index(
                        owner_pid,
                        pool,
                        key_value,
                        claim_id,
                        &pool_cfg.canister_role,
                        None,
                    )
                    .operation_id
                    .into_bytes(),
                ) =>
            {
                PlacementIndexEntryClassification::Repairable {
                    claim_id,
                    owner_pid,
                    provisional_pid: pid,
                }
            }

            PlacementIndexEntryState::Pending {
                claim_id,
                owner_pid,
                provisional_pid: Some(provisional_pid),
                ..
            } => PlacementIndexEntryClassification::NeedsCleanup {
                claim_id,
                owner_pid,
                provisional_pid,
            },
        };

        MetricEvent::completed(
            MetricOperation::Classify,
            Self::classification_reason(&classification),
        );
        Some(classification)
    }

    // Map an internal index entry classification to the public metric reason vocabulary.
    const fn classification_reason(
        classification: &PlacementIndexEntryClassification,
    ) -> MetricReason {
        match classification {
            PlacementIndexEntryClassification::Unavailable => MetricReason::InvalidChild,
            PlacementIndexEntryClassification::Bound { .. } => MetricReason::AlreadyBound,
            PlacementIndexEntryClassification::PendingFresh { .. } => MetricReason::PendingFresh,
            PlacementIndexEntryClassification::Repairable { .. } => MetricReason::StaleRepairable,
            PlacementIndexEntryClassification::Resumable { .. } => MetricReason::ResumedPending,
            PlacementIndexEntryClassification::NeedsCleanup { .. } => MetricReason::StaleCleanup,
        }
    }
}