tiny.game.transport

1pub const transport = @import("transport.zig");

1//! Two servers carry lines holding one command each from an outside tool to a host, over standard2//! input or a Unix socket, and carry each reply back. A tool or test drives a headless game by3//! writing one command per line and reading the reply to each. A tool either starts the host and4//! talks to it over the host's standard input, or connects to a host that is already running.5//!6//! A socket hands over bytes in pieces of any size, so a line can arrive split across reads, and7//! one read can carry more than one line. A host answers many commands in one session, and it wants8//! to reuse its memory from one command to the next.9//!10//! The caller supplies the object that answers each line (a *control object*): its `applyLine`11//! takes an arena, the line and a writer, writes the reply to the writer, and returns false to stop12//! serving. Both servers trim spaces, tabs and carriage returns from each line, skip a line left13//! empty, and stop when the control object returns false. The arena is reset before each line and14//! keeps its memory, so memory from one command serves the next.15//!16//! `serveStdio` reads lines from standard input and hands the control object a buffered writer to17//! standard output. `serveStdio` never flushes that writer, so the control object flushes each18//! reply itself. `serveSocket` listens on a Unix socket at a path the caller gives, prints a JSON19//! `listening` event with the path on standard output, and serves one connection at a time. A line20//! holds at most 1 MiB (`line_capacity`). When a line and its newline together pass 1 MiB, or a21//! read fails, `serveStdio` ends as if the input had ended. `serveSocket` returns22//! `error.LineCapacityExceeded` when the bytes it holds and one read together pass 1 MiB, so a line23//! under 1 MiB can end it. That error, `error.OutOfMemory` from growing the held bytes, an error24//! from the control object, or a failed accept returns from `serveSocket` and ends service for25//! every later client.26const std = @import("std");27const pretty_json = @import("pretty").json;28const sys = @import("sys");2930/// The most bytes one line may hold, 1 MiB. Both servers bound a line with it: `serveStdio` sizes31/// its read buffer to it, and `LineBuffer.feed` refuses bytes past it. On standard input, a line32/// and its newline together fit in it.33pub const line_capacity = 1024 * 1024;3435/// An arena that a control object gets for each line, reset before the next line. `serveStdio`36/// keeps one for the whole session, and `CommandWorkspace` holds one, so memory from one command37/// serves the next. A reset keeps the memory the arena grew to.38pub const CommandScratch = struct {39    arena: std.heap.ArenaAllocator,4041    /// Returns a scratch whose arena draws memory from `allocator`. A server builds one before it42    /// reads its first line.43    pub fn init(allocator: std.mem.Allocator) CommandScratch {44        return .{ .arena = .init(allocator) };45    }4647    /// Frees the arena's memory and leaves the scratch undefined. A server calls it when it stops48    /// serving.49    pub fn deinit(self: *CommandScratch) void {50        self.arena.deinit();51        self.* = undefined;52    }5354    /// Resets the arena and passes it, `line` and `out` to `control.applyLine`, returning that55    /// call's result. A server calls it once per line, and a true result means the server keeps56    /// serving. Memory the control object took from the arena for an earlier line is invalid once57    /// the call resets it. The call returns any error that `applyLine` returns.58    pub fn apply(self: *CommandScratch, control: anytype, line: []const u8, out: *std.Io.Writer) !bool {59        _ = self.arena.reset(.retain_capacity);60        return control.applyLine(self.arena.allocator(), line, out);61    }62};6364/// A scratch arena and a growing reply buffer for one connection, which keep a control object's65/// reply in memory until the server sends it. `serveSocket` keeps one per connection and sends the66/// reply after each line, and a test compares its reply with a direct call to the control object.67/// Once a first command has grown the arena and the buffer, repeating that command allocates68/// nothing more.69pub const CommandWorkspace = struct {70    scratch: CommandScratch,71    reply: std.Io.Writer.Allocating,7273    /// Returns a workspace whose arena and reply buffer draw memory from `allocator`. `serveSocket`74    /// builds one for each connection it accepts.75    pub fn init(allocator: std.mem.Allocator) CommandWorkspace {76        return .{77            .scratch = .init(allocator),78            .reply = .init(allocator),79        };80    }8182    /// Frees the reply buffer and the arena and leaves the workspace undefined. `serveSocket` calls83    /// it when a connection ends.84    pub fn deinit(self: *CommandWorkspace) void {85        self.reply.deinit();86        self.scratch.deinit();87        self.* = undefined;88    }8990    /// Clears the reply buffer, then hands the control object the reset arena, the line and a91    /// writer into the buffer. `serveSocket` calls it once per line and then sends `written` to the92    /// client. The call returns the control object's result, true to keep serving, and any error93    /// the control object returns. A failed allocation for the reply reaches the caller as94    /// `error.WriteFailed`, and a later call can succeed.95    pub fn apply(self: *CommandWorkspace, control: anytype, line: []const u8) !bool {96        self.reply.clearRetainingCapacity();97        return self.scratch.apply(control, line, &self.reply.writer);98    }99100    /// Returns the reply that the last `apply` wrote. `serveSocket` sends these bytes to the client101    /// after each line. The slice stays valid until the next `apply` or `deinit`.102    pub fn written(self: *CommandWorkspace) []const u8 {103        return self.reply.written();104    }105};106107/// Bytes read from a connection and held until they are consumed, from which whole lines are taken108/// in order. `serveSocket` feeds it each read, because a read can end inside a line or carry more109/// than one line. The buffer holds at most `line_capacity` bytes.110pub const LineBuffer = struct {111    allocator: std.mem.Allocator,112    pending: std.ArrayListUnmanaged(u8) = .empty,113114    /// Returns an empty buffer that grows with `allocator`. `serveSocket` builds one for each115    /// connection.116    pub fn init(allocator: std.mem.Allocator) LineBuffer {117        return .{ .allocator = allocator };118    }119120    /// Frees the held bytes and leaves the buffer undefined. `serveSocket` calls it when a121    /// connection ends. The bytes of a line that never received its newline are dropped.122    pub fn deinit(self: *LineBuffer) void {123        self.pending.deinit(self.allocator);124        self.* = undefined;125    }126127    /// Appends `bytes` to the held bytes. `serveSocket` feeds it each read from the connection. The128    /// call returns `error.LineCapacityExceeded` when the held bytes and `bytes` together pass129    /// `line_capacity`, and `error.OutOfMemory` when growing the buffer runs out of memory. The130    /// bound counts every held byte, so a read that finishes one line and starts later ones can131    /// pass it while each line is under 1 MiB.132    pub fn feed(self: *LineBuffer, bytes: []const u8) !void {133        std.debug.assert(self.pending.items.len <= line_capacity);134        if (bytes.len > line_capacity - self.pending.items.len) return error.LineCapacityExceeded;135        try self.pending.appendSlice(self.allocator, bytes);136    }137138    /// Returns the first whole line, trimmed of spaces, tabs and carriage returns, or `null` when139    /// the held bytes hold no newline. `serveSocket` takes lines with it until it returns `null`.140    /// The call leaves the line held, and a caller calls `consume` to move past it. The line points141    /// into the buffer and stays valid until the next `feed` or `consume`. A blank line comes back142    /// empty.143    pub fn next(self: *LineBuffer) ?[]const u8 {144        const newline = std.mem.indexOfScalar(u8, self.pending.items, '\n') orelse return null;145        const line = self.pending.items[0..newline];146        const trimmed = std.mem.trim(u8, line, " \t\r");147        return trimmed;148    }149150    /// Drops the first line and its newline, and moves the bytes after it to the front.151    /// `serveSocket` calls it after it handles each line from `next`. The call leaves the buffer as152    /// it was when no newline is held. The call copies every byte after the line.153    pub fn consume(self: *LineBuffer) void {154        const newline = std.mem.indexOfScalar(u8, self.pending.items, '\n') orelse return;155        const consumed = newline + 1;156        std.mem.copyForwards(u8, self.pending.items, self.pending.items[consumed..]);157        self.pending.shrinkRetainingCapacity(self.pending.items.len - consumed);158    }159};160161/// Reads lines from standard input and hands each one to `control` until the control object returns162/// false or the input ends. A host that a tool starts serves the tool's commands over its standard163/// input and output. The control object gets a buffered writer to standard output for its reply.164/// The call never flushes that writer, so the control object flushes each reply, and bytes it165/// leaves unflushed are lost when the call returns. Each line is trimmed of spaces, tabs and166/// carriage returns, and a line left empty is skipped. A last line without a newline is still167/// served. When a line and its newline together pass 1 MiB, or a read fails, the call ends as if168/// the input had ended and returns normally. The call returns any error the control object returns.169/// The call keeps a 1 MiB read buffer and a 64 KiB write buffer on its stack, and it allocates from170/// `allocator` for the arena alone.171pub fn serveStdio(allocator: std.mem.Allocator, control: anytype) !void {172    var read_buffer: [line_capacity]u8 = undefined;173    var reader = sys.stdio.stdin().reader(sys.stdio.debugIo(), &read_buffer);174    var write_buffer: [64 * 1024]u8 = undefined;175    var writer = sys.stdio.stdout().writer(sys.stdio.debugIo(), &write_buffer);176    var scratch = CommandScratch.init(allocator);177    defer scratch.deinit();178179    while (true) {180        const line = reader.interface.takeDelimiter('\n') catch break orelse break;181        const trimmed = std.mem.trim(u8, line, " \t\r");182        if (trimmed.len == 0) continue;183184        const proceed = try scratch.apply(control, trimmed, &writer.interface);185        if (!proceed) break;186    }187}188189/// Serves lines to `control` on a Unix socket at `path`, one connection at a time, until the190/// control object returns false. A host that a tool connects to while it runs serves the tool's191/// commands on a socket path. The call deletes any file at `path` before it listens, and deletes192/// the socket file again when it returns. Once it listens, the call prints one JSON line with an193/// `event` of `listening` and the path in `socket` on standard output. For each connection the call194/// keeps a `LineBuffer` and a `CommandWorkspace`, and after each nonempty line it writes the195/// control object's reply to the connection. A read error, the client closing, or a failed write196/// ends that connection, and the call accepts the next one. A partial line held when the client197/// closes is dropped. `error.LineCapacityExceeded` or `error.OutOfMemory` from the held bytes, an198/// error from the control object, or a failed accept returns from the call and ends service for199/// every later client.200pub fn serveSocket(allocator: std.mem.Allocator, control: anytype, path: []const u8) !void {201    sys.fs.deleteFile(path) catch {};202    const address = try sys.net.Address.initUnix(path);203    var server = try sys.net.Address.listen(address, .{});204    defer server.deinit();205    defer sys.fs.deleteFile(path) catch {};206207    try announceSocket(path);208209    accepting: while (true) {210        var accepted = try server.accept();211        defer accepted.stream.close();212213        var lines = LineBuffer.init(allocator);214        defer lines.deinit();215        var workspace = CommandWorkspace.init(allocator);216        defer workspace.deinit();217        var chunk: [16 * 1024]u8 = undefined;218219        reading: while (true) {220            const read = accepted.stream.read(&chunk) catch break :reading;221            if (read == 0) break :reading;222            try lines.feed(chunk[0..read]);223224            while (lines.next()) |line| {225                var proceed = true;226                if (line.len > 0) {227                    proceed = try workspace.apply(control, line);228                    accepted.stream.writeAll(workspace.written()) catch {229                        lines.consume();230                        break :reading;231                    };232                }233                lines.consume();234                if (!proceed) break :accepting;235            }236        }237    }238}239240fn announceSocket(path: []const u8) !void {241    var stdout_buffer: [4096]u8 = undefined;242    var writer = sys.stdio.stdout().writer(sys.stdio.debugIo(), &stdout_buffer);243    var json = pretty_json.Writer.init(&writer.interface, .minified);244    const root = try json.object();245    try root.field("event", "listening");246    try root.field("socket", path);247    try root.endLine();248    try writer.interface.flush();249}250251test "line buffer frames chunked input into trimmed lines" {252    var lines = LineBuffer.init(std.testing.allocator);253    defer lines.deinit();254255    try lines.feed("{\"cmd\":\"sta");256    try std.testing.expect(lines.next() == null);257    try lines.feed("tus\"}\r\n{\"cmd\":\"quit\"}\n");258259    const first = lines.next().?;260    try std.testing.expectEqualStrings("{\"cmd\":\"status\"}", first);261    lines.consume();262263    const second = lines.next().?;264    try std.testing.expectEqualStrings("{\"cmd\":\"quit\"}", second);265    lines.consume();266267    try std.testing.expect(lines.next() == null);268}