Zig 插件系统与动态加载：C ABI 契约、热重载与错误隔离

const std = @import("std");

pub fn loadPlugin(path: []const u8) !Plugin {
    var lib = try std.DynLib.open(path);   // 失败返回 error.FileNotFound / error.DlOpenFailed
    errdefer lib.close();
    // lookup 带类型参数返回 ?*T；符号不存在时返回 null，必须显式处理
    const init_fn = lib.lookup(*const fn (*const HostApi) callconv(.C) ?*anyopaque, "plugin_init")
        orelse return error.MissingSymbol;
    return .{ .lib = lib, .init = init_fn };
}

// 插件侧：src/plugin.zig
/// 宿主传给插件的接口表。extern struct 保证与 C 布局一致
pub const HostApi = extern struct {
    log: *const fn (level: u32, msg: [*:0]const u8) callconv(.C) void,
    alloc: *const fn (len: usize) callconv(.C) ?[*]u8,
    free: *const fn (ptr: [*]u8, len: usize) callconv(.C) void,
};

var host: *const HostApi = undefined;

export fn plugin_init(api: *const HostApi) callconv(.C) ?*anyopaque {
    host = api;
    const state = std.heap.page_allocator.create(State) catch return null;
    state.* = .{};
    return state;
}

export fn plugin_name() callconv(.C) [*:0]const u8 {
    return "echo";
}

/// 导出函数必须返回错误码而非 error union：Zig 的错误联合没有 C ABI
export fn plugin_process(ctx: ?*anyopaque, out_len: *usize) callconv(.C) i32 {
    const buf = doWork(@ptrCast(@alignCast(ctx.?))) catch |err| return switch (err) {
        error.OutOfMemory => -1,
        error.InvalidInput => -2,
    };
    out_len.* = buf.len;
    return 0;   // 0 表示成功
}

pub const ABI_VERSION: u32 = 3;
pub const CONTRACT_MAGIC: u32 = 0x504C5547;   // "PLUG"

/// 插件必须导出的元数据，宿主加载后第一件事就是读它
pub const PluginInfo = extern struct {
    magic: u32,             // 固定值，识别「这不是我们的插件」
    abi_version: u32,       // 契约版本
    struct_size: u32,       // sizeof(PluginInfo)，防字段增删导致的错位
    name: [*:0]const u8,
    capabilities: u32,      // 位图：声明支持哪些可选能力
};

export fn plugin_info() callconv(.C) *const PluginInfo {
    const info = PluginInfo{
        .magic = CONTRACT_MAGIC,
        .abi_version = ABI_VERSION,
        .struct_size = @sizeOf(PluginInfo),
        .name = "echo",
        .capabilities = 0b011,
    };
    return &info;
}

pub const Registry = struct {
    allocator: std.mem.Allocator,
    plugins: std.ArrayList(Loaded) = .empty,

    pub const Loaded = struct {
        lib: std.DynLib,
        ctx: ?*anyopaque,
        deinit: *const fn (?*anyopaque) callconv(.C) void,
    };

    pub fn loadDir(self: *Registry, dir_path: []const u8) !void {
        var dir = try std.fs.cwd().openDir(dir_path, .{ .iterate = true });
        defer dir.close();
        var it = dir.iterate();
        while (try it.next()) |entry| {
            if (entry.kind != .file or !std.mem.endsWith(u8, entry.name, ".so")) continue;
            const path = try std.fs.path.join(self.allocator, &.{ dir_path, entry.name });
            defer self.allocator.free(path);
            self.loadOne(path) catch |err| {   // 单个插件失败不影响其他
                std.log.warn("skip {s}: {s}", .{ entry.name, @errorName(err) });
            };
        }
    }

    fn loadOne(self: *Registry, path: []const u8) !void {
        var lib = try std.DynLib.open(path);
        errdefer lib.close();
        const info_fn = lib.lookup(*const fn () callconv(.C) *const PluginInfo, "plugin_info") orelse return error.MissingSymbol;
        const init_fn = lib.lookup(*const fn (*const HostApi) callconv(.C) ?*anyopaque, "plugin_init") orelse return error.MissingSymbol;
        const deinit_fn = lib.lookup(*const fn (?*anyopaque) callconv(.C) void, "plugin_deinit") orelse return error.MissingSymbol;
        try validate(info_fn());
        const ctx = init_fn(&host_api) orelse return error.InitFailed;
        try self.plugins.append(self.allocator, .{ .lib = lib, .ctx = ctx, .deinit = deinit_fn });
    }

    pub fn deinit(self: *Registry) void {
        for (self.plugins.items) |*p| {
            p.deinit(p.ctx);   // 先让插件清理自己的状态
            p.lib.close();     // 再卸载库
        }
        self.plugins.deinit(self.allocator);
    }
};

pub fn poll(self: *HotReloader, dir_path: []const u8) !void {
    var dir = try std.fs.cwd().openDir(dir_path, .{ .iterate = true });
    defer dir.close();
    var it = dir.iterate();
    while (try it.next()) |entry| {
        if (entry.kind != .file) continue;
        const gop = try self.mtimes.getOrPut(entry.name);
        const mtime = (try dir.statFile(entry.name)).mtime;
        if (!gop.found_existing) { gop.value_ptr.* = mtime; continue; }   // 首次见到，只记录
        if (gop.value_ptr.* != mtime) {                                    // 文件已更新
            gop.value_ptr.* = mtime;
            self.reload(entry.name) catch |err| std.log.err("reload {s}: {s}", .{ entry.name, @errorName(err) });
        }
    }
}

const builtin = @import("builtin");

pub fn libExtension() []const u8 {
    return switch (builtin.os.tag) {
        .windows => ".dll",
        .macos => ".dylib",
        else => ".so",
    };
}

const plugin = b.addSharedLibrary(.{
    .name = "echo",                       // 产出 libecho.so / echo.dll
    .root_module = b.createModule(.{ .root_source_file = b.path("src/plugin.zig"), .target = target, .optimize = optimize }),
});
b.installArtifact(plugin);

pub const Guarded = struct {
    failures: u32 = 0,
    disabled: bool = false,

    pub fn invoke(self: *Guarded, f: *const fn () callconv(.C) i32) i32 {
        if (self.disabled) return -3;                      // 已熔断，直接拒绝
        self.last_call_ns = std.time.nanoTimestamp();
        const rc = f();
        if (rc != 0) {                                     // 连续 5 次失败即熔断
            self.failures += 1;
            if (self.failures >= 5) self.disabled = true;
        } else self.failures = 0;
        return rc;
    }

};