Runs N SlateDB databases ("shards") in one bucket: opens and closes them, turns SlateDB's writer fencing into supervised events, fans out durability notifications, and finds the shard for a key. It knows nothing about what the application stores; the application puts its own per-shard processes on top.

Define one module per cluster. use takes :otp_app and optionally :defaults, options that the application environment and start_link/1 can override (for example shard_children in a library that builds on this one). :settings maps are merged by key, in this order: defaults, application environment, then start_link/1 options. Each source overrides only the settings it contains.

defmodule MyApp.Cluster do
  use Slap.Cluster, otp_app: :my_app
end

# config/runtime.exs
config :my_app, MyApp.Cluster,
  store: {:url, "s3://bucket/prefix", aws_endpoint: "https://rustfs:9000"},
  shards: 64,
  settings: %{flush_interval: "10ms"},
  cache: [capacity_bytes: 2 * 1024 * 1024 * 1024],
  shard_children: {MyApp.ShardChildren, :child_specs, []}

and add MyApp.Cluster to the application's supervision tree. On start it checks that the store honours conditional writes (see Slap.SlateDB.probe_store/3), then the strategy opens the shards. With the default Slap.Cluster.Strategy.Local, startup attempts every shard before start_link/1 returns; failed opens retry in the background. With probe: :background, it can return before any shard opens. Use await_ready/2 before boot work that needs every shard.

Options

• :store - required. A store, as for Slap.SlateDB.open/2. Shard n is the database <path>/shard-00n in it.
• :shards - required. The number of shards. Fixed for the life of the data: shard_for/1 depends on it.
• :path - the path of the shards in the store (default "").
• :settings - SlateDB settings for every shard, as for Slap.SlateDB.open/2. SlateDB's flush_interval defaults to 100 ms, which can add up to 100 ms before a durable write's WAL flush begins.
• :cache - [capacity_bytes: n] for one block cache shared by this node's shards, :disabled, or nil (default) for SlateDB's own cache per shard.
• :merge_operator - as for Slap.SlateDB.open/2.
• :strategy - module or {module, opts} (default Slap.Cluster.Strategy.Local). See Slap.Cluster.Strategy.
• :shard_children - {mod, fun, args} or a 1-arity function, called with the shard's Slap.Cluster.Shard context (prepended to args), returning child specs to start for each shard. See "Shard children".
• :child_options - application settings in the shard context (default []). The cluster does not interpret them. When :shard_children is {module, function, args}, the module may define Slap.Cluster.ShardChildren.validate_child_options!/1 to reject invalid settings before startup.
• :probe - true (default) runs the conditional write probe before startup completes and fails startup if the probe fails. :background starts without shards and retries after 1 s, backing off to at most 30 s. Calls return {:error, :unassigned} until the probe passes and the shards open. false skips the probe.
• :close_timeout - ms to wait for a shard's database to close on stop (default 30,000).
• :lag_interval - ms between durability lag telemetry samples per shard (default 1,000).

Shard children

When a shard opens on a node, its children start under a supervisor, after the database is open. They get a Slap.Cluster.Shard context with the database handle, and name themselves with via/2.

When the shard stops (the cluster shuts down, the strategy moves it, or it is fenced), the children stop first, while the database is still open, then the database is closed. Children that need to fail in-flight work should trap exits and check shard_status/1 in terminate/2: :stopping or :fenced. This works for processes anywhere under the children, not only for the direct ones, which is why it is not the exit reason.

If the database process crashes, the shard stops, and the strategy decides whether to reopen it (handle_shard_down/3 with :crashed).

Durability

Writes go straight to the context's db. notify_when_durable/3 sends a message once a write's seq is durable. All notifications for a shard come from one process, which releases waiters lowest seq first, so a process that asks in seq order (as a single writer does) receives them in seq order. One SlateDB subscription per shard serves every waiter.

Telemetry

Events are sent under [:slap, :cluster, ...]: [:shard, :start | :stop | :fenced], [:durability, :lag] (%{lag: last_write_seq - durable_seq}, every :lag_interval), and [:probe]. Metadata includes :cluster and :shard.

Invalid configuration and call arguments raise. Routing failures return {:error, reason} from call/4 and lookup/2.