Compression Plugin

The Compression plugin provides automatic response compression using gzip, deflate, or Brotli algorithms. It reduces bandwidth usage and improves page load times by compressing text-based responses before sending them to clients.

Overview

The compression plugin intercepts HTTP responses and compresses them based on the client's Accept-Encoding header. It intelligently decides whether to compress based on content type, size thresholds, and client capabilities. This plugin is essential for optimizing web performance and reducing bandwidth costs.

Key Features

Multiple compression algorithms: Supports gzip, deflate, and Brotli
Smart compression: Only compresses suitable content types
Size thresholds: Configurable minimum and maximum size limits
Content negotiation: Respects client Accept-Encoding preferences
Compression levels: Adjustable compression/speed trade-off
Already-compressed detection: Skips files that are already compressed

Configuration

The compression plugin is configured as part of the plugin pipeline in your host configuration:

<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
    <span itemprop="library">file://./plugins/compression.so</span>
    <meta itemprop="algorithms" content="gzip,brotli">
    <meta itemprop="min_size" content="1024">
    <meta itemprop="compression_level" content="6">
</li>

Configuration Parameters

Parameter	Type	Required	Default	Description
`algorithms`	String (comma-separated)	No	"gzip,deflate"	Enabled compression algorithms: "gzip", "deflate", "brotli" (or "br")
`min_size`	Integer	No	1024	Minimum response size in bytes to compress (default: 1KB)
`max_size`	Integer	No	10485760	Maximum response size in bytes to compress (default: 10MB)
`compression_level`	Integer (0-9)	No	6	Compression level: 0 (no compression) to 9 (maximum compression)
`compressible_types`	String (comma-separated)	No	See defaults	MIME types to compress

Default Compressible Types

By default, the plugin compresses these content types:

text/html - HTML documents
text/css - Stylesheets
text/javascript - JavaScript files
text/plain - Plain text files
application/json - JSON data
application/javascript - JavaScript files
application/xml - XML documents
application/rss+xml - RSS feeds
application/atom+xml - Atom feeds
image/svg+xml - SVG images

Note: Binary formats like images (JPEG, PNG) and videos are not compressed as they already use efficient compression algorithms.

Compression Algorithms

Gzip

Widely supported by all browsers
Good compression ratios
Fast compression/decompression
Recommended for general use

Deflate

Slightly smaller headers than gzip
Same compression algorithm as gzip
Less commonly used

Brotli

Better compression ratios than gzip (10-20% smaller)
Slower compression but similar decompression speed
Requires HTTPS in most browsers
Supported by modern browsers

Plugin Pipeline Placement

Important: The compression plugin should be placed near the end of the pipeline, after content-generating plugins but before the access-log plugin.

Typical pipeline order:

1. basic-auth.so      → Authenticates user
2. authorization.so   → Checks permissions
3. selector-handler.so → Processes requests
4. file-handler.so    → Serves files
5. compression.so     → Compresses responses ✓
6. access-log.so      → Logs requests

Examples

Basic Gzip Compression

<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
    <span itemprop="library">file://./plugins/compression.so</span>
</li>

Brotli with Custom Settings

<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
    <span itemprop="library">file://./plugins/compression.so</span>
    <meta itemprop="algorithms" content="brotli,gzip">
    <meta itemprop="compression_level" content="4">
    <meta itemprop="min_size" content="512">
</li>

Testing Compression

# Request with gzip support
curl -H "Accept-Encoding: gzip" -I http://localhost:3000/large-file.html

# Request with Brotli support
curl -H "Accept-Encoding: br" -I http://localhost:3000/large-file.html

# View compression headers
curl -H "Accept-Encoding: gzip, br" -v http://localhost:3000/index.html 2>&1 | grep -i encoding

JavaScript Example

// Modern browsers automatically handle compression
fetch('http://localhost:3000/api/data.json')
    .then(response => {
        // Response is automatically decompressed
        console.log('Content-Encoding:', response.headers.get('Content-Encoding'));
        return response.json();
    })
    .then(data => console.log(data));

Performance Considerations

Compression Levels

Level	Compression Ratio	CPU Usage	Use Case
1-3	Low	Very Low	High-traffic sites with CPU constraints
4-6	Medium	Medium	Balanced performance (recommended)
7-9	High	High	Maximum compression, low-traffic sites

Size Thresholds

min_size: Don't compress tiny files (overhead exceeds benefit)
max_size: Skip very large files to avoid memory issues
Sweet spot: Files between 1KB and 10MB typically benefit most

Browser Compatibility

Algorithm	Chrome	Firefox	Safari	Edge	IE11
gzip	✓	✓	✓	✓	✓
deflate	✓	✓	✓	✓	✓
brotli	✓ (HTTPS)	✓ (HTTPS)	✓	✓ (HTTPS)	✗

Monitoring Compression

The plugin logs compression statistics when running with -v:

[Compression] Compressed 45632 bytes to 8921 bytes using gzip (80.5% reduction)

Monitor compression effectiveness:

Track bandwidth savings
Monitor CPU usage
Analyze compression ratios by content type
Watch for already-compressed content

Best Practices

Pre-compress static assets: For static files, consider pre-compressing and serving .gz files
CDN integration: Many CDNs handle compression automatically
Vary header: The plugin adds Vary: Accept-Encoding for proper caching
Test thoroughly: Verify compression works with your specific content types

Troubleshooting

Common Issues

Issue	Cause	Solution
No compression occurring	Content type not in list or size thresholds	Check content type and size configuration
Already compressed warning	Content has Content-Encoding header	Normal - plugin correctly skipping compressed content
High CPU usage	Compression level too high	Reduce compression_level to 4-6
Brotli not working	HTTP instead of HTTPS	Most browsers require HTTPS for Brotli
Memory issues	Compressing very large files	Reduce max_size limit

Debug Logging

Run the server with -v flag to see compression details:

./rusty-beam -v config.html