kermit-proto 0.12.1

Sans-IO Kermit client and server for HP calculators: the client for the Kermit servers of the 48 and 49, the server for the 38G, 39G and 40G
Documentation
# kermit-proto

A sans-IO Kermit client and server for HP calculators. The client (user
Kermit) talks to the Kermit server of an HP 48 or 49 series calculator: send
and get files, run host commands, list the directory, end server mode. The
server (`Server`) is the "disk drive" that the 38G, 39G and 40G send aplets
to and get them from. Both share the codec, the prefixing and the Send-Init
negotiation; this page describes the client, and the `Server` docs say
where the server differs.

The crate never touches a port, a clock or a file. The caller owns all three:
it reads and writes the link (a serial port, a TCP bridge to an emulator),
supplies the current `Instant` (see below) and loads or stores file contents.
`Client` is a pure state machine in between, so it runs unchanged on any
transport and is tested by replaying byte traces recorded against real
calculator ROMs.

Supported: short packets (up to 94 bytes), block checks 1, 2 and 3, control
prefixing, 8th-bit prefixing and repeat compression as negotiated in the
Send-Init exchange, and the server commands `R` (get), `S` (send), `C` (host
command), `G D` (directory), `G F` (finish), `G L` (logout) and `I` (info).
Not supported: long packets and sliding windows (the HP calculators use
neither); attribute packets are acknowledged and ignored.

## The seam

- `Client::start(now, command)` begins a transaction; the first packet is
  queued at once.
- `Client::handle_input(now, bytes)` feeds bytes read from the link, in any
  chunking.
- `Client::handle_timeout(now)` tells the client time has passed; call it when
  `Client::next_timeout()` is reached (it does nothing early).
- `Client::poll_output(now)` hands out the next packet to write: exactly one
  packet including padding and EOL.
  The transport must put it on the wire as one unit, without inter-byte
  gaps (see the HP notes below).
- `Client::poll_event()` yields events: `FileStart`, `Data`, `Progress`,
  `FileEnd`, `ServerText` and finally exactly one `Done` or `Error`.
- `Client::next_timeout()` is when the client wants to be called again; use it
  as the read timeout.

After `Done` or `Error` keep calling `poll_output` until it returns `None`: the
final ACK or an E packet may still be queued. After a receive the client
lingers briefly (`Config::linger`) to re-ACK a retransmitted `B` packet, in
case its final ACK was lost; keep driving it until `next_timeout()` is `None`,
or start the next command.

## Time and WebAssembly

The state machine never reads a clock; every call that needs the time takes
`now` from the caller. The type is `kermit_proto::time::Instant`: `std::time::Instant`
on every target except `wasm32`, where it is `web_time::Instant` from the
[`web-time`](https://crates.io/crates/web-time) crate, because
`std::time::Instant::now()` panics on `wasm32-unknown-unknown`. A wasm caller
creates it with `Instant::now()` from `web-time` (or `kermit_proto::time::Instant::now()`),
which reads `performance.now()` in the browser. `kermit_proto::time::Duration` is
`core::time::Duration` everywhere. Native callers use `std::time` as before.

## Driver loop

```rust,no_run
use std::io::{ErrorKind, Read, Write};
use std::net::TcpStream;
use std::time::{Duration, Instant};
use kermit_proto::{Client, Command, Config, Event};

fn main() -> std::io::Result<()> {
    let mut link = TcpStream::connect("localhost:4848")?;
    let mut client = Client::new(Config::default());
    client
        .start(Instant::now(), Command::Host(b"6 7 *".to_vec()))
        .map_err(std::io::Error::other)?;
    let mut finished = false;
    let mut buf = [0u8; 512];
    loop {
        let now = Instant::now();
        while let Some(packet) = client.poll_output(now) {
            // A whole packet per call; the link must not split it.
            link.write_all(&packet)?;
        }
        while let Some(event) = client.poll_event() {
            match event {
                Event::ServerText(text) => println!("{}", String::from_utf8_lossy(&text)),
                Event::Done | Event::Error(_) => finished = true,
                _ => {}
            }
        }
        let wait = match client.next_timeout() {
            Some(t) => t.saturating_duration_since(now),
            None if finished => break, // idle and nothing left to write
            None => Duration::from_millis(100),
        };
        link.set_read_timeout(Some(wait.max(Duration::from_millis(10))))?;
        match link.read(&mut buf) {
            Ok(0) => break,
            Ok(n) => client.handle_input(Instant::now(), &buf[..n]),
            Err(e) if matches!(e.kind(), ErrorKind::WouldBlock | ErrorKind::TimedOut) => {
                client.handle_timeout(Instant::now())
            }
            Err(e) => return Err(e),
        }
    }
    Ok(())
}
```

## HP calculator notes

- Each packet must reach the wire as one unit: inter-byte gaps overrun the
  HP's receiver. This is a requirement on the transport, not something
  `write_all` guarantees (it may split the buffer into several writes). On a
  TCP socket to an emulator, or a serial port whose driver buffers a whole
  packet, one `write_all` per packet is enough; otherwise buffer the packet
  and hand it to the port in one call.
- In server mode the HP periodically NAKs packet 0 while idle, so a stale NAK
  can be waiting right after connecting. Discard input for about 0.5 s after
  opening the link; the client also tolerates a stale NAK that slips through
  (`Config::nak_grace`).
- The HP drops a command packet that arrives right after the final ACK of the
  previous transaction; leave a short pause (about 200 ms) between
  transactions.
- Commands go out before any parameter exchange, so their data must fit in one
  packet under the default MAXL of 80 with block check 1; `Client::start`
  refuses longer ones.
- The HP runs a host command (`C`) when it receives it and cannot tell a
  resend from a new command: `Config::first_packet_retries = Some(0)` sends
  it once. The HP also NAKs a `C` it rejects, right after it arrives (11 ms
  on a 48SX), and that NAK looks exactly like the periodic idle one. Since
  0.1.1, `Config::first_packet_nak_window` (the packet's time on the wire
  plus slack), `Config::first_packet_nak_grace` and
  `Config::first_packet_nak_byte_time` (lower bound: a NAK sooner than the
  packet's wire time is stale) let a NAK inside the window allow one resend
  if no answer follows within the grace.
- A host command's reply arrives either in the ACK (short reply) or as a
  text transfer (`X`, `D`.., `Z`, `B`); both end up as `Event::ServerText`.

## Lower layers

`codec` (framing, block checks, the deframer), `prefix` (control, 8th-bit and
repeat prefixing), `params` (Send-Init negotiation) and `trace` (a text format
for byte traces) are public for tools and tests.

## License

MIT