Skip to main content

weirdnet_net/stream/
mod.rs

1//! Streams (W1) that survive path changes (W15).
2//!
3//! An application accepts streams of its own protocol ids ([`Node::accept_streams`]) and opens
4//! them to a peer ([`Node::open_stream`]). A [`Stream`] is an ordered, reliable byte stream with
5//! no size cap and backpressure (a sender has at most [`Limits::window`] bytes unacknowledged).
6//! It is a logical stream: underneath, a libp2p substream carries it, over a direct connection
7//! when there is one, else through a relay.
8//!
9//! Path switching: when a direct connection to the peer comes up (DCUtR hole punching, or a
10//! dial), the side that opened the stream moves it there; when the connection under a stream
11//! goes away, the opener re-opens it over whatever path is left (the relay, kept warm while
12//! streams are open) and both sides carry on where the other stopped. Nothing is lost or
13//! repeated: every data frame carries its byte offset, each side acknowledges what it has, and
14//! after a move the sender sends again what wasn't acknowledged. A stream fails only when no
15//! path comes back within [`Limits::resume`].
16//!
17//! Wire format, on every substream of the application's protocol: the opener sends `Hello`
18//! (new or resume, the stream id, bytes received so far) and the acceptor answers `Welcome`
19//! (bytes received so far) or `Refuse`; then `Data` (offset, bytes), `Ack` (bytes received),
20//! `Fin` (total bytes) and `Reset` frames, each one a type byte and big-endian fields.
21//! Traffic is end-to-end encrypted by the connection (Noise), relayed or not.
22//!
23//! [`Node::accept_streams`]: crate::Node::accept_streams
24//! [`Node::open_stream`]: crate::Node::open_stream
25pub(crate) mod transport;
26
27use futures::channel::mpsc;
28use futures::io::{ReadHalf, WriteHalf};
29use futures::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt, SinkExt, StreamExt};
30use libp2p::swarm::ConnectionId;
31use libp2p::{PeerId, StreamProtocol};
32use std::collections::{HashMap, VecDeque};
33use std::io;
34use std::pin::Pin;
35use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
36use std::sync::{Arc, Mutex};
37use std::task::{Context, Poll};
38use std::time::{Duration, Instant};
39use transport::{Control, OpenError, PathEvent, Warm};
40
41/// How streams of one protocol behave.
42#[derive(Debug, Clone, Copy)]
43pub struct Limits {
44    /// Bytes a sender may have in flight unacknowledged (and a receiver buffers).
45    pub window: usize,
46    /// Largest data frame.
47    pub max_frame: usize,
48    /// Streams of this protocol open at once from others (more are refused).
49    pub max_streams: usize,
50    /// New inbound streams waiting for [`Incoming::accept`] (more are refused).
51    pub backlog: usize,
52    /// How long a stream waits for a path to come back before it fails.
53    pub resume: Duration,
54    /// Reset a stream after this long with nothing sent or received (`None`: never).
55    pub idle: Option<Duration>,
56}
57
58impl Default for Limits {
59    fn default() -> Self {
60        Limits { window: 1 << 20, max_frame: 64 * 1024, max_streams: 1024, backlog: 64, resume: Duration::from_secs(30), idle: None }
61    }
62}
63
64/// The kind of connection a stream is on.
65#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
66pub enum Path {
67    Direct,
68    Relayed,
69}
70
71const HELLO: u8 = 1;
72const WELCOME: u8 = 2;
73const REFUSE: u8 = 3;
74const DATA: u8 = 16;
75const ACK: u8 = 17;
76const FIN: u8 = 18;
77const RESET: u8 = 19;
78
79const REFUSE_BUSY: u8 = 1;
80const REFUSE_UNKNOWN: u8 = 2;
81const RESET_APP: u8 = 1;
82const RESET_IDLE: u8 = 2;
83
84const HANDSHAKE: Duration = Duration::from_secs(10);
85const LINGER: Duration = Duration::from_secs(2);
86const ACK_EVERY: Duration = Duration::from_millis(50);
87
88#[derive(Debug, PartialEq, Eq)]
89enum Frame {
90    Hello { resume: bool, id: u64, recv: u64 },
91    Welcome { recv: u64 },
92    Refuse(u8),
93    Data { off: u64, bytes: Vec<u8> },
94    Ack(u64),
95    Fin(u64),
96    Reset(u8),
97}
98
99fn bad(m: &str) -> io::Error {
100    io::Error::new(io::ErrorKind::InvalidData, m.to_string())
101}
102
103async fn u64_of<R: AsyncRead + Unpin>(r: &mut R) -> io::Result<u64> {
104    let mut b = [0u8; 8];
105    r.read_exact(&mut b).await?;
106    Ok(u64::from_be_bytes(b))
107}
108
109async fn read_frame<R: AsyncRead + Unpin>(r: &mut R, max_frame: usize) -> io::Result<Frame> {
110    let mut t = [0u8; 1];
111    r.read_exact(&mut t).await?;
112    Ok(match t[0] {
113        HELLO => {
114            let mut f = [0u8; 1];
115            r.read_exact(&mut f).await?;
116            Frame::Hello { resume: f[0] & 1 == 1, id: u64_of(r).await?, recv: u64_of(r).await? }
117        }
118        WELCOME => Frame::Welcome { recv: u64_of(r).await? },
119        REFUSE | RESET => {
120            let mut c = [0u8; 1];
121            r.read_exact(&mut c).await?;
122            if t[0] == REFUSE { Frame::Refuse(c[0]) } else { Frame::Reset(c[0]) }
123        }
124        DATA => {
125            let off = u64_of(r).await?;
126            let mut l = [0u8; 4];
127            r.read_exact(&mut l).await?;
128            let n = u32::from_be_bytes(l) as usize;
129            if n > max_frame {
130                return Err(bad("data frame too large"));
131            }
132            let mut bytes = vec![0u8; n];
133            r.read_exact(&mut bytes).await?;
134            Frame::Data { off, bytes }
135        }
136        ACK => Frame::Ack(u64_of(r).await?),
137        FIN => Frame::Fin(u64_of(r).await?),
138        _ => return Err(bad("unknown frame")),
139    })
140}
141
142fn encode(f: &Frame, out: &mut Vec<u8>) {
143    match f {
144        Frame::Hello { resume, id, recv } => {
145            out.extend([HELLO, *resume as u8]);
146            out.extend(id.to_be_bytes());
147            out.extend(recv.to_be_bytes());
148        }
149        Frame::Welcome { recv } => {
150            out.push(WELCOME);
151            out.extend(recv.to_be_bytes());
152        }
153        Frame::Refuse(c) => out.extend([REFUSE, *c]),
154        Frame::Reset(c) => out.extend([RESET, *c]),
155        Frame::Data { off, bytes } => {
156            out.push(DATA);
157            out.extend(off.to_be_bytes());
158            out.extend((bytes.len() as u32).to_be_bytes());
159            out.extend(bytes);
160        }
161        Frame::Ack(n) => {
162            out.push(ACK);
163            out.extend(n.to_be_bytes());
164        }
165        Frame::Fin(n) => {
166            out.push(FIN);
167            out.extend(n.to_be_bytes());
168        }
169    }
170}
171
172async fn write_frame<W: AsyncWrite + Unpin>(w: &mut W, f: &Frame) -> io::Result<()> {
173    let mut b = Vec::new();
174    encode(f, &mut b);
175    w.write_all(&b).await?;
176    w.flush().await
177}
178
179type Sub = (ReadHalf<libp2p::Stream>, WriteHalf<libp2p::Stream>);
180
181/// What a [`Stream`] reads: bytes, or why the stream failed.
182type Chunk = Result<Vec<u8>, String>;
183
184#[derive(Default)]
185struct Info {
186    relayed: AtomicBool,
187    moves: AtomicU32,
188}
189
190/// A reliable byte stream to a peer that moves between relayed and direct connections without
191/// losing anything. Use it as a `futures` `AsyncRead`/`AsyncWrite`, or with the blocking
192/// `std::io::Read`/`Write` (not from inside an async task). Closing (or dropping) it ends the
193/// sending side; reads return 0 once the peer has closed its side and everything has arrived.
194pub struct Stream {
195    peer: PeerId,
196    protocol: String,
197    tx: Option<mpsc::Sender<Vec<u8>>>,
198    rx: mpsc::Receiver<Chunk>,
199    buf: Vec<u8>,
200    pos: usize,
201    info: Arc<Info>,
202    reset: mpsc::UnboundedSender<()>,
203    max_frame: usize,
204}
205
206impl std::fmt::Debug for Stream {
207    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
208        f.debug_struct("Stream").field("peer", &self.peer).field("protocol", &self.protocol).field("path", &self.path()).finish()
209    }
210}
211
212impl Stream {
213    pub fn peer(&self) -> PeerId {
214        self.peer
215    }
216
217    pub fn protocol(&self) -> &str {
218        &self.protocol
219    }
220
221    /// The kind of connection the stream is on now.
222    pub fn path(&self) -> Path {
223        if self.info.relayed.load(Ordering::Relaxed) { Path::Relayed } else { Path::Direct }
224    }
225
226    /// How many times the stream has moved to another connection.
227    pub fn moves(&self) -> u32 {
228        self.info.moves.load(Ordering::Relaxed)
229    }
230
231    /// End the sending side (the peer reads to the end of what was written).
232    pub fn close_write(&mut self) {
233        self.tx = None;
234    }
235
236    /// Abort the stream both ways; the peer's reads fail.
237    pub fn reset(self) {
238        let _ = self.reset.unbounded_send(());
239    }
240}
241
242impl AsyncRead for Stream {
243    fn poll_read(mut self: Pin<&mut Self>, cx: &mut Context<'_>, out: &mut [u8]) -> Poll<io::Result<usize>> {
244        let this = &mut *self;
245        loop {
246            if this.pos < this.buf.len() {
247                let n = out.len().min(this.buf.len() - this.pos);
248                out[..n].copy_from_slice(&this.buf[this.pos..this.pos + n]);
249                this.pos += n;
250                return Poll::Ready(Ok(n));
251            }
252            match this.rx.poll_next_unpin(cx) {
253                Poll::Ready(Some(Ok(v))) => {
254                    this.buf = v;
255                    this.pos = 0;
256                }
257                Poll::Ready(Some(Err(e))) => return Poll::Ready(Err(io::Error::new(io::ErrorKind::ConnectionReset, e))),
258                Poll::Ready(None) => return Poll::Ready(Ok(0)),
259                Poll::Pending => return Poll::Pending,
260            }
261        }
262    }
263}
264
265impl AsyncWrite for Stream {
266    fn poll_write(mut self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8]) -> Poll<io::Result<usize>> {
267        let max = self.max_frame;
268        let Some(tx) = self.tx.as_mut() else { return Poll::Ready(Err(io::ErrorKind::BrokenPipe.into())) };
269        if buf.is_empty() {
270            return Poll::Ready(Ok(0));
271        }
272        match tx.poll_ready(cx) {
273            Poll::Ready(Ok(())) => {
274                let n = buf.len().min(max);
275                match tx.start_send(buf[..n].to_vec()) {
276                    Ok(()) => Poll::Ready(Ok(n)),
277                    Err(_) => Poll::Ready(Err(io::ErrorKind::BrokenPipe.into())),
278                }
279            }
280            Poll::Ready(Err(_)) => Poll::Ready(Err(io::ErrorKind::BrokenPipe.into())),
281            Poll::Pending => Poll::Pending,
282        }
283    }
284
285    fn poll_flush(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<io::Result<()>> {
286        Poll::Ready(Ok(()))
287    }
288
289    fn poll_close(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<io::Result<()>> {
290        self.tx = None;
291        Poll::Ready(Ok(()))
292    }
293}
294
295impl io::Read for Stream {
296    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
297        futures::executor::block_on(AsyncReadExt::read(self, buf))
298    }
299}
300
301impl io::Write for Stream {
302    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
303        futures::executor::block_on(AsyncWriteExt::write(self, buf))
304    }
305
306    fn flush(&mut self) -> io::Result<()> {
307        Ok(())
308    }
309}
310
311/// Inbound streams of one protocol. Dropping it stops accepting them.
312pub struct Incoming {
313    protocol: String,
314    rx: mpsc::Receiver<Stream>,
315    _task: Abort,
316}
317
318struct Abort(tokio::task::AbortHandle);
319
320impl Drop for Abort {
321    fn drop(&mut self) {
322        self.0.abort();
323    }
324}
325
326impl Incoming {
327    pub fn protocol(&self) -> &str {
328        &self.protocol
329    }
330
331    /// The next stream (blocking; `None` once the node stops).
332    pub fn accept(&mut self) -> Option<Stream> {
333        futures::executor::block_on(self.rx.next())
334    }
335
336    /// The next stream, waiting at most `d`.
337    pub fn accept_timeout(&mut self, d: Duration) -> Option<Stream> {
338        let deadline = Instant::now() + d;
339        loop {
340            match self.rx.try_recv() {
341                Ok(s) => return Some(s),
342                Err(mpsc::TryRecvError::Closed) => return None,
343                Err(mpsc::TryRecvError::Empty) if Instant::now() >= deadline => return None,
344                Err(mpsc::TryRecvError::Empty) => std::thread::sleep(Duration::from_millis(5)),
345            }
346        }
347    }
348
349    /// The next stream (async).
350    pub async fn next(&mut self) -> Option<Stream> {
351        self.rx.next().await
352    }
353}
354
355impl futures::Stream for Incoming {
356    type Item = Stream;
357
358    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Stream>> {
359        self.rx.poll_next_unpin(cx)
360    }
361}
362
363/// A substream that resumes a stream, handed to its driver.
364struct Resume {
365    sub: Sub,
366    relayed: bool,
367    conn: ConnectionId,
368    recv: u64,
369}
370
371type Registry = Arc<Mutex<HashMap<(PeerId, u64), mpsc::UnboundedSender<Resume>>>>;
372
373fn stream_err(e: OpenError) -> crate::NetError {
374    crate::NetError::Network(e.to_string())
375}
376
377fn app_side(peer: PeerId, protocol: &StreamProtocol, limits: &Limits, relayed: bool) -> (Stream, AppEnds, Arc<Info>) {
378    let (tx, app_in) = mpsc::channel(4);
379    let (app_out, rx) = mpsc::channel(4);
380    let (reset, reset_rx) = mpsc::unbounded();
381    let info = Arc::new(Info::default());
382    info.relayed.store(relayed, Ordering::Relaxed);
383    let s = Stream {
384        peer,
385        protocol: protocol.to_string(),
386        tx: Some(tx),
387        rx,
388        buf: vec![],
389        pos: 0,
390        info: info.clone(),
391        reset,
392        max_frame: limits.max_frame,
393    };
394    (s, AppEnds { app_in, app_out, reset_rx }, info)
395}
396
397struct AppEnds {
398    app_in: mpsc::Receiver<Vec<u8>>,
399    app_out: mpsc::Sender<Chunk>,
400    reset_rx: mpsc::UnboundedReceiver<()>,
401}
402
403/// Open a stream of `protocol` to `peer` (already connected or dialable by peer id).
404pub(crate) async fn open(control: Control, peer: PeerId, protocol: StreamProtocol, limits: Limits) -> crate::Result<Stream> {
405    let id = u64::from_be_bytes(uuid::Uuid::new_v4().as_bytes()[..8].try_into().unwrap_or_default());
406    let watch = control.watch();
407    let (sub, relayed, conn, _) = handshake(&control, peer, &protocol, id, false, 0, &limits).await?;
408    let (s, ends, info) = app_side(peer, &protocol, &limits, relayed);
409    let d = Driver::new(peer, protocol, id, true, limits, control, ends, info, watch, None);
410    tokio::spawn(d.run(sub, relayed, conn));
411    Ok(s)
412}
413
414/// The opener's handshake on a new substream: `Hello`, then the peer's `Welcome`.
415async fn handshake(
416    control: &Control,
417    peer: PeerId,
418    protocol: &StreamProtocol,
419    id: u64,
420    resume: bool,
421    recv: u64,
422    limits: &Limits,
423) -> crate::Result<(Sub, bool, ConnectionId, u64)> {
424    let opened = tokio::time::timeout(HANDSHAKE, control.open(peer, protocol.clone()))
425        .await
426        .map_err(|_| crate::NetError::Network(format!("no stream to {peer} in time")))?
427        .map_err(stream_err)?;
428    let (s, relayed, conn) = opened;
429    let (mut r, mut w) = s.split();
430    let shake = async {
431        write_frame(&mut w, &Frame::Hello { resume, id, recv }).await?;
432        read_frame(&mut r, limits.max_frame).await
433    };
434    match tokio::time::timeout(HANDSHAKE, shake).await {
435        Ok(Ok(Frame::Welcome { recv })) => Ok(((r, w), relayed, conn, recv)),
436        Ok(Ok(Frame::Refuse(REFUSE_BUSY))) => Err(crate::NetError::Network(format!("{peer} has too many {protocol} streams"))),
437        Ok(Ok(Frame::Refuse(_))) => Err(crate::NetError::Network(format!("{peer} refused the {protocol} stream"))),
438        Ok(Ok(_)) => Err(crate::NetError::Network("unexpected stream frame".into())),
439        Ok(Err(e)) => Err(crate::NetError::Network(format!("stream handshake: {e}"))),
440        Err(_) => Err(crate::NetError::Network("stream handshake timed out".into())),
441    }
442}
443
444/// Accept streams of `protocol`: answer handshakes, hand new streams to the returned
445/// [`Incoming`] and resumes to their drivers.
446pub(crate) fn accept(control: Control, protocol: StreamProtocol, limits: Limits, rt: &tokio::runtime::Handle) -> crate::Result<Incoming> {
447    let Some(mut inbound) = control.accept(protocol.clone(), limits.backlog.max(1)) else {
448        return Err(crate::NetError::Network(format!("{protocol} streams are accepted already")));
449    };
450    // one sender, so the channel holds exactly `backlog` streams (each clone would add a slot)
451    let (tx, rx) = mpsc::channel(limits.backlog.max(1) - 1);
452    let tx = Arc::new(Mutex::new(tx));
453    let registry: Registry = Arc::default();
454    let p = protocol.clone();
455    let task = rt.spawn(async move {
456        while let Some((peer, s, relayed, conn)) = inbound.next().await {
457            let (control, protocol, registry, tx) = (control.clone(), p.clone(), registry.clone(), tx.clone());
458            tokio::spawn(async move {
459                let (mut r, mut w) = s.split();
460                let hello = tokio::time::timeout(HANDSHAKE, read_frame(&mut r, limits.max_frame)).await;
461                let Ok(Ok(Frame::Hello { resume, id, recv })) = hello else { return };
462                if resume {
463                    let to = registry.lock().ok().and_then(|m| m.get(&(peer, id)).cloned());
464                    match to {
465                        Some(to) => {
466                            let _ = to.unbounded_send(Resume { sub: (r, w), relayed, conn, recv });
467                        }
468                        None => {
469                            let _ = write_frame(&mut w, &Frame::Refuse(REFUSE_UNKNOWN)).await;
470                        }
471                    }
472                    return;
473                }
474                let full = registry.lock().map(|m| m.len() >= limits.max_streams || m.contains_key(&(peer, id))).unwrap_or(true);
475                if full {
476                    let _ = write_frame(&mut w, &Frame::Refuse(REFUSE_BUSY)).await;
477                    return;
478                }
479                let (s, ends, info) = app_side(peer, &protocol, &limits, relayed);
480                let queued = tx.lock().map(|mut t| t.try_send(s).is_ok()).unwrap_or(false);
481                if !queued {
482                    let _ = write_frame(&mut w, &Frame::Refuse(REFUSE_BUSY)).await;
483                    return;
484                }
485                if write_frame(&mut w, &Frame::Welcome { recv: 0 }).await.is_err() {
486                    return;
487                }
488                let (rtx, rrx) = mpsc::unbounded();
489                if let Ok(mut m) = registry.lock() {
490                    m.insert((peer, id), rtx);
491                }
492                let watch = control.watch();
493                let d = Driver::new(peer, protocol, id, false, limits, control, ends, info, watch, Some(rrx));
494                d.run((r, w), relayed, conn).await;
495                if let Ok(mut m) = registry.lock() {
496                    m.remove(&(peer, id));
497                }
498            });
499        }
500        if let Ok(mut t) = tx.lock() {
501            t.close_channel();
502        }
503    });
504    Ok(Incoming { protocol: protocol.to_string(), rx, _task: Abort(task.abort_handle()) })
505}
506
507/// Carries one logical stream over its current substream, and moves it.
508struct Driver {
509    peer: PeerId,
510    protocol: StreamProtocol,
511    id: u64,
512    opener: bool,
513    limits: Limits,
514    control: Control,
515    _warm: Warm,
516    info: Arc<Info>,
517    watch: mpsc::UnboundedReceiver<PathEvent>,
518    resumes: Option<mpsc::UnboundedReceiver<Resume>>,
519    // the current substream's writer and generation; frames from every reader
520    writer: Option<WriteHalf<libp2p::Stream>>,
521    relayed: bool,
522    conn: Option<ConnectionId>,
523    want_move: bool,
524    generation: u64,
525    frames_tx: mpsc::Sender<(u64, Frame)>,
526    frames: mpsc::Receiver<(u64, Frame)>,
527    // a substream's reader saw it end (apart from frames, which wait while the inbox is full)
528    lost_tx: mpsc::UnboundedSender<u64>,
529    lost: mpsc::UnboundedReceiver<u64>,
530    // sending: bytes from `acked` on, the next offset to write, the total once closed
531    out: VecDeque<u8>,
532    acked: u64,
533    sent: u64,
534    app_in: Option<mpsc::Receiver<Vec<u8>>>,
535    fin: Option<u64>,
536    fin_sent: Option<u64>,
537    // receiving
538    inbox: VecDeque<Vec<u8>>,
539    inbox_bytes: usize,
540    recv: u64,
541    // bytes handed to the application (or dropped for it): what we acknowledge, so a sender's
542    // window bounds what we buffer and frames never have to wait
543    delivered: u64,
544    ack_sent: u64,
545    peer_fin: Option<u64>,
546    app_out: Option<mpsc::Sender<Chunk>>,
547    /// `None` once the application dropped its end (an end, not a reset).
548    reset_rx: Option<mpsc::UnboundedReceiver<()>>,
549    last: Instant,
550}
551
552enum Step {
553    Go,
554    Lost,
555    Fail(String),
556    Done,
557}
558
559impl Driver {
560    #[allow(clippy::too_many_arguments)]
561    fn new(
562        peer: PeerId,
563        protocol: StreamProtocol,
564        id: u64,
565        opener: bool,
566        limits: Limits,
567        control: Control,
568        ends: AppEnds,
569        info: Arc<Info>,
570        watch: mpsc::UnboundedReceiver<PathEvent>,
571        resumes: Option<mpsc::UnboundedReceiver<Resume>>,
572    ) -> Self {
573        let (frames_tx, frames) = mpsc::channel(16);
574        let (lost_tx, lost) = mpsc::unbounded();
575        Driver {
576            peer,
577            protocol,
578            id,
579            opener,
580            limits,
581            _warm: control.warm(peer),
582            control,
583            info,
584            watch,
585            resumes,
586            writer: None,
587            relayed: false,
588            conn: None,
589            want_move: false,
590            generation: 0,
591            frames_tx,
592            frames,
593            lost_tx,
594            lost,
595            out: VecDeque::new(),
596            acked: 0,
597            sent: 0,
598            app_in: Some(ends.app_in),
599            fin: None,
600            fin_sent: None,
601            inbox: VecDeque::new(),
602            inbox_bytes: 0,
603            recv: 0,
604            delivered: 0,
605            ack_sent: 0,
606            peer_fin: None,
607            app_out: Some(ends.app_out),
608            reset_rx: Some(ends.reset_rx),
609            last: Instant::now(),
610        }
611    }
612
613    /// Make `sub` the stream's substream; the peer has `peer_recv` bytes of ours.
614    fn adopt(&mut self, sub: Sub, relayed: bool, conn: ConnectionId, peer_recv: u64) {
615        let (mut r, w) = sub;
616        if let Some(mut old) = self.writer.replace(w) {
617            tokio::spawn(async move {
618                let _ = old.close().await;
619            });
620        }
621        if self.generation > 0 {
622            self.info.moves.fetch_add(1, Ordering::Relaxed);
623        }
624        self.generation += 1;
625        self.relayed = relayed;
626        self.conn = Some(conn);
627        self.info.relayed.store(relayed, Ordering::Relaxed);
628        self.on_ack(peer_recv);
629        self.sent = self.acked;
630        self.fin_sent = None;
631        // what we have counts as acknowledged: the handshake carried it
632        self.ack_sent = self.ack_sent.max(self.recv);
633        let (g, mut tx, lost, max) = (self.generation, self.frames_tx.clone(), self.lost_tx.clone(), self.limits.max_frame);
634        tokio::spawn(async move {
635            loop {
636                match read_frame(&mut r, max).await {
637                    Ok(f) => {
638                        if tx.send((g, f)).await.is_err() {
639                            break;
640                        }
641                    }
642                    Err(_) => {
643                        let _ = lost.unbounded_send(g);
644                        break;
645                    }
646                }
647            }
648        });
649        tracing::debug!(peer = %self.peer, id = self.id, relayed, "network: stream on a new path");
650    }
651
652    fn on_ack(&mut self, n: u64) {
653        if n > self.acked {
654            let k = ((n - self.acked) as usize).min(self.out.len());
655            self.out.drain(..k);
656            self.acked += k as u64;
657        }
658    }
659
660    async fn run(mut self, sub: Sub, relayed: bool, conn: ConnectionId) {
661        self.adopt(sub, relayed, conn, 0);
662        let mut done_at: Option<Instant> = None;
663        let mut tick = tokio::time::interval(ACK_EVERY);
664        loop {
665            if self.want_move {
666                self.want_move = false;
667                self.migrate().await;
668            }
669            let step = if self.writer.is_some() { self.flush().await } else { Step::Lost };
670            let step = match step {
671                Step::Go => self.select(&mut tick, done_at).await,
672                s => s,
673            };
674            match step {
675                Step::Go => {}
676                Step::Done => return,
677                Step::Fail(e) => return self.fail(e).await,
678                Step::Lost => {
679                    if done_at.is_some() {
680                        return;
681                    }
682                    self.writer = None;
683                    self.conn = None;
684                    if let Err(e) = self.recover().await {
685                        return self.fail(e).await;
686                    }
687                }
688            }
689            if done_at.is_none() && self.finished() {
690                done_at = Some(Instant::now());
691            }
692        }
693    }
694
695    fn finished(&self) -> bool {
696        self.fin.is_some_and(|f| self.acked == f && self.fin_sent.is_some())
697            && self.peer_fin.is_some_and(|f| f == self.recv)
698            && self.inbox.is_empty()
699            && self.app_out.is_none()
700            && self.ack_sent == self.recv
701    }
702
703    async fn fail(mut self, why: String) {
704        tracing::debug!(peer = %self.peer, id = self.id, "network: stream failed: {why}");
705        if let Some(w) = self.writer.as_mut() {
706            let _ = write_frame(w, &Frame::Reset(RESET_APP)).await;
707        }
708        if let Some(mut tx) = self.app_out.take() {
709            let _ = tx.try_send(Err(why));
710        }
711    }
712
713    /// Write what hasn't been written on this substream (data, then the end).
714    async fn flush(&mut self) -> Step {
715        let Some(w) = self.writer.as_mut() else { return Step::Lost };
716        let end = self.acked + self.out.len() as u64;
717        let mut batch = Vec::new();
718        while self.sent < end && batch.len() < 4 * self.limits.max_frame {
719            let from = (self.sent - self.acked) as usize;
720            let n = (self.out.len() - from).min(self.limits.max_frame);
721            let bytes: Vec<u8> = self.out.range(from..from + n).copied().collect();
722            encode(&Frame::Data { off: self.sent, bytes }, &mut batch);
723            self.sent += n as u64;
724        }
725        if let Some(f) = self.fin
726            && self.sent == f
727            && self.fin_sent != Some(self.generation)
728        {
729            encode(&Frame::Fin(f), &mut batch);
730            self.fin_sent = Some(self.generation);
731        }
732        if self.delivered > self.ack_sent && (self.delivered - self.ack_sent >= (self.limits.window / 4) as u64 || self.peer_fin.is_some()) {
733            encode(&Frame::Ack(self.delivered), &mut batch);
734            self.ack_sent = self.delivered;
735        }
736        if batch.is_empty() {
737            return Step::Go;
738        }
739        self.last = Instant::now();
740        // a write can hang on a connection that is closing: its going away ends the wait
741        let (conn, watch, peer, opener, relayed) = (self.conn, &mut self.watch, self.peer, self.opener, self.relayed);
742        let mut want_move = false;
743        let write = async {
744            w.write_all(&batch).await?;
745            w.flush().await
746        };
747        tokio::pin!(write);
748        let step = loop {
749            tokio::select! {
750                r = &mut write => break if r.is_ok() { Step::Go } else { Step::Lost },
751                ev = watch.next() => match ev {
752                    Some(ev) if !ev.up && Some(ev.conn) == conn => break Step::Lost,
753                    Some(ev) if moves_to(&ev, peer, opener, relayed) => want_move = true,
754                    _ => {}
755                },
756            }
757        };
758        self.want_move |= want_move;
759        step
760    }
761
762    async fn select(&mut self, tick: &mut tokio::time::Interval, done_at: Option<Instant>) -> Step {
763        let window = self.limits.window;
764        let can_take = self.app_in.is_some() && self.out.len() < window;
765        let deliver = !self.inbox.is_empty() || (self.peer_fin.is_some_and(|f| f == self.recv) && self.app_out.is_some());
766        let idle = self.limits.idle.map(|d| self.last + d);
767        let linger = done_at.map(|t| t + LINGER);
768        tokio::select! {
769            // a reset comes before the end that dropping the stream also makes
770            biased;
771            r = async { self.reset_rx.as_mut().unwrap().next().await }, if self.reset_rx.is_some() => match r {
772                Some(()) => Step::Fail("reset".into()),
773                // dropped: what was written still goes out, then the end
774                None => {
775                    self.reset_rx = None;
776                    Step::Go
777                }
778            },
779            f = self.frames.next() => match f {
780                Some((g, f)) => self.frame(g, f),
781                None => Step::Go,
782            },
783            g = self.lost.next() => match g {
784                Some(g) if g == self.generation => Step::Lost,
785                _ => Step::Go,
786            },
787            c = async { self.app_in.as_mut().unwrap().next().await }, if can_take => {
788                match c {
789                    Some(v) => self.out.extend(v),
790                    None => {
791                        self.app_in = None;
792                        self.fin = Some(self.acked + self.out.len() as u64);
793                    }
794                }
795                self.last = Instant::now();
796                Step::Go
797            }
798            r = futures::future::poll_fn(|cx| match self.app_out.as_mut() {
799                Some(tx) => tx.poll_ready(cx).map(|r| r.is_ok()),
800                None => Poll::Ready(false),
801            }), if deliver => {
802                self.deliver(r);
803                Step::Go
804            }
805            ev = self.watch.next() => match ev {
806                Some(ev) if !ev.up && Some(ev.conn) == self.conn => Step::Lost,
807                Some(ev) if moves_to(&ev, self.peer, self.opener, self.relayed) => {
808                    self.want_move = true;
809                    Step::Go
810                }
811                _ => Step::Go,
812            },
813            r = async { self.resumes.as_mut().unwrap().next().await }, if self.resumes.is_some() => {
814                if let Some(r) = r {
815                    self.take_resume(r).await;
816                }
817                Step::Go
818            }
819            _ = tick.tick() => {
820                if self.delivered > self.ack_sent && let Some(w) = self.writer.as_mut() {
821                    self.ack_sent = self.delivered;
822                    if write_frame(w, &Frame::Ack(self.delivered)).await.is_err() {
823                        return Step::Lost;
824                    }
825                }
826                Step::Go
827            }
828            _ = async { tokio::time::sleep_until(idle.unwrap().into()).await }, if idle.is_some() && done_at.is_none() => {
829                if let Some(w) = self.writer.as_mut() {
830                    let _ = write_frame(w, &Frame::Reset(RESET_IDLE)).await;
831                }
832                Step::Fail("idle".into())
833            }
834            _ = async { tokio::time::sleep_until(linger.unwrap().into()).await }, if linger.is_some() => Step::Done,
835        }
836    }
837
838    fn frame(&mut self, _g: u64, f: Frame) -> Step {
839        self.last = Instant::now();
840        match f {
841            Frame::Data { off, bytes } => {
842                let end = off + bytes.len() as u64;
843                if off <= self.recv && end > self.recv {
844                    let tail = bytes[(self.recv - off) as usize..].to_vec();
845                    self.recv = end;
846                    if self.app_out.is_some() {
847                        self.inbox_bytes += tail.len();
848                        self.inbox.push_back(tail);
849                    } else {
850                        self.delivered = self.recv;
851                    }
852                }
853                Step::Go
854            }
855            Frame::Ack(n) => {
856                self.on_ack(n);
857                Step::Go
858            }
859            Frame::Fin(n) => {
860                self.peer_fin = Some(n);
861                Step::Go
862            }
863            Frame::Reset(c) => Step::Fail(if c == RESET_IDLE { "the peer reset the idle stream".into() } else { "the peer reset the stream".into() }),
864            _ => Step::Go,
865        }
866    }
867
868    fn deliver(&mut self, ready: bool) {
869        if !ready {
870            // the reader is gone: what arrives is dropped
871            self.app_out = None;
872            self.inbox.clear();
873            self.inbox_bytes = 0;
874            self.delivered = self.recv;
875            return;
876        }
877        let Some(tx) = self.app_out.as_mut() else { return };
878        match self.inbox.pop_front() {
879            Some(v) => {
880                self.inbox_bytes -= v.len();
881                self.delivered += v.len() as u64;
882                if tx.start_send(Ok(v)).is_err() {
883                    self.app_out = None;
884                }
885            }
886            None => self.app_out = None, // the peer's end: reads return 0
887        }
888    }
889
890    /// The opener moves the stream to a new direct connection.
891    async fn migrate(&mut self) {
892        if !self.control.has_direct(self.peer) {
893            return;
894        }
895        match handshake(&self.control, self.peer, &self.protocol, self.id, true, self.recv, &self.limits).await {
896            Ok((sub, false, conn, peer_recv)) => self.adopt(sub, false, conn, peer_recv),
897            Ok(_) => {}
898            Err(e) => tracing::debug!(peer = %self.peer, "network: stream stays relayed: {e}"),
899        }
900    }
901
902    async fn take_resume(&mut self, r: Resume) {
903        let Resume { sub: (rd, mut w), relayed, conn, recv } = r;
904        if write_frame(&mut w, &Frame::Welcome { recv: self.recv }).await.is_ok() {
905            self.adopt((rd, w), relayed, conn, recv);
906        }
907    }
908
909    /// The substream went away: the opener opens another, the acceptor waits for one.
910    async fn recover(&mut self) -> std::result::Result<(), String> {
911        let deadline = tokio::time::Instant::now() + self.limits.resume;
912        let mut wait = Duration::from_millis(100);
913        loop {
914            if tokio::time::Instant::now() >= deadline {
915                return Err("no path to the peer came back".into());
916            }
917            if self.opener {
918                match handshake(&self.control, self.peer, &self.protocol, self.id, true, self.recv, &self.limits).await {
919                    Ok((sub, relayed, conn, peer_recv)) => {
920                        self.adopt(sub, relayed, conn, peer_recv);
921                        return Ok(());
922                    }
923                    Err(e) if e.to_string().contains("refused") => return Err(e.to_string()),
924                    Err(e) => tracing::debug!(peer = %self.peer, "network: stream resume: {e}"),
925                }
926                tokio::time::sleep(wait.min(deadline.saturating_duration_since(tokio::time::Instant::now()))).await;
927                wait = (wait * 2).min(Duration::from_secs(2));
928            } else {
929                let next = async { self.resumes.as_mut().unwrap().next().await };
930                match tokio::time::timeout_at(deadline, next).await {
931                    Ok(Some(r)) => {
932                        self.take_resume(r).await;
933                        if self.writer.is_some() {
934                            return Ok(());
935                        }
936                    }
937                    Ok(None) => return Err("closed".into()),
938                    Err(_) => return Err("the peer did not come back".into()),
939                }
940            }
941        }
942    }
943}
944
945/// The opener moves a relayed stream when a direct connection to its peer comes up.
946fn moves_to(ev: &PathEvent, peer: PeerId, opener: bool, relayed: bool) -> bool {
947    opener && relayed && ev.up && !ev.relayed && ev.peer == peer
948}
949
950#[cfg(test)]
951mod tests {
952    use super::*;
953
954    #[test]
955    fn frames_round_trip() {
956        let frames = [
957            Frame::Hello { resume: true, id: 7, recv: 1 << 40 },
958            Frame::Welcome { recv: 3 },
959            Frame::Refuse(REFUSE_BUSY),
960            Frame::Data { off: 9, bytes: vec![1, 2, 3] },
961            Frame::Ack(12),
962            Frame::Fin(12),
963            Frame::Reset(RESET_APP),
964        ];
965        for f in frames {
966            let mut b = vec![];
967            encode(&f, &mut b);
968            let got = futures::executor::block_on(read_frame(&mut &b[..], 1024)).unwrap();
969            assert_eq!(got, f);
970        }
971        let mut b = vec![];
972        encode(&Frame::Data { off: 0, bytes: vec![0; 2048] }, &mut b);
973        assert!(futures::executor::block_on(read_frame(&mut &b[..], 1024)).is_err());
974        assert!(futures::executor::block_on(read_frame(&mut &[99u8][..], 1024)).is_err());
975    }
976}