Add Rules documentation updates

[ngayerie]

Summary

Documentation updates covering undocumented behaviors, configuration guidance, and execution order details across Rules, ruleset engine, custom errors, and bulk redirects.

Source: Wiki review page

Changes (8 updates across 6 files)

#	Topic	File	Change
1	http.host always raw	src/content/fields/index.yaml	Clarifies that Origin Rules host overrides are not reflected in http.host seen by other rule phases, Workers, or request.cf
3	Custom Errors vs default WAF block page	rules/custom-errors/index.mdx	Explicit clarification that Custom Error Rules don't override the default WAF block page (legacy Custom Pages system)
4	Custom error asset size limit	rules/custom-errors/index.mdx	Documents ~1.5 MB limit after base64 inlining of referenced resources
5	Bulk Redirects and WAF	rules/url-forwarding/bulk-redirects/index.mdx	Bulk Redirects run after WAF — firewall events still log even when request is later redirected
6	X-Real-IP workaround	rules/transform/request-header-modification/index.mdx	Use Snippets or Workers with subrequest to set protected headers
7	x-forwarded-for re-added by proxy	rules/transform/request-header-modification/index.mdx	Cloudflare's backend proxy re-adds x-forwarded-for after all rule phases (not the cache service)
11	64 regex per rule limit	ruleset-engine/rules-language/expressions/index.mdx	New section documenting the maximum number of regular expressions per rule expression
12	Preserve query string	rules/url-forwarding/bulk-redirects/reference/parameters.mdx	Caution that enabling overwrites the target URL's query string entirely

Excluded (per Jira)

• Item 2: Nesting wildcard_replace inside regex_replace
• Item 8: Cloud Connector status display
• Item 9: Page Rules deprecation
• Item 10: SNI override (Trust & Safety approval)

Stats

6 files changed, +32 insertions, -5 deletions

Resolves DEE-3644

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
/src/content/docs/rules/	@pedrosousa, @cloudflare/appsec-reviewers, @elithrar, @cloudflare/product-owners
/src/content/docs/ruleset-engine/	@pedrosousa, @cloudflare/appsec-reviewers, @elithrar, @cloudflare/product-owners
*	@cloudflare/product-owners

[ask-bonk]

Review for PR #31670

Summary

This 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 checks

✅ pnpm run check        — 0 errors
✅ pnpm run format:core:check — All files formatted correctly
✅ pnpm run lint         — No issues

Suggested labels

docs, rules, ruleset-engine

---

Inline review comments

1. src/content/fields/index.yaml — imprecise request.cf reference

Line 18 (new description):

"...this change is not reflected in the http.host value seen by other rule phases ..., [Cloudflare Workers], or the request.cf object."

Issue: request.cf is an object that holds Cloudflare-specific metadata (e.g. colo, country, tlsClientAuth). It does not directly expose an http.host property. Workers read the Host header via request.headers.get("host") or from the request URL. Referencing request.cf as something that "sees" http.host could confuse readers.

Suggestion: Consider tightening the wording. For example:

If you have configured [Origin Rules](/rules/origin-rules/) that change the hostname, this change is not reflected in the `http.host` value seen by other rule phases (such as custom rules, cache rules, or transform rules) or [Cloudflare Workers](/workers/). All rule phases and Workers evaluate against the original, unmodified host.

Alternatively, if the intent is to mention request.cf properties that are host-derived, make that explicit:

...or host-derived properties in the [`request.cf`](/workers/runtime-apis/request/#incomingrequestcfproperties) object.

---

2. src/content/docs/rules/custom-errors/index.mdx — section hierarchy

Line 92 (new heading):

## Size limits

Issue: The size limit applies only to custom error assets, not to Error Pages or inline custom error rule responses. As an H2, it sits at the same level as ## Custom Error Assets, ## Custom Error Rules, and ## Error Pages, which makes it look like a peer topic.

Suggestion: Consider nesting it as an H3 under ## Custom Error Assets:

### Size limits

This keeps the page structure accurate (the limit is asset-specific) while still surfacing it in the table of contents. Not a blocker.

---

3. src/content/docs/rules/custom-errors/index.mdx — minor style inconsistency

Line 43 (updated note):

"...A custom WAF response configured directly in a WAF rule action takes precedence over both an Error Page and a Custom Error Rule."

Observation: The original text used singular "custom error rules" (lowercase) at the end; the update uses "Custom Error Rule" (title case). Elsewhere on the page the feature is referred to as "Custom Error Rules" (title case, plural) and "custom error rule" (sentence case, singular). This single instance of singular title case is slightly inconsistent but acceptable.

---

What changed (file-by-file)

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.

github run

[github-actions]

Preview URL: https://af77a26c.preview.developers.cloudflare.com
Preview Branch URL: https://ngayerie-dee-3644.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/rules/url-forwarding/bulk-redirects/	https://ngayerie-dee-3644.preview.developers.cloudflare.com/rules/url-forwarding/bulk-redirects/
https://developers.cloudflare.com/rules/custom-errors/	https://ngayerie-dee-3644.preview.developers.cloudflare.com/rules/custom-errors/
https://developers.cloudflare.com/ruleset-engine/rules-language/expressions/	https://ngayerie-dee-3644.preview.developers.cloudflare.com/ruleset-engine/rules-language/expressions/
https://developers.cloudflare.com/rules/transform/request-header-modification/	https://ngayerie-dee-3644.preview.developers.cloudflare.com/rules/transform/request-header-modification/
https://developers.cloudflare.com/rules/url-forwarding/bulk-redirects/reference/parameters/	https://ngayerie-dee-3644.preview.developers.cloudflare.com/rules/url-forwarding/bulk-redirects/reference/parameters/