# `Slap`
[🔗](https://github.com/mjrusso/slap/blob/slap-v0.7.1/slap/lib/slap.ex#L1)

Runs the Slap services under one supervisor: the Streams cluster, the
KV cluster, and the services built on them.

Add `{Slap, opts}` to a supervision tree, or call `start_link/1`:

    children = [
      {Slap,
       store: {:url, "s3://bucket/prefix"},
       streams: [shards: 8],
       kv: [shards: 8],
       files: [],
       yjs: []}
    ]

Each service is started when its key is present, with a keyword list of
its options (`[]` for the defaults). At least one cluster is required.

  * `:store` - required, as for `Slap.SlateDB.open/2`: for example
    `:memory`, `{:local, dir}` or `{:url, "s3://bucket/prefix"}`. File
    objects default to `files/` in it; inline bodies are stored in KV.
  * `:streams` - starts `Slap.Streams.Cluster`: `[shards: n, path: path,
    settings: settings, child_options: options]`. A key left out comes
    from the cluster's application config (`config :slap_streams,
    Slap.Streams.Cluster`), and otherwise `:shards` defaults to 8 and
    `:path` to `"streams"`. The shard count is fixed for the life of the
    data. See `Slap.Streams.Cluster` for `child_options:`. Snapshot logs
    (`Slap.SnapshotLog`) need only this cluster.
  * `:kv` - starts `Slap.KV.Cluster`, with the same keys (`config :slap_kv,
    Slap.KV.Cluster`; by default 8 shards under `"kv"`). See
    `Slap.KV.Cluster` for `child_options:`.
  * `:files` - starts `Slap.Files` after the KV cluster; requires `:kv`.
    Takes `Slap.Files`' options except `:cluster`. `:store` defaults to
    the store above.
  * `:yjs` - starts `Slap.Yjs.Docs` after the Streams cluster; requires
    `:streams`. Takes its options except `:cluster`.
  * `:strategy` - `module` or `{module, opts}`, a `Slap.Cluster.Strategy`
    for both clusters, to run as one node of a cluster. The nodes must be
    connected with distributed Erlang; see `:peers`. Without it, or a
    strategy in a cluster's application config, every shard is on this
    node (`Slap.Cluster.Strategy.Local`).
  * `:peers` - a fixed list of node names to stay connected to, through
    `Slap.Cluster.Peers`. Omit it on one node, or if something else
    connects the nodes, such as libcluster.

`:settings` merge with each cluster's defaults, which set
`flush_interval` to 10 ms.

Run one `Slap` per VM: it starts the built-in clusters, and a VM runs at
most one Streams cluster and one KV cluster. Its supervisor is registered
as `Slap`, so a second start returns `{:error, {:already_started, pid}}`.
An application that defines its own cluster modules
(`use Slap.Streams.Cluster`) supervises them and the services on them
directly.

Each cluster and its dependent services run in a separate `:rest_for_one`
branch: a cluster restart also restarts its services. Repeated service
failures can restart the cluster; repeated branch failures stop `Slap`.
The supervisors use OTP's default restart limits.

`Slap` starts no HTTP listener. `Slap.Router` serves the Streams and KV
HTTP APIs as one Plug.

Invalid option keys or service combinations raise `ArgumentError` when
building the child spec or calling `start_link/1`. Cluster values,
including `:settings`, are checked at startup. A top-level `nil` is
treated as missing.

# `start_link`

```elixir
@spec start_link(keyword()) :: Supervisor.on_start()
```

Starts a supervisor that runs the services listed in `opts`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
