@enbox/dwn-sdk-js 0.3.0 → 0.3.2

package/src/types/subscriptions.ts

@@ -2,6 +2,54 @@ import type { RecordsWriteMessage } from './records-types.js';
 import type { Filter, KeyValues } from './query-types.js';
 import type { GenericMessage, GenericMessageReply, MessageSubscription } from './message-types.js';
 
+// ---------------------------------------------------------------------------
+// ProgressToken — structured cursor for EventLog replay/resume
+// ---------------------------------------------------------------------------
+
+/**
+ * Structured cursor for EventLog replay and resume. Replaces the previous
+ * opaque `string` cursor to provide explicit ordering semantics required
+ * by causal frontier progression in multi-master sync.
+ *
+ * Comparisons are valid only when `streamId` and `epoch` are equal.
+ * `position` is compared numerically (BigInt-safe), never lexicographically.
+ * Progress tokens are source-local: they MUST NOT be reused across different
+ * remote providers or EventLog instances.
+ */
+export type ProgressToken = {
+  /** Stable identity of the source event stream domain. */
+  streamId : string;
+  /** Stream generation/version; changes on non-compatible reset. */
+  epoch : string;
+  /** Monotonic decimal string within `(streamId, epoch)`. Compared numerically. */
+  position : string;
+  /** The CID of the message associated with this event. */
+  messageCid : string;
+};
+
+/**
+ * Reason code for a {@link ProgressGapInfo} — explains why the cursor
+ * cannot be resumed.
+ */
+export type ProgressGapReason = 'token_too_old' | 'epoch_mismatch' | 'stream_mismatch';
+
+/**
+ * Metadata attached to a `DwnError(DwnErrorCode.EventLogProgressGap, ...)`
+ * when an EventLog implementation cannot resume from a given cursor.
+ *
+ * Subscribe handlers translate this into a 410 response.
+ */
+export type ProgressGapInfo = {
+  /** The cursor the consumer requested. */
+  requested : ProgressToken;
+  /** The oldest token still available for replay. */
+  oldestAvailable : ProgressToken;
+  /** The latest token available. */
+  latestAvailable : ProgressToken;
+  /** Why the cursor is no longer valid. */
+  reason : ProgressGapReason;
+};
+
 /**
  * Internal listener type used by {@link EventLog.emit} to notify in-process
  * subscribers. Not intended for direct consumer use — consumers should use
@@ -32,17 +80,16 @@ export type SubscriptionReply = GenericMessageReply & {
 // ---------------------------------------------------------------------------
 
 /**
- * A regular subscription event carrying a message and its EventLog cursor.
+ * A regular subscription event carrying a message and its EventLog progress token.
  */
 export type SubscriptionEvent = {
   type : 'event';
   /**
-   * Opaque cursor string assigned by the EventLog implementation. Clients should
-   * persist this value and pass it back to `subscribe()` or `read()` to resume
-   * from this point. The format is implementation-defined (e.g. numeric sequence
-   * for in-memory, Redis stream ID, NATS stream sequence, etc.).
+   * Structured progress token assigned by the EventLog implementation. Clients
+   * should persist this value and pass it back to `subscribe()` or `read()` to
+   * resume from this point.
    */
-  cursor : string;
+  cursor : ProgressToken;
   /** The event payload (message + optional initialWrite). */
   event : MessageEvent;
 };
