//! Interactive server lifecycle (M1-UI-001 .. M1-UI-004). //! //! M1-UI-001 asks for something unusual: when the requested endpoint is //! unavailable, startup must *fail* rather than pick another port. That is why //! nothing here retries -- a tool that quietly moved to port 8081 would leave //! the user looking at the wrong page. It is also why reuse_address stays off: //! Zig's option sets SO_REUSEPORT as well as SO_REUSEADDR, and SO_REUSEPORT //! would let a second server bind the same endpoint alongside this one. //! //! M1-UI-002 is satisfied by omission as much as by the line it prints: //! nothing in this module spawns a process, so no browser can be opened. //! //! M1-UI-003 likewise. No credential is read, because a loopback tool for one //! user needs none, and securing a non-loopback endpoint is the user's //! business. //! //! M1-UI-004 asks for SIGINT and SIGTERM to be the way the server stops, and //! that much the default disposition already did. What it did badly was give //! the port back: the kernel's close of the connection still open at that //! moment sends our FIN first, and the socket then owns the listen endpoint //! through FIN_WAIT_2 and TIME_WAIT for another minute, so an immediate //! restart fails. The handler below resets that one connection instead, which //! frees the endpoint at once. There is deliberately no browser control for //! stopping the server. const std = @import("std"); const net = std.Io.net; const posix = std.posix; const Completion = @import("../expr/Completion.zig"); const diag = @import("../diag.zig"); const Editor = @import("Editor.zig"); const Session = @import("Session.zig"); const state = @import("state.zig"); const Manifest = @import("../config/Manifest.zig"); const logging = @import("../log.zig"); const Stamp = logging.Stamp; const Stopwatch = @import("../util/time.zig").Stopwatch; const log = std.log.scoped(.server); pub const Error = error{ EndpointUnavailable, OutOfMemory }; pub const Endpoint = struct { host: []const u8, port: u16, pub const default: Endpoint = .{ .host = "127.0.0.1", .port = 8080 }; /// HOST:PORT, both required. Returns null rather than guessing. pub fn parse(text: []const u8) error{EndpointParseError}!Endpoint { const colon = std.mem.findScalarLast(u8, text, ':') orelse return error.EndpointParseError; const host = text[0..colon]; const port_text = text[colon + 1 ..]; if (host.len == 0 or port_text.len == 0) return error.EndpointParseError; // One colon only: HOST:PORT is the whole grammar. if (std.mem.findScalar(u8, host, ':') != null) return error.EndpointParseError; const port = std.fmt.parseInt(u16, port_text, 10) catch return error.EndpointParseError; return .{ .host = host, .port = port }; } /// HOST:PORT, the spelling `parse` accepts back. pub fn format(self: Endpoint, writer: *std.Io.Writer) std.Io.Writer.Error!void { try writer.print("{s}:{}", .{ self.host, self.port }); } /// The browsable address (M1-UI-002). A second rendering, and not the /// canonical one, so it is a named formatter rather than a second method /// that returns bytes (STYLE.md section 4). pub const Url = struct { endpoint: Endpoint, pub fn format(self: Url, writer: *std.Io.Writer) std.Io.Writer.Error!void { try writer.print("http://{s}:{d}/", .{ self.endpoint.host, self.endpoint.port }); } }; pub fn url(self: Endpoint) Url { return .{ .endpoint = self }; } }; /// Binds the endpoint, or fails. Never falls back to another port. pub fn listen(io: std.Io, endpoint: Endpoint) Error!net.Server { const address = net.IpAddress.parse(endpoint.host, endpoint.port) catch return error.EndpointUnavailable; // reuse_address stays off deliberately: it would also set SO_REUSEPORT, // which lets a second server share the endpoint (M1-UI-001). return address.listen(io, .{}) catch error.EndpointUnavailable; } pub const Response = struct { body: []const u8, content_type: []const u8, status: std.http.Status, }; const index_html = @embedFile("web/index.html"); const app_css = @embedFile("web/app.css"); const rule_editor_css = @embedFile("web/rule-editor.css"); /// A file the interface is made of, and where it is served. const Asset = struct { body: []const u8, content_type: []const u8, path: []const u8, }; /// One of the interface's ES modules, served under its own name, which is how /// the others import it (D1). fn script(comptime name: []const u8) Asset { return .{ .path = "/" ++ name, .content_type = "text/javascript; charset=utf-8", .body = @embedFile("web/" ++ name), }; } const assets = [_]Asset{ .{ .path = "/", .content_type = "text/html; charset=utf-8", .body = index_html }, .{ .path = "/app.css", .content_type = "text/css; charset=utf-8", .body = app_css }, .{ .path = "/rule-editor.css", .content_type = "text/css; charset=utf-8", .body = rule_editor_css }, script("app.js"), script("rule-editor.js"), script("legend.js"), script("problems.js"), script("draft.js"), script("api.js"), script("completion.js"), script("clause.js"), script("row-actions.js"), script("rule-picker.js"), script("rule-prompt.js"), script("fuzzy.js"), script("popover.js"), script("selection.js"), script("rule.js"), script("journal.js"), script("summary.js"), script("theme.js"), }; const plain_text = "text/plain; charset=utf-8"; const json_type = "application/json; charset=utf-8"; /// Decides a response from the request line alone, so the whole routing table /// is testable without a socket. pub fn respond(method: std.http.Method, target: []const u8) Response { if (method != .GET) return .{ .status = .method_not_allowed, .content_type = plain_text, .body = "method not allowed\n", }; const path = pathOf(target); for (assets) |asset| { if (std.mem.eql(u8, path, asset.path)) { return .{ .status = .ok, .content_type = asset.content_type, .body = asset.body }; } } return .{ .status = .not_found, .content_type = plain_text, .body = "not found\n" }; } /// Serves the API when the path asks for it, the embedded assets otherwise. /// Takes the request line and body rather than a connection, so the whole /// routing table is testable without a socket. /// /// Every API response carries the same state payload, whatever the outcome. /// The status says what happened; the body says what the interface should now /// show, so there is one rendering path and no follow-up request that could /// return results for a draft that has since been replaced (M1-UI-010). pub fn route( arena: std.mem.Allocator, session: *Session, method: std.http.Method, target: []const u8, body: []const u8, ) Response { const path = pathOf(target); if (!isApi(path)) return respond(method, target); if (std.mem.eql(u8, path, "/api/state")) { if (method != .GET) return methodNotAllowed(); return stateResponse(arena, session, target, .ok); } // M1-UI-008: the only way to change rules, and it takes fields. if (std.mem.eql(u8, path, "/api/rules")) { if (method != .PUT) return methodNotAllowed(); var diags = diag.List.init(arena); const decoding: Stopwatch = .start(); const drafted = Editor.decode(arena, body, &diags) catch return outOfMemory(); if (drafted == null) return rejected(arena, session, target, diags.items.items); log.debug("decoded {d} rules in {f}", .{ drafted.?.len, decoding.elapsed() }); session.apply(drafted.?) catch return outOfMemory(); return stateResponse(arena, session, target, .ok); } // M1-UI-016: the one explicit save action. if (std.mem.eql(u8, path, "/api/save")) { if (method != .POST) return methodNotAllowed(); const saved = session.save() catch return outOfMemory(); if (saved) log.info("saved {s}", .{session.rules_file}) else log.warn("save refused, the interface says why", .{}); return stateResponse(arena, session, target, if (saved) .ok else .conflict); } // M1-UI-014: the journal as it would be, without writing it anywhere. if (std.mem.eql(u8, path, "/api/preview")) { if (method != .GET) return methodNotAllowed(); const preview = session.preview(arena) catch return outOfMemory(); const rendered = state.renderPreview(arena, preview) catch return outOfMemory(); return .{ .status = .ok, .content_type = json_type, .body = rendered }; } // M1-UI-021: the same validation, atomic creation and no-overwrite // behaviour as `convert`. if (std.mem.eql(u8, path, "/api/finalize")) { if (method != .POST) return methodNotAllowed(); const written = session.finalize(arena) catch return outOfMemory(); if (written) log.info("wrote the journal", .{}) else log.warn("finalize refused, the interface says why", .{}); return stateResponse(arena, session, target, if (written) .ok else .conflict); } // Not a requirement: the aliases that complete a field at the cursor. // Like the preview, it answers with its own payload rather than the state. if (std.mem.eql(u8, path, "/api/complete")) { if (method != .POST) return methodNotAllowed(); return completeResponse(arena, session, body); } // M1-UI-009: there is no manifest or profile route to find, at any method. return .{ .status = .not_found, .content_type = plain_text, .body = "not found\n" }; } fn stateResponse( arena: std.mem.Allocator, session: *const Session, target: []const u8, status: std.http.Status, ) Response { const rendering: Stopwatch = .start(); const query = state.parseQuery(arena, target) catch return outOfMemory(); const body = state.renderJson(arena, session.view, query) catch return outOfMemory(); log.debug("rendered {d} B in {f}", .{ body.len, rendering.elapsed() }); return .{ .status = status, .content_type = json_type, .body = body }; } /// The interface sends the condition's text up to the cursor rather than an /// offset into it, so the two sides never have to agree on how to count. fn completeResponse(arena: std.mem.Allocator, session: *const Session, body: []const u8) Response { const Request = struct { before: []const u8 }; const request = std.json.parseFromSliceLeaky(Request, arena, body, .{}) catch return .{ .status = .bad_request, .content_type = plain_text, .body = "expected {\"before\": \"...\"}\n", }; const aliases = session.view.aliases(arena) catch return outOfMemory(); const completion = Completion.init(arena, request.before, aliases) catch return outOfMemory(); const rendered = arena.print("{f}", .{std.json.fmt(completion, .{})}) catch return outOfMemory(); return .{ .status = .ok, .content_type = json_type, .body = rendered }; } /// A malformed edit changes nothing: the session still holds the draft it /// held, and the reason joins the diagnostics the interface already shows. fn rejected( arena: std.mem.Allocator, session: *Session, target: []const u8, added: []const diag.Diagnostic, ) Response { var combined: std.ArrayList(diag.Diagnostic) = .empty; combined.appendSlice(arena, session.view.diagnostics) catch return outOfMemory(); combined.appendSlice(arena, added) catch return outOfMemory(); var view = session.view; view.diagnostics = combined.items; const query = state.parseQuery(arena, target) catch return outOfMemory(); const body = state.renderJson(arena, view, query) catch return outOfMemory(); return .{ .status = .bad_request, .content_type = json_type, .body = body }; } fn methodNotAllowed() Response { return .{ .status = .method_not_allowed, .content_type = plain_text, .body = "method not allowed\n", }; } fn outOfMemory() Response { return .{ .status = .internal_server_error, .content_type = plain_text, .body = "out of memory\n" }; } fn isApi(path: []const u8) bool { return std.mem.startsWith(u8, path, "/api/"); } fn pathOf(target: []const u8) []const u8 { if (std.mem.findScalar(u8, target, '?')) |at| return target[0..at]; return target; } /// The connection `serve` is holding, or -1 when it is waiting in `accept`. /// The signal handler cannot take a lock, so this is the whole handover. var held_connection: std.atomic.Value(posix.socket_t) = .init(-1); // zlinter-disable-current-line no_global_vars /// M1-UI-004: stop on SIGINT or SIGTERM, and leave the endpoint bindable. /// /// Only the connection still open at this moment matters. Ones the browser /// already closed were closed passively by us and left nothing behind; ones /// still queued in the kernel's backlog are reset by the kernel. This one the /// kernel would close actively on our behalf, and that FIN is what keeps the /// endpoint occupied afterwards -- so it is reset instead, by lingering for /// zero seconds. /// /// Everything here is a bare syscall or formatting into a stack buffer, /// because a handler may call nothing else -- std.log included. fn onShutdownSignal(_: posix.SIG) callconv(.c) void { const held_fd = held_connection.swap(-1, .seq_cst); if (held_fd >= 0) { const reset: posix.linger = .{ .onoff = 1, .linger = 0 }; // zlinter-disable-next-line no_swallow_error - a handler returns void and may call nothing else posix.setsockopt(held_fd, posix.SOL.SOCKET, posix.SO.LINGER, std.mem.asBytes(&reset)) catch {}; _ = posix.system.close(held_fd); } var buffer: [64]u8 = undefined; var notice: std.Io.Writer = .fixed(&buffer); // zlinter-disable-next-line no_swallow_error - the buffer holds a stamp and the word with room to spare notice.print("{f}stopped\n", .{Stamp.now(.info, .server)}) catch {}; _ = posix.system.write(posix.STDOUT_FILENO, notice.buffered().ptr, notice.end); // M1-CLI-006 lists what fails; a shutdown the user asked for is not on it. std.process.exit(0); } fn armShutdownSignals() void { const action: posix.Sigaction = .{ .handler = .{ .handler = onShutdownSignal }, .mask = posix.sigemptyset(), .flags = 0, }; posix.sigaction(.INT, &action, null); posix.sigaction(.TERM, &action, null); } /// Serves until the process is signalled. One connection at a time, which is /// enough for a single user on one machine. pub fn serve( gpa: std.mem.Allocator, io: std.Io, endpoint: Endpoint, session: *Session, ) Error!void { var server = try listen(io, endpoint); defer server.deinit(io); // M1-UI-002: print the URL, open nothing. log.info("listening on {f}", .{endpoint.url()}); // Armed only once the endpoint is bound, so a startup failure still exits // the ordinary way (M1-UI-001). armShutdownSignals(); // One arena for request scratch, reset between requests so a long // session does not accumulate. var scratch = std.heap.ArenaAllocator.init(gpa); defer scratch.deinit(); var connections: u32 = 0; var requests: u32 = 0; while (true) { var stream = server.accept(io) catch |err| { log.err("accept failed: {t}", .{err}); continue; }; connections += 1; // A gap between one connection's close and the next one's accept is // time a browser's request spent queued behind it. logging.setConnection(connections); log.debug("accepted", .{}); const before = requests; held_connection.store(stream.socket.handle, .seq_cst); defer { // Whoever wins the swap owns the close, so the handler and this // path cannot both close the same descriptor. if (held_connection.swap(-1, .seq_cst) >= 0) stream.close(io); log.debug("closed after {d} requests", .{requests - before}); logging.setConnection(null); } // The reader's buffer must hold an entire request head. var read_buffer: [16 * 1024]u8 = undefined; var write_buffer: [16 * 1024]u8 = undefined; var reader = stream.reader(io, &read_buffer); var writer = stream.writer(io, &write_buffer); // One bad request must not stop the server. handle(&reader.interface, &writer.interface, &scratch, session, &requests) catch |err| { log.err("connection failed: {t}", .{err}); }; } } /// Answers the one request a connection carries. It sees only the /// connection's reader and writer, so a test can be the other end. fn handle( reader: *std.Io.Reader, writer: *std.Io.Writer, scratch: *std.heap.ArenaAllocator, session: *Session, requests: *u32, ) !void { var http: std.http.Server = .init(reader, writer); var request = http.receiveHead() catch |err| switch (err) { // A connection the browser opened ahead of need and closed unused. error.HttpConnectionClosing => return, else => return err, }; const watch: Stopwatch = .start(); _ = scratch.reset(.retain_capacity); const arena = scratch.allocator(); // Reading the body invalidates the head's strings, so the request // line is copied out first. const method = request.head.method; const target = try arena.dupe(u8, request.head.target); requests.* += 1; logging.setRequest(.{ .method = method, .number = requests.*, .path = pathOf(target) }); // Before the scratch it points into is reset for the next request. defer logging.setRequest(null); if (needsEmptyBody( method.requestHasBody(), request.head.transfer_encoding, request.head.content_length, )) { request.head.content_length = 0; } var body_buffer: [4 * 1024]u8 = undefined; const body_reader = try request.readerExpectContinue(&body_buffer); // M1-SAFE-004 sets no input limit; an edit too large to hold fails as // an allocation failure rather than being silently truncated. const body = body_reader.allocRemaining(arena, .unlimited) catch |err| body: { // Routed as if empty. The response cannot say a body was lost, // so the log does. log.err("body not read: {t}", .{err}); break :body ""; }; // Assets get only the closing line; a page load fetches twenty. if (isApi(pathOf(target))) { log.debug("start {s}, body {d} B read in {f}", .{ target, body.len, watch.elapsed() }); } const response = route(arena, session, method, target, body); try request.respond(response.body, .{ .status = response.status, // A browser keeps an idle connection open for minutes, and while // `serve` waits on it, a request sent on any other connection // waits in the backlog. Closing after each response lets the next // one in as soon as this one is answered. .keep_alive = false, .extra_headers = &.{ .{ .name = "content-type", .value = response.content_type }, }, }); log.debug("end, {d}, {d} B in {f}", .{ @backingInt(response.status), response.body.len, watch.elapsed() }); } /// True when a request whose method may carry a body did not say it has one. /// /// POST /api/save sends nothing, and `curl -X POST` with no data sends neither /// a length nor an encoding. Left alone, reading that body waits for the /// client to hang up -- which a browser holding the connection open will not /// do, and this server has only the one connection -- and responding trips an /// assertion in std's keep-alive bookkeeping. Both go away by saying what is /// true: the body is empty. fn needsEmptyBody( method_may_have_body: bool, encoding: std.http.TransferEncoding, content_length: ?u64, ) bool { return method_may_have_body and encoding == .none and content_length == null; } // -- tests ------------------------------------------------------------------- const expect = std.testing.expect; const expectEqual = std.testing.expectEqual; const expectEqualStrings = std.testing.expectEqualStrings; const expectFmt = std.testing.expectFmt; const expectError = std.testing.expectError; const test_io = std.testing.io; test "M1-UI-001: the default endpoint is loopback port 8080" { try expectEqualStrings("127.0.0.1", Endpoint.default.host); try expectEqual(@as(u16, 8080), Endpoint.default.port); } test "M1-UI-001: --listen overrides the complete endpoint" { const parsed = try Endpoint.parse("0.0.0.0:9000"); try expectEqualStrings("0.0.0.0", parsed.host); try expectEqual(@as(u16, 9000), parsed.port); const loopback = try Endpoint.parse("127.0.0.1:1"); try expectEqual(@as(u16, 1), loopback.port); } test "M1-UI-001: a malformed endpoint is refused" { for ([_][]const u8{ "", "127.0.0.1", ":8080", "127.0.0.1:", "127.0.0.1:notaport", "127.0.0.1:65536", "127.0.0.1:-1", "127.0.0.1:80:80", }) |bad| { try expect(Endpoint.parse(bad) == error.EndpointParseError); } } test "M1-UI-002: the printed URL names the endpoint" { try expectFmt("http://127.0.0.1:8080/", "{f}", .{Endpoint.default.url()}); const other = try Endpoint.parse("0.0.0.0:9000"); try expectFmt("http://0.0.0.0:9000/", "{f}", .{other.url()}); // The other rendering is the one the command line accepts back. try expectFmt("0.0.0.0:9000", "{f}", .{other}); } test "M1-AC-021: a taken endpoint fails rather than moving to another port" { // Find a port we can bind, then prove the same endpoint cannot be bound // twice. reuse_address is deliberately left off. var port: u16 = 39000; var first = while (port < 39100) : (port += 1) { break listen(test_io, .{ .host = "127.0.0.1", .port = port }) catch continue; } else return error.SkipZigTest; defer first.deinit(test_io); try std.testing.expectError( error.EndpointUnavailable, listen(test_io, .{ .host = "127.0.0.1", .port = port }), ); } test "M1-UI-002: the index is served at the root" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const response = respond(.GET, "/"); try expectEqual(std.http.Status.ok, response.status); try expectEqualStrings("text/html; charset=utf-8", response.content_type); try expect(response.body.len > 0); } test "M1-UI-002: the stylesheet and script are served" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const css = respond(.GET, "/app.css"); try expectEqual(std.http.Status.ok, css.status); try expectEqualStrings("text/css; charset=utf-8", css.content_type); const javascript = respond(.GET, "/app.js"); try expectEqual(std.http.Status.ok, javascript.status); try expectEqualStrings("text/javascript; charset=utf-8", javascript.content_type); } test "M1-UI-008: the rule editor's script and stylesheet are served" { const javascript = respond(.GET, "/rule-editor.js"); try expectEqual(std.http.Status.ok, javascript.status); try expectEqualStrings("text/javascript; charset=utf-8", javascript.content_type); const css = respond(.GET, "/rule-editor.css"); try expectEqual(std.http.Status.ok, css.status); try expectEqualStrings("text/css; charset=utf-8", css.content_type); } test "M1-PKG-006: every module the interface imports is served" { // The modules import each other as "./name.js", which the browser resolves // against the importing script's path and Deno against its file, so one // spelling serves the page and the tests alike (D1). const imports = [_][]const u8{ "import \"./", "from \"./" }; for (assets) |asset| { for (imports) |needle| { var rest = asset.body; while (std.mem.find(u8, rest, needle)) |start| { // From the "/" of "./", which is the path the server knows. const path_start = start + needle.len - 1; const path_end = std.mem.findScalarPos(u8, rest, path_start, '"') orelse return error.TestUnexpectedResult; const path = rest[path_start..path_end]; const response = respond(.GET, path); try expectEqual(std.http.Status.ok, response.status); try expectEqualStrings("text/javascript; charset=utf-8", response.content_type); rest = rest[path_end..]; } } } } test "an unknown path is not found" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const response = respond(.GET, "/elsewhere"); try expectEqual(std.http.Status.not_found, response.status); } test "a method other than GET is refused on the assets" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const response = respond(.DELETE, "/"); try expectEqual(std.http.Status.method_not_allowed, response.status); } test "M1-UI-003: nothing authenticates, and nothing needs to" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); // No credential is consulted: the same request succeeds either way, which // is what M1-UI-003 permits for a loopback tool. try expectEqual(std.http.Status.ok, respond(.GET, "/").status); } test "a query string does not change which asset is served" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); try expectEqual(std.http.Status.ok, respond(.GET, "/app.css?v=2").status); } const Fixture = struct { tmp: std.testing.TmpDir, fn init(project_yaml: []const u8, rules_yaml: []const u8) !Fixture { var fixture: Fixture = .{ .tmp = std.testing.tmpDir(.{ .iterate = true }) }; try fixture.tmp.dir.writeFile(test_io, .{ .sub_path = "project.yaml", .data = project_yaml }); try fixture.tmp.dir.writeFile(test_io, .{ .sub_path = "rules.yaml", .data = rules_yaml }); try fixture.tmp.dir.createDirPath(test_io, "data"); try fixture.tmp.dir.writeFile(test_io, .{ .sub_path = "data/x.csv", .data = "A\n1\n" }); return fixture; } fn deinit(self: *Fixture) void { self.tmp.cleanup(); } fn open(self: *Fixture, arena: std.mem.Allocator) !*Session { const diags = try diag.List.create(arena); const manifest = try Manifest.loadFromFileVerified(arena, test_io, self.tmp.dir, "project.yaml", diags); return Session.open(arena, test_io, self.tmp.dir, &manifest, diags); } }; // -- the API routes ---------------------------------------------------------- const api_manifest = @embedFile("../testdata/ui/api_manifest.yaml"); const api_rules = @embedFile("../testdata/ui/api_rules.yaml"); fn makeApiFixture() !Fixture { var fixture = try Fixture.init(api_manifest, api_rules); try fixture.tmp.dir.createDirPath(test_io, "data"); try fixture.tmp.dir.writeFile(test_io, .{ .sub_path = "data/x.csv", .data = "A\n1\n" }); return fixture; } test "M1-UI-010: an edit and its results arrive in one exchange" { var fixture = try makeApiFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); const body = "{\"rules\":[{\"name\":\"r\",\"match\":\"a == \\\"nope\\\"\",\"targetAccount\":\"e:f\"}]}"; const response = route(alloc, session, .PUT, "/api/rules", body); // The response carries the results for the draft it was sent, so the // interface never has to ask a second time and never shows results for a // draft that has been replaced. try expectEqual(std.http.Status.ok, response.status); try expect(std.mem.find(u8, response.body, "\"status\":\"zero\"") != null); try expect(std.mem.find(u8, response.body, "\"dirty\":true") != null); try expect(std.mem.find(u8, response.body, "a == \\\"nope\\\"") != null); } test "M1-UI-005: an edit's results are filtered as the edit asked" { var fixture = try makeApiFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); // The draft leaves the fixture's one row unmatched. The interface shows // what an edit returns in place of what it showed before, so an // unfiltered answer would undo the filter the rows were shown under. const body = "{\"rules\":[{\"name\":\"r\",\"match\":\"a == \\\"nope\\\"\",\"targetAccount\":\"e:f\"}]}"; const hidden = route(alloc, session, .PUT, "/api/rules?status=one", body); try expect(std.mem.find(u8, hidden.body, "\"shown_rows\":0") != null); const shown = route(alloc, session, .PUT, "/api/rules?status=zero", body); try expect(std.mem.find(u8, shown.body, "\"shown_rows\":1") != null); } test "M1-UI-005: a refused edit's results are filtered as the edit asked" { var fixture = try makeApiFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); const response = route(alloc, session, .PUT, "/api/rules?status=", api_rules); try expectEqual(std.http.Status.bad_request, response.status); try expect(std.mem.find(u8, response.body, "\"shown_rows\":0") != null); } test "M1-UI-008: an edit of raw YAML is refused" { var fixture = try makeApiFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); const response = route(alloc, session, .PUT, "/api/rules", api_rules); try expectEqual(std.http.Status.bad_request, response.status); // And the draft is untouched by the attempt. try expect(!session.view.dirty); } test "M1-UI-009: nothing routes to the manifest or the profile" { var fixture = try makeApiFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); // M1-UI-009 is kept by there being no such route, at any method. for ([_][]const u8{ "/api/manifest", "/api/profile", "/api/project" }) |path| { for ([_]std.http.Method{ .GET, .PUT, .POST }) |method| { try expectEqual(std.http.Status.not_found, route(alloc, session, method, path, "").status); } } } test "M1-UI-010: the state endpoint is read-only" { var fixture = try makeApiFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); try expectEqual( std.http.Status.method_not_allowed, route(alloc, session, .PUT, "/api/state", "{}").status, ); try expectEqual( std.http.Status.method_not_allowed, route(alloc, session, .GET, "/api/rules", "").status, ); try expectEqual( std.http.Status.method_not_allowed, route(alloc, session, .GET, "/api/save", "").status, ); } test "M1-UI-016: saving a valid draft writes it and clears the dirty state" { var fixture = try makeApiFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); const body = "{\"rules\":[{\"name\":\"r\",\"match\":\"a == \\\"1\\\"\",\"targetAccount\":\"e:new\"}]}"; _ = route(alloc, session, .PUT, "/api/rules", body); const response = route(alloc, session, .POST, "/api/save", ""); try expectEqual(std.http.Status.ok, response.status); try expect(std.mem.find(u8, response.body, "\"dirty\":false") != null); const written = try fixture.tmp.dir.readFileAlloc(test_io, "rules.yaml", alloc, .unlimited); try expect(std.mem.find(u8, written, "e:new") != null); } test "M1-UI-016: saving an invalid draft is refused and says why" { var fixture = try makeApiFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); _ = route(alloc, session, .PUT, "/api/rules", "{\"rules\":[{\"name\":\"r\",\"match\":\"a ==\",\"targetAccount\":\"e:f\"}]}"); const response = route(alloc, session, .POST, "/api/save", ""); try expectEqual(std.http.Status.conflict, response.status); try expect(std.mem.find(u8, response.body, "\"savable\":false") != null); try expect(std.mem.find(u8, response.body, "diagnostics") != null); // The file is as it was. const written = try fixture.tmp.dir.readFileAlloc(test_io, "rules.yaml", alloc, .unlimited); try expectEqualStrings(api_rules, written); } test "M1-UI-019: saving an empty draft is refused" { var fixture = try makeApiFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); _ = route(alloc, session, .PUT, "/api/rules", "{\"rules\":[]}"); try expectEqual( std.http.Status.conflict, route(alloc, session, .POST, "/api/save", "").status, ); } test "M1-UI-015: the state carries the draft, its dirtiness and whether it can be saved" { var fixture = try makeApiFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); const response = route(alloc, session, .GET, "/api/state", ""); try expect(std.mem.find(u8, response.body, "\"dirty\":false") != null); try expect(std.mem.find(u8, response.body, "\"savable\":true") != null); try expect(std.mem.find(u8, response.body, "\"targetAccount\":\"e:f\"") != null); } test "M1-UI-016: a save that announces no body is treated as sending none" { // curl -X POST with no data sends neither a length nor an encoding. try expect(needsEmptyBody(true, .none, null)); // Anything that did say what it is sending is left exactly as it is. try expect(!needsEmptyBody(true, .none, 0)); try expect(!needsEmptyBody(true, .none, 42)); try expect(!needsEmptyBody(true, .chunked, null)); // And a GET has no body to say anything about. try expect(!needsEmptyBody(false, .none, null)); } test "M1-UI-002: a connection carries one request and then closes" { var fixture = try makeApiFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const session = try fixture.open(arena.allocator()); // A browser that keeps this connection open would otherwise hold back // every request it sends on another one (DESIGN_M1.md ยง6). var reader: std.Io.Reader = .fixed("GET / HTTP/1.1\r\n\r\nGET /app.js HTTP/1.1\r\n\r\n"); var writer: std.Io.Writer.Allocating = .init(arena.allocator()); var scratch = std.heap.ArenaAllocator.init(std.testing.allocator); defer scratch.deinit(); var requests: u32 = 0; try handle(&reader, &writer.writer, &scratch, session, &requests); try expectEqual(@as(u32, 1), requests); try expect(std.mem.find(u8, writer.written(), "connection: close\r\n") != null); } // -- preview and finalization ------------------------------------------------ fn makePreviewFixture() !Fixture { const manifest_text = @embedFile("../testdata/ui/manifest_text.yaml"); const rules_text = @embedFile("../testdata/ui/rules_text.yaml"); const fixture = try Fixture.init(manifest_text, rules_text); const dir = fixture.tmp.dir; try dir.createDirPath(test_io, "data"); try dir.writeFile(test_io, .{ .sub_path = "data/x.csv", .data = "Datum,Betrag,Text\n2026-09-11,-1.50,markt\n", }); return fixture; } test "M1-UI-014: the preview endpoint returns the whole journal" { var fixture = try makePreviewFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); const response = route(alloc, session, .GET, "/api/preview", ""); try expectEqual(std.http.Status.ok, response.status); try expect(std.mem.find(u8, response.body, "2026-09-11 markt") != null); // Nothing was saved or edited, so the rules on disk are the candidate. try expect(std.mem.find(u8, response.body, "\"final\":true") != null); } test "M1-UI-014: an unpreviewable state says why instead of showing part of one" { var fixture = try makePreviewFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); _ = route(alloc, session, .PUT, "/api/rules", "{\"rules\":[{\"name\":\"r\",\"match\":\"text == \\\"absent\\\"\",\"targetAccount\":\"e:f\"}]}"); const response = route(alloc, session, .GET, "/api/preview", ""); try expectEqual(std.http.Status.ok, response.status); try expect(std.mem.find(u8, response.body, "\"journal\":null") != null); try expect(std.mem.find(u8, response.body, "\"final\":false") != null); // The reasons come with it, not just the key. try expect(std.mem.find(u8, response.body, "\"diagnostics\":[]") == null); try expect(std.mem.find(u8, response.body, "\"message\":") != null); } test "M1-UI-014: a preview is marked non-final while the draft is unsaved" { var fixture = try makePreviewFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); _ = route(alloc, session, .PUT, "/api/rules", "{\"rules\":[{\"name\":\"markt\",\"match\":\"text == \\\"markt\\\"\",\"targetAccount\":\"expenses:other\"}]}"); const response = route(alloc, session, .GET, "/api/preview", ""); // The journal is complete, and it is still not what writing would produce. try expect(std.mem.find(u8, response.body, "2026-09-11 markt") != null); try expect(std.mem.find(u8, response.body, "\"final\":false") != null); } test "M1-AC-009: finalizing is refused until the edit is saved" { var fixture = try makePreviewFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); _ = route(alloc, session, .PUT, "/api/rules", "{\"rules\":[{\"name\":\"markt\",\"match\":\"text == \\\"markt\\\"\",\"targetAccount\":\"expenses:other\"}]}"); try expectEqual( std.http.Status.conflict, route(alloc, session, .POST, "/api/finalize", "").status, ); try expectError(error.FileNotFound, fixture.tmp.dir.access(test_io, "data/x.csv.journal", .{})); try expectEqual(std.http.Status.ok, route(alloc, session, .POST, "/api/save", "").status); try expectEqual(std.http.Status.ok, route(alloc, session, .POST, "/api/finalize", "").status); try fixture.tmp.dir.access(test_io, "data/x.csv.journal", .{}); } test "M1-UI-021: finalizing twice refuses the second time" { var fixture = try makePreviewFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); try expectEqual(std.http.Status.ok, route(alloc, session, .POST, "/api/finalize", "").status); const again = route(alloc, session, .POST, "/api/finalize", ""); try expectEqual(std.http.Status.conflict, again.status); try expect(std.mem.find(u8, again.body, "never overwritten") != null); } test "M1-UI-014: previewing and finalizing accept only their own method" { var fixture = try makePreviewFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); try expectEqual( std.http.Status.method_not_allowed, route(alloc, session, .POST, "/api/preview", "").status, ); try expectEqual( std.http.Status.method_not_allowed, route(alloc, session, .GET, "/api/finalize", "").status, ); } test "M1-UI-022: expressions are a text field, not a guided builder" { // A4: M1-UI-022 says a builder is not required, and there is none. The // condition is a textarea inside the per-rule controls, which is what // M1-UI-008 asks for and all it asks for. rule.js declares the condition // multiline, and rule-editor.js draws a multiline field as a textarea. const rule_js = @embedFile("web/rule.js"); const rule_editor_js = @embedFile("web/rule-editor.js"); try expect(std.mem.find(u8, rule_js, "\"matches when\", multiline: true") != null); try expect(std.mem.find(u8, rule_editor_js, "multiline ? \"textarea\"") != null); // Nothing here builds an expression out of pickers. for ([_][]const u8{ rule_editor_js, rule_js }) |source| { for ([_][]const u8{ "operator", "builder", "condition-picker", "addClause" }) |absent| { try expect(std.mem.find(u8, source, absent) == null); } } } // -- completing a field in a condition --------------------------------------- test "completion answers from the profile's aliases" { var fixture = try makeApiFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); const response = route(alloc, session, .POST, "/api/complete", "{\"before\":\"not \"}"); try expectEqual(std.http.Status.ok, response.status); try expectEqualStrings("{\"candidates\":[\"a\"],\"insert\":\"a\"}", response.body); } test "completion accepts only POST" { var fixture = try makeApiFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); try expectEqual( std.http.Status.method_not_allowed, route(alloc, session, .GET, "/api/complete", "").status, ); } test "completion refuses a body that does not say what precedes the cursor" { var fixture = try makeApiFixture(); defer fixture.deinit(); var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const session = try fixture.open(alloc); try expectEqual( std.http.Status.bad_request, route(alloc, session, .POST, "/api/complete", "{\"rules\":[]}").status, ); }