hrw4u/header_rewrite: Add session-scope state variables

[zwoop]

Add SESSION-FLAG, SESSION-INT8, and SESSION-INT16 conditions and their corresponding set-session-flag, set-session-int8, and set-session-int16 operators to the header_rewrite plugin. These mirror the existing transaction-scoped state variables but persist across keep-alive requests on the same connection, using a TS_USER_ARGS_SSN slot. The condition and operator classes are parameterized with a TSUserArgType scope argument to avoid code duplication. The hrw4u transpiler adds a SESSION_VARS section for declaring session-scoped variables, and the reverse transpiler handles both scopes. Documentation and tests are included.

Co-Authored-By: Craig Taylor

[Copilot]

Pull request overview

Adds session-scoped state variables to Apache Traffic Server’s header_rewrite plugin and keeps the hrw4u/u4wrh toolchain in sync by introducing SESSION_VARS and scope-aware variable emission/reversal.

Changes:

• header_rewrite: add SESSION-FLAG, SESSION-INT8, SESSION-INT16 conditions and set-session-{flag,int8,int16} operators using TS_USER_ARGS_SSN.
• hrw4u/u4wrh: add SESSION_VARS section support and scope-aware symbol generation/reversal.
• Add documentation and tests (gold test + hrw4u vars fixtures) for session variable persistence.

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tools/hrw4u/tests/data/vars/session_int8.output.txt	Adds expected HRW output for session int8 var usage.
tools/hrw4u/tests/data/vars/session_int8.input.txt	Adds hrw4u input using SESSION_VARS + comparison.
tools/hrw4u/tests/data/vars/session_int8.ast.txt	Adds expected AST for session int8 var parsing.
tools/hrw4u/tests/data/vars/session_int16.output.txt	Adds expected HRW output for session int16 var usage.
tools/hrw4u/tests/data/vars/session_int16.input.txt	Adds hrw4u input using SESSION_VARS + comparison.
tools/hrw4u/tests/data/vars/session_int16.ast.txt	Adds expected AST for session int16 var parsing.
tools/hrw4u/tests/data/vars/session_bool.output.txt	Adds expected HRW output for session bool var usage.
tools/hrw4u/tests/data/vars/session_bool.input.txt	Adds hrw4u input using SESSION_VARS + boolean condition.
tools/hrw4u/tests/data/vars/session_bool.ast.txt	Adds expected AST for session bool var parsing.
tools/hrw4u/tests/data/vars/session_assign.output.txt	Adds expected HRW output for assigning session vars.
tools/hrw4u/tests/data/vars/session_assign.input.txt	Adds hrw4u input mixing VARS + SESSION_VARS assignments.
tools/hrw4u/tests/data/vars/session_assign.ast.txt	Adds expected AST for mixed-scope variable declarations.
tools/hrw4u/src/visitor.py	Tracks current var scope and parses SESSION_VARS sections.
tools/hrw4u/src/types.py	Introduces VarScope and makes symbol emission scope-aware.
tools/hrw4u/src/symbols.py	Allocates variable slots per-scope and stores scope in symbols.
tools/hrw4u/src/hrw_visitor.py	Emits VARS and SESSION_VARS preambles in reverse transpile.
tools/hrw4u/src/hrw_symbols.py	Reverse-maps %{STATE-*}/%{SESSION-*} and set-{state,session}-* to hrw4u vars.
tools/hrw4u/grammar/hrw4u.g4	Adds SESSION_VARS grammar support.
tests/gold_tests/pluginTest/header_rewrite/rules/rule_session_vars.conf	Adds header_rewrite rules testing session flag persistence.
tests/gold_tests/pluginTest/header_rewrite/header_rewrite_bundle.replay.yaml	Adds a replay session validating keep-alive persistence behavior.
plugins/header_rewrite/statement.h	Adds session slot acquisition and scope-aware state access helpers.
plugins/header_rewrite/statement.cc	Adds SSN user-arg index reservation and scope-aware acquisition.
plugins/header_rewrite/operators.h	Parameterizes state operators with TSUserArgType scope.
plugins/header_rewrite/operators.cc	Executes state operators against TXN or SSN slots based on scope.
plugins/header_rewrite/factory.cc	Registers new set-session-* operators and SESSION-* conditions.
plugins/header_rewrite/conditions.h	Parameterizes state conditions with TSUserArgType scope.
plugins/header_rewrite/conditions.cc	Evaluates/prints state conditions against TXN or SSN slots based on scope.
doc/admin-guide/plugins/header_rewrite.en.rst	Documents new SESSION-* conditions and set-session-* operators.
doc/admin-guide/configuration/hrw4u.en.rst	Documents SESSION_VARS and independent slot limits per scope.

---

You can also share your feedback on Copilot code review. Take the survey.

[bneradt]

Codex review:

I have two follow-up concerns after reviewing and validating this PR.

1. SESSION_VARS does not look wired into the LSP declaration scanner yet. tools/hrw4u/src/lsp/strings.py still only enters declaration mode for VARS { ... }, so once users adopt SESSION_VARS, session-scoped variables appear likely to lose normal hover/type metadata in hrw4u-lsp. I have not done a live LSP repro yet, so I am flagging this as a tooling concern rather than a confirmed runtime bug.

2. hrw4u-kg skips SESSION_VARS. In tools/hrw4u/src/kg_visitor.py, visitSection() handles ctx.varSection() but not ctx.sessionVarSection(), so the new declaration block is ignored by knowledge-graph extraction. I reproduced this in the fix_tickets_4 container by running hrw4u-kg on tools/hrw4u/tests/data/vars/session_assign.input.txt: the output contained the VARS block and bool_0, but dropped the SESSION_VARS block and its session variables entirely.

[zwoop]

I've addressed Brian's comments.