Crate krabka_metadata

Expand description

Versioned metadata records and the immutable image they apply to.

krabka-metadata provides MetadataRecord, the versioned union of topic, partition, broker-registration, and topic-deletion records, and MetadataImage, an immutable snapshot of the cluster’s metadata.

Only MetadataImage::apply mutates the image, and the Raft state machine in krabka-raft calls that method. Everywhere else reads it through shared references and Arc clones.

§Applying controller records

use krabka_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 krabka_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 break_glass::BreakGlassAction;
pub use break_glass::BreakGlassApproval;
pub use break_glass::BreakGlassProposalRecord;
pub use kafka_record::KafkaRecordError;
pub use kafka_record::from_kafka_record;
pub use kafka_record::to_kafka_record;
pub use krabka_version::KrabkaVersion;
pub use krabka_version::PrivateRpc;
pub use krabka_version::private_rpc_version;
pub use kraft_translate::PRIVATE_RECORD_VERSION;
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 write_freeze::TopicFreezeRecord;
pub use krabka_voters as voters;

Modules§

acl: Wire-stable ACL types replicated through the raft quorum with MetadataRecord::V1AccessControlEntry and V1DeleteAccessControlEntry. They mirror the shape that Kafka exposes on the CreateAcls, DeleteAcls, and DescribeAcls wire messages, but they stay pure data. The authorizer in krabka-broker evaluates them.
break_glass: Break-glass proposal records, replicated through the raft quorum with MetadataRecord::V1BreakGlassProposal and V1DeleteBreakGlassProposal.
directory_id: KIP-858 reserved log-directory ids, transcribed from Kafka’s org.apache.kafka.common.DirectoryId.
group_version: KIP-848 group.version feature-level constants. It is a plain integer feature with no X.Y-IVn string table: level 0 means classic consumer groups only, and level 1 means next-gen (KIP-848) protocol GA. The range and 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 a Kafka Record whose value is the wincode encoding of the record.
krabka_version: The krabka-owned krabka.version feature (KIP-584).
kraft_translate: Translate Krabka’s internal MetadataRecord currency to and 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 Krabka advertises ([METADATA_VERSION_MIN, METADATA_VERSION_MAX]). JVM clients call MetadataVersion.fromFeatureLevel(N) and throw on any level their enum does not know, so the levels and X.Y-IVn names here MUST match upstream exactly. Verify against MetadataVersion.java in Kafka’s server-common module on trunk before editing: levels are never reused, so the table must carry every level up to METADATA_VERSION_MAX, reserved ones included.
transaction_version: KIP-890 transaction.version feature-level constants, matching Kafka’s TransactionVersion, which defines TV_0 to TV_2 only. 0 means classic (KIP-98) non-flexible txn-state records, 1 means flexible (tagged) txn-state records, and 2 means an epoch bump on completion plus server-side AddPartitionsToTxn verification. Both TV_1 and TV_2 bootstrap at 4.0-IV2.
write_freeze: Topic write-freeze registry entries, replicated through the raft quorum with MetadataRecord::V1TopicFreeze.

Structs§

