@serve.zone/interfaces 32.20.1 → 32.22.0

package/ts/data/runtimelocalstorageclaim.ts

@@ -0,0 +1,275 @@
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAssignment, IRuntimeAuthorityReference, IRuntimeController } from './runtimeassignment.js';
+import { snapshotRuntimeAssignment, validateRuntimeAssignment } from './runtimeassignment.js';
+import type { IRuntimeSessionBinding } from './runtimesession.js';
+import { snapshotRuntimeSessionBinding } from './runtimesession.js';
+import { captureNetwork, networkController, networkDigest, networkEqual, networkHash, networkId,
+  networkNodeId, networkRecord, networkReference, networkReferenceOf, networkRevision, requireNetwork,
+} from '../private/networkcontract.js';
+import { isRuntimeIdentityNumber } from '../private/runtimepolicy.js';
+import { createStorageContractReaders } from '../private/storagecontract.js';
+
+/**
+ * Where a local storage claim's bytes live, named by kind and never by path.
+ *
+ * `directory` is a node-local directory the node derives from the claim's identity under a root
+ * only the node knows. Network filesystems join this union as further kinds; their credentials
+ * travel as secrets and never inside a claim.
+ */
+export type TRuntimeLocalStorageSource = { kind: 'directory' };
+
+/** The owner and permission bits a node gives an `empty` volume's root directory when it creates it. */
+export interface IRuntimeLocalStorageOwnership {
+  uid: number;
+  gid: number;
+  /** Numeric directory permission bits, for example `0o750`; setuid is refused. */
+  mode: number;
+}
+
+/** Where the volume appears inside the workload's container. */
+export interface IRuntimeLocalStorageMount {
+  mountPath: string;
+  readOnly: boolean;
+}
+
+/**
+ * `bound` keeps the volume and lets the node mount it; `purge` orders the node to delete the
+ * volume's bytes. A purge always follows a bound generation of the same claim.
+ */
+export type TRuntimeLocalStorageLifecycle = 'bound' | 'purge';
+
+/**
+ * A controller's authority for one retained, node-local volume of one service.
+ *
+ * Cloudly and Onebox issue it alike. It names the volume by identity only: no host path, no
+ * device, no mount option and no credential. The node resolves the identity to its own storage.
+ *
+ * `initialization` says what the node does when the volume does not exist yet. `empty` creates an
+ * empty root with `initialOwnership`, which it must state, so a workload that runs as the image's
+ * own user never meets a root-owned directory by accident. `import` waits for the volume's bytes to
+ * be imported and states no ownership: an imported tree keeps the ownership it carries.
+ */
+export interface IRuntimeLocalStorageClaim {
+  id: string;
+  generation: number;
+  previous: IRuntimeAuthorityReference | null;
+  controller: IRuntimeController;
+  organizationId: string;
+  clusterId: string;
+  nodeId: string;
+  runtimeNamespace: string;
+  serviceId: string;
+  /** The service's own name for this volume, stable across every generation of the claim. */
+  volumeId: string;
+  source: TRuntimeLocalStorageSource;
+  initialization: 'empty' | 'import';
+  /** Required for `empty`, `null` for `import`. */
+  initialOwnership: IRuntimeLocalStorageOwnership | null;
+  mount: IRuntimeLocalStorageMount;
+  accessMode: 'ReadWriteOnce';
+  reclaimPolicy: 'retain';
+  lifecycle: TRuntimeLocalStorageLifecycle;
+  digest: TSha256Digest;
+}
+
+/**
+ * What the node holds for the volume after admission.
+ *
+ * `ready` exists and may be mounted; `import-required` is an `import` volume whose bytes have not
+ * arrived; `purged` is a volume whose bytes the node deleted; `uncertain` is a volume the node
+ * cannot vouch for, which it neither mounts nor deletes until an operator decides.
+ */
+export type TRuntimeLocalStorageClaimState = 'ready' | 'import-required' | 'purged' | 'uncertain';
+
+/** Controller push over the node's current authenticated session. */
+export interface IApplyRuntimeLocalStorageClaimRequest {
+  session: IRuntimeSessionBinding;
+  claim: IRuntimeLocalStorageClaim;
+}
+
+/**
+ * Durable admission acknowledgement. `claim` is the reference of the claim that was sent, also on
+ * a `historical` answer, whose `state` describes the newer generation the node holds.
+ */
+export interface IApplyRuntimeLocalStorageClaimResponse {
+  status: 'accepted' | 'replay' | 'historical';
+  state: TRuntimeLocalStorageClaimState;
+  claim: IRuntimeAuthorityReference;
+}
+
+export const runtimeLocalStorageClaimContract = Object.freeze({
+  digestDomain: 'serve.zone/runtime-local-storage-claim',
+  error: 'Runtime local storage claim contract rejected.',
+  accessMode: 'ReadWriteOnce',
+  reclaimPolicy: 'retain',
+  /** Every permission bit a claim may state: setgid, sticky and the rwx triplets. */
+  directoryModeBits: 0o3777,
+} as const);
+
+const fail = (): never => { throw new Error(runtimeLocalStorageClaimContract.error); };
+const safe = <T>(operationArg: () => T): T => { try { return operationArg(); } catch { return fail(); } };
+const { readMountPath } = createStorageContractReaders(fail);
+const claimStates = ['ready', 'import-required', 'purged', 'uncertain'] as const;
+const responseStatuses = ['accepted', 'replay', 'historical'] as const;
+
+const sourceOf = (valueArg: unknown): TRuntimeLocalStorageSource => {
+  const value = networkRecord(valueArg, ['kind']);
+  requireNetwork(value.kind === 'directory');
+  return { kind: 'directory' };
+};
+
+const ownershipOf = (valueArg: unknown): IRuntimeLocalStorageOwnership => {
+  const value = networkRecord(valueArg, ['uid', 'gid', 'mode']);
+  requireNetwork(isRuntimeIdentityNumber(value.uid) && isRuntimeIdentityNumber(value.gid)
+    && Number.isSafeInteger(value.mode) && (value.mode as number) >= 0
+    && ((value.mode as number) & ~runtimeLocalStorageClaimContract.directoryModeBits) === 0);
+  return { uid: value.uid as number, gid: value.gid as number, mode: value.mode as number };
+};
+
+const mountOf = (valueArg: unknown): IRuntimeLocalStorageMount => {
+  const value = networkRecord(valueArg, ['mountPath', 'readOnly']);
+  requireNetwork(typeof value.readOnly === 'boolean');
+  return { mountPath: readMountPath(value.mountPath, 'mountPath'), readOnly: value.readOnly };
+};
+
+/** Detached exact-schema snapshot. The digest is a separate check. */
+export const snapshotRuntimeLocalStorageClaim = (valueArg: unknown): IRuntimeLocalStorageClaim => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['id', 'generation', 'previous', 'controller',
+    'organizationId', 'clusterId', 'nodeId', 'runtimeNamespace', 'serviceId', 'volumeId', 'source',
+    'initialization', 'initialOwnership', 'mount', 'accessMode', 'reclaimPolicy', 'lifecycle', 'digest']);
+  const { id, generation, previous } = networkRevision(value);
+  requireNetwork((value.initialization === 'empty' && value.initialOwnership !== null)
+    || (value.initialization === 'import' && value.initialOwnership === null));
+  requireNetwork(value.accessMode === 'ReadWriteOnce' && value.reclaimPolicy === 'retain');
+  requireNetwork(value.lifecycle === 'bound' || (value.lifecycle === 'purge' && previous !== null));
+  return {
+    id, generation, previous,
+    controller: networkController(value.controller),
+    organizationId: networkId(value.organizationId),
+    clusterId: networkId(value.clusterId),
+    nodeId: networkNodeId(value.nodeId),
+    runtimeNamespace: networkId(value.runtimeNamespace),
+    serviceId: networkId(value.serviceId),
+    volumeId: networkId(value.volumeId),
+    source: sourceOf(value.source),
+    initialization: value.initialization as IRuntimeLocalStorageClaim['initialization'],
+    initialOwnership: value.initialOwnership === null ? null : ownershipOf(value.initialOwnership),
+    mount: mountOf(value.mount),
+    accessMode: 'ReadWriteOnce',
+    reclaimPolicy: 'retain',
+    lifecycle: value.lifecycle as TRuntimeLocalStorageLifecycle,
+    digest: networkDigest(value.digest),
+  };
+});
+
+export const computeRuntimeLocalStorageClaimDigest = async (valueArg: unknown): Promise<TSha256Digest> => {
+  const claim = snapshotRuntimeLocalStorageClaim(valueArg);
+  try {
+    return await networkHash(runtimeLocalStorageClaimContract.digestDomain, claim);
+  } catch {
+    return fail();
+  }
+};
+
+export const validateRuntimeLocalStorageClaim = async (valueArg: unknown): Promise<string[]> => {
+  try {
+    const claim = snapshotRuntimeLocalStorageClaim(valueArg);
+    return claim.digest === await computeRuntimeLocalStorageClaimDigest(claim)
+      ? [] : ['runtime local storage claim digest does not match'];
+  } catch {
+    return ['runtime local storage claim must use its exact canonical schema'];
+  }
+};
+
+/** The `{ id, generation, digest }` an assignment's `workload.storage` seals for this claim. */
+export const getRuntimeLocalStorageClaimReference = (valueArg: unknown): IRuntimeAuthorityReference =>
+  networkReferenceOf(snapshotRuntimeLocalStorageClaim(valueArg));
+
+/**
+ * Content binding only: the assignment seals this exact claim, and both name the same controller,
+ * organization, node, runtime namespace and service. A purge claim binds to no assignment, because
+ * no workload may mount a volume being deleted. The cluster ID must come from the authenticated
+ * session, because an assignment does not contain one.
+ */
+export const bindRuntimeLocalStorageClaimToAssignment = async (
+  claimArg: unknown, assignmentArg: unknown, expectedClusterIdArg: unknown,
+): Promise<{ claim: IRuntimeLocalStorageClaim; assignment: IRuntimeAssignment }> => {
+  const claim = snapshotRuntimeLocalStorageClaim(claimArg);
+  const assignment = safe(() => snapshotRuntimeAssignment(assignmentArg));
+  if ((await validateRuntimeLocalStorageClaim(claim)).length
+    || (await validateRuntimeAssignment(assignment)).length) fail();
+  safe(() => {
+    const expectedClusterId = networkId(expectedClusterIdArg);
+    const reference = assignment.workload.storage.find((itemArg) => itemArg.id === claim.id);
+    requireNetwork(reference !== undefined
+      && networkEqual(reference, getRuntimeLocalStorageClaimReference(claim))
+      && claim.lifecycle === 'bound'
+      && claim.clusterId === expectedClusterId
+      && networkEqual(assignment.controller, claim.controller)
+      && assignment.organizationId === claim.organizationId
+      && assignment.nodeId === claim.nodeId
+      && assignment.runtimeNamespace === claim.runtimeNamespace
+      && assignment.serviceId === claim.serviceId);
+  });
+  return { claim, assignment };
+};
+
+export const snapshotApplyRuntimeLocalStorageClaimRequest = (
+  valueArg: unknown,
+): IApplyRuntimeLocalStorageClaimRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['session', 'claim']);
+  return { session: snapshotRuntimeSessionBinding(value.session), claim: snapshotRuntimeLocalStorageClaim(value.claim) };
+});
+
+export const snapshotApplyRuntimeLocalStorageClaimResponse = (
+  valueArg: unknown,
+): IApplyRuntimeLocalStorageClaimResponse => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['status', 'state', 'claim']);
+  requireNetwork((responseStatuses as readonly unknown[]).includes(value.status)
+    && (claimStates as readonly unknown[]).includes(value.state));
+  return {
+    status: value.status as IApplyRuntimeLocalStorageClaimResponse['status'],
+    state: value.state as TRuntimeLocalStorageClaimState,
+    claim: networkReference(value.claim),
+  };
+});
+
+/**
+ * Admission-side content binding, not authentication: `trustedSessionArg` must be the node's
+ * CURRENT authenticated session, never read from the request. The request's session must equal it,
+ * the claim must name its controller, cluster, node and runtime namespace, and its digest must hold.
+ */
+export const bindApplyRuntimeLocalStorageClaimRequest = async (
+  valueArg: unknown, trustedSessionArg: unknown,
+): Promise<IApplyRuntimeLocalStorageClaimRequest> => {
+  const request = snapshotApplyRuntimeLocalStorageClaimRequest(valueArg);
+  const trustedSession = safe(() => snapshotRuntimeSessionBinding(trustedSessionArg));
+  if ((await validateRuntimeLocalStorageClaim(request.claim)).length) fail();
+  safe(() => requireNetwork(networkEqual(request.session, trustedSession)
+    && networkEqual(request.claim.controller, trustedSession.controller)
+    && request.claim.clusterId === trustedSession.clusterId
+    && request.claim.nodeId === trustedSession.nodeId
+    && request.claim.runtimeNamespace === trustedSession.runtimeNamespace));
+  return request;
+};
+
+/**
+ * Matches an answer to the exact claim that was sent. An `accepted` or `replay` answer must state a
+ * state the claim can be in: a bound claim is `ready`, `import-required` (for an `import` claim
+ * only) or `uncertain`; a purge is `purged` or `uncertain`. A `historical` answer describes the
+ * newer generation the node holds, so its state is not judged against the sent claim.
+ */
+export const bindApplyRuntimeLocalStorageClaimResponse = (
+  valueArg: unknown, requestArg: unknown,
+): IApplyRuntimeLocalStorageClaimResponse => safe(() => {
+  const response = snapshotApplyRuntimeLocalStorageClaimResponse(valueArg);
+  const { claim } = snapshotApplyRuntimeLocalStorageClaimRequest(requestArg);
+  requireNetwork(networkEqual(response.claim, getRuntimeLocalStorageClaimReference(claim)));
+  if (response.status !== 'historical') {
+    requireNetwork(claim.lifecycle === 'purge'
+      ? response.state === 'purged' || response.state === 'uncertain'
+      : response.state === 'ready' || response.state === 'uncertain'
+        || (response.state === 'import-required' && claim.initialization === 'import'));
+  }
+  return response;
+});

