bb-runtime 0.3.5

Sans-IO engine for the bytesandbrains framework — Node, Engine, Framework, Backends, roles, snapshot, runtime-side syscalls.
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

//! `DeliveryError`
//!
//! Returned by the host-facing `Node::deliver_inbound` /
//! `deliver_event` / `invoke` entry points when delivery cannot be
//! enqueued onto the ingress.

use crate::bus::AllocFailReason;

/// Errors surfaced by host-facing delivery methods on `Node`.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum DeliveryError {
    /// The ingress queue is closed (Node is shutting down).
    IngressClosed,

    /// `deliver_event` / `invoke` referenced an unknown module name.
    UnknownModule(String),

    /// `deliver_event` referenced a module that exists but has no
    /// such input port.
    UnknownInput {
        /// Module name (resolved successfully).
        module: String,
        /// Input port name (not found on the module).
        input: String,
    },

    /// `deliver_inbound` received bytes that failed
    /// `EnvelopeCodec::decode_capped` — malformed prost frame,
    /// schema-version mismatch, or one of the `NodeConfig.envelope_caps`
    /// limits exceeded.
    InvalidEnvelope(String),

    /// `deliver_event` / `invoke` payload exceeded the configured
    /// per-item cap (`NodeConfig::max_app_event_bytes` or
    /// `NodeConfig::max_invoke_bytes`). A matching
    /// `InfraEvent::AppIngressError` lands on the bus alongside this
    /// synchronous return so observers see the per-item rejection.
    OversizePayload {
        /// Bytes the caller attempted to admit.
        byte_count: usize,
        /// Cap value the boundary enforced.
        cap: usize,
    },

    /// `invoke` carried more `(name, bytes)` inputs than the
    /// configured `NodeConfig::max_invoke_inputs` cap allowed.
    /// Matching `InfraEvent::AppIngressError` lands on the bus.
    TooManyInputs {
        /// Inputs the caller attempted to admit.
        count: usize,
        /// Cap value the boundary enforced.
        cap: usize,
    },

    /// `deliver_event` / `invoke` could not allocate the
    /// framework-owned buffer needed to hold the caller's payload,
    /// either because `Vec::try_reserve_exact` returned
    /// `TryReserveError` or because admitting the payload would
    /// exceed `NodeConfig::ingress_byte_budget`. Matching
    /// `InfraEvent::AppIngressError` lands on the bus.
    AllocationFailed {
        /// Bytes the boundary tried to admit.
        byte_count: usize,
        /// Why the reservation failed.
        reason: AllocFailReason,
    },

    /// Admitting this payload would push the engine over
    /// `NodeConfig::ingress_byte_budget`. Matching
    /// `InfraEvent::AppIngressError` lands on the bus.
    BudgetExceeded {
        /// Bytes the boundary tried to admit.
        byte_count: usize,
        /// Bytes still available under the configured budget at the
        /// time of the rejection.
        budget_remaining: usize,
    },
}

impl std::fmt::Display for DeliveryError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::IngressClosed => write!(f, "ingress queue closed"),
            Self::UnknownModule(name) => write!(f, "unknown module: {name}"),
            Self::UnknownInput { module, input } => {
                write!(f, "module {module} has no input port '{input}'")
            }
            Self::InvalidEnvelope(detail) => {
                write!(f, "inbound envelope rejected: {detail}")
            }
            Self::OversizePayload { byte_count, cap } => {
                write!(f, "payload of {byte_count} bytes exceeds cap of {cap}")
            }
            Self::TooManyInputs { count, cap } => {
                write!(f, "{count} inputs exceeds cap of {cap}")
            }
            Self::AllocationFailed { byte_count, reason } => match reason {
                AllocFailReason::HeapExhausted => {
                    write!(f, "heap exhausted reserving {byte_count} bytes")
                }
                AllocFailReason::PerItemCapExceeded { cap } => {
                    write!(
                        f,
                        "per-item cap {cap} rejected payload of {byte_count} bytes"
                    )
                }
            },
            Self::BudgetExceeded {
                byte_count,
                budget_remaining,
            } => write!(
                f,
                "ingress budget exceeded: {byte_count} bytes requested, {budget_remaining} remaining"
            ),
        }
    }
}

impl std::error::Error for DeliveryError {}