HRW4U - Header Rewrite for You

HRW4U is a domain-specific language and compiler toolchain for Apache Traffic Server's header_rewrite plugin, providing a more readable and maintainable alternative to writing header rewrite rules directly.

Tools Overview

hrw4u - Forward Compiler

Compiles HRW4U source files into Apache Traffic Server header_rewrite configuration.

Input: Human-readable HRW4U syntax Output: Native header_rewrite plugin rules

u4wrh - Reverse Compiler

Decompiles existing header_rewrite rules back into HRW4U source code.

Input: Native header_rewrite plugin rules Output: Human-readable HRW4U syntax

Requirements

• Python 3.11+ (uses modern type annotations and performance features)
• ANTLR4 for grammar parsing
• uv (for Python environment management)

Development Setup

1. Clone and Setup Environment

git clone https://github.com/apache/trafficserver.git
cd trafficserver/tools/hrw4u

# Install uv if not already installed
# See: https://docs.astral.sh/uv/getting-started/installation/

# Create virtual environment and install dependencies
uv sync --all-extras

2. Build the Package

# Generate parsers and build packages
make

# Create distributable wheel
make package

3. Install for Development

# Install in development mode
uv pip install -e .

# Or install the built wheel
uv pip install dist/hrw4u-*.whl

Testing

# Run all tests
make test

# Run specific test categories
uv run pytest -m examples    # Documentation examples
uv run pytest -m conds       # Condition tests
uv run pytest -m ops         # Operator tests
uv run pytest -m reverse     # Reverse compilation tests

Usage

Forward Compilation (hrw4u)

# Compile HRW4U source to header_rewrite rules
hrw4u input.hrw4u > output.conf

# From stdin
cat input.hrw4u | hrw4u > output.conf

# Show parse tree (debugging)
hrw4u --ast input.hrw4u

# Enable debug output
hrw4u --debug input.hrw4u

Options:

• --hrw - Produce header_rewrite output (default)
• --ast - Show ANTLR parse tree
• --debug - Enable debug tracing

Reverse Compilation (u4wrh)

# Decompile header_rewrite rules to HRW4U source
u4wrh rules.conf > output.hrw4u

# From stdin
cat rules.conf | u4wrh > output.hrw4u

# Show parse tree (debugging)
u4wrh --ast rules.conf

# Enable debug output
u4wrh --debug rules.conf

Options:

• --hrw4u - Produce HRW4U source output (default)
• --ast - Show ANTLR parse tree
• --debug - Enable debug tracing

Example

HRW4U Source (example.hrw4u):

REMAP {
    if inbound.ip in {10.0.0.0/8, 192.168.0.0/16} {
        inbound.req.X-IP = "{inbound.ip}";
    }
}

Generated header_rewrite rules:

hrw4u example.hrw4u

cond %{REMAP_PSEUDO_HOOK} [AND]
cond %{IP:CLIENT} {10.0.0.0/8,192.168.0.0/16}
    set-header X-IP "%{IP:CLIENT}"

Generated hrw4u script from header_rewrite rules:

hrw4u example.hrw4u | u4wrh

REMAP {
    if inbound.ip in {10.0.0.0/8, 192.168.0.0/16} {
        inbound.req.X-IP = "{inbound.ip}";
    }
}

Passing the output from hrw4u back into u4wrh brings back the original script again!

JSON response bodies

Use the two-argument set-body form to set body content and its MIME type together. Double braces delimit literal brace content, so JSON object braces are not interpreted as HRW4U interpolation:

REMAP {
    http.status = 400;
    set-body("{{"error": "bad request"}}\n", "application/problem+json");
}

set-body-from(url) preserves the fetched response's Content-Type. Pass a second argument, set-body-from(url, content_type), to override it. This function is available in the READ_RESPONSE section.

Use set-body-from-file(path, content_type) in REMAP or SEND_RESPONSE to load a local body when the rule configuration is loaded. Relative paths are resolved from the directory containing the rule file.

Build System

The project uses a hybrid build system:

• GNU Make - Grammar generation and package building
• pyproject.toml - Modern Python packaging configuration
• ANTLR4 - Grammar compilation to Python parsers

Key Make Targets

make           # Build everything (default)
make clean     # Remove build artifacts
make test      # Run test suite
make package   # Create distributable wheel

Project Structure

tools/hrw4u/
├── src/                  # Python source code
│   ├── common.py        # Shared utilities and patterns
│   ├── types.py         # Type definitions and dataclasses
│   ├── symbols.py       # Symbol resolution engine
│   └── ...              # Additional modules
├── scripts/             # Command-line entry points
│   ├── hrw4u           # Forward compiler script
│   └── u4wrh           # Reverse compiler script
├── grammar/             # ANTLR4 grammar definitions
├── tests/               # Comprehensive test suite
└── pyproject.toml       # Modern Python package configuration

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

---

Part of the Apache Traffic Server project.