package/ts/data/serviceruntime.ts

@@ -76,19 +76,25 @@ export const serviceRuntimeContract = Object.freeze({
   maximumAssignmentPageSize: 256,
 } as const);
 
-const serviceRuntimeWaitingReasons = ['node-network-pending', 'conflict', 'failure-backoff'] as const;
+const serviceRuntimeWaitingReasons = [
+  'node-network-pending', 'conflict', 'failure-backoff', 'storage-import-pending', 'bindings-pending',
+] as const;
 const serviceRuntimeRefusals = [
   'cluster-runtime-missing', 'organization-missing', 'image-plan-missing', 'platform-unsupported',
   'secrets-unsupported', 'volumes-unsupported', 'port-protocol-unsupported', 'ports-too-many',
   'readiness-target-undeclared', 'environment-too-large', 'no-eligible-node', 'replica-limit',
   'node-authority-unsupported', 'network-policy-missing', 'network-policy-mismatch',
   'network-workload-pool-missing', 'network-workload-pool-exhausted',
+  'volume-driver-unsupported', 'volume-options-unsupported', 'volume-shared-unsupported',
+  'volume-placement-unsupported',
 ] as const;
 
 /**
  * Why the producer is not converging yet, though nothing needs an administrator:
  * `node-network-pending` waits for a node's network readiness, `conflict` for a sweep over inputs
- * that changed while it ran, `failure-backoff` for a failed replica's backoff to elapse.
+ * that changed while it ran, `failure-backoff` for a failed replica's backoff to elapse,
+ * `storage-import-pending` for an `import` local storage claim whose bytes have not arrived on its
+ * node, and `bindings-pending` for the secret manifest to cover every enabled binding of the service.
  */
 export type TServiceRuntimeWaitingReason = typeof serviceRuntimeWaitingReasons[number];
 
