vaegram 0.3.0

Telegram MTProto client library for users and bots
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
#[cfg(feature = "dns-config")]
mod dns_config;
mod fake_tls;
#[cfg(any(feature = "websocket", feature = "dns-config", feature = "web-proxy"))]
mod http1;
mod obfuscated;
mod proxy;
#[cfg(test)]
pub(crate) mod slow_link;
#[cfg(any(feature = "websocket", feature = "dns-config", feature = "web-proxy"))]
mod tls;
mod transport;
#[cfg(feature = "web-proxy")]
mod web_proxy;
#[cfg(feature = "websocket")]
mod websocket;

#[cfg(feature = "dns-config")]
pub use dns_config::{AccessPointRule, DnsConfig, IpPort};
pub use proxy::{Proxy, Secret};
pub use transport::Transport;
pub(crate) use transport::{Framing, MAX_PACKET, RecvBuf};
#[cfg(all(test, feature = "websocket"))]
pub(crate) use websocket::tests::{open_plain as open_plain_websocket, ping_when_idle};

use std::collections::VecDeque;
use std::io;
use std::net::SocketAddr;
use std::pin::Pin;
use std::sync::Arc;
use std::task::{Context, Poll};
use std::time::Duration;

use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt, ReadBuf};
use tokio::net::TcpStream;
use tokio::net::tcp::{OwnedReadHalf, OwnedWriteHalf};
use tokio::sync::Notify;

use crate::errors::{Error, Result};
use crate::session::internals::data_center::Dc;
use crate::session::{Call, Observer, Retry};
use crate::storage::recording::Recorder;
use crate::types::Json;
use fake_tls::{RecordReader, RecordWriter};
use obfuscated::Ctr;
use proxy::Target;

const READ_CHUNK: usize = 64 << 10;
/// The slowest link a connection still serves, in bytes per second: no deadline cuts short what would be done at
/// this rate.
pub(crate) const MIN_RATE: u64 = 8 << 10;
// What the stream took and the server isn't known to have got could still be on its way at MIN_RATE; a stream that
// then takes no byte (or doesn't finish a flush) for this long more goes to a peer that's gone, which TCP alone
// retries for many minutes.
const WRITE_STALL: Duration = Duration::from_secs(20);

const CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
// A web proxy's setup is several HTTPS requests and a long poll for WELCOME, each with its own deadline; this only
// bounds the whole.
#[cfg(feature = "web-proxy")]
const WEB_PROXY_CONNECT_TIMEOUT: Duration = Duration::from_secs(90);

/// A byte stream a [`ConnectionFactory`] hands back: a TCP socket, a TLS session, a tunnel, anything.
pub trait Stream: AsyncRead + AsyncWrite + Send + Unpin {}

impl<T: AsyncRead + AsyncWrite + Send + Unpin> Stream for T {}

/// The future a [`ConnectionFactory`] returns: the opened stream, or why it couldn't be opened.
pub type Connecting<'a> = Pin<Box<dyn Future<Output = io::Result<Box<dyn Stream>>> + Send + 'a>>;

/// Opens the byte stream a connection runs over, in place of a plain TCP connect: to bind a local address, enter a
/// network namespace or tunnel. It's given the data center's address, or the proxy's when one is set (the proxy
/// handshake then runs over the stream). A closure `Fn(SocketAddr) -> impl Future<Output = io::Result<impl Stream>>`
/// is one. Transfer and CDN connections use it too.
pub trait ConnectionFactory: Send + Sync {
    /// Opens a stream to `addr`. An error fails that connection attempt like a refused TCP connect.
    fn connect(&self, addr: SocketAddr) -> Connecting<'_>;
}

impl<F, Fut, S> ConnectionFactory for F
where
    F: Fn(SocketAddr) -> Fut + Send + Sync,
    Fut: Future<Output = io::Result<S>> + Send + 'static,
    S: Stream + 'static,
{
    fn connect(&self, addr: SocketAddr) -> Connecting<'_> {
        let stream = self(addr);
        Box::pin(async move { Ok(Box::new(stream.await?) as Box<dyn Stream>) })
    }
}

/// Lets a factory that is already shared be passed in.
impl<T: ConnectionFactory + ?Sized> ConnectionFactory for Arc<T> {
    fn connect(&self, addr: SocketAddr) -> Connecting<'_> {
        (**self).connect(addr)
    }
}

impl std::fmt::Debug for dyn ConnectionFactory {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("ConnectionFactory")
    }
}

/// How a session connects and talks to Telegram: transport, proxy, timeouts, retries and the device it reports.
/// [`ClientBuilder`](crate::ClientBuilder) fills one from its settings. Only the `unstable-raw` plumbing
/// (`Connection::connect` and `Session::connect`) takes an `Options`, so without that feature one built with the
/// setters here has no use.
#[derive(Clone, Debug)]
#[non_exhaustive]
pub struct Options {
    /// The framing of packets on the wire; [`Transport::Intermediate`] by default.
    pub transport: Transport,
    /// Hides the transport from DPI with an obfuscation header; off by default. MTProxy connections are always
    /// obfuscated, and the full transport can't be.
    pub obfuscated: bool,
    /// The proxy every connection goes through; `None` connects directly.
    pub proxy: Option<Proxy>,
    /// Opens every connection's stream instead of a TCP connect; see [`ConnectionFactory`].
    pub connection_factory: Option<Arc<dyn ConnectionFactory>>,
    /// How long a request waits for its answer before it fails with `Error::Timeout`; 30 seconds by default.
    pub request_timeout: Duration,
    /// Asked after every failed request whether to send it again, and after how long. The default sleeps off
    /// FLOOD_WAITs of up to a minute, five times per request.
    pub retry: Retry,
    /// Every request is sent inside `invokeWithoutUpdates`, so the connection never gets updates. Set by
    /// `ClientBuilder::no_updates`.
    pub no_updates: bool,
    /// Update batches held for the dispatcher. When it's full, a batch is dropped and a getDifference brings
    /// back what it held.
    pub updates_capacity: usize,
    /// Sees every request that ends; `None` by default.
    pub observer: Option<Observer>,
    /// Writes every message sent and received to a recording; `None` by default.
    pub record: Option<Recorder>,
    /// What the connection tells Telegram about the client in `initConnection`.
    pub device: Device,
    /// Carries MTProto over WebSocket on TLS (`wss://…web.telegram.org/apiws`), always obfuscated, instead of a
    /// direct TCP connection: for networks that only let HTTPS through. Set by `ClientBuilder::websocket`.
    #[cfg(feature = "websocket")]
    pub websocket: bool,
}

