Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Other skills

temps-add-plugin

Add a TempsPlugin so a crate's services, routes and OpenAPI schema are wired into the server - the trait in temps-core, register_services with require_service vs get_service, the two-phase initialisation, configure_routes/configure_public_routes/openapi_schema, and where the plugin list lives in the console startup. Use when creating a new feature crate, or when a crate needs to provide or consume a shared service.

gotempsh · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add gotempsh/temps --skill temps-add-plugin

About this skill


name: temps-add-plugin description: Add a TempsPlugin so a crate's services, routes and OpenAPI schema are wired into the server - the trait in temps-core, register_services with require_service vs get_service, the two-phase initialisation, configure_routes/configure_public_routes/openapi_schema, and where the plugin list lives in the console startup. Use when creating a new feature crate, or when a crate needs to provide or consume a shared service.

Add a plugin

Every feature crate plugs into the server through TempsPlugin. The plugin builds the crate's services from shared ones, publishes its own services for other plugins, and returns its router and OpenAPI document.

  • Trait and runtime: crates/temps-core/src/plugin.rs (TempsPlugin, ServiceRegistrationContext, PluginContext, PluginRoutes, RequiredService, PluginManager).
  • Smallest complete example: crates/temps-flags/src/plugin.rs (one service, one router, one OpenAPI doc, no background work).
  • Example with declared requirements: crates/temps-error-tracking/src/plugin.rs.
  • Example with deferred initialisation: crates/temps-blob/src/plugin.rs.
  • Where plugins are registered: register_builtin_plugins in crates/temps-cli/src/commands/serve/console/startup/plugins.rs.

1. The crate

A new crate under crates/:

  • Add it to members in the root Cargo.toml.
  • End its Cargo.toml with [lints] / workspace = true.
  • Typical layout, as in temps-flags: lib.rs, error.rs, services/, handlers/{mod,handler,types,audit}.rs, plugin.rs. Re-export the plugin from lib.rs (pub use plugin::FlagsPlugin;).
  • Add a description to [package].

2. Implement TempsPlugin

Shape of crates/temps-flags/src/plugin.rs:

pub struct FlagsPlugin;

impl TempsPlugin for FlagsPlugin {
    fn name(&self) -> &'static str {
        "flags"
    }

    fn register_services<'a>(
        &'a self,
        context: &'a ServiceRegistrationContext,
    ) -> Pin<Box<dyn Future<Output = Result<(), PluginError>> + Send + 'a>> {
        Box::pin(async move {
            let db = context.require_service::<DatabaseConnection>();
            context.register_service(Arc::new(FlagService::new(db)));
            Ok(())
        })
    }

    fn configure_routes(&self, context: &PluginContext) -> Option<PluginRoutes> {
        let flag_service = context.require_service::<FlagService>();
        let audit_service = context.require_service::<dyn AuditLogger>();
        let project_access_checker = context.get_service::<dyn temps_core::ProjectAccessChecker>();
        let app_state = Arc::new(FlagsAppState { flag_service, audit_service, project_access_checker });
        Some(PluginRoutes::new(configure_routes().with_state(app_state)))
    }

    fn openapi_schema(&self) -> Option<OpenApi> {
        Some(<FlagsApiDoc as OpenApiTrait>::openapi())
    }
}

Also provide new() and Default.

Services: require_service vs get_service

  • Services are keyed by type and returned as Arc<T>: require_service::<DatabaseConnection>() yields Arc<DatabaseConnection>. Trait objects use dyn: require_service::<dyn AuditLogger>().
  • require_service for anything the plugin cannot work without. It fails fast at startup with the missing type's name. Never wrap a required dependency in Option.
  • get_service only for genuinely optional collaborators, where None has a defined meaning. The canonical case is dyn temps_core::ProjectAccessChecker, which is None unless another plugin provides team-based access, and which the guard macros treat as a no-op.
  • Give each component its own Arc clone. Do not add accessors such as service.db() to hand dependencies around.
  • Publish with context.register_service(Arc::new(MyService::new(..))). If other plugins should depend on an abstraction, register an Arc<dyn Trait>.

Two-phase initialisation

PluginManager::initialize_plugins runs:

  1. Phase 1, register_services, for every plugin in registration order. require_service here only sees services registered by plugins earlier in the list, so register providers before consumers.
  2. verify_required_services: every type listed by a plugin's required_services() must now be registered; all gaps are reported in one error. Declare cross-plugin requirements there, as crates/temps-error-tracking/src/plugin.rs does with RequiredService::of::<temps_otel::OtelService>().
  3. Phase 2, initialize_plugin_services(&PluginContext): every service is registered, so a plugin can look up others and load configuration from the database. Do not block startup on slow work (pulling an image, starting a container); spawn it, as crates/temps-blob/src/plugin.rs does.

Routes, middleware and OpenAPI are collected after both phases.

Routes and OpenAPI

  • configure_routes returns authenticated routes (the auth middleware puts an AuthContext in the request; handlers take RequireAuth). Return None if the crate has no endpoints.
  • configure_public_routes is for endpoints without a user session (tracking pixels, inbound webhooks, token-authenticated delivery). Each one still authenticates its caller somehow; say how in the handler doc.
  • Paths have no /api prefix; build_application adds it. Use {param}.
  • Two plugins must not register the same method and path. Replacing an existing route is done with PluginRoutes::with_override, not a second .route().
  • openapi_schema returns the crate's #[derive(OpenApi)] doc. A route missing from it is missing from both generated clients.
  • configure_middleware exists for the rare plugin that adds middleware.

Handlers themselves follow the temps-add-handler skill.

3. Wire it into the server

In register_builtin_plugins (`crates/temps-cli/src/commands/ser

Read the complete source ↗