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/// **The named routine grammars, spelled.**
69///
70/// A dialect whose engine has a routine in a grammar Razeri does not carry
71/// renders the whole `CREATE` itself. These three functions write out the
72/// grammars Razeri does carry, from the same
73/// [`RoutineSpec`](razeri_plugin_contract::RoutineSpec) a dialect receives, so a
74/// grammar that is *"PL/pgSQL with one tweak"* starts from PL/pgSQL and says
75/// what differs rather than being written from nothing.
76pub use razeri_plugin_contract::routine_render;
77pub use razeri_plugin_contract::routine_render::{
78    render_procedure_as, render_scalar_function_as, render_table_function_as,
79};
80
81#[cfg(all(feature = "dynamic", not(target_arch = "wasm32")))]
82pub use dynamic::load_plugins_from_dir;
83pub use error::{EventSinkError, LanguageError, LlmError, StorageError};
84pub use event::{
85    EventCategory, EventEmitter, EventFilterKeys, EventPayload, EventQuery, EventRegistry,
86    EventSeverity, EventSink, EventSubject, EventSubjectKind, EventSummary, EventValidationError,
87    RazeriEvent, WorkflowContext,
88};
89pub use language::{LanguageRegistry, LanguageRenderer, LanguageRendererFactory};
90pub use llm::{
91    ChatResponse, LlmClient, LlmClientFactory, LlmRegistry, Message, ModelInfo, TokenUsage,
92};
93pub use model::{LlmModelAdapter, ModelCapabilities, ModelRegistry};
94pub use process::{
95    InstallError, PLUGIN_DIR_ENV, PluginDirReport, install_plugin_dir, plugin_dir_from_environment,
96    plugin_dir_report, process_registry,
97};
98pub use registry::PluginRegistry;
99pub use resolve::ResolveError;
100pub use storage::{
101    StorageListEntry, StorageMetadata, StorageOps, StorageProviderFactory, StorageRegistry,
102};
103
104// Re-export built-in sink types and factory. The JSONL sink is native-only
105// (filesystem via `tokio::fs`), so its re-export is absent on wasm.
106#[cfg(not(target_arch = "wasm32"))]
107pub use sinks::jsonl::JsonlSink;
108pub use sinks::stdout::StdoutSink;
109pub use sinks::webhook::WebhookSink;
110pub use sinks::{EventSinkConfig, create_sink};
111
112// Re-export alerting and health model
113pub use alerting::{
114    AlertCondition, AlertMetric, AlertResult, AlertRule, AlertScope, ComparisonOp, HealthDomain,
115    HealthStatus, HealthSummary, SinkStatus, discover_health, evaluate_rules, health_for_domain,
116};
117
118// Re-export inventory registration types
119pub use builder::{
120    DialectRegistration, EventSinkRegistration, LanguageRegistration, LlmRegistration,
121    ModelRegistration, StorageRegistration,
122};
123
124// ── Convenience helpers ───────────────────────────────────────────────
125
126use std::sync::Arc;
127
128/// Resolve a platform name to the dialect that renders it.
129///
130/// This is the **one resolver** — all service crates call it instead of
131/// matching on names themselves. Each dialect declares the spellings it answers
132/// to, so `"pg"` reaches `PostgreSQL` and `"mssql"` reaches SQL Server because
133/// those dialects say so. Matching ignores case and surrounding whitespace, and
134/// an unknown name comes back with near-miss suggestions.
135///
136/// A dialect the host loaded at run time resolves the same way as one linked
137/// in: both are read off the registry.
138///
139/// # Errors
140///
141/// [`ResolveError::UnknownDialect`], with suggestions, if no loaded dialect
142/// answers to the name; [`ResolveError::AmbiguousName`] if two do.
143///
144/// # Examples
145///
146/// ```no_run
147/// use razeri_plugin_api::{ResolveError, resolve_dialect_by_name};
148///
149/// # fn main() -> Result<(), ResolveError> {
150/// // Aliases, canonical names and casing all resolve to the same dialect.
151/// let dialect = resolve_dialect_by_name("pg")?;
152/// println!("{}", dialect.info().name);
153///
154/// let dialect = resolve_dialect_by_name("SNOWFLAKE")?;
155/// let dialect = resolve_dialect_by_name("sqlite")?;
156/// # Ok(())
157/// # }
158/// ```
159pub fn resolve_dialect_by_name(name: &str) -> Result<Arc<dyn PlatformDialect>, ResolveError> {
160    resolve::resolve_dialect_by_name(name)
161}
162
163/// Resolve a dialect by string name, returning `None` on failure.
164///
165/// Convenience wrapper around [`resolve_dialect_by_name`] for callers that
166/// prefer `Option` over `Result`.
167#[must_use]
168pub fn try_resolve_dialect_by_name(name: &str) -> Option<Arc<dyn PlatformDialect>> {
169    resolve_dialect_by_name(name).ok()
170}
razeri_plugin_api/lib.rs

razeri_plugin_api/
lib.rs
