nodedb_bridge/
envelope.rs

1// SPDX-License-Identifier: BUSL-1.1
2
3use std::sync::Arc;
4use std::time::Instant;
5
6/// A request envelope sent from the Control Plane (Tokio) to the Data Plane (TPC).
7///
8/// This is a lightweight descriptor — bulk data lives behind `Arc<[u8]>` or
9/// slab handles, not inline in the ring buffer slot.
10#[derive(Debug, Clone)]
11pub struct Request {
12    /// Globally unique request identifier (monotonic per connection for 24h).
13    pub request_id: u64,
14
15    /// Tenant scope for isolation and quota enforcement.
16    pub tenant_id: u64,
17
18    /// Virtual shard this request targets.
19    pub vshard_id: u32,
20
21    /// Opaque execution plan digest (interpreted by the Data Plane).
22    pub plan: Plan,
23
24    /// Absolute deadline — Data Plane must abandon work after this instant.
25    pub deadline: Instant,
26
27    /// Priority class for scheduling on the Data Plane core.
28    pub priority: Priority,
29
30    /// Distributed trace identifier for cross-plane observability.
31    pub trace_id: u64,
32}
33
34/// A response envelope sent from the Data Plane (TPC) back to the Control Plane (Tokio).
35#[derive(Debug)]
36pub struct Response {
37    /// Matches the originating `Request::request_id`.
38    pub request_id: u64,
39
40    /// Outcome of the execution.
41    pub status: Status,
42
43    /// Number of bytes produced by this response (for backpressure accounting).
44    pub bytes_produced: u64,
45
46    /// The LSN watermark at which this response was computed.
47    pub watermark_lsn: u64,
48
49    /// The result payload. `None` if the request was cancelled or failed.
50    pub payload: Option<Arc<[u8]>>,
51}
52
53/// The execution plan payload. Kept as an opaque blob at the bridge layer —
54/// the bridge doesn't interpret plans, it just moves them.
55#[derive(Debug, Clone)]
56pub enum Plan {
57    /// Raw serialized plan bytes (zero-copy via Arc).
58    Bytes(Arc<[u8]>),
59
60    /// Slab handle — the actual plan lives in a shared slab allocator
61    /// and the Data Plane looks it up by index.
62    SlabHandle { slab_id: u32, offset: u32, len: u32 },
63}
64
65/// Request priority for Data Plane scheduling.
66#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
67#[repr(u8)]
68pub enum Priority {
69    /// Control signals, cancellations, barrier coordination.
70    Critical = 0,
71    /// Interactive queries with latency SLOs.
72    Interactive = 1,
73    /// Batch operations, background compaction requests.
74    Background = 2,
75}
76
77/// Execution outcome status.
78#[derive(Debug, Clone, Copy, PartialEq, Eq)]
79pub enum Status {
80    /// Execution completed successfully.
81    Ok,
82    /// Partial result available (streaming response).
83    Partial,
84    /// Request was cancelled via `CANCEL(request_id)`.
85    Cancelled,
86    /// Deadline expired before completion.
87    DeadlineExceeded,
88    /// Execution failed with a deterministic numeric error code.
89    ///
90    /// The value is the numeric representation of the domain-level error code
91    /// (see `nodedb::bridge::envelope::ErrorCode` in the main crate for the
92    /// authoritative mapping). The bridge layer stays code-free to avoid
93    /// duplicating rich error variant logic across crates.
94    Error(u16),
95}
nodedb_bridge/envelope.rs

nodedb_bridge/
envelope.rs
