mix oban_powertools.limiter.simulate (oban_powertools v0.5.1)

Previews the per-request reserved/blocked verdicts for a worker's declared limiter config without touching the database, emitting telemetry, or writing any audit rows. Runs --count N sequential reservations against a fresh empty bucket through the pure Limits.compute_reservation/4 core.

Exit Codes

Flags

--worker MOD             Worker module to read declared :limits from.
                         (required)
--bucket-capacity N      Override declared bucket_capacity.
--bucket-span-ms N       Override declared bucket_span_ms (milliseconds).
--weight N               Override declared default_weight per reservation.
--count N                Number of sequential reservations to simulate
                         (default: 1).
--partition KEY          Override resolved partition_key (default:
                         "__global__").
--repo MyApp.Repo        Ecto repo module. Falls back to
                         `config :oban_powertools, repo: MyApp.Repo`.
--format human|json      Output format. "human" (default) renders a
                         readable per-request sequence with ANSI color
                         that auto-degrades in CI/non-TTY. "json" emits
                         a machine-readable payload with a
                         `schema_version: 1` stability contract.

Boot Strategy

This task starts only the Ecto repo via Ecto.Migrator.with_repo/2 for CLI-family consistency. The simulation loop itself is pure and writes zero rows to oban_powertools_limit_states or oban_powertools_limit_resources.

Rate-Limit Glossary

Source: ObanPowertools.Limits.Glossary.text/0

token_bucket — The rate-limiting algorithm used by ObanPowertools limiters. Each partition has a bucket of bucket_capacity tokens. Each reservation consumes weight tokens. The bucket refills (resets to zero tokens used) after bucket_span_ms milliseconds have elapsed since bucket_started_at.

bucket_capacity — The maximum number of tokens available per bucket window. A reservation that would bring tokens_used + weight above this value is blocked with the limit_reached blocker code.

bucket_span_ms — The duration of one bucket window in milliseconds. After this interval elapses since bucket_started_at, the bucket resets and tokens are available again. Used to compute retry_at for a limit_reached block.

weight — The per-reservation token cost. Defaults to the resource's default_weight (usually 1). Each successful reservation consumes weight tokens from the bucket.

weight_by — A dynamic weight resolver declared on the worker (e.g. weight_by: {:args, :cost}). At enqueue time the resolved value is bound to the reservation snapshot as the effective weight.

partition — A named isolation group within a limiter resource. Each partition maintains its own independent token bucket. For scope: :global limiters there is one partition (__global__); for scope: :partitioned there is one bucket per resolved partition_key.

partition_by — A dynamic partition key resolver declared on the worker (e.g. partition_by: {:args, :user_id}). At enqueue time the resolved value becomes the partition_key used to look up the correct bucket.

scope — The partitioning strategy for a limiter resource. global means one shared bucket across all callers. partitioned means one independent bucket per resolved partition_key, enabling per-user, per-account, or per-tenant limits.

cooldown — An operator-set hold on a partition until a specific DateTime. While a cooldown is active, all reservations for that partition are blocked with the cooldown blocker code regardless of remaining bucket capacity. Useful for propagating backpressure signals (e.g. HTTP 429 responses) into the limiter.

limit_reached — Blocker code returned when tokens_used + weight > bucket_capacity. The retry_at field indicates when the bucket will reset (bucket_started_at + bucket_span_ms, clamped to at least now).

cooldown (blocker code) — Blocker code returned when a resource partition is under an active operator cooldown. The retry_at field is cooldown_until — the DateTime at which the cooldown expires and reservations are permitted again.