Feat: Initialize Plugin Type and Hook Types

Author: krishnadubagunta

build.zig

@@ -0,0 +1,63 @@
+const std = @import("std");
+
+// Although this function looks imperative, it does not perform the build
+// directly and instead it mutates the build graph (`b`) that will be then
+// executed by an external runner. The functions in `std.Build` implement a DSL
+// for defining build steps and express dependencies between them, allowing the
+// build runner to parallelize the build automatically (and the cache system to
+// know when a step doesn't need to be re-run).
+pub fn build(b: *std.Build) void {
+    // Standard target options allow the person running `zig build` to choose
+    // what target to build for. Here we do not override the defaults, which
+    // means any target is allowed, and the default is native. Other options
+    // for restricting supported target set are available.
+    const target = b.standardTargetOptions(.{});
+
+    // This creates a module, which represents a collection of source files alongside
+    // some compilation options, such as optimization mode and linked system libraries.
+    // Zig modules are the preferred way of making Zig code available to consumers.
+    // addModule defines a module that we intend to make available for importing
+    // to our consumers. We must give it a name because a Zig package can expose
+    // multiple modules and consumers will need to be able to specify which
+    // module they want to access.
+    const mod = b.addModule("plumplugin", .{
+        // The root source file is the "entry point" of this module. Users of
+        // this module will only be able to access public declarations contained
+        // in this file, which means that if you have declarations that you
+        // intend to expose to consumers that were defined in other files part
+        // of this module, you will have to make sure to re-export them from
+        // the root file.
+        .root_source_file = b.path("src/root.zig"),
+        // Later on we'll use this module as the root module of a test executable
+        // which requires us to specify a target.
+        .target = target,
+    });
+
+    // Creates an executable that will run `test` blocks from the provided module.
+    // Here `mod` needs to define a target, which is why earlier we made sure to
+    // set the releative field.
+    const mod_tests = b.addTest(.{
+        .root_module = mod,
+    });
+
+    // A run step that will run the test executable.
+    const run_mod_tests = b.addRunArtifact(mod_tests);
+
+    // A top level step for running all tests. dependOn can be called multiple
+    // times and since the two run steps do not depend on one another, this will
+    // make the two of them run in parallel.
+    const test_step = b.step("test", "Run tests");
+    test_step.dependOn(&run_mod_tests.step);
+
+    // Just like flags, top level steps are also listed in the `--help` menu.
+    //
+    // The Zig build system is entirely implemented in userland, which means
+    // that it cannot hook into private compiler APIs. All compilation work
+    // orchestrated by the build system will result in other Zig compiler
+    // subcommands being invoked with the right flags defined. You can observe
+    // these invocations when one fails (or you pass a flag to increase
+    // verbosity) to validate assumptions and diagnose problems.
+    //
+    // Lastly, the Zig build system is relatively simple and self-contained,
+    // and reading its source code will allow you to master it.
+}

build.zig.zon

@@ -0,0 +1,81 @@
+.{
+    // This is the default name used by packages depending on this one. For
+    // example, when a user runs `zig fetch --save <url>`, this field is used
+    // as the key in the `dependencies` table. Although the user can choose a
+    // different name, most users will stick with this provided value.
+    //
+    // It is redundant to include "zig" in this name because it is already
+    // within the Zig package namespace.
+    .name = .plumplugin,
+    // This is a [Semantic Version](https://semver.org/).
+    // In a future version of Zig it will be used for package deduplication.
+    .version = "1.0.0",
+    // Together with name, this represents a globally unique package
+    // identifier. This field is generated by the Zig toolchain when the
+    // package is first created, and then *never changes*. This allows
+    // unambiguous detection of one package being an updated version of
+    // another.
+    //
+    // When forking a Zig project, this id should be regenerated (delete the
+    // field and run `zig build`) if the upstream project is still maintained.
+    // Otherwise, the fork is *hostile*, attempting to take control over the
+    // original project's identity. Thus it is recommended to leave the comment
+    // on the following line intact, so that it shows up in code reviews that
+    // modify the field.
+    .fingerprint = 0xf9e9abb823c14aea, // Changing this has security and trust implications.
+    // Tracks the earliest Zig version that the package considers to be a
+    // supported use case.
+    .minimum_zig_version = "0.15.1",
+    // This field is optional.
+    // Each dependency must either provide a `url` and `hash`, or a `path`.
+    // `zig build --fetch` can be used to fetch all dependencies of a package, recursively.
+    // Once all dependencies are fetched, `zig build` no longer requires
+    // internet connectivity.
+    .dependencies = .{
+        // See `zig fetch --save <url>` for a command-line interface for adding dependencies.
+        //.example = .{
+        //    // When updating this field to a new URL, be sure to delete the corresponding
+        //    // `hash`, otherwise you are communicating that you expect to find the old hash at
+        //    // the new URL. If the contents of a URL change this will result in a hash mismatch
+        //    // which will prevent zig from using it.
+        //    .url = "https://example.com/foo.tar.gz",
+        //
+        //    // This is computed from the file contents of the directory of files that is
+        //    // obtained after fetching `url` and applying the inclusion rules given by
+        //    // `paths`.
+        //    //
+        //    // This field is the source of truth; packages do not come from a `url`; they
+        //    // come from a `hash`. `url` is just one of many possible mirrors for how to
+        //    // obtain a package matching this `hash`.
+        //    //
+        //    // Uses the [multihash](https://multiformats.io/multihash/) format.
+        //    .hash = "...",
+        //
+        //    // When this is provided, the package is found in a directory relative to the
+        //    // build root. In this case the package's hash is irrelevant and therefore not
+        //    // computed. This field and `url` are mutually exclusive.
+        //    .path = "foo",
+        //
+        //    // When this is set to `true`, a package is declared to be lazily
+        //    // fetched. This makes the dependency only get fetched if it is
+        //    // actually used.
+        //    .lazy = false,
+        //},
+    },
+    // Specifies the set of files and directories that are included in this package.
+    // Only files and directories listed here are included in the `hash` that
+    // is computed for this package. Only files listed here will remain on disk
+    // when using the zig package manager. As a rule of thumb, one should list
+    // files required for compilation plus any license(s).
+    // Paths are relative to the build root. Use the empty string (`""`) to refer to
+    // the build root itself.
+    // A directory listed here means that all files within, recursively, are included.
+    .paths = .{
+        "build.zig",
+        "build.zig.zon",
+        "src",
+        // For example...
+        //"LICENSE",
+        //"README.md",
+    },
+}

