boson (uf-boson on crates.io)

Main crate — re-exports core types, runtime, optional backends, and the #[task] macro.

The crates.io package is uf-boson (boson is already taken). With [lib] name = "boson", imports stay use boson::….

Source of truth: cargo doc -p uf-boson --features mem,axum --open — guided get-started with Embedded and Remote worker. Published docs: https://docs.rs/uf-boson

Role

• task — #[task] macro and typed send_with
• Boson / BosonBuilder — worker boot
• Feature-gated backends: mem, sqlite, postgres, axum, telemetry-console
• Fleet backends: boson-backend-redis, boson-backend-nats
• prelude — common re-exports

Cargo features

This crate ships with no default features (default = []).

How to run examples

Navigational index: examples/README.md (when-to-use ladder, host-mount sketches, success checks).

Canonical teaching path (start here). Topology docs: Embedded / Remote worker.

1. Embedded — task_macro (standalone)

One process, in-memory backend. No external services.

cargo run -p uf-boson --example task_macro --features mem

Success: stdout prints greet world (actor=…).

2. Remote worker — SQLite (multi-process — run as a set)

Enqueue host and workers share one database file. They are not useful alone.

Local SQLite — 1–2 workers + enqueue:

export BOSON_SQLITE_PATH=/tmp/boson-remote.db

# Terminal 1 — worker A
BOSON_WORKER_ID=worker-a cargo run -p uf-boson --example remote_worker --features sqlite

# Terminal 2 — worker B (optional)
BOSON_WORKER_ID=worker-b cargo run -p uf-boson --example remote_worker --features sqlite

# Terminal 3 — enqueue
cargo run -p uf-boson --example remote_enqueue --features sqlite

3. Remote worker — Postgres (multi-process — run as a set)

Same pattern against a shared database URL (production-shaped durable backend).

export DATABASE_URL=postgres://localhost/boson

# Terminal 1 — worker A
BOSON_WORKER_ID=worker-a cargo run -p uf-boson --example postgres_worker --features postgres

# Terminal 2 — worker B (optional)
BOSON_WORKER_ID=worker-b cargo run -p uf-boson --example postgres_worker --features postgres

# Terminal 3 — enqueue
cargo run -p uf-boson --example postgres_enqueue --features postgres

Stop with Ctrl-C on each worker. Real apps put #[task] handlers in a shared crate and use my_tasks as _; from the worker binary.

Docker quickstart (no local Postgres install): the repo ships a Compose stack at infra/postgres/.

cd infra/postgres && docker compose up -d
export DATABASE_URL="postgres://boson:bench@127.0.0.1:5433/boson_bench"

Then run the worker/enqueue pair above from the repo root. Stop with docker compose -f infra/postgres/docker-compose.yml down.

4. Remote worker — Redis fleet (multi-process — run as a set)

Broker-backed fleet backend — same split shape, many enqueue hosts and workers sharing Redis. Not a uf-boson feature — depends on boson-backend-redis directly (a path dev-dependency in this crate; production apps add it to [dependencies]).

docker run -d --name boson-redis -p 6379:6379 redis:7
export BOSON_REDIS_URL=redis://127.0.0.1:6379

# Terminal 1 — worker A
BOSON_WORKER_ID=worker-a cargo run -p uf-boson --example redis_fleet_worker

# Terminal 2 — enqueue
cargo run -p uf-boson --example redis_fleet_enqueue

5. Remote worker — NATS WorkQueue (multi-process — run as a set)

Broker-backed fleet backend on NATS JetStream WorkQueue streams via connect_auto with BOSON_NATS_QUEUE_MODE=workqueue. Not a uf-boson feature — depends on boson-backend-nats directly.

docker run -d --name boson-nats -p 4222:4222 nats:2.10 -js
export BOSON_NATS_URL=nats://127.0.0.1:4222
export BOSON_NATS_QUEUE_MODE=workqueue

# Terminal 1 — worker A
BOSON_WORKER_POOLS=global BOSON_WORKER_ID=worker-a cargo run -p uf-boson --example nats_workqueue_worker

# Terminal 2 — enqueue
cargo run -p uf-boson --example nats_workqueue_enqueue

Other examples

Production: Boson does not authenticate /api/boson/* by itself. Install host AdminAuth and prefer BOSON_REQUIRE_ADMIN_AUTH=1 — see repository SECURITY.md.

Boot a worker (embedded)

[dependencies]
boson = { package = "uf-boson", version = "0.1.1", features = ["mem"] }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

use std::sync::Arc;

use boson::{configure, task, Boson, ExecutionContext, JsonExecutionContextFactory, MemQueueBackend};

#[task(name = "my_task")]
async fn my_task(ctx: Box<dyn ExecutionContext>) -> boson_core::Result<()> {
    let _ = ctx;
    Ok(())
}

let boson = Boson::builder()
    .queue_backend(Arc::new(MemQueueBackend::new()))
    .execution_context_factory(JsonExecutionContextFactory)
    .auto_registry()
    .build()?;
configure(boson);

With HTTP admin: features = ["mem", "axum"]. Full walkthrough: crate rustdoc Getting started and task_macro.

Define handlers and enqueue

After boot, add handlers with #[task] and enqueue with <TaskName>::send_with(...). See boson-macros for policy attributes.

Configuration precedence

Related crates

• boson-macros — #[boson::task] proc macro
• boson-runtime — worker runtime and builder
• boson-core — shared types and QueueBackend trait
• boson-axum — HTTP admin API