[Ruleset Engine] Add query param filtering to Fields reference (#19910)

Author: pedrosousa

src/components/FieldCatalog.tsx

@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useEffect, useState, type ChangeEvent } from "react";
 import FieldBadges from "./fields/FieldBadges";
 import Markdown from "react-markdown";
 import type { CollectionEntry } from "astro:content";
@@ -25,7 +25,7 @@ const FieldCatalog = ({ fields }: { fields: Fields }) => {
 	const categories = [
 		...new Set(
 			fields
-				.map((field) => field.categories)
+				.map((field) => field.categories ?? [])
 				.flat()
 				.sort(),
 		),
@@ -57,6 +57,21 @@ const FieldCatalog = ({ fields }: { fields: Fields }) => {
 		return true;
 	});
 
+	useEffect(() => {
+		// On component load, check for deep-links to categories in the query param
+		const params = new URLSearchParams(window.location.search);
+		const categories = params.getAll("field-category");
+		const searchTerm = params.get("search-term") ?? "";
+
+		if (!categories && !searchTerm) return;
+
+		setFilters({
+			...filters,
+			search: searchTerm,
+			categories: categories,
+		});
+	}, []);
+
 	return (
 		<div className="md:flex">
 			<div className="mr-8 w-full md:w-1/4">
@@ -79,19 +94,18 @@ const FieldCatalog = ({ fields }: { fields: Fields }) => {
 								type="checkbox"
 								className="mr-2"
 								value={category}
-								onClick={(e) => {
-									const target = e.target as HTMLInputElement;
-
-									if (target.checked) {
+								checked={filters.categories.includes(category)}
+								onChange={(e: ChangeEvent<HTMLInputElement>) => {
+									if (e.target.checked) {
 										setFilters({
 											...filters,
-											categories: [...filters.categories, target.value],
+											categories: [...filters.categories, e.target.value],
 										});
 									} else {
 										setFilters({
 											...filters,
 											categories: filters.categories.filter(
-												(f) => f !== target.value,
+												(f) => f !== e.target.value,
 											),
 										});
 									}
@@ -122,7 +136,7 @@ const FieldCatalog = ({ fields }: { fields: Fields }) => {
 						>
 							<div className="-mb-1 flex items-center">
 								<span
-									className="font-semibold text-lg text-ellipsis overflow-hidden whitespace-nowrap"
+									className="overflow-hidden text-ellipsis whitespace-nowrap text-lg font-semibold"
 									title={`${field.name}: ${field.data_type}`}
 								>
 									{field.name}

src/content/docs/learning-paths/mtls/mtls-app-security/index.mdx

@@ -63,7 +63,7 @@ Use the values from the previous step.
 
 mTLS is verified and checked in the [Cloudflare WAF phase](/waf/reference/phases/). This is done by creating WAF [Custom Rules](/waf/custom-rules/) using the dynamic fields.
 
-All Client Certificate details can be found in the [`cf.tls_*`](/ruleset-engine/rules-language/fields/reference/) fields in the [Cloudflare Ruleset Engine](/ruleset-engine/).
+All Client Certificate details can be found in the [`cf.tls_*`](/ruleset-engine/rules-language/fields/reference/?field-category=mTLS&field-category=SSL/TLS) fields in the [Cloudflare Ruleset Engine](/ruleset-engine/).
 
 Example WAF Custom Rule with action block:
 

src/content/docs/learning-paths/mtls/mtls-app-security/related-features.mdx

@@ -13,7 +13,7 @@ To make it easier to differentiate between Client Certificates, you can generate
 
 In cases of noticing excessive traffic, anomalous traffic (strange sequences of requests), or generally too many attack attempts registered from specific devices using your Client Certificates, it is best to [revoke](/ssl/client-certificates/revoke-client-certificate/) those.
 
-Additionally, ensure to have a WAF [Custom Rule](/waf/custom-rules/) in place to block [revoked](/api-shield/security/mtls/configure/#check-for-revoked-certificates) Client Certificates. Review the available [`cf.tls_*`](/ruleset-engine/rules-language/fields/reference/) fields.
+Additionally, ensure to have a WAF [Custom Rule](/waf/custom-rules/) in place to block [revoked](/api-shield/security/mtls/configure/#check-for-revoked-certificates) Client Certificates. Review the available [`cf.tls_*`](/ruleset-engine/rules-language/fields/reference/?field-category=mTLS&field-category=SSL/TLS) fields.
 
 Example WAF Custom Rule with action block:
 
@@ -100,7 +100,7 @@ Contact your account team for more information.
 [Revoked](/api-shield/security/mtls/configure/#check-for-revoked-certificates) Client Certificates are not automatically blocked unless you have an active WAF Custom Rule specifically checking for and blocking them. This check only applies to Client Certificates issued by the Cloudflare-managed CA. Cloudflare currently does not check certificate revocation lists (CRL) for CAs that have been uploaded by the customer ([BYO CA](/ssl/client-certificates/byo-ca/)). One can opt for Workers to manage a custom business logic and block revoked Client Certificates. See the [Workers section](/learning-paths/mtls/mtls-workers/) for more information.
 :::
 
-In order to effectively implement mTLS with Cloudflare, it is strongly recommended to properly configure the [Cloudflare WAF](/waf/). Review the available [`cf.tls_*`](/ruleset-engine/rules-language/fields/reference/) fields.
+In order to effectively implement mTLS with Cloudflare, it is strongly recommended to properly configure the [Cloudflare WAF](/waf/). Review the available [`cf.tls_*`](/ruleset-engine/rules-language/fields/reference/?field-category=mTLS&field-category=SSL/TLS) fields.
 
 Example WAF Custom Rule with action block:
 

src/content/docs/rules/reference/troubleshooting.mdx

@@ -81,4 +81,4 @@ In the current example, you could use the `raw.http.request.uri.path` field in b
 
 This way, the two rules will work as intended. Additionally, this allows you to use the same expression in the two rules, even when the first rule is updating the URI path value.
 
-For a list of raw fields, refer to the [Fields reference](/ruleset-engine/rules-language/fields/reference/).
+For a list of raw fields, refer to the [Fields reference](/ruleset-engine/rules-language/fields/reference/?field-category=Raw+fields).

src/content/docs/ruleset-engine/about/rules.mdx

@@ -3,14 +3,13 @@ title: Rules
 pcx_content_type: concept
 sidebar:
   order: 4
-
 ---
 
-import { Render } from "~/components"
+import { Render } from "~/components";
 
 A **rule** defines a filter and an action to perform on the incoming requests that match the filter. The rule filter **expression** defines the scope of the rule and the rule **action** defines what happens when there is a match for the expression. Rule filter expressions are defined using the [Rules language](/ruleset-engine/rules-language/).
 
-For example, consider the following ruleset with four rules (R1, R2, R3, and R4). For a given incoming request, the expression of the first two rules matches the request properties. Therefore, the action for these rules runs (*Execute* and *Log*, respectively). The action of the first rule executes a managed ruleset, which means that every rule in the managed ruleset is evaluated. The action of the second rule logs an event associated with the current phase. There is no match for the expressions of rules 3 and 4, so their actions do not run. Since no rule blocks the request, it proceeds to the next phase.
+For example, consider the following ruleset with four rules (R1, R2, R3, and R4). For a given incoming request, the expression of the first two rules matches the request properties. Therefore, the action for these rules runs (_Execute_ and _Log_, respectively). The action of the first rule executes a managed ruleset, which means that every rule in the managed ruleset is evaluated. The action of the second rule logs an event associated with the current phase. There is no match for the expressions of rules 3 and 4, so their actions do not run. Since no rule blocks the request, it proceeds to the next phase.
 
 ![Example of a rule execution scenario. Defines a ruleset with four rules, where the first rule executes a managed ruleset.](~/assets/images/ruleset-engine/rulesets-rules-example.png)
 
@@ -28,9 +27,8 @@ When you use `true` as the rule filter expression, this means "apply the rule to
 
 :::note[Notes]
 
-
-* A rule filter expression must evaluate to a boolean value (either `true` or `false`).
-* Rules of specific Cloudflare products, such as [Transform Rules](/rules/transform/), may include other expressions used to specify dynamic values. These expressions do not have to evaluate to a boolean value.
+- A rule filter expression must evaluate to a boolean value (either `true` or `false`).
+- Rules of specific Cloudflare products, such as [Transform Rules](/rules/transform/), may include other expressions used to specify dynamic values. These expressions do not have to evaluate to a boolean value.
   :::
 
 ### Field values during rule evaluation
@@ -39,11 +37,11 @@ While evaluating rules for a given request/response, the values of all request a
 
 For example:
 
-* If a [rewrite URL rule](/rules/transform/url-rewrite/) #1 updates the URI path or the query string of a request, rewrite URL rule #2 will not take these earlier changes into consideration.
-* If an [HTTP request header modification rule](/rules/transform/request-header-modification/) #1 sets the value of a request header, HTTP request header modification rule #2 will not be able to read or evaluate this new value.
-* If a rewrite URL rule updates the URI path or query string of a request, the `http.request.uri`, `http.request.uri.*`, and `http.request.full_uri` fields will have a different value in phases after the `http_request_transform` phase (where rewrite URL rules are executed).
+- If a [rewrite URL rule](/rules/transform/url-rewrite/) #1 updates the URI path or the query string of a request, rewrite URL rule #2 will not take these earlier changes into consideration.
+- If an [HTTP request header modification rule](/rules/transform/request-header-modification/) #1 sets the value of a request header, HTTP request header modification rule #2 will not be able to read or evaluate this new value.
+- If a rewrite URL rule updates the URI path or query string of a request, the `http.request.uri`, `http.request.uri.*`, and `http.request.full_uri` fields will have a different value in phases after the `http_request_transform` phase (where rewrite URL rules are executed).
 
 :::note
 
-If you want to use the original field values in rules evaluated later, you can use raw fields (for example, `raw.http.request.uri.path`) in their expressions. These special fields are immutable during the entire request evaluation workflow. For a list of raw fields, refer to the [Fields reference](/ruleset-engine/rules-language/fields/reference/).
+If you want to use the original field values in rules evaluated later, you can use raw fields (for example, `raw.http.request.uri.path`) in their expressions. These special fields are immutable during the entire request evaluation workflow. For a list of raw fields, refer to the [Fields reference](/ruleset-engine/rules-language/fields/reference/?field-category=Raw+fields).
 :::

src/content/docs/waf/account/rate-limiting-rulesets/create-dashboard.mdx

@@ -43,7 +43,7 @@ To create a new custom rate limiting ruleset:
 
    The available characteristics depend on your Cloudflare plan and product subscriptions.
 
-10. (Optional) To define an expression that specifies the conditions for incrementing the rate counter, enable **Use custom counting expression** and set the expression. By default, the counting expression is the same as the rule expression. The counting expression can include [response fields](/ruleset-engine/rules-language/fields/reference/).
+10. (Optional) To define an expression that specifies the conditions for incrementing the rate counter, enable **Use custom counting expression** and set the expression. By default, the counting expression is the same as the rule expression. The counting expression can include [response fields](/ruleset-engine/rules-language/fields/reference/?field-category=Response).
 
 11. Under **When rate exceeds**, define the maximum number of requests and the time period to consider when determining the rate.
 

src/content/docs/waf/custom-rules/use-cases/require-specific-headers.mdx

@@ -3,7 +3,7 @@ pcx_content_type: configuration
 title: Require specific HTTP headers
 ---
 
-Many organizations qualify traffic based on the presence of specific HTTP request headers. Use the Rules language [HTTP request header fields](/ruleset-engine/rules-language/fields/reference/) to target requests with specific headers.
+Many organizations qualify traffic based on the presence of specific HTTP request headers. Use the Rules language [HTTP request header fields](/ruleset-engine/rules-language/fields/reference/?field-category=Headers&search-term=http.request) to target requests with specific headers.
 
 This example uses the `http.headers.names` field to look for the presence of an `X-CSRF-Token` header. The [`lower()`](/ruleset-engine/rules-language/functions/#lower) transformation function converts the value to lowercase so that the expression is case insensitive.
 

src/content/docs/waf/managed-rules/index.mdx

@@ -52,4 +52,4 @@ At the zone level, you can only deploy each WAF managed ruleset once. At the [ac
 
 Cloudflare analyzes the body of incoming requests up to a certain maximum size that varies according to your Cloudflare plan. For Enterprise customers, the maximum body size is 128 KB, while for other plans the limit is lower. This means that the behavior of specific managed rules that analyze request bodies can vary according to your current Cloudflare plan.
 
-If included in your plan, you can use [request body fields](/ruleset-engine/rules-language/fields/reference/) such as `http.request.body.truncated` or `http.request.headers.truncated` in [custom rules](/waf/custom-rules/) that apply appropriate actions to requests that have not been fully analyzed by Cloudflare due to the maximum body size.
+If included in your plan, you can use [request body fields](/ruleset-engine/rules-language/fields/reference/?field-category=Body) such as `http.request.body.truncated` or `http.request.headers.truncated` in [custom rules](/waf/custom-rules/) that apply appropriate actions to requests that have not been fully analyzed by Cloudflare due to the maximum body size.

src/content/docs/waf/rate-limiting-rules/create-zone-dashboard.mdx

@@ -28,7 +28,7 @@ import { Render } from "~/components";
 
 7. Under **With the same characteristics**, add one or more characteristics that will define the request counters for rate limiting purposes. Each value combination will have its own counter to determine the rate. Refer to [How Cloudflare determines the request rate](/waf/rate-limiting-rules/request-rate/) for more information.
 
-8. (Optional) To define an expression that specifies the conditions for incrementing the rate counter, enable **Use custom counting expression** and set the expression. By default, the counting expression is the same as the rule expression. The counting expression can include [response fields](/ruleset-engine/rules-language/fields/reference/).
+8. (Optional) To define an expression that specifies the conditions for incrementing the rate counter, enable **Use custom counting expression** and set the expression. By default, the counting expression is the same as the rule expression. The counting expression can include [response fields](/ruleset-engine/rules-language/fields/reference/?field-category=Response).
 
 9. Under **When rate exceeds**, define the maximum number of requests and the time period to consider when determining the rate.
 

src/content/docs/waf/rate-limiting-rules/parameters.mdx

@@ -53,7 +53,7 @@ Use one or more of the following characteristics:
 | **JSON string value of** (enter key)                        | `lookup_json_string(http.request.body.raw, "<key>")`                                                                      | [Missing field versus empty value](#missing-field-versus-empty-value) and [`lookup_json_string()` function reference](/ruleset-engine/rules-language/functions/#lookup_json_string)                                                                      |
 | **JSON integer value of** (enter key)                       | `lookup_json_integer(http.request.body.raw, "<key>")`                                                                     | [Missing field versus empty value](#missing-field-versus-empty-value) and [`lookup_json_integer()` function reference](/ruleset-engine/rules-language/functions/#lookup_json_integer)                                                                    |
 | **Form input value of** (enter field name)                  | `http.request.body.form["<input_field_name>"]`                                                                            | [Missing field versus empty value](#missing-field-versus-empty-value)                                                                                                                                                                                    |
-| **JWT claim of** (enter token configuration ID, claim name) | `lookup_json_string( http.request.jwt.claims["<token_configuration_id>"][0], "<claim_name>")`                              | [Requirements for claims in JWT](#requirements-for-using-claims-inside-a-json-web-token-jwt), [missing field versus empty value](#missing-field-versus-empty-value) and [JWT Validation reference](/api-shield/security/jwt-validation/transform-rules/) |
+| **JWT claim of** (enter token configuration ID, claim name) | `lookup_json_string( http.request.jwt.claims["<token_configuration_id>"][0], "<claim_name>")`                             | [Requirements for claims in JWT](#requirements-for-using-claims-inside-a-json-web-token-jwt), [missing field versus empty value](#missing-field-versus-empty-value) and [JWT Validation reference](/api-shield/security/jwt-validation/transform-rules/) |
 | **Body**                                                    | `http.request.body.raw`                                                                                                   |
 | **Body size** (select operator, enter size)                 | `http.request.body.size`                                                                                                  |
 | **Custom** (enter expression)                               | Enter a custom expression. You can use a function such as `substring()` or `lower()`, or enter a more complex expression. | [Functions](/ruleset-engine/rules-language/functions/)                                                                                                                                                                                                   |
@@ -73,7 +73,7 @@ Only available in the Cloudflare dashboard when you enable **Use custom counting
 
 Defines the criteria used for determining the request rate. By default, the counting expression is the same as the rule matching expression (defined in **If incoming requests match**). This default is also applied when you set this field to an empty string (`""`).
 
-The counting expression can include [HTTP response fields](/ruleset-engine/rules-language/fields/reference/). When there are response fields in the counting expression, the counting will happen after the response is sent.
+The counting expression can include [HTTP response fields](/ruleset-engine/rules-language/fields/reference/?field-category=Response). When there are response fields in the counting expression, the counting will happen after the response is sent.
 
 In some cases, you cannot include HTTP response fields in the counting expression due to configuration restrictions. Refer to [Configuration restrictions](#configuration-restrictions) for details.
 
@@ -231,4 +231,4 @@ To use claims inside a JSON Web Token (JWT), you must first set up a [token vali
 
 - If the rule expression [includes IP lists](/waf/tools/lists/use-in-expressions/), you must enable the **Also apply rate limiting to cached assets** parameter.
 
-- The rule counting expression, defined in the **Increment counter when** parameter, cannot include both [HTTP response fields](/ruleset-engine/rules-language/fields/reference/) and [IP lists](/waf/tools/lists/custom-lists/#lists-with-ip-addresses-ip-lists). If you use IP lists, you must enable the **Also apply rate limiting to cached assets** parameter.
+- The rule counting expression, defined in the **Increment counter when** parameter, cannot include both [HTTP response fields](/ruleset-engine/rules-language/fields/reference/?field-category=Response) and [IP lists](/waf/tools/lists/custom-lists/#lists-with-ip-addresses-ip-lists). If you use IP lists, you must enable the **Also apply rate limiting to cached assets** parameter.