@@ -101,6 +107,11 @@ export type TServiceRuntimeWaitingReason = typeof serviceRuntimeWaitingReasons[n
  * node whose session resolved fewer workload authorities than this spec needs, which the admit step
  * refuses rather than handing the node work it would silently park. An attached network needs an
  * explicit matching policy and a current workload address pool; neither is defaulted.
+ *
+ * The volume refusals name what a local storage claim cannot express: `volume-driver-unsupported`
+ * a volume of a driver other than a node-local directory, `volume-options-unsupported` driver or
+ * mount options, `volume-shared-unsupported` one volume mounted by more than one replica or service,
+ * and `volume-placement-unsupported` a placement that does not pin each volume to one node.
  */
 export type TServiceRuntimeRefusal = typeof serviceRuntimeRefusals[number];
 

package/ts/private/ipaddress.ts

@@ -0,0 +1,140 @@
+/**
+ * Canonical IP address and prefix text, read into numbers a prefix test can compare.
+ *
+ * Only the one canonical spelling of each value is accepted: a dotted quad without leading zeros
+ * for IPv4, and the RFC 5952 form for IPv6 (lowercase, no leading zeros, the longest run of two or
+ * more zero groups compressed, the first run on a tie). A value two peers could spell differently
+ * would let the same address pass one comparison and fail another, so a non-canonical spelling is
+ * refused rather than normalized. IPv6 text with an embedded dotted quad or a zone index is refused
+ * for the same reason.
+ */
+
+export type TIpAddressFamily = 4 | 6;
+
+export interface IIpAddressValue {
+  family: TIpAddressFamily;
+  value: bigint;
+}
+
+export interface IIpPrefixValue {
+  family: TIpAddressFamily;
+  network: bigint;
+  length: number;
+}
+
+const familyBits = (familyArg: TIpAddressFamily): number => (familyArg === 4 ? 32 : 128);
+
+const parseIpv4 = (valueArg: string): bigint | null => {
+  if (valueArg.length > 15) {
+    return null;
+  }
+  const octets = valueArg.split('.');
+  if (octets.length !== 4
+    || !octets.every((octetArg) => /^(?:0|[1-9][0-9]{0,2})$/.test(octetArg) && Number(octetArg) <= 255)) {
+    return null;
+  }
+  return octets.reduce((sumArg, octetArg) => (sumArg << 8n) | BigInt(Number(octetArg)), 0n);
+};
+
+const parseIpv6Groups = (valueArg: string): string[] | null => {
+  if (valueArg.length > 39 || !/^[0-9a-f:]+$/.test(valueArg)) {
+    return null;
+  }
+  const halves = valueArg.split('::');
+  if (halves.length > 2) {
+    return null;
+  }
+  const head = halves[0] === '' ? [] : halves[0].split(':');
+  if (halves.length === 1) {
+    return head;
+  }
+  const tail = halves[1] === '' ? [] : halves[1].split(':');
+  if (head.length + tail.length > 7) {
+    return null;
+  }
+  return [...head, ...new Array<string>(8 - head.length - tail.length).fill('0'), ...tail];
+};
+
+const parseIpv6 = (valueArg: string): bigint | null => {
+  const groups = parseIpv6Groups(valueArg);
+  if (groups === null || groups.length !== 8
+    || !groups.every((groupArg) => /^[0-9a-f]{1,4}$/.test(groupArg))) {
+    return null;
+  }
+  return groups.reduce((sumArg, groupArg) => (sumArg << 16n) | BigInt(parseInt(groupArg, 16)), 0n);
+};
+
+/** The RFC 5952 text of one IPv6 address. */
+const formatIpv6 = (valueArg: bigint): string => {
+  const groups: number[] = [];
+  for (let index = 7; index >= 0; index--) {
+    groups.push(Number((valueArg >> BigInt(index * 16)) & 0xffffn));
+  }
+  let bestStart = -1;
+  let bestLength = 0;
+  for (let start = 0; start < 8;) {
+    if (groups[start] !== 0) {
+      start++;
+      continue;
+    }
+    let end = start;
+    while (end < 8 && groups[end] === 0) {
+      end++;
+    }
+    if (end - start > bestLength) {
+      bestStart = start;
+      bestLength = end - start;
+    }
+    start = end;
+  }
+  const text = groups.map((groupArg) => groupArg.toString(16));
+  if (bestLength < 2) {
+    return text.join(':');
+  }
+  return `${text.slice(0, bestStart).join(':')}::${text.slice(bestStart + bestLength).join(':')}`;
+};
+
+/** One canonical address literal of either family, or `null` for anything else. */
+export const parseCanonicalIpAddress = (valueArg: unknown): IIpAddressValue | null => {
+  if (typeof valueArg !== 'string') {
+    return null;
+  }
+  const ipv4 = parseIpv4(valueArg);
+  if (ipv4 !== null) {
+    return { family: 4, value: ipv4 };
+  }
+  const ipv6 = parseIpv6(valueArg);
+  return ipv6 !== null && formatIpv6(ipv6) === valueArg ? { family: 6, value: ipv6 } : null;
+};
+
+/**
+ * One canonical prefix `<address>/<length>` of either family whose host bits are all zero, or
+ * `null` for anything else. The length is written without leading zeros.
+ */
+export const parseCanonicalIpPrefix = (valueArg: unknown): IIpPrefixValue | null => {
+  if (typeof valueArg !== 'string') {
+    return null;
+  }
+  const parts = valueArg.split('/');
+  if (parts.length !== 2 || !/^(?:0|[1-9][0-9]{0,2})$/.test(parts[1])) {
+    return null;
+  }
+  const address = parseCanonicalIpAddress(parts[0]);
+  const length = Number(parts[1]);
+  if (address === null || length > familyBits(address.family)) {
+    return null;
+  }
+  const hostBits = BigInt(familyBits(address.family) - length);
+  return address.value % (1n << hostBits) === 0n
+    ? { family: address.family, network: address.value, length }
+    : null;
+};
+
+/** True when the address lies inside the prefix; families never contain each other. */
+export const ipPrefixContains = (prefixArg: IIpPrefixValue, addressArg: IIpAddressValue): boolean => {
+  if (prefixArg.family !== addressArg.family) {
+    return false;
+  }
+  const hostBits = BigInt(familyBits(prefixArg.family) - prefixArg.length);
+  return addressArg.value >> hostBits === prefixArg.network >> hostBits;
+};

package/ts/private/storagecontract.ts

@@ -614,6 +614,7 @@ export const createStorageContractReaders = (failArg: TCanonicalJsonFailure) =>
     readCapacityQuantity,
     capacityQuantityBytes,
     readEnvironmentKey,
+    readMountPath,
     normalizeCapacityRequest,
     normalizeDelivery,
     normalizeObjectStorageRequest,

package/ts/requests/clusteringress.ts

@@ -1,4 +1,10 @@
 import * as clusterIngressInterfaces from '../data/clusteringress.js';
+import type {
+  IClusterIngressDesignation,
+  IClusterIngressDesignationRequest,
+} from '../data/clusteringressdesignation.js';
+import type { IServiceRuntimeSpec } from '../data/serviceruntime.js';
+import type { IIdentityCredential } from '../data/user.js';
 import type { IProtocolOffer } from '../protocol.js';
 import * as plugins from '../plugins.js';
 
@@ -70,6 +76,12 @@ export interface IReq_Relay_Cloudly_GetClusterRouteTable extends plugins.typedre
  * Both hops judge the body in the one server order `protocol.readProtocolOffer`
  * states, negotiating before the bearer is verified, as the shape states at
  * `validateClusterIngressRegistration`.
+ *
+ * A protocol mismatch is refused with `IProtocolRefusal`; every other refusal
+ * travels as `IClusterIngressRegistrationRefusal` in `TypedResponseError.errorData`,
+ * naming the reason and the `retryAfterMs` the ingress waits before it registers
+ * again. The relay forwards Cloudly's refusal untouched and refuses with the same
+ * shape when it cannot reach Cloudly at all (`not-ready`).
  */
 export interface IReq_Ingress_Relay_Cloudly_RegisterClusterIngress extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -100,6 +112,25 @@ export interface IReq_Ingress_Relay_Cloudly_RegisterClusterIngress extends plugi
   };
 }
 
