Enum MetadataEntry 

pub enum MetadataEntry {
    CatalogDdl {
        payload: Vec<u8>,
    },
    CatalogDdlAudited {
        payload: Vec<u8>,
        auth_user_id: String,
        auth_user_name: String,
        sql_text: String,
    },
    Batch {
        entries: Vec<MetadataEntry>,
    },
    TopologyChange(TopologyChange),
    RoutingChange(RoutingChange),
    ClusterVersionBump {
        from: u16,
        to: u16,
    },
    DescriptorLeaseGrant(DescriptorLease),
    DescriptorLeaseRelease {
        node_id: u64,
        descriptor_ids: Vec<DescriptorId>,
    },
    DescriptorDrainStart {
        descriptor_id: DescriptorId,
        up_to_version: u64,
        expires_at: Hlc,
    },
    DescriptorDrainEnd {
        descriptor_id: DescriptorId,
    },
    CaTrustChange {
        add_ca_cert: Option<Vec<u8>>,
        remove_ca_fingerprint: Option<[u8; 32]>,
    },
    SurrogateAlloc {
        hwm: u32,
    },
    JoinTokenTransition {
        token_hash: [u8; 32],
        transition: JoinTokenTransitionKind,
        ts_ms: u64,
    },
    MigrationCheckpoint {
        migration_id: String,
        phase: MigrationPhaseTag,
        attempt: u32,
        payload: MigrationCheckpointPayload,
        crc32c: u32,
        ts_ms: u64,
    },
    MigrationAbort {
        migration_id: String,
        reason: String,
        compensations: Vec<Compensation>,
    },
}

An entry in the replicated metadata log.

Every mutation to cluster-wide state — DDL, topology, routing, descriptor leases, cluster version bumps — is encoded as one of these variants, proposed against the metadata Raft group, and applied on every node by a crate::metadata_group::applier::MetadataApplier.

The CatalogDdl variant is the single wire shape for every DDL mutation. Its payload is an opaque, host-serialized nodedb::control::catalog_entry::CatalogEntry value — the nodedb-cluster crate is deliberately ignorant of the host’s per-DDL-object struct shapes. This keeps the cluster crate layering-clean and makes adding new DDL object types on the host side a zero-wire-change operation.

Variants

CatalogDdl

Single generic DDL entry carrying an opaque host-side payload. Produced by every pgwire DDL handler via nodedb::control::metadata_proposer::propose_catalog_entry.

Fields

payload: Vec<u8>

CatalogDdlAudited

DDL entry with attached audit context. Produced by pgwire DDL handlers that have the authenticated identity + raw statement text bound at the call site (every CREATE, ALTER, DROP, GRANT, REVOKE path). Applied identically to CatalogDdl on every node; additionally, the production applier fsync- appends an audit record to the audit segment WAL with the authenticated user, HLC at commit, descriptor versions before

• after, and the raw SQL — exactly what J.4 requires.

Carries its own payload so legacy proposers (internal lease and descriptor-drain flows that have no SQL text) can keep using the plain CatalogDdl variant without synthesizing fake audit context.

Fields

payload: Vec<u8>

auth_user_id: String

Authenticated user id at propose time.

auth_user_name: String

Authenticated username at propose time.

sql_text: String

Raw SQL statement as the client sent it. Not parsed here — the cluster crate is opaque to SQL syntax. Persisted on every replica so post-hoc audit queries don’t depend on the proposing node still being alive.

Batch

Atomic batch of metadata entries proposed by a transactional DDL session (BEGIN; CREATE ...; CREATE ...; COMMIT;). The applier unpacks and applies each sub-entry in order at a single raft log index, so either all commit or none do.

Fields

entries: Vec<MetadataEntry>

TopologyChange(TopologyChange)

RoutingChange(RoutingChange)

ClusterVersionBump

Fields

from: u16

to: u16

DescriptorLeaseGrant(DescriptorLease)

DescriptorLeaseRelease

Fields

node_id: u64

descriptor_ids: Vec<DescriptorId>

DescriptorDrainStart

Begin draining leases on a descriptor. While a drain entry is active, any acquire_descriptor_lease at version <= up_to_version must be rejected cluster-wide so the in-flight DDL that bumps the version can make progress.

