//! Resident sealed-segment manifest. //! //! Upstream Jetstream V2 loads every sealed segment header and block index at //! startup, then refreshes that immutable metadata after seal or rewrite. //! Serving code never treats repeated disk reads as a "cache". Stream follows //! that boundary here: metadata is resident, lookups are synchronized, and a //! refcounted block-index handle remains valid across concurrent refreshes. const std = @import("std"); const metrics = @import("../runtime/metrics.zig"); const segment = @import("segment.zig"); const gloom = @import("gloom.zig"); const Allocator = std.mem.Allocator; const Io = std.Io; const ResidentBlocks = struct { allocator: Allocator, refs: std.atomic.Value(usize) = .init(1), entries: []segment.BlockIndexEntry, footer: []u8, segment_bloom: []const u8, block_bloom_region: []const u8, block_bloom_count: u32, block_bloom_size: u32, segment_bloom_valid: bool, block_bloom_valid: []bool, collection_index: segment.CollectionIndex, fn create( allocator: Allocator, entries: []segment.BlockIndexEntry, footer: []u8, segment_bloom: []const u8, block_bloom_region: []const u8, block_bloom_count: u32, block_bloom_size: u32, segment_bloom_valid: bool, block_bloom_valid: []bool, collection_index: segment.CollectionIndex, ) !*ResidentBlocks { const resident = try allocator.create(ResidentBlocks); resident.* = .{ .allocator = allocator, .entries = entries, .footer = footer, .segment_bloom = segment_bloom, .block_bloom_region = block_bloom_region, .block_bloom_count = block_bloom_count, .block_bloom_size = block_bloom_size, .segment_bloom_valid = segment_bloom_valid, .block_bloom_valid = block_bloom_valid, .collection_index = collection_index, }; return resident; } /// Heap bytes this entry keeps resident for the lifetime of the manifest: /// decoded block index, the raw footer (segment/block blooms alias into /// it), validity flags, and the collection index's own allocations. fn residentBytes(self: *const ResidentBlocks) usize { return @sizeOf(ResidentBlocks) + self.entries.len * @sizeOf(segment.BlockIndexEntry) + self.footer.len + self.block_bloom_valid.len + self.collection_index.entries.len * @sizeOf(segment.CollectionEntry) + self.collection_index.buffer.len; } fn retain(self: *ResidentBlocks) void { _ = self.refs.fetchAdd(1, .monotonic); } fn release(self: *ResidentBlocks) void { if (self.refs.fetchSub(1, .acq_rel) != 1) return; self.allocator.free(self.entries); self.collection_index.deinit(self.allocator); self.allocator.free(self.block_bloom_valid); self.allocator.free(self.footer); self.allocator.destroy(self); } }; pub const BlockIndex = struct { resident: *ResidentBlocks, entries: []const segment.BlockIndexEntry, pub fn deinit(self: *BlockIndex) void { self.resident.release(); self.* = undefined; } }; /// Stable manifest-resident planning metadata. Its slices remain valid across /// concurrent compaction refreshes until deinit releases the retained entry. pub const PlanningSegment = struct { resident: *ResidentBlocks, summary: Summary, blocks: []const segment.BlockIndexEntry, segment_bloom: []const u8, segment_bloom_valid: bool, collection_index: *const segment.CollectionIndex, pub fn deinit(self: *PlanningSegment) void { self.resident.release(); self.* = undefined; } pub fn blockBloom(self: *const PlanningSegment, block: usize) ?[]const u8 { if (block >= self.resident.block_bloom_count or !self.resident.block_bloom_valid[block]) return null; const size: usize = self.resident.block_bloom_size; const at = 8 + block * size; if (at + size > self.resident.block_bloom_region.len) return null; return self.resident.block_bloom_region[at..][0..size]; } }; pub const Summary = struct { idx: u64, size: u64, mtime: Io.Timestamp, header: segment.Header, }; pub const LookbackFloor = struct { seq: u64 = 0, witnessed_at: i64 = 0, }; const Metadata = struct { summary: Summary, blocks: *ResidentBlocks, fn deinit(self: *Metadata) void { self.blocks.release(); self.* = undefined; } }; pub const Manifest = struct { allocator: Allocator, io: Io, mu: Io.Mutex = .init, segments: std.ArrayList(Metadata) = .empty, stats: ?*metrics.Stats, generation: u64 = 0, invalidation_ctx: ?*anyopaque = null, invalidation_fn: ?*const fn (?*anyopaque, u64) anyerror!void = null, pub fn init(allocator: Allocator, io: Io, dir: Io.Dir, stats: ?*metrics.Stats) !Manifest { var manifest: Manifest = .{ .allocator = allocator, .io = io, .stats = stats }; errdefer manifest.deinit(); var iterator = dir.iterate(); while (try iterator.next(io)) |entry| { const idx = parseSegmentIndex(entry.name) orelse continue; const started = Io.Timestamp.now(io, .awake); var metadata = (try loadMetadata(allocator, io, dir, idx, false)) orelse continue; errdefer metadata.deinit(); try manifest.segments.append(allocator, metadata); if (stats) |s| { const elapsed = started.durationTo(Io.Timestamp.now(io, .awake)).toMicroseconds(); s.observeManifestLoad(@intCast(@max(0, elapsed))); } } std.mem.sort(Metadata, manifest.segments.items, {}, lessThan); try validateMonotonic(manifest.segments.items); manifest.generation = 1; if (stats) |s| { s.manifest_segments_loaded.store(manifest.segments.items.len, .release); s.manifest_resident_bytes.store(manifest.residentBytesLocked(), .release); } return manifest; } pub fn deinit(self: *Manifest) void { for (self.segments.items) |*metadata| metadata.deinit(); self.segments.deinit(self.allocator); } /// total sealed bytes + segment count, for the public metrics gauge pub fn sealedTotals(self: *Manifest) struct { bytes: u64, segments: u64 } { self.mu.lockUncancelable(self.io); defer self.mu.unlock(self.io); var bytes: u64 = 0; for (self.segments.items) |metadata| bytes += metadata.summary.size; return .{ .bytes = bytes, .segments = self.segments.items.len }; } pub fn all(self: *Manifest, allocator: Allocator) ![]Summary { self.mu.lockUncancelable(self.io); defer self.mu.unlock(self.io); const result = try allocator.alloc(Summary, self.segments.items.len); for (self.segments.items, result) |metadata, *summary| summary.* = metadata.summary; return result; } /// Oldest segment conservatively retained by the cursor lookback. This /// mirrors upstream: choose the first segment whose max witnessed time is /// inside the window, or the freshest segment when the entire archive is /// older. Returning its min bound may expose one extra segment, never less. pub fn lookbackFloor(self: *Manifest, now_us: i64, lookback_ns: u64) LookbackFloor { self.mu.lockUncancelable(self.io); defer self.mu.unlock(self.io); if (self.segments.items.len == 0) return .{}; const lookback_us: i64 = @intCast(lookback_ns / std.time.ns_per_us); const floor_time = now_us -| lookback_us; const selected = for (self.segments.items) |metadata| { if (metadata.summary.header.max_witnessed_at >= floor_time) break metadata.summary.header; } else self.segments.items[self.segments.items.len - 1].summary.header; return .{ .seq = selected.min_seq, .witnessed_at = selected.min_witnessed_at }; } pub fn segmentByIndex(self: *Manifest, idx: u64) ?Summary { self.mu.lockUncancelable(self.io); defer self.mu.unlock(self.io); const at = self.find(idx); if (at >= self.segments.items.len or self.segments.items[at].summary.idx != idx) return null; return self.segments.items[at].summary; } /// Return a stable view of resident metadata. The handle owns one /// reference so a concurrent compaction/timestamp refresh may swap the /// manifest entry without invalidating an in-flight replay. pub fn blockIndex(self: *Manifest, idx: u64) !BlockIndex { self.mu.lockUncancelable(self.io); defer self.mu.unlock(self.io); const at = self.find(idx); if (at >= self.segments.items.len or self.segments.items[at].summary.idx != idx) { if (self.stats) |stats| _ = stats.manifest_block_index_cache_misses_total.fetchAdd(1, .monotonic); return error.UnknownSegment; } if (self.stats) |stats| _ = stats.manifest_block_index_cache_hits_total.fetchAdd(1, .monotonic); const resident = self.segments.items[at].blocks; resident.retain(); return .{ .resident = resident, .entries = resident.entries }; } pub fn planningSegments(self: *Manifest, allocator: Allocator) ![]PlanningSegment { self.mu.lockUncancelable(self.io); defer self.mu.unlock(self.io); const result = try allocator.alloc(PlanningSegment, self.segments.items.len); errdefer allocator.free(result); var retained: usize = 0; errdefer for (result[0..retained]) |*item| item.deinit(); for (self.segments.items, result) |metadata, *item| { metadata.blocks.retain(); retained += 1; item.* = .{ .resident = metadata.blocks, .summary = metadata.summary, .blocks = metadata.blocks.entries, .segment_bloom = metadata.blocks.segment_bloom, .segment_bloom_valid = metadata.blocks.segment_bloom_valid, .collection_index = &metadata.blocks.collection_index, }; } return result; } pub fn refresh(self: *Manifest, dir: Io.Dir, idx: u64, verify_checksum: bool) !void { const started = Io.Timestamp.now(self.io, .awake); var next = (try loadMetadata(self.allocator, self.io, dir, idx, verify_checksum)) orelse return error.ActiveSegment; var moved = false; errdefer if (!moved) next.deinit(); self.mu.lockUncancelable(self.io); defer self.mu.unlock(self.io); const at = self.find(idx); try validateReplacement(self.segments.items, at, next.summary); if (at < self.segments.items.len and self.segments.items[at].summary.idx == idx) { var old = self.segments.items[at]; self.segments.items[at] = next; old.deinit(); } else { try self.segments.insert(self.allocator, at, next); } moved = true; self.generation +%= 1; if (self.invalidation_fn) |invalidate| try invalidate(self.invalidation_ctx, idx); if (self.stats) |stats| { stats.manifest_segments_loaded.store(self.segments.items.len, .release); stats.manifest_resident_bytes.store(self.residentBytesLocked(), .release); const elapsed = started.durationTo(Io.Timestamp.now(self.io, .awake)).toMicroseconds(); stats.observeManifestLoad(@intCast(@max(0, elapsed))); } } pub fn setInvalidator(self: *Manifest, ctx: ?*anyopaque, callback: ?*const fn (?*anyopaque, u64) anyerror!void) void { self.mu.lockUncancelable(self.io); defer self.mu.unlock(self.io); self.invalidation_ctx = ctx; self.invalidation_fn = callback; } pub fn currentGeneration(self: *Manifest) u64 { self.mu.lockUncancelable(self.io); defer self.mu.unlock(self.io); return self.generation; } /// Callers hold `mu` (or exclusive ownership during init). fn residentBytesLocked(self: *const Manifest) usize { var total: usize = self.segments.items.len * @sizeOf(Metadata); for (self.segments.items) |metadata| total += metadata.blocks.residentBytes(); return total; } fn find(self: *const Manifest, idx: u64) usize { return std.sort.lowerBound(Metadata, self.segments.items, idx, struct { fn order(key: u64, metadata: Metadata) std.math.Order { return std.math.order(key, metadata.summary.idx); } }.order); } }; fn loadMetadata(allocator: Allocator, io: Io, dir: Io.Dir, idx: u64, verify_checksum: bool) !?Metadata { var name_buffer: [64]u8 = undefined; const name = formatSegmentName(&name_buffer, idx); var file = try dir.openFile(io, name, .{}); defer file.close(io); const stat = try file.stat(io); var header_bytes: [segment.header_size]u8 = undefined; const header_read = try file.readPositionalAll(io, &header_bytes, 0); if (header_read != header_bytes.len) return error.Truncated; const header = segment.Header.decode(&header_bytes) catch |err| switch (err) { error.ActiveSegment => return null, else => return err, }; const index_len_u64 = @as(u64, header.block_count) * segment.BlockIndexEntry.encoded_size; if (header.block_index_offset + index_len_u64 > stat.size) return error.Truncated; const index_len: usize = @intCast(index_len_u64); const encoded = try allocator.alloc(u8, index_len); defer allocator.free(encoded); if (try file.readPositionalAll(io, encoded, header.block_index_offset) != index_len) return error.Truncated; const entries = try allocator.alloc(segment.BlockIndexEntry, header.block_count); errdefer allocator.free(entries); for (entries, 0..) |*entry, block| { const start = block * segment.BlockIndexEntry.encoded_size; entry.* = segment.BlockIndexEntry.decodePublic(encoded[start..][0..segment.BlockIndexEntry.encoded_size]); if (entry.offset < segment.header_size or entry.offset + 8 + entry.compressed_size > header.footer_offset) return error.BadBlockFrame; } if (header.did_bloom_offset < header.block_index_offset + index_len_u64 or header.block_did_bloom_offset < header.did_bloom_offset or header.collection_index_offset < header.block_did_bloom_offset or header.collection_index_offset > stat.size) return error.BadFooter; const footer_len: usize = @intCast(stat.size - header.did_bloom_offset); const footer = try allocator.alloc(u8, footer_len); errdefer allocator.free(footer); if (try file.readPositionalAll(io, footer, header.did_bloom_offset) != footer.len) return error.Truncated; const block_region_start: usize = @intCast(header.block_did_bloom_offset - header.did_bloom_offset); const collection_start: usize = @intCast(header.collection_index_offset - header.did_bloom_offset); if (block_region_start + 8 > collection_start) return error.BadFooter; const block_region = footer[block_region_start..collection_start]; const bloom_count = std.mem.readInt(u32, block_region[0..4], .little); const bloom_size = std.mem.readInt(u32, block_region[4..8], .little); if (bloom_count != header.block_count or 8 + @as(u64, bloom_count) * bloom_size != block_region.len) return error.BadFooter; const segment_bloom = footer[0..block_region_start]; const segment_bloom_valid = if (gloom.validateMarshaled(segment_bloom)) |_| true else |_| false; const block_bloom_valid = try allocator.alloc(bool, bloom_count); errdefer allocator.free(block_bloom_valid); for (block_bloom_valid, 0..) |*valid, block| { const at = 8 + block * @as(usize, bloom_size); valid.* = if (gloom.validateMarshaled(block_region[at..][0..@as(usize, bloom_size)])) |_| true else |_| false; } var collection_index = try segment.decodeCollectionIndex(allocator, footer[collection_start..], header.block_count); errdefer collection_index.deinit(allocator); if (verify_checksum) { var hasher = std.hash.XxHash3.init(0); hasher.update(header_bytes[12..]); hasher.update(encoded); hasher.update(footer); if (hasher.final() != header.checksum) return error.BadChecksum; } const resident = try ResidentBlocks.create( allocator, entries, footer, segment_bloom, block_region, bloom_count, bloom_size, segment_bloom_valid, block_bloom_valid, collection_index, ); return .{ .summary = .{ .idx = idx, .size = stat.size, .mtime = stat.mtime, .header = header }, .blocks = resident, }; } fn lessThan(_: void, left: Metadata, right: Metadata) bool { return left.summary.idx < right.summary.idx; } fn validateMonotonic(items: []const Metadata) !void { var prior_max: u64 = 0; var have_prior = false; for (items) |metadata| { const summary = metadata.summary; if (summary.header.event_count == 0) continue; if (have_prior and summary.header.min_seq <= prior_max) return error.SegmentSeqOverlap; prior_max = summary.header.max_seq; have_prior = true; } } fn validateReplacement(items: []const Metadata, at: usize, candidate: Summary) !void { if (candidate.header.event_count == 0) return; var before = at; while (before > 0) { before -= 1; if (items[before].summary.idx == candidate.idx) continue; if (items[before].summary.header.event_count == 0) continue; if (items[before].summary.header.max_seq >= candidate.header.min_seq) return error.SegmentSeqOverlap; break; } var after = at; if (after < items.len and items[after].summary.idx == candidate.idx) after += 1; while (after < items.len) : (after += 1) { if (items[after].summary.header.event_count == 0) continue; if (candidate.header.max_seq >= items[after].summary.header.min_seq) return error.SegmentSeqOverlap; break; } } pub fn formatSegmentName(buf: []u8, index: u64) []const u8 { var digits: [10]u8 = @splat('0'); var value = index; var at: usize = digits.len; while (value > 0) : (value /= 36) { at -= 1; digits[at] = std.fmt.digitToChar(@intCast(value % 36), .lower); } return std.fmt.bufPrint(buf, "seg_{s}.jss", .{digits}) catch unreachable; } pub fn parseSegmentIndex(name: []const u8) ?u64 { if (!std.mem.startsWith(u8, name, "seg_") or !std.mem.endsWith(u8, name, ".jss")) return null; const digits = name[4 .. name.len - 4]; if (digits.len != 10) return null; return std.fmt.parseInt(u64, digits, 36) catch null; } test "segment name round trip" { var buffer: [64]u8 = undefined; try std.testing.expectEqualStrings("seg_0000000000.jss", formatSegmentName(&buffer, 0)); try std.testing.expectEqualStrings("seg_000000000z.jss", formatSegmentName(&buffer, 35)); try std.testing.expectEqual(@as(?u64, 35), parseSegmentIndex(formatSegmentName(&buffer, 35))); try std.testing.expectEqual(@as(?u64, null), parseSegmentIndex("seg_x.jss")); } const writer_mod = @import("segment_writer.zig"); fn testEvent(seq: u64) segment.Event { return .{ .seq = seq, .witnessed_at = @intCast(seq * 10), .indexed_at = 0, .kind = .create, .did = "did:plc:manifesttestaccount", .collection = "app.bsky.feed.post", .rkey = "3lmanifesttest", .rev = "3lmanifestrev", .payload = "\xa1\x64text\x62hi", }; } fn writeSegment(allocator: Allocator, io: Io, dir: Io.Dir, idx: u64, seqs: []const u64, seal: bool) !void { var writer = try writer_mod.ActiveWriter.init(allocator); defer writer.deinit(); writer.max_events_per_block = 1; for (seqs) |seq| try writer.append(testEvent(seq)); if (seal) try writer.seal(); var name_buffer: [64]u8 = undefined; try dir.writeFile(io, .{ .sub_path = formatSegmentName(&name_buffer, idx), .data = writer.bytes() }); } test "resident manifest loads sealed metadata and measures real lookups" { var threaded: Io.Threaded = .init(std.testing.allocator, .{}); defer threaded.deinit(); const io = threaded.io(); var tmp = std.testing.tmpDir(.{}); defer tmp.cleanup(); var dir = try tmp.dir.createDirPathOpen(io, "segments", .{ .open_options = .{ .iterate = true } }); defer dir.close(io); try writeSegment(std.testing.allocator, io, dir, 0, &.{ 1, 2 }, true); try writeSegment(std.testing.allocator, io, dir, 1, &.{3}, false); var stats: metrics.Stats = .{}; var manifest = try Manifest.init(std.testing.allocator, io, dir, &stats); defer manifest.deinit(); const summaries = try manifest.all(std.testing.allocator); defer std.testing.allocator.free(summaries); try std.testing.expectEqual(@as(usize, 1), summaries.len); try std.testing.expectEqual(@as(u64, 0), summaries[0].idx); try std.testing.expectEqual(@as(u32, 2), summaries[0].header.block_count); try std.testing.expectEqual(@as(usize, 1), stats.manifest_segments_loaded.load(.acquire)); try std.testing.expectEqual(@as(u64, 1), stats.manifest_block_index_load_count.load(.monotonic)); const resident = stats.manifest_resident_bytes.load(.acquire); try std.testing.expect(resident > 0); try std.testing.expectEqual(manifest.residentBytesLocked(), resident); var blocks = try manifest.blockIndex(0); defer blocks.deinit(); try std.testing.expectEqual(@as(usize, 2), blocks.entries.len); try std.testing.expectError(error.UnknownSegment, manifest.blockIndex(42)); try std.testing.expectEqual(@as(u64, 1), stats.manifest_block_index_cache_hits_total.load(.monotonic)); try std.testing.expectEqual(@as(u64, 1), stats.manifest_block_index_cache_misses_total.load(.monotonic)); } test "lookback floor is conservative and falls back to freshest segment" { var threaded: Io.Threaded = .init(std.testing.allocator, .{}); defer threaded.deinit(); const io = threaded.io(); var tmp = std.testing.tmpDir(.{}); defer tmp.cleanup(); var dir = try tmp.dir.createDirPathOpen(io, "segments", .{ .open_options = .{ .iterate = true } }); defer dir.close(io); try writeSegment(std.testing.allocator, io, dir, 0, &.{ 1, 2 }, true); try writeSegment(std.testing.allocator, io, dir, 1, &.{ 3, 4 }, true); try writeSegment(std.testing.allocator, io, dir, 2, &.{ 5, 6 }, true); var manifest = try Manifest.init(std.testing.allocator, io, dir, null); defer manifest.deinit(); try std.testing.expectEqual(@as(u64, 5), manifest.lookbackFloor(100, 55 * std.time.ns_per_us).seq); try std.testing.expectEqual(@as(u64, 1), manifest.lookbackFloor(100, 150 * std.time.ns_per_us).seq); try std.testing.expectEqual(@as(u64, 5), manifest.lookbackFloor(100, 10 * std.time.ns_per_us).seq); } test "block index handle remains valid across verified refresh" { var threaded: Io.Threaded = .init(std.testing.allocator, .{}); defer threaded.deinit(); const io = threaded.io(); var tmp = std.testing.tmpDir(.{}); defer tmp.cleanup(); var dir = try tmp.dir.createDirPathOpen(io, "segments", .{ .open_options = .{ .iterate = true } }); defer dir.close(io); try writeSegment(std.testing.allocator, io, dir, 0, &.{1}, true); var stats: metrics.Stats = .{}; var manifest = try Manifest.init(std.testing.allocator, io, dir, &stats); defer manifest.deinit(); var old = try manifest.blockIndex(0); defer old.deinit(); try std.testing.expectEqual(@as(usize, 1), old.entries.len); try writeSegment(std.testing.allocator, io, dir, 0, &.{ 1, 2 }, true); try manifest.refresh(dir, 0, true); var current = try manifest.blockIndex(0); defer current.deinit(); try std.testing.expectEqual(@as(usize, 2), current.entries.len); try std.testing.expectEqual(@as(usize, 1), old.entries.len); try std.testing.expectEqual(@as(u64, 1), old.entries[0].max_seq); try std.testing.expectEqual(@as(usize, 1), stats.manifest_segments_loaded.load(.acquire)); try std.testing.expectEqual(@as(u64, 2), stats.manifest_block_index_load_count.load(.monotonic)); } test "invalidation failure leaves refreshed metadata owned and readable" { var threaded: Io.Threaded = .init(std.testing.allocator, .{}); defer threaded.deinit(); const io = threaded.io(); var tmp = std.testing.tmpDir(.{}); defer tmp.cleanup(); var dir = try tmp.dir.createDirPathOpen(io, "segments", .{ .open_options = .{ .iterate = true } }); defer dir.close(io); try writeSegment(std.testing.allocator, io, dir, 0, &.{1}, true); var manifest = try Manifest.init(std.testing.allocator, io, dir, null); defer manifest.deinit(); const Fail = struct { fn invalidate(_: ?*anyopaque, _: u64) anyerror!void { return error.OutOfMemory; } }; manifest.setInvalidator(null, Fail.invalidate); try writeSegment(std.testing.allocator, io, dir, 0, &.{ 1, 2 }, true); try std.testing.expectError(error.OutOfMemory, manifest.refresh(dir, 0, true)); // refresh committed its replacement before cache notification. Even when // notification cannot allocate, manifest ownership must remain valid so a // retry can invalidate without a dangling resident entry. var current = try manifest.blockIndex(0); defer current.deinit(); try std.testing.expectEqual(@as(usize, 2), current.entries.len); }