Crate haproxy_spoa_hub_plugin_api 

Plugin API for haproxy-spoa-hub.

ABI model

Plugins are loaded from .so files at runtime via dlopen. The interface between hub and plugin is a hand-rolled #[repr(C)] vtable defined in vtable::PluginVTable, reached via the exported get_plugin_vtable symbol.

See vtable for the load-bearing layout invariants and version evolution rules. In short: append-only, never reorder, never remove, version-gate every new field on the host. The matrix test in crates/hub/tests/abi_matrix.rs enforces these invariants by loading every published plugin version against the current hub.

Layout discipline for data types

PluginContext, SpoeMessage, ProcessingResult, Diagnostic, ConfigValue, SpoeValue, TxnVariable, and VarScope are all #[derive(StableAbi)] which gives them #[repr(C)] layout. Existing fields MUST NOT be reordered or removed. Adding a field is a layout change that requires a coordinated plugin-api version bump (and is itself a separate concern from vtable evolution — there is no per-field version-gating on data types).

abi_stable is pinned to =0.11.3 in Cargo.toml so plugins and hub see byte-identical RString / RVec / etc. across the FFI boundary. Bumping that pin is a coordinated rollout, not a routine patch.

Re-exports

pub use logging::HUB_LOG_SINK;

pub use logging::HubLogSink;

pub use logging::LogLevel;

pub use logging::LogSinkFn;

pub use metrics::MetricKind;

pub use metrics::MetricLabel;

pub use metrics::MetricRecorder;

pub use metrics::RecordMetricFn;

pub use types::ConfigValue;

pub use types::Diagnostic;

pub use types::DiagnosticSeverity;

pub use types::PluginContext;

pub use types::ProcessingResult;

pub use types::SpoeMessage;

pub use types::SpoeValue;

pub use types::TxnVariable;

pub use types::VarScope;

pub use vtable::GET_PLUGIN_VTABLE_SYMBOL;

pub use vtable::GetPluginVTableFn;

pub use vtable::PLUGIN_API_VERSION;

pub use vtable::PLUGIN_API_VERSION_V1;

pub use vtable::PLUGIN_API_VERSION_V2;

pub use vtable::PLUGIN_API_VERSION_V3;

pub use vtable::PLUGIN_API_VERSION_V4;

pub use vtable::PluginVTable;

pub use abi_stable;

Modules

logging

Forwarding of a plugin’s log records to the hub.

metrics

FFI-safe metric types and the recorder helper plugins use to emit Prometheus metrics through the hub.

types

vtable

Hand-rolled #[repr(C)] plugin vtable.

Macros

define_plugin

Define a plugin and emit the FFI surface (vtable + entry symbol).

Structs

PluginPanicError

Error raised when a plugin’s process panics. Wrapped in RBoxError by the define_plugin! macro’s panic-safety net.

RHashMap

An ffi-safe hashmap, which wraps std::collections::HashMap<K, V, S>, only requiring the K: Eq + Hash bounds when constructing it.

RSlice

Ffi-safe equivalent of &'a [T]

RStr

Ffi-safe equivalent of &'a str

RString

Ffi-safe equivalent of std::string::String.

RVec

Ffi-safe equivalent of std::vec::Vec.

Tuple2

An ffi safe 2 element tuple.

Enums

ROption

Ffi-safe equivalent of the std::option::Option type.

RResult

Ffi-safe equivalent of Result<T, E>.

Type Aliases

RBoxError

Ffi safe equivalent to Box<dyn std::error::Error + Send + Sync>.