expires_at is the HLC at which this drain entry is considered stale and ignored by is_draining checks on read. Acts as a TTL that prevents a crashed proposer from leaving an orphaned drain that blocks the cluster forever.

Fields

descriptor_id: DescriptorId

up_to_version: u64

expires_at: Hlc

DescriptorDrainEnd

End draining on a descriptor. Emitted explicitly on drain timeout so the cluster can make progress. On the happy path (successful Put* apply), the host-side applier clears drain implicitly — this variant is the escape hatch for the failure path.

Fields

descriptor_id: DescriptorId

CaTrustChange

Cluster-wide CA trust mutation (L.4). Proposed by nodedb rotate-ca --stage (to add a new CA) and nodedb rotate-ca --finalize --remove <fp> (to drop an old CA). Applied on every node by MetadataCommitApplier: writes or deletes data_dir/tls/ca.d/<fp_hex>.crt and triggers a live rebuild of the rustls server + client configs so the new trust set takes effect without restart.

add_ca_cert and remove_ca_fingerprint are independent: the --stage form sets add_ca_cert = Some(new_ca_der) + remove_ca_fingerprint = None; --finalize flips both. A single entry carrying both performs the cutover atomically once the operator has confirmed every node has reissued.

Fields

add_ca_cert: Option<Vec<u8>>

DER-encoded CA certificate to add to the trust set. None when this entry only removes.

remove_ca_fingerprint: Option<[u8; 32]>

SHA-256 fingerprint of the CA to remove from the trust set. None when this entry only adds.

SurrogateAlloc

Advance the cluster-wide surrogate high-watermark to hwm.

Proposed by the metadata-group leader whenever the local SurrogateRegistry flush threshold trips (every 1024 allocations or 200 ms, whichever comes first). Applied on every node by the host-side MetadataCommitApplier which calls SurrogateRegistry::restore_hwm(hwm) — idempotent and monotonic, so out-of-order replay or duplicate delivery are both safe. Followers must never allocate surrogates locally; they only advance their in-memory HWM via these log entries.

Fields

hwm: u32

JoinTokenTransition

Join-token lifecycle transition (L.4). Proposed by the bootstrap-listener handler on every state change so that all Raft peers can enforce single-use token semantics even after a crash-restart cycle.

token_hash is the SHA-256 of the token hex string — the raw token is never stored in the log. transition encodes the direction: Register for first issuance, BeginInFlight when a joiner presents the token, MarkConsumed when the bundle is delivered, RevertInFlight when the dead-man timer fires, and MarkExpired / MarkAborted for the terminal states.

Fields

token_hash: [u8; 32]

transition: JoinTokenTransitionKind

ts_ms: u64

Unix-ms timestamp at the time of the proposal.

MigrationCheckpoint

Crash-safe migration phase checkpoint. Persisted on every phase transition; on coordinator restart, recovery scans the MigrationStateTable and resumes from the latest committed checkpoint. Apply is idempotent on (migration_id, phase, attempt) — duplicate delivery is a no-op. CRC32C mismatch is fatal.

Fields

migration_id: String

Hyphenated UUID string (zerompk does not serialize uuid::Uuid).

phase: MigrationPhaseTag

attempt: u32

payload: MigrationCheckpointPayload

crc32c: u32

ts_ms: u64

MigrationAbort

Replicated migration abort with ordered compensations. Each compensation is applied in order; any failure is fatal (no warn-and-continue). On success, the migration’s row in MigrationStateTable is deleted.

Fields

migration_id: String

reason: String

compensations: Vec<Compensation>

Trait Implementations

impl Clone for MetadataEntry

fn clone(&self) -> MetadataEntry

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for MetadataEntry

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for MetadataEntry

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'__msgpack_de> FromMessagePack<'__msgpack_de> for MetadataEntry

fn read<R: Read<'__msgpack_de>>(reader: &mut R) -> Result<Self, Error>

where Self: Sized,

Reads the MessagePack representation of this value from the provided reader.

impl PartialEq for MetadataEntry

fn eq(&self, other: &MetadataEntry) -> 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 Serialize for MetadataEntry

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl ToMessagePack for MetadataEntry

fn write<W: Write>(&self, writer: &mut W) -> Result<(), Error>

Writes the MessagePack representation of this value into the provided writer.

impl Eq for MetadataEntry

impl StructuralPartialEq for MetadataEntry