flowbrigade 0.1.4

# flowbrigade Rust bindings

Rust bindings for FlowBrigade's experimental C ABI.

The Nim package remains the reference implementation. This crate is a thin,
safe wrapper around the exported C ABI and intentionally starts with the stable
subset already present in `include/flowbrigade.h`.

This crate requires Nim/Nimble at build time unless `FLOWBRIGADE_LIB_DIR`
points to an existing native FlowBrigade library. See
[REQUIREMENTS.md](REQUIREMENTS.md) for the full setup requirements.

## Compatibility

`flowbrigade` Rust crate `0.1.4` targets FlowBrigade core `0.4.1` or later and
FlowBrigade C ABI version `2`.

The Rust crate version and the FlowBrigade core version are intentionally
separate. The crate version tracks the Rust wrapper's own API stability, while
the core version and C ABI version describe the native library it links to.

## Installation

Install Nim and FlowBrigade first:

```sh
curl https://nim-lang.org/choosenim/init.sh -sSf | sh
nimble refresh
nimble install flowbrigade
```

Then add the Rust crate:

```sh
cargo add flowbrigade
```

During `cargo build`, this crate uses `nimble path flowbrigade` to find the
installed Nim package, builds FlowBrigade's C ABI library into Cargo's build
output directory, and links the Rust wrapper to it.

For local FlowBrigade development, point the binding at a checkout:

```sh
FLOWBRIGADE_SOURCE_DIR=/path/to/flowbrigade cargo test
```

If you already built the native library yourself, set `FLOWBRIGADE_LIB_DIR` to
the directory containing `libflowbrigade.so`, `libflowbrigade.dylib`, or
`flowbrigade.dll`.

## Example

```rust
use std::time::Duration;

use flowbrigade::TokenBucket;

let mut bucket = TokenBucket::new(10, Duration::from_secs(1), 20)?;
let decision = bucket.consume(1)?;

assert!(decision.allowed);
# Ok::<(), flowbrigade::Error>(())
```

## Implemented Surface

| Area | Rust API |
| --- | --- |
| ABI metadata | `abi_version`, `abi_version_string`, `abi_supports` |
| Duration helpers | `parse_duration`, `format_duration` |
| Backoff | `BackoffPolicy::fixed`, `BackoffPolicy::linear`, `BackoffPolicy::exponential`, `delay_for` |
| Token bucket | `TokenBucket` with inspect, consume, reset, configuration, and available-token helpers |
| GCRA | `GcraLimiter` with inspect, consume, allow, reset, configuration, interval, and capacity helpers |
| Fixed window | `FixedWindow` with inspect, consume, reset, configuration, and usage helpers |
| Keyed fixed window | `KeyedFixedWindow` with inspect, consume, clear, reset, reset-all, active-key, and configuration helpers |
| Keyed GCRA | `KeyedGcraLimiter` with inspect, consume, allow, prune, clear, reset, reset-all, active-key, and configuration helpers |
| Sliding window | `SlidingWindow` with inspect, consume, reset, configuration, and current-use helpers |
| Circuit breaker | `CircuitBreaker` with allow, success/failure recording, and state helpers |
| Bulkhead | `Bulkhead` with inspect, acquire, and release helpers |
| Keyed bulkhead | `KeyedBulkhead` with inspect, acquire, release, clear, and active-key helpers |
| Budget ledger | `BudgetLedger` with inspect, consume, refund, reset, and reset-all helpers |
| Retry allowance | `RetryAllowance` with original/retry recording, retry inspection, allow, clear, reset, reset-all, prune, active-key, and configuration helpers |
| Timeout and deadline | `Timeout`, `Deadline`, elapsed/remaining/expired checks, and deadline clamp |
| Lock store | `LockStore`, `LockLease`, acquire/release/refresh/inspect helpers |
| Throttle and debounce | `Throttle`, `Debouncer` state helpers |
| Retry callback runner | `retry_run` with Rust callback wrappers |
| Fallback callback runner | `fallback_run` with ordered Rust provider callbacks |
| Limiter registry | `LimiterRegistry` for named fixed, sliding, token bucket, keyed fixed, compound, and callback-backed stored fixed-window limiters |
| Observability export | `RateLimitDecision` and `BudgetDecision` JSON/Prometheus text export |