API reference › @evolu/nodejs › NodeJsRelayConfig

Defined in: packages/nodejs/src/local-first/Relay.ts:47

Configuration of a relay. A relay should also send the heartbeats that OwnerWebSocketTransport describes.

Extends

Properties

isOwnerAllowed?

readonly isOwnerAllowed?: (ownerId: string & Brand<"Id"> & Brand<"OwnerId">, options: {
  signal: AbortSignal;
}) => Awaitable<boolean>;

Defined in: packages/common/dist/src/local-first/Relay.d.ts:123

Optional callback to check if an OwnerId is allowed to access the relay. If this callback is not provided, all owners are allowed.

The callback receives the OwnerId and an options object with an abort AbortSignal, and returns a Awaitable boolean: true to allow access, or false to deny.

The callback can be synchronous (for SQLite or in-memory checks) or asynchronous (for calling remote APIs).

The callback returns a boolean rather than an error type because error handling and logging are the responsibility of the callback implementation.

OwnerId is used rather than short-lived tokens because this only controls relay access, not write permissions. Changes are encrypted end-to-end, so OwnerId exposure reveals no change contents. But anyone who knows an OwnerId can download the owner's encrypted changes and their timestamps from a relay and subscribe to new ones, as Privacy describes.

OwnerId exposure also allows write-key squatting. The relay stores the write key of the first write it accepts for an owner, so anyone who learns an OwnerId can claim it by writing there before the owner's devices do, unless StorageConfig.isOwnerWithinQuota refuses that write. The owner then gets ProtocolWriteKeyError on this relay until the operator deletes everything the relay stores for that OwnerId with Relay.deleteOwner, which removes the squatter's key and the data stored with it. This callback does not prevent that: it receives only the OwnerId of a connection, which a squatter can name as well, and every message on the connection can name another owner.

