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 13ee0cdf42 Add some more hrw4u help (#12286)
13ee0cdf42 is described below
commit 13ee0cdf42b18fade334064811018c9a5dcf314f
Author: mlibbey <[email protected]>
AuthorDate: Tue Jul 8 13:14:07 2025 -0700
Add some more hrw4u help (#12286)
Added a missing python requirement, and a few more steps to get hrw4u to
build for the first time.
Also included a few more doc hints on usage.
Co-authored-by: Miles Libbey <[email protected]>
---
doc/admin-guide/configuration/hrw4u.en.rst | 24 ++++++++++++++++++++----
tools/hrw4u/.gitignore | 2 ++
tools/hrw4u/bootstrap.sh | 14 ++++++++++++--
tools/hrw4u/requirements.txt | 1 +
4 files changed, 35 insertions(+), 6 deletions(-)
diff --git a/doc/admin-guide/configuration/hrw4u.en.rst
b/doc/admin-guide/configuration/hrw4u.en.rst
index 1ed4001853..5052a71c36 100644
--- a/doc/admin-guide/configuration/hrw4u.en.rst
+++ b/doc/admin-guide/configuration/hrw4u.en.rst
@@ -67,7 +67,7 @@ virtualenv or system-wide using:
.. code-block:: none
- pip install dist/hrw4u-1.0.0-py3-none-any.whl
+ pipx install dist/hrw4u-1.0.0-py3-none-any.whl
Using
-----
@@ -91,7 +91,8 @@ Syntax Differences
The basic structure is a `section` name defining the part of the transaction
to run in
followed by conditionals and operators. It uses `if () {} else {}` conditional
syntax
with `&& , || and ==`, with conditions and operators generally following
function() or
-object.style grammar. For instance:
+object.style grammar. Operator lines are terminated with `;` (whitespace is
still not
+significant). For instance:
.. code-block:: none
@@ -167,6 +168,7 @@ cond %{SSN-TXN-COUNT} >10 ssn-txn-count() > 10
Number of tra
cond %{TO-URL:<C>} =bar to.url.<C> == "bar" Remap ``To
URL`` component match, ``C`` 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.
=============================== ==================================
================================================
The conditions operating on headers and URLs are also available as operators.
E.g.:
@@ -180,10 +182,14 @@ The conditions operating on headers and URLs are also
available as operators. E.
In general, where it makes sense for the condition to be used as an operator,
it is available as an operator.
The rule of thumb is the conditional is an operator if the value is mutable.
+.. note::
+ Each parenthesis group in a conditional will produce a GROUP. Thus, the
original header_rewrite
+ config will be more readable with ``if ...`` than `if (...)`.
+
Operators
---------
-Operators in ``header_rewrite`` mapt to HRW4U as a mix of assignments and
function calls.
+Operators in ``header_rewrite`` map to HRW4U as a mix of assignments and
function calls.
The preference is the assignment style when appropriate.
============================= =================================
================================================
@@ -220,6 +226,15 @@ set-debug set-debug() Enables ATS
txn debug
skip-remap skip-remap() Skip remap processing (open
proxy)
================= ============================ ================================
+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.
+
+
Semantics
=========
@@ -246,7 +261,8 @@ A special section `VARS` is used to declare variables.
There is no equivalent in
`header_rewrite`, where you managed the variables manually.
.. note::
- The section name is always required in HRW4U, there are no implicit or
default hooks.
+ The section name is always required in HRW4U, there are no implicit or
default hooks. There
+ can be several if/else block per section block.
Groups
------
diff --git a/tools/hrw4u/.gitignore b/tools/hrw4u/.gitignore
new file mode 100644
index 0000000000..5df9179ad7
--- /dev/null
+++ b/tools/hrw4u/.gitignore
@@ -0,0 +1,2 @@
+build/
+dist/
\ No newline at end of file
diff --git a/tools/hrw4u/bootstrap.sh b/tools/hrw4u/bootstrap.sh
old mode 100644
new mode 100755
index c3b3de27ab..4852a9ae4d
--- a/tools/hrw4u/bootstrap.sh
+++ b/tools/hrw4u/bootstrap.sh
@@ -20,12 +20,22 @@ set -e
VENV_NAME="hrw4u"
+if ! which antlr; then
+ echo "Make sure antlr is installed, e.g. brew install antlr"
+ echo "Once its in your path, re-run this script."
+ exit
+fi
+
eval "$(pyenv init --path)"
eval "$(pyenv init -)"
# eval "$(pyenv virtualenv-init -)"
-echo "==> Creating virtualenv $VENV_NAME..."
-pyenv virtualenv "$VENV_NAME"
+if pyenv virtualenvs | grep hrw4u; then
+ pyenv uninstall -f "$VENV_NAME"
+else
+ echo "==> Creating virtualenv $VENV_NAME..."
+ pyenv virtualenv "$VENV_NAME"
+fi
echo "==> Activating virtualenv..."
pyenv activate "$VENV_NAME"
diff --git a/tools/hrw4u/requirements.txt b/tools/hrw4u/requirements.txt
index 8d66ac20d2..71967f5809 100644
--- a/tools/hrw4u/requirements.txt
+++ b/tools/hrw4u/requirements.txt
@@ -17,3 +17,4 @@
antlr4-python3-runtime
pytest
pyinstaller
+build
\ No newline at end of file
