Skip to content

Config options

This page is generated from the doc comments in the source. For the full types, see the API reference.

import { createServer } from 'shoehive/server';
createServer(options: ServerOptions): ShoehiveServer
Option Type Default Description
games readonly AnyGame[] required The games this server hosts. Each game id must be unique.
auth AuthHook Custom auth. Without it every connection is a guest with a resume token (ADR 0010).
secret string | readonly string[] SHOEHIVE_SECRET HMAC secrets for resume tokens: the first signs, all verify.
store Store an in-memory store Where tables are persisted.
wallet Wallet Money backend (ADR 0007). Exposed to game code from Phase 4.
logger Logger consoleLogger (silentLogger turns logging off) Where the server logs.
path string /shoehive WebSocket path.
origins readonly string[] any origin, except in production with an auth hook, where only same-origin pages may connect (a browser sends a site's cookies with a cross-site WebSocket upgrade, so any web page could otherwise connect as a signed-in visitor) Allowed Origin headers for browser connections, for example ['https://play.example.com']; ['*'] allows any. Clients that send no Origin (servers, native apps) are always allowed.
unknownUpgrades 'ignore' | 'refuse' | { refuseAfterMs: number } What attach() does with WebSocket upgrades for paths Shoehive does not serve. 'ignore' (default) leaves them to the HTTP server's other upgrade listeners. 'refuse' answers HTTP 404 and closes the socket at once: use it when Shoehive is the only WebSocket handler on that server. { refuseAfterMs } answers 404 after that long unless another listener has written to or closed the socket by then, which keeps other handlers working while still closing sockets nobody takes. listen() owns its HTTP server and always refuses at once.
reconnectGraceMs number 60 000 ms How long a seat is held after its player disconnects.
resumeTokenTtlMs number 7 days Resume token lifetime, renewed on every connect.
idleTableMs number 10 minutes Close tables nobody has joined and nobody is seated at after this long.
snapshotEvery number 100 Write a snapshot every N log entries (also on phase change and end).
limits ServerLimits Per-connection limits: see Limits.
clock Clock the system clock Time source for timers and timestamps. Tests pass a fake.
dev boolean NODE_ENV !== 'production' Dev checks in table runtimes.
devtools DevtoolsOption off The inspector (shoehive/devtools, ADR 0011). Off by default. true enables it outside production with a generated token, and the inspector URL is logged once at startup. In production it needs { enabled: true, allowInProduction: true, token } (a token of at least 32 characters), otherwise createServer throws.

Passed as limits. Every limit applies per connection.

Option Type Default Description
maxMessageBytes number 65 536 Largest accepted message, in bytes.
messagesPerSecond number 20 Sustained messages per second per connection.
burst number 40 Burst size of the per-connection token bucket.
maxInFlight number 32 Requests awaiting their ack per connection.
helloTimeoutMs number 10 000 ms Time a new connection has to send hello.
heartbeatMs number 15 000 ms WebSocket ping interval.
maxBufferedBytes number 8 MiB Bytes a connection may have queued but not yet sent before it is dropped (a reader that stopped reading). Table and lobby patches already pause at 1 MiB (backpressure); this is the hard cap for everything else.
maxTablesPerPlayer number 10 Open (not ended) tables one player may have created through table.create. Tables created with the server API do not count.
maxTables number 10 000 Tables the server holds before table.create from clients is refused.

devtools: true turns the inspector on outside production. The object form:

Option Type Default Description
enabled boolean required Turns the inspector on.
token string Required in production; generated (32 random bytes) in dev if omitted.
path string '/__shoehive' HTTP path of the inspector. Default '/__shoehive'; the socket is <path>/ws.
allowRemote boolean false Serve non-loopback clients too. Default false: loopback clients only.
allowInProduction boolean false Allow devtools when NODE_ENV === 'production'.

See Devtools for how to use it safely.

The server reads these environment variables:

Variable Effect
NODE_ENV production turns off dev checks and devtools, and makes secret (or SHOEHIVE_SECRET) required for guest identities.
SHOEHIVE_SECRET Resume-token secret, used when the secret option is not set.
import { createClient } from 'shoehive/client';
Option Type Default Description
url string required Server URL, for example ws://localhost:3000/shoehive.
name string Display name for a new guest.
storage TokenStorage | false localStorage in browsers, memory elsewhere Resume token storage. false disables it (every connection is a new guest).
connect (url: string) => WebSocketLike new WebSocket(url, 'shoehive.v1') Opens the socket.
reconnect { initialDelayMs?: number; maxDelayMs?: number } | false on Reconnect with exponential backoff and jitter. Default on; false disables it.
requestTimeoutMs number 15 000 ms How long a request waits for its ack.
autoConnect boolean true Connect immediately.