impl Default for Options {
    fn default() -> Self {
        Options {
            transport: Transport::default(),
            obfuscated: false,
            proxy: None,
            connection_factory: None,
            request_timeout: Duration::from_secs(30),
            retry: Retry::default(),
            no_updates: false,
            updates_capacity: 1024,
            observer: None,
            record: None,
            device: Device::default(),
            #[cfg(feature = "websocket")]
            websocket: false,
        }
    }
}

impl Options {
    /// Same as `Default`: the intermediate transport over a direct, unobfuscated TCP connection, a 30 s request
    /// timeout, room for 1024 update batches and the default retry policy.
    pub fn new() -> Self {
        Self::default()
    }

    /// Picks the MTProto transport the connection frames packets with.
    #[must_use]
    pub fn transport(mut self, transport: Transport) -> Self {
        self.transport = transport;
        self
    }

    /// Sets whether the transport is obfuscated. The full transport refuses obfuscation when connecting.
    #[must_use]
    pub fn obfuscated(mut self, obfuscated: bool) -> Self {
        self.obfuscated = obfuscated;
        self
    }

    /// Connects through `proxy` instead of directly.
    #[must_use]
    pub fn proxy(mut self, proxy: Proxy) -> Self {
        self.proxy = Some(proxy);
        self
    }

    /// Opens every connection's stream with `factory` instead of a TCP connect; see [`ConnectionFactory`].
    #[must_use]
    pub fn connection_factory(mut self, factory: impl ConnectionFactory + 'static) -> Self {
        self.connection_factory = Some(Arc::new(factory));
        self
    }

    /// Sets how long a request may wait for its answer.
    #[must_use]
    pub fn request_timeout(mut self, request_timeout: Duration) -> Self {
        self.request_timeout = request_timeout;
        self
    }

    /// Decides whether and when a failed request is sent again.
    #[must_use]
    pub fn retry(mut self, retry: Retry) -> Self {
        self.retry = retry;
        self
    }

    /// Sets whether every request goes inside `invokeWithoutUpdates`, so the connection never gets updates.
    #[must_use]
    pub fn no_updates(mut self, no_updates: bool) -> Self {
        self.no_updates = no_updates;
        self
    }

    /// Sets how many update batches are held for the dispatcher before one is dropped.
    #[must_use]
    pub fn updates_capacity(mut self, updates_capacity: usize) -> Self {
        self.updates_capacity = updates_capacity;
        self
    }

