# requisite
`requisite` makes data-handling requirements part of Rust function signatures.
Values carry the state required by the next operation, and APIs state that
requirement in their parameter types.
```rust
use requisite::prelude::*;
fn db_lookup(id: Tainted<u64, Trusted>) -> String { /* ... */ }
let body = Tainted::<_, Untrusted>::from_input(request_body);
let customer_id = sanitize(body, clean_customer_id);
db_lookup(customer_id);
```
The receiving function states its requirement in its parameter type. The
compiler then verifies that callers perform the required transition.
| [`trust`](#trust) | routes external input through a named sanitizer before trusted use |
| [`confidence`](#confidence) | converts a probability into an action tier and issues proof for the highest tier |
| [`fresh`](#freshness) | checks TTLs at read time and binds scoped values to their use site |
## Installation
```sh
cargo add requisite
```
`requisite` supports Rust 1.70 and later.
## Guides
| [Getting started](docs/getting-started.md) | add `requisite` and build an end-to-end flow |
| [Trust transitions](docs/trust.md) | route external input through infallible or fallible policies |
| [Confidence gates](docs/confidence.md) | validate probabilities and authorize high-confidence actions |
| [Freshness](docs/freshness.md) | enforce TTLs, recover stale values, and scope live data |
| [Integration patterns](docs/integration.md) | place wrappers at application boundaries and design typed APIs |
## Trust
```rust
use requisite::prelude::*;
fn db_lookup(id: Tainted<u64, Trusted>) -> String { /* ... */ }
let raw = Tainted::<_, Untrusted>::from_input("42; DROP TABLE customers".into());
println!("{:?}", raw.as_ref());
let clean = try_sanitize(raw, |s| {
s.chars()
.filter(char::is_ascii_digit)
.collect::<String>()
.parse::<u64>()
})?;
db_lookup(clean);
```
`Tainted<T, Untrusted>` marks data at an input boundary. `sanitize` handles
infallible transformations, while `try_sanitize` returns validation errors to
the caller. Successful transitions produce `Tainted<U, Trusted>`, which trusted
sinks accept directly.
The sanitizer closure defines what “trusted” means for a specific sink. Keep
the destination's cleaning policy in that closure. `widen()` supports APIs that
accept a lower trust requirement.
See [Trust transitions](docs/trust.md) for validation, type-changing policies,
and sink design.
## Confidence
`Confident<T>` carries a value and a validated probability. `gate()` applies the
default thresholds, and `gate_with()` accepts application-defined thresholds.
```rust
let aurora = Confident::new(forecast(kp_index), 0.97)?;
let plan = match aurora.gate() {
Gate::HighConfidence(proof, _) => {
wake_slepp(proof);
"woke him up"
}
Gate::Likely(_) => {
buzz_phone();
"sent a buzz"
}
Gate::Unsure(_) => "logged it",
};
```
The highest tier includes a `Certain` token. Functions such as `wake_slepp` can
require that token, making a successful confidence check part of their call
contract. Lower tiers remain available for proportionate actions such as a
notification or log entry.
```rust
let forecast = Confident::new(predicted_event, 0.99)?;
let thresholds = Thresholds::new(0.70, 0.98)?;
match forecast.gate_with(thresholds) {
Gate::HighConfidence(proof, value) => act(proof, value),
Gate::Likely(value) => notify(value),
Gate::Unsure(value) => record(value),
}
```
Custom thresholds may raise the `Certain` boundary above `0.95`. The lower
bound keeps every `Certain` token consistent for functions that require one.
See [Confidence gates](docs/confidence.md) for threshold configuration and
typed action authorization.
## Freshness
```rust
let quote = Fresh::fetch(price, Duration::from_secs(30));
match quote.get() {
Ok(price) => charge(customer, *price),
Err(stale) => println!("price is {} old, refetching", stale.age.as_secs()),
}
```
`Fresh::get` compares the value's age with its TTL and returns either the value
or a `Stale` error containing both durations. `into_inner` performs the same
check while consuming the wrapper, allowing ownership of a fresh non-`Clone`
value to move into the next operation. A stale result returns the value in
`StaleValue<T>`. `fetched_at` supports deterministic tests and rejects
timestamps ahead of the current monotonic clock.
`with_live` handles values whose validity is tied to one operation:
```rust
with_live(price, |live| {
let total = live.get().cents + tax;
total
});
```
The branded `Live` value stays within the closure while derived owned values can
be returned. The closure’s return type is independent of the private lifetime
brand, so retaining `Live` produces a lifetime error at the return site.
See [Freshness](docs/freshness.md) for cache access, stale-value recovery, and
deterministic tests.
## Enforcement model
| trusted sink arguments | `Tainted<T, Trusted>` parameter types |
| confidence-based action tiers | `Confident::gate()`, `gate_with()`, and `Gate<T>` |
| high-confidence action authorization | private `Certain` construction |
| operation-scoped values | branded `Live<'id, T>` lifetimes |
| TTL validity | `Fresh::get()` or `into_inner()` at read time |
| sanitization policy | the closure passed to `sanitize` or `try_sanitize` |
Runtime checks produce types that carry their result into the next operation.
For example, `gate()` converts a probability into a `Gate<T>`, and the highest
tier carries the `Certain` token required by sensitive actions.
## Compile-time guarantees
`tests/ui/` contains compile-fail cases for each type-level contract. `trybuild`
compares the compiler output with checked-in snapshots, so CI detects changes
that weaken a contract.
| `untrusted_to_sink.rs` | trusted sinks require sanitized input |
| `widen_upward.rs` | trust promotion goes through `sanitize` |
| `confidence_as_bool.rs` | confidence values go through `gate` |
| `forge_certain.rs` | `Certain` originates from the highest gate tier |
| `escape_live.rs` | scoped values remain inside their closure |
Regenerate snapshots after an intentional compiler diagnostic change:
```sh
TRYBUILD=overwrite cargo test --test compile_fail
```
Review the resulting diff to confirm that each failure still exercises its
documented contract.
## Try it
```sh
cargo run --example payment_flow
cargo test
```
## Layout
```
src/trust.rs Tainted<T, Tr>, sanitize, widen
src/confidence.rs Confident<T>, gate() -> Gate, Certain
src/fresh.rs Fresh<T> with a TTL; scoped::with_live
examples/payment_flow.rs payment and alerting example
tests/runtime.rs behavior tests
tests/ui/*.rs + .stderr compile-fail tests
docs/ user guides
```
## License
Licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.