Documentation

Advanced usage.

Environment variables

ScaleSocket can optionally expose CGI environment variables to the target.

The supported environment variables are:

See the Command-line reference and the --passenv argument for details.

HTTP endpoints

Metrics endpoint

ScaleSocket can expose an OpenMetrics and Prometheus compatible endpoint for scraping metrics.

The tracked metrics are:

See the Command-line reference and the --metrics flag for details.

Metadata endpoint

ScaleSocket can expose a JSON endpoint for retrieving rooms and their metadata.

When --framing is set to JSON, additional metadata can be set by the server using messages with a _meta: true field. This is useful for building a lobby or room list.

See the Command-line reference and the --api flag for details.

Health endpoint

ScaleSocket exposes a standard /health endpoint for checking readiness.

Delimiters

ScaleSocket parses output into messages by splitting output at newline (\n), except when --binary mode is enabled.

To alter this behaviour, the --delimiters argument can be used to specify a set of custom delimiters. For example --delimiters=, will split comma-separated output by the target into messages.

To set the delimiter to the null-byte (\0), use --null. This is useful for outputting multiline messages from the target, for example as a backend for htmx.

Caching

ScaleSocket can optionally cache server sent messages, and send them to new clients when they join a room.

Two types of caching are supported: all and tagged. Supported cache sizes are 1, 8 and 64.

This is an experimental feature.

Caching all messages

When --cache=all:8 is enabled, the last 8 messages sent by the server will be cached.

This is useful for enabling a chat history.

Caching tagged messages

When --framing is set to JSON, and --cache=tagged:8 is enabled, only messages with a _cache: true field will be cached.

This is useful for maintaining a state that is sent quickly to clients when they join a room.

See the Command-line reference and the --cache and --cachepersist arguments for details.

Next.