folk-api 0.1.2

Plugin contract for the Folk PHP application server
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

//! The `Plugin` trait: every plugin in Folk implements this.

use anyhow::Result;
use async_trait::async_trait;

use crate::context::PluginContext;
use crate::rpc::RpcMethodDef;

/// Lifecycle of a Folk plugin.
///
/// At server startup, plugins are booted in registration order. At shutdown,
/// they are stopped in reverse order. A plugin that holds long-running tasks
/// should consider implementing [`crate::ServerPlugin`] instead — the wrapper
/// handles the boilerplate of spawning, holding handles, and joining.
#[async_trait]
pub trait Plugin: Send + Sync + 'static {
    /// Stable plugin name. Conventionally lowercase, single-word: `"http"`,
    /// `"jobs"`, `"metrics"`. Used for log scoping, health/metric labels,
    /// and config-section routing in custom builds.
    fn name(&self) -> &'static str;

    /// Called once at server startup. Register RPC methods, health checks,
    /// and metrics via `ctx`, then spawn background tasks. Returning `Err`
    /// is fatal: the server aborts startup.
    async fn boot(&mut self, ctx: PluginContext) -> Result<()>;

    /// Called during graceful shutdown. Returning `Err` is logged but does
    /// not abort shutdown of other plugins.
    async fn shutdown(&self) -> Result<()>;

    /// Optional: the RPC methods this plugin exposes. Used for advertising
    /// (e.g., `folk admin list-methods`). Default is empty.
    fn rpc_methods(&self) -> Vec<RpcMethodDef> {
        Vec::new()
    }
}