arcly_http/core/

plugins.rs

//! Third-party plugin ecosystem.
//!
//! A plugin owns a corner of the framework's behaviour without forking the
//! core crate: register global routes, mutate the OpenAPI spec, attach
//! global interceptors, spawn background tasks under graceful shutdown.
//!
//! ## Object safety
//!
//! `ArclyPlugin` uses the *erased-type* pattern: each lifecycle hook returns
//! a `BoxFuture` instead of `async fn`, so the trait stays object-safe and
//! we can hold `Vec<Box<dyn ArclyPlugin>>`.
//!
//! ## Opaque context
//!
//! `ArclyPluginContext` exposes a small, framework-typed API for the things
//! plugins legitimately need to do. Axum / Tower types are private; the
//! public methods all speak in arcly types (`RequestContext`, `Response`).
//!
//! ## Deferred construction
//!
//! Plugins register *handler factories* rather than routes directly. At
//! launch time, once the frozen DI container exists, `App::launch` invokes
//! each factory with the real `&'static FrozenDiContainer` and mounts the
//! resulting axum route. This sidesteps any unsoundness from materialising
//! the container before it's built.

use std::fmt;

use futures::future::BoxFuture;

use crate::http::Response;

use crate::core::engine::{FrozenDiContainer, HttpMethod};
use crate::web::context::RequestContext;

// ─── Errors ─────────────────────────────────────────────────────────────

#[derive(Debug)]
pub struct PluginError {
    pub plugin: &'static str,
    pub stage: PluginStage,
    pub source: Box<dyn std::error::Error + Send + Sync>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PluginStage {
    Init,
    Start,
    Shutdown,
}

impl PluginError {
    pub fn new<E: Into<Box<dyn std::error::Error + Send + Sync>>>(
        plugin: &'static str,
        stage: PluginStage,
        source: E,
    ) -> Self {
        Self {
            plugin,
            stage,
            source: source.into(),
        }
    }
}

impl fmt::Display for PluginError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "plugin `{}` failed at {:?}: {}",
            self.plugin, self.stage, self.source
        )
    }
}
impl std::error::Error for PluginError {}

// ─── The trait ──────────────────────────────────────────────────────────

/// Plugin lifecycle.
///
/// All three hooks receive the framework's frozen DI container as a
/// `&'static` ref (after init completes), so background tasks and shutdown
/// drain routines can resolve injected services with zero locks. The init
/// hook receives the *mutable* `ArclyPluginContext`, through which the
/// plugin can `provide<T>` new singletons into the container before it
/// freezes.
pub trait ArclyPlugin: Send + Sync + 'static {
    fn name(&self) -> &'static str;

    /// **Pre-bind.** Register providers, routes, interceptors, openapi mutators.
    /// The container is built AFTER every plugin's `on_init` returns.
    fn on_init<'a>(
        &'a mut self,
        ctx: &'a mut ArclyPluginContext,
    ) -> BoxFuture<'a, Result<(), PluginError>> {
        let _ = ctx;
        Box::pin(async { Ok(()) })
    }

    /// **Post-bind.** Listener is live and accepting. Background tasks spawn
    /// here. `container` resolves any provider — including ones the plugin
    /// itself registered in `on_init`.
    fn on_start<'a>(
        &'a self,
        container: &'static FrozenDiContainer,
    ) -> BoxFuture<'a, Result<(), PluginError>> {
        let _ = container;
        Box::pin(async { Ok(()) })
    }

    /// **Graceful shutdown.** Invoked **after** the HTTP server has stopped
    /// accepting new connections and all in-flight requests have drained.
    /// Wrapped by `App` in a configurable timeout (default 5s) so a hung
    /// plugin can never wedge the process.
    fn on_shutdown<'a>(
        &'a self,
        container: &'static FrozenDiContainer,
    ) -> BoxFuture<'a, Result<(), PluginError>> {
        let _ = container;
        Box::pin(async { Ok(()) })
    }
}

// ─── Handler factory + context ─────────────────────────────────────────

/// A typed handler usable from plugin-registered routes. Takes a
/// `RequestContext`, returns a `Response`.
pub type PluginHandler =
    std::sync::Arc<dyn Fn(RequestContext) -> BoxFuture<'static, Response> + Send + Sync>;

#[doc(hidden)]
pub struct PluginRoute {
    pub method: HttpMethod,
    pub path: &'static str,
    pub handler: PluginHandler,
}

