@enbox/dwn-sdk-js 0.4.15 → 0.4.17

package/src/types/message-store.ts

@@ -6,6 +6,29 @@ export interface MessageStoreOptions {
   signal?: AbortSignal;
 }
 
+/**
+ * Read-time `$recordLimit` occupancy policy for one concrete protocol path.
+ *
+ * Stores partition matching latest RecordsWrites by `parentId`, rank each
+ * partition by `dateCreated` then `recordId` ascending, and apply `max`
+ * before the caller's filters, sort, and pagination.
+ */
+export type RecordLimitOccupancy = {
+  protocol: string;
+  protocolPath: string;
+  /**
+   * Root of the candidate context subtree. An exact-record request supplies
+   * its direct-parent context here so sibling candidates still consume slots.
+   * Omitted for root protocol paths.
+   */
+  contextId?: string;
+  max: number;
+};
+
+export interface MessageStoreQueryOptions extends MessageStoreOptions {
+  recordLimit?: RecordLimitOccupancy;
+}
+
 /**
  * Result of a {@link MessageStore.put} operation.
  */
@@ -98,7 +121,7 @@ export interface MessageStore {
     filters: Filter[],
     messageSort?: MessageSort,
     pagination?: Pagination,
-    options?: MessageStoreOptions
+    options?: MessageStoreQueryOptions
   ): Promise<{ messages: GenericMessage[], cursor?: PaginationCursor}>;
 
   /**
@@ -109,7 +132,7 @@ export interface MessageStore {
     tenant: string,
     filters: Filter[],
     messageSort?: MessageSort,
-    options?: MessageStoreOptions
+    options?: MessageStoreQueryOptions
   ): Promise<number>;
 
   /**

package/src/types/messages-types.ts

@@ -87,6 +87,20 @@ export type MessagesSubscribeMessage = {
 
 export type MessagesSubscribeReply = GenericMessageReply & {
   subscription?: MessageSubscription;
+  /**
+   * Feed fingerprint over the subscription's filter scopes, observed after the
+   * subscription became active. Present only when the filters map onto
+   * fingerprint domains and the message store exposes the replication feed.
+   */
+  fingerprint?: string;
+  /**
+   * High-water progress token of the tenant's replication log, observed after
+   * the subscription became active — the position-zero anchor when the log is
+   * empty. NOT a delivery cursor: adopting it as a checkpoint is sound only
+   * after verifying `fingerprint` against the local feed, since resuming from
+   * it skips every earlier log position.
+   */
+  head?: ProgressToken;
   /** Present when status.code is 410 — structured gap metadata. */
   error?: { code: 'ProgressGap' } & ProgressGapInfo;
 };

package/src/types/protocols-types.ts

@@ -149,33 +149,15 @@ export type ProtocolSizeDefinition = {
 };
 
 /**
- * Supported strategies for handling writes that would exceed a `$recordLimit`.
- */
-export enum ProtocolRecordLimitStrategy {
-  /** Reject the incoming write with an error. The author must delete old records first. */
-  Reject = 'reject',
-  /** Automatically delete the oldest record(s) (by `dateCreated`) to make room for the new one. */
-  PurgeOldest = 'purgeOldest',
-}
-
-/**
- * Limits the number of records at a given protocol path within the same parent context.
+ * Limits the visible records at a given protocol path within the same parent context.
  *
- * For root-level records, the count is across the entire protocol for the tenant.
- * For nested records, the count is scoped to the parent record's context.
- *
- * Only initial writes (new records) count toward the limit; updates to existing records do not.
+ * Root-level records form one group for the protocol path. Nested records are grouped by
+ * direct parent context. Occupants are selected deterministically at read time; valid writes
+ * outside the visible population remain stored and may become visible later.
  */
 export type ProtocolRecordLimitDefinition = {
-  /** Maximum number of records allowed at this path within the same parent context. Must be >= 1. */
+  /** Maximum number of visible records at this path within the same parent context. Must be >= 1. */
   max: number;
-
-  /**
-   * Strategy when the limit is reached.
-   * Currently only `'reject'` is implemented. Future strategies (e.g. `'purgeOldest'`)
-   * are defined in the wire format but not yet enforced.
-   */
-  strategy: ProtocolRecordLimitStrategy | `${ProtocolRecordLimitStrategy}` | (string & {});
 };
 
 /**
@@ -287,9 +269,8 @@ export type ProtocolRuleSet = {
   $tags?: ProtocolTagsDefinition;
 
   /**
-   * If $recordLimit is set, the number of records at this protocol path within the same
-   * parent context is constrained. When the limit is reached, the `strategy` determines
-   * whether the write is rejected or the oldest record is purged.
+   * If `$recordLimit` is set, reads expose at most `max` records at this protocol path
+   * within each direct parent context.
    */
   $recordLimit?: ProtocolRecordLimitDefinition;
 

