spillway

Typed protocol logic for Gleam and the BEAM

Keep Fluid protocol state explicit.

You keep your server. Spillway decides how Fluid protocol messages are ordered, accepted, rejected, and validated.

Start with Gleam
current_snmonotonic
joinscope + tenantopCSN -> SNsummaryack / nack
  1. connectnegotiate features
  2. submit opassign sequence
  3. summarizetrack minimum sequence

Small enough to own one layer.

  1. AboveTransport + persistence

    Your server owns sockets, storage, token issuance, and document lifetime.

  2. HereSpillway protocol core

    Pure Gleam functions for sequencing, feature negotiation, signal routing, summaries, nacks, and JWT claim validation.

  3. BelowFluid clients

    Clients receive ordered protocol messages while your server keeps its own runtime shape.

A narrow layer with explicit decisions.

Connection rules, ordered operations, and protocol responses stay testable as pure Gleam functions.

Connection checks

Validate tenant, document, expiration, and scope, then negotiate protocol versions and feature flags.

Ordered operations

Track connected clients, client sequence numbers, reference sequence numbers, and minimum sequence progression.

Protocol responses

Build nacks, summary acks, summary nacks, sequenced ops, and routed signals from typed constructors.

The public API names the state changes.

Spillway keeps protocol decisions explicit: clients join, ops receive sequence numbers, claims are checked, and invalid operations become protocol nacks.

CSN
client sequence number
SN
server sequence number
RSN
reference sequence number
MSN
minimum sequence number
sequencing.gleam
import spillway
import spillway/sequencing


let state =
  spillway.new_sequence_state()
  |> spillway.client_join("client-7", 0)


let assert sequencing.SequenceOk(next_state, assigned_sn, minimum_sn) =
  spillway.assign_sequence_number(state, "client-7", 1, 0)


#(next_state, assigned_sn, minimum_sn)

Proof before adoption.

  • stdlib + gleam_jsonSmall dependency surface; transport stays outside the library.
  • Pure functionsSequencing, feature negotiation, signal routing, and validation remain testable.
  • Protocol nacksInvalid CSN, RSN, unknown clients, and missing scopes become typed failures.
  • Summary pathsSummary validation plus ack/nack builders are part of the protocol surface.

HexDocs package docsTests on GitHubBrowse source

Add the protocol core, not the server.

Spillway is intentionally small: Gleam stdlib plus JSON, ready to sit under a server layer that owns sockets, persistence, and deployment policy. Install it where protocol decisions need to stay explicit.

terminal
gleam add spillway
Check HexDocs package docs