@procedures/client 0.35.1 → 0.36.0

package/src/events/recheck.ts

@@ -27,6 +27,24 @@ import type { Principal } from "../server/types.js";
  */
 export type RightsChange = string | ((principal: Principal | undefined) => boolean);
 
+/**
+ * The rows that a change of the rights touches (roadmap CLI-78): the rows of the collections and
+ * of the partitions of the scope. The partition is the partition after the resolver. Without a
+ * collection, the scope touches each collection. Without a partition, it touches each partition.
+ *
+ * - A string matches one name.
+ * - A test matches each name that it admits, for example each partition of a tenant. A test that
+ *   throws matches: a `reset` hint too many is safe, and a missing one is not.
+ * - A partition matches only a topic with a partition.
+ */
+export interface RightsScope {
+  readonly collection?: string | ((collection: string) => boolean) | undefined;
+  readonly partition?: string | ((partition: string) => boolean) | undefined;
+}
+
+/** One scope or a list of scopes of a change of the rights. A list touches the rows of each scope. */
+export type RightsScopes = RightsScope | readonly RightsScope[];
+
 /** The options of the re-check of the open subscriptions of a publisher (roadmap CLI-44). */
 export interface SubscriptionRecheck {
   /**
@@ -41,9 +59,12 @@ export interface SubscriptionRecheck {
    * removes the listener. Each call of the listener is a call of `rightsChanged()`: without a
    * change, each subscription gets a check.
    */
-  readonly rightsChanges?: ((listener: (change?: RightsChange) => void) => () => void) | undefined;
+  readonly rightsChanges?: ((listener: (change?: RightsChange, scope?: RightsScopes) => void) => () => void) | undefined;
 }
 
+/** The cause of a re-check: a change of the rights, or the max age. */
+export type RecheckCause = "rights" | "age";
+
 /** A subscription that the re-checks can hold and watch. */
 export interface RecheckedSubscription {
   /**
@@ -61,7 +82,7 @@ interface Watch {
   /** The timer of the max age, or undefined. */
   timer: Cancel | undefined;
   /** This function starts a check at once. The promise ends when the check ends. */
-  readonly recheck: () => Promise<void>;
+  readonly recheck: (cause: RecheckCause, scope?: RightsScopes) => Promise<void>;
 }
 
 /** True when the change touches a subscription of the principal. A test that throws touches it. */
@@ -76,10 +97,13 @@ function touches(change: RightsChange | undefined, principal: Principal | undefi
 }
 
 /** The promise of a check. A check that throws at once gives a rejected promise. */
