howdy/websocket/presence

Who is on a topic right now, across every connected node.

A process tracks itself on a topic under a key, usually a user id, with a meta value describing it, such as a name or a status. One key can be tracked by several processes, as when someone has the page open in two tabs: the key stays present until the last of them leaves.

import howdy/websocket
import howdy/websocket/presence

let users = presence.new("users", encode: user_to_json, decoder: user_decoder())

websocket.new(fn(socket) {
  presence.track(users, process.self(), "room:" <> room, key: user.id, meta: user)
  presence.watch(users, socket, "room:" <> room)
  Nil
})

A watching socket is sent the topic’s presences as soon as it watches, then a diff of joins and leaves after every change. The browser keeps the list with the client script served by client:

import { Presence } from "/howdy/presence.js"
const users = new Presence({ name: "users", topic: "room:lobby" })
users.onSync((list) => render(list))
socket.onmessage = (event) => {
  const message = JSON.parse(event.data)
  if (users.receive(message)) return
  // the app's own messages
}

Server code, such as a live view, can subscribe instead and get the same diffs as messages.

A presence lasts as long as the process that tracked it. Nothing needs cleaning up when a socket closes or crashes. Each node runs a tracker that owns its own processes’ presences and shares them with the trackers on the other nodes, so list answers for the whole cluster from local memory. When a node goes away, its presences leave on the others; if it comes back, they rejoin. A tracker that crashes forgets its node’s presences, as their processes are not told to track again.

Metas travel as JSON, so a node running different code can still read them: a meta that decoder cannot read is skipped by list and subscribe, and passed to the browser as it is.

pub type Diff(meta) {
  Diff(
    topic: String,
    joins: List(Entry(meta)),
    leaves: List(Entry(meta)),
  )
}

pub type Entry(meta) {
  Entry(key: String, metas: List(meta))
}

pub opaque type Presence(meta)

pub fn client(at path: String) -> controller.Builder(Nil)

pub fn client_script() -> String

pub fn count(presence: Presence(meta), topic: String) -> Int

pub fn list(
  presence: Presence(meta),
  topic: String,
) -> List(Entry(meta))

pub fn new(
  name: String,
  encode encode: fn(meta) -> json.Json,
  decoder decoder: decode.Decoder(meta),
) -> Presence(meta)

pub fn subscribe(
  presence: Presence(meta),
  topic: String,
  subject: process.Subject(msg),
  map: fn(Diff(meta)) -> msg,
) -> List(Entry(meta))

pub fn track(
  presence: Presence(meta),
  pid: process.Pid,
  topic: String,
  key key: String,
  meta meta: meta,
) -> Nil

pub fn untrack(
  presence: Presence(meta),
  pid: process.Pid,
  topic: String,
  key key: String,
) -> Nil

pub fn watch(
  presence: Presence(meta),
  socket: websocket.Socket(msg),
  topic: String,
) -> Nil