hrw4u/header_rewrite: Add session-scope state variables (#12989)

* hrw4u/header_rewrite: Add session-scope state variables

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

* Address Copilot review comments

Use SESSION_VARS instead of VARS for session sandbox check.
Reserve user-arg slots lazily per scope in acquire_state_slot().
Fix _state_vars type annotation to include VarScope in key tuple.

* Address bneradt's review: wire SESSION_VARS into kg and LSP

kg_visitor.py was missing sessionVarSection dispatch in visitSection,
causing hrw4u-kg to silently drop SESSION_VARS blocks. lsp/strings.py
only detected VARS { ... } for declaration mode, leaving session-scoped
variables without hover/type metadata in hrw4u-lsp.

Author: zwoop

doc/admin-guide/configuration/hrw4u.en.rst

@@ -405,7 +405,9 @@ TXN_CLOSE_HOOK                  TXN_CLOSE                End of transaction
 =============================== ======================== ================================
 
 A special section `VARS` is used to declare variables. There is no equivalent in
-`header_rewrite`, where you managed the variables manually.
+`header_rewrite`, where you managed the variables manually. Similarly,
+`SESSION_VARS` declares session-scoped variables that persist across all
+transactions on the same client connection (session).
 
 Variables and State Slots
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -416,6 +418,10 @@ Each variable type has a limited number of slots available:
 - ``int8`` - 4 slots (0-3)
 - ``int16`` - 1 slot (0)
 
+These limits apply independently to both ``VARS`` (transaction-scoped) and
+``SESSION_VARS`` (session-scoped) sections. For example, you can have 16 bool
+transaction variables *and* 16 bool session variables.
+
 By default, slots are assigned automatically in declaration order. You can explicitly assign
 a slot number using the ``@`` syntax::
 
@@ -426,6 +432,16 @@ a slot number using the ``@`` syntax::
         counter: int8 @2;       # Explicitly use int8 slot 2
     }
 
+    SESSION_VARS {
+        is_suspicious: bool;    # Session-scoped, persists across requests
+        penalty_level: int8;    # Session-scoped 8-bit integer
+    }
+
+Transaction variables (``VARS``) are reset for each new HTTP transaction, while
+session variables (``SESSION_VARS``) persist for the lifetime of the client
+connection. Session variables are useful for tracking state across keep-alive
+requests, such as marking a connection as suspicious after the first bad request.
+
 Explicit slot assignment is useful when you need predictable slot numbers across configurations
 or when integrating with existing header_rewrite rules that reference specific slot numbers. In
 addition, a remap configuration can use ``@PPARAM`` to set one of these slot variables explicitly

doc/admin-guide/plugins/header_rewrite.en.rst

@@ -862,6 +862,41 @@ There's only one such integer, and its value is returned from this condition.
 As such, the index, ``0``, is optional here. The initialized value of this
 state variable is ``0``.
 
+SESSION-FLAG
+~~~~~~~~~~~~
+::
+
+      cond %{SESSION-FLAG:<n>}
+
+This condition allows you to check the state of a session-scoped flag. The
+``<n>`` is the number of the flag, from 0 to 15. Unlike ``STATE-FLAG`` which
+is scoped to the current transaction, session flags persist across all
+transactions on the same client connection (session). The default value of all
+flags are ``false``.
+
+SESSION-INT8
+~~~~~~~~~~~~
+::
+
+      cond %{SESSION-INT8:<n>}
+
+This condition allows you to check the state of a session-scoped 8-bit unsigned
+integer. The ``<n>`` is the number of the integer, from 0 to 3. The current
+value is returned, and all 4 integers are initialized to 0. Session integers
+persist across all transactions on the same client connection.
+
+SESSION-INT16
+~~~~~~~~~~~~~
+::
+
+      cond %{SESSION-INT16:<0>}
+
+This condition allows you to check the state of a session-scoped 16-bit unsigned
+integer. There's only one such integer, and its value is returned from this
+condition. As such, the index, ``0``, is optional here. The initialized value
+is ``0``. Session integers persist across all transactions on the same client
+connection.
+
 STATUS
 ~~~~~~
 ::
@@ -1304,6 +1339,42 @@ The ``<value>`` is an unsigned 16-bit integer as well, 0-65535. It can also
 be a condition, in which case thevalue of the condition is used. The index,
 0, is always required eventhough there is only one 16-bit integer state variable.
 
