@korajs/sync 1.0.0-beta.0 → 1.0.0-beta.1

package/dist/index.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AwarenessManager: () => AwarenessManager,
+  BlobChunkChannel: () => BlobChunkChannel,
   ChaosTransport: () => ChaosTransport,
   ConnectionMonitor: () => ConnectionMonitor,
   DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD: () => DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD,
@@ -55,11 +56,13 @@ __export(index_exports, {
   WebSocketTransport: () => WebSocketTransport,
   createDeltaCursorFromBatch: () => createDeltaCursorFromBatch,
   createSyncStatusController: () => createSyncStatusController,
+  decodeBlobChunkBytes: () => decodeBlobChunkBytes,
   decodeDeltaCursor: () => decodeDeltaCursor,
   decodeYjsUpdate: () => decodeYjsUpdate,
   dedupeQuerySubsets: () => dedupeQuerySubsets,
   deriveKey: () => deriveKey,
   deriveVersionedKey: () => deriveVersionedKey,
+  encodeBlobChunkBytes: () => encodeBlobChunkBytes,
   encodeDeltaCursor: () => encodeDeltaCursor,
   encodeYjsUpdate: () => encodeYjsUpdate,
   filterOperationsByScope: () => filterOperationsByScope,
@@ -67,6 +70,9 @@ __export(index_exports, {
   getRemoteAwarenessStates: () => getRemoteAwarenessStates,
   isAcknowledgmentMessage: () => isAcknowledgmentMessage,
   isAwarenessUpdateMessage: () => isAwarenessUpdateMessage,
+  isBlobChunkPushMessage: () => isBlobChunkPushMessage,
+  isBlobChunkRequestMessage: () => isBlobChunkRequestMessage,
+  isBlobChunkResponseMessage: () => isBlobChunkResponseMessage,
   isClientSchemaVersionSupported: () => isClientSchemaVersionSupported,
   isEncryptedPayload: () => isEncryptedPayload,
   isErrorMessage: () => isErrorMessage,
@@ -306,6 +312,12 @@ function isSyncMessage(value) {
       return isAwarenessUpdateMessage(value);
     case "yjs-doc-update":
       return isYjsDocUpdateMessage(value);
+    case "blob-chunk-request":
+      return isBlobChunkRequestMessage(value);
+    case "blob-chunk-response":
+      return isBlobChunkResponseMessage(value);
+    case "blob-chunk-push":
+      return isBlobChunkPushMessage(value);
     default:
       return false;
   }
@@ -345,6 +357,21 @@ function isYjsDocUpdateMessage(value) {
   const msg = value;
   return msg.type === "yjs-doc-update" && typeof msg.messageId === "string" && typeof msg.collection === "string" && typeof msg.recordId === "string" && typeof msg.field === "string" && typeof msg.update === "string";
 }
+function isBlobChunkRequestMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const msg = value;
+  return msg.type === "blob-chunk-request" && typeof msg.messageId === "string" && typeof msg.requestId === "string" && typeof msg.hash === "string";
+}
+function isBlobChunkResponseMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const msg = value;
+  return msg.type === "blob-chunk-response" && typeof msg.messageId === "string" && typeof msg.requestId === "string" && (typeof msg.bytes === "string" || msg.bytes === null);
+}
+function isBlobChunkPushMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const msg = value;
+  return msg.type === "blob-chunk-push" && typeof msg.messageId === "string" && typeof msg.hash === "string" && typeof msg.bytes === "string";
+}
 
 // src/protocol/serializer.ts
 var import_core2 = require("@korajs/core");
@@ -585,7 +612,8 @@ function toProtoEnvelope(message) {
         accepted: message.accepted,
         rejectReason: message.rejectReason,
         selectedWireFormat: message.selectedWireFormat,
-        serverTime: message.serverTime
+        serverTime: message.serverTime,
+        blobStorageEnabled: message.blobStorageEnabled
       };
     case "operation-batch":
       return {
@@ -616,6 +644,28 @@ function toProtoEnvelope(message) {
         type: message.type,
         messageId: message.messageId
       };
+    case "blob-chunk-request":
+      return {
+        type: message.type,
+        messageId: message.messageId,
+        requestId: message.requestId,
+        hash: message.hash
+      };
+    case "blob-chunk-response":
+      return {
+        type: message.type,
+        messageId: message.messageId,
+        requestId: message.requestId,
+        hasBytes: message.bytes !== null,
+        ...message.bytes !== null ? { chunkBytes: message.bytes } : {}
+      };
+    case "blob-chunk-push":
+      return {
+        type: message.type,
+        messageId: message.messageId,
+        hash: message.hash,
+        chunkBytes: message.bytes
+      };
   }
 }
 function fromProtoEnvelope(envelope) {
@@ -648,7 +698,8 @@ function fromProtoEnvelope(envelope) {
         selectedWireFormat: envelope.selectedWireFormat === "json" || envelope.selectedWireFormat === "protobuf" ? envelope.selectedWireFormat : void 0,
         // Preserve the server's wall-clock time so clock-skew detection and
         // automatic timestamp rebase work over the protobuf wire, not just JSON.
-        ...envelope.serverTime !== void 0 ? { serverTime: envelope.serverTime } : {}
+        ...envelope.serverTime !== void 0 ? { serverTime: envelope.serverTime } : {},
+        ...envelope.blobStorageEnabled !== void 0 ? { blobStorageEnabled: envelope.blobStorageEnabled } : {}
       };
     case "operation-batch":
       return {
@@ -673,6 +724,27 @@ function fromProtoEnvelope(envelope) {
         message: envelope.errorMessage ?? "Unknown error",
         retriable: envelope.retriable ?? false
       };
+    case "blob-chunk-request":
+      return {
+        type: "blob-chunk-request",
+        messageId: envelope.messageId,
+        requestId: envelope.requestId ?? "",
+        hash: envelope.hash ?? ""
+      };
+    case "blob-chunk-response":
+      return {
+        type: "blob-chunk-response",
+        messageId: envelope.messageId,
+        requestId: envelope.requestId ?? "",
+        bytes: envelope.hasBytes ? envelope.chunkBytes ?? "" : null
+      };
+    case "blob-chunk-push":
+      return {
+        type: "blob-chunk-push",
+        messageId: envelope.messageId,
+        hash: envelope.hash ?? "",
+        bytes: envelope.chunkBytes ?? ""
+      };
     default:
       throw new import_core2.SyncError("Failed to decode sync message: unknown protobuf type", {
         type: envelope.type
@@ -818,6 +890,14 @@ function encodeEnvelope(envelope) {
   }
   if (envelope.retriable !== void 0) writer.uint32(144).bool(envelope.retriable);
   if (envelope.serverTime !== void 0) writer.uint32(152).int64(envelope.serverTime);
+  if (envelope.requestId && envelope.requestId.length > 0)
+    writer.uint32(162).string(envelope.requestId);
+  if (envelope.hash && envelope.hash.length > 0) writer.uint32(170).string(envelope.hash);
+  if (envelope.chunkBytes && envelope.chunkBytes.length > 0)
+    writer.uint32(178).string(envelope.chunkBytes);
+  if (envelope.hasBytes !== void 0) writer.uint32(184).bool(envelope.hasBytes);
+  if (envelope.blobStorageEnabled !== void 0)
+    writer.uint32(200).bool(envelope.blobStorageEnabled);
   return writer.finish();
 }
 function decodeEnvelope(bytes) {
@@ -889,6 +969,21 @@ function decodeEnvelope(bytes) {
       case 19:
         envelope.serverTime = longToNumber(reader.int64());
         break;
+      case 20:
+        envelope.requestId = reader.string();
+        break;
+      case 21:
+        envelope.hash = reader.string();
+        break;
+      case 22:
+        envelope.chunkBytes = reader.string();
+        break;
+      case 23:
+        envelope.hasBytes = reader.bool();
+        break;
+      case 25:
+        envelope.blobStorageEnabled = reader.bool();
+        break;
       default:
         reader.skipType(tag & 7);
     }
@@ -1480,7 +1575,7 @@ var ChaosTransport = class {
 };
 
 // src/engine/sync-engine.ts
-var import_core6 = require("@korajs/core");
+var import_core7 = require("@korajs/core");
 var import_internal2 = require("@korajs/core/internal");
 
 // src/awareness/awareness-manager.ts
@@ -1689,6 +1784,95 @@ var AwarenessManager = class {
   }
 };
 
+// src/blob/blob-chunk-channel.ts
+var import_core5 = require("@korajs/core");
+function encodeBlobChunkBytes(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function decodeBlobChunkBytes(encoded) {
+  const binary = atob(encoded);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    out[i] = binary.charCodeAt(i);
+  }
+  return out;
+}
+var BlobChunkChannel = class {
+  onSend;
+  handlers = /* @__PURE__ */ new Set();
+  constructor(options) {
+    this.onSend = options?.onSend ?? null;
+  }
+  /**
+   * Send a blob-chunk message to the peer. Response bytes are base64-encoded
+   * onto the wire here; callers pass a `Uint8Array`.
+   */
+  send(message) {
+    if (!this.onSend) {
+      return;
+    }
+    if (message.type === "blob-chunk-request") {
+      this.onSend({
+        type: "blob-chunk-request",
+        messageId: (0, import_core5.generateUUIDv7)(),
+        requestId: message.requestId,
+        hash: message.hash
+      });
+      return;
+    }
+    if (message.type === "blob-chunk-push") {
+      this.onSend({
+        type: "blob-chunk-push",
+        messageId: (0, import_core5.generateUUIDv7)(),
+        hash: message.hash,
+        bytes: encodeBlobChunkBytes(message.bytes)
+      });
+      return;
+    }
+    this.onSend({
+      type: "blob-chunk-response",
+      messageId: (0, import_core5.generateUUIDv7)(),
+      requestId: message.requestId,
+      bytes: message.bytes === null ? null : encodeBlobChunkBytes(message.bytes)
+    });
+  }
+  /**
+   * Register a handler for inbound blob-chunk messages. Multiple handlers are
+   * allowed; each receives every delivered message.
+   */
+  onMessage(handler) {
+    this.handlers.add(handler);
+    return () => {
+      this.handlers.delete(handler);
+    };
+  }
+  /**
+   * Deliver an inbound wire message to registered handlers, decoding response
+   * bytes from base64 back to a `Uint8Array` first.
+   */
+  deliver(message) {
+    if (this.handlers.size === 0) {
+      return;
+    }
+    const decoded = message.type === "blob-chunk-request" ? { type: "blob-chunk-request", requestId: message.requestId, hash: message.hash } : message.type === "blob-chunk-push" ? {
+      type: "blob-chunk-push",
+      hash: message.hash,
+      bytes: decodeBlobChunkBytes(message.bytes)
+    } : {
+      type: "blob-chunk-response",
+      requestId: message.requestId,
+      bytes: message.bytes === null ? null : decodeBlobChunkBytes(message.bytes)
+    };
+    for (const handler of this.handlers) {
+      handler(decoded);
+    }
+  }
+};
+
 // src/diagnostics/bandwidth-estimator.ts
 var BandwidthEstimator = class {
   maxSamples;
@@ -2132,7 +2316,7 @@ var SyncMetricsCollector = class {
 };
 
 // src/richtext/richtext-doc-channel.ts
-var import_core5 = require("@korajs/core");
+var import_core6 = require("@korajs/core");
 
 // src/richtext/doc-channel-wire.ts
 function encodeYjsUpdate(update) {
@@ -2211,7 +2395,7 @@ var RichtextDocChannel = class {
     }
     this.onSend({
       type: "yjs-doc-update",
-      messageId: (0, import_core5.generateUUIDv7)(),
+      messageId: (0, import_core6.generateUUIDv7)(),
       collection,
       recordId,
       field,
@@ -2443,6 +2627,7 @@ var SyncEngine = class {
   encryptor;
   awarenessManager;
   richtextDocChannel;
+  blobChunkChannel;
   metricsCollector;
   syncState;
   remoteVector = /* @__PURE__ */ new Map();
@@ -2457,6 +2642,7 @@ var SyncEngine = class {
   schemaBlocked = false;
   clockBlocked = false;
   clockSkewMs = null;
+  blobStorageEnabled = false;
   // Track delta exchange state
   deltaBatchesReceived = 0;
   deltaReceiveComplete = false;
@@ -2505,6 +2691,14 @@ var SyncEngine = class {
         this.transport.send(message);
       }
     });
+    this.blobChunkChannel = new BlobChunkChannel({
+      onSend: (message) => {
+        if (this.state !== "streaming") {
+          return;
+        }
+        this.transport.send(message);
+      }
+    });
     this.awarenessManager.onSend((message) => {
       if (this.state !== "streaming") return;
       const wireMessage = {
@@ -2521,7 +2715,7 @@ var SyncEngine = class {
    */
   async start() {
     if (this.state !== "disconnected") {
-      throw new import_core6.SyncError("Cannot start sync engine: not in disconnected state", {
+      throw new import_core7.SyncError("Cannot start sync engine: not in disconnected state", {
         currentState: this.state
       });
     }
@@ -2538,7 +2732,7 @@ var SyncEngine = class {
     this.transport.onClose((reason) => this.handleTransportClose(reason));
     this.transport.onError((err) => this.handleTransportError(err));
     if (this.schemaBlocked) {
-      throw new import_core6.SyncError(
+      throw new import_core7.SyncError(
         "Sync is blocked due to schema version mismatch. Upgrade the app schema or align sync.schemaVersion with the server.",
         { code: "SCHEMA_MISMATCH_BLOCKED" }
       );
@@ -2708,7 +2902,7 @@ var SyncEngine = class {
     return this.getStatus().pendingOperations;
   }
   emitApplyFailure(op, result, overrides) {
-    const reason = (0, import_core6.defaultApplyFailureReason)(result, overrides);
+    const reason = (0, import_core7.defaultApplyFailureReason)(result, overrides);
     this.emitter?.emit({
       type: "sync:apply-failed",
       operationId: op.id,
@@ -2818,6 +3012,31 @@ var SyncEngine = class {
   getRichtextDocChannel() {
     return this.richtextDocChannel;
   }
+  /**
+   * Side channel for out-of-band blob chunk transfer over the sync connection.
+   * The app layer bridges this to a `ChunkMessagePort` to pull/serve blob bytes.
+   */
+  getBlobChunkChannel() {
+    return this.blobChunkChannel;
+  }
+  /**
+   * Whether the connected server persists blob bytes centrally (learned from the
+   * handshake response). When true, the app uploads the bytes behind `blob`
+   * fields so they stay available after the authoring device goes offline.
+   */
+  isBlobStorageEnabled() {
+    return this.blobStorageEnabled;
+  }
+  /**
+   * Upload a blob chunk (or manifest) to the server for central persistence.
+   * A no-op unless connected and the server advertised blob storage.
+   */
+  uploadBlobChunk(hash, bytes) {
+    if (this.state !== "streaming" || !this.blobStorageEnabled) {
+      return;
+    }
+    this.blobChunkChannel.send({ type: "blob-chunk-push", hash, bytes });
+  }
   // --- Private methods ---
   messageChain = Promise.resolve();
   enqueueMessage(message) {
@@ -2843,6 +3062,11 @@ var SyncEngine = class {
       case "yjs-doc-update":
         this.richtextDocChannel.deliver(message);
         break;
+      case "blob-chunk-request":
+      case "blob-chunk-response":
+      case "blob-chunk-push":
+        this.blobChunkChannel.deliver(message);
+        break;
     }
   }
   handleMessageFailure(error) {
@@ -2875,6 +3099,7 @@ var SyncEngine = class {
   }
   async handleHandshakeResponse(msg) {
     if (this.state !== "handshaking") return;
+    this.blobStorageEnabled = msg.blobStorageEnabled === true;
     if (typeof msg.serverTime === "number") {
       this.evaluateClockSkew(msg.serverTime);
       if (this.clockBlocked) {
@@ -3059,7 +3284,7 @@ var SyncEngine = class {
     const targetSchemaVersion = this.config.schemaVersion ?? DEFAULT_SCHEMA_VERSION;
     const transforms = this.config.operationTransforms ?? [];
     for (const op of inScopeOps) {
-      const transformed = transforms.length > 0 ? (0, import_core6.applyOperationTransforms)(op, targetSchemaVersion, transforms) : op;
+      const transformed = transforms.length > 0 ? (0, import_core7.applyOperationTransforms)(op, targetSchemaVersion, transforms) : op;
       if (transformed === null) {
         continue;
       }
@@ -3069,20 +3294,20 @@ var SyncEngine = class {
           this.emitApplyFailure(transformed, result);
         }
       } catch (error) {
-        if (error instanceof import_core6.ClockDriftError) {
+        if (error instanceof import_core7.ClockDriftError) {
           this.emitApplyFailure(transformed, "rejected", {
-            code: import_core6.APPLY_FAILURE_CODES.CLOCK_DRIFT,
+            code: import_core7.APPLY_FAILURE_CODES.CLOCK_DRIFT,
             message: error.message,
             retriable: false
           });
           continue;
         }
         const message = error instanceof Error ? error.message : "Apply failed";
-        const code = error instanceof import_core6.SyncError ? error.code : error instanceof import_core6.KoraError ? error.code : error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : import_core6.APPLY_FAILURE_CODES.APPLY_FAILED;
+        const code = error instanceof import_core7.SyncError ? error.code : error instanceof import_core7.KoraError ? error.code : error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : import_core7.APPLY_FAILURE_CODES.APPLY_FAILED;
         this.emitApplyFailure(transformed, "rejected", {
           code,
           message,
-          retriable: code !== import_core6.APPLY_FAILURE_CODES.REFERENTIAL_INTEGRITY
+          retriable: code !== import_core7.APPLY_FAILURE_CODES.REFERENTIAL_INTEGRITY
         });
       }
     }
@@ -3352,7 +3577,7 @@ var SyncEngine = class {
   transitionTo(newState) {
     const validTargets = VALID_TRANSITIONS[this.state];
     if (!validTargets.includes(newState)) {
-      throw new import_core6.SyncError(`Invalid sync state transition: ${this.state} \u2192 ${newState}`, {
+      throw new import_core7.SyncError(`Invalid sync state transition: ${this.state} \u2192 ${newState}`, {
         from: this.state,
         to: newState
       });
@@ -3634,11 +3859,11 @@ var ReconnectionManager = class {
 };
 
 // src/encryption/sync-encryptor.ts
-var import_core8 = require("@korajs/core");
+var import_core9 = require("@korajs/core");
 
 // src/encryption/key-derivation.ts
-var import_core7 = require("@korajs/core");
-var KeyDerivationError = class extends import_core7.SyncError {
+var import_core8 = require("@korajs/core");
+var KeyDerivationError = class extends import_core8.SyncError {
   constructor(message, context) {
     super(message, { ...context, errorType: "KEY_DERIVATION_ERROR" });
     this.name = "KeyDerivationError";
@@ -3720,13 +3945,13 @@ async function deriveVersionedKey(passphrase, version, salt, iterations = DEFAUL
 }
 
 // src/encryption/sync-encryptor.ts
-var EncryptionError = class extends import_core8.SyncError {
+var EncryptionError = class extends import_core9.SyncError {
   constructor(message, context) {
     super(message, { ...context, errorType: "ENCRYPTION_ERROR" });
     this.name = "EncryptionError";
   }
 };
-var DecryptionError = class extends import_core8.SyncError {
+var DecryptionError = class extends import_core9.SyncError {
   constructor(message, context) {
     super(message, { ...context, errorType: "DECRYPTION_ERROR" });
     this.name = "DecryptionError";
@@ -4223,6 +4448,7 @@ function subscribeRemoteAwarenessStates(awareness, listener) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AwarenessManager,
+  BlobChunkChannel,
   ChaosTransport,
   ConnectionMonitor,
   DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD,
@@ -4247,11 +4473,13 @@ function subscribeRemoteAwarenessStates(awareness, listener) {
   WebSocketTransport,
   createDeltaCursorFromBatch,
   createSyncStatusController,
+  decodeBlobChunkBytes,
   decodeDeltaCursor,
   decodeYjsUpdate,
   dedupeQuerySubsets,
   deriveKey,
   deriveVersionedKey,
+  encodeBlobChunkBytes,
   encodeDeltaCursor,
   encodeYjsUpdate,
   filterOperationsByScope,
@@ -4259,6 +4487,9 @@ function subscribeRemoteAwarenessStates(awareness, listener) {
   getRemoteAwarenessStates,
   isAcknowledgmentMessage,
   isAwarenessUpdateMessage,
+  isBlobChunkPushMessage,
+  isBlobChunkRequestMessage,
+  isBlobChunkResponseMessage,
   isClientSchemaVersionSupported,
   isEncryptedPayload,
   isErrorMessage,