Skip to main content

Module vtable

haproxy_spoa_hub_plugin_api

Module vtable 

Source
Expand description

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

Design rationale: see ADR-001 / docs/abi-evolution.md (TBD). In short: abi_stable’s prefix-type model rejects loads where the host’s vtable has more fields than the plugin’s, blocking the host-grows-faster direction we need. The hand-rolled C-style vtable with a leading api_version: u32 field, version-gated host access, and an append-only evolution discipline gives us bidirectional ABI compat without a third-party load-time check that fights us.

§Layout invariants (load-bearing)

  1. api_version MUST be the first field.
  2. Existing fields MUST NOT be reordered or removed in any future crate version. New fields MUST be appended after the existing ones.
  3. PLUGIN_API_VERSION increments by 1 each time a new field is appended and the corresponding accessor lands.
  4. Hosts MUST read api_version before accessing any field beyond the v1 baseline. Reading newer fields on a plugin that reports a lower api_version is undefined behavior — the plugin’s allocation does not include those bytes.

See crates/hub/tests/abi_matrix.rs for the regression test that enforces invariants 1–3 by loading every published plugin version against the current hub binary.

Structs§

PluginVTable
The function table a plugin shared library exports.

Constants§

GET_PLUGIN_VTABLE_SYMBOL
Symbol name the hub looks up via dlsym after dlopen.
PLUGIN_API_VERSION
Latest API version this crate’s PluginVTable exposes. Plugin authors set this as the api_version field. When future versions of this crate append a field, this constant bumps by 1.
PLUGIN_API_VERSION_V1
API version corresponding to the v1 baseline (initial release of the hand-rolled vtable). Every field declared in PluginVTable is part of v1 and is present on every plugin built against this crate.
PLUGIN_API_VERSION_V2
API version v2: adds set_metric_recorder so plugins can emit Prometheus metrics through the hub’s existing recorder. Plugins built against v2 keep loading on v1 hubs (the hub ignores the field because it doesn’t know it exists); plugins built against v1 keep loading on v2 hubs (the hub gates access on api_version >= 2 and skips the install for v1 plugins).

Type Aliases§

GetPluginVTableFn
Type of the exported entry-point symbol.