bext-plugin-api 0.2.0

//! Lifecycle plugin trait for hooks that fire at server start, stop, deploy,
//! and other key events. All methods use JSON strings for WASM ABI compatibility.

/// A plugin that receives notifications at key server lifecycle points.
///
/// **Designed for both compile-time and WASM execution.** All methods
/// receive and return JSON strings for ABI compatibility. Lifecycle hooks
/// fire asynchronously after the response is sent — they must not block
/// the request path.
///
/// WASM plugins: fuel budgets are enforced per call (see `types::fuel`).
pub trait LifecyclePlugin: Send + Sync {
    /// Unique identifier.
    fn name(&self) -> &str;

    /// Execution order among lifecycle plugins. Lower runs first.
    fn priority(&self) -> u32 {
        1000
    }

    /// Called once when the server starts, after all subsystems are initialized.
    ///
    /// `config_json` contains this plugin's config section from bext.config.toml.
    fn on_server_start(&self, _config_json: &str) -> Result<(), String> {
        Ok(())
    }

    /// Called when the server is shutting down gracefully.
    fn on_server_stop(&self) -> Result<(), String> {
        Ok(())
    }

    /// Called after a request has been fully processed and the response sent.
    ///
    /// `event_json` contains: path, method, status, cache_status,
    /// render_time_us, tenant_id, site_id, encoding, is_bot.
    fn on_request_complete(&self, _event_json: &str) -> Result<(), String> {
        Ok(())
    }

    /// Called after a new entry is stored in the ISR cache.
    fn on_cache_write(&self, _key: &str, _tags_json: &str) -> Result<(), String> {
        Ok(())
    }

    /// Called when ISR cache entries are invalidated.
    fn on_cache_invalidate(&self, _pattern: &str, _count: u32) -> Result<(), String> {
        Ok(())
    }

    /// Called after a successful JSC pool reload (bundle updated).
    fn on_reload(&self) -> Result<(), String> {
        Ok(())
    }

    /// Cleanup before plugin unload. Release resources here.
    fn cleanup(&self) -> Result<(), String> {
        Ok(())
    }
}