milestone 19: hygiene sweep - dead ecs surface, single-source constants, tls classification, frontend state hazards, docker smoke network fix

tools/gen_web_assets.zig

@@ -4,7 +4,9 @@
 //! writes into `<out-dir>`:
 //!
 //! - `<name>.gz` next to each asset worth compressing, unless the dist already
-//!   ships one (a Vite plugin may pre-compress). Compression happens here, at
+//!   ships one (a Vite plugin may pre-compress), in which case the shipped
+//!   sibling is decompressed and byte-compared against its base file, and a
+//!   `.gz` with no base file at all is rejected. Compression happens here, at
 //!   build time, because `flate.Compress` needs a 64 KiB window per stream —
 //!   a cost the server must not pay per request for immutable content.
 //! - `assets.zig`, the module index the server embeds: one entry per servable
@@ -53,7 +55,12 @@ pub fn main(init: std.process.Init) !void {
 
     var assets: std.ArrayList(Asset) = .empty;
     for (names) |name| {
-        if (std.mem.endsWith(u8, name, ".gz") and contains(names, name[0 .. name.len - 3])) {
+        if (std.mem.endsWith(u8, name, ".gz")) {
+            if (!contains(names, name[0 .. name.len - 3])) {
+                // The server only ever reaches a `.gz` through its base file's
+                // entry, so an orphan is unservable bytes in the binary.
+                std.process.fatal("'{s}' has no base file; nothing can serve it", .{name});
+            }
             // A pre-compressed sibling; indexed alongside its base file below.
             continue;
         }
@@ -69,12 +76,13 @@ pub fn main(init: std.process.Init) !void {
         });
 
         const sibling = try std.fmt.allocPrint(arena, "{s}.gz", .{name});
-        const gz = if (contains(names, sibling))
-            dist.readFileAlloc(io, sibling, arena, .limited(max_asset_bytes)) catch |err| {
+        const gz = if (contains(names, sibling)) shipped: {
+            const shipped = dist.readFileAlloc(io, sibling, arena, .limited(max_asset_bytes)) catch |err| {
                 std.process.fatal("cannot read '{s}': {t}", .{ sibling, err });
-            }
-        else
-            try compressWorthwhile(arena, io, out, sibling, bytes) orelse continue;
+            };
+            try verifyShipped(arena, sibling, shipped, bytes);
+            break :shipped shipped;
+        } else try compressWorthwhile(arena, io, out, sibling, bytes) orelse continue;
 
         try assets.append(arena, .{
             .path = try std.fmt.allocPrint(arena, "/{s}", .{sibling}),
@@ -116,6 +124,30 @@ fn contains(sorted: []const []const u8, name: []const u8) bool {
     return false;
 }
 
+/// Fatal unless `gz` decompresses to exactly `base`.
+///
+/// The server answers a compressed request with the sibling's bytes under the
+/// *base* file's identity, so a sibling the dist shipped from a stale or
+/// truncated build would hand every client the wrong content behind a correct
+/// ETag. Nothing downstream can catch that: gzip carries a CRC of whatever it
+/// was compressed from, not of what it was supposed to be.
+fn verifyShipped(arena: Allocator, sub_path: []const u8, gz: []const u8, base: []const u8) !void {
+    var input: std.Io.Reader = .fixed(gz);
+    const window = try arena.alloc(u8, std.compress.flate.max_window_len);
+    var decompress: std.compress.flate.Decompress = .init(&input, .gzip, window);
+    const plain = decompress.reader.allocRemaining(arena, .limited(max_asset_bytes)) catch |err| {
+        // `Reader` collapses every decode failure into `ReadFailed` and stashes
+        // the real one; the stashed name is what identifies the bad file.
+        std.process.fatal("'{s}' is not readable gzip: {t}", .{ sub_path, decompress.err orelse err });
+    };
+    if (!std.mem.eql(u8, plain, base)) {
+        std.process.fatal(
+            "'{s}' does not decompress to its base file ({d} bytes out, {d} expected)",
+            .{ sub_path, plain.len, base.len },
+        );
+    }
+}
+
 /// Gzips `bytes`; writes and returns the result only when it is smaller than
 /// the original, else null. Equal-or-larger output means the asset is already
 /// compressed (an image, a font) and the sibling would waste binary size.