diff options
Diffstat (limited to 'src/9p.zig')
| -rw-r--r-- | src/9p.zig | 4350 |
1 files changed, 4350 insertions, 0 deletions
diff --git a/src/9p.zig b/src/9p.zig new file mode 100644 index 00000000..8f78ed6b --- /dev/null +++ b/src/9p.zig @@ -0,0 +1,4350 @@ +//! BASE 9P2000, ON THE WIRE AND NOTHING ELSE: the twenty-seven message types +//! of the original protocol, encoded into a caller's buffer and decoded back +//! out of one, with no allocator, no descriptor and no opinion about what any +//! message means. +//! +//! WHY A SECOND CODEC in a tree that already has `src/detached/wire.zig`. That +//! one is ours on both ends and can be renumbered by editing one file. This one +//! is somebody else's: plan9port's `9p` command, Plan 9's own `mount`, Linux's +//! v9fs and `ad` will all be talking to it, and not one of them will be +//! rebuilt to suit us. So every number below is copied from a primary source +//! with the file and line named, and the tests at the bottom assert LITERAL +//! BYTES against `u9fs/convS2M.c` rather than only round-tripping — a codec +//! that agrees with itself has proved nothing about interoperability. +//! +//! WHAT THIS DELIBERATELY IS NOT. There are three dialects; this is the first. +//! * 9P2000.u adds a numeric errno to `Rerror`, `n_uid`/`extension` to +//! `stat`, and Unix-flavoured `Tcreate`. We do not serve it. The tree is +//! acme's and it is INVENTED — every error in it is one we chose the +//! wording of, so a string is the whole error ABI and a number beside it +//! would be a second spelling of a decision we already made +//! (docs/registry.typ `9P-4`). It also costs a second dialect inside every +//! one of the parsers below, because `.u` changes the LAYOUT of `Rerror` +//! and `stat` rather than adding messages. +//! * 9P2000.L replaces most of the protocol: `Tstatfs`, `Tlopen`, `Tgetattr`, +//! `Tsymlink`, `Trename`, thirty-odd types and a POSIX file model. Our tree +//! has no symlinks, no hard links, no device nodes and no block counts to +//! report, so there is nothing on the other side of those messages to +//! answer them with. +//! * `Tsession`/`Tattach`-with-auth-blob from the 9P1 era, which u9fs still +//! carries commented out (`convS2M.c:60-65,140-148`) and which no client +//! built this century sends. +//! +//! TWO FACTS A READER MUST NOT GET WRONG, because both are silent when wrong: +//! +//! 1. `size[4]` INCLUDES ITSELF. `convS2M.c:216-224` computes `size` from +//! `sizeS2M`, whose first line is `n += BIT32SZ; /* size */`, and then +//! writes that number into the first four bytes. A reader that treats it +//! as a payload length is four bytes out of step on every message and +//! resynchronises never. +//! +//! 2. A `stat` HAS TWO LENGTHS IN FRONT OF IT. The record itself begins with +//! `size[2]` which counts everything AFTER itself — `convD2M.c:48-51`, +//! «note that length excludes count field itself», `PBIT16(p, ss-BIT16SZ)` +//! — and `Rstat`/`Twstat` then wrap the whole record in ANOTHER `[2]` +//! count, which is why Linux reads `Rstat` with the format string `"wS"` +//! and throws the first `w` away into a variable literally named `ignored` +//! (`linux/net/9p/client.c:1617,1633`), and writes `Twstat` as `"dwS"` +//! (`client.c:1776`). So the outer count is `Stat.size() + 2`, never +//! `Stat.size()`. `Stat` below owns both numbers and the test +//! "9p: the stat double length" is the one that would catch it. +//! +//! FREESTANDING. No libc, no OS, no allocator, no threads: this file imports +//! `std` for `mem.readInt`/`writeInt` and `debug.assert` and nothing more, so +//! it compiles for `wasm32-freestanding` and for the board's +//! `riscv32-freestanding` exactly as `wire.zig` does. Every integer on the wire +//! has an explicit width and is little-endian; no `usize` reaches it, and no +//! Zig struct is ever `@bitCast` onto it. Decoding BORROWS: every `[]const u8` +//! in a decoded `Msg` points into the caller's buffer, which stays alive until +//! the reply is written. +//! +//! MALFORMED INPUT IS REFUSED. This parser is fed by a socket, and a message +//! misread rather than refused is an out-of-bounds index. Nothing below indexes +//! without first checking; `Error` names every way a stream can be wrong. +//! +//! THE SERVER HALF IS APPENDED TO THIS FILE, the way `fuse.zig` keeps its wire +//! structs and its transport together: a fid table, the dispatch onto +//! `acmefs.zig`'s nine operations, and the msize handshake. Codec first, then +//! the seam. Keeping them in one file is what makes it possible to change a +//! layout and its only caller in one diff. +//! +//! Verified against `u9fs` (`fcall.h`, `convS2M.c`, `convM2S.c`, `convD2M.c`, +//! `convM2D.c`), `linux/net/9p/{protocol,client}.c`, and +//! `ad/crates/ninep/src/sansio/protocol.rs`. +const std = @import("std"); +const assert = std.debug.assert; + +pub const Error = error{ + /// The message ended inside a field, or `size` claims more bytes than the + /// caller handed over. Both are "not all of it has arrived", which is what + /// a stream reader wants to hear: buffer more and ask again. + Truncated, + /// A count larger than this protocol admits: `nwname > MAXWELEM`, a string + /// past 64 KiB, a `stat` past 64 KiB. Refused before anything is indexed. + Overlong, + /// A type byte 9P2000 does not define, or defines as illegal (`Terror`). + BadTag, + /// A field carrying a value it cannot mean — a `size` smaller than a + /// header, which is a number no encoder can have produced. + BadValue, + /// The message was decoded and bytes were left over, either inside `size` + /// or after it. A message that says more than its layout has room for is + /// not this message. + Trailing, + /// The encoder ran out of caller-supplied buffer. Nothing was written. + NoSpace, +}; + +// --------------------------------------------------------------------------- +// message types +// --------------------------------------------------------------------------- + +/// The type byte. Numbers from `u9fs/fcall.h:74-105`, which is the definitive +/// list: `Tversion = 100` and every name after it takes the next value, so the +/// gap at 106 is load-bearing and the enum below spells it rather than skipping +/// it silently. +/// +/// Non-exhaustive for the same reason `fuse.zig`'s `Opcode` is: `@enumFromInt` +/// of an unlisted value into an exhaustive enum is undefined behaviour, which +/// is the one bug in a protocol decoder that cannot be diagnosed from outside. +/// A `.u` or `.L` client will hand us `Tstatfs = 8` or `Tlopen = 12`; that must +/// arrive as a value we can refuse (`decode` returns `error.BadTag`) rather +/// than as UB. +/// +/// TWENTY-SEVEN REAL TYPES: thirteen T/R pairs, plus `Rerror`, which is a reply +/// with no request. `Terror = 106` is the twenty-eighth number and is defined +/// as illegal by the protocol — a client cannot ask for an error — so it is +/// listed to keep the numbering honest and refused by name in `decode`. +pub const Type = enum(u8) { + tversion = 100, + rversion = 101, + tauth = 102, + rauth = 103, + tattach = 104, + rattach = 105, + /// «Terror = 106, /* illegal */» — `fcall.h:82`. Never sent, never + /// accepted; here so that nobody re-derives 107 for `Rerror` by counting. + terror = 106, + rerror = 107, + tflush = 108, + rflush = 109, + twalk = 110, + rwalk = 111, + topen = 112, + ropen = 113, + tcreate = 114, + rcreate = 115, + tread = 116, + rread = 117, + twrite = 118, + rwrite = 119, + tclunk = 120, + rclunk = 121, + tremove = 122, + rremove = 123, + tstat = 124, + rstat = 125, + twstat = 126, + rwstat = 127, + _, +}; + +/// T-messages are EVEN, R-messages are ODD, all the way from `Tversion = 100` +/// to `Rwstat = 127` (`fcall.h:74-105`), because the enum assigns each T an +/// even number and lets its R take the next. So one byte tells a reader which +/// direction a message is travelling, which makes a stream carrying both +/// SELF-DEMUXING: `drawterm`'s single descriptor has requests going one way and +/// replies coming back on it, and the parity alone separates them. +/// +/// PaRDeS does not rely on that today — a connection has one role per side +/// (docs/9p.typ §"Layering"), so a server only ever reads T and a client only +/// ever reads R, and each refuses the other by name. This is here because the +/// ENCODING GUARANTEES it and a future 9P-inside-the-wire arrangement over the +/// board's UART would want it, and because a hand-typed number that breaks the +/// parity is a bug the test at the bottom catches for free. +pub fn isT(t: Type) bool { + return @intFromEnum(t) % 2 == 0; +} + +// --------------------------------------------------------------------------- +// constants +// --------------------------------------------------------------------------- + +/// `size[4] type[1] tag[2]`, and `size` counts these seven bytes too. Public +/// because the server half sizes its reply payloads against it: the largest +/// `Rread` that fits an msize is `msize - header_len - 4`. +pub const header_len: usize = 4 + 1 + 2; + +/// `QIDSZ` — `fcall.h:64`, `BIT8SZ+BIT32SZ+BIT64SZ`. +pub const qid_len: usize = 1 + 4 + 8; + +/// `STATFIXLEN` — `fcall.h:66-68`. The fixed part of a `stat` INCLUDING its own +/// leading `size[2]` and the four string count prefixes, excluding the string +/// bytes. `BIT16SZ + QIDSZ + 5*BIT16SZ + 4*BIT32SZ + BIT64SZ` = 49. +pub const stat_fixed: usize = 2 + qid_len + 5 * 2 + 4 * 4 + 8; + +/// `NOTAG` — `fcall.h:71`. The tag on `Tversion`/`Rversion`, which is the one +/// exchange that happens before tags mean anything. Note that `fcall.h` writes +/// it `~0U` and the wire field is two bytes, so it is 0xFFFF and not 0xFFFFFFFF. +pub const notag: u16 = 0xFFFF; + +/// `NOFID` — `fcall.h:121-123`. `Tattach.afid` when no authentication fid was +/// established, which is our only use of it: we serve `Tauth` a refusal. +pub const nofid: u32 = 0xFFFF_FFFF; + +/// `MAXWELEM` — `fcall.h:2`. The most path elements one `Twalk` may carry, and +/// a hard protocol bound rather than a buffer size: `convS2M.c:279-280` and +/// `convM2S.c:170-171` both return failure above it, so a 17-element walk is +/// refused by every implementation and must be split by the client. +pub const max_welem: usize = 16; + +/// The smallest msize we may agree to. NOT from the protocol — 9P has no floor, +/// and Plan 9's devmnt, plan9port's `9p` and our own client all accept 512 +/// (docs/registry.typ, `linux/net/9p/client.c:840-843`). This number exists +/// because the LINUX KERNEL refuses to mount below it, and a mount that fails +/// with `EINVAL` and no message is the worst diagnostic in the set. +pub const min_msize: u32 = 4096; + +/// `IOHDRSZ` — `fcall.h:72`, «ample room for Twrite/Rread header (iounit)». +/// The real `Rread` header is 11 bytes (`size[4] type[1] tag[2] count[4]`) and +/// `Twrite`'s is 23; 24 is the slack both ends have agreed to reserve for +/// thirty years, and `iounit` is quoted to clients as `msize - iohdrsz`. +pub const iohdrsz: u32 = 24; + +/// `ERRMAX` — Plan 9's `libc.h:146`. The buffer a Plan 9 client has for an +/// error string. ADVISORY here: `decode` does not refuse a longer `Rerror`, +/// because refusing a peer's error message is the least useful moment to +/// discover a length limit. The server half truncates its own to this. +pub const errmax: usize = 128; + +// Qid type bits — `u9fs/plan9.h:156-161`, cross-checked against +// `linux/include/net/9p/9p.h:344-352` which adds QTTMP = 0x04. These are the +// top five bits of `Stat.mode` shifted down 24; see `dmdir` below. +pub const qtdir: u8 = 0x80; +pub const qtappend: u8 = 0x40; +pub const qtexcl: u8 = 0x20; +/// 0x10 is `QTMOUNT`, a mounted channel — a thing only a Plan 9 kernel has, and +/// the reason the mode bits below have a gap at bit 28. +pub const qtmount: u8 = 0x10; +pub const qtauth: u8 = 0x08; +pub const qttmp: u8 = 0x04; +/// «plain file» — `plan9.h:161`. Zero, so a `Qid.type` of 0 is not "unset". +pub const qtfile: u8 = 0x00; + +// Mode bits — `u9fs/plan9.h:164-170`, with DMAUTH and DMTMP from +// `ad/crates/ninep/src/sansio/protocol.rs:486-495`: «bit 27 (DMAUTH) ... bit 26 +// (DMTMP) ... (Bit 28 is skipped for historical reasons)». That skipped bit is +// `DMMOUNT`, which is why the top five type bits are not the top five mode +// bits: they are DMDIR, DMAPPEND, DMEXCL, (gap), DMAUTH, DMTMP reproduced from +// the top down into `Qid.type` as QTDIR, QTAPPEND, QTEXCL, QTAUTH, QTTMP. +pub const dmdir: u32 = 0x8000_0000; +pub const dmappend: u32 = 0x4000_0000; +pub const dmexcl: u32 = 0x2000_0000; +pub const dmmount: u32 = 0x1000_0000; +pub const dmauth: u32 = 0x0800_0000; +pub const dmtmp: u32 = 0x0400_0000; +/// The rwx triples, and the ONLY part of `mode` that is a Unix permission. A +/// server that hands the high bits to `chmod`, or a client that hands the low +/// nine to a type test, has confused the two halves of one word. +pub const dmperm: u32 = 0o777; + +comptime { + // The three widths every offset below is derived from. A drifted number + // here is a codec that agrees with nothing, so make it a compile error. + assert(header_len == 7); + assert(qid_len == 13); + assert(stat_fixed == 49); + // Parity is the protocol's, not a convention we maintain by hand. + for (std.enums.values(Type)) |t| { + const even = @intFromEnum(t) % 2 == 0; + assert(isT(t) == even); + assert(std.mem.startsWith(u8, @tagName(t), if (even) "t" else "r")); + } +} + +// --------------------------------------------------------------------------- +// qid +// --------------------------------------------------------------------------- + +/// The server's name for a file: `type[1] version[4] path[8]`, thirteen bytes, +/// `convS2M.c:18-29`. Two files are the same file if and only if their qids +/// are equal, which is the whole contract — `path` identifies the file for the +/// life of the connection and `version` changes on every write, so a client +/// caches against the pair and never against a pathname. +pub const Qid = struct { + /// `qt*` bits. The high bits of `Stat.mode` shifted down 24. + type: u8, + version: u32, + path: u64, + + /// Writes thirteen bytes and returns them. Takes the whole buffer and + /// returns the used slice, so a caller can chain without arithmetic. + pub fn encode(self: Qid, buf: []u8) Error![]u8 { + if (buf.len < qid_len) return error.NoSpace; + buf[0] = self.type; + std.mem.writeInt(u32, buf[1..5], self.version, .little); + std.mem.writeInt(u64, buf[5..13], self.path, .little); + return buf[0..qid_len]; + } + + /// Reads thirteen bytes. Refuses a shorter buffer rather than reading one: + /// `gqid` in `convM2S.c:26-37` returns nil for exactly this case. + pub fn decode(bytes: []const u8) Error!Qid { + if (bytes.len < qid_len) return error.Truncated; + return .{ + .type = bytes[0], + .version = std.mem.readInt(u32, bytes[1..5], .little), + .path = std.mem.readInt(u64, bytes[5..13], .little), + }; + } +}; + +// --------------------------------------------------------------------------- +// stat +// --------------------------------------------------------------------------- + +/// One directory entry, and the payload of `Rstat` and `Twstat`. Layout from +/// `convD2M.c:56-83`: +/// +/// ``` +/// size[2] type[2] dev[4] qid[13] mode[4] atime[4] mtime[4] length[8] +/// name[s] uid[s] gid[s] muid[s] +/// ``` +/// +/// where `[s]` is `n[2]` plus n bytes of UTF-8, NOT NUL-terminated. `size` +/// counts everything after itself, so the record occupies `size() + 2` bytes; +/// see the module header for why that matters twice over. +/// +/// `type` and `dev` are Plan 9 kernel device identifiers and are meaningless +/// off Plan 9 — u9fs sends zeros and so do we, but they are on the wire because +/// the layout is fixed. `muid` is the uid of the last modifier; for a synthetic +/// tree it is whoever attached. +/// +/// A `Twstat` uses the sentinel "don't touch" values that acme(4) and +/// `stat(5)` specify: an empty string, an all-ones integer. Nothing here +/// interprets them; that is the server half's job. +pub const Stat = struct { + type: u16, + dev: u32, + qid: Qid, + mode: u32, + atime: u32, + mtime: u32, + length: u64, + name: []const u8, + uid: []const u8, + gid: []const u8, + muid: []const u8, + + /// The value that goes in the leading `size[2]`: every byte of the record + /// EXCEPT those two. `convD2M.c:46-50` computes `ss = STATFIXLEN + ns` and + /// then writes `ss - BIT16SZ`, so this is `stat_fixed - 2` plus the four + /// string bodies. Written out field by field rather than as 47, because a + /// number nobody can check against a layout is a comment that rots. + /// + /// Fallible: the prefix is two bytes, so a record whose strings do not fit + /// a u16 has no legal encoding and must be refused rather than wrapped. + pub fn size(self: Stat) Error!u16 { + const n = + 2 + // type + 4 + // dev + qid_len + // qid: type[1] version[4] path[8] + 4 + // mode + 4 + // atime + 4 + // mtime + 8 + // length + 2 + self.name.len + + 2 + self.uid.len + + 2 + self.gid.len + + 2 + self.muid.len; + assert(n >= stat_fixed - 2); + if (n > std.math.maxInt(u16)) return error.Overlong; + return @intCast(n); + } + + /// Writes `size[2]` and the record, and returns the `size() + 2` bytes of + /// it. `assert` at the end is `convD2M.c:85-86`'s `if(ss != p - buf)`: the + /// two arithmetics are written separately and must agree. + pub fn encode(self: Stat, buf: []u8) Error![]u8 { + const n = try self.size(); + const total = @as(usize, n) + 2; + if (buf.len < total) return error.NoSpace; + var w: Writer = .init(buf[0..total]); + try w.putU16(n); + try w.putU16(self.type); + try w.putU32(self.dev); + try w.putQid(self.qid); + try w.putU32(self.mode); + try w.putU32(self.atime); + try w.putU32(self.mtime); + try w.putU64(self.length); + try w.putString(self.name); + try w.putString(self.uid); + try w.putString(self.gid); + try w.putString(self.muid); + assert(w.n == total); + return buf[0..total]; + } + + /// Decodes exactly one record from `bytes`, which must be the whole of it — + /// prefix included — and nothing more. The strings BORROW from `bytes`. + /// + /// The equality check on the prefix is the second half of `statcheck` + /// (`convM2D.c:14-22`: walk the four counts, then `if(buf != ebuf) return + /// -1`). It is what makes the double length safe: the caller has already + /// bounded `bytes` by the OUTER count, so demanding that the INNER count + /// agree refuses the classic off-by-two in both directions instead of + /// trusting whichever one the sender got right. + pub fn decode(bytes: []const u8) Error!Stat { + var r: Reader = .init(bytes); + const n = try r.getU16(); + const body = bytes.len - 2; + if (n > body) return error.Truncated; + if (n < body) return error.Trailing; + const self: Stat = .{ + .type = try r.getU16(), + .dev = try r.getU32(), + .qid = try r.getQid(), + .mode = try r.getU32(), + .atime = try r.getU32(), + .mtime = try r.getU32(), + .length = try r.getU64(), + .name = try r.getString(), + .uid = try r.getString(), + .gid = try r.getString(), + .muid = try r.getString(), + }; + try r.end(); + return self; + } +}; + +// --------------------------------------------------------------------------- +// messages +// --------------------------------------------------------------------------- + +/// Every message base 9P2000 defines, with the fields it actually carries. +/// Layouts from `convS2M.c:231-419` and `convM2S.c:73-375`, which are the two +/// halves of the same table and disagree nowhere. +/// +/// The tag names are the type names, so `msgType` is a mechanical mapping and +/// not a table somebody maintains; a variant added here without a `Type` is a +/// compile error. +/// +/// NOT IN HERE: the message tag. A `Msg` is a message's CONTENT, and the tag is +/// the transport's matching of a reply to a request — it is a parameter of +/// `encode` and a field of `Decoded`. Putting it in the union would mean every +/// server handler that builds a reply has to remember to copy it. +/// +/// `Twalk` is the large variant at sixteen slices, so `Msg` is around 280 bytes +/// on a 64-bit host. That is a value passed by const pointer in practice and it +/// buys the thing that matters: a walk decodes with no allocator and no bound +/// the caller has to have guessed. +pub const Msg = union(enum) { + /// The first exchange, tagged `notag`. `msize` is the largest message + /// either end will send, INCLUDING the seven-byte header; `version` is + /// "9P2000" or a string starting with it. + tversion: struct { msize: u32, version: []const u8 }, + /// The server's answer: `msize` no larger than the client's, and `version` + /// either "9P2000" or the literal "unknown" — which is a successful reply + /// meaning "no dialect in common", not an `Rerror`. + rversion: struct { msize: u32, version: []const u8 }, + + tauth: struct { afid: u32, uname: []const u8, aname: []const u8 }, + /// `aqid` and not `qid`: `fcall.h:44` gives `Rauth` its own field, and + /// `convS2M.c:368-370` writes it. Same thirteen bytes, different meaning — + /// the qid of the auth FILE, not of the tree. + rauth: struct { aqid: Qid }, + + /// `afid` is `nofid` when the client did not authenticate. + tattach: struct { fid: u32, afid: u32, uname: []const u8, aname: []const u8 }, + rattach: struct { qid: Qid }, + + /// A STRING and nothing else. Base 9P2000 has no numeric error code; the + /// `errno` field is 9P2000.u's, which this file does not serve. See the + /// module header. + rerror: struct { ename: []const u8 }, + + /// `oldtag` is a u16 like every tag, even though `fcall.h:14` declares + /// `oldtag` as u32 — `convS2M.c:251-253` writes it with `PBIT16`. + tflush: struct { oldtag: u16 }, + rflush: void, + + /// `wname[0..nwname]` are the path elements; anything past `nwname` is + /// undefined and neither encoded nor compared. A zero-element walk is + /// legal and means "clone `fid` into `newfid`". + twalk: struct { + fid: u32, + newfid: u32, + nwname: u16, + wname: [max_welem][]const u8 = @splat(""), + }, + /// `nwqid` may be SHORTER than the request's `nwname`: a partial walk is a + /// successful `Rwalk` with fewer qids, and only a failure on the FIRST + /// element is an `Rerror`. + rwalk: struct { + nwqid: u16, + wqid: [max_welem]Qid = @splat(.{ .type = 0, .version = 0, .path = 0 }), + }, + + /// `mode` is OREAD/OWRITE/ORDWR/OEXEC plus OTRUNC/ORCLOSE, one byte. + topen: struct { fid: u32, mode: u8 }, + /// `iounit`: the largest atomic read or write, or 0 for "no promise". We + /// quote `msize - iohdrsz`. + ropen: struct { qid: Qid, iounit: u32 }, + + /// `perm` is the full mode word — `dmdir` and friends in the high bits, + /// `dmperm` in the low nine. + tcreate: struct { fid: u32, name: []const u8, perm: u32, mode: u8 }, + rcreate: struct { qid: Qid, iounit: u32 }, + + tread: struct { fid: u32, offset: u64, count: u32 }, + /// `count[4]` then the bytes, held as one slice because the count is the + /// slice's length and two ways to say one number is one way to disagree. + /// A reply longer than the request's `count` is a hard `-EIO` to Linux + /// (`net/9p/client.c:1475-1479`), so the server half clamps and this codec + /// carries whatever it is given. + rread: struct { data: []const u8 }, + + twrite: struct { fid: u32, offset: u64, data: []const u8 }, + /// The count actually written, which may be short. + rwrite: struct { count: u32 }, + + tclunk: struct { fid: u32 }, + rclunk: void, + tremove: struct { fid: u32 }, + rremove: void, + + tstat: struct { fid: u32 }, + /// Carries a decoded `Stat`, not a blob, so the double length is computed + /// in one place — `encode` derives the outer count from `stat.size() + 2` + /// and `decode` demands they agree. u9fs keeps `nstat` and a `uchar*` here + /// (`fcall.h:40-41`) and pays for it with `statcheck` as a separate call + /// every caller must remember. + rstat: struct { stat: Stat }, + twstat: struct { fid: u32, stat: Stat }, + rwstat: void, + + /// The type byte this message travels as. Mechanical, by name, so a + /// variant cannot acquire the wrong number. + pub fn msgType(msg: Msg) Type { + return switch (msg) { + inline else => |_, t| @field(Type, @tagName(t)), + }; + } +}; + +/// One complete message off the wire: its tag and its content. The tag is +/// separate for the reason `Msg`'s doc gives — a reply reuses the request's tag +/// and never looks inside it. +pub const Decoded = struct { + tag: u16, + msg: Msg, +}; + +/// How many bytes this message will be, once the caller has enough of it. +/// `null` when there are fewer than four, which is the only answer a stream +/// reader can act on: read more. +/// +/// Deliberately UNVALIDATED. It is the raw `size` field, and it is peeked +/// before the type byte has necessarily arrived, so there is nothing here to +/// check it against. `decode` does the refusing; this only says how much to +/// buffer, and a caller that compares the answer to its negotiated msize +/// refuses an absurd claim before growing anything. +pub fn frameLen(prefix: []const u8) ?u32 { + if (prefix.len < 4) return null; + return std.mem.readInt(u32, prefix[0..4], .little); +} + +/// The whole message's byte count, `size` included, which IS the value of the +/// `size` field. `sizeS2M` in `convS2M.c:38-208`, in the same order, so the two +/// can be read side by side. +/// +/// Computed before a single byte is written, which is what makes `encode`'s +/// `NoSpace` clean: a caller whose buffer is one byte short gets an error and +/// an untouched buffer, not a half-written message. +fn totalLen(msg: Msg) Error!usize { + const body: usize = switch (msg) { + .tversion => |m| 4 + try stringLen(m.version), + .rversion => |m| 4 + try stringLen(m.version), + .tauth => |m| 4 + try stringLen(m.uname) + try stringLen(m.aname), + .rauth => qid_len, + .tattach => |m| 4 + 4 + try stringLen(m.uname) + try stringLen(m.aname), + .rattach => qid_len, + .rerror => |m| try stringLen(m.ename), + .tflush => 2, + .rflush => 0, + .twalk => |m| blk: { + // The bound is the protocol's, and both halves of u9fs return + // failure above it (`convS2M.c:279`, `convM2S.c:170`). On this side + // it is a caller bug — the array is sixteen long — so it asserts. + assert(m.nwname <= max_welem); + var n: usize = 4 + 4 + 2; + for (m.wname[0..m.nwname]) |name| n += try stringLen(name); + break :blk n; + }, + .rwalk => |m| blk: { + assert(m.nwqid <= max_welem); + break :blk 2 + @as(usize, m.nwqid) * qid_len; + }, + .topen => 4 + 1, + .ropen => qid_len + 4, + .tcreate => |m| 4 + try stringLen(m.name) + 4 + 1, + .rcreate => qid_len + 4, + .tread => 4 + 8 + 4, + .rread => |m| try dataLen(m.data), + .twrite => |m| 4 + 8 + try dataLen(m.data), + .rwrite => 4, + .tclunk => 4, + .rclunk => 0, + .tremove => 4, + .rremove => 0, + .tstat => 4, + // THE DOUBLE LENGTH, in the one place it is computed: the outer count, + // then the record, whose own prefix is inside `size() + 2`. + .rstat => |m| 2 + 2 + @as(usize, try m.stat.size()), + .twstat => |m| 4 + 2 + 2 + @as(usize, try m.stat.size()), + .rwstat => 0, + }; + const total = header_len + body; + if (total > std.math.maxInt(u32)) return error.Overlong; + return total; +} + +/// `stringsz` — `convS2M.c:31-36`. The count is two bytes, so a longer string +/// has no encoding and is refused here rather than truncated silently. +fn stringLen(s: []const u8) Error!usize { + if (s.len > std.math.maxInt(u16)) return error.Overlong; + return 2 + s.len; +} + +/// The same for a `count[4]` payload: `Rread`'s and `Twrite`'s data. +fn dataLen(d: []const u8) Error!usize { + if (d.len > std.math.maxInt(u32)) return error.Overlong; + return 4 + d.len; +} + +/// Encodes one message into `buf` and returns the bytes of it, which start at +/// `buf[0]` and are exactly `size` long. +/// +/// `tag` is a parameter and not a field of `Msg`: a server handler builds a +/// reply and the transport supplies the request's tag, so the two cannot drift. +/// `notag` on anything but `Tversion`/`Rversion` is the caller's business. +pub fn encode(msg: Msg, tag: u16, buf: []u8) Error![]u8 { + const total = try totalLen(msg); + if (total > buf.len) return error.NoSpace; + + // The writer is bounded to `total` and not to `buf`, so a disagreement + // between `totalLen` and the field walk below cannot scribble past the + // message — it becomes `NoSpace` here or the assert at the end. + var w: Writer = .init(buf[0..total]); + try w.putU32(@intCast(total)); + try w.putByte(@intFromEnum(msg.msgType())); + try w.putU16(tag); + + switch (msg) { + .tversion => |m| { + try w.putU32(m.msize); + try w.putString(m.version); + }, + .rversion => |m| { + try w.putU32(m.msize); + try w.putString(m.version); + }, + .tauth => |m| { + try w.putU32(m.afid); + try w.putString(m.uname); + try w.putString(m.aname); + }, + .rauth => |m| try w.putQid(m.aqid), + .tattach => |m| { + try w.putU32(m.fid); + try w.putU32(m.afid); + try w.putString(m.uname); + try w.putString(m.aname); + }, + .rattach => |m| try w.putQid(m.qid), + .rerror => |m| try w.putString(m.ename), + .tflush => |m| try w.putU16(m.oldtag), + .rflush => {}, + .twalk => |m| { + try w.putU32(m.fid); + try w.putU32(m.newfid); + try w.putU16(m.nwname); + for (m.wname[0..m.nwname]) |name| try w.putString(name); + }, + .rwalk => |m| { + try w.putU16(m.nwqid); + for (m.wqid[0..m.nwqid]) |qid| try w.putQid(qid); + }, + .topen => |m| { + try w.putU32(m.fid); + try w.putByte(m.mode); + }, + .ropen => |m| { + try w.putQid(m.qid); + try w.putU32(m.iounit); + }, + .tcreate => |m| { + try w.putU32(m.fid); + try w.putString(m.name); + try w.putU32(m.perm); + try w.putByte(m.mode); + }, + .rcreate => |m| { + try w.putQid(m.qid); + try w.putU32(m.iounit); + }, + .tread => |m| { + try w.putU32(m.fid); + try w.putU64(m.offset); + try w.putU32(m.count); + }, + .rread => |m| { + try w.putU32(@intCast(m.data.len)); + try w.putBytes(m.data); + }, + .twrite => |m| { + try w.putU32(m.fid); + try w.putU64(m.offset); + try w.putU32(@intCast(m.data.len)); + try w.putBytes(m.data); + }, + .rwrite => |m| try w.putU32(m.count), + .tclunk => |m| try w.putU32(m.fid), + .rclunk => {}, + .tremove => |m| try w.putU32(m.fid), + .rremove => {}, + .tstat => |m| try w.putU32(m.fid), + .rstat => |m| { + // Outer count first: the whole record, its own prefix included. + try w.putU16(try m.stat.size() + 2); + try w.putStat(m.stat); + }, + .twstat => |m| { + try w.putU32(m.fid); + try w.putU16(try m.stat.size() + 2); + try w.putStat(m.stat); + }, + .rwstat => {}, + } + + // `convS2M.c:420-421`: `if(size != p-ap) return 0`. The two arithmetics are + // deliberately separate and this is the only thing that keeps them honest. + assert(w.n == total); + return buf[0..total]; +} + +/// Decodes exactly one complete message. `bytes` must be the message and +/// nothing else — `frameLen` is how a reader knows where that ends — and every +/// slice in the result BORROWS from it. +/// +/// Four ways this refuses, in the order the checks run, because the order is +/// what makes a stream reader's life simple: +/// * fewer than seven bytes, or `size` past the end -> `Truncated`, meaning +/// "come back with more". +/// * `size` short of the end -> `Trailing`. Two messages were handed over as +/// one, which is a framing bug in the caller, not a short read. +/// * a `size` that cannot hold a header -> `BadValue`. No encoder produced it. +/// * a type byte 9P2000 does not define, or defines illegal -> `BadTag`. +pub fn decode(bytes: []const u8) Error!Decoded { + if (bytes.len < header_len) return error.Truncated; + const size = std.mem.readInt(u32, bytes[0..4], .little); + // `convM2S.c:65-66` refuses this too, and it must be refused BEFORE the + // comparison against `bytes.len`: a size of 3 on a 3-byte buffer would + // otherwise slice a header out of nothing. + if (size < header_len) return error.BadValue; + if (size > bytes.len) return error.Truncated; + if (size < bytes.len) return error.Trailing; + + const t: Type = @enumFromInt(bytes[4]); + const tag = std.mem.readInt(u16, bytes[5..7], .little); + + // Bounded by `size` and not by `bytes`, which is the same thing here only + // because of the two checks above; keep it explicit so it stays true if a + // caller is ever allowed to pass a longer buffer. + var r: Reader = .init(bytes[header_len..size]); + + const msg: Msg = switch (t) { + .tversion => .{ .tversion = .{ .msize = try r.getU32(), .version = try r.getString() } }, + .rversion => .{ .rversion = .{ .msize = try r.getU32(), .version = try r.getString() } }, + .tauth => .{ .tauth = .{ + .afid = try r.getU32(), + .uname = try r.getString(), + .aname = try r.getString(), + } }, + .rauth => .{ .rauth = .{ .aqid = try r.getQid() } }, + .tattach => .{ .tattach = .{ + .fid = try r.getU32(), + .afid = try r.getU32(), + .uname = try r.getString(), + .aname = try r.getString(), + } }, + .rattach => .{ .rattach = .{ .qid = try r.getQid() } }, + .rerror => .{ .rerror = .{ .ename = try r.getString() } }, + .tflush => .{ .tflush = .{ .oldtag = try r.getU16() } }, + .rflush => .rflush, + .twalk => blk: { + var m: Msg = .{ .twalk = .{ + .fid = try r.getU32(), + .newfid = try r.getU32(), + .nwname = try r.getU16(), + } }; + // Checked before the loop, so a hostile 65535 never reaches the + // array. `convM2S.c:170-171` does the same and for the same reason. + if (m.twalk.nwname > max_welem) return error.Overlong; + for (m.twalk.wname[0..m.twalk.nwname]) |*name| name.* = try r.getString(); + break :blk m; + }, + .rwalk => blk: { + var m: Msg = .{ .rwalk = .{ .nwqid = try r.getU16() } }; + if (m.rwalk.nwqid > max_welem) return error.Overlong; + for (m.rwalk.wqid[0..m.rwalk.nwqid]) |*qid| qid.* = try r.getQid(); + break :blk m; + }, + .topen => .{ .topen = .{ .fid = try r.getU32(), .mode = try r.getByte() } }, + .ropen => .{ .ropen = .{ .qid = try r.getQid(), .iounit = try r.getU32() } }, + .tcreate => .{ .tcreate = .{ + .fid = try r.getU32(), + .name = try r.getString(), + .perm = try r.getU32(), + .mode = try r.getByte(), + } }, + .rcreate => .{ .rcreate = .{ .qid = try r.getQid(), .iounit = try r.getU32() } }, + .tread => .{ .tread = .{ + .fid = try r.getU32(), + .offset = try r.getU64(), + .count = try r.getU32(), + } }, + .rread => .{ .rread = .{ .data = try r.getData() } }, + .twrite => .{ .twrite = .{ + .fid = try r.getU32(), + .offset = try r.getU64(), + .data = try r.getData(), + } }, + .rwrite => .{ .rwrite = .{ .count = try r.getU32() } }, + .tclunk => .{ .tclunk = .{ .fid = try r.getU32() } }, + .rclunk => .rclunk, + .tremove => .{ .tremove = .{ .fid = try r.getU32() } }, + .rremove => .rremove, + .tstat => .{ .tstat = .{ .fid = try r.getU32() } }, + .rstat => .{ .rstat = .{ .stat = try Stat.decode(try r.getBlob16()) } }, + .twstat => .{ .twstat = .{ + .fid = try r.getU32(), + .stat = try Stat.decode(try r.getBlob16()), + } }, + .rwstat => .rwstat, + // «Terror = 106, /* illegal */». A peer that sent one is not speaking + // 9P2000, and every other unlisted byte is a `.u`/`.L` message or + // noise. Both are refused here, which is also why `Type` is + // non-exhaustive: this switch is reachable with any byte. + .terror, _ => return error.BadTag, + }; + + try r.end(); + return .{ .tag = tag, .msg = msg }; +} + +// --------------------------------------------------------------------------- +// primitives +// --------------------------------------------------------------------------- +// +// Explicit widths, little-endian, one field at a time. `GBIT*`/`PBIT*` in +// `fcall.h:48-58` are the reference, and they are byte-at-a-time shifts for +// exactly the reason this file does not blit a struct: the sender's word order +// and padding are not the protocol. + +const Writer = struct { + buf: []u8, + n: usize = 0, + + fn init(buf: []u8) Writer { + return .{ .buf = buf }; + } + + /// `n <= buf.len` is the invariant every putter preserves, which is what + /// makes the subtraction safe. + fn room(w: *Writer, k: usize) Error![]u8 { + if (w.buf.len - w.n < k) return error.NoSpace; + defer w.n += k; + return w.buf[w.n..][0..k]; + } + + fn putByte(w: *Writer, v: u8) Error!void { + (try w.room(1))[0] = v; + } + + fn putU16(w: *Writer, v: u16) Error!void { + std.mem.writeInt(u16, (try w.room(2))[0..2], v, .little); + } + + fn putU32(w: *Writer, v: u32) Error!void { + std.mem.writeInt(u32, (try w.room(4))[0..4], v, .little); + } + + fn putU64(w: *Writer, v: u64) Error!void { + std.mem.writeInt(u64, (try w.room(8))[0..8], v, .little); + } + + fn putBytes(w: *Writer, v: []const u8) Error!void { + @memcpy(try w.room(v.len), v); + } + + /// `n[2]` then the bytes, NOT NUL-terminated — `pstring`, `convS2M.c:4-16`. + /// The length was already refused by `stringLen` before anything was + /// written, so this asserts rather than erroring: reaching it with a longer + /// string means `totalLen` and this switch disagree. + fn putString(w: *Writer, v: []const u8) Error!void { + assert(v.len <= std.math.maxInt(u16)); + try w.putU16(@intCast(v.len)); + try w.putBytes(v); + } + + fn putQid(w: *Writer, v: Qid) Error!void { + _ = try v.encode(try w.room(qid_len)); + } + + fn putStat(w: *Writer, v: Stat) Error!void { + const total = @as(usize, try v.size()) + 2; + _ = try v.encode(try w.room(total)); + } +}; + +const Reader = struct { + bytes: []const u8, + i: usize = 0, + + fn init(bytes: []const u8) Reader { + return .{ .bytes = bytes }; + } + + /// The one place this file indexes, and the one place it can refuse to. + /// `i <= bytes.len` always, so the subtraction cannot wrap. + fn take(r: *Reader, n: usize) Error![]const u8 { + if (r.bytes.len - r.i < n) return error.Truncated; + defer r.i += n; + return r.bytes[r.i..][0..n]; + } + + fn getByte(r: *Reader) Error!u8 { + return (try r.take(1))[0]; + } + + fn getU16(r: *Reader) Error!u16 { + return std.mem.readInt(u16, (try r.take(2))[0..2], .little); + } + + fn getU32(r: *Reader) Error!u32 { + return std.mem.readInt(u32, (try r.take(4))[0..4], .little); + } + + fn getU64(r: *Reader) Error!u64 { + return std.mem.readInt(u64, (try r.take(8))[0..8], .little); + } + + /// `gstring`, `convM2S.c:4-22`, minus the memmove: u9fs shuffles the bytes + /// down over the count to make room for a '\0' because its callers are C + /// string functions. Ours borrow, so the slice IS the string and the buffer + /// is untouched. + fn getString(r: *Reader) Error![]const u8 { + return r.take(try r.getU16()); + } + + /// `count[4]` then the bytes: `Rread`'s and `Twrite`'s payload. A count + /// past the message is `Truncated` and not a clamp — Linux clamps here + /// (`protocol.c:386-388`) and then has to catch the lie again in + /// `client.c:1475-1479`. Refusing once is cheaper and says more. + fn getData(r: *Reader) Error![]const u8 { + return r.take(try r.getU32()); + } + + /// `count[2]` then the bytes: the OUTER count of an `Rstat`/`Twstat` stat. + /// Slicing exactly here is what lets `Stat.decode` insist that the record's + /// own prefix agrees, which is the whole defence against the double length. + fn getBlob16(r: *Reader) Error![]const u8 { + return r.take(try r.getU16()); + } + + fn getQid(r: *Reader) Error!Qid { + return Qid.decode(try r.take(qid_len)); + } + + fn end(r: *Reader) Error!void { + if (r.i != r.bytes.len) return error.Trailing; + } +}; + +// --------------------------------------------------------------------------- +// tests +// --------------------------------------------------------------------------- +// +// Three obligations, and the third is the one that is usually skipped. +// +// 1. every message round-trips to an equal value, because a hand-written +// codec is a codec whose two halves drift; +// 2. every malformed shape is REFUSED and none of them panics, because this +// parser is fed by a socket; +// 3. the bytes are the RIGHT bytes. A round-trip test proves the encoder and +// the decoder agree with each other and nothing about whether they agree +// with plan9port's `9p`, which is who will actually be on the far end. So +// four messages are hand-verified against `u9fs/convS2M.c` as literal +// arrays with the line numbers attached. + +const testing = std.testing; + +fn roundTrip(buf: []u8, tag: u16, msg: Msg) !Msg { + const bytes = try encode(msg, tag, buf); + // The framing has to agree with the encoder before anything else is worth + // checking: `size` includes itself, so this is also the regression test for + // the first of the module header's two facts. + try testing.expectEqual(bytes.len, frameLen(bytes).?); + const got = try decode(bytes); + try testing.expectEqual(tag, got.tag); + try testing.expectEqual(msg.msgType(), got.msg.msgType()); + try expectMsgEqual(msg, got.msg); + return got.msg; +} + +fn expectStatEqual(want: Stat, have: Stat) !void { + try testing.expectEqual(want.type, have.type); + try testing.expectEqual(want.dev, have.dev); + try testing.expectEqual(want.qid, have.qid); + try testing.expectEqual(want.mode, have.mode); + try testing.expectEqual(want.atime, have.atime); + try testing.expectEqual(want.mtime, have.mtime); + try testing.expectEqual(want.length, have.length); + try testing.expectEqualStrings(want.name, have.name); + try testing.expectEqualStrings(want.uid, have.uid); + try testing.expectEqualStrings(want.gid, have.gid); + try testing.expectEqualStrings(want.muid, have.muid); +} + +/// Field by field, because `std.meta.eql` is wrong here twice: a decoded slice +/// points into the wire buffer and never compares equal by pointer, and +/// `Twalk.wname` past `nwname` is scratch the decoder does not invent. +fn expectMsgEqual(want: Msg, have: Msg) !void { + switch (want) { + .tversion => |w| { + try testing.expectEqual(w.msize, have.tversion.msize); + try testing.expectEqualStrings(w.version, have.tversion.version); + }, + .rversion => |w| { + try testing.expectEqual(w.msize, have.rversion.msize); + try testing.expectEqualStrings(w.version, have.rversion.version); + }, + .tauth => |w| { + try testing.expectEqual(w.afid, have.tauth.afid); + try testing.expectEqualStrings(w.uname, have.tauth.uname); + try testing.expectEqualStrings(w.aname, have.tauth.aname); + }, + .rauth => |w| try testing.expectEqual(w.aqid, have.rauth.aqid), + .tattach => |w| { + try testing.expectEqual(w.fid, have.tattach.fid); + try testing.expectEqual(w.afid, have.tattach.afid); + try testing.expectEqualStrings(w.uname, have.tattach.uname); + try testing.expectEqualStrings(w.aname, have.tattach.aname); + }, + .rattach => |w| try testing.expectEqual(w.qid, have.rattach.qid), + .rerror => |w| try testing.expectEqualStrings(w.ename, have.rerror.ename), + .tflush => |w| try testing.expectEqual(w.oldtag, have.tflush.oldtag), + .rflush, .rclunk, .rremove, .rwstat => {}, + .twalk => |w| { + try testing.expectEqual(w.fid, have.twalk.fid); + try testing.expectEqual(w.newfid, have.twalk.newfid); + try testing.expectEqual(w.nwname, have.twalk.nwname); + for (w.wname[0..w.nwname], have.twalk.wname[0..w.nwname]) |a, b| + try testing.expectEqualStrings(a, b); + }, + .rwalk => |w| { + try testing.expectEqual(w.nwqid, have.rwalk.nwqid); + for (w.wqid[0..w.nwqid], have.rwalk.wqid[0..w.nwqid]) |a, b| + try testing.expectEqual(a, b); + }, + .topen => |w| { + try testing.expectEqual(w.fid, have.topen.fid); + try testing.expectEqual(w.mode, have.topen.mode); + }, + .ropen => |w| { + try testing.expectEqual(w.qid, have.ropen.qid); + try testing.expectEqual(w.iounit, have.ropen.iounit); + }, + .tcreate => |w| { + try testing.expectEqual(w.fid, have.tcreate.fid); + try testing.expectEqualStrings(w.name, have.tcreate.name); + try testing.expectEqual(w.perm, have.tcreate.perm); + try testing.expectEqual(w.mode, have.tcreate.mode); + }, + .rcreate => |w| { + try testing.expectEqual(w.qid, have.rcreate.qid); + try testing.expectEqual(w.iounit, have.rcreate.iounit); + }, + .tread => |w| { + try testing.expectEqual(w.fid, have.tread.fid); + try testing.expectEqual(w.offset, have.tread.offset); + try testing.expectEqual(w.count, have.tread.count); + }, + .rread => |w| try testing.expectEqualStrings(w.data, have.rread.data), + .twrite => |w| { + try testing.expectEqual(w.fid, have.twrite.fid); + try testing.expectEqual(w.offset, have.twrite.offset); + try testing.expectEqualStrings(w.data, have.twrite.data); + }, + .rwrite => |w| try testing.expectEqual(w.count, have.rwrite.count), + .tclunk => |w| try testing.expectEqual(w.fid, have.tclunk.fid), + .tremove => |w| try testing.expectEqual(w.fid, have.tremove.fid), + .tstat => |w| try testing.expectEqual(w.fid, have.tstat.fid), + .rstat => |w| try expectStatEqual(w.stat, have.rstat.stat), + .twstat => |w| { + try testing.expectEqual(w.fid, have.twstat.fid); + try expectStatEqual(w.stat, have.twstat.stat); + }, + } +} + +const sample_qid: Qid = .{ .type = qtdir, .version = 3, .path = 0x0102_0304_0506_0708 }; + +const sample_stat: Stat = .{ + .type = 0, + .dev = 0, + .qid = sample_qid, + .mode = dmdir | 0o755, + .atime = 1, + .mtime = 2, + .length = 0, + .name = "body", + .uid = "goblin", + .gid = "goblin", + .muid = "goblin", +}; + +test "9p: the type numbers and their parity are the protocol's own" { + // Copied from `u9fs/fcall.h:74-105`. Asserted as literals because a + // renumbering here is a codec that talks to nothing, and it must be a diff + // somebody reads rather than a silent change. + try testing.expectEqual(@as(u8, 100), @intFromEnum(Type.tversion)); + try testing.expectEqual(@as(u8, 106), @intFromEnum(Type.terror)); + try testing.expectEqual(@as(u8, 107), @intFromEnum(Type.rerror)); + try testing.expectEqual(@as(u8, 126), @intFromEnum(Type.twstat)); + try testing.expectEqual(@as(u8, 127), @intFromEnum(Type.rwstat)); + + // Twenty-eight numbers, 100..127 inclusive, no gaps and no strays. + try testing.expectEqual(@as(usize, 28), std.enums.values(Type).len); + for (std.enums.values(Type), 100..) |t, want| try testing.expectEqual(@as(u8, @intCast(want)), @intFromEnum(t)); + + try testing.expect(isT(.tversion)); + try testing.expect(!isT(.rversion)); + try testing.expect(isT(.twstat)); + try testing.expect(!isT(.rwstat)); + + // `notag` is two bytes wide even though `fcall.h:71` writes `~0U`. + try testing.expectEqual(@as(u16, 0xFFFF), notag); + try testing.expectEqual(@as(u32, 0xFFFF_FFFF), nofid); + try testing.expectEqual(@as(usize, 16), max_welem); +} + +test "9p: a qid is thirteen bytes" { + var buf: [32]u8 = undefined; + const bytes = try sample_qid.encode(&buf); + try testing.expectEqual(qid_len, bytes.len); + try testing.expectEqual(@as(usize, 13), bytes.len); + try testing.expectEqual(sample_qid, try Qid.decode(bytes)); + // Twelve bytes is not a qid, and a decoder that read one anyway would be + // reading the next field's first byte as the top of `path`. + try testing.expectError(error.Truncated, Qid.decode(bytes[0..12])); + try testing.expectError(error.NoSpace, sample_qid.encode(buf[0..12])); +} + +test "9p: an encoded stat is size() + 2 bytes" { + var buf: [256]u8 = undefined; + const bytes = try sample_stat.encode(&buf); + const n = try sample_stat.size(); + try testing.expectEqual(@as(usize, n) + 2, bytes.len); + // `STATFIXLEN - BIT16SZ` plus the four string bodies: 47 + 4 + 6 + 6 + 6. + try testing.expectEqual(@as(u16, 69), n); + try testing.expectEqual(stat_fixed - 2 + 22, n); + // The prefix on the wire is the count EXCLUDING itself — `convD2M.c:48-51`. + try testing.expectEqual(n, std.mem.readInt(u16, bytes[0..2], .little)); + try expectStatEqual(sample_stat, try Stat.decode(bytes)); + + // Empty strings still cost their counts: 47 and nothing more. + const bare: Stat = .{ + .type = 0, + .dev = 0, + .qid = .{ .type = qtfile, .version = 0, .path = 0 }, + .mode = 0, + .atime = 0, + .mtime = 0, + .length = 0, + .name = "", + .uid = "", + .gid = "", + .muid = "", + }; + try testing.expectEqual(@as(u16, 47), try bare.size()); + try testing.expectEqual(@as(usize, 49), (try bare.encode(&buf)).len); +} + +test "9p: every message round-trips" { + var buf: [512]u8 = undefined; + + _ = try roundTrip(&buf, notag, .{ .tversion = .{ .msize = 8192, .version = "9P2000" } }); + _ = try roundTrip(&buf, notag, .{ .rversion = .{ .msize = 8192, .version = "9P2000" } }); + // "unknown" is a SUCCESSFUL Rversion meaning no dialect in common, and the + // codec must carry it like any other string rather than treat it as an + // error path. + _ = try roundTrip(&buf, notag, .{ .rversion = .{ .msize = min_msize, .version = "unknown" } }); + _ = try roundTrip(&buf, 1, .{ .tauth = .{ .afid = 1, .uname = "goblin", .aname = "" } }); + _ = try roundTrip(&buf, 1, .{ .rauth = .{ .aqid = .{ .type = qtauth, .version = 0, .path = 9 } } }); + _ = try roundTrip(&buf, 2, .{ .tattach = .{ .fid = 0, .afid = nofid, .uname = "goblin", .aname = "" } }); + _ = try roundTrip(&buf, 2, .{ .rattach = .{ .qid = sample_qid } }); + _ = try roundTrip(&buf, 3, .{ .rerror = .{ .ename = "no such file" } }); + _ = try roundTrip(&buf, 4, .{ .tflush = .{ .oldtag = 3 } }); + _ = try roundTrip(&buf, 4, .rflush); + _ = try roundTrip(&buf, 5, .{ .twalk = .{ .fid = 0, .newfid = 1, .nwname = 2, .wname = .{ "7", "body" } ++ @as([max_welem - 2][]const u8, @splat("")) } }); + _ = try roundTrip(&buf, 5, .{ .rwalk = .{ .nwqid = 2, .wqid = .{ sample_qid, sample_qid } ++ @as([max_welem - 2]Qid, @splat(sample_qid)) } }); + _ = try roundTrip(&buf, 6, .{ .topen = .{ .fid = 1, .mode = 0 } }); + _ = try roundTrip(&buf, 6, .{ .ropen = .{ .qid = sample_qid, .iounit = 8192 - iohdrsz } }); + _ = try roundTrip(&buf, 7, .{ .tcreate = .{ .fid = 1, .name = "new", .perm = dmdir | 0o777, .mode = 2 } }); + _ = try roundTrip(&buf, 7, .{ .rcreate = .{ .qid = sample_qid, .iounit = 0 } }); + _ = try roundTrip(&buf, 8, .{ .tread = .{ .fid = 1, .offset = 0xdead_beef_cafe, .count = 4096 } }); + _ = try roundTrip(&buf, 8, .{ .rread = .{ .data = "hello" } }); + // A zero-byte Rread is end of file and not an error, which is exactly what + // docs/9p.typ promises a pty reader on exit. + _ = try roundTrip(&buf, 8, .{ .rread = .{ .data = "" } }); + _ = try roundTrip(&buf, 9, .{ .twrite = .{ .fid = 1, .offset = 0, .data = "Edit ,d" } }); + _ = try roundTrip(&buf, 9, .{ .twrite = .{ .fid = 1, .offset = 0, .data = "" } }); + _ = try roundTrip(&buf, 9, .{ .rwrite = .{ .count = 7 } }); + _ = try roundTrip(&buf, 10, .{ .tclunk = .{ .fid = 1 } }); + _ = try roundTrip(&buf, 10, .rclunk); + _ = try roundTrip(&buf, 11, .{ .tremove = .{ .fid = 1 } }); + _ = try roundTrip(&buf, 11, .rremove); + _ = try roundTrip(&buf, 12, .{ .tstat = .{ .fid = 1 } }); + _ = try roundTrip(&buf, 12, .{ .rstat = .{ .stat = sample_stat } }); + _ = try roundTrip(&buf, 13, .{ .twstat = .{ .fid = 1, .stat = sample_stat } }); + _ = try roundTrip(&buf, 13, .rwstat); + + // Every type that has a message got one. The count is the thirteen pairs + // plus Rerror; `Terror` is illegal and has no variant, which is what the + // arithmetic below is really asserting. + try testing.expectEqual(@as(usize, 27), @typeInfo(Msg).@"union".fields.len); + try testing.expectEqual(std.enums.values(Type).len - 1, @typeInfo(Msg).@"union".fields.len); +} + +test "9p: empty and maximum-length strings survive the trip" { + var buf: [70_000]u8 = undefined; + + // Empty is not absent: the count is still two bytes. + const empty = try roundTrip(&buf, 1, .{ .tattach = .{ .fid = 0, .afid = nofid, .uname = "", .aname = "" } }); + try testing.expectEqual(@as(usize, 0), empty.tattach.uname.len); + try testing.expectEqual(@as(usize, header_len + 4 + 4 + 2 + 2), (try encode(empty, 1, &buf)).len); + + // The largest string a `n[2]` count can describe, and the one past it. + var big: [65_536]u8 = undefined; + @memset(&big, 'x'); + const max = big[0..std.math.maxInt(u16)]; + const got = try roundTrip(&buf, 1, .{ .rerror = .{ .ename = max } }); + try testing.expectEqual(@as(usize, 65_535), got.rerror.ename.len); + try testing.expectError(error.Overlong, encode(.{ .rerror = .{ .ename = &big } }, 1, &buf)); + + // ...and a stat whose strings overflow its own two-byte prefix. Refused by + // `size()`, which is the only place that arithmetic happens. + var wide = sample_stat; + wide.name = max; + try testing.expectError(error.Overlong, wide.size()); + try testing.expectError(error.Overlong, encode(.{ .rstat = .{ .stat = wide } }, 1, &buf)); +} + +test "9p: Twalk carries 0, 1 and 16 elements and refuses 17" { + var buf: [512]u8 = undefined; + + // Zero elements is a legal walk and means "clone the fid". + const zero = try roundTrip(&buf, 1, .{ .twalk = .{ .fid = 0, .newfid = 1, .nwname = 0 } }); + try testing.expectEqual(@as(u16, 0), zero.twalk.nwname); + try testing.expectEqual(@as(usize, header_len + 4 + 4 + 2), (try encode(zero, 1, &buf)).len); + + _ = try roundTrip(&buf, 1, .{ .twalk = .{ + .fid = 0, + .newfid = 1, + .nwname = 1, + .wname = .{"body"} ++ @as([max_welem - 1][]const u8, @splat("")), + } }); + + // MAXWELEM exactly, all distinct so a swapped index cannot pass. + const names: [max_welem][]const u8 = .{ "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p" }; + const full = try roundTrip(&buf, 1, .{ .twalk = .{ .fid = 0, .newfid = 1, .nwname = max_welem, .wname = names } }); + try testing.expectEqual(@as(u16, 16), full.twalk.nwname); + for (names, full.twalk.wname[0..max_welem]) |a, b| try testing.expectEqualStrings(a, b); + // Rwalk's bound is the same and its own. + _ = try roundTrip(&buf, 1, .{ .rwalk = .{ .nwqid = max_welem, .wqid = @splat(sample_qid) } }); + + // Seventeen. Hand-built, because the encoder's array cannot hold one — the + // point is that a PEER can send it and must be refused before the count + // reaches an array of sixteen. + var raw: [256]u8 = undefined; + const bad = blk: { + var w: Writer = .init(&raw); + try w.putU32(0); // patched below + try w.putByte(@intFromEnum(Type.twalk)); + try w.putU16(1); + try w.putU32(0); + try w.putU32(1); + try w.putU16(17); + for (0..17) |i| try w.putString(&[_]u8{@intCast('a' + i)}); + std.mem.writeInt(u32, raw[0..4], @intCast(w.n), .little); + break :blk raw[0..w.n]; + }; + try testing.expectEqual(@as(usize, header_len + 4 + 4 + 2 + 17 * 3), bad.len); + try testing.expectError(error.Overlong, decode(bad)); + + // Same for Rwalk: seventeen qids is 221 bytes of legal-looking message. + const bad_r = blk: { + var w: Writer = .init(&raw); + try w.putU32(0); + try w.putByte(@intFromEnum(Type.rwalk)); + try w.putU16(1); + try w.putU16(17); + for (0..17) |_| try w.putQid(sample_qid); + std.mem.writeInt(u32, raw[0..4], @intCast(w.n), .little); + break :blk raw[0..w.n]; + }; + try testing.expectError(error.Overlong, decode(bad_r)); +} + +test "9p: the stat double length" { + var buf: [512]u8 = undefined; + + // THE fact. Rstat is `count[2]` then a record that begins with its own + // `size[2]`, and the outer number is the inner one plus two — + // `linux/net/9p/client.c:1633` reads it as "wS" and drops the first w. + var good: [512]u8 = undefined; + const n = blk: { + const bytes = try encode(.{ .rstat = .{ .stat = sample_stat } }, 1, &buf); + @memcpy(good[0..bytes.len], bytes); + break :blk bytes.len; + }; + const inner = try sample_stat.size(); + try testing.expectEqual(inner + 2, std.mem.readInt(u16, good[header_len..][0..2], .little)); + try testing.expectEqual(inner, std.mem.readInt(u16, good[header_len + 2 ..][0..2], .little)); + try testing.expectEqual(header_len + 2 + @as(usize, inner) + 2, n); + + // Twstat wraps the same pair behind a fid — `client.c:1776`, "dwS". + const w_bytes = try encode(.{ .twstat = .{ .fid = 7, .stat = sample_stat } }, 1, &buf); + try testing.expectEqual(inner + 2, std.mem.readInt(u16, w_bytes[header_len + 4 ..][0..2], .little)); + try testing.expectEqual(inner, std.mem.readInt(u16, w_bytes[header_len + 6 ..][0..2], .little)); + + // Now three ways to get it wrong, which is the whole reason `Stat.decode` + // is handed an exact slice instead of a cursor. Each is two bytes of edit + // on a message that is otherwise perfect, and each is refused. + var off: [512]u8 = undefined; + + // THE CLASSIC: the outer count written without the +2, so the record's own + // prefix then claims two bytes more than the outer count allowed. + @memcpy(off[0..n], good[0..n]); + std.mem.writeInt(u16, off[header_len..][0..2], inner, .little); + try testing.expectError(error.Truncated, decode(off[0..n])); + + // The outer count too large, which is the same mistake made twice. + @memcpy(off[0..n], good[0..n]); + std.mem.writeInt(u16, off[header_len..][0..2], inner + 4, .little); + try testing.expectError(error.Truncated, decode(off[0..n])); + + // The INNER count wrong instead, in both directions: a record that claims + // more than the outer count fits, and one that leaves bytes over inside it. + @memcpy(off[0..n], good[0..n]); + std.mem.writeInt(u16, off[header_len + 2 ..][0..2], inner + 2, .little); + try testing.expectError(error.Truncated, decode(off[0..n])); + + @memcpy(off[0..n], good[0..n]); + std.mem.writeInt(u16, off[header_len + 2 ..][0..2], inner - 1, .little); + try testing.expectError(error.Trailing, decode(off[0..n])); +} + +/// Every prefix of a complete message must be refused, in both of the two +/// shapes a short message arrives in: +/// * off a socket, where `size` still claims the whole thing and the header +/// check catches it; +/// * as a message that LIES about being complete, where `size` agrees with +/// the buffer and only the per-field walk can catch it. This is the one +/// that exercises every field boundary, and the one an attacker sends. +/// Neither may panic and neither may parse. +fn expectTruncatedAtEveryBoundary(full: []const u8) !void { + var scratch: [1024]u8 = undefined; + var n: usize = 0; + while (n < full.len) : (n += 1) { + try testing.expectError(error.Truncated, decode(full[0..n])); + if (n < header_len) continue; + @memcpy(scratch[0..n], full[0..n]); + std.mem.writeInt(u32, scratch[0..4], @intCast(n), .little); + try testing.expectError(error.Truncated, decode(scratch[0..n])); + } + // The complete message, by contrast, is fine — otherwise the loop above + // would pass for a message that never decodes at all. + _ = try decode(full); +} + +test "9p: truncation at every field boundary is refused" { + var buf: [512]u8 = undefined; + + // Tversion: size, type, tag, msize, a count, a string. + try expectTruncatedAtEveryBoundary(try encode( + .{ .tversion = .{ .msize = 8192, .version = "9P2000" } }, + notag, + &buf, + )); + // Twalk: two fids, a count, and then a loop of counted strings, which is + // the only variable-arity field in the protocol. + try expectTruncatedAtEveryBoundary(try encode(.{ .twalk = .{ + .fid = 1, + .newfid = 2, + .nwname = 3, + .wname = .{ "usr", "", "bin" } ++ @as([max_welem - 3][]const u8, @splat("")), + } }, 1, &buf)); + // Tread: the widest fixed body, and the one whose 8-byte offset a + // native-struct blit would misalign. + try expectTruncatedAtEveryBoundary(try encode( + .{ .tread = .{ .fid = 1, .offset = 0x0102_0304_0506_0708, .count = 8168 } }, + 1, + &buf, + )); + // Rstat: both lengths, and every field of the record behind them. + try expectTruncatedAtEveryBoundary(try encode(.{ .rstat = .{ .stat = sample_stat } }, 1, &buf)); + // Rread, whose count is a u32 and whose payload is the message's tail. + try expectTruncatedAtEveryBoundary(try encode(.{ .rread = .{ .data = "12345678" } }, 1, &buf)); + // Rwalk, the other variable-arity body. + try expectTruncatedAtEveryBoundary(try encode( + .{ .rwalk = .{ .nwqid = 3, .wqid = @splat(sample_qid) } }, + 1, + &buf, + )); + // Twstat: a fid in front of the double length. + try expectTruncatedAtEveryBoundary(try encode(.{ .twstat = .{ .fid = 1, .stat = sample_stat } }, 1, &buf)); +} + +test "9p: a size field that disagrees with the buffer is refused" { + var buf: [512]u8 = undefined; + const bytes = try encode(.{ .tclunk = .{ .fid = 1 } }, 1, &buf); + try testing.expectEqual(@as(usize, 11), bytes.len); + + var raw: [64]u8 = undefined; + @memcpy(raw[0..bytes.len], bytes); + + // Larger than the buffer: not all of it has arrived. Every value up to a + // hostile 4 GiB claim, which must not be believed for one instruction. + for ([_]u32{ 12, 13, 64, 1 << 20, std.math.maxInt(u32) }) |claim| { + std.mem.writeInt(u32, raw[0..4], claim, .little); + try testing.expectError(error.Truncated, decode(raw[0..bytes.len])); + } + + // Smaller than the buffer: two messages handed over as one. The caller's + // framing is wrong, and silently decoding the first would hide it. + std.mem.writeInt(u32, raw[0..4], 10, .little); + try testing.expectError(error.Trailing, decode(raw[0..bytes.len])); + + // Smaller than a header at all: a number no encoder produced. Refused + // before it is compared against the buffer, or a size of 3 on a 3-byte + // buffer would slice a header out of nothing. + for ([_]u32{ 0, 1, 6 }) |claim| { + std.mem.writeInt(u32, raw[0..4], claim, .little); + try testing.expectError(error.BadValue, decode(raw[0..bytes.len])); + try testing.expectError(error.BadValue, decode(raw[0..header_len])); + } +} + +test "9p: an unknown or illegal type byte is refused" { + var buf: [512]u8 = undefined; + const bytes = try encode(.{ .tclunk = .{ .fid = 1 } }, 1, &buf); + var raw: [64]u8 = undefined; + @memcpy(raw[0..bytes.len], bytes); + + // 106 is `Terror`, defined and illegal. 8 is 9P2000.L's `Tstatfs`, 12 is + // its `Tlopen`: dialects we do not serve, arriving as bytes we must refuse + // rather than `@enumFromInt` into an exhaustive enum. + for ([_]u8{ 0, 1, 8, 12, 99, 106, 128, 255 }) |t| { + raw[4] = t; + try testing.expectError(error.BadTag, decode(raw[0..bytes.len])); + } + + // ...and the whole byte space, because the guarantee is total: a byte is + // either a type we decode into a message of exactly that type, or an + // error. Never a panic, and never a message of some OTHER type. + var t: u16 = 0; + while (t <= 255) : (t += 1) { + raw[4] = @intCast(t); + const defined = t >= 100 and t <= 127 and t != @intFromEnum(Type.terror); + if (decode(raw[0..bytes.len])) |got| { + try testing.expectEqual(@as(u8, @intCast(t)), @intFromEnum(got.msg.msgType())); + // Exactly four types have a four-byte body: `fid[4]` for the three + // T-messages and `count[4]` for Rwrite. Nothing else may decode + // out of these bytes, and a fifth name here would mean a layout + // above is wrong. + try testing.expect(t == @intFromEnum(Type.tclunk) or + t == @intFromEnum(Type.tremove) or + t == @intFromEnum(Type.tstat) or + t == @intFromEnum(Type.rwrite)); + } else |err| { + // An undefined byte, or the illegal 106, is ALWAYS BadTag: it must + // never be diagnosed as a short body, because "read more" is the + // wrong advice for a peer speaking another dialect. + if (!defined) try testing.expectEqual(Error.BadTag, err); + } + } +} + +test "9p: trailing bytes inside the size are refused" { + var raw: [64]u8 = undefined; + + // A Tclunk whose `size` says twelve and whose body is five bytes: the fid + // decodes, and one byte is left over. `convM2S.c:377-381` refuses the same + // shape with `if(ap+size == p) return size; return 0;`. + var w: Writer = .init(&raw); + try w.putU32(12); + try w.putByte(@intFromEnum(Type.tclunk)); + try w.putU16(1); + try w.putU32(7); + try w.putByte(0xAA); + try testing.expectEqual(@as(usize, 12), w.n); + try testing.expectError(error.Trailing, decode(raw[0..12])); + + // Same for a body with room for a second copy of itself, which is how a + // 9P2000.u message with an extra field would arrive. + w = .init(&raw); + try w.putU32(header_len + 2 + 2); + try w.putByte(@intFromEnum(Type.tflush)); + try w.putU16(1); + try w.putU16(3); + try w.putU16(3); + try testing.expectError(error.Trailing, decode(raw[0..w.n])); +} + +test "9p: frameLen needs four bytes" { + var buf: [512]u8 = undefined; + const bytes = try encode(.{ .tread = .{ .fid = 1, .offset = 0, .count = 8168 } }, 1, &buf); + try testing.expectEqual(@as(usize, 23), bytes.len); + + // Zero through three: the reader has nothing to act on but "read more". + for (0..4) |n| try testing.expectEqual(@as(?u32, null), frameLen(bytes[0..n])); + // Four is enough, and the answer is the whole message including the four. + try testing.expectEqual(@as(?u32, 23), frameLen(bytes[0..4])); + try testing.expectEqual(@as(?u32, 23), frameLen(bytes)); + + // Unvalidated on purpose: the type byte may not have arrived yet, so there + // is nothing to check the claim against. A caller compares it to its msize. + var raw: [4]u8 = .{ 0xFF, 0xFF, 0xFF, 0xFF }; + try testing.expectEqual(@as(?u32, std.math.maxInt(u32)), frameLen(&raw)); + raw = .{ 0, 0, 0, 0 }; + try testing.expectEqual(@as(?u32, 0), frameLen(&raw)); +} + +test "9p: encode refuses a short buffer and writes nothing" { + var buf: [512]u8 = undefined; + const want = (try encode(.{ .rstat = .{ .stat = sample_stat } }, 1, &buf)).len; + + // Every buffer from empty to one byte short, because the interesting one is + // not always the last: the message is sized before a byte is written, so + // all of them must leave the buffer untouched. + var n: usize = 0; + while (n < want) : (n += 1) { + var scratch: [512]u8 = @splat(0xAA); + try testing.expectError(error.NoSpace, encode(.{ .rstat = .{ .stat = sample_stat } }, 1, scratch[0..n])); + // NOTHING written, not even the size prefix — including past the end of + // the slice it was given, which is the byte a length bug would reach. + for (scratch) |b| try testing.expectEqual(@as(u8, 0xAA), b); + } + + var exact: [512]u8 = @splat(0xAA); + try testing.expectEqual(want, (try encode(.{ .rstat = .{ .stat = sample_stat } }, 1, exact[0..want])).len); + try testing.expectEqual(@as(u8, 0xAA), exact[want]); +} + +test "9p: byte for byte against u9fs convS2M" { + var buf: [512]u8 = undefined; + + // A round-trip test proves the two halves of THIS file agree. These four + // prove they agree with the reference implementation, which is what + // plan9port's `9p`, Plan 9's mount driver and Linux's v9fs are all + // compatible with. Each array was written out by hand from `convS2M.c` and + // the line is named. + + // Tversion, `convS2M.c:236-240` with the header at :224-229. + // size[4]=19 type[1]=100 tag[2]=NOTAG msize[4]=8192 version[2+6] + // 19, not 12: `size` counts itself and the type and the tag. + try testing.expectEqualSlices(u8, &.{ + 0x13, 0x00, 0x00, 0x00, // size = 19 + 0x64, // Tversion = 100 + 0xff, 0xff, // NOTAG + 0x00, 0x20, 0x00, 0x00, // msize = 8192 + 0x06, 0x00, // n = 6 + '9', 'P', + '2', '0', + '0', '0', + }, try encode(.{ .tversion = .{ .msize = 8192, .version = "9P2000" } }, notag, &buf)); + + // Twalk, `convS2M.c:272-283`: fid, newfid, nwname, then `pstring` each, + // and `pstring` (:4-16) writes `n[2]` with NO terminator. + try testing.expectEqualSlices(u8, &.{ + 0x1b, 0x00, 0x00, 0x00, // size = 27 + 0x6e, // Twalk = 110 + 0x01, 0x00, // tag = 1 + 0x01, 0x00, 0x00, 0x00, // fid = 1 + 0x02, 0x00, 0x00, 0x00, // newfid = 2 + 0x02, 0x00, // nwname = 2 + 0x03, 0x00, + 'u', 's', + 'r', 0x03, + 0x00, 'b', + 'i', 'n', + }, try encode(.{ .twalk = .{ + .fid = 1, + .newfid = 2, + .nwname = 2, + .wname = .{ "usr", "bin" } ++ @as([max_welem - 2][]const u8, @splat("")), + } }, 1, &buf)); + + // Rread, `convS2M.c:392-397`: count[4] then the bytes. The 11-byte header + // this implies is where `msize - 11` comes from (docs/registry.typ). + try testing.expectEqualSlices(u8, &.{ + 0x0e, 0x00, 0x00, 0x00, // size = 14 + 0x75, // Rread = 117 + 0x09, 0x00, // tag = 9 + 0x03, 0x00, 0x00, 0x00, // count = 3 + 'a', 'b', 'c', + }, try encode(.{ .rread = .{ .data = "abc" } }, 9, &buf)); + + // Rstat, `convS2M.c:410-415` (`PBIT16(p, f->nstat)` then the blob) around + // `convD2M.c:50-83` (the record, whose own prefix is `ss - BIT16SZ`). THE + // double length, in bytes: 53 outside, 51 inside, 55 of body, 62 total. + const one: Stat = .{ + .type = 0, + .dev = 0, + .qid = .{ .type = qtdir, .version = 1, .path = 2 }, + .mode = dmdir | 0o755, + .atime = 3, + .mtime = 4, + .length = 0, + .name = "a", + .uid = "u", + .gid = "g", + .muid = "m", + }; + try testing.expectEqual(@as(u16, 51), try one.size()); + try testing.expectEqualSlices(u8, &.{ + 0x3e, 0x00, 0x00, 0x00, // size = 62 + 0x7d, // Rstat = 125 + 0x07, 0x00, // tag = 7 + 0x35, 0x00, // OUTER count = 53 = 51 + 2 + 0x33, 0x00, // stat size = 51, excluding these two + 0x00, 0x00, // type + 0x00, 0x00, 0x00, 0x00, // dev + 0x80, // qid.type = QTDIR + 0x01, 0x00, 0x00, 0x00, // qid.version = 1 + 0x02, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // qid.path = 2 + 0xed, 0x01, 0x00, 0x80, // mode = DMDIR | 0755 + 0x03, 0x00, 0x00, 0x00, // atime + 0x04, 0x00, 0x00, 0x00, // mtime + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // length + 0x01, 0x00, 'a', // name + 0x01, 0x00, 'u', // uid + 0x01, 0x00, 'g', // gid + 0x01, 0x00, 'm', // muid + }, try encode(.{ .rstat = .{ .stat = one } }, 7, &buf)); + + // The high five mode bits ARE the qid type bits, shifted down 24 + // (`protocol.rs:486-495`). Asserted here rather than implemented, because + // this codec carries both fields and the server half sets them. + try testing.expectEqual(qtdir, @as(u8, @intCast(dmdir >> 24))); + try testing.expectEqual(qtappend, @as(u8, @intCast(dmappend >> 24))); + try testing.expectEqual(qtexcl, @as(u8, @intCast(dmexcl >> 24))); + try testing.expectEqual(qtauth, @as(u8, @intCast(dmauth >> 24))); + try testing.expectEqual(qttmp, @as(u8, @intCast(dmtmp >> 24))); + try testing.expectEqual(@as(u32, 0o777), dmperm); +} + +// =========================================================================== +// THE SERVER HALF +// =========================================================================== +// +// Everything above is the wire. Everything below turns a stream of those +// messages into `acmefs.Req` and back. +// +// IT IS A SANS-IO STATE MACHINE and it never touches a descriptor: the caller +// pushes bytes in with `push`, pumps requests through the core with +// `retry`/`next`/`reply`, and takes bytes out with `output`/`wrote`. There is +// no socket here, no poll, no thread and no allocator, which is the whole +// point — the same code serves a unix socket on Linux, a TCP connection from +// another machine, and the board's UART, and the transport-specific part is +// two syscalls in the caller. +// +// WHAT IT IS NOT. It is not a filesystem: every question about what a file +// MEANS belongs to `acmefs.zig`, and this half knows only that a node id is a +// u64, that some nodes are directories, and that a reply may say "ask me +// later". There are exactly two exceptions, both named and both forced by the +// absence of a kernel: the root's node id, which arrives as a parameter to +// `init`, and `parentOf`, which is where `..` goes. +// +// Verified against `u9fs/u9fs.c` (the tree and the offset rules), +// `linux/net/9p/{client,error}.c` (what a real client does with our answers), +// `principia-softwarica/lib_networking/lib9p/srv.c` (flush ordering) and +// `ad/crates/ninep/src/sansio/server.rs` (the scars in its git history). + +// --------------------------------------------------------------------------- +// the error ABI +// --------------------------------------------------------------------------- +// +// `Rerror` carries a STRING and base 9P2000 has no number beside it, so the +// WORDING IS THIS SERVER'S ERROR ABI. Linux recovers an errno by exact match +// against a fixed table and a miss is not `EIO` but `ESERVERFAULT`, which +// userspace prints as "Unknown error 526" — so every string below is copied +// character for character out of `linux/net/9p/error.c:41-171`, with the errno +// it maps to named beside it. +// +// THIS WAS A CHOICE and `docs/registry.typ` `9P-4` left it open with three +// candidates. This is OPTION A. Option B was to serve 9P2000.u and send the +// number, which also restores `Tstatfs` — the one `acmefs.Op` with no +// base-9P2000 message — and keeps a human-readable string for Plan 9 clients; +// it costs a second dialect inside every parser above, because `.u` changes +// the LAYOUT of `Rerror` and `stat` rather than adding messages. Option C was +// acme's own wording (`Ebadctl`, `Ebadaddr`, `Ebadevent`), which is a table +// miss for every one of them; that is what `ad` shipped, so under +// `mount -t 9p` every error it can produce arrives as 526. +// +// The cost of option A is stated plainly: English kernel strings become this +// project's error ABI, and a script reading `event` sees "Invalid argument" +// where acme would have said something about a read too small. If `.u` is ever +// served this table stays as it is — `.u`'s `Rerror` carries the string too. + +/// EBADF. The fid a message names was never walked to, or has been clunked. +/// u9fs spells it `Ebadfid` (`u9fs.c:119`). +pub const e_unknown_fid = "fid unknown or out of range"; +/// EBADF. `Tattach` or `Twalk` named a `newfid` that is already bound. u9fs +/// `Efidactive` (`u9fs.c:124`). +pub const e_fid_in_use = "fid already in use"; +/// EBADF. A fid used for something its state does not allow: read on a fid +/// that was never opened, write on one opened `OREAD`, walk from an open one. +/// u9fs `Ebadusefid` (`u9fs.c:121`), whose five uses are ours. +pub const e_bad_use = "bad use of fid"; +/// ESPIPE. A directory read at an offset that is neither zero nor exactly +/// where the last one ended. u9fs `Ebadoffset` (`u9fs.c:763`). +pub const e_bad_offset = "bad offset in directory read"; +/// EACCES. The permission bits the core reported do not admit this open, or +/// the message asked for something a generated tree cannot do: create, remove, +/// remove-on-close, execute. +pub const e_perm = "permission denied"; +/// ENOTDIR. A walk with names from a fid that is not a directory. +pub const e_not_dir = "not a directory"; +/// ETXTBSY. A second `Topen` on one fid. The fid IS the open, so there is +/// nothing for the second one to mean. +pub const e_already_open = "file already open for I/O"; +/// ENAMETOOLONG. A walk element longer than `name_max`. No name in this tree +/// is, so this is a client asking for something that cannot exist — refused on +/// its length rather than looked up, because the fid has to be able to hold +/// the name it lands on (`Rstat` carries it). +pub const e_illegal_name = "illegal name"; +/// ENFILE. The fid table is full. Thirty-two is a lot of scripts. +pub const e_too_many_fids = "Too many open files in system"; +/// EPROTO. Not 9P2000 on this connection: an R-message arriving at a server, a +/// type byte no dialect we serve defines, a body that does not parse, a +/// message larger than the negotiated msize, or anything at all before +/// `Tversion`. +pub const e_botch = "protocol botch"; +/// EINTR. What a flushed request is answered with, immediately before its +/// `Rflush`. The same answer `fuse.zig:1338` gives a `FUSE_INTERRUPT`. +pub const e_interrupted = "Interrupted system call"; +/// EPERM. A `Twstat` carrying a non-zero length. The core honours exactly one +/// field and only the value zero (`acmefs.zig:1096-1104`), and this string +/// says so in a wording Linux already knows. +pub const e_trunc_only = "only support truncation to zero length"; +/// EPERM. A `Twstat` that would rename, or otherwise change the shape of a +/// tree that follows the pane list. +pub const e_wstat = "wstat prohibited"; +/// EAGAIN. The park table is full, or the core parked a request whose payload +/// is too large to copy into a slot. Both are honest to a client: retry. +pub const e_again = "Resource temporarily unavailable"; +/// EINVAL. A read whose count cannot hold the first thing the answer consists +/// of — one directory entry. Refused rather than answered short, because a +/// `Tread` returning zero bytes is END OF DIRECTORY and a client that believes +/// it stops asking. The same rule `acmefs` already applies to an `event` read +/// too small for one record, and `9P-17` records that this is what makes the +/// clamp to `count` safe. +pub const e_count_small = "Invalid argument"; +/// ENOENT. `Tattach` named an `aname`. There is one tree here and it has no +/// name; a client that asked for a different one should learn that now rather +/// than be handed this one (docs/9p.typ §12.4: "no `aname`"). +pub const e_no_tree = "No such file or directory"; +/// Not in Linux's table, and deliberately: Linux's client never sends `Tauth` +/// at all, and Plan 9's `mount` treats an error here as "no authentication +/// needed" and carries on. So this string is chosen for the human reading a +/// Plan 9 error message rather than for `p9_errstr2errno`. u9fs says the same +/// thing in a string that maps to zero — "not an error" — which is a subtlety +/// we do not need. Real authentication is `Tauth` or a tunnel, and neither is +/// ours (docs/9p.typ §10). +pub const e_no_auth = "authentication not required"; +/// EINVAL. `Tversion` offered an msize too small to serve (see `msize_min`). +/// `Rversion` has no way to say this — its `version` field means "no dialect +/// in common", which is a different fact — and `Rerror` is a legal reply to +/// any T-message, so this is the honest channel. +pub const e_small_msize = "Invalid argument"; + +/// The core's numeric errno as the string Linux turns back into that same +/// number. Every value `acmefs.E` defines is here by name; anything else +/// becomes EIO, because a number we did not choose to emit is a bug in this +/// file and "Input/output error" is the one answer that is never misleading. +pub fn errString(errno: u16) []const u8 { + return switch (errno) { + 1 => "Operation not permitted", // E.PERM, EPERM + 2 => "No such file or directory", // E.NOENT, ENOENT + 5 => "Input/output error", // E.IO, EIO + 12 => "Cannot allocate memory", // E.NOMEM, ENOMEM + 20 => "Not a directory", // E.NOTDIR, ENOTDIR + 22 => "Invalid argument", // E.INVAL, EINVAL + 23 => "Too many open files in system", // E.NFILE, ENFILE + 28 => "No space left on device", // E.NOSPC, ENOSPC + 38 => "Function not implemented", // E.NOSYS, ENOSYS + else => "Input/output error", + }; +} + +// --------------------------------------------------------------------------- +// open modes +// --------------------------------------------------------------------------- +// +// `Topen.mode`, from `u9fs/plan9.h:146-153`. The codec above carries the byte +// and has no opinion about it; these are what the byte MEANS, which is the +// server's business. + +/// The low two bits, which are a VALUE and not a mask: 0, 1, 2, 3. +pub const oread: u8 = 0; +pub const owrite: u8 = 1; +pub const ordwr: u8 = 2; +/// «execute, == read but check execute permission». Nothing in this tree is a +/// program, so it is refused rather than treated as a read. +pub const oexec: u8 = 3; +/// Or'ed in. Truncate first — this is how a shell's `>` reaches a 9P server, +/// and it maps onto `acmefs.Req.truncate` exactly as a `Twstat` with a zero +/// length does (docs/registry.typ `FIX-1`). +pub const otrunc: u8 = 16; +/// Or'ed in, close on exec. A CLIENT-SIDE flag: Plan 9's kernel consumes it +/// and never sends it, so a server that sees it may ignore it, and we do. +pub const ocexec: u8 = 32; +/// Or'ed in, remove on close. Refused: this tree's shape follows the pane list +/// and there is nothing in it a client may remove. +pub const orclose: u8 = 64; + +// --------------------------------------------------------------------------- +// sizes +// --------------------------------------------------------------------------- + +/// Fids one connection may hold at once. A FIXED ARRAY and not a map, costed +/// in `docs/registry.typ` `9P-11`: a linear scan of thirty-two is about 0.4 µs +/// and the wire is slower than that by orders of magnitude, so the map would +/// buy nothing and cost an allocator this file does not have. +/// +/// Overflow is a refusal (`e_too_many_fids`), not a queue. +pub const max_fids: usize = 32; + +/// Requests that may be outstanding at once — in flight, or parked because the +/// core answered `.again`. In practice this counts BLOCKED READERS: one slot +/// per process sitting on `event`. The number is `src/fuse.zig:793`'s, +/// unchanged, because `Status.again` means the same thing to both transports. +pub const max_slots: usize = 32; + +/// Bytes of request payload a park slot owns. A parked request's `data` cannot +/// go on borrowing the input buffer — the next message overwrites it — so it +/// is copied in when it fits. +/// +/// Smaller than `fuse.zig`'s 512, for a reason specific to this file: under +/// FUSE a LOOKUP name is a payload and may be 255 bytes, while a 9P walk +/// element is consumed inside the walk and never parks. What is left is a +/// write, and the only writes that could conceivably block are a `ctl` verb +/// line and an event write-back, both a few dozen bytes. A larger write that +/// the core tries to park is answered `e_again` — honest, and by construction +/// unreachable, since the core answers writes as transactions. +pub const park_data_max: usize = 128; + +/// The longest name a fid may land on, and the longest `uname` we keep. +/// +/// A BOUND rather than a buffer size: `Rstat` carries the file's name, so a +/// fid has to hold the name it walked to, and this is the number that makes +/// `msize_min` provable. Every name in the tree fits with room over — the +/// longest are a pane's decimal serial and `errors` — so a walk element longer +/// than this is refused as `e_illegal_name` rather than looked up and then +/// truncated, which would make `Rstat` lie. +pub const name_max: usize = 28; + +/// The smallest msize this server will agree to serve. DERIVED, not chosen: +/// `Rwalk` with the protocol's sixteen qids is the largest reply whose size +/// the client cannot influence after the handshake, so a connection that +/// cannot hold one cannot be served at all. +/// +/// Deliberately NOT `min_msize` (4096), which is the LINUX KERNEL's floor and +/// nobody else's: Plan 9's devmnt, plan9port's `9p` and pardes's own client all +/// accept 512, and the board would rather have the kilobytes back. +pub const msize_min: u32 = header_len + 2 + max_welem * qid_len; + +comptime { + assert(msize_min == 217); + // The other two replies whose size the client does not choose: `Rstat` + // carries one record with four strings, and a directory read must fit at + // least one such record or it can never make progress. Both must clear + // `msize_min`, or the floor above is not a floor. + assert(header_len + 2 + stat_fixed + 4 * name_max <= msize_min); + assert(header_len + 4 + stat_fixed + 4 * name_max <= msize_min); + // A pane serial is a u60, so its decimal name is at most twenty digits and + // `parentOf` cannot overflow the buffer it formats into. + assert(name_max >= 20); + // Modes are a value in the low two bits with flags above them. + assert(oread | owrite | ordwr | oexec == 3); + assert(otrunc | ocexec | orclose == 112); +} + +/// The server's name for a node. +/// +/// `qid.version` IS ALWAYS ZERO, and this is a policy rather than a +/// translation. It is the 9P equivalent of the `FOPEN_DIRECT_IO` that +/// `src/fuse.zig:172-176` relies on, and it is server-side rather than advice +/// to whoever mounts: Linux's client sets `P9L_DIRECT` — «no read or write +/// cache» — for any file whose qid version is zero, whatever the cache mode, +/// unless `ignoreqv` is passed explicitly (`linux/fs/9p/fid.h:52-53`, +/// `v9fs.c:93`). A synthetic tree of live editor state has no business being +/// cached: `body` changes under the reader's feet, `event` is a queue, and a +/// cached lookup under `new/` would create one pane and then serve the same +/// answer forever. Plan 9 needs nothing said to it — its cache is opt-in via +/// `mount -c` (docs/registry.typ `9P-3`). +/// +/// `qid.path` is the core's node id UNCHANGED, which is what makes the two +/// transports agree: one integer is a FUSE nodeid, a `d_ino` and a qid path at +/// once, and it never comes to mean a different file because pane serials are +/// never reused (`acmefs.zig:231-237`). +fn qidOf(node: u64, dir: bool) Qid { + return .{ .type = if (dir) qtdir else qtfile, .version = 0, .path = node }; +} + +/// Where `..` goes, and the ONE place in this file that decodes a node id. +/// +/// WHY THIS IS HERE AT ALL, because it is the fact that gets lost: under FUSE +/// the kernel resolves `.` and `..` in the pathname before a request is ever +/// sent, which is what lets `acmefs.zig:840` say they «are the kernel's +/// business, never ours». Under 9P THERE IS NO KERNEL. `Twalk` carries `..` as +/// an ordinary name element, and a client that normalises a path, or walks up +/// before walking down, sends it. Forwarding it to the core as a lookup would +/// answer `ENOENT` and break `cd ..`, so the server answers it. +/// +/// It can, without asking anything, because the tree has fixed depth and the +/// node id says where you are. `acmefs.Node` is +/// `packed struct(u64){ file: u4, serial: u60 }` (`acmefs.zig:238-240`), so +/// `file` is the low four bits and `serial` is everything above them, and: +/// +/// * at the root, `..` is the root. POSIX's rule and `intro(5)`'s: the root +/// is its own parent, and this is not an error. +/// * `serial == 0` is a top-level file (`index`, `cons`, `new`), whose +/// parent is the root. +/// * `file == 0` is `PaneFile.dir`, a pane's own directory, whose parent is +/// the root. +/// * anything else is a file inside a pane's directory, and its parent is +/// that directory: the same serial with `file` cleared. Its NAME is the +/// serial in decimal, which is how `acmefs`'s root lists it +/// (`acmefs.zig:992-994`). +/// +/// A well-behaved client only walks between directories, so the last case +/// should never arrive; it is answered correctly rather than trusted away. +/// +/// THE DEPTH ASSUMPTION IS THE WHOLE OF WHAT COULD ROT, and it is checked by +/// the shape of the node id rather than by hope: `Node` has ONE `file: u4`, so +/// a level below a pane's directory — `docs/9p.typ`'s `pty/` — cannot be +/// encoded in a node id at all today. If that changes, this function is the +/// one place that has to learn about it. +fn parentOf(node: u64, root: u64, buf: *[name_max]u8) struct { node: u64, name_len: u8 } { + const serial = node >> 4; + const file = node & 0xF; + if (node == root or serial == 0 or file == 0) { + buf[0] = '/'; + return .{ .node = root, .name_len = 1 }; + } + // A u60 is twenty decimal digits at most and `name_max` is checked against + // that above, so the format cannot fail. + const name = std.fmt.bufPrint(buf, "{d}", .{serial}) catch unreachable; + return .{ .node = serial << 4, .name_len = @intCast(name.len) }; +} + +/// The permission bits a DIRECTORY ENTRY reports, and the only place in this +/// file that reports a mode it was not told. +/// +/// `acmefs`'s staging format for a readdir is `node[8] dir[1] namelen[1] +/// name[]` (`acmefs.zig:942-957`) — the same record the FUSE transport decodes +/// — and it carries no mode and no length, because under FUSE the kernel asks +/// for those separately, with a `getattr` per entry it decides it wants. 9P +/// puts a whole `stat` in a directory read, so the choice is between a +/// `getattr` per entry — an extra round trip each, and a third msize buffer to +/// hold the entries across it — and reporting the tree's own defaults here. +/// +/// We report the defaults. `0o500` is what `TopFile.mode` and `PaneFile.mode` +/// give every directory in the tree without exception; `0o600` is what +/// `PaneFile.mode` gives every file but three; a length of zero is the true +/// length of every file here but `body`, `tag` and `index`. +/// +/// WHO SEES THE DIFFERENCE: only a client that reads permissions and sizes out +/// of a DIRECTORY READ, which is Plan 9's `ls -l` and nothing else. Linux's +/// v9fs takes names and qids from the read and stats each file separately, +/// 9pfuse does the same, and `Tstat` here answers out of the core's own +/// `getattr` — so `ls -l` through either of those is exact. +pub const dirent_dir_perm: u16 = 0o500; +pub const dirent_file_perm: u16 = 0o600; + +/// A 9P2000 server for one connection, over the filesystem ABI `fs`. +/// +/// WHY THIS IS A GENERIC and not a plain struct that imports `acmefs.zig`: +/// this file is freestanding-safe and must stay so — it compiles for +/// `wasm32-freestanding` and the board's `riscv32-freestanding`, and +/// `acmefs.zig` reaches `pardes.zig`, which reaches the build's generated +/// modules. Importing it would also drag every test in that graph into +/// `zig test src/9p.zig`. So the ABI arrives as a type parameter and the +/// coupling is exactly three declarations: +/// +/// * `fs.Req` with `tag, op, node, handle, off, size, data, truncate` +/// * `fs.Reply` with `tag, status, errno, attr, handle, written` +/// * `fs.Reply.Attr` with `node, dir, size, mode` +/// +/// which is `acmefs`'s ABI verbatim, so the real instantiation is +/// `Server(acmefs)` and it needs no translation layer at all. The `Op` and +/// `Status` values are reached as enum literals (`.lookup`, `.again`), so they +/// are checked against the real enums at that instantiation. The tests below +/// instantiate it on a stub filesystem, which is how they run with no core. +/// +/// THE THREE METHODS `src/fs_service.zig`'s `Transport` wants — `retry`, +/// `next` and `reply` — are here with those names and those shapes, and the +/// order contract is that file's: `retry()` to null first, then `next()` to +/// null. `fs_service` is deliberately NOT imported (it is `std.c` and +/// `pardes.zig` deep); the adapter that fills in a vtable is three functions +/// in whoever owns the socket. +/// +/// MEMORY, all of it caller-supplied or fixed: the two buffers, a fid table of +/// `max_fids` and a park table of `max_slots`. No allocator, and nothing here +/// grows. +pub fn Server(comptime fs: type) type { + return struct { + const Self = @This(); + + /// Bytes the caller has pushed and we have not finished with. + /// `in[0..frame]` is the message being served when `frame != 0`, and + /// every slice a decoded `Msg` holds points into it — which is why + /// nothing compacts this buffer until that message is done with. + in: []u8, + /// Encoded replies, oldest first, as a byte FIFO. Every 9P message + /// carries its own length, so the queue needs no side table: the + /// caller writes `output()` and tells us how much went. + out: []u8, + /// The node id of the tree's root — `@intFromEnum(acmefs.TopFile.root)` + /// — and the one fact about the tree this file is told rather than + /// deriving. `Tattach` needs somewhere to start and 9P has no way to + /// ask for it. + root: u64, + + in_len: usize = 0, + frame: u32 = 0, + out_len: usize = 0, + out_off: usize = 0, + + /// Negotiated by `Tversion`; ZERO means not yet, and nothing but + /// `Tversion` is served in that state. + msize: u32 = 0, + /// The stream is not 9P and there is no resynchronising from it: stop + /// serving and let the caller close. Write-once, like `fuse.Fs.dead`. + dead: bool = false, + + /// Whoever attached, for `Rstat`'s three name fields. The tree is + /// synthetic and has one owner: the client that opened the connection. + uname: [name_max]u8 = @splat(0), + uname_len: u8 = 0, + + fids: [max_fids]Fid = @splat(.{}), + slots: [max_slots]Slot = @splat(.{}), + /// The message being served. At most one, which is what keeps the + /// walk's accumulated qids and the borrowed names in one place instead + /// of in thirty-two slots. + job: Job = .{}, + /// Hands out `fs.Req.tag`s, and orders the park table. Never zero, so + /// that zero can mean "no request outstanding". + seq: u64 = 0, + + /// What a 9P message is being turned into. The reply's SHAPE, which is + /// what `reply` needs and what `Op` alone does not say: a `getattr` is + /// a step of `Rattach`, of `Rwalk` and of `Rstat`. + const Kind = enum { none, attach, walk, open, read, readdir, write, clunk, remove, stat, wstat }; + + /// One fid: a name the client gave a place in the tree. + /// + /// `perm` and `dir` are cached from the attributes the walk that landed + /// here already answered, because `Topen` has to check permission + /// itself — there is no kernel above us doing it, and `acmefs.open` + /// deliberately does not (`acmefs.zig:1023-1031`). `name` is cached + /// because `Rstat` carries it and a node id does not. + const Fid = struct { + used: bool = false, + /// The client's number. `nofid` is never one. + fid: u32 = 0, + node: u64 = 0, + dir: bool = false, + /// Permission bits as the core last reported them, which is what + /// `Topen` is checked against. + perm: u16 = 0, + open: bool = false, + /// The `Topen` mode, valid when `open`. + omode: u8 = 0, + /// `acmefs`'s open handle, repeated on every read, write and + /// release. + handle: u32 = 0, + /// THE DIRECTORY CURSOR, in the two coordinate systems it has to + /// live in at once: `diroff` is the BYTE offset 9P requires the + /// next read to carry, and `dirindex` is the ENTRY INDEX `acmefs` + /// counts in (`acmefs.zig:972`, `var skip = req.off;`). + diroff: u64 = 0, + dirindex: u32 = 0, + /// This fid has no client any more and still owes the core a + /// `release`. See `orphan`. + orphan: bool = false, + name: [name_max]u8 = @splat(0), + name_len: u8 = 0, + }; + + /// A request the core would not answer yet. Lifted from + /// `src/fuse.zig:806-822` with the FUSE opcode replaced by the 9P tag + /// and the reply shape, because `Status.again` means the same thing to + /// both transports and this is where `docs/registry.typ` `9P-16` says + /// we beat the prior art. + const Slot = struct { + used: bool = false, + /// The core answered `.again`; `retry()` will offer it back. + parked: bool = false, + /// Already offered in this retry round. Reset when a round finds + /// nothing, which gives every parked request exactly one attempt + /// per frame instead of letting the oldest starve the rest. + retried: bool = false, + /// `req.data` points into `data` below rather than into `in`. + copied: bool = false, + /// Arrival order, so retries are FIFO: the reader that blocked + /// first is offered first. + seq: u64 = 0, + /// The client's tag, which is what `Tflush` names. + tag: u16 = 0, + kind: Kind = .none, + /// The client's fid NUMBER and not an index: the fid may be + /// clunked while this is parked, and a stale index would be a + /// stale pointer. + fid: u32 = 0, + /// What the client asked for, which is what the answer is clamped + /// to (`docs/registry.typ` `9P-17`). + count: u32 = 0, + req: fs.Req = undefined, + data: [park_data_max]u8 = undefined, + }; + + /// The message in flight, and the accumulated answer. + const Job = struct { + kind: Kind = .none, + tag: u16 = 0, + /// The `fs.Req.tag` of the step the core is holding, or zero. + req_tag: u64 = 0, + /// The step itself, kept so that a park has something to copy and + /// a retry has something to re-offer. + req: fs.Req = undefined, + step: u8 = 0, + fid: u32 = 0, + newfid: u32 = 0, + count: u32 = 0, + offset: u64 = 0, + omode: u8 = 0, + /// Where the walk has got to: the node, its attributes and its + /// name, all of which `Rwalk`'s last qid and the bound fid need. + node: u64 = 0, + dir: bool = false, + perm: u16 = 0, + name: [name_max]u8 = @splat(0), + name_len: u8 = 0, + nwname: u8 = 0, + nwqid: u8 = 0, + wqid: [max_welem]Qid = @splat(.{ .type = 0, .version = 0, .path = 0 }), + /// The decoded T-message, BORROWING `in[0..frame]`: a walk's names + /// and a write's bytes live here and nowhere else. + msg: Msg = .rflush, + }; + + pub const Options = struct { + /// Room for one whole T-message. Caps the msize we will agree to, + /// with `out`. + in: []u8, + /// Room for two: one being written out and one being built. That + /// is what lets a reply be encoded the moment the core answers, + /// with no "can I write yet" question anywhere in this file. + out: []u8, + /// `@intFromEnum(acmefs.TopFile.root)`. + root: u64, + }; + + /// The buffers are the caller's, which is what "no allocator" means + /// here: the board hands over two static arrays, a desktop host hands + /// over two heap slices sized for a 128 KiB msize, and this file cannot + /// tell the difference. The msize follows from them and from the + /// client's `Tversion`; see `version`. + pub fn init(opts: Options) Self { + assert(opts.in.len >= msize_min); + assert(opts.out.len >= 2 * msize_min); + // Node zero is `acmefs.Node{}` — no file, no pane — and cannot be + // a root. A zero here would make every `..` land on nothing. + assert(opts.root != 0); + return .{ .in = opts.in, .out = opts.out, .root = opts.root }; + } + + /// The connection went away. Every open fid still owes the core a + /// `release`, and that debt outlives the connection: an `event` fid + /// dropped without one leaves the pane's reader count high forever, + /// which leaves the editor reporting button actions to a script that + /// is no longer there (`acmefs.zig:1053-1061`). So the fids are + /// ORPHANED rather than forgotten, and the caller keeps pumping + /// `next()` until it answers null. + pub fn hangup(s: *Self) void { + s.reset(); + s.dead = true; + s.in_len = 0; + s.frame = 0; + s.out_len = 0; + s.out_off = 0; + } + + /// What `Tversion` does to the connection, and what `hangup` does + /// first: «all fids are clunked and any outstanding I/O is abandoned» + /// (`version(5)`). The parked requests go without an answer, which is + /// exactly what abandoned means; the fids that are open become + /// orphans, because the core's side of an open is not the client's to + /// abandon. + fn reset(s: *Self) void { + for (&s.fids) |*f| { + if (!f.used) continue; + if (f.open) f.orphan = true else f.* = .{}; + } + for (&s.slots) |*sl| sl.* = .{}; + s.job = .{}; + } + + // -- bytes in, bytes out --------------------------------------------- + + /// Take as much of `bytes` as there is room for, and answer how much. + /// A short answer is not an error and not a loss: it is the only + /// back-pressure a sans-io server has, and the caller re-offers the + /// tail after pumping. Bytes are APPENDED, so a message already being + /// served does not move. + pub fn push(s: *Self, bytes: []const u8) usize { + if (s.dead) return 0; + const n = @min(bytes.len, s.in.len - s.in_len); + @memcpy(s.in[s.in_len..][0..n], bytes[0..n]); + s.in_len += n; + return n; + } + + /// The replies waiting to go, oldest first, as one contiguous run of + /// whole 9P messages. Valid until the next call to anything else here. + pub fn output(s: *const Self) []const u8 { + return s.out[s.out_off..s.out_len]; + } + + /// How many of `output()`'s bytes actually left. A partial write is + /// normal on a UART and on a full socket, and the remainder stays put. + pub fn wrote(s: *Self, n: usize) void { + assert(n <= s.out_len - s.out_off); + s.out_off += n; + if (s.out_off == s.out_len) { + s.out_off = 0; + s.out_len = 0; + } + } + + /// Slide the unwritten tail down. Called only when room is wanted, so + /// the common case — a fully written queue, reset to empty by `wrote` — + /// never moves a byte. + fn compact(s: *Self) void { + assert(s.out_off <= s.out_len); + const n = s.out_len - s.out_off; + std.mem.copyForwards(u8, s.out[0..n], s.out[s.out_off..s.out_len]); + s.out_off = 0; + s.out_len = n; + } + + /// THE RESERVATION RULE, and the reason no reply in this file can ever + /// fail to be written: a request is not handed to the core unless the + /// out queue already has room for the largest answer it could produce, + /// which is one msize. So `emit` cannot run out, a parked read that + /// completes cannot be dropped, and back-pressure lands where it can + /// be dealt with — `next()` and `retry()` answer null, the caller + /// writes some bytes, and the pump continues. + fn hasRoom(s: *Self) bool { + if (s.out_off != 0) s.compact(); + return s.out.len - s.out_len >= @max(s.msize, msize_min); + } + + /// Queue one reply. Infallible by the reservation rule above; if it + /// ever is not, the connection dies rather than the stream growing a + /// half-written message — a dropped reply hangs a client forever, + /// while a closed connection makes it fail and say so. + fn emit(s: *Self, tag: u16, msg: Msg) void { + const bytes = encode(msg, tag, s.out[s.out_len..]) catch { + s.dead = true; + return; + }; + s.out_len += bytes.len; + } + + fn fail(s: *Self, tag: u16, ename: []const u8) void { + assert(ename.len <= errmax); + s.emit(tag, .{ .rerror = .{ .ename = ename } }); + } + + /// The next `fs.Req.tag`. Unique for the life of the connection, which + /// is what lets `reply` find its target with no cooperation from the + /// core, and never zero. + fn tick(s: *Self) u64 { + s.seq += 1; + return s.seq; + } + + fn findFid(s: *Self, fid: u32) ?usize { + for (&s.fids, 0..) |*f, i| if (f.used and !f.orphan and f.fid == fid) return i; + return null; + } + + fn freeFid(s: *Self) ?usize { + for (&s.fids, 0..) |*f, i| if (!f.used) return i; + return null; + } + + fn dropFid(s: *Self, fid: u32) void { + if (s.findFid(fid)) |i| s.fids[i] = .{}; + } + + fn findSlot(s: *Self, req_tag: u64) ?usize { + for (&s.slots, 0..) |*sl, i| if (sl.used and sl.req.tag == req_tag) return i; + return null; + } + + fn freeSlot(s: *Self) ?usize { + for (&s.slots, 0..) |*sl, i| if (!sl.used) return i; + return null; + } + + /// A parked request by the tag the CLIENT gave it, which is what + /// `Tflush` names. + fn findTag(s: *Self, tag: u16) ?usize { + for (&s.slots, 0..) |*sl, i| if (sl.used and sl.tag == tag) return i; + return null; + } + + fn setUname(s: *Self, uname: []const u8) void { + const n = @min(uname.len, name_max); + @memcpy(s.uname[0..n], uname[0..n]); + s.uname_len = @intCast(n); + } + + // -- the transport seam ---------------------------------------------- + + /// Offer parked requests back, one per call, in arrival order. Call in + /// a loop until null, once per frame, BEFORE `next()`: the null both + /// ends the round and resets it, so every parked request gets exactly + /// one attempt per frame and a permanently blocked reader cannot + /// starve the others. `src/fs_service.zig:196-208` is the contract and + /// `src/fuse.zig:1166` is the other implementation of it. + pub fn retry(s: *Self) ?fs.Req { + var best: ?usize = null; + for (&s.slots, 0..) |*sl, i| { + if (!sl.used or !sl.parked or sl.retried) continue; + if (best == null or sl.seq < s.slots[best.?].seq) best = i; + } + const i = best orelse { + for (&s.slots) |*sl| sl.retried = false; + return null; + }; + // No room for the answer is the end of the round too, and it must + // reset it: leaving the flags set would make the next frame skip + // the requests this one never reached. + if (!s.hasRoom()) { + for (&s.slots) |*sl| sl.retried = false; + return null; + } + s.slots[i].retried = true; + // In flight again: `reply` re-parks it if the core still has + // nothing to say. + s.slots[i].parked = false; + return s.slots[i].req; + } + + /// The next request off the wire, or null when there is nothing more to + /// do with the bytes pushed so far. Call in a loop until null. + /// + /// ONE 9P MESSAGE IS NOT ONE REQUEST, which is the whole reason this is + /// a state machine: a three-element `Twalk` is three lookups, a + /// `Topen` with `OTRUNC` is a truncate and then an open, and a + /// `Tversion` is none at all. So this pump decodes a message when it + /// needs one, hands out its steps as the core answers them, and + /// answers null only when the input is exhausted, the queue is full, or + /// the core is holding a step. + pub fn next(s: *Self) ?fs.Req { + while (true) { + if (s.job.kind != .none) { + // A step is out with the core; the caller owes us a + // `reply` before there is anything else to ask. + if (s.job.req_tag != 0) return null; + if (s.stepJob()) |req| return req; + // The job answered itself — a walk that finished, an error + // — and `stepJob` cleared it. Round again for the next + // message. + assert(s.job.kind == .none); + continue; + } + if (s.orphan()) |req| return req; + if (!s.hasRoom()) return null; + if (!s.startFrame()) return null; + } + } + + /// Answer one request: queue the 9P reply it completes, advance the + /// message it is a step of, or park it. `bytes` is the payload the + /// core resolved and is borrowed for the duration of this call only — + /// the same rule `src/fs_service.zig:224-229` states for the FUSE + /// transport. + pub fn reply(s: *Self, r: *const fs.Reply, bytes: []const u8) void { + if (s.job.kind != .none and s.job.req_tag == r.tag) return s.jobReply(r, bytes); + if (s.findSlot(r.tag)) |i| return s.slotReply(i, r, bytes); + // An orphan's release, a park `Tversion` abandoned, or a request + // `Tflush` already answered. Nothing to say and nobody to say it + // to; `fuse.zig:1189` drops the same case for the same reason. + } + + /// A `release` nobody is waiting for: the fid it belonged to is gone + /// (the connection dropped, or `Tversion` reset it) but the core's + /// open is not. + /// + /// The slot is freed HERE rather than when the answer lands, because + /// nothing in the answer is wanted and `reply` already ignores a tag it + /// no longer holds. That also means a release the core parks is + /// dropped, which is the same trade `fuse.zig` makes for a write: a + /// release is a transaction in this design and does not block. + fn orphan(s: *Self) ?fs.Req { + for (&s.fids) |*f| { + if (!f.used or !f.orphan) continue; + assert(f.open); + const req: fs.Req = .{ + .tag = s.tick(), + .op = .release, + .node = f.node, + .handle = f.handle, + }; + f.* = .{}; + return req; + } + return null; + } + + /// Decode the message at the head of `in` and start serving it. False + /// when there is not a whole one there yet. + /// + /// The frame stays in `in` for as long as the message is being served, + /// because every string in a decoded `Msg` points into it. The `defer` + /// is what makes that airtight: a message that answered itself here + /// releases the frame immediately, and one that became a job hands the + /// frame to the job, which releases it in `finishJob` or copies what it + /// needs in `parkJob`. + fn startFrame(s: *Self) bool { + assert(s.job.kind == .none); + assert(s.frame == 0); + if (s.dead) return false; + const len = frameLen(s.in[0..s.in_len]) orelse return false; + // A `size` no encoder produced, or one this connection could never + // buffer: either way the stream is not 9P and waiting for more of + // it is waiting forever. + if (len < header_len or len > s.in.len) { + s.dead = true; + return false; + } + if (len > s.in_len) return false; + s.frame = len; + defer if (s.job.kind == .none) s.dropFrame(); + + const got = decode(s.in[0..len]) catch { + // The tag sits at a fixed offset and survives every way the + // body can be wrong, so the client still gets an answer rather + // than a hang. `len >= header_len` was checked above. + s.fail(std.mem.readInt(u16, s.in[5..7], .little), e_botch); + return true; + }; + // A server reads T-messages. An R-message here is a client on the + // wrong end of the connection, or the double-role link + // docs/9p.typ §7 tells us not to build. + if (!isT(got.msg.msgType())) { + s.fail(got.tag, e_botch); + return true; + } + // «The client must communicate the version before any other + // messages» — and until it has, there is no msize to bound + // anything by. + if (s.msize == 0 and got.msg != .tversion) { + s.fail(got.tag, e_botch); + return true; + } + if (s.msize != 0 and len > s.msize) { + s.fail(got.tag, e_botch); + return true; + } + s.dispatch(got); + return true; + } + + /// Release the served frame and slide the rest of the input down. The + /// move is one message long and happens once per message; the + /// alternative is a ring buffer, which would mean a decoded `Msg` + /// could straddle the wrap and no longer be one slice. + fn dropFrame(s: *Self) void { + assert(s.frame != 0); + assert(s.frame <= s.in_len); + const n = s.frame; + std.mem.copyForwards(u8, s.in[0 .. s.in_len - n], s.in[n..s.in_len]); + s.in_len -= n; + s.frame = 0; + } + + // -- the messages ---------------------------------------------------- + + /// One T-message onto its handler. Every message either answers itself + /// here or becomes `job`. + fn dispatch(s: *Self, got: Decoded) void { + switch (got.msg) { + .tversion => |m| s.version(got.tag, m.msize, m.version), + // REFUSED, all three, and each for its own reason. + // + // `Tauth`: there is no authentication here and there is not + // going to be one in this file. The socket's permissions are + // the protection and a network is tunnelled (docs/9p.typ §10). + // + // `Tcreate` and `Tremove`: the shape of this tree follows the + // pane list, so there is nothing in it for a client to make or + // unmake. The one place a client DOES create something is + // `new/`, where walking to a name is what creates a pane + // (`acmefs.zig:901-919`) — so the capability is there and it + // is not spelled `Tcreate`. That answers the open question in + // `docs/registry.typ` `9P-18`, and it takes most of `ad`'s + // shipped-and-fixed bug list off the table with it. + .tauth => s.fail(got.tag, e_no_auth), + .tcreate => s.fail(got.tag, e_perm), + .tattach => |m| s.attach(got.tag, m.fid, m.uname, m.aname), + .tflush => |m| s.flush(got.tag, m.oldtag), + .twalk => |m| s.walk(got, m.fid, m.newfid, @intCast(m.nwname)), + .topen => |m| s.open(got.tag, m.fid, m.mode), + .tread => |m| s.read(got.tag, m.fid, m.offset, m.count), + .twrite => |m| s.write(got, m.fid, m.offset, m.data.len), + .tclunk => |m| s.clunk(got.tag, m.fid, .clunk), + // A remove clunks the fid too — see `clunk` — which is the + // half of `remove(5)` that is easy to miss. + .tremove => |m| s.clunk(got.tag, m.fid, .remove), + .tstat => |m| s.stat(got.tag, m.fid), + .twstat => |m| s.wstat(got.tag, m.fid, m.stat), + // The R-variants, which `startFrame` already refused by + // parity. Answered rather than `unreachable`, because the cost + // of being wrong about that is a panic in a server. + else => s.fail(got.tag, e_botch), + } + } + + /// `Tversion`: the msize handshake, and a connection reset. + fn version(s: *Self, tag: u16, want: u32, ver: []const u8) void { + // Three ceilings and the smallest wins: what the client will + // accept, what one input buffer holds, and half of what the output + // queue holds (`Options.out`). + const cap: u32 = @intCast(@min(s.in.len, s.out.len / 2)); + const m = @min(want, cap); + if (m < msize_min) return s.fail(tag, e_small_msize); + // u9fs `rversion`: any version string that STARTS with "9P" is + // answered "9P2000", which is how a `.u` or `.L` client is told to + // fall back to the base protocol. Anything else has no dialect in + // common with us, and that is a SUCCESSFUL `Rversion` carrying the + // literal "unknown" rather than an `Rerror`. + const known = std.mem.startsWith(u8, ver, "9P"); + s.reset(); + // The msize only becomes real once a version is agreed: after + // "unknown" the client must negotiate again, and `startFrame` + // serves nothing else until it does. + s.msize = if (known) m else 0; + s.emit(tag, .{ .rversion = .{ .msize = m, .version = if (known) "9P2000" else "unknown" } }); + } + + fn attach(s: *Self, tag: u16, fid: u32, uname: []const u8, aname: []const u8) void { + // No `aname`. There is one tree here and it has no name; a client + // that asked for another one is told so rather than handed this. + if (aname.len != 0) return s.fail(tag, e_no_tree); + if (fid == nofid) return s.fail(tag, e_unknown_fid); + if (s.findFid(fid) != null) return s.fail(tag, e_fid_in_use); + if (s.freeFid() == null) return s.fail(tag, e_too_many_fids); + s.setUname(uname); + // The root's attributes come from the core like every other node's. + // Its node id is the only thing we were told (see `root`). + s.job = .{ .kind = .attach, .tag = tag, .fid = fid, .node = s.root }; + } + + fn walk(s: *Self, got: Decoded, fid: u32, newfid: u32, nwname: u8) void { + const tag = got.tag; + const i = s.findFid(fid) orelse return s.fail(tag, e_unknown_fid); + // «must not have been opened for I/O» — walk(5). The fid IS the + // open, so a walk would move the file out from under it. + if (s.fids[i].open) return s.fail(tag, e_bad_use); + if (newfid == nofid) return s.fail(tag, e_unknown_fid); + if (newfid != fid) { + if (s.findFid(newfid) != null) return s.fail(tag, e_fid_in_use); + // Checked BEFORE any lookup, because a lookup under `new/` + // creates a pane and a walk that then failed for want of a fid + // slot would leave one behind. + if (s.freeFid() == null) return s.fail(tag, e_too_many_fids); + } + if (nwname == 0) { + // THE CLONE. No names, no lookups, no qids: `Rwalk` with + // `nwqid == 0`, and it is a success — which is exactly why a + // failure on the first element may not be spelled that way. + if (newfid != fid) { + const j = s.freeFid().?; + s.fids[j] = s.fids[i]; + s.fids[j].fid = newfid; + // A clone shares the file and NOT the directory cursor: + // two fids on one directory each keep their own place, + // which is what a duplicated descriptor means everywhere + // else. The open state is not shared either, and cannot + // be — an open fid was refused above. + s.fids[j].diroff = 0; + s.fids[j].dirindex = 0; + } + s.emit(tag, .{ .rwalk = .{ .nwqid = 0 } }); + return; + } + if (!s.fids[i].dir) return s.fail(tag, e_not_dir); + s.job = .{ + .kind = .walk, + .tag = tag, + .fid = fid, + .newfid = newfid, + .nwname = nwname, + .node = s.fids[i].node, + .dir = s.fids[i].dir, + .perm = s.fids[i].perm, + .name = s.fids[i].name, + .name_len = s.fids[i].name_len, + .msg = got.msg, + }; + } + + fn open(s: *Self, tag: u16, fid: u32, mode: u8) void { + const i = s.findFid(fid) orelse return s.fail(tag, e_unknown_fid); + const f = &s.fids[i]; + if (f.open) return s.fail(tag, e_already_open); + // Nothing in a generated tree can be removed, so nothing in it can + // be opened remove-on-close either. + if (mode & orclose != 0) return s.fail(tag, e_perm); + const rw = mode & 3; + if (rw == oexec) return s.fail(tag, e_perm); + // A directory is read, and only read: 9P has no other verb for one, + // and truncating a pane list is not a thing to mean. + if (f.dir and (rw != oread or mode & otrunc != 0)) return s.fail(tag, e_perm); + var need: u16 = 0; + if (rw == oread or rw == ordwr) need |= 0o400; + if (rw == owrite or rw == ordwr or mode & otrunc != 0) need |= 0o200; + // THE PERMISSION CHECK IS OURS. Under FUSE the kernel does it, + // against the mode a `getattr` reported, and `acmefs.open` never + // sees a mode at all (`acmefs.zig:1023-1031`). Over 9P there is + // nobody above us, so this is what stops `errors` and `wrsel` — + // write-only in acme's own dirtab — from being readable. + if (f.perm & need != need) return s.fail(tag, e_perm); + s.job = .{ .kind = .open, .tag = tag, .fid = fid, .omode = mode }; + } + + fn read(s: *Self, tag: u16, fid: u32, offset: u64, count: u32) void { + const i = s.findFid(fid) orelse return s.fail(tag, e_unknown_fid); + const f = &s.fids[i]; + // The two conditions `u9fs.c:755-758` refuses, and the same + // answer: a fid that was never opened, or one opened write-only. + if (!f.open or (f.omode & 3) == owrite) return s.fail(tag, e_bad_use); + // THE CLAMP, `min(count, msize - 11)`. An `Rread` longer than the + // count asked for is a hard `-EIO` in Linux rather than a + // truncation (`net/9p/client.c:1475-1479`, `9P-17`), and one + // longer than the msize is a message the client cannot read at + // all. Eleven is `Rread`'s header: `size[4] type[1] tag[2] + // count[4]`. It is applied to the request as well as to the + // answer, so the core is never asked to produce bytes that would + // have to be thrown away. + const want = @min(count, s.msize - header_len - 4); + if (!f.dir) { + s.job = .{ .kind = .read, .tag = tag, .fid = fid, .offset = offset, .count = want }; + return; + } + // THE DIRECTORY RULE: offset zero, or exactly where the last read + // ended, and nothing else (`u9fs.c:760-769`, `lib9p/srv.c:473`). A + // client that seeks inside a directory is refused rather than + // served a listing that tears — which is the bug `ad` has, where an + // arbitrary offset that happens to land on an entry boundary is + // silently accepted (`9P-5`). + if (offset != f.diroff) { + if (offset != 0) return s.fail(tag, e_bad_offset); + f.diroff = 0; + f.dirindex = 0; + } + s.job = .{ .kind = .readdir, .tag = tag, .fid = fid, .offset = offset, .count = want }; + } + + fn write(s: *Self, got: Decoded, fid: u32, offset: u64, len: usize) void { + const tag = got.tag; + const i = s.findFid(fid) orelse return s.fail(tag, e_unknown_fid); + const f = &s.fids[i]; + if (!f.open or (f.omode & 3) == oread) return s.fail(tag, e_bad_use); + s.job = .{ + .kind = .write, + .tag = tag, + .fid = fid, + .offset = offset, + .count = @intCast(len), + .msg = got.msg, + }; + } + + fn clunk(s: *Self, tag: u16, fid: u32, kind: Kind) void { + assert(kind == .clunk or kind == .remove); + const i = s.findFid(fid) orelse return s.fail(tag, e_unknown_fid); + // An open fid owes the core a `release` before it goes. That is + // what decrements a pane's `event` reader count, and losing it + // leaves the editor reporting button actions to a script that has + // gone (`acmefs.zig:1069-1093`). + if (s.fids[i].open) { + s.job = .{ .kind = kind, .tag = tag, .fid = fid }; + return; + } + s.fids[i] = .{}; + if (kind == .remove) s.fail(tag, e_perm) else s.emit(tag, .rclunk); + } + + fn stat(s: *Self, tag: u16, fid: u32) void { + if (s.findFid(fid) == null) return s.fail(tag, e_unknown_fid); + s.job = .{ .kind = .stat, .tag = tag, .fid = fid }; + } + + fn wstat(s: *Self, tag: u16, fid: u32, st: Stat) void { + if (s.findFid(fid) == null) return s.fail(tag, e_unknown_fid); + // The sentinels `stat(5)` specifies: an empty string and an + // all-ones integer mean "do not touch". The codec above carries + // them and has no opinion; deciding is this file's job. + if (st.name.len != 0) return s.fail(tag, e_wstat); + if (st.length == std.math.maxInt(u64)) { + // Nothing left that we honour. Mode, owner, group and the two + // times are ACCEPTED AND IGNORED, which is what a filesystem + // of live editor state has to do with them + // (`acmefs.zig:1096-1104`): refusing would make `touch` and + // `chmod` fail on a tree where they mean nothing anyway. + s.emit(tag, .rwstat); + return; + } + // A length that is neither the sentinel nor zero. The core honours + // exactly one value, so name it — and this string is one Linux + // already knows, so `truncate` gets EPERM rather than 526. + if (st.length != 0) return s.fail(tag, e_trunc_only); + // ...and zero IS the truncate, which is the same `Req.truncate` + // that `Topen` with `OTRUNC` produces (`FIX-1`). + s.job = .{ .kind = .wstat, .tag = tag, .fid = fid }; + } + + /// `Tflush`: a park-table lookup, and THE ORDER IS THE POINT. + /// + /// The original is answered first and the `Rflush` second. That is what + /// `lib9p/srv.c:241-266` does with its chained flush list, and what + /// `srv.c:810-827` does when the original finally responds: write the + /// original's reply, then respond to every flush waiting on it. A + /// client that sees `Rflush` may reuse the tag, so a reply arriving + /// after it would be a reply to whatever the tag names NEXT. + /// + /// `docs/registry.typ` `9P-16` says this is where we beat the prior + /// art, and the reason is structural rather than clever: the park table + /// is already keyed per outstanding request, so this is a lookup and + /// two replies. `ad` gets the ordering right in thirty-nine lines and + /// then defaults its filesystem's `flush` hook to doing nothing, so a + /// client flushing a blocked `event` read waits for an unrelated editor + /// event to arrive. There is no hook here to forget to implement. + fn flush(s: *Self, tag: u16, oldtag: u16) void { + if (s.findTag(oldtag)) |i| { + // EINTR and drop it, which is exactly what `fuse.zig:1334-1341` + // answers a `FUSE_INTERRUPT` naming a parked request. + s.fail(s.slots[i].tag, e_interrupted); + s.slots[i] = .{}; + } + // A tag we do not hold was already answered or never existed. + // `Rflush` either way: after it the client may reuse the tag, and + // that is the only promise `flush(5)` makes. + s.emit(tag, .rflush); + } + + // -- steps and answers ----------------------------------------------- + + /// Record the step being handed to the core, so that a park has + /// something to copy and `reply` has something to match. + fn ask(s: *Self, req: fs.Req) fs.Req { + assert(req.tag != 0); + s.job.req = req; + s.job.req_tag = req.tag; + return req; + } + + /// The fid the message in flight names. Null cannot happen — nothing + /// else runs while a job does — and is answered rather than asserted, + /// because the cost of being wrong is a corrupted table. + fn jobFid(s: *Self) ?*Fid { + const i = s.findFid(s.job.fid) orelse { + s.fail(s.job.tag, e_unknown_fid); + s.finishJob(); + return null; + }; + return &s.fids[i]; + } + + /// The next core request the message in flight needs, or null when it + /// has just answered itself. + fn stepJob(s: *Self) ?fs.Req { + const j = &s.job; + assert(j.kind != .none); + assert(j.req_tag == 0); + switch (j.kind) { + .none => unreachable, + .attach => return s.ask(.{ .tag = s.tick(), .op = .getattr, .node = s.root }), + .walk => return s.stepWalk(), + .open => { + const f = s.jobFid() orelse return null; + // `OTRUNC` is a truncate and THEN an open, in that order. + if (j.step == 0 and j.omode & otrunc != 0) return s.ask(.{ + .tag = s.tick(), + .op = .setattr, + .node = f.node, + .truncate = true, + }); + return s.ask(.{ .tag = s.tick(), .op = .open, .node = f.node }); + }, + .read => { + const f = s.jobFid() orelse return null; + return s.ask(.{ + .tag = s.tick(), + .op = .read, + .node = f.node, + .handle = f.handle, + .off = j.offset, + .size = j.count, + }); + }, + .readdir => { + const f = s.jobFid() orelse return null; + // THE COORDINATE CHANGE. 9P counts bytes and `acmefs` + // counts entries (`acmefs.zig:972`), so the request carries + // the entry index this fid's byte cursor stands at, and + // `emitDirRead` advances both. + return s.ask(.{ + .tag = s.tick(), + .op = .readdir, + .node = f.node, + .handle = f.handle, + .off = f.dirindex, + .size = j.count, + }); + }, + .write => { + const f = s.jobFid() orelse return null; + return s.ask(.{ + .tag = s.tick(), + .op = .write, + .node = f.node, + .handle = f.handle, + .off = j.offset, + .size = j.count, + .data = j.msg.twrite.data, + }); + }, + .clunk, .remove => { + const f = s.jobFid() orelse return null; + return s.ask(.{ + .tag = s.tick(), + .op = .release, + .node = f.node, + .handle = f.handle, + }); + }, + .stat => { + const f = s.jobFid() orelse return null; + return s.ask(.{ .tag = s.tick(), .op = .getattr, .node = f.node }); + }, + .wstat => { + const f = s.jobFid() orelse return null; + return s.ask(.{ .tag = s.tick(), .op = .setattr, .node = f.node, .truncate = true }); + }, + } + } + + /// One walk element at a time, and the local ones without asking. + fn stepWalk(s: *Self) ?fs.Req { + const j = &s.job; + while (j.step < j.nwname) { + const name = j.msg.twalk.wname[j.step]; + // A name the fid could not hold cannot be a name in this tree, + // and refusing it on its length is what keeps `Rstat` honest. + if (name.len > name_max) { + s.stopWalk(e_illegal_name); + return null; + } + // `.` is the fid where it already stands, and costs nothing. + if (std.mem.eql(u8, name, ".")) { + j.wqid[j.nwqid] = qidOf(j.node, j.dir); + j.nwqid += 1; + j.step += 1; + continue; + } + if (std.mem.eql(u8, name, "..")) { + const p = parentOf(j.node, s.root, &j.name); + j.name_len = p.name_len; + j.node = p.node; + // WHICH node the parent is, is ours to work out; what it + // LOOKS like is not. A `getattr` keeps `perm`, `dir` and + // the qid the core's answer rather than this file's + // invention, and reports ENOENT if the pane closed + // underneath us. + return s.ask(.{ .tag = s.tick(), .op = .getattr, .node = p.node }); + } + @memcpy(j.name[0..name.len], name); + j.name_len = @intCast(name.len); + return s.ask(.{ .tag = s.tick(), .op = .lookup, .node = j.node, .data = name }); + } + // Every element resolved, so `newfid` is bound — and only now. A + // partial walk binds NOTHING, which is `ad`'s «new_fid is only + // bound when all elements were walked successfully» and the spec's. + const dst = pick: { + if (j.newfid == j.fid) break :pick s.findFid(j.fid) orelse { + s.fail(j.tag, e_unknown_fid); + s.finishJob(); + return null; + }; + break :pick s.freeFid() orelse { + s.fail(j.tag, e_too_many_fids); + s.finishJob(); + return null; + }; + }; + s.fids[dst] = .{ + .used = true, + .fid = j.newfid, + .node = j.node, + .dir = j.dir, + .perm = j.perm, + .name = j.name, + .name_len = j.name_len, + }; + s.emit(j.tag, .{ .rwalk = .{ .nwqid = j.nwqid, .wqid = j.wqid } }); + s.finishJob(); + return null; + } + + /// A walk that could not finish, and THE SCAR that says how to answer + /// it: «Spec: first element failure must be Rerror, not Rwalk with zero + /// qids» — `ad/crates/ninep/src/sansio/server.rs:335-338`, left in + /// their source after they shipped it the other way. Zero qids already + /// means the clone, so it cannot also mean a failure. + /// + /// A failure at any LATER element is a successful short `Rwalk`, and + /// the client is expected to notice that it got fewer qids than it + /// asked for. It gets no error string at all, which is the protocol's + /// choice and not ours. + fn stopWalk(s: *Self, ename: []const u8) void { + const j = &s.job; + if (j.nwqid == 0) + s.fail(j.tag, ename) + else + s.emit(j.tag, .{ .rwalk = .{ .nwqid = j.nwqid, .wqid = j.wqid } }); + s.finishJob(); + } + + fn finishJob(s: *Self) void { + s.job = .{}; + if (s.frame != 0) s.dropFrame(); + } + + /// The core answered a step of the message in flight. + fn jobReply(s: *Self, r: *const fs.Reply, bytes: []const u8) void { + const j = &s.job; + assert(j.kind != .none); + assert(j.req_tag == r.tag); + j.req_tag = 0; + + // A CLUNK CANNOT FAIL. «even if the clunk fails, the fid is no + // longer valid» — clunk(5) — and `remove(5)` says the same of + // remove, so the core's answer to the release is not consulted at + // all. That also means a release the core tried to park is dropped + // rather than leaving behind a fid the client can no longer reach. + if (j.kind == .clunk or j.kind == .remove) { + s.dropFid(j.fid); + if (j.kind == .remove) s.fail(j.tag, e_perm) else s.emit(j.tag, .rclunk); + s.finishJob(); + return; + } + if (r.status == .again) return s.parkJob(); + if (r.status == .err) { + const ename = errString(r.errno); + if (j.kind == .walk) return s.stopWalk(ename); + s.fail(j.tag, ename); + s.finishJob(); + return; + } + + switch (j.kind) { + .none, .clunk, .remove => unreachable, + .attach => { + const i = s.freeFid() orelse { + s.fail(j.tag, e_too_many_fids); + s.finishJob(); + return; + }; + const node = if (r.attr.node != 0) r.attr.node else s.root; + s.fids[i] = .{ + .used = true, + .fid = j.fid, + .node = node, + .dir = r.attr.dir, + .perm = r.attr.mode, + }; + // The root's name is "/" — one of the bugs `ad` shipped + // and then fixed (`9P-18`, commit `64f2f4b`). + s.fids[i].name[0] = '/'; + s.fids[i].name_len = 1; + s.emit(j.tag, .{ .rattach = .{ .qid = qidOf(node, r.attr.dir) } }); + s.finishJob(); + }, + .walk => { + if (r.attr.node != 0) j.node = r.attr.node; + j.dir = r.attr.dir; + j.perm = r.attr.mode; + j.wqid[j.nwqid] = qidOf(j.node, j.dir); + j.nwqid += 1; + j.step += 1; + // The job STAYS: `next()` asks `stepWalk` for the next + // element, or lets it bind the fid and answer. + }, + .open => { + if (j.step == 0 and j.omode & otrunc != 0) { + // The truncate landed; the open is the next step. + j.step = 1; + return; + } + const f = s.jobFid() orelse return; + f.open = true; + f.omode = j.omode; + f.handle = r.handle; + // A fresh open starts a directory at the beginning. + f.diroff = 0; + f.dirindex = 0; + // `iounit` is the largest atomic read or write: one message + // less the slack `fcall.h:72` has reserved for a `Twrite` + // header for thirty years. + s.emit(j.tag, .{ .ropen = .{ + .qid = qidOf(f.node, f.dir), + .iounit = s.msize - iohdrsz, + } }); + s.finishJob(); + }, + .read => { + // Clamped a second time, against the bytes that actually + // came back: the request already carried the count, and a + // core that answered with more would otherwise become an + // `-EIO` in the client rather than a bug here. + s.emit(j.tag, .{ .rread = .{ .data = bytes[0..@min(bytes.len, j.count)] } }); + s.finishJob(); + }, + .readdir => { + s.emitDirRead(j.tag, j.fid, bytes, j.count); + s.finishJob(); + }, + .write => { + // The core's own count and not the request's: `data` + // refusing a partial grapheme is a real short write, and + // claiming the whole request would tell the writer that + // its trailing bytes landed when they did not. + s.emit(j.tag, .{ .rwrite = .{ .count = @min(r.written, j.count) } }); + s.finishJob(); + }, + .stat => { + const f = s.jobFid() orelse return; + // The core is authoritative about size and mode, and the + // fid's cache follows: `body` grows between stats, and + // `Topen` is checked against `perm`. + f.perm = r.attr.mode; + f.dir = r.attr.dir; + s.emit(j.tag, .{ .rstat = .{ .stat = s.statOf(f, r.attr) } }); + s.finishJob(); + }, + .wstat => { + s.emit(j.tag, .rwstat); + s.finishJob(); + }, + } + } + + /// The core said `.again`: nothing consumed, ask me later. The request + /// moves into a park slot and the 9P tag goes with it, so the client + /// hears nothing at all until the core has something to say — which is + /// what makes a blocking `event` read work on a single-threaded core + /// with no waiter list anywhere. + fn parkJob(s: *Self) void { + const j = &s.job; + // Only these three can park, and only because the state a retry + // needs is scalars. A walk cannot: its names borrow the input + // buffer, which the next message overwrites. `e_again` is honest + // (the client may retry) and by construction unreachable — the + // core parks reads of `event` and nothing else. + switch (j.kind) { + .read, .readdir, .write => {}, + else => { + s.fail(j.tag, e_again); + s.finishJob(); + return; + }, + } + const i = s.freeSlot() orelse { + // Overflow is a refusal, not a queue: thirty-two blocked + // readers is thirty-two scripts watching one session. + s.fail(j.tag, e_again); + s.finishJob(); + return; + }; + const sl = &s.slots[i]; + sl.* = .{ + .used = true, + .parked = true, + .seq = s.tick(), + .tag = j.tag, + .kind = j.kind, + .fid = j.fid, + .count = j.count, + .req = j.req, + }; + if (j.req.data.len != 0) { + if (j.req.data.len > park_data_max) { + // A payload too large to copy would go on borrowing the + // input buffer, so parking it would park a dangling slice. + sl.* = .{}; + s.fail(j.tag, e_again); + s.finishJob(); + return; + } + @memcpy(sl.data[0..j.req.data.len], j.req.data); + sl.copied = true; + sl.req.data = sl.data[0..j.req.data.len]; + } + // The frame is nobody's now: everything the retry needs has been + // copied, so the next message may take its place. + s.finishJob(); + } + + /// The core answered a request that had been parked. + fn slotReply(s: *Self, i: usize, r: *const fs.Reply, bytes: []const u8) void { + const sl = &s.slots[i]; + if (r.status == .again) { + sl.parked = true; + return; + } + if (r.status == .err) { + s.fail(sl.tag, errString(r.errno)); + sl.* = .{}; + return; + } + switch (sl.kind) { + .read => s.emit(sl.tag, .{ .rread = .{ .data = bytes[0..@min(bytes.len, sl.count)] } }), + .readdir => s.emitDirRead(sl.tag, sl.fid, bytes, sl.count), + .write => s.emit(sl.tag, .{ .rwrite = .{ .count = @min(r.written, sl.count) } }), + // `parkJob` admits no other kind. + else => s.fail(sl.tag, e_botch), + } + sl.* = .{}; + } + + /// A directory read: `acmefs`'s staged entries become 9P `stat` + /// records, in place, and the fid's cursor advances by exactly what + /// was sent. + /// + /// THE ONE ENTRY THAT DID NOT FIT needs no buffer here, and that is + /// worth saying because every reference server has one: u9fs caches a + /// `dirent` per fid «for when convD2M fails» (`u9fs.c:780`) because + /// `readdir(3)` has already consumed it. `acmefs` re-stages the whole + /// listing from an entry index on every call and says why — + /// «re-staging from scratch on every call is what makes a partially + /// consumed answer safe to ask for again at a higher cookie» + /// (`acmefs.zig:1013-1016`) — so an entry that does not fit is simply + /// not counted, and the next read asks for it by index. + fn emitDirRead(s: *Self, tag: u16, fid: u32, staging: []const u8, count: u32) void { + const buf = s.out[s.out_len..]; + assert(buf.len > header_len + 4); + const cap = @min(@as(usize, count), buf.len - header_len - 4); + const who = s.uname[0..s.uname_len]; + var n: usize = header_len + 4; + var entries: u32 = 0; + var i: usize = 0; + // `node[8] dir[1] namelen[1] name[]`, repeated — `acmefs.zig:942`. + while (i + 10 <= staging.len) { + const nlen = staging[i + 9]; + if (i + 10 + nlen > staging.len) break; + const dir = staging[i + 8] != 0; + const rec: Stat = .{ + .type = 0, + .dev = 0, + .qid = qidOf(std.mem.readInt(u64, staging[i..][0..8], .little), dir), + .mode = (if (dir) dmdir else 0) | @as(u32, if (dir) dirent_dir_perm else dirent_file_perm), + .atime = 0, + .mtime = 0, + .length = 0, + .name = staging[i + 10 ..][0..nlen], + .uid = who, + .gid = who, + .muid = who, + }; + const size = @as(usize, rec.size() catch break) + 2; + // WHOLE RECORDS ONLY. `read(5)`: a directory read returns an + // integral number of entries, so the first one that does not + // fit ends the reply and the cursor stops in front of it. + if (n - header_len - 4 + size > cap) break; + _ = rec.encode(buf[n..]) catch break; + n += size; + entries += 1; + i += 10 + nlen; + } + // A count that cannot hold the FIRST entry is refused rather than + // answered with zero bytes, because zero bytes is end of directory + // and a client that believes it stops asking. `entries == 0` with + // nothing staged is the real end. + if (entries == 0 and staging.len != 0) return s.fail(tag, e_count_small); + const payload: u32 = @intCast(n - header_len - 4); + // The header goes on LAST, over bytes reserved for it, because the + // payload's length is only known once the entries are encoded — + // `u9fs.c:775-806` builds it the same way and for the same reason. + // Written by hand rather than through `encode`, which would want + // the payload contiguous somewhere else first, and this file will + // not carry a third msize buffer to make that true. The test "a + // directory read is whole stat records" decodes the result with + // `decode`, which is what keeps these four lines honest. + comptime assert(header_len == 7); + std.mem.writeInt(u32, buf[0..4], @intCast(n), .little); + buf[4] = @intFromEnum(Type.rread); + std.mem.writeInt(u16, buf[5..7], tag, .little); + std.mem.writeInt(u32, buf[7..11], payload, .little); + s.out_len += n; + // BOTH cursors, together, or the next read is refused: bytes for + // the client's offset rule, entries for `acmefs`'s index. + if (s.findFid(fid)) |k| { + s.fids[k].diroff += payload; + s.fids[k].dirindex += entries; + } + } + + /// One `stat` record for a file the core has just described. + /// + /// `type` and `dev` are Plan 9 kernel device identifiers, meaningless + /// off Plan 9, and zero — as u9fs sends them. `atime` and `mtime` are + /// zero because this tree has no times to report and the FUSE + /// transport already reports none (`fuse.zig:1544-1546`); an invented + /// time is one `make` would believe. The three name fields are whoever + /// attached: the tree is synthetic and has exactly one owner. + fn statOf(s: *const Self, f: *const Fid, a: fs.Reply.Attr) Stat { + const who = s.uname[0..s.uname_len]; + return .{ + .type = 0, + .dev = 0, + .qid = qidOf(if (a.node != 0) a.node else f.node, a.dir), + // The high bits are the type and the low nine are the + // permission: `dmdir` is `qtdir` shifted up 24, which the + // codec's last test asserts rather than assumes. + .mode = (if (a.dir) dmdir else 0) | @as(u32, a.mode), + .atime = 0, + .mtime = 0, + .length = a.size, + .name = f.name[0..f.name_len], + .uid = who, + .gid = who, + .muid = who, + }; + } + }; +} + +// --------------------------------------------------------------------------- +// server tests +// --------------------------------------------------------------------------- +// +// Driven with BYTE ARRAYS and a STUB FILESYSTEM, so there is no `Pardes` here +// and no transport either: `push` takes encoded messages, `pump` is +// `fs_service.drain` written out, and `reap` decodes what came back with the +// codec above. A test that fails is a message a real client would have been +// sent, byte for byte. + +/// Everything `Server` asks of a filesystem, plus a tree small enough to check +/// by eye. The three types are `acmefs`'s ABI verbatim — that is the whole +/// contract, and `Server(acmefs)` is the instantiation that matters — so this +/// is a MIRROR and not a redefinition: a field that drifts is a compile error +/// the moment the real adapter is built. +/// +/// THE NODE IDS ARE `acmefs.Node`'s PACKING, `{ file: u4, serial: u60 }`, and +/// they have to be: `parentOf` reads them. So pane 1's directory is `1 << 4`, +/// its `body` is that plus `PaneFile.body` (2), and the top-level files are +/// `TopFile`'s own 1..4 with a zero serial. +const StubFs = struct { + pub const Op = enum(u8) { lookup, getattr, setattr, open, read, write, release, readdir, statfs }; + pub const Status = enum(u8) { ok, again, err }; + + pub const Req = struct { + tag: u64, + op: Op, + node: u64, + handle: u32 = 0, + off: u64 = 0, + size: u32 = 0, + data: []const u8 = &.{}, + truncate: bool = false, + }; + + pub const Reply = struct { + tag: u64, + status: Status = .ok, + errno: u16 = 0, + attr: Attr = .{}, + handle: u32 = 0, + written: u32 = 0, + + pub const Attr = struct { + node: u64 = 0, + dir: bool = false, + size: u64 = 0, + mode: u16 = 0o600, + }; + }; + + const Entry = struct { node: u64, parent: u64, name: []const u8, dir: bool, mode: u16 }; + + /// `acmefs`'s tree, cut down: the root's four names, two panes, and six of + /// a pane's files including the two that matter most here — `event`, which + /// blocks, and `errors`, which is write-only. + const tree = [_]Entry{ + .{ .node = 1, .parent = 1, .name = "/", .dir = true, .mode = 0o500 }, + .{ .node = 2, .parent = 1, .name = "index", .dir = false, .mode = 0o400 }, + .{ .node = 3, .parent = 1, .name = "cons", .dir = false, .mode = 0o200 }, + .{ .node = 4, .parent = 1, .name = "new", .dir = true, .mode = 0o500 }, + .{ .node = 16, .parent = 1, .name = "1", .dir = true, .mode = 0o500 }, + .{ .node = 32, .parent = 1, .name = "2", .dir = true, .mode = 0o500 }, + .{ .node = 17, .parent = 16, .name = "addr", .dir = false, .mode = 0o600 }, + .{ .node = 18, .parent = 16, .name = "body", .dir = false, .mode = 0o600 }, + .{ .node = 19, .parent = 16, .name = "ctl", .dir = false, .mode = 0o600 }, + .{ .node = 21, .parent = 16, .name = "errors", .dir = false, .mode = 0o200 }, + .{ .node = 22, .parent = 16, .name = "event", .dir = false, .mode = 0o600 }, + .{ .node = 23, .parent = 16, .name = "tag", .dir = false, .mode = 0o600 }, + }; + + const body_node = 18; + const index_node = 2; + const event_node = 22; + + body: []const u8 = "hello, body\n", + /// `index`, and long enough that a read of it has to be clamped. + filler: [1024]u8 = @splat('x'), + /// One event record, or nothing — which is `Status.again`. + event: ?[]const u8 = null, + /// Set to make every write park, so the copy into a slot is exercised. + park_writes: bool = false, + releases: u32 = 0, + calls: u32 = 0, + writes: [128]u8 = undefined, + writes_len: usize = 0, + stage: [1024]u8 = undefined, + + const Answer = struct { reply: Reply, bytes: []const u8 = "" }; + + fn find(node: u64) ?usize { + for (tree, 0..) |e, i| if (e.node == node) return i; + return null; + } + + fn sizeOf(st: *const StubFs, node: u64) u64 { + return switch (node) { + body_node => st.body.len, + index_node => st.filler.len, + else => 0, + }; + } + + fn contentOf(st: *const StubFs, node: u64) []const u8 { + return switch (node) { + body_node => st.body, + index_node => &st.filler, + else => "", + }; + } + + fn attrOf(st: *const StubFs, e: Entry) Reply.Attr { + return .{ .node = e.node, .dir = e.dir, .mode = e.mode, .size = st.sizeOf(e.node) }; + } + + /// `acmefs`'s staging format, which is what the 9P server decodes: + /// `node[8] dir[1] namelen[1] name[]`, repeated, from an ENTRY INDEX. + fn stageDir(st: *StubFs, node: u64, skip: u64) []const u8 { + var n: usize = 0; + var seen: u64 = 0; + for (tree) |e| { + if (e.parent != node or e.node == node) continue; + if (seen < skip) { + seen += 1; + continue; + } + std.mem.writeInt(u64, st.stage[n..][0..8], e.node, .little); + st.stage[n + 8] = @intFromBool(e.dir); + st.stage[n + 9] = @intCast(e.name.len); + @memcpy(st.stage[n + 10 ..][0..e.name.len], e.name); + n += 10 + e.name.len; + } + return st.stage[0..n]; + } + + fn handle(st: *StubFs, req: Req) Answer { + st.calls += 1; + const fail: Answer = .{ .reply = .{ .tag = req.tag, .status = .err, .errno = 2 } }; + const i = find(req.node) orelse return fail; + switch (req.op) { + .lookup => { + for (tree) |e| { + if (e.parent != req.node or e.node == req.node) continue; + if (!std.mem.eql(u8, e.name, req.data)) continue; + return .{ .reply = .{ .tag = req.tag, .attr = st.attrOf(e) } }; + } + return fail; + }, + .getattr => return .{ .reply = .{ .tag = req.tag, .attr = st.attrOf(tree[i]) } }, + .setattr => { + if (req.truncate and req.node == body_node) st.body = ""; + return .{ .reply = .{ .tag = req.tag, .attr = st.attrOf(tree[i]) } }; + }, + .open => return .{ .reply = .{ .tag = req.tag, .handle = 7 } }, + .release => { + st.releases += 1; + return .{ .reply = .{ .tag = req.tag } }; + }, + .readdir => { + if (!tree[i].dir) return .{ .reply = .{ .tag = req.tag, .status = .err, .errno = 20 } }; + return .{ .reply = .{ .tag = req.tag }, .bytes = st.stageDir(req.node, req.off) }; + }, + .read => { + // `event`: one record per read, and `.again` when there is + // none — `acmefs.zig:1358-1367` exactly. + if (req.node == event_node) { + const rec = st.event orelse return .{ .reply = .{ .tag = req.tag, .status = .again } }; + st.event = null; + return .{ .reply = .{ .tag = req.tag }, .bytes = rec }; + } + const all = st.contentOf(req.node); + if (req.off >= all.len) return .{ .reply = .{ .tag = req.tag } }; + const from = all[@intCast(req.off)..]; + return .{ .reply = .{ .tag = req.tag }, .bytes = from[0..@min(from.len, req.size)] }; + }, + .write => { + if (st.park_writes) return .{ .reply = .{ .tag = req.tag, .status = .again } }; + const n = @min(req.data.len, st.writes.len - st.writes_len); + @memcpy(st.writes[st.writes_len..][0..n], req.data[0..n]); + st.writes_len += n; + return .{ .reply = .{ .tag = req.tag, .written = @intCast(n) } }; + }, + .statfs => return .{ .reply = .{ .tag = req.tag } }, + } + } +}; + +const Srv = Server(StubFs); + +/// One connection: two buffers, a stub filesystem and the server between them. +const Harness = struct { + in: [4096]u8 = undefined, + out: [8192]u8 = undefined, + fsys: StubFs = .{}, + srv: Srv = undefined, + + /// The buffers are fields, so the server can only be built once the + /// harness has an address. + fn start(h: *Harness) void { + h.srv = Srv.init(.{ .in = &h.in, .out = &h.out, .root = 1 }); + } + + fn answer(h: *Harness, req: StubFs.Req) void { + const a = h.fsys.handle(req); + h.srv.reply(&a.reply, a.bytes); + } + + /// THE TRANSPORT CONTRACT, in the shape `src/fs_service.zig:209-222` + /// requires it: every parked request offered once, then everything the + /// wire has, both loops to null. Written out rather than imported — + /// `fs_service` is `pardes.zig` deep — and writing it out is how these + /// tests document what they are testing against. + fn pump(h: *Harness) void { + while (h.srv.retry()) |req| h.answer(req); + while (h.srv.next()) |req| h.answer(req); + } + + fn send(h: *Harness, tag: u16, msg: Msg) !void { + var buf: [1024]u8 = undefined; + const bytes = try encode(msg, tag, &buf); + try testing.expectEqual(bytes.len, h.srv.push(bytes)); + h.pump(); + } + + /// One reply off the queue. Borrows the out buffer, so a caller checks it + /// before sending anything else. + fn reap(h: *Harness) !Decoded { + const out = h.srv.output(); + const len = frameLen(out) orelse return error.NoReply; + if (len > out.len) return error.ShortReply; + const got = try decode(out[0..len]); + h.srv.wrote(len); + return got; + } + + fn quiet(h: *Harness) !void { + try testing.expectEqual(@as(usize, 0), h.srv.output().len); + } + + /// `Tversion` and `Tattach`, which every test but the handshake ones want, + /// leaving the root on fid 0. + fn handshake(h: *Harness, msize: u32) !void { + h.start(); + try h.send(notag, .{ .tversion = .{ .msize = msize, .version = "9P2000" } }); + const v = try h.reap(); + try testing.expectEqualStrings("9P2000", v.msg.rversion.version); + try h.send(0, .{ .tattach = .{ .fid = 0, .afid = nofid, .uname = "goblin", .aname = "" } }); + const a = try h.reap(); + try testing.expectEqual(@as(u64, 1), a.msg.rattach.qid.path); + } + + /// A walk from the root to one name, landing on `newfid`. + fn walkTo(h: *Harness, tag: u16, newfid: u32, list: []const []const u8) !Decoded { + try h.send(tag, .{ .twalk = .{ + .fid = 0, + .newfid = newfid, + .nwname = @intCast(list.len), + .wname = wnames(list), + } }); + return h.reap(); + } +}; + +fn wnames(list: []const []const u8) [max_welem][]const u8 { + var out: [max_welem][]const u8 = @splat(""); + for (list, 0..) |n, i| out[i] = n; + return out; +} + +/// The names in a directory read, decoded as whole `stat` records. Which is +/// also the proof that `emitDirRead`'s hand-written header is right: this goes +/// through `Stat.decode`, which refuses anything that does not add up. +fn dirNames(data: []const u8, out: [][]const u8) !usize { + var n: usize = 0; + var i: usize = 0; + while (i < data.len) { + const size = std.mem.readInt(u16, data[i..][0..2], .little); + const st = try Stat.decode(data[i..][0 .. @as(usize, size) + 2]); + out[n] = st.name; + n += 1; + i += @as(usize, size) + 2; + } + return n; +} + +test "9p server: the version handshake clamps, falls back, and refuses" { + var h: Harness = .{}; + h.start(); + + // A client offering a megabyte gets what the buffers hold: one input + // buffer, or half the output queue, whichever is smaller. + try h.send(notag, .{ .tversion = .{ .msize = 1 << 20, .version = "9P2000" } }); + var got = try h.reap(); + try testing.expectEqual(notag, got.tag); + try testing.expectEqual(@as(u32, 4096), got.msg.rversion.msize); + try testing.expectEqualStrings("9P2000", got.msg.rversion.version); + + // BELOW LINUX'S FLOOR IS FINE. 4096 is the kernel's number and nobody + // else's: Plan 9's devmnt, plan9port's `9p` and our own client all accept + // 512, and refusing it would cost the board a kilobyte for nothing. + try h.send(notag, .{ .tversion = .{ .msize = 512, .version = "9P2000" } }); + got = try h.reap(); + try testing.expectEqual(@as(u32, 512), got.msg.rversion.msize); + + // A `.u` client is told to fall back rather than refused: u9fs answers + // "9P2000" to any version starting with "9P". + try h.send(notag, .{ .tversion = .{ .msize = 4096, .version = "9P2000.u" } }); + got = try h.reap(); + try testing.expectEqualStrings("9P2000", got.msg.rversion.version); + + // Something that is not 9P at all: the literal "unknown", in a SUCCESSFUL + // Rversion and not an Rerror. + try h.send(notag, .{ .tversion = .{ .msize = 4096, .version = "TCP/IP" } }); + got = try h.reap(); + try testing.expectEqualStrings("unknown", got.msg.rversion.version); + // ...and nothing else is served until a version is agreed. + try h.send(1, .{ .tattach = .{ .fid = 0, .afid = nofid, .uname = "goblin", .aname = "" } }); + got = try h.reap(); + try testing.expectEqualStrings(e_botch, got.msg.rerror.ename); + + // An msize too small to hold one `Rwalk` cannot be served at all, and + // `Rversion` has no field that means "too small" — so `Rerror`, which is a + // legal reply to any T-message. + try h.send(notag, .{ .tversion = .{ .msize = 64, .version = "9P2000" } }); + got = try h.reap(); + try testing.expectEqualStrings(e_small_msize, got.msg.rerror.ename); + try testing.expectEqual(@as(u32, 216), msize_min - 1); +} + +test "9p server: attach names the root, and the only tree there is" { + var h: Harness = .{}; + h.start(); + try h.send(notag, .{ .tversion = .{ .msize = 4096, .version = "9P2000" } }); + _ = try h.reap(); + + // An `aname` names a tree we do not have, and saying so beats handing over + // the one we do. + try h.send(1, .{ .tattach = .{ .fid = 0, .afid = nofid, .uname = "goblin", .aname = "work" } }); + var got = try h.reap(); + try testing.expectEqualStrings(e_no_tree, got.msg.rerror.ename); + + try h.send(2, .{ .tattach = .{ .fid = 0, .afid = nofid, .uname = "goblin", .aname = "" } }); + got = try h.reap(); + try testing.expectEqual(@as(u64, 1), got.msg.rattach.qid.path); + try testing.expectEqual(qtdir, got.msg.rattach.qid.type); + // ALWAYS ZERO, which is what makes Linux's client skip its cache. + try testing.expectEqual(@as(u32, 0), got.msg.rattach.qid.version); + + // The same fid twice is a client bug, refused rather than rebound. + try h.send(3, .{ .tattach = .{ .fid = 0, .afid = nofid, .uname = "goblin", .aname = "" } }); + got = try h.reap(); + try testing.expectEqualStrings(e_fid_in_use, got.msg.rerror.ename); + + // `Tauth` is refused, which is how a Plan 9 mount learns there is no + // authentication here and carries on without it. + try h.send(4, .{ .tauth = .{ .afid = 1, .uname = "goblin", .aname = "" } }); + got = try h.reap(); + try testing.expectEqualStrings(e_no_auth, got.msg.rerror.ename); + + // The attacher's name is what `Rstat` reports as owner, group and last + // modifier: the tree is synthetic and has exactly one owner. + try h.send(5, .{ .tstat = .{ .fid = 0 } }); + got = try h.reap(); + try testing.expectEqualStrings("/", got.msg.rstat.stat.name); + try testing.expectEqualStrings("goblin", got.msg.rstat.stat.uid); + try testing.expectEqualStrings("goblin", got.msg.rstat.stat.muid); + try testing.expect(got.msg.rstat.stat.mode & dmdir != 0); +} + +test "9p server: a three-element walk, and `..` with no kernel to resolve it" { + var h: Harness = .{}; + try h.handshake(4096); + + // Three elements in one message, on a tree that is three deep: `..` at the + // root is the root, which is POSIX's rule and intro(5)'s, and NOT an error. + var got = try h.walkTo(5, 1, &.{ "..", "1", "body" }); + try testing.expectEqual(@as(u16, 3), got.msg.rwalk.nwqid); + try testing.expectEqual(@as(u64, 1), got.msg.rwalk.wqid[0].path); + try testing.expectEqual(@as(u64, 16), got.msg.rwalk.wqid[1].path); + try testing.expectEqual(@as(u64, 18), got.msg.rwalk.wqid[2].path); + try testing.expectEqual(qtdir, got.msg.rwalk.wqid[1].type); + try testing.expectEqual(qtfile, got.msg.rwalk.wqid[2].type); + for (got.msg.rwalk.wqid[0..3]) |q| try testing.expectEqual(@as(u32, 0), q.version); + + // Up and down and up and down. `..` from a pane's directory is the root + // too, and five elements land where two would have. + got = try h.walkTo(6, 2, &.{ "..", "1", "..", "1", "body" }); + try testing.expectEqual(@as(u16, 5), got.msg.rwalk.nwqid); + try testing.expectEqual(@as(u64, 1), got.msg.rwalk.wqid[2].path); + try testing.expectEqual(@as(u64, 18), got.msg.rwalk.wqid[4].path); + // ...and the fid really is the body. + try h.send(7, .{ .tstat = .{ .fid = 2 } }); + got = try h.reap(); + try testing.expectEqualStrings("body", got.msg.rstat.stat.name); + try testing.expectEqual(@as(u64, 12), got.msg.rstat.stat.length); + + // `..` after an element that landed on a FILE is that pane's directory — + // `parentOf`'s third case — and the name comes out of the node id rather + // than out of the element, because "1" is not what the client typed. + got = try h.walkTo(8, 3, &.{ "1", "body", ".." }); + try testing.expectEqual(@as(u16, 3), got.msg.rwalk.nwqid); + try testing.expectEqual(@as(u64, 16), got.msg.rwalk.wqid[2].path); + try testing.expectEqual(qtdir, got.msg.rwalk.wqid[2].type); + try h.send(9, .{ .tstat = .{ .fid = 3 } }); + got = try h.reap(); + try testing.expectEqualStrings("1", got.msg.rstat.stat.name); + + // `.` is where the fid already stands, and it costs the core NOTHING: no + // request is made for it at all. + const before = h.fsys.calls; + got = try h.walkTo(10, 4, &.{ ".", "." }); + try testing.expectEqual(@as(u16, 2), got.msg.rwalk.nwqid); + try testing.expectEqual(@as(u64, 1), got.msg.rwalk.wqid[1].path); + try testing.expectEqual(before, h.fsys.calls); +} + +test "9p server: a walk failing on the first element is Rerror, on the second a short Rwalk" { + var h: Harness = .{}; + try h.handshake(4096); + + // THE SCAR (`ad/.../sansio/server.rs:335-338`): zero qids already means + // the clone, so a failure on the first element cannot be spelled that way. + var got = try h.walkTo(5, 1, &.{ "nope", "body" }); + try testing.expectEqualStrings("No such file or directory", got.msg.rerror.ename); + + // A failure LATER is a successful short `Rwalk` with no error string at + // all, which is the protocol's choice and not ours. + got = try h.walkTo(6, 1, &.{ "1", "nope" }); + try testing.expectEqual(@as(u16, 1), got.msg.rwalk.nwqid); + try testing.expectEqual(@as(u64, 16), got.msg.rwalk.wqid[0].path); + + // ...and `newfid` is NOT bound by a partial walk. + try h.send(7, .{ .tstat = .{ .fid = 1 } }); + got = try h.reap(); + try testing.expectEqualStrings(e_unknown_fid, got.msg.rerror.ename); + + // The clone does bind it, with zero qids and no lookups. + try h.send(8, .{ .twalk = .{ .fid = 0, .newfid = 1, .nwname = 0 } }); + got = try h.reap(); + try testing.expectEqual(@as(u16, 0), got.msg.rwalk.nwqid); + try h.send(9, .{ .tstat = .{ .fid = 1 } }); + got = try h.reap(); + try testing.expectEqualStrings("/", got.msg.rstat.stat.name); + + // A walk with names from something that is not a directory is not a walk. + got = try h.walkTo(10, 2, &.{"index"}); + try testing.expectEqual(@as(u16, 1), got.msg.rwalk.nwqid); + try h.send(11, .{ .twalk = .{ .fid = 2, .newfid = 3, .nwname = 1, .wname = wnames(&.{"body"}) } }); + got = try h.reap(); + try testing.expectEqualStrings(e_not_dir, got.msg.rerror.ename); + + // A name no fid could hold is refused on its length rather than looked up, + // which is what keeps `Rstat`'s name field honest. + got = try h.walkTo(12, 4, &.{"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}); + try testing.expectEqualStrings(e_illegal_name, got.msg.rerror.ename); + + // An in-use `newfid` is refused before anything is walked. + try h.send(13, .{ .twalk = .{ .fid = 0, .newfid = 1, .nwname = 1, .wname = wnames(&.{"1"}) } }); + got = try h.reap(); + try testing.expectEqualStrings(e_fid_in_use, got.msg.rerror.ename); +} + +test "9p server: open then read then clunk, and the release a clunk owes the core" { + var h: Harness = .{}; + try h.handshake(4096); + _ = try h.walkTo(5, 1, &.{ "1", "body" }); + + try h.send(6, .{ .topen = .{ .fid = 1, .mode = oread } }); + var got = try h.reap(); + try testing.expectEqual(@as(u64, 18), got.msg.ropen.qid.path); + // `iounit` is one message less the slack `fcall.h:72` reserves. + try testing.expectEqual(@as(u32, 4096 - iohdrsz), got.msg.ropen.iounit); + + // The fid IS the open, so a second one has nothing to mean. + try h.send(7, .{ .topen = .{ .fid = 1, .mode = oread } }); + got = try h.reap(); + try testing.expectEqualStrings(e_already_open, got.msg.rerror.ename); + + try h.send(8, .{ .tread = .{ .fid = 1, .offset = 0, .count = 4096 } }); + got = try h.reap(); + try testing.expectEqualStrings("hello, body\n", got.msg.rread.data); + + // Offsets are honoured on `body`, which is the whole reason `cat`, `wc` + // and `tail` work against this tree (docs/9p.typ §4). + try h.send(9, .{ .tread = .{ .fid = 1, .offset = 7, .count = 4096 } }); + got = try h.reap(); + try testing.expectEqualStrings("body\n", got.msg.rread.data); + + // Past the end is zero bytes, which is end of file and not an error. + try h.send(10, .{ .tread = .{ .fid = 1, .offset = 99, .count = 16 } }); + got = try h.reap(); + try testing.expectEqual(@as(usize, 0), got.msg.rread.data.len); + + // THE RELEASE. Without it a pane's `event` reader count never comes back + // down and the editor answers to a script that has gone. + try testing.expectEqual(@as(u32, 0), h.fsys.releases); + try h.send(11, .{ .tclunk = .{ .fid = 1 } }); + got = try h.reap(); + try testing.expect(got.msg == .rclunk); + try testing.expectEqual(@as(u32, 1), h.fsys.releases); + + // A FID USED AFTER CLUNK is a fid nobody knows. + try h.send(12, .{ .tread = .{ .fid = 1, .offset = 0, .count = 16 } }); + got = try h.reap(); + try testing.expectEqualStrings(e_unknown_fid, got.msg.rerror.ename); + try h.send(13, .{ .tclunk = .{ .fid = 1 } }); + got = try h.reap(); + try testing.expectEqualStrings(e_unknown_fid, got.msg.rerror.ename); + + // A clunk of a fid that was never opened needs no release at all. + _ = try h.walkTo(14, 2, &.{"index"}); + try h.send(15, .{ .tclunk = .{ .fid = 2 } }); + got = try h.reap(); + try testing.expect(got.msg == .rclunk); + try testing.expectEqual(@as(u32, 1), h.fsys.releases); +} + +test "9p server: every Rread is clamped to the client's count and to the msize" { + var h: Harness = .{}; + // A small msize on purpose: `index` is a kilobyte and one message cannot + // carry it. + try h.handshake(512); + _ = try h.walkTo(5, 1, &.{"index"}); + try h.send(6, .{ .topen = .{ .fid = 1, .mode = oread } }); + _ = try h.reap(); + + // The count, when the count is the smaller. + try h.send(7, .{ .tread = .{ .fid = 1, .offset = 0, .count = 5 } }); + var got = try h.reap(); + try testing.expectEqual(@as(usize, 5), got.msg.rread.data.len); + + // The MSIZE, when the client asks for more than one message can hold. An + // `Rread` longer than the count is a hard -EIO in Linux + // (`client.c:1475-1479`) and one longer than the msize is unreadable, so + // the answer is `msize - 11` exactly and the whole message is `msize`. + try h.send(8, .{ .tread = .{ .fid = 1, .offset = 0, .count = 1 << 20 } }); + const out = h.srv.output(); + try testing.expectEqual(@as(?u32, 512), frameLen(out)); + got = try h.reap(); + try testing.expectEqual(@as(usize, 512 - header_len - 4), got.msg.rread.data.len); + + // And the core was never asked for bytes that would have been thrown + // away: the clamp is on the request too. + try h.send(9, .{ .tread = .{ .fid = 1, .offset = 0, .count = 1 << 20 } }); + got = try h.reap(); + try testing.expectEqual(@as(usize, 501), got.msg.rread.data.len); +} + +test "9p server: a directory read is whole stat records at a cursor the client cannot invent" { + var h: Harness = .{}; + try h.handshake(4096); + // Walked before the root is opened, because an open fid cannot be walked + // (walk(5)) and the mode assertion at the bottom of this test needs it. + _ = try h.walkTo(4, 1, &.{"index"}); + try h.send(5, .{ .topen = .{ .fid = 0, .mode = oread } }); + _ = try h.reap(); + + var found: [8][]const u8 = undefined; + + // Two entries fit in 150 bytes; the third does not, so it is not counted + // and the next read asks for it by index. No cached entry anywhere, which + // is what `acmefs`'s re-staging buys (`acmefs.zig:1013-1016`). + try h.send(6, .{ .tread = .{ .fid = 0, .offset = 0, .count = 150 } }); + var got = try h.reap(); + const first = got.msg.rread.data.len; + try testing.expectEqual(@as(usize, 2), try dirNames(got.msg.rread.data, &found)); + try testing.expectEqualStrings("index", found[0]); + try testing.expectEqualStrings("cons", found[1]); + try testing.expect(first <= 150); + + // THE RULE: the next read carries exactly the byte offset where the last + // one ended. Not the entry count, and not anything the client chose. + try h.send(7, .{ .tread = .{ .fid = 0, .offset = first, .count = 150 } }); + got = try h.reap(); + const second = got.msg.rread.data.len; + try testing.expectEqual(@as(usize, 2), try dirNames(got.msg.rread.data, &found)); + try testing.expectEqualStrings("new", found[0]); + try testing.expectEqualStrings("1", found[1]); + + // An arbitrary offset is refused — even one that would land on an entry + // boundary, which is exactly the case `ad` accepts silently (`9P-5`). + try h.send(8, .{ .tread = .{ .fid = 0, .offset = first + second + 1, .count = 150 } }); + got = try h.reap(); + try testing.expectEqualStrings(e_bad_offset, got.msg.rerror.ename); + try h.send(9, .{ .tread = .{ .fid = 0, .offset = 3, .count = 150 } }); + got = try h.reap(); + try testing.expectEqualStrings(e_bad_offset, got.msg.rerror.ename); + + // The refusal did not move the cursor: the listing carries on. + try h.send(10, .{ .tread = .{ .fid = 0, .offset = first + second, .count = 150 } }); + got = try h.reap(); + try testing.expectEqual(@as(usize, 1), try dirNames(got.msg.rread.data, &found)); + try testing.expectEqualStrings("2", found[0]); + + // Zero bytes is END OF DIRECTORY, and it is not an error. + try h.send(11, .{ .tread = .{ .fid = 0, .offset = first + second + got.msg.rread.data.len, .count = 150 } }); + got = try h.reap(); + try testing.expectEqual(@as(usize, 0), got.msg.rread.data.len); + + // Offset zero REWINDS, which is the only seek 9P allows in a directory. + try h.send(12, .{ .tread = .{ .fid = 0, .offset = 0, .count = 150 } }); + got = try h.reap(); + try testing.expectEqual(@as(usize, 2), try dirNames(got.msg.rread.data, &found)); + try testing.expectEqualStrings("index", found[0]); + + // A count too small for ONE entry is refused rather than answered with + // zero bytes, because zero bytes means end of directory and a client that + // believes it stops asking. + try h.send(13, .{ .tread = .{ .fid = 0, .offset = 0, .count = 40 } }); + got = try h.reap(); + try testing.expectEqualStrings(e_count_small, got.msg.rerror.ename); + + // A directory's entries carry the tree's default mode and a zero length; + // the exact bits come from `Tstat`, which asks the core. + try h.send(14, .{ .tread = .{ .fid = 0, .offset = 0, .count = 150 } }); + got = try h.reap(); + const one = try Stat.decode(got.msg.rread.data[0 .. std.mem.readInt(u16, got.msg.rread.data[0..2], .little) + 2]); + try testing.expectEqualStrings("index", one.name); + try testing.expectEqual(@as(u32, dirent_file_perm), one.mode); + try testing.expectEqual(@as(u64, 0), one.length); + try testing.expectEqual(@as(u32, 0), one.qid.version); + + try h.send(16, .{ .tstat = .{ .fid = 1 } }); + got = try h.reap(); + try testing.expectEqual(@as(u32, 0o400), got.msg.rstat.stat.mode); + try testing.expectEqual(@as(u64, 1024), got.msg.rstat.stat.length); +} + +test "9p server: a blocked read parks, and the connection keeps working" { + var h: Harness = .{}; + try h.handshake(4096); + _ = try h.walkTo(5, 1, &.{ "1", "event" }); + try h.send(6, .{ .topen = .{ .fid = 1, .mode = oread } }); + _ = try h.reap(); + + // `Status.again`: nothing consumed, ask me later. NOT an error and NOT an + // empty read — the client hears nothing at all. + try h.send(7, .{ .tread = .{ .fid = 1, .offset = 0, .count = 4096 } }); + try h.quiet(); + + // A retry round finds it, the core still has nothing, and it goes back. + h.pump(); + h.pump(); + try h.quiet(); + + // Meanwhile the connection is not blocked: another tag is served while the + // read waits, which is the entire point of parking rather than waiting. + _ = try h.walkTo(8, 2, &.{ "1", "body" }); + try h.send(9, .{ .tstat = .{ .fid = 2 } }); + var got = try h.reap(); + try testing.expectEqualStrings("body", got.msg.rstat.stat.name); + + // The core has something now, and the retry round is what delivers it — + // with the tag the client used seven messages ago. + h.fsys.event = "Kli7 7 0 0 hello\n"; + h.pump(); + got = try h.reap(); + try testing.expectEqual(@as(u16, 7), got.tag); + try testing.expectEqualStrings("Kli7 7 0 0 hello\n", got.msg.rread.data); + try h.quiet(); + + // A write the core parks is copied out of the input buffer, so the next + // message may overwrite it and the retry still has its bytes. + _ = try h.walkTo(10, 3, &.{ "1", "ctl" }); + try h.send(11, .{ .topen = .{ .fid = 3, .mode = owrite } }); + _ = try h.reap(); + h.fsys.park_writes = true; + try h.send(12, .{ .twrite = .{ .fid = 3, .offset = 0, .data = "clean\n" } }); + try h.quiet(); + try h.send(13, .{ .tstat = .{ .fid = 2 } }); + _ = try h.reap(); + h.fsys.park_writes = false; + h.pump(); + got = try h.reap(); + try testing.expectEqual(@as(u16, 12), got.tag); + try testing.expectEqual(@as(u32, 6), got.msg.rwrite.count); + try testing.expectEqualStrings("clean\n", h.fsys.writes[0..h.fsys.writes_len]); + // Overflow is a refusal and not a queue. Thirty-two blocked readers is + // thirty-two scripts watching one session; the thirty-third is told to + // retry, which is honest, rather than dropped, which would hang it. + for (0..max_slots) |k| { + try h.send(@intCast(100 + k), .{ .tread = .{ .fid = 1, .offset = 0, .count = 4096 } }); + try h.quiet(); + } + try h.send(200, .{ .tread = .{ .fid = 1, .offset = 0, .count = 4096 } }); + got = try h.reap(); + try testing.expectEqualStrings(e_again, got.msg.rerror.ename); +} + +test "9p server: the reply queue is a FIFO that survives a partial write" { + var h: Harness = .{}; + try h.handshake(4096); + + // A UART writes what it can. What is left stays, in order, and the next + // reply lands behind it rather than on top of it. + try h.send(5, .{ .tstat = .{ .fid = 0 } }); + var saved: [256]u8 = undefined; + const one = h.srv.output(); + const n = one.len; + @memcpy(saved[0..n], one); + h.srv.wrote(3); + try testing.expectEqual(n - 3, h.srv.output().len); + + try h.send(6, .{ .tstat = .{ .fid = 0 } }); + const rest = h.srv.output(); + try testing.expectEqualSlices(u8, saved[3..n], rest[0 .. n - 3]); + const tail = rest[n - 3 ..]; + const second = try decode(tail[0..frameLen(tail).?]); + try testing.expectEqual(@as(u16, 6), second.tag); + + // `push` takes what there is room for and says how much, which is the only + // back-pressure a server with no descriptor has. (A buffer of zeros is + // also a `size` no encoder produced, so the connection dies on it — which + // is the other half of what a caller has to handle.) + var flood: [8192]u8 = @splat(0); + try testing.expectEqual(@as(usize, 4096), h.srv.push(&flood)); + h.pump(); + try testing.expect(h.srv.dead); + try testing.expectEqual(@as(usize, 0), h.srv.push(&flood)); +} + +test "9p server: Tflush answers the original first and the Rflush second" { + var h: Harness = .{}; + try h.handshake(4096); + _ = try h.walkTo(5, 1, &.{ "1", "event" }); + try h.send(6, .{ .topen = .{ .fid = 1, .mode = oread } }); + _ = try h.reap(); + try h.send(7, .{ .tread = .{ .fid = 1, .offset = 0, .count = 4096 } }); + try h.quiet(); + + // TWO messages, in this order and no other. A client that sees `Rflush` + // may reuse the tag, so a reply arriving after it would be a reply to + // whatever that tag names next. + try h.send(8, .{ .tflush = .{ .oldtag = 7 } }); + var got = try h.reap(); + try testing.expectEqual(@as(u16, 7), got.tag); + try testing.expectEqualStrings(e_interrupted, got.msg.rerror.ename); + got = try h.reap(); + try testing.expectEqual(@as(u16, 8), got.tag); + try testing.expect(got.msg == .rflush); + try h.quiet(); + + // The park slot is gone with it: the core producing an event now sends + // nothing, rather than a second answer to a tag the client has reused. + h.fsys.event = "Kli7 7 0 0 hello\n"; + h.pump(); + try h.quiet(); + + // A flush of a tag we do not hold is an `Rflush` and nothing else, which + // is the only promise flush(5) makes. + try h.send(9, .{ .tflush = .{ .oldtag = 99 } }); + got = try h.reap(); + try testing.expectEqual(@as(u16, 9), got.tag); + try testing.expect(got.msg == .rflush); + try h.quiet(); +} + +test "9p server: the fid and permission refusals, each in a string Linux knows" { + var h: Harness = .{}; + try h.handshake(4096); + + // A fid nobody walked to. + for ([_]Msg{ + .{ .tread = .{ .fid = 99, .offset = 0, .count = 16 } }, + .{ .tstat = .{ .fid = 99 } }, + .{ .tclunk = .{ .fid = 99 } }, + .{ .topen = .{ .fid = 99, .mode = oread } }, + .{ .twalk = .{ .fid = 99, .newfid = 98, .nwname = 0 } }, + }, 20..) |msg, tag| { + try h.send(@intCast(tag), msg); + const got = try h.reap(); + try testing.expectEqualStrings(e_unknown_fid, got.msg.rerror.ename); + } + + // A fid that was never opened, and one opened the other way round. Both + // are `u9fs.c:755-758`'s two conditions. + _ = try h.walkTo(5, 1, &.{ "1", "body" }); + try h.send(6, .{ .tread = .{ .fid = 1, .offset = 0, .count = 16 } }); + var got = try h.reap(); + try testing.expectEqualStrings(e_bad_use, got.msg.rerror.ename); + try h.send(7, .{ .topen = .{ .fid = 1, .mode = oread } }); + _ = try h.reap(); + try h.send(8, .{ .twrite = .{ .fid = 1, .offset = 0, .data = "x" } }); + got = try h.reap(); + try testing.expectEqualStrings(e_bad_use, got.msg.rerror.ename); + + // «must not have been opened for I/O» — walk(5). The fid IS the open. + try h.send(9, .{ .twalk = .{ .fid = 1, .newfid = 2, .nwname = 0 } }); + got = try h.reap(); + try testing.expectEqualStrings(e_bad_use, got.msg.rerror.ename); + + // THE PERMISSION CHECK IS OURS: there is no kernel above us to do it, and + // `errors` is write-only in acme's own dirtab. + _ = try h.walkTo(10, 3, &.{ "1", "errors" }); + try h.send(11, .{ .topen = .{ .fid = 3, .mode = oread } }); + got = try h.reap(); + try testing.expectEqualStrings(e_perm, got.msg.rerror.ename); + try h.send(12, .{ .topen = .{ .fid = 3, .mode = owrite } }); + got = try h.reap(); + try testing.expect(got.msg == .ropen); + + // A directory is read and only read; and nothing here can be removed, so + // nothing can be opened remove-on-close or executed either. + try h.send(13, .{ .topen = .{ .fid = 0, .mode = ordwr } }); + got = try h.reap(); + try testing.expectEqualStrings(e_perm, got.msg.rerror.ename); + _ = try h.walkTo(14, 4, &.{ "1", "tag" }); + for ([_]u8{ orclose, oexec, oread | orclose }, 30..) |mode, tag| { + try h.send(@intCast(tag), .{ .topen = .{ .fid = 4, .mode = mode } }); + got = try h.reap(); + try testing.expectEqualStrings(e_perm, got.msg.rerror.ename); + } +} + +test "9p server: Twstat with a zero length is the truncate, and so is OTRUNC" { + var h: Harness = .{}; + try h.handshake(4096); + _ = try h.walkTo(5, 1, &.{ "1", "body" }); + + // The sentinels stat(5) specifies: an empty string, an all-ones integer. + const sentinel: Stat = .{ + .type = std.math.maxInt(u16), + .dev = std.math.maxInt(u32), + .qid = .{ .type = 0xFF, .version = std.math.maxInt(u32), .path = std.math.maxInt(u64) }, + .mode = std.math.maxInt(u32), + .atime = std.math.maxInt(u32), + .mtime = std.math.maxInt(u32), + .length = std.math.maxInt(u64), + .name = "", + .uid = "", + .gid = "", + .muid = "", + }; + + // Nothing to do: accepted and ignored, which is what a filesystem of live + // editor state has to do with a mode, an owner and two times. + try h.send(6, .{ .twstat = .{ .fid = 1, .stat = sentinel } }); + var got = try h.reap(); + try testing.expect(got.msg == .rwstat); + try testing.expectEqualStrings("hello, body\n", h.fsys.body); + + // A length that is neither the sentinel nor zero. The core honours exactly + // one value, and this string is one Linux maps to EPERM rather than 526. + var five = sentinel; + five.length = 5; + try h.send(7, .{ .twstat = .{ .fid = 1, .stat = five } }); + got = try h.reap(); + try testing.expectEqualStrings(e_trunc_only, got.msg.rerror.ename); + + // A rename would change the shape of a tree that follows the pane list. + var renamed = sentinel; + renamed.name = "other"; + try h.send(8, .{ .twstat = .{ .fid = 1, .stat = renamed } }); + got = try h.reap(); + try testing.expectEqualStrings(e_wstat, got.msg.rerror.ename); + try testing.expectEqualStrings("hello, body\n", h.fsys.body); + + // ...and zero IS the truncate. + var zero = sentinel; + zero.length = 0; + try h.send(9, .{ .twstat = .{ .fid = 1, .stat = zero } }); + got = try h.reap(); + try testing.expect(got.msg == .rwstat); + try testing.expectEqualStrings("", h.fsys.body); + + // The other spelling of the same thing, and the one a shell's `>` + // produces: `Topen` with `OTRUNC` is a truncate and then an open, in that + // order, and it is refused on a fid with no write permission. + h.fsys.body = "hello, body\n"; + _ = try h.walkTo(10, 2, &.{"index"}); + try h.send(11, .{ .topen = .{ .fid = 2, .mode = oread | otrunc } }); + got = try h.reap(); + try testing.expectEqualStrings(e_perm, got.msg.rerror.ename); + try h.send(12, .{ .topen = .{ .fid = 1, .mode = owrite | otrunc } }); + got = try h.reap(); + try testing.expectEqual(@as(u64, 18), got.msg.ropen.qid.path); + try testing.expectEqualStrings("", h.fsys.body); +} + +test "9p server: create and remove are refused, and a remove clunks the fid anyway" { + var h: Harness = .{}; + try h.handshake(4096); + + // Nothing in a generated tree is a client's to make. The one place a + // client DOES create something is `new/`, where the WALK creates a pane — + // so the capability exists and is not spelled `Tcreate` (`9P-18`). + try h.send(5, .{ .tcreate = .{ .fid = 0, .name = "thing", .perm = 0o600, .mode = owrite } }); + var got = try h.reap(); + try testing.expectEqualStrings(e_perm, got.msg.rerror.ename); + + // A remove is refused too — but «the fid is clunked even if the remove + // fails», which is the half of remove(5) that is easy to miss, and the + // release still goes to the core. + _ = try h.walkTo(6, 1, &.{ "1", "body" }); + try h.send(7, .{ .topen = .{ .fid = 1, .mode = ordwr } }); + _ = try h.reap(); + try h.send(8, .{ .tremove = .{ .fid = 1 } }); + got = try h.reap(); + try testing.expectEqualStrings(e_perm, got.msg.rerror.ename); + try testing.expectEqual(@as(u32, 1), h.fsys.releases); + try h.send(9, .{ .tstat = .{ .fid = 1 } }); + got = try h.reap(); + try testing.expectEqualStrings(e_unknown_fid, got.msg.rerror.ename); +} + +test "9p server: a message arriving a byte at a time is served when its last byte lands" { + var h: Harness = .{}; + try h.handshake(4096); + + // The board's UART, and a socket that happened to split a write. Framing + // is `size[4]` and nothing may be served until all of it is in. + var buf: [64]u8 = undefined; + const bytes = try encode(.{ .tstat = .{ .fid = 0 } }, 5, &buf); + for (bytes[0 .. bytes.len - 1]) |b| { + try testing.expectEqual(@as(usize, 1), h.srv.push(&.{b})); + h.pump(); + try h.quiet(); + } + try testing.expectEqual(@as(usize, 1), h.srv.push(bytes[bytes.len - 1 ..])); + h.pump(); + const got = try h.reap(); + try testing.expectEqualStrings("/", got.msg.rstat.stat.name); + + // TWO messages in one push are two replies, in order, and the input buffer + // ends up empty. + var pair: [128]u8 = undefined; + const a = try encode(.{ .tstat = .{ .fid = 0 } }, 6, &pair); + const b = try encode(.{ .tstat = .{ .fid = 0 } }, 7, pair[a.len..]); + try testing.expectEqual(a.len + b.len, h.srv.push(pair[0 .. a.len + b.len])); + h.pump(); + try testing.expectEqual(@as(u16, 6), (try h.reap()).tag); + try testing.expectEqual(@as(u16, 7), (try h.reap()).tag); + try h.quiet(); +} + +test "9p server: what is not 9P2000 on this connection is refused, not guessed" { + var h: Harness = .{}; + try h.handshake(4096); + + var buf: [64]u8 = undefined; + const good = try encode(.{ .tstat = .{ .fid = 0 } }, 5, &buf); + + // An R-message: a client on the wrong end of the connection, or the + // double-role link docs/9p.typ §7 says not to build. + var raw: [64]u8 = undefined; + @memcpy(raw[0..good.len], good); + raw[4] = @intFromEnum(Type.rstat); + try testing.expectEqual(good.len, h.srv.push(raw[0..good.len])); + h.pump(); + var got = try h.reap(); + try testing.expectEqual(@as(u16, 5), got.tag); + try testing.expectEqualStrings(e_botch, got.msg.rerror.ename); + + // A type byte no dialect we serve defines — 8 is 9P2000.L's `Tstatfs` — + // still gets an answer, because the tag is at a fixed offset and a client + // that gets no reply hangs. + @memcpy(raw[0..good.len], good); + raw[4] = 8; + _ = h.srv.push(raw[0..good.len]); + h.pump(); + got = try h.reap(); + try testing.expectEqual(@as(u16, 5), got.tag); + try testing.expectEqualStrings(e_botch, got.msg.rerror.ename); + + // A `size` no encoder could have produced is not a message to answer: the + // stream is not 9P and there is no resynchronising from it. + @memcpy(raw[0..good.len], good); + std.mem.writeInt(u32, raw[0..4], 3, .little); + _ = h.srv.push(raw[0..good.len]); + h.pump(); + try h.quiet(); + try testing.expect(h.srv.dead); +} + +test "9p server: a connection that drops still pays the core its releases" { + var h: Harness = .{}; + try h.handshake(4096); + _ = try h.walkTo(5, 1, &.{ "1", "event" }); + _ = try h.walkTo(6, 2, &.{ "1", "body" }); + for ([_]u32{ 1, 2 }, 7..) |fid, tag| { + try h.send(@intCast(tag), .{ .topen = .{ .fid = fid, .mode = oread } }); + _ = try h.reap(); + } + // One blocked reader, so there is a parked request to abandon as well. + try h.send(9, .{ .tread = .{ .fid = 1, .offset = 0, .count = 4096 } }); + try h.quiet(); + + // The socket died. Every open fid still owes the core a release, and that + // debt outlives the connection — losing it leaves the editor reporting + // button actions to a script that is gone. + h.srv.hangup(); + h.pump(); + try testing.expectEqual(@as(u32, 2), h.fsys.releases); + // ...and nothing is written to a socket that has gone. + try h.quiet(); + + // `Tversion` is the same reset on a live connection: fids clunked, + // outstanding I/O abandoned, releases still paid (version(5)). + var g: Harness = .{}; + try g.handshake(4096); + _ = try g.walkTo(5, 1, &.{ "1", "event" }); + try g.send(6, .{ .topen = .{ .fid = 1, .mode = oread } }); + _ = try g.reap(); + try g.send(7, .{ .tread = .{ .fid = 1, .offset = 0, .count = 4096 } }); + try g.quiet(); + try g.send(notag, .{ .tversion = .{ .msize = 4096, .version = "9P2000" } }); + const v = try g.reap(); + try testing.expectEqualStrings("9P2000", v.msg.rversion.version); + try testing.expectEqual(@as(u32, 1), g.fsys.releases); + // The abandoned read is never answered, and the fid is gone. + g.fsys.event = "Kli7 7 0 0 hello\n"; + g.pump(); + try g.quiet(); + try g.send(8, .{ .tstat = .{ .fid = 1 } }); + const got = try g.reap(); + try testing.expectEqualStrings(e_unknown_fid, got.msg.rerror.ename); +} + +test "9p server: every errno the core can answer is a string Linux knows" { + // The nine values `acmefs.E` defines, spelled exactly as + // `linux/net/9p/error.c:41-171` holds them. A typo in any of these is + // "Unknown error 526" on every `mount -t 9p`, which is why they are + // asserted as literals rather than derived from anything. + try testing.expectEqualStrings("Operation not permitted", errString(1)); + try testing.expectEqualStrings("No such file or directory", errString(2)); + try testing.expectEqualStrings("Input/output error", errString(5)); + try testing.expectEqualStrings("Cannot allocate memory", errString(12)); + try testing.expectEqualStrings("Not a directory", errString(20)); + try testing.expectEqualStrings("Invalid argument", errString(22)); + try testing.expectEqualStrings("Too many open files in system", errString(23)); + try testing.expectEqualStrings("No space left on device", errString(28)); + try testing.expectEqualStrings("Function not implemented", errString(38)); + // A number this file never emits is EIO, not a table miss. + try testing.expectEqualStrings("Input/output error", errString(0)); + try testing.expectEqualStrings("Input/output error", errString(999)); + + // The server's own strings, from the same table and the fossil/u9fs half + // of it. Every one of these is a line in `error.c`, which is the whole + // difference between an errno and 526. + try testing.expectEqualStrings("fid unknown or out of range", e_unknown_fid); + try testing.expectEqualStrings("fid already in use", e_fid_in_use); + try testing.expectEqualStrings("bad use of fid", e_bad_use); + try testing.expectEqualStrings("bad offset in directory read", e_bad_offset); + try testing.expectEqualStrings("permission denied", e_perm); + try testing.expectEqualStrings("not a directory", e_not_dir); + try testing.expectEqualStrings("file already open for I/O", e_already_open); + try testing.expectEqualStrings("illegal name", e_illegal_name); + try testing.expectEqualStrings("Too many open files in system", e_too_many_fids); + try testing.expectEqualStrings("protocol botch", e_botch); + try testing.expectEqualStrings("Interrupted system call", e_interrupted); + try testing.expectEqualStrings("only support truncation to zero length", e_trunc_only); + try testing.expectEqualStrings("wstat prohibited", e_wstat); + try testing.expectEqualStrings("Resource temporarily unavailable", e_again); + // Every one of them fits the buffer a Plan 9 client has for it. + for ([_][]const u8{ + e_unknown_fid, e_fid_in_use, e_bad_use, e_bad_offset, e_perm, + e_not_dir, e_already_open, e_botch, e_interrupted, e_trunc_only, + e_wstat, e_again, e_no_tree, e_no_auth, e_count_small, + e_illegal_name, e_too_many_fids, e_small_msize, + }) |s| try testing.expect(s.len <= errmax); +} + +test "9p server: the fid table and the park table are what the board was costed for" { + // `docs/registry.typ` `9P-11` costed a fid table at 32 x 16 bytes. The + // real entry is larger, and the difference is not a mistake in either + // place: it is the entry NAME, which `Rstat` carries and a node id does + // not, plus the open handle and the two-coordinate directory cursor. The + // numbers are asserted here so that a change to `Fid` shows up as a diff + // in the board's budget rather than as a surprise on the board. + const S = Server(StubFs); + const fids = @sizeOf(S.Fid) * max_fids; + const slots = @sizeOf(S.Slot) * max_slots; + try testing.expect(fids <= 3 * 1024); + try testing.expect(slots <= 8 * 1024); + // Two buffers at a 4,096-byte msize — `in` and `out`'s two — plus the two + // tables, against 336 KB of free heap on the P4. + try testing.expect(3 * 4096 + fids + slots <= 24 * 1024); +} |