@evolu/common 6.0.1-preview.20 → 6.0.1-preview.22

package/dist/src/Evolu/Protocol.d.ts

@@ -20,7 +20,7 @@
  * transfer, ownership, real-time broadcasting, request-response semantics, and
  * error handling.
  *
- * ### Message Structure
+ * ### Message structure
  *
  * | Field                          | Notes                     |
  * | :----------------------------- | :------------------------ |
@@ -43,7 +43,7 @@
  * | - {@link NonNegativeInt}       | Number of ranges.         |
  * | - {@link Range}                |                           |
  *
- * ### WriteKey Validation
+ * ### WriteKey validation
  *
  * The initiator sends a hasWriteKey flag and optionally a WriteKey. The
  * WriteKey is required when sending messages as a secure token proving the
@@ -79,33 +79,33 @@
  * initiator. In relay-to-relay or P2P sync, both sides may require the
  * {@link OwnerWriteKey} depending on who is the initiator.
  *
- * ### Protocol Errors
+ * ### Protocol errors
  *
  * The protocol uses error codes in the header to signal issues:
  *
  * - {@link ProtocolWriteKeyError}: The provided WriteKey is invalid or missing.
- * - {@link ProtocolWriteError}: A write operation failed (e.g., due to storage
- *   limits or billing).
- * - {@link ProtocolSyncError}: A generic or unexpected synchronization failure
+ * - {@link ProtocolWriteError}: A serious relay-side write failure occurred.
+ * - {@link ProtocolSyncError}: A serious relay-side synchronization failure
  *   occurred.
+ * - {@link ProtocolQuotaExceededError}: Storage or billing quota exceeded.
  * - {@link ProtocolUnsupportedVersionError}: Protocol version mismatch.
  * - {@link ProtocolInvalidDataError}: The message is malformed or corrupted.
  *
  * All protocol errors except `ProtocolInvalidDataError` include the `OwnerId`
  * to allow clients to associate errors with the correct owner.
  *
- * ### Message Size Limit
+ * ### Message size limit
  *
  * The protocol enforces a strict maximum size for all messages, defined by
- * {@link maxProtocolMessageSize}. This ensures every {@link ProtocolMessage} is
+ * {@link ProtocolMessageMaxSize}. This ensures every {@link ProtocolMessage} is
  * less than or equal to this limit, enabling stateless transports, simplified
  * relay implementation, and predictable memory usage. When all messages don't
  * fit within the limit, the protocol automatically continues synchronization in
  * subsequent rounds using range-based reconciliation.
  *
- * Individual database mutations are limited to `maxMutationSize` (640KB), which
- * is smaller than the protocol message limit to ensure efficient sync with
- * {@link maxProtocolMessageRangesSize}.
+ * Database mutations are limited to 640KB, which is smaller than the protocol
+ * message limit to ensure efficient sync with
+ * {@link defaultProtocolMessageRangesMaxSize}.
  *
  * ### Why Binary?
  *
@@ -148,6 +148,15 @@
  * Version negotiation is per-owner, allowing Evolu Protocol to evolve safely
  * over time and provide clear feedback about version mismatches.
  *
+ * ### Credible exit
+ *
+ * The protocol specification is intentionally non-configurable to ensure
+ * universal compatibility. This design allows applications (users) to switch
+ * between any compliant relay without negotiation or compatibility checks
+ * beyond version matching. Relays are generic infrastructure that any
+ * application can use interchangeably making exit from any single provider
+ * technically feasible and economically viable.
+ *
  * @module
  */
 import { NonEmptyReadonlyArray } from "../Array.js";
@@ -160,10 +169,51 @@ import { NonNegativeInt, PositiveInt } from "../Type.js";
 import { Owner, OwnerId, OwnerWriteKey } from "./Owner.js";
 import { BaseRange, CrdtMessage, DbChange, EncryptedCrdtMessage, EncryptedDbChange, FingerprintRange, RangeType, SkipRange, StorageDep } from "./Storage.js";
 import { NodeId, Timestamp } from "./Timestamp.js";
