CompressionPlugin Schema

Schema definition for the Compression Plugin, which provides response compression using gzip, deflate, and brotli algorithms.

Schema Information

Property	Value
Schema URL	`https://rustybeam.net/schema/CompressionPlugin`
Parent Schema	https://rustybeam.net/schema/UtilityPlugin
Description	Response compression with multiple algorithms and configurable content type filters

Properties

Property	Type	Cardinality	Description
algorithms	https://rustybeam.net/schema/Text	0..1	Comma-separated list of compression algorithms: "gzip", "deflate", "brotli" (or "br"). Defaults to "gzip,deflate,brotli".
min_size	https://rustybeam.net/schema/Number	0..1	Minimum response size in bytes to compress. Responses smaller than this are not compressed. Defaults to 1024 (1KB).
max_size	https://rustybeam.net/schema/Number	0..1	Maximum response size in bytes to compress. Responses larger than this are not compressed. Defaults to 10485760 (10MB).
compressible_types	https://rustybeam.net/schema/Text	0..1	Comma-separated list of MIME types to compress. Defaults to text/html, text/css, text/javascript, text/plain, application/json, application/javascript, application/xml.
compression_level	https://rustybeam.net/schema/Number	0..1	Compression level (1-9): 1=fastest/least compression, 9=slowest/best compression. Defaults to 6 for balanced performance.
name	https://rustybeam.net/schema/Text	0..1	Plugin instance name for identification. Defaults to "compression" if not specified.

Usage Examples

Basic Compression (Default Settings)

<tr itemscope itemtype="https://rustybeam.net/schema/CompressionPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_compression.so</span>
</tr>

Custom Compression Configuration

<tr itemscope itemtype="https://rustybeam.net/schema/CompressionPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_compression.so</span>
    <span itemprop="algorithms">gzip,brotli</span>
    <span itemprop="min_size">2048</span>
    <span itemprop="max_size">5242880</span>
    <span itemprop="compression_level">9</span>
    <span itemprop="name">high_compression</span>
</tr>

Specific Content Types Only

<tr itemscope itemtype="https://rustybeam.net/schema/CompressionPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_compression.so</span>
    <span itemprop="algorithms">gzip</span>
    <span itemprop="compressible_types">text/html,text/css,application/json</span>
    <span itemprop="compression_level">3</span>
</tr>

Fast Compression for High Traffic

<tr itemscope itemtype="https://rustybeam.net/schema/CompressionPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_compression.so</span>
    <span itemprop="algorithms">gzip</span>
    <span itemprop="compression_level">1</span>
    <span itemprop="min_size">512</span>
    <span itemprop="name">fast_compression</span>
</tr>

Compression Algorithms

Algorithm	Config Value	Description	Compression Ratio	Speed
Gzip	`gzip`	Widely supported, good balance	Good	Fast
Deflate	`deflate`	Similar to gzip but different wrapper	Good	Fast
Brotli	`brotli` or `br`	Modern algorithm, best compression	Excellent	Slower

Algorithm Selection
The plugin automatically selects the best compression algorithm based on the client's Accept-Encoding header and the configured algorithms list. Brotli is preferred for modern browsers, with gzip as a widely compatible fallback.

Default Compressible Content Types

text/html - HTML documents
text/css - CSS stylesheets
text/javascript - JavaScript files
text/plain - Plain text files
application/json - JSON data
application/javascript - JavaScript applications
application/xml - XML documents
image/svg+xml - SVG images
application/font-woff - WOFF fonts
application/font-woff2 - WOFF2 fonts

Schema Inheritance

This schema inherits from the UtilityPlugin schema, which provides:

logfile - Log file path
directory - Directory configuration
enabled - Plugin enable/disable state

And ultimately from the base Plugin schema, which provides:

library - Plugin library path
plugin - Base plugin reference property

Compression Behavior

Content-Type Check: Only compresses configured MIME types
Size Filtering: Respects min_size and max_size limits
Client Support: Checks Accept-Encoding header
Already Compressed: Skips responses that are already compressed
Header Updates: Sets Content-Encoding and updates Content-Length
Error Handling: Falls back to uncompressed on compression errors

Validation Rules

algorithms must contain valid compression algorithms: "gzip", "deflate", "brotli", "br"
min_size and max_size must be positive integers
max_size should be greater than min_size
compression_level must be between 1 and 9 (inclusive)
compressible_types should contain valid MIME type patterns
The name property should be unique if multiple compression plugins are used

Plugin Pipeline Placement
The Compression Plugin should be placed near the end of the plugin pipeline, after content generation but before access logging. This ensures that generated content is compressed before being sent to clients.

Performance Considerations

CPU Usage: Higher compression levels use more CPU
Memory Usage: Compression requires buffering response content
Latency: Compression adds processing time
Bandwidth Savings: Significant reduction in transfer size
Cache Impact: Compressed responses may be cached differently

Recommended Settings by Use Case

Use Case	Algorithms	Level	Min Size	Rationale
High Traffic	gzip	1-3	1024	Fast compression, lower CPU usage
Static Content	gzip,brotli	9	512	Best compression, content rarely changes
API Responses	gzip,deflate	6	256	Balanced for JSON/XML responses
Mobile Optimized	brotli,gzip	8	512	Maximum bandwidth savings

Integration with Other Plugins

File Handler Plugin: Compresses static file responses
Selector Handler Plugin: Compresses HTML selector responses
Error Handler Plugin: Compresses custom error pages
Access Log Plugin: Should be placed after compression to log compressed sizes
Security Headers Plugin: Works together for optimal response headers

Client-Side Considerations

Browser Support: All modern browsers support gzip/deflate
Brotli Support: Supported by Chrome, Firefox, Safari, Edge
Accept-Encoding: Plugin respects client compression preferences
Decompression: Browsers handle decompression automatically
Content-Encoding: Properly set for client processing