Skip to main content

plexus_core/plexus/
wire.rs

1//! PERF-7: the item path — an item encoded once, by its method's own event
2//! type, straight into a buffer its socket writes from.
3//!
4//! | when | then |
5//! | -- | -- |
6//! | a method yields an event under the WebSocket pipe ([`pipe`]) | [`wrap_stream`](super::streaming::wrap_stream) serializes it once, by its own `Serialize`, into the pipe's buffer (a block from its connection's pool); the `Data` item carries it as [`Content`] — JSON bytes, no `Value` |
7//! | the pipe's buffer takes an event's JSON (`json`, PERF-34) | written by a real scan, not a byte at a time, the bytes `serde_json` writes |
8//! | the same event anywhere else (in process, a nested route, a test) | it becomes a `Value` as before: in-process items stay what they cost |
9//! | a transformer reads a `Data` item's content | [`Content`] decodes its bytes once, on demand (`Deref` to `Value`); one that rewrites it replaces the whole [`Content`] — an encoded item is a `Data` item, so no rewrite can miss one (PERF-17's finding: the gated view's rewrite did) |
10//! | the pipe writes an item | the notification's prefix (once a call), the metadata (once a stream), the content type and the content's bytes, and the suffix, into the same buffer: one frame, split off as `Bytes` (no allocation while the block has room) |
11//! | the transport offers a [`FrameSink`] (plexus-transport's socket loop) | the frame goes to the socket's writer as it is; the call's first frame is fenced, so it follows the subscription's answer that jsonrpsee queued |
12//! | it does not (jsonrpsee's own sink: stdio, an in-memory module) | the item's bytes go to the sink as one raw value, as before |
13//! | one change fans out to N watchers ([`Shared`]) | the first socket that sends it encodes it, once; every other writes those bytes |
14//! | a call has an input half ([`super::input`]) | [`pipe_duplex`] takes it instead: the same frames and buffer, and beside the method's items the frames of the input half (`credit`, `ack`, `input_closed`), made here since they are this transport's and no method's. [`pipe`] is unchanged by them |
15//! | the client offered `batch` at its upgrade ([`FrameSink::batching`], PERF-8) | the items a stream has ready together, up to the batch and about [`BATCH_BYTES`], go in one notification whose `results` are their array, the metadata said once; a lone item goes at once, in today's form |
16//!
17//! PERF-8 batches frames here (`results: […]`), PERF-9 adds an encoding
18//! ([`WireEncoding`]), PERF-13 relays a child's content as bytes.
19
20use std::borrow::Cow;
21use std::cell::{Cell, RefCell};
22use std::sync::{Arc, Mutex, OnceLock};
23
24use bytes::{BufMut, Bytes, BytesMut};
25use serde::{Deserialize, Serialize, Serializer};
26use serde_json::value::RawValue;
27use serde_json::Value;
28
29use super::types::{PlexusStreamItem, StreamMetadata};
30
31mod json;
32
33// ---------------------------------------------------------------------------
34// Content
35// ---------------------------------------------------------------------------
36
37/// A `data` item's content: the method's event, encoded once (JSON bytes),
38/// or a `Value` — whichever the item was made with. Reads as a `Value`
39/// either way ([`Content::value`], `Deref`), the bytes decoded once on
40/// demand; serializes as its JSON. Equal as JSON is equal.
41#[derive(Clone, Default)]
42pub struct Content(Repr);
43
44#[derive(Clone)]
45enum Repr {
46    Value(Value),
47    /// JSON text the pipe's writer wrote (valid by construction: the bytes
48    /// serde_json writes), and its `Value` once someone asked for it.
49    Json { text: Bytes, value: OnceLock<Value> },
50}
51
52impl Default for Repr {
53    fn default() -> Self {
54        Repr::Value(Value::Null)
55    }
56}
57
58impl Content {
59    /// Content that is a `Value`.
60    pub fn from_value(value: Value) -> Self {
61        Content(Repr::Value(value))
62    }
63
64    /// Content that is JSON text, checked (a parse, no `Value` built).
65    pub fn from_json(text: Bytes) -> Result<Self, serde_json::Error> {
66        serde_json::from_slice::<serde::de::IgnoredAny>(&text)?;
67        Ok(Self::json(text))
68    }
69
70    /// JSON text the pipe's writer wrote, taken as it is.
71    pub(crate) fn json(text: Bytes) -> Self {
72        Content(Repr::Json { text, value: OnceLock::new() })
73    }
74
75    /// The content as a `Value` (encoded bytes decoded once, kept).
76    pub fn value(&self) -> &Value {
77        match &self.0 {
78            Repr::Value(v) => v,
79            Repr::Json { text, value } => value.get_or_init(|| serde_json::from_slice(text).unwrap_or(Value::Null)),
80        }
81    }
82
83    /// The content as an owned `Value`.
84    pub fn into_value(self) -> Value {
85        match self.0 {
86            Repr::Value(v) => v,
87            Repr::Json { text, value } => value.into_inner().unwrap_or_else(|| serde_json::from_slice(&text).unwrap_or(Value::Null)),
88        }
89    }
90
91    /// A copy of the content as a `Value`.
92    pub fn to_value(&self) -> Value {
93        match &self.0 {
94            Repr::Value(v) => v.clone(),
95            Repr::Json { text, value } => value.get().cloned().unwrap_or_else(|| serde_json::from_slice(text).unwrap_or(Value::Null)),
96        }
97    }
98
99    /// The content as `T`, decoded straight from its bytes when it is
100    /// encoded (no `Value` in between).
101    pub fn decode<T: serde::de::DeserializeOwned>(&self) -> Result<T, serde_json::Error> {
102        match &self.0 {
103            Repr::Value(v) => T::deserialize(v),
104            Repr::Json { text, value } => match value.get() {
105                Some(v) => T::deserialize(v),
106                None => serde_json::from_slice(text),
107            },
108        }
109    }
110
111    /// The JSON text the content was encoded as, when it was.
112    pub fn json_bytes(&self) -> Option<&Bytes> {
113        match &self.0 {
114            Repr::Json { text, .. } => Some(text),
115            Repr::Value(_) => None,
116        }
117    }
118
119    /// Whether the content was encoded once from its event (PERF-7).
120    pub fn is_encoded(&self) -> bool {
121        matches!(self.0, Repr::Json { .. })
122    }
123
124    /// Its JSON text, appended to `out`: the bytes, or the `Value` written.
125    fn write_json(&self, out: &mut BytesMut) {
126        match &self.0 {
127            Repr::Json { text, .. } => out.put_slice(text),
128            Repr::Value(v) => {
129                let _ = serde_json::to_writer((&mut *out).writer(), v);
130            }
131        }
132    }
133}
134
135impl std::ops::Deref for Content {
136    type Target = Value;
137    fn deref(&self) -> &Value {
138        self.value()
139    }
140}
141
142impl From<Value> for Content {
143    fn from(value: Value) -> Self {
144        Content::from_value(value)
145    }
146}
147
148impl From<Content> for Value {
149    fn from(content: Content) -> Self {
150        content.into_value()
151    }
152}
153
154/// Whatever a `Value` compares with — another content, a `Value`, a string,
155/// a number, a bool — a content compares with as its `Value`.
156impl<T: ?Sized> PartialEq<T> for Content
157where
158    Value: PartialEq<T>,
159{
160    fn eq(&self, other: &T) -> bool {
161        self.value() == other
162    }
163}
164
165impl PartialEq<Content> for Value {
166    fn eq(&self, other: &Content) -> bool {
167        self == other.value()
168    }
169}
170
171impl std::fmt::Debug for Content {
172    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
173        match &self.0 {
174            Repr::Value(v) => v.fmt(f),
175            Repr::Json { text, .. } => write!(f, "{}", String::from_utf8_lossy(text)),
176        }
177    }
178}
179
180impl std::fmt::Display for Content {
181    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
182        match &self.0 {
183            Repr::Value(v) => v.fmt(f),
184            Repr::Json { text, .. } => f.write_str(&String::from_utf8_lossy(text)),
185        }
186    }
187}
188
189impl Serialize for Content {
190    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
191        if let Repr::Json { text, value } = &self.0 {
192            // serde_json writes a raw value as it is; any other serializer
193            // gets the `Value`.
194            if writing_json() {
195                if let Ok(raw) = serde_json::from_slice::<&RawValue>(text) {
196                    return raw.serialize(s);
197                }
198            }
199            if let Some(v) = value.get() {
200                return v.serialize(s);
201            }
202        }
203        self.value().serialize(s)
204    }
205}
206
207impl<'de> Deserialize<'de> for Content {
208    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
209        Value::deserialize(d).map(Content::from_value)
210    }
211}
212
213impl schemars::JsonSchema for Content {
214    fn inline_schema() -> bool {
215        <Value as schemars::JsonSchema>::inline_schema()
216    }
217    fn schema_name() -> Cow<'static, str> {
218        <Value as schemars::JsonSchema>::schema_name()
219    }
220    fn schema_id() -> Cow<'static, str> {
221        <Value as schemars::JsonSchema>::schema_id()
222    }
223    fn json_schema(generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
224        <Value as schemars::JsonSchema>::json_schema(generator)
225    }
226}
227
228// ---------------------------------------------------------------------------
229// The connection's encoding and its frames
230// ---------------------------------------------------------------------------
231
232/// The encoding of every frame on a connection, fixed when it opens. JSON
233/// text until PERF-9 adds msgpack.
234#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
235#[non_exhaustive]
236pub enum WireEncoding {
237    /// JSON-RPC 2.0 objects, one text message each.
238    #[default]
239    Json,
240}
241
242/// A frame ready for a socket, in its connection's encoding.
243#[derive(Debug, Clone)]
244pub struct WireFrame {
245    bytes: Bytes,
246    fence: bool,
247}
248
249impl WireFrame {
250    /// The frame's bytes (JSON text under [`WireEncoding::Json`]).
251    pub fn bytes(&self) -> &Bytes {
252        &self.bytes
253    }
254
255    /// The frame's bytes, owned.
256    pub fn into_bytes(self) -> Bytes {
257        self.bytes
258    }
259
260    /// A call's first frame: written only after every frame the connection's
261    /// method table queued before it (its subscription's answer among them,
262    /// which jsonrpsee queues when the call is accepted).
263    pub fn fenced(&self) -> bool {
264        self.fence
265    }
266}
267
268/// The frames a transport takes from a connection's calls (plexus-transport's
269/// socket loop puts one in each call's extensions): each item a frame, in
270/// order, written as it is. Cheap to clone.
271#[derive(Clone)]
272pub struct FrameSink {
273    tx: tokio::sync::mpsc::Sender<WireFrame>,
274    encoding: WireEncoding,
275    /// The connection's pool — one spare block a call starts in, so a short
276    /// call allocates none — and (KEEL-59) why it is ending, once it is.
277    /// One `Arc` for both: every call clones the sink.
278    shared: Arc<SinkShared>,
279    /// The most items one notification carries (PERF-8): 0 or 1, one an item.
280    batch: usize,
281    /// BIDIR-6: the connection's input halves. Carried here, not as an entry
282    /// of its own in the extensions, which every call clones: an entry is an
283    /// allocation a call (call.one_item's +2 allocations, +192 bytes).
284    inputs: Option<Arc<super::input::InputTable>>,
285}
286
287/// What every call's [`FrameSink`] on one connection shares.
288#[derive(Default)]
289struct SinkShared {
290    spare: Mutex<Option<BytesMut>>,
291    /// KEEL-59: set by the transport before it closes the connection for a
292    /// reason its calls are told ([`FrameSink::end_saying`]).
293    ending: std::sync::OnceLock<String>,
294}
295
296/// The most items one notification carries when the client offered `batch`
297/// at its upgrade (PERF-8, spec/02): a client may ask for fewer.
298pub const MAX_BATCH: usize = 64;
299
300/// Where a batch stops taking items: once what it holds reaches this many
301/// bytes, so a batch of large items stays small. A queue's 1,024 frames are
302/// bounded by frames, not bytes (PERF.115-37), and each item takes its size
303/// twice from a block: 64 items of 4 KB to a frame held 280 KB a frame and
304/// allocated a 512 KiB block every few frames, 16 KiB still 4,096 B an item
305/// in one run of two, and a ticket body's batch would hold a megabyte. At
306/// 8 KiB a full queue of 4 KB items holds about 18 MB, which the call's 80
307/// spare blocks keep. PERF-17 found a count alone cost a 4 KB stream 27 %, and
308/// said a batch should stop at bytes.
309pub const BATCH_BYTES: usize = 8 * 1024;
310
311/// What the transport's writer reads a [`FrameSink`]'s frames from.
312pub type FrameReceiver = tokio::sync::mpsc::Receiver<WireFrame>;
313
314impl FrameSink {
315    /// A connection's frame queue, bounded at `capacity` frames.
316    pub fn channel(capacity: usize, encoding: WireEncoding) -> (FrameSink, FrameReceiver) {
317        let (tx, rx) = tokio::sync::mpsc::channel(capacity.max(1));
318        (FrameSink { tx, encoding, shared: Arc::new(SinkShared::default()), batch: 0, inputs: None }, rx)
319    }
320
321    /// The same sink for a client that takes batches (it offered `batch` at
322    /// its upgrade): up to `max` items a stream has ready go in one
323    /// notification. 0 or 1: one an item, as before.
324    pub fn batching(mut self, max: usize) -> Self {
325        self.batch = max;
326        self
327    }
328
329    /// BIDIR-6: the same sink carrying the connection's input halves, where a
330    /// method with an `Input` finds its table.
331    pub fn with_inputs(mut self, table: Arc<super::input::InputTable>) -> Self {
332        self.inputs = Some(table);
333        self
334    }
335
336    /// BIDIR-6: the connection's input halves, when its transport carries
337    /// them.
338    pub fn inputs(&self) -> Option<&Arc<super::input::InputTable>> {
339        self.inputs.as_ref()
340    }
341
342    /// The most items one notification carries: 0 or 1, one an item.
343    pub fn batch(&self) -> usize {
344        self.batch
345    }
346
347    /// The connection's encoding.
348    pub fn encoding(&self) -> WireEncoding {
349        self.encoding
350    }
351
352    /// Whether the connection is gone.
353    pub fn is_closed(&self) -> bool {
354        self.tx.is_closed()
355    }
356
357    /// KEEL-59: the connection is about to close because its sign-in ended
358    /// (`why`, for the caller): from now each call on it, as it learns the
359    /// connection is closing, writes one `unauthenticated` item saying `why`
360    /// before it ends — the transport closes the method table first and the
361    /// frames after, so those items go out ahead of the close. The first
362    /// `why` stands.
363    pub fn end_saying(&self, why: &str) {
364        let _ = self.shared.ending.set(why.to_string());
365    }
366
367    /// KEEL-59: why the connection is ending, when the transport said.
368    pub fn ending(&self) -> Option<&str> {
369        self.shared.ending.get().map(String::as_str)
370    }
371
372    fn take_block(&self) -> Option<BytesMut> {
373        self.shared.spare.lock().ok().and_then(|mut s| s.take())
374    }
375
376    fn give_block(&self, block: BytesMut) {
377        if block.capacity() <= Buffer::POOLED {
378            if let Ok(mut s) = self.shared.spare.lock() {
379                if s.is_none() {
380                    *s = Some(block);
381                }
382            }
383        }
384    }
385}
386
387impl std::fmt::Debug for FrameSink {
388    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
389        f.debug_struct("FrameSink").field("encoding", &self.encoding).field("batch", &self.batch).field("closed", &self.tx.is_closed()).finish()
390    }
391}
392
393// ---------------------------------------------------------------------------
394// The buffer: blocks a call's items and frames are written into
395// ---------------------------------------------------------------------------
396
397/// A call's buffer. Each item and each frame is written at the end of the
398/// current block and split off as `Bytes` sharing it; a block is reused once
399/// every frame cut from it has been written and dropped, and a new one is
400/// allocated only when none is free.
401struct Buffer {
402    cur: BytesMut,
403    /// Blocks still holding frames in flight, kept to be reused once free.
404    spare: Vec<BytesMut>,
405    /// The size a new block is made at: grown with the frames it holds.
406    block: usize,
407    /// Whether a block has been made (or taken from the pool) yet.
408    started: bool,
409    /// Blocks made, for the tests.
410    #[cfg(test)]
411    made: usize,
412}
413
414impl Default for Buffer {
415    fn default() -> Self {
416        Buffer {
417            cur: BytesMut::new(),
418            spare: Vec::new(),
419            block: Self::FIRST,
420            started: false,
421            #[cfg(test)]
422            made: 0,
423        }
424    }
425}
426
427impl Buffer {
428    /// A first block: a short call's frames fit.
429    const FIRST: usize = 8 * 1024;
430    /// The largest block made for a stream's frames (one larger item gets a
431    /// block of its own size).
432    const MOST: usize = 512 * 1024;
433    /// The largest block a connection keeps for its next call.
434    const POOLED: usize = 64 * 1024;
435    /// Blocks kept to be reused. A stream that outruns its socket has the
436    /// connection's whole queue in flight (1,024 frames), and each item has
437    /// taken its size twice from a block, content and frame: 8.8 MB at 4 KB an
438    /// item, 36 MB at a ticket body. Blocks that hold fewer than that are
439    /// dropped before they come free, and every block filled is a new one, so
440    /// a faster encode allocates more: three held 8 KB an item at 4 KB and 37 KB
441    /// at a body (PERF-34; PERF-9 found it with msgpack, at b80cb2e). They are
442    /// bytes those frames hold anyway.
443    const SPARE: usize = 80;
444    /// Blocks kept once the queue has drained: what a long watch holds.
445    const DRAINED: usize = 3;
446
447    fn from_block(block: Option<BytesMut>) -> Self {
448        match block {
449            Some(cur) => Buffer { block: cur.capacity().max(Self::FIRST), cur, started: true, ..Buffer::default() },
450            None => Buffer::default(),
451        }
452    }
453
454    /// Room for `n` more bytes in the current block: it, or a free block, or
455    /// a new one.
456    fn room(&mut self, n: usize) {
457        if self.cur.capacity() - self.cur.len() >= n {
458            return;
459        }
460        if self.cur.try_reclaim(n) {
461            // None of this block's frames is left, and older ones went first.
462            self.spare.truncate(Self::DRAINED);
463            return;
464        }
465        // The current block holds unsent frames, or is too small: keep it
466        // for later and take a free one, if any is free.
467        let free = self.spare.iter_mut().position(|b| b.try_reclaim(n));
468        let next = match free {
469            Some(i) => self.spare.swap_remove(i),
470            None => {
471                // Every block is busy: the frames outrun the socket, so the
472                // next block holds more of them.
473                if self.started {
474                    self.block = (self.block * 2).clamp(Self::FIRST, Self::MOST);
475                }
476                self.started = true;
477                #[cfg(test)]
478                {
479                    self.made += 1;
480                }
481                BytesMut::with_capacity(self.block.max(n))
482            }
483        };
484        let old = std::mem::replace(&mut self.cur, next);
485        if old.capacity() > 0 {
486            if self.spare.len() >= Self::SPARE {
487                self.spare.remove(0);
488            }
489            self.spare.push(old);
490        }
491    }
492
493    /// What was written since the last split, as `Bytes`.
494    fn split(&mut self) -> Bytes {
495        self.cur.split().freeze()
496    }
497
498    /// The block a call with no connection leaves for its thread's next one:
499    /// all of it, with no frame of a call in flight, and not one a stream grew.
500    fn into_idle(mut self) -> Option<BytesMut> {
501        let _ = self.cur.try_reclaim(Self::FIRST);
502        (Self::FIRST..=Self::POOLED).contains(&self.cur.capacity()).then_some(self.cur)
503    }
504
505    /// The block to give back to the connection's pool: the current one,
506    /// whatever is left of it (frames still in flight keep what they hold).
507    fn into_block(self) -> Option<BytesMut> {
508        (self.cur.capacity() >= 1024).then_some(self.cur)
509    }
510}
511
512// ---------------------------------------------------------------------------
513// The pipe's encoder: the events of the stream the pipe polls
514// ---------------------------------------------------------------------------
515
516/// The pipe's encoder, for the task that polls a call's stream.
517struct Encoder {
518    /// The connection's encoding: JSON until PERF-9 reads it here.
519    #[allow(dead_code)]
520    encoding: WireEncoding,
521    buffer: RefCell<Buffer>,
522    /// How deep the poll is in streams [`wrap_stream`] wrapped: only the
523    /// outermost encodes — a stream polled inside a method's own (a call
524    /// it routes and reads in process) keeps its items as `Value`s.
525    ///
526    /// [`wrap_stream`]: super::streaming::wrap_stream
527    depth: Cell<u32>,
528    /// The last content's size, to make room for the next.
529    last: Cell<usize>,
530}
531
532tokio::task_local! {
533    static WIRE: Encoder;
534}
535
536thread_local! {
537    /// The pipe's serde_json writer is serializing an event on this thread.
538    static WRITING_JSON: Cell<u32> = const { Cell::new(0) };
539}
540
541/// Whether the serializer at work on this thread is the pipe's JSON writer
542/// (so a [`Shared`] event or an encoded [`Content`] may write its bytes as
543/// they are).
544fn writing_json() -> bool {
545    WRITING_JSON.with(|w| w.get() > 0)
546}
547
548struct WritingJson;
549
550impl WritingJson {
551    fn on() -> Self {
552        WRITING_JSON.with(|w| w.set(w.get() + 1));
553        WritingJson
554    }
555}
556
557impl Drop for WritingJson {
558    fn drop(&mut self) {
559        WRITING_JSON.with(|w| w.set(w.get().saturating_sub(1)));
560    }
561}
562
563/// Run `poll` (a wrapped stream's poll of its method's stream) one stream
564/// deeper: what it yields is not the pipe's to encode.
565pub(crate) fn nested<R>(poll: impl FnOnce() -> R) -> R {
566    if WIRE.try_with(|e| e.depth.set(e.depth.get() + 1)).is_err() {
567        return poll();
568    }
569    // Put back after the poll, a panic included.
570    struct Back;
571    impl Drop for Back {
572        fn drop(&mut self) {
573            let _ = WIRE.try_with(|e| e.depth.set(e.depth.get().saturating_sub(1)));
574        }
575    }
576    let _back = Back;
577    poll()
578}
579
580/// `event` encoded once into the pipe's buffer — when the pipe is polling
581/// this stream directly, the event is not a credential's (whose envelope is
582/// assembled as before) and it serializes. `None`: make a `Value` as before.
583pub(crate) fn encode<T: Serialize + ?Sized>(event: &T) -> Option<Content> {
584    WIRE.try_with(|e| {
585        if e.depth.get() > 0 {
586            return None;
587        }
588        let mut buffer = e.buffer.borrow_mut();
589        buffer.room(e.last.get().saturating_mul(2).max(256));
590        debug_assert!(buffer.cur.is_empty());
591        let (written, captured) = plexus_auth_core::credential::run_with_credential_capture(|| {
592            let _json = WritingJson::on();
593            json::write(&mut buffer.cur, event).is_ok()
594        });
595        if !written || !captured.is_empty() {
596            buffer.cur.clear();
597            return None;
598        }
599        e.last.set(buffer.cur.len());
600        Some(Content::json(buffer.split()))
601    })
602    .ok()
603    .flatten()
604}
605
606thread_local! {
607    /// The block of a call with no frame sink, for this thread's next one.
608    /// Such a call has no connection to keep a block, and it was half of what
609    /// a one-item call allocated (PERF-27).
610    static IDLE: Cell<Option<BytesMut>> = const { Cell::new(None) };
611}
612
613/// One call's frames: the notification around each item. With no frame sink
614/// there is none to write, so no prefix: jsonrpsee's sink writes its own.
615#[derive(Default)]
616struct Frames {
617    /// `{"jsonrpc":"2.0","method":M,"params":{"subscription":S,"result":`
618    prefix: Vec<u8>,
619    /// A `data` item's opening, `{"type":"data","metadata":…,"content_type":…,"content":`,
620    /// for the stream's metadata (shared by its items) and content type.
621    head: Option<(Arc<StreamMetadata>, Cow<'static, str>, Vec<u8>)>,
622    /// A batch's (PERF-8): `,"metadata":…,"results":[` for the stream's
623    /// metadata, and a `data` item's opening without it,
624    /// `{"type":"data","content_type":…,"content":`, for its content type.
625    batch: Option<(Arc<StreamMetadata>, Vec<u8>)>,
626    bare: Option<(Cow<'static, str>, Vec<u8>)>,
627}
628
629/// Where a notification's `params` stop and its `result` begins, in [`Frames::prefix`].
630const RESULT: &[u8] = br#","result":"#;
631
632impl Frames {
633    fn new(method: &str, subscription: &jsonrpsee::types::SubscriptionId<'_>) -> Self {
634        // Sized once: each grew from its first literal, and three reallocations a call.
635        let mut prefix = Vec::with_capacity(64);
636        prefix.extend_from_slice(br#"{"jsonrpc":"2.0","method":"#);
637        let _ = serde_json::to_writer(&mut prefix, method);
638        prefix.extend_from_slice(br#","params":{"subscription":"#);
639        let _ = serde_json::to_writer(&mut prefix, subscription);
640        prefix.extend_from_slice(RESULT);
641        Frames { prefix, head: None, batch: None, bare: None }
642    }
643
644    /// `item`'s JSON, written at the end of `out`.
645    fn item(&mut self, out: &mut BytesMut, item: &PlexusStreamItem) {
646        match item {
647            PlexusStreamItem::Data { metadata, content_type, content } => {
648                let fresh = match &self.head {
649                    Some((m, ct, _)) => !Arc::ptr_eq(m, metadata) || ct != content_type,
650                    None => true,
651                };
652                if fresh {
653                    let mut head = Vec::with_capacity(128);
654                    head.extend_from_slice(br#"{"type":"data","metadata":"#);
655                    let _ = serde_json::to_writer(&mut head, &**metadata);
656                    head.extend_from_slice(br#","content_type":"#);
657                    let _ = serde_json::to_writer(&mut head, content_type.as_ref());
658                    head.extend_from_slice(br#","content":"#);
659                    self.head = Some((metadata.clone(), content_type.clone(), head));
660                }
661                let head = &self.head.as_ref().expect("made above").2;
662                out.reserve(head.len() + content.json_bytes().map_or(64, Bytes::len) + 1);
663                out.put_slice(head);
664                content.write_json(out);
665                out.put_u8(b'}');
666            }
667            other => {
668                let _ = serde_json::to_writer((&mut *out).writer(), other);
669            }
670        }
671    }
672
673    /// `items`, ready together, in one notification (PERF-8, spec/02):
674    /// `{"jsonrpc":"2.0","method":M,"params":{"subscription":S,"metadata":…,"results":[…]}}`.
675    /// The metadata is the first `data` item's, said once: a `data` item whose
676    /// metadata writes the same leaves its own out; any other item is written
677    /// whole, as alone.
678    /// One item alone is today's frame.
679    fn batch(&mut self, buffer: &mut Buffer, items: &[PlexusStreamItem]) -> Bytes {
680        if let [item] = items {
681            return self.frame(buffer, item);
682        }
683        let shared = items.iter().find_map(|item| match item {
684            PlexusStreamItem::Data { metadata, .. } => Some(metadata),
685            _ => None,
686        });
687        let open = match shared {
688            Some(m) => {
689                if !matches!(&self.batch, Some((had, _)) if Arc::ptr_eq(had, m)) {
690                    let mut open = Vec::with_capacity(128);
691                    open.extend_from_slice(br#","metadata":"#);
692                    let _ = serde_json::to_writer(&mut open, &**m);
693                    open.extend_from_slice(br#","results":["#);
694                    self.batch = Some((m.clone(), open));
695                }
696                &self.batch.as_ref().expect("made above").1[..]
697            }
698            None => br#","results":["#,
699        };
700        let content: usize = items
701            .iter()
702            .map(|item| match item {
703                PlexusStreamItem::Data { content, .. } => content.json_bytes().map_or(64, Bytes::len) + 64,
704                _ => 256,
705            })
706            .sum();
707        let start = &self.prefix[..self.prefix.len() - RESULT.len()];
708        buffer.room(start.len() + open.len() + content + 4);
709        buffer.cur.put_slice(start);
710        buffer.cur.put_slice(open);
711        for (n, item) in items.iter().enumerate() {
712            if n > 0 {
713                buffer.cur.put_u8(b',');
714            }
715            match item {
716                PlexusStreamItem::Data { metadata, content_type, content } if shared.is_some_and(|m| same_metadata(m, metadata)) => {
717                    if !matches!(&self.bare, Some((ct, _)) if ct == content_type) {
718                        let mut bare = Vec::with_capacity(64);
719                        bare.extend_from_slice(br#"{"type":"data","content_type":"#);
720                        let _ = serde_json::to_writer(&mut bare, content_type.as_ref());
721                        bare.extend_from_slice(br#","content":"#);
722                        self.bare = Some((content_type.clone(), bare));
723                    }
724                    let bare = &self.bare.as_ref().expect("made above").1;
725                    buffer.cur.reserve(bare.len() + content.json_bytes().map_or(64, Bytes::len) + 1);
726                    buffer.cur.put_slice(bare);
727                    content.write_json(&mut buffer.cur);
728                    buffer.cur.put_u8(b'}');
729                }
730                other => self.item(&mut buffer.cur, other),
731            }
732        }
733        buffer.cur.put_slice(b"]}}");
734        buffer.split()
735    }
736
737    /// The notification carrying `item`: the frame a socket writes.
738    fn frame(&mut self, buffer: &mut Buffer, item: &PlexusStreamItem) -> Bytes {
739        let content = match item {
740            PlexusStreamItem::Data { content, .. } => content.json_bytes().map_or(256, Bytes::len),
741            _ => 256,
742        };
743        buffer.room(self.prefix.len() + content + 256);
744        buffer.cur.put_slice(&self.prefix);
745        self.item(&mut buffer.cur, item);
746        buffer.cur.put_slice(b"}}");
747        buffer.split()
748    }
749
750    /// The notification carrying `body`, JSON text this side wrote.
751    fn body(&mut self, buffer: &mut Buffer, body: &[u8]) -> Bytes {
752        buffer.room(self.prefix.len() + body.len() + 2);
753        buffer.cur.put_slice(&self.prefix);
754        buffer.cur.put_slice(body);
755        buffer.cur.put_slice(b"}}");
756        buffer.split()
757    }
758
759    /// `item` alone, for jsonrpsee's sink, which wraps it in the notification:
760    /// text of its own, its exact size, written once and not read again. The
761    /// copy and the check this took were most of the 6,644 instructions PERF-27
762    /// took off a one-item call's 50,842.
763    fn raw_item(&mut self, item: &PlexusStreamItem) -> Result<Box<RawValue>, serde_json::Error> {
764        if !matches!(item, PlexusStreamItem::Data { .. }) {
765            return serde_json::value::to_raw_value(item);
766        }
767        let mut text = BytesMut::new();
768        self.item(&mut text, item);
769        // This one stays: `Content::from_json` holds text to JSON's grammar, not to UTF-8.
770        let text = String::from_utf8(Vec::from(text)).map_err(serde::ser::Error::custom)?;
771        // SAFETY: one JSON value with nothing around it. `Frames::item` writes
772        // a `data` item's opening, then its content, then `}`. The opening is
773        // literal keys around values serde_json wrote into a `Vec`, which
774        // cannot fail. The content is one value: `encode`'s text, whole (a
775        // failed write leaves a `Value` instead); text `Content::from_json`
776        // parsed, by the same parse `RawValue::from_string` would run here; or
777        // a `Value`, which serde_json cannot fail to write.
778        // A debug build parses it here all the same (tests/no_frame_sink.rs).
779        Ok(unsafe { RawValue::from_string_unchecked(text) })
780    }
781}
782
783/// Pipe a call's stream to its accepted subscription: each item encoded
784/// once and written as one frame.
785///
786/// With a [`FrameSink`] in the call's extensions (plexus-transport's socket
787/// loop) each frame goes to the socket's writer as it is, the first fenced
788/// behind the subscription's answer; without one, each item goes to
789/// jsonrpsee's sink as one raw value. The pipe ends
790/// when the stream does, or when the caller lets go (an unsubscribe, a lost
791/// socket), dropping the stream at once.
792pub async fn pipe(sink: jsonrpsee::SubscriptionSink, stream: super::streaming::PlexusStream, ext: &http::Extensions) -> jsonrpsee::core::SubscriptionResult {
793    let frames = ext.get::<FrameSink>().cloned();
794    let encoding = frames.as_ref().map(FrameSink::encoding).unwrap_or_default();
795    let block = match &frames {
796        Some(to) => to.take_block(),
797        None => IDLE.try_with(Cell::take).ok().flatten(),
798    };
799    let buffer = Buffer::from_block(block);
800    let encoder = Encoder { encoding, buffer: RefCell::new(buffer), depth: Cell::new(0), last: Cell::new(0) };
801    WIRE.scope(encoder, run(sink, stream, frames)).await
802}
803
804async fn run(sink: jsonrpsee::SubscriptionSink, mut stream: super::streaming::PlexusStream, frames: Option<FrameSink>) -> jsonrpsee::core::SubscriptionResult {
805    use futures::StreamExt;
806    let mut notification = match &frames {
807        Some(_) => Frames::new(sink.method_name(), &sink.subscription_id()),
808        None => Frames::default(),
809    };
810    let mut first = true;
811    // KEEL-59: whether the call already said its end (a `done` or an
812    // `error` went out): a connection ending then adds nothing.
813    let mut said_end = false;
814    // A batch's items, kept for the call: no allocation until two are ready together.
815    let mut ready: Vec<PlexusStreamItem> = Vec::new();
816    let out: jsonrpsee::core::SubscriptionResult = async {
817        loop {
818            let mut closing = false;
819            let item = tokio::select! {
820                biased;
821                _ = sink.closed() => {
822                    closing = true;
823                    None
824                }
825                item = stream.next() => item,
826            };
827            let Some(item) = item else {
828                // KEEL-59: closing because its sign-in ended: the call says
829                // so, once, before the close. Made apart and boxed, awaited
830                // with no item alive: this rare await stays out of every
831                // call's state.
832                if closing {
833                    if let Some(say) = frames.as_ref().filter(|_| !said_end).and_then(|to| saying_end(to, &mut notification, sink.method_name(), first)) {
834                        say.await;
835                    }
836                }
837                return Ok(());
838            };
839            said_end = matches!(item, PlexusStreamItem::Done { .. } | PlexusStreamItem::Error { .. });
840            match &frames {
841                Some(to) => {
842                    // PERF-8: what else the stream has ready now goes with it,
843                    // for a client that takes batches. Never what is not ready
844                    // yet: a lone item goes at once, in today's form.
845                    let mut ended = false;
846                    let mut held = if to.batch > 1 { size(&item) } else { BATCH_BYTES };
847                    let more = held < BATCH_BYTES;
848                    let bytes = match more.then(|| ready_now(&mut stream, &mut ended)).flatten() {
849                        None => WIRE.with(|e| notification.frame(&mut e.buffer.borrow_mut(), &item)),
850                        Some(next) => {
851                            held += size(&next);
852                            ready.push(item);
853                            ready.push(next);
854                            while ready.len() < to.batch && held < BATCH_BYTES && !ended {
855                                match ready_now(&mut stream, &mut ended) {
856                                    Some(more) => {
857                                        held += size(&more);
858                                        ready.push(more);
859                                    }
860                                    None => break,
861                                }
862                            }
863                            let bytes = WIRE.with(|e| notification.batch(&mut e.buffer.borrow_mut(), &ready));
864                            ready.clear();
865                            bytes
866                        }
867                    };
868                    if to.tx.send(WireFrame { bytes, fence: first }).await.is_err() || ended {
869                        return Ok(());
870                    }
871                }
872                None => {
873                    // jsonrpsee's sink takes a raw value, which it wraps in
874                    // the notification: a copy, the price of a transport
875                    // without frames of its own (stdio, a module called in memory).
876                    let raw = notification.raw_item(&item)?;
877                    drop(item);
878                    sink.send(raw).await?;
879                }
880            }
881            first = false;
882        }
883    }
884    .await;
885    drop(stream);
886    let buffer = WIRE.with(|e| std::mem::take(&mut *e.buffer.borrow_mut()));
887    match &frames {
888        Some(to) => {
889            if let Some(block) = buffer.into_block() {
890                to.give_block(block);
891            }
892        }
893        None => {
894            let _ = IDLE.try_with(|idle| idle.set(buffer.into_idle()));
895        }
896    }
897    out
898}
899
900/// KEEL-59: why the input half closed with the call's last item: the
901/// refusal's own kind for a call ended `forbidden` or `unauthenticated`,
902/// else the method's end.
903fn closed_by(item: &PlexusStreamItem) -> &'static str {
904    match item {
905        PlexusStreamItem::Error { fields, .. } => match fields.get("error_kind").and_then(serde_json::Value::as_str) {
906            Some("forbidden") => "forbidden",
907            Some("unauthenticated") => "unauthenticated",
908            _ => "method_ended",
909        },
910        _ => "method_ended",
911    }
912}
913
914/// KEEL-59: the frame a call writes as its connection closes because its
915/// sign-in ended, sent — or nothing, when the connection is not ending so.
916fn saying_end(to: &FrameSink, notification: &mut Frames, method: &str, first: bool) -> Option<std::pin::Pin<Box<dyn std::future::Future<Output = ()> + Send>>> {
917    let why = to.ending()?;
918    let bytes = WIRE.with(|e| notification.frame(&mut e.buffer.borrow_mut(), &ending_item(method, why)));
919    let tx = to.tx.clone();
920    Some(Box::pin(async move {
921        let _ = tx.send(WireFrame { bytes, fence: first }).await;
922    }))
923}
924
925/// KEEL-59: the item a call ends with when its connection closes because
926/// its sign-in ended: `unauthenticated`, saying `why`. Its source is the
927/// service the subscription is in (`menger.call` → `menger`).
928fn ending_item(method: &str, why: &str) -> PlexusStreamItem {
929    let ns = method.split('.').next().unwrap_or(method);
930    PlexusStreamItem::from_plexus_error(
931        super::types::StreamMetadata::new(vec![ns.into()], super::context::PlexusContext::hash()),
932        &super::plexus::PlexusError::Unauthenticated(why.to_string()),
933        false,
934    )
935}
936
937/// About what an item writes into a batch: its encoded content, or a guess.
938fn size(item: &PlexusStreamItem) -> usize {
939    match item {
940        PlexusStreamItem::Data { content, .. } => content.json_bytes().map_or(256, Bytes::len),
941        _ => 128,
942    }
943}
944
945/// Whether two items' metadata write the same JSON: the same one, or equal
946/// (a child's items, relayed, each bring their own copy).
947fn same_metadata(a: &Arc<StreamMetadata>, b: &Arc<StreamMetadata>) -> bool {
948    Arc::ptr_eq(a, b) || (a.timestamp == b.timestamp && a.plexus_hash == b.plexus_hash && a.provenance == b.provenance)
949}
950
951/// The stream's next item if it is ready now: no waiting, so a batch never
952/// holds an item back for one that has not come. `ended` once the stream is.
953fn ready_now(stream: &mut super::streaming::PlexusStream, ended: &mut bool) -> Option<PlexusStreamItem> {
954    use futures::StreamExt;
955    match futures::FutureExt::now_or_never(stream.next()) {
956        Some(Some(item)) => Some(item),
957        Some(None) => {
958            *ended = true;
959            None
960        }
961        None => None,
962    }
963}
964
965// ---------------------------------------------------------------------------
966// The pipe of a call with an input half
967// ---------------------------------------------------------------------------
968
969/// What a call with an input half answers: its stream, or (BIDIR-17's
970/// review) the route that will make it, still resolving because its handler
971/// reads its input first. An error is the item to send.
972pub(crate) enum Output<'a> {
973    Ready(super::streaming::PlexusStream),
974    Routing(std::pin::Pin<&'a mut (dyn std::future::Future<Output = Result<super::streaming::PlexusStream, Value>> + Send + 'a)>),
975}
976
977impl Output<'_> {
978    /// The next turn of the output half: an item, or the route's refusal.
979    async fn next(&mut self) -> Turn {
980        std::future::poll_fn(|cx| loop {
981            match self {
982                Output::Ready(stream) => return stream.as_mut().poll_next(cx).map(Turn::Item),
983                Output::Routing(route) => match route.as_mut().poll(cx) {
984                    std::task::Poll::Ready(Ok(stream)) => *self = Output::Ready(stream),
985                    std::task::Poll::Ready(Err(item)) => return std::task::Poll::Ready(Turn::Failed(item)),
986                    std::task::Poll::Pending => return std::task::Poll::Pending,
987                },
988            }
989        })
990        .await
991    }
992}
993
994/// [`pipe`] for a call with an input half ([`super::input`]): the subscription
995/// is already accepted, and its first frame is the first `credit`.
996pub(crate) async fn pipe_duplex(sink: jsonrpsee::SubscriptionSink, out: Output<'_>, duplex: super::input::Duplex) -> jsonrpsee::core::SubscriptionResult {
997    let encoding = duplex.to.encoding();
998    let buffer = Buffer::from_block(duplex.to.take_block());
999    let encoder = Encoder { encoding, buffer: RefCell::new(buffer), depth: Cell::new(0), last: Cell::new(0) };
1000    WIRE.scope(encoder, run_duplex(sink, out, duplex)).await
1001}
1002
1003/// One frame of the input half, as `body` says.
1004async fn control(to: &FrameSink, notification: &mut Frames, body: &str, fence: bool) -> Result<(), ()> {
1005    let bytes = WIRE.with(|e| notification.body(&mut e.buffer.borrow_mut(), body.as_bytes()));
1006    to.tx.send(WireFrame { bytes, fence }).await.map_err(drop)
1007}
1008
1009/// `input_closed`: the half is over, said once, before anything final.
1010fn input_closed(reason: &str, ack: Option<u64>) -> String {
1011    match ack {
1012        Some(seq) => format!(r#"{{"type":"input_closed","reason":{},"ack":{seq}}}"#, Value::from(reason)),
1013        None => format!(r#"{{"type":"input_closed","reason":{}}}"#, Value::from(reason)),
1014    }
1015}
1016
1017/// What the loop below learned this turn.
1018enum Turn {
1019    /// The method's next item.
1020    Item(Option<PlexusStreamItem>),
1021    /// Nothing to write but what the ledger owes.
1022    Moved,
1023    /// The call is refused.
1024    Refused(super::duplex_gate::DuplexRefusal),
1025    /// The route answered an error: this item.
1026    Failed(Value),
1027}
1028
1029async fn run_duplex(sink: jsonrpsee::SubscriptionSink, mut output: Output<'_>, duplex: super::input::Duplex) -> jsonrpsee::core::SubscriptionResult {
1030    use futures::StreamExt;
1031    let super::input::Duplex { ledger, mut gate, inbox, credit, ns, to, slot } = duplex;
1032    let mut inbox = Some(inbox);
1033    let mut slot = Some(slot);
1034    let mut notification = Frames::new(sink.method_name(), &sink.subscription_id());
1035    let mut acked = 0u64;
1036    // KEEL-59: whether the call already said its end.
1037    let mut said_end = false;
1038    let out: Result<(), ()> = async {
1039        // Fenced behind the subscription's answer (the client holds nothing
1040        // yet: it may read this before it has the id).
1041        control(&to, &mut notification, &format!(r#"{{"type":"credit","n":{}}}"#, ledger.window()), true).await?;
1042        loop {
1043            let mut closing = false;
1044            let turn = tokio::select! {
1045                biased;
1046                _ = sink.closed() => {
1047                    closing = true;
1048                    Turn::Moved
1049                }
1050                frame = gate.next(), if inbox.is_some() => match frame {
1051                    Some(Ok(batch)) => {
1052                        // The handler let go of its input: the next turn says so.
1053                        let _ = inbox.as_ref().expect("guarded").send(batch);
1054                        Turn::Moved
1055                    }
1056                    Some(Err(why)) => Turn::Refused(why),
1057                    None => {
1058                        inbox = None;
1059                        Turn::Moved
1060                    }
1061                },
1062                _ = ledger.woken() => Turn::Moved,
1063                turn = output.next() => turn,
1064            };
1065            if closing {
1066                // KEEL-59: closing because its sign-in ended: both halves
1067                // end, said once, before the close — awaited outside the
1068                // select, with no item alive.
1069                drop(turn);
1070                if let (Some(why), false) = (to.ending(), said_end) {
1071                    if slot.take().is_some() && !ledger.client_ended() {
1072                        control(&to, &mut notification, &input_closed("unauthenticated", ledger.last_done()), false).await?;
1073                    }
1074                    let item = serde_json::to_string(&ending_item(sink.method_name(), why)).unwrap_or_default();
1075                    return control(&to, &mut notification, &item, false).await;
1076                }
1077                return Ok(());
1078            }
1079            if let Turn::Failed(item) = turn {
1080                if slot.take().is_some() && !ledger.client_ended() {
1081                    control(&to, &mut notification, &input_closed("method_ended", ledger.last_done()), false).await?;
1082                }
1083                return control(&to, &mut notification, &serde_json::to_string(&item).unwrap_or_default(), false).await;
1084            }
1085            let (item, refused) = match turn {
1086                Turn::Failed(_) => unreachable!("answered above"),
1087                Turn::Refused(why) => (None, Some(why)),
1088                Turn::Item(item) => (Some(item), ledger.take_refusal()),
1089                Turn::Moved => (None, ledger.take_refusal()),
1090            };
1091            if let Some(owed) = ledger.owed(acked) {
1092                if let Some(seq) = owed.ack {
1093                    control(&to, &mut notification, &format!(r#"{{"type":"ack","seq":{seq}}}"#), false).await?;
1094                }
1095                acked = owed.done;
1096                if owed.credit > 0 {
1097                    credit.grant(owed.credit);
1098                    control(&to, &mut notification, &format!(r#"{{"type":"credit","n":{}}}"#, owed.credit), false).await?;
1099                }
1100            }
1101            if let Some(why) = refused {
1102                // The handler's input ends with the refusal, and the call
1103                // with it: nothing the handler says after it goes out.
1104                if slot.take().is_some() && !ledger.client_ended() {
1105                    control(&to, &mut notification, &input_closed(why.kind(), ledger.last_done()), false).await?;
1106                }
1107                let item = serde_json::to_string(&why.to_item(&ns)).unwrap_or_default();
1108                return control(&to, &mut notification, &item, false).await;
1109            }
1110            if ledger.abandoned() && slot.is_some() && !ledger.client_ended() {
1111                slot = None;
1112                inbox = None;
1113                control(&to, &mut notification, &input_closed("method_ended", ledger.last_done()), false).await?;
1114            }
1115            let Some(item) = item else { continue };
1116            let Some(item) = item else { return Ok(()) };
1117            match &item {
1118                // After `done` there is no channel to tell anything on.
1119                PlexusStreamItem::Done { .. } | PlexusStreamItem::Error { .. } => {
1120                    said_end = true;
1121                    inbox = None;
1122                    if slot.take().is_some() && !ledger.client_ended() {
1123                        // KEEL-59: a call the dispatch's hold ended says so on
1124                        // its input half as the input half's own refusal does.
1125                        control(&to, &mut notification, &input_closed(closed_by(&item), ledger.last_done()), false).await?;
1126                    }
1127                }
1128                _ => {}
1129            }
1130            let bytes = WIRE.with(|e| notification.frame(&mut e.buffer.borrow_mut(), &item));
1131            drop(item);
1132            to.tx.send(WireFrame { bytes, fence: false }).await.map_err(drop)?;
1133        }
1134    }
1135    .await;
1136    drop(output);
1137    let _ = out; // Err: the socket is gone, as the call's end says.
1138    if let Some(block) = WIRE.with(|e| std::mem::take(&mut *e.buffer.borrow_mut())).into_block() {
1139        to.give_block(block);
1140    }
1141    Ok(())
1142}
1143
1144// ---------------------------------------------------------------------------
1145// Shared: one event, many streams
1146// ---------------------------------------------------------------------------
1147
1148/// An event many streams send — one change fanned out to every watcher.
1149/// The first socket that sends it encodes it, once; every other writes
1150/// those bytes as they are (PERF-7's fan-out). Anywhere else (in process, a
1151/// `Value`, another encoding) it serializes as `T` does. Reads as `T`.
1152///
1153/// An event that carries a credential is not kept encoded: each stream
1154/// encodes it, so each assembles its own `_credentials` envelope.
1155pub struct Shared<T>(Arc<SharedInner<T>>);
1156
1157struct SharedInner<T> {
1158    value: T,
1159    /// The JSON the first socket wrote (`None`: never kept — a credential).
1160    json: OnceLock<Option<Box<RawValue>>>,
1161}
1162
1163impl<T> Shared<T> {
1164    /// `value`, to be sent by many streams.
1165    pub fn new(value: T) -> Self {
1166        Shared(Arc::new(SharedInner { value, json: OnceLock::new() }))
1167    }
1168
1169    /// Whether this event has been encoded (a socket has sent it).
1170    pub fn is_encoded(&self) -> bool {
1171        matches!(self.0.json.get(), Some(Some(_)))
1172    }
1173}
1174
1175impl<T: Serialize> Shared<T> {
1176    fn encoded(&self) -> Option<&RawValue> {
1177        self.0
1178            .json
1179            .get_or_init(|| {
1180                let (text, captured) = plexus_auth_core::credential::run_with_credential_capture(|| serde_json::to_string(&self.0.value));
1181                match text {
1182                    Ok(text) if captured.is_empty() => RawValue::from_string(text).ok(),
1183                    _ => None,
1184                }
1185            })
1186            .as_deref()
1187    }
1188}
1189
1190impl<T> Clone for Shared<T> {
1191    fn clone(&self) -> Self {
1192        Shared(self.0.clone())
1193    }
1194}
1195
1196impl<T> std::ops::Deref for Shared<T> {
1197    type Target = T;
1198    fn deref(&self) -> &T {
1199        &self.0.value
1200    }
1201}
1202
1203impl<T: std::fmt::Debug> std::fmt::Debug for Shared<T> {
1204    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1205        self.0.value.fmt(f)
1206    }
1207}
1208
1209impl<T: Default> Default for Shared<T> {
1210    fn default() -> Self {
1211        Shared::new(T::default())
1212    }
1213}
1214
1215impl<T: Serialize> Serialize for Shared<T> {
1216    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
1217        if writing_json() {
1218            if let Some(raw) = self.encoded() {
1219                return raw.serialize(s);
1220            }
1221        }
1222        self.0.value.serialize(s)
1223    }
1224}
1225
1226impl<'de, T: Deserialize<'de>> Deserialize<'de> for Shared<T> {
1227    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
1228        T::deserialize(d).map(Shared::new)
1229    }
1230}
1231
1232impl<T: schemars::JsonSchema> schemars::JsonSchema for Shared<T> {
1233    fn inline_schema() -> bool {
1234        T::inline_schema()
1235    }
1236    fn schema_name() -> Cow<'static, str> {
1237        T::schema_name()
1238    }
1239    fn schema_id() -> Cow<'static, str> {
1240        T::schema_id()
1241    }
1242    fn json_schema(generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
1243        T::json_schema(generator)
1244    }
1245}
1246
1247#[cfg(test)]
1248mod tests {
1249    use std::collections::{BTreeMap, HashMap};
1250
1251    use super::*;
1252
1253    #[test]
1254    fn content_reads_as_its_value_either_way() {
1255        let v = serde_json::json!({"b": [1, 2], "a": "x"});
1256        let encoded = Content::from_json(Bytes::from_static(br#"{"b":[1,2],"a":"x"}"#)).unwrap();
1257        let valued = Content::from(v.clone());
1258        assert!(encoded.is_encoded() && !valued.is_encoded());
1259        assert_eq!(encoded, v);
1260        assert_eq!(valued, v);
1261        assert_eq!(encoded, valued);
1262        assert_eq!(encoded["a"], "x");
1263        assert_eq!(encoded.decode::<serde_json::Map<String, Value>>().unwrap().len(), 2);
1264        assert_eq!(serde_json::to_value(&encoded).unwrap(), v);
1265        assert_eq!(serde_json::to_string(&encoded).unwrap(), serde_json::to_string(&v).unwrap(), "outside the pipe it writes its Value");
1266        assert_eq!(encoded.into_value(), v);
1267        assert!(Content::from_json(Bytes::from_static(b"{nope")).is_err());
1268    }
1269
1270    /// PERF-27: a block a call was half of what a one-item call allocated on
1271    /// a transport with no frame sink, which has no connection to keep one.
1272    #[test]
1273    fn a_call_with_no_connection_leaves_its_block_whole_for_the_next() {
1274        let mut b = Buffer::default();
1275        b.room(300);
1276        b.cur.put_slice(&[1u8; 300]);
1277        drop(b.split());
1278        let block = b.into_idle().expect("a block this size is kept");
1279        assert!(block.capacity() >= Buffer::FIRST, "all of it again, not what was left: {}", block.capacity());
1280        let mut next = Buffer::from_block(Some(block));
1281        let kept = next.cur.as_ptr();
1282        next.room(300);
1283        assert_eq!(next.cur.as_ptr(), kept, "the next call makes none");
1284    }
1285
1286    /// One a stream grew is not kept, or a thread holds it for good.
1287    #[test]
1288    fn a_block_too_large_to_keep_goes() {
1289        let mut b = Buffer::default();
1290        b.room(Buffer::POOLED + 1);
1291        assert!(b.into_idle().is_none());
1292    }
1293
1294    /// A stream that outruns its socket holds the queue's 1,024 frames in
1295    /// flight. The blocks in rotation must hold them, or every block filled is
1296    /// a new one: at 4 KB an item (8.6 KB of block each, content and frame) a
1297    /// fresh block every 60 items, at a ticket body one every 15, for the
1298    /// stream's life. Red with 3 spares.
1299    #[test]
1300    fn a_queue_full_of_frames_comes_back_to_blocks_already_made() {
1301        for size in [8_600, 35_500] {
1302            let mut b = Buffer::default();
1303            let mut in_flight = std::collections::VecDeque::new();
1304            let item = vec![7u8; size];
1305            let mut ramp = 0;
1306            for n in 0..40_000 {
1307                b.room(item.len());
1308                b.cur.put_slice(&item);
1309                in_flight.push_back(b.split());
1310                if in_flight.len() > 1024 {
1311                    in_flight.pop_front();
1312                }
1313                if n == 20_000 {
1314                    ramp = b.made;
1315                }
1316            }
1317            assert_eq!(b.made, ramp, "at {size} B: past the ramp ({ramp} blocks), every block is one already made");
1318        }
1319    }
1320
1321    /// Those blocks are for the burst: a watch that lives on after one holds
1322    /// what it held before it.
1323    #[test]
1324    fn a_drained_queue_lets_its_blocks_go() {
1325        let mut b = Buffer::default();
1326        let mut in_flight = Vec::new();
1327        for _ in 0..4_000 {
1328            b.room(35_500);
1329            b.cur.put_slice(&[7u8; 35_500]);
1330            in_flight.push(b.split());
1331        }
1332        assert_eq!(b.spare.len(), Buffer::SPARE, "the burst keeps them");
1333        drop(in_flight);
1334        for _ in 0..200 {
1335            b.room(35_500);
1336            b.cur.put_slice(&[7u8; 35_500]);
1337            drop(b.split());
1338        }
1339        assert!(b.spare.len() <= Buffer::DRAINED, "drained, it keeps {}", b.spare.len());
1340    }
1341
1342    #[test]
1343    fn a_buffer_reuses_a_block_once_its_frames_are_gone() {
1344        let mut b = Buffer::default();
1345        b.room(100);
1346        b.cur.put_slice(&[1u8; 100]);
1347        let first = b.split();
1348        let block = b.cur.capacity() + 100;
1349        for _ in 0..1000 {
1350            b.room(100);
1351            b.cur.put_slice(&[2u8; 100]);
1352            drop(b.split());
1353        }
1354        assert_eq!(first.len(), 100, "a frame in flight stays whole");
1355        assert!(b.block <= Buffer::FIRST * 2, "blocks are reused, not grown, when frames are written: {} (first {block})", b.block);
1356    }
1357
1358    // -----------------------------------------------------------------------
1359    // PERF-34: the writer, held to serde_json
1360    // -----------------------------------------------------------------------
1361
1362    /// What the pipe's writer writes for `value` against `serde_json::to_vec`:
1363    /// the same bytes, or a refusal where it refuses.
1364    #[track_caller]
1365    fn same_as_serde_json<T: Serialize + ?Sized>(value: &T) {
1366        let _raw = WritingJson::on();
1367        let want = serde_json::to_vec(value);
1368        let mut got = BytesMut::new();
1369        let wrote = json::write(&mut got, value);
1370        match want {
1371            Ok(want) => {
1372                assert!(wrote.is_ok(), "serde_json wrote {}, the writer refused: {:?}", String::from_utf8_lossy(&want), wrote.err());
1373                assert_eq!(String::from_utf8_lossy(&got), String::from_utf8_lossy(&want));
1374                assert_eq!(&got[..], &want[..]);
1375            }
1376            Err(e) => assert!(wrote.is_err(), "serde_json refused ({e}), the writer wrote {}", String::from_utf8_lossy(&got)),
1377        }
1378    }
1379
1380    /// A seeded xorshift: a property test with no dependency, the same cases
1381    /// every run, and a failure that names what it failed on.
1382    struct Rng(u64);
1383
1384    impl Rng {
1385        fn next(&mut self) -> u64 {
1386            let mut x = self.0;
1387            x ^= x << 13;
1388            x ^= x >> 7;
1389            x ^= x << 17;
1390            self.0 = x;
1391            x
1392        }
1393        fn below(&mut self, n: usize) -> usize {
1394            (self.next() % n as u64) as usize
1395        }
1396    }
1397
1398    /// Everything a string can be, weighted to what breaks a scan: runs of
1399    /// plain text around each block size, every control character, quotes and
1400    /// backslashes alone and together, text that looks escaped and is not, and
1401    /// everything past ASCII, each width.
1402    fn a_string(r: &mut Rng) -> String {
1403        const PIECES: &[&str] = &[
1404            "\"", "\\", "\\\\", "\\\"", "\"\"", "\n", "\r", "\t", "\u{8}", "\u{c}", "\u{0}", "\u{1}", "\u{1f}", "\u{7f}", "\u{80}", "\u{ff}", "/", "é", "→", "—", "\u{2028}", "\u{2029}", "\u{feff}", "𝄞", "😀", "\u{10ffff}",
1405            "\\n", "\\u00e9", "\\ud83d", "\\x41", "\\", "\\u", "\\u12", "u0041", "<m-field label=\"x\">", "`code`", "{\"json\":\"in a string\"}", "null", " ",
1406        ];
1407        let mut s = String::new();
1408        for _ in 0..r.below(12) {
1409            match r.below(4) {
1410                0 => s.push_str(PIECES[r.below(PIECES.len())]),
1411                1 => s.extend(std::iter::repeat_n('x', r.below(70))),
1412                2 => s.push(char::from(r.below(128) as u8)),
1413                _ => s.push(char::from_u32(r.next() as u32 % 0x11_0000).unwrap_or('\u{fffd}')),
1414            }
1415        }
1416        s
1417    }
1418
1419    #[derive(Serialize)]
1420    #[serde(rename_all = "snake_case")]
1421    enum External {
1422        Unit,
1423        Newtype(String),
1424        Tuple(u8, String),
1425        Struct { a: u8, b: String },
1426    }
1427
1428    #[derive(Serialize)]
1429    #[serde(tag = "type", rename_all = "snake_case")]
1430    enum Internal {
1431        Unit,
1432        Newtype(Inner),
1433        Struct { n: u64, text: String, maybe: Option<String>, list: Vec<String> },
1434    }
1435
1436    #[derive(Serialize)]
1437    #[serde(tag = "t", content = "c")]
1438    enum Adjacent {
1439        Unit,
1440        Newtype(String),
1441        Tuple(u8, u8),
1442        Struct { s: String },
1443    }
1444
1445    #[derive(Serialize)]
1446    #[serde(untagged)]
1447    enum Untagged {
1448        Number(u8),
1449        Text(String),
1450        Fields { s: String },
1451    }
1452
1453    #[derive(Serialize, Clone)]
1454    struct Inner {
1455        s: String,
1456        #[serde(rename = "a key with a \"quote\" and a \n")]
1457        renamed: u8,
1458        #[serde(skip_serializing_if = "Option::is_none")]
1459        skipped: Option<u8>,
1460    }
1461
1462    /// A field's name that wants a look: the first, the next, and one past a block.
1463    #[derive(Serialize)]
1464    struct Names {
1465        #[serde(rename = "a \"first\" name\t")]
1466        first: u8,
1467        #[serde(rename = "a \\next\\ name")]
1468        next: u8,
1469        a_name_that_is_longer_than_a_block_of_sixteen: u8,
1470        #[serde(rename = "")]
1471        empty: u8,
1472        #[serde(rename = "é")]
1473        past_ascii: u8,
1474    }
1475
1476    #[derive(Serialize)]
1477    struct Flat {
1478        a: u8,
1479        #[serde(flatten)]
1480        inner: Inner,
1481        #[serde(flatten)]
1482        rest: BTreeMap<String, Value>,
1483    }
1484
1485    #[derive(Serialize)]
1486    struct Nothing;
1487
1488    #[derive(Serialize)]
1489    struct Wrapped(String);
1490
1491    #[derive(Serialize)]
1492    struct Pair(u8, String);
1493
1494    #[derive(Serialize, PartialEq, Eq, PartialOrd, Ord)]
1495    #[serde(rename_all = "snake_case")]
1496    enum KeyName {
1497        First,
1498    }
1499
1500    #[derive(Serialize, PartialEq, Eq, PartialOrd, Ord)]
1501    struct WrappedKey(String);
1502
1503    /// `serialize_bytes`, as `serde_bytes` calls it.
1504    struct Blob(&'static [u8]);
1505
1506    impl Serialize for Blob {
1507        fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
1508            s.serialize_bytes(self.0)
1509        }
1510    }
1511
1512    /// `collect_str`, in pieces.
1513    struct Pieces(String);
1514
1515    impl std::fmt::Display for Pieces {
1516        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1517            for (i, piece) in self.0.split('x').enumerate() {
1518                if i > 0 {
1519                    f.write_str("x\"")?;
1520                }
1521                f.write_str(piece)?;
1522            }
1523            Ok(())
1524        }
1525    }
1526
1527    impl Serialize for Pieces {
1528        fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
1529            s.collect_str(self)
1530        }
1531    }
1532
1533    /// A length that lies: serde_json writes what it is told, so the writer does.
1534    struct Lies(Option<usize>, u8);
1535
1536    impl Serialize for Lies {
1537        fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
1538            use serde::ser::{SerializeMap, SerializeSeq};
1539            if self.1 == 0 {
1540                let mut seq = s.serialize_seq(self.0)?;
1541                seq.serialize_element(&1)?;
1542                seq.serialize_element(&2)?;
1543                seq.end()
1544            } else {
1545                let mut map = s.serialize_map(self.0)?;
1546                map.serialize_entry("a", &1)?;
1547                map.serialize_entry("b", &2)?;
1548                map.end()
1549            }
1550        }
1551    }
1552
1553    /// A `Serialize` that fails partway, as a credential's or a user's can.
1554    struct Fails;
1555
1556    impl Serialize for Fails {
1557        fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
1558            use serde::ser::{Error, SerializeStruct};
1559            let mut st = s.serialize_struct("Fails", 2)?;
1560            st.serialize_field("written", "so far")?;
1561            st.end()?;
1562            Err(S::Error::custom("no"))
1563        }
1564    }
1565
1566    #[test]
1567    fn same_bytes_as_serde_json_on_every_shape() {
1568        same_as_serde_json(&());
1569        same_as_serde_json(&Nothing);
1570        same_as_serde_json(&Wrapped("x\"".into()));
1571        same_as_serde_json(&Pair(1, "a\n".into()));
1572        same_as_serde_json(&(1, "two", 3.5, true, None::<u8>, Some('c')));
1573        same_as_serde_json(&Vec::<u8>::new());
1574        same_as_serde_json(&Vec::<Vec<u8>>::from([vec![], vec![1], vec![]]));
1575        same_as_serde_json(&[(); 2]);
1576        same_as_serde_json(&BTreeMap::<String, u8>::new());
1577        same_as_serde_json(&BTreeMap::from([("a\"b".to_string(), BTreeMap::from([(1, 2)]))]));
1578        same_as_serde_json(&Blob(b""));
1579        same_as_serde_json(&Blob(b"\x00\xffabc"));
1580        same_as_serde_json(&'x');
1581        same_as_serde_json(&'"');
1582        same_as_serde_json(&'\u{1}');
1583        same_as_serde_json(&'𝄞');
1584        same_as_serde_json(&std::net::IpAddr::from([127, 0, 0, 1]));
1585        same_as_serde_json(&std::time::Duration::from_millis(1500));
1586        same_as_serde_json(&std::marker::PhantomData::<u8>);
1587        same_as_serde_json(&Ok::<u8, String>(1));
1588        same_as_serde_json(&Err::<u8, String>("no".into()));
1589        same_as_serde_json(&std::borrow::Cow::Borrowed("a\tb"));
1590        same_as_serde_json(&Arc::<str>::from("shared\n"));
1591        for lie in [None, Some(0), Some(1), Some(5)] {
1592            same_as_serde_json(&Lies(lie, 0));
1593            same_as_serde_json(&Lies(lie, 1));
1594        }
1595        same_as_serde_json(&Fails);
1596        same_as_serde_json(&vec![Some(Fails)]);
1597        same_as_serde_json(&External::Unit);
1598        same_as_serde_json(&External::Newtype("n\"".into()));
1599        same_as_serde_json(&External::Tuple(1, "t".into()));
1600        same_as_serde_json(&External::Struct { a: 1, b: "b".into() });
1601        same_as_serde_json(&Internal::Unit);
1602        same_as_serde_json(&Adjacent::Unit);
1603        same_as_serde_json(&Adjacent::Newtype("n".into()));
1604        same_as_serde_json(&Adjacent::Tuple(1, 2));
1605        same_as_serde_json(&Adjacent::Struct { s: "s".into() });
1606        same_as_serde_json(&Untagged::Number(1));
1607        same_as_serde_json(&Untagged::Text("t".into()));
1608        same_as_serde_json(&Untagged::Fields { s: "s".into() });
1609        same_as_serde_json(&Names { first: 1, next: 2, a_name_that_is_longer_than_a_block_of_sixteen: 3, empty: 4, past_ascii: 5 });
1610    }
1611
1612    #[test]
1613    fn same_bytes_as_serde_json_on_every_number() {
1614        same_as_serde_json(&[u8::MIN, u8::MAX]);
1615        same_as_serde_json(&[u16::MAX]);
1616        same_as_serde_json(&[u32::MAX]);
1617        same_as_serde_json(&[u64::MIN, 1, 9, 10, 99, 100, u64::MAX]);
1618        same_as_serde_json(&[u128::MAX]);
1619        same_as_serde_json(&[i8::MIN, i8::MAX]);
1620        same_as_serde_json(&[i16::MIN]);
1621        same_as_serde_json(&[i32::MIN]);
1622        same_as_serde_json(&[i64::MIN, -1, 0, i64::MAX]);
1623        same_as_serde_json(&[i128::MIN, i128::MAX]);
1624        for f in [0.0, -0.0, 0.1, 1.0, 1.5, -1.5, 1e7, 1e15, 1e16, 1e20, 1e21, 1e22, 1e100, 1e-5, 1e-7, 1e-100, 5e-324, 2.2250738585072014e-308, f64::MAX, f64::MIN, f64::EPSILON, f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
1625            same_as_serde_json(&f);
1626            same_as_serde_json(&(f as f32));
1627        }
1628        let mut r = Rng(0x9E37_79B9_7F4A_7C15);
1629        for _ in 0..20_000 {
1630            let bits = r.next();
1631            same_as_serde_json(&f64::from_bits(bits));
1632            same_as_serde_json(&f32::from_bits(bits as u32));
1633            same_as_serde_json(&(bits as i64));
1634        }
1635    }
1636
1637    /// serde_json's map keys: a string, or what reads as one; anything else
1638    /// refused by both.
1639    #[test]
1640    fn same_bytes_as_serde_json_on_every_key() {
1641        same_as_serde_json(&BTreeMap::from([(1u8, 0)]));
1642        same_as_serde_json(&BTreeMap::from([(-1i64, 0)]));
1643        same_as_serde_json(&BTreeMap::from([(u128::MAX, 0)]));
1644        same_as_serde_json(&BTreeMap::from([(i128::MIN, 0)]));
1645        same_as_serde_json(&BTreeMap::from([(true, 0)]));
1646        same_as_serde_json(&BTreeMap::from([('"', 0)]));
1647        same_as_serde_json(&BTreeMap::from([("a key\n", 0)]));
1648        same_as_serde_json(&BTreeMap::from([(KeyName::First, 0)]));
1649        same_as_serde_json(&BTreeMap::from([(WrappedKey("a\"".into()), 0)]));
1650        same_as_serde_json(&BTreeMap::from([(Some(1), 0)]));
1651        same_as_serde_json(&BTreeMap::from([(None::<u8>, 0)]));
1652        same_as_serde_json(&BTreeMap::from([(vec![1], 0)]));
1653        same_as_serde_json(&BTreeMap::from([((), 0)]));
1654        same_as_serde_json(&BTreeMap::from([((1, 2), 0)]));
1655        same_as_serde_json(&HashMap::from([(1.5f64.to_string(), 0)]));
1656        for key in [1.5f64, -0.0, 1e21, f64::NAN, f64::INFINITY] {
1657            same_as_serde_json(&FloatKey(key));
1658            same_as_serde_json(&FloatKey32(key as f32));
1659        }
1660        same_as_serde_json(&PiecesKey("axb\n".into()));
1661        same_as_serde_json(&BlobKey);
1662    }
1663
1664    struct FloatKey(f64);
1665
1666    impl Serialize for FloatKey {
1667        fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
1668            use serde::ser::SerializeMap;
1669            let mut map = s.serialize_map(Some(1))?;
1670            map.serialize_entry(&self.0, &0)?;
1671            map.end()
1672        }
1673    }
1674
1675    struct FloatKey32(f32);
1676
1677    impl Serialize for FloatKey32 {
1678        fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
1679            use serde::ser::SerializeMap;
1680            let mut map = s.serialize_map(Some(1))?;
1681            map.serialize_entry(&self.0, &0)?;
1682            map.end()
1683        }
1684    }
1685
1686    struct PiecesKey(String);
1687
1688    impl Serialize for PiecesKey {
1689        fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
1690            use serde::ser::SerializeMap;
1691            let mut map = s.serialize_map(Some(1))?;
1692            map.serialize_entry(&Pieces(self.0.clone()), &0)?;
1693            map.end()
1694        }
1695    }
1696
1697    struct BlobKey;
1698
1699    impl Serialize for BlobKey {
1700        fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
1701            use serde::ser::SerializeMap;
1702            let mut map = s.serialize_map(None)?;
1703            map.serialize_entry(&Blob(b"no"), &0)?;
1704            map.end()
1705        }
1706    }
1707
1708    /// A raw value's text goes as it is, whatever is in it; a `Content` and a
1709    /// `Shared`, encoded, are raw values to the writer.
1710    #[test]
1711    fn same_bytes_as_serde_json_on_raw_values() {
1712        #[derive(Serialize)]
1713        struct Holds {
1714            raw: Box<RawValue>,
1715            content: Content,
1716            shared: Shared<Inner>,
1717        }
1718        let raw = |text: &str| RawValue::from_string(text.to_string()).unwrap();
1719        same_as_serde_json(&raw(r#"{ "spaced" : [1, 2.50, "é"] }"#));
1720        same_as_serde_json(&raw("null"));
1721        same_as_serde_json(&Some(raw("[]")));
1722        same_as_serde_json(&vec![raw("1"), raw("\"two\"")]);
1723        same_as_serde_json(&BTreeMap::from([("k", raw("{}"))]));
1724        same_as_serde_json(&BTreeMap::from([(raw("\"a raw key\""), 0)].map(|(k, v)| (k.get().to_string(), v))));
1725        let inner = Inner { s: "s\"".into(), renamed: 1, skipped: None };
1726        let held = Holds {
1727            raw: raw("[ 1 ]"),
1728            content: Content::from_json(Bytes::from_static(br#"{"b":[1,2], "a":"x"}"#)).unwrap(),
1729            shared: Shared::new(inner.clone()),
1730        };
1731        same_as_serde_json(&held);
1732        same_as_serde_json(&Content::from(serde_json::json!({"a": 1})));
1733        same_as_serde_json(&Shared::new(inner));
1734        // a tag around a raw value, which serde_json refuses
1735        #[derive(Serialize)]
1736        #[serde(tag = "type")]
1737        enum Tagged {
1738            Raw(Box<RawValue>),
1739        }
1740        same_as_serde_json(&Tagged::Raw(raw("{}")));
1741    }
1742
1743    #[test]
1744    fn same_bytes_as_serde_json_on_every_string() {
1745        let mut r = Rng(0x2545_F491_4F6C_DD1D);
1746        for _ in 0..200_000 {
1747            let s = a_string(&mut r);
1748            same_as_serde_json(&s);
1749            same_as_serde_json(&Pieces(s));
1750        }
1751        for len in 0..300 {
1752            same_as_serde_json(&"x".repeat(len));
1753            same_as_serde_json(&"é".repeat(len));
1754            same_as_serde_json(&"\"".repeat(len));
1755            same_as_serde_json(&"\u{1}".repeat(len));
1756        }
1757        // a string that grows sixfold, past any room made for its length
1758        same_as_serde_json(&"\u{1f}".repeat(1 << 20));
1759    }
1760
1761    /// Every shape with the strings of [`a_string`] in it: keys included.
1762    #[test]
1763    fn same_bytes_as_serde_json_on_random_events() {
1764        let mut r = Rng(0x9E37_79B9_7F4A_7C15);
1765        for _ in 0..20_000 {
1766            let (a, b, c) = (a_string(&mut r), a_string(&mut r), a_string(&mut r));
1767            same_as_serde_json(&Internal::Struct { n: r.next(), text: a.clone(), maybe: (r.below(2) == 0).then(|| b.clone()), list: vec![c.clone(), a.clone()] });
1768            same_as_serde_json(&Internal::Newtype(Inner { s: b.clone(), renamed: r.next() as u8, skipped: (r.below(2) == 0).then_some(1) }));
1769            same_as_serde_json(&Flat { a: 1, inner: Inner { s: c.clone(), renamed: 2, skipped: None }, rest: BTreeMap::from([(a.clone(), Value::String(b.clone()))]) });
1770            let value = serde_json::json!({ (a.clone()): [b.clone(), null, 1, -1, 1.5, true, { (c.clone()): {} }, []] });
1771            same_as_serde_json(&value);
1772            same_as_serde_json(&Content::from(value));
1773            same_as_serde_json(&BTreeMap::from([(a, b), (c, String::new())]));
1774        }
1775    }
1776
1777    /// PERF-34: a hit at every position, around each block size, by each scan.
1778    #[test]
1779    fn scan_at_every_offset() {
1780        const ESCAPED: &[u8] = &[b'"', b'\\', 0x00, 0x01, 0x08, b'\t', b'\n', 0x0c, b'\r', 0x1f];
1781        const PLAIN: &[u8] = &[b'x', b' ', b'!', b'#', b'/', b'[', b']', b'^', 0x7f, 0x80, 0xc3, 0xff];
1782        let mut scans: Vec<(&str, unsafe fn(&[u8], *mut u8) -> usize)> = vec![("a byte at a time", json::scan::one_at_a_time), ("the best this CPU has", json::scan::copy_clean)];
1783        #[cfg(target_arch = "x86_64")]
1784        scans.push(("a CPU without AVX2", json::scan::x86::sse2));
1785        for (name, scan) in scans {
1786            for len in 0..=130usize {
1787                for fill in PLAIN {
1788                    let mut text = vec![*fill; len];
1789                    let mut copy = vec![0u8; len];
1790                    // SAFETY: `copy` is as long as `text`.
1791                    assert_eq!(unsafe { scan(&text, copy.as_mut_ptr()) }, len, "{name}: {len} of {fill:#x}");
1792                    assert_eq!(copy, text, "{name}: {len} of {fill:#x}, copied");
1793                    for at in 0..len {
1794                        for escaped in ESCAPED {
1795                            text[at] = *escaped;
1796                            // SAFETY: as above.
1797                            assert_eq!(unsafe { scan(&text, copy.as_mut_ptr()) }, at, "{name}: {escaped:#x} at {at} of {len}");
1798                            assert_eq!(&copy[..at], &text[..at], "{name}: the run before {escaped:#x} at {at} of {len}");
1799                            // the first of two
1800                            if at + 1 < len {
1801                                text[at + 1] = b'"';
1802                                // SAFETY: as above.
1803                                assert_eq!(unsafe { scan(&text, copy.as_mut_ptr()) }, at, "{name}: the first of two at {at} of {len}");
1804                                text[at + 1] = *fill;
1805                            }
1806                            text[at] = *fill;
1807                        }
1808                    }
1809                }
1810            }
1811        }
1812    }
1813
1814    // -----------------------------------------------------------------------
1815    // PERF-8: batches, for a client that offered them
1816    // -----------------------------------------------------------------------
1817
1818    /// A content type every test item carries.
1819    const CT: &str = "test.count";
1820
1821    fn meta(stamp: i64) -> Arc<StreamMetadata> {
1822        Arc::new(StreamMetadata { provenance: vec!["test".into()], plexus_hash: "ab".into(), timestamp: stamp })
1823    }
1824
1825    /// A data item as the pipe's encode makes one: its content already JSON.
1826    fn data(m: &Arc<StreamMetadata>, n: u64) -> PlexusStreamItem {
1827        let content = Content::json(Bytes::from(serde_json::to_vec(&serde_json::json!({"type": "item", "n": n})).unwrap()));
1828        PlexusStreamItem::Data { metadata: m.clone(), content_type: Cow::Borrowed(CT), content }
1829    }
1830
1831    fn done(stamp: i64) -> PlexusStreamItem {
1832        PlexusStreamItem::Done { metadata: StreamMetadata { provenance: vec!["test".into()], plexus_hash: "ab".into(), timestamp: stamp } }
1833    }
1834
1835    /// Every frame `stream` makes down the pipe, to a sink batching `batch`,
1836    /// as JSON, until its terminal item; `wait` once the stream stops for good.
1837    fn frames_of(stream: super::super::streaming::PlexusStream, batch: usize) -> Vec<Value> {
1838        let rt = tokio::runtime::Builder::new_current_thread().enable_all().build().unwrap();
1839        rt.block_on(async move {
1840            let (to, mut frames) = FrameSink::channel(1024, WireEncoding::Json);
1841            let to = to.batching(batch);
1842            let stream = Arc::new(Mutex::new(Some(stream)));
1843            let mut module = jsonrpsee::RpcModule::new(());
1844            module
1845                .register_subscription("open", "note", "close", move |_, pending, _, mut ext| {
1846                    let (to, stream) = (to.clone(), stream.lock().unwrap().take());
1847                    async move {
1848                        let sink = pending.accept().await?;
1849                        ext.insert(to);
1850                        pipe(sink, stream.expect("one call"), &ext).await
1851                    }
1852                })
1853                .unwrap();
1854            let (_answer, _notes) = module.raw_json_request(r#"{"jsonrpc":"2.0","id":1,"method":"open","params":[]}"#, 1).await.unwrap();
1855            let mut out = Vec::new();
1856            loop {
1857                let frame = tokio::time::timeout(std::time::Duration::from_secs(5), frames.recv()).await.expect("a frame in time").expect("the pipe runs");
1858                let v: Value = serde_json::from_slice(frame.bytes()).expect("a frame is one JSON value");
1859                let last = items_of(&v).last().map(|i| i["type"] == "done" || i["type"] == "error").unwrap_or(false);
1860                out.push(v);
1861                if last {
1862                    return out;
1863                }
1864            }
1865        })
1866    }
1867
1868    /// A notification's items, as a client that offered `batch` reads them: a
1869    /// `result` alone, or each of `results`, a `data` item without `metadata`
1870    /// taking the batch's.
1871    fn items_of(note: &Value) -> Vec<Value> {
1872        let params = &note["params"];
1873        if let Some(one) = params.get("result") {
1874            return vec![one.clone()];
1875        }
1876        let shared = params.get("metadata").cloned();
1877        params["results"]
1878            .as_array()
1879            .expect("`result` or `results`")
1880            .iter()
1881            .map(|item| {
1882                let mut item = item.clone();
1883                if item["type"] == "data" && item.get("metadata").is_none() {
1884                    item["metadata"] = shared.clone().expect("a data item without metadata takes the batch's");
1885                }
1886                item
1887            })
1888            .collect()
1889    }
1890
1891    fn ready(items: Vec<PlexusStreamItem>) -> super::super::streaming::PlexusStream {
1892        Box::pin(futures::stream::iter(items))
1893    }
1894
1895    /// 200 items ready at once, then `done`: batches of 64, in order, each item
1896    /// equal as JSON to the one a client that offered nothing is sent.
1897    #[test]
1898    fn a_batch_is_the_items_ready_together_in_one_notification() {
1899        let m = meta(7);
1900        let make = || ready((0..200).map(|n| data(&m, n)).chain([done(7)]).collect());
1901        let one_each = frames_of(make(), 0);
1902        assert_eq!(one_each.len(), 201, "one an item");
1903        assert!(one_each.iter().all(|f| f["params"].get("result").is_some() && f["params"].get("results").is_none()), "today's frames");
1904        let batched = frames_of(make(), 64);
1905        let sizes: Vec<usize> = batched.iter().map(|f| items_of(f).len()).collect();
1906        assert_eq!(sizes, vec![64, 64, 64, 9], "what was ready, up to 64, the last with `done`");
1907        assert!(batched.iter().all(|f| f["params"]["results"].is_array()), "a batch is `results`");
1908        let unbatched: Vec<Value> = one_each.iter().flat_map(items_of).collect();
1909        assert_eq!(batched.iter().flat_map(items_of).collect::<Vec<_>>(), unbatched, "the same items, in order, equal as JSON");
1910        assert!(batched.iter().all(|f| f["params"]["subscription"] == batched[0]["params"]["subscription"] && f["method"] == "note"), "one call's, on its own method");
1911    }
1912
1913    /// The metadata goes once a batch where it is the same: a `data` item of
1914    /// the batch's leaves its own out; any other keeps it.
1915    #[test]
1916    fn metadata_goes_once_a_batch_where_it_is_the_same() {
1917        // a child's items, relayed, each bring their own copy of the same
1918        let (a, b, copy) = (meta(7), meta(8), meta(7));
1919        let frames = frames_of(ready(vec![data(&a, 0), data(&a, 1), data(&b, 2), data(&copy, 3), done(9)]), 64);
1920        assert_eq!(frames.len(), 1);
1921        let p = &frames[0]["params"];
1922        assert_eq!(p["metadata"], serde_json::to_value(&*a).unwrap(), "the batch's, its first data item's");
1923        let raw = p["results"].as_array().unwrap();
1924        assert!(raw[0].get("metadata").is_none() && raw[1].get("metadata").is_none() && raw[3].get("metadata").is_none(), "the same, or an equal copy: {raw:?}");
1925        assert_eq!(raw[2]["metadata"], serde_json::to_value(&*b).unwrap(), "another stream's metadata stays with its item");
1926        assert_eq!(raw[4]["metadata"]["timestamp"], 9, "`done` keeps its own");
1927    }
1928
1929    /// A stream that yields one item and then waits: that item goes at once,
1930    /// alone, in today's form. A batch is what is ready, never what a timer
1931    /// waits for.
1932    #[test]
1933    fn a_lone_item_goes_at_once_alone() {
1934        let m = meta(7);
1935        let rt = tokio::runtime::Builder::new_current_thread().enable_all().build().unwrap();
1936        rt.block_on(async {
1937            let (to, mut frames) = FrameSink::channel(16, WireEncoding::Json);
1938            let to = to.batching(64);
1939            let stream: super::super::streaming::PlexusStream = Box::pin(futures::StreamExt::chain(futures::stream::iter([data(&m, 0)]), futures::stream::pending()));
1940            let stream = Arc::new(Mutex::new(Some(stream)));
1941            let mut module = jsonrpsee::RpcModule::new(());
1942            module
1943                .register_subscription("open", "note", "close", move |_, pending, _, mut ext| {
1944                    let (to, stream) = (to.clone(), stream.lock().unwrap().take());
1945                    async move {
1946                        let sink = pending.accept().await?;
1947                        ext.insert(to);
1948                        pipe(sink, stream.expect("one call"), &ext).await
1949                    }
1950                })
1951                .unwrap();
1952            let (_answer, _notes) = module.raw_json_request(r#"{"jsonrpc":"2.0","id":1,"method":"open","params":[]}"#, 1).await.unwrap();
1953            let frame = tokio::time::timeout(std::time::Duration::from_millis(500), frames.recv()).await.expect("at once, not when more come").unwrap();
1954            let v: Value = serde_json::from_slice(frame.bytes()).unwrap();
1955            assert_eq!(v["params"]["result"]["content"]["n"], 0, "alone, in today's form: {v}");
1956        });
1957    }
1958
1959    /// A batch of large items stops at its bytes: 4 KB items go two to a
1960    /// notification, not 64, and a ticket body goes alone.
1961    #[test]
1962    fn a_batch_stops_at_its_bytes() {
1963        let m = meta(7);
1964        let big = |n: u64, size: usize| PlexusStreamItem::Data { metadata: m.clone(), content_type: Cow::Borrowed(CT), content: Content::json(Bytes::from(format!(r#"{{"type":"item","n":{n},"pad":"{}"}}"#, "x".repeat(size)))) };
1965        let frames = frames_of(ready((0..20).map(|n| big(n, 4096)).chain([done(7)]).collect()), 64);
1966        let sizes: Vec<usize> = frames.iter().map(|f| items_of(f).len()).collect();
1967        assert!(sizes.iter().all(|&n| n <= 2), "about 8 KiB a batch: {sizes:?}");
1968        assert_eq!(sizes.iter().sum::<usize>(), 21);
1969        let frames = frames_of(ready((0..3).map(|n| big(n, 17_000)).chain([done(7)]).collect()), 64);
1970        assert!(frames.iter().take(2).all(|f| f["params"].get("result").is_some()), "a body alone, as today: {:?}", frames.iter().map(|f| items_of(f).len()).collect::<Vec<_>>());
1971    }
1972
1973    /// A client may ask for fewer than 64: no notification carries more.
1974    #[test]
1975    fn a_batch_holds_no_more_than_asked() {
1976        let m = meta(7);
1977        let frames = frames_of(ready((0..10).map(|n| data(&m, n)).chain([done(7)]).collect()), 4);
1978        assert_eq!(frames.iter().map(|f| items_of(f).len()).collect::<Vec<_>>(), vec![4, 4, 3]);
1979    }
1980}