    /// Has `observer` see every request. It runs on the connection's task, so it should return quickly.
    #[must_use]
    pub fn observer(mut self, observer: impl Fn(&Call<'_>) + Send + Sync + 'static) -> Self {
        self.observer = Some(Observer(Arc::new(observer)));
        self
    }

    /// Records the traffic into `record`.
    #[must_use]
    pub fn record(mut self, record: Recorder) -> Self {
        self.record = Some(record);
        self
    }

    /// Sets the device the connection describes to Telegram in `initConnection`.
    #[must_use]
    pub fn device(mut self, device: Device) -> Self {
        self.device = device;
        self
    }

    /// Sets whether MTProto goes over WebSocket on TLS instead of a direct TCP connection.
    #[cfg(feature = "websocket")]
    #[must_use]
    pub fn websocket(mut self, websocket: bool) -> Self {
        self.websocket = websocket;
        self
    }

    #[cfg(feature = "websocket")]
    pub(crate) fn uses_websocket(&self) -> bool {
        self.websocket
    }

    #[cfg(not(feature = "websocket"))]
    pub(crate) fn uses_websocket(&self) -> bool {
        false
    }
}

/// The client details sent in `initConnection`, which Telegram shows in the account's list of active sessions.
/// The default is model `vaegram`, the OS name as the system version, this crate's version as the app version and
/// language `en`.
#[non_exhaustive]
#[derive(Clone, Debug)]
pub struct Device {
    /// The device model, `"vaegram"` by default.
    pub model: String,
    /// The operating system version, the OS name (`std::env::consts::OS`) by default.
    pub system_version: String,
    /// The application version, this crate's version by default.
    pub app_version: String,
    /// The language code of the user interface, such as `en`; `en` by default.
    pub lang_code: String,
    /// The official language pack the client uses (`android`, `ios`, `tdesktop`, …); empty by default.
    pub lang_pack: String,
    /// The device's own language; `None` sends `lang_code`.
    pub system_lang_code: Option<String>,
    /// The client's UTC offset in seconds, sent as `tz_offset` in `initConnection.params`; `None` sends none.
    pub tz_offset: Option<i32>,
    /// The JSON `initConnection.params` carries; `None` sends none. With a `tz_offset` set too, it must be an
    /// object: its `tz_offset` key is replaced, or added if it has none.
    pub params: Option<Json>,
}

impl Default for Device {
    fn default() -> Self {
        Device {
            model: "vaegram".into(),
            system_version: std::env::consts::OS.into(),
            app_version: env!("CARGO_PKG_VERSION").into(),
            lang_code: "en".into(),
            lang_pack: String::new(),
            system_lang_code: None,
            tz_offset: None,
            params: None,
        }
    }
}

unstable_raw_pub! {
    /// One transport connection to a data center, framed and obfuscated as its [`Options`] say. It carries MTProto
    /// packets without MTProto encryption, which the [`Session`](crate::session::Session) above it adds; each session
    /// opens its own connections rather than taking one.
    ///
    /// Experimental (`unstable-raw`): may change or go away in any release.
    struct Connection {
        reader: Reader,
        writer: Writer,
    }
}

impl Connection {
    /// Opens the stream, through the proxy or connection factory when set, and sends the transport's opening
    /// bytes. Fails with `Error::InvalidArgument` for the full transport with obfuscation or an MTProxy, or for
    /// WebSocket with an MTProxy or the full transport, and with an I/O `TimedOut` error after 10 seconds (90
    /// through a web proxy).
    pub async fn connect(dc: &Dc, options: &Options) -> Result<Self> {
        let addr = dc.addr;
        let via = if options.proxy.is_some() { " through the proxy" } else { "" };
        #[cfg(feature = "web-proxy")]
        let limit = match options.proxy {
            Some(Proxy::Web { .. }) => WEB_PROXY_CONNECT_TIMEOUT,
            _ => CONNECT_TIMEOUT,
        };
        #[cfg(not(feature = "web-proxy"))]
        let limit = CONNECT_TIMEOUT;
        tokio::time::timeout(limit, Self::open(dc, options))
            .await
            .map_err(|_| io::Error::new(io::ErrorKind::TimedOut, format!("connecting to {addr}{via} timed out")))?
    }

    async fn open(dc: &Dc, options: &Options) -> Result<Self> {
        let addr = dc.addr;
        let secret = options.proxy.as_ref().and_then(Proxy::secret);
        // The full transport sends no header to hide, so obfuscation has nothing to wrap, and an MTProxy only
        // understands the obfuscated ones.
        if options.transport == Transport::Full && (options.obfuscated || secret.is_some()) {
            return Err(Error::InvalidArgument("the full transport can't be obfuscated or go through an MTProxy"));
        }
        #[cfg(feature = "websocket")]
        if options.websocket {
            if secret.is_some() || options.transport == Transport::Full {
                return Err(Error::InvalidArgument("WebSocket can't go through an MTProxy or use the full transport"));
            }
            return Self::open_websocket(dc, options, &websocket::Endpoint::of(dc)?).await;
        }
        let (read, write) = match (&options.connection_factory, &options.proxy) {
            #[cfg(feature = "web-proxy")]
            (factory, Some(Proxy::Web { host, secret })) => {
                let stream: Box<dyn Stream> = Box::new(web_proxy::open(host, secret, factory.clone()).await?);
                let (read, write) = tokio::io::split(stream);
                (ReadHalf::Boxed(read), WriteHalf::Boxed(write))
            }
            (None, proxy) => {
                let stream = match proxy {
                    None => TcpStream::connect(addr).await?,
                    Some(proxy) => {
                        let mut stream = TcpStream::connect(proxy.endpoint()).await?;
                        proxy.handshake(&mut stream, Target::Addr(addr)).await?;
                        stream
                    }
                };
                stream.set_nodelay(true)?;
                let (read, write) = stream.into_split();
                (ReadHalf::Tcp(read), WriteHalf::Tcp(write))
            }
            (Some(factory), proxy) => {
                let mut stream = match proxy {
                    None => factory.connect(addr).await?,
                    Some(proxy) => {
                        let mut stream = dial_any(factory.as_ref(), proxy.endpoint()).await?;
                        proxy.handshake(&mut stream, Target::Addr(addr)).await?;
                        stream
                    }
                };
                stream.flush().await?;
                let (read, write) = tokio::io::split(stream);
                (ReadHalf::Boxed(read), WriteHalf::Boxed(write))
            }
        };
        Self::start(dc, options, read, write, options.obfuscated || secret.is_some()).await
    }

    #[cfg(feature = "websocket")]
    async fn open_websocket(dc: &Dc, options: &Options, endpoint: &websocket::Endpoint) -> Result<Self> {
        let (read, write) = websocket::open(endpoint, options).await?;
        // Telegram's WebSocket endpoints only take obfuscated streams.
        let read = ReadHalf::WebSocket(Box::new(read));
        Self::start(dc, options, read, WriteHalf::WebSocket(write), true).await
    }

