The shared ABI and bundled Lua

One getter, exported at load

// trafikey — init, its last step: the getter exported under its name
fn init(ctx: &Context, _: &[ValkeyString]) -> Status {
    // … the earlier steps of init
    registry::export_shared_api(
        ctx,
        c"trafikey_get_api_v1",
        tra::trafikey_get_api_v1 as *const std::ffi::c_void,
    );
    Status::Ok
}

One name in the server’s registry is the whole native surface another module can reach.

A table negotiated by version and size

// trafikey — include/trafikey.h, the public header, from its first comment
/* Unreleased ABI 1 candidate. GetSharedAPI(ctx, "trafikey_get_api_v1") returns
 * TrafikeyGetApiV1. Negotiate version, struct size and feature bits first.
 * Script bytes are length-delimited, immutable, module-owned and not necessarily
 * NUL-terminated. Never free them or retain them beyond provider lifetime.
 * The original prefix through lua_source is unchanged; catalog is appended.
 * No dataset access or authorization bypass is exposed by this table. */
typedef struct TrafikeyApiV1 {
    uint32_t abi_version;
    uint32_t struct_size;
    uint64_t feature_bits;
    const uint8_t *(*lua_source)(size_t *length);
    const uint8_t *(*lua_source_by_id)(uint32_t id, size_t *length);
} TrafikeyApiV1;
typedef const TrafikeyApiV1 *(*TrafikeyGetApiV1)(uint32_t version, uint32_t minimum_size);
#define TRAFIKEY_FEATURE_LUA_CAPABILITIES UINT64_C(1)
#define TRAFIKEY_FEATURE_LUA_BITMAP_COUNT UINT64_C(2)
#define TRAFIKEY_FEATURE_LUA_FUNCTIONS UINT64_C(4)
#define TRAFIKEY_FEATURE_LUA_CATALOG UINT64_C(8)
#define TRAFIKEY_LUA_CAPABILITIES UINT32_C(0)
#define TRAFIKEY_LUA_BITMAP_COUNT UINT32_C(1)
#define TRAFIKEY_LUA_FUNCTIONS UINT32_C(2)
/* Request this prefix size only when using the old lua_source field. */
#define TRAFIKEY_API_V1_PREFIX_SIZE ((uint32_t)offsetof(TrafikeyApiV1, lua_source_by_id))

// trafikey — tra::TrafikeyApiV1, the table it shares and the getter it exports
#[repr(C)]
pub struct TrafikeyApiV1 {
    pub abi_version: u32,
    pub struct_size: u32,
    pub feature_bits: u64,
    pub lua_source: unsafe extern "C" fn(*mut usize) -> *const u8,
    pub lua_source_by_id: unsafe extern "C" fn(u32, *mut usize) -> *const u8,
}
// …
static SHARED: TrafikeyApiV1 = TrafikeyApiV1 {
    abi_version: 1,
    struct_size: std::mem::size_of::<TrafikeyApiV1>() as u32,
    feature_bits: 15,
    lua_source,
    lua_source_by_id,
};

#[no_mangle]
pub extern "C" fn trafikey_get_api_v1(version: u32, minimum_size: u32) -> *const TrafikeyApiV1 {
    if version != 1 || minimum_size > SHARED.struct_size {
        return std::ptr::null();
    }
    &SHARED
}

// trafikey — the three sources compiled in, and the selector that hands them out
static LUA: &[u8] = include_bytes!("../../../lua/capabilities.lua");
static BITMAP_LUA: &[u8] = include_bytes!("../../../lua/bitmap_count.lua");
static FUNCTIONS_LUA: &[u8] = include_bytes!("../../../lua/functions.lua");
// …
unsafe extern "C" fn lua_source_by_id(id: u32, length: *mut usize) -> *const u8 {
    if length.is_null() {
        return std::ptr::null();
    }
    let bytes = match id {
        0 => LUA,
        1 => BITMAP_LUA,
        2 => FUNCTIONS_LUA,
        _ => {
            // an unknown id: length 0 through the caller's pointer, and NULL
            unsafe {
                *length = 0;
            }
            return std::ptr::null();
        }
    };
    // a known id: its byte length through the caller's pointer, then the module-owned bytes
    unsafe {
        *length = bytes.len();
    }
    bytes.as_ptr()
}

Version, then size, then id: every request the table cannot answer is NULL, and every answer it gives is bytes the module keeps.

Three sources

-- trafikey bundled source 0, capabilities.lua — the whole file
#!lua flags=no-writes

-- Native module metadata only; no automatic installation or hidden keys.
if #KEYS ~= 0 or #ARGV ~= 0 then
    return redis.error_reply('ERR TRA arguments: no keys or arguments expected')
end
return redis.call('TRA.CAPABILITIES')

-- trafikey bundled source 1, bitmap_count.lua — the whole file
#!lua flags=no-writes

-- Existing ordinary bitmap-string slice; no custom type, hidden keys or writes.
local function bitmap_count(keys, args)
    if #keys ~= 1 or #args ~= 2 then
        return redis.error_reply('ERR TRA.LUA expected one key, start_byte and byte_count')
    end
    local function decimal(s)
        -- Bound parser work before pattern matching, including invalid input.
        if type(s) ~= 'string' or #s < 1 or #s > 9 then return nil end
        if not string.match(s, '^[0-9]+$') then return nil end
        if #s > 1 and string.sub(s, 1, 1) == '0' then return nil end
        return tonumber(s)
    end
    local start = decimal(args[1])
    local count = decimal(args[2])
    -- API work bound; not a Valkey memory/thread/latency tuning recommendation.
    if not start or not count or count < 1 or count > 4096
       or start > 536870911 or start + count > 536870912 then
        return redis.error_reply('ERR TRA.LUA invalid or excessive byte range')
    end
    local length = redis.call('STRLEN', keys[1])
    local cardinality = redis.call('BITCOUNT', keys[1], start, start + count - 1, 'BYTE')
    return {'trafikey.bitmap_count.v1', length, cardinality}
end

return bitmap_count(KEYS, ARGV)

-- trafikey bundled source 2, functions.lua — the library header and its two registrations
#!lua name=trafikey

-- Explicit installation only; never automatically replace an existing library.
-- … the bitmap_count function: the same code as source 1's
redis.register_function{
    function_name = 'trafikey_capabilities',
    callback = function(keys, args)
        if #keys ~= 0 or #args ~= 0 then
            return redis.error_reply('ERR TRA arguments: no keys or arguments expected')
        end
        return redis.call('TRA.CAPABILITIES')
    end,
    flags = {'no-writes'}
}
redis.register_function{
    function_name = 'trafikey_bitmap_count_v1',
    callback = bitmap_count,
    flags = {'no-writes'}
}

The bundled count is the server’s own STRLEN and BITCOUNT behind a strict, bounded argument check, on any route that runs it.

Installing is an authorized step

# deploy — README, the two explicit routes (angle brackets are placeholders)
SCRIPT LOAD <exact reviewed bytes of lua/bitmap_count.lua>
EVALSHA_RO <returned SHA> 1 <authorized-existing-string-key> 0 2
=> ["trafikey.bitmap_count.v1", <logical length>, <exact count in bytes 0 and 1>]

FUNCTION LOAD <exact reviewed bytes of lua/functions.lua>
FCALL_RO trafikey_bitmap_count_v1 1 <authorized-existing-string-key> 0 2

The module ships bytes; an authorized caller decides whether they become a script or a library, and reloads them by hand when the cache is cold.

Pattern & implementation

References