Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python
7.9 KB
Raw Blame
//! Durable shell handles. The numeric wire stays exact in JavaScript; the new
//! namespace cannot overlap any legacy u32 handle retained in saved history.
const std = @import("std");
const builtin = @import("builtin");
const Io = std.Io;
pub const Id = u64;
pub const first: Id = 1 << 32;
pub const last: Id = (1 << 53) - 1;
const marker = "shell-ids-v1\n";
const private_file = @import("credential_store.zig").private_file;
var test_mutex: Io.Mutex = .init;
var test_home: ?[]const u8 = null;

/// Existing job tests still exercise this allocator, in a private test-only
/// directory rather than the user's HOME. Dedicated tests call reserve directly.
pub fn forJob(io: Io) !Id {
    if (builtin.is_test) {
        test_mutex.lockUncancelable(io);
        defer test_mutex.unlock(io);
        if (test_home == null) {
            var tmp = std.testing.tmpDir(.{});
            var buf: [std.fs.max_path_bytes]u8 = undefined;
            const n = try tmp.dir.realPath(io, &buf);
            test_home = try std.heap.page_allocator.dupe(u8, buf[0..n]);
            tmp.dir.close(io);
            tmp.parent_dir.close(io);
        }
        return reserve(io, test_home.?);
    }
    const home = @import("job_registry.zig").home;
    // #1619: an fd or lock hiccup cleared on its own a moment later, while
    // the message blamed HOME's permissions. Retry those, and keep the cause.
    var attempt: u8 = 0;
    while (true) : (attempt += 1) {
        return reserve(io, home) catch |err| switch (err) {
            error.ShellIdentityHomeRequired, error.ShellIdentityStoreInvalid, error.ShellIdentityExhausted => return err,
            error.Canceled => return err,
            else => {
                if (!storageFault(err) and attempt < 3) {
                    io.sleep(.fromMilliseconds(25), .awake) catch return err;
                    continue;
                }
                last_cause = err;
                return error.ShellIdentityUnavailable;
            },
        };
    }
}

/// The underlying error behind the last ShellIdentityUnavailable.
pub threadlocal var last_cause: ?anyerror = null;

/// Errors that say HOME's storage itself is unusable; retrying cannot help.
pub fn storageFault(err: anyerror) bool {
    return switch (err) {
        error.AccessDenied, error.PermissionDenied, error.ReadOnlyFileSystem, error.NoSpaceLeft, error.NotDir, error.FileNotFound, error.SymLinkLoop, error.NameTooLong, error.BadPathName, error.DiskQuota => true,
        else => false,
    };
}

fn readCounter(io: Io, dir: Io.Dir, name: []const u8) !Id {
    var buf: [64]u8 = undefined;
    const data = dir.readFile(io, name, &buf) catch return error.ShellIdentityStoreInvalid;
    if (data.len < 2 or data[data.len - 1] != '\n') return error.ShellIdentityStoreInvalid;
    const n = std.fmt.parseInt(Id, data[0 .. data.len - 1], 10) catch return error.ShellIdentityStoreInvalid;
    if (n < first - 1 or n > last) return error.ShellIdentityStoreInvalid;
    return n;
}

fn writeCounter(io: Io, dir: Io.Dir, name: []const u8, n: Id) !void {
    var buf: [32]u8 = undefined;
    const data = try std.fmt.bufPrint(&buf, "{d}\n", .{n});
    try @import("credential_store.zig").replaceFile(io, dir, name, data, private_file);
}

pub fn reserve(io: Io, home: []const u8) !Id {
    for (0..50) |_| {
        return reserveLocked(io, home) catch |err| {
            if (err != error.ShellIdentityInitializing) return err;
            // Release the advisory lock before the creator can initialize it.
            try io.sleep(.fromMilliseconds(10), .awake);
            continue;
        };
    }
    return error.ShellIdentityStoreInvalid;
}