Owners specify which relays to connect to via OwnerTransport. In WebSocket-based implementations, this check occurs before accepting the connection, with the OwnerId typically extracted from the URL query string (e.g., ws://localhost:4000/?ownerId=...). The relay requires the URL to be in the correct format for OwnerId extraction.

Example

import {
  AppName,
  assertEqual,
  assertTrue,
  assertType,
  createAppOwner,
  createEvolu,
  createOwnerWebSocketTransport,
  createOwnerSecret,
  createRandomBytes,
  id,
  RelayUrl,
  type AnyTask,
} from "@evolu/common";
import type { RelayConfig } from "@evolu/common/local-first";

// Create once, persist the mnemonic securely, and restore it on later runs.
const appOwner = createAppOwner(
  createOwnerSecret({ randomBytes: createRandomBytes() }),
);
// Client: include the OwnerId so the relay can admit the connection.
const transport = createOwnerWebSocketTransport({
  url: RelayUrl.orThrow("wss://relay.evolu.dev/"),
  ownerId: appOwner.id,
});

const createTodoEvolu = createEvolu(
  { todo: { id: id("Todo") } },
  {
    appName: AppName.orThrow("AuthenticatedRelayExample"),
    appOwner,
    transports: [transport],
  },
);
assertType<typeof createTodoEvolu extends AnyTask ? true : false, true>();

// Relay: accept owners allowed by the app's access policy.
type IsOwnerAllowed = NonNullable<RelayConfig["isOwnerAllowed"]>;
const allowedOwnerIds = new Set([appOwner.id]);
const isOwnerAllowed: IsOwnerAllowed = (ownerId, { signal }) =>
  !signal.aborted && allowedOwnerIds.has(ownerId);

assertEqual(
  await isOwnerAllowed(appOwner.id, {
    signal: new AbortController().signal,
  }),
  true,
);
assertTrue(transport.url.includes(`ownerId=${appOwner.id}`));

Inherited from

RelayConfig.isOwnerAllowed


isOwnerWithinQuota

readonly isOwnerWithinQuota: (ownerId: string & Brand<"Id"> & Brand<"OwnerId">, requiredBytes: number & Brand<"NonNaN"> & Brand<"Finite"> & Brand<"Int"> & Brand<"NonNegative">) => Awaitable<boolean>;

Defined in: packages/common/dist/src/local-first/Storage.d.ts:77

Callback called before an attempt to write, to check if an OwnerId has sufficient quota for the write.

The callback receives the OwnerId and the total bytes that would be stored after the write (current stored bytes plus incoming bytes), and returns a Awaitable boolean: true to allow the write, or false to deny it due to quota limits.

The callback can be synchronous (for SQLite or in-memory checks) or asynchronous (for calling remote APIs).

The callback returns a boolean rather than an error because error handling and logging are the responsibility of the callback implementation. It must not throw or reject, because a throw is a defect that shuts the relay down for a supervisor to restart it; a callback calling a remote service catches its failure and returns whether to allow the write.

Relay deployments configure this callback. Client applications observe a denied relay write as a ProtocolQuotaError in the failure of that relay's route, which syncStateToOwnerSyncStatus reports as the owner's Error status.

Example

import {
  assertEqual,
  createAppOwner,
  createOwnerSecret,
  createRandomBytes,
  PositiveInt,
} from "@evolu/common";
import type { StorageConfig } from "@evolu/common/local-first";

// Create once, persist the mnemonic securely, and restore it on later runs.
const appOwner = createAppOwner(
  createOwnerSecret({ randomBytes: createRandomBytes() }),
);
const maxBytes = PositiveInt.orThrow(1024);
const relayStorageConfig: StorageConfig = {
  isOwnerWithinQuota: (ownerId, requiredBytes) =>
    ownerId === appOwner.id && requiredBytes <= maxBytes,
};

assertEqual(
  await relayStorageConfig.isOwnerWithinQuota(
    appOwner.id,
    PositiveInt.orThrow(2048),
  ),
  false,
);

Inherited from

RelayConfig.isOwnerWithinQuota


name?

readonly name?: string & Brand<"UrlSafeString"> & Brand<"Name">;

Defined in: packages/common/dist/src/local-first/Relay.d.ts:26

The relay name.

Implementations can use this for identification purposes (e.g., database file name, logging).

Inherited from

RelayConfig.name


pingInterval?

readonly pingInterval?: PositiveDuration;

Defined in: packages/nodejs/src/local-first/Relay.ts:80

How often the relay pings every connection with a WebSocket ping frame, which WebSocket clients answer automatically. A connection from which nothing has arrived since the previous ping is terminated, so an idle dead path is detected within two intervals. Any incoming data counts, so a slow upload that delays the answer keeps its connection. A connection with data still queued in the relay for it, such as a large reply on a slow link, is not pinged or terminated until the operating system takes the data, because the answer waits behind it; TCP ends such a connection if its path is dead. Nor is a connection whose requests the relay is serving, because it does not read the connection meanwhile; it is pinged again once they are served. A connection is terminated instead of queuing a broadcast that would leave more than 16 MB of broadcasts unsent to it, whether its client stopped reading or reads more slowly than its owners' traffic arrives; the client reconciles after it reconnects. Replies to a client's own requests do not count, because the relay writes them one at a time; see createRelay. Data the operating system already holds still delays the answer, so a link too slow to send it within an interval reconnects once, after the data ahead of the ping arrives. The traffic also keeps NAT mappings alive.

WebSocket clients do not tell JavaScript about pings, so the relay sends an empty text frame right after each one, with the same exceptions, as the heartbeat its clients watch; see OwnerWebSocketTransport. The interval must therefore be at most relayHeartbeatInterval, and createRelay panics on a longer one. Defaults to thirty seconds.


port?

readonly port?: number & Brand<"NonNaN"> & Brand<"Finite"> & Brand<"Int"> & Brand<"NonNegative"> & Brand<"LessThanOrEqualTo65535"> & Brand<"Port">;

Defined in: packages/nodejs/src/local-first/Relay.ts:52

The HTTP server's Port. Zero requests an automatically assigned port.