+/**
+ * The relay tells its registered ingress that it holds a newer table.
+ *
+ * A hint, not a delivery: it carries the revision alone and nothing secret, and
+ * the ingress answers it by pulling `getClusterIngressRouteTable` with the
+ * revision it already applied. A lost or repeated hint costs nothing, because the
+ * table's own revision is the idempotency; a hint whose revision is not greater
+ * than the applied one is ignored.
+ */
+export interface IReq_Relay_Ingress_PushClusterIngressRouteTableChanged
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Relay_Ingress_PushClusterIngressRouteTableChanged
+> {
+  method: 'pushClusterIngressRouteTableChanged';
+  request: clusterIngressInterfaces.IClusterIngressRouteTableChange;
+  response: Record<string, never>;
+}
+
 /**
  * The ingress fetches the table the relay holds.
  *
@@ -147,3 +178,37 @@ export interface IReq_Any_Ingress_GetClusterTrafficStatistics extends plugins.ty
     nextCursor?: string;
   };
 }
+
+/**
+ * Cloudly designates one existing service as the ingress of a cluster born on Pallet, creating the
+ * managed ingress bearer and the designation atomically. A cluster holds one kind of designation:
+ * Cloudly refuses a cluster that holds a fleet-cutover ingress designation.
+ */
+export interface IReq_Admin_Cloudly_DesignateClusterIngress
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_Cloudly_DesignateClusterIngress
+> {
+  method: 'designateClusterIngress';
+  request: {
+    identity: IIdentityCredential;
+    designation: IClusterIngressDesignationRequest;
+  };
+  response: {
+    designation: IClusterIngressDesignation;
+    /** The ingress service's exact-cluster runtime spec the designation was accepted against. */
+    spec: IServiceRuntimeSpec;
+    replayed: boolean;
+  };
+}
+
+/** The cluster's current ingress designation; `null` when the cluster holds none of this kind. */
+export interface IReq_Admin_Cloudly_GetClusterIngressDesignation
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_Cloudly_GetClusterIngressDesignation
+> {
+  method: 'getClusterIngressDesignation';
+  request: { identity: IIdentityCredential; clusterId: string };
+  response: { designation: IClusterIngressDesignation | null };
+}

