ADR-0018: Built-in Response Compression Middleware

ADR-0018: Built-in Response Compression Middleware

• Status: Accepted
• Date: 2025-10-27
• Deciders: Core Engineering Team

Context

ContextForge serves large JSON responses for endpoints like GET /tools, GET /servers, GET /openapi.json, and JSON-RPC messages. These responses can range from tens of kilobytes to several megabytes, especially in deployments with many registered tools and servers.

Bandwidth consumption impacts:

• Cloud egress costs (charged per GB transferred)
• Response latency (larger payloads take longer to transfer)
• Mobile client performance (slow networks, data caps)
• Multi-regional deployments (cross-region bandwidth costs)

We needed to decide whether to implement compression at the application level or rely on external infrastructure (nginx, CDN, service mesh).

Decision

We will implement built-in response compression middleware directly in the FastAPI application with support for multiple compression algorithms:

• Brotli (best compression ratio, modern browsers)
• Zstd (fast compression, good ratio)
• GZip (universal compatibility, fallback)

Implementation:

• Middleware location: mcpgateway/main.py:888-907
• Configuration: mcpgateway/config.py:379-384
• Algorithm priority: Brotli > Zstd > GZip (based on client Accept-Encoding header)
• Minimum response size threshold: configurable (default 500 bytes)
• Automatic Vary: Accept-Encoding header for cache compatibility

Environment Variables:

COMPRESSION_ENABLED=true                 # Enable/disable (default: true)
COMPRESSION_MINIMUM_SIZE=500             # Minimum bytes to compress (default: 500)
COMPRESSION_GZIP_LEVEL=6                 # GZip: 1-9 (default: 6 balanced)
COMPRESSION_BROTLI_QUALITY=4             # Brotli: 0-11 (default: 4 balanced)
COMPRESSION_ZSTD_LEVEL=3                 # Zstd: 1-22 (default: 3 fast)

Compression applies to:

• JSON responses (application/json)
• HTML (text/html)
• CSS (text/css)
• JavaScript (application/javascript, text/javascript)
• Plain text (text/plain)

Compression skips:

• Responses smaller than COMPRESSION_MINIMUM_SIZE
• Already compressed content (images, videos)
• Streaming responses (SSE, WebSocket)
• Clients not advertising Accept-Encoding

Consequences

Positive

• 📉 30-70% bandwidth reduction - JSON responses compress very well
• 💰 Lower egress costs - Significant savings in cloud environments
• 🚀 Faster response times - Smaller payloads transfer faster over network
• 📱 Better mobile experience - Critical for slow networks and data caps
• 🌍 Multi-regional efficiency - Reduced cross-region bandwidth usage
• 🎯 Application control - Tune compression per endpoint, no external dependency
• 🔧 No infrastructure changes - Works standalone without nginx/CDN

Negative

• ⚙️ CPU overhead - Compression adds 5-10ms latency for typical responses
• 💾 Memory usage - Compression buffers increase memory footprint slightly
• 🔄 Complexity - Additional middleware to maintain and configure

Neutral

• 🌐 Browser compatibility - Brotli supported in all modern browsers (95%+ coverage)
• 📊 Monitoring - Need to track compression ratios and CPU impact
• 🔀 Cache compatibility - Vary header ensures correct caching behavior

Performance Impact

Based on testing with real endpoints:

Latency impact:

• Brotli level 4: +5-10ms (balanced)
• GZip level 6: +3-7ms (faster)
• Zstd level 3: +2-5ms (fastest)

Net effect: For responses >10KB over slow networks (< 10 Mbps), compression reduces total time by 30-60% despite CPU overhead.

Tuning for Different Scenarios

High-traffic production (optimize for speed):

COMPRESSION_GZIP_LEVEL=4          # Faster compression
COMPRESSION_BROTLI_QUALITY=3      # Lower quality, faster
COMPRESSION_ZSTD_LEVEL=1          # Fastest

Bandwidth-constrained (optimize for size):

COMPRESSION_GZIP_LEVEL=9          # Best compression
COMPRESSION_BROTLI_QUALITY=11     # Maximum quality
COMPRESSION_ZSTD_LEVEL=9          # Balanced slow

Development (disable compression):

COMPRESSION_ENABLED=false         # No compression overhead

Why Not External Compression?

We considered delegating compression to nginx, CDN, or service mesh:

Decision rationale:

• Built-in compression works in all deployment modes (standalone, serverless, containers)
• Application-level control - Different compression for different endpoints
• Zero infrastructure dependency - Works without nginx/Envoy/CDN
• Optional composition - Can still use nginx/CDN on top for additional caching

Testing Compression

# Test Brotli compression
curl -H "Accept-Encoding: br" http://localhost:8000/openapi.json -v 2>&1 | grep -i "content-encoding"
# Should show: content-encoding: br

# Test GZip compression
curl -H "Accept-Encoding: gzip" http://localhost:8000/openapi.json -v 2>&1 | grep -i "content-encoding"
# Should show: content-encoding: gzip

# Verify Vary header
curl -H "Accept-Encoding: br" http://localhost:8000/openapi.json -v 2>&1 | grep -i "vary"
# Should show: vary: Accept-Encoding

# Measure compression ratio
curl -w "%{size_download}\n" -o /dev/null -s http://localhost:8000/openapi.json  # Uncompressed
curl -H "Accept-Encoding: br" -w "%{size_download}\n" -o /dev/null -s http://localhost:8000/openapi.json  # Brotli

Alternatives Considered

Status

This decision has been implemented. Response compression middleware is enabled by default with Brotli/Zstd/GZip support.

References

• Middleware implementation: mcpgateway/main.py:888-907
• Configuration: mcpgateway/config.py:379-384
• Testing guide: CLAUDE.md (Performance Configuration section)
• Scaling documentation: docs/docs/manage/scale.md:797-876