This is an automated email from the ASF dual-hosted git repository.
mlibbey pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new 105af5d025 docs: Add more condition/operators (#12339)
105af5d025 is described below
commit 105af5d02513bafa09f3454f11bffa1bd0dac2c5
Author: mlibbey <[email protected]>
AuthorDate: Tue Jul 15 09:20:01 2025 -0700
docs: Add more condition/operators (#12339)
Went through the hrw4u symbols.py conditionals and operators, and tried to
add the missing ones to the hrw4u doc. Also added section names in the
header_rewrite doc so that the "parts" could be quickly referenced.
---
doc/admin-guide/configuration/hrw4u.en.rst | 39 ++++++++++++++-------------
doc/admin-guide/plugins/header_rewrite.en.rst | 12 +++++++++
2 files changed, 33 insertions(+), 18 deletions(-)
diff --git a/doc/admin-guide/configuration/hrw4u.en.rst
b/doc/admin-guide/configuration/hrw4u.en.rst
index 5052a71c36..4c7608707a 100644
--- a/doc/admin-guide/configuration/hrw4u.en.rst
+++ b/doc/admin-guide/configuration/hrw4u.en.rst
@@ -149,11 +149,12 @@ cond %{ACCESS:/path} access("/path")
File exists a
cond %{CACHE} =hit-fresh cache() == "hit-fresh" Cache
lookup result status
cond %{CIDR:24,48} =ip cidr(24,48) == "ip" Match
masked client IP address
cond %{CLIENT-HEADER:X} =foo inbound.req.X == "foo" Original
client request header
-cond %{CLIENT-URL:<C> =bar inbound.url.<C> == "bar" URL
component match, ``C`` is ``host``, ``path`` etc.
+cond %{CLIENT-URL:<C> =bar inbound.url.<C> == "bar" URL
component match, <:ref:`C<admin-plugins-header-rewrite-url-parts>`> is
``host``, ``path`` etc.
+
cond %{COOKIE:foo} =bar {in,out}bound.cookie.foo == "bar" Check a
cookie value
-cond %{FROM-URL:<C>} =bar from.url.<C> == "bar" Remap
``From URL`` component match, ``C`` is ``host`` etc.
-cond %{HEADER:X} =foo {in,out}bound.req.X == "foo" Context
sensitive header conditions
-cond %{ID:UNIQUE} =... id.UNIQUE == "..." Unique
transaction identifier
+cond %{FROM-URL:<C>} =bar from.url.<C> == "bar" Remap
``From URL`` component match,
<:ref:`C<admin-plugins-header-rewrite-url-parts>`> is ``host`` etc.
+cond %{HEADER:X} =fo {in,out}bound.{req,resp}.X == "fo" Context
sensitive header conditions
+cond %{ID:UNIQUE} =... id.UNIQUE == "..."
(:ref:`Unique/request/process<admin-plugins-header-rewrite-id>`) transaction
identifier
cond %{INTERNAL-TRANSACTION} internal() Check if
transaction is internally generated
cond %{IP:CLIENT} ="..." inbound.ip == "..." Client's IP
address. Same as ``inbound.REMOTE_ADDR``
cond %{IP:INBOUND} ="..." inbound.server == "..." ATS's IP
address to which the client connected
@@ -161,14 +162,18 @@ cond %{IP:SERVER} ="..." outbound.ip == "..."
Upstream (nex
cond %{IP:OUTBOUND} ="..." outbound.server == "..." ATS's
outbound IP address, connecting upstream
cond %{LAST-CAPTURE:<#>} ="..." capture.<#> == "..." Last
capture group from regex match (range: `0-9`)
cond %{METHOD} =GET inbound.method == "GET" HTTP method
match
-cond %{NEXT-HOP:<C>} ="bar" outbound.url.<C> == "bar" Next-hop
URL component match, ``C`` is ``host`` etc.
-cond %{NOW:<U>} ="..." now.<U> == "..." Current
date/time in format, ``U`` selects time unit
+cond %{NEXT-HOP:<C>} ="bar" outbound.url.<C> == "bar" Next-hop
URL component match, <:ref:`C<admin-plugins-header-rewrite-url-parts>`> is
``host`` etc.
+cond %{NOW:<U>} ="..." now.<U> == "..." Current
date/time in format, <:ref:`U<admin-plugins-header-rewrite-geo>`> selects time
unit
cond %{RANDOM:500} >250 random(500) > 250 Random
number between 0 and the specified range
cond %{SSN-TXN-COUNT} >10 ssn-txn-count() > 10 Number of
transactions on server connection
-cond %{TO-URL:<C>} =bar to.url.<C> == "bar" Remap ``To
URL`` component match, ``C`` is ``host`` etc.
+cond %{TO-URL:<C>} =bar to.url.<C> == "bar" Remap ``To
URL`` component match, <:ref:`C<admin-plugins-header-rewrite-url-parts>`> is
``host`` etc.
cond %{TXN-COUNT} >10 txn-count() > 10 Number of
transactions on client connection
cond %{URL:<C> =bar {in,out}bound.url.<C> == "bar" Context
aware URL component match
-cond ${GEO:<C>} =bar geo.<C> == "bar" IP to Geo
mapping. ``C`` is ``country``, ``asn`` etc.
+cond %{GEO:<C>} =bar geo.<C> == "bar" IP to Geo
mapping. <:ref:`C<admin-plugins-header-rewrite-geo>`> is country, asn, etc.
+cond %{STATUS} =200 inbound.status ==200 Origin http
status code
+%{TCP-INFO} tcp.info TCP Info
struct field values
+cond %{HTTP-CNTL:<C>} http.cntl.<C> Check the
state of the <:ref:`C<admin-plugins-header-rewrite-set-http-cntl>`> HTTP control
+cond %{INBOUND:<C>} {in,out}bound.conn.<c> inbound
(:ref:`client, user agent<admin-plugins-header-rewrite-inbound>`) connection to
ATS
=============================== ==================================
================================================
The conditions operating on headers and URLs are also available as operators.
E.g.:
@@ -204,16 +209,17 @@ rm-destination QUERY ... remove_query("foo,bar")
Remove specified
rm-destination QUERY ... [I] keep_query("foo,bar") Keep only
specified query keys
run-plugin foo.so "args" run-plugin("foo.so", "arg1", ...) Run an
external remap plugin
set-body "foo" inbound.resp.body = "foo" Set the
response body
-set-body-from "https://..."; set-body-from("https://...";) Set the
response body from a URL
+set-body-from "\https://..."; set-body-from("\https://...";) Set the
response body from a URL
set-config <name> 12 set-config("name", 17) Set a
configuration variable to a value
set-conn-dscp 8 inbound.conn.dscp = 8 Set the DSCP
value for the connection
set-conn-mark 17 inbound.conn.mark = 17 Set the MARK
value for the connection
set-cookie foo bar {in,out}bound.cookie.foo = "bar" Set a
request/response cookie named foo
-set-destination <C> bar inbound.url.<C> = "bar" Set a URL
component, ``C`` is path, query etc.
-set-header X-Bar foo inbound.req.X-Bar = "foo" Assign a
client request header
-set-redirect <Code> <URL> set-redirect(302, "https://...";) Set a redirect
response
+set-destination <C> bar inbound.url.<C> = "bar" Set a URL
component, <:ref:`C<admin-plugins-header-rewrite-url-parts>`> is path, query
etc.
+set-header X-Bar foo inbound.{req,resp}.X-Bar = "foo" Assign a
client request/origin response header
+set-redirect <Code> <URL> set-redirect(302, "\https://...";) Set a
redirect response
set-status 404 http.status = 404 Set the
response status code
set-status-reason "No" http.status.reason = "no" Set the
response status reason
+set-http-cntl http.cntl.<C> = bool Turn on/off
<:ref:`C<admin-plugins-header-rewrite-set-http-cntl>`> controllers
============================= =================================
================================================
In addition to those operators above, HRW4U supports the following special
operators without arguments:
@@ -230,9 +236,9 @@ String concatenations
---------------------
You can concatenate values using strings, condition values and variable
expansions on the same line in
-operators using. For instance, `outbound.req.CustomHeader “Hello from
{inbound.ip}:{inbound.port}”`. As
-a result, the set-redirect's `[QSA]` flag would be implemented as
`set-redirect(302, "https://...?{inbound.url.query}";)``.
-Note the presence of the `?` -- the url.query doesn't include it.
+operators using. For instance, ``outbound.req.CustomHeader = “Hello from
{inbound.ip}:{inbound.port}”``. As
+a result, the set-redirect's ``[QSA]`` flag would be implemented as
``set-redirect(302, "https://...?{inbound.url.query}";)``.
+Note the presence of the ``?`` -- the url.query doesn't include it.
Semantics
@@ -567,9 +573,6 @@ the ``CACHE`` condition results to a header.::
if inbound.resp.All-Cache != "" {
inbound.resp.All-Cache = "{inbound.resp.All-Cache}, {cache()}";
}
- }
-
- SEND_RESPONSE {
if inbound.resp.All-Cache == "" {
inbound.resp.All-Cache = "{cache()}";
}
diff --git a/doc/admin-guide/plugins/header_rewrite.en.rst
b/doc/admin-guide/plugins/header_rewrite.en.rst
index 13be369d79..cfc59f3e0b 100644
--- a/doc/admin-guide/plugins/header_rewrite.en.rst
+++ b/doc/admin-guide/plugins/header_rewrite.en.rst
@@ -318,6 +318,8 @@ Per-Mapping`_ above.
The ``<part>`` allows the operand to match against just a component of the URL,
as documented in `URL Parts`_ below.
+.. _admin-plugins-header-rewrite-geo:
+
GEO
~~~
::
@@ -429,6 +431,8 @@ are of the same name as for `set-http-cntl`_. This
condition returns a ``true``
would only continue evaluation if logging is turned off.
+.. _admin-plugins-header-rewrite-id:
+
ID
~~
::
@@ -449,6 +453,8 @@ arguments to another operator. For example::
set-header ATS-Req-UUID %{ID:UNIQUE}
+.. _admin-plugins-header-rewrite-inbound:
+
INBOUND
~~~~~~~
::
@@ -596,6 +602,8 @@ For example::
cond %{NEXT-HOP:HOST} =www.secondparent.com
set-header Host vhost.secondparent.com
+.. _admin-plugins-header-rewrite-now:
+
NOW
~~~
::
@@ -1116,6 +1124,8 @@ set-cookie
Replaces the value of cookie ``<name>`` with ``<value>``, creating the cookie
if necessary.
+.. _admin-plugins-header-rewrite-set-http-cntl:
+
set-http-cntl
~~~~~~~~~~~~~
::
@@ -1202,6 +1212,8 @@ Old expansion variable Condition variable to use with
concatenations
%<cquup> %{CLIENT-URL:PATH}
========================
==========================================================================
+.. _admin-plugins-header-rewrite-url-parts:
+
URL Parts
---------