package/ts/requests/gateway.ts

@@ -5,6 +5,9 @@ import type {
   IGatewayClientCredential,
   IGatewayClientProvisioningSpec,
   IGatewayClientContext,
+  IGatewayClientDnsRecord,
+  IGatewayClientDnsRecordSyncResult,
+  IGatewayClientHostnameOwnership,
   IGatewayClientOwnership,
   IGatewayClientRoute,
   IGatewayDnsRecord,
@@ -13,6 +16,8 @@ import type {
   IGatewayRouteConfig,
   IGatewayRouteSyncResult,
   TGatewayRouteDnsMode,
+  TGatewayClientCertificateReleaseResult,
+  TGatewayClientCertificateResult,
   TGatewayClientProvisioningAction,
 } from '../data/gateway.js';
 import type { IMailOverviewDomain, IMailOverviewEmail } from './mail.js';
@@ -233,6 +238,72 @@ export interface IReq_SyncGatewayClientRoute extends plugins.typedrequestInterfa
   response: IGatewayRouteSyncResult;
 }
 
+/**
+ * Publishes, replaces or withdraws the one address record a gateway-client ownership holds.
+ *
+ * Gateway-client credentials only, with the `syncDnsRecords` capability; the hostname must match
+ * the client's `hostnamePatterns`. Idempotent: the same record again answers `managed-unchanged`,
+ * and deleting a record the ownership does not hold answers `managed-deleted`. The value must lie
+ * inside the client's `allowedDnsRecordAddresses` (`target-invalid` otherwise). A hostname held by
+ * anything else is `record-conflict` and stays untouched. Requires `dns.clientRecords`.
+ */
+export interface IReq_SyncGatewayClientDnsRecord extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_SyncGatewayClientDnsRecord
+> {
+  method: 'syncGatewayClientDnsRecord';
+  request: {
+    apiToken: string;
+    identity?: never;
+    ownership: IGatewayClientHostnameOwnership;
+  } & (
+    | { record: IGatewayClientDnsRecord; delete?: never }
+    | { delete: true; record?: never }
+  );
+  response: IGatewayClientDnsRecordSyncResult;
+}
+
+/**
+ * Answers the exact certificate for one owned hostname, starting its issuance when none is valid.
+ *
+ * Gateway-client credentials only, with `requestCertificates` and `readCertificates`; the hostname
+ * must match the client's `hostnamePatterns`. No gateway route is needed. The certificate is issued
+ * for exactly this one identifier in the client's own namespace, and asking again after
+ * `renewAfter` answers a renewed one. The `ready` answer carries the private key. Requires
+ * `certificates.exactIssuance`.
+ */
+export interface IReq_GetGatewayClientCertificate extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetGatewayClientCertificate
+> {
+  method: 'getGatewayClientCertificate';
+  request: {
+    apiToken: string;
+    identity?: never;
+    ownership: IGatewayClientHostnameOwnership;
+  };
+  response: TGatewayClientCertificateResult;
+}
+
+/**
+ * Removes the certificate material and any issuance an ownership holds, releasing its certificate claim; an address record under the same ownership is unaffected.
+ *
+ * Gateway-client credentials only, with `requestCertificates`. Idempotent: an ownership that holds
+ * nothing answers `unchanged`. Requires `certificates.exactIssuance`.
+ */
+export interface IReq_ReleaseGatewayClientCertificate extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ReleaseGatewayClientCertificate
+> {
+  method: 'releaseGatewayClientCertificate';
+  request: {
+    apiToken: string;
+    identity?: never;
+    ownership: IGatewayClientHostnameOwnership;
+  };
+  response: TGatewayClientCertificateReleaseResult;
+}
+
 export interface IReq_ReprovisionCertificateDomain extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_ReprovisionCertificateDomain