package/src/types/query-types.ts

@@ -37,7 +37,15 @@ export type StartsWithFilter = {
   startsWith: string;
 };
 
-export type FilterValue = EqualFilter | OneOfFilter | RangeFilter;
+/**
+ * Selects one hierarchical path and every proper `/`-delimited descendant.
+ * Supported only for the `contextId` and `protocolPath` indexes.
+ */
+export type SubtreeFilter = {
+  subtree: string;
+};
+
+export type FilterValue = EqualFilter | OneOfFilter | RangeFilter | SubtreeFilter;
 
 export type Filter = {
   [property: string]: FilterValue;
@@ -58,4 +66,4 @@ export type RangeCriterion = {
 export type PaginationCursor = {
   messageCid: string;
   value: string | number;
-};
+};

package/src/types/records-types.ts

@@ -154,7 +154,8 @@ export type RecordsFilter = {
   published?: boolean;
 
   /**
-   * When given all Records message under the context of the given `contextId` will be returned.
+   * Selects the exact context and its proper `/`-delimited descendants.
+   * Prefix-sharing sibling contexts are excluded.
    */
   contextId?: string;
   schema?: string;

package/src/utils/filter.ts

@@ -1,4 +1,30 @@
-import type { EqualFilter, Filter, FilterValue, KeyValues, OneOfFilter, RangeCriterion, RangeFilter, RangeValue } from '../types/query-types.js';
+import type { EqualFilter, Filter, FilterValue, KeyValues, OneOfFilter, RangeCriterion, RangeFilter, RangeValue, SubtreeFilter } from '../types/query-types.js';
+
+const SUBTREE_FILTER_PROPERTIES = new Set(['contextId', 'protocolPath']);
+
+/** Returns whether the value is a well-formed hierarchical subtree filter. */
+export function isSubtreeFilter(filter: FilterValue): filter is SubtreeFilter {
+  return typeof filter === 'object' &&
+    filter !== null &&
+    !Array.isArray(filter) &&
+    Object.keys(filter).length === 1 &&
+    typeof (filter as Partial<SubtreeFilter>).subtree === 'string';
+}
+
+/**
+ * Rejects subtree filters for indexes without hierarchical path semantics.
+ *
+ * @throws {TypeError} If a subtree filter targets an index other than `contextId` or `protocolPath`.
+ */
+export function assertValidSubtreeFilters(filters: Filter[]): void {
+  for (const filter of filters) {
+    for (const property in filter) {
+      if (isSubtreeFilter(filter[property]) && !SUBTREE_FILTER_PROPERTIES.has(property)) {
+        throw new TypeError(`SubtreeFilter is not supported for index '${property}'.`);
+      }
+    }
+  }
+}
 
 /**
  * A Utility class to help match indexes against filters.
@@ -84,7 +110,9 @@ export class FilterUtility {
         if (this.matchOneOf(filterValue, indexValue)) {
           return true;
         }
-      } else if (this.matchRange(filterValue, indexValue as RangeValue)) {
+      } else if (isSubtreeFilter(filterValue) && this.matchesSubtree(filterValue.subtree, indexValue)) {
+        return true;
+      } else if (this.isRangeFilter(filterValue) && this.matchRange(filterValue, indexValue as RangeValue)) {
         // `filterValue` is a `RangeFilter`
         // range filters cannot range over booleans
         return true;
@@ -181,6 +209,15 @@ export class FilterUtility {
     };
   }
 
+  /**
+   * Returns whether a candidate is the selected hierarchical path or one of
+   * its proper `/`-delimited descendants.
+   */
+  static matchesSubtree(subtree: string, candidate: unknown): candidate is string {
+    return typeof candidate === 'string' &&
+      (candidate === subtree || candidate.startsWith(`${subtree}/`));
+  }
+
 }
 
 export class FilterSelector {
@@ -238,4 +275,4 @@ export class FilterSelector {
     singlePropertyFilter[firstRemainingProperty] = filter[firstRemainingProperty];
     return singlePropertyFilter;
   }
-}
+}

