Struct PluginVTable 

#[repr(C)]
pub struct PluginVTable {
    pub api_version: u32,
    pub create: extern "C" fn() -> RResult<*mut c_void, RBoxError>,
    pub destroy: extern "C" fn(state: *mut c_void),
    pub init: extern "C" fn(state: *mut c_void, ctx: &PluginContext) -> RResult<(), RBoxError>,
    pub process: extern "C" fn(state: *const c_void, msg: &SpoeMessage) -> RResult<ProcessingResult, RBoxError>,
    pub name: extern "C" fn(state: *const c_void) -> RStr<'static>,
    pub plugin_version: extern "C" fn(state: *const c_void) -> RStr<'static>,
    pub shutdown: extern "C" fn(state: *const c_void),
    pub config_schema: extern "C" fn(state: *const c_void) -> ROption<RString>,
    pub validate: extern "C" fn(state: *const c_void, ctx: &PluginContext) -> RVec<Diagnostic>,
    pub set_metric_recorder: extern "C" fn(state: *mut c_void, record_fn: RecordMetricFn, ctx: *const c_void),
    pub drain: extern "C" fn(state: *const c_void, timeout_ms: u64) -> bool,
}

The function table a plugin shared library exports.

#[repr(C)] is mandatory: it pins field offsets and padding rules so plugins built against an older version of this crate keep working when the hub is built against a newer one (and vice versa).

Safety contract for hosts

Fields below the v1 baseline marker are version-gated. Hosts MUST NOT access them via &PluginVTable directly — the borrow would implicitly cover the whole struct, which on an older plugin is past the end of its allocation. Use the read_*_field accessors or read individual fields through the raw pointer (e.g. unsafe { (*ptr).api_version }) which read only the bytes for that field.

Fields

api_version: u32

Plugin’s reported API version. The hub uses this to gate access to fields beyond the v1 baseline.

create: extern "C" fn() -> RResult<*mut c_void, RBoxError>

Factory: allocate and return a new plugin state pointer. RErr aborts plugin loading.

destroy: extern "C" fn(state: *mut c_void)

Destructor: free the plugin state pointer. Called once at hub shutdown or when a plugin fails post-create. MUST tolerate being called with a state pointer that init() has not yet observed.

init: extern "C" fn(state: *mut c_void, ctx: &PluginContext) -> RResult<(), RBoxError>

Initialize the plugin. Called once after create and any schema/validate pre-checks. RErr aborts plugin loading.

process: extern "C" fn(state: *const c_void, msg: &SpoeMessage) -> RResult<ProcessingResult, RBoxError>

Handle one SPOE message. Called per request. The implementation is wrapped in catch_unwind by the define_plugin! macro so a panic does not abort the hub process.

name: extern "C" fn(state: *const c_void) -> RStr<'static>

Plugin’s display name. Borrowed for the lifetime of the plugin instance (until destroy is called). Plugins typically return a &'static str literal.

plugin_version: extern "C" fn(state: *const c_void) -> RStr<'static>

Plugin’s SemVer string. Same lifetime contract as name.

shutdown: extern "C" fn(state: *const c_void)

Shutdown hook. Called once before destroy.

config_schema: extern "C" fn(state: *const c_void) -> ROption<RString>

Optional JSON Schema string for config validation. RNone skips schema validation. The default define_plugin! macro emits a thunk that returns RNone when the plugin author has not declared one.

validate: extern "C" fn(state: *const c_void, ctx: &PluginContext) -> RVec<Diagnostic>

Deep config validation. Returns an empty RVec when the plugin’s config is valid. Errors block loading; warnings are surfaced but do not block.

set_metric_recorder: extern "C" fn(state: *mut c_void, record_fn: RecordMetricFn, ctx: *const c_void)

Install the hub’s metric recorder on the plugin. Called by the hub once between create and init, so the plugin can emit metrics from init onward. The plugin stores the record_fn and ctx (typically inside a MetricRecorder field of its state) and invokes record_fn(ctx, ...) for every metric event. The recorder remains valid until destroy returns; the hub guarantees lifetime, the plugin guarantees not to call it after destroy.

Plugins that don’t want metrics still need to provide a thunk (the define_plugin! macro emits a no-op default) — the field is unconditionally read on v2 hubs.

Host access: gated on api_version >= PLUGIN_API_VERSION_V2. Reading this field on a v1 plugin’s vtable is UB — the v1 allocation does not include these bytes.

drain: extern "C" fn(state: *const c_void, timeout_ms: u64) -> bool

Block until the plugin’s in-flight background work has completed or timeout_ms milliseconds have elapsed. Called by the hub on a config reload between the registry swap and the call to shutdown, so plugins with fire-and-forget tasks (mirror’s runtime.spawn’d HTTP dispatches; otel’s batched exporter queue) can finish ACK’d requests before their runtime is torn down.

Returns true if the plugin reports it has nothing more in flight (clean drain). Returns false if the timeout elapsed while in-flight work was still pending (forced shutdown — the hub will still proceed with shutdown, the open requests are lost). Plugins MUST treat the timeout as advisory — going over is acceptable in narrow margins, but the hub’s overall reload SLO depends on drain respecting the deadline.

process() calls landing on this plugin instance AFTER drain is invoked are still serviced; the hub’s swap happens before drain, so post-swap traffic goes to the NEW registry. Drain concerns only work already in flight against this (now-old) instance.

Plugins with no background state (synchronous handlers that complete inside process()) get the define_plugin! macro’s default thunk which returns true immediately — nothing to wait for. Plugins that spawn background tasks SHOULD override drain to wait on their in-flight counter.

Host access: gated on api_version >= PLUGIN_API_VERSION_V3. Reading this field on a v1 or v2 plugin’s vtable is UB — those allocations do not include these bytes. The hub treats older plugins as “drained immediately” because those plugins have no in-flight background state in practice (coraza, external-auth, fingerprinting, maxmind, otel pre-v0.4, sso-auth all complete their work inside process()).

Implementations

impl PluginVTable

pub unsafe fn read_api_version(vtable_ptr: *const PluginVTable) -> u32

Read just the api_version field of a plugin’s vtable.

Safety

vtable_ptr must be a non-null pointer to a PluginVTable allocation that is at least 4 bytes long (every plugin has at least the api_version field).

pub unsafe fn read_set_metric_recorder( vtable_ptr: *const PluginVTable, ) -> Option<extern "C" fn(state: *mut c_void, record_fn: RecordMetricFn, ctx: *const c_void)>

Read the v2 set_metric_recorder field, returning None for plugins built against v1 (whose allocation doesn’t include it).

Safety

vtable_ptr must be a non-null pointer to a PluginVTable allocation produced by a published plugin (i.e. consistent with the api_version field’s claim about which fields are present). On v1 plugins this function reads only api_version and returns None without touching past the v1 baseline.

pub unsafe fn read_drain( vtable_ptr: *const PluginVTable, ) -> Option<extern "C" fn(state: *const c_void, timeout_ms: u64) -> bool>

Read the v3 drain field, returning None for plugins built against v1 or v2 (whose allocation doesn’t include it). The hub treats None as “drained immediately” — see the field’s doc comment for the rationale (older plugins are synchronous).

Safety

vtable_ptr must be a non-null pointer to a PluginVTable allocation produced by a published plugin (i.e. consistent with the api_version field’s claim about which fields are present). On v1/v2 plugins this function reads only api_version and returns None without touching past the relevant baseline.