+set-session-flag
+~~~~~~~~~~~~~~~~
+::
+
+  set-session-flag <n> <value>
+
+This operator allows you to set the state of a session-scoped flag. The ``<n>``
+is the number of the flag, from 0 to 15. The ``<value>`` is either ``true`` or
+``false``, turning the flag on or off. Unlike ``set-state-flag``, session flags
+persist across all transactions on the same client connection.
+
+set-session-int8
+~~~~~~~~~~~~~~~~
+::
+
+   set-session-int8 <n> <value>
+
+This operator allows you to set the state of a session-scoped 8-bit unsigned
+integer. The ``<n>`` is the number of the integer, from 0 to 3. The ``<value>``
+is an unsigned 8-bit integer, 0-255. It can also be a condition, in which case
+the value of the condition is used. Session integers persist across all
+transactions on the same client connection.
+
+set-session-int16
+~~~~~~~~~~~~~~~~~
+::
+
+   set-session-int16 0 <value>
+
+This operator allows you to set the state of a session-scoped 16-bit unsigned
+integer. The ``<value>`` is an unsigned 16-bit integer, 0-65535. It can also
+be a condition, in which case the value of the condition is used. The index,
+0, is always required even though there is only one 16-bit session integer
+state variable. Session integers persist across all transactions on the same
+client connection.
+
 set-status
 ~~~~~~~~~~
 ::

plugins/header_rewrite/conditions.cc

@@ -1654,9 +1654,9 @@ ConditionStateFlag::set_qualifier(const std::string &q)
 
   _flag_ix = strtol(q.c_str(), nullptr, 10);
   if (_flag_ix < 0 || _flag_ix >= NUM_STATE_FLAGS) {
-    TSError("[%s] STATE-FLAG index out of range: %s", PLUGIN_NAME, q.c_str());
+    TSError("[%s] %s-FLAG index out of range: %s", PLUGIN_NAME, _scope_label(_scope), q.c_str());
   } else {
-    Dbg(pi_dbg_ctl, "\tParsing %%{STATE-FLAG:%s}", q.c_str());
+    Dbg(pi_dbg_ctl, "\tParsing %%{%s-FLAG:%s}", _scope_label(_scope), q.c_str());
     _mask = 1ULL << _flag_ix;
   }
 }
@@ -1665,15 +1665,15 @@ void
 ConditionStateFlag::append_value(std::string &s, const Resources &res)
 {
   s += eval(res) ? "TRUE" : "FALSE";
-  Dbg(pi_dbg_ctl, "Evaluating STATE-FLAG(%d)", _flag_ix);
+  Dbg(pi_dbg_ctl, "Evaluating %s-FLAG(%d)", _scope_label(_scope), _flag_ix);
 }
 
 bool
 ConditionStateFlag::eval(const Resources &res)
 {
-  auto data = reinterpret_cast<uint64_t>(TSUserArgGet(res.state.txnp, _txn_slot));
+  auto data = _get_state_data(_scope, res);
 
-  Dbg(pi_dbg_ctl, "Evaluating STATE-FLAG()");
+  Dbg(pi_dbg_ctl, "Evaluating %s-FLAG()", _scope_label(_scope));
 
   return (data & _mask) == _mask;
 }
@@ -1696,9 +1696,9 @@ ConditionStateInt8::set_qualifier(const std::string &q)
 
   _byte_ix = strtol(q.c_str(), nullptr, 10);
   if (_byte_ix < 0 || _byte_ix >= NUM_STATE_INT8S) {
-    TSError("[%s] STATE-INT8 index out of range: %s", PLUGIN_NAME, q.c_str());
+    TSError("[%s] %s-INT8 index out of range: %s", PLUGIN_NAME, _scope_label(_scope), q.c_str());
   } else {
-    Dbg(pi_dbg_ctl, "\tParsing %%{STATE-INT8:%s}", q.c_str());
+    Dbg(pi_dbg_ctl, "\tParsing %%{%s-INT8:%s}", _scope_label(_scope), q.c_str());
   }
 }
 
@@ -1709,15 +1709,15 @@ ConditionStateInt8::append_value(std::string &s, const Resources &res)
 
   s += std::to_string(data);
 
