Indiko.Blocks.API.Compression 2.1.2

Indiko.Blocks.API.Compression

Response compression block for reducing API response sizes using Gzip and Brotli compression algorithms.

Overview

This package provides automatic HTTP response compression for ASP.NET Core APIs, supporting both Gzip and Brotli compression with configurable compression levels and MIME types.

Features

• Gzip Compression: Standard compression with wide browser support
• Brotli Compression: Modern compression with better ratios
• HTTPS Support: Configurable compression over HTTPS
• MIME Type Filtering: Specify which content types to compress
• Compression Levels: Adjustable compression levels (Fastest, Optimal, SmallestSize)
• Automatic Negotiation: Client-side compression format negotiation
• Performance: Significant bandwidth reduction (60-80% typical)

Installation

dotnet add package Indiko.Blocks.API.Compression

Quick Start

Enable Compression

// Compression is automatically enabled via block system
// when configured in appsettings.json

Configuration (appsettings.json)

{
  "CompressionOptions": {
    "Enabled": true,
    "EnableGzip": true,
    "EnableBrotli": true,
    "EnableForHttps": true,
    "MimeTypes": [
      "application/json",
      "application/xml",
      "text/plain",
      "text/html",
      "text/css",
      "text/javascript",
      "application/javascript"
    ]
  }
}

Compression Algorithms

Gzip

• Browser Support: Universal (all modern browsers)
• Compression Ratio: Good (~60-70% reduction)
• Speed: Fast
• Use Case: Default choice for broad compatibility

Brotli

• Browser Support: Modern browsers (Chrome 50+, Firefox 44+, Edge 15+)
• Compression Ratio: Excellent (~70-80% reduction)
• Speed: Slightly slower than Gzip
• Use Case: Best compression for modern clients

Configuration Options

CompressionOptions

public class CompressionOptions
{
    // Enable/disable compression
    public bool Enabled { get; set; } = true;
    
    // Enable Gzip compression
    public bool EnableGzip { get; set; } = true;
    
    // Enable Brotli compression
    public bool EnableBrotli { get; set; } = true;
    
    // Enable compression over HTTPS
    public bool EnableForHttps { get; set; } = true;
    
    // MIME types to compress
    public string[] MimeTypes { get; set; }
}

Full Configuration Example

{
  "CompressionOptions": {
    "Enabled": true,
    "EnableGzip": true,
    "EnableBrotli": true,
    "EnableForHttps": true,
    "MimeTypes": [
      "text/plain",
      "text/html",
      "text/xml",
      "text/css",
      "text/javascript",
      "application/javascript",
      "application/json",
      "application/xml",
      "application/x-javascript",
      "image/svg+xml"
    ]
  }
}

Compression Levels

Gzip Configuration

services.Configure<GzipCompressionProviderOptions>(options =>
{
    // Fastest compression (less CPU, larger files)
    options.Level = CompressionLevel.Fastest;
    
    // Optimal balance (default)
    options.Level = CompressionLevel.Optimal;
    
    // Smallest size (more CPU, smaller files)
    options.Level = CompressionLevel.SmallestSize;
});

Brotli Configuration

services.Configure<BrotliCompressionProviderOptions>(options =>
{
    // Similar levels available
    options.Level = CompressionLevel.Fastest;
    options.Level = CompressionLevel.Optimal;
    options.Level = CompressionLevel.SmallestSize;
});

Default Behavior

By default, the block uses:

• Gzip: CompressionLevel.SmallestSize (best compression)
• Brotli: CompressionLevel.Fastest (fast with good compression)

This balances performance and bandwidth savings.

How It Works

Content Negotiation

1. Client sends request with Accept-Encoding header
2. Server checks if content type should be compressed
3. Server selects best compression algorithm (Brotli > Gzip)
4. Response is compressed and sent with Content-Encoding header

Example Request/Response

Request:

GET /api/users HTTP/1.1
Host: api.example.com
Accept-Encoding: gzip, deflate, br

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Encoding: br
Content-Length: 234
Vary: Accept-Encoding

[compressed content]

MIME Types

Default MIME Types

The block automatically compresses these types:

• text/plain
• text/css
• text/html
• text/xml
• text/javascript
• application/json
• application/xml
• application/javascript
• application/x-javascript

Custom MIME Types

Add additional types in configuration:

{
  "CompressionOptions": {
    "MimeTypes": [
      "application/json",
      "application/xml",
      "image/svg+xml",
      "application/vnd.api+json",
      "application/x-protobuf"
    ]
  }
}

Exclusions

Don't Compress

Compression is NOT applied to:

• Already Compressed: Images (JPEG, PNG, GIF), Videos, Audio files
• Small Responses: Responses under ~1KB (overhead not worth it)
• Streaming: Chunked transfer encoding
• No Accept-Encoding: Clients that don't support compression

Example: Exclude Specific Endpoint

