Skip to main content

turnloop_io/
lib.rs

1//! Shared transport glue. See the crate README for the adapter ownership contract.
2#![deny(unsafe_op_in_unsafe_fn)]
3pub use futures_io::{AsyncRead, AsyncWrite};
4use std::{
5    future::{Future, poll_fn},
6    io,
7    net::SocketAddr,
8    pin::Pin,
9    task::{Context, Poll},
10};
11pub use turnloop::{self, AsyncIo, ExecutorHandle, Instant, backend::Backend};
12pub mod dns;
13pub mod pool;
14
15/// A TCP, pipe, TLS or host stream with cancellation-safe futures-io operations.
16pub trait Stream: AsyncRead + AsyncWrite + Unpin {}
17impl<T: AsyncRead + AsyncWrite + Unpin> Stream for T {}
18
19/// Preserve portable error kinds even where no OS error number exists.
20pub fn error(e: turnloop::Error) -> io::Error {
21    if let Some(code) = e.os {
22        return io::Error::from_raw_os_error(code);
23    }
24    let kind = match e.kind {
25        turnloop::ErrorKind::TimedOut => io::ErrorKind::TimedOut,
26        turnloop::ErrorKind::Unsupported => io::ErrorKind::Unsupported,
27        turnloop::ErrorKind::InvalidInput => io::ErrorKind::InvalidInput,
28        turnloop::ErrorKind::Cancelled => io::ErrorKind::Interrupted,
29        turnloop::ErrorKind::BrokenPipe => io::ErrorKind::BrokenPipe,
30        _ => io::ErrorKind::Other,
31    };
32    io::Error::new(kind, e)
33}
34/// Read into caller storage; an empty read means transport EOF.
35pub async fn read<S: AsyncRead + Unpin>(stream: &mut S, bytes: &mut [u8]) -> io::Result<usize> {
36    poll_fn(|cx| Pin::new(&mut *stream).poll_read(cx, bytes)).await
37}
38/// Write all bytes and confirm transport delivery before releasing their owner.
39pub async fn write_all<S: AsyncWrite + Unpin>(stream: &mut S, mut bytes: &[u8]) -> io::Result<()> {
40    while !bytes.is_empty() {
41        let n = poll_fn(|cx| Pin::new(&mut *stream).poll_write(cx, bytes)).await?;
42        if n == 0 {
43            return Err(io::ErrorKind::WriteZero.into());
44        }
45        bytes = &bytes[n..];
46    }
47    flush(stream).await
48}
49/// Wait for delivery of accepted writes.
50pub async fn flush<S: AsyncWrite + Unpin>(stream: &mut S) -> io::Result<()> {
51    poll_fn(|cx| Pin::new(&mut *stream).poll_flush(cx)).await
52}
53/// Gracefully close after flushing accepted writes.
54pub async fn close<S: AsyncWrite + Unpin>(stream: &mut S) -> io::Result<()> {
55    poll_fn(|cx| Pin::new(&mut *stream).poll_close(cx)).await
56}
57/// A stream whose write direction can end while its read direction stays open.
58///
59/// futures-io's `poll_close` releases the whole transport. A half-close instead
60/// sends the peer EOF and keeps reading, which a server needs for a lingering
61/// close: closing a socket with unread peer bytes sends RST, and a received RST
62/// discards data the peer has not read yet on macOS and Windows. `AsyncIo`,
63/// `turnloop_tls::asynchronous::TlsStream` and `Transport` implement it.
64pub trait HalfClose: Stream {
65    /// Backend of the executor that owns the native handle.
66    type Backend: Backend;
67    /// The executor owning the native handle, whose timers bound a lingering close.
68    /// `None` once the transport has been released.
69    fn executor(&self) -> Option<ExecutorHandle<Self::Backend>>;
70    /// Flush accepted writes, then end the write direction without closing the
71    /// handle (TLS sends close_notify first). Reads continue until the peer's EOF;
72    /// later writes fail. Completed shutdowns stay complete on repeated polls.
73    /// Transports without a separate write direction return
74    /// `io::ErrorKind::Unsupported` (see `AsyncIo::poll_shutdown`).
75    fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>>;
76}
77impl<B: Backend> HalfClose for AsyncIo<B> {
78    type Backend = B;
79    fn executor(&self) -> Option<ExecutorHandle<B>> {
80        Some(AsyncIo::executor(self))
81    }
82    fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
83        self.get_mut().poll_shutdown(cx)
84    }
85}
86/// Half-close: flush accepted writes and end the write direction, keeping the
87/// transport open for reads. [`close`] keeps its full-close semantics.
88pub async fn shutdown<S: HalfClose>(stream: &mut S) -> io::Result<()> {
89    poll_fn(|cx| Pin::new(&mut *stream).poll_shutdown(cx)).await
90}
91/// How the discard phase of a lingering close ended.
92#[derive(Clone, Copy, Debug, Eq, PartialEq)]
93pub enum LingerEnd {
94    /// The peer ended its stream; all its remaining input was read and discarded.
95    Eof,
96    /// The linger deadline passed before the peer's EOF.
97    Deadline,
98    /// The transport cannot half-close, so it closed without lingering.
99    Unsupported,
100    /// The half-close, a discard read or the deadline timer failed (for example
101    /// the peer reset the connection); lingering stopped and the stream closed.
102    Failed(io::ErrorKind),
103}
104/// Outcome of a lingering close, including proof of the discarded input.
105#[derive(Clone, Copy, Debug, Eq, PartialEq)]
106pub struct Lingered {
107    /// Why discarding stopped.
108    pub end: LingerEnd,
109    /// Non-empty reads performed after the half-close.
110    pub reads: u64,
111    /// Peer bytes read and discarded after the half-close.
112    pub discarded: u64,
113}
114enum LingerPhase {
115    Shutdown,
116    Discard,
117    Close,
118    Done,
119}
120/// Future for [`linger_close`]. It borrows the stream and caller-retained scratch,
121/// allocates nothing, and waits only on the stream's own read and one executor
122/// timer, so an idle peer costs no turns before the deadline.
123pub struct LingerClose<'a, S: HalfClose> {
124    stream: &'a mut S,
125    scratch: &'a mut [u8],
126    executor: Option<ExecutorHandle<S::Backend>>,
127    deadline: Option<Instant>,
128    sleep: Option<(Instant, turnloop::Sleep<S::Backend>)>,
129    phase: LingerPhase,
130    lingered: Lingered,
131}
132/// Lingering close, as nginx `lingering_close`: flush and half-close, read and
133/// discard peer input until its EOF or `deadline`, then close.
134///
135/// Flush the final response before calling this. Closing with unread peer bytes
136/// (a pipelined request, HTTP/2 WINDOW_UPDATE or SETTINGS acknowledgements) sends
137/// RST, which can discard the peer's unread copy of that response. `scratch` must
138/// be non-empty; reuse a connection's retained input buffer. `None` lingers until
139/// the peer's EOF. The deadline bounds the half-close too. Transports that cannot
140/// half-close close at once ([`LingerEnd::Unsupported`]); half-close or read
141/// failures stop lingering and close ([`LingerEnd::Failed`]).
142///
143/// The result is `Err` when scratch is empty, when the half-close has not finished
144/// by the deadline (`TimedOut`: the peer stopped reading, so pending output cannot
145/// flush) or when the final `poll_close` fails. The stream is then not closed: drop
146/// it, which releases the handle. Dropping the future mid-way keeps in-flight
147/// operations owned by the stream, so a new lingering close resumes them.
148pub fn linger_close<'a, S: HalfClose>(
149    stream: &'a mut S,
150    scratch: &'a mut [u8],
151    deadline: Option<Instant>,
152) -> LingerClose<'a, S> {
153    LingerClose {
154        executor: stream.executor(),
155        stream,
156        scratch,
157        deadline,
158        sleep: None,
159        phase: LingerPhase::Shutdown,
160        lingered: Lingered {
161            end: LingerEnd::Deadline,
162            reads: 0,
163            discarded: 0,
164        },
165    }
166}
167impl<S: HalfClose> LingerClose<'_, S> {
168    /// Move the deadline, for example to honour an earlier server shutdown
169    /// deadline. The timer is re-armed on the next poll only if it changed.
170    pub fn set_deadline(&mut self, deadline: Option<Instant>) {
171        self.deadline = deadline;
172    }
173    /// Discard progress so far; `end` is meaningful once the future completes.
174    pub fn lingered(&self) -> Lingered {
175        self.lingered
176    }
177    /// Whether the deadline has passed. Otherwise its timer is armed (re-armed
178    /// only when the deadline moved) and registered with `cx`.
179    fn poll_expired(&mut self, cx: &mut Context<'_>) -> Result<bool, io::ErrorKind> {
180        let Some(deadline) = self.deadline else {
181            self.sleep = None;
182            return Ok(false);
183        };
184        if self.sleep.as_ref().is_none_or(|(at, _)| *at != deadline) {
185            let Some(executor) = &self.executor else {
186                return Ok(true);
187            };
188            if executor.now() >= deadline {
189                self.sleep = None;
190                return Ok(true);
191            }
192            // Replacing the timer drops (and closes) the previous one.
193            self.sleep = Some((deadline, executor.sleep_until(deadline)));
194        }
195        let Some((_, sleep)) = self.sleep.as_mut() else {
196            return Ok(false);
197        };
198        match Pin::new(sleep).poll(cx) {
199            Poll::Ready(Ok(())) => Ok(true),
200            Poll::Ready(Err(e)) => Err(error(e).kind()),
201            Poll::Pending => Ok(false),
202        }
203    }
204    fn poll_discard(&mut self, cx: &mut Context<'_>) -> Option<LingerEnd> {
205        loop {
206            match Pin::new(&mut *self.stream).poll_read(cx, self.scratch) {
207                Poll::Ready(Ok(0)) => return Some(LingerEnd::Eof),
208                Poll::Ready(Ok(n)) => {
209                    self.lingered.reads += 1;
210                    self.lingered.discarded += n as u64;
211                }
212                Poll::Ready(Err(e)) => return Some(LingerEnd::Failed(e.kind())),
213                Poll::Pending => break,
214            }
215        }
216        match self.poll_expired(cx) {
217            Ok(false) => None,
218            Ok(true) => Some(LingerEnd::Deadline),
219            Err(kind) => Some(LingerEnd::Failed(kind)),
220        }
221    }
222}
223impl<S: HalfClose> Future for LingerClose<'_, S> {
224    type Output = io::Result<Lingered>;
225    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
226        let this = self.get_mut();
227        loop {
228            match this.phase {
229                LingerPhase::Shutdown => {
230                    if this.scratch.is_empty() {
231                        return Poll::Ready(Err(io::Error::new(
232                            io::ErrorKind::InvalidInput,
233                            "lingering close needs non-empty scratch storage",
234                        )));
235                    }
236                    match Pin::new(&mut *this.stream).poll_shutdown(cx) {
237                        Poll::Pending => {
238                            let expired = match this.poll_expired(cx) {
239                                Ok(false) => return Poll::Pending,
240                                Ok(true) => io::ErrorKind::TimedOut,
241                                Err(kind) => kind,
242                            };
243                            this.lingered.end = if expired == io::ErrorKind::TimedOut {
244                                LingerEnd::Deadline
245                            } else {
246                                LingerEnd::Failed(expired)
247                            };
248                            this.sleep = None;
249                            this.phase = LingerPhase::Done;
250                            return Poll::Ready(Err(io::Error::new(
251                                expired,
252                                "half-close did not complete before the linger deadline",
253                            )));
254                        }
255                        Poll::Ready(Ok(())) => this.phase = LingerPhase::Discard,
256                        Poll::Ready(Err(e)) => {
257                            this.lingered.end = if e.kind() == io::ErrorKind::Unsupported {
258                                LingerEnd::Unsupported
259                            } else {
260                                LingerEnd::Failed(e.kind())
261                            };
262                            this.phase = LingerPhase::Close;
263                        }
264                    }
265                }
266                LingerPhase::Discard => {
267                    let Some(end) = this.poll_discard(cx) else {
268                        return Poll::Pending;
269                    };
270                    this.lingered.end = end;
271                    this.sleep = None;
272                    this.phase = LingerPhase::Close;
273                }
274                LingerPhase::Close => {
275                    let result = std::task::ready!(Pin::new(&mut *this.stream).poll_close(cx));
276                    this.phase = LingerPhase::Done;
277                    return Poll::Ready(result.map(|()| this.lingered));
278                }
279                LingerPhase::Done => return Poll::Ready(Ok(this.lingered)),
280            }
281        }
282    }
283}
284/// One deadline shared across every phase of an exchange; uses the executor timer.
285pub async fn deadline<B: Backend, F: Future<Output = io::Result<T>>, T>(
286    executor: &ExecutorHandle<B>,
287    at: Instant,
288    future: F,
289) -> io::Result<T> {
290    executor.timeout_at(at, future).await.map_err(error)?
291}
292/// Resolve a service endpoint using the loop's DNS capability. Literal IPs need
293/// no resolver and work on every raw-socket backend.
294pub async fn resolve<B: Backend>(
295    executor: &ExecutorHandle<B>,
296    host: &str,
297    port: u16,
298    at: Instant,
299) -> io::Result<SocketAddr> {
300    if let Ok(ip) = host.parse() {
301        return Ok(SocketAddr::new(ip, port));
302    }
303    deadline(executor, at, async {
304        executor
305            .resolve(turnloop::DnsRequest {
306                host: host.to_owned(),
307                port,
308            })
309            .await
310            .map_err(error)?
311            .into_iter()
312            .next()
313            .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, "DNS returned no addresses"))
314    })
315    .await
316}
317/// Core-owned wire output. Acknowledged only after a successful complete flush.
318pub trait Output {
319    fn output(&self) -> &[u8];
320    fn consume_output(&mut self, count: usize) -> io::Result<()>;
321}
322/// Drive one output phase without allocating another wire buffer.
323pub async fn drain<S: Stream, C: Output>(stream: &mut S, core: &mut C) -> io::Result<()> {
324    let n = core.output().len();
325    write_all(stream, core.output()).await?;
326    if n > 0 {
327        core.consume_output(n)?;
328    }
329    Ok(())
330}
331/// Owned listener. Drop cancels accepts and closes the backend handle.
332pub struct Listener<B: Backend> {
333    executor: ExecutorHandle<B>,
334    handle: turnloop::Handle,
335}
336impl<B: Backend> Listener<B> {
337    pub fn bind(executor: &ExecutorHandle<B>, address: SocketAddr) -> io::Result<Self> {
338        let handle = executor
339            .driver()
340            .tcp_listen(address, &Default::default())
341            .map_err(error)?;
342        Ok(Self {
343            executor: executor.clone(),
344            handle,
345        })
346    }
347    pub fn local_addr(&self) -> io::Result<SocketAddr> {
348        self.executor
349            .driver()
350            .local_addr(self.handle)
351            .map_err(error)
352    }
353    pub async fn accept(&self) -> io::Result<AsyncIo<B>> {
354        self.executor.accept(self.handle).await.map_err(error)
355    }
356}
357impl<B: Backend> Drop for Listener<B> {
358    fn drop(&mut self) {
359        let _ = self
360            .executor
361            .driver()
362            .close(self.handle, turnloop::Token(0));
363    }
364}
365
366/// Close an owned stream if an exchange fails or its future is cancelled.
367/// Commit only after all accepted output is flushed and parser progress is saved.
368pub struct CloseOnDrop<'a, S> {
369    slot: &'a mut Option<S>,
370    committed: bool,
371}
372impl<'a, S> CloseOnDrop<'a, S> {
373    pub fn new(slot: &'a mut Option<S>) -> Self {
374        Self {
375            slot,
376            committed: false,
377        }
378    }
379    pub fn stream(&mut self) -> io::Result<&mut S> {
380        self.slot
381            .as_mut()
382            .ok_or_else(|| io::ErrorKind::NotConnected.into())
383    }
384    pub fn commit(&mut self) {
385        self.committed = true;
386    }
387}
388impl<S> Drop for CloseOnDrop<'_, S> {
389    fn drop(&mut self) {
390        if !self.committed {
391            self.slot.take();
392        }
393    }
394}
395
396/// Protocol-core contract used by database and mail adapters. Events can borrow
397/// the core; the callback must finish consuming them before the next drive step.
398pub trait SansIo: Output {
399    type Event<'a>
400    where
401        Self: 'a;
402    fn event(&mut self, receive: impl FnMut(Self::Event<'_>) -> io::Result<()>)
403    -> io::Result<bool>;
404    fn ingest(&mut self, bytes: &[u8], now: Instant) -> io::Result<usize>;
405    fn disconnected(&mut self);
406}
407/// A shared sans-I/O driver. Protocol crates only implement SansIo; transport
408/// flushing, partial input, cancellation and read scheduling live here once.
409pub struct Driver<S, C: SansIo> {
410    stream: Option<S>,
411    core: Option<C>,
412    input: Box<[u8]>,
413    start: usize,
414    end: usize,
415}
416impl<S: Stream, C: SansIo> Driver<S, C> {
417    pub fn new(stream: S, core: C) -> Self {
418        Self {
419            stream: Some(stream),
420            core: Some(core),
421            input: vec![0; 16384].into_boxed_slice(),
422            start: 0,
423            end: 0,
424        }
425    }
426    pub fn core(&self) -> &C {
427        self.core.as_ref().expect("owned core")
428    }
429    pub fn core_mut(&mut self) -> &mut C {
430        self.core.as_mut().expect("owned core")
431    }
432    pub fn is_connected(&self) -> bool {
433        self.stream.is_some()
434    }
435    pub fn stream(&self) -> Option<&S> {
436        self.stream.as_ref()
437    }
438    /// Close immediately. Submitted transport storage remains owned by AsyncIo.
439    pub fn abort(&mut self) {
440        self.stream.take();
441        self.core_mut().disconnected();
442    }
443    /// Install a new transport after the protocol has entered its reconnect
444    /// state. Bytes from the failed transport are never fed to the new session.
445    pub fn replace_stream(&mut self, stream: S) -> io::Result<()> {
446        if self.stream.is_some() {
447            return Err(io::Error::other("transport is still connected"));
448        }
449        self.start = 0;
450        self.end = 0;
451        self.stream = Some(stream);
452        Ok(())
453    }
454    /// Guard a complete operation, including pauses between protocol events.
455    pub fn exchange(&mut self) -> Exchange<'_, S, C> {
456        Exchange {
457            driver: self,
458            committed: false,
459        }
460    }
461    /// A TLS transition is legal only at a drained plaintext boundary.
462    pub fn upgrade_stream(&mut self) -> io::Result<&mut S> {
463        if self.start != self.end || !self.core().output().is_empty() {
464            return Err(io::Error::new(
465                io::ErrorKind::InvalidData,
466                "undrained TLS boundary",
467            ));
468        }
469        self.stream
470            .as_mut()
471            .ok_or_else(|| io::ErrorKind::NotConnected.into())
472    }
473    /// Flush COPY or other output that has no corresponding input event.
474    pub async fn flush(&mut self) -> io::Result<()> {
475        let mut transport = CloseOnDrop::new(&mut self.stream);
476        let result = drain(transport.stream()?, self.core.as_mut().expect("owned core")).await;
477        if result.is_ok() {
478            transport.commit();
479        }
480        result
481    }
482    /// Drive until one protocol event is delivered. Wrap this in `deadline` for
483    /// the protocol's advertised timeout; cancellation closes and aborts the core.
484    pub async fn next<B: Backend>(
485        &mut self,
486        executor: &ExecutorHandle<B>,
487        mut receive: impl FnMut(C::Event<'_>) -> io::Result<()>,
488    ) -> io::Result<()> {
489        struct CoreGuard<'a, C: SansIo> {
490            core: &'a mut C,
491            done: bool,
492        }
493        impl<C: SansIo> Drop for CoreGuard<'_, C> {
494            fn drop(&mut self) {
495                if !self.done {
496                    self.core.disconnected();
497                }
498            }
499        }
500        let mut core = CoreGuard {
501            core: self.core.as_mut().expect("owned core"),
502            done: false,
503        };
504        let mut transport = CloseOnDrop::new(&mut self.stream);
505        loop {
506            if core.core.event(&mut receive)? {
507                core.done = true;
508                transport.commit();
509                return Ok(());
510            }
511            drain(transport.stream()?, core.core).await?;
512            // A completed write can itself produce a terminal event.
513            if core.core.event(&mut receive)? {
514                core.done = true;
515                transport.commit();
516                return Ok(());
517            }
518            if self.start < self.end {
519                let n = core
520                    .core
521                    .ingest(&self.input[self.start..self.end], executor.now())?;
522                if n == 0 {
523                    return Err(io::Error::other("core input stalled without an event"));
524                }
525                self.start += n;
526                continue;
527            }
528            self.start = 0;
529            self.end = read(transport.stream()?, &mut self.input).await?;
530            if self.end == 0 {
531                return Err(io::ErrorKind::UnexpectedEof.into());
532            }
533        }
534    }
535    /// Transfer a validated TLS-upgrade boundary, including unread transport data.
536    pub fn into_parts(mut self) -> io::Result<(S, C, Vec<u8>)> {
537        let stream = self
538            .stream
539            .take()
540            .ok_or_else(|| io::Error::from(io::ErrorKind::NotConnected))?;
541        Ok((
542            stream,
543            self.core.take().expect("owned core"),
544            self.input[self.start..self.end].to_vec(),
545        ))
546    }
547}
548/// Dropping an unfinished operation aborts both its protocol and transport.
549pub struct Exchange<'a, S: Stream, C: SansIo> {
550    driver: &'a mut Driver<S, C>,
551    committed: bool,
552}
553impl<S: Stream, C: SansIo> Exchange<'_, S, C> {
554    pub fn commit(&mut self) {
555        self.committed = true;
556    }
557}
558impl<S: Stream, C: SansIo> std::ops::Deref for Exchange<'_, S, C> {
559    type Target = Driver<S, C>;
560    fn deref(&self) -> &Self::Target {
561        self.driver
562    }
563}
564impl<S: Stream, C: SansIo> std::ops::DerefMut for Exchange<'_, S, C> {
565    fn deref_mut(&mut self) -> &mut Self::Target {
566        self.driver
567    }
568}
569impl<S: Stream, C: SansIo> Drop for Exchange<'_, S, C> {
570    fn drop(&mut self) {
571        if !self.committed {
572            self.driver.abort();
573        }
574    }
575}
576impl<S, C: SansIo> Drop for Driver<S, C> {
577    fn drop(&mut self) {
578        if let Some(core) = self.core.as_mut() {
579            core.disconnected();
580        }
581    }
582}