main.zig

const std = @import("std");
const net = std.Io.net;
const posix = std.posix;
const Allocator = std.mem.Allocator;
const builtin = @import("builtin");
const build_options = @import("build_options");
const acl = @import("acl.zig");
pub var app_io: std.Io = undefined;

const MAX_HEADER_SIZE = 8 * 1024;
const MAX_BODY_SIZE = 5 * 1024 * 1024 * 1024;
const MAX_KEY_LENGTH = 1024;
const MAX_BUCKET_LENGTH = 63;
const MAX_CONNECTIONS = 1024;

// Distributed mode constants
const CHUNK_SIZE = 4 * 1024 * 1024; // 4MB chunks for large files
const MAX_PEERS = 100;
const GOSSIP_INTERVAL_MS = 30_000;
const REPLICATION_TARGET = 3;
const TOMBSTONE_TTL_SECS = 24 * 60 * 60; // 24 hours before tombstone cleanup
const INLINE_THRESHOLD = 4 * 1024; // Objects <= 4KB stored inline in metadata
const GC_GRACE_PERIOD_SECS = 10 * 60; // 10 min delay before deleting unreferenced blocks
const QUORUM_SIZE = 2; // Need 2 matching responses for quorum reads
const MAX_BROADCAST_PEERS = 64; // Max peers a metadata/announce broadcast reaches
const MAX_META_RESPONSE = 16 * 1024; // Meta entries are small: header + inline data
const MAX_INDEX_SYNC_SIZE = 256 * 1024 * 1024; // Cap on a full index dump during join sync
const PEER_IO_TIMEOUT_SECS = 5; // Socket timeout for peer-to-peer requests

const ERROR_403 = "HTTP/1.1 403 Forbidden\r\nContent-Length: 6\r\nConnection: keep-alive\r\n\r\nDenied";
const ERROR_431 = "HTTP/1.1 431 Request Header Fields Too Large\r\nContent-Length: 0\r\nConnection: close\r\n\r\n";
const ERROR_400_ENTITY_TOO_LARGE = "HTTP/1.1 400 Bad Request\r\nContent-Length: 0\r\nConnection: close\r\n\r\n";

// Crash-safety knob. Default ON: PUT/CopyObject/multipart-complete fsync file
// contents (and best-effort parent dirs) so an acknowledged write survives a
// crash or power loss — the "SQLite for objects" claim requires it. Pass
// --fast (benchmark mode) or --no-fsync to restore the no-fsync fast path and
// the original benchmark numbers.
var enable_fsync: bool = true;

fn fsyncFile(file: std.Io.File) void {
    if (!enable_fsync) return;
    file.sync(app_io) catch {};
}

fn fsyncParentDir(path: []const u8) void {
    if (!enable_fsync) return;
    if (std.fs.path.dirname(path)) |dir| {
        var d = std.Io.Dir.cwd().openDir(app_io, dir, .{}) catch return;
        defer d.close(app_io);
        // fsync the dir fd so the rename entry is durable. Best-effort:
        // ignore failures (filesystems that reject dir fsync). Raw syscall
        // on Linux to keep the static musl build libc-free.
        if (builtin.os.tag == .linux) {
            _ = std.os.linux.fsync(d.handle);
        } else {
            _ = std.c.fsync(d.handle);
        }
    }
}

// Lightweight process metrics, mutated only on the event-loop thread so no
// atomics are needed (the background PushWorker never touches these).
const Metrics = struct {
    start_time_secs: i64 = 0,
    requests: u64 = 0,
    errors_4xx: u64 = 0,
    errors_5xx: u64 = 0,
    put_bytes: u64 = 0,
    get_bytes: u64 = 0,
};
var metrics: Metrics = .{};

/// Format a Unix timestamp (seconds) as an HTTP date (RFC 7231).
/// Returns a 29-byte string like "Mon, 02 Jan 2006 15:04:05 GMT".
/// When using with Response.setHeader, the returned slice must outlive
/// the response — use allocHttpDate to get a heap-allocated copy.
pub fn formatHttpDate(buf: *[29]u8, timestamp: i64) void {
    const secs: u64 = if (timestamp > 0) @intCast(timestamp) else 0;
    const es = std.time.epoch.EpochSeconds{ .secs = secs };
    const day = es.getEpochDay();
    const yd = day.calculateYearDay();
    const md = yd.calculateMonthDay();
    const ds = es.getDaySeconds();

    const dow = @mod(@as(i32, @intCast(day.day)) + 4, 7); // epoch was Thursday=4
    const day_names = [7]*const [3]u8{ "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" };
    const month_names = [12]*const [3]u8{ "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" };
    const mon_idx = @intFromEnum(md.month) - 1;

    _ = std.fmt.bufPrint(buf, "{s}, {d:0>2} {s} {d:0>4} {d:0>2}:{d:0>2}:{d:0>2} GMT", .{
        day_names[@intCast(dow)],
        md.day_index + 1,
        month_names[mon_idx],
        yd.year,
        ds.getHoursIntoDay(),
        ds.getMinutesIntoHour(),
        ds.getSecondsIntoMinute(),
    }) catch unreachable;
}

/// Format a Unix timestamp (seconds) as ISO 8601 for S3 XML responses.
/// Returns a 20-byte string like "2006-01-02T15:04:05Z".
pub fn formatIso8601(buf: *[20]u8, timestamp: i64) void {
    const secs: u64 = if (timestamp > 0) @intCast(timestamp) else 0;
    const es = std.time.epoch.EpochSeconds{ .secs = secs };
    const day = es.getEpochDay();
    const yd = day.calculateYearDay();
    const md = yd.calculateMonthDay();
    const ds = es.getDaySeconds();

    _ = std.fmt.bufPrint(buf, "{d:0>4}-{d:0>2}-{d:0>2}T{d:0>2}:{d:0>2}:{d:0>2}Z", .{
        yd.year,
        @intFromEnum(md.month),
        md.day_index + 1,
        ds.getHoursIntoDay(),
        ds.getMinutesIntoHour(),
        ds.getSecondsIntoMinute(),
    }) catch unreachable;
}

/// Result of decoding AWS chunked transfer encoding: the payload, plus the raw
/// trailer block that follows the terminating 0-size chunk (empty when absent).
pub const ChunkedBody = struct {
    data: []const u8,
    trailers: []const u8,
};

/// Decode AWS chunked transfer encoding.
/// Format: <hex-size>;chunk-signature=...\r\n<data>\r\n repeated, terminated by 0-size chunk.
/// The -TRAILER variants append `x-amz-checksum-*: <base64>` lines after that
/// final chunk; they are returned rather than discarded so the checksum can be
/// verified against the payload.
pub fn decodeAwsChunkedFull(allocator: Allocator, body: []const u8) !ChunkedBody {
    var result: std.ArrayListUnmanaged(u8) = .empty;
    errdefer result.deinit(allocator);

    var trailers: []const u8 = "";
    var pos: usize = 0;
    while (pos < body.len) {
        // Find the end of the chunk header line (terminated by \r\n)
        const line_end = std.mem.indexOfPos(u8, body, pos, "\r\n") orelse break;
        const chunk_header = body[pos..line_end];

        // Parse hex chunk size (before the first ';')
        const size_end = std.mem.indexOf(u8, chunk_header, ";") orelse chunk_header.len;
        const hex_str = chunk_header[0..size_end];
        const chunk_size = std.fmt.parseInt(usize, hex_str, 16) catch break;

        if (chunk_size == 0) {
            // Everything past the terminating chunk's CRLF is the trailer block.
            trailers = body[@min(line_end + 2, body.len)..];
            break;
        }

        // Data starts after \r\n
        const data_start = line_end + 2;
        if (data_start + chunk_size > body.len) break;

        try result.appendSlice(allocator, body[data_start .. data_start + chunk_size]);

        // Skip past data + \r\n
        pos = data_start + chunk_size + 2;
    }

    return .{ .data = try result.toOwnedSlice(allocator), .trailers = trailers };
}

/// Payload-only wrapper for callers with no interest in trailers.
pub fn decodeAwsChunked(allocator: Allocator, body: []const u8) ![]const u8 {
    const decoded = try decodeAwsChunkedFull(allocator, body);
    return decoded.data;
}

// ============================================================================
// PAYLOAD CHECKSUMS (x-amz-checksum-*, header or trailer form)
// ============================================================================

/// CRC-64/NVME is absent from Zig's CRC catalog, so build it from the generic
/// implementation. Check value for "123456789" is 0xae8b14860a799888.
const Crc64Nvme = std.hash.crc.Crc(u64, .{
    .polynomial = 0xad93d23594c93659,
    .initial = 0xffffffffffffffff,
    .reflect_input = true,
    .reflect_output = true,
    .xor_output = 0xffffffffffffffff,
});

pub const ChecksumAlgo = enum {
    crc32,
    crc32c,
    crc64nvme,
    sha1,
    sha256,

    /// Map a full header name ("x-amz-checksum-crc32c") to its algorithm.
    pub fn fromHeaderName(name: []const u8) ?ChecksumAlgo {
        const prefix = "x-amz-checksum-";
        if (!std.mem.startsWith(u8, name, prefix)) return null;
        const suffix = name[prefix.len..];
        if (std.mem.eql(u8, suffix, "crc32")) return .crc32;
        if (std.mem.eql(u8, suffix, "crc32c")) return .crc32c;
        if (std.mem.eql(u8, suffix, "crc64nvme")) return .crc64nvme;
        if (std.mem.eql(u8, suffix, "sha1")) return .sha1;
        if (std.mem.eql(u8, suffix, "sha256")) return .sha256;
        return null;
    }
};

/// Compute the base64 digest S3 carries in x-amz-checksum-<algo>.
pub fn computeChecksum(allocator: Allocator, algo: ChecksumAlgo, data: []const u8) ![]const u8 {
    var digest: [32]u8 = undefined;
    const raw: []const u8 = switch (algo) {
        .crc32 => blk: {
            std.mem.writeInt(u32, digest[0..4], std.hash.crc.Crc32IsoHdlc.hash(data), .big);
            break :blk digest[0..4];
        },
        .crc32c => blk: {
            std.mem.writeInt(u32, digest[0..4], std.hash.crc.Crc32Iscsi.hash(data), .big);
            break :blk digest[0..4];
        },
        .crc64nvme => blk: {
            std.mem.writeInt(u64, digest[0..8], Crc64Nvme.hash(data), .big);
            break :blk digest[0..8];
        },
        .sha1 => blk: {
            std.crypto.hash.Sha1.hash(data, digest[0..20], .{});
            break :blk digest[0..20];
        },
        .sha256 => blk: {
            std.crypto.hash.sha2.Sha256.hash(data, digest[0..32], .{});
            break :blk digest[0..32];
        },
    };
    const encoder = std.base64.standard.Encoder;
    const out = try allocator.alloc(u8, encoder.calcSize(raw.len));
    return encoder.encode(out, raw);
}

/// Verify every x-amz-checksum-* the client supplied against the received
/// payload. Returns the name of the first header that disagrees, or null when
/// all of them match (including when none were sent).
///
/// Composite values ("<base64>-<partcount>", returned by CompleteMultipartUpload)
/// describe an assembled object rather than this request body, so they are
/// skipped.
pub fn mismatchedChecksum(allocator: Allocator, req: *const Request) !?[]const u8 {
    var it = req.headers.iterator();
    while (it.next()) |entry| {
        const algo = ChecksumAlgo.fromHeaderName(entry.key_ptr.*) orelse continue;
        const want = std.mem.trim(u8, entry.value_ptr.*, " \t");
        if (want.len == 0) continue;
        if (std.mem.indexOfScalar(u8, want, '-') != null) continue;
        const got = try computeChecksum(allocator, algo, req.body);
        if (!std.mem.eql(u8, got, want)) return entry.key_ptr.*;
    }
    return null;
}

/// Heap-allocate an RFC 7231 date string suitable for Response.setHeader.
fn allocHttpDate(allocator: Allocator, timestamp: i64) ![]const u8 {
    var buf: [29]u8 = undefined;
    formatHttpDate(&buf, timestamp);
    return allocator.dupe(u8, &buf);
}

// ============================================================================
// DISTRIBUTED TYPES
// ============================================================================

const ContentHash = [20]u8; // 160-bit truncated BLAKE3
const NodeId = [20]u8; // 160-bit node identifier

/// Format bytes as lowercase hex string
fn bytesToHex(bytes: []const u8, out: []u8) void {
    const hex_chars = "0123456789abcdef";
    for (bytes, 0..) |b, i| {
        out[i * 2] = hex_chars[b >> 4];
        out[i * 2 + 1] = hex_chars[b & 0x0f];
    }
}

/// Content-Addressed Store - stores objects by their hash
const CAS = struct {
    data_dir: []const u8,

    const Blake3 = std.crypto.hash.Blake3;

    /// Store data and return its content hash (deduplicates automatically)
    pub fn store(self: *const CAS, allocator: Allocator, data: []const u8) !ContentHash {
        var hasher = Blake3.init(.{});
        hasher.update(data);
        var full_hash: [32]u8 = undefined;
        hasher.final(&full_hash);

        const hash: ContentHash = full_hash[0..20].*;
        const path = try self.hashToPath(allocator, hash);
        defer allocator.free(path);

        // Check if already exists (deduplication)
        if (std.Io.Dir.cwd().access(app_io, path, .{})) |_| {
            return hash;
        } else |_| {}

        // Write the blob atomically (temp file + rename) so a concurrent reader
        // never sees a half-written blob under a content hash.
        var af = try std.Io.Dir.cwd().createFileAtomic(app_io, path, .{
            .make_path = true,
            .replace = true,
        });
        defer af.deinit(app_io);
        try af.file.writeStreamingAll(app_io, data);
        try af.replace(app_io);

        return hash;
    }

    /// Retrieve data by content hash
    pub fn retrieve(self: *const CAS, allocator: Allocator, hash: ContentHash) ![]const u8 {
        const path = try self.hashToPath(allocator, hash);
        defer allocator.free(path);

        var file = std.Io.Dir.cwd().openFile(app_io, path, .{}) catch return error.NotFound;
        defer file.close(app_io);

        const stat = try file.stat(app_io);
        const data = try allocator.alloc(u8, stat.size);
        const bytes_read = try file.readPositionalAll(app_io, data, 0);
        return data[0..bytes_read];
    }

    /// Check if content exists locally
    pub fn exists(self: *const CAS, allocator: Allocator, hash: ContentHash) bool {
        const path = self.hashToPath(allocator, hash) catch return false;
        defer allocator.free(path);
        return if (std.Io.Dir.cwd().access(app_io, path, .{})) |_| true else |_| false;
    }

    /// Convert hash to filesystem path: .cas/xx/xxxx....blob
    fn hashToPath(self: *const CAS, allocator: Allocator, hash: ContentHash) ![]const u8 {
        var hex: [40]u8 = undefined;
        bytesToHex(&hash, &hex);
        return std.fs.path.join(allocator, &.{ self.data_dir, ".cas", hex[0..2], hex[2..] ++ ".blob" });
    }

    /// Compute hash without storing
    pub fn computeHash(data: []const u8) ContentHash {
        var hasher = Blake3.init(.{});
        hasher.update(data);
        var full_hash: [32]u8 = undefined;
        hasher.final(&full_hash);
        return full_hash[0..20].*;
    }

    /// Garbage collect unreferenced blocks
    /// Scans metadata index to build reference set, then removes orphaned CAS blobs
    pub fn garbageCollect(self: *const CAS, allocator: Allocator, meta_index: *const MetaIndex) !struct { scanned: usize, deleted: usize } {
        var referenced = std.AutoHashMap(ContentHash, void).init(allocator);
        defer referenced.deinit();

        // Phase 1: Collect all referenced hashes from metadata index
        const index_path = try std.fs.path.join(allocator, &.{ meta_index.data_dir, ".index" });
        defer allocator.free(index_path);

        var index_dir = std.Io.Dir.cwd().openDir(app_io, index_path, .{ .iterate = true }) catch {
            return .{ .scanned = 0, .deleted = 0 };
        };
        defer index_dir.close(app_io);

        var bucket_iter = index_dir.iterate();
        while (try bucket_iter.next(app_io)) |bucket_entry| {
            if (bucket_entry.kind == .directory) {
                try self.collectReferencedHashes(allocator, meta_index, bucket_entry.name, &referenced);
            }
        }

        // Phase 2: Scan CAS directory and delete unreferenced blocks
        const cas_path = try std.fs.path.join(allocator, &.{ self.data_dir, ".cas" });
        defer allocator.free(cas_path);

        var cas_dir = std.Io.Dir.cwd().openDir(app_io, cas_path, .{ .iterate = true }) catch {
            return .{ .scanned = 0, .deleted = 0 };
        };
        defer cas_dir.close(app_io);

        var scanned: usize = 0;
        var deleted: usize = 0;
        const now = std.Io.Clock.real.now(app_io).toSeconds();

        var prefix_iter = cas_dir.iterate();
        while (try prefix_iter.next(app_io)) |prefix_entry| {
            if (prefix_entry.kind == .directory and prefix_entry.name.len == 2) {
                const prefix_path = try std.fs.path.join(allocator, &.{ cas_path, prefix_entry.name });
                defer allocator.free(prefix_path);

                var blob_dir = std.Io.Dir.cwd().openDir(app_io, prefix_path, .{ .iterate = true }) catch continue;
                defer blob_dir.close(app_io);

                var blob_iter = blob_dir.iterate();
                while (try blob_iter.next(app_io)) |blob_entry| {
                    if (blob_entry.kind == .file and std.mem.endsWith(u8, blob_entry.name, ".blob")) {
                        scanned += 1;

                        // Reconstruct hash from path: prefix + name (without .blob)
                        const name_without_ext = blob_entry.name[0 .. blob_entry.name.len - 5];
                        if (name_without_ext.len != 38) continue; // 40 - 2 prefix = 38

                        var hex: [40]u8 = undefined;
                        @memcpy(hex[0..2], prefix_entry.name);
                        @memcpy(hex[2..], name_without_ext);

                        var hash: ContentHash = undefined;
                        _ = std.fmt.hexToBytes(&hash, &hex) catch continue;

                        // Check if referenced
                        if (!referenced.contains(hash)) {
                            // Check grace period using mtime
                            const blob_path = try std.fs.path.join(allocator, &.{ prefix_path, blob_entry.name });
                            defer allocator.free(blob_path);

                            const file = std.Io.Dir.cwd().openFile(app_io, blob_path, .{}) catch continue;
                            const stat = file.stat(app_io) catch {
                                file.close(app_io);
                                continue;
                            };
                            file.close(app_io);

                            const mtime_secs = stat.mtime.toSeconds();
                            const age = now - mtime_secs;

                            if (age > GC_GRACE_PERIOD_SECS) {
                                std.Io.Dir.cwd().deleteFile(app_io, blob_path) catch continue;
                                deleted += 1;
                            }
                        }
                    }
                }
            }
        }

        return .{ .scanned = scanned, .deleted = deleted };
    }

    fn collectReferencedHashes(self: *const CAS, allocator: Allocator, meta_index: *const MetaIndex, bucket: []const u8, referenced: *std.AutoHashMap(ContentHash, void)) !void {
        _ = self;
        const bucket_path = try std.fs.path.join(allocator, &.{ meta_index.data_dir, ".index", bucket });
        defer allocator.free(bucket_path);

        try collectHashesFromDir(allocator, bucket_path, bucket, "", meta_index, referenced);
    }
};

/// Recursively collect hashes from metadata directory for GC reference counting
fn collectHashesFromDir(allocator: Allocator, dir_path: []const u8, bucket: []const u8, prefix: []const u8, meta_index: *const MetaIndex, referenced: *std.AutoHashMap(ContentHash, void)) !void {
    var dir = std.Io.Dir.cwd().openDir(app_io, dir_path, .{ .iterate = true }) catch return;
    defer dir.close(app_io);

    var iter = dir.iterate();
    while (try iter.next(app_io)) |entry| {
        const full_name = if (prefix.len > 0)
            try std.fmt.allocPrint(allocator, "{s}/{s}", .{ prefix, entry.name })
        else
            try allocator.dupe(u8, entry.name);
        defer allocator.free(full_name);

        if (entry.kind == .directory) {
            const subdir = try std.fs.path.join(allocator, &.{ dir_path, entry.name });
            defer allocator.free(subdir);
            try collectHashesFromDir(allocator, subdir, bucket, full_name, meta_index, referenced);
        } else if (std.mem.endsWith(u8, entry.name, ".meta")) {
            // Read hash from metadata file (even tombstones - they still reference content)
            const key = full_name[0 .. full_name.len - 5]; // Remove .meta
            const path = try meta_index.metaPath(allocator, bucket, key);
            defer allocator.free(path);

            var file = std.Io.Dir.cwd().openFile(app_io, path, .{}) catch continue;
            defer file.close(app_io);

            var buf: [128]u8 = undefined;
            const bytes_read = file.readPositionalAll(app_io, &buf, 0) catch continue;
            const content = buf[0..bytes_read];

            var lines = std.mem.splitScalar(u8, content, '\n');
            const hash_hex = lines.next() orelse continue;

            if (hash_hex.len != 40) continue;
            var hash: ContentHash = undefined;
            _ = std.fmt.hexToBytes(&hash, hash_hex) catch continue;

            try referenced.put(hash, {});
        }
    }
}

/// Metadata Index - maps S3 paths to content hashes
/// Supports tombstones for delete propagation and inline storage for small objects
const MetaIndex = struct {
    data_dir: []const u8,

    const ObjectMeta = struct {
        hash: ContentHash,
        size: u64,
        created: i64,
        deleted: i64, // 0 = not deleted, >0 = tombstone timestamp
        inline_data: ?[]const u8, // For small objects (<= INLINE_THRESHOLD)
    };

    /// Store metadata for an S3 object (with optional inline data for small objects)
    pub fn put(self: *const MetaIndex, allocator: Allocator, bucket: []const u8, key: []const u8, hash: ContentHash, size: u64) !void {
        try self.putWithData(allocator, bucket, key, hash, size, null);
    }

    /// Store metadata with optional inline data
    pub fn putWithData(self: *const MetaIndex, allocator: Allocator, bucket: []const u8, key: []const u8, hash: ContentHash, size: u64, inline_data: ?[]const u8) !void {
        const path = try self.metaPath(allocator, bucket, key);
        defer allocator.free(path);

        // Write the index entry atomically (temp file + rename) so a concurrent
        // reader never sees a half-written .meta file.
        var af = try std.Io.Dir.cwd().createFileAtomic(app_io, path, .{
            .make_path = true,
            .replace = true,
        });
        defer af.deinit(app_io);

        // Format: hex_hash\nsize\ncreated\ndeleted\n[inline_data_base64]
        var hash_hex: [40]u8 = undefined;
        bytesToHex(&hash, &hash_hex);
        const created = std.Io.Clock.real.now(app_io).toSeconds();

        var buf: [128]u8 = undefined;
        const header = std.fmt.bufPrint(&buf, "{s}\n{d}\n{d}\n0\n", .{ hash_hex, size, created }) catch unreachable;
        try af.file.writeStreamingAll(app_io, header);

        // Write inline data if provided
        if (inline_data) |data| {
            try af.file.writeStreamingAll(app_io, data);
        }

        try af.replace(app_io);
    }

    /// Get metadata for an S3 object (returns null for tombstones)
    pub fn get(self: *const MetaIndex, allocator: Allocator, bucket: []const u8, key: []const u8) !?struct { hash: ContentHash, size: u64 } {
        const meta = try self.getFull(allocator, bucket, key) orelse return null;
        if (meta.inline_data) |data| allocator.free(data);
        return .{ .hash = meta.hash, .size = meta.size };
    }

    /// Get full metadata including inline data
    pub fn getFull(self: *const MetaIndex, allocator: Allocator, bucket: []const u8, key: []const u8) !?ObjectMeta {
        const path = try self.metaPath(allocator, bucket, key);
        defer allocator.free(path);

        var file = std.Io.Dir.cwd().openFile(app_io, path, .{}) catch return null;
        defer file.close(app_io);

        const stat = try file.stat(app_io);
        const content = try allocator.alloc(u8, stat.size);
        defer allocator.free(content);
        _ = try file.readPositionalAll(app_io, content, 0);

        // Parse: hex_hash\nsize\ncreated\ndeleted\n[inline_data]
        var lines = std.mem.splitScalar(u8, content, '\n');
        const hash_hex = lines.next() orelse return null;
        const size_str = lines.next() orelse return null;
        const created_str = lines.next() orelse return null;
        const deleted_str = lines.next() orelse return null;

        if (hash_hex.len != 40) return null;
        var hash: ContentHash = undefined;
        _ = std.fmt.hexToBytes(&hash, hash_hex) catch return null;

        const size = std.fmt.parseInt(u64, size_str, 10) catch return null;
        const created = std.fmt.parseInt(i64, created_str, 10) catch return null;
        const deleted = std.fmt.parseInt(i64, deleted_str, 10) catch 0;

        // Check tombstone - return null if deleted
        if (deleted > 0) return null;

        // Check for inline data after the 4th newline
        var header_end: usize = 0;
        var newline_count: usize = 0;
        for (content, 0..) |c, i| {
            if (c == '\n') {
                newline_count += 1;
                if (newline_count == 4) {
                    header_end = i + 1;
                    break;
                }
            }
        }

        var inline_data: ?[]const u8 = null;
        if (header_end < content.len) {
            inline_data = try allocator.dupe(u8, content[header_end..]);
        }

        return .{
            .hash = hash,
            .size = size,
            .created = created,
            .deleted = 0,
            .inline_data = inline_data,
        };
    }

    /// Read the raw meta file content (including tombstones) for replication
    pub fn readRaw(self: *const MetaIndex, allocator: Allocator, bucket: []const u8, key: []const u8) !?[]u8 {
        const path = try self.metaPath(allocator, bucket, key);
        defer allocator.free(path);

        var file = std.Io.Dir.cwd().openFile(app_io, path, .{}) catch return null;
        defer file.close(app_io);

        const stat = try file.stat(app_io);
        const content = try allocator.alloc(u8, stat.size);
        errdefer allocator.free(content);
        _ = try file.readPositionalAll(app_io, content, 0);
        return content;
    }

    /// Write raw meta file content verbatim, preserving origin timestamps
    pub fn writeRaw(self: *const MetaIndex, allocator: Allocator, bucket: []const u8, key: []const u8, content: []const u8) !void {
        const path = try self.metaPath(allocator, bucket, key);
        defer allocator.free(path);

        if (std.fs.path.dirname(path)) |dir| {
            std.Io.Dir.cwd().createDirPath(app_io, dir) catch {};
        }

        var file = try std.Io.Dir.cwd().createFile(app_io, path, .{});
        defer file.close(app_io);
        try file.writeStreamingAll(app_io, content);
    }

    /// Delete metadata by writing a tombstone (prevents resurrection during sync)
    pub fn delete(self: *const MetaIndex, allocator: Allocator, bucket: []const u8, key: []const u8) void {
        self.writeTombstone(allocator, bucket, key) catch {
            // Fallback: just delete the file if tombstone fails
            const path = self.metaPath(allocator, bucket, key) catch return;
            defer allocator.free(path);
            std.Io.Dir.cwd().deleteFile(app_io, path) catch {};
        };
    }

    /// Write tombstone marker (preserves hash for GC reference counting)
    fn writeTombstone(self: *const MetaIndex, allocator: Allocator, bucket: []const u8, key: []const u8) !void {
        const path = try self.metaPath(allocator, bucket, key);
        defer allocator.free(path);

        // Read existing metadata to preserve hash
        var file = std.Io.Dir.cwd().openFile(app_io, path, .{}) catch return;
        var buf: [128]u8 = undefined;
        const bytes_read = file.readPositionalAll(app_io, &buf, 0) catch return;
        file.close(app_io);
        const content = buf[0..bytes_read];

        var lines = std.mem.splitScalar(u8, content, '\n');
        const hash_hex = lines.next() orelse return;
        const size_str = lines.next() orelse return;
        const created_str = lines.next() orelse return;

        // Rewrite with tombstone timestamp
        var out_file = try std.Io.Dir.cwd().createFile(app_io, path, .{});
        defer out_file.close(app_io);

        const deleted = std.Io.Clock.real.now(app_io).toSeconds();
        var out_buf: [128]u8 = undefined;
        const new_content = std.fmt.bufPrint(&out_buf, "{s}\n{s}\n{s}\n{d}\n", .{ hash_hex, size_str, created_str, deleted }) catch unreachable;
        try out_file.writeStreamingAll(app_io, new_content);
    }

    /// Check if entry is a tombstone (for cleanup)
    pub fn isTombstone(self: *const MetaIndex, allocator: Allocator, bucket: []const u8, key: []const u8) bool {
        const path = self.metaPath(allocator, bucket, key) catch return false;
        defer allocator.free(path);

        var file = std.Io.Dir.cwd().openFile(app_io, path, .{}) catch return false;
        defer file.close(app_io);

        var buf: [128]u8 = undefined;
        const bytes_read = file.readPositionalAll(app_io, &buf, 0) catch return false;
        const content = buf[0..bytes_read];

        var lines = std.mem.splitScalar(u8, content, '\n');
        _ = lines.next(); // hash
        _ = lines.next(); // size
        _ = lines.next(); // created
        const deleted_str = lines.next() orelse return false;

        const deleted = std.fmt.parseInt(i64, deleted_str, 10) catch return false;
        return deleted > 0;
    }

    /// Cleanup expired tombstones
    pub fn cleanupTombstones(self: *const MetaIndex, allocator: Allocator) !void {
        const now = std.Io.Clock.real.now(app_io).toSeconds();
        const index_path = try std.fs.path.join(allocator, &.{ self.data_dir, ".index" });
        defer allocator.free(index_path);

        var dir = std.Io.Dir.cwd().openDir(app_io, index_path, .{ .iterate = true }) catch return;
        defer dir.close(app_io);

        var iter = dir.iterate();
        while (try iter.next(app_io)) |entry| {
            if (entry.kind == .directory) {
                try self.cleanupBucketTombstones(allocator, entry.name, now);
            }
        }
    }

    fn cleanupBucketTombstones(self: *const MetaIndex, allocator: Allocator, bucket: []const u8, now: i64) !void {
        const bucket_path = try std.fs.path.join(allocator, &.{ self.data_dir, ".index", bucket });
        defer allocator.free(bucket_path);

        self.cleanupDirTombstones(allocator, bucket_path, bucket, "", now) catch {};
    }

    fn cleanupDirTombstones(self: *const MetaIndex, allocator: Allocator, dir_path: []const u8, bucket: []const u8, prefix: []const u8, now: i64) !void {
        var dir = std.Io.Dir.cwd().openDir(app_io, dir_path, .{ .iterate = true }) catch return;
        defer dir.close(app_io);

        var iter = dir.iterate();
        while (try iter.next(app_io)) |entry| {
            const full_name = if (prefix.len > 0)
                try std.fmt.allocPrint(allocator, "{s}/{s}", .{ prefix, entry.name })
            else
                try allocator.dupe(u8, entry.name);
            defer allocator.free(full_name);

            if (entry.kind == .directory) {
                const subdir = try std.fs.path.join(allocator, &.{ dir_path, entry.name });
                defer allocator.free(subdir);
                try self.cleanupDirTombstones(allocator, subdir, bucket, full_name, now);
            } else if (std.mem.endsWith(u8, entry.name, ".meta")) {
                // Check if expired tombstone
                const key = full_name[0 .. full_name.len - 5]; // Remove .meta
                if (self.getTombstoneAge(allocator, bucket, key, now)) |age| {
                    if (age > TOMBSTONE_TTL_SECS) {
                        const path = try self.metaPath(allocator, bucket, key);
                        defer allocator.free(path);
                        std.Io.Dir.cwd().deleteFile(app_io, path) catch {};
                    }
                }
            }
        }
    }

    fn getTombstoneAge(self: *const MetaIndex, allocator: Allocator, bucket: []const u8, key: []const u8, now: i64) ?i64 {
        const path = self.metaPath(allocator, bucket, key) catch return null;
        defer allocator.free(path);

        var file = std.Io.Dir.cwd().openFile(app_io, path, .{}) catch return null;
        defer file.close(app_io);

        var buf: [128]u8 = undefined;
        const bytes_read = file.readPositionalAll(app_io, &buf, 0) catch return null;
        const content = buf[0..bytes_read];

        var lines = std.mem.splitScalar(u8, content, '\n');
        _ = lines.next(); // hash
        _ = lines.next(); // size
        _ = lines.next(); // created
        const deleted_str = lines.next() orelse return null;

        const deleted = std.fmt.parseInt(i64, deleted_str, 10) catch return null;
        if (deleted == 0) return null;
        return now - deleted;
    }

    fn metaPath(self: *const MetaIndex, allocator: Allocator, bucket: []const u8, key: []const u8) ![]const u8 {
        const key_with_ext = try std.fmt.allocPrint(allocator, "{s}.meta", .{key});
        defer allocator.free(key_with_ext);
        const path = try std.fs.path.join(allocator, &.{ self.data_dir, ".index", bucket, key_with_ext });
        // Same filesystem guards as S3Context.objectPath (NAME_MAX per
        // component, PATH_MAX total): an un-storable key must surface as a
        // client error, not a 500. Note key_with_ext includes the ".meta"
        // suffix, so its components are the ones that land on disk.
        var component_itr = std.mem.splitScalar(u8, key_with_ext, '/');
        while (component_itr.next()) |component| {
            if (component.len >= std.posix.NAME_MAX) {
                allocator.free(path);
                return error.NameTooLong;
            }
        }
        if (path.len >= std.posix.PATH_MAX) {
            allocator.free(path);
            return error.PathTooLong;
        }
        return path;
    }
};

// ============================================================================
// DISTRIBUTED OBJECT ATTRIBUTES
// ============================================================================
// Content-Type / user metadata / checksums for distributed objects live in
// `.index/<bucket>/<key>.attrs` (same `name: value` text format as the
// standalone sidecar). They replicate alongside metadata: pushed synchronously
// on write (`POST /_zs3/attrs`), pulled on read misses (`POST /_zs3/attrs_get`),
// and included in join-time index dumps (frames prefixed with a kind line).

fn distAttrsPath(allocator: Allocator, data_dir: []const u8, bucket: []const u8, key: []const u8) ![]const u8 {
    const key_with_ext = try std.fmt.allocPrint(allocator, "{s}.attrs", .{key});
    defer allocator.free(key_with_ext);
    const path = try std.fs.path.join(allocator, &.{ data_dir, ".index", bucket, key_with_ext });
    var component_itr = std.mem.splitScalar(u8, key_with_ext, '/');
    while (component_itr.next()) |component| {
        if (component.len >= std.posix.NAME_MAX) {
            allocator.free(path);
            return error.NameTooLong;
        }
    }
    if (path.len >= std.posix.PATH_MAX) {
        allocator.free(path);
        return error.PathTooLong;
    }
    return path;
}

fn attrsToText(allocator: Allocator, attrs: *const ObjectAttrs) ![]const u8 {
    var buf: std.ArrayListUnmanaged(u8) = .empty;
    errdefer buf.deinit(allocator);
    try attrsToTextInto(allocator, &buf, attrs);
    return buf.toOwnedSlice(allocator);
}

fn writeDistAttrs(allocator: Allocator, dist: *const DistributedContext, bucket: []const u8, key: []const u8, attrs: *const ObjectAttrs) void {
    const path = distAttrsPath(allocator, dist.meta_index.data_dir, bucket, key) catch return;
    defer allocator.free(path);
    const text = attrsToText(allocator, attrs) catch return;
    defer allocator.free(text);
    if (std.fs.path.dirname(path)) |dir| {
        std.Io.Dir.cwd().createDirPath(app_io, dir) catch {};
    }
    var file = std.Io.Dir.cwd().createFile(app_io, path, .{}) catch return;
    defer file.close(app_io);
    file.writeStreamingAll(app_io, text) catch {};
    if (enable_fsync) {
        fsyncFile(file);
        fsyncParentDir(path);
    }
}

fn readDistAttrs(allocator: Allocator, dist: *const DistributedContext, bucket: []const u8, key: []const u8) ?ObjectAttrs {
    const path = distAttrsPath(allocator, dist.meta_index.data_dir, bucket, key) catch return null;
    defer allocator.free(path);
    var file = std.Io.Dir.cwd().openFile(app_io, path, .{}) catch return null;
    defer file.close(app_io);
    const content = readToEndAlloc(file, allocator, 64 * 1024) catch return null;
    defer allocator.free(content);
    return parseAttrsContent(allocator, content) catch null;
}

fn deleteDistAttrs(allocator: Allocator, dist: *const DistributedContext, bucket: []const u8, key: []const u8) void {
    const path = distAttrsPath(allocator, dist.meta_index.data_dir, bucket, key) catch return;
    defer allocator.free(path);
    std.Io.Dir.cwd().deleteFile(app_io, path) catch {};
}

/// Last-write-wins bookkeeping for bucket create/delete propagation.
///
/// Bucket create and delete are broadcast by different nodes at different
/// times, so a peer can receive them in either order. Without ordering, a
/// late-arriving "bucket created" message resurrects a bucket that was
/// deleted moments earlier (issue: flaky `HEAD <bucket>` on replicas).
/// Each node persists per-bucket wall-clock timestamps for the last create
/// and last delete; an incoming op only applies if it is newer, and on a
/// timestamp tie the delete wins (matching the object-metadata tombstone
/// convention, so a delete issued in the same second as a create sticks).
///
/// Persisted as `<create_ts>\n<delete_ts>\n` in `data_dir/.buckets/<bucket>`
/// (a dot-directory, invisible to ListBuckets and index dumps).
const BucketOps = struct {
    data_dir: []const u8,

    const State = struct {
        create_ts: i64 = 0,
        delete_ts: i64 = 0, // 0 = never deleted
    };

    fn path(self: *const BucketOps, allocator: Allocator, bucket: []const u8) ![]const u8 {
        return std.fs.path.join(allocator, &.{ self.data_dir, ".buckets", bucket });
    }

    /// Read the persisted state; returns zeros when absent or unreadable.
    fn read(self: *const BucketOps, allocator: Allocator, bucket: []const u8) State {
        const p = self.path(allocator, bucket) catch return .{};
        defer allocator.free(p);

        var file = std.Io.Dir.cwd().openFile(app_io, p, .{}) catch return .{};
        defer file.close(app_io);

        const stat = file.stat(app_io) catch return .{};
        if (stat.size > 128) return .{};
        var buf: [128]u8 = undefined;
        _ = file.readPositionalAll(app_io, buf[0..@intCast(stat.size)], 0) catch return .{};
        var lines = std.mem.splitScalar(u8, buf[0..@intCast(stat.size)], '\n');
        const create_ts = std.fmt.parseInt(i64, lines.next() orelse return .{}, 10) catch return .{};
        const delete_ts = std.fmt.parseInt(i64, lines.next() orelse return .{}, 10) catch return .{};
        return .{ .create_ts = create_ts, .delete_ts = delete_ts };
    }

    fn write(self: *const BucketOps, allocator: Allocator, bucket: []const u8, state: State) void {
        const p = self.path(allocator, bucket) catch return;
        defer allocator.free(p);
        if (std.fs.path.dirname(p)) |dir| {
            std.Io.Dir.cwd().createDirPath(app_io, dir) catch {};
        }
        var file = std.Io.Dir.cwd().createFile(app_io, p, .{}) catch return;
        defer file.close(app_io);
        var buf: [64]u8 = undefined;
        const text = std.fmt.bufPrint(&buf, "{d}\n{d}\n", .{ state.create_ts, state.delete_ts }) catch return;
        file.writeStreamingAll(app_io, text) catch {};
    }

    /// Record a local or accepted create at `ts`.
    fn noteCreate(self: *const BucketOps, allocator: Allocator, bucket: []const u8, ts: i64) void {
        const state = self.read(allocator, bucket);
        self.write(allocator, bucket, .{ .create_ts = @max(state.create_ts, ts), .delete_ts = state.delete_ts });
    }

    /// Record a local or accepted delete at `ts`.
    fn noteDelete(self: *const BucketOps, allocator: Allocator, bucket: []const u8, ts: i64) void {
        const state = self.read(allocator, bucket);
        self.write(allocator, bucket, .{ .create_ts = state.create_ts, .delete_ts = @max(state.delete_ts, ts) });
    }

    /// A peer's create is applicable when it is strictly newer than any local
    /// delete; on a tie the delete wins so a deleted bucket cannot resurrect.
    fn shouldApplyCreate(self: *const BucketOps, allocator: Allocator, bucket: []const u8, create_ts: i64) bool {
        const state = self.read(allocator, bucket);
        if (state.delete_ts == 0) return true;
        return create_ts > state.delete_ts;
    }

    /// A peer's delete is applicable when it is at least as new as any local
    /// create; on a tie the delete wins.
    fn shouldApplyDelete(self: *const BucketOps, allocator: Allocator, bucket: []const u8, delete_ts: i64) bool {
        const state = self.read(allocator, bucket);
        return delete_ts >= state.create_ts;
    }
};

/// Peer information for DHT
const PeerInfo = struct {
    id: NodeId,
    address: net.IpAddress,
    last_seen: i64,
    content_count: u32,
};

/// Full Kademlia DHT implementation
/// XOR metric, 160 k-buckets, iterative lookup
const Kademlia = struct {
    const K = 20; // Bucket size (replication parameter)
    const ALPHA = 3; // Concurrency parameter for lookups
    const ID_BITS = 160; // 20 bytes * 8 bits

    self_id: NodeId,
    buckets: [ID_BITS]KBucket,
    // Provider records are only touched from the event-loop thread
    providers: std.AutoHashMap(ContentHash, std.ArrayListUnmanaged(NodeId)),
    allocator: Allocator,
    // Guards `buckets`: the push worker reads/updates the routing table
    // (gossip, peer snapshots) concurrently with the event loop
    mutex: std.Io.Mutex = .init,

    /// A single k-bucket holding up to K peers
    const KBucket = struct {
        peers: [K]?PeerInfo = [_]?PeerInfo{null} ** K,
        count: usize = 0,
        last_updated: i64 = 0,

        /// Add peer to bucket (LRU eviction if full)
        fn add(self: *KBucket, peer: PeerInfo) void {
            // Check if already exists, update if so
            for (&self.peers) |*slot| {
                if (slot.*) |*p| {
                    if (std.mem.eql(u8, &p.id, &peer.id)) {
                        p.* = peer;
                        self.last_updated = std.Io.Clock.real.now(app_io).toSeconds();
                        return;
                    }
                }
            }

            // Add to first empty slot
            if (self.count < K) {
                for (&self.peers) |*slot| {
                    if (slot.* == null) {
                        slot.* = peer;
                        self.count += 1;
                        self.last_updated = std.Io.Clock.real.now(app_io).toSeconds();
                        return;
                    }
                }
            }

            // Bucket full - replace oldest (LRU eviction)
            var oldest_idx: usize = 0;
            var oldest_time: i64 = std.math.maxInt(i64);
            for (self.peers, 0..) |slot, i| {
                if (slot) |p| {
                    if (p.last_seen < oldest_time) {
                        oldest_time = p.last_seen;
                        oldest_idx = i;
                    }
                }
            }
            self.peers[oldest_idx] = peer;
            self.last_updated = std.Io.Clock.real.now(app_io).toSeconds();
        }

        /// Remove peer from bucket
        fn remove(self: *KBucket, id: NodeId) void {
            for (&self.peers) |*slot| {
                if (slot.*) |p| {
                    if (std.mem.eql(u8, &p.id, &id)) {
                        slot.* = null;
                        self.count -= 1;
                        return;
                    }
                }
            }
        }

        /// Get all peers in bucket
        fn getPeers(self: *const KBucket, out: []PeerInfo) usize {
            var count: usize = 0;
            for (self.peers) |slot| {
                if (slot) |p| {
                    if (count < out.len) {
                        out[count] = p;
                        count += 1;
                    }
                }
            }
            return count;
        }
    };

    pub fn init(allocator: Allocator, self_id: NodeId) Kademlia {
        return .{
            .self_id = self_id,
            .buckets = [_]KBucket{.{}} ** ID_BITS,
            .providers = std.AutoHashMap(ContentHash, std.ArrayListUnmanaged(NodeId)).init(allocator),
            .allocator = allocator,
        };
    }

    pub fn deinit(self: *Kademlia) void {
        var it = self.providers.valueIterator();
        while (it.next()) |list| {
            list.deinit(self.allocator);
        }
        self.providers.deinit();
    }

    /// XOR distance between two node IDs
    pub fn xorDistance(a: NodeId, b: NodeId) NodeId {
        var result: NodeId = undefined;
        for (0..20) |i| {
            result[i] = a[i] ^ b[i];
        }
        return result;
    }

    /// Find the bucket index for a given node ID (based on XOR distance from self)
    fn bucketIndex(self: *const Kademlia, id: NodeId) usize {
        const dist = xorDistance(self.self_id, id);
        // Find highest bit set (leading zeros of XOR)
        for (0..20) |byte_idx| {
            if (dist[byte_idx] != 0) {
                // Count leading zeros in this byte
                const lz = @clz(dist[byte_idx]);
                return ID_BITS - 1 - (byte_idx * 8 + lz);
            }
        }
        return 0; // Same ID (shouldn't happen)
    }

    /// Add or update a peer in the routing table
    pub fn addPeer(self: *Kademlia, peer: PeerInfo) void {
        if (std.mem.eql(u8, &peer.id, &self.self_id)) return; // Don't add self
        const idx = self.bucketIndex(peer.id);
        self.mutex.lockUncancelable(app_io);
        defer self.mutex.unlock(app_io);
        self.buckets[idx].add(peer);
    }

    /// Remove a peer from the routing table
    pub fn removePeer(self: *Kademlia, id: NodeId) void {
        const idx = self.bucketIndex(id);
        self.mutex.lockUncancelable(app_io);
        defer self.mutex.unlock(app_io);
        self.buckets[idx].remove(id);
    }

    /// Find the K closest peers to a target ID
    pub fn findClosest(self: *Kademlia, target: NodeId, out: []PeerInfo) usize {
        const DistPeer = struct {
            peer: PeerInfo,
            dist: NodeId,

            fn lessThan(_: void, a: @This(), b: @This()) bool {
                return compareDist(a.dist, b.dist) == .lt;
            }
        };

        var candidates: [ID_BITS * K]DistPeer = undefined;
        var count: usize = 0;

        // Collect all peers with their distances
        self.mutex.lockUncancelable(app_io);
        defer self.mutex.unlock(app_io);
        for (&self.buckets) |*bucket| {
            var peers: [K]PeerInfo = undefined;
            const n = bucket.getPeers(&peers);
            for (peers[0..n]) |peer| {
                if (count < candidates.len) {
                    candidates[count] = .{
                        .peer = peer,
                        .dist = xorDistance(peer.id, target),
                    };
                    count += 1;
                }
            }
        }

        // Sort by distance
        std.mem.sort(DistPeer, candidates[0..count], {}, DistPeer.lessThan);

        // Copy to output
        const result_count = @min(count, out.len);
        for (0..result_count) |i| {
            out[i] = candidates[i].peer;
        }
        return result_count;
    }

    /// Compare two XOR distances (returns ordering)
    fn compareDist(a: NodeId, b: NodeId) std.math.Order {
        for (0..20) |i| {
            if (a[i] < b[i]) return .lt;
            if (a[i] > b[i]) return .gt;
        }
        return .eq;
    }

    /// Announce that we have content (store provider record)
    pub fn announce(self: *Kademlia, hash: ContentHash) !void {
        const result = try self.providers.getOrPut(hash);
        if (!result.found_existing) {
            result.value_ptr.* = .empty;
        }
        // Add self as provider
        for (result.value_ptr.items) |id| {
            if (std.mem.eql(u8, &id, &self.self_id)) return;
        }
        try result.value_ptr.append(self.allocator, self.self_id);
    }

    /// Record that a peer has content
    pub fn addProvider(self: *Kademlia, hash: ContentHash, provider: NodeId) !void {
        const result = try self.providers.getOrPut(hash);
        if (!result.found_existing) {
            result.value_ptr.* = .empty;
        }
        for (result.value_ptr.items) |id| {
            if (std.mem.eql(u8, &id, &provider)) return;
        }
        try result.value_ptr.append(self.allocator, provider);
    }

    /// Find nodes that have content
    pub fn findProviders(self: *Kademlia, hash: ContentHash) []NodeId {
        if (self.providers.get(hash)) |list| {
            return list.items;
        }
        return &.{};
    }

    /// Find a peer by its node ID
    pub fn findPeerById(self: *Kademlia, id: NodeId) ?PeerInfo {
        self.mutex.lockUncancelable(app_io);
        defer self.mutex.unlock(app_io);
        const bucket_idx = self.bucketIndex(id);
        for (self.buckets[bucket_idx].peers) |slot| {
            if (slot) |peer| {
                if (std.mem.eql(u8, &peer.id, &id)) {
                    return peer;
                }
            }
        }
        // Also search all buckets as fallback (peer might be in wrong bucket temporarily)
        for (&self.buckets) |*bucket| {
            for (bucket.peers) |slot| {
                if (slot) |peer| {
                    if (std.mem.eql(u8, &peer.id, &id)) {
                        return peer;
                    }
                }
            }
        }
        return null;
    }

    /// Get total peer count across all buckets
    pub fn peerCount(self: *Kademlia) usize {
        var count: usize = 0;
        self.mutex.lockUncancelable(app_io);
        defer self.mutex.unlock(app_io);
        for (self.buckets) |bucket| {
            count += bucket.count;
        }
        return count;
    }

    /// Collect known peers across all buckets (up to out.len)
    pub fn collectPeers(self: *Kademlia, out: []PeerInfo) usize {
        var count: usize = 0;
        self.mutex.lockUncancelable(app_io);
        defer self.mutex.unlock(app_io);
        for (&self.buckets) |*bucket| {
            for (bucket.peers) |slot| {
                if (slot) |peer| {
                    if (count >= out.len) return count;
                    out[count] = peer;
                    count += 1;
                }
            }
        }
        return count;
    }

    /// Get random peers for gossip
    pub fn getRandomPeers(self: *Kademlia, out: []PeerInfo, rng: std.Random) usize {
        var all_peers: [MAX_PEERS]PeerInfo = undefined;
        var total: usize = 0;

        self.mutex.lockUncancelable(app_io);
        for (&self.buckets) |*bucket| {
            var peers: [K]PeerInfo = undefined;
            const n = bucket.getPeers(&peers);
            for (peers[0..n]) |peer| {
                if (total < all_peers.len) {
                    all_peers[total] = peer;
                    total += 1;
                }
            }
        }
        self.mutex.unlock(app_io);

        if (total == 0) return 0;

        // Fisher-Yates shuffle and take first N
        const count = @min(out.len, total);
        for (0..count) |i| {
            const j = i + rng.uintLessThan(usize, total - i);
            const tmp = all_peers[i];
            all_peers[i] = all_peers[j];
            all_peers[j] = tmp;
            out[i] = all_peers[i];
        }
        return count;
    }

    /// Generate a random node ID in a specific bucket's range (for refresh)
    pub fn randomIdInBucket(self: *const Kademlia, bucket_idx: usize, rng: std.Random) NodeId {
        var id = self.self_id;
        // Flip the bit at bucket_idx position
        const byte_idx = (ID_BITS - 1 - bucket_idx) / 8;
        const bit_idx: u3 = @intCast(7 - ((ID_BITS - 1 - bucket_idx) % 8));
        id[byte_idx] ^= @as(u8, 1) << bit_idx;
        // Randomize lower bits
        for ((byte_idx + 1)..20) |i| {
            id[i] = rng.int(u8);
        }
        return id;
    }
};

/// Replication manager for background replication
const ReplicationManager = struct {
    pending: std.ArrayListUnmanaged(ContentHash),
    target_replicas: u8,
    allocator: Allocator,

    pub fn init(allocator: Allocator) ReplicationManager {
        return .{
            .pending = .empty,
            .target_replicas = REPLICATION_TARGET,
            .allocator = allocator,
        };
    }

    pub fn deinit(self: *ReplicationManager) void {
        self.pending.deinit(self.allocator);
    }

    /// Schedule content for replication
    pub fn schedule(self: *ReplicationManager, hash: ContentHash) !void {
        // Avoid duplicates
        for (self.pending.items) |h| {
            if (std.mem.eql(u8, &h, &hash)) return;
        }
        try self.pending.append(self.allocator, hash);
    }
};

/// Distributed mode configuration
const DistributedConfig = struct {
    enabled: bool = false,
    node_id: NodeId = undefined,
    bootstrap_peers: []const []const u8 = &.{},
    target_replicas: u8 = REPLICATION_TARGET,
    http_port: u16 = 9000,
    gossip_interval_ms: u64 = GOSSIP_INTERVAL_MS,
};

/// Background worker: replicates blobs, propagates bucket ops, and gossips
/// with peers periodically — all off the request path so client writes only
/// pay for the (small, synchronous) metadata push.
const PushWorker = struct {
    const Job = union(enum) {
        blob: struct { hash: ContentHash },
        bucket: struct { name: []u8, deleted: bool, ts: i64 },
    };

    const POLL_INTERVAL_MS = 50;

    dist: *DistributedContext = undefined,
    mutex: std.Io.Mutex = .init,
    jobs: std.ArrayListUnmanaged(Job) = .empty,

    /// Called from the event-loop thread; job memory must be owned by
    /// std.heap.page_allocator (freed on the worker thread)
    pub fn enqueue(self: *PushWorker, job: Job) void {
        self.mutex.lockUncancelable(app_io);
        defer self.mutex.unlock(app_io);
        self.jobs.append(std.heap.page_allocator, job) catch return;
    }

    pub fn run(self: *PushWorker) void {
        const allocator = std.heap.page_allocator;
        const interval_ms: i64 = @intCast(self.dist.config.gossip_interval_ms);
        var last_gossip = std.Io.Clock.real.now(app_io).toMilliseconds();

        while (true) {
            self.mutex.lockUncancelable(app_io);
            const job: ?Job = if (self.jobs.items.len > 0) self.jobs.orderedRemove(0) else null;
            self.mutex.unlock(app_io);

            if (job) |j| {
                self.execute(allocator, j);
            } else {
                std.Io.sleep(app_io, .fromMilliseconds(POLL_INTERVAL_MS), .real) catch {};
            }

            const now = std.Io.Clock.real.now(app_io).toMilliseconds();
            if (now - last_gossip >= interval_ms) {
                last_gossip = now;
                gossipOnce(allocator, self.dist);
            }
        }
    }

    fn execute(self: *PushWorker, allocator: Allocator, job: Job) void {
        const dist = self.dist;
        switch (job) {
            .blob => |b| {
                broadcastAnnounce(dist, allocator, b.hash, dist.config.node_id);
                replicateBlob(dist, allocator, b.hash);
            },
            .bucket => |b| {
                defer std.heap.page_allocator.free(b.name);
                // Body carries the origin timestamp so peers can order create
                // vs delete (LWW, delete wins ties) regardless of arrival order.
                const path = if (b.deleted) "/_zs3/bucket_delete" else "/_zs3/bucket";
                const body = std.fmt.allocPrint(allocator, "{s}\n{d}", .{ b.name, b.ts }) catch return;
                defer allocator.free(body);
                broadcastToPeers(dist, allocator, "POST", path, body);
            },
        }
    }
};

/// One gossip round: refresh a few random peers (they also learn about us
/// via the ping handshake) and pull their peer lists to repair the mesh
fn gossipOnce(allocator: Allocator, dist: *DistributedContext) void {
    var peers: [MAX_BROADCAST_PEERS]PeerInfo = undefined;
    const n = dist.kademlia.collectPeers(&peers);
    if (n == 0) return;

    const rounds = @min(n, 3);
    var seed: u64 = undefined;
    app_io.random(std.mem.asBytes(&seed));
    var prng = std.Random.DefaultPrng.init(seed);
    const start = prng.random().uintLessThan(usize, n);
    for (0..rounds) |i| {
        const peer = peers[(start + i) % n];
        if (pingPeerAddress(allocator, dist, peer.address)) |fresh| {
            dist.kademlia.addPeer(fresh); // refreshes last_seen
        } else |_| {}
        discoverPeersFrom(allocator, dist, peer);
    }
}

/// Extended context for distributed mode
const DistributedContext = struct {
    config: DistributedConfig,
    cas: CAS,
    meta_index: MetaIndex,
    kademlia: Kademlia,
    replication: ReplicationManager,
    worker: PushWorker,
    bucket_ops: BucketOps,
    allocator: Allocator,

    pub fn init(allocator: Allocator, data_dir: []const u8, config: DistributedConfig) DistributedContext {
        return .{
            .config = config,
            .cas = .{ .data_dir = data_dir },
            .meta_index = .{ .data_dir = data_dir },
            .kademlia = Kademlia.init(allocator, config.node_id),
            .replication = ReplicationManager.init(allocator),
            .worker = .{},
            .bucket_ops = .{ .data_dir = data_dir },
            .allocator = allocator,
        };
    }

    pub fn deinit(self: *DistributedContext) void {
        self.kademlia.deinit();
        self.replication.deinit();
    }
};

pub fn main(init: std.process.Init) !void {
    app_io = init.io;
    const allocator = init.gpa;
    proc_env = init.environ_map;

    // Parse CLI arguments
    var distributed_enabled = false;
    var bootstrap_peers: [10][]const u8 = undefined;
    var bootstrap_count: usize = 0;
    var port: u16 = 9000;
    var gossip_interval_ms: u64 = GOSSIP_INTERVAL_MS;
    var data_dir: []const u8 = build_options.data_dir;
    var raw_acl_list: []const u8 = build_options.acl_list;
    var show_help: bool = false;

    var args = try init.minimal.args.iterateAllocator(allocator);
    defer args.deinit();
    _ = args.skip(); // Skip program name

    // Subcommands run without starting the server: snapshot / clone / snapshots.
    // Peek at the first argument before option parsing.
    var argv_list: std.ArrayListUnmanaged([]const u8) = .empty;
    defer argv_list.deinit(allocator);
    while (args.next()) |arg| {
        argv_list.append(allocator, arg) catch {
            return error.OutOfMemory;
        };
    }
    if (argv_list.items.len > 0) {
        const sub = argv_list.items[0];
        if (std.mem.eql(u8, sub, "snapshot")) {
            defer client_ca_bundle.deinit(allocator);
            runSnapshot(allocator, argv_list.items[1..]) catch |e| {
                if (e != error.BadArgs) std.debug.print("snapshot failed: {t}\n", .{e});
                std.process.exit(1);
            };
            return;
        } else if (std.mem.eql(u8, sub, "clone")) {
            defer client_ca_bundle.deinit(allocator);
            runClone(allocator, argv_list.items[1..]) catch |e| {
                if (e != error.BadArgs) std.debug.print("clone failed: {t}\n", .{e});
                std.process.exit(1);
            };
            return;
        } else if (std.mem.eql(u8, sub, "snapshots")) {
            defer client_ca_bundle.deinit(allocator);
            runSnapshotsList(allocator, argv_list.items[1..]) catch |e| {
                if (e != error.BadArgs) std.debug.print("snapshots failed: {t}\n", .{e});
                std.process.exit(1);
            };
            return;
        }
    }

    for (argv_list.items) |arg| {
        if (std.mem.eql(u8, arg, "--distributed") or std.mem.eql(u8, arg, "-d")) {
            distributed_enabled = true;
        } else if (std.mem.startsWith(u8, arg, "--data-dir=")) {
            data_dir = arg[11..];
        } else if (std.mem.startsWith(u8, arg, "--acl=")) {
            raw_acl_list = arg[6..];
        } else if (std.mem.startsWith(u8, arg, "--bootstrap=")) {
            const peers_str = arg[12..];
            var it = std.mem.splitScalar(u8, peers_str, ',');
            while (it.next()) |peer| {
                if (bootstrap_count < bootstrap_peers.len) {
                    bootstrap_peers[bootstrap_count] = peer;
                    bootstrap_count += 1;
                }
            }
        } else if (std.mem.startsWith(u8, arg, "--port=")) {
            port = std.fmt.parseInt(u16, arg[7..], 10) catch 9000;
        } else if (std.mem.startsWith(u8, arg, "--gossip-interval-ms=")) {
            gossip_interval_ms = std.fmt.parseInt(u64, arg[21..], 10) catch GOSSIP_INTERVAL_MS;
        } else if (std.mem.eql(u8, arg, "--fsync")) {
            enable_fsync = true;
        } else if (std.mem.eql(u8, arg, "--no-fsync") or std.mem.eql(u8, arg, "--fast")) {
            enable_fsync = false;
        } else if (std.mem.startsWith(u8, arg, "--sse-key-file=")) {
            sse_key_file_opt = arg[15..];
        } else if (std.mem.startsWith(u8, arg, "--lifecycle-interval-s=")) {
            lifecycle_interval_s = std.fmt.parseInt(u64, arg[23..], 10) catch LIFECYCLE_INTERVAL_S;
        } else if (std.mem.eql(u8, arg, "--help") or std.mem.eql(u8, arg, "-h")) {
            show_help = true;
        }
    }

    metrics.start_time_secs = std.Io.Clock.real.now(app_io).toSeconds();

    if (show_help) {
        std.debug.print(
            \\zs3 - Distributed S3-compatible storage
            \\
            \\Usage: zs3 [OPTIONS]
            \\       zs3 snapshot --bucket=BUCKET --name=NAME [--endpoint=URL]
            \\       zs3 clone --bucket=BUCKET --name=NAME --dest=DIR [--endpoint=URL]
            \\       zs3 snapshots --bucket=BUCKET [--endpoint=URL]
            \\
            \\Options:
            \\  --distributed, -d
            \\      Enable distributed mode (peer-to-peer)
            \\
            \\  --bootstrap=PEERS
            \\      Comma-separated bootstrap peer addresses
            \\
            \\  --gossip-interval-ms={d}
            \\      Interval for background peer gossip/refresh
            \\
            \\  --port={d}
            \\      HTTP port to listen on
            \\
            \\  --data-dir={s}
            \\      The directory to store bucket data under
            \\
            \\  --acl={s}
            \\      The credentials for access
            \\
            \\  --fsync / --no-fsync, --fast
            \\      fsync file contents on acknowledged writes (default: on).
            \\      --fast disables fsync for benchmarks; acknowledged writes may
            \\      then be lost on crash or power loss.
            \\
            \\  --sse-key-file=PATH
            \\      SSE-S3 master key (64 hex chars). Default: ZS3_SSE_KEY env, or
            \\      <data-dir>/.zs3/sse.key (generated on first use).
            \\
            \\  --lifecycle-interval-s={d}
            \\      How often lifecycle rules (expiration, noncurrent version
            \\      cleanup, incomplete multipart abort) are evaluated.
            \\
            \\  --help, -h
            \\      Show this help
            \\
            \\Snapshots:
            \\  snapshot  chunk a bucket into content-addressed chunks and store
            \\            a manifest at .zs3snapshots/<name>.json (only missing
            \\            chunks are uploaded)
            \\  clone     fetch a snapshot manifest and materialize it into DIR,
            \\            downloading only chunks the local cache lacks
            \\            (default cache: DIR/.zs3/blobs)
            \\  snapshots list snapshot names in a bucket
            \\
            \\  Snapshot flags: --endpoint=URL (or ZS3_ENDPOINT), --bucket=NAME,
            \\    --name=NAME, --dest=DIR, --cache=DIR, --access-key=K
            \\    (or AWS_ACCESS_KEY_ID), --secret-key=S (or AWS_SECRET_ACCESS_KEY),
            \\    --region=R (default us-east-1), --chunk-bytes=N (default 4MB),
            \\    --ca-file=PEM (or ZS3_CA_FILE) to trust a private CA for https://
            \\    endpoints, --insecure to skip TLS verification
            \\
            \\Examples:
            \\  zs3                                    # Standalone mode
            \\  zs3 --distributed                      # Distributed, auto-discover via mDNS
            \\  zs3 -d --bootstrap=10.0.0.1:9000       # Distributed with bootstrap peer
            \\  zs3 --fast                             # Benchmark mode (no fsync)
            \\  zs3 snapshot --bucket=artifacts --name=v1
            \\  zs3 clone --bucket=artifacts --name=v1 --dest=./v1
            \\
        , .{ GOSSIP_INTERVAL_MS, port, data_dir, raw_acl_list, LIFECYCLE_INTERVAL_S });
        return;
    }

    const access_control_list = acl.parseCredentials(allocator, raw_acl_list) catch |err| {
        std.log.err("Invalid --acl / -Dacl-list value: {s}", .{@errorName(err)});
        return err;
    };
    defer allocator.free(access_control_list);

    if (std.mem.eql(u8, raw_acl_list, "admin:minioadmin:minioadmin")) {
        std.log.warn("Using built-in default credentials (admin:minioadmin:minioadmin) — DO NOT USE IN PRODUCTION", .{});
    }

    std.Io.Dir.cwd().createDir(app_io, data_dir, .default_dir) catch |err| switch (err) {
        error.PathAlreadyExists => {},
        else => return err,
    };

    // Initialize distributed context if enabled
    var dist_ctx: ?DistributedContext = null;
    defer if (dist_ctx) |*d| d.deinit();

    if (distributed_enabled) {
        // Generate or load node ID
        const node_id = try getOrCreateNodeId(allocator, data_dir);
        const config = DistributedConfig{
            .enabled = true,
            .node_id = node_id,
            .bootstrap_peers = bootstrap_peers[0..bootstrap_count],
            .http_port = port,
            .gossip_interval_ms = gossip_interval_ms,
        };
        dist_ctx = DistributedContext.init(allocator, data_dir, config);

        var id_hex: [40]u8 = undefined;
        bytesToHex(&node_id, &id_hex);
        std.log.info("Distributed mode enabled. Node ID: {s}", .{id_hex});
        std.log.info("Known peers: {d}", .{dist_ctx.?.kademlia.peerCount()});

        // Create .cas and .index directories
        const dot_cas_path = try std.fs.path.join(allocator, &[_][]const u8{ data_dir, ".cas" });
        defer allocator.free(dot_cas_path);

        std.Io.Dir.cwd().createDir(app_io, dot_cas_path, .default_dir) catch |err| switch (err) {
            error.PathAlreadyExists => {},
            else => {
                return error.FailedDataDirDotCasCreation;
            },
        };

        const dot_index_path = try std.fs.path.join(allocator, &[_][]const u8{ data_dir, ".index" });
        defer allocator.free(dot_index_path);

        std.Io.Dir.cwd().createDir(app_io, dot_index_path, .default_dir) catch |err| switch (err) {
            error.PathAlreadyExists => {},
            else => {
                return error.FailedDataDirDotIndexCreation;
            },
        };
    }

    // Keys reference slices in raw_acl_list (argv or build_options string), both of
    // which outlive the process — safe to store as map keys without copying.
    var access_control_map = std.StringHashMap(acl.Credential).init(allocator);
    errdefer access_control_map.deinit();

    for (access_control_list) |credential| {
        const gop = try access_control_map.getOrPut(credential.access_key);
        if (gop.found_existing) {
            std.log.err("Duplicate access key '{s}' in ACL list", .{credential.access_key});
            return error.DuplicateAccessKey;
        }
        gop.value_ptr.* = credential;
    }

    var ctx = S3Context{
        .allocator = allocator,
        .data_dir = data_dir,
        .access_control_map = access_control_map,
        .distributed = if (dist_ctx != null) &dist_ctx.? else null,
    };
    sse_ctx = &ctx;
    // Lifecycle rules run on their own thread; filesystem renames/unlinks are
    // atomic so the request loop needs no lock.
    const lifecycle_thread = std.Thread.spawn(.{}, lifecycleThreadMain, .{&ctx}) catch |err| blk: {
        std.log.warn("lifecycle thread not started: {t}", .{err});
        break :blk null;
    };
    if (lifecycle_thread) |t| t.detach();

    defer ctx.deinit();

    const address = net.IpAddress.parseIp4("0.0.0.0", port) catch unreachable;
    var server = try address.listen(app_io, .{ .reuse_address = true });
    defer server.deinit(app_io);

    if (distributed_enabled) {
        std.log.info("dS3 server listening on http://0.0.0.0:{d}", .{port});
        bootstrapPeers(allocator, &ctx, &dist_ctx.?);

        // Background replication/gossip worker
        dist_ctx.?.worker.dist = &dist_ctx.?;
        const worker_thread = try std.Thread.spawn(.{}, PushWorker.run, .{&dist_ctx.?.worker});
        worker_thread.detach();
    } else {
        std.log.info("S3 server listening on http://0.0.0.0:{d}", .{port});
    }

    if (builtin.os.tag == .linux) {
        try eventLoopEpoll(allocator, &ctx, &server);
    } else if (builtin.os.tag == .macos) {
        try eventLoopKqueue(allocator, &ctx, &server);
    }
}

/// Generate or load persistent node ID
fn getOrCreateNodeId(allocator: Allocator, data_dir: []const u8) !NodeId {
    const id_path = try std.fs.path.join(allocator, &.{ data_dir, ".node_id" });
    defer allocator.free(id_path);

    // Try to load existing ID
    if (std.Io.Dir.cwd().openFile(app_io, id_path, .{})) |file| {
        defer file.close(app_io);
        var id: NodeId = undefined;
        const n = file.readPositionalAll(app_io, &id, 0) catch return error.InvalidNodeId;
        if (n == 20) return id;
    } else |_| {}

    // Generate new random ID
    var id: NodeId = undefined;
    try app_io.randomSecure(&id);

    // Save it
    if (std.Io.Dir.cwd().createFile(app_io, id_path, .{})) |file| {
        defer file.close(app_io);
        file.writeStreamingAll(app_io, &id) catch {};
    } else |_| {}

    return id;
}

/// Handshake with a peer: exchange node IDs (the peer also learns about us
/// via the X-Zs3-* headers) and return its PeerInfo
fn pingPeerAddress(allocator: Allocator, dist: *const DistributedContext, address: net.IpAddress) !PeerInfo {
    var stream = address.connect(app_io, .{ .mode = .stream }) catch return error.ConnectionFailed;
    defer stream.close(app_io);
    setPeerTimeout(stream);

    var self_id_hex: [40]u8 = undefined;
    bytesToHex(&dist.config.node_id, &self_id_hex);
    var request_buffer: [512]u8 = undefined;
    const request = std.fmt.bufPrint(
        &request_buffer,
        "GET /_zs3/ping HTTP/1.1\r\nHost: {f}\r\nX-Zs3-Node-Id: {s}\r\nX-Zs3-Port: {d}\r\nConnection: close\r\n\r\n",
        .{ address, self_id_hex, dist.config.http_port },
    ) catch return error.BufferTooSmall;
    try streamWriteAll(stream, request);

    var response_buffer = try allocator.alloc(u8, MAX_HEADER_SIZE);
    defer allocator.free(response_buffer);
    var total_read: usize = 0;
    while (total_read < response_buffer.len) {
        const count = streamRead(stream, response_buffer[total_read..]) catch break;
        if (count == 0) break;
        total_read += count;
    }

    const response = response_buffer[0..total_read];
    if (!std.mem.startsWith(u8, response, "HTTP/1.1 200")) return error.InvalidBootstrapResponse;

    const id_prefix = "\"id\":\"";
    const id_start = (std.mem.indexOf(u8, response, id_prefix) orelse return error.InvalidBootstrapResponse) + id_prefix.len;
    if (response.len < id_start + 40) return error.InvalidBootstrapResponse;

    var id: NodeId = undefined;
    _ = std.fmt.hexToBytes(&id, response[id_start .. id_start + 40]) catch return error.InvalidBootstrapResponse;

    return .{
        .id = id,
        .address = address,
        .last_seen = std.Io.Clock.real.now(app_io).toSeconds(),
        .content_count = 0,
    };
}

/// Learn about a bootstrap peer's peers, handshaking with each discovered
/// node so the connection graph becomes bidirectional. Uses the gossiped
/// "addr" field when present, falling back to the source's IP + gossiped
/// port for older peers.
fn discoverPeersFrom(allocator: Allocator, dist: *DistributedContext, source: PeerInfo) void {
    const body = peerRequest(allocator, source.address, "GET", "/_zs3/peers", "", 64 * 1024) catch return;
    defer allocator.free(body);

    var it = std.mem.splitSequence(u8, body, "\"id\":\"");
    _ = it.next(); // text before the first match
    while (it.next()) |chunk| {
        if (chunk.len < 40) continue;
        var id: NodeId = undefined;
        _ = std.fmt.hexToBytes(&id, chunk[0..40]) catch continue;
        if (std.mem.eql(u8, &id, &dist.config.node_id)) continue;
        if (dist.kademlia.findPeerById(id) != null) continue;

        const port_key = "\"port\":";
        const port_idx = std.mem.indexOf(u8, chunk, port_key) orelse continue;
        var port_end = port_idx + port_key.len;
        while (port_end < chunk.len and std.ascii.isDigit(chunk[port_end])) port_end += 1;
        const port = std.fmt.parseInt(u16, chunk[port_idx + port_key.len .. port_end], 10) catch continue;

        var address: net.IpAddress = fallback: {
            var a = source.address;
            a.setPort(port);
            break :fallback a;
        };
        const addr_key = "\"addr\":\"";
        if (std.mem.indexOf(u8, chunk, addr_key)) |addr_idx| {
            const addr_start = addr_idx + addr_key.len;
            if (std.mem.indexOfScalarPos(u8, chunk, addr_start, '"')) |addr_end| {
                if (net.IpAddress.parseLiteral(chunk[addr_start..addr_end])) |parsed| {
                    address = parsed;
                } else |_| {}
            }
        }

        const peer = pingPeerAddress(allocator, dist, address) catch continue;
        dist.kademlia.addPeer(peer);
    }
}

fn connectBootstrapPeer(allocator: Allocator, dist: *const DistributedContext, peer_text: []const u8) !PeerInfo {
    if (net.IpAddress.parseLiteral(peer_text)) |address| {
        return pingPeerAddress(allocator, dist, address);
    } else |_| {}

    const separator = std.mem.lastIndexOfScalar(u8, peer_text, ':') orelse return error.InvalidBootstrapPeer;
    const host_text = peer_text[0..separator];
    const port = std.fmt.parseInt(u16, peer_text[separator + 1 ..], 10) catch return error.InvalidBootstrapPeer;
    const host = net.HostName.init(host_text) catch return error.InvalidBootstrapPeer;

    var lookup_buffer: [16]net.HostName.LookupResult = undefined;
    var lookup_queue: std.Io.Queue(net.HostName.LookupResult) = .init(&lookup_buffer);
    try host.lookup(app_io, &lookup_queue, .{ .port = port });

    while (lookup_queue.getOne(app_io)) |result| switch (result) {
        .address => |address| {
            return pingPeerAddress(allocator, dist, address) catch continue;
        },
        .canonical_name => continue,
    } else |err| switch (err) {
        error.Closed => return error.BootstrapPeerNotFound,
        error.Canceled => return error.Canceled,
    }
}

fn bootstrapPeers(allocator: Allocator, ctx: *const S3Context, dist: *DistributedContext) void {
    for (dist.config.bootstrap_peers) |peer_text| {
        const peer = connectBootstrapPeer(allocator, dist, peer_text) catch |err| {
            std.log.warn("Failed to connect to bootstrap peer {s}: {t}", .{ peer_text, err });
            continue;
        };
        dist.kademlia.addPeer(peer);
        std.log.info("Connected to bootstrap peer {s}", .{peer_text});
        discoverPeersFrom(allocator, dist, peer);
        syncIndexFromPeer(allocator, ctx, peer);
    }
    std.log.info("Known peers: {d}", .{dist.kademlia.peerCount()});
}

/// Read from a socket, tolerating EAGAIN. The std netRead treats EAGAIN as a
/// programmer bug because it assumes the socket blocks, but peer sockets carry
/// an SO_RCVTIMEO (see setPeerTimeout) and return it when that timeout expires.
/// Poll for readability and retry; report an expired poll as error.Timeout.
fn streamRead(stream: net.Stream, buffer: []u8) !usize {
    const fd = stream.socket.handle;
    while (true) {
        const rc = posix.system.read(fd, buffer.ptr, buffer.len);
        switch (posix.errno(rc)) {
            .SUCCESS => return @intCast(rc),
            .INTR => continue,
            .AGAIN => {
                var pfd = [1]posix.pollfd{.{ .fd = fd, .events = posix.POLL.IN, .revents = 0 }};
                const ready = posix.poll(&pfd, PEER_IO_TIMEOUT_SECS * 1000) catch return error.ReadFailed;
                if (ready == 0) return error.Timeout;
            },
            .TIMEDOUT => return error.Timeout,
            .CONNRESET => return error.ConnectionResetByPeer,
            else => return error.ReadFailed,
        }
    }
}

fn streamWriteAll(stream: net.Stream, bytes: []const u8) !void {
    var written: usize = 0;
    while (written < bytes.len) {
        const data = [1][]const u8{bytes[written..]};
        const n = try app_io.vtable.netWrite(
            app_io.userdata,
            stream.socket.handle,
            "",
            &data,
            1,
        );
        if (n == 0) return error.ConnectionResetByPeer;
        written += n;
    }
}

fn readToEndAlloc(file: std.Io.File, allocator: Allocator, max_size: usize) ![]u8 {
    var file_reader = file.reader(app_io, &.{});
    return file_reader.interface.allocRemaining(allocator, .limited(max_size));
}

fn eventLoopEpoll(allocator: Allocator, ctx: *const S3Context, server: *net.Server) !void {
    const linux = std.os.linux;
    const epfd = linux.epoll_create1(linux.EPOLL.CLOEXEC);
    if (@as(isize, @bitCast(epfd)) < 0) return error.EpollCreate;
    defer _ = linux.close(@intCast(epfd));

    var ev = linux.epoll_event{ .events = linux.EPOLL.IN, .data = .{ .fd = server.socket.handle } };
    if (@as(isize, @bitCast(linux.epoll_ctl(@intCast(epfd), linux.EPOLL.CTL_ADD, server.socket.handle, &ev))) < 0)
        return error.EpollCtl;

    var events: [MAX_CONNECTIONS]linux.epoll_event = undefined;
    var peer_addresses = std.AutoHashMap(posix.fd_t, net.IpAddress).init(allocator);
    defer peer_addresses.deinit();

    while (true) {
        const n = linux.epoll_wait(@intCast(epfd), &events, MAX_CONNECTIONS, -1);
        if (@as(isize, @bitCast(n)) < 0) continue;

        for (events[0..n]) |event| {
            if (event.data.fd == server.socket.handle) {
                const conn = server.accept(app_io) catch continue;
                peer_addresses.put(conn.socket.handle, conn.socket.address) catch {
                    conn.close(app_io);
                    continue;
                };
                var cev = linux.epoll_event{ .events = linux.EPOLL.IN | linux.EPOLL.ONESHOT, .data = .{ .fd = conn.socket.handle } };
                _ = linux.epoll_ctl(@intCast(epfd), linux.EPOLL.CTL_ADD, conn.socket.handle, &cev);
            } else {
                const remote_address = peer_addresses.get(event.data.fd) orelse net.IpAddress{ .ip4 = net.Ip4Address.unspecified(0) };
                _ = peer_addresses.remove(event.data.fd);
                const stream = net.Stream{ .socket = .{ .handle = event.data.fd, .address = remote_address } };
                _ = handleConnectionWithStream(allocator, ctx, stream) catch {};
                _ = linux.epoll_ctl(@intCast(epfd), linux.EPOLL.CTL_DEL, event.data.fd, null);
                stream.close(app_io);
            }
        }
    }
}

fn eventLoopKqueue(allocator: Allocator, ctx: *const S3Context, server: *net.Server) !void {
    const c = std.c;
    const kq = c.kqueue();
    if (kq < 0) return error.Kqueue;
    defer _ = c.close(kq);

    const server_fd = server.socket.handle;
    var changes: [1]c.Kevent = .{.{
        .ident = @intCast(server_fd),
        .filter = c.EVFILT.READ,
        .flags = c.EV.ADD,
        .fflags = 0,
        .data = 0,
        .udata = 0,
    }};
    var events: [MAX_CONNECTIONS]c.Kevent = undefined;
    var peer_addresses = std.AutoHashMap(posix.fd_t, net.IpAddress).init(allocator);
    defer peer_addresses.deinit();
    if (c.kevent(kq, &changes, 1, &events, 0, null) < 0) return error.Kevent;

    while (true) {
        const nev = c.kevent(kq, &changes, 0, &events, MAX_CONNECTIONS, null);
        if (nev < 0) continue;

        for (events[0..@intCast(nev)]) |ev| {
            const fd: posix.fd_t = @intCast(ev.ident);
            if (fd == server_fd) {
                const conn = server.accept(app_io) catch continue;
                peer_addresses.put(conn.socket.handle, conn.socket.address) catch {
                    conn.close(app_io);
                    continue;
                };
                var add: [1]c.Kevent = .{.{
                    .ident = @intCast(conn.socket.handle),
                    .filter = c.EVFILT.READ,
                    .flags = c.EV.ADD | c.EV.ONESHOT,
                    .fflags = 0,
                    .data = 0,
                    .udata = 0,
                }};
                const r = c.kevent(kq, &add, 1, &events, 0, null);
                if (r < 0) std.log.err("kevent add failed", .{});
            } else {
                const remote_address = peer_addresses.get(fd) orelse net.IpAddress{ .ip4 = net.Ip4Address.unspecified(0) };
                _ = peer_addresses.remove(fd);
                const stream = net.Stream{ .socket = .{ .handle = fd, .address = remote_address } };
                const keep = handleConnectionWithStream(allocator, ctx, stream) catch false;
                if (keep) {
                    peer_addresses.put(fd, remote_address) catch {
                        stream.close(app_io);
                        continue;
                    };
                    var add: [1]c.Kevent = .{.{
                        .ident = @intCast(fd),
                        .filter = c.EVFILT.READ,
                        .flags = c.EV.ADD | c.EV.ONESHOT,
                        .fflags = 0,
                        .data = 0,
                        .udata = 0,
                    }};
                    _ = c.kevent(kq, &add, 1, &events, 0, null);
                } else {
                    stream.close(app_io);
                }
            }
        }
    }
}

const S3Context = struct {
    allocator: Allocator,
    data_dir: []const u8,
    access_control_map: std.StringHashMap(acl.Credential),
    distributed: ?*DistributedContext = null, // Optional distributed mode

    fn bucketPath(self: *const S3Context, allocator: Allocator, bucket: []const u8) ![]const u8 {
        return std.fs.path.join(allocator, &[_][]const u8{ self.data_dir, bucket });
    }

    fn objectPath(self: *const S3Context, allocator: Allocator, bucket: []const u8, key: []const u8) ![]const u8 {
        const path = try std.fs.path.join(allocator, &[_][]const u8{ self.data_dir, bucket, key });
        // The flat-file layout turns a key into a filesystem path. Reject keys
        // that cannot be stored on this platform with a clean client error
        // instead of a 500 when the OS returns ENAMETOOLONG:
        //   - a single component longer than NAME_MAX (255) cannot be a filename
        //   - the full path must fit PATH_MAX (e.g. 1024 on macOS)
        var component_itr = std.mem.splitScalar(u8, key, '/');
        while (component_itr.next()) |component| {
            if (component.len >= std.posix.NAME_MAX) {
                allocator.free(path);
                return error.NameTooLong;
            }
        }
        if (path.len >= std.posix.PATH_MAX) {
            allocator.free(path);
            return error.PathTooLong;
        }
        return path;
    }

    pub fn deinit(self: *S3Context) void {
        self.access_control_map.deinit();
    }
};

const Request = struct {
    method: []const u8,
    path: []const u8,
    query: []const u8,
    headers: std.StringHashMap([]const u8),
    body: []const u8,
    remote_address: net.IpAddress,

    fn header(self: *const Request, name: []const u8) ?[]const u8 {
        var lower_buf: [128]u8 = undefined;
        const lower_name = std.ascii.lowerString(&lower_buf, name);
        return self.headers.get(lower_name);
    }

    fn deinit(self: *Request) void {
        self.headers.deinit();
    }
};

const Response = struct {
    status: u16 = 200,
    status_text: []const u8 = "OK",
    headers: std.ArrayListUnmanaged(Header) = .empty,
    body: []const u8 = "",
    send_file: ?std.Io.File = null,
    send_file_size: usize = 0,
    send_file_offset: usize = 0,
    allocator: Allocator,

    const Header = struct { name: []const u8, value: []const u8 };

    fn init(allocator: Allocator) Response {
        return .{
            .allocator = allocator,
        };
    }

    fn deinit(self: *Response) void {
        self.headers.deinit(self.allocator);
        if (self.send_file) |f| f.close(app_io);
    }

    fn setHeader(self: *Response, name: []const u8, value: []const u8) void {
        self.headers.append(self.allocator, .{ .name = name, .value = value }) catch {};
    }

    fn ok(self: *Response) void {
        self.status = 200;
        self.status_text = "OK";
    }

    fn noContent(self: *Response) void {
        self.status = 204;
        self.status_text = "No Content";
    }

    fn setXmlBody(self: *Response, body: []const u8) void {
        self.setHeader("Content-Type", "application/xml");
        self.body = body;
    }

    fn setSendFile(self: *Response, file: std.Io.File, size: usize, offset: usize) void {
        self.send_file = file;
        self.send_file_size = size;
        self.send_file_offset = offset;
    }

    fn write(self: *Response, stream: net.Stream) !void {
        var buf: [8192]u8 = undefined;
        var w: std.Io.Writer = .fixed(&buf);

        try w.print("HTTP/1.1 {d} {s}\r\n", .{ self.status, self.status_text });

        // Check if Content-Length was already set via setHeader
        var has_content_length = false;
        for (self.headers.items) |h| {
            if (std.ascii.eqlIgnoreCase(h.name, "content-length")) {
                has_content_length = true;
                break;
            }
        }

        // Only add auto Content-Length if not already set
        if (!has_content_length) {
            const content_len = if (self.send_file != null) self.send_file_size else self.body.len;
            try w.print("Content-Length: {d}\r\n", .{content_len});
        }
        try w.writeAll("Connection: close\r\n");

        for (self.headers.items) |h| {
            try w.print("{s}: {s}\r\n", .{ h.name, h.value });
        }
        try w.writeAll("\r\n");

        try streamWriteAll(stream, w.buffered());

        if (self.send_file) |file| {
            // Use sendfile for zero-copy transfer
            if (builtin.os.tag == .macos) {
                var offset: i64 = @intCast(self.send_file_offset);
                var remaining: usize = self.send_file_size;
                while (remaining > 0) {
                    var len: i64 = @intCast(remaining);
                    const rc = std.c.sendfile(file.handle, stream.socket.handle, offset, &len, null, 0);
                    if (len > 0) {
                        offset += len;
                        remaining -= @intCast(len);
                    }
                    if (rc == -1) {
                        const e = std.c._errno().*;
                        if (e == @intFromEnum(std.posix.E.AGAIN) or e == @intFromEnum(std.posix.E.INTR)) {
                            app_io.sleep(.fromMilliseconds(1), .awake) catch {}; // 1ms
                            continue;
                        }
                        break;
                    }
                }
            } else if (builtin.os.tag == .linux) {
                var offset: i64 = @intCast(self.send_file_offset);
                var remaining: usize = self.send_file_size;
                while (remaining > 0) {
                    const rc = std.os.linux.sendfile(stream.socket.handle, file.handle, &offset, remaining);
                    const sent = @as(isize, @bitCast(rc));
                    if (sent <= 0) break;
                    remaining -= @intCast(sent);
                }
            }
        } else if (self.body.len > 0) {
            try streamWriteAll(stream, self.body);
        }
    }
};

fn parseRequestFromBuf(allocator: Allocator, data: []const u8, stream: net.Stream) !Request {
    const total_read = data.len;
    const line_end = std.mem.indexOf(u8, data, "\r\n") orelse return error.InvalidRequest;
    const request_line = data[0..line_end];

    var parts = std.mem.splitScalar(u8, request_line, ' ');
    const method = parts.next() orelse return error.InvalidRequest;
    const full_path = parts.next() orelse return error.InvalidRequest;
    var path: []const u8 = full_path;
    var query: []const u8 = "";
    if (std.mem.indexOf(u8, full_path, "?")) |q_idx| {
        path = full_path[0..q_idx];
        query = full_path[q_idx + 1 ..];
    }

    var headers = std.StringHashMap([]const u8).init(allocator);
    var header_section = data[line_end + 2 ..];
    const header_end = std.mem.indexOf(u8, header_section, "\r\n\r\n") orelse header_section.len;
    header_section = header_section[0..header_end];

    var header_lines = std.mem.splitSequence(u8, header_section, "\r\n");
    while (header_lines.next()) |line| {
        if (line.len == 0) continue;
        const colon = std.mem.indexOf(u8, line, ":") orelse continue;
        var name_buf: [128]u8 = undefined;
        const name = std.ascii.lowerString(&name_buf, std.mem.trim(u8, line[0..colon], " "));
        const value = std.mem.trim(u8, line[colon + 1 ..], " ");
        try headers.put(try allocator.dupe(u8, name), try allocator.dupe(u8, value));
    }

    var body: []const u8 = "";
    if (headers.get("content-length")) |cl_str| {
        const content_length = std.fmt.parseInt(usize, cl_str, 10) catch 0;
        if (content_length > MAX_BODY_SIZE) return error.PayloadTooLarge;
        if (content_length > 0) {
            // Handle Expect: 100-continue - send 100 Continue before reading body
            if (headers.get("expect")) |expect| {
                if (std.ascii.eqlIgnoreCase(expect, "100-continue")) {
                    streamWriteAll(stream, "HTTP/1.1 100 Continue\r\n\r\n") catch {};
                }
            }

            const body_start_idx = std.mem.indexOf(u8, data, "\r\n\r\n").? + 4;
            // Ensure we don't underflow: already_read = max(0, total_read - body_start_idx)
            const already_read = if (total_read > body_start_idx) total_read - body_start_idx else 0;
            // Cap already_read to content_length to prevent overflow in memcpy
            const bytes_to_copy = @min(already_read, content_length);

            const body_buf = try allocator.alloc(u8, content_length);
            if (bytes_to_copy > 0) {
                @memcpy(body_buf[0..bytes_to_copy], data[body_start_idx .. body_start_idx + bytes_to_copy]);
            }

            var remaining = content_length - bytes_to_copy;
            var offset = bytes_to_copy;
            while (remaining > 0) {
                const n = streamRead(stream, body_buf[offset..]) catch |err| {
                    // Handle non-blocking sockets - retry on WouldBlock
                    if (err == error.WouldBlock) {
                        app_io.sleep(.fromMilliseconds(1), .awake) catch {}; // 1ms sleep before retry
                        continue;
                    }
                    return err;
                };
                if (n == 0) break;
                offset += n;
                remaining -= n;
            }
            body = body_buf;

            // Decode AWS chunked transfer encoding if present. Any STREAMING-*
            // form carries chunk framing: the base
            // STREAMING-AWS4-HMAC-SHA256-PAYLOAD, the -TRAILER variants (with
            // trailing x-amz-checksum-* headers after the final 0 chunk, used
            // when a checksum algorithm is negotiated via
            // x-amz-sdk-checksum-algorithm), and STREAMING-UNSIGNED-PAYLOAD-TRAILER
            // (unsigned streaming with a trailing checksum). Trailers are
            // lifted into the header map below and verified against the
            // payload in route(). Plain UNSIGNED-PAYLOAD is raw bytes and must
            // NOT be decoded.
            if (headers.get("x-amz-content-sha256")) |sha| {
                if (std.mem.startsWith(u8, sha, "STREAMING-")) {
                    const decoded = try decodeAwsChunkedFull(allocator, body);
                    body = decoded.data;
                    // Fold trailer lines into the header map so a trailing
                    // checksum is indistinguishable from a header one to every
                    // downstream consumer (validation, persistence, echo).
                    var line_it = std.mem.splitSequence(u8, decoded.trailers, "\r\n");
                    while (line_it.next()) |line| {
                        const trimmed = std.mem.trim(u8, line, " \t");
                        if (trimmed.len == 0) continue;
                        const colon = std.mem.indexOfScalar(u8, trimmed, ':') orelse continue;
                        const raw_name = std.mem.trim(u8, trimmed[0..colon], " \t");
                        const value = std.mem.trim(u8, trimmed[colon + 1 ..], " \t");
                        if (raw_name.len == 0 or raw_name.len > 128) continue;
                        const name = try allocator.alloc(u8, raw_name.len);
                        _ = std.ascii.lowerString(name, raw_name);
                        try headers.put(name, value);
                    }
                }
            }
        }
    }

    return Request{
        .method = try allocator.dupe(u8, method),
        .path = try allocator.dupe(u8, path),
        .query = try allocator.dupe(u8, query),
        .headers = headers,
        .body = body,
        .remote_address = stream.socket.address,
    };
}

fn hasAuth(data: []const u8) bool {
    if (hasAuthHeader(data)) return true;
    // Query-string SigV4 (presigned URLs): the request line carries
    // X-Amz-Signature=... instead of an Authorization header.
    return hasQueryAuth(data);
}

/// Requests servable without credentials: the /_zs3/ subtree (peer protocol,
/// console, metrics), GET /metrics, and CORS preflights.
fn isPublicRequest(data: []const u8) bool {
    if (std.mem.indexOf(u8, data, "/_zs3/") != null) return true;
    const line_end = std.mem.indexOf(u8, data, "\r\n") orelse return false;
    const line = data[0..line_end];
    var parts = std.mem.splitScalar(u8, line, ' ');
    const method = parts.next() orelse return false;
    const target = parts.next() orelse return false;
    if (std.mem.eql(u8, method, "OPTIONS")) return true;
    var path = target;
    if (std.mem.indexOfScalar(u8, path, '?')) |q| path = path[0..q];
    return std.mem.eql(u8, path, "/metrics");
}

/// Cheap pre-parse gate for unsigned requests. Private deployments keep the
/// fast 403 (no body read); a request is only routed for the real ACL check
/// when its bucket has an ACL file or object ACLs have ever been used.
fn mayBeAnonymousAllowed(ctx: *const S3Context, data: []const u8) bool {
    const line_end = std.mem.indexOf(u8, data, "\r\n") orelse return false;
    var parts = std.mem.splitScalar(u8, data[0..line_end], ' ');
    _ = parts.next() orelse return false;
    var target = parts.next() orelse return false;
    if (std.mem.indexOfScalar(u8, target, '?')) |q| target = target[0..q];
    if (target.len > 0 and target[0] == '/') target = target[1..];
    const bucket = if (std.mem.indexOfScalar(u8, target, '/')) |sl| target[0..sl] else target;
    if (bucket.len == 0 or !isValidBucketName(bucket)) return false;
    var path_buf: [std.posix.PATH_MAX]u8 = undefined;
    const acl_path = std.fmt.bufPrint(&path_buf, "{s}/{s}/" ++ BUCKET_CFG_DIR ++ "/acl", .{ ctx.data_dir, bucket }) catch return false;
    if (std.Io.Dir.cwd().access(app_io, acl_path, .{})) |_| return true else |_| {}
    return objectAclsUsed(ctx);
}

var object_acls_used_cache: enum { unknown, no, yes } = .unknown;

/// Whether any object has ever been given a public ACL (persisted as a
/// marker file so the fast path stays correct across restarts).
fn objectAclsUsed(ctx: *const S3Context) bool {
    switch (object_acls_used_cache) {
        .yes => return true,
        .no => return false,
        .unknown => {},
    }
    var path_buf: [std.posix.PATH_MAX]u8 = undefined;
    const marker = std.fmt.bufPrint(&path_buf, "{s}/.zs3/object-acls", .{ctx.data_dir}) catch return false;
    if (std.Io.Dir.cwd().access(app_io, marker, .{})) |_| {
        object_acls_used_cache = .yes;
        return true;
    } else |_| {
        object_acls_used_cache = .no;
        return false;
    }
}

fn noteObjectAclUsed(ctx: *const S3Context) void {
    if (object_acls_used_cache == .yes) return;
    var path_buf: [std.posix.PATH_MAX]u8 = undefined;
    const marker = std.fmt.bufPrint(&path_buf, "{s}/.zs3/object-acls", .{ctx.data_dir}) catch return;
    if (std.fs.path.dirname(marker)) |d| std.Io.Dir.cwd().createDirPath(app_io, d) catch {};
    var f = std.Io.Dir.cwd().createFile(app_io, marker, .{}) catch return;
    f.close(app_io);
    object_acls_used_cache = .yes;
}

fn hasQueryAuth(data: []const u8) bool {
    // Scan only the request line (up to the first CRLF) for the presigned marker.
    const line_end = std.mem.indexOf(u8, data, "\r\n") orelse data.len;
    const line = data[0..line_end];
    const needle = "X-Amz-Signature=";
    if (line.len < needle.len) return false;
    var i: usize = 0;
    while (i + needle.len <= line.len) : (i += 1) {
        var match = true;
        for (needle, 0..) |c, j| {
            if (std.ascii.toLower(line[i + j]) != std.ascii.toLower(c)) {
                match = false;
                break;
            }
        }
        if (match) return true;
    }
    return false;
}

fn hasAuthHeader(data: []const u8) bool {
    if (data.len < 14) return false;
    const needle = "authorization:";
    const end = data.len - 13;
    var i: usize = 0;
    while (i < end) : (i += 1) {
        if (std.ascii.toLower(data[i]) == needle[0] and
            std.ascii.toLower(data[i + 1]) == needle[1] and
            std.ascii.toLower(data[i + 2]) == needle[2] and
            std.ascii.toLower(data[i + 3]) == needle[3] and
            std.ascii.toLower(data[i + 4]) == needle[4] and
            std.ascii.toLower(data[i + 5]) == needle[5] and
            std.ascii.toLower(data[i + 6]) == needle[6] and
            std.ascii.toLower(data[i + 7]) == needle[7] and
            std.ascii.toLower(data[i + 8]) == needle[8] and
            std.ascii.toLower(data[i + 9]) == needle[9] and
            std.ascii.toLower(data[i + 10]) == needle[10] and
            std.ascii.toLower(data[i + 11]) == needle[11] and
            std.ascii.toLower(data[i + 12]) == needle[12] and
            data[i + 13] == ':')
        {
            return true;
        }
    }
    return false;
}

fn findHeaderEnd(data: []const u8) ?usize {
    if (data.len < 4) return null;
    const end = data.len - 3;
    const ptr = data.ptr;
    var i: usize = 0;
    while (i < end) : (i += 1) {
        if (ptr[i] == '\r' and ptr[i + 1] == '\n' and ptr[i + 2] == '\r' and ptr[i + 3] == '\n') {
            return i;
        }
    }
    return null;
}

fn handleConnectionWithStream(allocator: Allocator, ctx: *const S3Context, stream: net.Stream) !bool {
    var buf: [MAX_HEADER_SIZE]u8 = undefined;
    var total_read: usize = 0;

    while (total_read < buf.len) {
        const n = streamRead(stream, buf[total_read..]) catch return false;
        if (n == 0) return false;
        total_read += n;
        if (findHeaderEnd(buf[0..total_read])) |_| break;
    }
    if (total_read == 0) return false;
    // If the 8KB buffer filled without seeing the header terminator, the
    // request headers exceed MAX_HEADER_SIZE. Reject cleanly instead of
    // parsing a truncated header section.
    if (findHeaderEnd(buf[0..total_read]) == null) {
        streamWriteAll(stream, ERROR_431) catch return false;
        // Give the client's remaining bytes a moment to arrive, then drain
        // them so the close is a clean FIN. Closing with unread data in the
        // receive buffer sends a RST, which discards the 431 response.
        app_io.sleep(.fromMilliseconds(1), .awake) catch {};
        var discard: [512]u8 = undefined;
        for (0..64) |_| {
            const n = streamRead(stream, &discard) catch break;
            if (n == 0) break;
        }
        return false;
    }

    const data = buf[0..total_read];

    // Requests that never need auth: peer protocol, CORS preflight, and the
    // public observability/console endpoints.
    if (!isPublicRequest(data) and !hasAuth(data) and !mayBeAnonymousAllowed(ctx, data)) {
        streamWriteAll(stream, ERROR_403) catch return false;
        return true;
    }

    var arena = std.heap.ArenaAllocator.init(allocator);
    defer arena.deinit();
    const alloc = arena.allocator();

    var req = parseRequestFromBuf(alloc, data, stream) catch |err| {
        if (err == error.PayloadTooLarge) {
            streamWriteAll(stream, ERROR_400_ENTITY_TOO_LARGE) catch return false;
        }
        return false;
    };
    var res = Response.init(alloc);

    route(ctx, alloc, &req, &res) catch |err| {
        switch (err) {
            error.PathTooLong, error.NameTooLong => sendError(&res, 400, "KeyTooLong", "Object key is too long for the filesystem (path or filename component limit)"),
            else => {
                std.log.err("Handler error: {}", .{err});
                sendError(&res, 500, "InternalError", "Internal server error");
            },
        }
    };

    res.write(stream) catch return false;
    return false;
}

pub fn isValidBucketName(name: []const u8) bool {
    if (name.len < 3 or name.len > MAX_BUCKET_LENGTH) return false;
    for (name) |c| {
        // S3 bucket names must be lowercase letters, numbers, hyphens, or dots
        // Uppercase letters are NOT allowed
        if (!std.ascii.isLower(c) and !std.ascii.isDigit(c) and c != '-' and c != '.') return false;
    }
    if (name[0] == '-' or name[0] == '.' or name[name.len - 1] == '-' or name[name.len - 1] == '.') return false;
    return true;
}

fn isValidUploadId(id: []const u8) bool {
    if (id.len == 0 or id.len > 64) return false;
    for (id) |c| {
        if (!std.ascii.isAlphanumeric(c) and c != '-' and c != '_') return false;
    }
    return true;
}

pub fn isValidKey(key: []const u8) bool {
    if (key.len == 0 or key.len > MAX_KEY_LENGTH) return false;
    for (key) |c| {
        if (c < 32 or c == 127) return false; // no control chars
    }
    // Block path traversal attempts
    if (std.mem.indexOf(u8, key, "..")) |_| return false;
    // Block absolute paths
    if (key[0] == '/') return false;
    return true;
}

fn route(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response) !void {
    metrics.requests += 1;
    defer {
        if (res.status >= 500) {
            metrics.errors_5xx += 1;
        } else if (res.status >= 400) {
            metrics.errors_4xx += 1;
        }
    }
    var path = req.path;
    if (path.len > 0 and path[0] == '/') path = path[1..];

    // CORS preflight: browsers send OPTIONS without credentials. Answer
    // directly so the embedded console and direct-upload flows work.
    if (std.mem.eql(u8, req.method, "OPTIONS")) {
        res.status = 200;
        res.status_text = "OK";
        res.setHeader("Access-Control-Allow-Origin", "*");
        res.setHeader("Access-Control-Allow-Methods", "GET, HEAD, PUT, POST, DELETE, OPTIONS");
        res.setHeader("Access-Control-Allow-Headers", "authorization, x-amz-date, x-amz-content-sha256, content-type, x-amz-meta-*, x-amz-copy-source, range");
        res.setHeader("Access-Control-Expose-Headers", "ETag, Content-Length, Content-Type, Content-Range, x-amz-meta-*, x-amz-version-id");
        res.setHeader("Content-Length", "0");
        return;
    }

    // Public observability + console endpoints (no auth; safe to expose).
    if (std.mem.eql(u8, path, "metrics") and std.mem.eql(u8, req.method, "GET")) {
        try handleMetrics(ctx, allocator, res);
        return;
    }

    // Verify client-supplied payload checksums before anything is stored.
    // Covers the header form and the trailer form from STREAMING-*-TRAILER
    // uploads. CopyObject is exempt: its checksum headers describe the
    // destination object, not this (empty) request body.
    if (std.mem.eql(u8, req.method, "PUT") and req.header("x-amz-copy-source") == null) {
        if (try mismatchedChecksum(allocator, req)) |bad| {
            const msg = try std.fmt.allocPrint(allocator, "The {s} you specified did not match what we received", .{bad});
            sendError(res, 400, "XAmzContentChecksumMismatch", msg);
            return;
        }
    }

    // Handle peer protocol (no auth required for peer-to-peer)
    if (std.mem.startsWith(u8, path, "_zs3/")) {
        const sub = path[5..];
        // Console and metrics are served in both standalone and distributed mode.
        if (std.mem.eql(u8, sub, "console") and std.mem.eql(u8, req.method, "GET")) {
            handleConsole(allocator, res);
            return;
        }
        if (std.mem.eql(u8, sub, "metrics") and std.mem.eql(u8, req.method, "GET")) {
            try handleMetrics(ctx, allocator, res);
            return;
        }
        if (ctx.distributed) |dist| {
            try handlePeerProtocol(ctx, dist, allocator, req, res, sub);
        } else {
            sendError(res, 404, "NotFound", "Distributed mode not enabled");
        }
        return;
    }

    var acl_ctx = SigV4.verify(ctx, req, allocator);
    if (!acl_ctx.authenticated) {
        // Fall back to query-string SigV4 (presigned URLs).
        acl_ctx = SigV4.verifyPresigned(ctx, req, allocator);
    }

    // Split the raw path, then decode each segment: the filesystem stores
    // decoded names, while SigV4 above verified the raw (encoded) form.
    // Segments split before decoding so a literal %2F inside a key survives
    // as data rather than splitting the key.
    var path_parts = std.mem.splitScalar(u8, path, '/');
    const raw_bucket = path_parts.next() orelse "";
    const raw_key = path_parts.rest();
    const bucket = try uriDecodePath(allocator, raw_bucket);
    var key_buf: std.ArrayListUnmanaged(u8) = .empty;
    defer key_buf.deinit(allocator);
    var seg_iter = std.mem.splitScalar(u8, raw_key, '/');
    var first_seg = true;
    while (seg_iter.next()) |seg| {
        if (!first_seg) try key_buf.append(allocator, '/');
        first_seg = false;
        const dec = try uriDecodePath(allocator, seg);
        defer allocator.free(dec);
        try key_buf.appendSlice(allocator, dec);
    }
    var key: []const u8 = try key_buf.toOwnedSlice(allocator);

    if (bucket.len > 0 and !isValidBucketName(bucket)) {
        sendError(res, 400, "InvalidBucketName", "Bucket name is invalid");
        return;
    }
    if (key.len > 0 and !isValidKey(key)) {
        sendError(res, 400, "InvalidKey", "Object key is invalid");
        return;
    }

    // Unsigned requests are allowed only what the bucket/object ACL grants.
    if (!acl_ctx.authenticated) {
        if (anonymousRole(ctx, allocator, req, bucket, key)) |role| {
            acl_ctx = .{ .authenticated = true, .role = role, .anonymous = true };
        } else {
            sendError(res, 403, "AccessDenied", "Invalid credentials");
            return;
        }
    }
    if (!acl_ctx.granted(req.method)) {
        sendError(res, 403, "AccessDenied", "Insufficient permissions");
        return;
    }

    // Legacy fallback: objects written before path decoding are stored
    // encoded; prefer whichever file exists.
    key = try resolveLegacyKey(ctx, allocator, bucket, key, raw_key);

    // ?acl, ?tagging, ?versioning, ?versions, ?lifecycle, ?encryption
    if (try routeSubresource(ctx, allocator, req, res, bucket, key, acl_ctx.anonymous)) return;

    // Public-read-write grants object writes, never bucket create/delete.
    if (acl_ctx.anonymous and key.len == 0 and !std.mem.eql(u8, req.method, "GET") and !std.mem.eql(u8, req.method, "HEAD") and !hasQuery(req.query, "delete")) {
        sendError(res, 403, "AccessDenied", "Anonymous requests cannot create or delete buckets");
        return;
    }

    // In distributed mode, use CAS for object storage
    if (ctx.distributed != null) {
        if (key.len > 0) {
            if (std.mem.eql(u8, req.method, "PUT") and !hasQuery(req.query, "uploadId")) {
                if (req.header("x-amz-copy-source")) |_| {
                    try handleCopyObject(ctx, allocator, req, res, bucket, key);
                    return;
                }
                try handleDistributedPut(ctx, allocator, req, res, bucket, key);
                return;
            } else if (std.mem.eql(u8, req.method, "GET") and !hasQuery(req.query, "uploadId")) {
                try handleDistributedGet(ctx, allocator, req, res, bucket, key);
                return;
            } else if (std.mem.eql(u8, req.method, "DELETE") and !hasQuery(req.query, "uploadId")) {
                try handleDistributedDelete(ctx, allocator, res, bucket, key);
                return;
            } else if (std.mem.eql(u8, req.method, "HEAD")) {
                try handleDistributedHead(ctx, allocator, req, res, bucket, key);
                return;
            }
        } else if (bucket.len > 0 and std.mem.eql(u8, req.method, "GET")) {
            // Distributed LIST objects
            try handleDistributedList(ctx, allocator, req, res, bucket);
            return;
        }
    }

    // Standard S3 routing (standalone mode or bucket operations)
    if (std.mem.eql(u8, req.method, "GET")) {
        if (bucket.len == 0) {
            try handleListBuckets(ctx, allocator, res);
        } else if (key.len == 0) {
            try handleListObjects(ctx, allocator, req, res, bucket);
        } else if (hasQuery(req.query, "uploadId")) {
            try handleListParts(ctx, allocator, req, res, bucket, key);
        } else {
            try handleGetObject(ctx, allocator, req, res, bucket, key);
        }
    } else if (std.mem.eql(u8, req.method, "PUT")) {
        if (key.len == 0) {
            try handleCreateBucket(ctx, allocator, req, res, bucket);
        } else if (hasQuery(req.query, "uploadId")) {
            if (req.header("x-amz-copy-source")) |_| {
                try handleUploadPartCopy(ctx, allocator, req, res, bucket, key);
            } else {
                try handleUploadPart(ctx, allocator, req, res, bucket, key);
            }
        } else if (req.header("x-amz-copy-source")) |_| {
            try handleCopyObject(ctx, allocator, req, res, bucket, key);
        } else {
            try handlePutObject(ctx, allocator, req, res, bucket, key);
        }
    } else if (std.mem.eql(u8, req.method, "DELETE")) {
        if (key.len == 0) {
            try handleDeleteBucket(ctx, allocator, res, bucket);
        } else if (hasQuery(req.query, "uploadId")) {
            try handleAbortMultipart(ctx, allocator, req, res);
        } else {
            try handleDeleteObject(ctx, allocator, req, res, bucket, key);
        }
    } else if (std.mem.eql(u8, req.method, "HEAD")) {
        if (key.len == 0) {
            try handleHeadBucket(ctx, allocator, res, bucket);
        } else {
            try handleHeadObject(ctx, allocator, req, res, bucket, key);
        }
    } else if (std.mem.eql(u8, req.method, "POST")) {
        if (hasQuery(req.query, "delete")) {
            try handleDeleteObjects(ctx, allocator, req, res, bucket);
        } else if (hasQuery(req.query, "uploads")) {
            try handleInitiateMultipart(ctx, allocator, req, res, bucket, key);
        } else if (hasQuery(req.query, "uploadId")) {
            try handleCompleteMultipart(ctx, allocator, req, res, bucket, key);
        } else {
            sendError(res, 400, "InvalidRequest", "Unknown POST operation");
        }
    } else {
        sendError(res, 405, "MethodNotAllowed", "Method not allowed");
    }
}

pub const SigV4 = struct {
    const HmacSha256 = std.crypto.auth.hmac.sha2.HmacSha256;
    const Sha256 = std.crypto.hash.sha2.Sha256;

    const ParsedAuth = struct {
        access_key: []const u8,
        date: []const u8,
        region: []const u8,
        service: []const u8,
        signed_headers: []const u8,
        signature: []const u8,
    };

    const ACLCtx = struct {
        authenticated: bool,
        role: ?acl.Role,
        /// Granted by a public ACL rather than a signature.
        anonymous: bool = false,

        fn granted(self: *const ACLCtx, method: []const u8) bool {
            const role = self.role orelse return false;
            return acl.roleAllowsMethod(role, method);
        }
    };

    fn verify(ctx: *const S3Context, req: *const Request, allocator: Allocator) ACLCtx {
        var acl_ctx = ACLCtx{
            .authenticated = false,
            .role = null,
        };

        const auth_header = req.header("authorization") orelse return acl_ctx;
        const x_amz_date = req.header("x-amz-date") orelse return acl_ctx;
        const x_amz_content_sha256 = req.header("x-amz-content-sha256") orelse "UNSIGNED-PAYLOAD";

        const parsed = parseAuthHeader(auth_header) orelse return acl_ctx;
        const credential = ctx.access_control_map.get(parsed.access_key);

        if (credential == null) {
            return acl_ctx;
        }

        const canonical = buildCanonicalRequest(
            allocator,
            req,
            parsed.signed_headers,
            x_amz_content_sha256,
        ) catch return acl_ctx;
        defer allocator.free(canonical);

        const string_to_sign = buildStringToSign(
            allocator,
            x_amz_date,
            parsed.date,
            parsed.region,
            parsed.service,
            canonical,
        ) catch return acl_ctx;
        defer allocator.free(string_to_sign);

        const calculated_sig = calculateSignature(
            allocator,
            credential.?.secret_key,
            parsed.date,
            parsed.region,
            parsed.service,
            string_to_sign,
        ) catch return acl_ctx;
        defer allocator.free(calculated_sig);

        if (std.mem.eql(u8, calculated_sig, parsed.signature)) {
            acl_ctx.authenticated = true;
            acl_ctx.role = credential.?.role;
        }

        return acl_ctx;
    }

    /// Verify query-string SigV4 (presigned URLs). The signature covers the
    /// method, path, and all X-Amz-* query params except X-Amz-Signature
    /// itself, with payload UNSIGNED-PAYLOAD. Expiry (X-Amz-Date + X-Amz-Expires)
    /// is enforced against the server clock.
    fn verifyPresigned(ctx: *const S3Context, req: *const Request, allocator: Allocator) ACLCtx {
        var acl_ctx = ACLCtx{
            .authenticated = false,
            .role = null,
        };
        const signature = getQueryParam(req.query, "X-Amz-Signature") orelse return acl_ctx;
        const algorithm = getQueryParam(req.query, "X-Amz-Algorithm") orelse return acl_ctx;
        if (!std.mem.eql(u8, algorithm, "AWS4-HMAC-SHA256")) return acl_ctx;
        const credential_scope = getQueryParam(req.query, "X-Amz-Credential") orelse return acl_ctx;
        const amz_date = getQueryParam(req.query, "X-Amz-Date") orelse return acl_ctx;
        const expires_str = getQueryParam(req.query, "X-Amz-Expires") orelse return acl_ctx;
        const signed_headers = getQueryParam(req.query, "X-Amz-SignedHeaders") orelse return acl_ctx;

        // Credential is URL-encoded (slashes become %2F); decode before splitting.
        const cred_decoded = uriDecode(allocator, credential_scope) catch return acl_ctx;
        defer allocator.free(cred_decoded);
        var cred_iter = std.mem.splitScalar(u8, cred_decoded, '/');
        const access_key = cred_iter.next() orelse return acl_ctx;
        const date_stamp = cred_iter.next() orelse return acl_ctx;
        const region = cred_iter.next() orelse return acl_ctx;
        const service = cred_iter.next() orelse return acl_ctx;

        // Enforce expiry: request time + expires must still be in the future.
        const expires_secs = std.fmt.parseInt(i64, expires_str, 10) catch return acl_ctx;
        const req_time = parseAmzDate(amz_date) orelse return acl_ctx;
        const now = std.Io.Clock.real.now(app_io).toSeconds();
        if (now > req_time + expires_secs) return acl_ctx;

        const credential = ctx.access_control_map.get(access_key) orelse return acl_ctx;

        // Canonical query without the signature itself.
        const query_no_sig = stripQueryParam(allocator, req.query, "X-Amz-Signature") catch return acl_ctx;
        defer allocator.free(query_no_sig);
        const sorted_query = sortQueryString(allocator, query_no_sig) catch return acl_ctx;
        defer allocator.free(sorted_query);

        const canonical = buildCanonicalRequestWithQuery(allocator, req, signed_headers, "UNSIGNED-PAYLOAD", sorted_query) catch return acl_ctx;
        defer allocator.free(canonical);

        const string_to_sign = buildStringToSign(allocator, amz_date, date_stamp, region, service, canonical) catch return acl_ctx;
        defer allocator.free(string_to_sign);

        const calculated_sig = calculateSignature(allocator, credential.secret_key, date_stamp, region, service, string_to_sign) catch return acl_ctx;
        defer allocator.free(calculated_sig);

        if (std.mem.eql(u8, calculated_sig, signature)) {
            acl_ctx.authenticated = true;
            acl_ctx.role = credential.role;
        }
        return acl_ctx;
    }

    /// Parse an X-Amz-Date like 20250102T150405Z to Unix seconds (UTC).
    fn parseAmzDate(s: []const u8) ?i64 {
        if (s.len < 16) return null;
        // Basic format YYYYMMDDTHHMMSSZ
        const year = std.fmt.parseInt(i32, s[0..4], 10) catch return null;
        const month = std.fmt.parseInt(u8, s[4..6], 10) catch return null;
        const day = std.fmt.parseInt(u8, s[6..8], 10) catch return null;
        if (s[8] != 'T') return null;
        const hour = std.fmt.parseInt(u8, s[9..11], 10) catch return null;
        const min = std.fmt.parseInt(u8, s[11..13], 10) catch return null;
        const sec = std.fmt.parseInt(u8, s[13..15], 10) catch return null;
        if (month < 1 or month > 12 or day < 1 or day > 31 or hour > 23 or min > 59 or sec > 60) return null;
        const days = daysFromCivil(year, month, day);
        return days * 86400 + @as(i64, hour) * 3600 + @as(i64, min) * 60 + sec;
    }

    fn daysFromCivil(y: i32, m: u8, d: u8) i64 {
        const yy: i64 = if (m <= 2) @as(i64, y) - 1 else y;
        const era: i64 = @divFloor(if (yy >= 0) yy else yy - 399, 400);
        const yoe: i64 = yy - era * 400;
        const mp: i64 = @as(i64, m) + (if (m > 2) @as(i64, -3) else @as(i64, 9));
        const doy: i64 = @divFloor(153 * mp + 2, 5) + @as(i64, d) - 1;
        const doe: i64 = yoe * 365 + @divFloor(yoe, 4) - @divFloor(yoe, 100) + doy;
        return era * 146097 + doe - 719468;
    }

    /// Return the query string with one parameter removed (used to drop
    /// X-Amz-Signature before canonicalizing a presigned request).
    fn stripQueryParam(allocator: Allocator, query: []const u8, key: []const u8) ![]const u8 {
        var out: std.ArrayListUnmanaged(u8) = .empty;
        errdefer out.deinit(allocator);
        var first = true;
        var iter = std.mem.splitScalar(u8, query, '&');
        while (iter.next()) |pair| {
            if (pair.len == 0) continue;
            const eq = std.mem.indexOfScalar(u8, pair, '=');
            const name = if (eq) |e| pair[0..e] else pair;
            if (std.mem.eql(u8, name, key)) continue;
            if (!first) try out.append(allocator, '&');
            first = false;
            try out.appendSlice(allocator, pair);
        }
        return out.toOwnedSlice(allocator);
    }

    pub fn parseAuthHeader(header: []const u8) ?ParsedAuth {
        if (!std.mem.startsWith(u8, header, "AWS4-HMAC-SHA256 ")) return null;

        var result: ParsedAuth = undefined;

        const cred_start = std.mem.indexOf(u8, header, "Credential=") orelse return null;
        const cred_end = std.mem.indexOfPos(u8, header, cred_start, ",") orelse return null;
        const credential = header[cred_start + 11 .. cred_end];

        var cred_iter = std.mem.splitScalar(u8, credential, '/');
        result.access_key = cred_iter.next() orelse return null;
        result.date = cred_iter.next() orelse return null;
        result.region = cred_iter.next() orelse return null;
        result.service = cred_iter.next() orelse return null;

        const sh_start = std.mem.indexOf(u8, header, "SignedHeaders=") orelse return null;
        const sh_end = std.mem.indexOfPos(u8, header, sh_start, ",") orelse return null;
        result.signed_headers = header[sh_start + 14 .. sh_end];

        const sig_start = std.mem.indexOf(u8, header, "Signature=") orelse return null;
        result.signature = header[sig_start + 10 ..];

        return result;
    }

    fn buildCanonicalRequest(
        allocator: Allocator,
        req: *const Request,
        signed_headers: []const u8,
        payload_hash: []const u8,
    ) ![]const u8 {
        var result: std.ArrayListUnmanaged(u8) = .empty;
        errdefer result.deinit(allocator);

        try result.appendSlice(allocator, req.method);
        try result.append(allocator, '\n');

        // S3 uses single URI encoding — the path from the HTTP request line
        // is already URI-encoded, so use it as-is (no double-encoding)
        const canonical_path = if (req.path.len == 0) "/" else req.path;
        try result.appendSlice(allocator, canonical_path);
        try result.append(allocator, '\n');

        const sorted_query = try sortQueryString(allocator, req.query);
        defer allocator.free(sorted_query);
        try result.appendSlice(allocator, sorted_query);
        try result.append(allocator, '\n');

        var header_iter = std.mem.splitScalar(u8, signed_headers, ';');
        while (header_iter.next()) |header_name| {
            const value = req.header(header_name) orelse "";
            try result.appendSlice(allocator, header_name);
            try result.append(allocator, ':');
            try result.appendSlice(allocator, std.mem.trim(u8, value, " \t"));
            try result.append(allocator, '\n');
        }
        try result.append(allocator, '\n');

        try result.appendSlice(allocator, signed_headers);
        try result.append(allocator, '\n');

        try result.appendSlice(allocator, payload_hash);

        return result.toOwnedSlice(allocator);
    }

    fn buildCanonicalRequestWithQuery(
        allocator: Allocator,
        req: *const Request,
        signed_headers: []const u8,
        payload_hash: []const u8,
        sorted_query: []const u8,
    ) ![]const u8 {
        var result: std.ArrayListUnmanaged(u8) = .empty;
        errdefer result.deinit(allocator);

        try result.appendSlice(allocator, req.method);
        try result.append(allocator, '\n');

        const canonical_path = if (req.path.len == 0) "/" else req.path;
        try result.appendSlice(allocator, canonical_path);
        try result.append(allocator, '\n');

        try result.appendSlice(allocator, sorted_query);
        try result.append(allocator, '\n');

        // Signed headers are lowercase per SigV4; presigned URLs sign `host`
        // at minimum. Values come from the live request headers.
        var header_iter = std.mem.splitScalar(u8, signed_headers, ';');
        while (header_iter.next()) |header_name| {
            var lower_buf: [128]u8 = undefined;
            const lower = if (header_name.len <= lower_buf.len) std.ascii.lowerString(&lower_buf, header_name) else header_name;
            const value = req.header(lower) orelse req.header(header_name) orelse "";
            try result.appendSlice(allocator, lower);
            try result.append(allocator, ':');
            try result.appendSlice(allocator, std.mem.trim(u8, value, " \t"));
            try result.append(allocator, '\n');
        }
        try result.append(allocator, '\n');

        try result.appendSlice(allocator, signed_headers);
        try result.append(allocator, '\n');

        try result.appendSlice(allocator, payload_hash);

        return result.toOwnedSlice(allocator);
    }

    fn buildStringToSign(
        allocator: Allocator,
        amz_date: []const u8,
        date_stamp: []const u8,
        region: []const u8,
        service: []const u8,
        canonical_request: []const u8,
    ) ![]const u8 {
        var result: std.ArrayListUnmanaged(u8) = .empty;
        errdefer result.deinit(allocator);

        try result.appendSlice(allocator, "AWS4-HMAC-SHA256\n");
        try result.appendSlice(allocator, amz_date);
        try result.append(allocator, '\n');

        try result.appendSlice(allocator, date_stamp);
        try result.append(allocator, '/');
        try result.appendSlice(allocator, region);
        try result.append(allocator, '/');
        try result.appendSlice(allocator, service);
        try result.appendSlice(allocator, "/aws4_request\n");

        const canonical_hash = hash(canonical_request);
        var hex_buf: [64]u8 = undefined;
        _ = std.fmt.bufPrint(&hex_buf, "{x}", .{canonical_hash}) catch unreachable;
        try result.appendSlice(allocator, &hex_buf);

        return result.toOwnedSlice(allocator);
    }

    fn calculateSignature(
        allocator: Allocator,
        secret_key: []const u8,
        date_stamp: []const u8,
        region: []const u8,
        service: []const u8,
        string_to_sign: []const u8,
    ) ![]const u8 {
        var k_secret_buf: [256]u8 = undefined;
        const k_secret_len = 4 + secret_key.len;
        @memcpy(k_secret_buf[0..4], "AWS4");
        @memcpy(k_secret_buf[4..k_secret_len], secret_key);

        const k_date = hmac(k_secret_buf[0..k_secret_len], date_stamp);
        const k_region = hmac(&k_date, region);
        const k_service = hmac(&k_region, service);
        const k_signing = hmac(&k_service, "aws4_request");
        const sig = hmac(&k_signing, string_to_sign);

        const hex = try allocator.alloc(u8, 64);
        _ = std.fmt.bufPrint(hex, "{x}", .{sig}) catch unreachable;

        return hex;
    }

    pub fn hmac(key: []const u8, msg: []const u8) [32]u8 {
        var out: [32]u8 = undefined;
        HmacSha256.create(&out, msg, key);
        return out;
    }

    pub fn hash(data: []const u8) [32]u8 {
        var out: [32]u8 = undefined;
        Sha256.hash(data, &out, .{});
        return out;
    }
};

pub fn uriEncode(allocator: Allocator, input: []const u8, encode_slash: bool) ![]const u8 {
    var result: std.ArrayListUnmanaged(u8) = .empty;
    errdefer result.deinit(allocator);

    for (input) |c| {
        if (isUnreserved(c) or (c == '/' and !encode_slash)) {
            try result.append(allocator, c);
        } else {
            try result.append(allocator, '%');
            const hex = "0123456789ABCDEF";
            try result.append(allocator, hex[c >> 4]);
            try result.append(allocator, hex[c & 0x0F]);
        }
    }

    return result.toOwnedSlice(allocator);
}

fn isUnreserved(c: u8) bool {
    return (c >= 'A' and c <= 'Z') or
        (c >= 'a' and c <= 'z') or
        (c >= '0' and c <= '9') or
        c == '-' or c == '.' or c == '_' or c == '~';
}

pub fn uriDecode(allocator: Allocator, input: []const u8) ![]const u8 {
    var result: std.ArrayListUnmanaged(u8) = .empty;
    errdefer result.deinit(allocator);

    var i: usize = 0;
    while (i < input.len) {
        if (input[i] == '%' and i + 2 < input.len) {
            const high = hexDigitToInt(input[i + 1]) orelse {
                try result.append(allocator, input[i]);
                i += 1;
                continue;
            };
            const low = hexDigitToInt(input[i + 2]) orelse {
                try result.append(allocator, input[i]);
                i += 1;
                continue;
            };
            try result.append(allocator, (high << 4) | low);
            i += 3;
        } else if (input[i] == '+') {
            try result.append(allocator, ' ');
            i += 1;
        } else {
            try result.append(allocator, input[i]);
            i += 1;
        }
    }

    return result.toOwnedSlice(allocator);
}

fn hexDigitToInt(c: u8) ?u8 {
    if (c >= '0' and c <= '9') return c - '0';
    if (c >= 'A' and c <= 'F') return c - 'A' + 10;
    if (c >= 'a' and c <= 'f') return c - 'a' + 10;
    return null;
}

/// Decode %XX sequences in a URL path segment. Unlike uriDecode, '+' is left
/// alone: in paths it is a literal plus (RFC 3986), not a space — only query
/// strings use '+'-for-space.
pub fn uriDecodePath(allocator: Allocator, input: []const u8) ![]const u8 {
    var result: std.ArrayListUnmanaged(u8) = .empty;
    errdefer result.deinit(allocator);

    var i: usize = 0;
    while (i < input.len) {
        if (input[i] == '%' and i + 2 < input.len) {
            const high = hexDigitToInt(input[i + 1]) orelse {
                try result.append(allocator, input[i]);
                i += 1;
                continue;
            };
            const low = hexDigitToInt(input[i + 2]) orelse {
                try result.append(allocator, input[i]);
                i += 1;
                continue;
            };
            try result.append(allocator, (high << 4) | low);
            i += 3;
        } else {
            try result.append(allocator, input[i]);
            i += 1;
        }
    }

    return result.toOwnedSlice(allocator);
}

/// Resolve which on-disk name a request key refers to. New objects live at
/// the decoded (canonical) name, but objects written before path decoding
/// existed are stored under the still-encoded name — prefer whichever file
/// actually exists so those objects keep working, defaulting to canonical.
fn resolveLegacyKey(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, decoded: []const u8, raw: []const u8) ![]const u8 {
    if (std.mem.eql(u8, decoded, raw)) return allocator.dupe(u8, decoded);
    const dec_path = try ctx.objectPath(allocator, bucket, decoded);
    defer allocator.free(dec_path);
    if (std.Io.Dir.cwd().access(app_io, dec_path, .{})) |_| {
        return allocator.dupe(u8, decoded);
    } else |_| {}
    const raw_path = try ctx.objectPath(allocator, bucket, raw);
    defer allocator.free(raw_path);
    if (std.Io.Dir.cwd().access(app_io, raw_path, .{})) |_| {
        return allocator.dupe(u8, raw);
    } else |_| {}
    return allocator.dupe(u8, decoded);
}

pub fn sortQueryString(allocator: Allocator, query: []const u8) ![]const u8 {
    if (query.len == 0) return try allocator.dupe(u8, "");

    var pairs: std.ArrayListUnmanaged([]const u8) = .empty;
    defer pairs.deinit(allocator);

    var normalized: std.ArrayListUnmanaged([]const u8) = .empty;
    defer {
        for (normalized.items) |n| allocator.free(n);
        normalized.deinit(allocator);
    }

    var iter = std.mem.splitScalar(u8, query, '&');
    while (iter.next()) |pair| {
        if (pair.len > 0) {
            // Normalize params without '=' to 'key=' format (required by SigV4)
            if (std.mem.indexOf(u8, pair, "=") == null) {
                const norm = try std.fmt.allocPrint(allocator, "{s}=", .{pair});
                try normalized.append(allocator, norm);
                try pairs.append(allocator, norm);
            } else {
                try pairs.append(allocator, pair);
            }
        }
    }

    std.mem.sort([]const u8, pairs.items, {}, struct {
        fn lessThan(_: void, a: []const u8, b: []const u8) bool {
            return std.mem.order(u8, a, b) == .lt;
        }
    }.lessThan);

    var result: std.ArrayListUnmanaged(u8) = .empty;
    for (pairs.items, 0..) |pair, i| {
        if (i > 0) try result.append(allocator, '&');
        try result.appendSlice(allocator, pair);
    }

    return result.toOwnedSlice(allocator);
}

/// Returns true if the ETag list header (If-Match / If-None-Match value) matches
/// the given ETag. Handles `*` and comma-separated lists of quoted ETags.
pub fn etagListMatches(header: []const u8, etag: []const u8) bool {
    if (std.mem.eql(u8, std.mem.trim(u8, header, " \t"), "*")) return true;
    var it = std.mem.splitScalar(u8, header, ',');
    while (it.next()) |item| {
        if (std.mem.eql(u8, std.mem.trim(u8, item, " \t"), etag)) return true;
    }
    return false;
}

/// S3 ETag for a single object: quoted lowercase hex MD5 of the content.
/// (Multipart uploads use the composite `"md5-of-part-md5s-N"` form instead,
/// computed in handleCompleteMultipart.)
pub fn md5Etag(allocator: Allocator, data: []const u8) ![]const u8 {
    var digest: [16]u8 = undefined;
    std.crypto.hash.Md5.hash(data, &digest, .{});
    return std.fmt.allocPrint(allocator, "\"{x}\"", .{digest});
}

/// Compute the ETag (MD5 of content, same formula as PUT/GET) for an existing
/// object at `path`, or null if it doesn't exist. Only called when a conditional
/// header is present, so the read cost is paid only on conditional requests.
fn existingEtag(allocator: Allocator, path: []const u8) ?[]const u8 {
    var file = std.Io.Dir.cwd().openFile(app_io, path, .{}) catch return null;
    defer file.close(app_io);
    const content = readToEndAlloc(file, allocator, MAX_BODY_SIZE) catch return null;
    defer allocator.free(content);
    return md5Etag(allocator, content) catch null;
}

/// Evaluate If-Match / If-None-Match preconditions for a write to `path`.
/// Returns true if the request should proceed; false if a 412 has already been
/// sent. If-Match requires the object to exist with a matching ETag; If-None-Match
/// requires the object to be absent or have a non-matching ETag.
fn checkPutPreconditions(allocator: Allocator, req: *const Request, res: *Response, path: []const u8) bool {
    const if_match = req.header("if-match");
    const if_none_match = req.header("if-none-match");
    if (if_match == null and if_none_match == null) return true;

    const existing = existingEtag(allocator, path);
    defer if (existing) |e| allocator.free(e);

    if (if_match) |im| {
        const matches = if (existing) |e| etagListMatches(im, e) else false;
        if (!matches) {
            sendError(res, 412, "PreconditionFailed", "At least one of the pre-conditions you specified did not hold");
            return false;
        }
    }

    if (if_none_match) |inm| {
        const matches = if (existing) |e| etagListMatches(inm, e) else false;
        if (matches) {
            sendError(res, 412, "PreconditionFailed", "At least one of the pre-conditions you specified did not hold");
            return false;
        }
    }

    return true;
}

// ============================================================================
// OBJECT ATTRIBUTES (Content-Type, user metadata, checksums)
// ============================================================================
// Standalone objects are plain files; their S3 attributes live in a sidecar
// `<object path>.zs3attrs` so `ls` stays clean and old data dirs keep working
// (a missing sidecar means "binary/octet-stream", no metadata). Format is one
// `name: value` line per attribute; names are matched case-insensitively.

const DEFAULT_CONTENT_TYPE = "binary/octet-stream";

/// Guess a Content-Type from a key's extension. Used only when no sidecar
/// exists — i.e. for files zs3 did not write (the "point at an existing
/// tree" case). Explicitly stored Content-Types always win.
pub fn sniffContentType(key: []const u8) []const u8 {
    const dot = std.mem.lastIndexOfScalar(u8, key, '.') orelse return DEFAULT_CONTENT_TYPE;
    // Only the final path component's extension counts ("archive.tar.gz" -> gz).
    if (std.mem.indexOfScalar(u8, key[dot..], '/') != null) return DEFAULT_CONTENT_TYPE;
    const ext = key[dot + 1 ..];
    if (ext.len == 0 or ext.len > 8) return DEFAULT_CONTENT_TYPE;
    var lower_buf: [8]u8 = undefined;
    const lower = std.ascii.lowerString(&lower_buf, ext);
    const table = [_]struct { ext: []const u8, ct: []const u8 }{
        .{ .ext = "html", .ct = "text/html" },
        .{ .ext = "htm", .ct = "text/html" },
        .{ .ext = "css", .ct = "text/css" },
        .{ .ext = "js", .ct = "application/javascript" },
        .{ .ext = "mjs", .ct = "application/javascript" },
        .{ .ext = "json", .ct = "application/json" },
        .{ .ext = "xml", .ct = "application/xml" },
        .{ .ext = "txt", .ct = "text/plain" },
        .{ .ext = "md", .ct = "text/markdown" },
        .{ .ext = "csv", .ct = "text/csv" },
        .{ .ext = "png", .ct = "image/png" },
        .{ .ext = "jpg", .ct = "image/jpeg" },
        .{ .ext = "jpeg", .ct = "image/jpeg" },
        .{ .ext = "gif", .ct = "image/gif" },
        .{ .ext = "svg", .ct = "image/svg+xml" },
        .{ .ext = "webp", .ct = "image/webp" },
        .{ .ext = "ico", .ct = "image/x-icon" },
        .{ .ext = "mp4", .ct = "video/mp4" },
        .{ .ext = "webm", .ct = "video/webm" },
        .{ .ext = "mp3", .ct = "audio/mpeg" },
        .{ .ext = "wav", .ct = "audio/wav" },
        .{ .ext = "ogg", .ct = "audio/ogg" },
        .{ .ext = "pdf", .ct = "application/pdf" },
        .{ .ext = "wasm", .ct = "application/wasm" },
        .{ .ext = "woff", .ct = "font/woff" },
        .{ .ext = "woff2", .ct = "font/woff2" },
        .{ .ext = "ttf", .ct = "font/ttf" },
        .{ .ext = "zip", .ct = "application/zip" },
        .{ .ext = "gz", .ct = "application/gzip" },
        .{ .ext = "tar", .ct = "application/x-tar" },
    };
    for (table) |entry| {
        if (std.mem.eql(u8, lower, entry.ext)) return entry.ct;
    }
    return DEFAULT_CONTENT_TYPE;
}

const AttrEntry = struct { name: []const u8, value: []const u8 };

const ObjectAttrs = struct {
    content_type: []const u8,
    entries: []AttrEntry = &.{},
    // System fields, kept out of `entries` so they never echo as headers.
    /// Object tags in x-amz-tagging query form ("k=v&k2=v2", URL-encoded).
    tagging: ?[]const u8 = null,
    /// Canned object ACL (private / public-read / public-read-write).
    acl: ?[]const u8 = null,
    /// Version ID of this object (absent = the "null" version).
    version_id: ?[]const u8 = null,
    /// "AES256" when the file on disk is SSE-S3 encrypted; "SSE-C" for
    /// customer-key encryption (key MD5 in `sse_key_md5`).
    sse: ?[]const u8 = null,
    sse_key_md5: ?[]const u8 = null,
    /// Stored plaintext ETag for encrypted objects (MD5 of the content).
    etag: ?[]const u8 = null,

    fn deinit(self: *const ObjectAttrs, allocator: Allocator) void {
        allocator.free(self.content_type);
        for (self.entries) |e| {
            allocator.free(e.name);
            allocator.free(e.value);
        }
        allocator.free(self.entries);
        if (self.tagging) |v| allocator.free(v);
        if (self.acl) |v| allocator.free(v);
        if (self.version_id) |v| allocator.free(v);
        if (self.sse) |v| allocator.free(v);
        if (self.sse_key_md5) |v| allocator.free(v);
        if (self.etag) |v| allocator.free(v);
    }

    /// True when a sidecar is needed to represent this object.
    fn hasNonDefault(self: *const ObjectAttrs) bool {
        return !std.mem.eql(u8, self.content_type, DEFAULT_CONTENT_TYPE) or
            self.entries.len > 0 or self.tagging != null or self.acl != null or
            self.version_id != null or self.sse != null or self.sse_key_md5 != null or
            self.etag != null;
    }

    /// Deep copy (for carrying attrs across arena boundaries or editing).
    fn clone(self: *const ObjectAttrs, allocator: Allocator) !ObjectAttrs {
        var out = ObjectAttrs{ .content_type = try allocator.dupe(u8, self.content_type) };
        errdefer out.deinit(allocator);
        var entries: std.ArrayListUnmanaged(AttrEntry) = .empty;
        errdefer {
            for (entries.items) |e| {
                allocator.free(e.name);
                allocator.free(e.value);
            }
            entries.deinit(allocator);
        }
        for (self.entries) |e| {
            try entries.append(allocator, .{ .name = try allocator.dupe(u8, e.name), .value = try allocator.dupe(u8, e.value) });
        }
        out.entries = try entries.toOwnedSlice(allocator);
        if (self.tagging) |v| out.tagging = try allocator.dupe(u8, v);
        if (self.acl) |v| out.acl = try allocator.dupe(u8, v);
        if (self.version_id) |v| out.version_id = try allocator.dupe(u8, v);
        if (self.sse) |v| out.sse = try allocator.dupe(u8, v);
        if (self.sse_key_md5) |v| out.sse_key_md5 = try allocator.dupe(u8, v);
        if (self.etag) |v| out.etag = try allocator.dupe(u8, v);
        return out;
    }
};

/// Sidecar line names reserved for system fields (never echoed as headers).
fn isSystemAttrName(name: []const u8) bool {
    return std.mem.eql(u8, name, "tagging") or std.mem.eql(u8, name, "acl") or
        std.mem.eql(u8, name, "version-id") or std.mem.eql(u8, name, "sse") or
        std.mem.eql(u8, name, "sse-key-md5") or std.mem.eql(u8, name, "etag");
}

/// Serialize attrs to the `name: value` sidecar text (shared by the
/// standalone sidecar and the distributed .attrs entry).
fn attrsToTextInto(allocator: Allocator, buf: *std.ArrayListUnmanaged(u8), attrs: *const ObjectAttrs) !void {
    try buf.appendSlice(allocator, "content-type: ");
    try buf.appendSlice(allocator, attrs.content_type);
    try buf.append(allocator, '\n');
    for (attrs.entries) |e| {
        try buf.appendSlice(allocator, e.name);
        try buf.appendSlice(allocator, ": ");
        try buf.appendSlice(allocator, e.value);
        try buf.append(allocator, '\n');
    }
    const sys = [_]struct { name: []const u8, value: ?[]const u8 }{
        .{ .name = "tagging", .value = attrs.tagging },
        .{ .name = "acl", .value = attrs.acl },
        .{ .name = "version-id", .value = attrs.version_id },
        .{ .name = "sse", .value = attrs.sse },
        .{ .name = "sse-key-md5", .value = attrs.sse_key_md5 },
        .{ .name = "etag", .value = attrs.etag },
    };
    for (sys) |f| {
        if (f.value) |v| {
            try buf.appendSlice(allocator, f.name);
            try buf.appendSlice(allocator, ": ");
            try buf.appendSlice(allocator, v);
            try buf.append(allocator, '\n');
        }
    }
}

fn isAttrHeader(name: []const u8) bool {
    // Headers persisted on the object and echoed back on GET/HEAD.
    if (std.mem.startsWith(u8, name, "x-amz-meta-")) return true;
    if (std.mem.startsWith(u8, name, "x-amz-checksum-")) return true;
    if (std.mem.eql(u8, name, "x-amz-checksum-type")) return true;
    if (std.mem.eql(u8, name, "x-amz-sdk-checksum-algorithm")) return true;
    return false;
}

/// Collect attributes from a request: Content-Type plus persisted headers.
fn collectRequestAttrs(allocator: Allocator, req: *const Request) !ObjectAttrs {
    const ct = req.header("content-type") orelse DEFAULT_CONTENT_TYPE;
    var entries: std.ArrayListUnmanaged(AttrEntry) = .empty;
    errdefer {
        for (entries.items) |e| {
            allocator.free(e.name);
            allocator.free(e.value);
        }
        entries.deinit(allocator);
    }
    var it = req.headers.iterator();
    while (it.next()) |kv| {
        if (isAttrHeader(kv.key_ptr.*)) {
            try entries.append(allocator, .{
                .name = try allocator.dupe(u8, kv.key_ptr.*),
                .value = try allocator.dupe(u8, kv.value_ptr.*),
            });
        }
    }
    var out = ObjectAttrs{
        .content_type = try allocator.dupe(u8, ct),
        .entries = try entries.toOwnedSlice(allocator),
    };
    errdefer out.deinit(allocator);
    if (req.header("x-amz-tagging")) |t| {
        const tags = try parseTagQuery(allocator, t);
        defer freeTags(allocator, tags);
        out.tagging = try tagsToQuery(allocator, tags);
    }
    if (req.header("x-amz-acl")) |a| {
        if (!isCannedAcl(a)) return error.InvalidAcl;
        out.acl = try allocator.dupe(u8, normalizeCannedAcl(a));
    }
    return out;
}

fn attrsSidecarPath(allocator: Allocator, obj_path: []const u8) ![]const u8 {
    return std.fmt.allocPrint(allocator, "{s}.zs3attrs", .{obj_path});
}

/// Persist attributes next to a standalone object. Skips the write when there
/// is nothing non-default to store, keeping plain PUTs to a single file.
fn saveStandaloneAttrs(allocator: Allocator, obj_path: []const u8, attrs: *const ObjectAttrs) void {
    if (!attrs.hasNonDefault()) {
        // Remove any stale sidecar (e.g. overwrite with bare PUT after a
        // metadata PUT, or a CopyObject with REPLACE and no metadata).
        const old = attrsSidecarPath(allocator, obj_path) catch return;
        defer allocator.free(old);
        std.Io.Dir.cwd().deleteFile(app_io, old) catch {};
        return;
    }
    const sidecar = attrsSidecarPath(allocator, obj_path) catch return;
    defer allocator.free(sidecar);
    var buf: std.ArrayListUnmanaged(u8) = .empty;
    defer buf.deinit(allocator);
    attrsToTextInto(allocator, &buf, attrs) catch return;
    var af = std.Io.Dir.cwd().createFileAtomic(app_io, sidecar, .{ .make_path = true, .replace = true }) catch return;
    defer af.deinit(app_io);
    af.file.writeStreamingAll(app_io, buf.items) catch return;
    if (enable_fsync) fsyncFile(af.file);
    af.replace(app_io) catch {};
    if (enable_fsync) fsyncParentDir(sidecar);
}

fn loadStandaloneAttrs(allocator: Allocator, obj_path: []const u8, key: []const u8) !ObjectAttrs {
    const sidecar = try attrsSidecarPath(allocator, obj_path);
    defer allocator.free(sidecar);
    var file = std.Io.Dir.cwd().openFile(app_io, sidecar, .{}) catch {
        // No sidecar: this object was not written through the S3 API (or was
        // written bare). Sniff the extension so pre-existing trees serve
        // sensible Content-Types instead of binary/octet-stream.
        return .{ .content_type = try allocator.dupe(u8, sniffContentType(key)) };
    };
    defer file.close(app_io);
    const content = try readToEndAlloc(file, allocator, 64 * 1024);
    defer allocator.free(content);
    return parseAttrsContent(allocator, content);
}

fn parseAttrsContent(allocator: Allocator, content: []const u8) !ObjectAttrs {
    var ct: []const u8 = try allocator.dupe(u8, DEFAULT_CONTENT_TYPE);
    errdefer allocator.free(ct);
    var sys = ObjectAttrs{ .content_type = "" };
    errdefer {
        if (sys.tagging) |v| allocator.free(v);
        if (sys.acl) |v| allocator.free(v);
        if (sys.version_id) |v| allocator.free(v);
        if (sys.sse) |v| allocator.free(v);
        if (sys.sse_key_md5) |v| allocator.free(v);
        if (sys.etag) |v| allocator.free(v);
    }
    var entries: std.ArrayListUnmanaged(AttrEntry) = .empty;
    errdefer {
        for (entries.items) |e| {
            allocator.free(e.name);
            allocator.free(e.value);
        }
        entries.deinit(allocator);
    }
    var lines = std.mem.splitScalar(u8, content, '\n');
    while (lines.next()) |line| {
        const trimmed = std.mem.trim(u8, line, " \t\r");
        if (trimmed.len == 0) continue;
        const colon = std.mem.indexOfScalar(u8, trimmed, ':') orelse continue;
        const name = std.mem.trim(u8, trimmed[0..colon], " \t");
        const value = std.mem.trim(u8, trimmed[colon + 1 ..], " \t");
        if (name.len == 0) continue;
        if (std.mem.eql(u8, name, "content-type")) {
            allocator.free(ct);
            ct = try allocator.dupe(u8, value);
        } else if (isSystemAttrName(name)) {
            const dup = try allocator.dupe(u8, value);
            errdefer allocator.free(dup);
            const slot: *?[]const u8 = if (std.mem.eql(u8, name, "tagging")) &sys.tagging else if (std.mem.eql(u8, name, "acl")) &sys.acl else if (std.mem.eql(u8, name, "version-id")) &sys.version_id else if (std.mem.eql(u8, name, "sse")) &sys.sse else if (std.mem.eql(u8, name, "sse-key-md5")) &sys.sse_key_md5 else &sys.etag;
            if (slot.*) |old_v| allocator.free(old_v);
            slot.* = dup;
        } else {
            try entries.append(allocator, .{
                .name = try allocator.dupe(u8, name),
                .value = try allocator.dupe(u8, value),
            });
        }
    }
    sys.content_type = ct;
    sys.entries = try entries.toOwnedSlice(allocator);
    return sys;
}

fn deleteStandaloneAttrs(allocator: Allocator, obj_path: []const u8) void {
    const sidecar = attrsSidecarPath(allocator, obj_path) catch return;
    defer allocator.free(sidecar);
    std.Io.Dir.cwd().deleteFile(app_io, sidecar) catch {};
}

/// Apply stored attributes to a GET/HEAD response.
fn applyAttrsToResponse(res: *Response, attrs: *const ObjectAttrs) void {
    res.setHeader("Content-Type", attrs.content_type);
    for (attrs.entries) |e| {
        res.setHeader(e.name, e.value);
    }
    applySystemAttrHeaders(res, attrs);
}

/// Headers derived from system fields: tag count, version id, SSE echo.
fn applySystemAttrHeaders(res: *Response, attrs: *const ObjectAttrs) void {
    if (attrs.tagging) |t| {
        if (t.len > 0) {
            var n: usize = 1;
            for (t) |c| {
                if (c == '&') n += 1;
            }
            var buf: [16]u8 = undefined;
            const count = std.fmt.bufPrint(&buf, "{d}", .{n}) catch "0";
            // Header values must outlive the response: copy onto the arena.
            res.setHeader("x-amz-tagging-count", res.allocator.dupe(u8, count) catch return);
        }
    }
    if (attrs.version_id) |v| res.setHeader("x-amz-version-id", v);
    if (attrs.sse) |mode| {
        if (std.mem.eql(u8, mode, "SSE-C")) {
            res.setHeader("x-amz-server-side-encryption-customer-algorithm", "AES256");
            if (attrs.sse_key_md5) |m| res.setHeader("x-amz-server-side-encryption-customer-key-MD5", m);
        } else {
            res.setHeader("x-amz-server-side-encryption", mode);
        }
    }
}

/// Variant for 206 Partial Content: checksums describe the whole object, not
/// the range, so (like S3) they are omitted on ranged responses. Returning the
/// full-object checksum would fail SDK validation of the range bytes.
fn applyAttrsToRangeResponse(res: *Response, attrs: *const ObjectAttrs) void {
    res.setHeader("Content-Type", attrs.content_type);
    for (attrs.entries) |e| {
        if (std.mem.startsWith(u8, e.name, "x-amz-checksum-")) continue;
        if (std.mem.eql(u8, e.name, "x-amz-checksum-type")) continue;
        if (std.mem.eql(u8, e.name, "x-amz-sdk-checksum-algorithm")) continue;
        res.setHeader(e.name, e.value);
    }
    applySystemAttrHeaders(res, attrs);
}

/// Echo request checksums back on a PUT/CopyObject response, mirroring S3.
fn echoRequestChecksums(req: *const Request, res: *Response) void {
    var it = req.headers.iterator();
    while (it.next()) |kv| {
        const name: []const u8 = kv.key_ptr.*;
        if (std.mem.startsWith(u8, name, "x-amz-checksum-") or
            std.mem.eql(u8, name, "x-amz-sdk-checksum-algorithm"))
        {
            res.setHeader(name, kv.value_ptr.*);
        }
    }
}

fn handlePutObject(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, key: []const u8) !void {
    // Keys ending with '/' are folder markers — store as ".folder_marker" file
    const effective_key = if (key.len > 0 and key[key.len - 1] == '/')
        try std.fmt.allocPrint(allocator, "{s}.folder_marker", .{key})
    else
        try allocator.dupe(u8, key);
    defer allocator.free(effective_key);

    const path = try ctx.objectPath(allocator, bucket, effective_key);
    defer allocator.free(path);

    // Honor If-Match / If-None-Match before touching the object.
    if (!checkPutPreconditions(allocator, req, res, path)) return;

    // Validate headers that become stored attributes before writing anything.
    var attrs = collectRequestAttrs(allocator, req) catch |err| {
        if (err == error.InvalidTag) {
            sendError(res, 400, "InvalidTag", "The TagValue you have provided is invalid");
            return;
        }
        if (err == error.InvalidAcl) {
            sendError(res, 400, "InvalidArgument", "Unknown canned ACL");
            return;
        }
        return err;
    };
    defer attrs.deinit(allocator);

    // Server-side encryption: SSE-C headers, then x-amz-server-side-encryption,
    // then the bucket default. Encrypt into a separate buffer; the ETag is
    // always the MD5 of the plaintext.
    const sse = resolveSseForWrite(ctx, allocator, req, res, bucket) catch return;
    const stored_body: []const u8 = if (sse) |mode| blk: {
        const enc = sseEncrypt(allocator, req.body, mode) catch {
            sendError(res, 500, "InternalError", "Encryption failed");
            return;
        };
        try applySseToAttrs(allocator, &attrs, mode, req.body);
        noteBucketSseUsed(ctx, allocator, bucket);
        break :blk enc;
    } else req.body;

    const vstatus = bucketVersioning(ctx, allocator, bucket);
    archiveCurrentVersion(ctx, allocator, bucket, effective_key, path, vstatus) catch {
        sendError(res, 500, "InternalError", "Cannot archive previous version");
        return;
    };
    if (vstatus == .enabled) attrs.version_id = try newVersionId(allocator);

    // Write atomically: temp file + rename, so a concurrent GET never sees a
    // half-written object. make_path creates parent directories.
    var af = std.Io.Dir.cwd().createFileAtomic(app_io, path, .{
        .make_path = true,
        .replace = true,
    }) catch {
        sendError(res, 500, "InternalError", "Cannot create file");
        return;
    };
    defer af.deinit(app_io);

    af.file.writeStreamingAll(app_io, stored_body) catch {
        sendError(res, 500, "InternalError", "Cannot write file");
        return;
    };

    if (enable_fsync) fsyncFile(af.file);
    af.replace(app_io) catch {
        sendError(res, 500, "InternalError", "Cannot write file");
        return;
    };
    if (enable_fsync) fsyncParentDir(path);

    // Persist Content-Type / x-amz-meta-* / checksums / tags / ACL / version
    // / SSE state alongside the object.
    saveStandaloneAttrs(allocator, path, &attrs);
    echoRequestChecksums(req, res);
    if (attrs.acl != null) noteObjectAclUsed(ctx);

    // ETag is the MD5 of the content, so `aws s3 sync` and `rclone check`
    // agree with local md5sum.
    const etag = md5Etag(allocator, req.body) catch {
        sendError(res, 500, "InternalError", "ETag failed");
        return;
    };

    metrics.put_bytes += req.body.len;
    res.ok();
    res.setHeader("ETag", etag);
    if (attrs.version_id) |v| {
        res.setHeader("x-amz-version-id", try allocator.dupe(u8, v));
    } else if (vstatus != .disabled) {
        res.setHeader("x-amz-version-id", NULL_VERSION);
    }
    applySseResponseHeaders(res, &attrs, allocator);
}

fn handleGetObject(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, key: []const u8) !void {
    const effective_key = if (key.len > 0 and key[key.len - 1] == '/')
        try std.fmt.allocPrint(allocator, "{s}.folder_marker", .{key})
    else
        try allocator.dupe(u8, key);
    defer allocator.free(effective_key);
    const current_path = try ctx.objectPath(allocator, bucket, effective_key);
    defer allocator.free(current_path);

    // ?versionId= selects the current object or an archived version.
    const path = (try resolveRequestedVersion(ctx, allocator, req, res, bucket, effective_key, current_path)) orelse return;

    // Encrypted objects are decrypted in memory and served from there.
    if (try serveEncryptedIfNeeded(ctx, allocator, req, res, bucket, effective_key, path, false)) return;

    var file = std.Io.Dir.cwd().openFile(app_io, path, .{}) catch {
        sendMissingObject(ctx, allocator, res, bucket, effective_key);
        return;
    };

    const stat = file.stat(app_io) catch {
        file.close(app_io);
        sendError(res, 500, "InternalError", "Stat failed");
        return;
    };

    const last_modified = allocHttpDate(allocator, @intCast(stat.mtime.toSeconds())) catch {
        file.close(app_io);
        sendError(res, 500, "InternalError", "Date format failed");
        return;
    };

    // Conditional requests (If-Match / If-None-Match) need the ETag, which requires
    // reading the content. Only pay that cost when a conditional header is present.
    const if_match = req.header("if-match");
    const if_none_match = req.header("if-none-match");
    if (if_match != null or if_none_match != null) {
        const content = readToEndAlloc(file, allocator, MAX_BODY_SIZE) catch {
            file.close(app_io);
            sendError(res, 500, "InternalError", "Read failed");
            return;
        };
        file.close(app_io);

        const etag = md5Etag(allocator, content) catch {
            sendError(res, 500, "InternalError", "ETag failed");
            return;
        };

        if (if_match) |im| {
            if (!etagListMatches(im, etag)) {
                sendError(res, 412, "PreconditionFailed", "At least one of the pre-conditions you specified did not hold");
                return;
            }
        }
        if (if_none_match) |inm| {
            if (etagListMatches(inm, etag)) {
                res.status = 304;
                res.status_text = "Not Modified";
                return;
            }
        }

        // Preconditions passed — serve from the content we already read.
        // A satisfiable Range turns this into a 206, which (like S3) omits
        // whole-object checksums; decide before applying attributes.
        const cond_range = if (req.header("range")) |rh| parseRange(rh, content.len) else null;
        res.ok();
        res.setHeader("Accept-Ranges", "bytes");
        res.setHeader("ETag", etag);
        res.setHeader("Last-Modified", last_modified);
        // NB: no deinit — response headers borrow attrs memory, which the
        // request arena frees after the response is written.
        if (loadStandaloneAttrs(allocator, path, key)) |attrs| {
            if (cond_range != null) {
                applyAttrsToRangeResponse(res, &attrs);
            } else {
                applyAttrsToResponse(res, &attrs);
            }
            addNullVersionHeader(ctx, allocator, res, bucket, &attrs);
        } else |_| {}
        if (cond_range) |range| {
            const content_range = std.fmt.allocPrint(allocator, "bytes {d}-{d}/{d}", .{ range.start, range.end, content.len }) catch {
                sendError(res, 500, "InternalError", "Range format failed");
                return;
            };
            res.status = 206;
            res.status_text = "Partial Content";
            res.setHeader("Content-Range", content_range);
            res.body = content[range.start .. range.end + 1];
            metrics.get_bytes += res.body.len;
            return;
        }
        res.body = content;
        metrics.get_bytes += content.len;
        return;
    }

    // NB: no deinit — response headers borrow attrs memory, freed by the
    // request arena after the response is written.
    const obj_attrs = loadStandaloneAttrs(allocator, path, key) catch null;
    if (obj_attrs) |*a| addNullVersionHeader(ctx, allocator, res, bucket, a);

    // For range requests, use sendFile without ETag (efficient for large files)
    if (req.header("range")) |range_header| {
        if (parseRange(range_header, stat.size)) |range| {
            const len = range.end - range.start + 1;

            const content_range = std.fmt.allocPrint(allocator, "bytes {d}-{d}/{d}", .{ range.start, range.end, stat.size }) catch {
                file.close(app_io);
                sendError(res, 500, "InternalError", "Range format failed");
                return;
            };

            res.status = 206;
            res.status_text = "Partial Content";
            res.setHeader("Content-Range", content_range);
            res.setHeader("Accept-Ranges", "bytes");
            res.setHeader("Last-Modified", last_modified);
            if (obj_attrs) |*a| applyAttrsToRangeResponse(res, a);
            metrics.get_bytes += len;
            res.setSendFile(file, len, range.start);
            return;
        }
    }

    // For full file, read content to compute ETag
    const content = readToEndAlloc(file, allocator, MAX_BODY_SIZE) catch {
        file.close(app_io);
        sendError(res, 500, "InternalError", "Read failed");
        return;
    };
    file.close(app_io);

    const etag = md5Etag(allocator, content) catch {
        sendError(res, 500, "InternalError", "ETag failed");
        return;
    };

    res.ok();
    res.setHeader("Accept-Ranges", "bytes");
    res.setHeader("ETag", etag);
    res.setHeader("Last-Modified", last_modified);
    if (obj_attrs) |*a| applyAttrsToResponse(res, a);
    metrics.get_bytes += content.len;
    res.body = content;
}

fn handleDeleteObject(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, key: []const u8) !void {
    const effective_key = if (key.len > 0 and key[key.len - 1] == '/')
        try std.fmt.allocPrint(allocator, "{s}.folder_marker", .{key})
    else
        try allocator.dupe(u8, key);
    defer allocator.free(effective_key);

    const version_id = if (getQueryParam(req.query, "versionId")) |v| try uriDecode(allocator, v) else null;
    const outcome = deleteObjectVersioned(ctx, allocator, bucket, effective_key, version_id) catch {
        sendError(res, 500, "InternalError", "Delete failed");
        return;
    };
    if (outcome.not_found) {
        sendError(res, 404, "NoSuchVersion", "The specified version does not exist");
        return;
    }
    res.noContent();
    if (outcome.delete_marker) res.setHeader("x-amz-delete-marker", "true");
    if (outcome.version_id) |v| res.setHeader("x-amz-version-id", v);
}

fn deleteObjectInternal(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, path: []const u8) void {
    std.Io.Dir.cwd().deleteFile(app_io, path) catch |err| switch (err) {
        error.FileNotFound => {},
        else => std.log.warn("delete failed: {}", .{err}),
    };
    // Remove the attribute sidecar (Content-Type / user metadata) with it.
    deleteStandaloneAttrs(allocator, path);

    // Clean up empty parent directories up to bucket level
    const bucket_path = ctx.bucketPath(allocator, bucket) catch return;
    defer allocator.free(bucket_path);

    var dir_path = std.fs.path.dirname(path);
    while (dir_path) |dp| {
        if (dp.len <= bucket_path.len) break;
        std.Io.Dir.cwd().deleteDir(app_io, dp) catch break;
        dir_path = std.fs.path.dirname(dp);
    }
}

fn handleDeleteObjects(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8) !void {
    // Parse XML body: <Delete><Object><Key>...</Key></Object>...</Delete>
    var xml: std.ArrayListUnmanaged(u8) = .empty;
    defer xml.deinit(allocator);

    try xml.appendSlice(allocator, "<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
    try xml.appendSlice(allocator, "<DeleteResult xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\">");

    // Each <Object> carries a <Key> and optionally a <VersionId>.
    const quiet = if (xmlTagText(req.body, "Quiet")) |q| std.mem.eql(u8, q, "true") else false;
    var body = req.body;
    while (std.mem.indexOf(u8, body, "<Object>")) |start| {
        const after = body[start + 8 ..];
        const end = std.mem.indexOf(u8, after, "</Object>") orelse break;
        const block = after[0..end];
        body = after[end + 9 ..];
        const raw_key = xmlTagText(block, "Key") orelse continue;
        const key = try xmlUnescape(allocator, raw_key);
        const version_id: ?[]const u8 = if (xmlTagText(block, "VersionId")) |v| (if (v.len > 0) v else null) else null;

        if (key.len == 0 or !isValidKey(key)) {
            try xml.appendSlice(allocator, "<Error><Key>");
            try xmlEscape(allocator, &xml, key);
            try xml.appendSlice(allocator, "</Key><Code>InvalidKey</Code><Message>Object key is invalid</Message></Error>");
            continue;
        }
        // Legacy fallback: a decoded name may refer to a still-encoded file.
        const rkey = resolveLegacyKey(ctx, allocator, bucket, key, key) catch continue;
        const effective_key = if (rkey.len > 0 and rkey[rkey.len - 1] == '/')
            try std.fmt.allocPrint(allocator, "{s}.folder_marker", .{rkey})
        else
            rkey;
        // In distributed mode, also delete from metadata index
        if (ctx.distributed) |dist| {
            dist.meta_index.delete(allocator, bucket, rkey);
            deleteDistAttrs(allocator, dist, bucket, rkey);
        }

        const outcome = deleteObjectVersioned(ctx, allocator, bucket, effective_key, version_id) catch {
            try xml.appendSlice(allocator, "<Error><Key>");
            try xmlEscape(allocator, &xml, key);
            try xml.appendSlice(allocator, "</Key><Code>InternalError</Code><Message>Delete failed</Message></Error>");
            continue;
        };
        if (outcome.not_found) {
            try xml.appendSlice(allocator, "<Error><Key>");
            try xmlEscape(allocator, &xml, key);
            try xml.appendSlice(allocator, "</Key><VersionId>");
            try xmlEscape(allocator, &xml, version_id orelse "");
            try xml.appendSlice(allocator, "</VersionId><Code>NoSuchVersion</Code><Message>The specified version does not exist</Message></Error>");
            continue;
        }
        if (quiet) continue;
        try xml.appendSlice(allocator, "<Deleted><Key>");
        try xmlEscape(allocator, &xml, key);
        try xml.appendSlice(allocator, "</Key>");
        if (version_id) |v| {
            try xml.appendSlice(allocator, "<VersionId>");
            try xmlEscape(allocator, &xml, v);
            try xml.appendSlice(allocator, "</VersionId>");
        }
        if (outcome.delete_marker) {
            try xml.appendSlice(allocator, "<DeleteMarker>true</DeleteMarker>");
            if (outcome.version_id) |v| {
                try xml.appendSlice(allocator, "<DeleteMarkerVersionId>");
                try xml.appendSlice(allocator, v);
                try xml.appendSlice(allocator, "</DeleteMarkerVersionId>");
            }
        }
        try xml.appendSlice(allocator, "</Deleted>");
    }

    try xml.appendSlice(allocator, "</DeleteResult>");

    res.ok();
    res.setXmlBody(try xml.toOwnedSlice(allocator));
}

// ============================================================================
// COPY (CopyObject + UploadPartCopy)
// ============================================================================
// Server-side copy is what `aws s3 mv/sync`, `rclone move`, and the Terraform
// S3 backend are built on. The source is named by the x-amz-copy-source
// header: "[ / ]src-bucket/src-key" (URL-encoded, optional ?versionId=
// suffix which is accepted and ignored — zs3 keeps no versions).

const CopySource = struct {
    bucket: []const u8,
    key: []const u8, // decoded (canonical) form
    raw: []const u8, // verbatim header form, for the legacy fallback
    version_id: ?[]const u8 = null,
};

fn parseCopySource(allocator: Allocator, header: []const u8) !CopySource {
    var src = std.mem.trim(u8, header, " \t");
    if (src.len > 0 and src[0] == '/') src = src[1..];
    // ?versionId=... selects an archived version of the source.
    var version_id: ?[]const u8 = null;
    if (std.mem.indexOfScalar(u8, src, '?')) |q| {
        if (getQueryParam(src[q + 1 ..], "versionId")) |v| {
            if (v.len > 0) version_id = try uriDecode(allocator, v);
        }
        src = src[0..q];
    }
    const slash = std.mem.indexOfScalar(u8, src, '/') orelse return error.InvalidCopySource;
    // x-amz-copy-source is URL-encoded per spec: split raw, then decode each
    // segment (a literal %2F inside a key survives as data).
    const bucket = try uriDecodePath(allocator, src[0..slash]);
    errdefer allocator.free(bucket);
    const raw_key = src[slash + 1 ..];
    var key_buf: std.ArrayListUnmanaged(u8) = .empty;
    errdefer key_buf.deinit(allocator);
    var seg_iter = std.mem.splitScalar(u8, raw_key, '/');
    var first_seg = true;
    while (seg_iter.next()) |seg| {
        if (!first_seg) try key_buf.append(allocator, '/');
        first_seg = false;
        const dec = try uriDecodePath(allocator, seg);
        defer allocator.free(dec);
        try key_buf.appendSlice(allocator, dec);
    }
    const key = try key_buf.toOwnedSlice(allocator);
    const raw = try allocator.dupe(u8, raw_key);
    if (!isValidBucketName(bucket) or !isValidKey(key)) {
        allocator.free(bucket);
        allocator.free(key);
        allocator.free(raw);
        return error.InvalidCopySource;
    }
    return .{ .bucket = bucket, .key = key, .raw = raw, .version_id = version_id };
}

/// Parse x-amz-copy-source-range ("bytes=first-last" or "first-last").
fn parseCopyRange(header: []const u8, src_len: u64) ?Range {
    var spec = std.mem.trim(u8, header, " \t");
    if (std.mem.startsWith(u8, spec, "bytes=")) spec = spec[6..];
    const dash = std.mem.indexOfScalar(u8, spec, '-') orelse return null;
    const first = std.fmt.parseInt(u64, spec[0..dash], 10) catch return null;
    const last = std.fmt.parseInt(u64, spec[dash + 1 ..], 10) catch return null;
    if (src_len == 0 or first > last or last >= src_len) return null;
    return .{ .start = first, .end = last };
}

/// Read an object's bytes through either backend (standalone file or
/// distributed inline/CAS/peer fetch), for server-side copy.
fn readSourceBytes(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, key: []const u8) ![]const u8 {
    if (ctx.distributed) |dist| {
        const meta = try dist.meta_index.getFull(allocator, bucket, key) orelse
            fetchMetaFromPeers(ctx, allocator, bucket, key) orelse return error.NoSuchKey;
        // Note: callers pass the request arena, which frees inline_data; the
        // explicit free below keeps non-arena callers clean too.
        if (meta.inline_data) |data| {
            defer allocator.free(data);
            return allocator.dupe(u8, data);
        }
        if (meta.size == 0) return allocator.dupe(u8, "");
        if (dist.cas.retrieve(allocator, meta.hash)) |cached| {
            defer allocator.free(cached);
            return allocator.dupe(u8, cached);
        } else |_| {}
        const providers = dist.kademlia.findProviders(meta.hash);
        for (providers) |provider_id| {
            const peer = dist.kademlia.findPeerById(provider_id) orelse continue;
            const data = fetchFromPeer(allocator, peer.address, meta.hash) catch continue;
            if (!std.mem.eql(u8, &CAS.computeHash(data), &meta.hash)) {
                allocator.free(data);
                continue;
            }
            _ = dist.cas.store(allocator, data) catch {};
            return data;
        }
        var peers: [MAX_BROADCAST_PEERS]PeerInfo = undefined;
        const n = dist.kademlia.collectPeers(&peers);
        for (peers[0..n]) |peer| {
            const data = fetchFromPeer(allocator, peer.address, meta.hash) catch continue;
            if (!std.mem.eql(u8, &CAS.computeHash(data), &meta.hash)) {
                allocator.free(data);
                continue;
            }
            _ = dist.cas.store(allocator, data) catch {};
            return data;
        }
        return error.NoSuchKey;
    }
    const path = try ctx.objectPath(allocator, bucket, key);
    defer allocator.free(path);
    if (std.Io.Dir.cwd().openFile(app_io, path, .{})) |file| {
        defer file.close(app_io);
        // A directory fd opens successfully but reads fail — fall through to
        // the folder-marker lookup instead of erroring out.
        if (readToEndAlloc(file, allocator, MAX_BODY_SIZE)) |data| {
            return data;
        } else |_| {}
    } else |_| {}
    // Folder-marker fallback: keys ending in '/' are stored as ".folder_marker".
    if (key.len > 0 and key[key.len - 1] == '/') {
        const marker_key = try std.fmt.allocPrint(allocator, "{s}.folder_marker", .{key});
        defer allocator.free(marker_key);
        const marker_path = try ctx.objectPath(allocator, bucket, marker_key);
        defer allocator.free(marker_path);
        var mfile = std.Io.Dir.cwd().openFile(app_io, marker_path, .{}) catch return error.NoSuchKey;
        defer mfile.close(app_io);
        return readToEndAlloc(mfile, allocator, MAX_BODY_SIZE) catch error.NoSuchKey;
    }
    return error.NoSuchKey;
}

fn copyObjectXml(allocator: Allocator, etag: []const u8, tag: []const u8) ![]const u8 {
    var xml: std.ArrayListUnmanaged(u8) = .empty;
    errdefer xml.deinit(allocator);
    try xml.appendSlice(allocator, "<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
    try xml.appendSlice(allocator, tag);
    try xml.appendSlice(allocator, "<LastModified>");
    var iso_buf: [20]u8 = undefined;
    formatIso8601(&iso_buf, std.Io.Clock.real.now(app_io).toSeconds());
    try xml.appendSlice(allocator, &iso_buf);
    try xml.appendSlice(allocator, "</LastModified><ETag>");
    try xml.appendSlice(allocator, etag);
    try xml.appendSlice(allocator, "</ETag>");
    if (std.mem.eql(u8, tag, "<CopyObjectResult xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\">")) {
        try xml.appendSlice(allocator, "</CopyObjectResult>");
    } else {
        try xml.appendSlice(allocator, "</CopyPartResult>");
    }
    return xml.toOwnedSlice(allocator);
}

/// PUT /{bucket}/{key} with x-amz-copy-source: server-side copy.
fn handleCopyObject(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, key: []const u8) !void {
    const copy_src_header = req.header("x-amz-copy-source") orelse {
        sendError(res, 400, "InvalidRequest", "Missing x-amz-copy-source");
        return;
    };
    const src = parseCopySource(allocator, copy_src_header) catch {
        sendError(res, 400, "InvalidArgument", "Invalid x-amz-copy-source");
        return;
    };
    defer allocator.free(src.bucket);
    defer allocator.free(src.key);
    defer allocator.free(src.raw);

    // Legacy fallback for the source, same rule as request paths.
    const src_key = try resolveLegacyKey(ctx, allocator, src.bucket, src.key, src.raw);

    // Source: current object, or a specific version; decrypted if stored
    // with SSE (SSE-C needs the x-amz-copy-source-…-customer-* headers).
    const src_effective = if (src_key.len > 0 and src_key[src_key.len - 1] == '/')
        try std.fmt.allocPrint(allocator, "{s}.folder_marker", .{src_key})
    else
        src_key;
    var src_path_opt: ?[]const u8 = null;
    if (ctx.distributed == null) {
        const cur = try ctx.objectPath(allocator, src.bucket, src_effective);
        if (src.version_id) |vid| {
            switch (try resolveVersion(ctx, allocator, src.bucket, src_effective, cur, vid)) {
                .path => |p| src_path_opt = p,
                .delete_marker => {
                    sendError(res, 404, "NoSuchKey", "Copy source is a delete marker");
                    return;
                },
                .not_found => {
                    sendError(res, 404, "NoSuchVersion", "The specified version does not exist");
                    return;
                },
            }
        } else {
            src_path_opt = cur;
        }
    }
    const data = if (src_path_opt) |sp|
        readObjectPlaintext(allocator, req, sp, src_effective, true) catch |err| {
            sendCopySourceReadError(res, err);
            return;
        }
    else
        readSourceBytes(ctx, allocator, src.bucket, src_key) catch {
            sendError(res, 404, "NoSuchKey", "Copy source not found");
            return;
        };
    defer allocator.free(data);

    // Folder-marker destinations are stored as ".folder_marker" files, like PUT.
    const effective_key = if (key.len > 0 and key[key.len - 1] == '/')
        try std.fmt.allocPrint(allocator, "{s}.folder_marker", .{key})
    else
        try allocator.dupe(u8, key);
    defer allocator.free(effective_key);

    // MetadataDirective: COPY (default) inherits source attributes, REPLACE
    // uses the request's headers.
    const directive = req.header("x-amz-metadata-directive") orelse "COPY";
    const replace = std.ascii.eqlIgnoreCase(directive, "REPLACE");

    if (ctx.distributed) |dist| {
        const hash = CAS.computeHash(data);
        if (data.len <= INLINE_THRESHOLD) {
            try dist.meta_index.putWithData(allocator, bucket, effective_key, hash, data.len, data);
        } else {
            _ = try dist.cas.store(allocator, data);
            try dist.meta_index.put(allocator, bucket, effective_key, hash, data.len);
            dist.kademlia.announce(hash) catch {};
            dist.replication.schedule(hash) catch {};
        }
        if (replace) {
            if (collectRequestAttrs(allocator, req)) |a| {
                defer a.deinit(allocator);
                writeDistAttrs(allocator, dist, bucket, effective_key, &a);
            } else |_| {}
        } else if (readDistAttrs(allocator, dist, src.bucket, src_key) orelse fetchAttrsFromPeers(ctx, allocator, src.bucket, src_key)) |sa| {
            defer sa.deinit(allocator);
            writeDistAttrs(allocator, dist, bucket, effective_key, &sa);
        }
        propagateObjectMeta(ctx, allocator, bucket, effective_key);
        propagateObjectAttrs(ctx, allocator, bucket, effective_key);
        if (data.len > INLINE_THRESHOLD) {
            dist.worker.enqueue(.{ .blob = .{ .hash = hash } });
        }
        const etag = try md5Etag(allocator, data);
        defer allocator.free(etag);
        metrics.put_bytes += data.len;
        echoRequestChecksums(req, res);
        res.ok();
        res.setXmlBody(try copyObjectXml(allocator, etag, "<CopyObjectResult xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\">"));
        return;
    }

    const dst_path = try ctx.objectPath(allocator, bucket, effective_key);
    defer allocator.free(dst_path);
    if (!checkPutPreconditions(allocator, req, res, dst_path)) return;

    // Destination attributes: request headers (REPLACE) or the source's
    // (COPY), with tags following x-amz-tagging-directive separately.
    const tagging_replace = if (req.header("x-amz-tagging-directive")) |d| std.ascii.eqlIgnoreCase(d, "REPLACE") else false;
    const src_attrs: ?ObjectAttrs = if (src_path_opt) |sp| (loadStandaloneAttrs(allocator, sp, src_key) catch null) else null;
    var dst_attrs: ObjectAttrs = blk: {
        if (replace) {
            var a = collectRequestAttrs(allocator, req) catch |err| {
                if (err == error.InvalidTag) {
                    sendError(res, 400, "InvalidTag", "The TagValue you have provided is invalid");
                    return;
                }
                if (err == error.InvalidAcl) {
                    sendError(res, 400, "InvalidArgument", "Unknown canned ACL");
                    return;
                }
                return err;
            };
            if (!tagging_replace) {
                if (a.tagging) |t| allocator.free(t);
                a.tagging = if (src_attrs) |sa| (if (sa.tagging) |t| try allocator.dupe(u8, t) else null) else null;
            }
            break :blk a;
        }
        var a: ObjectAttrs = if (src_attrs) |sa| try sa.clone(allocator) else .{ .content_type = try allocator.dupe(u8, sniffContentType(key)) };
        // Version id, ACL and encryption state belong to the source object.
        if (a.version_id) |v| allocator.free(v);
        a.version_id = null;
        if (a.acl) |v| allocator.free(v);
        a.acl = null;
        if (a.sse) |v| allocator.free(v);
        a.sse = null;
        if (a.sse_key_md5) |v| allocator.free(v);
        a.sse_key_md5 = null;
        if (a.etag) |v| allocator.free(v);
        a.etag = null;
        if (tagging_replace) {
            if (a.tagging) |t| allocator.free(t);
            a.tagging = null;
            if (req.header("x-amz-tagging")) |t| {
                const tags = parseTagQuery(allocator, t) catch {
                    sendError(res, 400, "InvalidTag", "The TagValue you have provided is invalid");
                    return;
                };
                defer freeTags(allocator, tags);
                a.tagging = try tagsToQuery(allocator, tags);
            }
        }
        if (req.header("x-amz-acl")) |h| {
            if (isCannedAcl(h) and !std.mem.eql(u8, normalizeCannedAcl(h), "private")) {
                a.acl = try allocator.dupe(u8, normalizeCannedAcl(h));
            }
        }
        break :blk a;
    };
    defer dst_attrs.deinit(allocator);
    if (dst_attrs.acl != null) noteObjectAclUsed(ctx);

    const sse = resolveSseForWrite(ctx, allocator, req, res, bucket) catch return;
    const stored: []const u8 = if (sse) |mode| blk: {
        const enc = sseEncrypt(allocator, data, mode) catch {
            sendError(res, 500, "InternalError", "Encryption failed");
            return;
        };
        try applySseToAttrs(allocator, &dst_attrs, mode, data);
        noteBucketSseUsed(ctx, allocator, bucket);
        break :blk enc;
    } else data;

    const vstatus = bucketVersioning(ctx, allocator, bucket);
    archiveCurrentVersion(ctx, allocator, bucket, effective_key, dst_path, vstatus) catch {
        sendError(res, 500, "InternalError", "Cannot archive previous version");
        return;
    };
    if (vstatus == .enabled) dst_attrs.version_id = try newVersionId(allocator);

    var af = std.Io.Dir.cwd().createFileAtomic(app_io, dst_path, .{ .make_path = true, .replace = true }) catch {
        sendError(res, 500, "InternalError", "Cannot create file");
        return;
    };
    defer af.deinit(app_io);
    af.file.writeStreamingAll(app_io, stored) catch {
        sendError(res, 500, "InternalError", "Cannot write file");
        return;
    };
    if (enable_fsync) fsyncFile(af.file);
    af.replace(app_io) catch {
        sendError(res, 500, "InternalError", "Cannot write file");
        return;
    };
    if (enable_fsync) fsyncParentDir(dst_path);

    saveStandaloneAttrs(allocator, dst_path, &dst_attrs);
    if (dst_attrs.version_id) |v| res.setHeader("x-amz-version-id", try allocator.dupe(u8, v));
    if (src_attrs) |sa| {
        if (sa.version_id) |v| res.setHeader("x-amz-copy-source-version-id", try allocator.dupe(u8, v));
    }
    applySseResponseHeaders(res, &dst_attrs, allocator);

    const etag = try md5Etag(allocator, data);
    defer allocator.free(etag);
    metrics.put_bytes += data.len;
    echoRequestChecksums(req, res);
    res.ok();
    res.setXmlBody(try copyObjectXml(allocator, etag, "<CopyObjectResult xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\">"));
}

/// PUT /{bucket}/{key}?uploadId=..&partNumber=.. with x-amz-copy-source:
/// server-side copy of (a byte range of) an object into a multipart part.
fn handleUploadPartCopy(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, key: []const u8) !void {
    _ = bucket;
    _ = key;
    const upload_id = getQueryParam(req.query, "uploadId") orelse {
        sendError(res, 400, "InvalidRequest", "Missing uploadId");
        return;
    };
    if (!isValidUploadId(upload_id)) {
        sendError(res, 400, "InvalidArgument", "Invalid uploadId");
        return;
    }
    const part_number_str = getQueryParam(req.query, "partNumber") orelse {
        sendError(res, 400, "InvalidRequest", "Missing partNumber");
        return;
    };
    const part_number = std.fmt.parseInt(u32, part_number_str, 10) catch {
        sendError(res, 400, "InvalidArgument", "Invalid partNumber");
        return;
    };
    if (part_number < 1 or part_number > 10000) {
        sendError(res, 400, "InvalidArgument", "Invalid partNumber");
        return;
    }
    const copy_src_header = req.header("x-amz-copy-source") orelse {
        sendError(res, 400, "InvalidRequest", "Missing x-amz-copy-source");
        return;
    };
    const src = parseCopySource(allocator, copy_src_header) catch {
        sendError(res, 400, "InvalidArgument", "Invalid x-amz-copy-source");
        return;
    };
    defer allocator.free(src.bucket);
    defer allocator.free(src.key);
    defer allocator.free(src.raw);

    // Legacy fallback for the source, same rule as request paths.
    const src_key = try resolveLegacyKey(ctx, allocator, src.bucket, src.key, src.raw);

    const data = readCopySourcePlaintext(ctx, allocator, req, res, src, src_key) catch |err| {
        if (err == error.Handled) return;
        return err;
    };
    defer allocator.free(data);

    const slice = if (req.header("x-amz-copy-source-range")) |range_header|
        (parseCopyRange(range_header, data.len) orelse {
            sendError(res, 416, "InvalidRange", "Copy source range is not satisfiable");
            return;
        })
    else
        Range{ .start = 0, .end = if (data.len == 0) 0 else data.len - 1 };
    const part_data = if (data.len == 0) data[0..0] else data[slice.start .. slice.end + 1];

    const parts_dir = std.fmt.allocPrint(allocator, "{s}/.uploads/{s}", .{ ctx.data_dir, upload_id }) catch {
        sendError(res, 500, "InternalError", "Allocation failed");
        return;
    };
    defer allocator.free(parts_dir);
    // Upload must have been initiated; otherwise this is a NoSuchUpload, not a 500.
    var up_dir = std.Io.Dir.cwd().openDir(app_io, parts_dir, .{}) catch {
        sendError(res, 404, "NoSuchUpload", "Upload not found");
        return;
    };
    up_dir.close(app_io);

    const part_path = std.fmt.allocPrint(allocator, "{s}/{s}", .{ parts_dir, part_number_str }) catch {
        sendError(res, 500, "InternalError", "Allocation failed");
        return;
    };
    defer allocator.free(part_path);

    const etag = writeUploadPart(ctx, allocator, req, res, upload_id, part_path, part_data) catch |err| {
        if (err == error.Handled) return;
        return err;
    };
    defer allocator.free(etag);

    res.ok();
    res.setXmlBody(try copyObjectXml(allocator, etag, "<CopyPartResult xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\">"));
}

/// Source bytes for CopyObject / UploadPartCopy: a specific version if
/// requested, decrypted when stored with SSE.
fn readCopySourcePlaintext(ctx: *const S3Context, allocator: Allocator, req: *const Request, res: *Response, src: CopySource, src_key: []const u8) ![]const u8 {
    if (ctx.distributed != null) {
        return readSourceBytes(ctx, allocator, src.bucket, src_key) catch {
            sendError(res, 404, "NoSuchKey", "Copy source not found");
            return error.Handled;
        };
    }
    const src_effective = if (src_key.len > 0 and src_key[src_key.len - 1] == '/')
        try std.fmt.allocPrint(allocator, "{s}.folder_marker", .{src_key})
    else
        src_key;
    const cur = try ctx.objectPath(allocator, src.bucket, src_effective);
    var src_path = cur;
    if (src.version_id) |vid| {
        switch (try resolveVersion(ctx, allocator, src.bucket, src_effective, cur, vid)) {
            .path => |p| src_path = p,
            .delete_marker => {
                sendError(res, 404, "NoSuchKey", "Copy source is a delete marker");
                return error.Handled;
            },
            .not_found => {
                sendError(res, 404, "NoSuchVersion", "The specified version does not exist");
                return error.Handled;
            },
        }
    }
    return readObjectPlaintext(allocator, req, src_path, src_effective, true) catch |err| {
        sendCopySourceReadError(res, err);
        return error.Handled;
    };
}

fn handleHeadObject(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, key: []const u8) !void {
    const effective_key = if (key.len > 0 and key[key.len - 1] == '/')
        try std.fmt.allocPrint(allocator, "{s}.folder_marker", .{key})
    else
        try allocator.dupe(u8, key);
    defer allocator.free(effective_key);
    const current_path = try ctx.objectPath(allocator, bucket, effective_key);
    defer allocator.free(current_path);

    const path = (try resolveRequestedVersion(ctx, allocator, req, res, bucket, effective_key, current_path)) orelse return;
    if (try serveEncryptedIfNeeded(ctx, allocator, req, res, bucket, effective_key, path, true)) return;

    var file = std.Io.Dir.cwd().openFile(app_io, path, .{}) catch {
        sendMissingObject(ctx, allocator, res, bucket, effective_key);
        return;
    };
    defer file.close(app_io);

    const stat = file.stat(app_io) catch {
        sendError(res, 500, "InternalError", "Stat failed");
        return;
    };

    // Filesystem directories are implementation details for nested keys, not
    // S3 objects. Clients such as rclone probe a prefix with HeadObject before
    // listing it and expect a miss rather than an attempt to read the directory.
    if (stat.kind != .file) {
        sendError(res, 404, "NoSuchKey", "Object not found");
        return;
    }

    // Compute ETag from file content (same as PUT uses)
    const content = readToEndAlloc(file, allocator, MAX_BODY_SIZE) catch {
        sendError(res, 500, "InternalError", "Read failed");
        return;
    };
    defer allocator.free(content);

    const etag = md5Etag(allocator, content) catch {
        sendError(res, 500, "InternalError", "ETag failed");
        return;
    };

    // Conditional requests: If-Match mismatch → 412, If-None-Match match → 304.
    if (req.header("if-match")) |im| {
        if (!etagListMatches(im, etag)) {
            sendError(res, 412, "PreconditionFailed", "At least one of the pre-conditions you specified did not hold");
            return;
        }
    }
    if (req.header("if-none-match")) |inm| {
        if (etagListMatches(inm, etag)) {
            res.status = 304;
            res.status_text = "Not Modified";
            return;
        }
    }

    const len_str = std.fmt.allocPrint(allocator, "{d}", .{stat.size}) catch {
        sendError(res, 500, "InternalError", "Format failed");
        return;
    };

    const last_modified = allocHttpDate(allocator, @intCast(stat.mtime.toSeconds())) catch {
        sendError(res, 500, "InternalError", "Date format failed");
        return;
    };

    res.ok();
    res.setHeader("Content-Length", len_str);
    res.setHeader("Accept-Ranges", "bytes");
    res.setHeader("ETag", etag);
    res.setHeader("Last-Modified", last_modified);
    // NB: no deinit — headers borrow attrs memory (arena-freed after write).
    if (loadStandaloneAttrs(allocator, path, key)) |attrs| {
        applyAttrsToResponse(res, &attrs);
        addNullVersionHeader(ctx, allocator, res, bucket, &attrs);
    } else |_| {}
}

fn handleListObjects(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8) !void {
    const prefix_raw = getQueryParam(req.query, "prefix") orelse "";
    const prefix = try uriDecode(allocator, prefix_raw);
    defer allocator.free(prefix);

    const max_keys_str = getQueryParam(req.query, "max-keys") orelse "1000";
    const max_keys = std.fmt.parseInt(usize, max_keys_str, 10) catch 1000;

    const delimiter_raw = getQueryParam(req.query, "delimiter");
    const delimiter_decoded = if (delimiter_raw) |d| try uriDecode(allocator, d) else null;
    defer if (delimiter_decoded) |d| allocator.free(d);
    // Treat empty delimiter the same as no delimiter
    const delimiter = if (delimiter_decoded) |d| (if (d.len > 0) d else null) else null;

    const continuation_raw = getQueryParam(req.query, "continuation-token");
    const continuation = if (continuation_raw) |c| try uriDecode(allocator, c) else null;
    defer if (continuation) |c| allocator.free(c);

    const bucket_path = try ctx.bucketPath(allocator, bucket);
    defer allocator.free(bucket_path);

    var dir = std.Io.Dir.cwd().openDir(app_io, bucket_path, .{ .iterate = true }) catch {
        sendError(res, 404, "NoSuchBucket", "Bucket not found");
        return;
    };
    defer dir.close(app_io);

    var xml: std.ArrayListUnmanaged(u8) = .empty;
    defer xml.deinit(allocator);

    try xml.appendSlice(allocator, "<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
    try xml.appendSlice(allocator, "<ListBucketResult xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\">");
    try xml.appendSlice(allocator, "<Name>");
    try xmlEscape(allocator, &xml, bucket);
    try xml.appendSlice(allocator, "</Name><Prefix>");
    try xmlEscape(allocator, &xml, prefix);
    try xml.appendSlice(allocator, "</Prefix><MaxKeys>");
    var max_keys_num_buf: [32]u8 = undefined;
    const max_keys_num_str = std.fmt.bufPrint(&max_keys_num_buf, "{d}", .{max_keys}) catch "1000";
    try xml.appendSlice(allocator, max_keys_num_str);
    try xml.appendSlice(allocator, "</MaxKeys>");

    var keys: std.ArrayListUnmanaged(KeyInfo) = .empty;
    defer keys.deinit(allocator);

    try collectKeys(allocator, bucket_path, "", prefix, &keys, bucketSseUsed(ctx, allocator, bucket));

    std.mem.sort(KeyInfo, keys.items, {}, struct {
        fn lessThan(_: void, a: KeyInfo, b: KeyInfo) bool {
            return std.mem.order(u8, a.key, b.key) == .lt;
        }
    }.lessThan);

    var start_idx: usize = 0;
    if (continuation) |cont| {
        for (keys.items, 0..) |item, i| {
            if (std.mem.eql(u8, item.key, cont)) {
                start_idx = i;
                break;
            }
        }
    }

    var common_prefixes = std.StringHashMap(void).init(allocator);
    defer common_prefixes.deinit();

    var count: usize = 0;
    var is_truncated = false;
    var next_token: ?[]const u8 = null;

    for (keys.items[start_idx..]) |item| {
        if (count >= max_keys) {
            is_truncated = true;
            next_token = item.key;
            break;
        }

        if (delimiter) |delim| {
            const after_prefix = if (prefix.len > 0 and std.mem.startsWith(u8, item.key, prefix))
                item.key[prefix.len..]
            else
                item.key;

            if (std.mem.indexOf(u8, after_prefix, delim)) |delim_idx| {
                const common_prefix = item.key[0 .. prefix.len + delim_idx + delim.len];
                if (!common_prefixes.contains(common_prefix)) {
                    try common_prefixes.put(common_prefix, {});
                    try xml.appendSlice(allocator, "<CommonPrefixes><Prefix>");
                    try xmlEscape(allocator, &xml, common_prefix);
                    try xml.appendSlice(allocator, "</Prefix></CommonPrefixes>");
                    count += 1;
                }
                continue;
            }
        }

        try xml.appendSlice(allocator, "<Contents><Key>");
        try xmlEscape(allocator, &xml, item.key);
        try xml.appendSlice(allocator, "</Key><LastModified>");
        var iso_buf: [20]u8 = undefined;
        formatIso8601(&iso_buf, item.mtime);
        try xml.appendSlice(allocator, &iso_buf);
        try xml.appendSlice(allocator, "</LastModified><Size>");
        var size_buf: [32]u8 = undefined;
        const size_str = std.fmt.bufPrint(&size_buf, "{d}", .{item.size}) catch "0";
        try xml.appendSlice(allocator, size_str);
        try xml.appendSlice(allocator, "</Size><StorageClass>STANDARD</StorageClass></Contents>");
        count += 1;
    }

    var count_buf: [32]u8 = undefined;
    const count_str = std.fmt.bufPrint(&count_buf, "{d}", .{count}) catch "0";
    try xml.appendSlice(allocator, "<KeyCount>");
    try xml.appendSlice(allocator, count_str);
    try xml.appendSlice(allocator, "</KeyCount>");

    if (is_truncated) {
        try xml.appendSlice(allocator, "<IsTruncated>true</IsTruncated>");
        if (next_token) |token| {
            try xml.appendSlice(allocator, "<NextContinuationToken>");
            try xmlEscape(allocator, &xml, token);
            try xml.appendSlice(allocator, "</NextContinuationToken>");
        }
    } else {
        try xml.appendSlice(allocator, "<IsTruncated>false</IsTruncated>");
    }

    try xml.appendSlice(allocator, "</ListBucketResult>");

    res.ok();
    res.setXmlBody(try xml.toOwnedSlice(allocator));
}

const KeyInfo = struct {
    key: []const u8,
    size: u64,
    mtime: i64, // Unix timestamp in seconds
};

/// `check_sse`: consult sidecars to report plaintext sizes for encrypted
/// objects. Only worth its cost when the bucket has ever used SSE (see
/// bucketSseUsed), so plain buckets keep the one-stat-per-object LIST.
fn collectKeys(allocator: Allocator, base_path: []const u8, current_prefix: []const u8, filter_prefix: []const u8, keys: *std.ArrayListUnmanaged(KeyInfo), check_sse: bool) !void {
    const full_path = if (current_prefix.len > 0)
        try std.fs.path.join(allocator, &[_][]const u8{ base_path, current_prefix })
    else
        try allocator.dupe(u8, base_path);
    defer allocator.free(full_path);

    var dir = std.Io.Dir.cwd().openDir(app_io, full_path, .{ .iterate = true }) catch return;
    defer dir.close(app_io);

    // Two passes: first learn which files have a sidecar (needed to report
    // plaintext sizes for encrypted objects without a stat per object).
    const Ent = struct { name: []const u8, kind: std.Io.File.Kind };
    var ents: std.ArrayListUnmanaged(Ent) = .empty;
    defer {
        for (ents.items) |e| allocator.free(e.name);
        ents.deinit(allocator);
    }
    var sidecars = std.StringHashMap(void).init(allocator);
    defer sidecars.deinit();
    var iter = dir.iterate();
    while (try iter.next(app_io)) |entry| {
        if (entry.kind == .file and std.mem.endsWith(u8, entry.name, ".zs3attrs")) {
            const owner = try allocator.dupe(u8, entry.name[0 .. entry.name.len - ".zs3attrs".len]);
            try sidecars.put(owner, {});
            continue;
        }
        try ents.append(allocator, .{ .name = try allocator.dupe(u8, entry.name), .kind = entry.kind });
    }
    defer {
        var kit = sidecars.keyIterator();
        while (kit.next()) |k| allocator.free(k.*);
    }

    for (ents.items) |entry| {
        // The snapshot tree stays hidden unless this listing deliberately
        // targets it via prefix=".zs3snapshots/". Everything else lists —
        // including dot-prefixed user keys and .folder_marker files (which
        // translate back to trailing-slash keys below) — except attribute
        // sidecars, which are implementation detail, not S3 objects.
        if (entry.kind == .directory and std.mem.eql(u8, entry.name, ".zs3snapshots") and
            !std.mem.startsWith(u8, filter_prefix, SNAP_PREFIX)) continue;
        if (entry.kind == .directory and current_prefix.len == 0 and
            (std.mem.eql(u8, entry.name, BUCKET_CFG_DIR) or std.mem.eql(u8, entry.name, VERSIONS_DIR))) continue;

        const full_key = if (current_prefix.len > 0)
            try std.fmt.allocPrint(allocator, "{s}/{s}", .{ current_prefix, entry.name })
        else
            try allocator.dupe(u8, entry.name);

        if (entry.kind == .directory) {
            try collectKeys(allocator, base_path, full_key, filter_prefix, keys, check_sse);
            allocator.free(full_key);
        } else if (entry.kind == .file) {
            // Translate .folder_marker files back to keys ending with /
            const report_key = if (std.mem.endsWith(u8, full_key, ".folder_marker")) blk: {
                const trimmed = try allocator.dupe(u8, full_key[0 .. full_key.len - ".folder_marker".len]);
                allocator.free(full_key);
                break :blk trimmed;
            } else full_key;

            if (filter_prefix.len == 0 or std.mem.startsWith(u8, report_key, filter_prefix)) {
                // Use statFile instead of open+stat+close - much faster
                var size, const mtime = blk: {
                    const stat = dir.statFile(app_io, entry.name, .{}) catch break :blk .{ 0, @as(i64, 0) };
                    break :blk .{ stat.size, @as(i64, @intCast(stat.mtime.toSeconds())) };
                };
                if (check_sse and sidecars.contains(entry.name)) {
                    // Only objects with a sidecar can be encrypted.
                    const obj_path = try std.fs.path.join(allocator, &.{ full_path, entry.name });
                    defer allocator.free(obj_path);
                    if (loadStandaloneAttrs(allocator, obj_path, report_key)) |attrs| {
                        defer attrs.deinit(allocator);
                        if (attrs.sse != null) size = sseLogicalSize(size);
                    } else |_| {}
                }
                try keys.append(allocator, .{ .key = report_key, .size = size, .mtime = mtime });
            } else {
                allocator.free(report_key);
            }
        }
    }
}

fn handleCreateBucket(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8) !void {
    const path = try ctx.bucketPath(allocator, bucket);
    defer allocator.free(path);

    const canned: ?[]const u8 = if (req.header("x-amz-acl")) |h| blk: {
        if (!isCannedAcl(h)) {
            sendError(res, 400, "InvalidArgument", "Unknown canned ACL");
            return;
        }
        break :blk normalizeCannedAcl(h);
    } else null;

    std.Io.Dir.cwd().createDir(app_io, path, .default_dir) catch |err| switch (err) {
        error.PathAlreadyExists => {},
        else => {
            sendError(res, 500, "InternalError", "Cannot create bucket");
            return;
        },
    };
    if (canned) |c| {
        if (!std.mem.eql(u8, c, "private")) writeBucketConfig(ctx, allocator, bucket, "acl", c) catch {};
    }

    if (ctx.distributed) |dist| {
        const ts = std.Io.Clock.real.now(app_io).toSeconds();
        dist.bucket_ops.noteCreate(allocator, bucket, ts);
        if (std.heap.page_allocator.dupe(u8, bucket)) |name| {
            dist.worker.enqueue(.{ .bucket = .{ .name = name, .deleted = false, .ts = ts } });
        } else |_| {}
    }

    res.ok();
}

fn handleHeadBucket(ctx: *const S3Context, allocator: Allocator, res: *Response, bucket: []const u8) !void {
    const path = try ctx.bucketPath(allocator, bucket);
    defer allocator.free(path);

    var dir = std.Io.Dir.cwd().openDir(app_io, path, .{}) catch {
        sendError(res, 404, "NoSuchBucket", "Bucket not found");
        return;
    };
    dir.close(app_io);

    res.ok();
}

fn handleDeleteBucket(ctx: *const S3Context, allocator: Allocator, res: *Response, bucket: []const u8) !void {
    const path = try ctx.bucketPath(allocator, bucket);
    defer allocator.free(path);

    // A bucket with only its own configuration is empty. Stored object
    // versions (including delete markers) are not: S3 refuses too.
    if (bucketHasVersions(ctx, allocator, bucket)) {
        sendError(res, 409, "BucketNotEmpty", "The bucket you tried to delete is not empty. You must delete all versions in the bucket.");
        return;
    }
    if (std.fs.path.join(allocator, &.{ path, VERSIONS_DIR })) |vp| {
        defer allocator.free(vp);
        std.Io.Dir.cwd().deleteTree(app_io, vp) catch {};
    } else |_| {}
    if (std.fs.path.join(allocator, &.{ path, BUCKET_CFG_DIR })) |cp| {
        defer allocator.free(cp);
        std.Io.Dir.cwd().deleteTree(app_io, cp) catch {};
    } else |_| {}

    std.Io.Dir.cwd().deleteDir(app_io, path) catch |err| switch (err) {
        error.DirNotEmpty => {
            sendError(res, 409, "BucketNotEmpty", "Bucket is not empty");
            return;
        },
        error.FileNotFound => {
            sendError(res, 404, "NoSuchBucket", "Bucket does not exist");
            return;
        },
        else => std.log.warn("delete bucket failed: {}", .{err}),
    };

    if (ctx.distributed) |dist| {
        const ts = std.Io.Clock.real.now(app_io).toSeconds();
        dist.bucket_ops.noteDelete(allocator, bucket, ts);
        // Drop the object-metadata tree for this bucket so tombstones and
        // inline data don't leak, and peers can't serve a deleted bucket's
        // index on a later sync.
        if (std.fs.path.join(allocator, &.{ dist.meta_index.data_dir, ".index", bucket })) |index_path| {
            defer allocator.free(index_path);
            std.Io.Dir.cwd().deleteTree(app_io, index_path) catch {};
        } else |_| {}
        if (std.heap.page_allocator.dupe(u8, bucket)) |name| {
            dist.worker.enqueue(.{ .bucket = .{ .name = name, .deleted = true, .ts = ts } });
        } else |_| {}
    }

    res.noContent();
}

fn handleListBuckets(ctx: *const S3Context, allocator: Allocator, res: *Response) !void {
    var dir = std.Io.Dir.cwd().openDir(app_io, ctx.data_dir, .{ .iterate = true }) catch {
        sendError(res, 500, "InternalError", "Cannot open data dir");
        return;
    };
    defer dir.close(app_io);

    var xml: std.ArrayListUnmanaged(u8) = .empty;
    defer xml.deinit(allocator);

    try xml.appendSlice(allocator, "<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
    try xml.appendSlice(allocator, "<ListAllMyBucketsResult xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\">");
    try xml.appendSlice(allocator, "<Owner><ID>minioadmin</ID><DisplayName>minioadmin</DisplayName></Owner>");
    try xml.appendSlice(allocator, "<Buckets>");

    var iter = dir.iterate();
    while (try iter.next(app_io)) |entry| {
        if (entry.kind != .directory) continue;
        if (entry.name[0] == '.') continue;
        // Only list directories that are usable as buckets. An existing tree
        // can contain anything (`Backups`, `media_archive`); advertising them
        // as buckets and then rejecting every operation is worse than hiding
        // them. (A bucket created through the API always passes validation.)
        if (!isValidBucketName(entry.name)) continue;

        try xml.appendSlice(allocator, "<Bucket><Name>");
        try xmlEscape(allocator, &xml, entry.name);
        try xml.appendSlice(allocator, "</Name><CreationDate>");
        const mtime: i64 = blk: {
            const stat = dir.statFile(app_io, entry.name, .{}) catch break :blk 0;
            break :blk @intCast(stat.mtime.toSeconds());
        };
        var iso_buf: [20]u8 = undefined;
        formatIso8601(&iso_buf, mtime);
        try xml.appendSlice(allocator, &iso_buf);
        try xml.appendSlice(allocator, "</CreationDate></Bucket>");
    }

    try xml.appendSlice(allocator, "</Buckets></ListAllMyBucketsResult>");

    res.ok();
    res.setXmlBody(try xml.toOwnedSlice(allocator));
}

fn handleInitiateMultipart(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, key: []const u8) !void {
    // Encryption for the whole upload is fixed here; parts follow it.
    const sse = resolveSseForWrite(ctx, allocator, req, res, bucket) catch return;
    if (sse != null and ctx.distributed != null) {
        sendError(res, 501, "NotImplemented", "Encryption is not available in distributed mode");
        return;
    }
    // Content-Type / metadata / tags / ACL come from this request in S3.
    const init_attrs = collectRequestAttrs(allocator, req) catch |err| {
        if (err == error.InvalidTag) {
            sendError(res, 400, "InvalidTag", "The TagValue you have provided is invalid");
            return;
        }
        if (err == error.InvalidAcl) {
            sendError(res, 400, "InvalidArgument", "Unknown canned ACL");
            return;
        }
        return err;
    };
    defer init_attrs.deinit(allocator);

    // Generate unique upload ID using timestamp + random bytes to prevent collision
    const timestamp: u64 = @intCast(std.Io.Clock.real.now(app_io).toSeconds());
    var random_bytes: [8]u8 = undefined;
    try app_io.randomSecure(&random_bytes);
    const random_suffix = std.mem.readInt(u64, &random_bytes, .little);
    var upload_id_buf: [32]u8 = undefined;
    const upload_id = std.fmt.bufPrint(&upload_id_buf, "{x}{x}", .{ timestamp, random_suffix }) catch unreachable;

    const parts_dir = std.fmt.allocPrint(allocator, "{s}/.uploads/{s}", .{ ctx.data_dir, upload_id }) catch return;
    defer allocator.free(parts_dir);
    std.Io.Dir.cwd().createDirPath(app_io, parts_dir) catch {};

    const meta_path = std.fmt.allocPrint(allocator, "{s}/.uploads/{s}/.meta", .{ ctx.data_dir, upload_id }) catch return;
    defer allocator.free(meta_path);

    var meta_file = std.Io.Dir.cwd().createFile(app_io, meta_path, .{}) catch return;
    defer meta_file.close(app_io);
    const sse_line: []const u8 = if (sse) |m| switch (m) {
        .s3 => "\nsse=AES256",
        .customer => |c| std.fmt.allocPrint(allocator, "\nsse=SSE-C:{s}", .{c.key_md5_b64}) catch return,
    } else "";
    const meta_content = std.fmt.allocPrint(allocator, "{s}\n{s}{s}", .{ bucket, key, sse_line }) catch return;
    defer allocator.free(meta_content);
    meta_file.writeStreamingAll(app_io, meta_content) catch {};
    if (init_attrs.hasNonDefault()) {
        const attrs_path = std.fmt.allocPrint(allocator, "{s}/.uploads/{s}/.attrs", .{ ctx.data_dir, upload_id }) catch return;
        defer allocator.free(attrs_path);
        if (attrsToText(allocator, &init_attrs)) |text| {
            defer allocator.free(text);
            var af = std.Io.Dir.cwd().createFile(app_io, attrs_path, .{}) catch return;
            defer af.close(app_io);
            af.writeStreamingAll(app_io, text) catch {};
        } else |_| {}
    }
    if (sse) |m| switch (m) {
        .s3 => res.setHeader("x-amz-server-side-encryption", "AES256"),
        .customer => |c| {
            res.setHeader("x-amz-server-side-encryption-customer-algorithm", "AES256");
            res.setHeader("x-amz-server-side-encryption-customer-key-MD5", c.key_md5_b64);
        },
    };

    var xml: std.ArrayListUnmanaged(u8) = .empty;
    defer xml.deinit(allocator);

    try xml.appendSlice(allocator, "<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
    try xml.appendSlice(allocator, "<InitiateMultipartUploadResult xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\">");
    try xml.appendSlice(allocator, "<Bucket>");
    try xml.appendSlice(allocator, bucket);
    try xml.appendSlice(allocator, "</Bucket><Key>");
    try xmlEscape(allocator, &xml, key);
    try xml.appendSlice(allocator, "</Key><UploadId>");
    try xml.appendSlice(allocator, upload_id);
    try xml.appendSlice(allocator, "</UploadId></InitiateMultipartUploadResult>");

    res.ok();
    res.setXmlBody(try xml.toOwnedSlice(allocator));
}

fn handleUploadPart(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, key: []const u8) !void {
    _ = bucket;
    _ = key;

    const upload_id = getQueryParam(req.query, "uploadId") orelse {
        sendError(res, 400, "InvalidRequest", "Missing uploadId");
        return;
    };
    if (!isValidUploadId(upload_id)) {
        sendError(res, 400, "InvalidArgument", "Invalid uploadId");
        return;
    }
    const part_number = getQueryParam(req.query, "partNumber") orelse {
        sendError(res, 400, "InvalidRequest", "Missing partNumber");
        return;
    };
    _ = std.fmt.parseInt(u32, part_number, 10) catch {
        sendError(res, 400, "InvalidArgument", "Invalid partNumber");
        return;
    };

    const part_path = std.fmt.allocPrint(allocator, "{s}/.uploads/{s}/{s}", .{ ctx.data_dir, upload_id, part_number }) catch return;
    defer allocator.free(part_path);

    const parts_dir = std.fs.path.dirname(part_path) orelse return;
    var up_dir = std.Io.Dir.cwd().openDir(app_io, parts_dir, .{}) catch {
        sendError(res, 404, "NoSuchUpload", "Upload not found");
        return;
    };
    up_dir.close(app_io);

    const etag = writeUploadPart(ctx, allocator, req, res, upload_id, part_path, req.body) catch |err| {
        if (err == error.Handled) return;
        return err;
    };

    res.ok();
    res.setHeader("ETag", etag);
    if (readUploadMeta(ctx, allocator, upload_id)) |meta| switch (uploadSseFromMeta(meta)) {
        .none => {},
        .s3 => res.setHeader("x-amz-server-side-encryption", "AES256"),
        .customer_md5 => |m| {
            res.setHeader("x-amz-server-side-encryption-customer-algorithm", "AES256");
            res.setHeader("x-amz-server-side-encryption-customer-key-MD5", m);
        },
    };
}

/// GET /{bucket}/{key}?uploadId=.. : list uploaded parts.
fn handleListParts(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, key: []const u8) !void {
    const upload_id = getQueryParam(req.query, "uploadId") orelse {
        sendError(res, 400, "InvalidRequest", "Missing uploadId");
        return;
    };
    if (!isValidUploadId(upload_id)) {
        sendError(res, 400, "InvalidArgument", "Invalid uploadId");
        return;
    }
    const parts_dir = std.fmt.allocPrint(allocator, "{s}/.uploads/{s}", .{ ctx.data_dir, upload_id }) catch {
        sendError(res, 500, "InternalError", "Allocation failed");
        return;
    };
    defer allocator.free(parts_dir);

    var dir = std.Io.Dir.cwd().openDir(app_io, parts_dir, .{ .iterate = true }) catch {
        sendError(res, 404, "NoSuchUpload", "Upload not found");
        return;
    };
    defer dir.close(app_io);

    var nums: std.ArrayListUnmanaged(u32) = .empty;
    defer nums.deinit(allocator);
    var iter = dir.iterate();
    while (try iter.next(app_io)) |entry| {
        if (entry.kind == .file and entry.name[0] != '.') {
            const num = std.fmt.parseInt(u32, entry.name, 10) catch continue;
            try nums.append(allocator, num);
        }
    }
    std.mem.sort(u32, nums.items, {}, std.sort.asc(u32));

    const list_sse: ?UploadSse = if (readUploadMeta(ctx, allocator, upload_id)) |meta| blk: {
        const u = uploadSseFromMeta(meta);
        break :blk if (u == .none) null else u;
    } else null;

    var xml: std.ArrayListUnmanaged(u8) = .empty;
    defer xml.deinit(allocator);
    try xml.appendSlice(allocator, "<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
    try xml.appendSlice(allocator, "<ListPartsResult xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\">");
    try xml.appendSlice(allocator, "<Bucket>");
    try xmlEscape(allocator, &xml, bucket);
    try xml.appendSlice(allocator, "</Bucket><Key>");
    try xmlEscape(allocator, &xml, key);
    try xml.appendSlice(allocator, "</Key><UploadId>");
    try xml.appendSlice(allocator, upload_id);
    try xml.appendSlice(allocator, "</UploadId>");
    for (nums.items) |num| {
        var num_buf: [16]u8 = undefined;
        const num_str = std.fmt.bufPrint(&num_buf, "{d}", .{num}) catch continue;
        const part_path = std.fmt.allocPrint(allocator, "{s}/{s}", .{ parts_dir, num_str }) catch continue;
        defer allocator.free(part_path);
        var pf = std.Io.Dir.cwd().openFile(app_io, part_path, .{}) catch continue;
        defer pf.close(app_io);
        var stat = pf.stat(app_io) catch continue;
        const raw = readToEndAlloc(pf, allocator, MAX_BODY_SIZE) catch continue;
        defer allocator.free(raw);
        // Encrypted parts: report plaintext size and ETag when the key is
        // available (SSE-S3 always; SSE-C needs the request's key headers).
        var data: []const u8 = raw;
        if (list_sse) |usse| {
            const mode = uploadSseMode(allocator, req, res, usse) catch null;
            if (mode) |m| {
                if (sseIkm(ctx, m)) |ikm| {
                    if (sseDecrypt(allocator, raw, &ikm)) |plain| {
                        data = plain;
                    } else |_| {}
                } else |_| {}
            }
            stat.size = sseLogicalSize(stat.size);
        }
        const petag = md5Etag(allocator, data) catch continue;
        defer allocator.free(petag);
        try xml.appendSlice(allocator, "<Part><PartNumber>");
        try xml.appendSlice(allocator, num_str);
        try xml.appendSlice(allocator, "</PartNumber><ETag>");
        try xml.appendSlice(allocator, petag);
        try xml.appendSlice(allocator, "</ETag><Size>");
        var size_buf: [32]u8 = undefined;
        const size_str = std.fmt.bufPrint(&size_buf, "{d}", .{stat.size}) catch "0";
        try xml.appendSlice(allocator, size_str);
        try xml.appendSlice(allocator, "</Size></Part>");
    }
    try xml.appendSlice(allocator, "</ListPartsResult>");

    res.ok();
    res.setXmlBody(try xml.toOwnedSlice(allocator));
}

fn handleCompleteMultipart(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, key: []const u8) !void {
    const upload_id = getQueryParam(req.query, "uploadId") orelse {
        sendError(res, 400, "InvalidRequest", "Missing uploadId");
        return;
    };
    if (!isValidUploadId(upload_id)) {
        sendError(res, 400, "InvalidArgument", "Invalid uploadId");
        return;
    }

    const parts_dir = std.fmt.allocPrint(allocator, "{s}/.uploads/{s}", .{ ctx.data_dir, upload_id }) catch {
        sendError(res, 500, "InternalError", "Allocation failed");
        return;
    };
    defer allocator.free(parts_dir);

    const final_path = try ctx.objectPath(allocator, bucket, key);
    defer allocator.free(final_path);

    // Upload-level state written at initiate: SSE mode and attributes.
    const upload_meta = readUploadMeta(ctx, allocator, upload_id) orelse {
        sendError(res, 404, "NoSuchUpload", "Upload not found");
        return;
    };
    const upload_sse = uploadSseFromMeta(upload_meta);
    // Attributes sent at initiate (Content-Type, metadata, tags, ACL); the
    // upload directory goes away after assembly, so read them now.
    const init_attrs: ?ObjectAttrs = blk: {
        const attrs_path = try std.fmt.allocPrint(allocator, "{s}/.attrs", .{parts_dir});
        defer allocator.free(attrs_path);
        var f = std.Io.Dir.cwd().openFile(app_io, attrs_path, .{}) catch break :blk null;
        defer f.close(app_io);
        const text = readToEndAlloc(f, allocator, 64 * 1024) catch break :blk null;
        defer allocator.free(text);
        break :blk parseAttrsContent(allocator, text) catch null;
    };
    const sse_mode: ?SseMode = uploadSseMode(allocator, req, res, upload_sse) catch return;
    const sse_ikm: ?[32]u8 = if (sse_mode) |m| (sseIkm(ctx, m) catch {
        sseErrorResponse(res, error.BadSseKey);
        return;
    }) else null;
    var encryptor: ?SseEncryptor = if (sse_mode) |m| (SseEncryptor.init(allocator, &sse_ikm.?, m) catch {
        sendError(res, 500, "InternalError", "Encryption failed");
        return;
    }) else null;
    defer if (encryptor) |*e| e.deinit(allocator);

    const vstatus = bucketVersioning(ctx, allocator, bucket);
    archiveCurrentVersion(ctx, allocator, bucket, key, final_path, vstatus) catch {
        sendError(res, 500, "InternalError", "Cannot archive previous version");
        return;
    };

    if (std.fs.path.dirname(final_path)) |dir| {
        std.Io.Dir.cwd().createDirPath(app_io, dir) catch |err| {
            std.log.warn("makePath failed: {}", .{err});
        };
    }

    var final_file = std.Io.Dir.cwd().createFile(app_io, final_path, .{}) catch {
        sendError(res, 500, "InternalError", "Cannot create final file");
        return;
    };
    defer final_file.close(app_io);
    if (encryptor) |*e| {
        final_file.writeStreamingAll(app_io, e.out.items) catch {};
        e.out.clearRetainingCapacity();
    }

    var dir = std.Io.Dir.cwd().openDir(app_io, parts_dir, .{ .iterate = true }) catch {
        sendError(res, 404, "NoSuchUpload", "Upload not found");
        return;
    };
    defer dir.close(app_io);

    var parts: std.ArrayListUnmanaged(u32) = .empty;
    defer parts.deinit(allocator);

    var iter = dir.iterate();
    while (try iter.next(app_io)) |entry| {
        if (entry.kind == .file and entry.name[0] != '.') {
            const num = std.fmt.parseInt(u32, entry.name, 10) catch continue;
            try parts.append(allocator, num);
        }
    }

    std.mem.sort(u32, parts.items, {}, std.sort.asc(u32));

    var hasher = std.crypto.hash.Md5.init(.{});
    var parts_assembled: usize = 0;

    for (parts.items) |part_num| {
        var part_num_buf: [16]u8 = undefined;
        const part_num_str = std.fmt.bufPrint(&part_num_buf, "{d}", .{part_num}) catch continue;
        const part_path = std.fmt.allocPrint(allocator, "{s}/{s}", .{ parts_dir, part_num_str }) catch {
            std.log.warn("allocation failed for part path", .{});
            continue;
        };
        defer allocator.free(part_path);

        var part_file = std.Io.Dir.cwd().openFile(app_io, part_path, .{}) catch |err| {
            std.log.warn("failed to open part {d}: {}", .{ part_num, err });
            continue;
        };
        defer part_file.close(app_io);

        const stat = part_file.stat(app_io) catch continue;
        const data = allocator.alloc(u8, stat.size) catch continue;
        defer allocator.free(data);

        const bytes_read = part_file.readPositionalAll(app_io, data, 0) catch continue;
        var plain: []const u8 = data[0..bytes_read];
        if (encryptor) |*e| {
            // Parts were encrypted with the same key material at upload.
            const dec = sseDecrypt(allocator, plain, &sse_ikm.?) catch {
                sendError(res, 500, "InternalError", "Stored part failed authentication");
                return;
            };
            plain = dec;
            e.update(allocator, plain) catch {
                sendError(res, 500, "InternalError", "Encryption failed");
                return;
            };
            final_file.writeStreamingAll(app_io, e.out.items) catch |err| {
                std.log.warn("failed to write part {d}: {}", .{ part_num, err });
                continue;
            };
            e.out.clearRetainingCapacity();
        } else {
            final_file.writeStreamingAll(app_io, plain) catch |err| {
                std.log.warn("failed to write part {d}: {}", .{ part_num, err });
                continue;
            };
        }

        var part_hash: [16]u8 = undefined;
        std.crypto.hash.Md5.hash(plain, &part_hash, .{});
        hasher.update(&part_hash);
        parts_assembled += 1;
    }
    if (encryptor) |*e| {
        e.finish(allocator) catch {};
        final_file.writeStreamingAll(app_io, e.out.items) catch {};
        e.out.clearRetainingCapacity();
    }

    std.Io.Dir.cwd().deleteTree(app_io, parts_dir) catch |err| {
        std.log.warn("failed to cleanup upload dir: {}", .{err});
    };
    if (enable_fsync) {
        final_file.sync(app_io) catch {};
        fsyncParentDir(final_path);
    }

    var final_hash: [16]u8 = undefined;
    hasher.final(&final_hash);
    const composite_etag = try std.fmt.allocPrint(allocator, "\"{x}-{d}\"", .{ final_hash, parts_assembled });

    // Attributes: those sent at initiate (Content-Type, metadata, tags, ACL),
    // else anything on this request; plus version id and SSE state.
    var final_attrs: ObjectAttrs = init_attrs orelse
        (collectRequestAttrs(allocator, req) catch ObjectAttrs{ .content_type = try allocator.dupe(u8, DEFAULT_CONTENT_TYPE) });
    defer final_attrs.deinit(allocator);
    if (vstatus == .enabled) final_attrs.version_id = try newVersionId(allocator);
    if (sse_mode) |m| {
        try applySseToAttrs(allocator, &final_attrs, m, "");
        noteBucketSseUsed(ctx, allocator, bucket);
        allocator.free(final_attrs.etag.?);
        final_attrs.etag = try allocator.dupe(u8, composite_etag);
    }
    saveStandaloneAttrs(allocator, final_path, &final_attrs);
    if (final_attrs.acl != null) noteObjectAclUsed(ctx);
    if (final_attrs.version_id) |v| {
        res.setHeader("x-amz-version-id", try allocator.dupe(u8, v));
    } else if (vstatus != .disabled) {
        res.setHeader("x-amz-version-id", NULL_VERSION);
    }
    applySseResponseHeaders(res, &final_attrs, allocator);

    // In distributed mode, index the assembled file so distributed GET can find it
    if (ctx.distributed) |dist| {
        const assembled = blk: {
            var f = std.Io.Dir.cwd().openFile(app_io, final_path, .{}) catch break :blk null;
            defer f.close(app_io);
            const stat = f.stat(app_io) catch break :blk null;
            const data = allocator.alloc(u8, stat.size) catch break :blk null;
            const n = f.readPositionalAll(app_io, data, 0) catch break :blk null;
            break :blk data[0..n];
        };
        if (assembled) |data| {
            const content_hash = CAS.computeHash(data);
            if (data.len <= INLINE_THRESHOLD) {
                dist.meta_index.putWithData(allocator, bucket, key, content_hash, data.len, data) catch {};
            } else {
                _ = dist.cas.store(allocator, data) catch {};
                dist.meta_index.put(allocator, bucket, key, content_hash, data.len) catch {};
                dist.kademlia.announce(content_hash) catch {};
                dist.replication.schedule(content_hash) catch {};
            }
            propagateObjectMeta(ctx, allocator, bucket, key);
            if (data.len > INLINE_THRESHOLD) {
                dist.worker.enqueue(.{ .blob = .{ .hash = content_hash } });
            }
        }
    }

    var xml: std.ArrayListUnmanaged(u8) = .empty;
    defer xml.deinit(allocator);

    try xml.appendSlice(allocator, "<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
    try xml.appendSlice(allocator, "<CompleteMultipartUploadResult xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\">");
    try xml.appendSlice(allocator, "<Bucket>");
    try xml.appendSlice(allocator, bucket);
    try xml.appendSlice(allocator, "</Bucket><Key>");
    try xmlEscape(allocator, &xml, key);
    try xml.appendSlice(allocator, "</Key><ETag>");
    try xml.appendSlice(allocator, composite_etag);
    try xml.appendSlice(allocator, "</ETag></CompleteMultipartUploadResult>");

    res.ok();
    res.setXmlBody(try xml.toOwnedSlice(allocator));
}

fn handleAbortMultipart(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response) !void {
    const upload_id = getQueryParam(req.query, "uploadId") orelse {
        sendError(res, 400, "InvalidRequest", "Missing uploadId");
        return;
    };
    if (!isValidUploadId(upload_id)) {
        sendError(res, 400, "InvalidArgument", "Invalid uploadId");
        return;
    }

    const parts_dir = std.fmt.allocPrint(allocator, "{s}/.uploads/{s}", .{ ctx.data_dir, upload_id }) catch {
        sendError(res, 500, "InternalError", "Allocation failed");
        return;
    };
    defer allocator.free(parts_dir);

    std.Io.Dir.cwd().deleteTree(app_io, parts_dir) catch |err| {
        std.log.warn("abort multipart cleanup failed: {}", .{err});
    };

    res.noContent();
}

pub const Range = struct { start: u64, end: u64 };

pub fn parseRange(header: []const u8, file_size: u64) ?Range {
    if (!std.mem.startsWith(u8, header, "bytes=")) return null;
    const range_spec = header[6..];

    const dash = std.mem.indexOf(u8, range_spec, "-") orelse return null;
    const start_str = range_spec[0..dash];
    const end_str = range_spec[dash + 1 ..];

    // Suffix range: bytes=-N means last N bytes (clamp to file size per RFC 7233)
    if (start_str.len == 0 and end_str.len > 0) {
        const suffix_len = std.fmt.parseInt(u64, end_str, 10) catch return null;
        if (suffix_len == 0) return null;
        const actual = @min(suffix_len, file_size);
        return .{ .start = file_size - actual, .end = file_size - 1 };
    }

    if (file_size == 0) return null;
    const start = if (start_str.len > 0) std.fmt.parseInt(u64, start_str, 10) catch return null else 0;
    const end = if (end_str.len > 0) std.fmt.parseInt(u64, end_str, 10) catch return null else file_size - 1;

    if (start > end or end >= file_size) return null;
    return .{ .start = start, .end = end };
}

pub fn hasQuery(query: []const u8, key: []const u8) bool {
    if (std.mem.indexOf(u8, query, key)) |idx| {
        const at_start = (idx == 0) or (query[idx - 1] == '&');
        const end = idx + key.len;
        const at_end = (end == query.len) or (query[end] == '&') or (query[end] == '=');
        if (at_start and at_end) return true;
    }
    return false;
}

pub fn getQueryParam(query: []const u8, key: []const u8) ?[]const u8 {
    var iter = std.mem.splitScalar(u8, query, '&');
    while (iter.next()) |pair| {
        if (std.mem.indexOf(u8, pair, "=")) |eq_idx| {
            if (std.mem.eql(u8, pair[0..eq_idx], key)) {
                return pair[eq_idx + 1 ..];
            }
        } else {
            if (std.mem.eql(u8, pair, key)) {
                return "";
            }
        }
    }
    return null;
}

/// Decode an HTTP/1.1 chunked body (RFC 9112 §7.1). Chunk extensions and
/// trailers are ignored. Returns what was decoded before any malformed chunk.
pub fn decodeHttpChunked(allocator: Allocator, body: []const u8) ![]u8 {
    var out: std.ArrayListUnmanaged(u8) = .empty;
    errdefer out.deinit(allocator);
    var rest = body;
    while (true) {
        const eol = std.mem.indexOf(u8, rest, "\r\n") orelse break;
        var size_text = rest[0..eol];
        if (std.mem.indexOfScalar(u8, size_text, ';')) |semi| size_text = size_text[0..semi];
        const size = std.fmt.parseInt(usize, std.mem.trim(u8, size_text, " \t"), 16) catch break;
        rest = rest[eol + 2 ..];
        if (size == 0) break;
        if (rest.len < size) {
            try out.appendSlice(allocator, rest);
            break;
        }
        try out.appendSlice(allocator, rest[0..size]);
        rest = rest[size..];
        if (std.mem.startsWith(u8, rest, "\r\n")) rest = rest[2..];
    }
    return out.toOwnedSlice(allocator);
}

/// Text of the first <tag>...</tag> in `xml` (no attribute or nesting
/// support; enough for the flat S3 request/response bodies zs3 handles).
pub fn xmlTagText(xml: []const u8, tag: []const u8) ?[]const u8 {
    var open_buf: [64]u8 = undefined;
    var close_buf: [64]u8 = undefined;
    if (tag.len + 3 > open_buf.len) return null;
    const open = std.fmt.bufPrint(&open_buf, "<{s}>", .{tag}) catch return null;
    const close = std.fmt.bufPrint(&close_buf, "</{s}>", .{tag}) catch return null;
    const start = std.mem.indexOf(u8, xml, open) orelse return null;
    const body = xml[start + open.len ..];
    const end = std.mem.indexOf(u8, body, close) orelse return null;
    return std.mem.trim(u8, body[0..end], " \t\r\n");
}

pub fn xmlEscape(allocator: Allocator, list: *std.ArrayListUnmanaged(u8), input: []const u8) !void {
    for (input) |c| {
        switch (c) {
            '<' => try list.appendSlice(allocator, "&lt;"),
            '>' => try list.appendSlice(allocator, "&gt;"),
            '&' => try list.appendSlice(allocator, "&amp;"),
            '"' => try list.appendSlice(allocator, "&quot;"),
            '\'' => try list.appendSlice(allocator, "&apos;"),
            else => try list.append(allocator, c),
        }
    }
}

// ============================================================================
// DISTRIBUTED HANDLERS
// ============================================================================

/// Handle peer-to-peer protocol endpoints (/_zs3/*)
fn handlePeerProtocol(ctx: *const S3Context, dist: *DistributedContext, allocator: Allocator, req: *Request, res: *Response, path: []const u8) !void {
    if (std.mem.eql(u8, path, "ping")) {
        if (req.header("x-zs3-node-id")) |peer_id_hex| {
            if (req.header("x-zs3-port")) |peer_port_text| {
                if (peer_id_hex.len == 40) {
                    var peer_id: NodeId = undefined;
                    if (std.fmt.hexToBytes(&peer_id, peer_id_hex)) |_| {
                        if (std.fmt.parseInt(u16, peer_port_text, 10)) |peer_port| {
                            var peer_address = req.remote_address;
                            peer_address.setPort(peer_port);
                            dist.kademlia.addPeer(.{
                                .id = peer_id,
                                .address = peer_address,
                                .last_seen = std.Io.Clock.real.now(app_io).toSeconds(),
                                .content_count = 0,
                            });
                        } else |_| {}
                    } else |_| {}
                }
            }
        }

        // Health check - returns node ID
        var id_hex: [40]u8 = undefined;
        bytesToHex(&dist.config.node_id, &id_hex);
        res.ok();
        res.body = try std.fmt.allocPrint(allocator, "{{\"id\":\"{s}\",\"peers\":{d}}}", .{ id_hex, dist.kademlia.peerCount() });
    } else if (std.mem.eql(u8, path, "peers")) {
        // Return known peers for gossip
        var json: std.ArrayListUnmanaged(u8) = .empty;
        try json.appendSlice(allocator, "[");

        var peers: [20]PeerInfo = undefined;
        var seed: u64 = undefined;
        app_io.random(std.mem.asBytes(&seed));
        var prng = std.Random.DefaultPrng.init(seed);
        const count = dist.kademlia.getRandomPeers(&peers, prng.random());

        for (peers[0..count], 0..) |peer, i| {
            if (i > 0) try json.appendSlice(allocator, ",");
            var id_hex: [40]u8 = undefined;
            bytesToHex(&peer.id, &id_hex);

            var buf: [192]u8 = undefined;
            const peer_json = std.fmt.bufPrint(&buf, "{{\"id\":\"{s}\",\"port\":{d},\"addr\":\"{f}\"}}", .{ id_hex, peer.address.getPort(), peer.address }) catch continue;
            try json.appendSlice(allocator, peer_json);
        }

        try json.appendSlice(allocator, "]");
        res.ok();
        res.setHeader("Content-Type", "application/json");
        res.body = try json.toOwnedSlice(allocator);
    } else if (std.mem.startsWith(u8, path, "blob/")) {
        // Content transfer by hash
        const hash_hex = path[5..];
        if (hash_hex.len != 40) {
            sendError(res, 400, "InvalidRequest", "Invalid hash");
            return;
        }

        var hash: ContentHash = undefined;
        _ = std.fmt.hexToBytes(&hash, hash_hex) catch {
            sendError(res, 400, "InvalidRequest", "Invalid hash format");
            return;
        };

        if (std.mem.eql(u8, req.method, "GET")) {
            // Fetch blob by hash
            const data = dist.cas.retrieve(allocator, hash) catch {
                sendError(res, 404, "NotFound", "Content not found");
                return;
            };
            res.ok();
            res.body = data;
        } else if (std.mem.eql(u8, req.method, "PUT")) {
            // Store blob (pushed from another node) and record ourselves as provider
            const stored_hash = dist.cas.store(allocator, req.body) catch {
                sendError(res, 500, "InternalError", "Failed to store");
                return;
            };
            dist.kademlia.announce(stored_hash) catch {};
            res.ok();
        } else {
            sendError(res, 405, "MethodNotAllowed", "Method not allowed");
        }
    } else if (std.mem.startsWith(u8, path, "providers/")) {
        // Find providers for content
        const hash_hex = path[10..];
        if (hash_hex.len != 40) {
            sendError(res, 400, "InvalidRequest", "Invalid hash");
            return;
        }

        var hash: ContentHash = undefined;
        _ = std.fmt.hexToBytes(&hash, hash_hex) catch {
            sendError(res, 400, "InvalidRequest", "Invalid hash format");
            return;
        };

        const providers = dist.kademlia.findProviders(hash);

        var json: std.ArrayListUnmanaged(u8) = .empty;
        try json.appendSlice(allocator, "[");
        for (providers, 0..) |id, i| {
            if (i > 0) try json.appendSlice(allocator, ",");
            var id_hex: [40]u8 = undefined;
            bytesToHex(&id, &id_hex);
            try json.append(allocator, '"');
            try json.appendSlice(allocator, &id_hex);
            try json.append(allocator, '"');
        }
        try json.appendSlice(allocator, "]");

        res.ok();
        res.setHeader("Content-Type", "application/json");
        res.body = try json.toOwnedSlice(allocator);
    } else if (std.mem.eql(u8, path, "announce")) {
        // Announce content availability
        if (!std.mem.eql(u8, req.method, "POST")) {
            sendError(res, 405, "MethodNotAllowed", "Use POST");
            return;
        }
        // Body should contain: hash_hex\nnode_id_hex
        var lines = std.mem.splitScalar(u8, req.body, '\n');
        const hash_hex = lines.next() orelse {
            sendError(res, 400, "InvalidRequest", "Missing hash");
            return;
        };
        const provider_hex = lines.next() orelse {
            sendError(res, 400, "InvalidRequest", "Missing provider");
            return;
        };

        if (hash_hex.len != 40 or provider_hex.len != 40) {
            sendError(res, 400, "InvalidRequest", "Invalid format");
            return;
        }

        var hash: ContentHash = undefined;
        var provider: NodeId = undefined;
        _ = std.fmt.hexToBytes(&hash, hash_hex) catch {
            sendError(res, 400, "InvalidRequest", "Invalid hash");
            return;
        };
        _ = std.fmt.hexToBytes(&provider, provider_hex) catch {
            sendError(res, 400, "InvalidRequest", "Invalid provider");
            return;
        };

        dist.kademlia.addProvider(hash, provider) catch {};
        res.ok();
    } else if (std.mem.eql(u8, path, "findnode")) {
        // Kademlia FIND_NODE
        const target_hex = req.header("x-target-id") orelse {
            sendError(res, 400, "InvalidRequest", "Missing X-Target-Id header");
            return;
        };

        if (target_hex.len != 40) {
            sendError(res, 400, "InvalidRequest", "Invalid target ID");
            return;
        }

        var target: NodeId = undefined;
        _ = std.fmt.hexToBytes(&target, target_hex) catch {
            sendError(res, 400, "InvalidRequest", "Invalid target format");
            return;
        };

        var closest: [Kademlia.K]PeerInfo = undefined;
        const count = dist.kademlia.findClosest(target, &closest);

        var json: std.ArrayListUnmanaged(u8) = .empty;
        try json.appendSlice(allocator, "[");
        for (closest[0..count], 0..) |peer, i| {
            if (i > 0) try json.appendSlice(allocator, ",");
            var id_hex: [40]u8 = undefined;
            bytesToHex(&peer.id, &id_hex);
            var buf: [128]u8 = undefined;
            const peer_json = std.fmt.bufPrint(&buf, "{{\"id\":\"{s}\",\"port\":{d}}}", .{ id_hex, peer.address.getPort() }) catch continue;
            try json.appendSlice(allocator, peer_json);
        }
        try json.appendSlice(allocator, "]");

        res.ok();
        res.setHeader("Content-Type", "application/json");
        res.body = try json.toOwnedSlice(allocator);
    } else if (std.mem.eql(u8, path, "meta")) {
        // Replicated metadata entry pushed from a peer
        // Body: "<bucket>\n<key>\n<raw meta content>"
        if (!std.mem.eql(u8, req.method, "POST")) {
            sendError(res, 405, "MethodNotAllowed", "Use POST");
            return;
        }
        const bucket_end = std.mem.indexOfScalar(u8, req.body, '\n') orelse {
            sendError(res, 400, "InvalidRequest", "Missing bucket");
            return;
        };
        const bucket = req.body[0..bucket_end];
        const key_end = std.mem.indexOfScalarPos(u8, req.body, bucket_end + 1, '\n') orelse {
            sendError(res, 400, "InvalidRequest", "Missing key");
            return;
        };
        const key = req.body[bucket_end + 1 .. key_end];
        const content = req.body[key_end + 1 ..];

        if (!isValidBucketName(bucket) or !isValidKey(key)) {
            sendError(res, 400, "InvalidRequest", "Invalid bucket or key");
            return;
        }
        applyRemoteMeta(ctx, allocator, bucket, key, content) catch {
            sendError(res, 400, "InvalidRequest", "Invalid meta entry");
            return;
        };
        res.ok();
    } else if (std.mem.eql(u8, path, "meta_get")) {
        // Metadata lookup for a peer's read-through fallback
        // Body: "<bucket>\n<key>", response: raw meta content (may be a tombstone)
        if (!std.mem.eql(u8, req.method, "POST")) {
            sendError(res, 405, "MethodNotAllowed", "Use POST");
            return;
        }
        const bucket_end = std.mem.indexOfScalar(u8, req.body, '\n') orelse {
            sendError(res, 400, "InvalidRequest", "Missing bucket");
            return;
        };
        const bucket = req.body[0..bucket_end];
        const key = req.body[bucket_end + 1 ..];

        if (!isValidBucketName(bucket) or !isValidKey(key)) {
            sendError(res, 400, "InvalidRequest", "Invalid bucket or key");
            return;
        }
        const content = (dist.meta_index.readRaw(allocator, bucket, key) catch null) orelse {
            sendError(res, 404, "NotFound", "No metadata for key");
            return;
        };
        res.ok();
        res.body = content;
    } else if (std.mem.eql(u8, path, "attrs")) {
        // Replicated attribute entry pushed from a peer
        // Body: "<bucket>\n<key>\n<raw attrs content>" (empty content = delete)
        if (!std.mem.eql(u8, req.method, "POST")) {
            sendError(res, 405, "MethodNotAllowed", "Use POST");
            return;
        }
        const bucket_end = std.mem.indexOfScalar(u8, req.body, '\n') orelse {
            sendError(res, 400, "InvalidRequest", "Missing bucket");
            return;
        };
        const bucket = req.body[0..bucket_end];
        const key_end = std.mem.indexOfScalarPos(u8, req.body, bucket_end + 1, '\n') orelse {
            sendError(res, 400, "InvalidRequest", "Missing key");
            return;
        };
        const key = req.body[bucket_end + 1 .. key_end];
        const content = req.body[key_end + 1 ..];

        if (!isValidBucketName(bucket) or !isValidKey(key)) {
            sendError(res, 400, "InvalidRequest", "Invalid bucket or key");
            return;
        }
        applyRemoteAttrs(ctx, allocator, bucket, key, content) catch {
            sendError(res, 400, "InvalidRequest", "Invalid attrs entry");
            return;
        };
        res.ok();
    } else if (std.mem.eql(u8, path, "attrs_get")) {
        // Attribute lookup for a peer's read-through fallback
        // Body: "<bucket>\n<key>", response: raw attrs content (empty = none)
        if (!std.mem.eql(u8, req.method, "POST")) {
            sendError(res, 405, "MethodNotAllowed", "Use POST");
            return;
        }
        const bucket_end = std.mem.indexOfScalar(u8, req.body, '\n') orelse {
            sendError(res, 400, "InvalidRequest", "Missing bucket");
            return;
        };
        const bucket = req.body[0..bucket_end];
        const key = req.body[bucket_end + 1 ..];

        if (!isValidBucketName(bucket) or !isValidKey(key)) {
            sendError(res, 400, "InvalidRequest", "Invalid bucket or key");
            return;
        }
        const apath = distAttrsPath(allocator, dist.meta_index.data_dir, bucket, key) catch {
            sendError(res, 400, "InvalidRequest", "Invalid bucket or key");
            return;
        };
        defer allocator.free(apath);
        var afile = std.Io.Dir.cwd().openFile(app_io, apath, .{}) catch {
            sendError(res, 404, "NotFound", "No attributes for key");
            return;
        };
        defer afile.close(app_io);
        const acontent = readToEndAlloc(afile, allocator, MAX_META_RESPONSE) catch {
            sendError(res, 500, "InternalError", "Read failed");
            return;
        };
        res.ok();
        res.body = acontent;
    } else if (std.mem.eql(u8, path, "index")) {
        // Full index dump for a joining peer
        if (!std.mem.eql(u8, req.method, "GET")) {
            sendError(res, 405, "MethodNotAllowed", "Use GET");
            return;
        }
        var out: std.ArrayListUnmanaged(u8) = .empty;
        dumpMetaIndex(dist, allocator, &out) catch {
            out.deinit(allocator);
            sendError(res, 500, "InternalError", "Index dump failed");
            return;
        };
        res.ok();
        res.body = try out.toOwnedSlice(allocator);
    } else if (std.mem.eql(u8, path, "bucket")) {
        // Bucket creation propagated from a peer (body: "bucket\ncreate_ts")
        if (!std.mem.eql(u8, req.method, "POST")) {
            sendError(res, 405, "MethodNotAllowed", "Use POST");
            return;
        }
        const bucket_end = std.mem.indexOfScalar(u8, req.body, '\n') orelse req.body.len;
        if (!isValidBucketName(req.body[0..bucket_end])) {
            sendError(res, 400, "InvalidBucketName", "Bucket name is invalid");
            return;
        }
        const bucket = req.body[0..bucket_end];
        // Missing ts (legacy peer) is treated as "now" so a bare-name create still applies.
        const create_ts = if (bucket_end < req.body.len)
            std.fmt.parseInt(i64, req.body[bucket_end + 1 ..], 10) catch 0
        else
            std.Io.Clock.real.now(app_io).toSeconds();
        // LWW: an older create must not resurrect a bucket deleted more recently.
        if (!dist.bucket_ops.shouldApplyCreate(allocator, bucket, create_ts)) {
            res.ok();
            return;
        }
        const bucket_path = try ctx.bucketPath(allocator, bucket);
        defer allocator.free(bucket_path);
        std.Io.Dir.cwd().createDirPath(app_io, bucket_path) catch {};
        dist.bucket_ops.noteCreate(allocator, bucket, create_ts);
        res.ok();
    } else if (std.mem.eql(u8, path, "bucket_delete")) {
        // Bucket deletion propagated from a peer (body: "bucket\ndelete_ts")
        if (!std.mem.eql(u8, req.method, "POST")) {
            sendError(res, 405, "MethodNotAllowed", "Use POST");
            return;
        }
        const bucket_end = std.mem.indexOfScalar(u8, req.body, '\n') orelse req.body.len;
        if (!isValidBucketName(req.body[0..bucket_end])) {
            sendError(res, 400, "InvalidBucketName", "Bucket name is invalid");
            return;
        }
        const bucket = req.body[0..bucket_end];
        // Missing ts (legacy peer) is treated as "now" so a bare-name delete still applies.
        const delete_ts = if (bucket_end < req.body.len)
            std.fmt.parseInt(i64, req.body[bucket_end + 1 ..], 10) catch 0
        else
            std.Io.Clock.real.now(app_io).toSeconds();
        // LWW: a stale delete must not remove a bucket recreated more recently.
        if (!dist.bucket_ops.shouldApplyDelete(allocator, bucket, delete_ts)) {
            res.ok();
            return;
        }
        const bucket_path = try ctx.bucketPath(allocator, bucket);
        defer allocator.free(bucket_path);
        std.Io.Dir.cwd().deleteTree(app_io, bucket_path) catch {};
        const index_path = try std.fs.path.join(allocator, &.{ dist.meta_index.data_dir, ".index", bucket });
        defer allocator.free(index_path);
        std.Io.Dir.cwd().deleteTree(app_io, index_path) catch {};
        dist.bucket_ops.noteDelete(allocator, bucket, delete_ts);
        res.ok();
    } else {
        sendError(res, 404, "NotFound", "Unknown peer endpoint");
    }
}

/// Distributed PUT - store in CAS, update metadata, announce to DHT
fn handleDistributedPut(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, key: []const u8) !void {
    const dist = ctx.distributed.?;

    // Ensure bucket directory exists in index
    const bucket_path = try ctx.bucketPath(allocator, bucket);
    defer allocator.free(bucket_path);
    std.Io.Dir.cwd().createDirPath(app_io, bucket_path) catch {};

    // Compute content hash
    const hash = CAS.computeHash(req.body);

    // Honor If-Match / If-None-Match against the existing object's MD5 ETag.
    // Content is loaded only when a conditional header is present.
    const if_match = req.header("if-match");
    const if_none_match = req.header("if-none-match");
    if (if_match != null or if_none_match != null) {
        const existing_bytes = readSourceBytes(ctx, allocator, bucket, key) catch null;
        defer if (existing_bytes) |b| allocator.free(b);
        const existing_etag = if (existing_bytes) |b| md5Etag(allocator, b) catch null else null;
        defer if (existing_etag) |e| allocator.free(e);

        if (if_match) |im| {
            const matches = if (existing_etag) |e| etagListMatches(im, e) else false;
            if (!matches) {
                sendError(res, 412, "PreconditionFailed", "At least one of the pre-conditions you specified did not hold");
                return;
            }
        }
        if (if_none_match) |inm| {
            const matches = if (existing_etag) |e| etagListMatches(inm, e) else false;
            if (matches) {
                sendError(res, 412, "PreconditionFailed", "At least one of the pre-conditions you specified did not hold");
                return;
            }
        }
    }

    // For small objects, store inline in metadata (skip CAS)
    // Inline objects are NOT announced to DHT since they can't be fetched via blob API
    if (req.body.len <= INLINE_THRESHOLD) {
        try dist.meta_index.putWithData(allocator, bucket, key, hash, req.body.len, req.body);
    } else {
        // Store content in CAS for larger objects
        _ = try dist.cas.store(allocator, req.body);
        try dist.meta_index.put(allocator, bucket, key, hash, req.body.len);

        // Announce to DHT and schedule replication (only for CAS objects)
        dist.kademlia.announce(hash) catch {};
        dist.replication.schedule(hash) catch {};
    }

    // Propagate the namespace entry to peers synchronously (small, keeps
    // cross-node reads consistent); replicate CAS blobs in the background
    propagateObjectMeta(ctx, allocator, bucket, key);
    // Persist Content-Type / metadata and propagate best-effort.
    if (collectRequestAttrs(allocator, req)) |a| {
        defer a.deinit(allocator);
        writeDistAttrs(allocator, dist, bucket, key, &a);
        propagateObjectAttrs(ctx, allocator, bucket, key);
        echoRequestChecksums(req, res);
    } else |_| {}
    if (req.body.len > INLINE_THRESHOLD) {
        dist.worker.enqueue(.{ .blob = .{ .hash = hash } });
    }

    // Return ETag as the MD5 of the content (matches standalone mode).
    const etag = try md5Etag(allocator, req.body);

    metrics.put_bytes += req.body.len;
    res.ok();
    res.setHeader("ETag", etag);
}

/// Distributed GET - lookup metadata, retrieve from CAS/inline or peers with quorum
fn handleDistributedGet(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, key: []const u8) !void {
    const dist = ctx.distributed.?;

    // Lookup metadata (for Last-Modified and the existence check),
    // falling back to a peer lookup when the entry isn't known locally.
    const meta = try dist.meta_index.getFull(allocator, bucket, key) orelse
        fetchMetaFromPeers(ctx, allocator, bucket, key) orelse {
            sendError(res, 404, "NoSuchKey", "Object not found");
            return;
        };
    // Note: inline_data/bytes are arena-allocated, freed after the write.

    // Load bytes through inline/CAS/provider/peer fallback.
    const data = readSourceBytes(ctx, allocator, bucket, key) catch {
        sendError(res, 404, "NoSuchKey", "Content not available from any provider");
        return;
    };

    // ETag is the MD5 of the content, matching standalone mode.
    const etag = md5Etag(allocator, data) catch {
        sendError(res, 500, "InternalError", "ETag failed");
        return;
    };
    if (req.header("if-match")) |im| {
        if (!etagListMatches(im, etag)) {
            sendError(res, 412, "PreconditionFailed", "At least one of the pre-conditions you specified did not hold");
            return;
        }
    }
    if (req.header("if-none-match")) |inm| {
        if (etagListMatches(inm, etag)) {
            res.status = 304;
            res.status_text = "Not Modified";
            return;
        }
    }

    // NB: no deinit on dattrs — serveContent headers borrow it (arena).
    const dattrs = readDistAttrs(allocator, dist, bucket, key) orelse fetchAttrsFromPeers(ctx, allocator, bucket, key);
    const dattrs_ptr: ?*const ObjectAttrs = if (dattrs) |*a| a else null;

    return serveContent(allocator, req, res, data, etag, meta.created, dattrs_ptr);
}

/// Serve content with range request support
fn serveContent(allocator: Allocator, req: *Request, res: *Response, data: []const u8, etag: []const u8, created: i64, attrs: ?*const ObjectAttrs) void {
    const last_modified = allocHttpDate(allocator, created) catch {
        sendError(res, 500, "InternalError", "Date format failed");
        return;
    };

    // Handle range requests
    if (req.header("range")) |range_header| {
        if (parseRange(range_header, data.len)) |range| {
            const content_range = std.fmt.allocPrint(allocator, "bytes {d}-{d}/{d}", .{ range.start, range.end, data.len }) catch {
                sendError(res, 500, "InternalError", "Range format failed");
                return;
            };

            res.status = 206;
            res.status_text = "Partial Content";
            res.setHeader("Content-Range", content_range);
            res.setHeader("Accept-Ranges", "bytes");
            res.setHeader("Last-Modified", last_modified);
            if (attrs) |a| applyAttrsToRangeResponse(res, a) else res.setHeader("Content-Type", DEFAULT_CONTENT_TYPE);
            metrics.get_bytes += range.end - range.start + 1;
            res.body = data[range.start .. range.end + 1];
            return;
        }
    }

    res.ok();
    res.setHeader("Accept-Ranges", "bytes");

    res.setHeader("ETag", etag);
    res.setHeader("Last-Modified", last_modified);
    if (attrs) |a| applyAttrsToResponse(res, a) else res.setHeader("Content-Type", DEFAULT_CONTENT_TYPE);
    metrics.get_bytes += data.len;
    res.body = data;
}

/// Fetch content from a remote peer
fn fetchFromPeer(allocator: Allocator, address: net.IpAddress, hash: ContentHash) ![]const u8 {
    var hash_hex: [40]u8 = undefined;
    bytesToHex(&hash, &hash_hex);
    var path_buf: [64]u8 = undefined;
    const path = std.fmt.bufPrint(&path_buf, "/_zs3/blob/{s}", .{hash_hex}) catch return error.BufferTooSmall;
    return peerRequest(allocator, address, "GET", path, "", MAX_BODY_SIZE);
}

/// Set send/receive timeouts on a peer socket so a stuck peer can't wedge
/// the event loop (peer requests are synchronous within a request handler)
fn setPeerTimeout(stream: net.Stream) void {
    const tv = posix.timeval{ .sec = PEER_IO_TIMEOUT_SECS, .usec = 0 };
    posix.setsockopt(stream.socket.handle, posix.SOL.SOCKET, posix.SO.RCVTIMEO, std.mem.asBytes(&tv)) catch {};
    posix.setsockopt(stream.socket.handle, posix.SOL.SOCKET, posix.SO.SNDTIMEO, std.mem.asBytes(&tv)) catch {};
}

/// Send a request to a peer's /_zs3/ endpoint and return the response body
fn peerRequest(allocator: Allocator, address: net.IpAddress, method: []const u8, path: []const u8, body: []const u8, max_response: usize) ![]u8 {
    var stream = address.connect(app_io, .{ .mode = .stream }) catch return error.ConnectionFailed;
    defer stream.close(app_io);
    setPeerTimeout(stream);

    var header_buf: [512]u8 = undefined;
    const header = std.fmt.bufPrint(&header_buf, "{s} {s} HTTP/1.1\r\nHost: {f}\r\nContent-Length: {d}\r\nConnection: close\r\n\r\n", .{ method, path, address, body.len }) catch return error.BufferTooSmall;
    streamWriteAll(stream, header) catch return error.WriteFailed;
    if (body.len > 0) streamWriteAll(stream, body) catch return error.WriteFailed;

    var response: std.ArrayListUnmanaged(u8) = .empty;
    defer response.deinit(allocator);
    var chunk: [16 * 1024]u8 = undefined;
    while (true) {
        const n = streamRead(stream, &chunk) catch break;
        if (n == 0) break;
        try response.appendSlice(allocator, chunk[0..n]);
        if (response.items.len > max_response) return error.ResponseTooLarge;
    }

    const data = response.items;
    const header_end = std.mem.indexOf(u8, data, "\r\n\r\n") orelse return error.InvalidResponse;
    if (!std.mem.startsWith(u8, data, "HTTP/1.1 200")) return error.RequestFailed;
    return allocator.dupe(u8, data[header_end + 4 ..]);
}

/// Best-effort broadcast of a peer-protocol request to all known peers
fn broadcastToPeers(dist: *DistributedContext, allocator: Allocator, method: []const u8, path: []const u8, body: []const u8) void {
    var peers: [MAX_BROADCAST_PEERS]PeerInfo = undefined;
    const n = dist.kademlia.collectPeers(&peers);
    for (peers[0..n]) |peer| {
        const response = peerRequest(allocator, peer.address, method, path, body, 4096) catch continue;
        allocator.free(response);
    }
}

/// Parse the logical timestamp of a raw meta entry: max(created, deleted).
/// Returns null if the content doesn't parse as a meta entry (also validates).
pub fn metaContentTimestamp(content: []const u8) ?i64 {
    var lines = std.mem.splitScalar(u8, content, '\n');
    const hash_hex = lines.next() orelse return null;
    if (hash_hex.len != 40) return null;
    var hash: ContentHash = undefined;
    _ = std.fmt.hexToBytes(&hash, hash_hex) catch return null;
    _ = std.fmt.parseInt(u64, lines.next() orelse return null, 10) catch return null;
    const created = std.fmt.parseInt(i64, lines.next() orelse return null, 10) catch return null;
    const deleted = std.fmt.parseInt(i64, lines.next() orelse return null, 10) catch return null;
    return @max(created, deleted);
}

pub fn isTombstoneContent(content: []const u8) bool {
    var lines = std.mem.splitScalar(u8, content, '\n');
    _ = lines.next(); // hash
    _ = lines.next(); // size
    _ = lines.next(); // created
    const deleted_str = lines.next() orelse return false;
    const deleted = std.fmt.parseInt(i64, deleted_str, 10) catch return false;
    return deleted > 0;
}

/// Apply a meta entry received from a peer with last-write-wins conflict
/// resolution (ties prefer the tombstone so deletes don't resurrect)
fn applyRemoteMeta(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, key: []const u8, content: []const u8) !void {
    const dist = ctx.distributed.?;
    const incoming_ts = metaContentTimestamp(content) orelse return error.InvalidMeta;

    if (dist.meta_index.readRaw(allocator, bucket, key) catch null) |existing| {
        defer allocator.free(existing);
        if (metaContentTimestamp(existing)) |existing_ts| {
            if (existing_ts > incoming_ts) return;
            if (existing_ts == incoming_ts and !isTombstoneContent(content)) return;
        }
    }

    // Ensure the bucket data dir exists so ListBuckets sees the bucket
    const bucket_path = try ctx.bucketPath(allocator, bucket);
    defer allocator.free(bucket_path);
    std.Io.Dir.cwd().createDirPath(app_io, bucket_path) catch {};

    try dist.meta_index.writeRaw(allocator, bucket, key, content);
}

/// Push the local meta entry (object or tombstone) for bucket/key to all peers
fn propagateObjectMeta(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, key: []const u8) void {
    const dist = ctx.distributed orelse return;
    const content = (dist.meta_index.readRaw(allocator, bucket, key) catch return) orelse return;
    defer allocator.free(content);

    const body = std.fmt.allocPrint(allocator, "{s}\n{s}\n{s}", .{ bucket, key, content }) catch return;
    defer allocator.free(body);
    broadcastToPeers(dist, allocator, "POST", "/_zs3/meta", body);
}

/// Push the local attribute entry for bucket/key to all peers. An empty
/// content means "no attributes" (e.g. after a delete), telling peers to drop
/// their copy so stale Content-Types don't survive.
fn propagateObjectAttrs(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, key: []const u8) void {
    const dist = ctx.distributed orelse return;
    const path = distAttrsPath(allocator, dist.meta_index.data_dir, bucket, key) catch return;
    defer allocator.free(path);
    var content: []const u8 = "";
    var owned: ?[]u8 = null;
    if (std.Io.Dir.cwd().openFile(app_io, path, .{})) |file| {
        defer file.close(app_io);
        owned = readToEndAlloc(file, allocator, 64 * 1024) catch null;
        if (owned) |o| content = o;
    } else |_| {}
    defer if (owned) |o| allocator.free(o);

    const body = std.fmt.allocPrint(allocator, "{s}\n{s}\n{s}", .{ bucket, key, content }) catch return;
    defer allocator.free(body);
    broadcastToPeers(dist, allocator, "POST", "/_zs3/attrs", body);
}

/// Apply an attribute entry received from a peer. Attributes carry no
/// timestamp; the meta entry (which has LWW) is the source of ordering truth
/// and is always pushed before its attributes.
fn applyRemoteAttrs(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, key: []const u8, content: []const u8) !void {
    const dist = ctx.distributed.?;
    if (content.len == 0) {
        deleteDistAttrs(allocator, dist, bucket, key);
        return;
    }
    // Validate shape before storing.
    const parsed = try parseAttrsContent(allocator, content);
    parsed.deinit(allocator);
    const path = try distAttrsPath(allocator, dist.meta_index.data_dir, bucket, key);
    defer allocator.free(path);
    if (std.fs.path.dirname(path)) |dir| {
        std.Io.Dir.cwd().createDirPath(app_io, dir) catch {};
    }
    var file = try std.Io.Dir.cwd().createFile(app_io, path, .{});
    defer file.close(app_io);
    try file.writeStreamingAll(app_io, content);
}

/// Read-through fallback for attributes: ask peers, cache locally.
fn fetchAttrsFromPeers(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, key: []const u8) ?ObjectAttrs {
    const dist = ctx.distributed.?;
    const body = std.fmt.allocPrint(allocator, "{s}\n{s}", .{ bucket, key }) catch return null;
    defer allocator.free(body);

    var peers: [MAX_BROADCAST_PEERS]PeerInfo = undefined;
    const n = dist.kademlia.collectPeers(&peers);
    for (peers[0..n]) |peer| {
        const content = peerRequest(allocator, peer.address, "POST", "/_zs3/attrs_get", body, MAX_META_RESPONSE) catch continue;
        defer allocator.free(content);
        if (content.len == 0) continue;
        applyRemoteAttrs(ctx, allocator, bucket, key, content) catch continue;
        return readDistAttrs(allocator, dist, bucket, key);
    }
    return null;
}

/// Tell all peers that `provider` has the content for `hash`
fn broadcastAnnounce(dist: *DistributedContext, allocator: Allocator, hash: ContentHash, provider: NodeId) void {
    var hash_hex: [40]u8 = undefined;
    bytesToHex(&hash, &hash_hex);
    var provider_hex: [40]u8 = undefined;
    bytesToHex(&provider, &provider_hex);

    var body_buf: [81]u8 = undefined;
    const body = std.fmt.bufPrint(&body_buf, "{s}\n{s}", .{ hash_hex, provider_hex }) catch return;
    broadcastToPeers(dist, allocator, "POST", "/_zs3/announce", body);
}

/// Push a CAS blob to peers until the replication target is met
/// (this node counts as one replica), announcing each new holder
fn replicateBlob(dist: *DistributedContext, allocator: Allocator, hash: ContentHash) void {
    if (dist.replication.target_replicas <= 1) return;
    const data = dist.cas.retrieve(allocator, hash) catch return;
    defer allocator.free(data);

    var hash_hex: [40]u8 = undefined;
    bytesToHex(&hash, &hash_hex);
    var path_buf: [64]u8 = undefined;
    const path = std.fmt.bufPrint(&path_buf, "/_zs3/blob/{s}", .{hash_hex}) catch return;

    var peers: [MAX_BROADCAST_PEERS]PeerInfo = undefined;
    const n = dist.kademlia.collectPeers(&peers);
    var replicas: usize = 1;
    for (peers[0..n]) |peer| {
        if (replicas >= dist.replication.target_replicas) break;
        const response = peerRequest(allocator, peer.address, "PUT", path, data, 4096) catch continue;
        allocator.free(response);
        replicas += 1;
        // No local addProvider here: this runs on the worker thread and the
        // providers map belongs to the event loop; peers learn via announce
        broadcastAnnounce(dist, allocator, hash, peer.id);
    }
}

/// Read-through fallback: on a local metadata miss, ask peers for the entry.
/// Caches whatever it learns locally (including tombstones) via LWW.
fn fetchMetaFromPeers(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, key: []const u8) ?MetaIndex.ObjectMeta {
    const dist = ctx.distributed.?;

    const body = std.fmt.allocPrint(allocator, "{s}\n{s}", .{ bucket, key }) catch return null;
    defer allocator.free(body);

    var peers: [MAX_BROADCAST_PEERS]PeerInfo = undefined;
    const n = dist.kademlia.collectPeers(&peers);
    for (peers[0..n]) |peer| {
        const content = peerRequest(allocator, peer.address, "POST", "/_zs3/meta_get", body, MAX_META_RESPONSE) catch continue;
        defer allocator.free(content);

        applyRemoteMeta(ctx, allocator, bucket, key, content) catch continue;
        // Re-read locally: null means the entry is a tombstone
        const meta = (dist.meta_index.getFull(allocator, bucket, key) catch null) orelse continue;

        // The source peer can serve the blob for CAS-backed objects
        if (meta.inline_data == null and meta.size > 0) {
            dist.kademlia.addProvider(meta.hash, peer.id) catch {};
        }
        return meta;
    }
    return null;
}

/// Pull the full metadata index from a peer (join-time sync).
/// Wire format per entry: "<kind>\n<bucket>\n<key>\n<content_len>\n" + content
/// bytes, where kind is "meta" or "attrs". Entries without a kind line (from
/// older peers) are treated as "meta".
fn syncIndexFromPeer(allocator: Allocator, ctx: *const S3Context, peer: PeerInfo) void {
    const body = peerRequest(allocator, peer.address, "GET", "/_zs3/index", "", MAX_INDEX_SYNC_SIZE) catch |err| {
        std.log.warn("Index sync from peer failed: {t}", .{err});
        return;
    };
    defer allocator.free(body);

    var applied: usize = 0;
    var offset: usize = 0;
    while (offset < body.len) {
        const l1_end = std.mem.indexOfScalarPos(u8, body, offset, '\n') orelse break;
        const l1 = body[offset..l1_end];
        const l2_end = std.mem.indexOfScalarPos(u8, body, l1_end + 1, '\n') orelse break;
        const l2 = body[l1_end + 1 .. l2_end];
        const l3_end = std.mem.indexOfScalarPos(u8, body, l2_end + 1, '\n') orelse break;
        const l3 = body[l2_end + 1 .. l3_end];

        // New format has 4 header lines (kind first); old format has 3.
        var kind: []const u8 = "meta";
        var bucket: []const u8 = l1;
        var key: []const u8 = l2;
        var len_str: []const u8 = l3;
        var content_off = l3_end + 1;
        if (std.mem.eql(u8, l1, "meta") or std.mem.eql(u8, l1, "attrs")) {
            const l4_end = std.mem.indexOfScalarPos(u8, body, l3_end + 1, '\n') orelse break;
            kind = l1;
            bucket = l2;
            key = l3;
            len_str = body[l3_end + 1 .. l4_end];
            content_off = l4_end + 1;
        }
        const content_len = std.fmt.parseInt(usize, len_str, 10) catch break;
        if (content_off + content_len > body.len) break;
        const content = body[content_off..][0..content_len];
        offset = content_off + content_len;

        if (!isValidBucketName(bucket) or !isValidKey(key)) continue;
        if (std.mem.eql(u8, kind, "attrs")) {
            applyRemoteAttrs(ctx, allocator, bucket, key, content) catch continue;
        } else {
            applyRemoteMeta(ctx, allocator, bucket, key, content) catch continue;
        }
        applied += 1;
    }
    std.log.info("Synced {d} metadata entries from bootstrap peer", .{applied});
}

/// Serialize the entire metadata index (including tombstones) for a joining peer
fn dumpMetaIndex(dist: *const DistributedContext, allocator: Allocator, out: *std.ArrayListUnmanaged(u8)) !void {
    const index_path = try std.fs.path.join(allocator, &.{ dist.meta_index.data_dir, ".index" });
    defer allocator.free(index_path);

    var dir = std.Io.Dir.cwd().openDir(app_io, index_path, .{ .iterate = true }) catch return;
    defer dir.close(app_io);

    var iter = dir.iterate();
    while (try iter.next(app_io)) |entry| {
        if (entry.kind != .directory or entry.name[0] == '.') continue;
        const bucket = try allocator.dupe(u8, entry.name);
        defer allocator.free(bucket);
        try dumpMetaDir(dist, allocator, bucket, "", out);
    }
}

fn dumpMetaDir(dist: *const DistributedContext, allocator: Allocator, bucket: []const u8, prefix: []const u8, out: *std.ArrayListUnmanaged(u8)) !void {
    const dir_path = if (prefix.len > 0)
        try std.fs.path.join(allocator, &.{ dist.meta_index.data_dir, ".index", bucket, prefix })
    else
        try std.fs.path.join(allocator, &.{ dist.meta_index.data_dir, ".index", bucket });
    defer allocator.free(dir_path);

    var dir = std.Io.Dir.cwd().openDir(app_io, dir_path, .{ .iterate = true }) catch return;
    defer dir.close(app_io);

    var iter = dir.iterate();
    while (try iter.next(app_io)) |entry| {
        if (entry.name[0] == '.') continue;
        const full_name = if (prefix.len > 0)
            try std.fmt.allocPrint(allocator, "{s}/{s}", .{ prefix, entry.name })
        else
            try allocator.dupe(u8, entry.name);
        defer allocator.free(full_name);

        if (entry.kind == .directory) {
            try dumpMetaDir(dist, allocator, bucket, full_name, out);
        } else if (std.mem.endsWith(u8, entry.name, ".meta")) {
            const key = full_name[0 .. full_name.len - 5];
            const content = (dist.meta_index.readRaw(allocator, bucket, key) catch continue) orelse continue;
            defer allocator.free(content);

            const frame = try std.fmt.allocPrint(allocator, "meta\n{s}\n{s}\n{d}\n", .{ bucket, key, content.len });
            defer allocator.free(frame);
            try out.appendSlice(allocator, frame);
            try out.appendSlice(allocator, content);
        } else if (std.mem.endsWith(u8, entry.name, ".attrs")) {
            const key = full_name[0 .. full_name.len - 6];
            const apath = try distAttrsPath(allocator, dist.meta_index.data_dir, bucket, key);
            defer allocator.free(apath);
            var afile = std.Io.Dir.cwd().openFile(app_io, apath, .{}) catch continue;
            defer afile.close(app_io);
            const acontent = readToEndAlloc(afile, allocator, MAX_META_RESPONSE) catch continue;
            defer allocator.free(acontent);

            const frame = try std.fmt.allocPrint(allocator, "attrs\n{s}\n{s}\n{d}\n", .{ bucket, key, acontent.len });
            defer allocator.free(frame);
            try out.appendSlice(allocator, frame);
            try out.appendSlice(allocator, acontent);
        }
    }
}

/// Distributed DELETE - write tombstone and propagate it to peers
fn handleDistributedDelete(ctx: *const S3Context, allocator: Allocator, res: *Response, bucket: []const u8, key: []const u8) !void {
    const dist = ctx.distributed.?;
    dist.meta_index.delete(allocator, bucket, key);
    deleteDistAttrs(allocator, dist, bucket, key);
    propagateObjectMeta(ctx, allocator, bucket, key);
    propagateObjectAttrs(ctx, allocator, bucket, key);
    res.noContent();
}

/// Distributed LIST - list objects from metadata index
fn handleDistributedList(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8) !void {
    const dist = ctx.distributed.?;

    const prefix_raw = getQueryParam(req.query, "prefix") orelse "";
    const prefix = try uriDecode(allocator, prefix_raw);
    defer allocator.free(prefix);

    const max_keys_str = getQueryParam(req.query, "max-keys") orelse "1000";
    const max_keys = std.fmt.parseInt(usize, max_keys_str, 10) catch 1000;

    const delimiter_raw = getQueryParam(req.query, "delimiter");
    const delimiter_decoded = if (delimiter_raw) |d| try uriDecode(allocator, d) else null;
    defer if (delimiter_decoded) |d| allocator.free(d);
    const delimiter = if (delimiter_decoded) |d| (if (d.len > 0) d else null) else null;

    const continuation_raw = getQueryParam(req.query, "continuation-token");
    const continuation = if (continuation_raw) |c| try uriDecode(allocator, c) else null;
    defer if (continuation) |c| allocator.free(c);

    // Path to the bucket's index directory
    const index_path = try std.fs.path.join(allocator, &.{ dist.meta_index.data_dir, ".index", bucket });
    defer allocator.free(index_path);

    var xml: std.ArrayListUnmanaged(u8) = .empty;
    defer xml.deinit(allocator);

    try xml.appendSlice(allocator, "<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
    try xml.appendSlice(allocator, "<ListBucketResult xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\">");
    try xml.appendSlice(allocator, "<Name>");
    try xmlEscape(allocator, &xml, bucket);
    try xml.appendSlice(allocator, "</Name><Prefix>");
    try xmlEscape(allocator, &xml, prefix);
    try xml.appendSlice(allocator, "</Prefix><MaxKeys>");
    var dist_max_keys_num_buf: [32]u8 = undefined;
    const dist_max_keys_num_str = std.fmt.bufPrint(&dist_max_keys_num_buf, "{d}", .{max_keys}) catch "1000";
    try xml.appendSlice(allocator, dist_max_keys_num_str);
    try xml.appendSlice(allocator, "</MaxKeys>");

    var keys: std.ArrayListUnmanaged(KeyInfo) = .empty;
    defer keys.deinit(allocator);

    // Collect keys from metadata index
    collectMetaKeys(allocator, index_path, "", prefix, &keys, &dist.meta_index, bucket) catch {};

    std.mem.sort(KeyInfo, keys.items, {}, struct {
        fn lessThan(_: void, a: KeyInfo, b: KeyInfo) bool {
            return std.mem.order(u8, a.key, b.key) == .lt;
        }
    }.lessThan);

    var start_idx: usize = 0;
    if (continuation) |cont| {
        for (keys.items, 0..) |item, i| {
            if (std.mem.eql(u8, item.key, cont)) {
                start_idx = i;
                break;
            }
        }
    }

    var common_prefixes = std.StringHashMap(void).init(allocator);
    defer common_prefixes.deinit();

    var count: usize = 0;
    var is_truncated = false;
    var next_token: ?[]const u8 = null;

    for (keys.items[start_idx..]) |item| {
        if (count >= max_keys) {
            is_truncated = true;
            next_token = item.key;
            break;
        }

        if (delimiter) |delim| {
            const after_prefix = if (prefix.len > 0 and std.mem.startsWith(u8, item.key, prefix))
                item.key[prefix.len..]
            else
                item.key;

            if (std.mem.indexOf(u8, after_prefix, delim)) |delim_idx| {
                const common_prefix = item.key[0 .. prefix.len + delim_idx + delim.len];
                if (!common_prefixes.contains(common_prefix)) {
                    try common_prefixes.put(common_prefix, {});
                    try xml.appendSlice(allocator, "<CommonPrefixes><Prefix>");
                    try xmlEscape(allocator, &xml, common_prefix);
                    try xml.appendSlice(allocator, "</Prefix></CommonPrefixes>");
                    count += 1;
                }
                continue;
            }
        }

        try xml.appendSlice(allocator, "<Contents><Key>");
        try xmlEscape(allocator, &xml, item.key);
        try xml.appendSlice(allocator, "</Key><LastModified>");
        var iso_buf2: [20]u8 = undefined;
        formatIso8601(&iso_buf2, item.mtime);
        try xml.appendSlice(allocator, &iso_buf2);
        try xml.appendSlice(allocator, "</LastModified><Size>");
        var size_buf: [32]u8 = undefined;
        const size_str = std.fmt.bufPrint(&size_buf, "{d}", .{item.size}) catch "0";
        try xml.appendSlice(allocator, size_str);
        try xml.appendSlice(allocator, "</Size><StorageClass>STANDARD</StorageClass></Contents>");
        count += 1;
    }

    var count_buf: [32]u8 = undefined;
    const count_str = std.fmt.bufPrint(&count_buf, "{d}", .{count}) catch "0";
    try xml.appendSlice(allocator, "<KeyCount>");
    try xml.appendSlice(allocator, count_str);
    try xml.appendSlice(allocator, "</KeyCount>");

    if (is_truncated) {
        try xml.appendSlice(allocator, "<IsTruncated>true</IsTruncated>");
        if (next_token) |token| {
            try xml.appendSlice(allocator, "<NextContinuationToken>");
            try xmlEscape(allocator, &xml, token);
            try xml.appendSlice(allocator, "</NextContinuationToken>");
        }
    } else {
        try xml.appendSlice(allocator, "<IsTruncated>false</IsTruncated>");
    }

    try xml.appendSlice(allocator, "</ListBucketResult>");

    res.ok();
    res.setXmlBody(try xml.toOwnedSlice(allocator));
}

/// Collect keys from the metadata index directory
fn collectMetaKeys(allocator: Allocator, base_path: []const u8, current_prefix: []const u8, filter_prefix: []const u8, keys: *std.ArrayListUnmanaged(KeyInfo), meta_index: *const MetaIndex, bucket: []const u8) !void {
    const full_path = if (current_prefix.len > 0)
        try std.fs.path.join(allocator, &[_][]const u8{ base_path, current_prefix })
    else
        try allocator.dupe(u8, base_path);
    defer allocator.free(full_path);

    var dir = std.Io.Dir.cwd().openDir(app_io, full_path, .{ .iterate = true }) catch return;
    defer dir.close(app_io);

    var iter = dir.iterate();
    while (try iter.next(app_io)) |entry| {
        // Same snapshot-prefix carve-out as standalone collectKeys.
        if (entry.name[0] == '.' and !std.mem.startsWith(u8, filter_prefix, SNAP_PREFIX)) continue;

        const full_name = if (current_prefix.len > 0)
            try std.fmt.allocPrint(allocator, "{s}/{s}", .{ current_prefix, entry.name })
        else
            try allocator.dupe(u8, entry.name);

        if (entry.kind == .directory) {
            try collectMetaKeys(allocator, base_path, full_name, filter_prefix, keys, meta_index, bucket);
            allocator.free(full_name);
        } else if (entry.kind == .file) {
            // Strip .meta extension to get the key
            if (std.mem.endsWith(u8, entry.name, ".meta")) {
                const key_name_len = full_name.len - 5; // Remove ".meta"
                const key = full_name[0..key_name_len];

                if (filter_prefix.len == 0 or std.mem.startsWith(u8, key, filter_prefix)) {
                    // Get full metadata (returns null for tombstones)
                    const meta = meta_index.getFull(allocator, bucket, key) catch null;
                    // Skip tombstoned entries - they shouldn't appear in listings
                    if (meta) |m| {
                        if (m.inline_data) |data| allocator.free(data);
                        const key_copy = try allocator.dupe(u8, key);
                        try keys.append(allocator, .{ .key = key_copy, .size = m.size, .mtime = m.created });
                    }
                }
            }
            allocator.free(full_name);
        }
    }
}

/// Distributed HEAD - return metadata without body
fn handleDistributedHead(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, key: []const u8) !void {
    const dist = ctx.distributed.?;

    const meta = try dist.meta_index.getFull(allocator, bucket, key) orelse
        fetchMetaFromPeers(ctx, allocator, bucket, key) orelse {
            sendError(res, 404, "NoSuchKey", "Object not found");
            return;
        };
    if (meta.inline_data) |data| allocator.free(data);

    const size_str = std.fmt.allocPrint(allocator, "{d}", .{meta.size}) catch {
        sendError(res, 500, "InternalError", "Format failed");
        return;
    };
    // ETag is the MD5 of the content, matching standalone mode. HEAD loads
    // the bytes (local CAS/inline, or peer fetch) to hash them.
    const head_data = readSourceBytes(ctx, allocator, bucket, key) catch {
        sendError(res, 404, "NoSuchKey", "Content not available from any provider");
        return;
    };
    const etag = md5Etag(allocator, head_data) catch {
        sendError(res, 500, "InternalError", "ETag failed");
        return;
    };

    // Conditional requests: If-Match mismatch → 412, If-None-Match match → 304.
    if (req.header("if-match")) |im| {
        if (!etagListMatches(im, etag)) {
            sendError(res, 412, "PreconditionFailed", "At least one of the pre-conditions you specified did not hold");
            return;
        }
    }
    if (req.header("if-none-match")) |inm| {
        if (etagListMatches(inm, etag)) {
            res.status = 304;
            res.status_text = "Not Modified";
            return;
        }
    }

    const last_modified = allocHttpDate(allocator, meta.created) catch {
        sendError(res, 500, "InternalError", "Date format failed");
        return;
    };

    res.ok();
    res.setHeader("Content-Length", size_str);
    res.setHeader("ETag", etag);
    res.setHeader("Accept-Ranges", "bytes");
    res.setHeader("Last-Modified", last_modified);
    // NB: no deinit — headers borrow attrs memory (arena-freed after write).
    const hattrs = readDistAttrs(allocator, dist, bucket, key) orelse fetchAttrsFromPeers(ctx, allocator, bucket, key);
    if (hattrs) |*a| {
        applyAttrsToResponse(res, a);
    } else {
        res.setHeader("Content-Type", DEFAULT_CONTENT_TYPE);
    }
}

/// Prometheus-compatible process metrics. No auth: safe to scrape.
fn handleMetrics(ctx: *const S3Context, allocator: Allocator, res: *Response) !void {
    const now = std.Io.Clock.real.now(app_io).toSeconds();
    const uptime = now - metrics.start_time_secs;
    const peers: usize = if (ctx.distributed) |dist| dist.kademlia.peerCount() else 0;

    var buckets: usize = 0;
    if (std.Io.Dir.cwd().openDir(app_io, ctx.data_dir, .{ .iterate = true })) |*d| {
        var dir = d.*;
        defer dir.close(app_io);
        var iter = dir.iterate();
        while (iter.next(app_io) catch null) |entry| {
            if (entry.kind == .directory and entry.name[0] != '.') buckets += 1;
        }
    } else |_| {}

    const body = try std.fmt.allocPrint(allocator,
        \\# HELP zs3_requests_total Total HTTP requests served since start.
        \\# TYPE zs3_requests_total counter
        \\zs3_requests_total {d}
        \\# HELP zs3_errors_4xx Total 4xx responses served.
        \\# TYPE zs3_errors_4xx counter
        \\zs3_errors_4xx {d}
        \\# HELP zs3_errors_5xx Total 5xx responses served.
        \\# TYPE zs3_errors_5xx counter
        \\zs3_errors_5xx {d}
        \\# HELP zs3_put_bytes Total object bytes written via PUT/CopyObject.
        \\# TYPE zs3_put_bytes counter
        \\zs3_put_bytes {d}
        \\# HELP zs3_get_bytes Total object bytes served via GET.
        \\# TYPE zs3_get_bytes counter
        \\zs3_get_bytes {d}
        \\# HELP zs3_uptime_seconds Seconds since process start.
        \\# TYPE zs3_uptime_seconds gauge
        \\zs3_uptime_seconds {d}
        \\# HELP zs3_buckets Number of buckets in the data dir.
        \\# TYPE zs3_buckets gauge
        \\zs3_buckets {d}
        \\# HELP zs3_known_peers Peers in the Kademlia routing table (0 in standalone mode).
        \\# TYPE zs3_known_peers gauge
        \\zs3_known_peers {d}
        \\
    , .{ metrics.requests, metrics.errors_4xx, metrics.errors_5xx, metrics.put_bytes, metrics.get_bytes, uptime, buckets, peers });

    res.ok();
    res.setHeader("Content-Type", "text/plain; version=0.0.4");
    res.body = body;
}

const console_html = @embedFile("console.html");

/// Single-file browser console (no auth on the page itself; the JS signs S3
/// requests with keys the user types, kept in localStorage only).
fn handleConsole(allocator: Allocator, res: *Response) void {
    _ = allocator;
    res.ok();
    res.setHeader("Content-Type", "text/html; charset=utf-8");
    res.setHeader("Cache-Control", "no-store");
    res.body = console_html;
}

fn sendError(res: *Response, status: u16, code: []const u8, message: []const u8) void {
    res.status = status;
    res.status_text = switch (status) {
        200 => "OK",
        204 => "No Content",
        206 => "Partial Content",
        304 => "Not Modified",
        400 => "Bad Request",
        403 => "Forbidden",
        404 => "Not Found",
        405 => "Method Not Allowed",
        409 => "Conflict",
        412 => "Precondition Failed",
        416 => "Range Not Satisfiable",
        500 => "Internal Server Error",
        else => "Error",
    };
    res.setHeader("Content-Type", "application/xml");

    res.body = std.fmt.allocPrint(res.allocator, "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Error><Code>{s}</Code><Message>{s}</Message></Error>", .{ code, message }) catch return;
}

// ============================================================================
// SNAPSHOTS + CLONE ("git clone for object storage")
// ============================================================================
// A snapshot is a manifest (stored as a regular object under
// `.zs3snapshots/<name>.json`) mapping bucket/key names to immutable BLAKE3
// content hashes plus the chunk list each object is split into. Chunks are
// stored as objects under `.zs3snapshots/chunks/<hex>` and content-addressed,
// so a second snapshot only PUTs chunks the bucket lacks, and a clone only
// GETs chunks the local cache lacks. Re-cloning a warm cache transfers only
// the manifest (bytes, not megabytes).
//
// Manifest JSON (generated and consumed here; keys are JSON-escaped):
// {"version":1,"bucket":"b","name":"n","created":169...,"chunk_bytes":4194304,
//  "objects":[{"key":"...","size":N,"hash":"<blake3-32-hex>","chunks":["..."]}]}

const SNAP_PREFIX = ".zs3snapshots/";
const SNAP_CHUNK_PREFIX = ".zs3snapshots/chunks/";
const DEFAULT_CHUNK_BYTES: usize = 4 * 1024 * 1024;

const SnapArgs = struct {
    endpoint: []const u8 = "http://127.0.0.1:9000",
    bucket: []const u8 = "",
    name: []const u8 = "",
    dest: []const u8 = "",
    cache: []const u8 = "",
    access: []const u8 = "",
    secret: []const u8 = "",
    region: []const u8 = "us-east-1",
    chunk_bytes: usize = DEFAULT_CHUNK_BYTES,
    insecure: bool = false,
    /// Extra PEM CA file trusted in addition to the system store.
    ca_file: []const u8 = "",
};

// Process environment for snapshot/clone credential lookup (no libc getenv,
// so the static musl build stays pure). Set once in main().
var proc_env: ?*const std.process.Environ.Map = null;

fn getenvStr(name: []const u8) ?[]const u8 {
    const m = proc_env orelse return null;
    return m.get(name);
}

fn parseSnapArgs(allocator: Allocator, args: []const []const u8) !SnapArgs {
    var out = SnapArgs{};
    _ = allocator;
    // Env fallbacks so `zs3 clone` works with standard S3 env vars.
    if (getenvStr("ZS3_ENDPOINT")) |v| out.endpoint = v;
    if (getenvStr("AWS_ACCESS_KEY_ID")) |v| out.access = v;
    if (getenvStr("AWS_SECRET_ACCESS_KEY")) |v| out.secret = v;
    if (getenvStr("AWS_DEFAULT_REGION")) |v| out.region = v;
    for (args) |arg| {
        if (std.mem.startsWith(u8, arg, "--endpoint=")) {
            out.endpoint = arg[11..];
        } else if (std.mem.startsWith(u8, arg, "--bucket=")) {
            out.bucket = arg[9..];
        } else if (std.mem.startsWith(u8, arg, "--name=")) {
            out.name = arg[7..];
        } else if (std.mem.startsWith(u8, arg, "--dest=")) {
            out.dest = arg[7..];
        } else if (std.mem.startsWith(u8, arg, "--cache=")) {
            out.cache = arg[8..];
        } else if (std.mem.startsWith(u8, arg, "--access-key=")) {
            out.access = arg[13..];
        } else if (std.mem.startsWith(u8, arg, "--secret-key=")) {
            out.secret = arg[13..];
        } else if (std.mem.startsWith(u8, arg, "--region=")) {
            out.region = arg[9..];
        } else if (std.mem.startsWith(u8, arg, "--chunk-bytes=")) {
            out.chunk_bytes = std.fmt.parseInt(usize, arg[14..], 10) catch DEFAULT_CHUNK_BYTES;
        } else if (std.mem.eql(u8, arg, "--insecure")) {
            out.insecure = true;
        } else if (std.mem.startsWith(u8, arg, "--ca-file=")) {
            out.ca_file = arg[10..];
        } else {
            std.debug.print("Unknown snapshot option: {s}\n", .{arg});
            return error.BadArgs;
        }
    }
    if (getenvStr("ZS3_CA_FILE")) |v| {
        if (out.ca_file.len == 0) out.ca_file = v;
    }
    if (out.access.len == 0) out.access = "minioadmin";
    if (out.secret.len == 0) out.secret = "minioadmin";
    return out;
}

fn blake3Hex32(data: []const u8, out: *[64]u8) void {
    var hasher = std.crypto.hash.Blake3.init(.{});
    hasher.update(data);
    var digest: [32]u8 = undefined;
    hasher.final(&digest);
    bytesToHex(&digest, out);
}

fn jsonEscape(allocator: Allocator, out: *std.ArrayListUnmanaged(u8), s: []const u8) !void {
    try out.append(allocator, '"');
    for (s) |c| {
        switch (c) {
            '"' => try out.appendSlice(allocator, "\\\""),
            '\\' => try out.appendSlice(allocator, "\\\\"),
            '\n' => try out.appendSlice(allocator, "\\n"),
            '\r' => try out.appendSlice(allocator, "\\r"),
            '\t' => try out.appendSlice(allocator, "\\t"),
            else => {
                if (c < 0x20) {
                    var buf: [6]u8 = undefined;
                    const text = std.fmt.bufPrint(&buf, "\\u{x:0>4}", .{c}) catch continue;
                    try out.appendSlice(allocator, text);
                } else {
                    try out.append(allocator, c);
                }
            },
        }
    }
    try out.append(allocator, '"');
}

fn xmlUnescape(allocator: Allocator, s: []const u8) ![]const u8 {
    var out: std.ArrayListUnmanaged(u8) = .empty;
    errdefer out.deinit(allocator);
    var i: usize = 0;
    while (i < s.len) {
        if (s[i] == '&') {
            if (std.mem.startsWith(u8, s[i..], "&lt;")) {
                try out.append(allocator, '<');
                i += 4;
            } else if (std.mem.startsWith(u8, s[i..], "&gt;")) {
                try out.append(allocator, '>');
                i += 4;
            } else if (std.mem.startsWith(u8, s[i..], "&amp;")) {
                try out.append(allocator, '&');
                i += 5;
            } else if (std.mem.startsWith(u8, s[i..], "&quot;")) {
                try out.append(allocator, '"');
                i += 6;
            } else if (std.mem.startsWith(u8, s[i..], "&apos;")) {
                try out.append(allocator, '\'');
                i += 6;
            } else {
                try out.append(allocator, s[i]);
                i += 1;
            }
        } else {
            try out.append(allocator, s[i]);
            i += 1;
        }
    }
    return out.toOwnedSlice(allocator);
}

/// Minimal S3 client (header SigV4) for snapshot/clone. HTTP only; put a
/// proxy in front for TLS, same as the server side.
/// One HTTP connection for the snapshot/clone client: a raw socket, or a
/// socket wrapped in std.crypto.tls.Client for https:// endpoints. TLS uses
/// the system CA bundle (loaded lazily on first verification) and verifies
/// the hostname; --insecure disables both for self-signed test servers.
const ClientConn = struct {
    stream: net.Stream,
    tls: ?*TlsState = null,

    const TlsState = struct {
        sock_reader: net.Stream.Reader,
        sock_writer: net.Stream.Writer,
        client: std.crypto.tls.Client,
        bufs: []u8,

        const tls_len = std.crypto.tls.Client.min_buffer_len;
        // socket read | socket write | tls plaintext read | tls ciphertext write
        const sock_read_len = tls_len;
        const sock_write_len = tls_len;
        const tls_read_len = tls_len + 32 * 1024;
        const tls_write_len = tls_len;

        fn create(allocator: Allocator, stream: net.Stream, host: []const u8, insecure: bool, ca_file: []const u8) !*TlsState {
            if (!build_options.tls) return error.TlsNotSupported;
            const st = try allocator.create(TlsState);
            errdefer allocator.destroy(st);
            st.bufs = try allocator.alloc(u8, sock_read_len + sock_write_len + tls_read_len + tls_write_len);
            errdefer allocator.free(st.bufs);
            const sock_read = st.bufs[0..sock_read_len];
            const sock_write = st.bufs[sock_read_len..][0..sock_write_len];
            const tls_read = st.bufs[sock_read_len + sock_write_len ..][0..tls_read_len];
            const tls_write = st.bufs[sock_read_len + sock_write_len + tls_read_len ..][0..tls_write_len];
            st.sock_reader = stream.reader(app_io, sock_read);
            st.sock_writer = stream.writer(app_io, sock_write);
            if (!insecure) {
                // Load the system CA store once; the TLS client only consults
                // it, it does not populate it.
                try client_ca_lock.lock(app_io);
                defer client_ca_lock.unlock(app_io);
                if (client_ca_bundle.map.count() == 0) {
                    const now = std.Io.Clock.real.now(app_io);
                    client_ca_bundle.rescan(allocator, app_io, now) catch |err| {
                        std.debug.print("could not load system CA certificates: {t} (use --insecure to skip verification)\n", .{err});
                        return error.TlsHandshakeFailed;
                    };
                    if (ca_file.len > 0) {
                        client_ca_bundle.addCertsFromFilePath(allocator, app_io, now, std.Io.Dir.cwd(), ca_file) catch |err| {
                            std.debug.print("could not load --ca-file {s}: {t}\n", .{ ca_file, err });
                            return error.TlsHandshakeFailed;
                        };
                    }
                }
            }
            var entropy: [std.crypto.tls.Client.Options.entropy_len]u8 = undefined;
            app_io.random(&entropy);
            st.client = std.crypto.tls.Client.init(
                &st.sock_reader.interface,
                &st.sock_writer.interface,
                .{
                    .host = if (insecure) .no_verification else .{ .explicit = host },
                    .ca = if (insecure) .no_verification else .{ .bundle = .{
                        .gpa = allocator,
                        .io = app_io,
                        .lock = &client_ca_lock,
                        .bundle = &client_ca_bundle,
                    } },
                    .read_buffer = tls_read,
                    .write_buffer = tls_write,
                    .entropy = &entropy,
                    .realtime_now = std.Io.Clock.real.now(app_io),
                    // HTTP Content-Length detects truncation; matches std.http.
                    .allow_truncation_attacks = true,
                },
            ) catch |err| {
                std.debug.print("TLS handshake with {s} failed: {t}\n", .{ host, err });
                return error.TlsHandshakeFailed;
            };
            return st;
        }
    };

    fn writeAll(self: *ClientConn, bytes: []const u8) !void {
        if (self.tls) |st| {
            st.client.writer.writeAll(bytes) catch return error.WriteFailed;
            st.client.writer.flush() catch return error.WriteFailed;
            st.sock_writer.interface.flush() catch return error.WriteFailed;
            return;
        }
        try streamWriteAll(self.stream, bytes);
    }

    fn read(self: *ClientConn, buffer: []u8) !usize {
        if (self.tls) |st| {
            return st.client.reader.readSliceShort(buffer) catch return error.ReadFailed;
        }
        return streamRead(self.stream, buffer);
    }

    fn close(self: *ClientConn, allocator: Allocator) void {
        if (self.tls) |st| {
            st.client.end() catch {};
            st.sock_writer.interface.flush() catch {};
            allocator.free(st.bufs);
            allocator.destroy(st);
        }
        self.stream.close(app_io);
    }
};

var client_ca_bundle: std.crypto.Certificate.Bundle = .empty;
var client_ca_lock: std.Io.RwLock = .init;

const S3Client = struct {
    allocator: Allocator,
    host: []const u8,
    port: u16,
    bucket: []const u8,
    region: []const u8,
    access: []const u8,
    secret: []const u8,
    tls: bool = false,
    /// Skip certificate and hostname verification (self-signed test servers).
    insecure: bool = false,
    /// Extra PEM CA file to trust (e.g. a private CA for a TLS proxy).
    ca_file: []const u8 = "",

    fn defaultPort(self: *const S3Client) u16 {
        return if (self.tls) 443 else 80;
    }

    const Resp = struct {
        status: u16,
        body: []u8,
    };

    fn connectTcp(self: *const S3Client) !net.Stream {
        if (net.IpAddress.parseLiteral(self.host)) |addr| {
            var a = addr;
            a.setPort(self.port);
            return a.connect(app_io, .{ .mode = .stream }) catch error.ConnectionFailed;
        } else |_| {}
        const hn = net.HostName.init(self.host) catch return error.BadHost;
        var lookup_buffer: [8]net.HostName.LookupResult = undefined;
        var lookup_queue: std.Io.Queue(net.HostName.LookupResult) = .init(&lookup_buffer);
        hn.lookup(app_io, &lookup_queue, .{ .port = self.port }) catch return error.DnsFailed;
        while (lookup_queue.getOne(app_io)) |result| switch (result) {
            .address => |addr| {
                return addr.connect(app_io, .{ .mode = .stream }) catch continue;
            },
            .canonical_name => continue,
        } else |_| {}
        return error.ConnectionFailed;
    }

    fn connect(self: *const S3Client) !ClientConn {
        if (self.tls and !build_options.tls) {
            std.debug.print("this zs3 was built with -Dtls=false; https:// endpoints need a TLS-terminating proxy or a default build\n", .{});
            return error.TlsNotSupported;
        }
        const stream = try self.connectTcp();
        errdefer stream.close(app_io);
        if (!self.tls) return .{ .stream = stream };
        const st = try ClientConn.TlsState.create(self.allocator, stream, self.host, self.insecure, self.ca_file);
        return .{ .stream = stream, .tls = st };
    }

    const QueryPair = struct { name: []const u8, value: []const u8 };

    fn request(self: *const S3Client, method: []const u8, key: []const u8, query: []const QueryPair, body: []const u8, content_type: ?[]const u8) !Resp {
        // Path: /bucket[/key-segments...], each segment URI-encoded.
        var path_buf: std.ArrayListUnmanaged(u8) = .empty;
        defer path_buf.deinit(self.allocator);
        try path_buf.append(self.allocator, '/');
        try path_buf.appendSlice(self.allocator, self.bucket);
        if (key.len > 0) {
            try path_buf.append(self.allocator, '/');
            var seg_iter = std.mem.splitScalar(u8, key, '/');
            var first = true;
            while (seg_iter.next()) |seg| {
                if (!first) try path_buf.append(self.allocator, '/');
                first = false;
                const enc_seg = try uriEncode(self.allocator, seg, true);
                defer self.allocator.free(enc_seg);
                try path_buf.appendSlice(self.allocator, enc_seg);
            }
        }
        const path = path_buf.items;

        // Canonical query: encoded name=value pairs, sorted by name.
        var qbuf: std.ArrayListUnmanaged(u8) = .empty;
        defer qbuf.deinit(self.allocator);
        var order: [8]usize = undefined;
        for (query, 0..) |_, i| order[i] = i;
        std.mem.sort(usize, order[0..query.len], query, struct {
            fn lessThan(q: []const QueryPair, a: usize, b: usize) bool {
                return std.mem.order(u8, q[a].name, q[b].name) == .lt;
            }
        }.lessThan);
        for (order[0..query.len], 0..) |qi, i| {
            if (i > 0) try qbuf.append(self.allocator, '&');
            const en = try uriEncode(self.allocator, query[qi].name, true);
            defer self.allocator.free(en);
            const ev = try uriEncode(self.allocator, query[qi].value, true);
            defer self.allocator.free(ev);
            try qbuf.appendSlice(self.allocator, en);
            try qbuf.append(self.allocator, '=');
            try qbuf.appendSlice(self.allocator, ev);
        }

        const now_secs = std.Io.Clock.real.now(app_io).toSeconds();
        var dt_buf: [16]u8 = undefined;
        formatAmzDate(&dt_buf, now_secs);
        const amz_date = dt_buf[0..16];
        const date_stamp = dt_buf[0..8];

        const payload_hash_bin = SigV4.hash(body);
        var payload_hex: [64]u8 = undefined;
        _ = std.fmt.bufPrint(&payload_hex, "{x}", .{payload_hash_bin}) catch unreachable;

        // Canonical request (must match the server's builder exactly).
        var canon: std.ArrayListUnmanaged(u8) = .empty;
        defer canon.deinit(self.allocator);
        try canon.appendSlice(self.allocator, method);
        try canon.append(self.allocator, '\n');
        try canon.appendSlice(self.allocator, path);
        try canon.append(self.allocator, '\n');
        try canon.appendSlice(self.allocator, qbuf.items);
        try canon.append(self.allocator, '\n');
        try canon.appendSlice(self.allocator, "host:");
        try canon.appendSlice(self.allocator, self.host);
        if (self.port != self.defaultPort()) {
            const ps = try std.fmt.allocPrint(self.allocator, ":{d}", .{self.port});
            defer self.allocator.free(ps);
            try canon.appendSlice(self.allocator, ps);
        }
        try canon.append(self.allocator, '\n');
        try canon.appendSlice(self.allocator, "x-amz-content-sha256:");
        try canon.appendSlice(self.allocator, &payload_hex);
        try canon.append(self.allocator, '\n');
        try canon.appendSlice(self.allocator, "x-amz-date:");
        try canon.appendSlice(self.allocator, amz_date);
        try canon.append(self.allocator, '\n');
        try canon.append(self.allocator, '\n');
        try canon.appendSlice(self.allocator, "host;x-amz-content-sha256;x-amz-date");
        try canon.append(self.allocator, '\n');
        try canon.appendSlice(self.allocator, &payload_hex);

        const sts = try SigV4.buildStringToSign(self.allocator, amz_date, date_stamp, self.region, "s3", canon.items);
        defer self.allocator.free(sts);
        const sig = try SigV4.calculateSignature(self.allocator, self.secret, date_stamp, self.region, "s3", sts);
        defer self.allocator.free(sig);

        var req_buf: std.ArrayListUnmanaged(u8) = .empty;
        defer req_buf.deinit(self.allocator);
        const req_line = try std.fmt.allocPrint(self.allocator, "{s} {s}{s}{s} HTTP/1.1\r\n", .{
            method, path, if (qbuf.items.len > 0) "?" else "", qbuf.items,
        });
        defer self.allocator.free(req_line);
        try req_buf.appendSlice(self.allocator, req_line);
        const host_hdr = if (self.port != self.defaultPort())
            try std.fmt.allocPrint(self.allocator, "Host: {s}:{d}\r\n", .{ self.host, self.port })
        else
            try std.fmt.allocPrint(self.allocator, "Host: {s}\r\n", .{self.host});
        defer self.allocator.free(host_hdr);
        try req_buf.appendSlice(self.allocator, host_hdr);
        const auth_hdr = try std.fmt.allocPrint(self.allocator, "Authorization: AWS4-HMAC-SHA256 Credential={s}/{s}/{s}/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature={s}\r\n", .{
            self.access, date_stamp, self.region, sig,
        });
        defer self.allocator.free(auth_hdr);
        try req_buf.appendSlice(self.allocator, auth_hdr);
        const date_hdr = try std.fmt.allocPrint(self.allocator, "x-amz-date: {s}\r\nx-amz-content-sha256: {s}\r\n", .{ amz_date, payload_hex });
        defer self.allocator.free(date_hdr);
        try req_buf.appendSlice(self.allocator, date_hdr);
        if (content_type) |ct| {
            const ct_hdr = try std.fmt.allocPrint(self.allocator, "Content-Type: {s}\r\n", .{ct});
            defer self.allocator.free(ct_hdr);
            try req_buf.appendSlice(self.allocator, ct_hdr);
        }
        const cl_hdr = try std.fmt.allocPrint(self.allocator, "Content-Length: {d}\r\nConnection: close\r\n\r\n", .{body.len});
        defer self.allocator.free(cl_hdr);
        try req_buf.appendSlice(self.allocator, cl_hdr);
        try req_buf.appendSlice(self.allocator, body);

        var conn = try self.connect();
        defer conn.close(self.allocator);
        try conn.writeAll(req_buf.items);

        // Read headers, then exactly Content-Length (server always sends it).
        var resp: std.ArrayListUnmanaged(u8) = .empty;
        defer resp.deinit(self.allocator);
        var chunk: [32 * 1024]u8 = undefined;
        var header_len: ?usize = null;
        var content_len: usize = 0;
        var chunked = false;
        var status: u16 = 0;
        while (header_len == null) {
            const n = conn.read(&chunk) catch break;
            if (n == 0) break;
            try resp.appendSlice(self.allocator, chunk[0..n]);
            if (std.mem.indexOf(u8, resp.items, "\r\n\r\n")) |he| {
                header_len = he + 4;
                // Status line: HTTP/1.1 200 OK
                var line_iter = std.mem.splitScalar(u8, resp.items[0..he], '\n');
                if (line_iter.next()) |status_line| {
                    var sp = std.mem.splitScalar(u8, std.mem.trim(u8, status_line, " \t\r"), ' ');
                    _ = sp.next();
                    if (sp.next()) |code| status = std.fmt.parseInt(u16, code, 10) catch 0;
                }
                // Content-Length scan (case-insensitive).
                var h_iter = std.mem.splitSequence(u8, resp.items[0..he], "\r\n");
                while (h_iter.next()) |hline| {
                    if (hline.len > 15 and std.ascii.eqlIgnoreCase(hline[0..15], "content-length:")) {
                        content_len = std.fmt.parseInt(usize, std.mem.trim(u8, hline[15..], " \t"), 10) catch 0;
                    } else if (hline.len > 18 and std.ascii.eqlIgnoreCase(hline[0..18], "transfer-encoding:")) {
                        chunked = std.ascii.indexOfIgnoreCase(hline[18..], "chunked") != null;
                    }
                }
            } else if (resp.items.len > MAX_HEADER_SIZE + 1024) {
                return error.ResponseTooLarge;
            }
        }
        const hl = header_len orelse return error.InvalidResponse;
        if (chunked) {
            // AWS and most proxies answer error (and some LIST) responses
            // with Transfer-Encoding: chunked. Read to EOF (we sent
            // Connection: close), then de-chunk.
            while (true) {
                const n = conn.read(&chunk) catch break;
                if (n == 0) break;
                try resp.appendSlice(self.allocator, chunk[0..n]);
                if (resp.items.len > MAX_BODY_SIZE) return error.ResponseTooLarge;
            }
            const out_body = try decodeHttpChunked(self.allocator, resp.items[hl..]);
            return .{ .status = status, .body = out_body };
        }
        while (resp.items.len - hl < content_len) {
            const n = conn.read(&chunk) catch break;
            if (n == 0) break;
            try resp.appendSlice(self.allocator, chunk[0..n]);
            if (resp.items.len > MAX_BODY_SIZE) return error.ResponseTooLarge;
        }
        const out_body = try self.allocator.dupe(u8, resp.items[hl..@min(hl + content_len, resp.items.len)]);
        return .{ .status = status, .body = out_body };
    }

    fn get(self: *const S3Client, key: []const u8) ![]u8 {
        const r = try self.request("GET", key, &.{}, "", null);
        defer self.allocator.free(r.body);
        if (r.status != 200) return failRequest("GET", key, r);
        return self.allocator.dupe(u8, r.body);
    }

    fn put(self: *const S3Client, key: []const u8, body: []const u8, content_type: ?[]const u8) !void {
        const r = try self.request("PUT", key, &.{}, body, content_type);
        defer self.allocator.free(r.body);
        if (r.status != 200) return failRequest("PUT", key, r);
    }

    /// Print the S3 error code for a failed request so `zs3 clone` against a
    /// foreign server says "403 InvalidAccessKeyId" instead of just failing.
    fn failRequest(method: []const u8, key: []const u8, r: Resp) error{RequestFailed} {
        const code = xmlTagText(r.body, "Code") orelse "";
        std.debug.print("{s} {s}: server returned {d} {s}\n", .{ method, key, r.status, code });
        return error.RequestFailed;
    }

    fn head(self: *const S3Client, key: []const u8) bool {
        const r = self.request("HEAD", key, &.{}, "", null) catch return false;
        defer self.allocator.free(r.body);
        return r.status == 200;
    }
};

/// Format Unix seconds as X-Amz-Date (YYYYMMDDTHHMMSSZ).
fn formatAmzDate(buf: *[16]u8, timestamp: i64) void {
    const secs: u64 = if (timestamp > 0) @intCast(timestamp) else 0;
    const es = std.time.epoch.EpochSeconds{ .secs = secs };
    const day = es.getEpochDay();
    const yd = day.calculateYearDay();
    const md = yd.calculateMonthDay();
    const ds = es.getDaySeconds();
    _ = std.fmt.bufPrint(buf, "{d:0>4}{d:0>2}{d:0>2}T{d:0>2}{d:0>2}{d:0>2}Z", .{
        yd.year,
        @intFromEnum(md.month),
        md.day_index + 1,
        ds.getHoursIntoDay(),
        ds.getMinutesIntoHour(),
        ds.getSecondsIntoMinute(),
    }) catch unreachable;
}

pub const Endpoint = struct { host: []const u8, port: u16, tls: bool };

pub fn splitEndpoint(endpoint: []const u8) !Endpoint {
    var rest = endpoint;
    var tls = false;
    if (std.mem.startsWith(u8, rest, "http://")) {
        rest = rest[7..];
    } else if (std.mem.startsWith(u8, rest, "https://")) {
        rest = rest[8..];
        tls = true;
    } else {
        return error.BadEndpoint;
    }
    // Strip any trailing path.
    if (std.mem.indexOfScalar(u8, rest, '/')) |s| rest = rest[0..s];
    if (std.mem.lastIndexOfScalar(u8, rest, ':')) |c| {
        const port = std.fmt.parseInt(u16, rest[c + 1 ..], 10) catch return error.BadEndpoint;
        return .{ .host = rest[0..c], .port = port, .tls = tls };
    }
    return .{ .host = rest, .port = if (tls) 443 else 80, .tls = tls };
}

/// List all keys under a prefix (handles ListObjectsV2 pagination).
fn s3ListAll(client: *const S3Client, allocator: Allocator, prefix: []const u8) !std.ArrayListUnmanaged([]const u8) {
    var keys: std.ArrayListUnmanaged([]const u8) = .empty;
    errdefer {
        for (keys.items) |k| allocator.free(k);
        keys.deinit(allocator);
    }
    var token: ?[]const u8 = null;
    defer if (token) |t| allocator.free(t);
    while (true) {
        var qbuf: [3]S3Client.QueryPair = undefined;
        var qn: usize = 0;
        qbuf[qn] = .{ .name = "list-type", .value = "2" };
        qn += 1;
        qbuf[qn] = .{ .name = "prefix", .value = prefix };
        qn += 1;
        if (token) |t| {
            qbuf[qn] = .{ .name = "continuation-token", .value = t };
            qn += 1;
        }
        const r = try client.request("GET", "", qbuf[0..qn], "", null);
        defer allocator.free(r.body);
        if (r.status != 200) return S3Client.failRequest("LIST", prefix, r);

        var search: []const u8 = r.body;
        while (std.mem.indexOf(u8, search, "<Key>")) |s| {
            const ks = s + 5;
            const e = std.mem.indexOf(u8, search[ks..], "</Key>") orelse break;
            const raw = search[ks .. ks + e];
            const unesc = try xmlUnescape(allocator, raw);
            try keys.append(allocator, unesc);
            search = search[ks + e + 6 ..];
        }
        const trunc = std.mem.indexOf(u8, r.body, "<IsTruncated>true</IsTruncated>") != null;
        if (!trunc) break;
        const ns = std.mem.indexOf(u8, r.body, "<NextContinuationToken>") orelse break;
        const nks = ns + 23;
        const ne = std.mem.indexOf(u8, r.body[nks..], "</NextContinuationToken>") orelse break;
        if (token) |t| allocator.free(t);
        token = try xmlUnescape(allocator, r.body[nks .. nks + ne]);
    }
    return keys;
}

fn runSnapshot(allocator: Allocator, args: []const []const u8) !void {
    const sa = try parseSnapArgs(allocator, args);
    if (sa.bucket.len == 0 or sa.name.len == 0) {
        std.debug.print("Usage: zs3 snapshot --bucket=BUCKET --name=NAME [--endpoint=URL] [--chunk-bytes=N]\n", .{});
        return error.BadArgs;
    }
    if (std.mem.indexOf(u8, sa.name, "/") != null) {
        std.debug.print("Snapshot name must not contain '/'\n", .{});
        return error.BadArgs;
    }
    const ep = try splitEndpoint(sa.endpoint);
    var client = S3Client{
        .allocator = allocator,
        .host = ep.host,
        .port = ep.port,
        .bucket = sa.bucket,
        .region = sa.region,
        .access = sa.access,
        .secret = sa.secret,
        .tls = ep.tls,
        .insecure = sa.insecure,
        .ca_file = sa.ca_file,
    };

    var keys = try s3ListAll(&client, allocator, "");
    defer {
        for (keys.items) |k| allocator.free(k);
        keys.deinit(allocator);
    }

    var manifest: std.ArrayListUnmanaged(u8) = .empty;
    defer manifest.deinit(allocator);
    try manifest.appendSlice(allocator, "{\"version\":1,\"bucket\":");
    try jsonEscape(allocator, &manifest, sa.bucket);
    try manifest.appendSlice(allocator, ",\"name\":");
    try jsonEscape(allocator, &manifest, sa.name);
    const now = std.Io.Clock.real.now(app_io).toSeconds();
    const created = try std.fmt.allocPrint(allocator, ",\"created\":{d},\"chunk_bytes\":{d},\"objects\":[", .{ now, sa.chunk_bytes });
    defer allocator.free(created);
    try manifest.appendSlice(allocator, created);

    var objects: usize = 0;
    var total_bytes: usize = 0;
    var uploaded_chunks: usize = 0;
    var reused_chunks: usize = 0;
    var first = true;
    for (keys.items) |key| {
        if (std.mem.startsWith(u8, key, SNAP_PREFIX)) continue;
        const data = client.get(key) catch |e| {
            std.debug.print("skip {s}: GET failed ({t})\n", .{ key, e });
            continue;
        };
        defer allocator.free(data);

        var whole_hex: [64]u8 = undefined;
        blake3Hex32(data, &whole_hex);

        // Chunk, dedup-upload, collect hashes.
        var chunk_hexes: std.ArrayListUnmanaged([64]u8) = .empty;
        defer chunk_hexes.deinit(allocator);
        var off: usize = 0;
        if (data.len == 0) {
            // Empty objects have no chunks; the manifest entry alone suffices.
        }
        while (off < data.len) {
            const end = @min(off + sa.chunk_bytes, data.len);
            var chex: [64]u8 = undefined;
            blake3Hex32(data[off..end], &chex);
            try chunk_hexes.append(allocator, chex);
            const chunk_key = try std.fmt.allocPrint(allocator, "{s}{s}", .{ SNAP_CHUNK_PREFIX, chex });
            defer allocator.free(chunk_key);
            if (client.head(chunk_key)) {
                reused_chunks += 1;
            } else {
                client.put(chunk_key, data[off..end], "application/octet-stream") catch |e| {
                    std.debug.print("PUT chunk failed ({t})\n", .{e});
                    return e;
                };
                uploaded_chunks += 1;
            }
            off = end;
        }

        if (!first) try manifest.append(allocator, ',');
        first = false;
        try manifest.appendSlice(allocator, "{\"key\":");
        try jsonEscape(allocator, &manifest, key);
        const meta = try std.fmt.allocPrint(allocator, ",\"size\":{d},\"hash\":\"{s}\",\"chunks\":[", .{ data.len, whole_hex });
        defer allocator.free(meta);
        try manifest.appendSlice(allocator, meta);
        for (chunk_hexes.items, 0..) |chex, i| {
            if (i > 0) try manifest.append(allocator, ',');
            try manifest.append(allocator, '"');
            try manifest.appendSlice(allocator, &chex);
            try manifest.append(allocator, '"');
        }
        try manifest.appendSlice(allocator, "]}");
        objects += 1;
        total_bytes += data.len;
    }
    try manifest.appendSlice(allocator, "]}");

    const manifest_key = try std.fmt.allocPrint(allocator, "{s}{s}.json", .{ SNAP_PREFIX, sa.name });
    defer allocator.free(manifest_key);
    try client.put(manifest_key, manifest.items, "application/json");
    std.debug.print("snapshot {s}: {d} objects, {d} bytes, {d} chunks uploaded, {d} reused -> {s}/{s}\n", .{
        sa.name, objects, total_bytes, uploaded_chunks, reused_chunks, sa.bucket, manifest_key,
    });
}

fn runSnapshotsList(allocator: Allocator, args: []const []const u8) !void {
    const sa = try parseSnapArgs(allocator, args);
    if (sa.bucket.len == 0) {
        std.debug.print("Usage: zs3 snapshots --bucket=BUCKET [--endpoint=URL]\n", .{});
        return error.BadArgs;
    }
    const ep = try splitEndpoint(sa.endpoint);
    var client = S3Client{
        .allocator = allocator,
        .host = ep.host,
        .port = ep.port,
        .bucket = sa.bucket,
        .region = sa.region,
        .access = sa.access,
        .secret = sa.secret,
        .tls = ep.tls,
        .insecure = sa.insecure,
        .ca_file = sa.ca_file,
    };
    var keys = try s3ListAll(&client, allocator, SNAP_PREFIX);
    defer {
        for (keys.items) |k| allocator.free(k);
        keys.deinit(allocator);
    }
    for (keys.items) |key| {
        if (std.mem.endsWith(u8, key, ".json") and !std.mem.startsWith(u8, key[SNAP_PREFIX.len..], "chunks/")) {
            std.debug.print("{s}\n", .{key[SNAP_PREFIX.len .. key.len - 5]});
        }
    }
}

// Manifest parser: extracts objects in order. Format is writer-controlled.
const SnapObject = struct {
    key: []const u8,
    size: usize,
    hash: [64]u8,
    chunks: [][]const u8,
};

fn skipWs(s: []const u8, i: *usize) void {
    while (i.* < s.len and (s[i.*] == ' ' or s[i.*] == '\n' or s[i.*] == '\r' or s[i.*] == '\t')) i.* += 1;
}

fn parseJsonString(allocator: Allocator, s: []const u8, i: *usize) ![]const u8 {
    // s[i] == '"'
    i.* += 1;
    var out: std.ArrayListUnmanaged(u8) = .empty;
    errdefer out.deinit(allocator);
    while (i.* < s.len) {
        const c = s[i.*];
        if (c == '"') {
            i.* += 1;
            return out.toOwnedSlice(allocator);
        } else if (c == '\\') {
            i.* += 1;
            if (i.* >= s.len) return error.BadManifest;
            const e = s[i.*];
            switch (e) {
                '"', '\\', '/' => try out.append(allocator, e),
                'n' => try out.append(allocator, '\n'),
                'r' => try out.append(allocator, '\r'),
                't' => try out.append(allocator, '\t'),
                'b' => try out.append(allocator, 0x08),
                'f' => try out.append(allocator, 0x0c),
                'u' => {
                    if (i.* + 4 >= s.len) return error.BadManifest;
                    const cp = std.fmt.parseInt(u21, s[i.* + 1 .. i.* + 5], 16) catch return error.BadManifest;
                    var buf: [4]u8 = undefined;
                    const n = std.unicode.utf8Encode(cp, &buf) catch return error.BadManifest;
                    try out.appendSlice(allocator, buf[0..n]);
                    i.* += 4;
                },
                else => return error.BadManifest,
            }
            i.* += 1;
        } else {
            try out.append(allocator, c);
            i.* += 1;
        }
    }
    return error.BadManifest;
}

fn parseManifest(allocator: Allocator, body: []const u8) ![]SnapObject {
    var objects: std.ArrayListUnmanaged(SnapObject) = .empty;
    errdefer {
        for (objects.items) |*o| {
            allocator.free(o.key);
            for (o.chunks) |c| allocator.free(c);
            allocator.free(o.chunks);
        }
        objects.deinit(allocator);
    }
    // Find "objects":[ ... ] and parse each {"key","size","hash","chunks"}.
    const arr_start = std.mem.indexOf(u8, body, "\"objects\"") orelse return error.BadManifest;
    var i = arr_start + 9;
    skipWs(body, &i);
    if (i >= body.len or body[i] != ':') return error.BadManifest;
    i += 1;
    skipWs(body, &i);
    if (i >= body.len or body[i] != '[') return error.BadManifest;
    i += 1;
    while (true) {
        skipWs(body, &i);
        if (i >= body.len) return error.BadManifest;
        if (body[i] == ']') {
            i += 1;
            break;
        }
        if (body[i] == ',') {
            i += 1;
            continue;
        }
        if (body[i] != '{') return error.BadManifest;
        i += 1;
        var key: ?[]const u8 = null;
        var size: usize = 0;
        var hash: [64]u8 = undefined;
        var chunks: std.ArrayListUnmanaged([]const u8) = .empty;
        errdefer {
            if (key) |k| allocator.free(k);
            for (chunks.items) |c| allocator.free(c);
            chunks.deinit(allocator);
        }
        while (true) {
            skipWs(body, &i);
            if (i >= body.len) return error.BadManifest;
            if (body[i] == '}') {
                i += 1;
                break;
            }
            if (body[i] == ',') {
                i += 1;
                continue;
            }
            if (body[i] != '"') return error.BadManifest;
            const field = try parseJsonString(allocator, body, &i);
            defer allocator.free(field);
            skipWs(body, &i);
            if (i >= body.len or body[i] != ':') return error.BadManifest;
            i += 1;
            skipWs(body, &i);
            if (std.mem.eql(u8, field, "key")) {
                if (i >= body.len or body[i] != '"') return error.BadManifest;
                key = try parseJsonString(allocator, body, &i);
            } else if (std.mem.eql(u8, field, "size")) {
                const start = i;
                while (i < body.len and body[i] >= '0' and body[i] <= '9') i += 1;
                size = std.fmt.parseInt(usize, body[start..i], 10) catch return error.BadManifest;
            } else if (std.mem.eql(u8, field, "hash")) {
                if (i >= body.len or body[i] != '"') return error.BadManifest;
                const h = try parseJsonString(allocator, body, &i);
                defer allocator.free(h);
                if (h.len != 64) return error.BadManifest;
                @memcpy(&hash, h);
            } else if (std.mem.eql(u8, field, "chunks")) {
                if (i >= body.len or body[i] != '[') return error.BadManifest;
                i += 1;
                while (true) {
                    skipWs(body, &i);
                    if (i >= body.len) return error.BadManifest;
                    if (body[i] == ']') {
                        i += 1;
                        break;
                    }
                    if (body[i] == ',') {
                        i += 1;
                        continue;
                    }
                    if (body[i] != '"') return error.BadManifest;
                    const c = try parseJsonString(allocator, body, &i);
                    try chunks.append(allocator, c);
                }
            } else {
                // Skip unknown field value (string/number/array/object, one level).
                if (i < body.len and body[i] == '"') {
                    const tmp = try parseJsonString(allocator, body, &i);
                    allocator.free(tmp);
                } else {
                    while (i < body.len and body[i] != ',' and body[i] != '}') i += 1;
                }
            }
        }
        try objects.append(allocator, .{
            .key = key orelse return error.BadManifest,
            .size = size,
            .hash = hash,
            .chunks = try chunks.toOwnedSlice(allocator),
        });
    }
    return objects.toOwnedSlice(allocator);
}

fn runClone(allocator: Allocator, args: []const []const u8) !void {
    const sa = try parseSnapArgs(allocator, args);
    if (sa.bucket.len == 0 or sa.name.len == 0 or sa.dest.len == 0) {
        std.debug.print("Usage: zs3 clone --bucket=BUCKET --name=NAME --dest=DIR [--endpoint=URL] [--cache=DIR]\n", .{});
        return error.BadArgs;
    }
    const ep = try splitEndpoint(sa.endpoint);
    var client = S3Client{
        .allocator = allocator,
        .host = ep.host,
        .port = ep.port,
        .bucket = sa.bucket,
        .region = sa.region,
        .access = sa.access,
        .secret = sa.secret,
        .tls = ep.tls,
        .insecure = sa.insecure,
        .ca_file = sa.ca_file,
    };
    const manifest_key = try std.fmt.allocPrint(allocator, "{s}{s}.json", .{ SNAP_PREFIX, sa.name });
    defer allocator.free(manifest_key);
    const manifest_body = client.get(manifest_key) catch {
        std.debug.print("snapshot '{s}' not found in bucket '{s}' (run `zs3 snapshots --bucket={s}` to list)\n", .{ sa.name, sa.bucket, sa.bucket });
        return error.SnapshotNotFound;
    };
    defer allocator.free(manifest_body);

    const objects = try parseManifest(allocator, manifest_body);
    defer {
        for (objects) |*o| {
            allocator.free(o.key);
            for (o.chunks) |c| allocator.free(c);
            allocator.free(o.chunks);
        }
        allocator.free(objects);
    }

    const cache_dir = if (sa.cache.len > 0)
        try allocator.dupe(u8, sa.cache)
    else
        try std.fmt.allocPrint(allocator, "{s}/.zs3/blobs", .{sa.dest});
    defer allocator.free(cache_dir);

    var transferred: usize = 0;
    var reused: usize = 0;
    var files: usize = 0;
    for (objects) |obj| {
        // Assemble from cache, fetching only missing chunks.
        var assembled: std.ArrayListUnmanaged(u8) = .empty;
        defer assembled.deinit(allocator);
        for (obj.chunks) |chex| {
            const blob_path = try std.fmt.allocPrint(allocator, "{s}/{s}/{s}", .{ cache_dir, chex[0..2], chex[2..] });
            defer allocator.free(blob_path);
            if (std.Io.Dir.cwd().openFile(app_io, blob_path, .{})) |file| {
                defer file.close(app_io);
                const stat = try file.stat(app_io);
                const prev = assembled.items.len;
                try assembled.appendNTimes(allocator, 0, stat.size);
                _ = try file.readPositionalAll(app_io, assembled.items[prev..], 0);
                reused += stat.size;
            } else |_| {
                const chunk_key = try std.fmt.allocPrint(allocator, "{s}{s}", .{ SNAP_CHUNK_PREFIX, chex });
                defer allocator.free(chunk_key);
                const data = try client.get(chunk_key);
                defer allocator.free(data);
                var af = try std.Io.Dir.cwd().createFileAtomic(app_io, blob_path, .{ .make_path = true, .replace = true });
                defer af.deinit(app_io);
                try af.file.writeStreamingAll(app_io, data);
                if (enable_fsync) fsyncFile(af.file);
                try af.replace(app_io);
                try assembled.appendSlice(allocator, data);
                transferred += data.len;
            }
        }
        // Verify whole-object hash before materializing.
        var whole_hex: [64]u8 = undefined;
        blake3Hex32(assembled.items, &whole_hex);
        if (!std.mem.eql(u8, &whole_hex, &obj.hash)) {
            std.debug.print("WARNING: hash mismatch for {s}, skipping\n", .{obj.key});
            continue;
        }
        const dest_path = try std.fs.path.join(allocator, &.{ sa.dest, obj.key });
        defer allocator.free(dest_path);
        var out = try std.Io.Dir.cwd().createFileAtomic(app_io, dest_path, .{ .make_path = true, .replace = true });
        defer out.deinit(app_io);
        try out.file.writeStreamingAll(app_io, assembled.items);
        if (enable_fsync) fsyncFile(out.file);
        try out.replace(app_io);
        if (enable_fsync) fsyncParentDir(dest_path);
        files += 1;
    }
    // Keep a copy of the manifest beside the cache for auditability.
    const meta_path = try std.fmt.allocPrint(allocator, "{s}/.zs3/manifest.json", .{sa.dest});
    defer allocator.free(meta_path);
    if (std.fs.path.dirname(meta_path)) |dir| {
        std.Io.Dir.cwd().createDirPath(app_io, dir) catch {};
    }
    if (std.Io.Dir.cwd().createFile(app_io, meta_path, .{})) |file| {
        defer file.close(app_io);
        file.writeStreamingAll(app_io, manifest_body) catch {};
    } else |_| {}
    std.debug.print("clone {s}: {d} files, {d} bytes transferred, {d} reused from cache\n", .{ sa.name, files, transferred, reused });
}

// ============================================================================
// BUCKET CONFIGURATION (ACL, versioning, lifecycle, encryption, tagging)
// ============================================================================
// Per-bucket settings live as small files under `<bucket>/.zs3bucket/`, and
// object versions under `<bucket>/.zs3versions/`. Both directories are hidden
// from LIST, ignored by snapshots, and removed with the bucket.

const BUCKET_CFG_DIR = ".zs3bucket";
const VERSIONS_DIR = ".zs3versions";
const OWNER_ID = "minioadmin";

fn bucketConfigPath(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, name: []const u8) ![]const u8 {
    return std.fs.path.join(allocator, &.{ ctx.data_dir, bucket, BUCKET_CFG_DIR, name });
}

fn readBucketConfig(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, name: []const u8) ?[]u8 {
    const path = bucketConfigPath(ctx, allocator, bucket, name) catch return null;
    defer allocator.free(path);
    var file = std.Io.Dir.cwd().openFile(app_io, path, .{}) catch return null;
    defer file.close(app_io);
    return readToEndAlloc(file, allocator, 1024 * 1024) catch null;
}

fn writeBucketConfig(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, name: []const u8, content: []const u8) !void {
    const path = try bucketConfigPath(ctx, allocator, bucket, name);
    defer allocator.free(path);
    var af = try std.Io.Dir.cwd().createFileAtomic(app_io, path, .{ .make_path = true, .replace = true });
    defer af.deinit(app_io);
    try af.file.writeStreamingAll(app_io, content);
    fsyncFile(af.file);
    try af.replace(app_io);
    fsyncParentDir(path);
}

fn deleteBucketConfig(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, name: []const u8) void {
    const path = bucketConfigPath(ctx, allocator, bucket, name) catch return;
    defer allocator.free(path);
    std.Io.Dir.cwd().deleteFile(app_io, path) catch {};
}

fn bucketExists(ctx: *const S3Context, allocator: Allocator, bucket: []const u8) bool {
    const path = ctx.bucketPath(allocator, bucket) catch return false;
    defer allocator.free(path);
    var dir = std.Io.Dir.cwd().openDir(app_io, path, .{}) catch return false;
    dir.close(app_io);
    return true;
}

/// Read attrs for an object through whichever backend is active.
fn loadObjectAttrsAny(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, key: []const u8) ?ObjectAttrs {
    if (ctx.distributed) |dist| {
        return readDistAttrs(allocator, dist, bucket, key);
    }
    const path = ctx.objectPath(allocator, bucket, key) catch return null;
    defer allocator.free(path);
    // Missing object: no attrs.
    std.Io.Dir.cwd().access(app_io, path, .{}) catch return null;
    return loadStandaloneAttrs(allocator, path, key) catch null;
}

fn saveObjectAttrsAny(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, key: []const u8, attrs: *const ObjectAttrs) !void {
    if (ctx.distributed) |dist| {
        writeDistAttrs(allocator, dist, bucket, key, attrs);
        propagateObjectAttrs(ctx, allocator, bucket, key);
        return;
    }
    const path = try ctx.objectPath(allocator, bucket, key);
    defer allocator.free(path);
    saveStandaloneAttrs(allocator, path, attrs);
}

fn objectExistsAny(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, key: []const u8) bool {
    if (ctx.distributed) |dist| {
        const meta = dist.meta_index.getFull(allocator, bucket, key) catch return false;
        if (meta) |m| {
            if (m.inline_data) |d| allocator.free(d);
            return true;
        }
        return false;
    }
    const path = ctx.objectPath(allocator, bucket, key) catch return false;
    defer allocator.free(path);
    const stat = std.Io.Dir.cwd().statFile(app_io, path, .{}) catch return false;
    return stat.kind == .file;
}

// ---------------------------------------------------------------------------
// Tagging
// ---------------------------------------------------------------------------

const Tag = struct { key: []const u8, value: []const u8 };

const MAX_TAGS = 10;

fn freeTags(allocator: Allocator, tags: []Tag) void {
    for (tags) |t| {
        allocator.free(t.key);
        allocator.free(t.value);
    }
    allocator.free(tags);
}

fn validateTags(tags: []const Tag) !void {
    if (tags.len > MAX_TAGS) return error.InvalidTag;
    for (tags, 0..) |t, i| {
        if (t.key.len == 0 or t.key.len > 128 or t.value.len > 256) return error.InvalidTag;
        for (tags[0..i]) |prev| {
            if (std.mem.eql(u8, prev.key, t.key)) return error.InvalidTag;
        }
    }
}

/// Parse the x-amz-tagging header / query form: "k=v&k2=v2" (URL-encoded).
pub fn parseTagQuery(allocator: Allocator, text: []const u8) ![]Tag {
    var list: std.ArrayListUnmanaged(Tag) = .empty;
    errdefer {
        for (list.items) |t| {
            allocator.free(t.key);
            allocator.free(t.value);
        }
        list.deinit(allocator);
    }
    const trimmed = std.mem.trim(u8, text, " \t");
    if (trimmed.len == 0) return list.toOwnedSlice(allocator);
    var it = std.mem.splitScalar(u8, trimmed, '&');
    while (it.next()) |pair| {
        if (pair.len == 0) continue;
        const eq = std.mem.indexOfScalar(u8, pair, '=');
        const raw_k = if (eq) |e| pair[0..e] else pair;
        const raw_v = if (eq) |e| pair[e + 1 ..] else "";
        const k = try uriDecode(allocator, raw_k);
        errdefer allocator.free(k);
        const v = try uriDecode(allocator, raw_v);
        errdefer allocator.free(v);
        try list.append(allocator, .{ .key = k, .value = v });
    }
    try validateTags(list.items);
    return list.toOwnedSlice(allocator);
}

/// Parse a <Tagging><TagSet><Tag><Key/><Value/></Tag>…</TagSet></Tagging> body.
pub fn parseTaggingXml(allocator: Allocator, body: []const u8) ![]Tag {
    var list: std.ArrayListUnmanaged(Tag) = .empty;
    errdefer {
        for (list.items) |t| {
            allocator.free(t.key);
            allocator.free(t.value);
        }
        list.deinit(allocator);
    }
    if (std.mem.indexOf(u8, body, "<Tagging") == null) return error.MalformedXML;
    var rest = body;
    while (std.mem.indexOf(u8, rest, "<Tag>")) |start| {
        const after = rest[start + 5 ..];
        const end = std.mem.indexOf(u8, after, "</Tag>") orelse return error.MalformedXML;
        const block = after[0..end];
        const k = xmlTagText(block, "Key") orelse return error.MalformedXML;
        const v = xmlTagText(block, "Value") orelse "";
        const dk = try xmlUnescape(allocator, k);
        errdefer allocator.free(dk);
        const dv = try xmlUnescape(allocator, v);
        errdefer allocator.free(dv);
        try list.append(allocator, .{ .key = dk, .value = dv });
        rest = after[end + 6 ..];
    }
    try validateTags(list.items);
    return list.toOwnedSlice(allocator);
}

pub fn tagsToQuery(allocator: Allocator, tags: []const Tag) ![]const u8 {
    var buf: std.ArrayListUnmanaged(u8) = .empty;
    errdefer buf.deinit(allocator);
    for (tags, 0..) |t, i| {
        if (i > 0) try buf.append(allocator, '&');
        const ek = try uriEncode(allocator, t.key, true);
        defer allocator.free(ek);
        const ev = try uriEncode(allocator, t.value, true);
        defer allocator.free(ev);
        try buf.appendSlice(allocator, ek);
        try buf.append(allocator, '=');
        try buf.appendSlice(allocator, ev);
    }
    return buf.toOwnedSlice(allocator);
}

fn tagsToXml(allocator: Allocator, tags: []const Tag) ![]const u8 {
    var xml: std.ArrayListUnmanaged(u8) = .empty;
    errdefer xml.deinit(allocator);
    try xml.appendSlice(allocator, "<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
    try xml.appendSlice(allocator, "<Tagging xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\"><TagSet>");
    for (tags) |t| {
        try xml.appendSlice(allocator, "<Tag><Key>");
        try xmlEscape(allocator, &xml, t.key);
        try xml.appendSlice(allocator, "</Key><Value>");
        try xmlEscape(allocator, &xml, t.value);
        try xml.appendSlice(allocator, "</Value></Tag>");
    }
    try xml.appendSlice(allocator, "</TagSet></Tagging>");
    return xml.toOwnedSlice(allocator);
}

/// GET/PUT/DELETE /{bucket}/{key}?tagging
fn handleObjectTagging(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, key: []const u8) !void {
    const effective_key = if (key.len > 0 and key[key.len - 1] == '/')
        try std.fmt.allocPrint(allocator, "{s}.folder_marker", .{key})
    else
        try allocator.dupe(u8, key);
    defer allocator.free(effective_key);

    if (!objectExistsAny(ctx, allocator, bucket, effective_key)) {
        sendError(res, 404, "NoSuchKey", "Object not found");
        return;
    }
    var attrs = loadObjectAttrsAny(ctx, allocator, bucket, effective_key) orelse
        ObjectAttrs{ .content_type = try allocator.dupe(u8, DEFAULT_CONTENT_TYPE) };
    // NB: attrs memory feeds response headers; arena-freed after write.

    if (std.mem.eql(u8, req.method, "GET")) {
        const tags = if (attrs.tagging) |t| try parseTagQuery(allocator, t) else &[_]Tag{};
        res.ok();
        if (attrs.version_id) |v| res.setHeader("x-amz-version-id", v);
        res.setXmlBody(try tagsToXml(allocator, tags));
        return;
    }
    if (std.mem.eql(u8, req.method, "PUT")) {
        const tags = parseTaggingXml(allocator, req.body) catch |err| switch (err) {
            error.MalformedXML => {
                sendError(res, 400, "MalformedXML", "The XML you provided was not well-formed");
                return;
            },
            error.InvalidTag => {
                sendError(res, 400, "InvalidTag", "The TagValue you have provided is invalid");
                return;
            },
            else => return err,
        };
        if (attrs.tagging) |old| allocator.free(old);
        attrs.tagging = try tagsToQuery(allocator, tags);
        try saveObjectAttrsAny(ctx, allocator, bucket, effective_key, &attrs);
        res.ok();
        if (attrs.version_id) |v| res.setHeader("x-amz-version-id", v);
        return;
    }
    if (std.mem.eql(u8, req.method, "DELETE")) {
        if (attrs.tagging) |old| allocator.free(old);
        attrs.tagging = null;
        try saveObjectAttrsAny(ctx, allocator, bucket, effective_key, &attrs);
        res.noContent();
        if (attrs.version_id) |v| res.setHeader("x-amz-version-id", v);
        return;
    }
    sendError(res, 405, "MethodNotAllowed", "Method not allowed");
}

/// GET/PUT/DELETE /{bucket}?tagging
fn handleBucketTagging(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8) !void {
    if (!bucketExists(ctx, allocator, bucket)) {
        sendError(res, 404, "NoSuchBucket", "Bucket not found");
        return;
    }
    if (std.mem.eql(u8, req.method, "GET")) {
        const stored = readBucketConfig(ctx, allocator, bucket, "tagging") orelse {
            sendError(res, 404, "NoSuchTagSet", "The TagSet does not exist");
            return;
        };
        const tags = try parseTagQuery(allocator, stored);
        res.ok();
        res.setXmlBody(try tagsToXml(allocator, tags));
        return;
    }
    if (std.mem.eql(u8, req.method, "PUT")) {
        const tags = parseTaggingXml(allocator, req.body) catch |err| switch (err) {
            error.MalformedXML => {
                sendError(res, 400, "MalformedXML", "The XML you provided was not well-formed");
                return;
            },
            error.InvalidTag => {
                sendError(res, 400, "InvalidTag", "The TagValue you have provided is invalid");
                return;
            },
            else => return err,
        };
        const q = try tagsToQuery(allocator, tags);
        try writeBucketConfig(ctx, allocator, bucket, "tagging", q);
        res.ok();
        return;
    }
    if (std.mem.eql(u8, req.method, "DELETE")) {
        deleteBucketConfig(ctx, allocator, bucket, "tagging");
        res.noContent();
        return;
    }
    sendError(res, 405, "MethodNotAllowed", "Method not allowed");
}

// ---------------------------------------------------------------------------
// ACLs (canned)
// ---------------------------------------------------------------------------
// zs3 has one owner (the configured credentials). Canned ACLs decide what
// anonymous (unsigned) requests may do: `public-read` grants GET/HEAD/LIST,
// `public-read-write` adds PUT/POST/DELETE on objects. Everything else is
// `private`. Grants to specific AWS accounts have no meaning here and are
// rejected with a clear error rather than silently accepted.

pub fn isCannedAcl(name: []const u8) bool {
    const canned = [_][]const u8{ "private", "public-read", "public-read-write", "authenticated-read", "bucket-owner-read", "bucket-owner-full-control", "aws-exec-read", "log-delivery-write" };
    for (canned) |c| {
        if (std.mem.eql(u8, c, name)) return true;
    }
    return false;
}

/// Collapse canned ACLs to the three that change behavior here.
pub fn normalizeCannedAcl(name: []const u8) []const u8 {
    if (std.mem.eql(u8, name, "public-read")) return "public-read";
    if (std.mem.eql(u8, name, "public-read-write")) return "public-read-write";
    return "private";
}

fn aclAllowsAnonymousRead(acl_name: ?[]const u8) bool {
    const a = acl_name orelse return false;
    return std.mem.eql(u8, a, "public-read") or std.mem.eql(u8, a, "public-read-write");
}

fn aclAllowsAnonymousWrite(acl_name: ?[]const u8) bool {
    const a = acl_name orelse return false;
    return std.mem.eql(u8, a, "public-read-write");
}

fn readBucketAcl(ctx: *const S3Context, allocator: Allocator, bucket: []const u8) []const u8 {
    const stored = readBucketConfig(ctx, allocator, bucket, "acl") orelse return "private";
    return normalizeCannedAcl(std.mem.trim(u8, stored, " \t\r\n"));
}

/// Role an unsigned request gets from bucket/object ACLs, or null (403).
fn anonymousRole(ctx: *const S3Context, allocator: Allocator, req: *const Request, bucket: []const u8, key: []const u8) ?acl.Role {
    if (bucket.len == 0) return null;
    const is_read = std.mem.eql(u8, req.method, "GET") or std.mem.eql(u8, req.method, "HEAD");
    const bucket_acl = readBucketAcl(ctx, allocator, bucket);
    if (aclAllowsAnonymousWrite(bucket_acl)) return .Writer;
    if (is_read and aclAllowsAnonymousRead(bucket_acl)) return .Reader;
    if (is_read and key.len > 0) {
        const effective_key = if (key[key.len - 1] == '/')
            std.fmt.allocPrint(allocator, "{s}.folder_marker", .{key}) catch return null
        else
            key;
        if (loadObjectAttrsAny(ctx, allocator, bucket, effective_key)) |attrs| {
            if (aclAllowsAnonymousRead(attrs.acl)) return .Reader;
        }
    }
    return null;
}

fn aclPolicyXml(allocator: Allocator, canned: []const u8) ![]const u8 {
    var xml: std.ArrayListUnmanaged(u8) = .empty;
    errdefer xml.deinit(allocator);
    try xml.appendSlice(allocator, "<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
    try xml.appendSlice(allocator, "<AccessControlPolicy xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\"><Owner><ID>" ++ OWNER_ID ++ "</ID><DisplayName>" ++ OWNER_ID ++ "</DisplayName></Owner><AccessControlList>");
    try xml.appendSlice(allocator, "<Grant><Grantee xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:type=\"CanonicalUser\"><ID>" ++ OWNER_ID ++ "</ID><DisplayName>" ++ OWNER_ID ++ "</DisplayName></Grantee><Permission>FULL_CONTROL</Permission></Grant>");
    if (aclAllowsAnonymousRead(canned)) {
        try xml.appendSlice(allocator, "<Grant><Grantee xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:type=\"Group\"><URI>http://acs.amazonaws.com/groups/global/AllUsers</URI></Grantee><Permission>READ</Permission></Grant>");
    }
    if (aclAllowsAnonymousWrite(canned)) {
        try xml.appendSlice(allocator, "<Grant><Grantee xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:type=\"Group\"><URI>http://acs.amazonaws.com/groups/global/AllUsers</URI></Grantee><Permission>WRITE</Permission></Grant>");
    }
    try xml.appendSlice(allocator, "</AccessControlList></AccessControlPolicy>");
    return xml.toOwnedSlice(allocator);
}

/// Resolve the ACL a PUT ?acl request asks for: x-amz-acl header, or an
/// AccessControlPolicy body reduced to its AllUsers grants.
fn aclFromRequest(req: *const Request) ![]const u8 {
    if (req.header("x-amz-acl")) |h| {
        if (!isCannedAcl(h)) return error.InvalidAcl;
        return normalizeCannedAcl(h);
    }
    const body = req.body;
    if (std.mem.indexOf(u8, body, "<AccessControlPolicy") == null) return error.MalformedACL;
    var read = false;
    var write = false;
    var rest = body;
    while (std.mem.indexOf(u8, rest, "<Grant>")) |start| {
        const after = rest[start + 7 ..];
        const end = std.mem.indexOf(u8, after, "</Grant>") orelse return error.MalformedACL;
        const grant = after[0..end];
        const perm = xmlTagText(grant, "Permission") orelse "";
        const uri = xmlTagText(grant, "URI") orelse "";
        const all_users = std.mem.endsWith(u8, uri, "/AllUsers");
        const owner = if (xmlTagText(grant, "ID")) |id| std.mem.eql(u8, id, OWNER_ID) else false;
        if (all_users) {
            if (std.mem.eql(u8, perm, "READ")) read = true;
            if (std.mem.eql(u8, perm, "WRITE")) write = true;
            if (std.mem.eql(u8, perm, "FULL_CONTROL")) {
                read = true;
                write = true;
            }
        } else if (!owner and !std.mem.endsWith(u8, uri, "/AuthenticatedUsers")) {
            // Grants to arbitrary accounts cannot be honored.
            return error.UnsupportedGrantee;
        }
        rest = after[end + 8 ..];
    }
    if (write) return "public-read-write";
    if (read) return "public-read";
    return "private";
}

fn sendAclError(res: *Response, err: anyerror) void {
    switch (err) {
        error.InvalidAcl => sendError(res, 400, "InvalidArgument", "Unknown canned ACL"),
        error.MalformedACL => sendError(res, 400, "MalformedACLError", "The XML you provided was not well-formed or did not validate against our published schema"),
        error.UnsupportedGrantee => sendError(res, 400, "UnresolvableGrantByEmailAddress", "zs3 supports canned ACLs and AllUsers grants only"),
        else => sendError(res, 500, "InternalError", "ACL update failed"),
    }
}

/// GET/PUT /{bucket}?acl
fn handleBucketAcl(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8) !void {
    if (!bucketExists(ctx, allocator, bucket)) {
        sendError(res, 404, "NoSuchBucket", "Bucket not found");
        return;
    }
    if (std.mem.eql(u8, req.method, "GET")) {
        res.ok();
        res.setXmlBody(try aclPolicyXml(allocator, readBucketAcl(ctx, allocator, bucket)));
        return;
    }
    if (std.mem.eql(u8, req.method, "PUT")) {
        const canned = aclFromRequest(req) catch |err| {
            sendAclError(res, err);
            return;
        };
        try writeBucketConfig(ctx, allocator, bucket, "acl", canned);
        res.ok();
        return;
    }
    sendError(res, 405, "MethodNotAllowed", "Method not allowed");
}

/// GET/PUT /{bucket}/{key}?acl
fn handleObjectAcl(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, key: []const u8) !void {
    const effective_key = if (key.len > 0 and key[key.len - 1] == '/')
        try std.fmt.allocPrint(allocator, "{s}.folder_marker", .{key})
    else
        try allocator.dupe(u8, key);
    defer allocator.free(effective_key);
    if (!objectExistsAny(ctx, allocator, bucket, effective_key)) {
        sendError(res, 404, "NoSuchKey", "Object not found");
        return;
    }
    var attrs = loadObjectAttrsAny(ctx, allocator, bucket, effective_key) orelse
        ObjectAttrs{ .content_type = try allocator.dupe(u8, DEFAULT_CONTENT_TYPE) };
    if (std.mem.eql(u8, req.method, "GET")) {
        res.ok();
        if (attrs.version_id) |v| res.setHeader("x-amz-version-id", v);
        res.setXmlBody(try aclPolicyXml(allocator, attrs.acl orelse "private"));
        return;
    }
    if (std.mem.eql(u8, req.method, "PUT")) {
        const canned = aclFromRequest(req) catch |err| {
            sendAclError(res, err);
            return;
        };
        if (attrs.acl) |old| allocator.free(old);
        attrs.acl = if (std.mem.eql(u8, canned, "private")) null else try allocator.dupe(u8, canned);
        if (attrs.acl != null) noteObjectAclUsed(ctx);
        try saveObjectAttrsAny(ctx, allocator, bucket, effective_key, &attrs);
        res.ok();
        if (attrs.version_id) |v| res.setHeader("x-amz-version-id", v);
        return;
    }
    sendError(res, 405, "MethodNotAllowed", "Method not allowed");
}

// ---------------------------------------------------------------------------
// Subresource routing
// ---------------------------------------------------------------------------

/// Bucket/object subresources (?acl, ?tagging, ?versioning, ?versions,
/// ?lifecycle, ?encryption). Returns true when the request was handled.
/// Anonymous callers may read but never change configuration.
fn routeSubresource(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, key: []const u8, anonymous: bool) !bool {
    if (bucket.len == 0) return false;
    const q = req.query;
    const is_get = std.mem.eql(u8, req.method, "GET");
    const mutating = !is_get and !std.mem.eql(u8, req.method, "HEAD");

    const sub: enum { none, acl, tagging, versioning, versions, lifecycle, encryption } =
        if (hasQuery(q, "acl")) .acl else if (hasQuery(q, "tagging")) .tagging else if (hasQuery(q, "versioning")) .versioning else if (hasQuery(q, "versions")) .versions else if (hasQuery(q, "lifecycle")) .lifecycle else if (hasQuery(q, "encryption")) .encryption else .none;
    if (sub == .none) return false;

    // Configuration changes need real credentials, even on public-read-write
    // buckets (S3 keeps WRITE_ACP separate from WRITE).
    const object_data_change = key.len > 0 and sub == .tagging;
    if (anonymous and mutating and !object_data_change) {
        sendError(res, 403, "AccessDenied", "Anonymous requests cannot change bucket configuration");
        return true;
    }

    switch (sub) {
        .acl => if (key.len == 0) try handleBucketAcl(ctx, allocator, req, res, bucket) else try handleObjectAcl(ctx, allocator, req, res, bucket, key),
        .tagging => if (key.len == 0) try handleBucketTagging(ctx, allocator, req, res, bucket) else try handleObjectTagging(ctx, allocator, req, res, bucket, key),
        .versioning => try handleBucketVersioning(ctx, allocator, req, res, bucket),
        .versions => if (key.len == 0 and is_get) try handleListObjectVersions(ctx, allocator, req, res, bucket) else return false,
        .lifecycle => try handleBucketLifecycle(ctx, allocator, req, res, bucket),
        .encryption => try handleBucketEncryption(ctx, allocator, req, res, bucket),
        .none => unreachable,
    }
    return true;
}

// (implemented in the versioning / lifecycle / encryption sections below)

// ---------------------------------------------------------------------------
// Versioning
// ---------------------------------------------------------------------------
// The current version of a key stays at its normal path, so the directory is
// still a plain tree of files. Older versions and delete markers move to
// `<bucket>/.zs3versions/<key>.v/<version-id>` (`.zs3attrs` sidecars travel
// with them; delete markers are empty `<version-id>.deletemarker` files).
// An object written before versioning was enabled is the "null" version,
// exactly as in S3. Version IDs are 32 hex chars: 16 of write time in
// nanoseconds, 16 random.

const VersioningStatus = enum { disabled, enabled, suspended };

const NULL_VERSION = "null";
const DELETE_MARKER_SUFFIX = ".deletemarker";
const VERSION_DIR_SUFFIX = ".v";

fn bucketVersioning(ctx: *const S3Context, allocator: Allocator, bucket: []const u8) VersioningStatus {
    const stored = readBucketConfig(ctx, allocator, bucket, "versioning") orelse return .disabled;
    defer allocator.free(stored);
    const t = std.mem.trim(u8, stored, " \t\r\n");
    if (std.mem.eql(u8, t, "Enabled")) return .enabled;
    if (std.mem.eql(u8, t, "Suspended")) return .suspended;
    return .disabled;
}

/// GET/PUT /{bucket}?versioning
fn handleBucketVersioning(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8) !void {
    if (!bucketExists(ctx, allocator, bucket)) {
        sendError(res, 404, "NoSuchBucket", "Bucket not found");
        return;
    }
    if (std.mem.eql(u8, req.method, "GET")) {
        const status = bucketVersioning(ctx, allocator, bucket);
        const body = switch (status) {
            .disabled => "<?xml version=\"1.0\" encoding=\"UTF-8\"?><VersioningConfiguration xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\"/>",
            .enabled => "<?xml version=\"1.0\" encoding=\"UTF-8\"?><VersioningConfiguration xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\"><Status>Enabled</Status></VersioningConfiguration>",
            .suspended => "<?xml version=\"1.0\" encoding=\"UTF-8\"?><VersioningConfiguration xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\"><Status>Suspended</Status></VersioningConfiguration>",
        };
        res.ok();
        res.setXmlBody(body);
        return;
    }
    if (std.mem.eql(u8, req.method, "PUT")) {
        if (ctx.distributed != null) {
            sendError(res, 501, "NotImplemented", "Versioning is not available in distributed mode");
            return;
        }
        const status = xmlTagText(req.body, "Status") orelse {
            sendError(res, 400, "IllegalVersioningConfigurationException", "The Versioning element must contain a Status of Enabled or Suspended");
            return;
        };
        if (!std.mem.eql(u8, status, "Enabled") and !std.mem.eql(u8, status, "Suspended")) {
            sendError(res, 400, "IllegalVersioningConfigurationException", "Status must be Enabled or Suspended");
            return;
        }
        try writeBucketConfig(ctx, allocator, bucket, "versioning", status);
        res.ok();
        return;
    }
    sendError(res, 405, "MethodNotAllowed", "Method not allowed");
}

pub fn isValidVersionId(vid: []const u8) bool {
    if (std.mem.eql(u8, vid, NULL_VERSION)) return true;
    if (vid.len != 32) return false;
    for (vid) |c| {
        if (!std.ascii.isHex(c) or std.ascii.isUpper(c)) return false;
    }
    return true;
}

fn newVersionId(allocator: Allocator) ![]const u8 {
    const now = std.Io.Clock.real.now(app_io);
    const nanos: u64 = @intCast(@max(now.nanoseconds, 0));
    var rnd: [8]u8 = undefined;
    app_io.random(&rnd);
    return std.fmt.allocPrint(allocator, "{x:0>16}{x:0>16}", .{ nanos, std.mem.readInt(u64, &rnd, .little) });
}

fn versionsDirPath(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, effective_key: []const u8) ![]const u8 {
    const leaf = try std.fmt.allocPrint(allocator, "{s}" ++ VERSION_DIR_SUFFIX, .{effective_key});
    defer allocator.free(leaf);
    return std.fs.path.join(allocator, &.{ ctx.data_dir, bucket, VERSIONS_DIR, leaf });
}

fn versionFilePath(allocator: Allocator, vdir: []const u8, vid: []const u8, suffix: []const u8) ![]const u8 {
    return std.fmt.allocPrint(allocator, "{s}/{s}{s}", .{ vdir, vid, suffix });
}

/// Version id of the object at `path` ("null" when it has none).
fn currentVersionId(allocator: Allocator, path: []const u8, key: []const u8) []const u8 {
    const attrs = loadStandaloneAttrs(allocator, path, key) catch return NULL_VERSION;
    // Arena-allocated; deinit is cosmetic here but keeps non-arena callers clean.
    const vid = if (attrs.version_id) |v| allocator.dupe(u8, v) catch NULL_VERSION else NULL_VERSION;
    attrs.deinit(allocator);
    return vid;
}

fn renameFile(old_path: []const u8, new_path: []const u8) !void {
    try std.Io.Dir.rename(std.Io.Dir.cwd(), old_path, std.Io.Dir.cwd(), new_path, app_io);
}

/// Move the current object (file + sidecar) into the versions directory
/// under its version id. Called before any overwrite or delete on a bucket
/// with versioning enabled or suspended. In the suspended state the null
/// version is overwritten in place (S3 semantics), so nothing is archived.
fn archiveCurrentVersion(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, effective_key: []const u8, path: []const u8, status: VersioningStatus) !void {
    if (status == .disabled) return;
    const stat = std.Io.Dir.cwd().statFile(app_io, path, .{}) catch return;
    if (stat.kind != .file) return;
    const vid = currentVersionId(allocator, path, effective_key);
    if (status == .suspended and std.mem.eql(u8, vid, NULL_VERSION)) return;

    const vdir = try versionsDirPath(ctx, allocator, bucket, effective_key);
    defer allocator.free(vdir);
    try std.Io.Dir.cwd().createDirPath(app_io, vdir);

    const dst = try versionFilePath(allocator, vdir, vid, "");
    defer allocator.free(dst);
    try renameFile(path, dst);
    const src_sidecar = try attrsSidecarPath(allocator, path);
    defer allocator.free(src_sidecar);
    const dst_sidecar = try attrsSidecarPath(allocator, dst);
    defer allocator.free(dst_sidecar);
    renameFile(src_sidecar, dst_sidecar) catch {
        std.Io.Dir.cwd().deleteFile(app_io, dst_sidecar) catch {};
    };
    // A null version supersedes a null delete marker.
    if (std.mem.eql(u8, vid, NULL_VERSION)) {
        const marker = try versionFilePath(allocator, vdir, NULL_VERSION, DELETE_MARKER_SUFFIX);
        defer allocator.free(marker);
        std.Io.Dir.cwd().deleteFile(app_io, marker) catch {};
    }
    fsyncParentDir(dst);
    fsyncParentDir(path);
}

const VersionEntry = struct {
    vid: []const u8,
    is_marker: bool,
    mtime: i64,
    size: u64,
};

/// Stored (non-current) versions of a key, newest first.
fn listStoredVersions(allocator: Allocator, vdir: []const u8) !std.ArrayListUnmanaged(VersionEntry) {
    var out: std.ArrayListUnmanaged(VersionEntry) = .empty;
    errdefer out.deinit(allocator);
    var dir = std.Io.Dir.cwd().openDir(app_io, vdir, .{ .iterate = true }) catch return out;
    defer dir.close(app_io);
    var it = dir.iterate();
    while (try it.next(app_io)) |entry| {
        if (entry.kind != .file) continue;
        if (std.mem.endsWith(u8, entry.name, ".zs3attrs")) continue;
        const is_marker = std.mem.endsWith(u8, entry.name, DELETE_MARKER_SUFFIX);
        const vid = if (is_marker) entry.name[0 .. entry.name.len - DELETE_MARKER_SUFFIX.len] else entry.name;
        if (!isValidVersionId(vid)) continue;
        const stat = dir.statFile(app_io, entry.name, .{}) catch continue;
        try out.append(allocator, .{
            .vid = try allocator.dupe(u8, vid),
            .is_marker = is_marker,
            .mtime = @intCast(stat.mtime.toSeconds()),
            .size = stat.size,
        });
    }
    std.mem.sort(VersionEntry, out.items, {}, struct {
        fn lessThan(_: void, a: VersionEntry, b: VersionEntry) bool {
            if (a.mtime != b.mtime) return a.mtime > b.mtime;
            // Same second: generated ids sort by time; "null" is oldest.
            if (std.mem.eql(u8, a.vid, NULL_VERSION)) return false;
            if (std.mem.eql(u8, b.vid, NULL_VERSION)) return true;
            return std.mem.order(u8, a.vid, b.vid) == .gt;
        }
    }.lessThan);
    return out;
}

/// After the current object is removed, make the newest stored data version
/// current again (unless the newest entry is a delete marker).
fn promoteLatestVersion(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, effective_key: []const u8, path: []const u8) !void {
    const vdir = try versionsDirPath(ctx, allocator, bucket, effective_key);
    defer allocator.free(vdir);
    var versions = try listStoredVersions(allocator, vdir);
    defer versions.deinit(allocator);
    if (versions.items.len == 0) {
        removeEmptyVersionDirs(ctx, allocator, bucket, vdir);
        return;
    }
    const newest = versions.items[0];
    if (newest.is_marker) return;
    const src = try versionFilePath(allocator, vdir, newest.vid, "");
    defer allocator.free(src);
    if (std.fs.path.dirname(path)) |d| std.Io.Dir.cwd().createDirPath(app_io, d) catch {};
    try renameFile(src, path);
    const src_sidecar = try attrsSidecarPath(allocator, src);
    defer allocator.free(src_sidecar);
    const dst_sidecar = try attrsSidecarPath(allocator, path);
    defer allocator.free(dst_sidecar);
    renameFile(src_sidecar, dst_sidecar) catch {
        std.Io.Dir.cwd().deleteFile(app_io, dst_sidecar) catch {};
    };
    fsyncParentDir(path);
    if (versions.items.len == 1) removeEmptyVersionDirs(ctx, allocator, bucket, vdir);
}

/// Remove an empty `<key>.v` directory and empty parents up to .zs3versions.
fn removeEmptyVersionDirs(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, vdir: []const u8) void {
    const root = std.fs.path.join(allocator, &.{ ctx.data_dir, bucket, VERSIONS_DIR }) catch return;
    defer allocator.free(root);
    var cur: ?[]const u8 = vdir;
    while (cur) |d| {
        if (d.len < root.len) break;
        std.Io.Dir.cwd().deleteDir(app_io, d) catch break;
        cur = std.fs.path.dirname(d);
    }
}

fn bucketHasVersions(ctx: *const S3Context, allocator: Allocator, bucket: []const u8) bool {
    const root = std.fs.path.join(allocator, &.{ ctx.data_dir, bucket, VERSIONS_DIR }) catch return false;
    defer allocator.free(root);
    return dirHasAnyFile(allocator, root);
}

fn dirHasAnyFile(allocator: Allocator, path: []const u8) bool {
    var dir = std.Io.Dir.cwd().openDir(app_io, path, .{ .iterate = true }) catch return false;
    defer dir.close(app_io);
    var it = dir.iterate();
    while (it.next(app_io) catch null) |entry| {
        if (entry.kind == .file) return true;
        if (entry.kind == .directory) {
            const sub = std.fs.path.join(allocator, &.{ path, entry.name }) catch continue;
            defer allocator.free(sub);
            if (dirHasAnyFile(allocator, sub)) return true;
        }
    }
    return false;
}

const ResolvedVersion = union(enum) {
    /// Path of the file holding this version (current object or archived).
    path: []const u8,
    delete_marker,
    not_found,
};

/// Locate a specific version of a key.
fn resolveVersion(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, effective_key: []const u8, path: []const u8, vid: []const u8) !ResolvedVersion {
    if (!isValidVersionId(vid)) return .not_found;
    if (std.Io.Dir.cwd().statFile(app_io, path, .{})) |st| {
        if (st.kind == .file and std.mem.eql(u8, currentVersionId(allocator, path, effective_key), vid)) {
            return .{ .path = try allocator.dupe(u8, path) };
        }
    } else |_| {}
    const vdir = try versionsDirPath(ctx, allocator, bucket, effective_key);
    defer allocator.free(vdir);
    const vpath = try versionFilePath(allocator, vdir, vid, "");
    if (std.Io.Dir.cwd().access(app_io, vpath, .{})) |_| return .{ .path = vpath } else |_| {}
    allocator.free(vpath);
    const marker = try versionFilePath(allocator, vdir, vid, DELETE_MARKER_SUFFIX);
    defer allocator.free(marker);
    if (std.Io.Dir.cwd().access(app_io, marker, .{})) |_| return .delete_marker else |_| {}
    return .not_found;
}

/// The delete marker that currently hides a key, if any.
fn latestDeleteMarker(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, effective_key: []const u8) ?[]const u8 {
    const vdir = versionsDirPath(ctx, allocator, bucket, effective_key) catch return null;
    defer allocator.free(vdir);
    var versions = listStoredVersions(allocator, vdir) catch return null;
    defer versions.deinit(allocator);
    if (versions.items.len == 0) return null;
    if (!versions.items[0].is_marker) return null;
    return versions.items[0].vid;
}

const DeleteOutcome = struct {
    delete_marker: bool = false,
    version_id: ?[]const u8 = null,
    not_found: bool = false,
};

/// DELETE semantics for one key: with no version id, remove the current
/// object (unversioned) or add a delete marker (versioned); with a version
/// id, permanently remove that version and promote the next one.
fn deleteObjectVersioned(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, effective_key: []const u8, version_id: ?[]const u8) !DeleteOutcome {
    const path = try ctx.objectPath(allocator, bucket, effective_key);
    defer allocator.free(path);
    const status = bucketVersioning(ctx, allocator, bucket);

    if (version_id) |vid| {
        if (!isValidVersionId(vid)) return .{ .not_found = true };
        const vdir = try versionsDirPath(ctx, allocator, bucket, effective_key);
        defer allocator.free(vdir);
        // Current object?
        if (std.Io.Dir.cwd().statFile(app_io, path, .{})) |st| {
            if (st.kind == .file and std.mem.eql(u8, currentVersionId(allocator, path, effective_key), vid)) {
                deleteObjectInternal(ctx, allocator, bucket, path);
                try promoteLatestVersion(ctx, allocator, bucket, effective_key, path);
                return .{ .version_id = try allocator.dupe(u8, vid) };
            }
        } else |_| {}
        const vpath = try versionFilePath(allocator, vdir, vid, "");
        defer allocator.free(vpath);
        if (std.Io.Dir.cwd().deleteFile(app_io, vpath)) |_| {
            deleteStandaloneAttrs(allocator, vpath);
            removeEmptyVersionDirs(ctx, allocator, bucket, vdir);
            return .{ .version_id = try allocator.dupe(u8, vid) };
        } else |_| {}
        const marker = try versionFilePath(allocator, vdir, vid, DELETE_MARKER_SUFFIX);
        defer allocator.free(marker);
        if (std.Io.Dir.cwd().deleteFile(app_io, marker)) |_| {
            // Removing the marker that hid the key brings the newest
            // remaining version back.
            if (std.Io.Dir.cwd().access(app_io, path, .{})) |_| {} else |_| {
                try promoteLatestVersion(ctx, allocator, bucket, effective_key, path);
            }
            removeEmptyVersionDirs(ctx, allocator, bucket, vdir);
            return .{ .version_id = try allocator.dupe(u8, vid), .delete_marker = true };
        } else |_| {}
        return .{ .not_found = true };
    }

    switch (status) {
        .disabled => {
            deleteObjectInternal(ctx, allocator, bucket, path);
            return .{};
        },
        .enabled => {
            try archiveCurrentVersion(ctx, allocator, bucket, effective_key, path, status);
            const vdir = try versionsDirPath(ctx, allocator, bucket, effective_key);
            defer allocator.free(vdir);
            try std.Io.Dir.cwd().createDirPath(app_io, vdir);
            const vid = try newVersionId(allocator);
            const marker = try versionFilePath(allocator, vdir, vid, DELETE_MARKER_SUFFIX);
            defer allocator.free(marker);
            var f = try std.Io.Dir.cwd().createFile(app_io, marker, .{});
            f.close(app_io);
            fsyncParentDir(marker);
            cleanupEmptyObjectDirs(ctx, allocator, bucket, path);
            return .{ .version_id = vid, .delete_marker = true };
        },
        .suspended => {
            // Non-null current versions are kept; the null version (and any
            // stored null version) is replaced by a null delete marker.
            try archiveCurrentVersion(ctx, allocator, bucket, effective_key, path, status);
            deleteObjectInternal(ctx, allocator, bucket, path);
            const vdir = try versionsDirPath(ctx, allocator, bucket, effective_key);
            defer allocator.free(vdir);
            try std.Io.Dir.cwd().createDirPath(app_io, vdir);
            const null_data = try versionFilePath(allocator, vdir, NULL_VERSION, "");
            defer allocator.free(null_data);
            std.Io.Dir.cwd().deleteFile(app_io, null_data) catch {};
            deleteStandaloneAttrs(allocator, null_data);
            const marker = try versionFilePath(allocator, vdir, NULL_VERSION, DELETE_MARKER_SUFFIX);
            defer allocator.free(marker);
            var f = try std.Io.Dir.cwd().createFile(app_io, marker, .{});
            f.close(app_io);
            fsyncParentDir(marker);
            return .{ .version_id = try allocator.dupe(u8, NULL_VERSION), .delete_marker = true };
        },
    }
}

/// Remove empty parent directories of a (now absent) object path, up to the
/// bucket root. Same walk deleteObjectInternal does after unlinking.
fn cleanupEmptyObjectDirs(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, path: []const u8) void {
    const bucket_path = ctx.bucketPath(allocator, bucket) catch return;
    defer allocator.free(bucket_path);
    var dir_path = std.fs.path.dirname(path);
    while (dir_path) |dp| {
        if (dp.len <= bucket_path.len) break;
        std.Io.Dir.cwd().deleteDir(app_io, dp) catch break;
        dir_path = std.fs.path.dirname(dp);
    }
}

// --- ListObjectVersions -----------------------------------------------------

const ListedVersion = struct {
    key: []const u8, // S3 key (folder markers translated)
    vid: []const u8,
    is_marker: bool,
    is_current: bool,
    mtime: i64,
    size: u64,
    path: ?[]const u8, // data file, for ETag
};

fn listedVersionLess(_: void, a: ListedVersion, b: ListedVersion) bool {
    const ko = std.mem.order(u8, a.key, b.key);
    if (ko != .eq) return ko == .lt;
    if (a.is_current != b.is_current) return a.is_current;
    if (a.mtime != b.mtime) return a.mtime > b.mtime;
    if (std.mem.eql(u8, a.vid, NULL_VERSION)) return false;
    if (std.mem.eql(u8, b.vid, NULL_VERSION)) return true;
    return std.mem.order(u8, a.vid, b.vid) == .gt;
}

/// Translate an effective (on-disk) key back to its S3 key.
fn displayKey(allocator: Allocator, effective_key: []const u8) ![]const u8 {
    if (std.mem.endsWith(u8, effective_key, ".folder_marker")) {
        return allocator.dupe(u8, effective_key[0 .. effective_key.len - ".folder_marker".len]);
    }
    return allocator.dupe(u8, effective_key);
}

fn collectStoredVersions(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, rel: []const u8, filter_prefix: []const u8, out: *std.ArrayListUnmanaged(ListedVersion)) !void {
    const root = try std.fs.path.join(allocator, &.{ ctx.data_dir, bucket, VERSIONS_DIR });
    defer allocator.free(root);
    const full = if (rel.len > 0) try std.fs.path.join(allocator, &.{ root, rel }) else try allocator.dupe(u8, root);
    defer allocator.free(full);
    var dir = std.Io.Dir.cwd().openDir(app_io, full, .{ .iterate = true }) catch return;
    defer dir.close(app_io);
    var it = dir.iterate();
    while (try it.next(app_io)) |entry| {
        if (entry.kind != .directory) continue;
        const sub_rel = if (rel.len > 0) try std.fmt.allocPrint(allocator, "{s}/{s}", .{ rel, entry.name }) else try allocator.dupe(u8, entry.name);
        if (std.mem.endsWith(u8, entry.name, VERSION_DIR_SUFFIX)) {
            const effective_key = sub_rel[0 .. sub_rel.len - VERSION_DIR_SUFFIX.len];
            const key = try displayKey(allocator, effective_key);
            if (filter_prefix.len > 0 and !std.mem.startsWith(u8, key, filter_prefix)) continue;
            const vdir = try std.fs.path.join(allocator, &.{ root, sub_rel });
            var versions = try listStoredVersions(allocator, vdir);
            defer versions.deinit(allocator);
            for (versions.items) |v| {
                try out.append(allocator, .{
                    .key = key,
                    .vid = v.vid,
                    .is_marker = v.is_marker,
                    .is_current = false,
                    .mtime = v.mtime,
                    .size = v.size,
                    .path = if (v.is_marker) null else try versionFilePath(allocator, vdir, v.vid, ""),
                });
            }
        } else {
            try collectStoredVersions(ctx, allocator, bucket, sub_rel, filter_prefix, out);
        }
    }
}

/// ETag and logical size for a stored file (decrypting metadata for SSE).
fn fileEtagAndSize(allocator: Allocator, path: []const u8, key: []const u8, raw_size: u64) struct { etag: []const u8, size: u64 } {
    if (loadStandaloneAttrs(allocator, path, key)) |attrs| {
        if (attrs.sse != null) {
            // Size on disk, not the caller's (possibly already logical) size.
            const st = std.Io.Dir.cwd().statFile(app_io, path, .{}) catch return .{ .etag = attrs.etag orelse "\"\"", .size = 0 };
            return .{ .etag = attrs.etag orelse "\"\"", .size = ssePlaintextSize(st.size) };
        }
    } else |_| {}
    var file = std.Io.Dir.cwd().openFile(app_io, path, .{}) catch return .{ .etag = "\"\"", .size = raw_size };
    defer file.close(app_io);
    const content = readToEndAlloc(file, allocator, MAX_BODY_SIZE) catch return .{ .etag = "\"\"", .size = raw_size };
    defer allocator.free(content);
    return .{ .etag = md5Etag(allocator, content) catch "\"\"", .size = raw_size };
}

/// GET /{bucket}?versions
fn handleListObjectVersions(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8) !void {
    const prefix = try uriDecode(allocator, getQueryParam(req.query, "prefix") orelse "");
    const max_keys = std.fmt.parseInt(usize, getQueryParam(req.query, "max-keys") orelse "1000", 10) catch 1000;
    const delimiter_decoded = if (getQueryParam(req.query, "delimiter")) |d| try uriDecode(allocator, d) else null;
    const delimiter: ?[]const u8 = if (delimiter_decoded) |d| (if (d.len > 0) d else null) else null;
    const key_marker = if (getQueryParam(req.query, "key-marker")) |k| try uriDecode(allocator, k) else "";
    const vid_marker = if (getQueryParam(req.query, "version-id-marker")) |v| try uriDecode(allocator, v) else "";

    const bucket_path = try ctx.bucketPath(allocator, bucket);
    defer allocator.free(bucket_path);
    if (!bucketExists(ctx, allocator, bucket)) {
        sendError(res, 404, "NoSuchBucket", "Bucket not found");
        return;
    }

    var entries: std.ArrayListUnmanaged(ListedVersion) = .empty;
    defer entries.deinit(allocator);

    // Current objects.
    var keys: std.ArrayListUnmanaged(KeyInfo) = .empty;
    defer keys.deinit(allocator);
    try collectKeys(allocator, bucket_path, "", prefix, &keys, bucketSseUsed(ctx, allocator, bucket));
    for (keys.items) |k| {
        const effective_key = if (k.key.len > 0 and k.key[k.key.len - 1] == '/')
            try std.fmt.allocPrint(allocator, "{s}.folder_marker", .{k.key})
        else
            k.key;
        const path = try ctx.objectPath(allocator, bucket, effective_key);
        try entries.append(allocator, .{
            .key = k.key,
            .vid = currentVersionId(allocator, path, effective_key),
            .is_marker = false,
            .is_current = true,
            .mtime = k.mtime,
            .size = k.size,
            .path = path,
        });
    }
    // Stored versions and delete markers.
    try collectStoredVersions(ctx, allocator, bucket, "", prefix, &entries);

    std.mem.sort(ListedVersion, entries.items, {}, listedVersionLess);

    var xml: std.ArrayListUnmanaged(u8) = .empty;
    defer xml.deinit(allocator);
    try xml.appendSlice(allocator, "<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
    try xml.appendSlice(allocator, "<ListVersionsResult xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\"><Name>");
    try xmlEscape(allocator, &xml, bucket);
    try xml.appendSlice(allocator, "</Name><Prefix>");
    try xmlEscape(allocator, &xml, prefix);
    try xml.appendSlice(allocator, "</Prefix><KeyMarker>");
    try xmlEscape(allocator, &xml, key_marker);
    try xml.appendSlice(allocator, "</KeyMarker><VersionIdMarker>");
    try xmlEscape(allocator, &xml, vid_marker);
    try xml.appendSlice(allocator, "</VersionIdMarker><MaxKeys>");
    var mk_buf: [32]u8 = undefined;
    try xml.appendSlice(allocator, std.fmt.bufPrint(&mk_buf, "{d}", .{max_keys}) catch "1000");
    try xml.appendSlice(allocator, "</MaxKeys>");
    if (delimiter) |d| {
        try xml.appendSlice(allocator, "<Delimiter>");
        try xmlEscape(allocator, &xml, d);
        try xml.appendSlice(allocator, "</Delimiter>");
    }

    var body: std.ArrayListUnmanaged(u8) = .empty;
    defer body.deinit(allocator);
    var common_prefixes = std.StringHashMap(void).init(allocator);
    defer common_prefixes.deinit();

    var count: usize = 0;
    var truncated = false;
    var next_key: []const u8 = "";
    var next_vid: []const u8 = "";
    var prev_key: []const u8 = "";
    var passed_vid_marker = false;
    for (entries.items) |e| {
        // Pagination: resume strictly after (key-marker, version-id-marker).
        if (key_marker.len > 0) {
            const ko = std.mem.order(u8, e.key, key_marker);
            if (ko == .lt) continue;
            if (ko == .eq) {
                if (vid_marker.len == 0) continue;
                if (!passed_vid_marker) {
                    if (std.mem.eql(u8, e.vid, vid_marker)) passed_vid_marker = true;
                    continue;
                }
            }
        }
        if (count >= max_keys) {
            truncated = true;
            break;
        }
        if (delimiter) |delim| {
            const after_prefix = if (prefix.len > 0 and std.mem.startsWith(u8, e.key, prefix)) e.key[prefix.len..] else e.key;
            if (std.mem.indexOf(u8, after_prefix, delim)) |idx| {
                const cp = e.key[0 .. prefix.len + idx + delim.len];
                if (!common_prefixes.contains(cp)) {
                    try common_prefixes.put(cp, {});
                    try body.appendSlice(allocator, "<CommonPrefixes><Prefix>");
                    try xmlEscape(allocator, &body, cp);
                    try body.appendSlice(allocator, "</Prefix></CommonPrefixes>");
                    count += 1;
                    next_key = e.key;
                    next_vid = e.vid;
                }
                continue;
            }
        }
        const is_latest = !std.mem.eql(u8, e.key, prev_key);
        prev_key = e.key;
        var iso: [20]u8 = undefined;
        formatIso8601(&iso, e.mtime);
        if (e.is_marker) {
            try body.appendSlice(allocator, "<DeleteMarker><Key>");
            try xmlEscape(allocator, &body, e.key);
            try body.appendSlice(allocator, "</Key><VersionId>");
            try body.appendSlice(allocator, e.vid);
            try body.appendSlice(allocator, if (is_latest) "</VersionId><IsLatest>true</IsLatest><LastModified>" else "</VersionId><IsLatest>false</IsLatest><LastModified>");
            try body.appendSlice(allocator, &iso);
            try body.appendSlice(allocator, "</LastModified><Owner><ID>" ++ OWNER_ID ++ "</ID><DisplayName>" ++ OWNER_ID ++ "</DisplayName></Owner></DeleteMarker>");
        } else {
            const es = fileEtagAndSize(allocator, e.path.?, e.key, e.size);
            try body.appendSlice(allocator, "<Version><Key>");
            try xmlEscape(allocator, &body, e.key);
            try body.appendSlice(allocator, "</Key><VersionId>");
            try body.appendSlice(allocator, e.vid);
            try body.appendSlice(allocator, if (is_latest) "</VersionId><IsLatest>true</IsLatest><LastModified>" else "</VersionId><IsLatest>false</IsLatest><LastModified>");
            try body.appendSlice(allocator, &iso);
            try body.appendSlice(allocator, "</LastModified><ETag>");
            try xmlEscape(allocator, &body, es.etag);
            try body.appendSlice(allocator, "</ETag><Size>");
            var size_buf: [32]u8 = undefined;
            try body.appendSlice(allocator, std.fmt.bufPrint(&size_buf, "{d}", .{es.size}) catch "0");
            try body.appendSlice(allocator, "</Size><Owner><ID>" ++ OWNER_ID ++ "</ID><DisplayName>" ++ OWNER_ID ++ "</DisplayName></Owner><StorageClass>STANDARD</StorageClass></Version>");
        }
        count += 1;
        next_key = e.key;
        next_vid = e.vid;
    }

    if (truncated) {
        try xml.appendSlice(allocator, "<IsTruncated>true</IsTruncated><NextKeyMarker>");
        try xmlEscape(allocator, &xml, next_key);
        try xml.appendSlice(allocator, "</NextKeyMarker><NextVersionIdMarker>");
        try xmlEscape(allocator, &xml, next_vid);
        try xml.appendSlice(allocator, "</NextVersionIdMarker>");
    } else {
        try xml.appendSlice(allocator, "<IsTruncated>false</IsTruncated>");
    }
    try xml.appendSlice(allocator, body.items);
    try xml.appendSlice(allocator, "</ListVersionsResult>");
    res.ok();
    res.setXmlBody(try xml.toOwnedSlice(allocator));
}

/// Plaintext size of an SSE file given its on-disk size (defined with the
/// encryption format below).
fn ssePlaintextSize(raw_size: u64) u64 {
    return sseLogicalSize(raw_size);
}

// ---------------------------------------------------------------------------
// Version helpers used by GET / HEAD
// ---------------------------------------------------------------------------

/// Map ?versionId= to the file to serve. Sends the error response and returns
/// null when the version is missing or is a delete marker.
fn resolveRequestedVersion(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, effective_key: []const u8, current_path: []const u8) !?[]const u8 {
    const vid_raw = getQueryParam(req.query, "versionId") orelse return current_path;
    const vid = try uriDecode(allocator, vid_raw);
    if (ctx.distributed != null) {
        if (std.mem.eql(u8, vid, NULL_VERSION)) return current_path;
        sendError(res, 404, "NoSuchVersion", "The specified version does not exist");
        return null;
    }
    switch (try resolveVersion(ctx, allocator, bucket, effective_key, current_path, vid)) {
        .path => |p| {
            res.setHeader("x-amz-version-id", vid);
            return p;
        },
        .delete_marker => {
            res.setHeader("x-amz-delete-marker", "true");
            res.setHeader("x-amz-version-id", vid);
            sendError(res, 405, "MethodNotAllowed", "The specified version is a delete marker");
            return null;
        },
        .not_found => {
            sendError(res, 404, "NoSuchVersion", "The specified version does not exist");
            return null;
        },
    }
}

/// 404 for a missing current object, flagging a delete marker when one hides
/// the key.
fn sendMissingObject(ctx: *const S3Context, allocator: Allocator, res: *Response, bucket: []const u8, effective_key: []const u8) void {
    if (ctx.distributed == null) {
        if (latestDeleteMarker(ctx, allocator, bucket, effective_key)) |vid| {
            res.setHeader("x-amz-delete-marker", "true");
            res.setHeader("x-amz-version-id", vid);
        }
    }
    sendError(res, 404, "NoSuchKey", "Object not found");
}

/// On a versioned bucket every object has a version id; those written before
/// versioning report "null" (applySystemAttrHeaders covers the rest).
fn addNullVersionHeader(ctx: *const S3Context, allocator: Allocator, res: *Response, bucket: []const u8, attrs: *const ObjectAttrs) void {
    if (attrs.version_id != null) return;
    for (res.headers.items) |h| {
        if (std.mem.eql(u8, h.name, "x-amz-version-id")) return;
    }
    if (bucketVersioning(ctx, allocator, bucket) != .disabled) res.setHeader("x-amz-version-id", NULL_VERSION);
}

// ============================================================================
// SERVER-SIDE ENCRYPTION (SSE-S3 and SSE-C)
// ============================================================================
// Encrypted objects are stored as a small header followed by 64KB AES-256-GCM
// chunks (each with its own 16-byte tag), so ranges decrypt without reading
// the whole file and a flipped byte anywhere fails authentication:
//
//   "ZS3E" | version=1 | mode (1=SSE-S3, 2=SSE-C) | 2 reserved |
//   chunk size (u32 LE) | 32-byte salt | 8-byte nonce base
//   chunk i: AES-256-GCM(plain[i]) || tag, nonce = base || i (u32 LE), AAD = header
//
// Per-object keys are HKDF-SHA256(master or customer key, salt). SSE-S3 uses
// a server master key from --sse-key-file / ZS3_SSE_KEY, or one generated
// into <data-dir>/.zs3/sse.key on first use. SSE-C keys are never stored;
// only their MD5 is kept so the right key can be recognised.
//
// The ETag stays the MD5 of the plaintext and is stored in the sidecar.

const SSE_MAGIC = "ZS3E";
const SSE_VERSION: u8 = 1;
pub const SSE_HEADER_LEN: usize = 52;
pub const SSE_CHUNK: usize = 64 * 1024;
const SSE_TAG: usize = 16;
const SSE_HKDF_INFO = "zs3-sse-v1";

const Aes256Gcm = std.crypto.aead.aes_gcm.Aes256Gcm;
const HkdfSha256 = std.crypto.kdf.hkdf.HkdfSha256;

pub const SseMode = union(enum) {
    s3,
    customer: struct { key: [32]u8, key_md5_b64: []const u8 },

    fn modeByte(self: SseMode) u8 {
        return switch (self) {
            .s3 => 1,
            .customer => 2,
        };
    }
};

var sse_master_key: ?[32]u8 = null;
var sse_key_file_opt: []const u8 = "";

/// Plaintext length encoded by an SSE file of `raw` bytes.
pub fn sseLogicalSize(raw: u64) u64 {
    if (raw < SSE_HEADER_LEN) return 0;
    const c = raw - SSE_HEADER_LEN;
    const per = @as(u64, SSE_CHUNK + SSE_TAG);
    const n = (c + per - 1) / per;
    if (c < n * SSE_TAG) return 0;
    return c - n * SSE_TAG;
}

fn hexDecode32(text: []const u8) ?[32]u8 {
    const t = std.mem.trim(u8, text, " \t\r\n");
    if (t.len != 64) return null;
    var out: [32]u8 = undefined;
    _ = std.fmt.hexToBytes(&out, t) catch return null;
    return out;
}

/// Load (or create) the SSE-S3 master key.
fn sseMasterKey(ctx: *const S3Context) ![32]u8 {
    if (sse_master_key) |k| return k;
    if (getenvStr("ZS3_SSE_KEY")) |hex| {
        sse_master_key = hexDecode32(hex) orelse {
            std.log.err("ZS3_SSE_KEY must be 64 hex characters (32 bytes)", .{});
            return error.BadSseKey;
        };
        return sse_master_key.?;
    }
    var path_buf: [std.posix.PATH_MAX]u8 = undefined;
    const path = if (sse_key_file_opt.len > 0)
        sse_key_file_opt
    else
        try std.fmt.bufPrint(&path_buf, "{s}/.zs3/sse.key", .{ctx.data_dir});
    if (std.Io.Dir.cwd().openFile(app_io, path, .{})) |file| {
        defer file.close(app_io);
        var buf: [256]u8 = undefined;
        const n = file.readPositionalAll(app_io, &buf, 0) catch 0;
        sse_master_key = hexDecode32(buf[0..n]) orelse {
            std.log.err("SSE key file {s} must contain 64 hex characters", .{path});
            return error.BadSseKey;
        };
        return sse_master_key.?;
    } else |_| {}
    if (sse_key_file_opt.len > 0) {
        std.log.err("SSE key file {s} not found", .{path});
        return error.BadSseKey;
    }
    // Generate one. Losing this file makes every SSE-S3 object unreadable.
    var key: [32]u8 = undefined;
    try app_io.randomSecure(&key);
    var hex: [64]u8 = undefined;
    _ = std.fmt.bufPrint(&hex, "{x}", .{key}) catch unreachable;
    if (std.fs.path.dirname(path)) |d| std.Io.Dir.cwd().createDirPath(app_io, d) catch {};
    var af = try std.Io.Dir.cwd().createFileAtomic(app_io, path, .{ .make_path = true, .replace = true, .permissions = .fromMode(0o600) });
    defer af.deinit(app_io);
    try af.file.writeStreamingAll(app_io, &hex);
    fsyncFile(af.file);
    try af.replace(app_io);
    std.log.warn("generated SSE-S3 master key at {s}; back it up, encrypted objects cannot be read without it", .{path});
    sse_master_key = key;
    return key;
}

fn sseDeriveKey(ikm: *const [32]u8, salt: *const [32]u8) [32]u8 {
    const prk = HkdfSha256.extract(salt, ikm);
    var out: [32]u8 = undefined;
    HkdfSha256.expand(&out, SSE_HKDF_INFO, prk);
    return out;
}

fn sseNonce(base: *const [8]u8, index: u32) [12]u8 {
    var n: [12]u8 = undefined;
    @memcpy(n[0..8], base);
    std.mem.writeInt(u32, n[8..12], index, .little);
    return n;
}

/// Incremental encryptor: feed plaintext, drain ciphertext from `out`.
const SseEncryptor = struct {
    key: [32]u8,
    header: [SSE_HEADER_LEN]u8,
    base: [8]u8,
    index: u32 = 0,
    pending: std.ArrayListUnmanaged(u8) = .empty,
    out: std.ArrayListUnmanaged(u8) = .empty,

    fn init(allocator: Allocator, ikm: *const [32]u8, mode: SseMode) !SseEncryptor {
        var salt: [32]u8 = undefined;
        try app_io.randomSecure(&salt);
        var base: [8]u8 = undefined;
        try app_io.randomSecure(&base);
        var header: [SSE_HEADER_LEN]u8 = undefined;
        @memcpy(header[0..4], SSE_MAGIC);
        header[4] = SSE_VERSION;
        header[5] = mode.modeByte();
        header[6] = 0;
        header[7] = 0;
        std.mem.writeInt(u32, header[8..12], @intCast(SSE_CHUNK), .little);
        @memcpy(header[12..44], &salt);
        @memcpy(header[44..52], &base);
        var e = SseEncryptor{ .key = sseDeriveKey(ikm, &salt), .header = header, .base = base };
        try e.out.appendSlice(allocator, &header);
        return e;
    }

    fn deinit(self: *SseEncryptor, allocator: Allocator) void {
        self.pending.deinit(allocator);
        self.out.deinit(allocator);
        std.crypto.secureZero(u8, &self.key);
    }

    fn emitChunk(self: *SseEncryptor, allocator: Allocator, plain: []const u8) !void {
        const start = self.out.items.len;
        try self.out.resize(allocator, start + plain.len + SSE_TAG);
        const c = self.out.items[start .. start + plain.len];
        const tag = self.out.items[start + plain.len ..][0..SSE_TAG];
        Aes256Gcm.encrypt(c, tag, plain, &self.header, sseNonce(&self.base, self.index), self.key);
        self.index += 1;
    }

    fn update(self: *SseEncryptor, allocator: Allocator, data: []const u8) !void {
        var rest = data;
        if (self.pending.items.len > 0) {
            const need = SSE_CHUNK - self.pending.items.len;
            const take = @min(need, rest.len);
            try self.pending.appendSlice(allocator, rest[0..take]);
            rest = rest[take..];
            if (self.pending.items.len == SSE_CHUNK) {
                try self.emitChunk(allocator, self.pending.items);
                self.pending.clearRetainingCapacity();
            }
        }
        while (rest.len >= SSE_CHUNK) {
            try self.emitChunk(allocator, rest[0..SSE_CHUNK]);
            rest = rest[SSE_CHUNK..];
        }
        if (rest.len > 0) try self.pending.appendSlice(allocator, rest);
    }

    fn finish(self: *SseEncryptor, allocator: Allocator) !void {
        if (self.pending.items.len > 0) {
            try self.emitChunk(allocator, self.pending.items);
            self.pending.clearRetainingCapacity();
        }
    }
};

fn sseIkm(ctx: *const S3Context, mode: SseMode) ![32]u8 {
    return switch (mode) {
        .s3 => try sseMasterKey(ctx),
        .customer => |c| c.key,
    };
}

pub fn sseEncryptWith(allocator: Allocator, ikm: *const [32]u8, plaintext: []const u8, mode: SseMode) ![]u8 {
    var enc = try SseEncryptor.init(allocator, ikm, mode);
    defer enc.deinit(allocator);
    try enc.update(allocator, plaintext);
    try enc.finish(allocator);
    return allocator.dupe(u8, enc.out.items);
}

/// Encrypt a whole object for storage (PUT / CopyObject).
fn sseEncrypt(allocator: Allocator, plaintext: []const u8, mode: SseMode) ![]u8 {
    const ikm = try sseIkm(sse_ctx.?, mode);
    return sseEncryptWith(allocator, &ikm, plaintext, mode);
}

/// Decrypt a stored SSE file with the given key material.
pub fn sseDecrypt(allocator: Allocator, data: []const u8, ikm: *const [32]u8) ![]u8 {
    if (data.len < SSE_HEADER_LEN or !std.mem.eql(u8, data[0..4], SSE_MAGIC) or data[4] != SSE_VERSION) return error.BadCiphertext;
    const header = data[0..SSE_HEADER_LEN];
    const chunk_size: usize = std.mem.readInt(u32, header[8..12], .little);
    if (chunk_size == 0 or chunk_size > 16 * 1024 * 1024) return error.BadCiphertext;
    const salt = header[12..44];
    const base = header[44..52];
    var key = sseDeriveKey(ikm, salt);
    defer std.crypto.secureZero(u8, &key);
    var out: std.ArrayListUnmanaged(u8) = .empty;
    errdefer out.deinit(allocator);
    var rest = data[SSE_HEADER_LEN..];
    var index: u32 = 0;
    while (rest.len > 0) : (index += 1) {
        if (rest.len < SSE_TAG) return error.BadCiphertext;
        const clen = @min(rest.len - SSE_TAG, chunk_size);
        const c = rest[0..clen];
        const tag = rest[clen..][0..SSE_TAG].*;
        const start = out.items.len;
        try out.resize(allocator, start + clen);
        Aes256Gcm.decrypt(out.items[start..], c, tag, header, sseNonce(base, index), key) catch return error.AuthenticationFailed;
        rest = rest[clen + SSE_TAG ..];
    }
    return out.toOwnedSlice(allocator);
}

/// Handlers run with a single S3Context; keep a pointer for key lookup from
/// helpers that do not receive it.
var sse_ctx: ?*const S3Context = null;

fn sseErrorResponse(res: *Response, err: anyerror) void {
    switch (err) {
        error.SseKeyRequired => sendError(res, 400, "InvalidRequest", "The object was stored using a form of Server Side Encryption. The correct parameters must be provided to retrieve the object."),
        error.SseKeyMismatch, error.AuthenticationFailed => sendError(res, 403, "AccessDenied", "The provided encryption key does not match the key used to encrypt the object"),
        error.SseKeyNotExpected => sendError(res, 400, "InvalidRequest", "The encryption parameters are not applicable to this object"),
        error.BadSseKey => sendError(res, 500, "InternalError", "Server-side encryption key unavailable"),
        error.BadCiphertext => sendError(res, 500, "InternalError", "Stored object is not valid ciphertext"),
        else => sendError(res, 500, "InternalError", "Decryption failed"),
    }
}

fn md5Base64(allocator: Allocator, data: []const u8) ![]const u8 {
    var digest: [16]u8 = undefined;
    std.crypto.hash.Md5.hash(data, &digest, .{});
    const out = try allocator.alloc(u8, std.base64.standard.Encoder.calcSize(16));
    _ = std.base64.standard.Encoder.encode(out, &digest);
    return out;
}

/// Parse SSE-C headers (`x-amz-[copy-source-]server-side-encryption-customer-*`).
/// Returns null when none are present; validates algorithm and key MD5.
fn sseCustomerKeyFromHeaders(allocator: Allocator, req: *const Request, copy_source: bool) !?SseMode {
    const pfx = if (copy_source) "x-amz-copy-source-server-side-encryption-customer-" else "x-amz-server-side-encryption-customer-";
    var name_buf: [96]u8 = undefined;
    const alg_name = try std.fmt.bufPrint(&name_buf, "{s}algorithm", .{pfx});
    const alg = req.header(alg_name) orelse return null;
    if (!std.ascii.eqlIgnoreCase(alg, "AES256")) return error.SseBadAlgorithm;
    var key_name_buf: [96]u8 = undefined;
    const key_name = try std.fmt.bufPrint(&key_name_buf, "{s}key", .{pfx});
    const key_b64 = req.header(key_name) orelse return error.SseBadKey;
    var key: [32]u8 = undefined;
    const dec_len = std.base64.standard.Decoder.calcSizeForSlice(key_b64) catch return error.SseBadKey;
    if (dec_len != 32) return error.SseBadKey;
    std.base64.standard.Decoder.decode(&key, key_b64) catch return error.SseBadKey;
    const computed = try md5Base64(allocator, &key);
    var md5_name_buf: [96]u8 = undefined;
    const md5_name = try std.fmt.bufPrint(&md5_name_buf, "{s}key-md5", .{pfx});
    if (req.header(md5_name)) |given| {
        if (!std.mem.eql(u8, std.mem.trim(u8, given, " "), computed)) return error.SseBadKeyMd5;
    }
    return .{ .customer = .{ .key = key, .key_md5_b64 = computed } };
}

fn sendSseHeaderError(res: *Response, err: anyerror) void {
    switch (err) {
        error.SseBadAlgorithm => sendError(res, 400, "InvalidArgument", "The encryption algorithm specified is not valid; only AES256 is supported"),
        error.SseBadKey => sendError(res, 400, "InvalidArgument", "The secret key was invalid for the specified algorithm (expected 256 bits, base64)"),
        error.SseBadKeyMd5 => sendError(res, 400, "InvalidDigest", "The calculated MD5 hash of the key did not match the hash that was provided"),
        error.SseKmsUnsupported => sendError(res, 501, "NotImplemented", "aws:kms encryption is not supported; use AES256"),
        else => sendError(res, 400, "InvalidArgument", "Invalid server-side encryption request"),
    }
}

/// Decide how a new object is stored: SSE-C headers, then
/// x-amz-server-side-encryption, then the bucket's default encryption.
/// Sends the error response and returns error.Handled on bad input.
fn resolveSseForWrite(ctx: *const S3Context, allocator: Allocator, req: *const Request, res: *Response, bucket: []const u8) !?SseMode {
    if (sseCustomerKeyFromHeaders(allocator, req, false)) |maybe| {
        if (maybe) |m| return m;
    } else |err| {
        sendSseHeaderError(res, err);
        return error.Handled;
    }
    if (req.header("x-amz-server-side-encryption")) |alg| {
        if (std.ascii.eqlIgnoreCase(alg, "AES256")) return .s3;
        if (std.ascii.eqlIgnoreCase(alg, "aws:kms") or std.ascii.eqlIgnoreCase(alg, "aws:kms:dsse")) {
            sendSseHeaderError(res, error.SseKmsUnsupported);
            return error.Handled;
        }
        sendSseHeaderError(res, error.SseBadAlgorithm);
        return error.Handled;
    }
    if (ctx.distributed != null) return null;
    if (bucketDefaultEncryption(ctx, allocator, bucket)) return .s3;
    return null;
}

/// Whether any object in the bucket was ever stored encrypted. LIST only
/// pays for sidecar reads in such buckets.
fn bucketSseUsed(ctx: *const S3Context, allocator: Allocator, bucket: []const u8) bool {
    const path = bucketConfigPath(ctx, allocator, bucket, "sse-used") catch return false;
    defer allocator.free(path);
    std.Io.Dir.cwd().access(app_io, path, .{}) catch return false;
    return true;
}

fn noteBucketSseUsed(ctx: *const S3Context, allocator: Allocator, bucket: []const u8) void {
    if (bucketSseUsed(ctx, allocator, bucket)) return;
    writeBucketConfig(ctx, allocator, bucket, "sse-used", "1") catch {};
}

/// Whether the bucket's default encryption configuration asks for SSE-S3.
fn bucketDefaultEncryption(ctx: *const S3Context, allocator: Allocator, bucket: []const u8) bool {
    const stored = readBucketConfig(ctx, allocator, bucket, "encryption.xml") orelse return false;
    defer allocator.free(stored);
    const alg = xmlTagText(stored, "SSEAlgorithm") orelse return false;
    return std.mem.eql(u8, alg, "AES256");
}

fn applySseToAttrs(allocator: Allocator, attrs: *ObjectAttrs, mode: SseMode, plaintext: []const u8) !void {
    if (attrs.sse) |v| allocator.free(v);
    if (attrs.sse_key_md5) |v| allocator.free(v);
    if (attrs.etag) |v| allocator.free(v);
    attrs.sse_key_md5 = null;
    switch (mode) {
        .s3 => attrs.sse = try allocator.dupe(u8, "AES256"),
        .customer => |c| {
            attrs.sse = try allocator.dupe(u8, "SSE-C");
            attrs.sse_key_md5 = try allocator.dupe(u8, c.key_md5_b64);
        },
    }
    attrs.etag = try md5Etag(allocator, plaintext);
}

/// Echo SSE state on write responses (PUT / CopyObject / CompleteMultipart).
fn applySseResponseHeaders(res: *Response, attrs: *const ObjectAttrs, allocator: Allocator) void {
    const mode = attrs.sse orelse return;
    if (std.mem.eql(u8, mode, "SSE-C")) {
        res.setHeader("x-amz-server-side-encryption-customer-algorithm", "AES256");
        if (attrs.sse_key_md5) |m| res.setHeader("x-amz-server-side-encryption-customer-key-MD5", allocator.dupe(u8, m) catch return);
    } else {
        res.setHeader("x-amz-server-side-encryption", "AES256");
    }
}

/// Read an object's plaintext from `path`, decrypting SSE objects. For SSE-C
/// the key must come from the request (copy-source headers when
/// `copy_source`).
fn readObjectPlaintext(allocator: Allocator, req: *const Request, path: []const u8, key: []const u8, copy_source: bool) ![]u8 {
    var file = try std.Io.Dir.cwd().openFile(app_io, path, .{});
    defer file.close(app_io);
    const raw = try readToEndAlloc(file, allocator, MAX_BODY_SIZE);
    const attrs = loadStandaloneAttrs(allocator, path, key) catch return raw;
    defer attrs.deinit(allocator);
    const mode = attrs.sse orelse return raw;
    defer allocator.free(raw);
    if (std.mem.eql(u8, mode, "SSE-C")) {
        const provided = sseCustomerKeyFromHeaders(allocator, req, copy_source) catch return error.SseKeyMismatch;
        const m = provided orelse return error.SseKeyRequired;
        if (attrs.sse_key_md5) |expected| {
            if (!std.mem.eql(u8, expected, m.customer.key_md5_b64)) return error.SseKeyMismatch;
        }
        return sseDecrypt(allocator, raw, &m.customer.key);
    }
    const master = try sseMasterKey(sse_ctx.?);
    return sseDecrypt(allocator, raw, &master);
}

fn sendCopySourceReadError(res: *Response, err: anyerror) void {
    switch (err) {
        error.FileNotFound => sendError(res, 404, "NoSuchKey", "Copy source not found"),
        else => sseErrorResponse(res, err),
    }
}

/// GET/HEAD path for encrypted objects: decrypt in memory and serve (ranges
/// and conditional headers included). Returns false for plain objects.
fn serveEncryptedIfNeeded(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8, effective_key: []const u8, path: []const u8, head_only: bool) !bool {
    if (ctx.distributed != null) return false;
    const attrs = loadStandaloneAttrs(allocator, path, effective_key) catch return false;
    if (attrs.sse == null) {
        // A key was offered for a plain object: S3 rejects that.
        if (req.header("x-amz-server-side-encryption-customer-algorithm") != null) {
            sseErrorResponse(res, error.SseKeyNotExpected);
            return true;
        }
        return false;
    }
    const stat = std.Io.Dir.cwd().statFile(app_io, path, .{}) catch {
        sendMissingObject(ctx, allocator, res, bucket, effective_key);
        return true;
    };
    const content = readObjectPlaintext(allocator, req, path, effective_key, false) catch |err| {
        sseErrorResponse(res, err);
        return true;
    };
    const etag = attrs.etag orelse try md5Etag(allocator, content);
    if (req.header("if-match")) |im| {
        if (!etagListMatches(im, etag)) {
            sendError(res, 412, "PreconditionFailed", "At least one of the pre-conditions you specified did not hold");
            return true;
        }
    }
    if (req.header("if-none-match")) |inm| {
        if (etagListMatches(inm, etag)) {
            res.status = 304;
            res.status_text = "Not Modified";
            return true;
        }
    }
    const mtime: i64 = @intCast(stat.mtime.toSeconds());
    if (head_only) {
        const last_modified = try allocHttpDate(allocator, mtime);
        res.ok();
        res.setHeader("Content-Length", try std.fmt.allocPrint(allocator, "{d}", .{content.len}));
        res.setHeader("Accept-Ranges", "bytes");
        res.setHeader("ETag", etag);
        res.setHeader("Last-Modified", last_modified);
        applyAttrsToResponse(res, &attrs);
        addNullVersionHeader(ctx, allocator, res, bucket, &attrs);
        return true;
    }
    serveContent(allocator, req, res, content, etag, mtime, &attrs);
    addNullVersionHeader(ctx, allocator, res, bucket, &attrs);
    return true;
}

/// GET/PUT/DELETE /{bucket}?encryption (bucket default encryption).
fn handleBucketEncryption(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8) !void {
    if (!bucketExists(ctx, allocator, bucket)) {
        sendError(res, 404, "NoSuchBucket", "Bucket not found");
        return;
    }
    if (std.mem.eql(u8, req.method, "GET")) {
        const stored = readBucketConfig(ctx, allocator, bucket, "encryption.xml") orelse {
            sendError(res, 404, "ServerSideEncryptionConfigurationNotFoundError", "The server side encryption configuration was not found");
            return;
        };
        res.ok();
        res.setXmlBody(stored);
        return;
    }
    if (std.mem.eql(u8, req.method, "PUT")) {
        if (ctx.distributed != null) {
            sendError(res, 501, "NotImplemented", "Encryption is not available in distributed mode");
            return;
        }
        const alg = xmlTagText(req.body, "SSEAlgorithm") orelse {
            sendError(res, 400, "MalformedXML", "ServerSideEncryptionConfiguration requires a Rule with SSEAlgorithm");
            return;
        };
        if (std.mem.eql(u8, alg, "aws:kms") or std.mem.eql(u8, alg, "aws:kms:dsse")) {
            sendSseHeaderError(res, error.SseKmsUnsupported);
            return;
        }
        if (!std.mem.eql(u8, alg, "AES256")) {
            sendSseHeaderError(res, error.SseBadAlgorithm);
            return;
        }
        // Make sure the master key exists now, not on the first PUT.
        _ = sseMasterKey(ctx) catch {
            sseErrorResponse(res, error.BadSseKey);
            return;
        };
        try writeBucketConfig(ctx, allocator, bucket, "encryption.xml", req.body);
        res.ok();
        return;
    }
    if (std.mem.eql(u8, req.method, "DELETE")) {
        deleteBucketConfig(ctx, allocator, bucket, "encryption.xml");
        res.noContent();
        return;
    }
    sendError(res, 405, "MethodNotAllowed", "Method not allowed");
}

// --- Multipart uploads with SSE ---------------------------------------------
// Parts are encrypted on upload (with the customer key for SSE-C, the master
// key for SSE-S3) and re-encrypted as one object on completion, so no part
// ever sits on disk in the clear. SSE-C uploads need the customer key on
// UploadPart and on CompleteMultipartUpload.

const UploadSse = union(enum) {
    none,
    s3,
    customer_md5: []const u8,
};

fn uploadSseFromMeta(meta_content: []const u8) UploadSse {
    var lines = std.mem.splitScalar(u8, meta_content, '\n');
    _ = lines.next();
    _ = lines.next();
    while (lines.next()) |line| {
        if (std.mem.startsWith(u8, line, "sse=AES256")) return .s3;
        if (std.mem.startsWith(u8, line, "sse=SSE-C:")) return .{ .customer_md5 = line["sse=SSE-C:".len..] };
    }
    return .none;
}

fn readUploadMeta(ctx: *const S3Context, allocator: Allocator, upload_id: []const u8) ?[]u8 {
    const meta_path = std.fmt.allocPrint(allocator, "{s}/.uploads/{s}/.meta", .{ ctx.data_dir, upload_id }) catch return null;
    defer allocator.free(meta_path);
    var f = std.Io.Dir.cwd().openFile(app_io, meta_path, .{}) catch return null;
    defer f.close(app_io);
    return readToEndAlloc(f, allocator, 64 * 1024) catch null;
}

/// Key material for an encrypted upload's parts, from the upload's SSE mode
/// and (for SSE-C) the request headers.
fn uploadSseMode(allocator: Allocator, req: *const Request, res: *Response, usse: UploadSse) !?SseMode {
    switch (usse) {
        .none => return null,
        .s3 => return .s3,
        .customer_md5 => |expected| {
            const provided = sseCustomerKeyFromHeaders(allocator, req, false) catch |err| {
                sendSseHeaderError(res, err);
                return error.Handled;
            };
            const m = provided orelse {
                sseErrorResponse(res, error.SseKeyRequired);
                return error.Handled;
            };
            if (!std.mem.eql(u8, expected, m.customer.key_md5_b64)) {
                sseErrorResponse(res, error.SseKeyMismatch);
                return error.Handled;
            }
            return m;
        },
    }
}

/// Write one part, encrypting it when the upload is encrypted. Returns the
/// plaintext ETag.
fn writeUploadPart(ctx: *const S3Context, allocator: Allocator, req: *const Request, res: *Response, upload_id: []const u8, part_path: []const u8, data: []const u8) ![]const u8 {
    var stored: []const u8 = data;
    if (readUploadMeta(ctx, allocator, upload_id)) |meta| {
        const usse = uploadSseFromMeta(meta);
        if (try uploadSseMode(allocator, req, res, usse)) |mode| {
            const ikm = sseIkm(ctx, mode) catch {
                sseErrorResponse(res, error.BadSseKey);
                return error.Handled;
            };
            stored = sseEncryptWith(allocator, &ikm, data, mode) catch {
                sendError(res, 500, "InternalError", "Encryption failed");
                return error.Handled;
            };
        }
    }
    var file = std.Io.Dir.cwd().createFile(app_io, part_path, .{}) catch {
        sendError(res, 500, "InternalError", "Cannot create part file");
        return error.Handled;
    };
    defer file.close(app_io);
    file.writeStreamingAll(app_io, stored) catch {
        sendError(res, 500, "InternalError", "Cannot write part");
        return error.Handled;
    };
    if (enable_fsync) {
        fsyncFile(file);
        fsyncParentDir(part_path);
    }
    return md5Etag(allocator, data);
}

// ============================================================================
// LIFECYCLE
// ============================================================================
// Rules are stored verbatim as `<bucket>/.zs3bucket/lifecycle.xml` and
// evaluated by a background thread every --lifecycle-interval-s seconds.
// Supported: Expiration (Days / Date / ExpiredObjectDeleteMarker),
// NoncurrentVersionExpiration (NoncurrentDays),
// AbortIncompleteMultipartUpload (DaysAfterInitiation), with Filter by
// Prefix, Tag, or And{Prefix, Tag...} (and the legacy top-level Prefix).
// Transitions to other storage classes have no meaning here and are rejected.

const LIFECYCLE_INTERVAL_S: u64 = 3600;
var lifecycle_interval_s: u64 = LIFECYCLE_INTERVAL_S;

const LifecycleRule = struct {
    id: []const u8,
    enabled: bool,
    prefix: []const u8,
    tags: []const Tag,
    expiration_days: ?u32 = null,
    expiration_date: ?i64 = null,
    expired_delete_marker: bool = false,
    noncurrent_days: ?u32 = null,
    abort_mpu_days: ?u32 = null,
};

/// Days since 1970-01-01 for a civil date (Howard Hinnant's algorithm).
fn civilToEpochDays(y_in: i64, m: u32, d: u32) i64 {
    const y: i64 = if (m <= 2) y_in - 1 else y_in;
    const era: i64 = @divFloor(y, 400);
    const yoe: i64 = y - era * 400;
    const mp: i64 = @intCast((m + 9) % 12);
    const doy: i64 = @divFloor(153 * mp + 2, 5) + @as(i64, d) - 1;
    const doe: i64 = yoe * 365 + @divFloor(yoe, 4) - @divFloor(yoe, 100) + doy;
    return era * 146097 + doe - 719468;
}

/// "YYYY-MM-DD" or "YYYY-MM-DDThh:mm:ss[.fff]Z" to Unix seconds.
pub fn parseIso8601(text: []const u8) ?i64 {
    const t = std.mem.trim(u8, text, " \t\r\n");
    if (t.len < 10 or t[4] != '-' or t[7] != '-') return null;
    const y = std.fmt.parseInt(i64, t[0..4], 10) catch return null;
    const m = std.fmt.parseInt(u32, t[5..7], 10) catch return null;
    const d = std.fmt.parseInt(u32, t[8..10], 10) catch return null;
    if (m < 1 or m > 12 or d < 1 or d > 31) return null;
    var secs: i64 = civilToEpochDays(y, m, d) * 86400;
    if (t.len >= 19 and (t[10] == 'T' or t[10] == ' ')) {
        const hh = std.fmt.parseInt(i64, t[11..13], 10) catch return null;
        const mm = std.fmt.parseInt(i64, t[14..16], 10) catch return null;
        const ss = std.fmt.parseInt(i64, t[17..19], 10) catch return null;
        secs += hh * 3600 + mm * 60 + ss;
    }
    return secs;
}

fn parseLifecycleTags(allocator: Allocator, block: []const u8, list: *std.ArrayListUnmanaged(Tag)) !void {
    var rest = block;
    while (std.mem.indexOf(u8, rest, "<Tag>")) |start| {
        const after = rest[start + 5 ..];
        const end = std.mem.indexOf(u8, after, "</Tag>") orelse return error.MalformedXML;
        const tb = after[0..end];
        const k = xmlTagText(tb, "Key") orelse return error.MalformedXML;
        const v = xmlTagText(tb, "Value") orelse "";
        try list.append(allocator, .{ .key = try xmlUnescape(allocator, k), .value = try xmlUnescape(allocator, v) });
        rest = after[end + 6 ..];
    }
}

/// Text of the first <tag> that is a direct child (not nested inside <sub>).
fn xmlTagTextOutside(block: []const u8, tag: []const u8, sub: []const u8) ?[]const u8 {
    var open_buf: [64]u8 = undefined;
    var sub_open_buf: [64]u8 = undefined;
    var sub_close_buf: [64]u8 = undefined;
    const open = std.fmt.bufPrint(&open_buf, "<{s}>", .{tag}) catch return null;
    const sub_open = std.fmt.bufPrint(&sub_open_buf, "<{s}>", .{sub}) catch return null;
    const sub_close = std.fmt.bufPrint(&sub_close_buf, "</{s}>", .{sub}) catch return null;
    const pos = std.mem.indexOf(u8, block, open) orelse return null;
    if (std.mem.indexOf(u8, block, sub_open)) |so| {
        const sc = std.mem.indexOf(u8, block, sub_close) orelse block.len;
        if (pos > so and pos < sc) {
            // inside the sub-block: look after it
            return xmlTagText(block[sc..], tag);
        }
    }
    return xmlTagText(block, tag);
}

pub fn parseLifecycleXml(allocator: Allocator, body: []const u8) ![]LifecycleRule {
    if (std.mem.indexOf(u8, body, "<LifecycleConfiguration") == null) return error.MalformedXML;
    var rules: std.ArrayListUnmanaged(LifecycleRule) = .empty;
    errdefer rules.deinit(allocator);
    var rest = body;
    while (std.mem.indexOf(u8, rest, "<Rule>")) |start| {
        const after = rest[start + 6 ..];
        const end = std.mem.indexOf(u8, after, "</Rule>") orelse return error.MalformedXML;
        const rb = after[0..end];
        rest = after[end + 7 ..];

        const status = xmlTagText(rb, "Status") orelse return error.MalformedXML;
        const enabled = if (std.mem.eql(u8, status, "Enabled")) true else if (std.mem.eql(u8, status, "Disabled")) false else return error.MalformedXML;
        const id = try xmlUnescape(allocator, xmlTagText(rb, "ID") orelse "");
        if (id.len > 255) return error.InvalidArgument;

        var prefix: []const u8 = "";
        var tags: std.ArrayListUnmanaged(Tag) = .empty;
        if (std.mem.indexOf(u8, rb, "<Filter>")) |fs| {
            const fe = std.mem.indexOf(u8, rb[fs..], "</Filter>") orelse return error.MalformedXML;
            const fb = rb[fs + 8 .. fs + fe];
            if (xmlTagText(fb, "Prefix")) |pf| prefix = try xmlUnescape(allocator, pf);
            try parseLifecycleTags(allocator, fb, &tags);
        } else if (std.mem.indexOf(u8, rb, "<Filter/>") != null) {
            // empty filter: whole bucket
        } else if (xmlTagText(rb, "Prefix")) |pf| {
            prefix = try xmlUnescape(allocator, pf);
        }

        var rule = LifecycleRule{ .id = id, .enabled = enabled, .prefix = prefix, .tags = try tags.toOwnedSlice(allocator) };
        var actions: usize = 0;
        if (std.mem.indexOf(u8, rb, "<Expiration>")) |es| {
            const ee = std.mem.indexOf(u8, rb[es..], "</Expiration>") orelse return error.MalformedXML;
            const eb = rb[es + 12 .. es + ee];
            if (xmlTagText(eb, "Days")) |d| {
                rule.expiration_days = std.fmt.parseInt(u32, d, 10) catch return error.InvalidArgument;
            }
            if (xmlTagText(eb, "Date")) |d| {
                rule.expiration_date = parseIso8601(d) orelse return error.InvalidArgument;
            }
            if (xmlTagText(eb, "ExpiredObjectDeleteMarker")) |v| rule.expired_delete_marker = std.mem.eql(u8, v, "true");
            if (rule.expiration_days != null and rule.expiration_date != null) return error.InvalidArgument;
            if (rule.expired_delete_marker and (rule.expiration_days != null or rule.expiration_date != null)) return error.InvalidArgument;
            if (rule.expired_delete_marker and rule.tags.len > 0) return error.InvalidArgument;
            actions += 1;
        }
        if (std.mem.indexOf(u8, rb, "<NoncurrentVersionExpiration>")) |ns| {
            const ne = std.mem.indexOf(u8, rb[ns..], "</NoncurrentVersionExpiration>") orelse return error.MalformedXML;
            const nb = rb[ns + 29 .. ns + ne];
            const d = xmlTagText(nb, "NoncurrentDays") orelse return error.MalformedXML;
            rule.noncurrent_days = std.fmt.parseInt(u32, d, 10) catch return error.InvalidArgument;
            actions += 1;
        }
        if (std.mem.indexOf(u8, rb, "<AbortIncompleteMultipartUpload>")) |as_| {
            const ae = std.mem.indexOf(u8, rb[as_..], "</AbortIncompleteMultipartUpload>") orelse return error.MalformedXML;
            const ab = rb[as_ + 32 .. as_ + ae];
            const d = xmlTagText(ab, "DaysAfterInitiation") orelse return error.MalformedXML;
            rule.abort_mpu_days = std.fmt.parseInt(u32, d, 10) catch return error.InvalidArgument;
            if (rule.tags.len > 0) return error.InvalidArgument;
            actions += 1;
        }
        if (std.mem.indexOf(u8, rb, "<Transition>") != null or std.mem.indexOf(u8, rb, "<NoncurrentVersionTransition>") != null) {
            return error.TransitionUnsupported;
        }
        if (actions == 0) return error.InvalidArgument;
        try rules.append(allocator, rule);
    }
    if (rules.items.len == 0) return error.MalformedXML;
    if (rules.items.len > 1000) return error.InvalidArgument;
    return rules.toOwnedSlice(allocator);
}

/// GET/PUT/DELETE /{bucket}?lifecycle
fn handleBucketLifecycle(ctx: *const S3Context, allocator: Allocator, req: *Request, res: *Response, bucket: []const u8) !void {
    if (!bucketExists(ctx, allocator, bucket)) {
        sendError(res, 404, "NoSuchBucket", "Bucket not found");
        return;
    }
    if (std.mem.eql(u8, req.method, "GET")) {
        const stored = readBucketConfig(ctx, allocator, bucket, "lifecycle.xml") orelse {
            sendError(res, 404, "NoSuchLifecycleConfiguration", "The lifecycle configuration does not exist");
            return;
        };
        res.ok();
        res.setXmlBody(stored);
        return;
    }
    if (std.mem.eql(u8, req.method, "PUT")) {
        _ = parseLifecycleXml(allocator, req.body) catch |err| {
            switch (err) {
                error.MalformedXML => sendError(res, 400, "MalformedXML", "The XML you provided was not well-formed or did not validate against our published schema"),
                error.InvalidArgument => sendError(res, 400, "InvalidArgument", "Invalid lifecycle rule (check Days, Date, filters and actions)"),
                error.TransitionUnsupported => sendError(res, 501, "NotImplemented", "Storage class transitions are not supported; zs3 has one storage class"),
                else => return err,
            }
            return;
        };
        try writeBucketConfig(ctx, allocator, bucket, "lifecycle.xml", req.body);
        res.ok();
        return;
    }
    if (std.mem.eql(u8, req.method, "DELETE")) {
        deleteBucketConfig(ctx, allocator, bucket, "lifecycle.xml");
        res.noContent();
        return;
    }
    sendError(res, 405, "MethodNotAllowed", "Method not allowed");
}

// --- Background evaluation ---------------------------------------------------

fn lifecycleThreadMain(ctx: *const S3Context) void {
    while (true) {
        app_io.sleep(.fromMilliseconds(@intCast(lifecycle_interval_s * 1000)), .awake) catch {};
        runLifecycleOnce(ctx) catch |err| std.log.warn("lifecycle pass failed: {t}", .{err});
    }
}

fn ruleTagsMatch(ctx: *const S3Context, allocator: Allocator, rule: *const LifecycleRule, bucket: []const u8, effective_key: []const u8) bool {
    if (rule.tags.len == 0) return true;
    const attrs = loadObjectAttrsAny(ctx, allocator, bucket, effective_key) orelse return false;
    const stored = attrs.tagging orelse return false;
    const tags = parseTagQuery(allocator, stored) catch return false;
    for (rule.tags) |want| {
        var found = false;
        for (tags) |have| {
            if (std.mem.eql(u8, have.key, want.key) and std.mem.eql(u8, have.value, want.value)) {
                found = true;
                break;
            }
        }
        if (!found) return false;
    }
    return true;
}

/// One pass over every bucket with a lifecycle configuration.
fn runLifecycleOnce(ctx: *const S3Context) !void {
    var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
    defer arena.deinit();
    const allocator = arena.allocator();
    const now = std.Io.Clock.real.now(app_io).toSeconds();

    var root = try std.Io.Dir.cwd().openDir(app_io, ctx.data_dir, .{ .iterate = true });
    defer root.close(app_io);
    var it = root.iterate();
    while (try it.next(app_io)) |entry| {
        if (entry.kind != .directory or !isValidBucketName(entry.name)) continue;
        const bucket = try allocator.dupe(u8, entry.name);
        const stored = readBucketConfig(ctx, allocator, bucket, "lifecycle.xml") orelse continue;
        const rules = parseLifecycleXml(allocator, stored) catch continue;
        for (rules) |*rule| {
            if (!rule.enabled) continue;
            applyLifecycleRule(ctx, allocator, bucket, rule, now) catch |err| {
                std.log.warn("lifecycle rule {s} on {s}: {t}", .{ rule.id, bucket, err });
            };
        }
    }
}

fn applyLifecycleRule(ctx: *const S3Context, allocator: Allocator, bucket: []const u8, rule: *const LifecycleRule, now: i64) !void {
    const bucket_path = try ctx.bucketPath(allocator, bucket);

    // Expiration of current objects.
    if (rule.expiration_days != null or rule.expiration_date != null) {
        var keys: std.ArrayListUnmanaged(KeyInfo) = .empty;
        try collectKeys(allocator, bucket_path, "", rule.prefix, &keys, false);
        for (keys.items) |k| {
            const expired = if (rule.expiration_days) |days|
                now - k.mtime >= @as(i64, days) * 86400
            else
                now >= rule.expiration_date.?;
            if (!expired) continue;
            const effective_key = if (k.key.len > 0 and k.key[k.key.len - 1] == '/')
                try std.fmt.allocPrint(allocator, "{s}.folder_marker", .{k.key})
            else
                k.key;
            if (!ruleTagsMatch(ctx, allocator, rule, bucket, effective_key)) continue;
            if (ctx.distributed) |dist| {
                dist.meta_index.delete(allocator, bucket, k.key);
                deleteDistAttrs(allocator, dist, bucket, k.key);
            }
            _ = deleteObjectVersioned(ctx, allocator, bucket, effective_key, null) catch continue;
            std.log.info("lifecycle: expired {s}/{s} (rule {s})", .{ bucket, k.key, rule.id });
        }
    }

    // Noncurrent versions and orphaned delete markers.
    if (rule.noncurrent_days != null or rule.expired_delete_marker) {
        var versions: std.ArrayListUnmanaged(ListedVersion) = .empty;
        try collectStoredVersions(ctx, allocator, bucket, "", rule.prefix, &versions);
        // Group per key: entries come out grouped by directory already, but
        // sort to be safe.
        std.mem.sort(ListedVersion, versions.items, {}, listedVersionLess);
        var i: usize = 0;
        while (i < versions.items.len) {
            var j = i;
            while (j < versions.items.len and std.mem.eql(u8, versions.items[j].key, versions.items[i].key)) : (j += 1) {}
            const group = versions.items[i..j];
            i = j;
            const effective_key = if (group[0].key.len > 0 and group[0].key[group[0].key.len - 1] == '/')
                try std.fmt.allocPrint(allocator, "{s}.folder_marker", .{group[0].key})
            else
                group[0].key;
            const current_path = try ctx.objectPath(allocator, bucket, effective_key);
            const has_current = if (std.Io.Dir.cwd().statFile(app_io, current_path, .{})) |st| st.kind == .file else |_| false;
            const vdir = try versionsDirPath(ctx, allocator, bucket, effective_key);

            if (rule.expired_delete_marker and !has_current and group.len == 1 and group[0].is_marker) {
                const marker = try versionFilePath(allocator, vdir, group[0].vid, DELETE_MARKER_SUFFIX);
                std.Io.Dir.cwd().deleteFile(app_io, marker) catch {};
                removeEmptyVersionDirs(ctx, allocator, bucket, vdir);
                std.log.info("lifecycle: removed expired delete marker {s}/{s}", .{ bucket, group[0].key });
                continue;
            }
            if (rule.noncurrent_days) |days| {
                if (rule.tags.len > 0 and !ruleTagsMatch(ctx, allocator, rule, bucket, effective_key)) continue;
                for (group, 0..) |v, idx| {
                    // Without a current object the newest stored entry is the
                    // latest version and stays.
                    if (!has_current and idx == 0) continue;
                    const fpath = try versionFilePath(allocator, vdir, v.vid, if (v.is_marker) DELETE_MARKER_SUFFIX else "");
                    // Age counts from when the version became noncurrent,
                    // which the rename into .zs3versions records as ctime.
                    const st = std.Io.Dir.cwd().statFile(app_io, fpath, .{}) catch continue;
                    const became_noncurrent: i64 = @intCast(st.ctime.toSeconds());
                    if (now - became_noncurrent < @as(i64, days) * 86400) continue;
                    std.Io.Dir.cwd().deleteFile(app_io, fpath) catch continue;
                    if (!v.is_marker) deleteStandaloneAttrs(allocator, fpath);
                    std.log.info("lifecycle: removed noncurrent version {s}/{s} {s}", .{ bucket, v.key, v.vid });
                }
                removeEmptyVersionDirs(ctx, allocator, bucket, vdir);
            }
        }
    }

    // Abandoned multipart uploads.
    if (rule.abort_mpu_days) |days| {
        const uploads = try std.fs.path.join(allocator, &.{ ctx.data_dir, ".uploads" });
        var udir = std.Io.Dir.cwd().openDir(app_io, uploads, .{ .iterate = true }) catch return;
        defer udir.close(app_io);
        var uit = udir.iterate();
        while (try uit.next(app_io)) |entry| {
            if (entry.kind != .directory) continue;
            const upload_id = try allocator.dupe(u8, entry.name);
            const meta = readUploadMeta(ctx, allocator, upload_id) orelse continue;
            var lines = std.mem.splitScalar(u8, meta, '\n');
            const ub = lines.next() orelse continue;
            const uk = lines.next() orelse continue;
            if (!std.mem.eql(u8, ub, bucket) or !std.mem.startsWith(u8, uk, rule.prefix)) continue;
            const st = udir.statFile(app_io, entry.name, .{}) catch continue;
            const initiated: i64 = @intCast(st.mtime.toSeconds());
            if (now - initiated < @as(i64, days) * 86400) continue;
            const dir_path = try std.fs.path.join(allocator, &.{ uploads, upload_id });
            std.Io.Dir.cwd().deleteTree(app_io, dir_path) catch continue;
            std.log.info("lifecycle: aborted stale upload {s} ({s}/{s})", .{ upload_id, ub, uk });
        }
    }
}