oxedyne/fe2o3/fe2o3_net/src/lens/tap.rs
8.3 KiB, 1 run
created by r1870400018:65648, 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 | //! The lens's tap: a websocket's messages as rows of a [`Sink`]. |
| 2 | //! |
| 3 | //! [`Tap`] is a [`FrameTap`] for [`crate::ws::tap`]'s seam. Each message, either way, goes to a |
| 4 | //! caller's filter along with the connection's context. The filter says whether the message is |
| 5 | //! worth a row, where it is filed and what of it is kept, and an Oxegen peer will use that to |
| 6 | //! reduce a biometric enrolment bundle to its kind, its ids and its size before anything touches |
| 7 | //! a disk. What the filter returns still passes through the sink's [`Redact`](super::Redact), so a |
| 8 | //! filter that forgets a field is not the last line of defence. |
| 9 | //! |
| 10 | //! [`Frame::shape`] is the default arm for a filter: the message's kind and byte count and |
| 11 | //! nothing of its content. |
| 12 | |
| 13 | use super::{ |
| 14 | redact::{ |
| 15 | NoTest, |
| 16 | StrTest, |
| 17 | }, |
| 18 | row::Row, |
| 19 | sink::{ |
| 20 | now_ms, |
| 21 | Sink, |
| 22 | }, |
| 23 | }; |
| 24 | use crate::ws::{ |
| 25 | core::WebSocketMessage, |
| 26 | tap::FrameTap, |
| 27 | }; |
| 28 | |
| 29 | use oxedyne_fe2o3_core::prelude::*; |
| 30 | use oxedyne_fe2o3_jdat::prelude::*; |
| 31 | |
| 32 | use std::{ |
| 33 | marker::PhantomData, |
| 34 | sync::{ |
| 35 | atomic::{ |
| 36 | AtomicU64, |
| 37 | Ordering, |
| 38 | }, |
| 39 | Arc, |
| 40 | }, |
| 41 | }; |
| 42 | |
| 43 | |
| 44 | /// Which way a message was travelling. |
| 45 | #[derive(Clone, Copy, Debug, Eq, PartialEq)] |
| 46 | pub enum Dir { |
| 47 | In, // read from the peer |
| 48 | Out, // sent to the peer |
| 49 | } |
| 50 | |
| 51 | impl Dir { |
| 52 | |
| 53 | /// The row's kind, so its tag reads `ev frame.in` or `ev frame.out`. |
| 54 | pub fn kind(&self) -> &'static str { |
| 55 | match self { |
| 56 | Self::In => "frame.in", |
| 57 | Self::Out => "frame.out", |
| 58 | } |
| 59 | } |
| 60 | } |
| 61 | |
| 62 | /// What a filter keeps of one message: the sink key it is filed under, the row's source id and its |
| 63 | /// payload fields. |
| 64 | #[derive(Clone, Debug)] |
| 65 | pub struct Frame { |
| 66 | pub key: Vec<String>, // the sink key, a session or a source |
| 67 | pub d: String, // the row's short source id |
| 68 | pub body: Vec<(String, Dat)>, // payload fields, in the order they were added |
| 69 | } |
| 70 | |
| 71 | impl Frame { |
| 72 | |
| 73 | pub fn new(key: &[&str], d: &str) -> Self { |
| 74 | Self { |
| 75 | key: key.iter().map(|s| s.to_string()).collect(), |
| 76 | d: d.to_string(), |
| 77 | body: Vec::new(), |
| 78 | } |
| 79 | } |
| 80 | |
| 81 | /// Adds a payload field, or replaces one of the same name where it stands. |
| 82 | pub fn with(mut self, name: &str, val: Dat) -> Self { |
| 83 | for (k, v) in self.body.iter_mut() { |
| 84 | if k == name { |
| 85 | *v = val; |
| 86 | return self; |
| 87 | } |
| 88 | } |
| 89 | self.body.push((name.to_string(), val)); |
| 90 | self |
| 91 | } |
| 92 | |
| 93 | /// Adds `op`, the kind of message, and `bytes`, its payload length, and nothing of what it |
| 94 | /// says. A filter that does not recognise a message should end here. |
| 95 | pub fn shape(self, msg: &WebSocketMessage) -> Self { |
| 96 | let (op, bytes) = match msg { |
| 97 | WebSocketMessage::Text(t) => ("text", t.len()), |
| 98 | WebSocketMessage::Binary(b) => ("binary", b.len()), |
| 99 | WebSocketMessage::Ping(b) => ("ping", b.len()), |
| 100 | WebSocketMessage::Pong(b) => ("pong", b.len()), |
| 101 | WebSocketMessage::Close(c, r) => ( |
| 102 | "close", |
| 103 | c.as_ref().map_or(0, |_| 2) + r.as_ref().map_or(0, |r| r.len()), |
| 104 | ), |
| 105 | }; |
| 106 | self.with("op", Dat::Str(op.to_string())).with("bytes", Dat::U64(bytes as u64)) |
| 107 | } |
| 108 | } |
| 109 | |
| 110 | /// A [`FrameTap`] that writes the messages its filter keeps to a [`Sink`]. |
| 111 | /// |
| 112 | /// The filter is `Fn(Dir, &C, &WebSocketMessage) -> Option<Frame>` over the connection context |
| 113 | /// `C`; `None` drops the message. The sequence number `n` of the row envelope counts from 1 across |
| 114 | /// the whole tap and advances only for a message the filter kept, so a reader sees no gap. It is |
| 115 | /// one counter, not one per key, so it stays bounded however many connections come and go. |
| 116 | /// |
| 117 | /// A write that fails is counted in [`lost`](Self::lost) and logged once, and the message flows on |
| 118 | /// regardless: a debug feed must never be able to stop the socket it watches. The append is a |
| 119 | /// blocking file write made on the task that read or sent the message. Size the sink's |
| 120 | /// `Gates::max_data` for the frames the filter builds, since a row over it is trimmed. |
| 121 | pub struct Tap<C, F, T: StrTest = NoTest> { |
| 122 | sink: Arc<Sink<T>>, |
| 123 | build: String, // the build tag, `b` of the envelope |
| 124 | filter: F, |
| 125 | n: AtomicU64, // the last sequence number issued |
| 126 | lost: AtomicU64, // writes that failed |
| 127 | phantom: PhantomData<fn(C)>, |
| 128 | } |
| 129 | |
| 130 | impl<C, F, T> Tap<C, F, T> |
| 131 | where |
| 132 | T: StrTest, |
| 133 | F: Fn(Dir, &C, &WebSocketMessage) -> Option<Frame> + Send + Sync, |
| 134 | { |
| 135 | pub fn new(sink: Arc<Sink<T>>, build: &str, filter: F) -> Self { |
| 136 | Self { |
| 137 | sink, |
| 138 | build: build.to_string(), |
| 139 | filter, |
| 140 | n: AtomicU64::new(0), |
| 141 | lost: AtomicU64::new(0), |
| 142 | phantom: PhantomData, |
| 143 | } |
| 144 | } |
| 145 | |
| 146 | /// How many rows could not be written. |
| 147 | pub fn lost(&self) -> u64 { |
| 148 | self.lost.load(Ordering::Relaxed) |
| 149 | } |
| 150 | |
| 151 | fn take(&self, dir: Dir, ctx: &C, msg: &WebSocketMessage) { |
| 152 | let frame = match (self.filter)(dir, ctx, msg) { |
| 153 | Some(frame) => frame, |
| 154 | None => return, |
| 155 | }; |
| 156 | // Daimond's `nextSeq` is incremented before it is used, so the first row is 1. |
| 157 | let n = self.n.fetch_add(1, Ordering::Relaxed) + 1; |
| 158 | let t = now_ms().unwrap_or(0); |
| 159 | let mut row = Row::new(&frame.d, n, &self.build, t, dir.kind()); |
| 160 | for (k, v) in frame.body { |
| 161 | row = row.with(&k, v); |
| 162 | } |
| 163 | let key: Vec<&str> = frame.key.iter().map(|s| s.as_str()).collect(); |
| 164 | if let Err(e) = self.sink.write(&key, &frame.d, &[row], t) { |
| 165 | // The first failure is told; the rest would only repeat it. |
| 166 | if self.lost.fetch_add(1, Ordering::Relaxed) == 0 { |
| 167 | error!(e, "lens: a tapped frame could not be written, and later losses are only counted."); |
| 168 | } |
| 169 | } |
| 170 | } |
| 171 | } |
| 172 | |
| 173 | impl<C, F, T> FrameTap for Tap<C, F, T> |
| 174 | where |
| 175 | T: StrTest, |
| 176 | F: Fn(Dir, &C, &WebSocketMessage) -> Option<Frame> + Send + Sync, |
| 177 | { |
| 178 | type Ctx = C; |
| 179 | |
| 180 | fn inbound(&self, ctx: &C, msg: &WebSocketMessage) { |
| 181 | self.take(Dir::In, ctx, msg); |
| 182 | } |
| 183 | |
| 184 | fn outbound(&self, ctx: &C, msg: &WebSocketMessage) { |
| 185 | self.take(Dir::Out, ctx, msg); |
| 186 | } |
| 187 | } |
| 188 | |
| 189 | |
| 190 | #[cfg(test)] |
| 191 | mod tests { |
| 192 | use super::*; |
| 193 | use crate::ws::status::WebSocketStatusCode; |
| 194 | |
| 195 | fn field<'a>(f: &'a Frame, name: &str) -> Option<&'a Dat> { |
| 196 | f.body.iter().find(|(k, _)| k == name).map(|(_, v)| v) |
| 197 | } |
| 198 | |
| 199 | #[test] |
| 200 | fn shape_counts_the_payload_of_each_kind_and_keeps_none_of_it() { |
| 201 | let cases = [ |
| 202 | (WebSocketMessage::Text("secret words".to_string()), "text", 12), |
| 203 | (WebSocketMessage::Binary(vec![1, 2, 3]), "binary", 3), |
| 204 | (WebSocketMessage::Ping(vec![]), "ping", 0), |
| 205 | (WebSocketMessage::Pong(vec![9]), "pong", 1), |
| 206 | (WebSocketMessage::Close(None, None), "close", 0), |
| 207 | (WebSocketMessage::Close(Some(WebSocketStatusCode::MessageTooBig), None), |
| 208 | "close", 2), |
| 209 | (WebSocketMessage::Close(Some(WebSocketStatusCode::MessageTooBig), Some("bye".to_string())), |
| 210 | "close", 5), |
| 211 | ]; |
| 212 | for (msg, op, bytes) in cases { |
| 213 | let f = Frame::new(&["k"], "d").shape(&msg); |
| 214 | assert_eq!(field(&f, "op"), Some(&Dat::Str(op.to_string())), "{:?}", msg); |
| 215 | assert_eq!(field(&f, "bytes"), Some(&Dat::U64(bytes)), "{:?}", msg); |
| 216 | assert_eq!(f.body.len(), 2, "shape adds the kind and the size and nothing else"); |
| 217 | } |
| 218 | } |
| 219 | |
| 220 | #[test] |
| 221 | fn a_field_added_twice_is_replaced_where_it_stands() { |
| 222 | let f = Frame::new(&["a", "b"], "dev") |
| 223 | .with("x", Dat::U8(1)) |
| 224 | .with("y", Dat::U8(2)) |
| 225 | .with("x", Dat::U8(3)); |
| 226 | assert_eq!(f.key, vec!["a".to_string(), "b".to_string()]); |
| 227 | assert_eq!(f.body, vec![("x".to_string(), Dat::U8(3)), ("y".to_string(), Dat::U8(2))]); |
| 228 | } |
| 229 | |
| 230 | #[test] |
| 231 | fn a_direction_names_its_kind() { |
| 232 | assert_eq!(Dir::In.kind(), "frame.in"); |
| 233 | assert_eq!(Dir::Out.kind(), "frame.out"); |
| 234 | } |
| 235 | } |