Crate crabka_metadata 

Versioned metadata records and the immutable image they apply to.

crabka-metadata provides MetadataRecord (the versioned union of topic / partition / broker registrations / topic deletions) and MetadataImage (an immutable snapshot of the cluster’s metadata).

The image is mutated only by MetadataImage::apply called from the Raft state machine in crabka-raft. Everywhere else it’s read via shared references and Arc clones.

Applying controller records

use crabka_metadata::{MetadataImage, MetadataRecord, TopicRecord};
use uuid::Uuid;

let mut image = MetadataImage::new(Uuid::new_v4());
let topic_id = Uuid::new_v4();

image.apply(&MetadataRecord::V1Topic(TopicRecord {
    name: "orders".into(),
    topic_id,
    partitions: 0,
    replication_factor: 3,
}));

let topic = image.topic("orders").expect("topic exists");
assert_eq!(topic.topic_id, topic_id);

Canonical quota entity keys

use crabka_metadata::canonicalize_entity;

let key = canonicalize_entity(vec![
    ("user".to_string(), Some("alice".to_string())),
    ("client-id".to_string(), Some("analytics".to_string())),
]);

assert_eq!(key[0].0, "client-id");
assert_eq!(key[1].0, "user");

Re-exports

pub use acl::AclEntry;

pub use acl::AclEntryFilter;

pub use acl::AclOperation;

pub use acl::PatternType;

pub use acl::PermissionType;

pub use acl::ResourceType;

pub use kafka_record::KafkaRecordError;

pub use kafka_record::from_kafka_record;

pub use kafka_record::to_kafka_record;

pub use kraft_translate::TranslateError;

pub use kraft_translate::from_kraft;

pub use kraft_translate::from_kraft_value;

pub use kraft_translate::to_kraft;

pub use kraft_translate::to_kraft_records;

pub use kraft_translate::to_kraft_values;

pub use voters::KRaftVersionRange;

pub use voters::Voter;

pub use voters::VoterEndpoint;

pub use voters::VoterSet;

Modules

acl

Wire-stable ACL types replicated through the raft quorum via MetadataRecord::V1AccessControlEntry / V1DeleteAccessControlEntry. Mirrors the shape Kafka exposes on the CreateAcls / DeleteAcls / DescribeAcls wire messages, but stays pure data — the authorizer in crabka-broker evaluates these.

group_version

KIP-848 group.version feature-level constants. A plain integer feature (no X.Y-IVn string table): level 0 = classic consumer groups only, level 1 = next-gen (KIP-848) protocol GA. Range + the metadata.version bootstrap-default threshold are pinned against the cp-kafka 4.0 GroupVersion enum (verified empirically 2026-05-30).

kafka_record

Bridge between MetadataRecord and the Kafka Record wire type.

kraft_translate

Translate Crabka’s internal MetadataRecord currency to/from the KIP-631 KraftMetadataRecord wire shape so the controller log and snapshots are genuinely KIP-631-framed.

metadata_version

KIP-778 metadata.version feature-level model. The canonical string<->integer-level table, mirrored byte-for-byte from upstream Kafka’s MetadataVersion enum over the range Crabka advertises ([METADATA_VERSION_MIN, METADATA_VERSION_MAX]). JVM clients call MetadataVersion.fromFeatureLevel(N) and throw on any level their enum doesn’t know, so the levels and X.Y-IVn names here MUST match upstream exactly. Verify against the cp-kafka 4.0 enum before editing.

transaction_version

KIP-890 transaction.version feature-level constants. Plain integer feature: 0 = classic (KIP-98) non-flexible txn-state records; 1 = flexible (tagged) txn-state records; 2 = epoch-bump-on-completion + server-side AddPartitionsToTxn verification. Range + the metadata.version bootstrap threshold are pinned against the cp-kafka 4.0 TransactionVersion enum (verified empirically 2026-05-30; both TV_1 and TV_2 bootstrap at 4.0-IV2).

voters

KIP-853 voter set value types: a voter is (id, directory-id, endpoints, kraft.version range).

Structs

BrokerConfigRecord

Per-broker configuration key/value pair. Some(value) = set; None = delete.

BrokerEndpoint

A single named listener endpoint advertised by a broker. Stored as a list on BrokerRegistrationRecord::endpoints so KRaft-style metadata can advertise per-listener host:port/protocol triples to clients on Metadata v9+. Legacy single-listener brokers leave the list empty and rely on the top-level host+port fields.

