uni_plugin/
lib.rs

1//! Plugin framework for uni-db.
2//!
3//! `uni-plugin` defines the trait surface, registry, manifest, and capability
4//! model that every uni-db extension — scalar function, aggregate, procedure,
5//! per-label storage, index kind, graph algorithm, CRDT, hook, trigger, background
6//! job, logical type, auth provider, authz policy, collation, CDC
7//! output, catalog, replacement scan — registers through.
8//!
9//! The crate intentionally has **no host integration**: it does not depend on
10//! `uni-query`, `uni-store`, `uni-crdt`, `uni-algo`, or `uni`. Those crates
11//! depend on `uni-plugin` and adapt their existing surfaces to the traits
12//! defined here. This direction keeps the dependency graph acyclic and lets
13//! the trait surface be reviewed in isolation.
14//!
15//! # Layout
16//!
17//! - [`plugin`] — the `Plugin` trait, `PluginManifest`, `PluginHandle`.
18//! - [`qname`] — qualified plugin-function names (`namespace.local`).
19//! - [`capability`] — `Capability`, `CapabilitySet`, `Determinism`, `Scope`.
20//! - [`manifest`] — TOML / JSON manifest (de)serialization.
21//! - [`registrar`] — the builder a plugin's `register()` method calls.
22//! - [`registry`] — per-surface trait-object tables (`arc-swap`-backed for
23//!   wait-free reads).
24//! - [`traits`] — one module per extension surface (scalar functions,
25//!   aggregates, procedures, hooks, …).
26//! - [`errors`] — `PluginError`, `FnError`, plus per-trait error helpers.
27//!
28//! # Stability
29//!
30//! Until uni-plugin reaches `1.0.0`, trait shapes may change.
31//! The semver guarantees apply only to `0.x` major versions in the meantime.
32//!
33//! # Examples
34//!
35//! ```
36//! use uni_plugin::{Plugin, PluginManifest, PluginRegistrar, PluginError, QName};
37//!
38//! struct NoopPlugin;
39//!
40//! impl Plugin for NoopPlugin {
41//!     fn manifest(&self) -> &PluginManifest {
42//!         // In real plugins, store the manifest in a `OnceLock` populated
43//!         // at construction.
44//!         unimplemented!("see crates/uni-plugin-builtin for real examples")
45//!     }
46//!     fn register(&self, _r: &mut PluginRegistrar<'_>) -> Result<(), PluginError> {
47//!         Ok(())
48//!     }
49//! }
50//! ```
51
52// Rust guideline compliant
53#![warn(missing_docs)]
54#![warn(rust_2018_idioms)]
55#![warn(unsafe_op_in_unsafe_fn)]
56#![warn(missing_debug_implementations)]
57
58pub mod adapter_common;
59pub mod adapters;
60pub mod capability;
61pub mod circuit_breaker;
62pub mod errors;
63pub mod fs_guard;
64pub mod hex;
65pub mod host;
66pub mod host_services;
67pub mod lifecycle;
68pub mod manifest;
69pub mod observability;
70pub mod plugin;
71pub mod qname;
72pub mod registrar;
73pub mod registry;
74pub mod reload;
75pub mod scheduler;
76pub mod secrets;
77pub mod surfaces;
78pub mod traits;
79pub mod verify;
80pub mod wire_manifest;
81
82#[doc(inline)]
83pub use crate::capability::{
84    Capability, CapabilitySet, Determinism, GrantError, ManifestCapability, Scope, SideEffects,
85};
86#[doc(inline)]
87pub use crate::errors::{FnError, PluginError, ReloadError};
88#[doc(inline)]
89pub use crate::fs_guard::normalize_capability_path;
90#[doc(inline)]
91pub use crate::host_services::{HttpEgress, HttpResponse, KmsProvider};
92#[doc(inline)]
93pub use crate::manifest::{AbiRange, PluginManifest, ProvidedSurfaces};
94#[doc(inline)]
95pub use crate::plugin::{Plugin, PluginHandle, PluginId, PluginInitContext};
96#[doc(inline)]
97pub use crate::qname::{QName, RESERVED_PLUGIN_IDS, is_reserved_plugin_id};
98#[doc(inline)]
99pub use crate::registrar::PluginRegistrar;
100#[doc(inline)]
101pub use crate::registry::{PluginRecordSnapshot, PluginRegistry};
102#[doc(inline)]
103pub use crate::reload::{
104    CdcHandoff, IndexHandoff, OldProviders, ReloadDispatcher, ReloadKindHandlers, ReloadOutcome,
105};
uni_plugin/lib.rs

uni_plugin/
lib.rs
