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-pluginAbout 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_pluginsincrates/temps-cli/src/commands/serve/console/startup/plugins.rs.
1. The crate
A new crate under crates/:
- Add it to
membersin the rootCargo.toml. - End its
Cargo.tomlwith[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 fromlib.rs(pub use plugin::FlagsPlugin;). - Add a
descriptionto[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>()yieldsArc<DatabaseConnection>. Trait objects usedyn:require_service::<dyn AuditLogger>(). require_servicefor anything the plugin cannot work without. It fails fast at startup with the missing type's name. Never wrap a required dependency inOption.get_serviceonly for genuinely optional collaborators, whereNonehas a defined meaning. The canonical case isdyn temps_core::ProjectAccessChecker, which isNoneunless another plugin provides team-based access, and which the guard macros treat as a no-op.- Give each component its own
Arcclone. Do not add accessors such asservice.db()to hand dependencies around. - Publish with
context.register_service(Arc::new(MyService::new(..))). If other plugins should depend on an abstraction, register anArc<dyn Trait>.
Two-phase initialisation
PluginManager::initialize_plugins runs:
- Phase 1,
register_services, for every plugin in registration order.require_servicehere only sees services registered by plugins earlier in the list, so register providers before consumers. verify_required_services: every type listed by a plugin'srequired_services()must now be registered; all gaps are reported in one error. Declare cross-plugin requirements there, ascrates/temps-error-tracking/src/plugin.rsdoes withRequiredService::of::<temps_otel::OtelService>().- 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, ascrates/temps-blob/src/plugin.rsdoes.
Routes, middleware and OpenAPI are collected after both phases.
Routes and OpenAPI
configure_routesreturns authenticated routes (the auth middleware puts anAuthContextin the request; handlers takeRequireAuth). ReturnNoneif the crate has no endpoints.configure_public_routesis 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
/apiprefix;build_applicationadds 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_schemareturns the crate's#[derive(OpenApi)]doc. A route missing from it is missing from both generated clients.configure_middlewareexists 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