    /// Sends what the transport starts with, the obfuscation header or the transport's tag, on a stream just opened.
    async fn start(dc: &Dc, options: &Options, read: ReadHalf, mut write: WriteHalf, obfuscate: bool) -> Result<Self> {
        let secret = options.proxy.as_ref().and_then(Proxy::secret);
        let transport =
            if secret.is_some_and(|s| s.padded) { Transport::PaddedIntermediate } else { options.transport };
        let tls = secret.is_some_and(|s| s.domain.is_some());
        let (encrypt, decrypt, records) = match transport.tag() {
            Some(tag) if obfuscate => {
                let (header, encrypt, decrypt) = obfuscated::init(tag, dc.wire_id() as i16, secret.map(|s| &s.key));
                // Behind fake TLS the header rides in the first record together with the first packet.
                let records = tls.then(|| RecordWriter::new(header));
                if !tls {
                    write.write_all(&header).await?;
                }
                (Some(encrypt), Some(decrypt), records)
            }
            Some(tag) => {
                write.write_all(if transport == Transport::Abridged { &tag[..1] } else { &tag[..] }).await?;
                (None, None, None)
            }
            // The full transport starts with its first packet.
            None => (None, None, None),
        };
        let framing = Framing::new(transport);
        Ok(Self {
            reader: Reader {
                wire: Wire { half: read, records: tls.then(RecordReader::default) },
                framing,
                decrypt,
                buf: RecvBuf::default(),
                last_byte: tokio::time::Instant::now(),
            },
            writer: Writer {
                room: write.room(),
                half: write,
                framing,
                encrypt,
                records,
                buf: Vec::new(),
                drained_by: tokio::time::Instant::now(),
                written: 0,
                arrived: 0,
                unproven: VecDeque::new(),
                arrived_id: i64::MIN,
            },
        })
    }

    /// Frames `payload` and writes it out.
    pub async fn send(&mut self, payload: &[u8]) -> Result<()> {
        self.writer.send(payload).await
    }

    /// Waits for the next whole packet and returns its payload. Fails with `UnexpectedEof` once the other side
    /// closes the stream.
    pub async fn recv(&mut self) -> Result<Vec<u8>> {
        self.reader.recv().await
    }

    pub(crate) fn into_split(self) -> (Reader, Writer) {
        (self.reader, self.writer)
    }
}

/// Dials the first address of `host` the factory can open, as a TCP connect to a host name tries each in turn.
async fn dial_any(factory: &dyn ConnectionFactory, host: (&str, u16)) -> io::Result<Box<dyn Stream>> {
    let mut last = io::Error::other("the host has no address");
    for addr in tokio::net::lookup_host(host).await? {
        match factory.connect(addr).await {
            Ok(stream) => return Ok(stream),
            Err(e) => last = e,
        }
    }
    Err(last)
}

pub(crate) struct Reader {
    wire: Wire,
    framing: Framing,
    decrypt: Option<Ctr>,
    buf: RecvBuf,
    last_byte: tokio::time::Instant,
}

impl Reader {
    /// Cancel-safe: bytes wait in the buffer until a whole packet is there.
    pub(crate) async fn recv(&mut self) -> Result<Vec<u8>> {
        loop {
            if let Some(packet) = self.framing.decode(&mut self.buf)? {
                return Ok(packet);
            }
            let buf = self.buf.make_room();
            buf.reserve(READ_CHUNK);
            let start = buf.len();
            if self.wire.read_buf(buf).await? == 0 {
                return Err(io::Error::from(io::ErrorKind::UnexpectedEof).into());
            }
            self.last_byte = tokio::time::Instant::now();
            if let Some(decrypt) = &mut self.decrypt {
                decrypt.apply(&mut buf[start..]);
            }
        }
    }

    /// When bytes last came in, whole packet or not: a big one takes a while on a slow link.
    pub(crate) fn last_byte(&self) -> tokio::time::Instant {
        self.last_byte
    }
}

struct Wire {
    half: ReadHalf,
    records: Option<RecordReader>,
}

impl AsyncRead for Wire {
    fn poll_read(mut self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>) -> Poll<io::Result<()>> {
        let this = &mut *self;
        match &mut this.records {
            Some(records) => records.poll_read(&mut this.half, cx, buf),
            None => Pin::new(&mut this.half).poll_read(cx, buf),
        }
    }
}

// TCP keeps its own halves, so the default path has no boxing or dynamic dispatch.
enum ReadHalf {
    Tcp(OwnedReadHalf),
    Boxed(tokio::io::ReadHalf<Box<dyn Stream>>),
    #[cfg(feature = "websocket")]
    WebSocket(Box<websocket::Read>),
}

impl AsyncRead for ReadHalf {
    fn poll_read(self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>) -> Poll<io::Result<()>> {
        match self.get_mut() {
            ReadHalf::Tcp(half) => Pin::new(half).poll_read(cx, buf),
            ReadHalf::Boxed(half) => Pin::new(half).poll_read(cx, buf),
            #[cfg(feature = "websocket")]
            ReadHalf::WebSocket(half) => Pin::new(half).poll_read(cx, buf),
        }
    }
}

enum WriteHalf {
    Tcp(OwnedWriteHalf),
    Boxed(tokio::io::WriteHalf<Box<dyn Stream>>),
    #[cfg(feature = "websocket")]
    WebSocket(websocket::Write),
}

impl WriteHalf {
    /// Free bytes the layer below needs in front of a framed packet.
    fn room(&self) -> usize {
        match self {
            #[cfg(feature = "websocket")]
            WriteHalf::WebSocket(_) => websocket::ROOM,
            _ => 0,
        }
    }
}

impl AsyncWrite for WriteHalf {
    fn poll_write(self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8]) -> Poll<io::Result<usize>> {
        match self.get_mut() {
            WriteHalf::Tcp(half) => Pin::new(half).poll_write(cx, buf),
            WriteHalf::Boxed(half) => Pin::new(half).poll_write(cx, buf),
            #[cfg(feature = "websocket")]
            WriteHalf::WebSocket(half) => Pin::new(half).poll_write(cx, buf),
        }
    }

    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
        match self.get_mut() {
            WriteHalf::Tcp(half) => Pin::new(half).poll_flush(cx),
            WriteHalf::Boxed(half) => Pin::new(half).poll_flush(cx),
            #[cfg(feature = "websocket")]
            WriteHalf::WebSocket(half) => Pin::new(half).poll_flush(cx),
        }
    }

    fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
        match self.get_mut() {
            WriteHalf::Tcp(half) => Pin::new(half).poll_shutdown(cx),
            WriteHalf::Boxed(half) => Pin::new(half).poll_shutdown(cx),
            #[cfg(feature = "websocket")]
            WriteHalf::WebSocket(half) => Pin::new(half).poll_shutdown(cx),
        }
    }
}

