@evolu/common 6.0.1-preview.28 → 6.0.1-preview.29

package/src/Evolu/Owner.ts

@@ -8,6 +8,7 @@ import {
   Entropy32,
   RandomBytesDep,
 } from "../Crypto.js";
+import { getOrNull } from "../Result.js";
 import {
   brand,
   Id,
@@ -16,12 +17,8 @@ import {
   idToIdBytes,
   Mnemonic,
   NonNegativeInt,
-  PositiveInt,
 } from "../Type.js";
-import { getOrNull } from "../Result.js";
-import type { Timestamp } from "./Timestamp.js";
-import { TimestampBytes } from "./Timestamp.js";
-import type { Storage } from "./Storage.js";
+import type { Storage, EncryptedDbChange } from "./Storage.js";
 
 /**
  * The Owner represents ownership of data in Evolu. Every database change is
@@ -159,6 +156,17 @@ export const createOwner = (secret: OwnerSecret): Owner => ({
  * preserved because it coordinates deletion information across devices. Other
  * devices need to sync the information that an owner was deleted so they can
  * delete their local data as well.
+ *
+ * ### Privacy Considerations
+ *
+ * AppOwner must never be shared with anyone, except for its {@link OwnerId},
+ * which can be used for authorization with
+ * {@link createOwnerWebSocketTransport}. It's safe because OwnerId is
+ * pseudonymous (it can't be assigned to a specific person).
+ *
+ * For data sharing scenarios, use {@link SharedOwner} and
+ * {@link SharedReadonlyOwner} instead, which are designed specifically for
+ * collaborative access.
  */
 export interface AppOwner extends Owner {
   readonly type: "AppOwner";
@@ -294,7 +302,17 @@ export type OwnerTransport = OwnerWebSocketTransport;
 /**
  * WebSocket transport configuration.
  *
- * ### Authentication and Error Handling
+ * ### Authentication via URL
+ *
+ * The {@link OwnerId} is passed as a URL query parameter. While this approach is
+ * generally discouraged for authentication tokens (they get logged), it's safe
+ * here because OwnerId is pseudonymous and used only for access verification -
+ * it provides no ability to read encrypted data or write changes.
+ *
+ * See: [HTTP headers in Websockets client
+ * API](https://stackoverflow.com/questions/4361173/http-headers-in-websockets-client-api/74564827#74564827)
+ *
+ * ### Error Handling
  *
  * When a relay rejects a connection (invalid OwnerId, unauthorized owner, or
  * server error), the browser WebSocket API does not expose the specific HTTP
@@ -317,14 +335,23 @@ export interface OwnerWebSocketTransport {
  * Creates an {@link OwnerWebSocketTransport} for the given relay URL and
  * {@link OwnerId}.
  *
+ * The URL must be a WebSocket base URL without query parameters or fragments
+ * (e.g., `wss://relay.evolu.dev`, not `wss://relay.evolu.dev?foo=bar`). The
+ * function appends the `ownerId` as a query parameter.
+ *
  * ### Example
  *
  * ```ts
+ * // Create transport "wss://relay.evolu.dev?ownerId=..."
  * const transport = createOwnerWebSocketTransport({
  *   url: "wss://relay.evolu.dev",
  *   ownerId: owner.id,
  * });
- * // Result: { type: "WebSocket", url: "wss://relay.evolu.dev?ownerId=..." }
+ *
+ * // Use with createEvolu
+ * const evolu = createEvolu(deps)(Schema, {
+ *   transports: [transport],
+ * });
  * ```
  */
 export const createOwnerWebSocketTransport = (config: {
@@ -355,6 +382,11 @@ export const parseOwnerIdFromOwnerWebSocketTransportUrl = (
   url: string,
 ): OwnerId | null => getOrNull(OwnerId.fromUnknown(url.split("=")[1]));
 
+/** Base interface for all owner errors. */
+export interface BaseOwnerError {
+  readonly ownerId: OwnerId;
+}
+
 /**
  * Usage data for an {@link OwnerId}.
  *
@@ -368,27 +400,44 @@ export interface OwnerUsage {
   /** The {@link Owner} this usage data belongs to. */
   readonly ownerId: OwnerIdBytes;
 
-  /** Total bytes stored in the database. */
-  readonly storedBytes: PositiveInt;
-
-  /** Total bytes received. */
-  readonly receivedBytes: number;
-
-  /** Total bytes sent. */
-  readonly sentBytes: number;
-
   /**
-   * The minimum {@link Timestamp}.
+   * Total logical data bytes stored.
    *
-   * Helps {@link Storage} choose faster algorithms.
-   */
-  readonly firstTimestamp: TimestampBytes | null;
-
-  /**
-   * The maximum {@link Timestamp}.
+   * Measures the size of {@link EncryptedDbChange}s only, excluding
+   * {@link Storage} implementation overhead (with SqliteStorage: indexes,
+   * skiplist columns, etc.). This provides:
    *
-   * Helps {@link Storage} choose faster algorithms. Free relays can use it to
-   * identify inactive accounts for cleanup or archival.
+   * - **Predictable measurement** - same data = same byte count across all
+   *   instances
+   * - **Quota enforcement** - consistent billing/limits independent of storage
+   *   implementation
+   * - **Overhead tracking** - actual Storage size can be compared against this to
+   *   monitor efficiency
    */
-  readonly lastTimestamp: TimestampBytes | null;
+  readonly storedBytes: NonNegativeInt;
+
+  // TODO: Decide how to use receivedBytes and sentBytes.
+  // /** Total bytes received. */
+  // readonly receivedBytes: NonNegativeInt;
+
+  // TODO: Decide how to use sentBytes.
+  // /** Total bytes sent. */
+  // readonly sentBytes: NonNegativeInt;
+
+  // TODO: Decide how to use firstTimestamp.
+  // /**
+  //  * The minimum {@link Timestamp}.
+  //  *
+  //  * Helps {@link Storage} choose faster algorithms.
+  //  */
+  // readonly firstTimestamp: TimestampBytes | null;
+
+  // TODO: Decide how to use lastTimestamp.
+  // /**
+  //  * The maximum {@link Timestamp}.
+  //  *
+  //  * Helps {@link Storage} choose faster algorithms. Free relays can use it to
+  //  * identify inactive accounts for cleanup or archival.
+  //  */
+  // readonly lastTimestamp: TimestampBytes | null;
 }

package/src/Evolu/Protocol.ts

@@ -85,10 +85,10 @@
  *
  * - {@link ProtocolWriteKeyError}: The provided WriteKey is invalid or missing.
  * - {@link ProtocolWriteError}: A serious relay-side write failure occurred.
+ * - {@link ProtocolQuotaError}: Storage or billing quota exceeded.
  * - {@link ProtocolSyncError}: A serious relay-side synchronization failure
  *   occurred.
- * - {@link ProtocolQuotaExceededError}: Storage or billing quota exceeded.
- * - {@link ProtocolUnsupportedVersionError}: Protocol version mismatch.
+ * - {@link ProtocolVersionError}: Protocol version mismatch.
  * - {@link ProtocolInvalidDataError}: The message is malformed or corrupted.
  *
  * All protocol errors except `ProtocolInvalidDataError` include the `OwnerId`
@@ -160,6 +160,19 @@
  * @module
  */
 
+/**
+ * TODO:
+ *
+ * - The client-relay naming convention in functions like
+ *   `applyProtocolMessageAsClient` and `applyProtocolMessageAsRelay` is not
+ *   ideal. In the future, clients will be able to sync directly with each other
+ *   (P2P), making the current naming misleading. Consider using
+ *   initiator/non-initiator terminology instead, and consolidate into a single
+ *   `applyProtocolMessage` function with conditional arguments to reduce code
+ *   duplication.
+ * - ProtocolQuotaError should return storedBytes and actual quota.
+ */
+
 import { Packr } from "msgpackr";
 import { isNonEmptyReadonlyArray, NonEmptyReadonlyArray } from "../Array.js";
 import { assert } from "../Assert.js";
@@ -204,6 +217,7 @@ import {
 } from "../Type.js";
 import { Predicate } from "../Types.js";
 import {
+  BaseOwnerError,
   Owner,
   OwnerId,
   OwnerIdBytes,
@@ -342,36 +356,31 @@ export const ProtocolErrorCode = {
   WriteKeyError: 1,
   /** A code for {@link ProtocolWriteError}. */
   WriteError: 2,
+  /** A code for {@link ProtocolQuotaError}. */
+  QuotaError: 3,
   /** A code for {@link ProtocolSyncError}. */
-  SyncError: 3,
-  /** A code for {@link ProtocolQuotaExceededError}. */
-  QuotaExceededError: 4,
+  SyncError: 4,
 } as const;
 
 type ProtocolErrorCode =
   (typeof ProtocolErrorCode)[keyof typeof ProtocolErrorCode];
 
 export type ProtocolError =
-  | ProtocolUnsupportedVersionError
+  | ProtocolVersionError
   | ProtocolInvalidDataError
   | ProtocolWriteKeyError
   | ProtocolWriteError
   | ProtocolSyncError
-  | ProtocolQuotaExceededError
+  | ProtocolQuotaError
   | ProtocolTimestampMismatchError;
 
-/** Base interface for all protocol errors. */
-export interface ProtocolErrorBase {
-  readonly ownerId: OwnerId;
-}
-
 /**
  * Represents a version mismatch in the Evolu Protocol. Occurs when the
  * initiator and non-initiator are using incompatible protocol versions.
  */
-export interface ProtocolUnsupportedVersionError extends ProtocolErrorBase {
-  readonly type: "ProtocolUnsupportedVersionError";
-  readonly unsupportedVersion: NonNegativeInt;
+export interface ProtocolVersionError extends BaseOwnerError {
+  readonly type: "ProtocolVersionError";
+  readonly version: NonNegativeInt;
   /** Indicates which side is obsolete and should update. */
   readonly isInitiator: boolean;
 }
@@ -384,7 +393,7 @@ export interface ProtocolInvalidDataError {
 }
 
 /** Error when a {@link OwnerWriteKey} is invalid, missing, or fails validation. */
-export interface ProtocolWriteKeyError extends ProtocolErrorBase {
+export interface ProtocolWriteKeyError extends BaseOwnerError {
   readonly type: "ProtocolWriteKeyError";
 }
 
@@ -392,27 +401,31 @@ export interface ProtocolWriteKeyError extends ProtocolErrorBase {
  * 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 {
+export interface ProtocolWriteError extends BaseOwnerError {
   readonly type: "ProtocolWriteError";
 }
 
 /**
- * Error indicating a serious relay-side synchronization failure. Clients should
- * log this error and show a generic sync error to the user.
+ * Error when storage or billing quota is exceeded.
+ *
+ * When relay rejects writes due to quota, the affected device stops syncing
+ * because RBSR requires both sides to converge—if the relay won't accept the
+ * client's data, they can never reach the same state. Only the device with
+ * excess local data is affected. Other devices that haven't exceeded quota can
+ * still sync normally.
+ *
+ * Clients should prompt the user to upgrade their plan.
  */
-export interface ProtocolSyncError extends ProtocolErrorBase {
-  readonly type: "ProtocolSyncError";
+export interface ProtocolQuotaError extends BaseOwnerError {
+  readonly type: "ProtocolQuotaError";
 }
 
 /**
- * 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.
+ * Error indicating a serious relay-side synchronization failure. Clients should
+ * log this error and show a generic sync error to the user.
  */
-export interface ProtocolQuotaExceededError extends ProtocolErrorBase {
-  readonly type: "ProtocolQuotaExceededError";
+export interface ProtocolSyncError extends BaseOwnerError {
+  readonly type: "ProtocolSyncError";
 }
 
 /**
@@ -862,10 +875,10 @@ const createRunLengthEncoder = <T>(
 export interface ApplyProtocolMessageAsClientOptions {
   getWriteKey?: (ownerId: OwnerId) => OwnerWriteKey | null;
 
-  /** For testing purposes only; should not be used in production. */
-  version?: NonNegativeInt;
-
   rangesMaxSize?: ProtocolMessageRangesMaxSize;
+
+  /** For tests only. */
+  version?: NonNegativeInt;
 }
 
 /**
@@ -887,22 +900,23 @@ export const applyProtocolMessageAsClient =
       ApplyProtocolMessageAsClientResult,
       | ProtocolInvalidDataError
       | ProtocolSyncError
-      | ProtocolUnsupportedVersionError
+      | ProtocolVersionError
       | ProtocolWriteError
       | ProtocolWriteKeyError
-      | ProtocolQuotaExceededError
+      | ProtocolQuotaError
     >
   > => {
     // try-catch instead of Result for performance and stacktraces
+    // DEV: Measure it again, I think we should use Result with new Error.
     try {
       const input = createBuffer(inputMessage);
       const [requestedVersion, ownerId] = decodeVersionAndOwner(input);
       const version = options.version ?? protocolVersion;
 
       if (requestedVersion !== version) {
-        return err<ProtocolUnsupportedVersionError>({
-          type: "ProtocolUnsupportedVersionError",
-          unsupportedVersion: requestedVersion,
+        return err<ProtocolVersionError>({
+          type: "ProtocolVersionError",
+          version: requestedVersion,
           isInitiator: version < requestedVersion,
           ownerId,
         });
@@ -929,16 +943,16 @@ export const applyProtocolMessageAsClient =
                 type: "ProtocolWriteError",
                 ownerId,
               });
+            case ProtocolErrorCode.QuotaError:
+              return err<ProtocolQuotaError>({
+                type: "ProtocolQuotaError",
+                ownerId,
+              });
             case ProtocolErrorCode.SyncError:
               return err<ProtocolSyncError>({
                 type: "ProtocolSyncError",
                 ownerId,
               });
-            case ProtocolErrorCode.QuotaExceededError:
-              return err<ProtocolQuotaExceededError>({
-                type: "ProtocolQuotaExceededError",
-                ownerId,
-              });
             default:
               throw new ProtocolDecodeError(
                 `Invalid ProtocolErrorCode: ${errorCode}`,
@@ -950,11 +964,13 @@ export const applyProtocolMessageAsClient =
       const messages = decodeMessages(input);
       const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
 
-      if (
-        isNonEmptyReadonlyArray(messages) &&
-        !(await deps.storage.writeMessages(ownerIdBytes, messages))
-      ) {
-        return ok({ type: "no-response" });
+      if (isNonEmptyReadonlyArray(messages)) {
+        const writeResult = await deps.storage.writeMessages(
+          ownerIdBytes,
+          messages,
+        );
+        // Errors are handled by the Storage. Here we just stop syncing.
+        if (!writeResult.ok) return ok({ type: "no-response" });
       }
 
       // Now: No writeKey, no sync.
@@ -1033,12 +1049,13 @@ export const applyProtocolMessageAsRelay =
   async (
     inputMessage: Uint8Array,
     options: ApplyProtocolMessageAsRelayOptions = {},
-    /** For testing purposes only; should not be used in production. */
+    /** For tests only. */
     version = protocolVersion,
   ): Promise<
     Result<ApplyProtocolMessageAsRelayResult, ProtocolInvalidDataError>
   > => {
     // try-catch instead of Result for performance and stacktraces
+    // DEV: Measure it again, I think we should use Result with new Error.
     try {
       const input = createBuffer(inputMessage);
       const [requestedVersion, ownerId] = decodeVersionAndOwner(input);
@@ -1104,17 +1121,39 @@ export const applyProtocolMessageAsRelay =
           });
         }
 
+        const writeResult = await deps.storage.writeMessages(
+          ownerIdBytes,
+          messages,
+        );
+
+        if (!writeResult.ok) {
+          const errorCode =
+            writeResult.error.type === "StorageWriteError"
+              ? ProtocolErrorCode.WriteError
+              : ProtocolErrorCode.QuotaError;
+          const message = createProtocolMessageBuffer(ownerId, {
+            messageType: MessageType.Response,
+            errorCode,
+          }).unwrap();
+          return ok({ type: "response", message });
+        }
+
         /**
-         * Broadcast messages to all subscribed devices. This ensures real-time
+         * Broadcast messages to all subscribed owners for real-time
          * synchronization between clients.
          *
+         * Messages are only broadcasted after successful write to ensure
+         * devices that can still sync aren't affected by quota errors, and to
+         * prevent using a half-working relay service (broadcasting without
+         * persistence).
+         *
          * When a relay's database is deleted or clients migrate to a new relay
          * (without data migration), clients will sync their data to the relay,
          * and the relay will broadcast those messages to other connected
          * clients. Those clients may receive messages they already have, but
-         * this is safe because `applyMessages` is idempotent. As the relay
-         * becomes more synchronized with clients over time, fewer duplicate
-         * messages will be broadcasted.
+         * this is safe because Evolu sync is idempotent. As the relay becomes
+         * more synchronized with clients over time, fewer duplicate messages
+         * will be broadcasted.
          */
         if (options.broadcast) {
           const broadcastBuffer = createProtocolMessageBuffer(ownerId, {
@@ -1128,16 +1167,6 @@ export const applyProtocolMessageAsRelay =
           }
           options.broadcast(ownerId, broadcastBuffer.unwrap());
         }
-
-        if (!(await deps.storage.writeMessages(ownerIdBytes, messages))) {
-          return ok({
-            type: "response",
-            message: createProtocolMessageBuffer(ownerId, {
-              messageType: MessageType.Response,
-              errorCode: ProtocolErrorCode.WriteError,
-            }).unwrap(),
-          });
-        }
       }
 
       const ranges = decodeRanges(input);