Capability SDK

Third-party product capabilities depend on boson-sdk. Host applications compose them through boson-runtime.

Public surface

Capability authors should import from boson_sdk::prelude:

• Capability, CapabilityDescriptor, MigrationSet, JobHandler
• EventEnvelope, EventConsumer, publish_in_tx
• AuthenticatedUser, IdentityAuth, user_auth_middleware
• AdminPrincipal, require_scope
• PlatformConfig::capability_config, RequestContext, api_error

Do not depend on adapter crates or vendor SDKs from a capability.

Capability lifecycle

1. Declare descriptor(), scopes(), and optional migrations().
2. Return pre-bound app_router() / admin_router() routers.
3. Emit events with publish_in_tx inside the same SQL transaction as domain writes.
4. Register event_consumers(), job_handlers(), and health_checks() as needed.
5. Register capabilities from a shared composition module used by migrate, Server, and Worker.

// apps/app/src/lib.rs
pub fn register_app(ctx: &RuntimeContext, registry: &mut CapabilityRegistry) -> Result<()> {
    registry.register(Arc::new(ItemsCapability::new(
        ctx.database.clone(),
        ctx.identity_auth.clone(),
        &ctx.config,
    )?))?;
    Ok(())
}

// apps/server/src/main.rs
boson_runtime::Builder::from_env()
    .register(my_app_app::register_app)
    .run_server()
    .await

Builder::register and Builder::capability accumulate installers in order. Builder::extend remains as a compatibility alias that also appends.

Configuration

Core platform sections remain closed. Capability-owned settings live under:

capabilities:
  items:
    max_items: 100

Deserialize with config.capability_config::<T>("items").

Migrations

Platform migrations are embedded in boson-runtime at compile time and applied into _sqlx_migrations; deployed binaries do not need the Boson source tree. Capability migrations are directories declared by Capability::migrations() and applied in registration order into a dedicated _sqlx_migrations_<capability> table, so version numbers only need to be unique within that capability.

Scopes

Capabilities declare Admin scopes via Capability::scopes(). The runtime collects them after registration and uses the set when issuing Admin API keys. Bootstrap tokens continue to carry *.

Local workflow

boson create my-app
cd my-app
boson doctor
boson start

Infrastructure, migrations, service processes, health gates, and logs stay behind the Boson lifecycle. Use boson status, boson logs, and boson doctor when needed. Migrations are applied by the generated migrate binary during boson start; they are not a separate public CLI command.

For Boson contributors, the hidden --boson-path create option can point a generated app at a local checkout. See examples/my-api for a complete standalone reference app.