apache · cmcfarlen · Feb 13, 2026 · Feb 13, 2026 · Feb 13, 2026 · Feb 17, 2026
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
diff --git a/.github/instructions/HRW.instructions.md b/.github/instructions/HRW.instructions.md
@@ -0,0 +1,223 @@
+---
+applyTo:
+  - "plugins/header_rewrite/**/*"
+  - "tools/hrw4u/**/*"
+---
+
+# Header Rewrite Plugin and HRW4U Transpiler
+
+## Overview
+
+Two closely related components that must be kept in sync:
+
+1. **header_rewrite plugin** (`plugins/header_rewrite/`) - ATS plugin for modifying HTTP headers
+2. **hrw4u transpiler** (`tools/hrw4u/`) - DSL compiler for generating header_rewrite configurations
+
+## Critical Requirement: Feature Synchronization
+
+**Features added to either component may require corresponding changes in the other.**
+
+### When to Update Both
+
+- **New operator in header_rewrite** → Add syntax and code generation in hrw4u
+- **New condition in header_rewrite** → Add parsing and symbols in hrw4u
+- **New variable/resource in header_rewrite** → Update hrw4u symbol tables and types
+- **New hook in header_rewrite** → Add hook syntax in hrw4u
+- **New hrw4u syntax** → Ensure correct header_rewrite config generation
+
+### Bidirectional Compilation
+
+Both directions must work:
+- **hrw4u** (forward): HRW4U source → header_rewrite config
+- **u4wrh** (reverse): header_rewrite config → HRW4U source
+
+Round-trip test: `hrw4u example.hrw4u | u4wrh` should produce equivalent output.
+
+## Header Rewrite Plugin
+
+### Architecture
+
+**Core files:**
+- `parser.cc/h` - Configuration syntax parser
+- `factory.cc/h` - Factory for operators and conditions
+- `operators.cc/h` - Header manipulation operations
+- `conditions.cc/h` - Conditional logic
+- `resources.cc/h` - Available variables (headers, IPs, etc.)
+- `statement.cc/h` - Rule statement abstraction
+- `ruleset.cc/h` - Rule collection and execution
+- `matcher.cc/h` - Pattern matching
+- `value.cc/h` - Value extraction and manipulation
+
+### Adding Features
+
+**New operator:**
+1. Define class in `operators.h`, implement in `operators.cc`
+2. Register in `factory.cc`
+3. Update hrw4u: `tables.py` (forward mapping tables), `visitor.py` (forward compiler - HRW4UVisitor), and `generators.py` (reverse-resolution tables used by u4wrh)
+
+**New condition:**
+1. Define class in `conditions.h`, implement in `conditions.cc`
+2. Register in `factory.cc`
+3. Update hrw4u: `visitor.py` for parsing, `tables.py` for symbol maps
+
+**New resource/variable:**
+1. Define in `resources.h`, implement in `resources.cc`
+2. Update hrw4u: `types.py` for type system, `tables.py` (OPERATOR_MAP/CONDITION_MAP/etc.) for symbol tables, `symbols.py` for resolver wiring, and `generators.py` for reverse mappings
+
+## HRW4U Transpiler
+
+### Purpose
+
+Provides readable DSL syntax that compiles to header_rewrite configuration.
+
+**Requirements:** Python 3.11+, ANTLR4
+
+### Project Structure
+
+```
+tools/hrw4u/
+├── src/                    # Python source
+│   ├── common.py          # Shared utilities
+│   ├── types.py           # Type system
+│   ├── symbols.py         # Symbol resolution
+│   ├── hrw_symbols.py     # Header rewrite symbols
+│   ├── tables.py          # Symbol/type tables
+│   ├── visitor.py         # Forward compiler (HRW4UVisitor - hrw4u script)
+│   ├── hrw_visitor.py     # Reverse compiler (HRWInverseVisitor - u4wrh script)
+│   ├── generators.py      # Reverse-resolution table generation
+│   ├── validation.py      # Semantic validation
+│   └── lsp/               # LSP server
+├── scripts/               # CLI tools
+│   ├── hrw4u             # Forward compiler (hrw4u → HRW config)
+│   ├── u4wrh             # Reverse compiler (HRW config → hrw4u)
+│   └── hrw4u-lsp         # LSP server
+├── grammar/              # ANTLR4 grammars
+└── tests/                # Test suite
+```
+
+### Key Modules
+
+**Type System (`types.py`):**
+- HRW4U type hierarchy
+- Variable types (string, int, bool, IP, etc.)
+- Operator signatures
+- Type checking and inference
+
+**Symbol Resolution (`symbols.py`, `hrw_symbols.py`, `tables.py`):**
+- Symbol tables for variables, operators, functions
+- Scope management
+- Built-in symbols for header_rewrite resources
+
+**Reverse-Resolution Tables (`generators.py`):**
+- Generates derived tables and reverse mappings from primary forward tables
+- Used by u4wrh (reverse compiler) to map HRW config back to hrw4u syntax
+- Eliminates duplication by maintaining single source of truth in forward tables
+
+**Visitors:**
+- `visitor.py` (HRW4UVisitor) - Forward compilation: hrw4u DSL → header_rewrite config
+- `hrw_visitor.py` (HRWInverseVisitor) - Reverse compilation: header_rewrite config → hrw4u DSL
+- `kg_visitor.py` (KnowledgeGraphVisitor) - Extracts structured graph data for analysis/visualization (used by `hrw4u-kg` script, rarely modified)
+
+### Adding Features
+
+**New operator:**
+1. Update grammar if new syntax needed
+2. Add symbol definition in `hrw_symbols.py`
+3. Add type signature in `types.py`
+4. Update forward compiler in `visitor.py` (HRW4UVisitor) to handle new operator
+5. Update `generators.py` to generate reverse mappings for u4wrh
+6. Update reverse compiler in `hrw_visitor.py` (HRWInverseVisitor) if special handling needed
+7. Add tests in `tests/test_ops.py` and `tests/test_ops_reverse.py`
+8. Update corresponding header_rewrite plugin code
+
+**New condition:**
+1. Update grammar if needed
+2. Add symbol definition in `hrw_symbols.py` and type info in `types.py`
+3. Update forward compiler in `visitor.py` (HRW4UVisitor)
+4. Update `generators.py` for reverse mappings
+5. Update reverse compiler in `hrw_visitor.py` (HRWInverseVisitor) if needed
+6. Add tests
+7. Update header_rewrite plugin
+
+**New variable:**
+1. Add to symbol tables (`tables.py`, `hrw_symbols.py`)
+2. Add type definition (`types.py`)
+3. Update forward compiler in `visitor.py` (HRW4UVisitor) for property access
+4. Update `generators.py` for reverse mappings
+5. Add tests
+6. Ensure header_rewrite supports it
+
+### Code Style
+
+**Python (3.11+):**
+- 4-space indentation (never tabs)
+- Type hints on all functions
+- Dataclasses for structured data
+- Modern Python features (match/case, walrus operator)
+
+**C++ (header_rewrite):**
+- Follow ATS C++20 standards
+- CamelCase classes, snake_case functions/variables
+- 2-space indentation
+- Empty line after declarations
+
+## Feature Addition Example
+
+**Hypothetical example to illustrate the workflow:**
+
+Adding a `has-prefix` operator (this operator does not exist):
+
+1. **header_rewrite plugin:**
+   ```cpp
+   // operators.h
+   class OperatorHasPrefix : public Operator {
+     void exec(const Resources &res) override;
+   };
+
+   // operators.cc - implement exec()
+   // factory.cc - register operator
+   ```
+
+2. **hrw4u transpiler:**
+   ```python
+   # hrw_symbols.py
+   OPERATORS = {
+       'has-prefix': OperatorSymbol(
+           name='has-prefix',
+           params=['target', 'prefix'],
+           return_type=BoolType()
+       ),
+   }
+
+   # generators.py
+   def generate_has_prefix_op(target, prefix):
+       return f'has-prefix {target} {prefix}'
+
+   # tests/test_ops.py
+   def test_has_prefix():
+       # Test forward compilation
+
+   # tests/test_ops_reverse.py
+   def test_has_prefix_reverse():
+       # Test reverse compilation
+   ```
+
+3. **Verify round-trip:**
+   ```bash
+   echo 'REMAP { if req.Host has-prefix "www." { } }' | hrw4u | u4wrh
+   ```
+
+## Common Pitfalls
+
+1. **Forgetting to update both components** - Changes often need coordination
+2. **Breaking round-trip** - Always test `hrw4u | u4wrh` round-trip
+3. **Symbol table drift** - Keep hrw4u symbols synced with plugin capabilities
+4. **Type mismatches** - Ensure type system matches plugin runtime behavior
+5. **Missing tests** - Add tests for both forward and reverse compilation
+
+## Documentation
+
+- User docs: `doc/admin-guide/plugins/header_rewrite.en.html`
+- Plugin README: `plugins/header_rewrite/README`
+- HRW4U README: `tools/hrw4u/README.md`
+- LSP README: `tools/hrw4u/LSP_README.md`
diff --git a/AGENTS.md b/AGENTS.md
@@ -308,6 +308,38 @@ SMDebug(dbg_ctl, "Processing request for URL: %s", url);
 - UPPER_CASE for macros and constants: `HTTP_SM_SET_DEFAULT_HANDLER`
 - Private member variables have the `m_` prefix.
 
