@waku/sds 0.0.4-383e0b2.0 → 0.0.4-4c18ca2.0

package/src/message_channel/message_channel.ts

@@ -1,6 +1,7 @@
 import { TypedEventEmitter } from "@libp2p/interface";
 import { sha256 } from "@noble/hashes/sha256";
 import { bytesToHex } from "@noble/hashes/utils";
+import { Logger } from "@waku/utils";
 
 import { DefaultBloomFilter } from "../bloom_filter/bloom.js";
 
@@ -21,6 +22,8 @@ export const DEFAULT_BLOOM_FILTER_OPTIONS = {
 const DEFAULT_CAUSAL_HISTORY_SIZE = 2;
 const DEFAULT_RECEIVED_MESSAGE_TIMEOUT = 1000 * 60 * 5; // 5 minutes
 
+const log = new Logger("sds:message-channel");
+
 interface MessageChannelOptions {
   causalHistorySize?: number;
   receivedMessageTimeoutEnabled?: boolean;
@@ -28,13 +31,13 @@ interface MessageChannelOptions {
 }
 
 export class MessageChannel extends TypedEventEmitter<MessageChannelEvents> {
+  public readonly channelId: ChannelId;
   private lamportTimestamp: number;
   private filter: DefaultBloomFilter;
   private outgoingBuffer: Message[];
   private acknowledgements: Map<string, number>;
   private incomingBuffer: Message[];
   private localHistory: { timestamp: number; historyEntry: HistoryEntry }[];
-  public channelId: ChannelId;
   private causalHistorySize: number;
   private acknowledgementCount: number;
   private timeReceived: Map<string, number>;
@@ -82,8 +85,30 @@ export class MessageChannel extends TypedEventEmitter<MessageChannelEvents> {
       options.receivedMessageTimeout ?? DEFAULT_RECEIVED_MESSAGE_TIMEOUT;
   }
 
-  // Periodically called by the library consumer to process async operations
-  // in a sequential manner.
+  public static getMessageId(payload: Uint8Array): string {
+    return bytesToHex(sha256(payload));
+  }
+
+  /**
+   * Processes all queued tasks sequentially to ensure proper message ordering.
+   *
+   * This method should be called periodically by the library consumer to execute
+   * queued send/receive operations in the correct sequence.
+   *
+   * @example
+   * ```typescript
+   * const channel = new MessageChannel("my-channel");
+   *
+   * // Queue some operations
+   * await channel.sendMessage(payload, callback);
+   * channel.receiveMessage(incomingMessage);
+   *
+   * // Process all queued operations
+   * await channel.processTasks();
+   * ```
+   *
+   * @throws Will emit a 'taskError' event if any task fails, but continues processing remaining tasks
+   */
   public async processTasks(): Promise<void> {
     while (this.tasks.length > 0) {
       const item = this.tasks.shift();
@@ -91,35 +116,33 @@ export class MessageChannel extends TypedEventEmitter<MessageChannelEvents> {
         continue;
       }
 
-      // Use a generic helper function to ensure type safety
       await this.executeTask(item);
     }
   }
 
-  private async executeTask<A extends Command>(item: Task<A>): Promise<void> {
-    const handler = this.handlers[item.command];
-    await handler(item.params as ParamsByAction[A]);
-  }
-
-  public static getMessageId(payload: Uint8Array): string {
-    return bytesToHex(sha256(payload));
-  }
-
   /**
-   * Send a message to the SDS channel.
+   * Queues a message to be sent on this channel.
    *
-   * Increments the lamport timestamp, constructs a `Message` object
-   * with the given payload, and adds it to the outgoing buffer.
+   * The message will be processed sequentially when processTasks() is called.
+   * This ensures proper lamport timestamp ordering and causal history tracking.
    *
-   * If the callback is successful, the message is also added to
-   * the bloom filter and message history. In the context of
-   * Waku, this likely means the message was published via
-   * light push or relay.
+   * @param payload - The message content as a byte array
+   * @param callback - Optional callback function called after the message is processed
+   * @returns Promise that resolves when the message is queued (not sent)
    *
-   * See https://rfc.vac.dev/vac/raw/sds/#send-message
+   * @example
+   * ```typescript
+   * const channel = new MessageChannel("chat-room");
+   * const message = new TextEncoder().encode("Hello, world!");
    *
-   * @param payload - The payload to send.
-   * @param callback - A callback function that returns a boolean indicating whether the message was sent successfully.
+   * await channel.sendMessage(message, async (processedMessage) => {
+   *   console.log("Message processed:", processedMessage.messageId);
+   *   return { success: true };
+   * });
+   *
+   * // Actually send the message
+   * await channel.processTasks();
+   * ```
    */
   public async sendMessage(
     payload: Uint8Array,
@@ -137,49 +160,6 @@ export class MessageChannel extends TypedEventEmitter<MessageChannelEvents> {
     });
   }
 
-  public async _sendMessage(
-    payload: Uint8Array,
-    callback?: (message: Message) => Promise<{
-      success: boolean;
-      retrievalHint?: Uint8Array;
-    }>
-  ): Promise<void> {
-    this.lamportTimestamp++;
-
-    const messageId = MessageChannel.getMessageId(payload);
-
-    const message: Message = {
-      messageId,
-      channelId: this.channelId,
-      lamportTimestamp: this.lamportTimestamp,
-      causalHistory: this.localHistory
-        .slice(-this.causalHistorySize)
-        .map(({ historyEntry }) => historyEntry),
-      bloomFilter: this.filter.toBytes(),
-      content: payload
-    };
-
-    this.outgoingBuffer.push(message);
-
-    if (callback) {
-      const { success, retrievalHint } = await callback(message);
-      if (success) {
-        this.filter.insert(messageId);
-        this.localHistory.push({
-          timestamp: this.lamportTimestamp,
-          historyEntry: {
-            messageId,
-            retrievalHint
-          }
-        });
-        this.timeReceived.set(messageId, Date.now());
-        this.safeDispatchEvent(MessageChannelEvent.MessageSent, {
-          detail: message
-        });
-      }
-    }
-  }
-
   /**
    * Sends a short-lived message without synchronization or reliability requirements.
    *
@@ -206,39 +186,25 @@ export class MessageChannel extends TypedEventEmitter<MessageChannelEvents> {
     });
   }
 
-  public async _sendEphemeralMessage(
-    payload: Uint8Array,
-    callback?: (message: Message) => Promise<boolean>
-  ): Promise<void> {
-    const message: Message = {
-      messageId: MessageChannel.getMessageId(payload),
-      channelId: this.channelId,
-      content: payload,
-      lamportTimestamp: undefined,
-      causalHistory: [],
-      bloomFilter: undefined
-    };
-
-    if (callback) {
-      await callback(message);
-    }
-  }
-
   /**
-   * Process a received SDS message for this channel.
+   * Queues a received message for processing.
+   *
+   * The message will be processed when processTasks() is called, ensuring
+   * proper dependency resolution and causal ordering.
    *
-   * Review the acknowledgement status of messages in the outgoing buffer
-   * by inspecting the received message's bloom filter and causal history.
-   * Add the received message to the bloom filter.
-   * If the local history contains every message in the received message's
-   * causal history, deliver the message. Otherwise, add the message to the
-   * incoming buffer.
+   * @param message - The message to receive and process
    *
-   * See https://rfc.vac.dev/vac/raw/sds/#receive-message
+   * @example
+   * ```typescript
+   * const channel = new MessageChannel("chat-room");
    *
-   * @param message - The received SDS message.
+   * // Receive a message from the network
+   * channel.receiveMessage(incomingMessage);
+   *
+   * // Process the received message
+   * await channel.processTasks();
+   * ```
    */
-
   public receiveMessage(message: Message): void {
     this.tasks.push({
       command: Command.Receive,
@@ -248,67 +214,17 @@ export class MessageChannel extends TypedEventEmitter<MessageChannelEvents> {
     });
   }
 
-  public _receiveMessage(message: Message): void {
-    if (
-      message.content &&
-      message.content.length > 0 &&
-      this.timeReceived.has(message.messageId)
-    ) {
-      // Received a duplicate message
-      return;
-    }
-
-    if (!message.lamportTimestamp) {
-      // Messages with no timestamp are ephemeral messages and should be delivered immediately
-      this.deliverMessage(message);
-      return;
-    }
-    if (message.content?.length === 0) {
-      this.safeDispatchEvent(MessageChannelEvent.SyncReceived, {
-        detail: message
-      });
-    } else {
-      this.safeDispatchEvent(MessageChannelEvent.MessageReceived, {
-        detail: message
-      });
-    }
-    // review ack status
-    this.reviewAckStatus(message);
-    // add to bloom filter (skip for messages with empty content)
-    if (message.content?.length && message.content.length > 0) {
-      this.filter.insert(message.messageId);
-    }
-    // verify causal history
-    const dependenciesMet = message.causalHistory.every((historyEntry) =>
-      this.localHistory.some(
-        ({ historyEntry: { messageId } }) =>
-          messageId === historyEntry.messageId
-      )
-    );
-    if (!dependenciesMet) {
-      this.incomingBuffer.push(message);
-      this.timeReceived.set(message.messageId, Date.now());
-    } else {
-      this.deliverMessage(message);
-      this.safeDispatchEvent(MessageChannelEvent.MessageDelivered, {
-        detail: {
-          messageId: message.messageId,
-          sentOrReceived: "received"
-        }
-      });
-    }
-  }
-
-  // https://rfc.vac.dev/vac/raw/sds/#periodic-incoming-buffer-sweep
-  // Note that even though this function has side effects, it is not async
-  // and does not need to be called through the queue.
+  /**
+   * Processes messages in the incoming buffer, delivering those with satisfied dependencies.
+   *
+   * @returns Array of history entries for messages still missing dependencies
+   */
   public sweepIncomingBuffer(): HistoryEntry[] {
     const { buffer, missing } = this.incomingBuffer.reduce<{
       buffer: Message[];
       missing: Set<HistoryEntry>;
     }>(
       ({ buffer, missing }, message) => {
-        // Check each message for missing dependencies
         const missingDependencies = message.causalHistory.filter(
           (messageHistoryEntry) =>
             !this.localHistory.some(
@@ -317,10 +233,8 @@ export class MessageChannel extends TypedEventEmitter<MessageChannelEvents> {
             )
         );
         if (missingDependencies.length === 0) {
-          // Any message with no missing dependencies is delivered
-          // and removed from the buffer (implicitly by not adding it to the new incoming buffer)
           this.deliverMessage(message);
-          this.safeDispatchEvent(MessageChannelEvent.MessageDelivered, {
+          this.safeSendEvent(MessageChannelEvent.MessageDelivered, {
             detail: {
               messageId: message.messageId,
               sentOrReceived: "received"
@@ -340,8 +254,6 @@ export class MessageChannel extends TypedEventEmitter<MessageChannelEvents> {
             return { buffer, missing };
           }
         }
-        // Any message with missing dependencies stays in the buffer
-        // and the missing message IDs are returned for processing.
         missingDependencies.forEach((dependency) => {
           missing.add(dependency);
         });
@@ -352,10 +264,9 @@ export class MessageChannel extends TypedEventEmitter<MessageChannelEvents> {
       },
       { buffer: new Array<Message>(), missing: new Set<HistoryEntry>() }
     );
-    // Update the incoming buffer to only include messages with no missing dependencies
     this.incomingBuffer = buffer;
 
-    this.safeDispatchEvent(MessageChannelEvent.MissedMessages, {
+    this.safeSendEvent(MessageChannelEvent.MissedMessages, {
       detail: Array.from(missing)
     });
 
@@ -367,7 +278,6 @@ export class MessageChannel extends TypedEventEmitter<MessageChannelEvents> {
     unacknowledged: Message[];
     possiblyAcknowledged: Message[];
   } {
-    // Partition all messages in the outgoing buffer into unacknowledged and possibly acknowledged messages
     return this.outgoingBuffer.reduce<{
       unacknowledged: Message[];
       possiblyAcknowledged: Message[];
@@ -420,13 +330,161 @@ export class MessageChannel extends TypedEventEmitter<MessageChannelEvents> {
     };
 
     if (callback) {
-      await callback(message);
-      this.safeDispatchEvent(MessageChannelEvent.SyncSent, {
+      try {
+        await callback(message);
+        this.safeSendEvent(MessageChannelEvent.SyncSent, {
+          detail: message
+        });
+        return true;
+      } catch (error) {
+        log.error("Callback execution failed in sendSyncMessage:", error);
+        throw error;
+      }
+    }
+    return false;
+  }
+
+  private _receiveMessage(message: Message): void {
+    const isDuplicate =
+      message.content &&
+      message.content.length > 0 &&
+      this.timeReceived.has(message.messageId);
+
+    if (isDuplicate) {
+      return;
+    }
+
+    if (!message.lamportTimestamp) {
+      this.deliverMessage(message);
+      return;
+    }
+    if (message.content?.length === 0) {
+      this.safeSendEvent(MessageChannelEvent.SyncReceived, {
+        detail: message
+      });
+    } else {
+      this.safeSendEvent(MessageChannelEvent.MessageReceived, {
         detail: message
       });
-      return true;
     }
-    return false;
+    this.reviewAckStatus(message);
+    if (message.content?.length && message.content.length > 0) {
+      this.filter.insert(message.messageId);
+    }
+    const dependenciesMet = message.causalHistory.every((historyEntry) =>
+      this.localHistory.some(
+        ({ historyEntry: { messageId } }) =>
+          messageId === historyEntry.messageId
+      )
+    );
+    if (!dependenciesMet) {
+      this.incomingBuffer.push(message);
+      this.timeReceived.set(message.messageId, Date.now());
+    } else {
+      this.deliverMessage(message);
+      this.safeSendEvent(MessageChannelEvent.MessageDelivered, {
+        detail: {
+          messageId: message.messageId,
+          sentOrReceived: "received"
+        }
+      });
+    }
+  }
+
+  private async executeTask<A extends Command>(item: Task<A>): Promise<void> {
+    try {
+      const handler = this.handlers[item.command];
+      await handler(item.params as ParamsByAction[A]);
+    } catch (error) {
+      log.error(`Task execution failed for command ${item.command}:`, error);
+      this.dispatchEvent(
+        new CustomEvent("taskError", {
+          detail: { command: item.command, error, params: item.params }
+        })
+      );
+    }
+  }
+
+  private safeSendEvent<T extends MessageChannelEvent>(
+    event: T,
+    eventInit?: CustomEventInit
+  ): void {
+    try {
+      this.dispatchEvent(new CustomEvent(event, eventInit));
+    } catch (error) {
+      log.error(`Failed to dispatch event ${event}:`, error);
+    }
+  }
+
+  private async _sendMessage(
+    payload: Uint8Array,
+    callback?: (message: Message) => Promise<{
+      success: boolean;
+      retrievalHint?: Uint8Array;
+    }>
+  ): Promise<void> {
+    this.lamportTimestamp++;
+
+    const messageId = MessageChannel.getMessageId(payload);
+
+    const message: Message = {
+      messageId,
+      channelId: this.channelId,
+      lamportTimestamp: this.lamportTimestamp,
+      causalHistory: this.localHistory
+        .slice(-this.causalHistorySize)
+        .map(({ historyEntry }) => historyEntry),
+      bloomFilter: this.filter.toBytes(),
+      content: payload
+    };
+
+    this.outgoingBuffer.push(message);
+
+    if (callback) {
+      try {
+        const { success, retrievalHint } = await callback(message);
+        if (success) {
+          this.filter.insert(messageId);
+          this.localHistory.push({
+            timestamp: this.lamportTimestamp,
+            historyEntry: {
+              messageId,
+              retrievalHint
+            }
+          });
+          this.timeReceived.set(messageId, Date.now());
+          this.safeSendEvent(MessageChannelEvent.MessageSent, {
+            detail: message
+          });
+        }
+      } catch (error) {
+        log.error("Callback execution failed in _sendMessage:", error);
+        throw error;
+      }
+    }
+  }
+
+  private async _sendEphemeralMessage(
+    payload: Uint8Array,
+    callback?: (message: Message) => Promise<boolean>
+  ): Promise<void> {
+    const message: Message = {
+      messageId: MessageChannel.getMessageId(payload),
+      channelId: this.channelId,
+      content: payload,
+      lamportTimestamp: undefined,
+      causalHistory: [],
+      bloomFilter: undefined
+    };
+
+    if (callback) {
+      try {
+        await callback(message);
+      } catch (error) {
+        log.error("Callback execution failed in _sendEphemeralMessage:", error);
+        throw error;
+      }
+    }
   }
 
   // See https://rfc.vac.dev/vac/raw/sds/#deliver-message
@@ -470,14 +528,13 @@ export class MessageChannel extends TypedEventEmitter<MessageChannelEvents> {
   // to determine the acknowledgement status of messages in the outgoing buffer.
   // See https://rfc.vac.dev/vac/raw/sds/#review-ack-status
   private reviewAckStatus(receivedMessage: Message): void {
-    // the participant MUST mark all messages in the received causal_history as acknowledged.
     receivedMessage.causalHistory.forEach(({ messageId }) => {
       this.outgoingBuffer = this.outgoingBuffer.filter(
         ({ messageId: outgoingMessageId }) => {
           if (outgoingMessageId !== messageId) {
             return true;
           }
-          this.safeDispatchEvent(MessageChannelEvent.MessageAcknowledged, {
+          this.safeSendEvent(MessageChannelEvent.MessageAcknowledged, {
             detail: messageId
           });
           return false;
@@ -488,7 +545,6 @@ export class MessageChannel extends TypedEventEmitter<MessageChannelEvents> {
         this.filter.insert(messageId);
       }
     });
-    // the participant MUST mark all messages included in the bloom_filter as possibly acknowledged
     if (!receivedMessage.bloomFilter) {
       return;
     }
@@ -506,7 +562,7 @@ export class MessageChannel extends TypedEventEmitter<MessageChannelEvents> {
       const count = (this.acknowledgements.get(message.messageId) ?? 0) + 1;
       if (count < this.acknowledgementCount) {
         this.acknowledgements.set(message.messageId, count);
-        this.safeDispatchEvent(MessageChannelEvent.PartialAcknowledgement, {
+        this.safeSendEvent(MessageChannelEvent.PartialAcknowledgement, {
           detail: {
             messageId: message.messageId,
             count