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

package/dist/index.js

@@ -21,6 +21,20 @@ var SYNC_STATUSES = [
   "error",
   "schema-mismatch"
 ];
+var MemoryRejectedOperationStorage = class {
+  rejected = /* @__PURE__ */ new Map();
+  async record(rejected) {
+    this.rejected.set(rejected.operationId, rejected);
+  }
+  async list() {
+    return [...this.rejected.values()];
+  }
+  async remove(operationIds) {
+    for (const id of operationIds) {
+      this.rejected.delete(id);
+    }
+  }
+};
 var ScopeViolationError = class extends KoraError {
   constructor(operationId, collection, scope, message) {
     super(
@@ -218,10 +232,18 @@ function isSyncMessage(value) {
       return isAcknowledgmentMessage(value);
     case "error":
       return isErrorMessage(value);
+    case "operation-rejected":
+      return isOperationRejectedMessage(value);
     case "awareness-update":
       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;
   }
@@ -251,6 +273,11 @@ function isErrorMessage(value) {
   const msg = value;
   return msg.type === "error" && typeof msg.messageId === "string" && typeof msg.code === "string" && typeof msg.message === "string" && typeof msg.retriable === "boolean";
 }
+function isOperationRejectedMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const msg = value;
+  return msg.type === "operation-rejected" && typeof msg.messageId === "string" && typeof msg.operationId === "string" && typeof msg.collection === "string" && typeof msg.recordId === "string" && typeof msg.code === "string" && typeof msg.message === "string" && typeof msg.retriable === "boolean";
+}
 function isAwarenessUpdateMessage(value) {
   if (typeof value !== "object" || value === null) return false;
   const msg = value;
@@ -261,6 +288,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
 import { SyncError } from "@korajs/core";
@@ -501,7 +543,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 {
@@ -526,12 +569,45 @@ function toProtoEnvelope(message) {
         errorMessage: message.message,
         retriable: message.retriable
       };
+    case "operation-rejected":
+      return {
+        type: message.type,
+        messageId: message.messageId,
+        operationId: message.operationId,
+        collection: message.collection,
+        recordId: message.recordId,
+        errorCode: message.code,
+        errorMessage: message.message,
+        retriable: message.retriable
+      };
     case "awareness-update":
     case "yjs-doc-update":
       return {
         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) {
@@ -564,7 +640,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 {
@@ -589,6 +666,38 @@ function fromProtoEnvelope(envelope) {
         message: envelope.errorMessage ?? "Unknown error",
         retriable: envelope.retriable ?? false
       };
+    case "operation-rejected":
+      return {
+        type: "operation-rejected",
+        messageId: envelope.messageId,
+        operationId: envelope.operationId ?? "",
+        collection: envelope.collection ?? "",
+        recordId: envelope.recordId ?? "",
+        code: envelope.errorCode ?? "REJECTED",
+        message: envelope.errorMessage ?? "",
+        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 SyncError("Failed to decode sync message: unknown protobuf type", {
         type: envelope.type
@@ -734,6 +843,20 @@ 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);
+  if (envelope.operationId && envelope.operationId.length > 0)
+    writer.uint32(210).string(envelope.operationId);
+  if (envelope.collection && envelope.collection.length > 0)
+    writer.uint32(218).string(envelope.collection);
+  if (envelope.recordId && envelope.recordId.length > 0)
+    writer.uint32(226).string(envelope.recordId);
   return writer.finish();
 }
 function decodeEnvelope(bytes) {
@@ -805,6 +928,30 @@ 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;
+      case 26:
+        envelope.operationId = reader.string();
+        break;
+      case 27:
+        envelope.collection = reader.string();
+        break;
+      case 28:
+        envelope.recordId = reader.string();
+        break;
       default:
         reader.skipType(tag & 7);
     }
@@ -1612,6 +1759,95 @@ var AwarenessManager = class {
   }
 };
 
+// src/blob/blob-chunk-channel.ts
+import { generateUUIDv7 } from "@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: generateUUIDv7(),
+        requestId: message.requestId,
+        hash: message.hash
+      });
+      return;
+    }
+    if (message.type === "blob-chunk-push") {
+      this.onSend({
+        type: "blob-chunk-push",
+        messageId: generateUUIDv7(),
+        hash: message.hash,
+        bytes: encodeBlobChunkBytes(message.bytes)
+      });
+      return;
+    }
+    this.onSend({
+      type: "blob-chunk-response",
+      messageId: 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;
@@ -2055,7 +2291,7 @@ var SyncMetricsCollector = class {
 };
 
 // src/richtext/richtext-doc-channel.ts
-import { generateUUIDv7 } from "@korajs/core";
+import { generateUUIDv7 as generateUUIDv72 } from "@korajs/core";
 
 // src/richtext/doc-channel-wire.ts
 function encodeYjsUpdate(update) {
@@ -2134,7 +2370,7 @@ var RichtextDocChannel = class {
     }
     this.onSend({
       type: "yjs-doc-update",
-      messageId: generateUUIDv7(),
+      messageId: generateUUIDv72(),
       collection,
       recordId,
       field,
@@ -2304,6 +2540,37 @@ var OutboundQueue = class {
   get isInitialized() {
     return this.initialized;
   }
+  /**
+   * Remove a single operation the server permanently rejected — from the queue,
+   * from any in-flight batch, and from durable storage — so a later batch ack or
+   * a reconnect `returnBatch` can never resend or resurrect it. Returns the
+   * removed operation so the caller can record it in a durable rejected store,
+   * or null if it was not present (already acknowledged and removed).
+   */
+  async reject(opId) {
+    let removed = null;
+    for (const [batchId, ops] of this.inFlight) {
+      const idx = ops.findIndex((op) => op.id === opId);
+      if (idx !== -1) {
+        removed = ops[idx] ?? null;
+        ops.splice(idx, 1);
+        if (ops.length === 0) {
+          this.inFlight.delete(batchId);
+        }
+        break;
+      }
+    }
+    if (!removed) {
+      const idx = this.queue.findIndex((op) => op.id === opId);
+      if (idx !== -1) {
+        removed = this.queue[idx] ?? null;
+        this.queue.splice(idx, 1);
+      }
+    }
+    this.seen.delete(opId);
+    await this.storage.dequeue([opId]);
+    return removed;
+  }
   /**
    * Remove operations by id from queue and persistent storage.
    * Used when ops were already sent during handshake delta exchange.
@@ -2343,10 +2610,12 @@ var SyncEngine = class {
   serializer;
   emitter;
   outboundQueue;
+  rejectedStorage;
   batchSize;
   encryptor;
   awarenessManager;
   richtextDocChannel;
+  blobChunkChannel;
   metricsCollector;
   syncState;
   remoteVector = /* @__PURE__ */ new Map();
@@ -2361,6 +2630,7 @@ var SyncEngine = class {
   schemaBlocked = false;
   clockBlocked = false;
   clockSkewMs = null;
+  blobStorageEnabled = false;
   // Track delta exchange state
   deltaBatchesReceived = 0;
   deltaReceiveComplete = false;
@@ -2393,6 +2663,7 @@ var SyncEngine = class {
     this.activeScope = options.config.scopeMap;
     const queueStorage = options.queueStorage ?? new MemoryQueueStorage();
     this.outboundQueue = new OutboundQueue(queueStorage);
+    this.rejectedStorage = options.rejectedStorage ?? new MemoryRejectedOperationStorage();
     this.metricsCollector = new SyncMetricsCollector(options.metricsConfig);
     if (this.emitter) {
       this.metricsCollector.attachEmitter(this.emitter);
@@ -2409,6 +2680,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 = {
@@ -2722,6 +3001,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) {
@@ -2741,12 +3045,20 @@ var SyncEngine = class {
       case "error":
         this.handleError(message);
         break;
+      case "operation-rejected":
+        await this.handleOperationRejected(message);
+        break;
       case "awareness-update":
         this.handleAwarenessUpdate(message);
         break;
       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) {
@@ -2779,6 +3091,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) {
@@ -3072,6 +3385,50 @@ var SyncEngine = class {
     this.emitter?.emit({ type: "sync:disconnected", reason: msg.message });
     this.transitionTo("disconnected");
   }
+  /**
+   * Handle a per-operation rejection: divert the op out of the pending outbound
+   * queue (so it is never retried or resurrected on reconnect), record it in the
+   * durable rejected store (so it is kept and explainable), and emit an event so
+   * the app can reconcile. Unlike {@link handleError}, this is a normal per-op
+   * signal, so the connection stays up.
+   */
+  async handleOperationRejected(msg) {
+    await this.outboundQueue.reject(msg.operationId);
+    await this.rejectedStorage.record({
+      operationId: msg.operationId,
+      collection: msg.collection,
+      recordId: msg.recordId,
+      code: msg.code,
+      message: msg.message,
+      retriable: msg.retriable,
+      rejectedAt: Date.now()
+    });
+    await this.refreshPendingCount();
+    this.emitter?.emit({
+      type: "sync:operation-rejected",
+      operationId: msg.operationId,
+      collection: msg.collection,
+      recordId: msg.recordId,
+      code: msg.code,
+      message: msg.message,
+      retriable: msg.retriable
+    });
+  }
+  /**
+   * Every operation the server rejected that has not yet been reconciled. The app
+   * uses this (alongside the `sync:operation-rejected` event) to surface failed
+   * submissions and decide whether to roll back or resubmit.
+   */
+  getRejectedOperations() {
+    return this.rejectedStorage.list();
+  }
+  /**
+   * Forget rejected operations by id once the app has reconciled them (rolled the
+   * optimistic write back or resubmitted a corrected op).
+   */
+  clearRejectedOperations(operationIds) {
+    return this.rejectedStorage.remove(operationIds);
+  }
   async checkDeltaComplete() {
     if (!this.deltaSendComplete || !this.deltaReceiveComplete) {
       return;
@@ -4126,6 +4483,7 @@ function subscribeRemoteAwarenessStates(awareness, listener) {
 }
 export {
   AwarenessManager,
+  BlobChunkChannel,
   ChaosTransport,
   ConnectionMonitor,
   DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD,
@@ -4135,6 +4493,7 @@ export {
   InvalidScopeError,
   JsonMessageSerializer,
   KeyDerivationError,
+  MemoryRejectedOperationStorage,
   NegotiatedMessageSerializer,
   OFFLINE_SYNC_STATUS,
   OutboundQueue,
@@ -4150,11 +4509,13 @@ export {
   WebSocketTransport,
   createDeltaCursorFromBatch,
   createSyncStatusController,
+  decodeBlobChunkBytes,
   decodeDeltaCursor,
   decodeYjsUpdate,
   dedupeQuerySubsets,
   deriveKey,
   deriveVersionedKey,
+  encodeBlobChunkBytes,
   encodeDeltaCursor,
   encodeYjsUpdate,
   filterOperationsByScope,
@@ -4162,12 +4523,16 @@ export {
   getRemoteAwarenessStates,
   isAcknowledgmentMessage,
   isAwarenessUpdateMessage,
+  isBlobChunkPushMessage,
+  isBlobChunkRequestMessage,
+  isBlobChunkResponseMessage,
   isClientSchemaVersionSupported,
   isEncryptedPayload,
   isErrorMessage,
   isHandshakeMessage,
   isHandshakeResponseMessage,
   isOperationBatchMessage,
+  isOperationRejectedMessage,
   isSchemaMismatchReject,
   isSyncMessage,
   isYjsDocUpdateMessage,