Oregami
Repositories/oxedyne/fe2o3

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
13use super::{
14 redact::{
15 NoTest,
16 StrTest,
17 },
18 row::Row,
19 sink::{
20 now_ms,
21 Sink,
22 },
23};
24use crate::ws::{
25 core::WebSocketMessage,
26 tap::FrameTap,
27};
28
29use oxedyne_fe2o3_core::prelude::*;
30use oxedyne_fe2o3_jdat::prelude::*;
31
32use 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)]
46pub enum Dir {
47 In, // read from the peer
48 Out, // sent to the peer
49}
50
51impl 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)]
65pub 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
71impl 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.
121pub 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
130impl<C, F, T> Tap<C, F, T>
131where
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
173impl<C, F, T> FrameTap for Tap<C, F, T>
174where
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)]
191mod 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}