pub(crate) struct Writer {
    half: WriteHalf,
    // Bytes kept free in front of the framing room, for the WebSocket frame header.
    room: usize,
    framing: Framing,
    encrypt: Option<Ctr>,
    records: Option<RecordWriter>,
    pub(crate) buf: Vec<u8>,
    // When the bytes past `arrived` could all have left at MIN_RATE, counted from the last proof that bytes arrived.
    drained_by: tokio::time::Instant,
    // Bytes the stream took, and how many of them the server is known to have got.
    written: u64,
    arrived: u64,
    // The packets past `arrived`, oldest first: the newest msg_id each carried, and `written` at its end.
    unproven: VecDeque<(i64, u64)>,
    // The newest msg_id known to have arrived, or the last one sent before this connection: a proof about one up
    // to it says nothing new.
    arrived_id: i64,
}

impl Writer {
    pub(crate) fn begin(&mut self) {
        self.buf.clear();
        self.buf.resize(self.room + Framing::ROOM, 0);
    }

    pub(crate) async fn finish(&mut self) -> Result<()> {
        let start = self.framing.frame_after(&mut self.buf, self.room);
        if let Some(encrypt) = &mut self.encrypt {
            encrypt.apply(&mut self.buf[start..]);
        }
        #[cfg(feature = "websocket")]
        {
            // A WebSocket message goes out whole, so it gets the time for all of it.
            let len = self.buf.len() - start;
            let deadline = stall_deadline(self.drained_by) + at_min_rate(len as u64);
            if let WriteHalf::WebSocket(half) = &mut self.half {
                tokio::time::timeout_at(deadline, half.send_in_place(&mut self.buf, start))
                    .await
                    .map_err(stalled)??;
                self.written += len as u64;
                self.drained_by = taken(self.drained_by, len);
                return Ok(());
            }
        }
        let mut wire = match &mut self.records {
            Some(records) => records.wrap(&self.buf[start..]),
            None => &self.buf[start..],
        };
        // A slow link frees room in the socket's buffers a little at a time, and Linux wakes a blocked writer only
        // once about a third of its buffer is free: so each write gets until the bytes not yet known to have arrived
        // could have left at MIN_RATE, then WRITE_STALL more.
        while !wire.is_empty() {
            match tokio::time::timeout_at(stall_deadline(self.drained_by), self.half.write(wire)).await {
                Ok(Ok(0)) => return Err(io::Error::from(io::ErrorKind::WriteZero).into()),
                Ok(Ok(n)) => {
                    self.written += n as u64;
                    self.drained_by = taken(self.drained_by, n);
                    wire = &wire[n..];
                }
                Ok(Err(e)) => return Err(e.into()),
                Err(elapsed) => return Err(stalled(elapsed)),
            }
        }
        // A boxed stream may buffer (TLS does, and so may a ConnectionFactory's); TCP's flush is a no-op.
        tokio::time::timeout_at(stall_deadline(self.drained_by), self.half.flush()).await.map_err(stalled)??;
        Ok(())
    }

    /// When the bytes not yet known to have reached the server could all have got there at MIN_RATE, counted from
    /// the last proof that bytes arrived: the server can't answer the last request before then.
    pub(crate) fn drained_by(&self) -> tokio::time::Instant {
        self.drained_by
    }

    /// Bytes the stream took that the server isn't known to have got.
    pub(crate) fn backlog(&self) -> u64 {
        self.written - self.arrived
    }

    /// Notes that the packet just finished carried msg_ids up to `last`, all newer than the packets before it had.
    pub(crate) fn sent(&mut self, last: i64) {
        self.unproven.push_back((last, self.written));
    }

    /// Msg_ids up to `last` went out on an earlier connection: the server referring to one proves nothing here.
    pub(crate) fn sent_before(&mut self, last: i64) {
        self.arrived_id = last;
    }

    /// The server referred to `msg_id`, so it got the packet that carried it, and every packet written before that
    /// one on this stream. What is left of the backlog counts from now.
    pub(crate) fn arrived(&mut self, msg_id: i64) {
        if msg_id <= self.arrived_id {
            return;
        }
        let mut end = None;
        while let Some((last, at)) = self.unproven.pop_front() {
            self.arrived_id = last;
            end = Some(at);
            if last >= msg_id {
                break;
            }
        }
        if let Some(end) = end {
            self.arrived = end;
            self.drained_by = tokio::time::Instant::now() + at_min_rate(self.backlog());
        }
    }

    pub(crate) async fn send(&mut self, payload: &[u8]) -> Result<()> {
        self.begin();
        self.buf.extend_from_slice(payload);
        self.finish().await
    }