-/** Maximum size of the entire protocol message in bytes. */
-export declare const maxProtocolMessageSize: PositiveInt;
-/** Maximum size of the ranges in bytes. */
-export declare const maxProtocolMessageRangesSize: PositiveInt;
+/**
+ * Protocol message maximum size.
+ *
+ * Defines the upper limit for how large a single protocol message can be.
+ * Implementations must enforce a maximum size between 1MB and 100MB to ensure
+ * compatibility across all Evolu implementations (the maximum size of mutation
+ * change is hardcoded and enforced hence the maximum size can't be smaller).
+ *
+ * Larger maximum sizes can be configured by relays to reduce roundtrips. For
+ * example, a dedicated relay with ample resources could configure a 100MB
+ * maximum to minimize roundtrips for large syncs.
+ *
+ * Only relays can safely configure larger sizes, as clients will handle them.
+ * Increasing this value on the client side would break compatibility with
+ * relays that enforce smaller limits.
+ */
+export declare const ProtocolMessageMaxSize: import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int">, number, import("../Type.js").IntError, number, import("../Type.js").NumberError>, "Between1000000-100000000", import("../Type.js").BetweenError<1000000, 100000000>, import("../Type.js").IntError | import("../Type.js").NumberError>;
+export type ProtocolMessageMaxSize = typeof ProtocolMessageMaxSize.Type;
+/**
+ * Default {@link ProtocolMessageMaxSize} (1MB).
+ *
+ * The standard size used across Evolu implementations. Relays with more
+ * resources can configure larger sizes to reduce roundtrips.
+ */
+export declare const defaultProtocolMessageMaxSize: ProtocolMessageMaxSize;
+/**
+ * Protocol message ranges maximum size.
+ *
+ * Defines the upper limit for how large the ranges section of a protocol
+ * message can be. Implementations must enforce a maximum size between 3KB and
+ * 100KB to ensure compatibility.
+ *
+ * The upper bound is set to ensure ranges fit within the default 1MB
+ * {@link defaultProtocolMessageMaxSize}, maintaining compatibility between all
+ * clients and relays.
+ */
+export declare const ProtocolMessageRangesMaxSize: import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int">, number, import("../Type.js").IntError, number, import("../Type.js").NumberError>, "Between3000-100000", import("../Type.js").BetweenError<3000, 100000>, import("../Type.js").IntError | import("../Type.js").NumberError>;
+export type ProtocolMessageRangesMaxSize = typeof ProtocolMessageRangesMaxSize.Type;
+/**
+ * Default {@link ProtocolMessageRangesMaxSize} (30KB).
+ *
+ * The standard size used across Evolu implementations. Relays with more
+ * resources can configure larger sizes to reduce roundtrips.
+ */
+export declare const defaultProtocolMessageRangesMaxSize: ProtocolMessageRangesMaxSize;
 /** Evolu Protocol Message. */
 export type ProtocolMessage = Uint8Array & Brand<"ProtocolMessage">;
 /** Evolu Protocol version. */
@@ -194,9 +244,11 @@ export declare const ProtocolErrorCode: {
     readonly WriteError: 2;
     /** A code for {@link ProtocolSyncError}. */
     readonly SyncError: 3;
+    /** A code for {@link ProtocolQuotaExceededError}. */
+    readonly QuotaExceededError: 4;
 };
 type ProtocolErrorCode = (typeof ProtocolErrorCode)[keyof typeof ProtocolErrorCode];
