Skip to main content

kermit_proto/
server.rs

1//! The Kermit server state machine: the calculator is the client and we
2//! are the "disk drive" it sends to and gets from, as the 38G, 39G and 40G
3//! expect (wiki: protocols/aplet-transfer).
4//!
5//! The calculator opens every transaction: an I packet (parameters only),
6//! an R packet (it wants a file; the caller decides, [`Server::serve`] or
7//! [`Server::refuse`]) or an S packet (it sends files, which arrive as
8//! [`ServerEvent::Received`]). Between transactions the server waits
9//! without a deadline. Generic commands (G) are refused with an E packet.
10//!
11//! The seam is the client's: [`Server::handle_input`],
12//! [`Server::handle_timeout`], [`Server::poll_output`],
13//! [`Server::poll_event`] and [`Server::next_timeout`], each taking the
14//! caller's `now`.
15
16use crate::time::{Duration, Instant};
17use std::collections::VecDeque;
18
19use crate::client::{Error, OutgoingFile};
20use crate::codec::{BlockCheck, CR, Deframer, FrameError, Framing, Packet, parse_frame, unchar};
21use crate::params::{InitParams, Negotiated, negotiate};
22use crate::prefix::{self, Quoting};
23
24/// Tunables of a [`Server`].
25///
26/// Non-exhaustive: start from [`ServerConfig::default`] and set the fields
27/// you need.
28#[derive(Clone, Debug)]
29#[non_exhaustive]
30pub struct ServerConfig {
31    /// Block check we accept in our answer to the client's Send-Init
32    /// (default type 3; the client's own choice wins when it asks for
33    /// less).
34    pub block_check: BlockCheck,
35    /// `true` (default): QBIN `Y`, no 8th-bit prefixing unless the client
36    /// asks; `false`: we ask for it with `&`.
37    pub eight_bit_clean: bool,
38    /// Inside a transaction: how long we wait for the client's next packet
39    /// before we resend (or NAK) (default 10 s, the 38G's own TIME).
40    pub timeout: Duration,
41    /// Resends (or NAKs) per packet before the transaction fails (default 5).
42    pub retries: u32,
43    /// Delay before each packet we send in reply to input (default 0).
44    pub packet_pause: Duration,
45    /// Most decoded data bytes accepted in one receive transaction; more
46    /// fails it with [`Error::TooLarge`] and an E packet. Default 4 MiB;
47    /// `None` means no limit.
48    pub max_size: Option<usize>,
49}
50
51impl Default for ServerConfig {
52    fn default() -> Self {
53        ServerConfig {
54            block_check: BlockCheck::Type3,
55            eight_bit_clean: true,
56            timeout: Duration::from_secs(10),
57            retries: 5,
58            packet_pause: Duration::ZERO,
59            max_size: Some(4 << 20),
60        }
61    }
62}
63
64/// Something that happened on the server's side of the link.
65#[derive(Clone, Debug, PartialEq, Eq)]
66#[non_exhaustive]
67pub enum ServerEvent {
68    /// The client asks for a file (R). Answer with [`Server::serve`] or
69    /// [`Server::refuse`]; the server waits for the answer.
70    Request {
71        /// The file name, decoded.
72        name: Vec<u8>,
73    },
74    /// A file starts: one we serve (the name from the client's ACK to F,
75    /// else ours) or one the client sends (its F packet).
76    FileStart {
77        /// File name.
78        name: Vec<u8>,
79        /// `true` when we send it.
80        sending: bool,
81    },
82    /// Bytes of the current file acknowledged (send) or received.
83    Progress {
84        /// Bytes so far.
85        done: u64,
86        /// The file's size when we send it; `None` when receiving.
87        total: Option<u64>,
88    },
89    /// A file the client sent is complete.
90    Received {
91        /// Its name (the F packet).
92        name: Vec<u8>,
93        /// Its bytes.
94        data: Vec<u8>,
95    },
96    /// The client discarded the file it was sending (Z with `D`).
97    Discarded {
98        /// Its name.
99        name: Vec<u8>,
100    },
101    /// The file we served is acknowledged to its end (its Z).
102    Sent {
103        /// Its name.
104        name: Vec<u8>,
105    },
106    /// An E packet from the client, with its decoded text. Ends a running
107    /// transaction; also the client's answer to [`Server::refuse`].
108    Remote(Vec<u8>),
109    /// A transaction failed on our side (timeout, protocol, too large,
110    /// cancelled); an E packet went out where one makes sense.
111    Error(Error),
112    /// A transaction ended normally (its B acknowledged).
113    Done,
114}
115
116/// Why [`Server::serve`] or [`Server::refuse`] was refused: no request is
117/// waiting for an answer (for [`Server::reject`]: no file is being
118/// received).
119#[derive(Clone, Copy, Debug, PartialEq, Eq)]
120pub struct NoRequest;
121
122impl std::fmt::Display for NoRequest {
123    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
124        f.write_str("no file request is waiting for an answer")
125    }
126}
127
128impl std::error::Error for NoRequest {}
129
130#[derive(Clone, Copy, Debug, PartialEq, Eq)]
131enum Step {
132    Init,
133    File,
134    Data { chunk: usize },
135    Eof,
136    Break,
137}
138
139#[derive(Debug)]
140struct Sending {
141    file: OutgoingFile,
142    pos: usize,
143    step: Step,
144}
145
146#[derive(Debug)]
147enum Phase {
148    /// Between transactions.
149    Idle,
150    /// An R arrived; the caller has not answered yet.
151    Requested,
152    /// We send the requested file; `self.seq` is the packet awaiting its ACK.
153    Send(Sending),
154    /// The client sends; `self.seq` is the packet expected.
155    Receive {
156        name: Option<Vec<u8>>,
157        data: Vec<u8>,
158    },
159}
160
161/// Sans-IO Kermit server. See the module documentation.
162#[derive(Debug)]
163pub struct Server {
164    config: ServerConfig,
165    ours: InitParams,
166    deframer: Deframer,
167    phase: Phase,
168    neg: Option<Negotiated>,
169    seq: u8,
170    /// The packet to resend on a timeout or NAK (send), or on a duplicate
171    /// of the packet it answered (receive and between transactions).
172    last_sent: Vec<u8>,
173    /// Between transactions: the seq and type of the packet `last_sent`
174    /// answered, so a retransmission of it gets the same answer.
175    answered: Option<(u8, u8)>,
176    queue: VecDeque<(Instant, Vec<u8>)>,
177    events: VecDeque<ServerEvent>,
178    deadline: Option<Instant>,
179    retries: u32,
180    received: usize,
181}
182
183impl Server {
184    /// New server, waiting for the client's first packet.
185    pub fn new(config: ServerConfig) -> Self {
186        let ours = InitParams {
187            maxl: 94,
188            time: config.timeout.as_secs().clamp(1, 94) as u8,
189            npad: 0,
190            padc: 0,
191            eol: CR,
192            qctl: b'#',
193            qbin: if config.eight_bit_clean { b'Y' } else { b'&' },
194            chkt: config.block_check.to_char(),
195            rept: b' ',
196        };
197        Server {
198            config,
199            ours,
200            deframer: Deframer::new(),
201            phase: Phase::Idle,
202            neg: None,
203            seq: 0,
204            last_sent: Vec::new(),
205            answered: None,
206            queue: VecDeque::new(),
207            events: VecDeque::new(),
208            deadline: None,
209            retries: 0,
210            received: 0,
211        }
212    }
213
214    /// Our Send-Init parameters (what we answer an I or S with).
215    pub fn params(&self) -> InitParams {
216        self.ours
217    }
218
219    /// Feed bytes read from the link.
220    pub fn handle_input(&mut self, now: Instant, bytes: &[u8]) {
221        self.deframer.push(bytes);
222        while let Some(frame) = self.deframer.next_frame() {
223            let kind = frame.get(3).copied();
224            let check = match (&self.phase, self.neg) {
225                (Phase::Receive { .. }, Some(n)) if kind != Some(b'S') => n.check,
226                (Phase::Send(s), Some(n)) if s.step != Step::Init => n.check,
227                _ => BlockCheck::Type1,
228            };
229            let mut parsed = parse_frame(&frame, check);
230            if let (Phase::Idle, Err(FrameError::BadCheck), Some(n)) =
231                (&self.phase, &parsed, self.neg)
232            {
233                // A retransmission of the last packet of a transaction that
234                // ran with another block check (the B after a CRC receive).
235                parsed = parse_frame(&frame, n.check);
236            }
237            // A SEQ byte outside `tochar(0..=63)` (below space, or above
238            // `_`) is no packet to answer: `parse_frame` would fold it into
239            // 0..=63, and the answer would carry a seq the client never sent.
240            if frame.get(2).is_some_and(|c| !(32..=95).contains(c)) {
241                parsed = Err(FrameError::BadLength);
242            }
243            let raw_seq = frame.get(2).map(|&c| unchar(c));
244            match self.phase {
245                Phase::Idle => self.on_idle(now, parsed),
246                Phase::Requested => self.on_requested(now, parsed),
247                Phase::Send(_) => self.on_send(now, parsed, raw_seq),
248                Phase::Receive { .. } => self.on_receive(now, parsed),
249            }
250        }
251    }
252
253    /// Call when the time from [`Server::next_timeout`] has passed.
254    pub fn handle_timeout(&mut self, now: Instant) {
255        let Some(d) = self.deadline else { return };
256        if now < d {
257            return;
258        }
259        self.deadline = None;
260        match self.phase {
261            Phase::Receive { .. } => {
262                let nak = self.nak();
263                self.retry_with(now, nak);
264            }
265            Phase::Send(_) => {
266                let bytes = self.last_sent.clone();
267                self.retry_with(now, bytes);
268            }
269            Phase::Idle | Phase::Requested => {}
270        }
271    }
272
273    /// Next packet to write (one whole packet, as the client's). `None` if
274    /// nothing is due at `now`.
275    pub fn poll_output(&mut self, now: Instant) -> Option<Vec<u8>> {
276        match self.queue.front() {
277            Some((due, _)) if *due <= now => {}
278            _ => return None,
279        }
280        let (_, bytes) = self.queue.pop_front()?;
281        if matches!(self.phase, Phase::Send(_) | Phase::Receive { .. }) {
282            self.deadline = now.checked_add(self.config.timeout);
283        }
284        Some(bytes)
285    }
286
287    /// Next event, in order.
288    pub fn poll_event(&mut self) -> Option<ServerEvent> {
289        self.events.pop_front()
290    }
291
292    /// When the server wants to be called again: a queued packet becomes
293    /// due, or the client's next packet is late. `None` between
294    /// transactions: the server waits for the client as long as it takes.
295    pub fn next_timeout(&self) -> Option<Instant> {
296        let due = self.queue.iter().map(|(t, _)| *t).min();
297        match (due, self.deadline) {
298            (Some(a), Some(b)) => Some(a.min(b)),
299            (a, b) => a.or(b),
300        }
301    }
302
303    /// No transaction is running and no request waits for an answer.
304    pub fn is_idle(&self) -> bool {
305        matches!(self.phase, Phase::Idle)
306    }
307
308    /// A request ([`ServerEvent::Request`]) waits for [`Server::serve`] or
309    /// [`Server::refuse`].
310    pub fn is_requested(&self) -> bool {
311        matches!(self.phase, Phase::Requested)
312    }
313
314    /// Answer the waiting request with `file`: S, F, D.., Z, B. The F
315    /// carries `file.name`.
316    pub fn serve(&mut self, now: Instant, file: OutgoingFile) -> Result<(), NoRequest> {
317        if !self.is_requested() {
318            return Err(NoRequest);
319        }
320        self.neg = None;
321        self.seq = 0;
322        self.retries = 0;
323        self.answered = None;
324        self.phase = Phase::Send(Sending {
325            file,
326            pos: 0,
327            step: Step::Init,
328        });
329        let bytes =
330            Packet::new(0, b'S', self.ours.encode()).wire(BlockCheck::Type1, &Framing::default());
331        self.reply(now, bytes);
332        Ok(())
333    }
334
335    /// Refuse the waiting request with an E packet carrying `text` (e.g.
336    /// "File not found"). The calculator answers with its own E, which
337    /// comes as [`ServerEvent::Remote`].
338    pub fn refuse(&mut self, now: Instant, text: &[u8]) -> Result<(), NoRequest> {
339        if !self.is_requested() {
340            return Err(NoRequest);
341        }
342        let data = prefix::encode_all(text, &Quoting::default());
343        let bytes = Packet::new(self.seq, b'E', data).wire(BlockCheck::Type1, &Framing::default());
344        self.queue.push_back((self.paused(now), bytes));
345        self.go_idle();
346        Ok(())
347    }
348
349    /// Refuse the file being received, right after its
350    /// [`ServerEvent::FileStart`]: an E packet carrying `text` (in place of
351    /// the ACK to the F if that is not written yet) and
352    /// [`ServerEvent::Error`] ([`Error::Cancelled`]). Refused when no file
353    /// is being received.
354    pub fn reject(&mut self, now: Instant, text: &[u8]) -> Result<(), NoRequest> {
355        if !matches!(self.phase, Phase::Receive { .. }) {
356            return Err(NoRequest);
357        }
358        // The E answers the client's last packet (the F), by its number.
359        self.seq = (self.seq + 63) % 64;
360        self.fail(now, Error::Cancelled, Some(text));
361        Ok(())
362    }
363
364    /// Abort a running transaction with an E packet "Cancelled" and
365    /// [`ServerEvent::Error`] ([`Error::Cancelled`]); a waiting request is
366    /// refused the same way. Nothing between transactions.
367    pub fn cancel(&mut self, now: Instant) {
368        if !self.is_idle() {
369            self.fail(now, Error::Cancelled, Some(b"Cancelled"));
370        }
371    }
372
373    // ---- helpers ----
374
375    fn check(&self) -> BlockCheck {
376        self.neg.map_or(BlockCheck::Type1, |n| n.check)
377    }
378
379    fn framing(&self) -> Framing {
380        self.neg.map_or_else(Framing::default, |n| n.framing)
381    }
382
383    fn send_quoting(&self) -> Quoting {
384        self.neg.map_or_else(Quoting::default, |n| n.send)
385    }
386
387    fn recv_quoting(&self) -> Quoting {
388        self.neg.map_or_else(Quoting::default, |n| n.recv)
389    }
390
391    fn paused(&self, now: Instant) -> Instant {
392        now.checked_add(self.config.packet_pause).unwrap_or(now)
393    }
394
395    fn nak(&self) -> Vec<u8> {
396        Packet::new(self.seq, b'N', Vec::new()).wire(self.check(), &self.framing())
397    }
398
399    fn reply(&mut self, now: Instant, bytes: Vec<u8>) {
400        self.last_sent = bytes.clone();
401        self.deadline = None;
402        let due = self.paused(now);
403        self.queue.push_back((due, bytes));
404    }
405
406    fn reply_packet(&mut self, now: Instant, seq: u8, kind: u8, data: Vec<u8>) {
407        let bytes = Packet::new(seq, kind, data).wire(self.check(), &self.framing());
408        self.reply(now, bytes);
409    }
410
411    fn retry_with(&mut self, now: Instant, bytes: Vec<u8>) {
412        self.retries += 1;
413        if self.retries > self.config.retries {
414            self.fail(now, Error::Timeout, Some(b"Too many retries"));
415        } else {
416            self.deadline = None;
417            let due = self.paused(now);
418            self.queue.push_back((due, bytes));
419        }
420    }
421
422    fn go_idle(&mut self) {
423        self.phase = Phase::Idle;
424        self.deadline = None;
425        self.retries = 0;
426    }
427
428    /// The transaction ends with `event`; the last packet sent answers a
429    /// retransmission of the client's packet `(seq, kind)`.
430    fn finish(&mut self, event: ServerEvent, answered: Option<(u8, u8)>) {
431        self.events.push_back(event);
432        self.go_idle();
433        self.answered = answered;
434    }
435
436    fn fail(&mut self, now: Instant, err: Error, text: Option<&[u8]>) {
437        self.queue.clear();
438        if let Some(text) = text {
439            let data = prefix::encode_all(text, &self.send_quoting());
440            let bytes = Packet::new(self.seq, b'E', data).wire(self.check(), &self.framing());
441            self.queue.push_back((now, bytes));
442        }
443        self.finish(ServerEvent::Error(err), None);
444    }
445
446    fn protocol(&mut self, now: Instant, msg: String, text: &[u8]) {
447        self.fail(now, Error::Protocol(msg), Some(text));
448    }
449
450    fn remote(&mut self, data: &[u8], q: &Quoting) {
451        let text = prefix::decode(data, q).unwrap_or_else(|_| data.to_vec());
452        self.finish(ServerEvent::Remote(text), None);
453    }
454
455    fn decode(&mut self, now: Instant, data: &[u8], q: &Quoting) -> Option<Vec<u8>> {
456        match prefix::decode(data, q) {
457            Ok(v) => Some(v),
458            Err(e) => {
459                self.protocol(now, e.to_string(), b"Bad prefix");
460                None
461            }
462        }
463    }
464
465    // ---- between transactions ----
466
467    fn on_idle(&mut self, now: Instant, parsed: Result<Packet, FrameError>) {
468        let Ok(p) = parsed else { return };
469        if self.answered == Some((p.seq, p.kind)) && p.kind != b'E' && p.kind != b'N' {
470            // A retransmission of what we answered last: the same answer.
471            let due = self.paused(now);
472            self.queue.push_back((due, self.last_sent.clone()));
473            return;
474        }
475        match p.kind {
476            b'I' => {
477                self.neg = None;
478                let bytes = Packet::new(p.seq, b'Y', self.ours.encode())
479                    .wire(BlockCheck::Type1, &Framing::default());
480                self.reply(now, bytes);
481                self.answered = Some((p.seq, b'I'));
482            }
483            b'S' => {
484                let theirs = InitParams::decode(&p.data);
485                let n = negotiate(&self.ours, &theirs);
486                // The ACK to S uses type 1 but already the client's framing.
487                let bytes = Packet::new(p.seq, b'Y', self.ours.encode())
488                    .wire(BlockCheck::Type1, &n.framing);
489                self.reply(now, bytes);
490                self.neg = Some(n);
491                self.seq = (p.seq + 1) % 64;
492                self.retries = 0;
493                self.received = 0;
494                self.answered = None;
495                self.phase = Phase::Receive {
496                    name: None,
497                    data: Vec::new(),
498                };
499            }
500            b'R' => {
501                let Some(name) = self.decode(now, &p.data, &Quoting::default()) else {
502                    return;
503                };
504                self.neg = None;
505                self.seq = p.seq;
506                self.answered = None;
507                self.phase = Phase::Requested;
508                self.events.push_back(ServerEvent::Request { name });
509            }
510            b'E' => {
511                let text = prefix::decode(&p.data, &Quoting::default()).unwrap_or(p.data);
512                self.events.push_back(ServerEvent::Remote(text));
513            }
514            b'N' | b'Y' => {}
515            _ => {
516                // G (generic), C (host command) and the rest: not served.
517                let data = prefix::encode_all(b"Unimplemented", &Quoting::default());
518                let bytes =
519                    Packet::new(p.seq, b'E', data).wire(BlockCheck::Type1, &Framing::default());
520                self.reply(now, bytes);
521                self.answered = Some((p.seq, p.kind));
522            }
523        }
524    }
525
526    fn on_requested(&mut self, now: Instant, parsed: Result<Packet, FrameError>) {
527        let Ok(p) = parsed else { return };
528        match p.kind {
529            b'E' => {
530                let text = prefix::decode(&p.data, &Quoting::default()).unwrap_or(p.data);
531                self.finish(ServerEvent::Remote(text), None);
532            }
533            // The client gave up on its request and starts over.
534            b'I' | b'S' => {
535                self.go_idle();
536                self.on_idle(now, Ok(p));
537            }
538            // A retransmitted R (or anything else) waits for the caller.
539            _ => {}
540        }
541    }
542
543    // ---- receiving ----
544
545    fn on_receive(&mut self, now: Instant, parsed: Result<Packet, FrameError>) {
546        let n = self.seq;
547        let p = match parsed {
548            Ok(p) => p,
549            Err(FrameError::BadCheck) => {
550                let nak = self.nak();
551                self.retry_with(now, nak);
552                return;
553            }
554            Err(FrameError::BadLength) => return,
555        };
556        if p.kind == b'E' {
557            let q = self.recv_quoting();
558            self.remote(&p.data, &q);
559            return;
560        }
561        if p.seq != n {
562            if p.seq == (n + 63) % 64 && p.kind != b'N' {
563                // A duplicate (the 38G and 39G send their S twice): the
564                // same answer again, counted as a retry (only a new packet
565                // resets the count), so a peer replaying one packet cannot
566                // hold the transaction open.
567                let bytes = self.last_sent.clone();
568                self.retry_with(now, bytes);
569            }
570            return;
571        }
572        let q = self.recv_quoting();
573        match p.kind {
574            b'F' => {
575                let Some(name) = self.decode(now, &p.data, &q) else {
576                    return;
577                };
578                self.events.push_back(ServerEvent::FileStart {
579                    name: name.clone(),
580                    sending: false,
581                });
582                if let Phase::Receive { name: n, data } = &mut self.phase {
583                    *n = Some(name);
584                    data.clear();
585                }
586                // The ACK to F carries the name the file is stored under.
587                self.reply_packet(now, n, b'Y', p.data);
588            }
589            b'D' => {
590                let Some(chunk) = self.decode(now, &p.data, &q) else {
591                    return;
592                };
593                self.received = self.received.saturating_add(chunk.len());
594                if let Some(limit) = self.config.max_size
595                    && self.received > limit
596                {
597                    self.fail(now, Error::TooLarge { limit }, Some(b"Too large"));
598                    return;
599                }
600                let Phase::Receive {
601                    name: Some(_),
602                    data,
603                } = &mut self.phase
604                else {
605                    self.protocol(now, "D before F".to_string(), b"Unexpected packet");
606                    return;
607                };
608                data.extend_from_slice(&chunk);
609                let done = data.len() as u64;
610                self.events
611                    .push_back(ServerEvent::Progress { done, total: None });
612                self.reply_packet(now, n, b'Y', Vec::new());
613            }
614            b'Z' => {
615                let Some(flag) = self.decode(now, &p.data, &q) else {
616                    return;
617                };
618                let Phase::Receive { name, data } = &mut self.phase else {
619                    return;
620                };
621                let Some(name) = name.take() else {
622                    self.protocol(now, "Z before F".to_string(), b"Unexpected packet");
623                    return;
624                };
625                let data = std::mem::take(data);
626                self.events.push_back(if flag == b"D" {
627                    ServerEvent::Discarded { name }
628                } else {
629                    ServerEvent::Received { name, data }
630                });
631                self.reply_packet(now, n, b'Y', Vec::new());
632            }
633            b'A' | b'X' => self.reply_packet(now, n, b'Y', Vec::new()),
634            b'B' => {
635                if matches!(&self.phase, Phase::Receive { name: Some(_), .. }) {
636                    self.protocol(
637                        now,
638                        "B before the Z of the current file".to_string(),
639                        b"Unexpected B",
640                    );
641                    return;
642                }
643                self.reply_packet(now, n, b'Y', Vec::new());
644                self.finish(ServerEvent::Done, Some((n, b'B')));
645                return;
646            }
647            b'N' => return,
648            other => {
649                self.protocol(
650                    now,
651                    format!("unexpected packet {:?}", char::from(other)),
652                    b"Unexpected packet",
653                );
654                return;
655            }
656        }
657        self.seq = (n + 1) % 64;
658        self.retries = 0;
659    }
660
661    // ---- sending ----
662
663    fn on_send(&mut self, now: Instant, parsed: Result<Packet, FrameError>, raw_seq: Option<u8>) {
664        let n = self.seq;
665        let p = match parsed {
666            Ok(p) => p,
667            Err(FrameError::BadCheck) => {
668                if raw_seq == Some(n) {
669                    let bytes = self.last_sent.clone();
670                    self.retry_with(now, bytes);
671                }
672                return;
673            }
674            Err(FrameError::BadLength) => return,
675        };
676        match p.kind {
677            b'E' => {
678                let q = self.recv_quoting();
679                self.remote(&p.data, &q);
680            }
681            b'Y' if p.seq == n => {
682                let sent = std::mem::take(&mut self.last_sent);
683                self.queue.retain(|(_, b)| *b != sent);
684                self.last_sent = sent;
685                self.on_ack(now, &p.data);
686            }
687            b'N' if p.seq == (n + 1) % 64 => self.on_ack(now, &[]),
688            b'N' if p.seq == n => {
689                let bytes = self.last_sent.clone();
690                self.retry_with(now, bytes);
691            }
692            _ => {}
693        }
694    }
695
696    fn sending(&mut self) -> Option<&mut Sending> {
697        match &mut self.phase {
698            Phase::Send(s) => Some(s),
699            _ => None,
700        }
701    }
702
703    fn send_next(&mut self, now: Instant, kind: u8, data: Vec<u8>) {
704        self.seq = (self.seq + 1) % 64;
705        self.reply_packet(now, self.seq, kind, data);
706    }
707
708    fn max_data(&self) -> usize {
709        let maxl = self.neg.map_or(80, |n| usize::from(n.peer_maxl));
710        Packet::max_data(maxl, self.check())
711    }
712
713    fn on_ack(&mut self, now: Instant, data: &[u8]) {
714        self.retries = 0;
715        let Some(step) = self.sending().map(|s| s.step) else {
716            return;
717        };
718        match step {
719            Step::Init => {
720                let theirs = InitParams::decode(data);
721                self.neg = Some(negotiate(&self.ours, &theirs));
722                let max = self.max_data();
723                let q = self.send_quoting();
724                let Some(s) = self.sending() else { return };
725                let (name, used) = prefix::encode(&s.file.name, &q, max);
726                if used != s.file.name.len() {
727                    self.protocol(
728                        now,
729                        format!("file name does not fit in a packet of {max} data bytes"),
730                        b"File name too long",
731                    );
732                    return;
733                }
734                s.step = Step::File;
735                self.send_next(now, b'F', name);
736            }
737            Step::File => {
738                let name = if data.is_empty() {
739                    self.sending()
740                        .map(|s| s.file.name.clone())
741                        .unwrap_or_default()
742                } else {
743                    let q = self.recv_quoting();
744                    let Some(name) = self.decode(now, data, &q) else {
745                        return;
746                    };
747                    name
748                };
749                self.events.push_back(ServerEvent::FileStart {
750                    name,
751                    sending: true,
752                });
753                self.next_data(now);
754            }
755            Step::Data { chunk } => {
756                let Some(s) = self.sending() else { return };
757                s.pos += chunk;
758                let done = s.pos as u64;
759                let total = s.file.data.len() as u64;
760                self.events.push_back(ServerEvent::Progress {
761                    done,
762                    total: Some(total),
763                });
764                self.next_data(now);
765            }
766            Step::Eof => {
767                let Some(s) = self.sending() else { return };
768                s.step = Step::Break;
769                let name = s.file.name.clone();
770                self.events.push_back(ServerEvent::Sent { name });
771                self.send_next(now, b'B', Vec::new());
772            }
773            Step::Break => self.finish(ServerEvent::Done, None),
774        }
775    }
776
777    fn next_data(&mut self, now: Instant) {
778        let max = self.max_data();
779        let q = self.send_quoting();
780        let Some(s) = self.sending() else { return };
781        let rest = s.file.data.get(s.pos..).unwrap_or_default();
782        if rest.is_empty() {
783            s.step = Step::Eof;
784            self.send_next(now, b'Z', Vec::new());
785        } else {
786            let (enc, used) = prefix::encode(rest, &q, max);
787            s.step = Step::Data { chunk: used };
788            self.send_next(now, b'D', enc);
789        }
790    }
791}
792
793#[cfg(test)]
794#[allow(clippy::unwrap_used, clippy::expect_used)]
795pub(crate) mod test_support {
796    use super::*;
797    use crate::trace::{self, Direction};
798
799    /// Replay `text` at a fixed `now` against a new server: In lines are
800    /// fed to it, Out lines must match its output. `answer(name)` answers
801    /// each request: `Some(data)` serves it under that name, `None` refuses
802    /// it with "File not found". Returns the server and its events.
803    pub(crate) fn replay_server(
804        config: ServerConfig,
805        text: &str,
806        answer: &dyn Fn(&[u8]) -> Option<Vec<u8>>,
807    ) -> (Server, Vec<ServerEvent>) {
808        let now = Instant::now();
809        let mut s = Server::new(config);
810        let mut events = Vec::new();
811        for (i, (dir, bytes)) in trace::parse(text).unwrap().into_iter().enumerate() {
812            match dir {
813                Direction::Out => {
814                    let got = s.poll_output(now);
815                    assert_eq!(
816                        got.as_deref().map(trace::escape),
817                        Some(trace::escape(&bytes)),
818                        "trace entry {i}: expected output > {}",
819                        trace::escape(&bytes)
820                    );
821                }
822                Direction::In => s.handle_input(now, &bytes),
823            }
824            while let Some(e) = s.poll_event() {
825                if let ServerEvent::Request { name } = &e {
826                    match answer(name) {
827                        Some(data) => s
828                            .serve(
829                                now,
830                                OutgoingFile {
831                                    name: name.clone(),
832                                    data,
833                                },
834                            )
835                            .unwrap(),
836                        None => s.refuse(now, b"File not found").unwrap(),
837                    }
838                }
839                events.push(e);
840            }
841        }
842        let extra = s.poll_output(now);
843        assert_eq!(
844            extra.as_deref().map(trace::escape),
845            None,
846            "unexpected trailing output"
847        );
848        (s, events)
849    }
850}
851
852#[cfg(test)]
853#[allow(clippy::unwrap_used, clippy::expect_used)]
854mod tests {
855    use super::test_support::replay_server;
856    use super::*;
857    use crate::trace;
858
859    const T1: BlockCheck = BlockCheck::Type1;
860    const T3: BlockCheck = BlockCheck::Type3;
861    /// The 38G's and 39G's Send-Init (wiki: protocols/aplet-transfer).
862    const CALC: &[u8] = b"~* @-#Y3";
863    /// The calculator's ACK to our S.
864    const CALC_ACK: &[u8] = b"~& @-# 1";
865    /// Our params with the default config.
866    const OURS: &[u8] = b"~* @-#Y3 ";
867
868    fn wire(seq: u8, kind: u8, data: &[u8], check: BlockCheck) -> Vec<u8> {
869        Packet::new(seq, kind, data.to_vec())
870            .encode(check, &Framing::default())
871            .unwrap()
872    }
873
874    fn out(seq: u8, kind: u8, data: &[u8], check: BlockCheck) -> String {
875        format!("> {}\n", trace::escape(&wire(seq, kind, data, check)))
876    }
877
878    fn inp(seq: u8, kind: u8, data: &[u8], check: BlockCheck) -> String {
879        format!("< {}\n", trace::escape(&wire(seq, kind, data, check)))
880    }
881
882    fn none(_: &[u8]) -> Option<Vec<u8>> {
883        None
884    }
885
886    #[test]
887    fn our_params_encode() {
888        assert_eq!(Server::new(ServerConfig::default()).params().encode(), OURS);
889    }
890
891    #[test]
892    fn info_then_refused_request() {
893        let mut t = inp(0, b'I', CALC, T1) + &out(0, b'Y', OURS, T1);
894        // The calculator's I comes twice: the same answer twice.
895        t += &inp(0, b'I', CALC, T1);
896        t += &out(0, b'Y', OURS, T1);
897        t += &inp(0, b'R', b"HP38DIR.CUR", T1);
898        t += &out(0, b'E', b"File not found", T1);
899        t += &inp(0, b'E', b"Transfer Failed#M#J", T1);
900        let (s, ev) = replay_server(ServerConfig::default(), &t, &none);
901        assert_eq!(
902            ev,
903            vec![
904                ServerEvent::Request {
905                    name: b"HP38DIR.CUR".to_vec()
906                },
907                ServerEvent::Remote(b"Transfer Failed\r\n".to_vec()),
908            ]
909        );
910        assert!(s.is_idle());
911        assert_eq!(s.next_timeout(), None);
912    }
913
914    #[test]
915    fn serves_a_file() {
916        let mut t = inp(0, b'R', b"FUNCTION.000", T1);
917        t += &out(0, b'S', OURS, T1);
918        t += &inp(0, b'Y', CALC_ACK, T1);
919        t += &out(1, b'F', b"FUNCTION.000", T1);
920        t += &inp(1, b'Y', b"FUNCTION.000", T1);
921        t += &out(2, b'D', b"HP38BinB#H", T1);
922        t += &inp(2, b'Y', b"", T1);
923        t += &out(3, b'Z', b"", T1);
924        t += &inp(3, b'Y', b"", T1);
925        t += &out(4, b'B', b"", T1);
926        t += &inp(4, b'Y', b"", T1);
927        let answer = |_: &[u8]| Some(b"HP38BinB\x08".to_vec());
928        let (s, ev) = replay_server(ServerConfig::default(), &t, &answer);
929        let name = b"FUNCTION.000".to_vec();
930        assert_eq!(
931            ev,
932            vec![
933                ServerEvent::Request { name: name.clone() },
934                ServerEvent::FileStart {
935                    name: name.clone(),
936                    sending: true
937                },
938                ServerEvent::Progress {
939                    done: 9,
940                    total: Some(9)
941                },
942                ServerEvent::Sent { name },
943                ServerEvent::Done,
944            ]
945        );
946        assert!(s.is_idle());
947    }
948
949    #[test]
950    fn receives_a_file_with_crc_and_a_doubled_s() {
951        let mut t = inp(0, b'S', CALC, T1) + &out(0, b'Y', OURS, T1);
952        t += &inp(0, b'S', CALC, T1);
953        t += &out(0, b'Y', OURS, T1);
954        t += &inp(1, b'F', b"XYZ00000.000", T3);
955        t += &out(1, b'Y', b"XYZ00000.000", T3);
956        t += &inp(2, b'D', b"HP39BinB#CXYZ", T3);
957        t += &out(2, b'Y', b"", T3);
958        t += &inp(3, b'Z', b"", T3);
959        t += &out(3, b'Y', b"", T3);
960        t += &inp(4, b'B', b"", T3);
961        t += &out(4, b'Y', b"", T3);
962        // The B again (our ACK lost): the same ACK.
963        t += &inp(4, b'B', b"", T3);
964        t += &out(4, b'Y', b"", T3);
965        let (s, ev) = replay_server(ServerConfig::default(), &t, &none);
966        let name = b"XYZ00000.000".to_vec();
967        assert_eq!(
968            ev,
969            vec![
970                ServerEvent::FileStart {
971                    name: name.clone(),
972                    sending: false
973                },
974                ServerEvent::Progress {
975                    done: 12,
976                    total: None
977                },
978                ServerEvent::Received {
979                    name,
980                    data: b"HP39BinB\x03XYZ".to_vec()
981                },
982                ServerEvent::Done,
983            ]
984        );
985        assert!(s.is_idle());
986    }
987
988    #[test]
989    fn type1_when_asked() {
990        let cfg = ServerConfig {
991            block_check: T1,
992            ..ServerConfig::default()
993        };
994        let ours = b"~* @-#Y1 ";
995        let mut t = inp(0, b'S', CALC, T1) + &out(0, b'Y', ours, T1);
996        t += &inp(1, b'F', b"A.000", T1);
997        t += &out(1, b'Y', b"A.000", T1);
998        t += &inp(2, b'Z', b"D", T1);
999        t += &out(2, b'Y', b"", T1);
1000        t += &inp(3, b'B', b"", T1);
1001        t += &out(3, b'Y', b"", T1);
1002        let (_, ev) = replay_server(cfg, &t, &none);
1003        assert_eq!(
1004            ev,
1005            vec![
1006                ServerEvent::FileStart {
1007                    name: b"A.000".to_vec(),
1008                    sending: false
1009                },
1010                ServerEvent::Discarded {
1011                    name: b"A.000".to_vec()
1012                },
1013                ServerEvent::Done,
1014            ]
1015        );
1016    }
1017
1018    #[test]
1019    fn generic_commands_are_refused() {
1020        let t = inp(0, b'G', b"D", T1) + &out(0, b'E', b"Unimplemented", T1);
1021        let (s, ev) = replay_server(ServerConfig::default(), &t, &none);
1022        assert!(ev.is_empty());
1023        assert!(s.is_idle());
1024    }
1025
1026    #[test]
1027    fn calculator_error_ends_a_receive() {
1028        let mut t = inp(0, b'S', CALC, T1) + &out(0, b'Y', OURS, T1);
1029        t += &inp(1, b'E', b"Cancelled", T3);
1030        let (s, ev) = replay_server(ServerConfig::default(), &t, &none);
1031        assert_eq!(ev, vec![ServerEvent::Remote(b"Cancelled".to_vec())]);
1032        assert!(s.is_idle());
1033    }
1034
1035    /// A file refused at its F: an E with the F's number instead of the
1036    /// ACK, and the transaction is over.
1037    #[test]
1038    fn a_rejected_file_gets_an_e_instead_of_the_ack() {
1039        let now = Instant::now();
1040        let mut s = Server::new(ServerConfig::default());
1041        s.handle_input(now, &wire(0, b'S', CALC, T1));
1042        assert_eq!(s.poll_output(now), Some(wire(0, b'Y', OURS, T1)));
1043        s.handle_input(now, &wire(1, b'F', b"GAME.000", T3));
1044        assert_eq!(
1045            s.poll_event(),
1046            Some(ServerEvent::FileStart {
1047                name: b"GAME.000".to_vec(),
1048                sending: false
1049            })
1050        );
1051        s.reject(now, b"File exists").unwrap();
1052        assert_eq!(s.poll_output(now), Some(wire(1, b'E', b"File exists", T3)));
1053        assert_eq!(s.poll_output(now), None);
1054        assert_eq!(s.poll_event(), Some(ServerEvent::Error(Error::Cancelled)));
1055        assert!(s.is_idle());
1056        assert_eq!(s.reject(now, b"x"), Err(NoRequest));
1057    }
1058
1059    /// A client that replays its previous packet forever gets the same
1060    /// answer `retries` times, then the transaction ends with the retry
1061    /// error.
1062    #[test]
1063    fn a_replaying_client_runs_out_of_retries() {
1064        let now = Instant::now();
1065        let cfg = ServerConfig {
1066            retries: 2,
1067            ..ServerConfig::default()
1068        };
1069        let mut s = Server::new(cfg);
1070        s.handle_input(now, &wire(0, b'S', CALC, T1));
1071        assert_eq!(s.poll_output(now), Some(wire(0, b'Y', OURS, T1)));
1072        for _ in 0..2 {
1073            s.handle_input(now, &wire(0, b'S', CALC, T1));
1074            assert_eq!(s.poll_output(now), Some(wire(0, b'Y', OURS, T1)));
1075        }
1076        s.handle_input(now, &wire(0, b'S', CALC, T1));
1077        assert_eq!(
1078            s.poll_output(now),
1079            Some(wire(1, b'E', b"Too many retries", T3))
1080        );
1081        assert_eq!(s.poll_event(), Some(ServerEvent::Error(Error::Timeout)));
1082        assert!(s.is_idle());
1083    }
1084
1085    #[test]
1086    fn receive_timeouts_nak_then_fail() {
1087        let now = Instant::now();
1088        let cfg = ServerConfig {
1089            retries: 1,
1090            ..ServerConfig::default()
1091        };
1092        let mut s = Server::new(cfg);
1093        s.handle_input(now, &wire(0, b'S', CALC, T1));
1094        assert_eq!(s.poll_output(now), Some(wire(0, b'Y', OURS, T1)));
1095        let t1 = s.next_timeout().unwrap();
1096        assert_eq!(t1, now + Duration::from_secs(10));
1097        s.handle_timeout(t1);
1098        assert_eq!(s.poll_output(t1), Some(wire(1, b'N', b"", T3)));
1099        let t2 = s.next_timeout().unwrap();
1100        s.handle_timeout(t2);
1101        assert_eq!(
1102            s.poll_output(t2),
1103            Some(wire(1, b'E', b"Too many retries", T3))
1104        );
1105        assert_eq!(s.poll_event(), Some(ServerEvent::Error(Error::Timeout)));
1106        assert!(s.is_idle());
1107        assert_eq!(s.next_timeout(), None);
1108    }
1109
1110    #[test]
1111    fn send_resends_on_nak_and_timeout() {
1112        let now = Instant::now();
1113        let mut s = Server::new(ServerConfig::default());
1114        s.handle_input(now, &wire(0, b'R', b"A", T1));
1115        assert!(s.is_requested());
1116        assert_eq!(
1117            s.poll_event(),
1118            Some(ServerEvent::Request {
1119                name: b"A".to_vec()
1120            })
1121        );
1122        s.serve(
1123            now,
1124            OutgoingFile {
1125                name: b"A".to_vec(),
1126                data: b"x".to_vec(),
1127            },
1128        )
1129        .unwrap();
1130        let first = s.poll_output(now).unwrap();
1131        s.handle_input(now, &wire(0, b'N', b"", T1));
1132        assert_eq!(s.poll_output(now), Some(first.clone()));
1133        let t = s.next_timeout().unwrap();
1134        s.handle_timeout(t);
1135        assert_eq!(s.poll_output(t), Some(first));
1136        assert_eq!(
1137            s.serve(
1138                now,
1139                OutgoingFile {
1140                    name: vec![],
1141                    data: vec![]
1142                }
1143            ),
1144            Err(NoRequest)
1145        );
1146    }
1147
1148    #[test]
1149    fn cancel_while_requested() {
1150        let now = Instant::now();
1151        let mut s = Server::new(ServerConfig::default());
1152        s.handle_input(now, &wire(0, b'R', b"A", T1));
1153        s.cancel(now);
1154        assert_eq!(s.poll_output(now), Some(wire(0, b'E', b"Cancelled", T1)));
1155        assert_eq!(
1156            s.poll_event(),
1157            Some(ServerEvent::Request {
1158                name: b"A".to_vec()
1159            })
1160        );
1161        assert_eq!(s.poll_event(), Some(ServerEvent::Error(Error::Cancelled)));
1162        assert!(s.is_idle());
1163    }
1164
1165    #[test]
1166    fn a_seq_out_of_range_is_ignored() {
1167        let now = Instant::now();
1168        let mut s = Server::new(ServerConfig::default());
1169        for seq_byte in [0x1f_u8, 0x7e] {
1170            for kind in *b"SIR" {
1171                let mut frame = vec![crate::codec::SOH, crate::codec::tochar(3), seq_byte, kind];
1172                let chk = T1.compute(&frame[1..]);
1173                frame.extend_from_slice(&chk);
1174                frame.push(CR);
1175                s.handle_input(now, &frame);
1176            }
1177        }
1178        assert_eq!(s.poll_output(now), None);
1179        assert_eq!(s.poll_event(), None);
1180        assert!(s.is_idle());
1181    }
1182}