@enbox/dwn-sdk-js 0.0.8 → 0.1.1

package/src/store/storage-controller.ts

@@ -1,11 +1,13 @@
 import type { DataStore } from '../types/data-store.js';
 import type { EventLog } from '../types/subscriptions.js';
+import type { Filter } from '../types/query-types.js';
 import type { GenericMessage } from '../types/message-types.js';
 import type { MessageStore } from '../types/message-store.js';
 import type { StateIndex } from '../types/state-index.js';
 import type { RecordsDeleteMessage, RecordsQueryReplyEntry, RecordsWriteMessage } from '../types/records-types.js';
 
 import { DwnConstant } from '../core/dwn-constant.js';
+import { FilterUtility } from '../utils/filter.js';
 import { Message } from '../core/message.js';
 import { Records } from '../utils/records.js';
 import { RecordsDelete } from '../interfaces/records-delete.js';
@@ -18,6 +20,11 @@ export type ResumableRecordsDeleteData = {
   message: RecordsDeleteMessage;
 };
 
+export type ResumableRecordsSquashData = {
+  tenant: string;
+  message: RecordsWriteMessage;
+};
+
 /**
  * A class that provides an abstraction for the usage of MessageStore, DataStore, and StateIndex.
  */
@@ -82,6 +89,76 @@ export class StorageController {
     );
   }
 
+  /**
+   * Performs the squash processing for a `RecordsWrite` with `squash: true`.
+   * Deletes all sibling records at the same protocol path and parent context whose
+   * `messageTimestamp` is strictly older than the squash record's `messageTimestamp`.
+   * Unlike normal `RecordsDelete` tombstones, squash targets are fully purged — no initial writes
+   * are retained.
+   *
+   * This method is idempotent — it can be safely re-run on resume after a crash.
+   */
+  public async performRecordsSquash({ tenant, message }: ResumableRecordsSquashData): Promise<void> {
+    const { protocol, protocolPath, messageTimestamp } = message.descriptor;
+
+    // Build a filter to find all sibling records at the same protocol path and parent context.
+    // We query by interface only (not method) so that both RecordsWrite and RecordsDelete messages are found.
+    const filter: Filter = {
+      interface    : DwnInterfaceName.Records,
+      protocol,
+      protocolPath : protocolPath,
+    };
+
+    // Scope by parent context for nested records
+    const parentContextId = Records.getParentContextFromOfContextId(message.contextId);
+    if (parentContextId !== undefined && parentContextId !== '') {
+      const prefixFilter = FilterUtility.constructPrefixFilterAsRangeFilter(parentContextId);
+      filter.contextId = prefixFilter;
+    }
+
+    // Query for all records at this path and context
+    const { messages: siblingMessages } = await this.messageStore.query(tenant, [filter]);
+
+    // Group messages by recordId — RecordsWrite messages use `message.recordId`,
+    // RecordsDelete messages use `message.descriptor.recordId`.
+    const recordIdToMessages = new Map<string, GenericMessage[]>();
+    for (const msg of siblingMessages) {
+      let recordId: string;
+      if (Records.isRecordsWrite(msg)) {
+        recordId = msg.recordId;
+      } else {
+        recordId = (msg as RecordsDeleteMessage).descriptor.recordId;
+      }
+
+      const existing = recordIdToMessages.get(recordId);
+      if (existing !== undefined) {
+        existing.push(msg);
+      } else {
+        recordIdToMessages.set(recordId, [msg]);
+      }
+    }
+
+    // Delete all records whose newest message timestamp is strictly older than the squash timestamp.
+    // Skip the squash record itself.
+    for (const [recordId, messages] of recordIdToMessages) {
+      if (recordId === message.recordId) {
+        continue;
+      }
+
+      // Use the newest message's timestamp to determine if the record predates the squash.
+      const newestMessage = await Message.getNewestMessage(messages);
+      if (newestMessage === undefined) {
+        continue;
+      }
+
+      const newestTimestamp = newestMessage.descriptor.messageTimestamp;
+      if (newestTimestamp < messageTimestamp) {
+        // Fully purge this record — all messages (including initial write) and their data
+        await StorageController.purgeRecordMessages(tenant, messages, this.messageStore, this.dataStore, this.stateIndex);
+      }
+    }
+  }
+
   /**
    * Deletes the data referenced by the given message if needed.
    * @param message The message to check if the data it references should be deleted.
@@ -164,7 +241,7 @@ export class StorageController {
    * Purges (permanent hard-delete) all messages of the SAME `recordId` given and their associated data and events.
    * Assumes that the given `recordMessages` are all of the same `recordId`.
    */
