razeri_plugin_api/
lib.rs

1// Copyright (C) 2026 Gabriel Shea
2// Licensed under either of the Apache License, Version 2.0 or the MIT
3// license, at your option.
4
5#![warn(missing_docs)]
6
7//! # razeri-plugin-api
8//!
9//! Extension point traits and registries for the Razeri platform.
10//!
11//! This crate defines the **plugin API surface** — the traits that third-party
12//! developers implement to extend Razeri with new database dialects, storage
13//! backends, LLM providers, language renderers, and event sinks.
14//!
15//! ## Extension Points
16//!
17//! | Trait | Registry | Key Type |
18//! |-------|----------|----------|
19//! | [`PlatformDialect`] | [`PlatformRegistry`] | string (canonical name) |
20//! | [`StorageProviderFactory`] | [`StorageRegistry`] | `StoragePlatform` enum + string |
21//! | [`LlmClientFactory`] / [`LlmClient`] | [`LlmRegistry`] | string |
22//! | [`LlmModelAdapter`] | [`ModelRegistry`] | (provider, model) pair |
23//! | [`LanguageRendererFactory`] | [`LanguageRegistry`] | string |
24//! | [`EventSink`] | [`EventRegistry`] | fan-out (all sinks) |
25//!
26//! ## Composition Root
27//!
28//! Use [`PluginRegistryBuilder`] to wire everything together at application
29//! startup, then pass the resulting [`PluginRegistry`] to subsystems:
30//!
31//! ```ignore
32//! let registry = PluginRegistryBuilder::new()
33//!     .with_dialect("postgres", Arc::new(pg_dialect))
34//!     .with_llm("ollama".into(), Arc::new(ollama_factory))
35//!     .with_auto_discovered()
36//!     .build();
37//! ```
38
39pub mod alerting;
40pub mod builder;
41pub mod conformance;
42pub mod dialect;
43pub mod dynamic;
44pub mod error;
45pub mod event;
46pub mod language;
47pub mod llm;
48pub mod model;
49pub mod process;
50pub mod registry;
51pub mod resolve;
52pub mod sinks;
53pub mod storage;
54
55// ── Convenience re-exports ────────────────────────────────────────────
56
57pub use builder::PluginRegistryBuilder;
58pub use dialect::{DialectInfo, PlatformDialect, PlatformRegistry};
59
60// The contract a plugin's types and traits are written against, re-exported so
61// a dialect crate can depend on this one crate and reach everything it needs.
62pub use dynamic::{
63    API_VERSION, ApiVersionFn, PLUGIN_API_VERSION_SYMBOL, PLUGIN_REGISTER_SYMBOL, PluginLoadResult,
64    RegisterPluginFn,
65};
66pub use razeri_plugin_contract;
67
68#[cfg(all(feature = "dynamic", not(target_arch = "wasm32")))]
69pub use dynamic::load_plugins_from_dir;
70pub use error::{EventSinkError, LanguageError, LlmError, StorageError};
71pub use event::{
72    EventCategory, EventEmitter, EventFilterKeys, EventPayload, EventQuery, EventRegistry,
73    EventSeverity, EventSink, EventSubject, EventSubjectKind, EventSummary, EventValidationError,
74    RazeriEvent, WorkflowContext,
75};
76pub use language::{LanguageRegistry, LanguageRenderer, LanguageRendererFactory};
77pub use llm::{
78    ChatResponse, LlmClient, LlmClientFactory, LlmRegistry, Message, ModelInfo, TokenUsage,
79};
80pub use model::{LlmModelAdapter, ModelCapabilities, ModelRegistry};
81pub use process::{
82    InstallError, PLUGIN_DIR_ENV, PluginDirReport, install_plugin_dir, plugin_dir_from_environment,
83    plugin_dir_report, process_registry,
84};
85pub use registry::PluginRegistry;
86pub use resolve::ResolveError;
87pub use storage::{
88    StorageListEntry, StorageMetadata, StorageOps, StorageProviderFactory, StorageRegistry,
89};
90
91// Re-export built-in sink types and factory. The JSONL sink is native-only
92// (filesystem via `tokio::fs`), so its re-export is absent on wasm.
93#[cfg(not(target_arch = "wasm32"))]
94pub use sinks::jsonl::JsonlSink;
95pub use sinks::stdout::StdoutSink;
96pub use sinks::webhook::WebhookSink;
97pub use sinks::{EventSinkConfig, create_sink};
98
99// Re-export alerting and health model
100pub use alerting::{
101    AlertCondition, AlertMetric, AlertResult, AlertRule, AlertScope, ComparisonOp, HealthDomain,
102    HealthStatus, HealthSummary, SinkStatus, discover_health, evaluate_rules, health_for_domain,
103};
104
105// Re-export inventory registration types
106pub use builder::{
107    DialectRegistration, EventSinkRegistration, LanguageRegistration, LlmRegistration,
108    ModelRegistration, StorageRegistration,
109};
110
111// ── Convenience helpers ───────────────────────────────────────────────
112
113use std::sync::Arc;
114
115/// Resolve a platform name to the dialect that renders it.
116///
117/// This is the **one resolver** — all service crates call it instead of
118/// matching on names themselves. Each dialect declares the spellings it answers
119/// to, so `"pg"` reaches `PostgreSQL` and `"mssql"` reaches SQL Server because
120/// those dialects say so. Matching ignores case and surrounding whitespace, and
121/// an unknown name comes back with near-miss suggestions.
122///
123/// A dialect the host loaded at run time resolves the same way as one linked
124/// in: both are read off the registry.
125///
126/// # Errors
127///
128/// [`ResolveError::UnknownDialect`], with suggestions, if no loaded dialect
129/// answers to the name; [`ResolveError::AmbiguousName`] if two do.
130///
131/// # Examples
132///
133/// ```no_run
134/// use razeri_plugin_api::{ResolveError, resolve_dialect_by_name};
135///
136/// # fn main() -> Result<(), ResolveError> {
137/// // Aliases, canonical names and casing all resolve to the same dialect.
138/// let dialect = resolve_dialect_by_name("pg")?;
139/// println!("{}", dialect.info().name);
140///
141/// let dialect = resolve_dialect_by_name("SNOWFLAKE")?;
142/// let dialect = resolve_dialect_by_name("sqlite")?;
143/// # Ok(())
144/// # }
145/// ```
146pub fn resolve_dialect_by_name(name: &str) -> Result<Arc<dyn PlatformDialect>, ResolveError> {
147    resolve::resolve_dialect_by_name(name)
148}
149
150/// Resolve a dialect by string name, returning `None` on failure.
151///
152/// Convenience wrapper around [`resolve_dialect_by_name`] for callers that
153/// prefer `Option` over `Result`.
154#[must_use]
155pub fn try_resolve_dialect_by_name(name: &str) -> Option<Arc<dyn PlatformDialect>> {
156    resolve_dialect_by_name(name).ok()
157}
razeri_plugin_api/lib.rs

razeri_plugin_api/
lib.rs
