diff options
Diffstat (limited to 'src/net/ip.zig')
| -rw-r--r-- | src/net/ip.zig | 2903 |
1 files changed, 2903 insertions, 0 deletions
diff --git a/src/net/ip.zig b/src/net/ip.zig new file mode 100644 index 0000000..2cc4301 --- /dev/null +++ b/src/net/ip.zig @@ -0,0 +1,2903 @@ +//! A minimal IPv4 stack: Ethernet, ARP, IPv4, ICMP echo, UDP, a DHCP client, one TCP client and +//! HTTP GET. This is what replaces lwIP. +//! +//! Two functions drive everything and nothing else touches the outside world: +//! +//! stack.onFrame(frame) a received Ethernet frame, headers and all +//! stack.tick(now_ms) time passing, in milliseconds, from anywhere the caller likes +//! +//! and one callback carries frames out (`send`, supplied to `init`). There is no `std.Io`, no +//! allocator, no clock read and no hidden thread. That is not minimalism for its own sake: it is +//! what makes the whole stack testable on the host, where a "network" is a test function that hands +//! `onFrame` bytes it wrote by hand and reads back whatever `send` was given. Every protocol +//! behaviour in this file is exercised that way in `ip_test.zig`, including retransmission - which +//! on a real timer would be a flaky test and here is two calls to `tick`. +//! +//! **Everything is statically sized.** `Stack` is one struct with fixed buffers inside it; there is +//! no allocator, not even a `FixedBufferAllocator`, because nothing here has a lifetime that an +//! arena would model better than a field does. `@sizeOf(Stack)` is asserted at compile time below +//! (`footprint`) so the number cannot drift silently against the ~128 KB of L2MEM the image has. +//! +//! Wire formats are matched field by field against the lwIP this replaces, and every one is cited: +//! ESP-IDF v6.0.2 carries lwIP at `components/lwip/lwip/src/`, and the packed structs in +//! `include/lwip/prot/*.h` are the reference for offsets, and its `.c` files for behaviour. Where +//! this stack deliberately differs from lwIP, the comment says so and why. +//! +//! ## What this is not +//! +//! * No IPv6, no TCP listen/accept, no IP fragmentation or reassembly, no TLS. Out of scope. +//! * No congestion control. TCP sends at most one unacknowledged segment at a time (see `Tcp`), +//! which is a fixed window of one and therefore needs no congestion window, no slow start and +//! no fast recovery. It is also slow. For an HTTP GET of a few kilobytes over Wi-Fi that is the +//! right trade; for bulk transfer it is not, and nothing here pretends otherwise. +//! * No VLAN tags, no 802.1Q. A tagged frame is dropped as an unknown ethertype. +//! * No transfer coding but `identity` and `chunked`. Anything else - `gzip`, `deflate`, a +//! stack of them - is rejected with `error.UnsupportedTransferEncoding` rather than handed +//! back with its framing bytes still in it. +//! * DNS resolves A records only, one query at a time, over the UDP already here, with no +//! cache. `resolve` follows `httpGet`'s protocol exactly: start, `error.WouldBlock`, the +//! caller drives `tick`/`onFrame`, call again with the same name. + +const std = @import("std"); +const assert = std.debug.assert; + +// =============================================================================== sizing +// +// The whole static footprint, in one place. Every buffer in `Stack` is one of these. + +/// Ethernet MTU: the largest IP datagram that fits in one frame. +pub const mtu: usize = 1500; +/// Ethernet header: 6 destination + 6 source + 2 ethertype. lwIP `prot/ethernet.h:89` +/// (`SIZEOF_ETH_HDR`, with its optional `ETH_PAD_SIZE` at zero). +pub const eth_hlen: usize = 14; +/// The largest frame this stack will build or accept, excluding the FCS the MAC appends. +pub const frame_max: usize = eth_hlen + mtu; + +/// ARP cache entries. Four is enough for the gateway, one peer, and two strangers, which is the +/// whole population a single-connection HTTP client on a home /24 ever needs to address. +pub const arp_cache_len: usize = 4; + +/// Bytes of HTTP response head (status line plus headers) that may be buffered while waiting for +/// the blank line. Exceeding this fails the request rather than truncating silently. +/// +/// 2048, raised from 1024 against a measurement rather than a guess. A real response from the site +/// this stack was pointed at - Cloudflare in front of GitHub Pages - carries **1043 bytes** of head: +/// 26 header lines, of which `Report-To` alone is 254 bytes and `Nel`, `X-Fastly-Request-ID`, +/// `X-GitHub-Request-Id` and `alt-svc` are another 200 between them. At 1024 the request failed with +/// `HttpHeadersTooLong` after the body had already been negotiated, 19 bytes short. +/// +/// Modern CDN responses simply have large heads, and 1 KB is not a realistic ceiling for one. 2 KB +/// leaves about a kilobyte of margin over the measured case; the failure remains a named error +/// rather than truncation, so a head that exceeds even this is still diagnosable rather than silently +/// wrong. +pub const http_head_max: usize = 2048; + +/// Bytes of chunked *framing* - one chunk's extension parameters, or the whole trailer section - +/// tolerated before the response is failed. Framing is skipped rather than stored, so this bounds +/// work and not memory: without it a peer that streams `;a=b` forever, or trailer lines forever, +/// is a request that never ends and never errors. 512 is generous; a real trailer section is one +/// or two short lines. +pub const http_framing_max: usize = 512; + +/// The longest host name `resolve` will encode into a DNS question, in dotted text. RFC 1035 2.3.4 +/// allows 255; this stack holds the encoded question in `Stack` for the duration of the query, and +/// 64 covers every name a device that fetches one URL will ever ask for. A longer one is +/// `error.NameTooLong`, never a silently truncated question. +pub const dns_name_max: usize = 64; + +/// The encoded question that `dns_name_max` produces. Encoding turns `a.b` into `1a1b0`: one +/// length byte per label plus the root label, which for a name with no trailing dot is exactly +/// two bytes more than the text. RFC 1035 4.1.2. +pub const dns_qname_max: usize = dns_name_max + 2; + +/// Bytes of outbound TCP payload held for retransmission. This is sized for one HTTP request line +/// plus headers; there is no streaming send, so it is also the hard limit on request size. +pub const tcp_tx_max: usize = 512; + +/// The receive window this stack advertises, in bytes, when it has that much room to consume into. +/// One MSS: a peer that fills the window gets a segment acknowledged before it may send another. +pub const tcp_window: u16 = 1460; + +/// TCP MSS offered in the SYN. 1500 - 20 (IP) - 20 (TCP). +pub const tcp_mss: u16 = 1460; + +/// RFC 1122 4.2.2.6: a peer that sends no MSS option is assumed to accept 536. +pub const tcp_default_mss: u16 = 536; + +/// Initial retransmission timeout. RFC 6298 2.1 specifies 1 s for a connection with no RTT sample, +/// and this stack never takes an RTT sample - see `Tcp.rto_ms`. +pub const tcp_rto_initial_ms: u32 = 1000; +/// Retransmission timeout ceiling. RFC 6298 5.7 allows any value at or above 60 s; 16 s is chosen +/// against a device whose whole reason to exist is one short request. +pub const tcp_rto_max_ms: u32 = 16_000; +/// Retransmissions of the same segment before the connection is abandoned with `error.TimedOut`. +/// With the backoff above that is 1+2+4+8+16+16 = 47 s of trying. +pub const tcp_max_retries: u8 = 6; +/// TIME_WAIT duration. RFC 793 says 2*MSL, conventionally 240 s. Two seconds is what this uses: +/// holding a connection block for four minutes on a part with 128 KB of RAM to protect a +/// port number that this stack increments on every connect is the wrong trade. The risk it drops is +/// a late duplicate segment from the *previous* incarnation of the same 4-tuple being accepted into +/// a new one, and incrementing the local port already makes a repeat 4-tuple require 16,384 +/// connections first. +pub const tcp_time_wait_ms: u32 = 2000; +/// How long a half-closed connection waits for the peer's FIN before the block is released. RFC +/// 793 has no such timer and a connection may legitimately sit in FIN-WAIT-2 forever; Linux uses +/// 60 s for the same reason this uses 10 s - a peer that has our FIN and never answers is a peer +/// that is gone, and the one connection block here is not worth holding for it. +pub const tcp_fin_wait2_ms: u32 = 10_000; + +/// DHCP retransmission backoff, in milliseconds, indexed by attempt. RFC 2131 4.1 asks for +/// randomised exponential backoff starting at 4 s; this starts at 2 s because the first DHCP +/// exchange is on the critical path of every boot, and does not randomise because there is one +/// client on this board and the collision RFC 2131 is avoiding is between many. +const dhcp_backoff_ms = [_]u32{ 2_000, 4_000, 8_000, 16_000, 32_000, 64_000 }; + +/// Minimum length of the BOOTP/DHCP message this stack transmits, in UDP payload bytes. RFC 951 +/// fixed BOOTP messages at 300 bytes and relay agents in the field still expect at least that +/// much; lwIP pads the same way through its fixed-size `struct dhcp_msg` +/// (`prot/dhcp.h:63-91`: 236 + 4 cookie + `DHCP_OPTIONS_LEN` 68 = 308). +const dhcp_min_msg_len: usize = 300; + +/// DNS retransmission backoff, in milliseconds, indexed by attempt. RFC 1035 4.2.1 leaves the +/// timer to the implementation; this is BIND's classic 1 s doubling, and the array length is the +/// try count, so the whole exchange is bounded at 1+2+4 = 7 s and then `error.TimedOut`. The +/// transaction id is *not* redrawn between tries: a slow first answer must still be accepted. +const dns_backoff_ms = [_]u32{ 1_000, 2_000, 4_000 }; + +/// Compression pointers followed while skipping one name (RFC 1035 4.1.4). This is the bound that +/// makes a hostile message terminate: see `dnsSkipName`, where the argument is written out. +const dns_max_jumps: u8 = 16; + +// =============================================================== addresses and enumerations + +pub const Mac = [6]u8; +pub const Ip4 = [4]u8; + +pub const mac_broadcast: Mac = @splat(0xff); +pub const ip_any: Ip4 = @splat(0x00); +pub const ip_broadcast: Ip4 = @splat(0xff); + +/// Ethernet type field values. lwIP `prot/ieee.h:52-85` (`enum lwip_ieee_eth_type`). +pub const EtherType = enum(u16) { + ip4 = 0x0800, + arp = 0x0806, + vlan = 0x8100, + ip6 = 0x86dd, + _, +}; + +/// IP header protocol numbers. lwIP `prot/ip.h:46-50`. +pub const Protocol = enum(u8) { + icmp = 1, + tcp = 6, + udp = 17, + _, +}; + +// =============================================================================== checksum +// +// One implementation for IPv4, ICMP, UDP and TCP. The last two prepend a pseudo-header, which is +// the only difference between them: the arithmetic is identical, so it is written once. + +/// The Internet checksum of RFC 1071: the one's complement of the one's complement sum of the +/// data taken as 16-bit big-endian words, with a zero byte appended if the length is odd. +/// +/// Incremental, because TCP and UDP checksum a pseudo-header, a header and a payload that are +/// three separate buffers and never adjacent in memory. Feeding them in sequence must give the +/// same answer as checksumming the concatenation, which is why `half` exists: a chunk of odd +/// length leaves the high byte of a word owed, and the next chunk's first byte completes it. +/// Getting that wrong is invisible until a payload happens to have odd length, which for HTTP is +/// most of the time. +pub const Checksum = struct { + /// Accumulated 16-bit words. Deferring the end-around carry is safe for any length this + /// stack can produce: 32 bits absorbs 65,536 words, and the largest thing checksummed here is + /// 1,500 bytes. + sum: u32 = 0, + /// High byte of a 16-bit word whose low byte has not arrived yet. + half: ?u8 = null, + + pub fn update(self: *Checksum, bytes: []const u8) void { + var b = bytes; + if (self.half) |hi| { + if (b.len == 0) return; + self.sum += (@as(u32, hi) << 8) | b[0]; + self.half = null; + b = b[1..]; + } + var i: usize = 0; + while (i + 1 < b.len) : (i += 2) self.sum += std.mem.readInt(u16, b[i..][0..2], .big); + if (i < b.len) self.half = b[i]; + } + + /// Feed a big-endian 16-bit value, for the pseudo-header fields that are not in any buffer. + pub fn update16(self: *Checksum, v: u16) void { + var tmp: [2]u8 = undefined; + std.mem.writeInt(u16, &tmp, v, .big); + self.update(&tmp); + } + + /// The checksum as it goes on the wire. RFC 1071 1: an odd-length buffer is padded with a + /// zero byte, which the fold below does implicitly by shifting the owed byte up. + pub fn final(self: Checksum) u16 { + var s = self.sum; + if (self.half) |hi| s += @as(u32, hi) << 8; + while (s >> 16 != 0) s = (s & 0xffff) + (s >> 16); + return ~@as(u16, @truncate(s)); + } +}; + +/// The Internet checksum of one contiguous buffer. +pub fn checksum(bytes: []const u8) u16 { + var c: Checksum = .{}; + c.update(bytes); + return c.final(); +} + +/// The TCP/UDP pseudo-header of RFC 793 3.1: source address, destination address, a zero byte, the +/// protocol number and the transport length. Not transmitted; only checksummed. +fn pseudoHeader(c: *Checksum, src: Ip4, dst: Ip4, proto: Protocol, len: u16) void { + c.update(&src); + c.update(&dst); + c.update16(@intFromEnum(proto)); // the zero byte and the protocol byte, as one word + c.update16(len); +} + +/// A checksum for a UDP or TCP segment: pseudo-header, then the segment with its own checksum +/// field already zeroed. +fn transportChecksum(src: Ip4, dst: Ip4, proto: Protocol, segment: []const u8) u16 { + var c: Checksum = .{}; + pseudoHeader(&c, src, dst, proto, @intCast(segment.len)); + c.update(segment); + return c.final(); +} + +/// Verify a received transport checksum. A UDP datagram may carry zero, meaning "not computed" +/// (RFC 768); TCP may not. +fn transportChecksumOk(src: Ip4, dst: Ip4, proto: Protocol, segment: []const u8, field: u16) bool { + if (proto == .udp and field == 0) return true; + // Summing a segment that already contains its own checksum yields 0 (or, equivalently, the + // sum before complementing is 0xffff). RFC 1071 1. + return transportChecksum(src, dst, proto, segment) == 0; +} + +/// A transmitted UDP checksum of zero would be read as "not computed", so RFC 768 requires it be +/// sent as the equivalent 0xffff instead. TCP has no such rule and no such ambiguity. +pub fn udpChecksumOnWire(c: u16) u16 { + return if (c == 0) 0xffff else c; +} + +// ============================================================== unaligned big-endian access +// +// `std.mem.readInt`/`writeInt` with an explicit endianness at every single field. Never a shift and +// an or: a network header written by hand is where byte order goes wrong, and it goes wrong +// silently, on one field, in a way that looks like a hardware problem. + +inline fn rd16(b: []const u8, off: usize) u16 { + return std.mem.readInt(u16, b[off..][0..2], .big); +} +inline fn rd32(b: []const u8, off: usize) u32 { + return std.mem.readInt(u32, b[off..][0..4], .big); +} +inline fn wr16(b: []u8, off: usize, v: u16) void { + std.mem.writeInt(u16, b[off..][0..2], v, .big); +} +inline fn wr32(b: []u8, off: usize, v: u32) void { + std.mem.writeInt(u32, b[off..][0..4], v, .big); +} +inline fn rdIp(b: []const u8, off: usize) Ip4 { + return b[off..][0..4].*; +} +inline fn wrIp(b: []u8, off: usize, v: Ip4) void { + b[off..][0..4].* = v; +} +inline fn rdMac(b: []const u8, off: usize) Mac { + return b[off..][0..6].*; +} +inline fn wrMac(b: []u8, off: usize, v: Mac) void { + b[off..][0..6].* = v; +} + +// ============================================================================ header offsets +// +// Byte offsets rather than packed structs. `extern struct` would need `align(1)` on every field and +// a byte-swap on every access on this little-endian part, and the offsets are what the RFCs and +// lwIP's headers actually state, so this is the form that can be checked against them by eye. + +/// lwIP `prot/ethernet.h:76-83` (`struct eth_hdr`). +const eth = struct { + const dst = 0; + const src = 6; + const ethertype = 12; +}; + +/// lwIP `prot/etharp.h:86-96` (`struct etharp_hdr`), `SIZEOF_ETHARP_HDR` 28 at `:102`. +const arp = struct { + const hwtype = 0; + const proto = 2; + const hwlen = 4; + const protolen = 5; + const opcode = 6; + const sha = 8; // sender hardware address + const spa = 14; // sender protocol address + const tha = 18; // target hardware address + const tpa = 24; // target protocol address + const len = 28; + + /// lwIP `prot/iana.h:54` (`LWIP_IANA_HWTYPE_ETHERNET`). + const hwtype_ethernet: u16 = 1; + /// lwIP `prot/etharp.h:105-108` (`enum etharp_opcode`). + const op_request: u16 = 1; + const op_reply: u16 = 2; +}; + +/// lwIP `prot/ip4.h:73-97` (`struct ip_hdr`), `IP_HLEN` 20 at `:64`. +const ip4 = struct { + const v_hl = 0; + const tos = 1; + const total_len = 2; + const id = 4; + const frag = 6; + const ttl = 8; + const proto = 9; + const chksum = 10; + const src = 12; + const dst = 16; + const hlen = 20; + + /// lwIP `prot/ip4.h:84-87`. + const flag_df: u16 = 0x4000; + const flag_mf: u16 = 0x2000; + const offset_mask: u16 = 0x1fff; +}; + +/// lwIP `prot/icmp.h:89-95` (`struct icmp_echo_hdr`). +const icmp = struct { + const type_ = 0; + const code = 1; + const chksum = 2; + const id = 4; + const seq = 6; + const hlen = 8; + + /// lwIP `prot/icmp.h:46,50`. + const echo_reply: u8 = 0; + const echo_request: u8 = 8; +}; + +/// lwIP `prot/udp.h:53-58` (`struct udp_hdr`), `UDP_HLEN` 8 at `:46`. +const udp = struct { + const src_port = 0; + const dst_port = 2; + const len = 4; + const chksum = 6; + const hlen = 8; +}; + +/// lwIP `prot/tcp.h:56-65` (`struct tcp_hdr`), `TCP_HLEN` 20 at `:47`. +const tcp = struct { + const src_port = 0; + const dst_port = 2; + const seq = 4; + const ack = 8; + /// Top four bits are the header length in 32-bit words; the low six are the flags. + /// lwIP `prot/tcp.h:85-87`. + const hdrlen_flags = 12; + const window = 14; + const chksum = 16; + const urgent = 18; + const hlen = 20; + + /// lwIP `prot/tcp.h:72-81`. + const fin: u8 = 0x01; + const syn: u8 = 0x02; + const rst: u8 = 0x04; + const psh: u8 = 0x08; + const ack_f: u8 = 0x10; + const urg: u8 = 0x20; + + /// RFC 793 3.1: kind 2, length 4, then the 16-bit MSS. + const opt_end: u8 = 0; + const opt_nop: u8 = 1; + const opt_mss: u8 = 2; +}; + +/// lwIP `prot/dhcp.h:50-91` (`struct dhcp_msg`) and `:51-56` for the offsets named there. +const dhcp = struct { + const op = 0; + const htype = 1; + const hlen = 2; + const hops = 3; + const xid = 4; + const secs = 8; + const flags = 10; + const ciaddr = 12; + const yiaddr = 16; + const siaddr = 20; + const giaddr = 24; + const chaddr = 28; + const sname = 44; // DHCP_SNAME_OFS + const file = 108; // DHCP_FILE_OFS + const cookie = 236; // DHCP_MSG_LEN + const options = 240; // DHCP_OPTIONS_OFS = DHCP_MSG_LEN + 4 + + /// lwIP `prot/dhcp.h:116-117`. + const bootrequest: u8 = 1; + const bootreply: u8 = 2; + /// lwIP `prot/dhcp.h:120-127`. + const discover: u8 = 1; + const offer: u8 = 2; + const request: u8 = 3; + const ack: u8 = 5; + const nak: u8 = 6; + /// lwIP `prot/dhcp.h:129`. + const magic_cookie: u32 = 0x63825363; + /// RFC 2131 figure 2: the top bit of `flags` asks the server to broadcast its reply. + const flag_broadcast: u16 = 0x8000; + + /// lwIP `prot/dhcp.h:134-165`. Only the ones this client uses. + const opt_pad: u8 = 0; + const opt_subnet_mask: u8 = 1; + const opt_router: u8 = 3; + const opt_dns: u8 = 6; + const opt_hostname: u8 = 12; + const opt_requested_ip: u8 = 50; + const opt_lease_time: u8 = 51; + const opt_overload: u8 = 52; + const opt_msg_type: u8 = 53; + const opt_server_id: u8 = 54; + const opt_param_list: u8 = 55; + const opt_max_msg_size: u8 = 57; + const opt_t1: u8 = 58; + const opt_t2: u8 = 59; + const opt_end: u8 = 255; + + /// lwIP `prot/iana.h:66-68`. + const server_port: u16 = 67; + const client_port: u16 = 68; +}; + +/// RFC 1035 4.1. There is no lwIP reference for this one: lwIP's resolver is `core/dns.c`, which +/// builds the same header out of its own `struct dns_hdr` (`core/dns.c:180-190`) - the offsets +/// below are the RFC's, and `dns.c` is only a cross-check. +const dns = struct { + // 4.1.1 header, six 16-bit fields. + const id = 0; + const flags = 2; + const qdcount = 4; + const ancount = 6; + const nscount = 8; + const arcount = 10; + const hlen = 12; + + /// 4.1.1: QR is the top bit of `flags`, RD is bit 8, RCODE the bottom four bits. + const flag_qr: u16 = 0x8000; + const flag_rd: u16 = 0x0100; + const rcode_mask: u16 = 0x000f; + /// RCODE 3, "name error": the name authoritatively does not exist. RFC 1035 4.1.1. + const rcode_name_error: u16 = 3; + + /// 4.1.4: the two top bits of a length byte set means the rest is a 14-bit offset. + const ptr_mask: u8 = 0xc0; + /// 2.3.4: a label is at most 63 bytes, which is also why 0x40 and 0x80 are free to be flags. + const label_max: u8 = 63; + + /// 3.2.2 TYPE and 3.2.4 CLASS. Only the two this stack looks at, plus CNAME, which is not + /// followed but must be stepped over: a name behind a CNAME chain answers with the chain and + /// the A record together, and a resolver that stops at the first record finds the CNAME. + const type_a: u16 = 1; + const type_cname: u16 = 5; + const class_in: u16 = 1; + + /// 3.2.1: TYPE(2) CLASS(2) TTL(4) RDLENGTH(2) after the name. + const rr_fixed = 10; + + /// lwIP `prot/iana.h:64` (`LWIP_IANA_PORT_DNS`). + const port: u16 = 53; +}; + +// ============================================================================== ARP cache + +const ArpEntry = struct { + ip: Ip4 = ip_any, + mac: Mac = @splat(0), + /// `tick`'s clock at the last hit or update. Zero means the entry is empty. + stamp_ms: u64 = 0, + + inline fn valid(self: ArpEntry) bool { + return self.stamp_ms != 0; + } +}; + +/// Entries older than this are treated as absent and re-resolved. lwIP's default is 300 s +/// (`ARP_TMR_INTERVAL` 1000 ms x `ARP_MAXAGE` 300, `core/ipv4/etharp.c`); the same here. +const arp_max_age_ms: u64 = 300_000; +/// How often an unanswered ARP request is repeated while `httpGet` waits for a MAC address. +const arp_retry_ms: u64 = 1000; +/// ARP requests sent for one destination before `httpGet` gives up with `error.HostUnreachable`. +const arp_max_tries: u8 = 5; + +// ================================================================================ DHCP state + +pub const DhcpState = enum { + /// `dhcpStart` has not been called, or `setStatic` has taken over. + off, + /// DISCOVER sent, waiting for an OFFER. + selecting, + /// REQUEST sent, waiting for an ACK. + requesting, + /// Bound, lease held, T1 not yet reached. + bound, + /// Past T1: unicast REQUEST to the server that granted the lease. + renewing, + /// Past T2: broadcast REQUEST to any server. + rebinding, +}; + +const Dhcp = struct { + state: DhcpState = .off, + xid: u32 = 0, + /// The address the server offered, held between OFFER and ACK. + offered: Ip4 = ip_any, + /// Option 54 from the OFFER, echoed in the REQUEST and unicast to when renewing. + server: Ip4 = ip_any, + /// Option 51, seconds. `0xffff_ffff` is an infinite lease (RFC 2131 3.3). + lease_s: u32 = 0, + /// Absolute deadlines derived from the lease at bind time, in `tick`'s milliseconds. + t1_ms: u64 = 0, + t2_ms: u64 = 0, + expire_ms: u64 = 0, + /// When the next DISCOVER/REQUEST retransmission is due, and how many have gone out. + retry_ms: u64 = 0, + tries: u8 = 0, + /// `tick`'s clock when acquisition began, for the `secs` field. + started_ms: u64 = 0, +}; + +// ================================================================================ TCP state + +pub const TcpState = enum { + closed, + /// Waiting for the peer's MAC address before the SYN can be built. + arp_wait, + syn_sent, + established, + /// Our FIN is sent; the peer has not FINed. + fin_wait_1, + fin_wait_2, + /// The peer FINed first and we have replied with our own FIN. + last_ack, + time_wait, +}; + +const Tcp = struct { + state: TcpState = .closed, + + peer_ip: Ip4 = ip_any, + peer_port: u16 = 0, + local_port: u16 = 0, + + /// Initial send sequence number. The SYN occupies `iss`; request data occupies + /// `iss+1 .. iss+1+tx_len`; a FIN occupies `iss+1+tx_len`. Every offset in this struct is + /// derived from that one layout, which is why there is no separate "unacked offset". + iss: u32 = 0, + /// Oldest sequence number not yet acknowledged by the peer. + snd_una: u32 = 0, + /// Next sequence number to send. + snd_nxt: u32 = 0, + /// The peer's advertised window. + snd_wnd: u32 = 0, + /// The peer's MSS, from its SYN's option or RFC 1122's default. + snd_mss: u16 = tcp_default_mss, + /// Set once a FIN has been queued behind the request data. + fin_queued: bool = false, + /// Set once the peer's FIN has been received in order. Receiving it does not by itself move + /// `state`, so that `tcpSendData` stays the only thing that changes it. + peer_fin: bool = false, + + /// Next sequence number expected from the peer. + rcv_nxt: u32 = 0, + + /// Retransmission deadline in `tick`'s milliseconds, and the current timeout. `rto_ms` doubles + /// on every retransmission and is never reduced by an RTT measurement, because this stack + /// takes none: with a single segment in flight and a fixed backoff there is nothing an RTT + /// estimator would change except the first timeout, and 1 s is already RFC 6298's answer for + /// that case. + rto_deadline_ms: u64 = 0, + rto_ms: u32 = tcp_rto_initial_ms, + retries: u8 = 0, + /// When TIME_WAIT ends. + close_deadline_ms: u64 = 0, + + /// The request bytes, held for retransmission until acknowledged. + tx: [tcp_tx_max]u8 = undefined, + tx_len: usize = 0, + + /// Sequence number of the first byte of `tx`. + inline fn dataStart(self: Tcp) u32 { + return self.iss +% 1; + } + /// Sequence number one past the last byte of `tx`. + inline fn dataEnd(self: Tcp) u32 { + return self.iss +% 1 +% @as(u32, @intCast(self.tx_len)); + } +}; + +/// Sequence-number comparison. TCP sequence numbers wrap, so they are compared by the sign of the +/// difference and never by `<`. RFC 1982 serial arithmetic; the classic bug this avoids is a +/// connection that stalls forever once the sequence space crosses 2^32. +inline fn seqLt(a: u32, b: u32) bool { + return @as(i32, @bitCast(a -% b)) < 0; +} +inline fn seqLe(a: u32, b: u32) bool { + return @as(i32, @bitCast(a -% b)) <= 0; +} +inline fn seqGt(a: u32, b: u32) bool { + return seqLt(b, a); +} +inline fn seqGe(a: u32, b: u32) bool { + return seqLe(b, a); +} + +// =============================================================================== HTTP state + +pub const HttpError = error{ + /// The request is in flight. Call `tick`, feed frames to `onFrame`, and call `httpGet` again + /// with the same arguments. This is the only "error" a healthy request returns. + WouldBlock, + /// `httpGet` was called with different arguments while a request was in flight. + Busy, + /// The peer's MAC address could not be resolved. + HostUnreachable, + /// The peer sent RST. + ConnectionReset, + /// The peer FINed or vanished before the body was complete. + ConnectionClosed, + /// Retransmissions exhausted. + TimedOut, + /// The status line, the headers, or a chunked body's trailer section exceeded its budget + /// (`http_head_max`, `http_framing_max`). + HttpHeadersTooLong, + /// The status line was not `HTTP/1.x SSS`. + HttpMalformed, + /// A chunked body's framing was not RFC 7230 4.1: a size with no hex digits, a size that + /// overflows `usize`, or a CRLF that was not where the grammar puts it. Distinct from + /// `HttpMalformed` because the two point at different halves of the response, and on a board + /// with one UART the error name is the whole diagnosis. + HttpChunkMalformed, + /// `Transfer-Encoding` was present and was neither `identity` nor `chunked`. + UnsupportedTransferEncoding, + /// The body did not fit in the caller's `out` buffer. + StreamTooLong, + /// The request line and headers did not fit in `tcp_tx_max`, or `path` is unusable. + RequestTooLong, + /// `httpGet` was called before the stack had an address. + NoAddress, +}; + +const HttpPhase = enum { idle, head, body, complete, failed }; + +const Http = struct { + phase: HttpPhase = .idle, + /// Valid when `phase == .failed`. + err: HttpError = error.WouldBlock, + + /// The caller's output buffer, borrowed for the duration of the request. Recorded rather than + /// copied, so the caller must not move or resize it between `httpGet` calls; the identity check + /// in `httpGet` catches the common way of getting that wrong. + out: []u8 = &.{}, + out_len: usize = 0, + + /// The request being served, kept so a re-entrant `httpGet` can be told apart from a new one. + /// The hash covers the path *and* the `Host:` name, which is what makes two requests to the + /// same address for the same path but different virtual hosts distinguishable - and they must + /// be, or the second silently rides on the first's connection. A hash rather than the strings + /// themselves because `Stack` has a 4 KiB budget and the strings are the caller's, alive for + /// the duration of the call only. + req_host: Ip4 = ip_any, + req_port: u16 = 0, + req_hash: u64 = 0, + + /// Status line and headers, accumulated until the blank line. + head: [http_head_max]u8 = undefined, + head_len: usize = 0, + + status: u16 = 0, + /// `null` means the response had no usable `Content-Length`, so the body ends at the peer's + /// FIN - or, when `chunked`, at the zero-length chunk. + content_length: ?usize = null, + + // ------------------------------------------------------- RFC 7230 4.1 chunked decoding + // + // Four fields hold the whole position in the chunked grammar, because a segment boundary may + // fall between any two bytes of it and the decoder has to resume from exactly here. + + /// `Transfer-Encoding: chunked` was in force on this response. + chunked: bool = false, + chunk: ChunkState = .size, + /// In `.size`, the hexadecimal size accumulated so far; in `.data`, the bytes of this chunk + /// still to come. The two are the same number, which is why one field serves both: the size + /// read is the count remaining the instant the header ends. + chunk_left: usize = 0, + /// At least one hex digit has been seen in the size being read. RFC 7230 4.1 is `1*HEXDIG`, + /// so an empty size is malformed - and without this flag a stray CRLF reads as a chunk of + /// length zero, which is the terminator, which ends the body early and looks like success. + chunk_digit: bool = false, + /// Framing bytes consumed in the extension or trailer section now being skipped, against + /// `http_framing_max`. + chunk_skip: u16 = 0, +}; + +/// Where the chunked decoder is in RFC 7230 4.1's grammar: +/// +/// chunked-body = *chunk last-chunk trailer-part CRLF +/// chunk = chunk-size [ chunk-ext ] CRLF chunk-data CRLF +/// last-chunk = 1*("0") [ chunk-ext ] CRLF +/// +/// Every terminal in that grammar that can be split by a segment boundary is a state, including +/// the two halves of each CRLF. That is not pedantry: a 1,460-byte segment ends wherever the +/// server's writes happen to end, and "the CR arrived and the LF did not" is a case that happens. +const ChunkState = enum { + /// Reading hex digits of `chunk-size`. + size, + /// A `;` was seen: skipping `chunk-ext` to the CR that ends the header. + ext, + /// The CR of the chunk header is in; its LF must follow. + size_lf, + /// Copying `chunk_left` more bytes of `chunk-data` into the caller's `out`. + data, + /// The data is in; the CR of the CRLF that closes the chunk must follow. + data_cr, + /// ...and its LF. + data_lf, + /// At the first byte of a trailer line - or of the CRLF that ends the whole body. + trailer, + /// Inside a trailer line, skipping to its CR. + trailer_line, + /// The LF of a trailer line. + trailer_lf, + /// The LF of the final empty line. The response is complete after it, and not before. + end_lf, +}; + +// ================================================================================ DNS state + +pub const DnsError = error{ + /// The query is in flight. Call `tick`, feed frames to `onFrame`, and call `resolve` again + /// with the same name. This is the only "error" a healthy query returns. + WouldBlock, + /// `resolve` was called with a different name while a query was in flight. One query is + /// outstanding at a time; the caller must finish or abandon the first. + Busy, + /// `resolve` was called before the stack had an address of its own to send from. + NoAddress, + /// No resolver: DHCP supplied none and `setDnsServer` was not called. + NoDnsServer, + /// The name was empty, had an empty label, or had a label over 63 bytes. RFC 1035 2.3.4. + NameInvalid, + /// The name was longer than `dns_name_max`. + NameTooLong, + /// `dns_backoff_ms.len` queries went out and nothing came back. + TimedOut, + /// The server said the name does not exist (RCODE 3), or answered with no A record in it - + /// a CNAME chain leading nowhere, or an AAAA-only name. Both mean the same thing to a stack + /// that speaks IPv4 only. + NameNotFound, + /// The server answered with a non-zero RCODE other than name-error: SERVFAIL, REFUSED. + DnsRefused, + /// A response that matched the id and the question could not be parsed: a name that runs off + /// the end, a compression pointer that goes forward or loops, an RDLENGTH past the message. + /// Responses that do *not* match the id and question are ignored rather than reported, so + /// this is the server or an attacker who already guessed both, never stray traffic. + DnsMalformed, +}; + +const DnsPhase = enum { idle, waiting, done, failed }; + +const DnsQuery = struct { + phase: DnsPhase = .idle, + /// Valid when `phase == .failed`. + err: DnsError = error.WouldBlock, + + /// The question, in RFC 1035 4.1.2 wire form, root label included. Held rather than + /// re-encoded because it is needed in three places: to build each retransmission from `tick`, + /// to compare against the question echoed in a response, and to tell a re-entrant `resolve` + /// from a new one. Comparing the encoded form is what makes the last two exact. + qname: [dns_qname_max]u8 = undefined, + qname_len: u8 = 0, + + /// The transaction id, held across retransmissions so a slow first answer still matches. + id: u16 = 0, + /// The ephemeral source port, redrawn per query. Together with `id` that is 32 bits an + /// off-path spoofer has to guess, which is the whole of what plain DNS offers. + local_port: u16 = 0, + + tries: u8 = 0, + retry_ms: u64 = 0, + + /// Valid when `phase == .done`. + result: Ip4 = ip_any, +}; + +// ================================================================================= counters +// +// Not statistics for their own sake: the first hardware bring-up of this stack will be a board that +// either answers a ping or does not, with no debugger and one UART. These are what turns "nothing +// happens" into "1,204 frames arrived, 1,204 were dropped, and the checksum counter is zero", which +// says the frames are not for us rather than that the checksum code is broken. + +pub const Counters = struct { + rx_frames: u32 = 0, + rx_dropped: u32 = 0, + tx_frames: u32 = 0, + tx_dropped: u32 = 0, + arp_rx: u32 = 0, + arp_tx: u32 = 0, + icmp_echo: u32 = 0, + udp_rx: u32 = 0, + dhcp_rx: u32 = 0, + dhcp_tx: u32 = 0, + tcp_rx: u32 = 0, + tcp_tx: u32 = 0, + tcp_retx: u32 = 0, + tcp_rst_rx: u32 = 0, + /// Queries sent, retransmissions among them, and responses that matched the outstanding + /// query's id and question. `dns_tx > dns_rx` with `dns_retx` climbing is a resolver that is + /// not answering; `dns_rx == 0` with `udp_rx` climbing is an answer arriving and being + /// rejected, which is a different bug in a different place. + dns_tx: u32 = 0, + dns_retx: u32 = 0, + dns_rx: u32 = 0, + /// Frames discarded because a checksum did not verify. A non-zero value here with a working + /// link means a bug in this file or a broken SDIO transfer, not a network problem. + checksum_bad: u32 = 0, +}; + +// ==================================================================================== Stack + +pub const Stack = struct { + // ------------------------------------------------------------------ identity and route + mac: Mac, + /// `null` until DHCP binds or `setStatic` is called. + addr: ?Ip4 = null, + mask: Ip4 = ip_any, + gw: Ip4 = ip_any, + /// The resolver, from DHCP option 6 or `setDnsServer`. `null` means nothing to ask. + dns: ?Ip4 = null, + + /// Where frames go. Called synchronously from `onFrame`, `tick` and `httpGet`; the slice is + /// borrowed for the duration of the call and must be copied if the transport needs it later. + /// + /// Note the absence of a context pointer: the interface this slice implements specifies + /// `*const fn ([]const u8) void`, so a callee needing state has to reach it some other way. + send: *const fn (frame: []const u8) void, + + // ------------------------------------------------------------------------------ clock + /// The last value handed to `tick`. `onFrame` needs a timestamp for the ARP cache and takes it + /// from here rather than reading a clock, which is what keeps this file free of any hardware + /// dependency at all. + now_ms: u64 = 0, + + // ------------------------------------------------------------------------------ state + arp_cache: [arp_cache_len]ArpEntry = @splat(.{}), + /// Pending ARP resolution for the TCP peer: deadline, tries. + arp_retry_ms: u64 = 0, + arp_tries: u8 = 0, + + dhcp: Dhcp = .{}, + tcp: Tcp = .{}, + http: Http = .{}, + /// The one outstanding DNS query. Named `query` and not `dns`, which is the server's address. + query: DnsQuery = .{}, + counters: Counters = .{}, + + /// IPv4 identification field. Incremented per datagram. Nothing here fragments, so this only + /// has to be non-constant for the benefit of middleboxes and packet captures. + ip_id: u16 = 0, + /// Mixed into transaction ids, initial sequence numbers and ephemeral ports. There is no + /// hardware RNG in this file's reach, so this is seeded from the MAC and stirred by every + /// `tick` value observed - which for the two uses here (not colliding with a previous + /// incarnation of the same connection, and not matching a stale DHCP reply) is sufficient. + /// It is emphatically *not* a source of security-relevant randomness. + entropy: u64, + + /// The single transmit staging buffer. Every frame this stack sends is built here and handed to + /// `send` before the next one starts, so one is enough - and `send` is documented as borrowing. + tx: [frame_max]u8 = undefined, + + /// The total static footprint of one `Stack`, asserted so the number in the report cannot rot. + pub const footprint = @sizeOf(Stack); + + // =========================================================================== lifecycle + + /// A single struct-literal return, deliberately: result-location semantics then construct the + /// buffers in the caller's storage instead of memcpy-ing several kilobytes off a stack that is + /// 8 KB by default on this target. + pub fn init(mac: [6]u8, send: *const fn (frame: []const u8) void) Stack { + return .{ + .mac = mac, + .send = send, + .entropy = std.hash.Wyhash.hash(0x4200_cafe, &mac), + }; + } + + /// Stir and draw. Not random; see `entropy`. + fn draw(self: *Stack) u32 { + self.entropy = self.entropy *% 6364136223846793005 +% 1442695040888963407; + return @truncate(self.entropy >> 32); + } + + // ============================================================================= address + + /// The configured address, or `null` if there is none yet. + pub fn ip(self: *Stack) ?[4]u8 { + return self.addr; + } + + pub fn netmask(self: *Stack) Ip4 { + return self.mask; + } + + pub fn gateway(self: *Stack) Ip4 { + return self.gw; + } + + /// The resolver `resolve` will ask: the first server DHCP offered (option 6), or whatever + /// `setDnsServer` last set. `null` means `resolve` will answer `error.NoDnsServer`. + pub fn dnsServer(self: *Stack) ?Ip4 { + return self.dns; + } + + /// Override the resolver. Only needed on a network whose DHCP server offers none, or when + /// configuring statically: the ordinary path is a lease that carries option 6, which + /// `dhcpBind` already stores, and a caller that does nothing gets that. + /// + /// Any query in flight is abandoned: it was addressed to the old server and its answer would + /// now be rejected as coming from the wrong source. + pub fn setDnsServer(self: *Stack, addr: Ip4) void { + self.dns = addr; + self.query.phase = .idle; + } + + pub fn dhcpState(self: *Stack) DhcpState { + return self.dhcp.state; + } + + pub fn tcpState(self: *Stack) TcpState { + return self.tcp.state; + } + + /// The status code of the last response whose head was parsed. Zero before that. + pub fn httpStatus(self: *Stack) u16 { + return self.http.status; + } + + /// Configure statically and stop any DHCP activity. This is the path the first hardware test + /// takes: it makes the board reachable without a working DHCP client, so an ARP or ping + /// failure means the SDIO transport or the association is wrong rather than this file. + pub fn setStatic(self: *Stack, addr: [4]u8, mask: [4]u8, gw: [4]u8) void { + self.dhcp = .{}; + self.addr = addr; + self.mask = mask; + self.gw = gw; + // Any query in flight was sent from the old address, so its answer is addressed to a + // station that no longer exists. `dns` itself is left alone: a resolver learnt from a + // previous lease is still the right one to ask on the same wire. + self.query.phase = .idle; + self.announce(); + } + + /// Is this address ours, or one everybody on the wire is meant to hear? + fn forUs(self: *Stack, dst: Ip4) bool { + if (std.mem.eql(u8, &dst, &ip_broadcast)) return true; + const a = self.addr orelse return false; + if (std.mem.eql(u8, &dst, &a)) return true; + // Subnet broadcast: host bits all ones. + var i: usize = 0; + while (i < 4) : (i += 1) { + if (dst[i] | self.mask[i] != 0xff) return false; + if (dst[i] & self.mask[i] != a[i] & self.mask[i]) return false; + } + return true; + } + + fn onLink(self: *Stack, dst: Ip4) bool { + const a = self.addr orelse return true; // unconfigured: everything is a direct neighbour + var i: usize = 0; + while (i < 4) : (i += 1) { + if ((dst[i] ^ a[i]) & self.mask[i] != 0) return false; + } + return true; + } + + // ================================================================== frame construction + + fn emitFrame(self: *Stack, len: usize) void { + if (len > frame_max) { + self.counters.tx_dropped += 1; + return; + } + // Ethernet's 60-byte minimum (64 with FCS) is padded by the MAC, and ESP-Hosted's slave + // hands the frame to the C6's Wi-Fi MAC, which does the same. Nothing is padded here. + self.counters.tx_frames += 1; + self.send(self.tx[0..len]); + } + + fn ethHeader(self: *Stack, dst: Mac, ethertype: EtherType) void { + wrMac(&self.tx, eth.dst, dst); + wrMac(&self.tx, eth.src, self.mac); + wr16(&self.tx, eth.ethertype, @intFromEnum(ethertype)); + } + + /// Build and send an IPv4 datagram whose payload the caller has already written to + /// `self.tx[eth_hlen + ip4.hlen ..]`. Returns false if the destination's MAC is unknown, in + /// which case an ARP request has been sent and the datagram is dropped. + /// + /// Dropping rather than queueing is lwIP's `ETHARP_SUPPORT_STATIC_ENTRIES`-less behaviour minus + /// its one-packet queue (`core/ipv4/etharp.c`, `etharp_query`). Nothing here needs the queue: + /// DHCP is broadcast, ICMP replies go to a peer whose MAC just arrived in the request, and TCP + /// resolves the peer before the SYN is built (`TcpState.arp_wait`). + fn emitIp(self: *Stack, src: Ip4, dst: Ip4, proto: Protocol, payload_len: usize) bool { + assert(payload_len <= mtu - ip4.hlen); + const total: u16 = @intCast(ip4.hlen + payload_len); + + const dst_mac = self.routeMac(dst) orelse { + self.counters.tx_dropped += 1; + return false; + }; + self.ethHeader(dst_mac, .ip4); + + const h = self.tx[eth_hlen..][0..ip4.hlen]; + h[ip4.v_hl] = 0x45; // IPv4, 5 words of header, no options + h[ip4.tos] = 0; + wr16(h, ip4.total_len, total); + wr16(h, ip4.id, self.ip_id); + self.ip_id +%= 1; + // DF set: this stack neither fragments what it sends nor reassembles what it receives, so + // saying so is more useful than letting a router fragment a datagram we cannot rebuild. + wr16(h, ip4.frag, ip4.flag_df); + h[ip4.ttl] = 64; // RFC 1122 3.2.1.7 recommends 64 + h[ip4.proto] = @intFromEnum(proto); + wr16(h, ip4.chksum, 0); + wrIp(h, ip4.src, src); + wrIp(h, ip4.dst, dst); + wr16(h, ip4.chksum, checksum(h)); + + self.emitFrame(eth_hlen + total); + return true; + } + + /// The MAC a datagram for `dst` must be sent to: broadcast for a broadcast address, the peer + /// itself if it is on-link, otherwise the gateway. `null` means unresolved, and an ARP request + /// has been sent. + fn routeMac(self: *Stack, dst: Ip4) ?Mac { + if (std.mem.eql(u8, &dst, &ip_broadcast)) return mac_broadcast; + if (self.addr != null) { + // Subnet broadcast. + var all_ones = true; + var i: usize = 0; + while (i < 4) : (i += 1) { + if (dst[i] | self.mask[i] != 0xff) all_ones = false; + } + if (all_ones and self.onLink(dst)) return mac_broadcast; + } + const next = if (self.onLink(dst)) dst else self.gw; + if (self.arpLookup(next)) |m| return m; + self.arpRequest(next); + return null; + } + + // ================================================================================= ARP + + /// An entry's timestamp is *not* refreshed by a lookup, only by an ARP packet from that host. + /// Refreshing on use looks like a cheap optimisation and is a real bug: an entry kept alive by + /// our own traffic is never re-resolved, so a gateway whose MAC changes - VRRP failover, a + /// replaced router, a roam to a different AP with a different BSSID-derived address - is never + /// noticed, and every frame goes to a MAC that no longer answers. Ageing out after + /// `arp_max_age_ms` of no ARP traffic from that host costs one dropped segment and a + /// retransmission; getting it wrong costs the connection. + fn arpLookup(self: *Stack, target: Ip4) ?Mac { + for (&self.arp_cache) |*e| { + if (!e.valid()) continue; + if (self.now_ms -% e.stamp_ms > arp_max_age_ms) { + e.stamp_ms = 0; + continue; + } + if (std.mem.eql(u8, &e.ip, &target)) return e.mac; + } + return null; + } + + /// Insert or refresh. `insert` false means "update only if already known", which is how a + /// four-entry cache survives a busy /24: every ARP request on the segment is a broadcast, and a + /// cache that admitted all of them would evict the gateway within seconds. lwIP draws the same + /// line with `ETHARP_FLAG_TRY_HARD` (`core/ipv4/etharp.c`, `etharp_update_arp_entry`). + fn arpStore(self: *Stack, target: Ip4, hw: Mac, insert: bool) void { + if (std.mem.eql(u8, &target, &ip_any)) return; + if (std.mem.eql(u8, &target, &ip_broadcast)) return; + for (&self.arp_cache) |*e| { + if (e.valid() and std.mem.eql(u8, &e.ip, &target)) { + e.mac = hw; + e.stamp_ms = self.now_ms; + return; + } + } + if (!insert) return; + // Free slot, else the least recently used. + var victim: *ArpEntry = &self.arp_cache[0]; + for (&self.arp_cache) |*e| { + if (!e.valid()) { + victim = e; + break; + } + if (e.stamp_ms < victim.stamp_ms) victim = e; + } + victim.* = .{ .ip = target, .mac = hw, .stamp_ms = self.now_ms }; + } + + fn arpEmit(self: *Stack, opcode: u16, target_ip: Ip4, target_mac: Mac, dst_mac: Mac, spa: Ip4) void { + self.ethHeader(dst_mac, .arp); + const h = self.tx[eth_hlen..][0..arp.len]; + wr16(h, arp.hwtype, arp.hwtype_ethernet); + wr16(h, arp.proto, @intFromEnum(EtherType.ip4)); + h[arp.hwlen] = 6; + h[arp.protolen] = 4; + wr16(h, arp.opcode, opcode); + wrMac(h, arp.sha, self.mac); + wrIp(h, arp.spa, spa); + wrMac(h, arp.tha, target_mac); + wrIp(h, arp.tpa, target_ip); + self.counters.arp_tx += 1; + self.emitFrame(eth_hlen + arp.len); + } + + fn arpRequest(self: *Stack, target: Ip4) void { + // RFC 826: the target hardware address of a request is "don't care"; zero is conventional. + self.arpEmit(arp.op_request, target, @splat(0), mac_broadcast, self.addr orelse ip_any); + } + + /// Gratuitous ARP: a broadcast request for our own address, which every listener treats as + /// "this MAC now owns this IP". Sent when an address is acquired, so the gateway and the AP + /// learn us without waiting to need us. RFC 5227 2.3. + fn announce(self: *Stack) void { + const a = self.addr orelse return; + self.arpEmit(arp.op_request, a, @splat(0), mac_broadcast, a); + } + + fn arpInput(self: *Stack, body: []const u8) void { + if (body.len < arp.len) { + self.counters.rx_dropped += 1; + return; + } + // RFC 826 "Packet Reception", exactly the four checks lwIP makes at + // `core/ipv4/etharp.c:656-659`. + if (rd16(body, arp.hwtype) != arp.hwtype_ethernet or + rd16(body, arp.proto) != @intFromEnum(EtherType.ip4) or + body[arp.hwlen] != 6 or body[arp.protolen] != 4) + { + self.counters.rx_dropped += 1; + return; + } + self.counters.arp_rx += 1; + + const spa = rdIp(body, arp.spa); + const sha = rdMac(body, arp.sha); + const tpa = rdIp(body, arp.tpa); + const for_us = if (self.addr) |a| std.mem.eql(u8, &tpa, &a) else false; + + // Learn the sender. Admitted to a free slot only when the packet was addressed to us - + // either a request we must answer or the reply to a request we sent. + self.arpStore(spa, sha, for_us); + + if (rd16(body, arp.opcode) == arp.op_request and for_us) { + // A reply goes back to the requester, not to the broadcast address. + self.arpEmit(arp.op_reply, spa, sha, sha, self.addr.?); + } + } + + // =============================================================================== input + + /// A received Ethernet frame. Everything this stack does in response happens before this + /// returns, including any frame it sends. + pub fn onFrame(self: *Stack, frame: []const u8) void { + self.counters.rx_frames += 1; + if (frame.len < eth_hlen or frame.len > frame_max) { + self.counters.rx_dropped += 1; + return; + } + const dst = rdMac(frame, eth.dst); + // The C6's MAC filter should already have done this, but a promiscuous or misconfigured + // transport would otherwise have this stack answering ARP for other stations. + if (!std.mem.eql(u8, &dst, &self.mac) and !std.mem.eql(u8, &dst, &mac_broadcast)) { + self.counters.rx_dropped += 1; + return; + } + const body = frame[eth_hlen..]; + switch (@as(EtherType, @enumFromInt(rd16(frame, eth.ethertype)))) { + .arp => self.arpInput(body), + .ip4 => self.ip4Input(body), + // .vlan lands here: an 802.1Q tag would need the 4-byte shim skipped and the real + // ethertype read from behind it. Nothing on this board tags frames, so it is dropped + // rather than half-handled. + else => self.counters.rx_dropped += 1, + } + } + + fn ip4Input(self: *Stack, body: []const u8) void { + if (body.len < ip4.hlen) { + self.counters.rx_dropped += 1; + return; + } + if (body[ip4.v_hl] >> 4 != 4) { + self.counters.rx_dropped += 1; + return; + } + const hlen = @as(usize, body[ip4.v_hl] & 0x0f) * 4; + if (hlen < ip4.hlen or hlen > body.len) { + self.counters.rx_dropped += 1; + return; + } + if (checksum(body[0..hlen]) != 0) { + self.counters.checksum_bad += 1; + return; + } + const total = rd16(body, ip4.total_len); + if (total < hlen or total > body.len) { + // Shorter than claimed: truncated. Longer than claimed happens legitimately - a + // 60-byte minimum-length Ethernet frame padding a 28-byte datagram - and is handled by + // trusting `total` below, but a frame shorter than its own IP header claims is junk. + self.counters.rx_dropped += 1; + return; + } + const frag = rd16(body, ip4.frag); + if (frag & (ip4.flag_mf | ip4.offset_mask) != 0) { + // A fragment. Reassembly is out of scope, and accepting the first fragment as a whole + // datagram would be worse than dropping it. + self.counters.rx_dropped += 1; + return; + } + + const src = rdIp(body, ip4.src); + const dst = rdIp(body, ip4.dst); + const proto: Protocol = @enumFromInt(body[ip4.proto]); + const payload = body[hlen..total]; + + if (!self.forUs(dst)) { + // One exception, and it is the reason DHCP works at all: a server may unicast its + // OFFER or ACK to the address it is about to grant, which is not yet ours, at a MAC + // that is. RFC 2131 4.1 permits exactly this. So while unbound, UDP is let through to + // the demultiplexer, which will only match the DHCP client port. + const dhcp_pending = self.addr == null and self.dhcp.state != .off; + if (!(dhcp_pending and proto == .udp)) { + self.counters.rx_dropped += 1; + return; + } + } + + switch (proto) { + .icmp => self.icmpInput(src, dst, payload), + .udp => self.udpInput(src, dst, payload), + .tcp => self.tcpInput(src, dst, payload), + else => self.counters.rx_dropped += 1, + } + } + + // ================================================================================ ICMP + + fn icmpInput(self: *Stack, src: Ip4, dst: Ip4, payload: []const u8) void { + if (payload.len < icmp.hlen) { + self.counters.rx_dropped += 1; + return; + } + // ICMP has no pseudo-header (RFC 792): the checksum covers the message alone. + if (checksum(payload) != 0) { + self.counters.checksum_bad += 1; + return; + } + if (payload[icmp.type_] != icmp.echo_request) { + // Destination-unreachable and time-exceeded carry useful information that nothing here + // consumes; a stack with no routing decisions to revise has nothing to do with them. + self.counters.rx_dropped += 1; + return; + } + // A request addressed to the broadcast address is answered from our own address only; a + // reply sourced from a broadcast address is malformed and some hosts treat it as an attack. + if (self.addr == null) return; + if (payload.len > mtu - ip4.hlen) { + // Would need fragmenting to answer. `ping -s 1473` from the development host lands + // here as a fragmented request and is already dropped above; this covers the rest. + self.counters.rx_dropped += 1; + return; + } + _ = dst; + + const out = self.tx[eth_hlen + ip4.hlen ..][0..payload.len]; + @memcpy(out, payload); + out[icmp.type_] = icmp.echo_reply; + out[icmp.code] = 0; + wr16(out, icmp.chksum, 0); + wr16(out, icmp.chksum, checksum(out)); + self.counters.icmp_echo += 1; + _ = self.emitIp(self.addr.?, src, .icmp, payload.len); + } + + // ================================================================================= UDP + + fn udpInput(self: *Stack, src: Ip4, dst: Ip4, payload: []const u8) void { + if (payload.len < udp.hlen) { + self.counters.rx_dropped += 1; + return; + } + const ulen = rd16(payload, udp.len); + if (ulen < udp.hlen or ulen > payload.len) { + self.counters.rx_dropped += 1; + return; + } + const datagram = payload[0..ulen]; + if (!transportChecksumOk(src, dst, .udp, datagram, rd16(datagram, udp.chksum))) { + self.counters.checksum_bad += 1; + return; + } + self.counters.udp_rx += 1; + + const sport = rd16(datagram, udp.src_port); + const dport = rd16(datagram, udp.dst_port); + const data = datagram[udp.hlen..]; + if (dport == dhcp.client_port) { + self.dhcpInput(src, data); + } else if (self.query.phase == .waiting and dport == self.query.local_port) { + self.dnsInput(src, sport, data); + } else { + // No sockets, so nothing else has a port. A real stack would answer with ICMP port + // unreachable; announcing which ports are closed is of no use to this device. + self.counters.rx_dropped += 1; + } + } + + /// Send a UDP datagram. `src` may be `0.0.0.0`, which DHCP needs before it has an address. + fn emitUdp(self: *Stack, src: Ip4, sport: u16, dst: Ip4, dport: u16, data_len: usize) bool { + const seg_len = udp.hlen + data_len; + assert(seg_len <= mtu - ip4.hlen); + const seg = self.tx[eth_hlen + ip4.hlen ..][0..seg_len]; + wr16(seg, udp.src_port, sport); + wr16(seg, udp.dst_port, dport); + wr16(seg, udp.len, @intCast(seg_len)); + wr16(seg, udp.chksum, 0); + wr16(seg, udp.chksum, udpChecksumOnWire(transportChecksum(src, dst, .udp, seg))); + return self.emitIp(src, dst, .udp, seg_len); + } + + // ================================================================================ DHCP + + /// Begin acquiring an address. Idempotent while an acquisition is in progress; a call while + /// bound restarts from DISCOVER. + pub fn dhcpStart(self: *Stack) void { + self.addr = null; + self.mask = ip_any; + self.gw = ip_any; + self.dns = null; + // The resolver is gone with the lease, so anything in flight to it is abandoned rather + // than left to time out against a server this stack no longer believes in. + self.query.phase = .idle; + self.dhcp = .{ + .state = .selecting, + .xid = self.draw(), + .started_ms = self.now_ms, + }; + self.dhcpSend(dhcp.discover); + self.dhcp.tries = 1; + self.dhcp.retry_ms = self.now_ms + dhcp_backoff_ms[0]; + } + + /// Options are appended through this so a length byte can never be written by hand. + const OptWriter = struct { + buf: []u8, + i: usize = 0, + + fn raw(self: *OptWriter, code: u8, value: []const u8) void { + assert(value.len <= 255); + assert(self.i + 2 + value.len <= self.buf.len); + self.buf[self.i] = code; + self.buf[self.i + 1] = @intCast(value.len); + @memcpy(self.buf[self.i + 2 ..][0..value.len], value); + self.i += 2 + value.len; + } + fn byte(self: *OptWriter, code: u8, v: u8) void { + self.raw(code, &[_]u8{v}); + } + fn word(self: *OptWriter, code: u8, v: u16) void { + var t: [2]u8 = undefined; + std.mem.writeInt(u16, &t, v, .big); + self.raw(code, &t); + } + fn address(self: *OptWriter, code: u8, v: Ip4) void { + self.raw(code, &v); + } + fn end(self: *OptWriter) void { + assert(self.i < self.buf.len); + self.buf[self.i] = dhcp.opt_end; + self.i += 1; + } + }; + + /// Build and send one DHCP message. The RFC 2131 4.3.6 table is what decides which fields are + /// set: it is the part of DHCP that servers actually enforce, and getting `ciaddr` or the + /// server identifier wrong produces a NAK rather than an error message. + fn dhcpSend(self: *Stack, kind: u8) void { + const msg = self.tx[eth_hlen + ip4.hlen + udp.hlen ..][0..dhcp_min_msg_len]; + @memset(msg, 0); + + const renewing = self.dhcp.state == .renewing; + const rebinding = self.dhcp.state == .rebinding; + // RENEWING and REBINDING carry the bound address in `ciaddr` and no requested-IP option; + // SELECTING and REQUESTING carry zero and use option 50. lwIP makes the same distinction + // at `core/ipv4/dhcp.c:2026-2030`. + const use_ciaddr = renewing or rebinding; + + msg[dhcp.op] = dhcp.bootrequest; + msg[dhcp.htype] = @intCast(arp.hwtype_ethernet); + msg[dhcp.hlen] = 6; + msg[dhcp.hops] = 0; + wr32(msg, dhcp.xid, self.dhcp.xid); + wr16(msg, dhcp.secs, @intCast(@min(0xffff, (self.now_ms -% self.dhcp.started_ms) / 1000))); + // Ask the server to broadcast its reply. lwIP clears this flag + // (`core/ipv4/dhcp.c:2024-2025`: "we don't need the broadcast flag since we can receive + // unicast traffic before being fully configured"), and so can this stack - `ip4Input` has + // the explicit exemption for it. The flag is set anyway because a broadcast reply is the + // path with the fewest ways to fail on first bring-up: it needs no ARP entry at the server, + // no unicast-to-unconfigured-host handling in the AP, and no exemption in this file. + wr16(msg, dhcp.flags, dhcp.flag_broadcast); + if (use_ciaddr) wrIp(msg, dhcp.ciaddr, self.addr orelse ip_any); + @memcpy(msg[dhcp.chaddr..][0..6], &self.mac); + wr32(msg, dhcp.cookie, dhcp.magic_cookie); + + var o: OptWriter = .{ .buf = msg[dhcp.options..] }; + o.byte(dhcp.opt_msg_type, kind); + // RFC 2131 3.5: the maximum message size we can reassemble. One MTU minus the headers, + // which for this stack is also the largest datagram it can receive at all. + o.word(dhcp.opt_max_msg_size, @intCast(mtu - ip4.hlen - udp.hlen)); + if (kind == dhcp.request and !use_ciaddr) { + o.address(dhcp.opt_requested_ip, self.dhcp.offered); + o.address(dhcp.opt_server_id, self.dhcp.server); + } + // RFC 2131 4.3.6: a REQUEST in RENEWING/REBINDING must not carry a server identifier. + o.raw(dhcp.opt_param_list, &[_]u8{ + dhcp.opt_subnet_mask, + dhcp.opt_router, + dhcp.opt_dns, + dhcp.opt_lease_time, + dhcp.opt_t1, + dhcp.opt_t2, + }); + o.raw(dhcp.opt_hostname, "esp32p4"); + o.end(); + // Everything past the END option stays zero: RFC 2131 4.1 pads with option 0. + + const src = if (use_ciaddr) (self.addr orelse ip_any) else ip_any; + // RENEWING unicasts to the server that granted the lease; every other message is broadcast + // (RFC 2131 4.3.6, 4.4.5). + const dst = if (renewing) self.dhcp.server else ip_broadcast; + self.counters.dhcp_tx += 1; + _ = self.emitUdp(src, dhcp.client_port, dst, dhcp.server_port, dhcp_min_msg_len); + } + + /// One parsed option, or the end of the list. + const Opt = struct { code: u8, value: []const u8 }; + + /// Walk a DHCP option list. Stops at END, at a truncated option, or at the end of the buffer - + /// a malformed length must not walk off the datagram, which is the classic DHCP parser bug. + fn dhcpOption(body: []const u8, want: u8) ?[]const u8 { + if (body.len <= dhcp.options) return null; + var i: usize = dhcp.options; + while (i < body.len) { + const code = body[i]; + if (code == dhcp.opt_end) return null; + if (code == dhcp.opt_pad) { + i += 1; + continue; + } + if (i + 2 > body.len) return null; + const len = body[i + 1]; + if (i + 2 + len > body.len) return null; + if (code == want) return body[i + 2 ..][0..len]; + i += 2 + len; + } + return null; + } + + fn dhcpOptionIp(body: []const u8, want: u8) ?Ip4 { + const v = dhcpOption(body, want) orelse return null; + if (v.len < 4) return null; + return v[0..4].*; + } + + fn dhcpOptionU32(body: []const u8, want: u8) ?u32 { + const v = dhcpOption(body, want) orelse return null; + if (v.len != 4) return null; + return std.mem.readInt(u32, v[0..4], .big); + } + + fn dhcpInput(self: *Stack, src: Ip4, body: []const u8) void { + if (self.dhcp.state == .off) return; + if (body.len < dhcp.options) { + self.counters.rx_dropped += 1; + return; + } + if (body[dhcp.op] != dhcp.bootreply) return; + if (rd32(body, dhcp.cookie) != dhcp.magic_cookie) return; + if (rd32(body, dhcp.xid) != self.dhcp.xid) return; + // The reply must be about our hardware address, not a relayed one for someone else. + if (body[dhcp.hlen] != 6 or !std.mem.eql(u8, body[dhcp.chaddr..][0..6], &self.mac)) return; + + const kind_opt = dhcpOption(body, dhcp.opt_msg_type) orelse return; + if (kind_opt.len != 1) return; + self.counters.dhcp_rx += 1; + + switch (kind_opt[0]) { + dhcp.offer => { + if (self.dhcp.state != .selecting) return; + self.dhcp.offered = rdIp(body, dhcp.yiaddr); + if (std.mem.eql(u8, &self.dhcp.offered, &ip_any)) return; + // Option 54 is how the REQUEST names which offer it accepts. A server that omits + // it is out of spec; `siaddr` is the best fallback, and the sender is the last. + self.dhcp.server = dhcpOptionIp(body, dhcp.opt_server_id) orelse blk: { + const s = rdIp(body, dhcp.siaddr); + break :blk if (std.mem.eql(u8, &s, &ip_any)) src else s; + }; + self.dhcp.state = .requesting; + self.dhcpSend(dhcp.request); + self.dhcp.tries = 1; + self.dhcp.retry_ms = self.now_ms + dhcp_backoff_ms[0]; + }, + dhcp.ack => { + switch (self.dhcp.state) { + .requesting, .renewing, .rebinding => {}, + else => return, + } + const granted = rdIp(body, dhcp.yiaddr); + if (std.mem.eql(u8, &granted, &ip_any)) return; + self.dhcpBind(body, granted, src); + }, + dhcp.nak => { + switch (self.dhcp.state) { + .requesting, .renewing, .rebinding => {}, + else => return, + } + // RFC 2131 4.4.5: a NAK sends the client back to INIT. The lease is gone, so the + // address goes with it - continuing to use it would be squatting. + self.dhcpStart(); + }, + else => {}, + } + } + + fn dhcpBind(self: *Stack, body: []const u8, granted: Ip4, src: Ip4) void { + self.addr = granted; + self.mask = dhcpOptionIp(body, dhcp.opt_subnet_mask) orelse .{ 255, 255, 255, 0 }; + self.gw = dhcpOptionIp(body, dhcp.opt_router) orelse ip_any; + self.dns = dhcpOptionIp(body, dhcp.opt_dns); + if (dhcpOptionIp(body, dhcp.opt_server_id)) |s| self.dhcp.server = s else if (std.mem.eql(u8, &self.dhcp.server, &ip_any)) { + self.dhcp.server = src; + } + + // RFC 2131 3.3. A server that sends no lease time is out of spec; an hour is a safe + // assumption, being short enough that a wrong guess self-corrects. + const lease = dhcpOptionU32(body, dhcp.opt_lease_time) orelse 3600; + self.dhcp.lease_s = lease; + if (lease == 0xffff_ffff) { + // Infinite lease: never renew. + self.dhcp.t1_ms = std.math.maxInt(u64); + self.dhcp.t2_ms = std.math.maxInt(u64); + self.dhcp.expire_ms = std.math.maxInt(u64); + } else { + // The server may state T1 and T2 itself; otherwise lwIP's derivation, which is RFC + // 2131 4.4.5's: half the lease, and seven eighths of it + // (`core/ipv4/dhcp.c:757` and `:766`). + const t1 = dhcpOptionU32(body, dhcp.opt_t1) orelse lease / 2; + const t2 = dhcpOptionU32(body, dhcp.opt_t2) orelse (lease / 8) * 7; + const base = self.now_ms; + self.dhcp.t1_ms = base + @as(u64, @min(t1, lease)) * 1000; + self.dhcp.t2_ms = base + @as(u64, @min(t2, lease)) * 1000; + self.dhcp.expire_ms = base + @as(u64, lease) * 1000; + } + self.dhcp.state = .bound; + self.dhcp.tries = 0; + self.dhcp.retry_ms = 0; + self.announce(); + } + + fn dhcpTick(self: *Stack) void { + // T1 while bound: start renewing. RFC 2131 4.4.5 requires a fresh transaction id, and the + // first REQUEST goes out on this same tick rather than one backoff later - a state change + // that transmits nothing is how a lease quietly expires while the client thinks it is + // renewing. + if (self.dhcp.state == .bound and self.now_ms >= self.dhcp.t1_ms) { + self.dhcp.state = .renewing; + self.dhcp.xid = self.draw(); + self.dhcp.started_ms = self.now_ms; + self.dhcp.tries = 0; + self.dhcp.retry_ms = 0; + } + switch (self.dhcp.state) { + .off, .bound => return, + .selecting, .requesting, .renewing, .rebinding => {}, + } + if (self.dhcp.state == .renewing and self.now_ms >= self.dhcp.t2_ms) { + // T2: the granting server is not answering. Ask anyone. + self.dhcp.state = .rebinding; + self.dhcp.tries = 0; + self.dhcp.retry_ms = 0; + } + if ((self.dhcp.state == .renewing or self.dhcp.state == .rebinding) and + self.now_ms >= self.dhcp.expire_ms) + { + // The lease is over. Give up the address before asking again: keeping it would mean + // using an address the server may already have given away. + self.dhcpStart(); + return; + } + if (self.dhcp.retry_ms != 0 and self.now_ms < self.dhcp.retry_ms) return; + const kind: u8 = if (self.dhcp.state == .selecting) dhcp.discover else dhcp.request; + self.dhcpSend(kind); + const idx = @min(self.dhcp.tries, dhcp_backoff_ms.len - 1); + self.dhcp.retry_ms = self.now_ms + dhcp_backoff_ms[idx]; + if (self.dhcp.tries < 255) self.dhcp.tries += 1; + } + + // ================================================================================= DNS + // + // One question, QTYPE=A, QCLASS=IN, recursion desired, over the UDP above. No cache, no + // search list, no NS or SOA handling, no TCP fallback on a truncated answer: this resolves + // the one name a device that fetches one URL has to resolve, and says so with a named error + // when it cannot. + // + // The hard part of DNS parsing is not the header, it is that a name in a resource record may + // be a compression pointer into anywhere earlier in the message (RFC 1035 4.1.4). A parser + // that follows those without a bound hangs on a message that points at itself, and such a + // message costs an attacker two bytes. `dnsSkipName` is where that is dealt with. + + /// Encode a dotted name into RFC 1035 4.1.2 wire form: each label prefixed with its length, + /// terminated by the zero-length root label. Returns the encoded length. + /// + /// `out` must be at least `dns_qname_max`, which the length check below makes sufficient: a + /// name of `n` text bytes with no trailing dot encodes to exactly `n + 2`. + fn dnsEncodeName(name: []const u8, out: []u8) DnsError!usize { + assert(out.len >= dns_qname_max); + if (name.len > dns_name_max) return error.NameTooLong; + // A trailing dot is the root label written out, and `example.com.` names the same node as + // `example.com`. Everything after it - an empty final label - is not. + var rest = name; + if (rest.len != 0 and rest[rest.len - 1] == '.') rest = rest[0 .. rest.len - 1]; + if (rest.len == 0) return error.NameInvalid; + + var o: usize = 0; + var labels = std.mem.splitScalar(u8, rest, '.'); + while (labels.next()) |label| { + // An empty label inside a name (`a..b`, or a leading dot) is not a name. + if (label.len == 0 or label.len > dns.label_max) return error.NameInvalid; + out[o] = @intCast(label.len); + @memcpy(out[o + 1 ..][0..label.len], label); + o += 1 + label.len; + } + out[o] = 0; + return o + 1; + } + + /// Compare an encoded name against the question we asked, ASCII-case-insensitively. RFC 4343: + /// label comparison ignores case, and a resolver is entitled to answer `0X4200.CAFE` to a + /// question about `0x4200.cafe`. Length bytes are 0-63 and so are never touched by the fold. + fn dnsQNameEql(a: []const u8, b: []const u8) bool { + if (a.len != b.len) return false; + for (a, b) |x, y| if (std.ascii.toLower(x) != std.ascii.toLower(y)) return false; + return true; + } + + /// Step over the name at `start` and return the offset of the byte after it - which for a + /// name that ends in a compression pointer is two bytes after the pointer, *not* wherever the + /// pointer led. `null` means the name is unparseable and the message is to be rejected. + /// + /// **Why this terminates.** Two independent bounds, because one of them is not enough: + /// + /// * A pointer must point strictly backwards (`target < here`). That alone is the check + /// most implementations stop at, and it is *not* sufficient: after jumping back the walk + /// moves forward again over labels, so a pointer at offset 12 to offset 10 and a label at + /// 10 that is two bytes long lands back at 12, and the pair loops forever with every + /// individual jump going backwards. + /// * So the jumps themselves are counted, and `dns_max_jumps` of them ends the name. That + /// is the bound that actually holds: the loop below does at most `dns_max_jumps` jumps + /// and, between them, walks labels whose lengths are positive, so it visits at most + /// `dns_max_jumps * msg.len` bytes and stops. A legitimate answer uses one jump per name. + fn dnsSkipName(msg: []const u8, start: usize) ?usize { + var i = start; + var jumps: u8 = 0; + // The offset after the name in the *message*, fixed by the first pointer taken. + var after: ?usize = null; + while (true) { + if (i >= msg.len) return null; + const len = msg[i]; + if (len & dns.ptr_mask == dns.ptr_mask) { + if (i + 1 >= msg.len) return null; + const target = (@as(usize, len & 0x3f) << 8) | msg[i + 1]; + if (after == null) after = i + 2; + if (target >= i) return null; + jumps += 1; + if (jumps > dns_max_jumps) return null; + i = target; + continue; + } + // 0x40 and 0x80 are the reserved label types of RFC 1035 4.1.4 / RFC 6891; neither is + // something this stack can skip a known number of bytes past, so neither is accepted. + if (len & dns.ptr_mask != 0) return null; + if (len == 0) return after orelse i + 1; + i += 1 + @as(usize, len); + if (i > msg.len) return null; + } + } + + /// Build and send the query held in `self.query`. Called for the first transmission and for + /// every retransmission, from the same fields, so the two cannot drift apart. + fn dnsSend(self: *Stack) void { + const src = self.addr orelse return; + const server = self.dns orelse return; + const qn_len: usize = self.query.qname_len; + const msg_len = dns.hlen + qn_len + 4; + const msg = self.tx[eth_hlen + ip4.hlen + udp.hlen ..][0..msg_len]; + wr16(msg, dns.id, self.query.id); + // RD only. Not AD, not CD, not EDNS0: this asks a recursive resolver for one A record and + // has nothing to validate with. + wr16(msg, dns.flags, dns.flag_rd); + wr16(msg, dns.qdcount, 1); + wr16(msg, dns.ancount, 0); + wr16(msg, dns.nscount, 0); + wr16(msg, dns.arcount, 0); + @memcpy(msg[dns.hlen..][0..qn_len], self.query.qname[0..qn_len]); + wr16(msg, dns.hlen + qn_len, dns.type_a); + wr16(msg, dns.hlen + qn_len + 2, dns.class_in); + self.counters.dns_tx += 1; + _ = self.emitUdp(src, self.query.local_port, server, dns.port, msg_len); + } + + fn dnsFail(self: *Stack, e: DnsError) void { + self.query.phase = .failed; + self.query.err = e; + } + + /// A datagram to the port the outstanding query was sent from. Called from inside `onFrame`. + /// + /// Everything that does not match the query is *ignored*, not failed: on a real network the + /// port this query owns will collect late answers to previous queries, scans, and whatever + /// else is loose on the segment, and any of those failing the query would be a denial of + /// service that costs one packet. Only a response that matches the source, the id and the + /// question can decide the query - and then it decides it either way. + fn dnsInput(self: *Stack, src: Ip4, sport: u16, msg: []const u8) void { + const server = self.dns orelse return; + if (!std.mem.eql(u8, &src, &server)) return; + if (sport != dns.port) return; + if (msg.len < dns.hlen) return; + if (rd16(msg, dns.id) != self.query.id) return; + + const flags = rd16(msg, dns.flags); + if (flags & dns.flag_qr == 0) return; // a query, not a response + if (rd16(msg, dns.qdcount) != 1) return; + + // The question, echoed. A server that answers a different question - or an attacker who + // guessed the id and the port but not the name - is not answering this. + const qn = self.query.qname[0..self.query.qname_len]; + var off = dns.hlen + qn.len + 4; + if (msg.len < off) return; + if (!dnsQNameEql(msg[dns.hlen..][0..qn.len], qn)) return; + if (rd16(msg, dns.hlen + qn.len) != dns.type_a) return; + if (rd16(msg, dns.hlen + qn.len + 2) != dns.class_in) return; + + self.counters.dns_rx += 1; + + const rcode = flags & dns.rcode_mask; + if (rcode != 0) { + self.dnsFail(if (rcode == dns.rcode_name_error) error.NameNotFound else error.DnsRefused); + return; + } + + // Walk the answer section and take the first A record. Walking rather than reading the + // first record is what makes a CNAME chain work: `0x4200.cafe` may answer with the CNAME + // and the A together, in that order, and a resolver that reads answer[0] gets a name. + var left = rd16(msg, dns.ancount); + while (left != 0) : (left -= 1) { + off = dnsSkipName(msg, off) orelse { + self.dnsFail(error.DnsMalformed); + return; + }; + if (off + dns.rr_fixed > msg.len) { + self.dnsFail(error.DnsMalformed); + return; + } + const rtype = rd16(msg, off); + const rclass = rd16(msg, off + 2); + const rdlen: usize = rd16(msg, off + 8); + off += dns.rr_fixed; + if (off + rdlen > msg.len) { + self.dnsFail(error.DnsMalformed); + return; + } + if (rtype == dns.type_a and rclass == dns.class_in and rdlen == 4) { + self.query.result = rdIp(msg, off); + self.query.phase = .done; + return; + } + off += rdlen; + } + // A well-formed answer with no A record in it: NODATA, or a CNAME chain this stack will + // not chase a second query down. + self.dnsFail(error.NameNotFound); + } + + fn dnsTick(self: *Stack) void { + if (self.query.phase != .waiting) return; + if (self.now_ms < self.query.retry_ms) return; + if (self.query.tries >= dns_backoff_ms.len) { + self.dnsFail(error.TimedOut); + return; + } + self.query.retry_ms = self.now_ms + dns_backoff_ms[self.query.tries]; + self.query.tries += 1; + self.counters.dns_retx += 1; + self.dnsSend(); + } + + /// Resolve `name` to an IPv4 address. + /// + /// **The protocol is `httpGet`'s, deliberately.** There is no clock and no `std.Io` here, so + /// there is nothing for a blocking call to block on: the first call sends the query and + /// returns `error.WouldBlock`, and the caller drives `tick` and `onFrame` and calls again + /// with the same name until an address or a real error comes back. + /// + /// const addr = while (true) { + /// stack.tick(hal.systimer.millis()); + /// while (transport.next()) |frame| stack.onFrame(frame); + /// if (stack.resolve("0x4200.cafe")) |a| break a + /// else |e| if (e != error.WouldBlock) return e; + /// }; + /// + /// The wait is bounded whether or not the caller bounds it: `dns_backoff_ms` retransmits + /// three times over 7 s and then answers `error.TimedOut`. Nothing here waits forever, and + /// the retransmissions happen in `tick`, so a caller that ticks and polls rarely still gets + /// them on time. + /// + /// One query is outstanding at a time. A call naming something else while one is in flight is + /// `error.Busy`; a call naming something else after one has finished starts a new query, + /// which is what makes the loop above safe to write for two names in a row. + pub fn resolve(self: *Stack, name: []const u8) DnsError!Ip4 { + // Encoded first, and compared in encoded form: `0x4200.cafe`, `0x4200.cafe.` and + // `0X4200.CAFE` are one name, and a caller that spells it differently between two polls + // of the same loop must not get `error.Busy` for it. + var wire: [dns_qname_max]u8 = undefined; + const wire_len = try dnsEncodeName(name, &wire); + const same = self.query.qname_len == wire_len and + dnsQNameEql(self.query.qname[0..wire_len], wire[0..wire_len]); + + switch (self.query.phase) { + .idle => {}, + .waiting => { + if (!same) return error.Busy; + return error.WouldBlock; + }, + // A finished query for this name is collected and the slot released. A finished query + // for a different name falls through and is replaced. + .done => if (same) { + self.query.phase = .idle; + return self.query.result; + }, + .failed => if (same) { + self.query.phase = .idle; + return self.query.err; + }, + } + + if (self.addr == null) return error.NoAddress; + if (self.dns == null) return error.NoDnsServer; + + @memcpy(self.query.qname[0..wire_len], wire[0..wire_len]); + self.query.qname_len = @intCast(wire_len); + self.query.id = @truncate(self.draw()); + // RFC 6335's dynamic range, as `tcpConnect` uses. Redrawn per query so a late answer to + // the previous one cannot be mistaken for this one even if the id happens to repeat. + self.query.local_port = @intCast(49152 + self.draw() % (65535 - 49152 + 1)); + self.query.result = ip_any; + self.query.err = error.WouldBlock; + self.query.phase = .waiting; + self.query.tries = 1; + self.query.retry_ms = self.now_ms + dns_backoff_ms[0]; + self.dnsSend(); + return error.WouldBlock; + } + + // ================================================================================= TCP + // + // One connection, client side only, one unacknowledged segment at a time. The send side is a + // single static buffer holding the whole request, so "retransmission" is always "send from + // `snd_una` again" and there is no retransmission queue. The receive side has no reassembly + // buffer at all: a segment that is not the next one expected is answered with a duplicate ACK + // and dropped. Three of those is a fast-retransmit signal to any modern peer, so the common + // case of one lost segment costs a round trip rather than an RTO - but a reordered segment + // costs a retransmission that a reassembly buffer would have avoided. That is the price of not + // having one, and on a Wi-Fi link where reordering is rare it is the right price. + + fn emitTcp(self: *Stack, flags: u8, seq: u32, data: []const u8, mss_opt: bool) bool { + const src = self.addr orelse return false; + const opt_len: usize = if (mss_opt) 4 else 0; + const seg_len = tcp.hlen + opt_len + data.len; + assert(seg_len <= mtu - ip4.hlen); + const seg = self.tx[eth_hlen + ip4.hlen ..][0..seg_len]; + + wr16(seg, tcp.src_port, self.tcp.local_port); + wr16(seg, tcp.dst_port, self.tcp.peer_port); + wr32(seg, tcp.seq, seq); + wr32(seg, tcp.ack, self.tcp.rcv_nxt); + const words: u16 = @intCast((tcp.hlen + opt_len) / 4); + wr16(seg, tcp.hdrlen_flags, (words << 12) | flags); + wr16(seg, tcp.window, self.rcvWindow()); + wr16(seg, tcp.chksum, 0); + wr16(seg, tcp.urgent, 0); + if (mss_opt) { + seg[tcp.hlen] = tcp.opt_mss; + seg[tcp.hlen + 1] = 4; + wr16(seg, tcp.hlen + 2, tcp_mss); + } + if (data.len != 0) @memcpy(seg[tcp.hlen + opt_len ..], data); + wr16(seg, tcp.chksum, transportChecksum(src, self.tcp.peer_ip, .tcp, seg)); + + self.counters.tcp_tx += 1; + return self.emitIp(src, self.tcp.peer_ip, .tcp, seg_len); + } + + /// The window to advertise: real back-pressure, not a constant. Everything accepted is consumed + /// synchronously into the HTTP head buffer or the caller's `out`, so the window is whatever + /// room is left there, capped at one MSS. Advertising a fixed window while the consumer had no + /// room left would turn "the response is bigger than your buffer" into a silently dropped + /// segment and an RTO storm. + fn rcvWindow(self: *Stack) u16 { + const room: usize = switch (self.http.phase) { + .head => (http_head_max - self.http.head_len) + self.http.out.len, + // Chunked framing - the CRLF closing each chunk, the zero-length chunk, the trailer + // section and the final CRLF - is consumed and discarded rather than delivered, so it + // needs window that `out` does not account for. Without this a body that exactly + // fills `out` closes the window before its own terminator can arrive, and the request + // stalls until the RTO gives up on a peer that is behaving perfectly. + .body => (self.http.out.len - self.http.out_len) + + @as(usize, if (self.http.chunked) http_framing_max + 16 else 0), + else => tcp_window, + }; + return @intCast(@min(room, tcp_window)); + } + + /// Reset the connection and fail the request. RST is sent unless the peer sent one. + fn tcpAbort(self: *Stack, err: HttpError, send_rst: bool) void { + if (send_rst and self.tcp.state != .closed and self.tcp.state != .arp_wait) { + _ = self.emitTcp(tcp.rst | tcp.ack_f, self.tcp.snd_nxt, &.{}, false); + } + self.tcp.state = .closed; + if (self.http.phase == .head or self.http.phase == .body) { + self.http.phase = .failed; + self.http.err = err; + } + } + + /// Set up the connection block for a fresh connect. Written field by field on purpose: the + /// obvious `self.tcp = .{ ... }` would assign `tx` from the struct's `undefined` default, which + /// in a safe build overwrites the request bytes with 0xAA, and in a release build memsets half + /// a kilobyte for nothing. + fn tcpConnect(self: *Stack, peer: Ip4, port: u16) void { + // A fresh ephemeral port every time. RFC 6335's dynamic range is 49152-65535, and moving + // through it is what makes the short TIME_WAIT above safe. + const span: u32 = 65535 - 49152 + 1; + const iss = self.draw(); + self.tcp.state = .arp_wait; + self.tcp.peer_ip = peer; + self.tcp.peer_port = port; + self.tcp.local_port = @intCast(49152 + self.draw() % span); + self.tcp.iss = iss; + self.tcp.snd_una = iss; + self.tcp.snd_nxt = iss; + self.tcp.snd_wnd = 0; + self.tcp.snd_mss = tcp_default_mss; + self.tcp.fin_queued = false; + self.tcp.peer_fin = false; + self.tcp.rcv_nxt = 0; + self.tcp.rto_deadline_ms = 0; + self.tcp.rto_ms = tcp_rto_initial_ms; + self.tcp.retries = 0; + self.tcp.close_deadline_ms = 0; + self.tcp.tx_len = 0; + self.arp_tries = 0; + self.arp_retry_ms = 0; + } + + fn tcpSendSyn(self: *Stack) void { + self.tcp.state = .syn_sent; + self.tcp.snd_nxt = self.tcp.iss +% 1; + _ = self.emitTcp(tcp.syn, self.tcp.iss, &.{}, true); + self.armRto(); + } + + fn armRto(self: *Stack) void { + self.tcp.rto_deadline_ms = self.now_ms + self.tcp.rto_ms; + } + + /// Send as much of the request as the peer's window and MSS allow, then the FIN if the whole + /// request has gone out. One segment in flight, so this sends at most one segment per call. + /// + /// Only `established` sends: receiving the peer's FIN does not move the state, it sets + /// `peer_fin`, so this stays the single place that decides what goes on the wire and the state + /// only ever changes when a FIN of ours actually leaves. + fn tcpSendData(self: *Stack) void { + if (self.tcp.state != .established) return; + // Nothing outstanding is the precondition for sending: this is the fixed window of one. + if (seqLt(self.tcp.snd_una, self.tcp.snd_nxt)) return; + + const end = self.tcp.dataEnd(); + if (seqLt(self.tcp.snd_nxt, end)) { + const off: usize = self.tcp.snd_nxt -% self.tcp.dataStart(); + const remaining = self.tcp.tx_len - off; + const window: usize = self.tcp.snd_una +% self.tcp.snd_wnd -% self.tcp.snd_nxt; + const n = @min(@min(remaining, self.tcp.snd_mss), @max(window, 1)); + // PSH on the last segment of the request: the peer's application should see it without + // waiting for more. RFC 793 has no requirement here; every HTTP server expects it. + const last = off + n == self.tcp.tx_len; + const flags: u8 = tcp.ack_f | (if (last) tcp.psh else 0); + const seq = self.tcp.snd_nxt; + self.tcp.snd_nxt = seq +% @as(u32, @intCast(n)); + _ = self.emitTcp(flags, seq, self.tcp.tx[off..][0..n], false); + self.armRto(); + return; + } + if (self.tcp.fin_queued and self.tcp.snd_nxt == end) { + const seq = self.tcp.snd_nxt; + self.tcp.snd_nxt = seq +% 1; + _ = self.emitTcp(tcp.fin | tcp.ack_f, seq, &.{}, false); + self.armRto(); + // RFC 793's FIN-WAIT-1 if we closed first, its CLOSING/LAST-ACK if the peer did. Both + // of the latter are `last_ack` here: they differ only in which ACK is still owed, and + // `closeCheck` settles that from the sequence numbers. + self.tcp.state = if (self.tcp.peer_fin) .last_ack else .fin_wait_1; + } + } + + /// Half-close: everything we mean to send has been sent, so send FIN once the data is out. + fn tcpFinish(self: *Stack) void { + if (self.tcp.fin_queued) return; + self.tcp.fin_queued = true; + self.tcpSendData(); + } + + /// Both directions closed and our FIN acknowledged: nothing is left in flight, so the + /// connection block can be released after TIME_WAIT. Called once at the end of every segment, + /// which covers both orders of arrival - the peer's FIN then its ACK, or the reverse. + fn closeCheck(self: *Stack) void { + switch (self.tcp.state) { + .fin_wait_1, .fin_wait_2, .last_ack => {}, + else => return, + } + if (!self.tcp.peer_fin) return; + if (self.tcp.snd_una != self.tcp.snd_nxt) return; + self.tcp.state = .time_wait; + self.tcp.rto_deadline_ms = 0; + self.tcp.close_deadline_ms = self.now_ms + tcp_time_wait_ms; + } + + fn tcpInput(self: *Stack, src: Ip4, dst: Ip4, seg: []const u8) void { + if (seg.len < tcp.hlen) { + self.counters.rx_dropped += 1; + return; + } + const hf = rd16(seg, tcp.hdrlen_flags); + const hlen = @as(usize, hf >> 12) * 4; + if (hlen < tcp.hlen or hlen > seg.len) { + self.counters.rx_dropped += 1; + return; + } + if (!transportChecksumOk(src, dst, .tcp, seg, rd16(seg, tcp.chksum))) { + self.counters.checksum_bad += 1; + return; + } + const flags: u8 = @truncate(hf & 0x3f); + const sport = rd16(seg, tcp.src_port); + const dport = rd16(seg, tcp.dst_port); + + if (self.tcp.state == .closed or + dport != self.tcp.local_port or + sport != self.tcp.peer_port or + !std.mem.eql(u8, &src, &self.tcp.peer_ip)) + { + // Not for our one connection. A real stack would RST; a client with no listening port + // gains nothing by telling a scanner it is there. + self.counters.rx_dropped += 1; + return; + } + self.counters.tcp_rx += 1; + + const seq = rd32(seg, tcp.seq); + const ackno = rd32(seg, tcp.ack); + const data = seg[hlen..]; + + if (flags & tcp.rst != 0) { + self.counters.tcp_rst_rx += 1; + // RFC 5961 3: only a RST whose sequence number is the next one expected may tear the + // connection down. Anything else gets a challenge ACK, which is also what stops a + // blind off-path reset. + if (self.tcp.state == .syn_sent) { + // In SYN-SENT the RST is validated by its ACK instead: there is no rcv_nxt yet. + if (flags & tcp.ack_f != 0 and ackno == self.tcp.snd_nxt) self.tcpAbort(error.ConnectionReset, false); + return; + } + if (seq == self.tcp.rcv_nxt) { + self.tcpAbort(error.ConnectionReset, false); + } else { + _ = self.emitTcp(tcp.ack_f, self.tcp.snd_nxt, &.{}, false); + } + return; + } + + if (self.tcp.state == .syn_sent) { + if (flags & tcp.syn == 0) { + self.counters.rx_dropped += 1; + return; + } + if (flags & tcp.ack_f == 0) { + // A simultaneous open. Nothing on the other end of an HTTP GET does this. + self.counters.rx_dropped += 1; + return; + } + if (ackno != self.tcp.iss +% 1) { + // Not acknowledging our SYN: an old duplicate. RFC 793 says reset it. + _ = self.emitTcp(tcp.rst, ackno, &.{}, false); + return; + } + self.tcp.rcv_nxt = seq +% 1; + self.tcp.snd_una = ackno; + self.tcp.snd_wnd = rd16(seg, tcp.window); + self.tcp.snd_mss = parseMss(seg[tcp.hlen..hlen]) orelse tcp_default_mss; + self.tcp.state = .established; + self.tcp.rto_ms = tcp_rto_initial_ms; + self.tcp.retries = 0; + // The ACK completing the handshake carries the first data segment, which is one frame + // saved and what every other stack does. + self.tcp.rto_deadline_ms = 0; + self.tcpSendData(); + if (self.tcp.snd_nxt == self.tcp.snd_una) { + // Nothing to send yet; the handshake still needs acknowledging. + _ = self.emitTcp(tcp.ack_f, self.tcp.snd_nxt, &.{}, false); + } + return; + } + + // A duplicate SYN in an established connection is either a retransmitted SYN whose ACK was + // lost - answer with an ACK - or an attack. Never a reason to re-open. + if (flags & tcp.syn != 0 and seqLt(seq, self.tcp.rcv_nxt)) { + _ = self.emitTcp(tcp.ack_f, self.tcp.snd_nxt, &.{}, false); + return; + } + + if (flags & tcp.ack_f != 0) self.tcpAck(ackno, rd16(seg, tcp.window)); + + // ---- receive side + var payload = data; + var accept = false; + if (payload.len != 0) { + if (seqLe(seq, self.tcp.rcv_nxt) and seqGt(seq +% @as(u32, @intCast(payload.len)), self.tcp.rcv_nxt)) { + // Overlaps what we already have: trim the duplicate prefix. A retransmission after + // a lost ACK arrives exactly like this, and rejecting it would deadlock. + const skip: usize = self.tcp.rcv_nxt -% seq; + payload = payload[skip..]; + accept = true; + } else if (seqLe(seq +% @as(u32, @intCast(payload.len)), self.tcp.rcv_nxt)) { + // Wholly old. Re-acknowledge so the peer stops. + _ = self.emitTcp(tcp.ack_f, self.tcp.snd_nxt, &.{}, false); + return; + } else { + // Out of order, and there is nowhere to keep it. The duplicate ACK below is the + // signal that makes the peer resend. + _ = self.emitTcp(tcp.ack_f, self.tcp.snd_nxt, &.{}, false); + return; + } + } + + if (accept) { + // Never accept more than the window we advertised. + const room = self.rcvWindow(); + if (payload.len > room) payload = payload[0..room]; + self.tcp.rcv_nxt +%= @intCast(payload.len); + // Consuming the data may itself put a segment on the wire - completing the body sends + // our FIN - and every segment carries `rcv_nxt`, so a separate ACK would be a wasted + // frame. Counting is the honest way to know: anything emitted has already acknowledged + // this data, and nothing emitted means we still owe an ACK. + const tx_before = self.counters.tcp_tx; + self.httpOnData(payload); + if (self.tcp.state == .closed) return; // httpOnData failed and aborted + if (self.counters.tcp_tx == tx_before) { + _ = self.emitTcp(tcp.ack_f, self.tcp.snd_nxt, &.{}, false); + } + } + + // ---- FIN, in order only. An out-of-order FIN names a sequence number beyond data we have + // not seen, and honouring it would close the connection over a hole. + if (flags & tcp.fin != 0) { + const fin_seq = seq +% @as(u32, @intCast(data.len)); + const in_order = fin_seq == self.tcp.rcv_nxt; + // A FIN we have already consumed, arriving again because our ACK was lost. It must be + // re-acknowledged or the peer retransmits until it gives up and resets. + const duplicate = self.tcp.peer_fin and fin_seq +% 1 == self.tcp.rcv_nxt; + if (in_order and !self.tcp.peer_fin) { + self.tcp.rcv_nxt +%= 1; + self.tcp.peer_fin = true; + self.httpOnEof(); + } + if (in_order or duplicate) { + // Our own FIN, if it has not gone yet, acknowledges the peer's on the way out. + const tx_before = self.counters.tcp_tx; + self.tcpFinish(); + if (self.counters.tcp_tx == tx_before) { + _ = self.emitTcp(tcp.ack_f, self.tcp.snd_nxt, &.{}, false); + } + } + } + + self.closeCheck(); + } + + fn tcpAck(self: *Stack, ackno: u32, window: u16) void { + // An ACK ahead of what we sent is invalid; an old one is a duplicate. + if (seqGt(ackno, self.tcp.snd_nxt)) return; + self.tcp.snd_wnd = window; + if (seqLe(ackno, self.tcp.snd_una)) { + // Duplicate ACK. With one segment in flight there is nothing to fast-retransmit. + return; + } + self.tcp.snd_una = ackno; + self.tcp.retries = 0; + self.tcp.rto_ms = tcp_rto_initial_ms; + if (self.tcp.snd_una == self.tcp.snd_nxt) { + self.tcp.rto_deadline_ms = 0; // nothing outstanding + } else { + self.armRto(); + } + if (self.tcp.state == .fin_wait_1 and self.tcp.snd_una == self.tcp.snd_nxt) { + self.tcp.state = .fin_wait_2; + self.tcp.close_deadline_ms = self.now_ms + tcp_fin_wait2_ms; + } + // Window opened or data acknowledged: there may be more to send. + self.tcpSendData(); + } + + /// RFC 793 3.1 option format: kind, then for kinds above 1 a length byte covering both. + fn parseMss(opts: []const u8) ?u16 { + var i: usize = 0; + while (i < opts.len) { + const kind = opts[i]; + if (kind == tcp.opt_end) return null; + if (kind == tcp.opt_nop) { + i += 1; + continue; + } + if (i + 2 > opts.len) return null; + const len = opts[i + 1]; + if (len < 2 or i + len > opts.len) return null; + if (kind == tcp.opt_mss and len == 4) { + const v = rd16(opts, i + 2); + // Below RFC 1122's floor a peer's MSS is not believable; above our MTU it cannot + // be honoured anyway. + return @min(@max(v, 64), tcp_mss); + } + i += len; + } + return null; + } + + fn tcpTick(self: *Stack) void { + switch (self.tcp.state) { + .closed => {}, + .arp_wait => { + if (self.arpLookup(self.tcpNextHop())) |_| { + self.tcpSendSyn(); + return; + } + if (self.arp_retry_ms != 0 and self.now_ms < self.arp_retry_ms) return; + if (self.arp_tries >= arp_max_tries) { + self.tcpAbort(error.HostUnreachable, false); + return; + } + self.arpRequest(self.tcpNextHop()); + self.arp_tries += 1; + self.arp_retry_ms = self.now_ms + arp_retry_ms; + }, + .fin_wait_2 => { + // Our FIN is acknowledged and nothing is outstanding, so there is no RTO to run: + // the only thing left is the peer's FIN, and this is how long we wait for it. + if (self.now_ms >= self.tcp.close_deadline_ms) self.tcp.state = .closed; + }, + .time_wait => { + if (self.now_ms >= self.tcp.close_deadline_ms) self.tcp.state = .closed; + }, + else => { + if (self.tcp.rto_deadline_ms == 0) return; + if (self.now_ms < self.tcp.rto_deadline_ms) return; + if (self.tcp.retries >= tcp_max_retries) { + self.tcpAbort(error.TimedOut, true); + return; + } + self.tcp.retries += 1; + self.counters.tcp_retx += 1; + // Exponential backoff, RFC 6298 5.5. + self.tcp.rto_ms = @min(self.tcp.rto_ms * 2, tcp_rto_max_ms); + self.tcpRetransmit(); + }, + } + } + + fn tcpNextHop(self: *Stack) Ip4 { + return if (self.onLink(self.tcp.peer_ip)) self.tcp.peer_ip else self.gw; + } + + /// Go back to `snd_una` and send again. With one segment in flight this is the whole of + /// retransmission: there is no queue to walk and no partial-ACK case to handle. + fn tcpRetransmit(self: *Stack) void { + const una = self.tcp.snd_una; + if (una == self.tcp.iss) { + // The SYN. Its MSS option must be repeated: a peer that only ever sees the + // retransmission would otherwise assume 536. + self.tcp.snd_nxt = self.tcp.iss; + self.tcpSendSyn(); + return; + } + const end = self.tcp.dataEnd(); + if (seqLt(una, end)) { + self.tcp.snd_nxt = una; + self.tcpSendData(); + return; + } + if (self.tcp.fin_queued and una == end) { + self.tcp.snd_nxt = una; + // `tcpSendData` re-sends the FIN and re-arms, but it refuses to run in FIN_WAIT_1 + // (which is where a lost FIN leaves us), so the segment is emitted directly. + _ = self.emitTcp(tcp.fin | tcp.ack_f, una, &.{}, false); + self.tcp.snd_nxt = una +% 1; + self.armRto(); + return; + } + // Nothing identifiable outstanding: a bare ACK, which costs one frame and cannot hurt. + _ = self.emitTcp(tcp.ack_f, self.tcp.snd_nxt, &.{}, false); + self.armRto(); + } + + // ================================================================================ HTTP + + /// Fetch `path` from `host:port` over HTTP/1.1 and write the body to `out`, sending the + /// address literal as the `Host:` header. Exactly `httpGetHost(host, null, ...)`; see there + /// for the protocol, which is the whole of how this is used. + pub fn httpGet(self: *Stack, host: [4]u8, port: u16, path: []const u8, out: []u8) HttpError!usize { + return self.httpGetHost(host, null, port, path, out); + } + + /// Fetch `path` from `host:port` over HTTP/1.1 and write the body to `out`. + /// + /// `name` is the `Host:` header. `null` sends the address literal - `Host: 192.168.1.90` - + /// which is right for a bare address and is what `httpGet` does. A name is what a + /// name-based virtual host requires: one address behind a CDN serves thousands of sites and + /// picks between them on this header alone, so `Host: 104.21.46.8` gets the CDN's own error + /// page and never the site. The address is still where the connection goes; the name only + /// ever appears in the header, and nothing here resolves it - `resolve` does that, and the + /// two are separate because a caller may have the address already. + /// + /// The port is appended as `:port` only when it is not 80, name or no name. RFC 7230 5.4. + /// + /// **This does not block, and it is not a one-shot call.** There is no `std.Io` here and no + /// clock, so there is nothing for a blocking call to block on: the frames that carry the + /// response arrive through `onFrame` and time advances through `tick`, both of which are the + /// caller's to drive. So the first call starts the request and returns `error.WouldBlock`, and + /// the caller keeps driving and keeps calling with the same arguments until it returns a length: + /// + /// while (true) { + /// stack.tick(hal.systimer.millis()); + /// while (transport.next()) |frame| stack.onFrame(frame); + /// if (stack.httpGetHost(addr, "0x4200.cafe", 80, "/", &buf)) |n| break :done buf[0..n] + /// else |e| if (e != error.WouldBlock) return e; + /// } + /// + /// `out` is borrowed until the request completes: it is written to from inside `onFrame` as the + /// body arrives, so it must not move or be reused meanwhile. Calling with different arguments + /// while a request is in flight returns `error.Busy` rather than quietly abandoning the first, + /// and `name` is one of those arguments: two requests to one address for one path but + /// different virtual hosts are different requests. + /// + /// `Content-Length` is honoured, and so is `Transfer-Encoding: chunked` - the body handed back + /// is decoded, with no framing bytes in it. A response with neither ends at the peer's FIN, + /// which is why the request says `Connection: close`. + pub fn httpGetHost( + self: *Stack, + host: [4]u8, + name: ?[]const u8, + port: u16, + path: []const u8, + out: []u8, + ) HttpError!usize { + // The name is folded into the path hash rather than given a field of its own: `Stack` has + // a 4 KiB budget, and what this has to distinguish is "the same call again" from "a + // different call", which a hash does exactly. Seeding with the name's hash rather than + // concatenating keeps `null` (seed 0) distinct from any name, including the empty one. + const req_hash = std.hash.Wyhash.hash( + if (name) |nm| std.hash.Wyhash.hash(0x486f_7374, nm) else 0, + path, + ); + switch (self.http.phase) { + .idle => {}, + .head, .body => { + if (!std.mem.eql(u8, &self.http.req_host, &host) or + self.http.req_port != port or + self.http.req_hash != req_hash or + self.http.out.ptr != out.ptr or + self.http.out.len != out.len) return error.Busy; + return error.WouldBlock; + }, + .complete => { + const n = self.http.out_len; + self.http.phase = .idle; + return n; + }, + .failed => { + const e = self.http.err; + self.http.phase = .idle; + return e; + }, + } + + if (self.addr == null) return error.NoAddress; + + // The request, built once into the TCP send buffer where it stays until acknowledged. + var w: RequestWriter = .{ .buf = &self.tcp.tx }; + w.str("GET "); + w.str(if (path.len == 0) "/" else path); + w.str(" HTTP/1.1\r\nHost: "); + if (name) |nm| w.str(nm) else w.ipv4(host); + if (port != 80) { + w.str(":"); + w.dec(port); + } + // Connection: close is not politeness, it is the framing: it is what makes a response with + // no Content-Length terminable, and it is what makes the peer's FIN the end of the body. + w.str("\r\nUser-Agent: zig-p4/0.1\r\nAccept: */*\r\nConnection: close\r\n\r\n"); + if (w.overflow) return error.RequestTooLong; + + self.http = .{ + .phase = .head, + .out = out, + .req_host = host, + .req_port = port, + .req_hash = req_hash, + }; + self.tcpConnect(host, port); + self.tcp.tx_len = w.i; + self.tcp.fin_queued = false; + // A MAC address may already be known, in which case the SYN goes out now rather than one + // `tick` later. + if (self.arpLookup(self.tcpNextHop()) != null) { + self.tcpSendSyn(); + } else { + self.arpRequest(self.tcpNextHop()); + self.arp_tries = 1; + self.arp_retry_ms = self.now_ms + arp_retry_ms; + } + return error.WouldBlock; + } + + /// A bounds-checked append into a fixed buffer. Overflow is recorded, not asserted: a caller's + /// long path is a request error, not a bug in this file. + const RequestWriter = struct { + buf: []u8, + i: usize = 0, + overflow: bool = false, + + fn str(self: *RequestWriter, s: []const u8) void { + if (self.overflow or self.i + s.len > self.buf.len) { + self.overflow = true; + return; + } + @memcpy(self.buf[self.i..][0..s.len], s); + self.i += s.len; + } + fn dec(self: *RequestWriter, v: u32) void { + var tmp: [10]u8 = undefined; + var n: usize = 0; + var x = v; + while (true) { + tmp[n] = '0' + @as(u8, @intCast(x % 10)); + n += 1; + x /= 10; + if (x == 0) break; + } + while (n > 0) { + n -= 1; + self.str(tmp[n .. n + 1]); + } + } + fn ipv4(self: *RequestWriter, a: Ip4) void { + for (a, 0..) |b, k| { + if (k != 0) self.str("."); + self.dec(b); + } + } + }; + + /// Fail the request and reset the connection. The phase is set before `tcpAbort`, which would + /// otherwise overwrite `err` with its own argument on the way past. + fn httpFail(self: *Stack, e: HttpError) void { + self.http.phase = .failed; + self.http.err = e; + self.tcpAbort(e, true); + } + + /// In-order TCP payload. Called from inside `onFrame`. + fn httpOnData(self: *Stack, bytes: []const u8) void { + var rest = bytes; + if (self.http.phase == .head) { + const room = http_head_max - self.http.head_len; + const n = @min(room, rest.len); + @memcpy(self.http.head[self.http.head_len..][0..n], rest[0..n]); + const scan_from = self.http.head_len -| 3; + self.http.head_len += n; + rest = rest[n..]; + + const blank = std.mem.indexOfPos(u8, self.http.head[0..self.http.head_len], scan_from, "\r\n\r\n") orelse { + if (self.http.head_len == http_head_max) self.httpFail(error.HttpHeadersTooLong); + return; + }; + const head_end = blank + 4; + // Anything the head buffer swallowed past the blank line is body. This is the case a + // test has to cover deliberately, because it only happens when a segment boundary does + // not coincide with the end of the headers - which on a real server is most of the time. + const spill = self.http.head[head_end..self.http.head_len]; + self.parseHead(self.http.head[0..blank]) catch |e| { + self.httpFail(e); + return; + }; + self.http.phase = .body; + // `spill` aliases `self.http.head`, and `httpBody` only ever writes to `self.http.out`, + // so passing it through is safe. Copy first if that ever stops being true. + // + // It is called unconditionally, even when `spill` is empty: that is what completes a + // `Content-Length: 0` response, whose body is over the moment its headers are. + self.httpBody(spill); + if (self.http.phase != .body) return; + } + if (rest.len != 0) self.httpBody(rest); + } + + /// Status line and headers, without the terminating blank line. + fn parseHead(self: *Stack, head: []const u8) HttpError!void { + var lines = std.mem.splitSequence(u8, head, "\r\n"); + const status_line = lines.next() orelse return error.HttpMalformed; + // "HTTP/1.1 200 OK": version, space, three digits. + if (status_line.len < 12) return error.HttpMalformed; + if (!std.mem.startsWith(u8, status_line, "HTTP/1.")) return error.HttpMalformed; + if (status_line[8] != ' ') return error.HttpMalformed; + var code: u16 = 0; + for (status_line[9..12]) |c| { + if (c < '0' or c > '9') return error.HttpMalformed; + code = code * 10 + (c - '0'); + } + self.http.status = code; + self.http.content_length = null; + self.http.chunked = false; + + while (lines.next()) |line| { + if (line.len == 0) continue; + const colon = std.mem.indexOfScalar(u8, line, ':') orelse continue; + const name = line[0..colon]; + const value = std.mem.trim(u8, line[colon + 1 ..], " \t"); + // RFC 7230 3.2: field names are case-insensitive. Servers vary, and a stack that + // compares them exactly works against nginx and fails against something else. + if (std.ascii.eqlIgnoreCase(name, "content-length")) { + self.http.content_length = std.fmt.parseInt(usize, value, 10) catch + return error.HttpMalformed; + } else if (std.ascii.eqlIgnoreCase(name, "transfer-encoding")) { + // RFC 7230 3.3.1: the final coding decides the framing. Exactly two are + // understood - `chunked`, which frames the body, and `identity`, which does not - + // and a list, or a coding that transforms the bytes, is refused. Guessing at + // `gzip` would hand the caller compressed data and call it a body. + if (std.ascii.eqlIgnoreCase(value, "chunked")) { + self.http.chunked = true; + } else if (!std.ascii.eqlIgnoreCase(value, "identity")) { + return error.UnsupportedTransferEncoding; + } + } + } + if (self.http.chunked) { + // RFC 7230 3.3.3 case 3: when both are present the chunked framing wins and + // `Content-Length` must be ignored - it is the classic request-smuggling + // disagreement, and a response that carries both is not to be believed twice. + self.http.content_length = null; + self.http.chunk = .size; + self.http.chunk_left = 0; + self.http.chunk_digit = false; + self.http.chunk_skip = 0; + } + // A response whose body cannot possibly fit is refused now rather than after copying most + // of it: the caller gets a clean error instead of a truncated buffer. A chunked response + // announces no total, so its equivalent check is per chunk, in `httpChunkedBody`. + if (self.http.content_length) |len| { + if (len > self.http.out.len) return error.StreamTooLong; + } + } + + fn httpBody(self: *Stack, bytes: []const u8) void { + if (self.http.chunked) return self.httpChunkedBody(bytes); + var b = bytes; + if (self.http.content_length) |len| { + const want = len - self.http.out_len; + if (b.len > want) b = b[0..want]; + } + if (self.http.out_len + b.len > self.http.out.len) { + self.httpFail(error.StreamTooLong); + return; + } + @memcpy(self.http.out[self.http.out_len..][0..b.len], b); + self.http.out_len += b.len; + if (self.http.content_length) |len| { + if (self.http.out_len >= len) self.httpComplete(); + } + } + + /// Charge `n` bytes against the framing budget. False means the request has been failed and + /// the decoder must stop. + fn chunkSkip(self: *Stack, n: usize) bool { + const total = @as(usize, self.http.chunk_skip) + n; + if (total > http_framing_max) { + self.httpFail(error.HttpHeadersTooLong); + return false; + } + self.http.chunk_skip = @intCast(total); + return true; + } + + /// RFC 7230 4.1 chunked decoding, resumable between any two bytes. + /// + /// The decoder's whole position lives in `http.chunk`, `chunk_left`, `chunk_digit` and + /// `chunk_skip`, and `bytes` is whatever the last segment happened to carry. Nothing is + /// buffered and nothing is looked ahead at: a size split across two segments accumulates a + /// digit at a time, a CRLF split across two segments is two states, and a chunk's data is + /// copied out as it arrives however it is cut up. That is not a hypothetical - a 1,460-byte + /// segment ends where the server's writes ended, which is nowhere in particular. + /// + /// `out` receives decoded data only. No size, no extension, no CRLF and no trailer byte is + /// ever copied into it, and every failure is a named error rather than a short body. + fn httpChunkedBody(self: *Stack, bytes: []const u8) void { + var b = bytes; + while (b.len != 0) { + switch (self.http.chunk) { + .size => { + const c = b[0]; + const digit: ?u8 = switch (c) { + '0'...'9' => c - '0', + 'a'...'f' => c - 'a' + 10, + 'A'...'F' => c - 'A' + 10, + else => null, + }; + b = b[1..]; + if (digit) |d| { + // Checked, not truncated: a size that does not fit `usize` is a malformed + // message, and wrapping it would turn a hostile header into a short read + // that looks like a complete body. + if (self.http.chunk_left > (std.math.maxInt(usize) - @as(usize, d)) / 16) { + self.httpFail(error.HttpChunkMalformed); + return; + } + self.http.chunk_left = self.http.chunk_left * 16 + d; + self.http.chunk_digit = true; + continue; + } + // RFC 7230 4.1 is `1*HEXDIG`. Without this an empty line reads as a chunk of + // size zero, which is the terminator, which ends the body early. + if (!self.http.chunk_digit) { + self.httpFail(error.HttpChunkMalformed); + return; + } + self.http.chunk_skip = 0; + switch (c) { + ';' => self.http.chunk = .ext, + '\r' => self.http.chunk = .size_lf, + else => { + self.httpFail(error.HttpChunkMalformed); + return; + }, + } + }, + .ext => { + // chunk-ext is skipped whole: nothing here depends on one, so the only thing + // that matters is finding the CR that ends the header - possibly not in this + // segment at all. + const cr = std.mem.indexOfScalar(u8, b, '\r'); + const n = cr orelse b.len; + if (!self.chunkSkip(n)) return; + b = b[n..]; + if (cr != null) { + b = b[1..]; + self.http.chunk = .size_lf; + } + }, + .size_lf => { + if (b[0] != '\n') { + self.httpFail(error.HttpChunkMalformed); + return; + } + b = b[1..]; + if (self.http.chunk_left == 0) { + // The zero-length chunk. What follows is the trailer section, and the + // body is not complete until its final CRLF. + self.http.chunk_skip = 0; + self.http.chunk = .trailer; + } else { + // Refused on the header rather than part-way through the copy, which is + // what `Content-Length` gets: the caller sees the error before the buffer + // has been half filled with a body it will never be given. + if (self.http.chunk_left > self.http.out.len - self.http.out_len) { + self.httpFail(error.StreamTooLong); + return; + } + self.http.chunk = .data; + } + }, + .data => { + // In bounds by construction: `.size_lf` refused any chunk larger than the room + // left, and this only ever takes `chunk_left` of it. + const n = @min(self.http.chunk_left, b.len); + @memcpy(self.http.out[self.http.out_len..][0..n], b[0..n]); + self.http.out_len += n; + self.http.chunk_left -= n; + b = b[n..]; + if (self.http.chunk_left == 0) self.http.chunk = .data_cr; + }, + .data_cr => { + if (b[0] != '\r') { + self.httpFail(error.HttpChunkMalformed); + return; + } + b = b[1..]; + self.http.chunk = .data_lf; + }, + .data_lf => { + if (b[0] != '\n') { + self.httpFail(error.HttpChunkMalformed); + return; + } + b = b[1..]; + // `.data` is only ever left with the chunk exhausted, so the accumulator the + // next size builds in already reads zero and is not re-zeroed here. Asserted + // rather than assumed: re-zeroing would be dead code that hides the day the + // invariant stops holding, and a stale count would be silent. + assert(self.http.chunk_left == 0); + self.http.chunk_digit = false; + self.http.chunk = .size; + }, + .trailer => { + if (!self.chunkSkip(1)) return; + const cr = b[0] == '\r'; + b = b[1..]; + self.http.chunk = if (cr) .end_lf else .trailer_line; + }, + .trailer_line => { + const cr = std.mem.indexOfScalar(u8, b, '\r'); + const n = cr orelse b.len; + if (!self.chunkSkip(n)) return; + b = b[n..]; + if (cr != null) { + b = b[1..]; + self.http.chunk = .trailer_lf; + } + }, + .trailer_lf => { + if (b[0] != '\n') { + self.httpFail(error.HttpChunkMalformed); + return; + } + b = b[1..]; + self.http.chunk = .trailer; + }, + .end_lf => { + if (b[0] != '\n') { + self.httpFail(error.HttpChunkMalformed); + return; + } + self.httpComplete(); + // Anything after the final CRLF belongs to a response this connection will + // never ask for: `Connection: close` was sent, and the FIN follows. + return; + }, + } + } + } + + fn httpComplete(self: *Stack) void { + self.http.phase = .complete; + // The body is in hand; close our half. Reading further would only cost frames. + self.tcpFinish(); + } + + /// The peer closed. Whether that completes the response depends on the framing. + fn httpOnEof(self: *Stack) void { + switch (self.http.phase) { + .body => { + if (self.http.chunked) { + // The zero-length chunk and its trailer never arrived. RFC 7230 4.1 makes + // them the framing, so a close before them is a truncated body, however many + // whole chunks came first - reporting what did arrive would be reporting a + // prefix as the whole. + self.http.phase = .failed; + self.http.err = error.ConnectionClosed; + } else if (self.http.content_length) |len| { + if (self.http.out_len >= len) { + self.http.phase = .complete; + } else { + // Fewer body bytes than Content-Length promised. + self.http.phase = .failed; + self.http.err = error.ConnectionClosed; + } + } else { + // No Content-Length: the FIN *is* the framing (RFC 7230 3.3.3 case 7). + self.http.phase = .complete; + } + }, + .head => { + self.http.phase = .failed; + self.http.err = error.ConnectionClosed; + }, + else => {}, + } + } + + // ================================================================================ tick + + /// Advance time. Drives DHCP retransmission and renewal, ARP resolution and TCP + /// retransmission. `now_ms` must be monotonic; it need not start at zero and it need not be + /// called at any particular rate, but nothing times out between calls, so a 47-second TCP + /// deadline needs ticks more often than every 47 seconds to be observed on time. + pub fn tick(self: *Stack, now_ms: u64) void { + self.now_ms = now_ms; + // Stir. The MAC alone would make every boot draw the same transaction ids, initial sequence + // numbers and ephemeral ports, which is how two runs of the same firmware end up accepting + // each other's stale DHCP replies. `now_ms` is the only outside input this file has, and a + // caller that ticks a real timer before starting DHCP therefore gets a different sequence + // every boot. Still not a source of security-relevant randomness - see `entropy`. + self.entropy ^= now_ms *% 0x9e37_79b9_7f4a_7c15; + self.dhcpTick(); + self.dnsTick(); + self.tcpTick(); + } +}; + +// The footprint claim, enforced at compile time, so a buffer that grows fails the build rather than +// the board. +// +// 4 KiB is the budget and it is measured, not guessed: the image has ~128 KB of L2MEM, nothing +// initialises the 32 MB of PSRAM, and ESP-Hosted's queues and its seven task stacks are competing +// for the same space. `Stack` is 3,576 bytes today. The failure this prevents is a stack overflow +// on a part with no debugger, which is indistinguishable from the SDIO bus not coming up. +comptime { + // 6 KiB, raised from 4 KiB when `http_head_max` went from 1024 to 2048 to fit a real CDN + // response head (1043 bytes measured). This is a regression alarm, not a budget: it exists so a + // buffer cannot grow unnoticed, and moving it is a decision to be justified at the buffer that + // caused it - which the comment on `http_head_max` does. The image's real constraint is the + // ~128 KB of L2MEM, and the heap in examples/http.zig was reduced by the same amount to pay for + // this. + if (Stack.footprint > 6 * 1024) @compileError(std.fmt.comptimePrint( + "ip.Stack is {d} bytes, over the 4 KiB budget", + .{Stack.footprint}, + )); +} + +// The host tests live in `ip_test.zig` - 117 cases, and they are the correctness argument for this +// slice, since it is the one part of the P4 bring-up that can be proven without the board. They are +// in their own file because they are longer than the stack, and because the tests deliberately +// re-derive every header offset from the RFCs rather than importing the tables above: a test that +// shares the constant it is checking passes on a consistent misreading. +// +// This reference is what makes `zig build test` find them: build.zig runs `src/net/ip.zig` as a +// test root, and Zig only collects tests from files the root actually references. +test { + _ = @import("ip_test.zig"); +} |