nodedb_bridge/
envelope.rs

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

nodedb_bridge/
envelope.rs
