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//! storage backend, index kind, graph algorithm, CRDT, hook, trigger, background
6//! job, logical type, auth provider, authz policy, connector, collation, CDC
7//! output, catalog, replacement scan, Pregel program — 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 host;
65pub mod host_services;
66pub mod lifecycle;
67pub mod manifest;
68pub mod observability;
69pub mod plugin;
70pub mod qname;
71pub mod registrar;
72pub mod registry;
73pub mod reload;
74pub mod scheduler;
75pub mod secrets;
76pub mod surfaces;
77pub mod traits;
78pub mod verify;
79
80#[doc(inline)]
81pub use crate::capability::{
82    Capability, CapabilitySet, Determinism, ManifestCapability, Scope, SideEffects,
83};
84#[doc(inline)]
85pub use crate::errors::{FnError, PluginError, ReloadError};
86#[doc(inline)]
87pub use crate::fs_guard::normalize_capability_path;
88#[doc(inline)]
89pub use crate::host_services::{HttpEgress, HttpResponse, KmsProvider};
90#[doc(inline)]
91pub use crate::manifest::{AbiRange, PluginManifest, ProvidedSurfaces};
92#[doc(inline)]
93pub use crate::plugin::{Plugin, PluginHandle, PluginId, PluginInitContext};
94#[doc(inline)]
95pub use crate::qname::{QName, RESERVED_PLUGIN_IDS, is_reserved_plugin_id};
96#[doc(inline)]
97pub use crate::registrar::PluginRegistrar;
98#[doc(inline)]
99pub use crate::registry::{PluginRecordSnapshot, PluginRegistry};
100#[doc(inline)]
101pub use crate::reload::{
102    CdcHandoff, IndexHandoff, OldProviders, ReloadDispatcher, ReloadKindHandlers, ReloadOutcome,
103};
uni_plugin/lib.rs

uni_plugin/
lib.rs
