folk_api/
plugin.rs

1//! The `Plugin` trait: every plugin in Folk implements this.
2
3use anyhow::Result;
4use async_trait::async_trait;
5
6use crate::context::PluginContext;
7use crate::rpc::RpcMethodDef;
8
9/// Lifecycle of a Folk plugin.
10///
11/// At server startup, plugins are booted in registration order. At shutdown,
12/// they are stopped in reverse order. A plugin that holds long-running tasks
13/// should consider implementing [`crate::ServerPlugin`] instead — the wrapper
14/// handles the boilerplate of spawning, holding handles, and joining.
15#[async_trait]
16pub trait Plugin: Send + Sync + 'static {
17    /// Stable plugin name. Conventionally lowercase, single-word: `"http"`,
18    /// `"jobs"`, `"metrics"`. Used for log scoping, health/metric labels,
19    /// and config-section routing in custom builds.
20    fn name(&self) -> &'static str;
21
22    /// Called once at server startup. Register RPC methods, health checks,
23    /// and metrics via `ctx`, then spawn background tasks. Returning `Err`
24    /// is fatal: the server aborts startup.
25    async fn boot(&mut self, ctx: PluginContext) -> Result<()>;
26
27    /// Called during graceful shutdown. Returning `Err` is logged but does
28    /// not abort shutdown of other plugins.
29    async fn shutdown(&self) -> Result<()>;
30
31    /// Optional: the RPC methods this plugin exposes. Used for advertising
32    /// (e.g., `folk admin list-methods`). Default is empty.
33    fn rpc_methods(&self) -> Vec<RpcMethodDef> {
34        Vec::new()
35    }
36}
folk_api/plugin.rs

folk_api/
plugin.rs
