A2UICore.Version (A2UICore v0.1.1)

Copy Markdown View Source

A2UI protocol-version registry and catalog compatibility rules.

Wire envelopes carry a string version field ("v0.9", "v0.9.1", "v1.0"). This module holds the supported set and the exact catalog-compatibility rule from the reference implementation (DEFAULT_CATALOG_COMPATIBILITY + the "same major ≥ 1" SemVer rule

  • normalization for non-semver identifiers).

Compatibility rule (verbatim from upstream)

  1. Normalize both sides via A2UICore.SemVer.to_canonical/1.
  2. Equal canonicals ⇒ compatible.
  3. The explicit map (below) extends compatibility per message version.
  4. If both sides are SemVer and the catalog's major is ≥ 1 and equals the message's major, they're compatible (minor/patch ignored).
  5. Otherwise — fallback: normalized raw string equality.

Summary

Types

protocol_version()

Functions

all()

All protocol versions known to this library, including legacy ones.

catalog_compatible?(catalog_version, message_version)

Whether catalog_version is compatible with message_version per the rule documented in the moduledoc.

catalog_compatible?(catalog_version, message_version, compatibility_map)
default_catalog_compatibility()

The default catalog-compatibility map (normalized canonical keys).

protocol_version?(version)

True if version (after SemVer parse) matches a known protocol version. The candidate may be written 0.9, v0.9, 0.9.1, v0.9.1, v1.0.

supported()

The versions this build implements. v0.8 is intentionally excluded.

to_protocol_version(version)

Resolves the protocol version a version designator names.

Types

protocol_version()

(since 0.1.0) 
@type protocol_version() :: String.t()

Functions

all()

(since 0.1.0) 
@spec all() :: [protocol_version()]

All protocol versions known to this library, including legacy ones.

catalog_compatible?(catalog_version, message_version)

(since 0.1.0) 
@spec catalog_compatible?(term(), term()) :: boolean()

Whether catalog_version is compatible with message_version per the rule documented in the moduledoc.

Examples

iex> A2UICore.Version.catalog_compatible?("v1.0", "v1.0")
true
iex> A2UICore.Version.catalog_compatible?("v0.9", "v0.9.1")
true
iex> A2UICore.Version.catalog_compatible?("v0.9.1", "v0.9")
true
iex> A2UICore.Version.catalog_compatible?("v1.0", "v0.9")
false
iex> A2UICore.Version.catalog_compatible?("unknown", "v1.0")
false

catalog_compatible?(catalog_version, message_version, compatibility_map)

(since 0.1.0) 
@spec catalog_compatible?(term(), term(), map()) :: boolean()

default_catalog_compatibility()

(since 0.1.0) 
@spec default_catalog_compatibility() :: %{
  required(String.t()) => MapSet.t(String.t())
}

The default catalog-compatibility map (normalized canonical keys).

Message canonical version → the catalog canonical versions it accepts.

protocol_version?(version)

(since 0.1.0) 
@spec protocol_version?(term()) :: boolean()

True if version (after SemVer parse) matches a known protocol version. The candidate may be written 0.9, v0.9, 0.9.1, v0.9.1, v1.0.

supported()

(since 0.1.0) 
@spec supported() :: [protocol_version()]

The versions this build implements. v0.8 is intentionally excluded.

to_protocol_version(version)

(since 0.1.0) 
@spec to_protocol_version(term()) :: {:ok, protocol_version()} | :error

Resolves the protocol version a version designator names.

v0.9, v0.9.1 and v1.0 (and any SemVer-equal variant such as 1.0.0-beta) round-trip to the same protocol version. Invalid strings produce :error (never raise).