diff --git a/src/content/docs/ruleset-engine/rules-language/fields/http-request-body.mdx b/src/content/docs/ruleset-engine/rules-language/fields/http-request-body.mdx index b9bcc3418a8da0..0d9e10280b7932 100644 --- a/src/content/docs/ruleset-engine/rules-language/fields/http-request-body.mdx +++ b/src/content/docs/ruleset-engine/rules-language/fields/http-request-body.mdx @@ -28,7 +28,7 @@ The Cloudflare Rules language supports these HTTP body fields. `http.request.body.raw` `String` -Represents the unaltered HTTP request body. +The unaltered HTTP request body. When the value of `http.request.body.truncated` is true, the return value may be truncated. @@ -58,7 +58,7 @@ This field may have a value larger than the one returned by `len(http.request.bo `http.request.body.form` `Map>` -Represents the HTTP request body of a form as a Map (or associative array). Populated when the Content-Type header is `application/x-www-form-urlencoded`. +The HTTP request body of a form represented as a Map (or associative array). Populated when the `Content-Type` header is `application/x-www-form-urlencoded`. The values are not pre-processed and retain the original case used in the request. @@ -83,9 +83,9 @@ Example value: `http.request.body.form.names` `Array` -Represents the names of the form fields in an HTTP request where the content type is `application/x-www-form-urlencoded`. +The names of the form fields in an HTTP request where the content type is `application/x-www-form-urlencoded`. -The names are not pre-processed and retain the original case used in the request. They are listed in the same order as in the request. +Names are not pre-processed and retain the original case used in the request. They are listed in the same order as in the request. Duplicate names are listed multiple times. @@ -109,7 +109,7 @@ Example value: `http.request.body.form.values` `Array` -Represents the values of the form fields in an HTTP request where the content type is `application/x-www-form-urlencoded`. +The values of the form fields in an HTTP request where the content type is `application/x-www-form-urlencoded`. The values are not pre-processed and retain the original case used in the request. They are listed in the same order as in the request. @@ -149,7 +149,7 @@ This field is available on all Cloudflare plans. `http.request.body.multipart` `Map>` -A Map (or associative array) of multipart names to multipart values in the request body. +A Map (or associative array) representation of multipart names to multipart values in the request body. Example value: diff --git a/src/content/docs/ruleset-engine/rules-language/fields/http-request-header.mdx b/src/content/docs/ruleset-engine/rules-language/fields/http-request-header.mdx index 67aff5abd29118..640efc8717cff1 100644 --- a/src/content/docs/ruleset-engine/rules-language/fields/http-request-header.mdx +++ b/src/content/docs/ruleset-engine/rules-language/fields/http-request-header.mdx @@ -16,7 +16,7 @@ The Cloudflare Rules language supports these HTTP header fields. `http.request.headers` `Map>` -Represents HTTP request headers as a Map (or associative array). +The HTTP request headers represented as a Map (or associative array). The keys of the associative array are the names of HTTP request headers converted to lowercase. @@ -44,7 +44,7 @@ Example value: `http.request.headers.names` `Array` -Represents the names of the headers in the HTTP request. +The names of the headers in the HTTP request. The names are not pre-processed and retain the original case used in the request. @@ -72,7 +72,7 @@ Example value: `["content-type"]` `http.request.headers.values` `Array` -Represents the values of the headers in the HTTP request. +The values of the headers in the HTTP request. The values are not pre-processed and retain the original case used in the request. @@ -122,7 +122,7 @@ When `true`, `http.request.headers`, `http.request.headers.names`, and `http.req `http.request.accepted_languages` `Array` -Represents the list of language tags provided in the [`Accept-Language`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language) HTTP request header, sorted by weight (`;q=`, with a default weight of `1`) in descending order. +List of language tags provided in the [`Accept-Language`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language) HTTP request header, sorted by weight (`;q=`, with a default weight of `1`) in descending order. If the HTTP header is not present in the request or is empty, `http.request.accepted_languages[0]` will return a "[missing value](/ruleset-engine/rules-language/values/#notes)", which the `concat()` function will handle as an empty string. diff --git a/src/content/docs/ruleset-engine/rules-language/fields/http-request-response.mdx b/src/content/docs/ruleset-engine/rules-language/fields/http-request-response.mdx index 85f3295304f387..89f3255b6c006c 100644 --- a/src/content/docs/ruleset-engine/rules-language/fields/http-request-response.mdx +++ b/src/content/docs/ruleset-engine/rules-language/fields/http-request-response.mdx @@ -16,7 +16,7 @@ The Cloudflare Rules language supports these HTTP response fields. `http.response.code` `Integer` -Represents the HTTP status code returned to the client, either set by a Cloudflare product or returned by the origin server. +The HTTP status code returned to the client, either set by a Cloudflare product or returned by the origin server. Example value: `403` @@ -25,7 +25,7 @@ Example value: `http.response.headers` `Map>` -Represents HTTP response headers as a Map (or associative array). +The HTTP response headers represented as a Map (or associative array). When there are repeating headers, the array includes them in the order they appear in the response. The keys convert to lowercase. @@ -47,7 +47,7 @@ Example value: ## `http.response.headers.names` -Represents the names of the headers in the HTTP response. The names are not pre-processed and retain the original case used in the response. +The names of the headers in the HTTP response. The names are not pre-processed and retain the original case used in the response. The order of header names is not guaranteed but will match `http.response.headers.values`. @@ -67,7 +67,7 @@ Example value: `["content-type"]` ## `http.response.headers.values` -Represents the values of the headers in the HTTP response. +The values of the headers in the HTTP response. The values are not pre-processed and retain the original case used in the response. @@ -155,7 +155,7 @@ Note: This field is only available in [HTTP response header modifications](/rule `cf.response.error_type` `String` -Contains a string with the type of error in the response being returned. The default value is an empty string (`""`). +A string with the type of error in the response being returned. The default value is an empty string (`""`). The available values are the following: diff --git a/src/content/docs/ruleset-engine/rules-language/fields/standard-fields.mdx b/src/content/docs/ruleset-engine/rules-language/fields/standard-fields.mdx index 2a0cb2ab5ca044..2b935f8a102f55 100644 --- a/src/content/docs/ruleset-engine/rules-language/fields/standard-fields.mdx +++ b/src/content/docs/ruleset-engine/rules-language/fields/standard-fields.mdx @@ -8,7 +8,7 @@ head: content: Standard fields | Fields reference --- -import { Details } from "~/components"; +import { Details, Render } from "~/components"; Most standard fields use the same naming conventions as [Wireshark display fields](https://www.wireshark.org/docs/wsug_html_chunked/ChWorkBuildDisplayFilterSection.html). However, there are some subtle differences between Cloudflare and Wireshark: @@ -34,7 +34,7 @@ The Cloudflare Rules language supports these standard fields. `http.cookie` `String` -Represents the entire cookie as a string. +The entire cookie as a string. Example value: @@ -46,7 +46,7 @@ session=8521F670545D7865F79C3D7BEDC29CCE;-background=light `http.host` `String` -Represents the hostname used in the full request URI. +The hostname used in the full request URI. Example value: @@ -58,7 +58,7 @@ www.example.org `http.referer` `String` -Represents the HTTP Referer request header, which contains the address of the web page that linked to the currently requested page. +The HTTP `Referer` request header, which contains the address of the web page that linked to the currently requested page. Example value: @@ -70,7 +70,7 @@ Referer: htt­ps://developer.example.org/en-US/docs/Web/JavaScript `http.request.full_uri` `String` -Represents the full URI as received by the web server (does not include `#fragment`, which is not sent to web servers). +The full URI as received by the web server (does not include `#fragment`, which is not sent to web servers). Example value: @@ -82,7 +82,7 @@ htt­ps://www.example.org/articles/index?section=539061&expand=comments `http.request.method` `String` -Represents the HTTP method, returned as a string of uppercase characters. +The HTTP method, returned as a string of uppercase characters. Example value: @@ -94,7 +94,7 @@ GET `http.request.cookies` `Map>` -Represents the `Cookie` HTTP header associated with a request as a Map (associative array). The cookie values are not pre-processed and retain the original case used in the request. +The `Cookie` HTTP header associated with a request represented as a Map (associative array). The cookie values are not pre-processed and retain the original case used in the request. **Decoding:** The cookie names are URL decoded. If two cookies have the same name after decoding, their value arrays are merged. @@ -114,7 +114,7 @@ Example value: `http.request.timestamp.sec` `Integer` -Represents the timestamp when Cloudflare received the request, expressed as Unix time in seconds. This value is 10 digits long. +The timestamp when Cloudflare received the request, expressed as UNIX time in seconds. This value is 10 digits long. To obtain the timestamp milliseconds, use the `http.request.timestamp.msec` field. @@ -130,7 +130,7 @@ When validating HMAC tokens in an expression, pass this field as the `currentTim `http.request.timestamp.msec` `Integer` -Represents the millisecond when Cloudflare received the request, between 0 and 999. +The millisecond when Cloudflare received the request, between 0 and 999. To obtain the complete timestamp, use both `http.request.timestamp.sec` and `http.request.timestamp.msec` fields. @@ -146,7 +146,7 @@ Here is the formatted information for the provided rows: `http.request.uri` `String` -Represents the URI path and query string of the request. +The URI path and query string of the request. Example value: @@ -158,7 +158,7 @@ Example value: `http.request.uri.path` `String` -Represents the URI path of the request. +The URI path of the request. Example value: @@ -197,7 +197,7 @@ Example values: `http.request.uri.query` `String` -Represents the entire query string, without the `?` delimiter. +The entire query string, without the `?` delimiter. Example value: @@ -209,7 +209,7 @@ section=539061&expand=comments `http.user_agent` `String` -Represents the HTTP User-Agent request header, which contains a characteristic string to identify the client operating system and web browser. +The HTTP `User-Agent` request header, which contains a characteristic string to identify the client operating system and web browser. Example value: @@ -221,7 +221,7 @@ Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65 `http.request.version` `String` -Represents the version of the HTTP protocol used. Use this field when different checks are needed for different versions. +The version of the HTTP protocol used. Use this field when different checks are needed for different versions. Example values: @@ -232,7 +232,7 @@ Example values: `http.x_forwarded_for` `String` -Represents the full `X-Forwarded-For` HTTP header. +The full `X-Forwarded-For` HTTP header. Example value: @@ -244,7 +244,7 @@ Example value: `ip.src` `IP address` -Represents the client TCP IP address, which may be adjusted to reflect the actual address of the client using HTTP headers such as `X-Forwarded-For` or `X-Real-IP`. +The client TCP IP address, which may be adjusted to reflect the actual address of the client using HTTP headers such as `X-Forwarded-For` or `X-Real-IP`. Example value: @@ -256,7 +256,7 @@ Example value: `ip.src.lat` `String` -Represents the latitude associated with the client IP address. +The latitude associated with the client IP address. Example value: @@ -268,7 +268,7 @@ Example value: `ip.src.lon` `String` -Represents the longitude associated with the client IP address. +The longitude associated with the client IP address. Example value: @@ -280,7 +280,7 @@ Example value: `ip.src.city` `String` -Represents the city associated with the client IP address. +The city associated with the client IP address. Example value: @@ -292,7 +292,7 @@ San Francisco `ip.src.postal_code` `String` -Represents the postal code associated with the incoming request. +The postal code associated with the incoming request. Example value: @@ -304,7 +304,7 @@ Example value: `ip.src.metro_code` `String` -Represents the metro code or Designated Market Area (DMA) code associated with the incoming request. +The metro code or Designated Market Area (DMA) code associated with the incoming request. Example value: @@ -316,7 +316,7 @@ Example value: `ip.src.region` `String` -Represents the region name associated with the incoming request. +The region name associated with the incoming request. Example value: @@ -328,7 +328,7 @@ Texas `ip.src.region_code` `String` -Represents the region code associated with the incoming request. +The region code associated with the incoming request. Example value: @@ -340,7 +340,7 @@ TX `ip.src.timezone.name` `String` -Represents the name of the timezone associated with the incoming request. This field is only available in rewrite expressions of [Transform Rules](/rules/transform/). +The name of the timezone associated with the incoming request. This field is only available in rewrite expressions of [Transform Rules](/rules/transform/). Example value: @@ -352,7 +352,7 @@ America/Chicago `ip.src.asnum` `Number` -Represents the 16- or 32-bit integer representing the Autonomous System (AS) number associated with the client IP address. +The 16-bit or 32-bit integer representing the Autonomous System (AS) number associated with the client IP address. This field has the same value as the `ip.geoip.asnum` field, which is deprecated. The `ip.geoip.asnum` field is still available for new and existing rules, but you should use the `ip.src.asnum` field instead. @@ -360,7 +360,7 @@ This field has the same value as the `ip.geoip.asnum` field, which is deprecated `ip.src.continent` `String` -Represents the continent code associated with the client IP address: +The continent code associated with the client IP address: - **AF**: Africa - **AN**: Antarctica @@ -377,7 +377,7 @@ This field has the same value as the `ip.geoip.continent` field, which is deprec `ip.src.country` `String` -Represents the 2-letter country code in [ISO 3166-1 Alpha 2](https://www.iso.org/obp/ui/#search/code/) format. +The 2-letter country code in [ISO 3166-1 Alpha 2](https://www.iso.org/obp/ui/#search/code/) format. Example value: @@ -393,7 +393,7 @@ This field has the same value as the `ip.geoip.country` field, which is deprecat `ip.src.subdivision_1_iso_code` `String` -Represents the ISO 3166-2 code for the first-level region associated with the IP address. When the actual value is not available, this field contains an empty string. +The ISO 3166-2 code for the first-level region associated with the IP address. When the actual value is not available, this field contains an empty string. Example value: @@ -409,7 +409,7 @@ This field has the same value as the `ip.geoip.subdivision_1_iso_code` field, wh `ip.src.subdivision_2_iso_code` `String` -Represents the ISO 3166-2 code for the second-level region associated with the IP address. When the actual value is not available, this field contains an empty string. +The ISO 3166-2 code for the second-level region associated with the IP address. When the actual value is not available, this field contains an empty string. Example value: @@ -476,7 +476,12 @@ This field has the same value as the `ip.geoip.is_in_european_union` field, whic `raw.http.request.full_uri` `String` -Similar to the [`http.request.full_uri`](#httprequestfull_uri) non-raw field. Represents the full URI as received by the web server without the URI fragment (if any) and without any transformation. +The raw full URI as received by the web server without the URI fragment (if any) and without any transformation. + + **Note:** This raw field may include some basic normalization done by Cloudflare's HTTP server. However, this can change in the future. @@ -484,7 +489,12 @@ Similar to the [`http.request.full_uri`](#httprequestfull_uri) non-raw field. Re `raw.http.request.uri` `String` -Similar to the [`http.request.uri`](#httprequesturi) non-raw field. Represents the URI path and query string of the request without any transformation. +The raw URI path and query string of the request without any transformation. + + **Note:** This raw field may include some basic normalization done by Cloudflare's HTTP server. However, this can change in the future. @@ -492,7 +502,12 @@ Similar to the [`http.request.uri`](#httprequesturi) non-raw field. Represents t `raw.http.request.uri.path` `String` -Similar to the [`http.request.uri.path`](#httprequesturipath) non-raw field. Represents the URI path of the request without any transformation. +The raw URI path of the request without any transformation. + + **Note:** This raw field may include some basic normalization done by Cloudflare's HTTP server. However, this can change in the future. @@ -500,13 +515,26 @@ Similar to the [`http.request.uri.path`](#httprequesturipath) non-raw field. Rep `raw.http.request.uri.path.extension` `String` -Similar to the [`http.request.uri.path.extension`](#httprequesturipathextension) non-raw field. Represents the file extension in the request URI path without any transformation. +The raw file extension in the request URI path without any transformation. + + ## `raw.http.request.uri.query` `raw.http.request.uri.query` `String` -Similar to the [`http.request.uri.query`](#httprequesturiquery) non-raw field. Represents the entire query string without the `?` delimiter and without any transformation. +The entire query string without the `?` delimiter and without any transformation. + + **Note:** This raw field may include some basic normalization done by Cloudflare's HTTP server. However, this can change in the future. diff --git a/src/content/docs/ruleset-engine/rules-language/fields/uri.mdx b/src/content/docs/ruleset-engine/rules-language/fields/uri.mdx index 2bf89a132816bd..beff5428b9af85 100644 --- a/src/content/docs/ruleset-engine/rules-language/fields/uri.mdx +++ b/src/content/docs/ruleset-engine/rules-language/fields/uri.mdx @@ -8,6 +8,8 @@ head: content: URI argument and value fields | Fields reference --- +import { Render } from "~/components"; + The Cloudflare Rules language includes URI argument and value fields associated with HTTP requests. Many of these fields return [arrays](/ruleset-engine/rules-language/values/#arrays) containing the respective values. The Cloudflare Rules language supports these URI argument and value fields. @@ -16,7 +18,7 @@ The Cloudflare Rules language supports these URI argument and value fields. `http.request.uri.args` `Map>` -Represents the HTTP URI arguments associated with a request as a Map (associative array). +The HTTP URI arguments associated with a request represented as a Map (associative array). When an argument repeats, the array contains multiple items in the order they appear in the request. @@ -37,7 +39,7 @@ Example value: `http.request.uri.args.names` `Array` -Represents the names of the arguments in the HTTP URI query string. The names are not pre-processed and retain the original case used in the request. +The names of the arguments in the HTTP URI query string. The names are not pre-processed and retain the original case used in the request. When a name repeats, the array contains multiple items in the order that they appear in the request. @@ -56,7 +58,7 @@ Example value: `http.request.uri.args.values` `Array` -Represents the values of arguments in the HTTP URI query string. The values are not pre-processed and retain the original case used in the request. They are in the same order as in the request. +The values of arguments in the HTTP URI query string. The values are not pre-processed and retain the original case used in the request. They are in the same order as in the request. Duplicated values are listed multiple times. @@ -75,16 +77,35 @@ Example value: `raw.http.request.uri.args` `Map>` -Contains the same field values as [`http.request.uri.args`](#httprequesturiargs). +The raw HTTP URI arguments associated with a request represented as a Map (associative array). + + ## `raw.http.request.uri.args.names` `raw.http.request.uri.args.names` `Array` -Contains the same field values as [`http.request.uri.args.names`](#httprequesturiargsnames). +The raw names of the arguments in the HTTP URI query string. + + ## `raw.http.request.uri.args.values` `raw.http.request.uri.args.values` `Array` -Contains the same field values as [`http.request.uri.args.values`](#httprequesturiargsvalues). +The raw values of arguments in the HTTP URI query string. + + diff --git a/src/content/partials/ruleset-engine/raw-fields-definition-with-link.mdx b/src/content/partials/ruleset-engine/raw-fields-definition-with-link.mdx new file mode 100644 index 00000000000000..2d876447ed9048 --- /dev/null +++ b/src/content/partials/ruleset-engine/raw-fields-definition-with-link.mdx @@ -0,0 +1,8 @@ +--- +params: + - fieldLink +--- + +import { Markdown } from "~/components"; + +This is the raw field version of the field. Raw fields, prefixed with `raw.`, preserve original request values for later evaluations. These fields are immutable during the entire request evaluation workflow, and they are not affected by the actions of previously matched rules.