-function started(check: () => Promise<void>): Promise<void> {
-  return new Promise<void>((resolve) => resolve(check()));
+function started(check: RecheckCheck, cause: RecheckCause, scope: RightsScopes | undefined): Promise<void> {
+  return new Promise<void>((resolve) => resolve(check(cause, scope)));
 }
 
+/** The check of a subscription. A check of a change of the rights can get the scope of the change. */
+type RecheckCheck = (cause: RecheckCause, scope?: RightsScopes) => Promise<void>;
+
 /**
  * The re-checks of the open subscriptions of one publisher (roadmap CLI-44). The publisher gives
  * each new subscription to `watch()`, with the check of its admission.
@@ -110,15 +134,16 @@ export class SubscriptionRechecks {
 
   /**
    * This function watches a subscription until it ends. A change of the rights of its principal
-   * and its max age start the check. The check must throw the refusal.
+   * and its max age start the check. The check gets the cause and the scope of the change. It must
+   * throw the refusal.
    */
-  watch(subscription: RecheckedSubscription, principal: Principal | undefined, check: () => Promise<void>): void {
+  watch(subscription: RecheckedSubscription, principal: Principal | undefined, check: RecheckCheck): void {
     const watch: Watch = {
       principal,
       timer: undefined,
-      recheck: () => {
+      recheck: (cause, scope) => {
         this.stopTimer(watch);
-        return subscription.hold(started(check)).then(() => {
+        return subscription.hold(started(check, cause, scope)).then(() => {
           // A check that passes gives the admission a new age
           if (this.watches.has(watch)) this.startTimer(watch);
         });
@@ -130,7 +155,7 @@ export class SubscriptionRechecks {
     this.startTimer(watch);
     if (this.source && !this.stopListening) {
       try {
-        this.stopListening = this.source((change) => void this.rightsChanged(change));
+        this.stopListening = this.source((change, scope) => void this.rightsChanged(change, scope));
       } catch (error) {
         // A source that cannot listen cannot tell a revocation: the subscription ends
         void subscription.hold(Promise.reject(error));
@@ -140,12 +165,12 @@ export class SubscriptionRechecks {
 
   /**
    * This function starts a check of each watched subscription that the change touches. The
-   * promise ends when each check ends.
+   * promise ends when each check ends. Each check gets the scope of the change.
    */
-  rightsChanged(change?: RightsChange): Promise<void> {
+  rightsChanged(change?: RightsChange, scope?: RightsScopes): Promise<void> {
     const checks: Array<Promise<void>> = [];
     for (const watch of [...this.watches]) {
-      if (touches(change, watch.principal)) checks.push(watch.recheck());
+      if (touches(change, watch.principal)) checks.push(watch.recheck("rights", scope));
     }
     return Promise.all(checks).then(() => undefined);
   }
@@ -166,7 +191,7 @@ export class SubscriptionRechecks {
     this.stopTimer(watch);
     const timer = this.clock.after(this.maxAgeMs, () => {
       if (watch.timer === timer) watch.timer = undefined;
-      void watch.recheck();
+      void watch.recheck("age");
     });
     // A check does not keep a Node process alive
     timer.unref?.();

package/src/procedures/collection/admission.ts

@@ -4,8 +4,10 @@
  * `admission` of `createCollectionProcedures()` gives the rules as data:
  *
  * - `admit` examines each row `{ id, value }` that a read gives. It has the shape of `AdmitItem`,
- *   the output filter of a host. The change events with values give it the same rows for each
- *   subscriber, so the reads and the events obey one rule.
+ *   the output filter of a host. The publisher of the change events gives it the rows of each
+ *   event for each subscriber (roadmap CLI-78). Thus the reads and the events obey one rule.
+ * - `admitsAll` tells that `admit` admits each row of a partition for a call. The events of such a
+ *   subscriber then pass without the filter of each row.
  * - `guard` examines each write `{ op, id, doc, prev }` before the storage changes. A refused write
  *   gets `FORBIDDEN` with the reason `write-not-allowed`.
  * - `versionOf` gives the version of a stored item (roadmap CLI-55). With it, a guarded write
@@ -16,8 +18,11 @@
  * (`admittedStorage()`). Each read and each write of each procedure goes through this view.
  *
  * - A refused row is absent: `get` gives undefined, `has` gives false, and the lists, `size`,
- *   `find` and `changes` do not have it. A delta of `changes` puts the id of a refused row in
- *   `deleted`, so a copy of the caller drops it.
+ *   `find` and `changes` do not have it.
+ * - A delta of `changes` gives only ids that the caller can read (roadmap CLI-78). The view
+ *   does not know which rows the caller read before the delta. Thus a delta with a refused row or
+ *   with a deleted row becomes a full answer of the admitted rows. The copy of the caller then
+ *   drops each other row. When `admitsAll` admits the caller, the delta stays as it is.
  * - An error of `admit` fails the read. It does not hide the rows, so a sync does not delete them.
  * - The guard reads the stored item before the write. With `versionOf`, the write expects the
  *   version of that item (roadmap CLI-16). A change of another writer between the read and the
@@ -66,10 +71,23 @@ export type CollectionWriteGuard = (write: CollectionWrite, invocation: Invocati
 export interface CollectionAdmission {
   /**
    * The rule of the rows. It gets each row `{ id, value }` of a read and the invocation of the
-   * call, and it gives true to admit the row. The change events with values apply it for each
-   * subscriber, with the invocation of the subscription.
+   * call, and it gives true to admit the row. The publisher of the change events applies it to the
+   * rows of each event for each subscriber, with the invocation of the subscription (roadmap
+   * CLI-78). A subscriber gets only the ids of the rows that it can read.
    */
   admit?: AdmitItem | undefined;
+  /**
+   * This function tells that the rule `admit` admits each row of a partition for a call (roadmap
+   * CLI-78). It gets the invocation and the partition (undefined for the collection without a
+   * partition). True: the change events reach the subscriber without the filter of each row, as
+   * before CLI-78. The publisher asks at the start of a subscription and at each re-check.
+   *
+   * - Give true only when `admit` admits each row of the partition. Else the subscriber gets the
+   *   ids of rows that it cannot read.
+   * - An error gives false.
+   * - Without it, the publisher examines each row of each event for each subscriber.
+   */
+  admitsAll?: ((invocation: Invocation, partition: string | undefined) => boolean | Promise<boolean>) | undefined;
   /** The guard of each `set`, `patch` and `delete`, also of the batches and of `clear`. */
   guard?: CollectionWriteGuard | undefined;
   /**
@@ -154,8 +172,9 @@ function withoutValue(conflict: VersionConflict): VersionConflict {
  * @param storage - The storage of the call: of the collection, or of its partition
  * @param admission - The rules of the collection
  * @param ctx - The context of the call. The rules get its invocation.
+ * @param partition - The partition of the call. `admitsAll` gets it.
  */
-export function admittedStorage<T>(storage: CollectionStorage<T>, admission: CollectionAdmission | undefined, ctx: ProcedureContext): CollectionStorage<T> {
+export function admittedStorage<T>(storage: CollectionStorage<T>, admission: CollectionAdmission | undefined, ctx: ProcedureContext, partition?: string): CollectionStorage<T> {
   const admit = admission?.admit;
   const guard = admission?.guard;
   if (!admit && !guard) return storage;
@@ -234,6 +253,23 @@ export function admittedStorage<T>(storage: CollectionStorage<T>, admission: Col
     return new VersionConflictError(kept, error instanceof Error ? error.message : undefined);
   };
 
+  /** This function tells if `admitsAll` admits the caller. An error gives false. */
+  const readsAll = async (): Promise<boolean> => {
+    if (!admission?.admitsAll || invocation === undefined) return false;
+    try {
+      return (await admission.admitsAll(invocation, partition)) === true;
+    } catch {
+      return false;
+    }
+  };
+  /** The full answer of `changes`: each admitted row, at a version that the rows include. */
+  const fullAnswer = async (): Promise<StorageChanges<T>> => {
+    const all = await storage.getChangesSince!(undefined);
+    if (all.full) return { version: all.version, full: true, changed: await admitted(all.changed), deleted: [] };
+    // A log that does not give all rows: the rows, read after the version, include that version
+    return { version: all.version, full: true, changed: await entries(), deleted: [] };
+  };
+
   const view: CollectionStorage<T> = {
     async get(id) {
       const value = await storage.get(id);
@@ -322,10 +358,15 @@ export function admittedStorage<T>(storage: CollectionStorage<T>, admission: Col
       if (!admit) return changes;
       const changed = await admitted(changes.changed);
       if (changes.full) return { ...changes, changed };
-      // A delta: the copy of the caller drops each refused row
       const kept = new Set(changed.map(([id]) => id));
       const refused = changes.changed.filter(([id]) => !kept.has(id)).map(([id]) => id);
-      return { ...changes, changed, deleted: [...changes.deleted, ...refused] };
+      // A delta of admitted rows only gives no id that the caller cannot read
+      if (refused.length === 0 && changes.deleted.length === 0) return { ...changes, changed };
+      // A caller that reads each row of the partition gets the delta as before (roadmap CLI-78)
+      if (await readsAll()) return { ...changes, changed, deleted: [...changes.deleted, ...refused] };
+      // The view does not know if the caller read a refused or a deleted row before. A full answer
+      // gives no other id, and the copy of the caller drops each row that it cannot read.
+      return fullAnswer();
     };
   }
   if (storage.query) {

package/src/procedures/collection/changes.ts

@@ -22,12 +22,18 @@
  *   listens to the topic, the procedures publish nothing, and the chain stops.
  * - The publishes of one storage and one topic run one at a time, in the order of the writes. A
  *   write resolves after its event is on the bus. A failed publish never fails the write.
+ * - With the rule `admission.admit`, the publisher filters the ids of each event for each
+ *   subscriber (roadmap CLI-78, `hint-filter.ts`). The event carries the rows after the changes,
+ *   from the change log. While a subscriber has a filter, each write first reads the rows before
+ *   it (`getBatch`). Thus a row that leaves the rule reaches that subscriber as a delete.
  */
 
 import type { EventBus } from "../../events/types.js";
 import { withRows } from "../../events/rows.js";
 import type { AdmitItem } from "../invoke.js";
 import type { StorageChanges } from "./storage.js";
+import type { CollectionAdmission } from "./admission.js";
+import { hasFilteredSubscriber, withHintImages, type HintRowState } from "./hint-filter.js";
 import type { RepositoryProvider } from "../types.js";
 import { collectionTopicTarget } from "./topic.js";
 
@@ -52,7 +58,10 @@ export interface CollectionChangeEvent {
    * Without the option, the event has no values: read them with `changes`.
    */
   readonly values?: ReadonlyArray<{ readonly id: string; readonly value: unknown }> | undefined;
-  /** With the option `values`: the changed ids whose values the filter refused. Read them with `changes`. */
+  /**
+   * With the option `values`: the changed ids whose values the output filter of the host refused.
+   * Read them with `changes`. A row that the rule of the rows refuses is not in the event (roadmap CLI-78).
+   */
   readonly withheld?: readonly string[] | undefined;
   /**
    * The version of each changed item, as `versionOf(id)` of the storage gives it (roadmap CLI-77).
@@ -90,6 +99,8 @@ export function collectionTopicReads(topic: string, repository?: RepositoryProvi
 /** The part of a storage that the change events read. */
 interface ChangeLog {
   getChangesSince?(since?: string): Promise<StorageChanges<unknown>>;
+  /** The stored items of the ids: the rows before a write, for the row filter of the subscribers (roadmap CLI-78). */
+  getBatch?(ids: string[]): Promise<Map<string, unknown>>;
 }
 
 /** A write that ended, and that no event told yet. */
@@ -99,6 +110,8 @@ interface EndedWrite {
   readonly origin: string | undefined;
   /** True when the chain had a version when the write started. */
   readonly anchored: boolean;
+  /** The stored items of the ids before the write, when a subscriber has a row filter (roadmap CLI-78). */
+  before?: ReadonlyMap<string, unknown> | undefined;
 }
 
 /** The chain of the events of one storage and one topic. */
@@ -152,7 +165,8 @@ function hint(version: string | undefined, origin: string | undefined): Collecti
 /**
  * The event of a delta with the values of the changed items. Each row `{ id, value }` passes the
  * output filter of each subscriber and the rule of the rows of the collection, and a refused row
- * goes from `values` to `withheld`.
+ * goes from `values` to `withheld`. The row filter of a subscriber (roadmap CLI-78) first takes the
+ * rows that the rule refuses out of the event. Thus only the output filter of the host withholds a row.
  */
 function withValues(event: CollectionChangeEvent, entries: ReadonlyArray<{ readonly id: string; readonly value: unknown }>, admit: AdmitItem | undefined): CollectionChangeEvent {
   return withRows(
@@ -174,7 +188,8 @@ function withValues(event: CollectionChangeEvent, entries: ReadonlyArray<{ reado
 }
 
 /** One publish: the event of the writes that ended since the last publish. */
-async function publish(chain: ChangeChain, storage: ChangeLog, bus: EventBus, topic: string, values: boolean, admit: AdmitItem | undefined): Promise<void> {
+async function publish(chain: ChangeChain, storage: ChangeLog, bus: EventBus, topic: string, values: boolean, admission: CollectionAdmission | undefined): Promise<void> {
+  const admit = admission?.admit;
   const writes = chain.ended.splice(0);
   // An earlier publish told these writes
   if (writes.length === 0) return;
@@ -211,7 +226,33 @@ async function publish(chain: ChangeChain, storage: ChangeLog, bus: EventBus, to
     deleted: changes.deleted,
     ...(origin !== undefined && { origin }),
   };
-  bus.emit(topic, values ? withValues(event, changes.changed.map(([id, value]) => ({ id, value })), admit) : event);
+  const out = values ? withValues(event, changes.changed.map(([id, value]) => ({ id, value })), admit) : event;
+  // The rows of the event for the row filter of each subscriber (roadmap CLI-78)
+  bus.emit(topic, admit ? withHintImages(out, { after: afterOf(changes), before: beforeOf(writes), admission: admission! }) : out);
+}
+
+/** The rows after the changes, from the change log: a changed id has its item, a deleted id has none. */
+function afterOf(changes: StorageChanges<unknown>): Map<string, HintRowState> {
+  const after = new Map<string, HintRowState>();
+  for (const id of changes.deleted) after.set(id, { found: false });
+  for (const [id, value] of changes.changed) after.set(id, { found: true, value });
+  return after;
+}
+
+/**
+ * The rows before the changes: for each id, the read of the first write that read it. An id
+ * without a read is unknown, so the filter of a subscriber makes a hint without ids for it.
+ */
+function beforeOf(writes: readonly EndedWrite[]): Map<string, HintRowState> {
+  const before = new Map<string, HintRowState>();
+  for (const write of writes) {
+    if (!write.before || write.ids === "*") continue;
+    for (const id of write.ids) {
+      if (before.has(id)) continue;
+      before.set(id, write.before.has(id) ? { found: true, value: write.before.get(id) } : { found: false });
+    }
+  }
+  return before;
 }
 
 /**
@@ -227,7 +268,7 @@ async function publish(chain: ChangeChain, storage: ChangeLog, bus: EventBus, to
  * @param origin - The origin of the write
  * @param write - The write
  * @param values - True: the events carry the values, for the output filter of each subscriber
- * @param admit - The rule of the rows of the collection: each subscriber applies it to the values (roadmap CLI-41)
+ * @param admission - The rules of the rows of the collection: each subscriber applies `admit` to the rows of the event (roadmap CLI-41, CLI-78)
  */
 export async function writeWithChangeEvent<R>(
   bus: EventBus | undefined,
@@ -237,16 +278,24 @@ export async function writeWithChangeEvent<R>(
   origin: string | undefined,
   write: () => Promise<R>,
   values = false,
-  admit?: AdmitItem,
+  admission?: CollectionAdmission,
 ): Promise<R> {
   if (bus === undefined || topic === undefined) return write();
   const chain = chainOf(storage, topic);
   const started: EndedWrite = { ids, origin, anchored: chain.anchor !== undefined };
+  // A subscriber with a row filter: the rows before the write tell it which rows left the rule (roadmap CLI-78)
+  if (admission?.admit && ids !== "*" && ids.length > 0 && storage.getBatch && hasFilteredSubscriber(bus, topic) && bus.hasSubscribers(topic)) {
+    try {
+      started.before = await storage.getBatch([...ids]);
+    } catch {
+      // Without the rows before the write, the filter of a subscriber makes a hint without ids
+    }
+  }
   try {
     return await write();
   } finally {
     chain.ended.push(started);
-    const run = chain.tail.then(() => publish(chain, storage, bus, topic, values, admit));
+    const run = chain.tail.then(() => publish(chain, storage, bus, topic, values, admission));
     chain.tail = run.catch(() => undefined);
     await chain.tail;
   }