Config options
This page is generated from the doc comments in the source. For the full types, see the API reference.
Server options
Section titled “Server options”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. |
Limits
Section titled “Limits”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
Section titled “Devtools”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.
Environment variables
Section titled “Environment variables”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. |
Client options
Section titled “Client options”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. |
