@serve.zone/interfaces 31.8.0 → 32.0.0

package/ts/data/networklease.ts

@@ -1,7 +1,7 @@
 import type { TSha256Digest } from './immutableimage.js';
-import type { IRuntimeAuthorityReferenceV1 } from './runtimeassignment.js';
-import type { IRuntimeNetworkDnsWindow, IRuntimeNetworkNodeScopeV1 } from './networkprojection.js';
-import { snapshotRuntimeNetworkNodeScopeV1, snapshotRuntimeNetworkProjectionV1, validateRuntimeNetworkProjectionV1 } from './networkprojection.js';
+import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
+import type { IRuntimeNetworkDnsWindow, IRuntimeNetworkNodeScope } from './networkprojection.js';
+import { snapshotRuntimeNetworkNodeScope, snapshotRuntimeNetworkProjection, validateRuntimeNetworkProjection } from './networkprojection.js';
 import { captureNetwork, failNetwork, networkCounter, networkDigest, networkDnsWindow, networkEffectiveDnsWindow, networkEqual,
   networkHash, networkId, networkList, networkMaximumDnsLeaseMs, networkRecord, networkReference, networkReferenceOf,
   networkRenewsProjection, networkSafe, networkSameScope, networkScope, networkSignature, requireNetwork } from '../private/networkcontract.js';
