Trait Plugin

Source

pub trait Plugin:
    Sized
    + Send
    + 'static {
    // Required method
    fn build(self, app: AppBuilder) -> AppBuilder;

    // Provided methods
    fn name(&self) -> Cow<'static, str> { ... }
    fn contract(&self) -> Option<PluginContract> { ... }
}

Expand description

A reusable Autumn integration that wires itself into an AppBuilder.

See the module-level documentation for conventions and examples.

Required Methods§

Source

fn build(self, app: AppBuilder) -> AppBuilder

Apply this plugin’s configuration to the builder.

Called exactly once per AppBuilder. Implementations typically chain AppBuilder::on_startup, AppBuilder::on_shutdown, AppBuilder::nest, AppBuilder::with_extension and (with the db feature) AppBuilder::migrations.

Plugins can also install tier-1 subsystem replacements here — AppBuilder::with_config_loader, AppBuilder::with_pool_provider (with the db feature), AppBuilder::with_telemetry_provider, and AppBuilder::with_session_store — which is the canonical way to distribute a custom subsystem (e.g. AwsSecretsConfigPlugin) for downstream consumers as a one-line install. See docs/guide/extensibility.md for the full extensibility model.

Provided Methods§

Source

fn name(&self) -> Cow<'static, str>

Stable identifier used for duplicate-registration detection.

Defaults to std::any::type_name of the concrete plugin struct, so two instances of the same type collide by default. Override to allow multiple instances of the same type to coexist; the return type is Cow<'static, str> so plugins can compute a unique label from runtime configuration without leaking memory.

Source

fn contract(&self) -> Option<PluginContract>

Declare which autumn-web versions this plugin supports, and any experimental surface it knowingly depends on.

Returning None (the default) declares nothing and changes no behaviour — every plugin written before the contract existed keeps working. Returning a contract whose autumn_web range excludes the framework this plugin is compiled into makes AppBuilder::plugin panic at registration with a diagnostic naming both versions and both remedies. That is deliberate: a silent mismatch is the failure mode this contract exists to remove.

See plugin_contract for the stability tiers and the SemVer policy each one carries.

use autumn_web::plugin_contract::PluginContract;

impl Plugin for MyPlugin {
    fn contract(&self) -> Option<PluginContract> {
        Some(
            PluginContract::new(env!("CARGO_PKG_NAME"))
                .plugin_version(env!("CARGO_PKG_VERSION"))
                .autumn_web("0.9"),
        )
    }

    fn build(self, app: AppBuilder) -> AppBuilder { app }
}