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