brazier/presence

Types

Presence

opaque </>

A running tracker.

pub opaque type Presence(meta)

PresenceConfig

opaque </>

How to build a tracker. Use new and the setters.

pub opaque type PresenceConfig(meta)

PresenceError

</>

pub type PresenceError {
  MetaTooLarge(bytes: Int)
  PresenceLimitExceeded(limit: String)
  InvalidTopic(String)
  InvalidKey(String)
  AlreadyTracked
  NotTracked
  TrackerDown
  TrackerTimeout
  InvalidConfig(String)
  StartFailed(String)
  StopFailed(String)
  MetaDecodeFailed(String)
  InvalidMessage
  PubSubFailed(String)
}

Constructors

```
MetaTooLarge(bytes: Int)
```
The encoded meta is larger than max_meta_bytes.
```
PresenceLimitExceeded(limit: String)
```
A limit was reached: max_topics_per_pid or max_entries_per_shard.
```
InvalidTopic(String)
```
The topic is empty or too long for this tracker’s diff topics.
```
InvalidKey(String)
```
The key is empty or longer than 255 bytes.
```
AlreadyTracked
```
The calling process already tracks this key on this topic.
```
NotTracked
```
The calling process does not track this key on this topic.
```
TrackerDown
```
The tracker (or the shard for this topic) is not running.
```
TrackerTimeout
```
The shard did not answer in time.
```
InvalidConfig(String)
```
The configuration is invalid.
```
StartFailed(String)
```
The tracker did not start.
```
StopFailed(String)
```
The tracker did not stop within the deadline.
```
MetaDecodeFailed(String)
```
A meta does not decode with the tracker’s decoder.
```
InvalidMessage
```
The message given to decode_diff is not a diff of this tracker.
```
PubSubFailed(String)
```
PubSub refused a diff subscription.

Tracking

</>

What a session is present as: key on topic, with meta. A brazier.presence app computes these from its state after every update.

pub type Tracking(meta) {
  Tracking(topic: String, key: String, meta: meta)
}

Constructors

Tracking(topic: String, key: String, meta: meta)

Values

clock_sample_periods

</>

pub fn clock_sample_periods(
  config: PresenceConfig(m),
  periods: Int,
) -> PresenceConfig(m)

Heartbeats between checks of which peers are ahead.

decode_diff

</>

pub fn decode_diff(
  presence: Presence(meta),
  message: dynamic.Dynamic,
) -> Result(sync.Diff(meta), PresenceError)

Decode the message part of a diff delivery.

diff_topic

</>

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

The PubSub topic diffs for topic are delivered on.

down_period

</>

pub fn down_period(
  config: PresenceConfig(m),
  ms: Int,
) -> PresenceConfig(m)

Silence after which a peer is down. Longer than the keepalive interval, broadcast_period × (max_silent_periods + 1), or idle peers would go down between keepalives.

get_by_key

</>

pub fn get_by_key(
  presence: Presence(meta),
  topic: String,
  key: String,
) -> Result(sync.Entry(meta), PresenceError)

What is tracked under key on topic. Error(NotTracked) if nothing.

handle

</>

pub fn handle(
  config: PresenceConfig(meta),
) -> Result(Presence(meta), PresenceError)

The handle of the tracker config starts, for a tracker started with supervised. It does not check that the tracker is running: calls return TrackerDown until it is.

list

</>

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

Everything tracked on topic on reachable nodes, by key.

max_delta_sizes

</>

pub fn max_delta_sizes(
  config: PresenceConfig(m),
  sizes: List(Int),
) -> PresenceConfig(m)

Sizes of the delta generations kept for peers that fall behind: positive and strictly increasing.

max_entries_per_shard

</>

pub fn max_entries_per_shard(
  config: PresenceConfig(m),
  limit: Int,
) -> PresenceConfig(m)

Most entries one shard holds, from every node, before it refuses tracks.

max_name_bytes

</>

pub const max_name_bytes: Int

Upper bound for a tracker name, in bytes.

max_silent_periods

</>

pub fn max_silent_periods(
  config: PresenceConfig(m),
  periods: Int,
) -> PresenceConfig(m)

Heartbeats without changes before an empty keepalive is sent.

max_topic_bytes

</>

