Crate uni_plugin 

Plugin framework for uni-db.

uni-plugin defines the trait surface, registry, manifest, and capability model that every uni-db extension — scalar function, aggregate, procedure, storage backend, index kind, graph algorithm, CRDT, hook, trigger, background job, logical type, auth provider, authz policy, connector, collation, CDC output, catalog, replacement scan, Pregel program — registers through.

The crate intentionally has no host integration: it does not depend on uni-query, uni-store, uni-crdt, uni-algo, or uni. Those crates depend on uni-plugin and adapt their existing surfaces to the traits defined here. This direction keeps the dependency graph acyclic and lets the trait surface be reviewed in isolation.

Layout

• plugin — the Plugin trait, PluginManifest, PluginHandle.
• qname — qualified plugin-function names (namespace.local).
• capability — Capability, CapabilitySet, Determinism, Scope.
• manifest — TOML / JSON manifest (de)serialization.
• registrar — the builder a plugin’s register() method calls.
• registry — per-surface trait-object tables (arc-swap-backed for wait-free reads).
• traits — one module per extension surface (scalar functions, aggregates, procedures, hooks, …).
• errors — PluginError, FnError, plus per-trait error helpers.

Stability

Until uni-plugin reaches 1.0.0, trait shapes may change. The semver guarantees apply only to 0.x major versions in the meantime.

Examples

use uni_plugin::{Plugin, PluginManifest, PluginRegistrar, PluginError, QName};

struct NoopPlugin;

impl Plugin for NoopPlugin {
    fn manifest(&self) -> &PluginManifest {
        // In real plugins, store the manifest in a `OnceLock` populated
        // at construction.
        unimplemented!("see crates/uni-plugin-builtin for real examples")
    }
    fn register(&self, _r: &mut PluginRegistrar<'_>) -> Result<(), PluginError> {
        Ok(())
    }
}

Modules

adapter_common

Shared helpers reused by every loader adapter crate.

adapters

Adapters that bridge one plugin surface to another.

capability

Plugin capabilities — declared in manifest, granted at load time.

circuit_breaker

Per-(plugin_id, qname) circuit breaker.

errors

Error types for the plugin framework.

fs_guard

Path normalization for filesystem capability matching.

host

Host-side helpers for procedure execution and principal threading.

host_services

Host service traits for capability-gated plugin host functions.

lifecycle

Plugin lifecycle state machine.

manifest

Plugin manifest — TOML and JSON (de)serialization.

observability

Observability helpers for plugin invocations.

plugin

The core Plugin trait and supporting types.

qname

Qualified plugin item names — namespace.local.

registrar

The PluginRegistrar a plugin’s register() method calls.

registry

The PluginRegistry — per-surface trait-object tables.

reload

Per-kind hot-reload discipline orchestration.

scheduler

Background-job scheduler skeleton.

secrets

Sealer/unsealer secret membrane.

surfaces

Per-surface trait abstractions for the plugin registry.

traits

Per-surface capability traits.

verify

Manifest signing and hash-pinning verification.

Structs

AbiRange

A semver range expressing which ABI majors this plugin supports.

CapabilitySet

A set of capabilities — declared by manifest, granted by loader.

CdcHandoff

One live CDC stream and the new provider that will resume it.

FnError

Per-invocation error returned by a plugin’s work function.

HttpResponse

Response returned by an HttpEgress request.

IndexHandoff

One live index handle and the new provider that will reopen it.

ManifestCapability

A capability as it appears in a guest plugin manifest (WASM / Extism) — either a bare capability name ("network", "scalar-fn") or a structured object carrying attenuation patterns ({"kind":"network","allow":["https://api.example/**"]}).

OldProviders

Pre-swap snapshot of the old plugin’s stateful providers.

PluginHandle

A handle returned by Uni::add_plugin and similar APIs.

PluginId

Reverse-DNS plugin identifier — e.g. "ai.dragonscale.geo".

PluginInitContext

Init-time context provided to Plugin::init.

PluginManifest

Top-level plugin manifest.

PluginRecordSnapshot

A deep-clone snapshot of one plugin’s registry footprint.

PluginRegistrar

The builder passed to crate::Plugin::register.

PluginRegistry

All-surfaces plugin registry.

ProvidedSurfaces

Declarative summary of what surfaces a plugin’s register() will add.

QName

Qualified plugin item name — namespace.local.

ReloadDispatcher

Orchestrates per-kind reload discipline between drain and commit.

ReloadKindHandlers

Host-supplied handlers wiring per-kind in-flight resources into the reload pipeline.

ReloadOutcome

The outcome of a successful reload — opaque container for any new in-flight resources the dispatcher constructed (reopened index handles, restarted CDC streams) so the host can re-attach them.

Enums

Capability

A single permission grant.

Determinism

Determinism characterization — drives planner caching and hoisting.

PluginError

Errors surfaced by the plugin framework itself.

ReloadError

Errors produced by the hot-reload pipeline.

Scope

Lifetime scope of a plugin’s registrations.

SideEffects

Declared side-effects of a plugin.

Constants

RESERVED_PLUGIN_IDS

Reserved single-token plugin ids that are exempt from the reverse-DNS id-format requirement.

Traits

HttpEgress

A blocking HTTP egress service backing the uni.http.* host functions.

KmsProvider

A signing / verification service backing the uni.kms.* host functions.

Plugin

The trait every uni-db extension implements.

Functions

is_reserved_plugin_id

Returns true if id is one of the framework-reserved single-token plugin ids exempt from the reverse-DNS requirement.

normalize_capability_path

Lexically normalize an absolute capability path for allow-list matching.