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>,
    },
    DdlPrepared {
        token: u64,
        entry: Box<MetadataEntry>,
    },
    DdlPrepareAcquire {
        token: u64,
    },
    DdlPrepareRelease {
        token: u64,
    },
    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]>,
    },
    SyncProducerRegister {
        lite_id: String,
        producer_id: u64,
        tenant_id: u64,
        epoch: u64,
        created_ms: i64,
    },
    SyncProducerFence {
        lite_id: String,
        new_epoch: u64,
    },
    SurrogateAlloc {
        hwm: u32,
    },
    SurrogateReserve {
        node_id: u64,
        request_id: u64,
        batch_size: 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>

DdlPrepared

A catalog DDL proposal fenced by the replicated preparation owner. Appliers execute entry only while token is the current owner; superseded proposals are deterministic no-ops so they cannot wedge the Raft apply watermark.

Fields

token: u64

entry: Box<MetadataEntry>

DdlPrepareAcquire

Acquire the replicated global descriptor-preparation lease. The first unexpired owner wins; contenders observe the winner after this entry is applied and retry after its matching release or expiry.

Fields

token: u64

DdlPrepareRelease

Release the descriptor-preparation lease iff token still owns it.

Fields

token: u64

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.

SyncProducerRegister

Replicate a new Lite client registration to every node.

On apply every node writes the same registration row verbatim and advances its producer-id allocator HWM to at least producer_id, so a future leader never reissues the same id after a failover. The producer_id and initial epoch are assigned by the leader before proposing, so all replicas store identical state.

Applied host-side only; the cluster cache tracks the applied index.

Fields

lite_id: String

producer_id: u64

tenant_id: u64

epoch: u64

created_ms: i64

SyncProducerFence

Replicate a fencing epoch advance to every node.

Applied with max-wins semantics: each node sets current_epoch = max(stored_epoch, new_epoch) so out-of-order or duplicate delivery cannot roll the epoch backwards. A fence entry with no prior register row is a no-op on that node (tolerated for reordering/missing idempotency).

Applied host-side only; the cluster cache tracks the applied index.

Fields

lite_id: String

new_epoch: u64

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

SurrogateReserve

Reserve a disjoint batch of surrogates for one node (HiLo).

The carved [start, end) range is not carried in the entry: it is computed AT APPLY by advancing the cluster-wide surrogate global watermark on every node. Because every node applies the metadata log in the same order against an identical watermark, all nodes deterministically agree on which range this reservation carves — guaranteeing globally-unique, disjoint surrogate batches without any node ever minting a value another node also minted.

node_id + request_id identify the requesting node and the specific in-flight reservation so the owning node’s host-side applier can (a) install the carved batch locally and (b) fire the completion signal that unblocks the waiting allocation path. Only the owning node installs the batch; every other node merely advances the watermark so future reservations stay disjoint.

Fields

node_id: u64

request_id: u64

batch_size: 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 Eq for MetadataEntry

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

Equality operator ==.

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

Inequality operator !=.

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 StructuralPartialEq for MetadataEntry

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.