Mix.install([{:slap, "~> 0.7.1"}])About this notebook
This notebook has a short example for each Slap API: SlateDB, Streams, snapshot logs, Yjs, KV and files. It requires Elixir 1.18 or later and Erlang/OTP 26.2 or later. Run the cells in order. They keep data in memory, so it is lost when the runtime stops.
To run it without Livebook, paste the cells into IEx started with
iex -e 'Mix.install([{:slap, "~> 0.7.1"}])'.
SlateDB
Open a database, write a value and wait until it is durable, read it back, and close the database:
{:ok, db} = Slap.SlateDB.open("example", store: :memory)
{:ok, _seq} = Slap.SlateDB.put(db, "user:1", "Ada", await_durable: true)
{:ok, "Ada"} = Slap.SlateDB.get(db, "user:1")
:ok = Slap.SlateDB.close(db)Start the services
Slap.start_link/1 starts a supervisor, which starts each service listed
in the options: here streams, yjs, kv and files. Yjs stores its
documents in Streams, and Files stores its records in KV. The Streams and KV
clusters get one shard each:
{:ok, _} =
Slap.start_link(
store: :memory,
streams: [shards: 1],
yjs: [],
kv: [shards: 1],
files: []
)Run this cell only once: running it again fails with
{:error, {:already_started, pid}}. To start over, restart the runtime
from Livebook's Runtime panel and run the cells in order. In IEx, start a
new session.
The architecture guide shows
what Slap starts and how the packages depend on each other.
Streams
Create, append to, and read a stream:
{:ok, :created, _} = Slap.Streams.create("/events", content_type: "text/plain")
{:ok, %{result: :appended}} = Slap.Streams.append("/events", "created")
{:ok, %{messages: [{0, "created"}]}} = Slap.Streams.read("/events", 0)Snapshot logs
A snapshot log is an append-only log, stored in Streams, whose prefix can be replaced by a snapshot. A snapshot at an offset must contain the effects of every entry before that offset; the log cannot check this. Publishing the snapshot trims those entries:
base = "/v1/stream/examples/log"
{:ok, _} = Slap.SnapshotLog.append(base, "one")
{:ok, %{entries: ["one"], offset: offset}} = Slap.SnapshotLog.next(base, 0, wait: 0)
:ok = Slap.SnapshotLog.snapshot(base, offset, "state after one")
{:reset, %{snapshot: "state after one", offset: ^offset}} = Slap.SnapshotLog.next(base, nil)A new consumer calls next(base, nil) to get the current snapshot and the
offset to read later entries from.
Yjs
Define a document server module, join a document, and edit it with y_ex:
defmodule Example.DocServer do
use Slap.Yjs.DocServer
end
{:ok, server} = Slap.Yjs.Docs.join(Example.DocServer, {"examples", "doc-1"})
{:ok, doc} = Slap.Yjs.DocServer.doc(server, 5_000)
text = Yex.Doc.get_text(doc, "text")
:ok = Yex.Text.insert(text, 0, "hello")Call sync/2 to wait for the document's buffered changes to be stored, then
read the text:
:ok = Slap.Yjs.DocServer.sync(server, 5_000)
"hello" = Yex.Text.to_string(text)KV
Write a row only if it does not exist yet, then read it:
{:ok, version} = Slap.KV.put("users", "42", "Ada", if_version: :absent)
{:ok, %{value: "Ada", version: ^version}} = Slap.KV.get("users", "42")A conditional write fails if the version it names is no longer current. The error includes the current version:
{:ok, _} = Slap.KV.put("users", "42", "Grace", if_version: version)
{:error, {:conflict, _current}} = Slap.KV.put("users", "42", "Katherine", if_version: version)Files
Files use the KV cluster. Small bodies are stored in KV records:
ref = {"examples", "hello.txt"}
{:ok, %{storage: :inline}} = Slap.Files.put(ref, "hello", if_version: :absent)
{:ok, "hello"} = Slap.Files.read(ref)Next steps
- For production configuration, see the
Slapmodule and each package's guide, linked from the package overview. - To serve the HTTP APIs, see the standalone server guide.