flowbrigade 0.1.4

Rust bindings for FlowBrigade's C ABI.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

# Contributing

Thanks for helping improve the FlowBrigade Rust bindings.

This project is intentionally small. The Nim package remains the reference
implementation, and this crate should wrap FlowBrigade's C ABI rather than
reimplementing flow-control logic in Rust.

## Scope

Good fits:

- safe wrappers around existing `fb_*` C ABI functions
- Rust-friendly result and error types
- tests for FFI edge cases and handle lifetime behavior
- examples and documentation
- CI and packaging improvements

Out of scope:

- independent Rust implementations of FlowBrigade algorithms
- web-framework-specific middleware in this crate
- generic storage/cache abstraction unrelated to exposed FlowBrigade behavior
- adding wrappers for Nim features before they are exported through the C ABI

## Development Setup

This crate targets FlowBrigade core `0.4.0` or later and C ABI version `2`.
Install Nim and FlowBrigade first:

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

For local development against a FlowBrigade checkout, set
`FLOWBRIGADE_SOURCE_DIR`:

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

Then run the Rust checks from this repository:

```sh
cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo run --example quickstart
```

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

## FFI Workflow

Prefer tests first for new wrappers.

1. Add or update a focused Rust test.
2. Confirm it fails for the expected reason.
3. Add the smallest safe wrapper around the existing C ABI.
4. Run `cargo test` and `cargo clippy -- -D warnings`.
5. Update README examples when public behavior changes.

Unsafe code should stay inside the binding layer. Public APIs should expose safe
Rust types unless the caller must explicitly handle raw FFI data.

## Security

For wrappers that accept untrusted input, preserve the validation performed by
FlowBrigade and avoid adding unchecked conversions. For wrappers around mutable
opaque handles, document that handles should not be shared across threads
without synchronization unless the Rust type explicitly provides it.

Report security issues privately using `SECURITY.md`.