-  private static async purgeRecordMessages(
+  public static async purgeRecordMessages(
     tenant: string,
     recordMessages: GenericMessage[],
     messageStore: MessageStore,

package/src/types/protocols-types.ts

@@ -75,6 +75,7 @@ export enum ProtocolAction {
   Delete = 'delete',
   Prune = 'prune',
   Read = 'read',
+  Squash = 'squash',
   Update = 'update'
 }
 
@@ -184,6 +185,17 @@ export type ProtocolRecordLimitDefinition = {
   strategy: ProtocolRecordLimitStrategy | `${ProtocolRecordLimitStrategy}` | (string & {});
 };
 
+/**
+ * Delivery strategy for records at a given protocol path.
+ * Controls how a DWN server proactively distributes records to participants' DWN endpoints.
+ *
+ * - `'direct'`    — The origin DWN pushes new records to all participants' DWN endpoints.
+ *                    Best for small participant sets (2–50).
+ * - `'subscribe'` — Participant providers establish `RecordsSubscribe` connections to the
+ *                    origin DWN. Best for asymmetric fan-out or unbounded audiences.
+ */
+export type ProtocolDeliveryStrategy = 'direct' | 'subscribe';
+
 /**
  * Tag rules for records at a given protocol path. Each non-`$`-prefixed property
  * is a JSON Schema object constraining that tag's value.
@@ -222,7 +234,7 @@ export type ProtocolTagSchema = {
 /**
  * Union of all value types that can appear as properties of a `ProtocolRuleSet`.
  * This includes:
- * - `$`-prefixed directive values (`$encryption`, `$actions`, `$role`, `$ref`, `$size`, `$tags`)
+ * - `$`-prefixed directive values (`$encryption`, `$actions`, `$role`, `$ref`, `$size`, `$tags`, `$delivery`)
  * - Child `ProtocolRuleSet` entries (non-`$` keys)
  */
 type ProtocolRuleSetValue =
@@ -232,6 +244,7 @@ type ProtocolRuleSetValue =
   | ProtocolTagsDefinition
   | ProtocolSizeDefinition
   | ProtocolRecordLimitDefinition
+  | ProtocolDeliveryStrategy
   | boolean
   | string
   | undefined;
@@ -293,6 +306,24 @@ export type ProtocolRuleSet = {
    */
   $immutable?: boolean;
 
+  /**
+   * Delivery strategy hint for records at this protocol path.
+   * When set, the DWN server SHOULD proactively deliver records to participants' DWN endpoints.
+   *
+   * - `'direct'`    — Origin DWN pushes to all participant DWN endpoints upon receipt.
+   * - `'subscribe'` — Participant providers subscribe to the origin DWN via `RecordsSubscribe`.
+   */
+  $delivery?: ProtocolDeliveryStrategy;
+
+  /**
+   * If `$squash` is `true`, enables squash writes at this protocol path.
+   * A squash write is a `RecordsWrite` with `squash: true` in the descriptor that
+   * atomically creates a new record (the snapshot) and deletes all sibling records
+   * at the same protocol path within the same parent context that have a
+   * `messageTimestamp` strictly older than the squash record's `messageTimestamp`.
+   */
+  $squash?: boolean;
+
   /**
    * Non-`$`-prefixed keys are nested child `ProtocolRuleSet` entries.
    * At runtime, JSON Schema validation ensures only valid child rule sets appear here.

package/src/types/records-types.ts

@@ -38,6 +38,14 @@ export type RecordsWriteDescriptor = {
   datePublished?: string;
   dataFormat: string;
   permissionGrantId?: string;
+
+  /**
+   * When `true`, this record is a squash (snapshot) write. The protocol rule set at this record's
+   * `protocolPath` must have `$squash: true`; otherwise the message is rejected.
+   * A squash write must be an initial write (a new record, not an update).
+   * This is an immutable property.
+   */
+  squash?: true;
 };
 
 export type RecordsWriteMessageOptions = {