Skip to content

About

Reference implementation of the Selvage Session Protocol: the server, the Rust client and the conformance harness.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

selvage-reference-server

A Rust workspace for the Selvage Session Protocol. selvaged is a memory-only reference server that seats peers in a room and relays sealed frames it cannot read; the client library the protocol is proved with lives beside it. This repository is the protocol's reference implementation. A client with a host-run relay does not need this process for its own room. With the editor clients documented in docs/rooms.md, the host starts selvaged separately or joins an existing server, then gives the editor its address. selvaged is kept as the conformance server the wire vectors replay against and as an optional standalone relay for testing. See the specification's docs/peer-host-relay.md; guests reach a host-run relay over Tailscale or a LAN.

Get it working

The published image is the server alone, and a server alone is enough for a client to join a room; the page is a second container, and the pair is printed by the landing page's Run card, which owns the reader-facing commands: the three steps it prints name the repositories bare, which docker reads as :latest — the tag the release publishes — and it prints no teardown, so stopping the pair is docker stop or docker rm -f, a step it leaves to the reader.

docker rm -f selvaged-solo 2>/dev/null
docker run -d --rm --name selvaged-solo -p 127.0.0.1:8081:8080 \
  ghcr.io/selvage-protocol/selvaged:latest

That is re-runnable: the removal clears the name a previous run left, and --rm takes the container with it when it stops. Stopping it later, and taking it with its logs, is a command of its own:

docker rm -f selvaged-solo

The name and the host port above are this example's own, so it and the card's pair can be up at once: the card's server runs as selvaged and its page publishes 8080, so stopping either pair leaves the other's container alone. A client reaches this container at ws://127.0.0.1:8081 — the host port the mapping above publishes. Both GHCR packages are public, so a pull needs no account and no docker login. Deploying has the other addresses a client might be pointed at, and why they do not answer.

From a checkout

With Nix, cargo and rustc come from the flake, so run cargo through the dev shell:

nix develop . -c cargo run -p selvaged -- --listen 127.0.0.1:8080

Without Nix, install Rust via rustup (any recent stable works), and the same cargo run needs no other setup. For a binary to keep, build it release and run that:

nix develop . -c cargo build --release --locked -p selvaged
./target/release/selvaged --listen 127.0.0.1:8080

Build the image from this checkout

The image is the server alone, on one port:

docker buildx build --load -t selvaged:local .
docker run --rm -p 127.0.0.1:8080:8080 selvaged:local

docker compose up builds the same Dockerfile through compose.yaml, which runs it beside the published page image, both read-only with every capability dropped. This is the route for an image you are changing, or one built from your own checkout.

To serve a page from that container, mount a directory and name it with --serve-page: the image carries none, and its own command passes no such flag.

docker run --rm -p 127.0.0.1:8080:8080 -v "$PWD/page:/page:ro" \
  selvaged:local --listen 0.0.0.0:8080 --serve-page /page

Nix

The flake's default package is selvaged, so nix run builds the binary and starts it with the same flags:

nix run . -- --listen 0.0.0.0:8080

Commands

selvaged is one binary with no configuration file, and the flags below are the whole of its surface:

usage: selvaged [--listen ADDR] [--room-grace-ms MS] [--serve-page DIR]
                [--max-connections N] [--max-rooms N] [--max-peers-per-room N]
                [--outbound-queue-bytes N] [--max-envelope-bytes N]
                [--inbound-bytes-per-sec N] [--inbound-burst-bytes N]

What it prints, and its flags has the startup line, every flag with its default, and which of those bounds are per process and which are per connection.

--help prints the usage line, a short description of the server, and every flag with its default. --version prints selvaged/<version>.

More

Licence

The server is FSL-1.1-MIT, source-available and not open source; the workspace default is MIT OR Apache-2.0, which covers crates/protocol, crates/client and crates/harness, and vectors/ is vendored from the specification repository under CC-BY-4.0. Licence has the terms, the paths and what the published image carries.

About

Reference implementation of the Selvage Session Protocol: the server, the Rust client and the conformance harness.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages