@serfab/cadre-core 1.17.0 → 1.18.0

package/src/membership-view.ts

@@ -0,0 +1,144 @@
+/**
+ * An in-memory copy of one small control table's rows, kept until the table changes, so the
+ * membership, owner, peer-record and admission-chain reads that every flow repeats cost nothing
+ * after the first.
+ * `ControlDatabase` keeps one per cached table and drops it from its table-change subscription
+ * (`docs/architecture.md` → "Membership rows view"); this class holds only the caching rules, so
+ * they are testable without a database.
+ */
+/**
+ * How long installed rows are served before the next read reloads them, change or no change.
+ * The reload is the only path for a change that reaches this node with no storage event: a
+ * machine outside the block's cohort (a cadre larger than its replication breadth), or one in
+ * the cohort that the writer could not reach when it committed (one side of a NAT pair; the
+ * cohort auto-connect scenarios). Longer than Optimystic's read-repair window
+ * ({@link OPTIMYSTIC_READ_REPAIR_WINDOW_MS}), so the reload's storage read starts the cohort
+ * consult that brings such a change in instead of being served from the local copy, and
+ * shorter than any reconcile backstop (`DEFAULT_CONTROL_COHORT_RECONCILE_MS`, 2 minutes), so
+ * the backstop pass, the only reader on an idle party, reloads rather than serving kept rows.
+ * The reload rate on an idle party is therefore the pass rate, and the staleness bound for
+ * such a change is the backstop, not this value.
+ *
+ * A machine that was offline when a sibling committed is covered sooner than either:
+ * `CadreNode` drops every view when a sibling becomes reachable (its identify on a new
+ * connection; `ControlDatabase.invalidateMembershipViews`), so the pass that starts then reads
+ * storage.
+ */
+export const MEMBERSHIP_VIEW_MAX_AGE_MS = 15_000;
+
+/**
+ * Optimystic's lazy read-repair window (`clusterPolicy.readRepairWindowMs`, which cadre does
+ * not set, so this is Optimystic's default): a read of a held block checked less than this
+ * long ago is served from the local copy without asking the cohort. A read after it is
+ * served locally too, but starts a cohort consult whose landing raises a table change.
+ *
+ * NOTE: a copy, since db-p2p exports no default for it. If cadre ever sets
+ * `readRepairWindowMs` in its cluster policy, derive this from that value.
+ */
+const OPTIMYSTIC_READ_REPAIR_WINDOW_MS = 10_000;
+
+/**
+ * How long after a sibling becomes reachable (its identify on a new connection) `CadreNode`
+ * drops the views a second time: one read-repair window, plus a second for timer slop. The
+ * drop at the identify is not enough by itself. A node's reads before the sibling arrived
+ * (its start pass, with no cohort to ask) stamp the window, so the reload the identify
+ * starts is served from the local copy without a consult and the view would keep the
+ * pre-connection rows until {@link MEMBERSHIP_VIEW_MAX_AGE_MS}. The reload past the window
+ * starts the consults that bring in what the sibling committed while this node was away.
+ */
+export const MEMBERSHIP_VIEW_RECONNECT_RELOAD_MS = OPTIMYSTIC_READ_REPAIR_WINDOW_MS + 1_000;
+
+/** One load's rows, and whether the view may keep them. */
+export interface MembershipViewLoad<Row> {
+	rows: readonly Row[];
+	/**
+	 * False when no later change event is guaranteed to reach the view for these rows (the
+	 * read that produced them did not arm the table's change bridge), so they serve only the
+	 * callers of this load.
+	 */
+	installable: boolean;
+}
+
+/**
+ * Reads the whole table. `retry` is the caller's: false from a caller holding the control
+ * write lock, whose read must not sleep a retry backoff.
+ */
+export type MembershipViewLoader<Row> = (retry: boolean) => Promise<MembershipViewLoad<Row>>;
+
+export interface MembershipViewOptions {
+	/** Default {@link MEMBERSHIP_VIEW_MAX_AGE_MS}. */
+	maxAgeMs?: number;
+	/** Monotonic clock in milliseconds; default `performance.now`. */
+	now?: () => number;
+}
+
+export class MembershipView<Row> {
+	private rows: readonly Row[] | undefined;
+	/** When the load that produced {@link rows} started: the rows are no older than this. */
+	private loadedAt = 0;
+	/** Bumped by every {@link invalidate}; a load installs only if it is unchanged since the load began. */
+	private generation = 0;
+	/**
+	 * The load each `retry` flag's callers share, current generation only. Separate per flag
+	 * so a caller under the write lock never awaits a retrying load's backoff sleep.
+	 */
+	private readonly inFlight = new Map<boolean, Promise<readonly Row[]>>();
+	private readonly maxAgeMs: number;
+	private readonly now: () => number;
+
+	constructor(private readonly loader: MembershipViewLoader<Row>, options: MembershipViewOptions = {}) {
+		this.maxAgeMs = options.maxAgeMs ?? MEMBERSHIP_VIEW_MAX_AGE_MS;
+		this.now = options.now ?? (() => performance.now());
+	}
+
+	/**
+	 * The table's rows: the installed copy while it is younger than the maximum age, otherwise a
+	 * load, shared with every caller of the same `retry` flag that arrives while it runs. A load
+	 * that raced an {@link invalidate} answers its own callers with what it read, as an uncached
+	 * read would have, and keeps nothing. A failed load keeps nothing and rejects.
+	 */
+	read(retry: boolean): Promise<readonly Row[]> {
+		if (this.rows !== undefined && this.now() - this.loadedAt < this.maxAgeMs) {
+			return Promise.resolve(this.rows);
+		}
+		return this.inFlight.get(retry) ?? this.startLoad(retry);
+	}
+
+	/** Read the table without serving, joining or keeping anything. */
+	async readThrough(retry: boolean): Promise<readonly Row[]> {
+		return (await this.loader(retry)).rows;
+	}
+
+	/**
+	 * Drop the installed rows and every load in flight, so the next read loads afresh and no
+	 * earlier load installs. Synchronous and flag-setting only: the table-change handler calls
+	 * it inside the committing call.
+	 */
+	invalidate(): void {
+		this.generation++;
+		this.rows = undefined;
+		this.inFlight.clear();
+	}
+
+	private startLoad(retry: boolean): Promise<readonly Row[]> {
+		const load = this.load(retry, this.generation, this.now());
+		this.inFlight.set(retry, load);
+		const forget = (): void => {
+			if (this.inFlight.get(retry) === load) {
+				this.inFlight.delete(retry);
+			}
+		};
+		// Both arms handled, so a failed load rejects only for the callers awaiting it.
+		void load.then(forget, forget);
+		return load;
+	}
+
+	private async load(retry: boolean, generation: number, startedAt: number): Promise<readonly Row[]> {
+		const { rows, installable } = await this.loader(retry);
+		if (installable && generation === this.generation) {
+			this.rows = rows;
+			this.loadedAt = startedAt;
+		}
+		return rows;
+	}
+}