BrokerConfigRecord: Per-broker configuration key/value pair. Some(value) = set; None = delete.
BrokerEndpoint: A single named listener endpoint advertised by a broker. It is stored as a list on BrokerRegistrationRecord::endpoints, so KRaft-style metadata can advertise per-listener host:port and protocol triples to clients on Metadata v9+. A legacy single-listener broker leaves the list empty and relies on the top-level host and port fields.
BrokerRegistrationChangeRecord: Kafka’s BrokerRegistrationChangeRecord (metadata apiKey 17): a delta on the registration of one broker.
BrokerRegistrationRecord
ClientMetricsConfigRecord: KIP-714 client-metrics subscription config. Authoritative target state: each V1ClientMetricsConfig fully replaces the previous override map for name, the subscription name. An empty map deletes the subscription. The IncrementalAlterConfigs handler merges before it submits the record, in the same pattern as TopicConfigRecord.
ClientQuotaRecord
ControllerRegistrationRecord: KIP-919 controller registration persisted in the metadata log.
DelegationToken: In-memory image type for a single delegation token (KIP-48). Mirrors DelegationTokenRecord without any tombstone concerns. The apply path handles tombstones as removals.
DelegationTokenRecord: A single delegation token’s authoritative state (KIP-48). The record has replacement semantics: a new record with the same token_id overwrites the prior one in the image. Both Create and Renew use that. Removal goes through DeleteDelegationTokenRecord.
DeleteDelegationTokenRecord: Tombstone record that removes a delegation token (KIP-48) from the image. The ExpireDelegationToken handlers and the background expiry sweep emit it.
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 and does not store 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.
GroupConfigRecord: KIP-1071 dynamic configuration for one group resource. Each record is the authoritative override map for group_id; an empty map clears the resource.
KRaftVersionRange: Supported kraft.version range for a voter. The range is inclusive.
KRaftVersionRecord: KIP-853: finalizes the cluster-wide kraft.version feature level.
LeaderEpoch: A partition leader epoch. KIP-320 wire type: int32.
MetadataImage
NodeId: A broker or controller node id: the canonical krabka_ids::NodeId newtype, which is a u64 internally and Kafka’s int32 on the wire.
PartitionDirAssignmentRecord: KIP-858 directory-assignment delta. A broker reports which log-dir UUID hosts its replica of (topic, partition). Apply treats it as a DELTA: it sets ONLY the slot of the reporting replica in PartitionRecord.directories and never touches leader, isr, replicas, adding, or removing. It therefore cannot clobber a concurrent reassignment or ISR change. On the KRaft log it is encoded as Kafka’s standard PartitionChangeRecord with only the directories field set.
PartitionElrRecord: KIP-966 eligible-leader state for one partition. Empty vectors clear it.
PartitionOffsetAdvanceRecord: Diskless offset-sequencer delta: advance a partition’s committed next-offset by count.
PartitionRecord
PartitionRecoveryRecord
PartitionUpdateRecord: A Kafka PartitionChangeRecord can carry assignment, ELR, and recovery changes together. This record preserves that atomic update on replay.
ProducerIdsRecord: Durable controller state for cluster-wide producer-ID block allocation. next_producer_id is the first ID not covered by any committed block.
QuotaEntity
ScramCredentialRecord
TopicConfigRecord: Mutable topic configuration overrides. Authoritative target state: each V1TopicConfig record fully replaces the previous override map for topic. An empty map clears all overrides. The AlterConfigs handler merges before it submits the record.
TopicRecord
UnregisterBrokerRecord: KIP-919 / UnregisterBroker (api_key 64), Kafka’s UnregisterBrokerRecord (metadata apiKey 1). Marks a broker as permanently unregistered: the admin operator confirms that the broker is gone for good and asks the cluster to drop its registration entry from the metadata image. Later Metadata responses no longer advertise the endpoints of the broker, and clients stop routing to it.
UnregisterControllerRecord: KIP-1312 UnregisterController (api_key 94), Kafka trunk’s UnregisterControllerRecord (metadata apiKey 29). Removes the registration of one controller. An apply against an unknown node_id does nothing.
Voter: One voter’s full identity.
VoterEndpoint: A single listener endpoint advertised by a voter.
VoterSet: The authoritative voter set, ordered by node id.
VotersRecord: KIP-853: full snapshot of the controller voter set.

Enums§

FencingChange: A change to the fencing state of a broker registration, as Kafka’s BrokerRegistrationFencingChange encodes it in BrokerRegistrationChangeRecord.Fenced.
LeaderRecoveryState: KIP-704 state of an uncleanly elected leader.
MetadataError
MetadataRecord
ThrottleKind: Selects which broker byte-rate config key to read.

Constants§

DEFAULT_BROKER_CONFIG_NODE_ID: Internal identity for Kafka’s cluster-wide default broker-config resource. Broker IDs are non-negative signed 32-bit integers on the Kafka wire, so this value cannot collide with a real broker.

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. Both krabka format and the broker’s standalone self-bootstrap use this, so a fresh cluster finalizes the release default of every feature.
bootstrap_feature_records_with_overrides: KIP-1022 krabka 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).
supported_feature_ranges: Supported feature ranges advertised by a Krabka broker or controller when it registers with the KRaft controller.
validate_feature_dependencies: KIP-1022 dependency validation for a fully-resolved feature→level map, as seeded by krabka format. For every finalized feature, each of its dependencies(level) must be present in resolved at >= the required level. Returns Err with the name of the first unmet dependency, enforcing the rule at format time in the same way as the UpdateFeatures handler.

Type Aliases§

EntityKey

Crate krabka_metadata

Crate krabka_metadata Copy item path

§Applying controller records

§Canonical quota entity keys

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate krabka_metadata