ExZarr.Codecs.Registry (ExZarr v1.1.0)

Registry for managing built-in and custom codecs.

The registry maintains a mapping of codec IDs to codec modules and provides functions for registering, querying, and using codecs.

Overview

The registry is started automatically as part of ExZarr's supervision tree and is initialized with all built-in codecs. Custom codecs can be registered at application startup (via configuration) or at runtime.

Built-in Codecs

The following codecs are registered by default:

:none - No compression (passthrough)
:zlib - Zlib compression
:crc32c - CRC32C checksum
:zstd - Zstandard compression (if available)
:lz4 - LZ4 compression (if available)
:snappy - Snappy compression (if available)
:blosc - Blosc meta-compressor (if available)
:bzip2 - Bzip2 compression (if available)

Registering Custom Codecs

Via Configuration

Add to config/config.exs:

config :ex_zarr, :custom_codecs, [
  MyApp.CustomCodec,
  MyApp.AnotherCodec
]

Programmatically

ExZarr.Codecs.Registry.register(MyApp.CustomCodec)

At Application Start

defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    # Register custom codecs
    ExZarr.Codecs.Registry.register(MyApp.CustomCodec)

    # ... rest of supervision tree
  end
end

Querying Codecs

# Get a codec module
{:ok, module} = ExZarr.Codecs.Registry.get(:zstd)

# List all registered codec IDs
ids = ExZarr.Codecs.Registry.list()

# List only available codecs
available = ExZarr.Codecs.Registry.available()

# Get codec information
{:ok, info} = ExZarr.Codecs.Registry.info(:zstd)

Summary

Types

codec_id()

codec_module()

registry_state()

Functions

available()

Lists only available codecs.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get(codec_id)

Gets a codec module by ID.

info(codec_id)

Gets information about a codec.

list()

Lists all registered codec IDs.

Registers a custom codec module.

start_link(opts \\ [])

Starts the codec registry.

unregister(codec_id)

Unregisters a codec by ID.

Types

codec_id()

@type codec_id() :: atom()

codec_module()

@type codec_module() :: module()

registry_state()

@type registry_state() :: %{
  codecs: %{required(codec_id()) => codec_module()},
  opts: keyword()
}

Functions

available()

@spec available() :: [codec_id()]

Lists only available codecs.

A codec is available if it's registered and its available?/0 callback returns true.

Examples

iex> ExZarr.Codecs.Registry.available()
[:none, :zlib, :crc32c, :zstd, :lz4]

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get(codec_id)

@spec get(codec_id()) :: {:ok, codec_module()} | {:error, :not_found}

Gets a codec module by ID.

Examples

iex> ExZarr.Codecs.Registry.get(:zstd)
{:ok, ExZarr.Codecs.ZstdCodec}

iex> ExZarr.Codecs.Registry.get(:nonexistent)
{:error, :not_found}

Returns

{:ok, module()} - Codec found
{:error, :not_found} - Codec not registered

info(codec_id)

@spec info(codec_id()) :: {:ok, map()} | {:error, :not_found}

Gets information about a codec.

Returns the codec's metadata from its codec_info/0 callback.

Examples

iex> ExZarr.Codecs.Registry.info(:zstd)
{:ok, %{
  name: "Zstandard",
  version: "1.0.0",
  type: :compression,
  description: "Zstandard compression algorithm"
}}

Returns

{:ok, map()} - Codec information
{:error, :not_found} - Codec not registered

list()

@spec list() :: [codec_id()]

Lists all registered codec IDs.

Returns codec IDs regardless of whether they're currently available.

Examples

iex> ExZarr.Codecs.Registry.list()
[:none, :zlib, :crc32c, :zstd, :lz4, :snappy, :blosc, :bzip2, :my_codec]

register(codec_module, opts \\ [])

@spec register(
  codec_module(),
  keyword()
) :: :ok | {:error, term()}

Registers a custom codec module.

The module must implement the Codec behavior.

Options

:force - If true, overwrites existing codec with same ID (default: false)

Examples

iex> ExZarr.Codecs.Registry.register(MyCustomCodec)
:ok

iex> ExZarr.Codecs.Registry.register(MyCodec, force: true)
:ok

Returns

:ok - Codec registered successfully
{:error, :already_registered} - Codec ID already in use (unless force: true)
{:error, :invalid_codec} - Module doesn't implement Codec behavior

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the codec registry.

This is typically called automatically by the application supervision tree.

unregister(codec_id)

@spec unregister(codec_id()) :: :ok | {:error, term()}

Unregisters a codec by ID.

Built-in codecs cannot be unregistered.

Examples

iex> ExZarr.Codecs.Registry.unregister(:my_codec)
:ok

iex> ExZarr.Codecs.Registry.unregister(:zlib)
{:error, :cannot_unregister_builtin}

Returns

:ok - Codec unregistered successfully
{:error, :not_found} - Codec not registered
{:error, :cannot_unregister_builtin} - Cannot unregister built-in codec