Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_jdat/src/pipe.rs

11.1 KiB, 1 run

created by r1870400018:75863, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1//! Length-prefixed BDAT frames over a tokio byte stream, for two processes that talk over a pipe or
2//! a socket.
3//!
4//! A frame is a four-byte big-endian length followed by exactly that many bytes of one BDAT value.
5//! BDAT is already self-delimiting, but a reader of a stream it did not write needs to know how
6//! much it is being asked to hold *before* it holds it, so the length comes first and is checked
7//! against a ceiling the caller chooses.
8//!
9//! The rules the reader keeps, for bytes it did not create:
10//!
11//! * **A frame over the ceiling is refused before it is read.** The declared length is compared
12//! with the ceiling as soon as the prefix arrives, so a prefix promising four gigabytes costs
13//! four bytes, no buffer is sized from it and no body byte is waited for.
14//! * **Partial frames never surface.** A read returns a whole decoded value or a fault. A stream
15//! that ends between frames is a clean end (`None`); one that ends inside a prefix or a body is
16//! [`PipeFault::ShortPrefix`] or [`PipeFault::Truncated`], never a shorter value.
17//! * **A frame is one value.** A body that does not decode, or that holds bytes after its value,
18//! is [`PipeFault::Undecodable`]. Nesting is held to a depth limit as well as the byte ceiling.
19//!
20//! The writer refuses a value whose encoding exceeds its ceiling before writing a byte, so a
21//! refused frame leaves the stream exactly as it was and the next frame still lines up.
22//!
23//! The faults are named and recoverable from the error with [`PipeFault::of`], because a caller
24//! deciding whether to drop a connection needs to know which thing went wrong.
25//!
26//! Neither read nor write is cancel-safe: dropping a pending read part-way through a frame leaves
27//! the stream misaligned, so a caller selecting over a read keeps the reader's future alive rather
28//! than restarting it. This module sits beside, and follows the shape of, the Hand's native
29//! messaging codec; it differs in carrying BDAT rather than JSON text, and in a big-endian prefix,
30//! since both ends are ours rather than Chrome's.
31//!
32//! Enabled by the `pipe` feature, which is off by default so that a wasm or synchronous user of
33//! this crate pulls in no tokio.
34
35use crate::{
36 bdat::DecodeLimits,
37 daticle::Dat,
38};
39
40use oxedyne_fe2o3_core::prelude::*;
41
42use tokio::io::{
43 AsyncRead,
44 AsyncReadExt,
45 AsyncWrite,
46 AsyncWriteExt,
47};
48
49
50/// The width of the length prefix, in bytes.
51pub const LEN_PREFIX: usize = 4;
52
53/// The largest ceiling a frame can have, set by the width of the prefix.
54pub const LEN_MAX: usize = u32::MAX as usize;
55
56/// The named ways a frame fails to be read or written.
57#[derive(Clone, Copy, Debug, Eq, PartialEq)]
58pub enum PipeFault {
59 /// The stream ended part-way through a length prefix.
60 ShortPrefix,
61 /// The stream ended before the declared number of body bytes arrived.
62 Truncated,
63 /// The frame declared, or would need, more bytes than the ceiling.
64 TooBig,
65 /// The body was not exactly one BDAT value within the limits.
66 Undecodable,
67 /// The stream could not be read or written at all.
68 Io,
69}
70
71impl PipeFault {
72
73 /// Every fault, so a search over them is exhaustive by construction.
74 pub const ALL: [Self; 5] = [
75 Self::ShortPrefix,
76 Self::Truncated,
77 Self::TooBig,
78 Self::Undecodable,
79 Self::Io,
80 ];
81
82 /// The stable identifier that begins every message this fault raises.
83 pub fn name(&self) -> &'static str {
84 match self {
85 Self::ShortPrefix => "pipe.short-prefix",
86 Self::Truncated => "pipe.truncated",
87 Self::TooBig => "pipe.too-big",
88 Self::Undecodable => "pipe.undecodable",
89 Self::Io => "pipe.io",
90 }
91 }
92
93 /// Builds the error this fault raises, with the detail that identifies the case.
94 ///
95 /// # Arguments
96 /// * `detail` - What was wrong, in a sentence a developer reading a journal can use.
97 pub fn raise(&self, detail: &str) -> Error<ErrTag> {
98 match self {
99 Self::ShortPrefix => err!("{}: {}", self.name(), detail; Input, Decode, Missing),
100 Self::Truncated => err!("{}: {}", self.name(), detail; Input, Decode, Missing),
101 Self::TooBig => err!("{}: {}", self.name(), detail; Input, TooBig),
102 Self::Undecodable => err!("{}: {}", self.name(), detail; Input, Decode, Invalid),
103 Self::Io => err!("{}: {}", self.name(), detail; IO, Wire),
104 }
105 }
106
107 /// The fault an error carries, where it carries one, looking through any layers wrapped
108 /// around it.
109 ///
110 /// # Arguments
111 /// * `e` - The error to inspect.
112 pub fn of(e: &Error<ErrTag>) -> Option<Self> {
113 for msg in e.msgs() {
114 for f in Self::ALL {
115 if msg.starts_with(f.name()) {
116 return Some(f);
117 }
118 }
119 }
120 None
121 }
122}
123
124/// Reads whole frames from a byte stream, refusing any over its ceiling.
125#[derive(Debug)]
126pub struct FrameReader<R> {
127 r: R,
128 max: usize,
129 depth: usize,
130}
131
132impl<R: AsyncRead + Unpin> FrameReader<R> {
133
134 /// A reader of frames up to `max` bytes of body, with the default nesting limit.
135 ///
136 /// A ceiling over [`LEN_MAX`] is held to [`LEN_MAX`], since no prefix can declare more.
137 ///
138 /// # Arguments
139 /// * `r` - The stream.
140 /// * `max` - The largest body, in bytes, the reader will accept.
141 pub fn new(r: R, max: usize) -> Self {
142 Self {
143 r,
144 max: std::cmp::min(max, LEN_MAX),
145 depth: DecodeLimits::DEFAULT_MAX_DEPTH,
146 }
147 }
148
149 /// The same reader with a different nesting limit for decoded values.
150 ///
151 /// # Arguments
152 /// * `depth` - The greatest nesting depth, with the root value at depth 1.
153 pub fn with_max_depth(mut self, depth: usize) -> Self {
154 self.depth = depth;
155 self
156 }
157
158 /// The body ceiling in force.
159 pub fn max(&self) -> usize { self.max }
160
161 /// Gives back the stream.
162 pub fn into_inner(self) -> R { self.r }
163
164 /// Reads the next whole frame's body without decoding it, for a relay that forwards frames.
165 ///
166 /// Returns `None` at a clean end between frames.
167 pub async fn read_bytes(&mut self) -> Outcome<Option<Vec<u8>>> {
168 let mut pre = [0u8; LEN_PREFIX];
169 let got = res!(read_upto(&mut self.r, &mut pre).await);
170 if got == 0 {
171 return Ok(None);
172 }
173 if got < LEN_PREFIX {
174 return Err(PipeFault::ShortPrefix.raise(&fmt!(
175 "The stream ended {} bytes into a {}-byte length prefix.", got, LEN_PREFIX)));
176 }
177 let n = u32::from_be_bytes(pre) as usize;
178 if n > self.max {
179 return Err(PipeFault::TooBig.raise(&fmt!(
180 "The prefix declares {} bytes and the ceiling is {}. Nothing more was read.",
181 n, self.max)));
182 }
183 let mut body = vec![0u8; n];
184 let got = res!(read_upto(&mut self.r, &mut body).await);
185 if got < n {
186 return Err(PipeFault::Truncated.raise(&fmt!(
187 "The prefix declares {} bytes and the stream ended after {}.", n, got)));
188 }
189 Ok(Some(body))
190 }
191
192 /// Reads and decodes the next whole frame.
193 ///
194 /// Returns `None` at a clean end between frames.
195 pub async fn read(&mut self) -> Outcome<Option<Dat>> {
196 let body = match res!(self.read_bytes().await) {
197 Some(b) => b,
198 None => return Ok(None),
199 };
200 let lims = DecodeLimits::new(self.depth, self.max);
201 match Dat::from_bytes_limited(&body, &lims) {
202 Ok((d, used)) if used == body.len() => Ok(Some(d)),
203 Ok((_, used)) => Err(PipeFault::Undecodable.raise(&fmt!(
204 "The frame holds {} bytes after its value, which ends at byte {} of {}.",
205 body.len() - used, used, body.len()))),
206 Err(e) => Err(PipeFault::Undecodable.raise(&fmt!(
207 "The {}-byte frame is not one BDAT value: {}", body.len(), e))),
208 }
209 }
210}
211
212/// Writes whole frames to a byte stream, refusing any over its ceiling before writing a byte.
213#[derive(Debug)]
214pub struct FrameWriter<W> {
215 w: W,
216 max: usize,
217}
218
219impl<W: AsyncWrite + Unpin> FrameWriter<W> {
220
221 /// A writer of frames up to `max` bytes of body.
222 ///
223 /// A ceiling over [`LEN_MAX`] is held to [`LEN_MAX`], since no prefix can declare more.
224 ///
225 /// # Arguments
226 /// * `w` - The stream.
227 /// * `max` - The largest body, in bytes, the writer will send.
228 pub fn new(w: W, max: usize) -> Self {
229 Self {
230 w,
231 max: std::cmp::min(max, LEN_MAX),
232 }
233 }
234
235 /// The body ceiling in force.
236 pub fn max(&self) -> usize { self.max }
237
238 /// Gives back the stream.
239 pub fn into_inner(self) -> W { self.w }
240
241 /// Encodes a value and writes it as one frame, then flushes.
242 ///
243 /// # Arguments
244 /// * `dat` - The value.
245 pub async fn write(&mut self, dat: &Dat) -> Outcome<()> {
246 let body = match dat.as_bytes() {
247 Ok(b) => b,
248 Err(e) => return Err(PipeFault::Undecodable.raise(&fmt!(
249 "The value could not be encoded: {}", e))),
250 };
251 self.write_bytes(&body).await
252 }
253
254 /// Writes an already encoded body as one frame, then flushes, for a relay that forwards
255 /// frames.
256 ///
257 /// # Arguments
258 /// * `body` - The body, one BDAT value.
259 pub async fn write_bytes(&mut self, body: &[u8]) -> Outcome<()> {
260 if body.len() > self.max {
261 return Err(PipeFault::TooBig.raise(&fmt!(
262 "The frame would hold {} bytes and the ceiling is {}. Nothing was written.",
263 body.len(), self.max)));
264 }
265 // One buffer, so a frame goes out in as few writes as the stream allows.
266 let mut whole = Vec::with_capacity(LEN_PREFIX + body.len());
267 whole.extend_from_slice(&(body.len() as u32).to_be_bytes());
268 whole.extend_from_slice(body);
269 if let Err(e) = self.w.write_all(&whole).await {
270 return Err(PipeFault::Io.raise(&fmt!("The frame could not be written: {}.", e)));
271 }
272 match self.w.flush().await {
273 Ok(()) => Ok(()),
274 Err(e) => Err(PipeFault::Io.raise(&fmt!("The frame could not be flushed: {}.", e))),
275 }
276 }
277}
278
279/// Fills a buffer, returning how much of it arrived before the stream ended.
280///
281/// `read_exact` cannot tell a clean end from a short one, and that difference is what a reader
282/// needs: nothing at all means the other end has gone, and part of a prefix means something is
283/// wrong.
284///
285/// # Arguments
286/// * `r` - The stream.
287/// * `buf` - The buffer to fill.
288async fn read_upto<R: AsyncRead + Unpin>(r: &mut R, buf: &mut [u8]) -> Outcome<usize> {
289 let mut n = 0;
290 while n < buf.len() {
291 match r.read(&mut buf[n..]).await {
292 Ok(0) => break,
293 Ok(k) => n += k,
294 Err(ref e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
295 Err(e) => return Err(PipeFault::Io.raise(&fmt!(
296 "The stream could not be read: {}.", e))),
297 }
298 }
299 Ok(n)
300}