pub fn max_topic_bytes(presence: Presence(meta)) -> Int

The largest topic this tracker accepts: its diff topic (presence:<name>:<topic>) must fit PubSub’s 255 bytes.

max_topics_per_pid

</>

pub fn max_topics_per_pid(
  config: PresenceConfig(m),
  limit: Int,
) -> PresenceConfig(m)

Most entries one process may track on one shard.

max_transfer_entries

</>

pub fn max_transfer_entries(
  config: PresenceConfig(m),
  limit: Int,
) -> PresenceConfig(m)

Most entries a shard accepts in one transfer from a peer. A larger one is rejected and logged, and requested again at the next clock sample.

new

</>

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

A tracker named name (1 to 32 bytes of a-z, 0-9 and _) whose metas are encoded with encode and read back with decoder.

Defaults, from Phoenix.Tracker: one shard, heartbeat every 1500ms, an empty heartbeat after 10 silent periods, down after 30s, permanently down after 20 minutes, clocks sampled every 2 heartbeats, delta generations of 100, 1000 and 10000. Brazier’s limits: 1024-byte metas, 100 entries per process per shard, 1,000,000 entries per shard and transfers of at most 1,000,000 entries.

permdown_period

</>

pub fn permdown_period(
  config: PresenceConfig(m),
  ms: Int,
) -> PresenceConfig(m)

Silence after which a peer’s data is dropped. More than down_period.

pool_size

</>

pub fn pool_size(
  config: PresenceConfig(m),
  size: Int,
) -> PresenceConfig(m)

Shards per node. Must be the same on every node.

replicas

</>

pub fn replicas(
  presence: Presence(meta),
  topic: String,
) -> Result(List(#(String, ReplicaStatus)), PresenceError)

The peers the shard for topic knows, by node name.

running

</>

pub fn running(presence: Presence(meta)) -> Bool

Whether the tracker runs on this node (its supervisor is registered). A running tracker may still be restarting a shard: calls for that shard’s topics return TrackerDown meanwhile.

shard_pid

</>

pub fn shard_pid(
  presence: Presence(meta),
  topic: String,
) -> Result(process.Pid, PresenceError)

The shard process for topic. Tracked processes monitor it: if it dies, their entries are gone and they must track again.

start

</>

pub fn start(
  config: PresenceConfig(meta),
) -> Result(Presence(meta), PresenceError)

Start a tracker on this node, unlinked from the caller. PubSub must be running.

stop

</>

pub fn stop(
  presence: Presence(meta),
) -> Result(Nil, PresenceError)

Stop a tracker started with start. Its shards tell their peers, which drop this node’s entries at once.

</>

pub fn subscribe(
  presence: Presence(meta),
  topic: String,
) -> Result(Nil, PresenceError)

Receive this node’s diffs for topic as {brazier_pubsub, diff_topic(presence, topic), Diff}.

supervised

</>

pub fn supervised(
  config: PresenceConfig(meta),
) -> Result(
  supervision.ChildSpecification(Presence(meta)),
  PresenceError,
)

A child specification that starts the tracker linked to a supervisor. Get the handle to use it with handle.

track

</>

pub fn track(
  presence: Presence(meta),
  topic: String,
  key: String,
  meta: meta,
) -> Result(String, PresenceError)

Track the calling process under key on topic. Returns the meta’s ref.

unsubscribe

</>

pub fn unsubscribe(
  presence: Presence(meta),
  topic: String,
) -> Result(Nil, PresenceError)

untrack

</>

pub fn untrack(
  presence: Presence(meta),
  topic: String,
  key: String,
) -> Result(Nil, PresenceError)

Stop tracking the calling process under key on topic.

untrack_all

</>

pub fn untrack_all(
  presence: Presence(meta),
) -> Result(Nil, PresenceError)

Stop tracking the calling process everywhere on this tracker.

update

</>

pub fn update(
  presence: Presence(meta),
  topic: String,
  key: String,
  meta: meta,
) -> Result(String, PresenceError)

Replace the meta the calling process tracks under key on topic. Returns the new ref; the old one becomes ref_prev.

validate_config

</>

pub fn validate_config(
  config: PresenceConfig(m),
) -> Result(PresenceConfig(m), PresenceError)

Check a configuration.