Concord.Compression (Concord v3.0.2)

Value compression for Concord KV store.

Provides transparent compression for large values to reduce memory usage and improve performance. Compression is automatically applied based on configurable size thresholds.

Configuration

config :concord,
  compression: [
    enabled: true,
    algorithm: :zlib,        # :zlib, :gzip, or :none
    threshold_bytes: 1024,   # Compress values larger than 1KB
    level: 6                 # Compression level 0-9 (0=none, 9=max)
  ]

Compression Format

Compressed values are stored as tuples: {:compressed, algorithm, binary} Uncompressed values are stored as-is.

Examples

# Compress a value
compressed = Concord.Compression.compress("large data...")
# {:compressed, :zlib, <<...>>}

# Decompress automatically
value = Concord.Compression.decompress(compressed)
# "large data..."

# Check if value should be compressed
Concord.Compression.should_compress?("small")  # false
Concord.Compression.should_compress?(large_data)  # true

Summary

Functions

compress(value, opts \\ [])

Compresses a value if it exceeds the configured size threshold.

config()

Returns the compression configuration.

decompress(compressed)

Decompresses a value if it was compressed.

safe_decompress(compressed)

Safely decompresses and decodes a recognized compression envelope.

should_compress?(value, opts \\ [])

Checks if a value should be compressed based on size threshold.

stats(value)

Returns compression statistics for a value.

Types

algorithm()

@type algorithm() :: :zlib | :gzip | :none

compressed_value()

@type compressed_value() :: {:compressed, algorithm(), binary()}

Functions

compress(value, opts \\ [])

@spec compress(
  term(),
  keyword()
) :: term() | compressed_value()

Compresses a value if it exceeds the configured size threshold.

Options

:algorithm - Compression algorithm (:zlib, :gzip, or :none)
:level - Compression level 0-9 (default: 6)
:force - Force compression regardless of size (default: false)

Examples

iex> Concord.Compression.compress("small value")
"small value"

iex> large_value = String.duplicate("x", 2048)
iex> Concord.Compression.compress(large_value)
{:compressed, :zlib, <<...>>}

iex> Concord.Compression.compress("force compress", force: true)
{:compressed, :zlib, <<...>>}

config()

@spec config() :: keyword()

Returns the compression configuration.

decompress(compressed)

@spec decompress(term() | compressed_value()) :: term()

Decompresses a value if it was compressed.

Automatically detects compressed values and decompresses them. Non-compressed values are returned as-is.

Examples

iex> Concord.Compression.decompress("plain value")
"plain value"

iex> compressed = {:compressed, :zlib, binary}
iex> Concord.Compression.decompress(compressed)
"original value"

safe_decompress(compressed)

@spec safe_decompress(term()) :: {:ok, term()} | {:error, :invalid_compressed_value}

Safely decompresses and decodes a recognized compression envelope.

Returns {:error, :invalid_compressed_value} for unsupported algorithms, malformed compressed data, or an external term larger than the immutable replicated-command limit. Logical safety is checked recursively by Concord.Validation after decoding.

should_compress?(value, opts \\ [])

@spec should_compress?(
  term(),
  keyword()
) :: boolean()

Checks if a value should be compressed based on size threshold.

Examples

iex> Concord.Compression.should_compress?("small")
false

iex> large = String.duplicate("x", 2048)
iex> Concord.Compression.should_compress?(large)
true

stats(value)

@spec stats(term()) :: map()

Returns compression statistics for a value.

Examples

iex> value = String.duplicate("x", 2048)
iex> Concord.Compression.stats(value)
%{
  original_size: 2048,
  compressed_size: 45,
  compression_ratio: 45.5,
  savings_bytes: 2003,
  savings_percent: 97.8
}