Getting started with Slap

Copy Markdown View Source
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