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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
//! Shared RX stop metadata for all serial data tools.
//!
//! Every tool that consumes from the RX session (`read`, `transact`,
//! `capture_boot`) produces the same stop metadata vocabulary so clients can
//! reason about why an operation ended and whether the result was truncated.
use std::fmt;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
/// Canonical reason an RX operation stopped.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum RxStopReason {
/// Operation completed its data collection window (first-byte settle for
/// `read`, or pattern found / max_bytes reached for `read(match=...)`).
DataComplete,
/// The requested timeout elapsed before the operation could finish normally.
Timeout,
/// The configured match pattern was found in the accumulated buffer.
MatchFound,
/// The max_bytes limit was reached before the operation could finish otherwise.
MaxBufferedBytes,
/// No new data was received within the configured silence timeout.
NoNewRxTimeout,
/// The underlying serial connection was closed.
ConnectionClosed,
/// The MCP request was cancelled by the client.
Cancelled,
/// The read collected the configured maximum number of frames
/// (`max_frames` in framing configuration).
MaxFrames,
/// A runtime frame decode error occurred (e.g. SLIP malformed escape
/// sequence).
FramingError,
/// The read drained all buffered bytes immediately (cat semantics).
Drained,
}
impl fmt::Display for RxStopReason {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let s = serde_json::to_value(self)
.map_err(|_| fmt::Error)?
.as_str()
.ok_or(fmt::Error)?
.to_string();
write!(f, "{s}")
}
}
/// Structured metadata attached to every RX operation result.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct RxStopMetadata {
/// Why the operation stopped.
pub stop_reason: RxStopReason,
/// `true` when `bytes_returned < bytes_observed` because the operation
/// capped the returned data (e.g. max_bytes limit exceeded observed data).
pub truncated: bool,
/// Total bytes the operation observed from the RX stream before stopping.
#[schemars(schema_with = "crate::schema_helpers::uint_schema")]
pub bytes_observed: usize,
/// Bytes actually returned in the result `data` field.
#[schemars(schema_with = "crate::schema_helpers::uint_schema")]
pub bytes_returned: usize,
}
impl RxStopMetadata {
pub fn data_complete(bytes_observed: usize, bytes_returned: usize) -> Self {
Self {
stop_reason: RxStopReason::DataComplete,
truncated: bytes_returned < bytes_observed,
bytes_observed,
bytes_returned,
}
}
pub fn timeout(bytes_observed: usize) -> Self {
Self {
stop_reason: RxStopReason::Timeout,
truncated: false,
bytes_observed,
bytes_returned: bytes_observed,
}
}
pub fn match_found(bytes_observed: usize, bytes_returned: usize) -> Self {
Self {
stop_reason: RxStopReason::MatchFound,
truncated: bytes_returned < bytes_observed,
bytes_observed,
bytes_returned,
}
}
pub fn max_buffered_bytes(bytes_observed: usize, bytes_returned: usize) -> Self {
Self {
stop_reason: RxStopReason::MaxBufferedBytes,
truncated: bytes_returned < bytes_observed,
bytes_observed,
bytes_returned,
}
}
pub fn connection_closed(bytes_observed: usize, bytes_returned: usize) -> Self {
Self {
stop_reason: RxStopReason::ConnectionClosed,
truncated: bytes_returned < bytes_observed,
bytes_observed,
bytes_returned,
}
}
pub fn cancelled() -> Self {
Self {
stop_reason: RxStopReason::Cancelled,
truncated: false,
bytes_observed: 0,
bytes_returned: 0,
}
}
pub fn no_new_rx_timeout(bytes_observed: usize) -> Self {
Self {
stop_reason: RxStopReason::NoNewRxTimeout,
truncated: false,
bytes_observed,
bytes_returned: bytes_observed,
}
}
pub fn max_frames(bytes_observed: usize, bytes_returned: usize) -> Self {
Self {
stop_reason: RxStopReason::MaxFrames,
truncated: false,
bytes_observed,
bytes_returned,
}
}
pub fn framing_error(bytes_observed: usize) -> Self {
Self {
stop_reason: RxStopReason::FramingError,
truncated: false,
bytes_observed,
bytes_returned: 0,
}
}
pub fn drained(_end_offset: u64, _bytes_observed: usize, bytes_returned: usize) -> Self {
Self {
stop_reason: RxStopReason::Drained,
truncated: false,
bytes_observed: bytes_returned,
bytes_returned,
}
}
pub fn new(
reason: RxStopReason,
bytes_observed: usize,
bytes_returned: usize,
truncated: bool,
) -> Self {
Self {
stop_reason: reason,
truncated,
bytes_observed,
bytes_returned,
}
}
pub fn with_bytes(mut self, observed: usize, returned: usize) -> Self {
self.bytes_observed = observed;
self.bytes_returned = returned;
self.truncated = returned < observed;
self
}
}