Dust SDK for Elixir

Reactive state sync for Elixir and Phoenix apps. Connect to a Dust store, read and write data, and subscribe to changes with glob-pattern callbacks.

Installation

# mix.exs
def deps do
  [{:dustlayer, "~> 0.1"}]
end

Setup

Generate the Dust module, config, and migration:

mix dust.install

Or configure manually:

# lib/my_app/dust.ex
defmodule MyApp.Dust do
  use Dust, otp_app: :my_app
end

# config/config.exs
config :my_app, MyApp.Dust,
  stores: ["org/store"],
  repo: MyApp.Repo

# lib/my_app/application.ex — add to children
MyApp.Dust

Usage

# Write
MyApp.Dust.put("org/store", "users/alice", %{name: "Alice", role: "admin"})

# Read (instant, from local cache)
{:ok, user} = MyApp.Dust.get("org/store", "users/alice")

# Delete
MyApp.Dust.delete("org/store", "users/alice")

# Merge (update children without replacing siblings)
MyApp.Dust.merge("org/store", "users/alice", %{"role" => "superadmin"})

# Enum (list matching entries)
entries = MyApp.Dust.enum("org/store", "users/*")

# Paginated enum
page = MyApp.Dust.enum("org/store", "users/**", limit: 20, order: :desc)

# Batch read
values = MyApp.Dust.get_many("org/store", ["users/alice", "users/bob"])

# Range read [from, to)
page = MyApp.Dust.range("org/store", "logs.2026-04-01", "logs.2026-04-30")

# Compare-and-swap
{:ok, entry} = MyApp.Dust.entry("org/store", "users/alice")
case MyApp.Dust.put("org/store", "users/alice", updated, if_match: entry.revision) do
  :ok -> :saved
  {:error, :conflict} -> :retry
end

# Put-new — claim a key only if it does not already exist (race-free).
# Returns {:error, :exists} if another writer got there first.
case MyApp.Dust.put("org/store", "locks/poll", node_id, if_absent: true) do
  {:ok, _seq} -> :i_won_the_claim
  {:error, :exists} -> :someone_else_holds_it
end

# Freshness — entry.synced_at is the local wall-clock (unix epoch ms) when
# this node last wrote the row from a sync event. Use it to reason about how
# stale the local mirror is (nil for subtree-assembled entries).
{:ok, entry} = MyApp.Dust.entry("org/store", "users/alice")
age_ms = System.system_time(:millisecond) - entry.synced_at

# Subscribe to changes
MyApp.Dust.on("org/store", "users/*", fn event ->
  IO.puts("#{event.path} changed: #{inspect(event.value)}")
end)

Authentication and Capabilities

Tokens need entries:read to join and read a store. Add entries:write for writes, leases, rollback, and single_flight.

status = MyApp.Dust.status("org/store")
# %{
#   connection: :connected,
#   permissions: %{read: true, write: false},
#   scopes: ["entries:read"],
#   store_access: %{mode: :selected, store_ids: ["..."]}
# }

case MyApp.Dust.lease("org/store", "jobs/nightly") do
  {:error, {:missing_scope, "entries:write", message}} ->
    Logger.warning(message)

  other ->
    other
end

Coordination: leases & single-flight

single_flight computes an expensive thing once across your fleet and shares the result — replacing hand-rolled "check S3, maybe do the work, coordinate with other nodes" schemes. It is at-least-once while Dust is reachable, not exactly-once: fun must be idempotent and publish a small pointer (keep the bytes in S3/your DB).

# Done-forever (presence mode): OCR a PDF once per content hash.
{:ok, %Dust.Flight{value: manifest}} =
  MyApp.Dust.single_flight("org/store", "artifacts/#{hash}", fn _lease ->
    {:ok, keys} = download_and_ocr(hash)   # bytes stay in R2
    {:publish, %{"manifest" => keys}}      # publish a small pointer
  end, lease_ttl: :timer.minutes(20))      # heartbeat-renewed while it runs

# Fresh-within-a-window (freshness mode): poll a Facebook page at most hourly,
# shared across prod + staging. The value carries its own timestamp.
MyApp.Dust.single_flight("org/store", "pages/#{slug}", fn _lease ->
  {:publish, %{"posts" => poll(slug), "fetched_at" => System.system_time(:millisecond)}}
end,
  fresh?: fn v -> System.system_time(:millisecond) - v["fetched_at"] < :timer.hours(1) end,
  lease_ttl: :timer.minutes(5),
  on_unavailable: :run_local)              # never block; pay-once-per-node when Dust is down

fun returns {:publish, value} (store + share it) or {:abort, reason} (release the lease, publish nothing). Prefer {:abort, _} over raising for transient failures — abort releases immediately (waiters re-elect at once); a raised fun only frees the lease at lease_ttl. Map definitive negatives to {:publish} (so the freshness window holds) and transient ones to {:abort} (so they aren't cached).

The low-level lease underneath is also available directly:

case MyApp.Dust.lease("org/store", "jobs/nightly", ttl_ms: 60_000) do
  {:ok, lease} ->
    do_work()
    MyApp.Dust.put("org/store", "jobs/nightly/result", result, fence: lease)
    MyApp.Dust.release("org/store", lease)

  {:error, :held} -> :someone_else_has_it
end

single_flight uses the same lease/write path, so it also requires entries:write. Missing write scope returns {:error, {:missing_scope, "entries:write", message}}; it does not trigger the on_unavailable: :run_local fallback.

fence: lease rejects a write ({:error, :fenced}) if the lease was lost mid-run, so a stale holder can't clobber a newer one's result.

Upgrading

`synced_at` cache column

The cache row gained a synced_at column (local wall-clock, unix epoch ms, surfaced as Dust.Entry.synced_at). Fresh installs get it automatically. Existing adopters must add the column before upgrading — generate a migration and add:

alter table(:dust_cache) do
  add :synced_at, :bigint
end

The column is nullable, so rows written before the upgrade read back synced_at: nil.

Full Documentation

See the main Dust README for the complete API reference, type system (counters, sets, decimals, files), Phoenix PubSub integration, declarative subscribers, audit log, and testing helpers.

Next Page → Changelog