@@ -57,10 +104,10 @@ export type SubscriptionEvent = {
 export type SubscriptionEose = {
   type : 'eose';
   /**
-   * Opaque cursor string of the last stored event that was replayed.
+   * Progress token of the last stored event that was replayed.
    * Echoes the input cursor when no stored events matched (i.e. already caught up).
    */
-  cursor : string;
+  cursor : ProgressToken;
 };
 
 /**
@@ -80,15 +127,15 @@ export type SubscriptionListener = (message: SubscriptionMessage) => void;
  */
 export type EventLogSubscribeOptions = {
   /**
-   * Opaque cursor string to resume from (exclusive — events after this cursor
+   * Progress token to resume from (exclusive — events after this position
    * are replayed). When provided, stored events are replayed first, followed by
    * an EOSE marker, then live events. When omitted, only live events are delivered.
    *
-   * Cursor values are implementation-defined and must be obtained from a prior
-   * interaction with the same EventLog instance (e.g. `SubscriptionEvent.cursor`,
-   * `EventLogReadResult.cursor`, or the return value of `emit()`).
+   * Tokens must be obtained from a prior interaction with the same EventLog
+   * instance (e.g. `SubscriptionEvent.cursor`, `EventLogReadResult.cursor`,
+   * or the return value of `emit()`).
    */
-  cursor? : string;
+  cursor? : ProgressToken;
 
   /**
    * Filters evaluated against event indexes. Events must match at least one
@@ -113,14 +160,22 @@ export type EventLogEntry = {
 
   /** Indexes associated with the event (used for filter matching). */
   indexes: KeyValues;
+
+  /**
+   * The CID of the message that produced this event. Populated by
+   * implementations that track it (e.g. {@link EventEmitterEventLog}).
+   * Consumers should fall back to computing the CID from the message
+   * if this is absent.
+   */
+  messageCid?: string;
 };
 
 /**
  * Options accepted by {@link EventLog.read}.
  */
 export type EventLogReadOptions = {
-  /** Opaque cursor string to resume from (exclusive — returns events after this cursor). */
-  cursor? : string;
+  /** Progress token to resume from (exclusive — returns events after this position). */
+  cursor? : ProgressToken;
 
   /** Maximum number of events to return. */
   limit? : number;
@@ -137,14 +192,14 @@ export type EventLogReadResult = {
   events : EventLogEntry[];
 
   /**
-   * Opaque cursor string for resuming subsequent reads or subscriptions.
+   * Progress token for resuming subsequent reads or subscriptions.
    *
-   * - When events are returned: cursor of the last event.
+   * - When events are returned: token of the last event.
    * - When no events are returned but a cursor was provided: the input cursor
    *   (meaning "you are caught up, nothing new since this point").
    * - When no events exist and no cursor was provided: `undefined`.
    */
-  cursor? : string;
+  cursor? : ProgressToken;
 };
 
 /**
@@ -162,9 +217,13 @@ export type EventLogReadResult = {
 export interface EventLog {
   /**
    * Persist an event and notify in-process subscribers.
-   * @returns The opaque cursor string assigned to the event, or empty string on failure.
+   * @param tenant     The tenant DID.
+   * @param event      The event payload.
+   * @param indexes    Index values for the event.
+   * @param messageCid The CID of the message being emitted — embedded in the returned token.
+   * @returns A {@link ProgressToken} assigned to the event, or `undefined` on failure.
    */
-  emit(tenant: string, event: MessageEvent, indexes: KeyValues): Promise<string>;
+  emit(tenant: string, event: MessageEvent, indexes: KeyValues, messageCid: string): Promise<ProgressToken | undefined>;
 
   /**
    * Read events from the log starting after `cursor`, optionally filtered.
@@ -188,6 +247,13 @@ export interface EventLog {
    */
   subscribe(tenant: string, id: string, listener: SubscriptionListener, options?: EventLogSubscribeOptions): Promise<EventSubscription>;
 
+  /**
+   * Returns the oldest and latest available progress tokens for a tenant,
+   * or `undefined` if the tenant has no events. Used to construct
+   * `ProgressGap` metadata when a consumer's cursor is no longer replayable.
+   */
+  getReplayBounds(tenant: string): Promise<{ oldest: ProgressToken; latest: ProgressToken } | undefined>;
+
   /**
    * Delete events older than the given sequence number or ISO-8601 timestamp.
    */

package/src/utils/messages.ts

@@ -67,6 +67,29 @@ export class Messages {
       }
 
       messagesQueryFilters.push(this.convertFilter(filter));
+
+      // When protocolPathPrefix is used with a protocol, inject a shadow filter
+      // for ProtocolsConfigure events. Without this, protocol metadata updates
+      // would be excluded (ProtocolsConfigure indexes have no protocolPath).
+      // This mirrors the existing core-protocol additional-filter pattern above.
+      // The messageTimestamp constraint is carried over so time-bounded queries
+      // (including cursor-based subscriptions) also apply to the shadow filter.
+      if ((filter.protocolPathPrefix !== undefined || filter.contextIdPrefix !== undefined) && filter.protocol !== undefined) {
+        const metadataFilter: Filter = {
+          interface : 'Protocols',
+          method    : 'Configure',
+          protocol  : filter.protocol,
+        };
+
+        if (filter.messageTimestamp !== undefined) {
+          const timestampFilter = FilterUtility.convertRangeCriterion(filter.messageTimestamp);
+          if (timestampFilter) {
+            metadataFilter.messageTimestamp = timestampFilter;
+          }
+        }
+
+        messagesQueryFilters.push(metadataFilter);
+      }
     }
 
     return messagesQueryFilters;
@@ -78,12 +101,35 @@ export class Messages {
   private static convertFilter(filter: MessagesFilter): Filter {
     const filterCopy = { ...filter } as Filter;
 
-    const { messageTimestamp } = filter;
+    const { messageTimestamp, protocolPathPrefix, contextIdPrefix } = filter;
     const messageTimestampFilter = messageTimestamp ? FilterUtility.convertRangeCriterion(messageTimestamp) : undefined;
     if (messageTimestampFilter) {
       filterCopy.messageTimestamp = messageTimestampFilter;
       delete filterCopy.dateUpdated;
     }
+
+    // Convert protocolPathPrefix into a protocolPath range filter.
+    // The range gte: prefix, lt: prefix + '/\uffff' matches:
+    //   - exact: 'post' (prefix itself)
+    //   - children: 'post/attachment', 'post/comment', etc.
+    //   - NOT siblings: 'poster', 'postfix' (excluded because '/' < any alphanumeric)
+    if (protocolPathPrefix !== undefined) {
+      delete (filterCopy as any).protocolPathPrefix;
+      filterCopy.protocolPath = {
+        gte : protocolPathPrefix,
+        lt  : protocolPathPrefix + '/\uffff',
+      };
+    }
+
+    // Convert contextIdPrefix into a contextId range filter (same pattern).
+    if (contextIdPrefix !== undefined) {
+      delete (filterCopy as any).contextIdPrefix;
+      filterCopy.contextId = {
+        gte : contextIdPrefix,
+        lt  : contextIdPrefix + '/\uffff',
+      };
+    }
+
     return filterCopy as Filter;
   }
 }