BrokerRegistrationRecord

ClientMetricsConfigRecord

KIP-714 client-metrics subscription config. Authoritative target state: each V1ClientMetricsConfig fully replaces the previous override map for name (the subscription name). Empty map = delete the subscription. Merging happens at the IncrementalAlterConfigs handler before the record is submitted (same pattern as TopicConfigRecord).

ClientQuotaRecord

DelegationToken

In-memory image type for a single delegation token (KIP-48). Mirrors DelegationTokenRecord minus any tombstone concerns — tombstones are handled as removals on the apply path.

DelegationTokenRecord

A single delegation token’s authoritative state (KIP-48). Replacement semantics — appending a new record with the same token_id overwrites the prior one in the image (used by both Create and Renew). Removal goes through DeleteDelegationTokenRecord. hmac is the 32-byte HMAC-SHA-256 over token_id keyed by the broker’s master secret key; clients authenticate via SCRAM-SHA-256 using the hex-encoded HMAC as the password.

DeleteDelegationTokenRecord

Tombstone record removing a delegation token (KIP-48) from the image. Emitted by ExpireDelegationToken handlers and the background expiry sweep.

DeleteScramCredentialRecord

DeleteTopicRecord

FeatureLevelRecord

KIP-584 finalized feature level. level is the finalized max_version_level for name. level == 0 is the KIP-584 sentinel for “delete this finalized feature” — MetadataImage::apply removes the entry rather than storing a zero. Replacement semantics: a later record with the same name overwrites the previous level.

FeaturesEpochRecord

Snapshot-only carrier for the KIP-584 finalized-features epoch.

KRaftVersionRecord

KIP-853: finalizes the cluster-wide kraft.version feature level.

MetadataImage

PartitionDirAssignmentRecord

KIP-858 directory-assignment delta. A broker reports which log-dir UUID hosts its replica of (topic, partition). Applied as a DELTA: sets ONLY the reporting replica’s slot in PartitionRecord.directories, never touching leader/isr/replicas/adding/removing — so it cannot clobber a concurrent reassignment or ISR change. On the KRaft log it rides a Crabka-private carrier (via to_kraft) so it decodes back to this same delta and applies as a one-slot merge — never a full-record replace.

PartitionRecord

QuotaEntity

ScramCredentialRecord

TopicConfigRecord

Mutable topic configuration overrides. Authoritative target state: each V1TopicConfig record fully replaces the previous override map for topic. Empty map = clear all overrides. Merging happens at the AlterConfigs handler before the record is submitted.

TopicRecord

UnregisterBrokerRecord

KIP-185 / UnregisterBroker (api_key 64). Marks a broker as permanently unregistered: the admin operator confirms the broker is gone for good and asks the cluster to drop its registration entry from the metadata image. Subsequent Metadata responses no longer advertise the broker’s endpoints; clients stop routing to it.

VotersRecord

KIP-853: full snapshot of the controller voter set.

Enums

MetadataError

MetadataRecord

ThrottleKind

Selects which KIP-73 throttle rate config key to read.

Traits

Feature

One versioned cluster feature (KIP-584).

Functions

bootstrap_feature_records

KIP-584/1022 bootstrap: one V1FeatureLevel record per registered feature at its per-release default, derived from bootstrap_mv (the bootstrap metadata.version level). Used by both crabka format and the broker’s standalone self-bootstrap so a fresh cluster finalizes every feature’s release default.

bootstrap_feature_records_with_overrides

KIP-1022 crabka format seeding: one V1FeatureLevel record per registered feature, each at its explicit --feature NAME=LEVEL override if present in overrides, else its per-release default for bootstrap_mv.

canonicalize_entity

feature

Look up a registered feature by name.

feature_registry

All features this broker supports finalizing. Single source of truth.

is_supported_level

True if level is within the registered feature’s supported range. false for an unknown feature (nothing supports that level).

validate_feature_dependencies

KIP-1022 dependency validation for a fully-resolved feature→level map (as seeded by crabka format). For every finalized feature, each of its dependencies(level) must be present in resolved at >= the required level. Returns Err naming the first unmet dependency. A no-op for today’s registry (no feature declares dependencies) but enforces the rule at format time, mirroring the UpdateFeatures handler.

Type Aliases

EntityKey

NodeId