examples/server.exs
serves the Streams and KV HTTP APIs from one listener. It does not
authenticate requests. Use it to try the HTTP APIs.
Requires Elixir 1.18 or later and Erlang/OTP 26.2 or later. The SlateDB NIF is precompiled for macOS and Linux (glibc and musl) on x86_64 and arm64. The first run downloads it and compiles the dependencies; later runs reuse them.
Download the script and run it:
curl -fsSLo server.exs https://raw.githubusercontent.com/mjrusso/slap/main/slap/examples/server.exs
elixir server.exs
The script installs slap and bandit with Mix.install. The server
listens on http://127.0.0.1:4437, with Streams under /v1/stream/ and KV
under /v1/kv/. GET /health answers 200 once the listener is up. By
default the data is in memory and is lost when the server stops.
Streams
With the server running, use another terminal for the HTTP examples below. Create a JSON stream, then append to it. The JSON extension stores each element of an appended array as a separate message.
curl -X PUT -H 'Content-Type: application/json' http://localhost:4437/v1/stream/events
curl -X POST -H 'Content-Type: application/json' \
--data '[{"type":"created","id":1},{"type":"updated","id":1}]' \
http://localhost:4437/v1/stream/events
Read the stream. The JSON messages are returned as an array.
curl 'http://localhost:4437/v1/stream/events?offset=-1'
Fork the stream at its current end, then append to the fork. The source still contains only the first two messages.
curl -X PUT -H 'Content-Type: application/json' \
-H 'Stream-Forked-From: /v1/stream/events' \
http://localhost:4437/v1/stream/events-fork
curl -X POST -H 'Content-Type: application/json' --data '{"type":"deleted","id":1}' \
http://localhost:4437/v1/stream/events-fork
curl 'http://localhost:4437/v1/stream/events-fork?offset=-1'
curl 'http://localhost:4437/v1/stream/events?offset=-1'
KV
Set three rows, get one, then scan a range of keys in the
people partition. The range stops before c.
curl -X PUT --data-binary 'Ada' http://localhost:4437/v1/kv/people/a
curl -X PUT --data-binary 'Grace' http://localhost:4437/v1/kv/people/b
curl -X PUT --data-binary 'Katherine' http://localhost:4437/v1/kv/people/c
curl http://localhost:4437/v1/kv/people/a
curl 'http://localhost:4437/v1/kv/people?gte=a<=c'
The scan returns JSON with keys and values encoded as unpadded base64url.
Storage
--store local:DIR keeps the data in a local directory:
elixir server.exs --store local:./data
For S3, create the bucket and set AWS_REGION and credentials (such as
AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY) in the server's environment.
Start the server with:
elixir server.exs --store s3:s3://my-bucket/my-app
See choosing the shard count for local-storage guidance and running another cluster on the same store before running a script against a store an application is using. Existing data requires its original shard count.
Use --port PORT to change the port. For shard counts, placement or other
service settings, edit the options passed to Slap in the script. See
Slap for the available options.
Inspection
Slap Inspect requires a named Erlang node. Start the script with a name:
elixir --sname slap server.exs
Then connect with slap-inspect --node slap@HOST. See the
inspector guide
for details.
Serving the APIs from an application
Add {:bandit, "~> 1.12"} alongside slap in your application's
dependencies, then supervise Slap and a listener for Slap.Router:
children = [
{Slap, store: {:url, "s3://bucket/db"}, streams: [shards: 8], kv: [shards: 4]},
{Bandit, plug: {Slap.Router, streams: [], kv: []}, port: 4437, ip: :loopback}
]Slap.Router takes each service's router options (see
Slap.Streams.HTTP.Router and Slap.KV.HTTP.Router). Include only the
services the listener should serve. You can also mount an individual
service's router directly.
Put authentication and authorization in front of the router.
ip: :loopback accepts connections from this machine only; without ip:,
Bandit listens on every interface.
Migrating from Slap.Server
Slap.Server combined service startup and the HTTP listener. Replace it
with the two children shown above:
- Add
banditto your dependencies. Move:store,:streams,:kv,:strategyand:peersfromSlap.ServertoSlap. - Move
:portand:ipto the Bandit child. Move any:httpoptions nested under:streamsor:kvto that service's options inSlap.Router. - Before starting against existing data, preserve each cluster's path, shard count and child options as described below.
The old server always used the paths "streams" and "kv". Each cluster
used the :shards and :child_options passed directly to Slap.Server,
defaulting to 8 shards and []. It ignored these three keys in
config :slap_streams, Slap.Streams.Cluster and
config :slap_kv, Slap.KV.Cluster.
Slap uses application-configured values for keys omitted from streams:
or kv:. Set path:, shards: and child_options: explicitly in each
service's options to preserve the old values, or update its application
config to match. The path must still point to the existing data, and the
shard count must match the one recorded in the store.
If you used the installed slap.server Mix task, switch to running
examples/server.exs with elixir. The script uses the default paths and 8
shards per cluster. If you started the task with --streams-shards or
--kv-shards, set the same shards: in the script. The Mix task remains
available in this repository for development.
From a checkout
This repository's tests and benchmarks use the slap.server Mix task,
which takes server options as flags. It is available in the checkout's
:dev and :test environments. See the development guide.