[Rules] Add Rules documentation updates - #31670
Conversation
Document undocumented behaviors and configuration guidance across Rules, ruleset engine, custom errors, and bulk redirects: 1. http.host always raw, even with Origin Rules host override 3. Custom Error Rules vs default WAF block page distinction 4. Custom error asset size limit (1.5 MB after base64 inlining) 5. Bulk Redirects execution order relative to WAF 6. X-Real-IP and other protected headers via Snippets/Workers subrequest 7. x-forwarded-for re-added by Cloudflare backend proxy after rule phases 11. Maximum 64 regular expressions per rule expression 12. Preserve query string overwrites target URL query string Resolves DEE-3644
github-actions
Bot
added
size/s
product:rules
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
Review for PR #31670SummaryThis PR adds accurate, tightly-scoped documentation updates across 6 files (+32/-5) in the Rules, ruleset engine, and fields reference areas. The changes address previously undocumented limits, execution-order edge cases, and configuration guidance sourced from an internal wiki review. Automated checksSuggested labels
Inline review comments1.
|
| File | Change |
|---|---|
src/content/fields/index.yaml |
Expands http.host description to clarify that Origin Rules overrides are invisible to other phases, Workers, and request.cf. |
src/content/docs/rules/custom-errors/index.mdx |
Clarifies that Custom Error Rules do not override the default WAF block page; adds new Size limits section documenting the ~1.5 MB asset limit. |
src/content/docs/rules/url-forwarding/bulk-redirects/index.mdx |
New section explaining that Bulk Redirects run after WAF, so firewall events are still logged even for redirected requests. |
src/content/docs/rules/transform/request-header-modification/index.mdx |
Adds workaround for setting protected headers (e.g. x-real-ip) via Snippets or Workers subrequests; corrects x-forwarded-for re-addition behavior from "cache service" to "backend proxy". |
src/content/docs/ruleset-engine/rules-language/expressions/index.mdx |
New section documenting the 64-regular-expression limit per rule expression. |
src/content/docs/rules/url-forwarding/bulk-redirects/reference/parameters.mdx |
Adds :::caution admonition that Preserve query string overwrites any query string present in the target URL. |
Verdict
Approve with minor suggestions. The content is technically accurate, follows the style guide, and all CI checks pass. The request.cf wording in index.yaml is the only item that should be tightened before merge.
- http.host: drop misleading request.cf reference (it holds metadata
like colo/country, not the host header)
- custom-errors: nest 'Size limits' as H3 under 'Custom Error Assets'
(the limit is asset-specific, not page-wide)
- custom-errors: align casing ('custom error rule' lowercase to match
the rest of the page)
Review✅ No issues found in commit Code ReviewThis code review is in beta and may not always be helpful — use your judgment. ✅ No code review issues found. Style Guide Review✅ No style-guide issues found. CommandsOnly codeowners can run commands. Post a comment with the command to trigger it.
|
mabba verified all 8 claims against fl2, rulesets-control-plane, custom-pages, nginx-ssl, pingora-origin, and pingora-backend-router. Items 1, 5, 6b, 7, and 11 are verified accurate. Three items needed rewording: - #4 base64 inlining: only images and binary resources (including those referenced from CSS via url()) are base64-encoded. CSS and JavaScript files are inlined as plain text inside <style>/<script> tags. Verified at custom-pages/collapsify/src/flattener.rs. - #6 x-real-ip workaround: the protected-header restriction is enforced by an unconditional rewrite in fl2/lib/module-header-upstreaming. Workers and Snippets can influence the value via a fetch() subrequest, but the value must be a syntactically valid IP address, and cross-zone subrequests are hard-overridden to an internal Cloudflare address to prevent IP spoofing. Verified at fl2/bin/fl2/src/visitor.rs:140-145. - #12 Preserve query string: the target's query string is *always* dropped when Preserve query string is enabled — unconditionally, even when the request has no query string. Verified at fl2/bin/fl2/src/rulesets/actions/redirect.rs:263-271.
ngayerie
changed the title
Add Sam Marsh and Maurizio Abba as code owners for /src/content/docs/rules/. Add Maurizio Abba as code owner for /src/content/docs/ruleset-engine/.
3 participants
Summary
Documentation updates covering undocumented behaviors, configuration guidance, and execution order details across Rules, ruleset engine, custom errors, and bulk redirects.
Changes
http.hostalways rawsrc/content/fields/index.yamlhttp.hostseen by other rule phases or Workersrules/custom-errors/index.mdxrules/custom-errors/index.mdxrules/url-forwarding/bulk-redirects/index.mdxrules/transform/request-header-modification/index.mdxfetch()subrequest; value must be a valid IP; cross-zone subrequests are hard-overriddenrules/transform/request-header-modification/index.mdxx-forwarded-forafter all rule phases (not the cache service)ruleset-engine/rules-language/expressions/index.mdxrules/url-forwarding/bulk-redirects/reference/parameters.mdxResolves DEE-3644