Skip to main content

net_io/
session.rs

1//! Sans-IO sessions: a protocol engine reacts to bytes and returns what to do next.
2
3use std::collections::VecDeque;
4use std::fmt;
5use std::fs::File;
6use std::sync::Arc;
7use std::sync::atomic::{AtomicU64, Ordering};
8use std::time::{Duration, Instant};
9
10use crate::buf::{Buffer, BufferPool};
11use crate::completer::Completer;
12use crate::error::{CloseReason, LimitKind, NetError, RefusalCause, TimeoutKind};
13use crate::gate::KillHandle;
14use crate::id::WorkerId;
15use crate::info::{ConnectionInfo, GateTag};
16use crate::limits::SizeClass;
17use crate::link::Link;
18
19/// A sans-IO protocol engine bound to one connection.
20///
21/// net-io reads, calls the session with the bytes, and does what the returned
22/// [`Step`] says. Sessions are called only on the worker that owns the
23/// connection, never concurrently.
24///
25/// # Examples
26///
27/// ```no_run
28/// use net_io::{Input, Session, SessionContext, Step};
29///
30/// struct Echo;
31/// impl Session for Echo {
32///     fn on_data(&mut self, cx: &mut SessionContext<'_>, input: &mut Input) -> Step {
33///         // Copy as much as the output budget takes; the rest stays in `input`,
34///         // and net-io calls on_data again after the flush because the input changed.
35///         let taken = cx.output().push_partial(input.bytes());
36///         input.consume(taken);
37///         Step::Write
38///     }
39/// }
40///
41/// let server = net_io::serve_sessions("127.0.0.1:7002", |_info: &net_io::ConnectionInfo| Echo)?;
42/// server.wait_for_stop();
43/// # Ok::<(), net_io::NetError>(())
44/// ```
45pub trait Session: Send + 'static {
46    /// Once, after admission and the handshake.
47    fn on_open(&mut self, cx: &mut SessionContext<'_>) -> Step {
48        let _ = cx;
49        Step::Read
50    }
51
52    /// Bytes arrived; `input` holds everything not yet consumed.
53    fn on_data(&mut self, cx: &mut SessionContext<'_>, input: &mut Input) -> Step;
54
55    /// After a `Step::Write` flushed all pending output.
56    fn on_writable(&mut self, cx: &mut SessionContext<'_>) -> Step {
57        let _ = cx;
58        Step::Read
59    }
60
61    /// Another thread posted a completion through this connection's [`Completer`].
62    fn on_wake(&mut self, cx: &mut SessionContext<'_>, token: u32, value: u64) -> Step {
63        let _ = (cx, token, value);
64        Step::Abort
65    }
66
67    /// A deadline passed. `Close` or `Abort` closes with the timeout's own reason
68    /// and close style; anything else re-arms with the same limits.
69    fn on_timeout(&mut self, cx: &mut SessionContext<'_>, which: TimeoutKind) -> Step {
70        let _ = (cx, which);
71        Step::Close
72    }
73
74    /// The peer sent FIN; the session may keep writing (half-close).
75    fn on_peer_closed(&mut self, cx: &mut SessionContext<'_>) -> Step {
76        let _ = cx;
77        Step::Close
78    }
79
80    /// The gate denied a write and no byte of the current response has left:
81    /// write the protocol's refusal for `code` into `output`.
82    fn on_denied(&mut self, code: u16, output: &mut Output) {
83        let _ = (code, output);
84    }
85
86    /// Exactly once, with the one close reason.
87    fn on_close(&mut self, info: &ConnectionInfo, reason: CloseReason) {
88        let _ = (info, reason);
89    }
90}
91
92/// Creates one session per admitted connection. Any `Fn(&ConnectionInfo) -> S` is one.
93///
94/// # Examples
95///
96/// ```
97/// use net_io::{ConnectionInfo, Input, RefusalCause, Session, SessionContext, SessionFactory, Step};
98///
99/// struct Discard;
100/// impl Session for Discard {
101///     fn on_data(&mut self, _cx: &mut SessionContext<'_>, input: &mut Input) -> Step {
102///         let n = input.bytes().len();
103///         input.consume(n);
104///         Step::Read
105///     }
106/// }
107///
108/// struct OnlyLoopback;
109/// impl SessionFactory for OnlyLoopback {
110///     type Session = Discard;
111///     fn open(&self, info: &ConnectionInfo) -> Result<Discard, RefusalCause> {
112///         match info.client_addr() {
113///             Some(addr) if addr.ip().is_loopback() => Ok(Discard),
114///             _ => Err(RefusalCause::Session),
115///         }
116///     }
117/// }
118///
119/// let info = ConnectionInfo::for_testing("10.0.0.1:1".parse().unwrap());
120/// assert!(OnlyLoopback.open(&info).is_err());
121/// ```
122pub trait SessionFactory: Send + Sync + 'static {
123    /// The session type.
124    type Session: Session;
125
126    /// A session for this connection.
127    ///
128    /// # Errors
129    ///
130    /// Refusing closes the connection with `CloseReason::Refused(cause)`.
131    fn open(&self, info: &ConnectionInfo) -> Result<Self::Session, RefusalCause>;
132}
133
134impl<F, S> SessionFactory for F
135where
136    F: Fn(&ConnectionInfo) -> S + Send + Sync + 'static,
137    S: Session,
138{
139    type Session = S;
140    fn open(&self, info: &ConnectionInfo) -> Result<S, RefusalCause> {
141        Ok(self(info))
142    }
143}
144
145/// What the session wants next.
146///
147/// ```
148/// assert_ne!(net_io::Step::Close, net_io::Step::Abort);
149/// ```
150#[non_exhaustive]
151#[derive(Clone, Copy, Debug, PartialEq, Eq)]
152pub enum Step {
153    /// Wait for more input. Output pushed in this call is not sent: return
154    /// `Write` (or `Close`) to flush it first.
155    Read,
156    /// Flush pending output, then `on_writable`.
157    Write,
158    /// No reads, no idle timer, until a completion or the park deadline.
159    Park {
160        /// The deadline; `None` uses the park timeout.
161        until: Option<Instant>,
162    },
163    /// Graceful: flush, FIN, bounded linger.
164    Close,
165    /// RST now.
166    Abort,
167}
168
169/// Which deadlines run.
170///
171/// ```
172/// assert_eq!(net_io::Phase::default(), net_io::Phase::Idle);
173/// ```
174#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
175pub enum Phase {
176    /// Between exchanges: the idle timeout.
177    #[default]
178    Idle,
179    /// Receiving an exchange: the read timeout, the inbound rate, the exchange deadline.
180    Receiving,
181    /// Sending: the write timeout, the outbound rate, the exchange deadline.
182    Sending,
183}
184
185/// Why a swap was refused.
186///
187/// ```
188/// assert_ne!(net_io::SwapError::NotEmpty, net_io::SwapError::Busy);
189/// ```
190#[non_exhaustive]
191#[derive(Clone, Copy, Debug, PartialEq, Eq)]
192pub enum SwapError {
193    /// The buffers are of different size classes.
194    ClassMismatch,
195    /// The incoming buffer has data.
196    NotEmpty,
197    /// A driver operation holds the buffer.
198    Busy,
199}
200
201impl fmt::Display for SwapError {
202    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
203        f.write_str(match self {
204            SwapError::ClassMismatch => "the buffers are of different size classes",
205            SwapError::NotEmpty => "the incoming buffer is not empty",
206            SwapError::Busy => "a driver operation holds the buffer",
207        })
208    }
209}
210
211impl std::error::Error for SwapError {}
212
213/// The connection's read buffer: a zero-copy view of what was read and not yet consumed.
214///
215/// ```
216/// let mut input = net_io::Input::from_bytes(b"GET / HTTP/1.1\r\n");
217/// assert_eq!(input.bytes(), b"GET / HTTP/1.1\r\n");
218/// input.consume(4);
219/// assert_eq!(input.bytes(), b"/ HTTP/1.1\r\n");
220/// ```
221#[derive(Debug)]
222pub struct Input {
223    pub(crate) buf: Buffer,
224    pub(crate) start: usize,
225    pub(crate) changed: bool,
226    /// The buffer travels with a receive on the reactor: `buf` is a stand-in, and
227    /// the unconsumed bytes are in the lent buffer until it comes back.
228    lent: bool,
229}
230
231impl Input {
232    pub(crate) fn new(buf: Buffer) -> Input {
233        Input {
234            buf,
235            lent: false,
236            start: 0,
237            changed: false,
238        }
239    }
240
241    /// An input holding `bytes`, for tests of sessions (allocates).
242    #[must_use]
243    pub fn from_bytes(bytes: &[u8]) -> Input {
244        let class = (bytes.len() as u32)
245            .max(1024)
246            .next_power_of_two()
247            .max(SizeClass::SMALL.bytes());
248        let class = SizeClass::new(class.min(1 << 20)).unwrap_or(SizeClass::LARGE);
249        let mut pool = BufferPool::standalone(u64::from(class.bytes()));
250        let mut input = Input::new(match pool.take(class) {
251            Some(b) => b,
252            None => return Input::new(Buffer::detached(class)),
253        });
254        let n = bytes.len().min(input.buf.capacity());
255        input.buf.spare()[..n].copy_from_slice(&bytes[..n]);
256        input.buf.set_len(n);
257        input
258    }
259
260    /// The unconsumed bytes.
261    #[must_use]
262    pub fn bytes(&self) -> &[u8] {
263        self.buf.as_slice().get(self.start..).unwrap_or(&[])
264    }
265
266    /// Consumes `n` bytes (saturating at the length).
267    pub fn consume(&mut self, n: usize) {
268        let n = n.min(self.buf.len() - self.start);
269        self.start += n;
270        if n > 0 {
271            self.changed = true;
272        }
273        if self.start == self.buf.len() {
274            self.buf.clear();
275            self.start = 0;
276        }
277    }
278
279    /// Whether the buffer is full: the session must consume or grow it.
280    #[must_use]
281    pub fn is_full(&self) -> bool {
282        !self.lent && self.buf.len() == self.buf.capacity() && self.start == 0
283    }
284
285    /// The buffer's size class.
286    #[must_use]
287    pub fn class(&self) -> SizeClass {
288        self.buf.class()
289    }
290
291    /// Exchanges the read buffer with an empty `other` of the same class in O(1):
292    /// `other` now holds the unconsumed bytes, and the connection reads into the
293    /// buffer it was given.
294    ///
295    /// # Errors
296    ///
297    /// [`SwapError::ClassMismatch`], [`SwapError::NotEmpty`].
298    ///
299    /// ```
300    /// use net_io::{BufferPool, Input};
301    /// let mut input = Input::from_bytes(b"body");
302    /// let mut pool = BufferPool::standalone(1 << 20);
303    /// let mut spare = pool.take(input.class()).unwrap();
304    /// input.swap(&mut spare).unwrap();
305    /// assert_eq!(spare.as_slice(), b"body");
306    /// assert!(input.bytes().is_empty());
307    /// ```
308    pub fn swap(&mut self, other: &mut Buffer) -> Result<(), SwapError> {
309        if other.class() != self.buf.class() {
310            return Err(SwapError::ClassMismatch);
311        }
312        if !other.is_empty() {
313            return Err(SwapError::NotEmpty);
314        }
315        if self.start > 0 {
316            self.buf.compact(self.start);
317            self.start = 0;
318        }
319        std::mem::swap(&mut self.buf, other);
320        self.changed = true;
321        Ok(())
322    }
323
324    /// Room to read into, compacting first when the free tail is under a quarter.
325    pub(crate) fn spare_for_read(&mut self) -> &mut [u8] {
326        let free = self.buf.capacity() - self.buf.len();
327        if self.start > 0 && free < self.buf.capacity() / 4 {
328            self.buf.compact(self.start);
329            self.start = 0;
330        }
331        self.buf.spare()
332    }
333
334    /// Hands the buffer to a receive (compacted first when the free tail is small),
335    /// leaving an empty stand-in until [`Input::give_back`].
336    #[cfg(feature = "reactor")]
337    pub(crate) fn lend(&mut self) -> Buffer {
338        let _ = self.spare_for_read();
339        self.lent = true;
340        std::mem::replace(&mut self.buf, Buffer::placeholder())
341    }
342
343    /// The lent buffer is back, with what the receive added.
344    #[cfg(feature = "reactor")]
345    pub(crate) fn give_back(&mut self, buf: Buffer) {
346        self.buf = buf;
347        self.lent = false;
348    }
349
350    /// Whether a receive holds the buffer.
351    #[cfg(feature = "reactor")]
352    pub(crate) fn lent(&self) -> bool {
353        self.lent
354    }
355
356    pub(crate) fn filled(&mut self, n: usize) {
357        let len = self.buf.len() + n;
358        self.buf.set_len(len);
359        self.changed = true;
360    }
361}
362
363/// The output budget was reached; return `Step::Write` and continue after the flush.
364///
365/// ```
366/// assert_eq!(net_io::OutputFull.to_string(), "the connection's output budget is full");
367/// ```
368#[derive(Clone, Copy, Debug, PartialEq, Eq)]
369pub struct OutputFull;
370
371impl fmt::Display for OutputFull {
372    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
373        f.write_str("the connection's output budget is full")
374    }
375}
376
377impl std::error::Error for OutputFull {}
378
379#[derive(Debug)]
380pub(crate) enum Chunk {
381    Pooled(Buffer, usize),
382    Static(&'static [u8], usize),
383    /// `left` bytes of a file from `offset`.
384    File {
385        file: Arc<File>,
386        offset: u64,
387        left: u64,
388    },
389}
390
391impl Chunk {
392    /// The bytes in memory; a file has none.
393    pub(crate) fn remaining(&self) -> &[u8] {
394        match self {
395            Chunk::Pooled(b, off) => &b.as_slice()[*off..],
396            Chunk::Static(s, off) => &s[*off..],
397            Chunk::File { .. } => &[],
398        }
399    }
400
401    /// Bytes still to go.
402    pub(crate) fn len(&self) -> usize {
403        match self {
404            Chunk::File { left, .. } => usize::try_from(*left).unwrap_or(usize::MAX),
405            other => other.remaining().len(),
406        }
407    }
408
409    pub(crate) fn is_file(&self) -> bool {
410        matches!(self, Chunk::File { .. })
411    }
412
413    /// `n` bytes of this chunk went out.
414    pub(crate) fn advance(&mut self, n: usize) {
415        match self {
416            Chunk::Pooled(_, off) | Chunk::Static(_, off) => *off += n,
417            Chunk::File { offset, left, .. } => {
418                *offset += n as u64;
419                *left -= n as u64;
420            }
421        }
422    }
423}
424
425/// What the session wants written: a bounded queue of chunks.
426///
427/// ```
428/// let mut out = net_io::Output::standalone(64 * 1024);
429/// out.push(b"hello ").unwrap();
430/// out.push_static(b"world").unwrap();
431/// assert_eq!(out.pending(), 11);
432/// ```
433#[derive(Debug)]
434pub struct Output {
435    pub(crate) chunks: VecDeque<Chunk>,
436    free: Vec<Buffer>,
437    budget: Arc<AtomicU64>,
438    limit: u32,
439    used: u32,
440    wipe: bool,
441    /// A push found no free buffer and the budget spent since the last flush.
442    refused: bool,
443    pub(crate) response_open: bool,
444    pub(crate) response_tag: Option<GateTag>,
445    pub(crate) bytes_since_begin: u64,
446}
447
448const OUTPUT_CLASS: SizeClass = SizeClass::MEDIUM;
449const MAX_CHUNKS: usize = 64;
450/// The most free buffers one output holds; the rest of a large close goes to the budget.
451const FREE_MAX: usize = 4;
452
453impl Output {
454    pub(crate) fn new(budget: Arc<AtomicU64>, limit: u32, wipe: bool) -> Output {
455        Output {
456            chunks: VecDeque::with_capacity(MAX_CHUNKS),
457            free: Vec::new(),
458            budget,
459            limit,
460            used: 0,
461            wipe,
462            refused: false,
463            response_open: false,
464            response_tag: None,
465            bytes_since_begin: 0,
466        }
467    }
468
469    /// An output with its own budget, for tests of sessions (allocates).
470    #[must_use]
471    pub fn standalone(limit: u32) -> Output {
472        Output::new(Arc::new(AtomicU64::new(u64::from(limit))), limit, true)
473    }
474
475    fn take_buffer(&mut self) -> Option<Buffer> {
476        if let Some(b) = self.free.pop() {
477            return Some(b);
478        }
479        let bytes = u64::from(OUTPUT_CLASS.bytes());
480        let mut left = self.budget.load(Ordering::Relaxed);
481        loop {
482            if left < bytes {
483                self.refused = true;
484                return None;
485            }
486            match self.budget.compare_exchange_weak(
487                left,
488                left - bytes,
489                Ordering::AcqRel,
490                Ordering::Relaxed,
491            ) {
492                Ok(_) => return Some(Buffer::detached(OUTPUT_CLASS)),
493                Err(actual) => left = actual,
494            }
495        }
496    }
497
498    /// Takes buffers the worker's pool already holds, so the next pushes reuse them
499    /// instead of charging the budget again. Before this, spares an output gave the
500    /// pool after a send were never taken back, and every flush of more than one
501    /// buffer charged the budget anew until it ran out (found by ws-net).
502    ///
503    /// With none of its class cached, the pool frees buffers it caches for other
504    /// classes if the budget could not cover the next push otherwise: the push
505    /// charges the budget directly and cannot reach them.
506    pub(crate) fn refill(&mut self, pool: &mut BufferPool) {
507        while self.free.len() < FREE_MAX {
508            match pool.take_cached(OUTPUT_CLASS) {
509                Some(b) => self.free.push(b),
510                None => break,
511            }
512        }
513        if self.free.is_empty() {
514            pool.make_room(OUTPUT_CLASS);
515        }
516    }
517
518    /// Whether a push was refused for want of budget since the last call: a flush
519    /// that then finds nothing queued must not call the session back at once.
520    pub(crate) fn take_refused(&mut self) -> bool {
521        std::mem::take(&mut self.refused)
522    }
523
524    fn room(&self) -> usize {
525        let tail = match self.chunks.back() {
526            Some(Chunk::Pooled(b, _)) => b.capacity() - b.len(),
527            _ => 0,
528        };
529        let more = (self.limit.saturating_sub(self.used) / OUTPUT_CLASS.bytes()) as usize
530            * OUTPUT_CLASS.bytes() as usize;
531        tail + more
532    }
533
534    /// Copies as much of `bytes` as the budget allows; returns how many were taken.
535    pub fn push_partial(&mut self, mut bytes: &[u8]) -> usize {
536        let mut taken = 0;
537        while !bytes.is_empty() {
538            if let Some(Chunk::Pooled(b, _)) = self.chunks.back_mut() {
539                let spare = b.spare();
540                if !spare.is_empty() {
541                    let n = spare.len().min(bytes.len());
542                    spare[..n].copy_from_slice(&bytes[..n]);
543                    let len = b.len() + n;
544                    b.set_len(len);
545                    bytes = &bytes[n..];
546                    taken += n;
547                    continue;
548                }
549            }
550            if self.chunks.len() >= MAX_CHUNKS
551                || self.used.saturating_add(OUTPUT_CLASS.bytes()) > self.limit
552            {
553                break;
554            }
555            match self.take_buffer() {
556                Some(b) => {
557                    self.used += OUTPUT_CLASS.bytes();
558                    self.chunks.push_back(Chunk::Pooled(b, 0));
559                }
560                None => break,
561            }
562        }
563        taken
564    }
565
566    /// Copies all of `bytes`, or nothing.
567    ///
568    /// # Errors
569    ///
570    /// [`OutputFull`] when the budget cannot take all of it.
571    pub fn push(&mut self, bytes: &[u8]) -> Result<(), OutputFull> {
572        if bytes.len() > self.room() {
573            return Err(OutputFull);
574        }
575        let n = self.push_partial(bytes);
576        if n == bytes.len() {
577            Ok(())
578        } else {
579            Err(OutputFull)
580        }
581    }
582
583    /// Moves an owned buffer in (no copy).
584    ///
585    /// # Errors
586    ///
587    /// [`OutputFull`] when the budget or the chunk limit is reached.
588    pub fn push_buffer(&mut self, buffer: Buffer) -> Result<(), OutputFull> {
589        let size = u32::try_from(buffer.capacity()).unwrap_or(u32::MAX);
590        if self.chunks.len() >= MAX_CHUNKS || self.used.saturating_add(size) > self.limit {
591            return Err(OutputFull);
592        }
593        self.used += size;
594        self.chunks.push_back(Chunk::Pooled(buffer, 0));
595        Ok(())
596    }
597
598    /// Queues a static slice (no copy, not counted against the budget).
599    ///
600    /// # Errors
601    ///
602    /// [`OutputFull`] when the chunk limit is reached.
603    pub fn push_static(&mut self, bytes: &'static [u8]) -> Result<(), OutputFull> {
604        if self.chunks.len() >= MAX_CHUNKS {
605            return Err(OutputFull);
606        }
607        if !bytes.is_empty() {
608            self.chunks.push_back(Chunk::Static(bytes, 0));
609        }
610        Ok(())
611    }
612
613    /// Queues `len` bytes of `file` from `offset`, sent zero copy where the OS can and
614    /// read in pieces otherwise (TLS, named pipes). Not counted against the budget; the
615    /// file stays open until the chunk has gone. Keep it from shrinking meanwhile: the
616    /// connection is reset with `Io(FileTruncated)` if it does. A read on TLS or a pipe
617    /// happens on the worker's thread, so a slow disk holds that worker.
618    ///
619    /// On the reactor a file goes out in pieces of at most 256 KiB, each after a gate
620    /// check, and a worker sends at most 256 KiB of file between two looks at the OS,
621    /// so a stream to a fast reader cannot hold off the worker's other connections.
622    /// To interleave small replies with a stream on one connection, push the stream a
623    /// few pieces at a time from `on_writable`.
624    ///
625    /// # Errors
626    ///
627    /// [`OutputFull`] when the chunk limit is reached.
628    pub fn push_file(&mut self, file: Arc<File>, offset: u64, len: u64) -> Result<(), OutputFull> {
629        if self.chunks.len() >= MAX_CHUNKS {
630            return Err(OutputFull);
631        }
632        if len > 0 {
633            self.chunks.push_back(Chunk::File {
634                file,
635                offset,
636                left: len,
637            });
638        }
639        Ok(())
640    }
641
642    /// The file at the front of the queue, if that is what goes next.
643    pub(crate) fn front_file(&self) -> Option<(Arc<File>, u64, u64)> {
644        match self.chunks.front() {
645            Some(Chunk::File { file, offset, left }) => Some((file.clone(), *offset, *left)),
646            _ => None,
647        }
648    }
649
650    /// Reads the front file's next piece into a buffer at the front of the queue, for
651    /// a path that cannot send a file directly.
652    #[cfg(feature = "reactor")]
653    pub(crate) fn pull_file(&mut self) -> Result<(), crate::error::CloseReason> {
654        use crate::error::{CloseReason, LimitKind, OsErrorClass};
655        let Some((file, offset, left)) = self.front_file() else {
656            return Ok(());
657        };
658        let Some(mut b) = self.take_buffer() else {
659            return Err(CloseReason::Limit(LimitKind::BufferBudget));
660        };
661        let spare = b.spare();
662        let take = usize::try_from(left).unwrap_or(usize::MAX).min(spare.len());
663        let read = crate::sys::read_file_at(&file, &mut spare[..take], offset);
664        let n = match read {
665            Ok(0) => {
666                self.release_chunk(b);
667                return Err(CloseReason::Io(OsErrorClass::FileTruncated));
668            }
669            Ok(n) => n,
670            Err(e) => {
671                self.release_chunk(b);
672                return Err(CloseReason::Io(OsErrorClass::from_io(&e)));
673            }
674        };
675        b.set_len(n);
676        self.used += OUTPUT_CLASS.bytes();
677        if let Some(front) = self.chunks.front_mut() {
678            front.advance(n);
679            if front.len() == 0 {
680                self.chunks.pop_front();
681            }
682        }
683        self.chunks.push_front(Chunk::Pooled(b, 0));
684        Ok(())
685    }
686
687    /// Marks the start of a response (for the gate's denial boundary).
688    pub fn begin_response(&mut self) {
689        self.response_open = true;
690        self.response_tag = None;
691        self.bytes_since_begin = 0;
692    }
693
694    /// Marks the start of a response and tags it for the gate (`WriteCheck::response`).
695    pub fn begin_tagged_response(&mut self, tag: GateTag) {
696        self.begin_response();
697        self.response_tag = Some(tag);
698    }
699
700    /// Marks the end of the response; clears the tag.
701    pub fn end_response(&mut self) {
702        self.response_open = false;
703        self.response_tag = None;
704    }
705
706    /// Bytes queued and not yet sent.
707    #[must_use]
708    pub fn pending(&self) -> usize {
709        self.chunks.iter().map(Chunk::len).sum()
710    }
711
712    /// Whether nothing is queued.
713    #[must_use]
714    pub fn is_empty(&self) -> bool {
715        self.chunks.is_empty()
716    }
717
718    /// Overwrites every pending chunk net-io owns with zeroes and drops it.
719    pub fn wipe_all(&mut self) {
720        while let Some(chunk) = self.chunks.pop_front() {
721            if let Chunk::Pooled(mut b, _) = chunk {
722                b.wipe();
723                self.release_chunk(b);
724            }
725        }
726        self.used = 0;
727    }
728
729    fn release_chunk(&mut self, mut b: Buffer) {
730        self.used = self
731            .used
732            .saturating_sub(u32::try_from(b.capacity()).unwrap_or(u32::MAX));
733        if self.wipe {
734            b.wipe();
735        } else {
736            b.clear();
737        }
738        if b.class() == OUTPUT_CLASS && self.free.len() < FREE_MAX {
739            self.free.push(b);
740        } else {
741            // A buffer moved in with push_buffer goes back to the shared budget.
742            self.budget
743                .fetch_add(b.capacity() as u64, Ordering::Release);
744        }
745    }
746
747    /// Keeps one free buffer and gives the rest to `pool`. A buffer moved in with
748    /// `push_buffer` came from that pool, and kept here it would be allocated again
749    /// for the next one.
750    pub(crate) fn return_spares(&mut self, pool: &mut BufferPool) {
751        while self.free.len() > 1 {
752            if let Some(b) = self.free.pop() {
753                pool.put(b);
754            }
755        }
756    }
757
758    /// Gives every free buffer to `pool`, for an output set aside while its
759    /// connection waits: there the pool's keep limit applies and other classes can
760    /// reach them, and the next session to take an output gets them back through
761    /// `refill`.
762    #[cfg(feature = "reactor")]
763    pub(crate) fn return_all_spares(&mut self, pool: &mut BufferPool) {
764        while let Some(b) = self.free.pop() {
765            pool.put(b);
766        }
767    }
768
769    /// The bytes one send offers: at most the chunks one vectored call takes.
770    #[cfg(feature = "reactor")]
771    pub(crate) fn pending_in_send(&self) -> usize {
772        self.chunks
773            .iter()
774            .take(crate::sys::MAX_SLICES)
775            .take_while(|c| !c.is_file())
776            .map(Chunk::len)
777            .sum()
778    }
779
780    /// The chunks as slices for one send; returns how many.
781    #[cfg(feature = "reactor")]
782    pub(crate) fn fill_slices<'a>(&'a self, out: &mut [std::io::IoSlice<'a>]) -> usize {
783        let mut n = 0;
784        for chunk in self
785            .chunks
786            .iter()
787            .take(out.len())
788            .take_while(|c| !c.is_file())
789        {
790            out[n] = std::io::IoSlice::new(chunk.remaining());
791            n += 1;
792        }
793        n
794    }
795
796    /// Marks `n` bytes as sent, releasing finished chunks.
797    pub(crate) fn advance(&mut self, mut n: usize) {
798        while let Some(front) = self.chunks.front_mut() {
799            let rem = front.len();
800            if n < rem {
801                front.advance(n);
802                return;
803            }
804            n -= rem;
805            if let Some(Chunk::Pooled(b, _)) = self.chunks.pop_front() {
806                self.release_chunk(b);
807            }
808        }
809    }
810
811    /// Resets for the next connection.
812    pub(crate) fn reset(&mut self) {
813        self.wipe_all();
814        self.response_open = false;
815        self.response_tag = None;
816        self.bytes_since_begin = 0;
817        self.refused = false;
818    }
819}
820
821/// Everything a session may touch, for one call.
822pub struct SessionContext<'a> {
823    pub(crate) link: &'a mut Link,
824    pub(crate) output: &'a mut Output,
825    pub(crate) pool: &'a mut BufferPool,
826    pub(crate) completer: &'a Completer,
827    pub(crate) draining: bool,
828    pub(crate) pressure: f32,
829    pub(crate) worker: WorkerId,
830    pub(crate) grow_to: Option<SizeClass>,
831}
832
833impl SessionContext<'_> {
834    /// The connection's facts.
835    #[must_use]
836    pub fn info(&self) -> &ConnectionInfo {
837        &self.link.info
838    }
839
840    /// The output queue.
841    pub fn output(&mut self) -> &mut Output {
842        // Spares the output gave the pool after its last send come back first, up to
843        // what one output may hold: a few pops, no allocation.
844        if self.output.free.len() < FREE_MAX {
845            self.output.refill(self.pool);
846        }
847        self.output
848    }
849
850    /// The worker's clock.
851    #[must_use]
852    pub fn now(&self) -> Instant {
853        self.link.now()
854    }
855
856    /// Chooses which deadlines run.
857    pub fn set_phase(&mut self, phase: crate::session::Phase) {
858        self.link.set_phase(phase);
859    }
860
861    /// The deadline for the current exchange (`None` clears it).
862    pub fn set_exchange_deadline(&mut self, at: Option<Instant>) {
863        self.link.set_exchange_deadline(at);
864    }
865
866    /// Overrides this connection's idle timeout from its next wait for an
867    /// exchange on; `None` restores the listener's limit. For example, a
868    /// protocol shortens keep-alive while the worker pool is nearly full.
869    /// Values below the timer tick are raised to one tick.
870    ///
871    /// ```no_run
872    /// use std::time::Duration;
873    /// use net_io::{Input, Session, SessionContext, Step};
874    ///
875    /// struct KeepAlive;
876    /// impl Session for KeepAlive {
877    ///     fn on_data(&mut self, cx: &mut SessionContext<'_>, input: &mut Input) -> Step {
878    ///         let n = input.bytes().len();
879    ///         input.consume(n);
880    ///         let short = (cx.pressure() > 0.75).then_some(Duration::from_secs(2));
881    ///         cx.set_idle_timeout(short);
882    ///         Step::Write
883    ///     }
884    /// }
885    /// ```
886    pub fn set_idle_timeout(&mut self, timeout: Option<Duration>) {
887        self.link.set_idle_timeout(timeout);
888    }
889
890    /// Whether drain started: finish the current exchange, then close.
891    #[must_use]
892    pub fn draining(&self) -> bool {
893        self.draining
894    }
895
896    /// 0.0 to 1.0: busy workers (blocking driver); 1.0 while the control line sheds.
897    #[must_use]
898    pub fn pressure(&self) -> f32 {
899        self.pressure
900    }
901
902    /// A handle other threads can use to abort this connection.
903    #[must_use]
904    pub fn kill_handle(&self) -> KillHandle {
905        KillHandle {
906            slot: self.link.slot.clone(),
907            generation: self.link.generation,
908            id: self.link.info.id,
909        }
910    }
911
912    /// This worker's completion queue. A connection whose session takes it is
913    /// woken for posts while it waits for input too; on the blocking driver on
914    /// Linux that wait then costs one `poll` before each receive.
915    #[must_use]
916    pub fn completer(&self) -> Completer {
917        self.link.wakeable.set(true);
918        self.completer.clone()
919    }
920
921    /// The worker that runs this connection.
922    #[must_use]
923    pub fn worker(&self) -> WorkerId {
924        self.worker
925    }
926
927    /// This worker's buffer pool.
928    pub fn buffers(&mut self) -> &mut BufferPool {
929        self.pool
930    }
931
932    /// Returns a buffer (for example one taken by `Input::swap`); it is wiped.
933    pub fn release(&mut self, buffer: Buffer) {
934        self.pool.put(buffer);
935    }
936
937    /// Moves the unconsumed input into a buffer of `class` after this call returns.
938    ///
939    /// # Errors
940    ///
941    /// `Limit { which: ReadBuffer }` above the maximum read class.
942    pub fn grow_input(&mut self, class: SizeClass) -> Result<(), NetError> {
943        if class > self.link.limits.read_class_max {
944            return Err(NetError::Limit {
945                which: LimitKind::ReadBuffer,
946            });
947        }
948        self.grow_to = Some(class);
949        Ok(())
950    }
951}
952
953impl fmt::Debug for SessionContext<'_> {
954    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
955        f.debug_struct("SessionContext")
956            .field("id", &self.link.info.id)
957            .field("draining", &self.draining)
958            .finish()
959    }
960}
961
962#[cfg(test)]
963mod tests {
964    use super::*;
965
966    #[test]
967    fn test_input_consume_saturates_and_resets() {
968        let mut i = Input::from_bytes(b"abc");
969        i.consume(10);
970        assert!(i.bytes().is_empty());
971        assert_eq!(i.start, 0);
972    }
973
974    #[test]
975    fn test_input_swap_rules() {
976        let mut i = Input::from_bytes(b"xyz");
977        let mut pool = BufferPool::standalone(1 << 22);
978        let mut wrong = pool.take(SizeClass::LARGE).unwrap();
979        assert_eq!(i.swap(&mut wrong), Err(SwapError::ClassMismatch));
980        let mut full = pool.take(i.class()).unwrap();
981        full.set_len(1);
982        assert_eq!(i.swap(&mut full), Err(SwapError::NotEmpty));
983        let mut empty = pool.take(i.class()).unwrap();
984        i.consume(1);
985        i.swap(&mut empty).unwrap();
986        assert_eq!(empty.as_slice(), b"yz");
987    }
988
989    #[test]
990    fn test_output_push_all_or_nothing_and_partial() {
991        let mut o = Output::standalone(OUTPUT_CLASS.bytes());
992        let big = vec![7u8; OUTPUT_CLASS.bytes() as usize + 1];
993        assert_eq!(o.push(&big), Err(OutputFull));
994        assert!(o.is_empty());
995        assert_eq!(o.push_partial(&big), OUTPUT_CLASS.bytes() as usize);
996        assert_eq!(o.pending(), OUTPUT_CLASS.bytes() as usize);
997    }
998
999    #[test]
1000    fn test_output_advance_releases_chunks() {
1001        let mut o = Output::standalone(1 << 20);
1002        o.push(b"hello").unwrap();
1003        o.push_static(b" world").unwrap();
1004        o.advance(7);
1005        assert_eq!(o.pending(), 4);
1006        assert_eq!(o.chunks.len(), 1);
1007        assert_eq!(o.used, 0);
1008        o.advance(4);
1009        assert!(o.is_empty());
1010    }
1011
1012    #[test]
1013    fn test_output_response_markers() {
1014        let mut o = Output::standalone(1 << 20);
1015        o.begin_tagged_response(GateTag(3));
1016        assert_eq!(o.response_tag, Some(GateTag(3)));
1017        o.end_response();
1018        assert_eq!(o.response_tag, None);
1019    }
1020
1021    /// Property: whatever mix of pushes is accepted and however the sends split,
1022    /// the bytes that leave are the accepted bytes in order, and the budget returns.
1023    #[test]
1024    fn prop_output_stream_matches_accepted_pushes() {
1025        use crate::testing::Gen;
1026        static TEXT: [u8; 4096] = {
1027            let mut t = [0u8; 4096];
1028            let mut i = 0;
1029            while i < t.len() {
1030                t[i] = (i % 251) as u8;
1031                i += 1;
1032            }
1033            t
1034        };
1035        let mut g = Gen::new(0x0047_0041);
1036        for round in 0..if cfg!(miri) { 3 } else { 300 } {
1037            let mut o = Output::standalone(64 * 1024);
1038            let mut expected = Vec::new();
1039            let mut sent = Vec::new();
1040            for _ in 0..200 {
1041                match g.below(4) {
1042                    0 => {
1043                        let n = g.below(40_000) as usize;
1044                        let data: Vec<u8> = (0..n).map(|_| g.next_u64() as u8).collect();
1045                        let took = o.push_partial(&data);
1046                        expected.extend_from_slice(&data[..took]);
1047                    }
1048                    1 => {
1049                        let n = g.below(3000) as usize;
1050                        let data: Vec<u8> = (0..n).map(|_| g.next_u64() as u8).collect();
1051                        if o.push(&data).is_ok() {
1052                            expected.extend_from_slice(&data);
1053                        }
1054                    }
1055                    2 => {
1056                        let start = g.below(TEXT.len() as u64) as usize;
1057                        let piece = &TEXT[start..];
1058                        if o.push_static(piece).is_ok() {
1059                            expected.extend_from_slice(piece);
1060                        }
1061                    }
1062                    _ => {
1063                        // A send of a random size, taken from the front chunks as a vectored write would.
1064                        let mut want = g.below(70_000) as usize;
1065                        let mut taken = 0;
1066                        for chunk in o.chunks.iter() {
1067                            if want == 0 {
1068                                break;
1069                            }
1070                            let r = chunk.remaining();
1071                            let n = r.len().min(want);
1072                            sent.extend_from_slice(&r[..n]);
1073                            want -= n;
1074                            taken += n;
1075                        }
1076                        o.advance(taken);
1077                    }
1078                }
1079            }
1080            while !o.is_empty() {
1081                let n = o.chunks.front().map_or(0, |c| c.remaining().len());
1082                if let Some(c) = o.chunks.front() {
1083                    sent.extend_from_slice(c.remaining());
1084                }
1085                o.advance(n);
1086            }
1087            assert!(sent == expected, "round {round}: stream differs");
1088            assert_eq!(o.used, 0, "round {round}: budget not returned");
1089            assert_eq!(o.pending(), 0);
1090        }
1091    }
1092}