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 | |
| 35 | use crate::{ |
| 36 | bdat::DecodeLimits, |
| 37 | daticle::Dat, |
| 38 | }; |
| 39 | |
| 40 | use oxedyne_fe2o3_core::prelude::*; |
| 41 | |
| 42 | use tokio::io::{ |
| 43 | AsyncRead, |
| 44 | AsyncReadExt, |
| 45 | AsyncWrite, |
| 46 | AsyncWriteExt, |
| 47 | }; |
| 48 | |
| 49 | |
| 50 | /// The width of the length prefix, in bytes. |
| 51 | pub const LEN_PREFIX: usize = 4; |
| 52 | |
| 53 | /// The largest ceiling a frame can have, set by the width of the prefix. |
| 54 | pub 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)] |
| 58 | pub 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 | |
| 71 | impl 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)] |
| 126 | pub struct FrameReader<R> { |
| 127 | r: R, |
| 128 | max: usize, |
| 129 | depth: usize, |
| 130 | } |
| 131 | |
| 132 | impl<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)] |
| 214 | pub struct FrameWriter<W> { |
| 215 | w: W, |
| 216 | max: usize, |
| 217 | } |
| 218 | |
| 219 | impl<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. |
| 288 | async 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 | } |