-export type ProtocolError = ProtocolUnsupportedVersionError | ProtocolInvalidDataError | ProtocolWriteKeyError | ProtocolWriteError | ProtocolSyncError | ProtocolTimestampMismatchError;
+export type ProtocolError = ProtocolUnsupportedVersionError | ProtocolInvalidDataError | ProtocolWriteKeyError | ProtocolWriteError | ProtocolSyncError | ProtocolQuotaExceededError | ProtocolTimestampMismatchError;
 /** Base interface for all protocol errors. */
 export interface ProtocolErrorBase {
     readonly ownerId: OwnerId;
@@ -222,19 +274,29 @@ export interface ProtocolWriteKeyError extends ProtocolErrorBase {
     readonly type: "ProtocolWriteKeyError";
 }
 /**
- * Error when a write fails due to storage limits or billing requirements.
- * Indicates the need to expand capacity or resolve payment issues.
+ * Error indicating a serious relay-side write failure. Clients should log this
+ * error and show a generic sync error to the user.
  */
 export interface ProtocolWriteError extends ProtocolErrorBase {
     readonly type: "ProtocolWriteError";
 }
 /**
- * Error indicating a synchronization failure during the protocol exchange. Used
- * for unexpected or generic sync errors not covered by other error types.
+ * Error indicating a serious relay-side synchronization failure. Clients should
+ * log this error and show a generic sync error to the user.
  */
 export interface ProtocolSyncError extends ProtocolErrorBase {
     readonly type: "ProtocolSyncError";
 }
+/**
+ * Error when storage or billing quota is exceeded. Clients should prompt the
+ * user to upgrade their plan or expand capacity.
+ *
+ * TODO: Add callback to relay config to check quota and return this error when
+ * limits are reached.
+ */
+export interface ProtocolQuotaExceededError extends ProtocolErrorBase {
+    readonly type: "ProtocolQuotaExceededError";
+}
 /**
  * Error when embedded timestamp doesn't match expected timestamp in
  * EncryptedDbChange. Indicates potential tampering or corruption of CRDT
@@ -248,11 +310,11 @@ export interface ProtocolTimestampMismatchError {
 /**
  * Creates a {@link ProtocolMessage} from CRDT messages.
  *
- * If the message size would exceed {@link maxProtocolMessageSize}, the protocol
- * ensures all messages will be sent in the next round(s) even over
+ * If the message size would exceed {@link defaultProtocolMessageMaxSize}, the
+ * protocol ensures all messages will be sent in the next round(s) even over
  * unidirectional and stateless transports.
  */
-export declare const createProtocolMessageFromCrdtMessages: (deps: RandomBytesDep & SymmetricCryptoDep) => (owner: Owner, messages: NonEmptyReadonlyArray<CrdtMessage>, maxSize?: PositiveInt) => ProtocolMessage;
+export declare const createProtocolMessageFromCrdtMessages: (deps: RandomBytesDep & SymmetricCryptoDep) => (owner: Owner, messages: NonEmptyReadonlyArray<CrdtMessage>, maxSize?: ProtocolMessageMaxSize) => ProtocolMessage;
 /** Creates a {@link ProtocolMessage} for sync. */
 export declare const createProtocolMessageForSync: (deps: StorageDep) => (ownerId: OwnerId, subscriptionFlag?: SubscriptionFlag) => ProtocolMessage | null;
 export declare const createProtocolMessageForUnsubscribe: (ownerId: OwnerId) => ProtocolMessage;
@@ -270,8 +332,8 @@ export interface ProtocolMessageBuffer {
     readonly getSize: () => PositiveInt;
 }
 export declare const createProtocolMessageBuffer: (ownerId: OwnerId, options: {
-    readonly totalMaxSize?: PositiveInt | undefined;
-    readonly rangesMaxSize?: PositiveInt | undefined;
+    readonly totalMaxSize?: ProtocolMessageMaxSize | undefined;
+    readonly rangesMaxSize?: ProtocolMessageRangesMaxSize | undefined;
     readonly version?: NonNegativeInt;
 } & ({
     readonly messageType: typeof MessageType.Request;
@@ -299,8 +361,7 @@ export interface ApplyProtocolMessageAsClientOptions {
     getWriteKey?: (ownerId: OwnerId) => OwnerWriteKey | null;
     /** For testing purposes only; should not be used in production. */
     version?: NonNegativeInt;
-    totalMaxSize?: PositiveInt;
-    rangesMaxSize?: PositiveInt;
+    rangesMaxSize?: ProtocolMessageRangesMaxSize;
 }
 /**
  * Result type for {@link applyProtocolMessageAsClient} that distinguishes
@@ -314,7 +375,7 @@ export type ApplyProtocolMessageAsClientResult = {
 } | {
     readonly type: "broadcast";
 };
-export declare const applyProtocolMessageAsClient: (deps: StorageDep) => (inputMessage: Uint8Array, options?: ApplyProtocolMessageAsClientOptions) => Promise<Result<ApplyProtocolMessageAsClientResult, ProtocolInvalidDataError | ProtocolSyncError | ProtocolUnsupportedVersionError | ProtocolWriteError | ProtocolWriteKeyError>>;
+export declare const applyProtocolMessageAsClient: (deps: StorageDep) => (inputMessage: Uint8Array, options?: ApplyProtocolMessageAsClientOptions) => Promise<Result<ApplyProtocolMessageAsClientResult, ProtocolInvalidDataError | ProtocolSyncError | ProtocolUnsupportedVersionError | ProtocolWriteError | ProtocolWriteKeyError | ProtocolQuotaExceededError>>;
 export interface ApplyProtocolMessageAsRelayOptions {
     /** To subscribe an owner for broadcasting. */
     subscribe?: (ownerId: OwnerId) => void;
@@ -322,8 +383,8 @@ export interface ApplyProtocolMessageAsRelayOptions {
     unsubscribe?: (ownerId: OwnerId) => void;
     /** To broadcast a protocol message to all subscribers. */
     broadcast?: (ownerId: OwnerId, message: ProtocolMessage) => void;
-    totalMaxSize?: PositiveInt;
-    rangesMaxSize?: PositiveInt;
+    totalMaxSize?: ProtocolMessageMaxSize;
+    rangesMaxSize?: ProtocolMessageRangesMaxSize;
 }
 /**
  * Result type for {@link applyProtocolMessageAsRelay}.

package/dist/src/Evolu/Protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Protocol.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Protocol.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Protocol.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Protocol.ts"],"names":[],"mappings":"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"}

package/dist/src/Evolu/Protocol.js

@@ -1,4 +1,3 @@
-/* eslint-disable jsdoc/no-undefined-types */
 /**
  * Evolu Protocol
  *
@@ -21,7 +20,7 @@
  * transfer, ownership, real-time broadcasting, request-response semantics, and
  * error handling.
  *
- * ### Message Structure
+ * ### Message structure
  *
  * | Field                          | Notes                     |
  * | :----------------------------- | :------------------------ |
@@ -44,7 +43,7 @@
  * | - {@link NonNegativeInt}       | Number of ranges.         |
  * | - {@link Range}                |                           |
  *
- * ### WriteKey Validation
+ * ### WriteKey validation
  *
  * The initiator sends a hasWriteKey flag and optionally a WriteKey. The
  * WriteKey is required when sending messages as a secure token proving the
@@ -80,33 +79,33 @@
  * initiator. In relay-to-relay or P2P sync, both sides may require the
  * {@link OwnerWriteKey} depending on who is the initiator.
  *
- * ### Protocol Errors
+ * ### Protocol errors
  *
  * The protocol uses error codes in the header to signal issues:
  *
  * - {@link ProtocolWriteKeyError}: The provided WriteKey is invalid or missing.
- * - {@link ProtocolWriteError}: A write operation failed (e.g., due to storage
- *   limits or billing).
- * - {@link ProtocolSyncError}: A generic or unexpected synchronization failure
+ * - {@link ProtocolWriteError}: A serious relay-side write failure occurred.
+ * - {@link ProtocolSyncError}: A serious relay-side synchronization failure
  *   occurred.
+ * - {@link ProtocolQuotaExceededError}: Storage or billing quota exceeded.
  * - {@link ProtocolUnsupportedVersionError}: Protocol version mismatch.
  * - {@link ProtocolInvalidDataError}: The message is malformed or corrupted.
  *
  * All protocol errors except `ProtocolInvalidDataError` include the `OwnerId`
  * to allow clients to associate errors with the correct owner.
  *
- * ### Message Size Limit
+ * ### Message size limit
  *
  * The protocol enforces a strict maximum size for all messages, defined by
- * {@link maxProtocolMessageSize}. This ensures every {@link ProtocolMessage} is
+ * {@link ProtocolMessageMaxSize}. This ensures every {@link ProtocolMessage} is
  * less than or equal to this limit, enabling stateless transports, simplified
  * relay implementation, and predictable memory usage. When all messages don't
  * fit within the limit, the protocol automatically continues synchronization in
  * subsequent rounds using range-based reconciliation.
  *
- * Individual database mutations are limited to `maxMutationSize` (640KB), which
- * is smaller than the protocol message limit to ensure efficient sync with
- * {@link maxProtocolMessageRangesSize}.
+ * Database mutations are limited to 640KB, which is smaller than the protocol
+ * message limit to ensure efficient sync with
+ * {@link defaultProtocolMessageRangesMaxSize}.
  *
  * ### Why Binary?
  *
@@ -149,6 +148,15 @@
  * Version negotiation is per-owner, allowing Evolu Protocol to evolve safely
  * over time and provide clear feedback about version mismatches.
  *
+ * ### Credible exit
+ *
+ * The protocol specification is intentionally non-configurable to ensure
+ * universal compatibility. This design allows applications (users) to switch
+ * between any compliant relay without negotiation or compatibility checks
+ * beyond version matching. Relays are generic infrastructure that any
+ * application can use interchangeably making exit from any single provider
+ * technically feasible and economically viable.
+ *
  * @module
  */
 import { Packr } from "msgpackr";
@@ -160,21 +168,62 @@ import { eqArrayNumber } from "../Eq.js";
 import { computeBalancedBuckets } from "../Number.js";
 import { objectToEntries } from "../Object.js";
 import { err, ok } from "../Result.js";
-import { Base64Url, base64UrlToUint8Array, DateIso, Id, idBytesToId, idBytesTypeValueLength, idToIdBytes, Json, jsonToJsonValue, NonNegativeInt, Number, uint8ArrayToBase64Url, } from "../Type.js";
+import { Base64Url, base64UrlToUint8Array, between, DateIso, Id, idBytesToId, idBytesTypeValueLength, idToIdBytes, Int, Json, jsonToJsonValue, NonNegativeInt, Number, uint8ArrayToBase64Url, } from "../Type.js";
 import { ownerIdToOwnerIdBytes, ownerWriteKeyLength, } from "./Owner.js";
 import { fingerprintSize, InfiniteUpperBound, RangeType, } from "./Storage.js";
 import { Counter, eqTimestamp, Millis, timestampBytesLength, timestampBytesToTimestamp, timestampToTimestampBytes, } from "./Timestamp.js";
 /**
- * MessagePack serializer for standard compatibility and compact encoding.
+ * Evolu uses MessagePack for numbers and JSONs.
  *
  * - `variableMapSize: true` - More compact maps, ~5-10% slower encoding
  * - `useRecords: false` - Standard MessagePack without extensions
  */
 const packr = new Packr({ variableMapSize: true, useRecords: false });
-/** Maximum size of the entire protocol message in bytes. */
-export const maxProtocolMessageSize = 1_000_000;
-/** Maximum size of the ranges in bytes. */
-export const maxProtocolMessageRangesSize = 30_000;
+const minProtocolMessageMaxSize = 1_000_000;
+const maxProtocolMessageMaxSize = 100_000_000;
+/**
+ * Protocol message maximum size.
+ *
+ * Defines the upper limit for how large a single protocol message can be.
+ * Implementations must enforce a maximum size between 1MB and 100MB to ensure
+ * compatibility across all Evolu implementations (the maximum size of mutation
+ * change is hardcoded and enforced hence the maximum size can't be smaller).
+ *
+ * Larger maximum sizes can be configured by relays to reduce roundtrips. For
+ * example, a dedicated relay with ample resources could configure a 100MB
+ * maximum to minimize roundtrips for large syncs.
+ *
+ * Only relays can safely configure larger sizes, as clients will handle them.
+ * Increasing this value on the client side would break compatibility with
+ * relays that enforce smaller limits.
+ */
+export const ProtocolMessageMaxSize = between(minProtocolMessageMaxSize, maxProtocolMessageMaxSize)(Int);
+/**
+ * Default {@link ProtocolMessageMaxSize} (1MB).
+ *
+ * The standard size used across Evolu implementations. Relays with more
+ * resources can configure larger sizes to reduce roundtrips.
+ */
+export const defaultProtocolMessageMaxSize = minProtocolMessageMaxSize;
+/**
+ * Protocol message ranges maximum size.
+ *
+ * Defines the upper limit for how large the ranges section of a protocol
+ * message can be. Implementations must enforce a maximum size between 3KB and
+ * 100KB to ensure compatibility.
+ *
+ * The upper bound is set to ensure ranges fit within the default 1MB
+ * {@link defaultProtocolMessageMaxSize}, maintaining compatibility between all
+ * clients and relays.
+ */
+export const ProtocolMessageRangesMaxSize = between(3_000, 100_000)(Int);
+/**
+ * Default {@link ProtocolMessageRangesMaxSize} (30KB).
+ *
+ * The standard size used across Evolu implementations. Relays with more
+ * resources can configure larger sizes to reduce roundtrips.
+ */
+export const defaultProtocolMessageRangesMaxSize = 30_000;
 /** Evolu Protocol version. */
 export const protocolVersion = 0;
 export const MessageType = {
@@ -201,18 +250,20 @@ export const ProtocolErrorCode = {
     WriteError: 2,
     /** A code for {@link ProtocolSyncError}. */
     SyncError: 3,
+    /** A code for {@link ProtocolQuotaExceededError}. */
+    QuotaExceededError: 4,
 };
 /**
  * Creates a {@link ProtocolMessage} from CRDT messages.
  *
- * If the message size would exceed {@link maxProtocolMessageSize}, the protocol
- * ensures all messages will be sent in the next round(s) even over
+ * If the message size would exceed {@link defaultProtocolMessageMaxSize}, the
+ * protocol ensures all messages will be sent in the next round(s) even over
  * unidirectional and stateless transports.
  */
 export const createProtocolMessageFromCrdtMessages = (deps) => (owner, messages, maxSize) => {
     const buffer = createProtocolMessageBuffer(owner.id, {
         messageType: MessageType.Request,
-        totalMaxSize: maxSize ?? maxProtocolMessageSize,
+        totalMaxSize: maxSize ?? defaultProtocolMessageMaxSize,
         writeKey: owner.writeKey,
     });
     let notAllMessagesSent = false;
@@ -236,8 +287,8 @@ export const createProtocolMessageFromCrdtMessages = (deps) => (owner, messages,
          *
          * The ideal approach would be to send three ranges (skip, fingerprint,
          * skip) where the fingerprint of unsent messages would act as narrow sync
-         * probe. I think we can send {@link zeroFingerprint} which can be
-         * interpreted as an indication that the other side should reply with
+         * probe. I think we can send `zeroFingerprint` which can be interpreted
+         * as an indication that the other side should reply with
          * {@link TimestampsRange}, so no need to restart syncing.
          *
          * For now, using a random fingerprint avoids extra complexity and is good
@@ -272,7 +323,7 @@ export const createProtocolMessageForUnsubscribe = (ownerId) => createProtocolMe
     subscriptionFlag: SubscriptionFlags.Unsubscribe,
 }).unwrap();
 export const createProtocolMessageBuffer = (ownerId, options) => {
-    const { totalMaxSize = maxProtocolMessageSize, rangesMaxSize = maxProtocolMessageRangesSize, version = protocolVersion, } = options;
+    const { totalMaxSize = defaultProtocolMessageMaxSize, rangesMaxSize = defaultProtocolMessageRangesMaxSize, version = protocolVersion, } = options;
     const buffers = {
         header: createBuffer(),
         messages: {
@@ -507,6 +558,11 @@ export const applyProtocolMessageAsClient = (deps) => async (inputMessage, optio
                             type: "ProtocolSyncError",
                             ownerId,
                         });
+                    case ProtocolErrorCode.QuotaExceededError:
+                        return err({
+                            type: "ProtocolQuotaExceededError",
+                            ownerId,
+                        });
                     default:
                         throw new ProtocolDecodeError(`Invalid ProtocolErrorCode: ${errorCode}`);
                 }
@@ -537,7 +593,6 @@ export const applyProtocolMessageAsClient = (deps) => async (inputMessage, optio
         const output = createProtocolMessageBuffer(ownerId, {
             messageType: MessageType.Request,
             writeKey,
-            totalMaxSize: options.totalMaxSize,
             rangesMaxSize: options.rangesMaxSize,
         });
         const syncResult = sync(deps)(ranges, output, ownerIdBytes);

package/dist/src/Evolu/Relay.d.ts

@@ -1,14 +1,81 @@
-import { ConsoleConfig } from "../Console.js";
+import { ConsoleConfig, ConsoleDep } from "../Console.js";
 import { TimingSafeEqualDep } from "../Crypto.js";
+import { LazyValue } from "../Function.js";
 import { Result } from "../Result.js";
 import { SqliteError } from "../Sqlite.js";
 import { SimpleName } from "../Type.js";
+import { OwnerId } from "./Owner.js";
+import { ProtocolInvalidDataError } from "./Protocol.js";
 import { CreateSqliteStorageBaseOptions, SqliteStorageDeps, Storage } from "./Storage.js";
 export interface Relay extends Disposable {
 }
 export interface RelayConfig extends ConsoleConfig {
+    /**
+     * The relay name.
+     *
+     * Implementations can use this for identification purposes (e.g., database
+     * file name, logging).
+     */
     readonly name?: SimpleName;
+    /**
+     * Optional callback to authenticate an {@link OwnerId} with the relay.
+     *
+     * If this callback is not provided, all owners are allowed.
+     *
+     * If provided, the callback receives the OwnerId and should return a promise
+     * that resolves to `true` to allow access, or `false` to deny.
+     *
+     * The callback returns a boolean rather than an error type because error
+     * handling and logging are the responsibility of the callback implementation,
+     * not the relay. This prevents leaking authentication implementation details
+     * into the generic relay interface.
+     *
+     * OwnerId is used for authentication rather than short-lived tokens because
+     * this only controls relay access, not write permissions. Since all data is
+     * encrypted on the relay, OwnerId exposure is safe.
+     *
+     * Owners specify which relays to connect to via {@link TransportConfig}. In
+     * WebSocket-based implementations, this check occurs before accepting the
+     * connection, with the OwnerId typically extracted from the URL path (e.g.,
+     * `ws://localhost:4000/<ownerId>`).
+     *
+     * ### Example
+     *
+     * ```ts
+     * const relay = await createNodeJsRelay(deps)({
+     *   authenticateOwner: async (ownerId) => {
+     *     const isRegistered = await db.checkOwner(ownerId);
+     *     if (!isRegistered) {
+     *       logger.warn("Unauthorized access attempt", { ownerId });
+     *     }
+     *     return isRegistered;
+     *   },
+     * });
+     * ```
+     */
+    readonly authenticateOwner?: (ownerId: OwnerId) => Promise<boolean>;
 }
-export type RelaySqliteStorageDeps = SqliteStorageDeps & TimingSafeEqualDep;
-export declare const createRelayStorage: (deps: RelaySqliteStorageDeps) => (options: CreateSqliteStorageBaseOptions) => Result<Storage, SqliteError>;
+export declare const createRelaySqliteStorage: (deps: SqliteStorageDeps & TimingSafeEqualDep) => (options: CreateSqliteStorageBaseOptions) => Result<Storage, SqliteError>;
+export interface RelayLogger {
+    readonly started: (enableLogging: boolean, port: number) => void;
+    readonly storageError: (error: unknown) => void;
+    readonly upgradeSocketError: (error: Error) => void;
+    readonly invalidOrMissingOwnerIdInUrl: (url: string | undefined) => void;
+    readonly unauthorizedOwner: (ownerId: OwnerId) => void;
+    readonly authenticateOwnerError: (error: unknown) => void;
+    readonly connectionEstablished: (totalConnectionCount: number) => void;
+    readonly connectionWebSocketError: (error: Error) => void;
+    readonly relayOptionSubscribe: (ownerId: OwnerId, getSubscriberCount: LazyValue<number>) => void;
+    readonly relayOptionUnsubscribe: (ownerId: OwnerId, getSubscriberCount: LazyValue<number>) => void;
+    readonly relayOptionBroadcast: (ownerId: OwnerId, broadcastCount: number, subscriberCount: number) => void;
+    readonly messageLength: (messageLength: number) => void;
+    readonly applyProtocolMessageAsRelayError: (error: ProtocolInvalidDataError) => void;
+    readonly responseLength: (responseLength: number) => void;
+    readonly applyProtocolMessageAsRelayUnknownError: (error: unknown) => void;
+    readonly connectionClosed: (totalConnectionCount: number) => void;
+    readonly shuttingDown: () => void;
+    readonly webSocketServerDisposed: () => void;
+    readonly httpServerDisposed: () => void;
+}
+export declare const createRelayLogger: (deps: ConsoleDep) => RelayLogger;
 //# sourceMappingURL=Relay.d.ts.map

package/dist/src/Evolu/Relay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Relay.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Relay.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAW,MAAM,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAO,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EAEL,8BAA8B,EAE9B,iBAAiB,EACjB,OAAO,EACR,MAAM,cAAc,CAAC;AAGtB,MAAM,WAAW,KAAM,SAAQ,UAAU;CAAG;AAE5C,MAAM,WAAW,WAAY,SAAQ,aAAa;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;CAC5B;AAED,MAAM,MAAM,sBAAsB,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAE5E,eAAO,MAAM,kBAAkB,GAC5B,MAAM,sBAAsB,MAC5B,SAAS,8BAA8B,KAAG,MAAM,CAAC,OAAO,EAAE,WAAW,CAiKrE,CAAC"}
+{"version":3,"file":"Relay.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Relay.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAW,MAAM,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAO,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,OAAO,EAAkC,MAAM,YAAY,CAAC;AACrE,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAEL,8BAA8B,EAE9B,iBAAiB,EACjB,OAAO,EACR,MAAM,cAAc,CAAC;AAGtB,MAAM,WAAW,KAAM,SAAQ,UAAU;CAAG;AAE5C,MAAM,WAAW,WAAY,SAAQ,aAAa;IAChD;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACrE;AAED,eAAO,MAAM,wBAAwB,GAClC,MAAM,iBAAiB,GAAG,kBAAkB,MAC5C,SAAS,8BAA8B,KAAG,MAAM,CAAC,OAAO,EAAE,WAAW,CAiKrE,CAAC;AAEJ,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,CAAC,aAAa,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjE,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAChD,QAAQ,CAAC,kBAAkB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACpD,QAAQ,CAAC,4BAA4B,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IACzE,QAAQ,CAAC,iBAAiB,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACvD,QAAQ,CAAC,sBAAsB,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC1D,QAAQ,CAAC,qBAAqB,EAAE,CAAC,oBAAoB,EAAE,MAAM,KAAK,IAAI,CAAC;IACvE,QAAQ,CAAC,wBAAwB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC1D,QAAQ,CAAC,oBAAoB,EAAE,CAC7B,OAAO,EAAE,OAAO,EAChB,kBAAkB,EAAE,SAAS,CAAC,MAAM,CAAC,KAClC,IAAI,CAAC;IACV,QAAQ,CAAC,sBAAsB,EAAE,CAC/B,OAAO,EAAE,OAAO,EAChB,kBAAkB,EAAE,SAAS,CAAC,MAAM,CAAC,KAClC,IAAI,CAAC;IACV,QAAQ,CAAC,oBAAoB,EAAE,CAC7B,OAAO,EAAE,OAAO,EAChB,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,MAAM,KACpB,IAAI,CAAC;IACV,QAAQ,CAAC,aAAa,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,IAAI,CAAC;IACxD,QAAQ,CAAC,gCAAgC,EAAE,CACzC,KAAK,EAAE,wBAAwB,KAC5B,IAAI,CAAC;IACV,QAAQ,CAAC,cAAc,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1D,QAAQ,CAAC,uCAAuC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC3E,QAAQ,CAAC,gBAAgB,EAAE,CAAC,oBAAoB,EAAE,MAAM,KAAK,IAAI,CAAC;IAClE,QAAQ,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC;IAClC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,IAAI,CAAC;IAC7C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,IAAI,CAAC;CACzC;AAED,eAAO,MAAM,iBAAiB,GAAI,MAAM,UAAU,KAAG,WA8FnD,CAAC"}