[HttpGet("large-binary")]
[ResponseCache(NoStore = true, Location = ResponseCacheLocation.None)]
public IActionResult GetLargeBinary()
{
    // This endpoint returns pre-compressed data
    Response.Headers.Add("Content-Encoding", "identity");
    return File(binaryData, "application/octet-stream");
}

Performance Impact

Bandwidth Savings

Average Savings: 60-80% bandwidth reduction

CPU Impact

• Gzip: ~2-5ms additional server processing
• Brotli: ~5-10ms additional server processing

For most APIs, this is negligible compared to network transfer time.

HTTPS Compression

Security Consideration

Compression over HTTPS can theoretically be vulnerable to attacks like BREACH. However, for APIs:

1. APIs rarely reflect user input in responses
2. BREACH requires specific attack conditions
3. Benefits typically outweigh risks for APIs

Enable/Disable

{
  "CompressionOptions": {
    "EnableForHttps": true  // Set to false if concerned about BREACH
  }
}

Testing Compression

Using cURL

# Test Gzip
curl -H "Accept-Encoding: gzip" -I https://api.example.com/api/users

# Test Brotli
curl -H "Accept-Encoding: br" -I https://api.example.com/api/users

# Response should include:
# Content-Encoding: br (or gzip)

Using Browser DevTools

1. Open Developer Tools (F12)
2. Go to Network tab
3. Make API request
4. Check response headers for Content-Encoding
5. Compare Size (compressed) vs Content (uncompressed)

Best Practices

1. Enable Both: Support both Gzip and Brotli for broad compatibility
2. Compress Text Only: Don't compress images, videos, or already-compressed files
3. Monitor Performance: Track CPU usage and response times
4. Adjust Levels: Use faster compression for high-traffic endpoints
5. Cache Headers: Combine with response caching for better performance
6. CDN: Use CDN compression if available

Advanced Configuration

Conditional Compression

public class ConditionalCompressionBlock : CompressionBlock
{
    public override void ConfigureServices(IServiceCollection services)
    {
        services.AddResponseCompression(options =>
        {
            options.EnableForHttps = true;
            
            // Custom condition
            options.Providers.Add<GzipCompressionProvider>();
            options.Providers.Add<BrotliCompressionProvider>();
            
            // Only compress responses > 4KB
            options.MimeTypes = ResponseCompressionDefaults.MimeTypes;
        });
    }
}

Per-Endpoint Control

[HttpGet]
[ResponseCache(VaryByHeader = "Accept-Encoding")]
public IActionResult GetData()
{
    // Compression applied automatically
    return Ok(data);
}

[HttpGet("no-compression")]
public IActionResult GetUncompressedData()
{
    // Disable compression for this endpoint
    Response.Headers.Add("Content-Encoding", "identity");
    return Ok(data);
}

Environment-Specific Configuration

Development (Faster)

{
  "CompressionOptions": {
    "Enabled": true,
    "EnableGzip": true,
    "EnableBrotli": false,  // Disable for faster dev server
    "EnableForHttps": true
  }
}

Production (Best Compression)

{
  "CompressionOptions": {
    "Enabled": true,
    "EnableGzip": true,
    "EnableBrotli": true,  // Enable for best compression
    "EnableForHttps": true
  }
}

Monitoring

Key Metrics

• Compression Ratio: Uncompressed size / Compressed size
• CPU Usage: Monitor server CPU during compression
• Response Time: Total time including compression
• Bandwidth Savings: Network bytes saved

Logging

public class CompressionLoggingMiddleware
{
    public async Task InvokeAsync(HttpContext context, RequestDelegate next)
    {
        var originalBodyStream = context.Response.Body;
        
        using var memoryStream = new MemoryStream();
        context.Response.Body = memoryStream;
        
        await next(context);
        
        var uncompressedSize = memoryStream.Length;
        memoryStream.Position = 0;
        
        await memoryStream.CopyToAsync(originalBodyStream);
        
        var encoding = context.Response.Headers["Content-Encoding"].ToString();
        var compressedSize = context.Response.ContentLength ?? uncompressedSize;
        
        _logger.LogInformation(
            "Compressed response: {UncompressedSize} ? {CompressedSize} bytes ({Encoding})",
            uncompressedSize, compressedSize, encoding);
    }
}

Troubleshooting

Compression Not Working

1. Check Accept-Encoding header in request
2. Verify MIME type is in configuration
3. Ensure response is not already compressed
4. Check if Enabled = true in configuration
5. Verify middleware order (UseResponseCompression should be early)

Performance Issues

1. Reduce compression level (use Fastest)
2. Increase minimum response size threshold
3. Disable Brotli, use only Gzip
4. Consider CDN compression instead

Target Framework

• .NET 10

Dependencies

• Microsoft.AspNetCore.ResponseCompression
• Indiko.Blocks.Common.Abstractions

License

See LICENSE file in the repository root.

Related Packages

• Indiko.Blocks.API.Swagger - API documentation
• Indiko.Blocks.API.FeatureManagement - Feature flags
• Indiko.Blocks.API.Idempotency - Idempotent requests
• Indiko.Hosting.Web - Web API hosting