How Headroom's ContentRouter Manages and Routes Content Types for Optimal Compression

Headroom's ContentRouter selects compression strategies through a three-phase pipeline that detects mixed-content documents, classifies pure content types using a Rust-based detector, and maps specific ContentType enums to specialized CompressionStrategy implementations.

In the chopratejas/headroom repository, the ContentRouter serves as the intelligent traffic controller for compression operations. This component analyzes incoming payloads to determine whether they contain code, JSON, search results, or mixed formats, then routes each section to the appropriate compressor. Understanding how Headroom's ContentRouter manages and routes different content types reveals the architectural decisions that optimize compression ratios across diverse data formats.

The Three-Phase Routing Architecture

The routing logic in headroom/transforms/content_router.py follows a strict decision hierarchy implemented across three distinct phases.

Phase 1: Mixed-Content Detection

Before attempting content classification, the router checks if the input contains multiple distinct formats. The is_mixed_content() function (lines 24-41) scans the document using four compiled regex patterns: _CODE_FENCE_PATTERN, _JSON_BLOCK_START, _SEARCH_RESULT_PATTERN, and _PROSE_PATTERN.

If at least two indicators trigger simultaneously, the router returns CompressionStrategy.MIXED and delegates to _compress_mixed(), which splits the document into sections using split_into_sections() and compresses each independently with its optimal strategy.

Phase 2: Content-Type Classification

For non-mixed content, _determine_strategy() calls _detect_content() (lines 10-27) to identify the specific format. The implementation first attempts detection via the Rust-based headroom._core.detect_content_type binding. If this returns plain_text, the system falls back to _regex_detect_content_type() for lightweight pattern matching.

The result is a ContentType enum value defined in headroom/transforms/content_detector.py, such as SOURCE_CODE, JSON_ARRAY, SEARCH_RESULTS, BUILD_OUTPUT, GIT_DIFF, HTML, or PLAIN_TEXT.

Phase 3: Strategy Mapping and Selection

The final phase occurs in _strategy_from_detection() (lines 27-36), which translates ContentType enums into concrete implementations through a static mapping dictionary:

mapping = {
    ContentType.SOURCE_CODE: CompressionStrategy.CODE_AWARE,
    ContentType.JSON_ARRAY: CompressionStrategy.SMART_CRUSHER,
    ContentType.SEARCH_RESULTS: CompressionStrategy.SEARCH,
    ContentType.BUILD_OUTPUT: CompressionStrategy.LOG,
    ContentType.GIT_DIFF: CompressionStrategy.DIFF,
    ContentType.HTML: CompressionStrategy.HTML,
    ContentType.PLAIN_TEXT: CompressionStrategy.TEXT,
}

If the detected type lacks a specific mapping, the router uses self.config.fallback_strategy, which defaults to CompressionStrategy.KOMPRESS.

Implementation Details and Source Code References

Content Detection Deep Dive

The detection pipeline prioritizes performance through Rust integration. When headroom._core.detect_content_type returns a lowercase type tag, _detect_content() converts it to the corresponding Python enum member. This approach minimizes Python overhead for large payloads while maintaining accuracy through the regex fallback for edge cases.

Strategy Resolution Logic

The _determine_strategy() method orchestrates the complete decision flow:

if is_mixed_content(content):
    return CompressionStrategy.MIXED
detection = _detect_content(content)
return self._strategy_from_detection(detection)

Configuration flags can alter resolution logic. When prefer_code_aware_for_code is disabled, source code routes to KOMPRESS instead of CODE_AWARE, allowing users to bypass AST-aware processing when unnecessary.

Fallback Chains and Error Handling

The _apply_strategy_to_content() method implements resilient fallback chains. If CODE_AWARE compression fails or is disabled, the router automatically attempts KOMPRESS. Similarly, SMART_CRUSHER failures cascade to the fallback strategy. Each routing decision is captured in a RoutingDecision object, with final results stored in RouterCompressionResult including the actually applied strategy.

Configuration Options

Customize routing behavior through ContentRouterConfig:

• enable_code_aware: Toggle AST-aware compression for source code detection
• fallback_strategy: Default compressor when detection fails or mapping is undefined (default: KOMPRESS)
• prefer_code_aware_for_code: Prefer CODE_AWARE over KOMPRESS for detected code types

Practical Code Examples

Basic Content Routing

from headroom.transforms import ContentRouter

router = ContentRouter()

# JSON payload automatically routes to SmartCrusher

json_data = '[{"id":1,"value":"compress me"}]'
result = router.compress(json_data)
print(result.strategy_used)  # CompressionStrategy.SMART_CRUSHER

Handling Mixed Documents

mixed_doc = """

# Configuration

```json
{"setting": "value"}

Explanation text follows. """

result = router.compress(mixed_doc) print(result.strategy_used) # CompressionStrategy.MIXED

print(result.routing_log) # List of RoutingDecision objects per section

### Custom Configuration

```python
from headroom.transforms import ContentRouter, ContentRouterConfig, CompressionStrategy

config = ContentRouterConfig(
    enable_code_aware=False,
    fallback_strategy=CompressionStrategy.TEXT
)
router = ContentRouter(config=config)

# Forces TEXT strategy for plain content instead of KOMPRESS

result = router.compress("Simple text document")

Summary

• ContentRouter analyzes all payloads through is_mixed_content() before attempting type-specific detection
• Mixed documents split into sections and route individually via CompressionStrategy.MIXED
• Pure content flows through Rust-based detection (headroom._core.detect_content_type) with regex fallback in _detect_content()
• Strategy mapping uses a static dictionary linking ContentType enums to CompressionStrategy implementations in _strategy_from_detection()
• Fallback chains ensure compression succeeds even when preferred strategies fail or are disabled
• Configuration via ContentRouterConfig controls code-aware preferences and default fallback behavior

Frequently Asked Questions

What happens when ContentRouter encounters unrecognized content?

When detection returns an unmapped type or the Rust detector fails, the router defaults to self.config.fallback_strategy, which is CompressionStrategy.KOMPRESS unless explicitly configured otherwise. This ensures all payloads receive compression even when type classification is uncertain or ambiguous.

How does ContentRouter handle documents containing both code and prose?

The is_mixed_content() function identifies these documents by scanning for multiple pattern indicators including code fences, JSON blocks, search results, and prose sections. When mixed content is detected, the router applies CompressionStrategy.MIXED, splits the document using split_into_sections(), and routes each section to its optimal compressor individually, preserving format-specific optimizations.

Can I force ContentRouter to use a specific compression strategy?

While ContentRouter is designed for automatic selection, you can influence outcomes through configuration. Set enable_code_aware=False to force code payloads toward KOMPRESS, or adjust fallback_strategy to change the default catch-all. However, for explicit strategy selection, instantiate specific compressors directly rather than using the router, as the router's purpose is intelligent routing based on content analysis.

What telemetry does ContentRouter provide for routing decisions?

After compression, _record_to_toin() logs the operation to the TOIN telemetry system, except for SMART_CRUSHER operations which self-record. The RouterCompressionResult object contains routing_log with RoutingDecision entries detailing which strategy was selected, whether fallback chains were invoked, and which compressor ultimately processed the content.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}