towershield_cloudflare/lib.rs
1//! Offline Cloudflare Ruleset Engine exporter for portable shield rules.
2//!
3//! Turns a [`towershield_core::RuleSet`] into Cloudflare expression text, a
4//! Rulesets API-shaped JSON payload, and a human-readable
5//! [`ExportReport`]. Export is pure CPU: no network, credentials, zone IDs,
6//! Terraform, or live deploy side effects. The Tower middleware remains the
7//! authoritative in-process denylist; edge rules are a coarse first filter.
8//!
9//! # Domain map
10//!
11//! | Concept | Types |
12//! |---|---|
13//! | Entry point | [`CloudflareExporter`] |
14//! | Run configuration | [`CloudflareExportOptions`], [`HostScope`], [`options::CloudflareAction`] |
15//! | Plan budgets | [`CloudflarePlan`], [`CloudflareCapabilities`] |
16//! | Success artifacts | [`CloudflareOutput`], [`ExportReport`], [`output::ExportDiagnostic`] |
17//! | Hard failure | [`exporter::ExportError`] |
18//! | Matcher lowering | [`expression`] |
19//! | Known Tower↔edge gaps | [`parity`] |
20//!
21//! ## Pipeline
22//!
23//! 1. Filter enabled **deny** rules (allow rules are Tower-only exclusions).
24//! 2. Lower each matcher to a Cloudflare fragment ([`expression`]).
25//! 3. Emit soft diagnostics for unsupported or approximated operators.
26//! 4. Pack fragments into plan-sized `or` groups with optional host scope.
27//! 5. Return [`CloudflareOutput`] for review or hand-off to your deploy tooling.
28//!
29//! Hard failures ([`exporter::ExportError`]) abort export: missing host
30//! scope, nothing exportable, or plan budget overflow. Soft gaps appear as
31//! [`output::ExportDiagnostic`] entries inside a successful output.
32//!
33//! ## Parity
34//!
35//! Edge matching and the Tower path denylist are not byte-identical. See
36//! [`parity`] for field normalisation, segment/wildcard gaps, and how the
37//! exporter reports them.
38//!
39//! # Features
40//!
41//! | Feature | Effect |
42//! |---|---|
43//! | `serde` (default) | JSON pretty-print of Rulesets API payloads |
44//! | `regex` (default) | Export regex matchers and include the broader rule tier |
45//! | `rayon` | Forwarded to `towershield-core` (compile-side only) |
46#![forbid(unsafe_code)]
47#![deny(missing_docs)]
48#![deny(clippy::all)]
49
50pub mod exporter;
51pub mod expression;
52pub mod options;
53pub mod output;
54pub mod parity;
55pub mod plan;
56
57pub use exporter::CloudflareExporter;
58pub use options::{CloudflareExportOptions, HostScope};
59pub use output::{CloudflareOutput, ExportReport};
60pub use plan::{CloudflareCapabilities, CloudflarePlan};