package/src/utils/grant-key-coverage.ts

@@ -1,6 +1,7 @@
 import type { PermissionScope, RecordsPermissionScope } from '../types/permission-types.js';
 import type { ProtocolDefinition, ProtocolRuleSet } from '../types/protocols-types.js';
 
+import { FilterUtility } from './filter.js';
 import { KeyDerivationScheme } from './hd-key.js';
 import { ProtocolAction } from '../types/protocols-types.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
@@ -171,7 +172,7 @@ function readGrantKeyScopeCoversDeliveredScope(input: {
     return false;
   }
 
-  if (isBoundaryAwareSubtree(grantProtocolPath, deliveredProtocolPath)) {
+  if (FilterUtility.matchesSubtree(grantProtocolPath, deliveredProtocolPath)) {
     return true;
   }
 
@@ -206,7 +207,7 @@ function writeGrantKeyScopeCoversDeliveredScope(input: {
     return true;
   }
 
-  return isBoundaryAwareSubtree(grantProtocolPath, deliveredProtocolPath);
+  return FilterUtility.matchesSubtree(grantProtocolPath, deliveredProtocolPath);
 }
 
 function getGrantKeyReadRolePathsForScope(protocolDefinition: ProtocolDefinition, scopeProtocolPath: string): string[] {
@@ -257,7 +258,7 @@ function collectReadRolePaths(protocolDefinition: ProtocolDefinition, ruleSet: P
 
 function getGrantKeyRolePathsCoveredByScope(protocolDefinition: ProtocolDefinition, scopeProtocolPath?: string): string[] {
   return collectRolePaths(protocolDefinition, protocolDefinition.structure as ProtocolRuleSet)
-    .filter((rolePath) => scopeProtocolPath === undefined || isBoundaryAwareSubtree(scopeProtocolPath, rolePath));
+    .filter((rolePath) => scopeProtocolPath === undefined || FilterUtility.matchesSubtree(scopeProtocolPath, rolePath));
 }
 
 function collectRolePaths(protocolDefinition: ProtocolDefinition, ruleSet: ProtocolRuleSet, parentPath: string[] = []): string[] {
@@ -285,10 +286,6 @@ function isGrantKeyLocalRolePath(protocolDefinition: ProtocolDefinition, protoco
   return ruleSet?.$role === true && ruleSet.$keyAgreement !== undefined;
 }
 
-function isBoundaryAwareSubtree(scopePath: string, candidatePath: string): boolean {
-  return `${candidatePath}/`.startsWith(`${scopePath}/`);
-}
-
 function getGrantKeyScopeCacheKey(scope: GrantKeyProtocolPathScope): string {
   return JSON.stringify([scope.protocol, scope.protocolPath]);
 }

package/src/utils/messages.ts

@@ -6,6 +6,7 @@ import type { MessagesFilter } from '../types/messages-types.js';
 import { FilterUtility } from './filter.js';
 import { normalizeProtocolUrl } from './url.js';
 import { Records } from './records.js';
+import { Replication } from './replication.js';
 import { isEmptyObject, removeUndefinedProperties } from '@enbox/common';
 
 type StoredMessageWithEncodedData = GenericMessage & { encodedData?: string };
@@ -122,6 +123,50 @@ export class Messages {
     return metadataFilter;
   }
 
+  /**
+   * Maps a filter set onto the replication fingerprint domains it covers, or
+   * `undefined` when the filters do not correspond to fingerprint domains.
+   * An empty filter set covers the global domain; a set of protocol-only
+   * filters covers each protocol's domain plus its tagged core-protocol
+   * domains. Any other filter shape has no domain mapping.
+   */
+  public static computeFingerprintScopes(filters: MessagesFilter[]): string[] | undefined {
+    if (filters.length === 0) {
+      return [Replication.globalDomain];
+    }
+
+    const protocols = new Set<string>();
+    for (const filter of filters) {
+      const keys = Object.keys(filter);
+      if (keys.length !== 1 || typeof filter.protocol !== 'string') {
+        return undefined;
+      }
+
+      protocols.add(filter.protocol);
+    }
+
+    // Fail closed for filter sets naming a core protocol directly: the core
+    // protocols contribute no tagged domains for themselves, so the domain
+    // set would not span everything such filters enumerate — two feeds could
+    // fingerprint identically while differing in enumerable messages. No
+    // fingerprint beats one whose coverage is known-incomplete.
+    for (const protocol of protocols) {
+      if (Replication.isCoreProtocolUri(protocol)) {
+        return undefined;
+      }
+    }
+
+    const scopes: string[] = [];
+    for (const protocol of protocols) {
+      scopes.push(
+        Replication.protocolDomain(protocol),
+        ...Replication.taggedCoreProtocolDomains(protocol, protocols),
+      );
+    }
+
+    return scopes;
+  }
+
   /**
    * Returns a copy of a RecordsWrite message without inline encodedData, and the
    * detached encodedData value for wire surfaces that carry data beside the message.
@@ -151,26 +196,16 @@ export class Messages {
       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)
+    // Convert protocolPathPrefix into a segment-aware protocolPath subtree filter.
     if (protocolPathPrefix !== undefined) {
       delete (filterCopy as any).protocolPathPrefix;
-      filterCopy.protocolPath = {
-        gte : protocolPathPrefix,
-        lt  : protocolPathPrefix + '/\uffff',
-      };
+      filterCopy.protocolPath = { subtree: protocolPathPrefix };
     }
 
-    // Convert contextIdPrefix into a contextId range filter (same pattern).
+    // Convert contextIdPrefix into the same segment-aware subtree filter.
     if (contextIdPrefix !== undefined) {
       delete (filterCopy as any).contextIdPrefix;
-      filterCopy.contextId = {
-        gte : contextIdPrefix,
-        lt  : contextIdPrefix + '/\uffff',
-      };
+      filterCopy.contextId = { subtree: contextIdPrefix };
     }
 
     return filterCopy;

package/src/utils/permission-scope.ts

@@ -1,3 +1,5 @@
+import { FilterUtility } from './filter.js';
+
 /**
  * Minimal protocol-bound scope shape used by permission grant authorization.
  *
@@ -38,22 +40,13 @@ export class PermissionScopeMatcher {
     }
 
     if (scope.protocolPath !== undefined) {
-      return PermissionScopeMatcher.matchesSubtree(scope.protocolPath, target.protocolPath);
+      return FilterUtility.matchesSubtree(scope.protocolPath, target.protocolPath);
     }
 
     if (scope.contextId !== undefined) {
-      return PermissionScopeMatcher.matchesContextId(scope.contextId, target.contextId);
+      return FilterUtility.matchesSubtree(scope.contextId, target.contextId);
     }
 
     return true;
   }
-
-  private static matchesContextId(scopeContextId: string, candidateContextId: unknown): boolean {
-    return PermissionScopeMatcher.matchesSubtree(scopeContextId, candidateContextId);
-  }
-
-  private static matchesSubtree(scopeValue: string, candidateValue: unknown): boolean {
-    return typeof candidateValue === 'string' &&
-      (candidateValue === scopeValue || candidateValue.startsWith(scopeValue + '/'));
-  }
 }