fn reserveLocked(io: Io, home: []const u8) !Id {
    if (home.len == 0) return error.ShellIdentityHomeRequired;
    var buf: [std.fs.max_path_bytes]u8 = undefined;
    const path = try std.fmt.bufPrint(&buf, "{s}/.codegraff", .{home});
    Io.Dir.cwd().createDir(io, path, @import("credential_store.zig").private_dir) catch |err| {
        if (err != error.PathAlreadyExists) return err;
    };
    var dir = try Io.Dir.cwd().openDir(io, path, .{});
    defer dir.close(io);
    var fresh = true;
    const lock = dir.createFile(io, "shell-id.lock", .{
        .read = true,
        .truncate = false,
        .exclusive = true,
        .lock = .exclusive,
        .permissions = private_file,
    }) catch |err| blk: {
        if (err != error.PathAlreadyExists) return err;
        fresh = false;
        break :blk try dir.openFile(io, "shell-id.lock", .{ .mode = .read_write, .lock = .exclusive });
    };
    defer lock.close(io);
    if (fresh) {
        if (builtin.os.tag != .windows) {
            // The first reserver may not be the process that created the
            // directory. Sync its parent before initializing durable state.
            const parent = try Io.Dir.cwd().openFile(io, home, .{ .allow_directory = true });
            defer parent.close(io);
            try parent.sync(io);
        }
        // Existing counters without their initialization marker are not a new
        // store. Do not reset them after deletion/replacement of the lock file.
        if (dir.statFile(io, "shell-id.counter", .{})) |_| return error.ShellIdentityStoreInvalid else |e| if (e != error.FileNotFound) return e;
        try lock.writePositionalAll(io, marker, 0);
        try lock.sync(io);
        try writeCounter(io, dir, "shell-id.counter", first - 1);
    } else {
        var content: [32]u8 = undefined;
        const n = try lock.readPositionalAll(io, &content, 0);
        if (n == 0) return error.ShellIdentityInitializing;
        if (!std.mem.eql(u8, content[0..n], marker)) return error.ShellIdentityStoreInvalid;
    }
    const current = try readCounter(io, dir, "shell-id.counter");
    if (current == last) return error.ShellIdentityExhausted;
    const next = current + 1;
    // Atomic replacement yields the old or new valid counter after a crash.
    // Spawn happens only after the new counter and directory entry are synced.
    try writeCounter(io, dir, "shell-id.counter", next);
    return next;
}

test "shell identity reservations survive a fresh allocator and remain JS exact" {
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    var buf: [std.fs.max_path_bytes]u8 = undefined;
    const n = try tmp.dir.realPath(std.testing.io, &buf);
    try std.testing.expectEqual(first, try reserve(std.testing.io, buf[0..n]));
    try std.testing.expectEqual(first + 1, try reserve(std.testing.io, buf[0..n]));
    try std.testing.expect(last <= 9007199254740991);
    try std.testing.expectError(error.ShellIdentityHomeRequired, reserve(std.testing.io, ""));
}

test "shell identity fails closed on missing corrupt or exhausted storage" {
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    var buf: [std.fs.max_path_bytes]u8 = undefined;
    const n = try tmp.dir.realPath(io, &buf);
    const home = buf[0..n];
    _ = try reserve(io, home);
    var dir = try tmp.dir.openDir(io, ".codegraff", .{});
    defer dir.close(io);
    try dir.deleteFile(io, "shell-id.counter");
    try std.testing.expectError(error.ShellIdentityStoreInvalid, reserve(io, home));
    // An initializer killed after syncing its marker must never reset IDs.
    try std.testing.expectError(error.ShellIdentityStoreInvalid, reserve(io, home));
    try dir.writeFile(io, .{ .sub_path = "shell-id.lock", .data = "" });
    try std.testing.expectError(error.ShellIdentityStoreInvalid, reserve(io, home));
    try dir.writeFile(io, .{ .sub_path = "shell-id.lock", .data = marker });
    try dir.writeFile(io, .{ .sub_path = "shell-id.counter", .data = "bad" });
    try std.testing.expectError(error.ShellIdentityStoreInvalid, reserve(io, home));
    try writeCounter(io, dir, "shell-id.counter", last);
    try std.testing.expectError(error.ShellIdentityExhausted, reserve(io, home));
    try dir.deleteFile(io, "shell-id.lock");
    try std.testing.expectError(error.ShellIdentityStoreInvalid, reserve(io, home));
}