Iconvex.Extension (iconvex v0.1.1)

Copy Markdown View Source

Transactional registration for external codec packages.

A package application can publish its complete codec set and table-provider set with one ownership token:

{:ok, token} =
  Iconvex.Extension.register(
    [
      MyPackage.Codec,
      {MyPackage.OtherCodec,
       canonical: "MY-SOURCE-OTHER", aliases: ["MY-OTHER"]}
    ],
    owner: :my_package,
    priority: 0,
    table_providers: [:my_table]
  )

# Store `token` in the application state.
:ok = Iconvex.Extension.unregister(token)

An atom in :table_providers uses the package :owner as its OTP application. {table_id, application} may be used when the table files live in a different application.

Providers become available before the codec routes are committed. Registration failure rolls back every provider acquired by this transaction. Shutdown removes codec routes before providers, so a concurrent conversion cannot resolve a new codec against a missing provider. The route snapshot makes each commit or removal externally atomic.

The token is opaque and exact. Passing an unknown or stale token is an idempotent no-op, and provider cleanup uses the underlying ownership references so it cannot remove a later replacement. Repeating an identical registration for the same owner adopts the committed token, including after a supervised registry-worker restart. A different active transaction for that owner is rejected.

Managed name claims are deterministic: canonical claims outrank aliases, then the larger integer priority wins within the same claim kind. Equal-rank claims by different modules are rejected as ambiguous. Priorities should be fixed package metadata, not runtime configuration.

Summary

Types

A module or a module with registration-specific canonical name and aliases.

Registration options.

A table ID using the owner application, or an explicit table ID/application pair.

Opaque ownership token for one complete package transaction.

Functions

Atomically registers one external package's codecs and table providers.

Removes the transaction owned by token.

Types

codec_registration()

@type codec_registration() :: module() | {module(), keyword()}

A module or a module with registration-specific canonical name and aliases.

register_option()

@type register_option() ::
  {:owner, atom()}
  | {:priority, integer()}
  | {:table_providers, [table_provider()]}

Registration options.

:owner and :priority are required. :table_providers defaults to an empty list, allowing codec-only packages. An empty codec and provider set is rejected; provider-only data packages are supported.

table_provider()

@type table_provider() :: atom() | {atom(), atom()}

A table ID using the owner application, or an explicit table ID/application pair.

token()

@opaque token()

Opaque ownership token for one complete package transaction.

Functions

register(registrations, options \\ [])

@spec register([codec_registration()], [register_option()]) ::
  {:ok, token()} | {:error, term()}

Atomically registers one external package's codecs and table providers.

Returns the same token when the active transaction for :owner has exactly the same codec metadata, providers, and priority.

unregister(token)

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

Removes the transaction owned by token.

Removal is conditional, replacement-safe, and idempotent. Unknown or already consumed reference tokens return :ok.