Malachi.
View Source
The control plane's metadata made authoritative via Raft, with a local read cache.
It pairs a Malachi.Cluster.MetadataServer (one ra cluster running Malachi.Metadata.apply/3)
with a local Malachi.Metadata materialized view. Mutations go through the Raft log (durable and
replicated); on commit, the very same command is applied to the local cache. Because
Malachi.Metadata.apply/3 is deterministic, the cache equals the replicated state, so reads are
served locally from the cache (no Raft round-trip on the hot path) with read-your-writes
consistency. One field is the exception: a registered segment's opened_at comes from the
timestamp the leader wrote into the log entry, which the reply does not carry, so the cache stamps
its own clock instead. The two differ by the commit latency, and the next refresh/1 (or the
broker's re-seed) installs the replicated value.
The cache is correct without refreshing as long as this process is the only writer (the
single-control-node topology). refresh/1 re-reads the replicated state for the multi-writer case
or after recovery.
ra must already be running (e.g. :ra.start_in/1), as with Malachi.Cluster.MetadataServer.
Summary
Functions
Stateless form: submit command to the Raft cluster server_id and apply it to the caller's
metadata cache, returning {metadata, reply} (the same shape as Malachi.Metadata.apply/3, so
it is a drop-in metadata command function). The caller threads the cache, which lets a single
operation perform several mutations with read-your-writes between them (e.g. a produce that opens
and seals a segment). On a transport failure the cache is left unchanged.
Submits command through the Raft log and, on commit, applies it to the local cache too.
Returns {reply, replicated_metadata}. reply is the machine reply (e.g. {:ok, root_id} or
{:error, :already_exists}), or {:error, reason} on a transport failure (cache unchanged).
Stops and deletes the underlying Raft cluster (removing its on-disk state).
The local metadata view, for reads (routing, segment lookup).
Re-reads the replicated state into the cache (multi-writer or post-recovery).
Starts (or joins) the Raft cluster cluster_name and seeds the local cache from it.
Types
@type t() :: %Malachi.Cluster.ReplicatedMetadata{ cache: Malachi.Metadata.t(), server_id: Malachi.Cluster.MetadataServer.server_id() }
Functions
@spec apply_command( Malachi.Cluster.MetadataServer.server_id(), Malachi.Metadata.t(), Malachi.Metadata.command() ) :: {Malachi.Metadata.t(), term()}
Stateless form: submit command to the Raft cluster server_id and apply it to the caller's
metadata cache, returning {metadata, reply} (the same shape as Malachi.Metadata.apply/3, so
it is a drop-in metadata command function). The caller threads the cache, which lets a single
operation perform several mutations with read-your-writes between them (e.g. a produce that opens
and seals a segment). On a transport failure the cache is left unchanged.
@spec command(t(), Malachi.Metadata.command()) :: {term(), t()}
Submits command through the Raft log and, on commit, applies it to the local cache too.
Returns {reply, replicated_metadata}. reply is the machine reply (e.g. {:ok, root_id} or
{:error, :already_exists}), or {:error, reason} on a transport failure (cache unchanged).
Stops and deletes the underlying Raft cluster (removing its on-disk state).
@spec metadata(t()) :: Malachi.Metadata.t()
The local metadata view, for reads (routing, segment lookup).
Re-reads the replicated state into the cache (multi-writer or post-recovery).
@spec start(Malachi.Cluster.MetadataServer.cluster_name()) :: {:ok, t()} | {:error, term()}
Starts (or joins) the Raft cluster cluster_name and seeds the local cache from it.