Loading the module

The declaration: two hooks, no commands, no value types

// trafikey — the module declaration
valkey_module! {
    name: "trafikey",
    // the declaration's own number; EMQ.VERSION and TRA.CAPABILITIES report other strings
    version: 100,
    allocator: (ValkeyAlloc, ValkeyAlloc),
    // no module value type in the default build
    data_types: [],
    // the gate, before anything registers
    preload: preload,
    // the steps after every row has registered
    init: init,
    // no command from the macro: each one comes from a row of registry::TABLE
    commands: [],
}

Two hooks and two empty lists: the macro declares when the module checks, and the table declares what it serves.

The gate: three conditions, one match arm

// trafikey — preload, the gate the declaration names
/// Load gate, before anything registers: no module arguments, a Valkey 9.x host, and every
/// host API this module calls present. raw wrappers unwrap the host pointers and the release
/// profile aborts on panic, so a missing API must refuse the load instead of killing the node.
fn preload(ctx: &Context, args: &[ValkeyString]) -> Status {
    // one boolean over the whole API list (read below)
    let apis = registry::host_apis_present();
    // the server's own version; an Err here falls to the refusing arm
    match ctx.get_server_version() {
        // the API list, the loadmodule line's arguments, the major: all three or nothing
        Ok(v) if apis && args.is_empty() && v.major == 9 => Status::Ok,
        _ => Status::Err,
    }
}

# trafikist — the workspace release profile
[profile.release]
# …
panic = "abort"
# …
# Release abort semantics prevent unwinding across FFI; they do not provide panic recovery.

# trafikey — the host binding the crate compiles against
[dependencies]
# Pinned host binding: crates.io valkey-module 0.1.14 (checksummed; its feature set predates git 9ed1bbf,
# which adds a 9-0 feature). Bindgen runs over the crate's bundled header; the 9.x gate is in preload().
valkey-module = { version = "=0.1.14", default-features = false, features = ["min-valkey-compatibility-version-8-0"] }

The gate is the one place a host is judged: compiled against a binding at the Valkey 8 level, loaded only on a Valkey 9 server, with arguments refused outright.

The API half of the gate

// trafikey — registry::host_apis_present, the API half of the gate
macro_rules! all_present {
    ($($api:ident),* $(,)?) => { true $(&& unsafe { (*std::ptr::addr_of!(raw::$api)).is_some() })* };
}

/// The preload API gate: every host API this module calls is present. raw wrappers unwrap the
/// host pointers and the release profile aborts on panic, so a missing API must refuse the load.
pub fn host_apis_present() -> bool {
    all_present!(
        RedisModule_OpenKey,
        // …
        RedisModule_CreateCommand,
        RedisModule_GetCommand,
        RedisModule_SetCommandInfo,
        RedisModule_SetCommandACLCategories,
        // …
        // emq: the raw host adapter (emq/host.rs) and its replies.
        RedisModule_Call,
        // …
        RedisModule_CachedMicroseconds,
        RedisModule_AvoidReplicaTraffic,
        // …
        // the caller's ACL check, for keys outside a command's key-spec
        RedisModule_ACLCheckKeyPermissions,
        // …
        // the three server-info reads behind the epoch init loads
        RedisModule_GetServerInfo,
        RedisModule_ServerInfoGetFieldC,
        RedisModule_FreeServerInfo,
        // the context flags behind the server mode init records
        RedisModule_GetContextFlags,
    )
}

The API list is the module's whole contract with its host, checked once, before the first registration.

init, in order

// trafikey — init, after every row has registered
fn init(ctx: &Context, _: &[ValkeyString]) -> Status {
    // step 0, only in a build with the probe-type feature: the probe's module data type
    #[cfg(feature = "probe-type")]
    if probe_type::PROBE_TYPE.create_data_type(ctx.ctx).is_err() {
        return Status::Err;
    }
    // step 1: every row's ACL categories; a table that differs from the registered set refuses
    if registry::set_acl_categories(ctx) == Status::Err {
        return Status::Err;
    }
    // step 2: the server epoch, run_id, read once and held in memory; no key is written
    if let Err(e) = emq::epoch::load(ctx) {
        ctx.log_warning(&format!(
            "trafikey: emq epoch not loaded: {}",
            emq::errors::text(&e)
        ));
        return Status::Err;
    }
    // step 3: the server mode, read once; this step cannot refuse
    emq::host::load_mode(ctx);
    // step 4: the versioned shared C API, exported under its name for other modules
    registry::export_shared_api(
        ctx,
        c"trafikey_get_api_v1",
        tra::trafikey_get_api_v1 as *const std::ffi::c_void,
    );
    Status::Ok
}

// trafikey — emq::epoch::load, init's step 2
/// Reads `INFO server` `run_id` once (host.rs [`super::host::server_run_id`]) and caches it for
/// the process. A second call keeps the first value (one process, one `run_id`). A missing host
/// API or a malformed value refuses typed, and module init then refuses the load.
pub(crate) fn load(ctx: &Context) -> Result<(), ValkeyError> {
    let id = host::server_run_id(ctx)?;
    // exactly 40 lowercase hex characters, as the server prints a run_id
    if !valid_run_id(&id) {
        return Err(errors::emq(errors::HOST_CALL));
    }
    let _ = RUN_ID.set(id);
    Ok(())
}

// trafikey — registry::export_shared_api, init's step 4: one name, one pointer
pub fn export_shared_api(ctx: &Context, name: &CStr, api: *const c_void) {
    unsafe { raw::export_shared_api(ctx.ctx, api, name.as_ptr()) };
}

A fixed order with early returns: by the time init answers Status::Ok, the categories, the epoch and the mode are all in place.

Recap — loading the module

Next in this module: The registration table — one row per command, and everything that derives from it.

References