@@ -15,8 +15,8 @@ import { captureNetwork, failNetwork, networkCounter, networkDigest, networkDnsW
  * projection by exact reference, so it never joins the projection chain and stops being
  * admissible the moment a successor projection is admitted.
  */
-export interface IRuntimeNetworkDnsLeaseRenewal extends IRuntimeNetworkNodeScopeV1 {
-  projection: IRuntimeAuthorityReferenceV1;
+export interface IRuntimeNetworkDnsLeaseRenewal extends IRuntimeNetworkNodeScope {
+  projection: IRuntimeAuthorityReference;
   /** Orders the renewals of one projection. A receiver may skip sequences, never go back. */
   sequence: number;
   /**
@@ -29,14 +29,14 @@ export interface IRuntimeNetworkDnsLeaseRenewal extends IRuntimeNetworkNodeScope
 
 /** Names one renewal without its window: what a receiver records and what an ACK repeats. */
 export interface IRuntimeNetworkDnsLeaseRenewalReference {
-  projection: IRuntimeAuthorityReferenceV1;
+  projection: IRuntimeAuthorityReference;
   sequence: number;
   digest: TSha256Digest;
 }
 
 export interface ISignedRuntimeNetworkDnsLeaseRenewal {
   /** The signing authority revision that also signs this controller's projections. */
-  authority: IRuntimeAuthorityReferenceV1;
+  authority: IRuntimeAuthorityReference;
   renewal: IRuntimeNetworkDnsLeaseRenewal;
   /** Ed25519 signature of the complete domain-separated envelope, lowercase hex. */
   signature: string;
@@ -51,7 +51,7 @@ export interface ISignedRuntimeNetworkDnsLeaseRenewal {
 export interface IHoldRuntimeNetworkDnsLeaseRenewalsRequest {
   /** The relay's own socket names the cluster; one relay carries every node of it, so the node is named here. */
   nodeId: string;
-  projection: IRuntimeAuthorityReferenceV1;
+  projection: IRuntimeAuthorityReference;
   /** Ascending by sequence. Empty holds nothing for this node. */
   renewals: ISignedRuntimeNetworkDnsLeaseRenewal[];
 }
@@ -75,6 +75,33 @@ export const runtimeNetworkDnsLeaseRenewalContract = Object.freeze({
   revocationLatency: 'a-detached-cluster-keeps-dns-authority-until-its-last-held-window-ends',
 } as const);
 
+/**
+ * Every reason a relay refuses to hold a run, in the words the refusal leads with.
+ *
+ * A hold is the one call whose outcome a controller cannot read back from its own records: the
+ * run lives in the relay's memory, so the refusal is the only statement about whether that node's
+ * windows are carried. The relay writes `<name>: <reason>` and the controller matches the name,
+ * which is why the names are stated here instead of being spelled out on both sides.
+ */
+export const holdRuntimeNetworkDnsLeaseRenewalsRefusals = Object.freeze([
+  /** The run itself is not a valid one, so nothing of it was held. */
+  'escrow-run-invalid',
+  /** This relay carries no session for that node; its renewals were not held. */
+  'escrow-node-not-carried',
+  /** The node's session changed while the run waited, so the run is for a session that is gone. */
+  'escrow-run-foreign-session',
+  /** The relay already holds a run that is provably newer for the same projection. */
+  'escrow-run-stale',
+  /** The run renews a projection that cannot be ordered against the held one. */
+  'escrow-run-unordered',
+  /** A node reached this method: a run is held only for the controller, over the relay's session. */
+  'escrow-cloudly-only',
+] as const);
+
+/** One of the reasons a relay answers instead of holding a run. */
+export type THoldRuntimeNetworkDnsLeaseRenewalsRefusal =
+  typeof holdRuntimeNetworkDnsLeaseRenewalsRefusals[number];
+
 export const snapshotRuntimeNetworkDnsLeaseRenewal = (value: unknown): IRuntimeNetworkDnsLeaseRenewal => networkSafe(() => {
   const item = networkRecord(captureNetwork(value), ['controller', 'nodeId', 'runtimeNamespace', 'projection', 'sequence', 'dns', 'digest']);
   return { ...networkScope(item), projection: networkReference(item.projection), sequence: networkCounter(item.sequence),
@@ -130,9 +157,9 @@ export const getRuntimeNetworkEffectiveDnsWindow = async (
   projectionValue: unknown, renewalValue: unknown | null,
 ): Promise<IRuntimeNetworkDnsWindow> => {
   try {
-    const projectionInput = snapshotRuntimeNetworkProjectionV1(projectionValue);
+    const projectionInput = snapshotRuntimeNetworkProjection(projectionValue);
     const renewalInput = renewalValue === null ? null : snapshotRuntimeNetworkDnsLeaseRenewal(renewalValue);
-    const projection = await validateRuntimeNetworkProjectionV1(projectionInput);
+    const projection = await validateRuntimeNetworkProjection(projectionInput);
     const renewal = renewalInput === null ? null : await validateRuntimeNetworkDnsLeaseRenewal(renewalInput);
     return networkEffectiveDnsWindow(projection, renewal);
   } catch { return failNetwork(); }
@@ -158,12 +185,12 @@ export const admitRuntimeNetworkDnsLeaseRenewal = async (
   try {
     // Snapshot ALL caller-owned inputs before the first asynchronous operation.
     const incoming = snapshotRuntimeNetworkDnsLeaseRenewal(value);
-    const projectionInput = snapshotRuntimeNetworkProjectionV1(currentProjectionValue);
+    const projectionInput = snapshotRuntimeNetworkProjection(currentProjectionValue);
     const previousInput = previousValue === null ? null : snapshotRuntimeNetworkDnsLeaseRenewal(previousValue);
-    const trusted = snapshotRuntimeNetworkNodeScopeV1(trustedScopeValue);
+    const trusted = snapshotRuntimeNetworkNodeScope(trustedScopeValue);
     const now = networkCounter(nowValue);
     const renewal = await validateRuntimeNetworkDnsLeaseRenewal(incoming);
-    const projection = await validateRuntimeNetworkProjectionV1(projectionInput);
+    const projection = await validateRuntimeNetworkProjection(projectionInput);
     requireNetwork(networkSameScope(projection, trusted) && networkRenewsProjection(renewal, projection));
     const previous = previousInput === null ? null : await validateRuntimeNetworkDnsLeaseRenewal(previousInput);
     if (previous !== null) {

package/ts/data/networknode.ts

@@ -0,0 +1,37 @@
+import type { IRuntimeNetworkProtectedAuthority } from './networkauthority.js';
+import { captureNetwork, networkCounter, networkId, networkRecord, networkSafe } from '../private/networkcontract.js';
+
+type TEgressOwner = IRuntimeNetworkProtectedAuthority['egressAuthorities'][number];
+
+/**
+ * One unmet condition of a node's runtime network readiness, in the order the node producer meets
+ * them: the node joins the protected authority's egress, every egress owner reports current
+ * protection, a handoff is reserved, the router selection carries it, the node's acknowledged
+ * projection carries it, and the node is a managed VPN member. `protection-receipts-pending` names
+ * the egress owners whose current receipts are still missing.
+ */
+export type TRuntimeNetworkNodeReadinessGap =
+  | { condition: 'egress-pending' | 'handoff-pending' | 'selection-pending' | 'projection-pending' | 'vpn-member-pending' }
+  | { condition: 'protection-receipts-pending'; owners: [TEgressOwner, ...TEgressOwner[]] };
+
+/** A node is ready exactly when nothing is missing. */
+export type IRuntimeNetworkNodeReadiness = { nodeId: string } & (
+  | { ready: true; missing: [] }
+  | { ready: false; missing: [TRuntimeNetworkNodeReadinessGap, ...TRuntimeNetworkNodeReadinessGap[]] }
+);
+
+/**
+ * The router incarnation of one node. A handoff's id and router incarnation id derive from it, so
+ * advancing it is the only way to give a node's router a fresh handoff.
+ */
+export interface IRuntimeRouterIncarnation {
+  /** The node id. */
+  id: string;
+  /** Starts at 1 with the node's first handoff; every reincarnation advances it by one. */
+  incarnation: number;
+}
+
+export const snapshotRuntimeRouterIncarnation = (value: unknown): IRuntimeRouterIncarnation => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['id', 'incarnation']);
+  return { id: networkId(item.id), incarnation: networkCounter(item.incarnation) };
+});