Expand description
Portable path-denylist rule model shared by the Tower middleware and offline exporters.
This crate owns the declarative rule vocabulary and the compile/evaluate
lifecycle. It has no HTTP runtime dependency: adapters supply a path
string (or InspectionPath) and receive a ShieldDecision. Use
towershield for the Tower layer, and
towershield-cloudflare for offline edge export of the same rules.
§Domain map
| Concept | Types |
|---|---|
| Rule identity / grouping | RuleId, RuleGroup, RuleDisposition |
| Declarative rule | Rule, PathMatcher, CaseSensitivity |
| Authoring collection | RuleSet, RuleSchemaVersion |
| Hot-path evaluation | CompiledRuleSet, InspectionPath, ShieldDecision, ShieldMatch |
| Built-in denylist | DEFAULT_RULES, defaults::default_rules |
| Compile failure | ruleset::CompileError |
§Lifecycle
Build a RuleSet (or clone DEFAULT_RULES), call RuleSet::compile
once at startup (or config reload), then call CompiledRuleSet::evaluate
per request. Allow rules win over deny rules; no match means allow
(fail-open for unmatched application traffic). Disabled rules are dropped
at compile and never evaluated.
§Encoding policy
Path matching uses a derived inspection form — never a mutated request.
See InspectionPath for single-pass percent-decode rules, what is
excluded (query string, .. collapse), and intentional %2F behaviour.
Match metadata in ShieldMatch is for server-side metrics only; do not
embed it in client-facing responses.
§Features
Re-exports§
pub use defaults::DEFAULT_RULES;pub use inspection::InspectionPath;pub use matcher::CaseSensitivity;pub use matcher::MatchKind;pub use matcher::PathMatcher;pub use rule::Rule;pub use rule::RuleDisposition;pub use rule::RuleGroup;pub use rule::RuleId;pub use ruleset::CompiledRuleSet;pub use ruleset::RuleSchemaVersion;pub use ruleset::RuleSet;
Modules§
- defaults
- Conservative built-in scanner-probe denylist shipped with the library.
- inspection
- Single-pass path inspection used as the matching surface.
- matcher
- Semantic path-comparison operators used by
crate::Rulematchers. - rule
- Rule identity, grouping, disposition, and the declarative
Rulevalue. - ruleset
- Rule-set assembly, compile-time validation, and per-request evaluation.
Structs§
- Shield
Match - Identity of the deny rule that produced a
ShieldDecision::Block.
Enums§
- Shield
Decision - Outcome of evaluating an inspection path against a
CompiledRuleSet.