Server (Rest)
Reference for @folkways/realtime/server — Folkways.Rest options, createToken() and publish().
import { Folkways } from '@folkways/realtime/server';
const rte = new Folkways.Rest({ url, segment, signingKey: { kid, privateKey } });Rest runs on Node.js 20+, Deno, Bun and edge runtimes with WebCrypto. It throws InvalidArgument if it is created
in a browser, because it holds a private key. A guide is in Issue tokens from your backend.
RestOptions
| Option | Type | Default | Meaning |
|---|---|---|---|
url | string | required | The node's HTTP address, e.g. https://rte.example.com |
segment | string | required | The segment ID (a UUID) from the dashboard |
signingKey | SigningKey | required | One of the segment's signing keys, with its private half. Below |
identity | string | 'server' | The identity this server publishes as |
capabilities | { topics: string; ops: Op[] }[] | publish on every topic | Permissions of this server's own token, used by publish() |
fetch | fetch-compatible function | globalThis.fetch | For runtimes without a global fetch |
timeoutMs | number | 10000 | Timeout of each HTTP request |
SigningKey
| Field | Type | Meaning |
|---|---|---|
kid | string | The key's ID, as shown on the segment's Signing keys tab |
privateKey | string | The private key as a PKCS#8 PEM (-----BEGIN PRIVATE KEY-----) for Ed25519 or P-256, or the shared secret of an HS256 key |
alg | 'EdDSA' | 'ES256' | 'HS256' | Optional. Read from privateKey when left out |
A public key, an rte_… key or a missing field throws InvalidArgument. A P-256 key in the older
BEGIN EC PRIVATE KEY format must first be converted:
openssl pkcs8 -topk8 -nocrypt -in key.ec.pem -out key.pem.
createToken(options?)
Signs a token in process; makes no network call.
| Option | Type | Default | Meaning |
|---|---|---|---|
identity | string | required unless kind is 'anonymous' | Who the token is for. At most 256 bytes; must not start with anon: |
kind | 'user' | 'agent' | 'service' | 'anonymous' | 'user' | The kind of client. 'anonymous' takes no identity |
capabilities | { topics: string; ops: Op[] }[] | [] | Topic patterns and operations. Each needs a pattern and at least one op |
ttlMs | number | 600000 | Lifetime in ms; kept between 1 second and 15 minutes |
Resolves with:
| Field | Type | Meaning |
|---|---|---|
token | string | The signed JWT. Hand it to your app |
expiresAt | number | Expiry, Unix ms |
identity | string | null | The identity, or null for anonymous |
kind | string | The kind |
capabilities | { topics, ops }[] | The permissions granted |
Op is one of 'subscribe', 'publish', 'set', 'signal', 'history', 'presence'. See
Permissions.
publish(topic, event, data, options?)
Publishes one event over HTTP and resolves with the node's PublishReceipt.
| Parameter | Type | Meaning |
|---|---|---|
topic | string | The topic |
event | string | The event's name |
data | any JSON value, string or bytes | The payload |
options.delivery | 'stream' | 'kv' | Default 'stream'. Signals can't be sent from a server |
options.key | string | kv: the key |
options.ttlMs | number | kv: how long the value lives |
options.remove | boolean | kv: remove the key |
options.headers | Record<string, string> | Headers passed to subscribers |
options.contentType | content type name or number | Labels the payload |
options.idempotencyKey | string | 32 hex digits or a UUID; reuse it to retry safely |
The server signs its own service token for this, caches it and renews it a minute before it expires. Errors are
RealtimeErrors, as in the client; isRealtimeError from either entry point recognises them.
Other exports
@folkways/realtime/server also exports Rest, Code, codeName, RealtimeError, isRealtimeError and the
types RestOptions, CreateTokenOptions, IssuedToken, RestPublishOptions, SigningKey, SigningAlgorithm,
Permission, Op, Delivery and PublishReceipt.