//! Durable lifecycle phase in the shared metadata database. const std = @import("std"); const meta_store = @import("../../storage/meta_store.zig"); const log = std.log.scoped(.stream); const key = "phase"; const entered_at_key = "phase/entered_at"; const backfill_started_at_key = "backfill/timing/started_at"; const backfill_completed_at_key = "backfill/timing/completed_at"; pub const Phase = enum { bootstrap, merging, steady_state }; /// Wall-clock span from entering bootstrap to the backfill engine draining and /// committing `merging`. Absent endpoints mean "not known", never "zero", so an /// operator cannot read an in-progress or pre-upgrade run as instantaneous. pub const BackfillTiming = struct { started_at_us: ?i64 = null, completed_at_us: ?i64 = null, pub fn durationUs(self: BackfillTiming) ?i64 { const started = self.started_at_us orelse return null; const completed = self.completed_at_us orelse return null; // A backwards clock must not render as a negative or huge duration. return if (completed < started) 0 else completed - started; } }; pub const Store = struct { meta: *meta_store.Store, pub fn init(meta: *meta_store.Store) Store { return .{ .meta = meta }; } pub fn deinit(_: *Store, _: std.Io) void {} pub fn read(self: *Store, _: std.Io) !?Phase { const maybe_bytes = try self.meta.getAlloc(self.meta.allocator, key); const bytes = maybe_bytes orelse return null; defer self.meta.allocator.free(bytes); return std.meta.stringToEnum(Phase, bytes) orelse error.InvalidLifecyclePhase; } /// When the current phase was entered. Null means the key is absent — a /// fresh data dir, or a run that pre-dates this field. A read failure or /// undecodable value propagates rather than reporting absence, so storage /// trouble can never be mistaken for a first boot. pub fn readEnteredAt(self: *Store, _: std.Io) !?i64 { return self.readTime(entered_at_key); } pub fn readBackfillTiming(self: *Store, _: std.Io) !BackfillTiming { return .{ .started_at_us = try self.readTime(backfill_started_at_key), .completed_at_us = try self.readTime(backfill_completed_at_key), }; } fn readTime(self: *Store, k: []const u8) !?i64 { const maybe_bytes = try self.meta.getAlloc(self.meta.allocator, k); const bytes = maybe_bytes orelse return null; defer self.meta.allocator.free(bytes); return std.fmt.parseInt(i64, bytes, 10) catch error.InvalidPhaseTimestamp; } pub fn write(self: *Store, io: std.Io, phase: Phase) !void { return self.writeAt(io, phase, std.Io.Timestamp.now(io, .real).toMicroseconds()); } /// Phase and its entry timestamp commit in one synced batch, as upstream's /// WritePhase does. Two separate durable writes would let a crash land a /// phase whose timestamp belongs to the previous one. pub fn writeAt(self: *Store, _: std.Io, phase: Phase, entered_at_us: i64) !void { var buf: [24]u8 = undefined; var batch = self.meta.batch(); defer batch.deinit(); batch.put(key, @tagName(phase)); batch.put(entered_at_key, std.fmt.bufPrint(&buf, "{d}", .{entered_at_us}) catch unreachable); try batch.commitDurable(); log.info("phase -> {s}", .{@tagName(phase)}); } /// Upstream's WritePhaseWithBackfillTiming: the transition that closes /// backfill publishes the phase and both timing endpoints together, so a /// reader never sees `merging` without the span that produced it. pub fn writeAtWithBackfillTiming( self: *Store, _: std.Io, phase: Phase, entered_at_us: i64, timing: BackfillTiming, ) !void { var entered_buf: [24]u8 = undefined; var started_buf: [24]u8 = undefined; var completed_buf: [24]u8 = undefined; var batch = self.meta.batch(); defer batch.deinit(); batch.put(key, @tagName(phase)); batch.put(entered_at_key, std.fmt.bufPrint(&entered_buf, "{d}", .{entered_at_us}) catch unreachable); if (timing.started_at_us) |v| batch.put(backfill_started_at_key, std.fmt.bufPrint(&started_buf, "{d}", .{v}) catch unreachable); if (timing.completed_at_us) |v| batch.put(backfill_completed_at_key, std.fmt.bufPrint(&completed_buf, "{d}", .{v}) catch unreachable); try batch.commitDurable(); log.info("phase -> {s}", .{@tagName(phase)}); } }; test "phase round-trip and first-boot null" { const testing = std.testing; var tmp = testing.tmpDir(.{}); defer tmp.cleanup(); var path_buf: [std.fs.max_path_bytes]u8 = undefined; const path_len = try tmp.dir.realPath(testing.io, &path_buf); var meta = try meta_store.Store.open(testing.allocator, path_buf[0..path_len]); defer meta.deinit(); var store = Store.init(&meta); try testing.expectEqual(@as(?Phase, null), try store.read(testing.io)); try store.write(testing.io, .bootstrap); try testing.expectEqual(@as(?Phase, .bootstrap), try store.read(testing.io)); try store.write(testing.io, .steady_state); try testing.expectEqual(@as(?Phase, .steady_state), try store.read(testing.io)); } test "phase corruption and storage errors fail closed" { const testing = std.testing; var tmp = testing.tmpDir(.{}); defer tmp.cleanup(); var path_buf: [std.fs.max_path_bytes]u8 = undefined; const path_len = try tmp.dir.realPath(testing.io, &path_buf); var meta = try meta_store.Store.open(testing.allocator, path_buf[0..path_len]); defer meta.deinit(); var store = Store.init(&meta); try meta.putDurable(key, "banana"); try testing.expectError(error.InvalidLifecyclePhase, store.read(testing.io)); try testing.expect(meta_store.armReadFault(key, 1)); defer meta_store.disarmReadFault(); try testing.expectError(error.InjectedStoreFault, store.read(testing.io)); } test "phase entry stamp and backfill timing survive reopen and fail closed" { const testing = std.testing; var tmp = testing.tmpDir(.{}); defer tmp.cleanup(); var path_buf: [std.fs.max_path_bytes]u8 = undefined; const path_len = try tmp.dir.realPath(testing.io, &path_buf); var meta = try meta_store.Store.open(testing.allocator, path_buf[0..path_len]); defer meta.deinit(); var store = Store.init(&meta); // Absent is absent, not zero: a fresh dir must not read as "entered at the // epoch" or "backfill took no time". try testing.expectEqual(@as(?i64, null), try store.readEnteredAt(testing.io)); const fresh = try store.readBackfillTiming(testing.io); try testing.expectEqual(@as(?i64, null), fresh.durationUs()); try store.writeAt(testing.io, .bootstrap, 1_000_000); try testing.expectEqual(@as(?i64, 1_000_000), try store.readEnteredAt(testing.io)); // A later transition republishes the stamp and both endpoints together. try store.writeAtWithBackfillTiming(testing.io, .merging, 9_000_000, .{ .started_at_us = 1_000_000, .completed_at_us = 7_500_000, }); try testing.expectEqual(@as(?Phase, .merging), try store.read(testing.io)); try testing.expectEqual(@as(?i64, 9_000_000), try store.readEnteredAt(testing.io)); const timing = try store.readBackfillTiming(testing.io); try testing.expectEqual(@as(?i64, 6_500_000), timing.durationUs()); } test "phase and its entry stamp commit atomically" { const testing = std.testing; var tmp = testing.tmpDir(.{}); defer tmp.cleanup(); var path_buf: [std.fs.max_path_bytes]u8 = undefined; const path_len = try tmp.dir.realPath(testing.io, &path_buf); var meta = try meta_store.Store.open(testing.allocator, path_buf[0..path_len]); defer meta.deinit(); var store = Store.init(&meta); try store.writeAt(testing.io, .bootstrap, 1_000_000); // Arm the *stamp* key specifically. Two separate durable writes would land // the new phase and then fail, leaving a phase carrying the previous // phase's stamp and misreporting how long it has run. One batch writes // both or neither. try testing.expect(meta_store.armFault(entered_at_key, 1)); defer meta_store.disarmFault(); try testing.expectError(error.InjectedStoreFault, store.writeAt(testing.io, .merging, 5_000_000)); meta_store.disarmFault(); try testing.expectEqual(@as(?Phase, .bootstrap), try store.read(testing.io)); try testing.expectEqual(@as(?i64, 1_000_000), try store.readEnteredAt(testing.io)); } test "a backwards clock never yields a negative backfill duration" { const timing: BackfillTiming = .{ .started_at_us = 5_000, .completed_at_us = 1_000 }; try std.testing.expectEqual(@as(?i64, 0), timing.durationUs()); const open: BackfillTiming = .{ .started_at_us = 5_000 }; try std.testing.expectEqual(@as(?i64, null), open.durationUs()); }