+**Doxygen Comments:**
+
+When adding doxygen comments:
+
+- `@brief` is assumed for the first sentence, so give a brief summary right
+  after `/** ` without using `@brief`.
+- In the description of classes, functions, and member variables, convey the
+  responsibility of the item being described (its role and intent), not just
+  what the code obviously does.
+- Use `@a <name>` to reference a function argument by name in prose
+  (e.g. "If @a size is zero..."). Use `@c <text>` for inline code or
+  constants (e.g. `@c true`, `@c NULL`, `@c MyEnum::VALUE`).
+- Use `@ref`, `@see`, or `@sa` to cross-reference related types or functions
+  when that helps convey how items interact.
+- Use `@param` with `[in]`, `[out]`, or `[in,out]` to indicate the
+  parameter's direction, followed by a description of its meaning.
+- Use `@return` to describe the semantics of the returned value. Don't
+  restate the type; that is obvious from the signature and rendered docs.
+- Use `@note` for non-obvious caveats and `@warning` for hazards (e.g. lock
+  ordering, lifetime, or threading constraints).
+- Use `@code` ... `@endcode` for embedded usage examples.
+- For templates, document type parameters with `@tparam`.
+
+Conventions specific to this codebase:
+
+- Every new header file should start with a `/** @file` block (see existing
+  headers in `include/` for the standard license/section layout).
+- Prefer trailing briefs for data members and enumerators, e.g.
+  `int max_conns{0}; ///< Maximum concurrent connections.`
+- Use single-line `///` briefs for short function or type docs where a full
+  `/** ... */` block would be overkill.
+
 **Modern C++ Patterns (Preferred):**
 ```cpp
 // GOOD - Modern C++20

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -541,13 +541,15 @@ check_symbol_exists(SSL_error_description "openssl/ssl.h" HAVE_SSL_ERROR_DESCRIP
 check_symbol_exists(SSL_CTX_set_ciphersuites "openssl/ssl.h" TS_USE_TLS_SET_CIPHERSUITES)
 check_symbol_exists(SSL_CTX_set_keylog_callback "openssl/ssl.h" TS_HAS_TLS_KEYLOGGING)
 check_symbol_exists(SSL_CTX_set_tlsext_ticket_key_cb "openssl/ssl.h" HAVE_SSL_CTX_SET_TLSEXT_TICKET_KEY_CB)
+check_symbol_exists(SSL_CTX_add_cert_compression_alg "openssl/ssl.h" HAVE_SSL_CTX_ADD_CERT_COMPRESSION_ALG)
+check_symbol_exists(SSL_CTX_set1_cert_comp_preference "openssl/ssl.h" HAVE_SSL_CTX_SET1_CERT_COMP_PREFERENCE)
 check_symbol_exists(SSL_get_all_async_fds openssl/ssl.h TS_USE_TLS_ASYNC)
 check_symbol_exists(OSSL_PARAM_construct_end "openssl/params.h" HAVE_OSSL_PARAM_CONSTRUCT_END)
 check_symbol_exists(TLS1_3_VERSION "openssl/ssl.h" TS_USE_TLS13)
 check_symbol_exists(MD5_Init "openssl/md5.h" HAVE_MD5_INIT)
-check_symbol_exists(ENGINE_load_dynamic "include/openssl/engine.h" HAVE_ENGINE_LOAD_DYNAMIC)
-check_symbol_exists(ENGINE_get_default_RSA "include/openssl/engine.h" HAVE_ENGINE_GET_DEFAULT_RSA)
-check_symbol_exists(ENGINE_load_private_key "include/openssl/engine.h" HAVE_ENGINE_LOAD_PRIVATE_KEY)
+check_symbol_exists(ENGINE_load_dynamic "openssl/engine.h" HAVE_ENGINE_LOAD_DYNAMIC)
+check_symbol_exists(ENGINE_get_default_RSA "openssl/engine.h" HAVE_ENGINE_GET_DEFAULT_RSA)
+check_symbol_exists(ENGINE_load_private_key "openssl/engine.h" HAVE_ENGINE_LOAD_PRIVATE_KEY)
 check_symbol_exists(sysctlbyname "sys/sysctl.h" HAVE_SYSCTLBYNAME)
 
 if(SSLLIB_IS_OPENSSL3)
@@ -917,7 +919,8 @@ endif()
 add_custom_target(
   rat
   COMMENT "Running Apache RAT"
-  COMMAND java -jar ${CMAKE_SOURCE_DIR}/ci/apache-rat-0.13-SNAPSHOT.jar -E ${CMAKE_SOURCE_DIR}/ci/rat-regex.txt -d
+  COMMAND java -jar ${CMAKE_SOURCE_DIR}/ci/apache-rat-0.17.jar --input-exclude-file
+          ${CMAKE_SOURCE_DIR}/ci/rat-exclude.txt --input-include-file ${CMAKE_SOURCE_DIR}/ci/rat-include.txt --
           ${CMAKE_SOURCE_DIR}
 )
 

diff --git a/ci/apache-rat-0.13-SNAPSHOT.jar b/ci/apache-rat-0.13-SNAPSHOT.jar
diff --git a/ci/apache-rat-0.17.jar b/ci/apache-rat-0.17.jar
diff --git a/ci/asan_leak_suppression/regression.txt b/ci/asan_leak_suppression/regression.txt
@@ -2,7 +2,6 @@ leak:RegressionTest_PARENTSELECTION
 leak:ParentConfig::reconfigure
 leak:RegressionTest_SDK_API_TSHttpConnectIntercept
 leak:RegressionTest_SDK_API_TSHttpConnectServerIntercept
-leak:make_log_host
 leak:ReRegressionSM::clone
 leak:RegressionTest_ram_cache
 leak:RegressionTest_HttpTransact_is_request_valid
@@ -11,9 +10,7 @@ leak:MakeTextLogFormat
 leak:RegressionTest_HttpTransact_handle_trace_and_options_requests
 leak:CRYPTO_malloc
 leak:RegressionTest_SDK_API_TSMgmtGet
-leak:RegressionTest_Cache_vol
 leak:RegressionTest_SDK_API_TSCache
-leak:RegressionTest_Hdrs
 leak:RegressionTest_SDK_API_TSPortDescriptor
 leak:RegressionTest_HostDBProcessor
 leak:RegressionTest_DNS

diff --git a/ci/asan_leak_suppression/unit_tests.txt b/ci/asan_leak_suppression/unit_tests.txt
@@ -1,10 +1,4 @@
-# leaks in test_X509HostnameValidator
-leak:libcrypto.so.1.1
-# for OpenSSL 1.0.2:
-leak:CRYPTO_malloc
-leak:CRYPTO_realloc
-leak:ConsCell
-# PR#10295
-leak:pcre_jit_stack_alloc
-# PR#10541
+# marshal_hdr in test_http_hdr_print_and_copy_aux is intentionally
+# not destroyed because it holds a reference to a stack-allocated
+# TestRefCountObj whose free() override calls exit(1).
 leak:test_http_hdr_print_and_copy_aux