-  Dbg(pi_dbg_ctl, "Appending STATE-INT8(%d) to evaluation value -> %s", data, s.c_str());
+  Dbg(pi_dbg_ctl, "Appending %s-INT8(%d) to evaluation value -> %s", _scope_label(_scope), data, s.c_str());
 }
 
 bool
 ConditionStateInt8::eval(const Resources &res)
 {
   uint8_t data = _get_data(res);
 
-  Dbg(pi_dbg_ctl, "Evaluating STATE-INT8()");
+  Dbg(pi_dbg_ctl, "Evaluating %s-INT8()", _scope_label(_scope));
 
   return static_cast<const MatcherType *>(_matcher.get())->test(data, res);
 }
@@ -1742,9 +1742,9 @@ ConditionStateInt16::set_qualifier(const std::string &q)
     long ix = strtol(q.c_str(), nullptr, 10);
 
     if (ix != 0) {
-      TSError("[%s] STATE-INT16 index out of range: %s", PLUGIN_NAME, q.c_str());
+      TSError("[%s] %s-INT16 index out of range: %s", PLUGIN_NAME, _scope_label(_scope), q.c_str());
     } else {
-      Dbg(pi_dbg_ctl, "\tParsing %%{STATE-INT16:%s}", q.c_str());
+      Dbg(pi_dbg_ctl, "\tParsing %%{%s-INT16:%s}", _scope_label(_scope), q.c_str());
     }
   }
 }
@@ -1755,15 +1755,15 @@ ConditionStateInt16::append_value(std::string &s, const Resources &res)
   uint16_t data = _get_data(res);
 
   s += std::to_string(data);
-  Dbg(pi_dbg_ctl, "Appending STATE-INT16(%d) to evaluation value -> %s", data, s.c_str());
+  Dbg(pi_dbg_ctl, "Appending %s-INT16(%d) to evaluation value -> %s", _scope_label(_scope), data, s.c_str());
 }
 
 bool
 ConditionStateInt16::eval(const Resources &res)
 {
   uint16_t data = _get_data(res);
 
-  Dbg(pi_dbg_ctl, "Evaluating STATE-INT8()");
+  Dbg(pi_dbg_ctl, "Evaluating %s-INT16()", _scope_label(_scope));
 
   return static_cast<const MatcherType *>(_matcher.get())->test(data, res);
 }

plugins/header_rewrite/conditions.h

@@ -800,17 +800,17 @@ class ConditionGroup : public Condition
   bool       _end  = false;
 };
 
-// State Flags
+// State/Session Flags (parameterized by scope)
 class ConditionStateFlag : public Condition
 {
   using SelfType = ConditionStateFlag;
   // No matcher for this, it's all easy peasy
 
 public:
-  explicit ConditionStateFlag()
+  explicit ConditionStateFlag(TSUserArgType scope = TS_USER_ARGS_TXN) : _scope(scope)
   {
     static_assert(sizeof(void *) == 8, "State Variables requires a 64-bit system.");
-    Dbg(dbg_ctl, "Calling CTOR for ConditionStateFlag");
+    Dbg(dbg_ctl, "Calling CTOR for ConditionStateFlag (scope=%s)", _scope_label(_scope));
   }
 
   // noncopyable
@@ -826,26 +826,33 @@ class ConditionStateFlag : public Condition
   bool
   need_txn_slot() const override
   {
-    return true;
+    return _scope == TS_USER_ARGS_TXN;
+  }
+
+  bool
+  need_ssn_slot() const override
+  {
+    return _scope == TS_USER_ARGS_SSN;
   }
 
 private:
-  int      _flag_ix = -1;
-  uint64_t _mask    = 0;
+  TSUserArgType _scope   = TS_USER_ARGS_TXN;
+  int           _flag_ix = -1;
+  uint64_t      _mask    = 0;
 };
 