    /// Completes when the stream has control frames to send: a WebSocket's answers to pings. Never on other streams.
    /// The future holds the signal alone, not the writer, which isn't `Sync`, so the session task stays `Send`.
    pub(crate) fn control_ready(&self) -> impl Future<Output = ()> {
        let signal = self.control_signal();
        async move {
            match signal {
                Some(signal) => signal.notified().await,
                None => std::future::pending().await,
            }
        }
    }

    fn control_signal(&self) -> Option<&Notify> {
        #[cfg(feature = "websocket")]
        if let WriteHalf::WebSocket(half) = &self.half {
            return Some(half.control_signal());
        }
        None
    }

    /// Sends those control frames with no packet, so an idle connection still answers pings; a no-op off WebSocket.
    pub(crate) async fn flush_control(&mut self) -> Result<()> {
        #[cfg(feature = "websocket")]
        if let WriteHalf::WebSocket(half) = &mut self.half {
            half.flush_control().await?;
        }
        Ok(())
    }
}

/// How long `n` bytes take at MIN_RATE.
fn at_min_rate(n: u64) -> Duration {
    Duration::from_nanos(n.saturating_mul(1_000_000_000) / MIN_RATE)
}

/// `drained_by` once the stream took `n` more bytes now.
fn taken(drained_by: tokio::time::Instant, n: usize) -> tokio::time::Instant {
    drained_by.max(tokio::time::Instant::now()) + at_min_rate(n as u64)
}

/// The latest a write or flush may still move a byte: WRITE_STALL after the bytes not yet known to have arrived
/// could have left.
fn stall_deadline(drained_by: tokio::time::Instant) -> tokio::time::Instant {
    drained_by.max(tokio::time::Instant::now()) + WRITE_STALL
}

fn stalled(_: tokio::time::error::Elapsed) -> Error {
    io::Error::new(io::ErrorKind::TimedOut, "the peer stopped taking bytes").into()
}

#[cfg(test)]
mod tests {
    use tokio::net::TcpListener;

    use super::*;

    fn full() -> Options {
        Options { transport: Transport::Full, ..Options::default() }
    }

    #[cfg(feature = "websocket")]
    #[tokio::test]
    async fn websocket_refuses_mtproxy_and_full() {
        // A data center with no WebSocket name: getting past the refusal would fail differently.
        let dc = Dc { id: 9, addr: "127.0.0.1:9".parse().unwrap(), test: false, media: false };
        let secret = "00".repeat(16).parse().unwrap();
        let mtproxy = Proxy::MtProxy { host: "127.0.0.1".into(), port: 9, secret };
        let websocket = Options { websocket: true, ..Options::default() };
        let refused = [
            Options { proxy: Some(mtproxy), ..websocket.clone() },
            Options { transport: Transport::Full, ..websocket.clone() },
        ];
        for options in refused {
            let result = Connection::connect(&dc, &options).await;
            assert!(matches!(result, Err(Error::InvalidArgument(_))), "{options:?}");
        }
        assert!(matches!(Connection::connect(&dc, &websocket).await, Err(Error::InvalidDc(9))));
    }

    #[tokio::test]
    async fn full_with_obfuscation_is_refused() {
        // Nothing listens here: the refusal has to come before any connection is tried.
        let dc = Dc { id: 2, addr: "127.0.0.1:9".parse().unwrap(), test: false, media: false };
        let secret = "00".repeat(16).parse().unwrap();
        let mtproxy = Proxy::MtProxy { host: "127.0.0.1".into(), port: 9, secret };
        for options in [Options { obfuscated: true, ..full() }, Options { proxy: Some(mtproxy), ..full() }] {
            let refused = Connection::connect(&dc, &options).await;
            assert!(matches!(refused, Err(Error::InvalidArgument(_))), "{options:?}");
        }
    }

    /// A connection over `link`, which has to be the only one the options open.
    async fn connected(link: slow_link::SlowLink) -> Connection {
        let link = std::sync::Mutex::new(Some(link));
        let options = Options::new().transport(Transport::Intermediate).connection_factory(move |_: SocketAddr| {
            let link = link.lock().unwrap().take();
            async move { link.ok_or_else(|| io::Error::other("one connection only")) }
        });
        let dc = Dc { id: 2, addr: "127.0.0.1:9".parse().unwrap(), test: false, media: false };
        Connection::connect(&dc, &options).await.unwrap()
    }

    #[tokio::test(start_paused = true)]
    async fn a_slow_link_that_wakes_its_writer_late_still_gets_every_packet_out() {
        // 1 MiB of room that drains at MIN_RATE; a writer that found it full waits for a third of it, as on Linux.
        let (link, _far) = slow_link::SlowLink::new(1 << 20, (1 << 20) / 3, MIN_RATE as usize);
        let mut connection = connected(link).await;
        let start = tokio::time::Instant::now();
        for _ in 0..2 {
            connection.send(&vec![0; 1 << 20]).await.unwrap();
        }
        // Each packet waited about 43 s for room, while bytes kept moving.
        assert!(start.elapsed() > WRITE_STALL * 2, "{:?}", start.elapsed());
    }

    #[tokio::test(start_paused = true)]
    async fn a_write_the_peer_takes_nothing_of_fails_after_the_stall() {
        // Room for the transport's tag and a few bytes more, and nothing ever drains, like a peer that vanished.
        let (link, _far) = slow_link::SlowLink::new(64, 1, 0);
        let mut connection = connected(link).await;
        let (start, packet) = (tokio::time::Instant::now(), vec![0; 1 << 20]);
        // Bounded from outside too, so a write left unbounded fails here instead of hanging the paused clock.
        let sending = tokio::time::timeout(Duration::from_secs(600), connection.send(&packet));
        let e = sending.await.expect("the write was never bounded").unwrap_err();
        assert!(matches!(&e, Error::Io(err) if err.kind() == io::ErrorKind::TimedOut), "{e}");
        // The 60 bytes it took could need 7 ms at MIN_RATE, then WRITE_STALL.
        let elapsed = start.elapsed();
        assert!((WRITE_STALL..WRITE_STALL + Duration::from_secs(1)).contains(&elapsed), "{elapsed:?}");
    }

