canic-core 0.69.5

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

//! Module: access::metrics
//!
//! Responsibility: expose the approved access-layer metrics facade.
//! Does not own: runtime metric backends, workflow decisions, or storage records.
//! Boundary: access predicates and macro-expanded endpoints emit metrics here.
//!
//! This module intentionally sits at the access layer boundary. Access logic
//! must not depend directly on ops/runtime metric backends; endpoint identity,
//! metric kinds, and authority attribution are normalized here so internal
//! metric schemas can evolve without touching callers.

use crate::{
    cdk::types::Principal,
    ids::{AccessMetricKind, EndpointCall},
    ops,
};

///
/// AccessMetrics
///
/// Access-denial metrics by predicate kind and name.
///
/// Invariants:
/// - Emitted only on denial and represent the kind where access failed.
/// - Called exactly once per denied request.
/// - Cardinality is bounded by endpoint name + kind + predicate name.
/// - Custom predicates are attributed to AccessMetricKind::Custom.
///

pub struct AccessMetrics;

impl AccessMetrics {
    /// Record one denied endpoint access predicate.
    pub fn increment(call: EndpointCall, kind: AccessMetricKind, predicate: &'static str) {
        // Intentionally forward only the normalized endpoint name.
        // Callers must not depend on backend naming conventions.
        ops::runtime::metrics::access::AccessMetrics::increment(
            call.endpoint.name,
            kind,
            predicate,
        );
    }
}

///
/// DelegatedAuthMetrics
///
/// Delegated authorization authority metrics.
///
/// Records which delegated-auth authority principal was used to
/// successfully validate a delegated token.
///
/// WHY THIS LIVES HERE:
/// - Access predicates are the *only* place where delegation validity is known.
/// - Downstream layers must not infer authority from request context.
/// - This ensures cryptographic attribution remains tightly scoped.
///
/// Invariants:
/// - Called only after cryptographic verification succeeds.
/// - Must not be called on denied or partially-verified tokens.
/// - Cardinality is bounded by active delegation authorities.
///

pub struct DelegatedAuthMetrics;

impl DelegatedAuthMetrics {
    /// Record which delegated-auth authority verified a request.
    pub fn record_authority(authority: Principal) {
        ops::runtime::metrics::delegated_auth::DelegatedAuthMetrics::record_authority(authority);
    }
}