package/src/owner-grant-protocol.ts

@@ -368,7 +368,7 @@ export function verifyOwnerGrantReply(
 // ── Member side (handler) ────────────────────────────────────────────────────
 
 /** The control-database surface a redemption needs; a `ControlDatabase` satisfies it. */
-export type OwnerGrantStore = Pick<ControlDatabase, 'seatOwnerGrant' | 'isOwnerGrantLive' | 'redeemOwnerGrant'>;
+export type OwnerGrantStore = Pick<ControlDatabase, 'queryOwnerGrant' | 'seatOwnerGrant' | 'isOwnerGrantLive' | 'redeemOwnerGrant'>;
 
 export interface OwnerGrantHandlerOptions extends MemberRedemptionHandlerOptions {
   store: OwnerGrantStore;
@@ -385,10 +385,11 @@ const REDEEM_CONSTRAINT_CODES: ReadonlyArray<ConstraintRefusalRow<OwnerGrantReje
  * Member side of the grant protocol (`MemberRedemptionHandler` has the shape): after the
  * request's shape, it checks the party and both signatures — nothing about the connecting
  * peer, whose identity is unrelated to the key it seats — then seats the row from the bundle
- * and redeems. An issuer this member does not know as an owner is the one retryable refusal
- * left: the holder tries the next address, which may hold the issuer's row.
+ * when this member holds none and redeems. An issuer this member does not know as an owner is
+ * the one retryable refusal left: the holder tries the next address, which may hold the
+ * issuer's row.
  */
-export class OwnerGrantHandler extends MemberRedemptionHandler<OwnerGrantRedeemRequest, OwnerGrantRedeemReply> {
+export class OwnerGrantHandler extends MemberRedemptionHandler<OwnerGrantRedeemRequest, OwnerGrantRedeemReply, OwnerGrantRow> {
   private readonly store: OwnerGrantStore;
   protected readonly busyRefusal = rejection('busy', 'Too many concurrent redemptions');
   protected readonly internalRefusal = rejection('internal', 'Internal redemption error');
@@ -414,25 +415,25 @@ export class OwnerGrantHandler extends MemberRedemptionHandler<OwnerGrantRedeemR
     return null;
   }
 
-  protected isLive(request: OwnerGrantRedeemRequest): Promise<boolean> {
-    return this.store.isOwnerGrantLive(request.grant);
+  protected readHeld(request: OwnerGrantRedeemRequest): Promise<OwnerGrantRow | null> {
+    return this.store.queryOwnerGrant(request.grant.key);
   }
 
-  /** The two writes — the seat (its own transaction; a no-op when held) and the redemption — each answered by name when it fails. */
-  protected async redeemAdmitted(request: OwnerGrantRedeemRequest, remotePeerId: string): Promise<OwnerGrantRedeemReply> {
-    try {
-      await this.store.seatOwnerGrant(request.grant);
-    } catch (error) {
-      if (error instanceof OwnerGrantIssuerUnknownError) {
-        return rejection('issuer-unknown', 'The grant\'s issuer is not known as an owner here');
-      }
-      log('seating grant %s from %s failed: %o', request.grant.key, remotePeerId, error);
-      return constraintRefusal(error, REDEEM_CONSTRAINT_CODES) ?? writeFailureRefusal(error);
+  protected isLive(request: OwnerGrantRedeemRequest, held: OwnerGrantRow | null): Promise<boolean> {
+    return this.store.isOwnerGrantLive(request.grant, held);
+  }
+
+  /** The two writes — the seat only when this member holds no row, and the redemption, carrying the held row — as `CadreInviteHandler.redeemAdmitted`. */
+  protected async redeemAdmitted(request: OwnerGrantRedeemRequest, remotePeerId: string, held: OwnerGrantRow | null): Promise<OwnerGrantRedeemReply> {
+    if (held === null) {
+      const refused = await this.seat(request, remotePeerId);
+      if (refused) return refused;
     }
     let alreadyOwner: boolean;
     try {
       const result = await this.store.redeemOwnerGrant({
         grantKey: request.grant.key,
+        ...(held ? { held } : {}),
         seatedKey: request.ownerKey,
         usageStampId: request.usageStampId,
         grantSig: request.grantSig,
@@ -447,8 +448,22 @@ export class OwnerGrantHandler extends MemberRedemptionHandler<OwnerGrantRedeemR
       log('redeeming grant %s for %s failed: %o', request.grant.key, request.ownerKey, error);
       return constraintRefusal(error, REDEEM_CONSTRAINT_CODES) ?? writeFailureRefusal(error);
     }
-    // The row as held: the seat inserted this copy verbatim, or found the same row.
-    return { accepted: true, partyId: this.partyId, grant: request.grant, alreadyOwner };
+    // The row as held: read before the write, or the bundle's copy the seat inserted verbatim or found.
+    return { accepted: true, partyId: this.partyId, grant: held ?? request.grant, alreadyOwner };
+  }
+
+  /** Seat the bundle's copy of the row; a refusal answered by name, or null once it is held. */
+  private async seat(request: OwnerGrantRedeemRequest, remotePeerId: string): Promise<OwnerGrantRejection | null> {
+    try {
+      await this.store.seatOwnerGrant(request.grant);
+      return null;
+    } catch (error) {
+      if (error instanceof OwnerGrantIssuerUnknownError) {
+        return rejection('issuer-unknown', 'The grant\'s issuer is not known as an owner here');
+      }
+      log('seating grant %s from %s failed: %o', request.grant.key, remotePeerId, error);
+      return constraintRefusal(error, REDEEM_CONSTRAINT_CODES) ?? writeFailureRefusal(error);
+    }
   }
 }
 

package/src/peer-addr-book.ts

@@ -4,7 +4,7 @@
  * — Optimystic's cluster client, repo client, FRET ping/announce, all funnelling
  * into `libp2p.dialProtocol(peerId, …)` — has an address to use for a sibling
  * whose connection has dropped, instead of failing with `NoValidAddressesError`
- * until the next reconcile pass happens to re-dial it.
+ * until the reconcile pass the drop starts re-dials it.
  *
  * Shared by the control-cohort reconcile pass and the strand one (both in
  * `CadreNode`): each resolves a peer's addresses its own way and then needs
@@ -190,9 +190,10 @@ function lastAddressedPeerId(parsed: Multiaddr): string | null {
  * that id is the address's FIRST `/p2p/` component (`dedupe-addresses.js`), so a
  * plain address round-trips without its suffix while a relayed one — whose first
  * `/p2p/` names the relay — keeps it. Comparing and de-duplicating on this
- * suffix-stripped form matches either shape.
+ * suffix-stripped form matches either shape. `CadreNode.claimNode` compares a QR
+ * code's addresses with a connection's remote address on it for the same reason.
  */
-function addrKey(addr: string, peerId: PeerId): string {
+export function addrKey(addr: string, peerId: PeerId): string {
   const suffix = `/p2p/${peerId.toString()}`;
   return addr.endsWith(suffix) ? addr.slice(0, -suffix.length) : addr;
 }