    #[tokio::test(start_paused = true)]
    async fn a_flush_that_never_ends_fails_once_the_bytes_could_have_left() {
        // Takes everything at once and then never finishes a flush, as a stream that can't get its buffer out; the
        // one flush that completes is the connect's.
        let (link, _far) = slow_link::SlowLink::new(4 << 20, 1, 0);
        let mut connection = connected(link.flushes(1)).await;
        let (start, packet) = (tokio::time::Instant::now(), vec![0; 1 << 20]);
        let sending = tokio::time::timeout(Duration::from_secs(600), connection.send(&packet));
        let e = sending.await.expect("the flush was never bounded").unwrap_err();
        assert!(matches!(&e, Error::Io(err) if err.kind() == io::ErrorKind::TimedOut), "{e}");
        // 1 MiB at MIN_RATE is 128 s, then WRITE_STALL.
        let least = Duration::from_secs(128) + WRITE_STALL;
        assert!((least..least + Duration::from_secs(1)).contains(&start.elapsed()), "{:?}", start.elapsed());
    }

    #[tokio::test(start_paused = true)]
    async fn the_server_referring_to_a_packet_proves_it_and_every_one_before_it_arrived() {
        let (link, _far) = slow_link::SlowLink::new(4 << 20, 1, 0);
        let mut connection = connected(link).await;
        let w = &mut connection.writer;
        w.sent_before(5);
        // Three packets of the same size, carrying msg_ids up to 10, 20 and 30.
        for last in [10, 20, 30] {
            w.send(&[0; 1020]).await.unwrap();
            w.sent(last);
        }
        let all = w.backlog();
        // A msg_id from before this connection proves nothing about it.
        w.arrived(3);
        assert_eq!(w.backlog(), all);
        // An answer to 13, one of the second packet's messages: it arrived, and the first, written before it.
        w.arrived(13);
        assert_eq!(w.backlog(), all / 3);
        assert_eq!(w.drained_by(), tokio::time::Instant::now() + at_min_rate(all / 3));
        // The first packet's answer coming later, out of order, adds nothing.
        w.arrived(8);
        assert_eq!(w.backlog(), all / 3);
        w.arrived(30);
        assert_eq!(w.backlog(), 0);
        assert_eq!(w.drained_by(), tokio::time::Instant::now());
    }

    #[tokio::test]
    async fn full_sends_no_preamble_and_numbers_its_packets() {
        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let dc = Dc { id: 2, addr: listener.local_addr().unwrap(), test: false, media: false };
        // A server that reads whole full packets from the very first byte and sends each one back.
        let server = tokio::spawn(async move {
            let (mut stream, _) = listener.accept().await.unwrap();
            let (mut incoming, mut outgoing) = (Framing::new(Transport::Full), Framing::new(Transport::Full));
            let mut buf = RecvBuf::default();
            let mut got = Vec::new();
            while got.len() < 2 {
                if let Some(packet) = incoming.decode(&mut buf).unwrap() {
                    got.push(packet);
                } else {
                    assert!(stream.read_buf(buf.make_room()).await.unwrap() > 0);
                }
            }
            for packet in &got {
                let mut frame = vec![0; Framing::ROOM];
                frame.extend_from_slice(packet);
                let start = outgoing.frame(&mut frame);
                stream.write_all(&frame[start..]).await.unwrap();
            }
            got
        });
        let mut connection = Connection::connect(&dc, &full()).await.unwrap();
        connection.send(b"abcd1234").await.unwrap();
        connection.send(b"efgh5678").await.unwrap();
        assert_eq!(connection.recv().await.unwrap(), b"abcd1234");
        assert_eq!(connection.recv().await.unwrap(), b"efgh5678");
        assert_eq!(server.await.unwrap(), [b"abcd1234".to_vec(), b"efgh5678".to_vec()]);
    }

    /// Reads the intermediate tag and one packet, then sends the packet back.
    async fn echo_one(stream: &mut (impl AsyncRead + AsyncWrite + Unpin)) -> [u8; 4] {
        let (mut tag, mut len) = ([0; 4], [0; 4]);
        stream.read_exact(&mut tag).await.unwrap();
        stream.read_exact(&mut len).await.unwrap();
        let mut payload = vec![0; u32::from_le_bytes(len) as usize];
        stream.read_exact(&mut payload).await.unwrap();
        stream.write_all(&len).await.unwrap();
        stream.write_all(&payload).await.unwrap();
        tag
    }

    /// A factory that hands out one end of an in-memory pipe, never a socket, and records what it was asked for.
    fn piped() -> (Options, tokio::io::DuplexStream, Arc<std::sync::Mutex<Vec<SocketAddr>>>) {
        let (ours, theirs) = tokio::io::duplex(1 << 16);
        let (dialed, end) = (Arc::new(std::sync::Mutex::new(Vec::new())), std::sync::Mutex::new(Some(ours)));
        let seen = dialed.clone();
        let factory = move |addr: SocketAddr| {
            seen.lock().unwrap().push(addr);
            let end = end.lock().unwrap().take();
            async move { end.ok_or_else(|| io::Error::other("dialed twice")) }
        };
        (Options { connection_factory: Some(Arc::new(factory)), ..Options::default() }, theirs, dialed)
    }