/// Mutable handle plugins receive during `on_init`.
///
/// `provide<T>` queues a singleton for the DI container, applied just before
/// the container freezes. Once frozen the container is `&'static` and
/// reads are lock-free for the lifetime of the process.
pub(crate) type OpenApiMutator = Box<dyn FnOnce(&mut serde_json::Value) + Send + Sync>;
pub(crate) type PendingProvider =
    Box<dyn FnOnce(&mut crate::core::engine::DiContainerBuilder) + Send>;

pub struct ArclyPluginContext {
    pub(crate) extra_routes: Vec<PluginRoute>,
    pub(crate) openapi_mutators: Vec<OpenApiMutator>,
    pub(crate) global_interceptors: Vec<&'static dyn crate::web::interceptors::Interceptor>,
    pub(crate) pending_providers: Vec<PendingProvider>,
}

impl ArclyPluginContext {
    #[doc(hidden)]
    pub fn new() -> Self {
        Self {
            extra_routes: Vec::new(),
            openapi_mutators: Vec::new(),
            global_interceptors: Vec::new(),
            pending_providers: Vec::new(),
        }
    }

    /// Inject a singleton of type `T` into the DI container. Resolves later
    /// via `Inject<T>` in any controller / service / interceptor.
    ///
    /// Order: every plugin's `on_init` runs first, then all `provide<T>`
    /// closures are applied in declaration order, *then* the container
    /// freezes. So one plugin can read another's provision in `on_start`
    /// but not in `on_init`.
    pub fn provide<T: Send + Sync + 'static>(&mut self, value: T) {
        self.pending_providers.push(Box::new(move |b| {
            b.register(value);
        }));
    }

    /// Register a route. The handler receives a fully-built `RequestContext`
    /// — including DI access via `ctx.inject::<T>()` — and returns a
    /// `Response`. The path is mounted verbatim under the application root.
    pub fn add_route<F, Fut>(&mut self, method: HttpMethod, path: &'static str, handler: F)
    where
        F: Fn(RequestContext) -> Fut + Send + Sync + 'static,
        Fut: std::future::Future<Output = Response> + Send + 'static,
    {
        let arc: PluginHandler = std::sync::Arc::new(move |ctx| Box::pin(handler(ctx)));
        self.extra_routes.push(PluginRoute {
            method,
            path,
            handler: arc,
        });
    }

    /// Shortcut: register a GET.
    pub fn add_get<F, Fut>(&mut self, path: &'static str, handler: F)
    where
        F: Fn(RequestContext) -> Fut + Send + Sync + 'static,
        Fut: std::future::Future<Output = Response> + Send + 'static,
    {
        self.add_route(HttpMethod::GET, path, handler);
    }

    /// Mutate the assembled OpenAPI document at launch time.
    pub fn modify_openapi<F>(&mut self, f: F)
    where
        F: FnOnce(&mut serde_json::Value) + Send + Sync + 'static,
    {
        self.openapi_mutators.push(Box::new(f));
    }

    /// Read a required environment variable.
    ///
    /// Returns `Err(PluginError)` with stage `Init` if the variable is absent
    /// or contains non-UTF-8 bytes, so callers can propagate it cleanly with `?`.
    pub fn require_env(&self, key: &'static str) -> Result<String, PluginError> {
        std::env::var(key).map_err(|_| {
            PluginError::new(
                "ArclyPluginContext",
                PluginStage::Init,
                format!("required env var `{key}` is missing or not valid UTF-8"),
            )
        })
    }

    /// Read an environment variable with a fallback default.
    pub fn env_or(&self, key: &str, default: impl Into<String>) -> String {
        std::env::var(key).unwrap_or_else(|_| default.into())
    }

    /// Attach an interceptor that fires on **every** route registered via
    /// the macros. Plugin routes opt in separately if they want it.
    pub fn register_global_interceptor(
        &mut self,
        ic: &'static dyn crate::web::interceptors::Interceptor,
    ) {
        self.global_interceptors.push(ic);
    }
}

impl Default for ArclyPluginContext {
    fn default() -> Self {
        Self::new()
    }
}

// Route mounting moved to `crate::web::plugin_routes` so this module stays
// HTTP-agnostic. Re-exported here to keep the existing import path working.
pub use crate::web::plugin_routes::build_plugin_route;