-// INT8 state variables
+// State/Session INT8 variables (parameterized by scope)
 class ConditionStateInt8 : public Condition
 {
   using DataType    = uint8_t;
   using MatcherType = Matchers<DataType>;
   using SelfType    = ConditionStateInt8;
 
 public:
-  explicit ConditionStateInt8()
+  explicit ConditionStateInt8(TSUserArgType scope = TS_USER_ARGS_TXN) : _scope(scope)
   {
     static_assert(sizeof(void *) == 8, "State Variables requires a 64-bit system.");
-    Dbg(dbg_ctl, "Calling CTOR for ConditionStateInt8");
+    Dbg(dbg_ctl, "Calling CTOR for ConditionStateInt8 (scope=%s)", _scope_label(_scope));
   }
 
   // noncopyable
@@ -862,36 +869,42 @@ class ConditionStateInt8 : public Condition
   bool
   need_txn_slot() const override
   {
-    return true;
+    return _scope == TS_USER_ARGS_TXN;
+  }
+
+  bool
+  need_ssn_slot() const override
+  {
+    return _scope == TS_USER_ARGS_SSN;
   }
 
 private:
-  // Little helper function to extract out the data from the TXN user pointer
   uint8_t
   _get_data(const Resources &res) const
   {
     TSAssert(_byte_ix >= 0 && _byte_ix < NUM_STATE_INT8S);
-    auto    ptr  = reinterpret_cast<uint64_t>(TSUserArgGet(res.state.txnp, _txn_slot));
+    auto    ptr  = _get_state_data(_scope, res);
     uint8_t data = (ptr & STATE_INT8_MASKS[_byte_ix]) >> (NUM_STATE_FLAGS + _byte_ix * 8);
 
     return data;
   }
 
-  int _byte_ix = -1;
+  TSUserArgType _scope   = TS_USER_ARGS_TXN;
+  int           _byte_ix = -1;
 };
 
-// INT16 state variables
+// State/Session INT16 variables (parameterized by scope)
 class ConditionStateInt16 : public Condition
 {
   using DataType    = uint16_t;
   using MatcherType = Matchers<DataType>;
   using SelfType    = ConditionStateInt16;
 
 public:
-  explicit ConditionStateInt16()
+  explicit ConditionStateInt16(TSUserArgType scope = TS_USER_ARGS_TXN) : _scope(scope)
   {
     static_assert(sizeof(void *) == 8, "State Variables requires a 64-bit system.");
-    Dbg(dbg_ctl, "Calling CTOR for ConditionStateInt16");
+    Dbg(dbg_ctl, "Calling CTOR for ConditionStateInt16 (scope=%s)", _scope_label(_scope));
   }
 
   // noncopyable
@@ -908,18 +921,25 @@ class ConditionStateInt16 : public Condition
   bool
   need_txn_slot() const override
   {
-    return true;
+    return _scope == TS_USER_ARGS_TXN;
+  }
+
+  bool
+  need_ssn_slot() const override
+  {
+    return _scope == TS_USER_ARGS_SSN;
   }
 
 private:
-  // Little helper function to extract out the data from the TXN user pointer
   uint16_t
   _get_data(const Resources &res) const
   {
-    auto ptr = reinterpret_cast<uint64_t>(TSUserArgGet(res.state.txnp, _txn_slot));
+    auto ptr = _get_state_data(_scope, res);
 
     return ((ptr & STATE_INT16_MASK) >> 48);
   }
+
+  TSUserArgType _scope = TS_USER_ARGS_TXN;
 };
 
 // Last regex capture

plugins/header_rewrite/factory.cc

@@ -87,6 +87,12 @@ operator_factory(const std::string &op)
     o = new OperatorSetStateInt8();
   } else if (op == "set-state-int16") {
     o = new OperatorSetStateInt16();
+  } else if (op == "set-session-flag") {
+    o = new OperatorSetStateFlag(TS_USER_ARGS_SSN);
+  } else if (op == "set-session-int8") {
+    o = new OperatorSetStateInt8(TS_USER_ARGS_SSN);
+  } else if (op == "set-session-int16") {
+    o = new OperatorSetStateInt16(TS_USER_ARGS_SSN);
   } else if (op == "set-effective-address") {
     o = new OperatorSetEffectiveAddress();
   } else if (op == "set-next-hop-strategy") {
@@ -191,6 +197,12 @@ condition_factory(const std::string &cond)
     c = new ConditionStateInt8();
   } else if (c_name == "STATE-INT16") {
     c = new ConditionStateInt16();
+  } else if (c_name == "SESSION-FLAG") {
+    c = new ConditionStateFlag(TS_USER_ARGS_SSN);
+  } else if (c_name == "SESSION-INT8") {
+    c = new ConditionStateInt8(TS_USER_ARGS_SSN);
+  } else if (c_name == "SESSION-INT16") {
+    c = new ConditionStateInt16(TS_USER_ARGS_SSN);
   } else if (c_name == "LAST-CAPTURE") {
     c = new ConditionLastCapture();
   } else {