    #[tokio::test]
    async fn custom_connector_carries_the_handshake() {
        let dc = Dc { id: 2, addr: "149.154.167.51:443".parse().unwrap(), test: false, media: false };
        let (options, mut server, dialed) = piped();
        let server = tokio::spawn(async move { echo_one(&mut server).await });
        let mut connection = Connection::connect(&dc, &options).await.unwrap();
        connection.send(b"abcd1234").await.unwrap();
        assert_eq!(connection.recv().await.unwrap(), b"abcd1234");
        assert_eq!((server.await.unwrap(), dialed.lock().unwrap().clone()), ([0xee; 4], vec![dc.addr]));
    }

    #[tokio::test]
    async fn proxy_runs_over_connector() {
        let dc = Dc { id: 2, addr: "149.154.167.51:443".parse().unwrap(), test: false, media: false };
        let (options, mut server, dialed) = piped();
        let proxy = Proxy::Http { host: "127.0.0.1".into(), port: 8080, auth: None };
        let options = Options { proxy: Some(proxy), ..options };
        let server = tokio::spawn(async move {
            let mut head = Vec::new();
            while !head.ends_with(b"\r\n\r\n") {
                head.push(server.read_u8().await.unwrap());
            }
            server.write_all(b"HTTP/1.1 200 Connection established\r\n\r\n").await.unwrap();
            (head, echo_one(&mut server).await)
        });
        let mut connection = Connection::connect(&dc, &options).await.unwrap();
        connection.send(b"abcd1234").await.unwrap();
        assert_eq!(connection.recv().await.unwrap(), b"abcd1234");
        let (head, tag) = server.await.unwrap();
        assert!(head.starts_with(b"CONNECT 149.154.167.51:443 "), "{}", String::from_utf8_lossy(&head));
        // The factory is asked for the proxy; the data center is reached through it.
        assert_eq!((tag, dialed.lock().unwrap().clone()), ([0xee; 4], vec!["127.0.0.1:8080".parse().unwrap()]));
    }

    #[tokio::test]
    async fn every_proxy_address_is_tried() {
        let dc = Dc { id: 2, addr: "149.154.167.51:443".parse().unwrap(), test: false, media: false };
        let dialed = Arc::new(std::sync::Mutex::new(Vec::new()));
        let seen = dialed.clone();
        // "localhost" may give an IPv6 address first; only an IPv4 one opens, onto a pipe nobody reads.
        let factory = move |addr: SocketAddr| {
            seen.lock().unwrap().push(addr);
            async move {
                match addr.is_ipv4() {
                    true => Ok(tokio::io::duplex(64).0),
                    false => Err(io::Error::new(io::ErrorKind::ConnectionRefused, "no IPv6 here")),
                }
            }
        };
        let proxy = Proxy::Http { host: "localhost".into(), port: 8080, auth: None };
        let options = Options { proxy: Some(proxy), connection_factory: Some(Arc::new(factory)), ..Options::default() };
        assert!(Connection::connect(&dc, &options).await.is_err());
        // Dialing stopped at the first address that opened, however the host resolved.
        assert!(dialed.lock().unwrap().last().is_some_and(SocketAddr::is_ipv4), "{:?}", dialed.lock().unwrap());
    }

    #[tokio::test]
    async fn a_connector_error_fails_connect() {
        let dc = Dc { id: 2, addr: "149.154.167.51:443".parse().unwrap(), test: false, media: false };
        let refuse = |_: SocketAddr| async {
            Err::<tokio::io::DuplexStream, _>(io::Error::new(io::ErrorKind::ConnectionRefused, "no route"))
        };
        let options = Options { connection_factory: Some(Arc::new(refuse)), ..Options::default() };
        let result = Connection::connect(&dc, &options).await;
        assert!(
            matches!(&result, Err(Error::Io(e)) if e.kind() == io::ErrorKind::ConnectionRefused),
            "{:?}",
            result.err()
        );
        assert_eq!(format!("{:?}", options.connection_factory.unwrap()), "ConnectionFactory");
    }

    #[tokio::test]
    async fn options_build_from_new_and_setters() {
        let options = Options::new();
        assert_eq!(
            (options.transport, options.obfuscated, options.updates_capacity),
            (Transport::Intermediate, false, 1024)
        );
        assert_eq!(options.request_timeout, Duration::from_secs(30));
        assert!(options.proxy.is_none() && options.connection_factory.is_none() && !options.no_updates);
        let dc = Dc { id: 2, addr: "149.154.167.51:443".parse().unwrap(), test: false, media: false };
        let refuse = |_: SocketAddr| async {
            Err::<tokio::io::DuplexStream, _>(io::Error::new(io::ErrorKind::ConnectionRefused, "no route"))
        };
        // An already shared factory can be passed in.
        let shared: Arc<dyn ConnectionFactory> = Arc::new(refuse);
        let result = Connection::connect(&dc, &Options::new().connection_factory(Arc::clone(&shared))).await;
        assert!(matches!(&result, Err(Error::Io(e)) if e.kind() == io::ErrorKind::ConnectionRefused));
        // The full transport refuses obfuscation before anything is dialed.
        let full = Options::new().transport(Transport::Full).obfuscated(true).connection_factory(refuse);
        assert!(matches!(Connection::connect(&dc, &full).await, Err(Error::InvalidArgument(_))));
    }
}