package/ts/requests/runtimesession.ts

@@ -8,6 +8,7 @@ import type * as credential from '../data/networkcredential.js';
 import type * as assignmentSecret from '../runtime.assignmentsecret.js';
 import type * as fleet from '../data/fleetcutover.js';
 import type { IRuntimeStorageClaim } from '../data/runtimestorageclaim.js';
+import type * as localStorage from '../data/runtimelocalstorageclaim.js';
 
 /** Current-peer, exact-projection authorization; response contains secret keys. */
 export interface IReq_Pallet_Controller_GetRuntimeManagedVpnCredential extends plugins.typedrequestInterfaces.implementsTR<
@@ -163,6 +164,21 @@ export interface IReq_Controller_Pallet_ApplyRuntimeAssignment extends plugins.t
   response: data.IApplyRuntimeAssignmentResponse;
 }
 
+/**
+ * Controller push of one local storage claim over the already authenticated Pallet-initiated
+ * connection; `bindApplyRuntimeLocalStorageClaimRequest` binds it to that session. The answer is a
+ * durable admission acknowledgement plus the volume's state; it grants no mount by itself, which
+ * only an assignment that seals the claim's reference does.
+ */
+export interface IReq_Controller_Pallet_ApplyRuntimeLocalStorageClaim extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Controller_Pallet_ApplyRuntimeLocalStorageClaim
+> {
+  method: 'applyRuntimeLocalStorageClaim';
+  request: localStorage.IApplyRuntimeLocalStorageClaimRequest;
+  response: localStorage.IApplyRuntimeLocalStorageClaimResponse;
+}
+
 /** Current-peer report, including exact historical outbox recovery after reconnect. */
 export interface IReq_Pallet_Controller_ReportRuntimeAssignmentObservation extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,