src/root.zig

@@ -0,0 +1,89 @@
+//! This module defines the plugin system for PlumCache.
+//!
+//! The plugin system enables extensibility through hooks that can intercept and modify
+//! database operations at various points in their execution lifecycle. This allows
+//! for custom functionality such as validation, transformation, logging, and more,
+//! without modifying the core database code.
+//!
+//! The main components are:
+//! - `HookType`: An enumeration of the available interception points
+//! - `Plugin`: A structure that defines a plugin's metadata and execution function
+
+/// `HookType` defines the points in the database operation lifecycle where plugins can intercept.
+///
+/// Each hook type represents a specific moment during data operations:
+/// - `Before*` hooks run before an operation is performed, allowing for validation or modification
+/// - `After*` hooks run after an operation completes, enabling post-processing or side effects
+///
+/// This enum-based approach allows for type-safe hook registration and dispatch.
+const std = @import("std");
+const builtin = @import("builtin");
+const native = builtin.os;
+
+pub const HookType = enum {
+    /// Triggered before retrieving a key's value
+    BeforeGet,
+    /// Triggered before saving a key-value pair
+    BeforeSave,
+    /// Triggered before deleting a key
+    BeforeDelete,
+    /// Triggered after retrieving a key's value
+    AfterGet,
+    /// Triggered after saving a key-value pair
+    AfterSave,
+    /// Triggered after deleting a key
+    AfterDelete,
+};
+
+/// `Plugin` represents an extension module that can hook into the database operations.
+///
+/// Each plugin has:
+/// - A name for identification
+/// - A hook type specifying when it should be executed
+/// - A function that will be called when the hook triggers
+///
+/// The plugin's run function receives the operation's key and value as parameters,
+/// allowing it to inspect or modify the data being processed.
+pub const Plugin = struct {
+    /// Unique identifier for the plugin
+    name: []const u8,
+    /// The point in execution where this plugin should be triggered
+    hook: HookType,
+    /// Function to call when the hook is triggered.
+    ///
+    /// Parameters:
+    ///   - `key`: The key involved in the database operation.
+    ///   - `value`: The value involved in the database operation.
+    ///
+    /// Returns:
+    ///   - `void`. This function does not return a value.
+    run: *const fn (key: []u8, value: []u8) void,
+
+    fn init(name: []u8) Plugin {
+        const dynLib = loadSystemLibrary(name);
+        const run = dynLib.findSymbol("run") orelse return error.SymbolNotFound;
+        return @ptrCast(run());
+    }
+
+    pub fn loadSystemLibrary(lib_name: []const u8) !std.DynLib {
+        var buffer: [128]u8 = undefined;
+
+        // Construct correct library filename for Linux and macOS
+        const lib_full_name = switch (std.builtin.os.tag) {
+            .linux => blk: {
+                const len = try std.fmt.bufPrint(&buffer, "lib{s}.so", .{lib_name});
+                break :blk buffer[0..len];
+            },
+            .macos => blk: {
+                const len = try std.fmt.bufPrint(&buffer, "lib{s}.dylib", .{lib_name});
+                break :blk buffer[0..len];
+            },
+            else => return error.UnsupportedOS,
+        };
+
+        std.debug.print("Loading system library: {s}\n", .{lib_full_name});
+
+        // Load library from native OS paths
+        return std.DynLib.open(lib_full_name);
+    }
+};