Struct ComponentRegistry 

pub struct ComponentRegistry { /* private fields */ }

A component registry stored as a TlsMap<ComponentId, VLBytes> where each value is a protobuf-encoded ComponentMetadata describing the component’s data type and permission policies.

The registry provides deterministic TLS serialization (sorted by ComponentId) and enforces that hardcoded and reserved component IDs cannot be modified through this map (their permissions are enforced in code).

Stored at well-known component ID 0x8000 (ComponentId::COMPONENT_REGISTRY).

One raw map, a validated view

The map holds every entry exactly as it was read, byte for byte — including entries this build cannot validate. Validation is applied lazily on read: get, iter, contains, and len present only recognized entries (those that pass validate_entry). An entry that fails validation is invisible to all of them, so a write against it falls to the deny-by-default NoRegistryEntry policy verdict. The raw bytes still surface through to_bytes (verbatim) and unrecognized_ids (a diagnostic).

Two invariants motivate carrying bytes we can’t read:

• Never fork by dropping bytes. The registry lives inside the app_data_dictionary group-context extension; every member must compute byte-identical dict bytes or the group splits. A committer reads the dict, changes one component, and re-emits the whole thing, so it must round-trip untouched entries exactly — and prost does not preserve unknown proto fields across a decode/re-encode, which is why we keep raw VLBytes and never re-serialize an entry we didn’t author.
• Never brick on state we didn’t write. A single entry left by a newer protocol version, or by a historically buggy writer (a poisoned group), must degrade to “that one component is unwritable here,” never to “no commit on this group validates again.” Rejecting the whole snapshot would do the latter, because the registry is decoded on the validation path of every commit.

Tolerance is a read-side backstop, not an enforcement hole: new entries still cannot enter a group’s registry unvalidated (the steady-state wire path validates per-mutation and the bootstrap validator validates each entry of the initial delta).

Implementations

impl ComponentRegistry

pub fn new() -> Self

pub fn get( &self, id: &ComponentId, ) -> Result<Option<ComponentMetadata>, ComponentRegistryError>

Get the metadata for a recognized component.

Returns Ok(None) both when no entry exists and when an entry exists but fails validate_entry — an unreadable entry is deny-by-default, indistinguishable from absent, so callers never have to tell the two apart. The Result is retained for API stability; this method does not currently produce an error.

pub fn set( &mut self, id: ComponentId, meta: ComponentMetadata, ) -> Result<(), ComponentRegistryError>

Register or update a component’s metadata.

For mutable components in the registry, this silently overwrites any existing entry — there is no audit log here because the audit trail lives in the MLS commit history that produced the change.

A valid write to an id that currently holds an unrecognized entry repairs it — the raw bytes are overwritten, so to_bytes serializes the repaired value rather than resurrecting the broken bytes.

Rejects invalid IDs, IDs in the reserved range, hardcoded components (whose permissions are enforced in code, not metadata), immutable components that already hold a recognized entry (write-once semantics), metadata missing required fields, and constrained components with invalid policy values.

pub fn remove(&mut self, id: &ComponentId) -> Result<(), ComponentRegistryError>

Remove a component from the registry.

Rejects everything set rejects (invalid IDs, reserved, hardcoded, and overwrite of a write-once-immutable entry). Removing a modifiable id drops its bytes whether the entry was recognized or an unrecognized one preserved by from_bytes (repair-by-delete).

pub fn contains(&self, id: &ComponentId) -> bool

Returns true if the registry contains a recognized entry for the given component. An unrecognized (preserved-but-invalid) entry reports false.

pub fn len(&self) -> usize

Returns the number of recognized entries. Unrecognized entries preserved by from_bytes are not counted.

pub fn is_empty(&self) -> bool

Returns true if the registry has no recognized entries. A registry carrying only unrecognized entries still reports empty.

pub fn iter( &self, ) -> impl Iterator<Item = Result<(ComponentId, ComponentMetadata), ComponentRegistryError>> + '_

Iterate over the recognized component IDs and their decoded metadata, in ComponentId order. Unrecognized entries preserved by from_bytes are skipped — writes against them fall to deny-by-default — and are surfaced via unrecognized_ids instead.

Each item is a Result for API stability; a recognized entry always decodes, so this only ever yields Ok.

pub fn to_bytes(&self) -> Result<Vec<u8>, ComponentRegistryError>

Serialize the registry as the dict-storage format: the raw TlsMap<ComponentId, VLBytes> snapshot, verbatim. Because the map is stored exactly as read (recognized and unrecognized entries alike), a load → store round-trip is byte-identical and never drops data another (possibly newer) client wrote.

Wire-format encoding (a TlsMapDelta describing changes) is done piecemeal at the call site — there is no whole-registry wire encoder, because every steady-state update emits only the few entries it touches, and the bootstrap encoder builds its TlsMapDelta-from-empty inline at the synthesis site (see xmtp_mls::groups::app_data::migration::synthesize_initial_component_values).

pub fn from_bytes(bytes: &[u8]) -> Result<Self, ComponentRegistryError>

Deserialize a component registry from its dict-storage format: a raw TlsMap<ComponentId, VLBytes> snapshot.

Fails only when the outer TlsMap doesn’t decode (truncated / non-canonical bytes). Individual entries are not validated here — they’re kept raw and validated lazily on read, so an entry from a newer protocol version (or a historical invalid entry) is preserved rather than making every future commit on the group unvalidatable. Callers that care can inspect unrecognized_ids and log.

New entries cannot enter a group’s registry unvalidated: the steady-state wire path validates per-mutation (ComponentRegistryComponent::apply_update_payload / expand_to_changes) and the bootstrap validator validates each entry of the initial delta. Tolerance here is the read-side backstop, not the enforcement point.

pub fn unrecognized_ids(&self) -> impl Iterator<Item = ComponentId> + '_

Component ids of entries from_bytes preserved but that could not validate. Empty in the overwhelmingly common case; non-empty means the dict was written by a newer protocol version (or carries a historical invalid entry) and is worth a log line at the load site.

pub fn validate_entry( id: ComponentId, raw: &[u8], ) -> Result<(), ComponentRegistryError>

Validate one (ComponentId, raw bytes) entry against the registry’s invariants — the single definition of “recognized.” Used by the wire-decode path in the bootstrap validator (which walks a TlsMapDelta’s mutations directly so it can surface the Insert-only check before per-entry validation) and, internally, by every read method.

Trait Implementations

impl Clone for ComponentRegistry

fn clone(&self) -> ComponentRegistry

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ComponentRegistry

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ComponentRegistry

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for ComponentRegistry

fn eq(&self, other: &ComponentRegistry) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for ComponentRegistry