folk_api/lib.rs
1//! # `folk-api`
2//!
3//! Plugin contract for Folk: every plugin in Folk depends on this crate
4//! and **only** on this crate. The server core (`folk-core`) provides the
5//! concrete implementations of [`Executor`], [`RpcRegistrar`],
6//! [`HealthRegistry`], and [`MetricsRegistry`].
7//!
8//! ## Writing a plugin
9//!
10//! Most plugins should:
11//!
12//! 1. Implement [`ServerPlugin`] (not [`Plugin`] directly) for a long-running
13//! background task.
14//! 2. Wrap the implementation in [`ServerPluginWrapper`].
15//! 3. Implement [`PluginFactory`] to construct the plugin from config.
16//! 4. Export `pub fn folk_plugin_factory() -> Box<dyn PluginFactory>`.
17//!
18//! See `folk-spec/adr/0006-plugin-api-shape.md` for the full design rationale,
19//! and `folk-plugin-http` for a complete working example (phase 6).
20
21pub mod context;
22pub mod executor;
23pub mod factory;
24pub mod health;
25pub mod metrics;
26pub mod plugin;
27pub mod rpc;
28pub mod server_plugin;
29
30pub use context::PluginContext;
31pub use executor::Executor;
32pub use factory::PluginFactory;
33pub use health::{HealthCheckFn, HealthRegistry, HealthStatus};
34pub use metrics::{Counter, CounterVec, Gauge, GaugeVec, Histogram, HistogramVec, MetricsRegistry};
35pub use plugin::Plugin;
36pub use rpc::{BoxFuture, RpcHandler, RpcMethodDef, RpcRegistrar};
37pub use server_plugin::{ServerPlugin, ServerPluginWrapper};
38
39/// The Folk API version. Equals this crate's `Cargo.toml` `version` field.
40///
41/// Used for diagnostics and the `folk --version` output. There is no runtime
42/// version negotiation; see `folk-spec/adr/0004-no-capability-negotiation.md`.
43pub const FOLK_API_VERSION: &str = env!("CARGO_PKG_VERSION");