@serve.zone/interfaces 32.2.0 → 32.4.0

package/ts/data/runtimeassignment.ts

@@ -55,7 +55,20 @@ export interface IRuntimeAssignment extends IRuntimeAssignmentScope {
   /** No automatic relocation or expiry-based claim of a stopped writer. */
   offlinePolicy: 'continue-node-bound';
   workload: {
+    /**
+     * The registry that published this image, which is the publication identity the image release
+     * is bound to. It is never rewritten: only `pullEndpoint` decides where the bytes are fetched.
+     */
     registryHost: string;
+    /**
+     * Where this node fetches the image instead of `registryHost`, as `host[:port]`.
+     *
+     * A cluster whose relay forwards the registry states the relay's own origin here, so a node
+     * pulls inside its cluster and nothing cluster-side dials the control plane. Absent when the
+     * node pulls from the publishing registry itself. The reference stays digest-pinned either
+     * way, so the endpoint decides reachability and never content.
+     */
+    pullEndpoint?: string;
     repository: string;
     imageDigest: TSha256Digest;
     platform: TImmutableContainerPlatform;
@@ -99,7 +112,7 @@ const workloadAuthorityDemands: Readonly<Record<
 export const requiredWorkloadAuthorities = (
   workloadArg: IRuntimeAssignment['workload'],
 ): TRuntimeWorkloadAuthority[] => {
-  if (!isExactRecord(workloadArg, workloadKeys) || !Array.isArray(workloadArg.storage)) {
+  if (!isExactRecord(workloadArg, workloadKeys, optionalWorkloadKeys) || !Array.isArray(workloadArg.storage)) {
     fail(workloadSchemaMessage);
   }
   return runtimeWorkloadAuthorities
@@ -107,6 +120,30 @@ export const requiredWorkloadAuthorities = (
     .sort(compareWireTokens);
 };
 
+/**
+ * The digest-pinned image reference a node pulls this workload by.
+ *
+ * One function decides where the bytes come from: the stated `pullEndpoint`, else the publishing
+ * `registryHost`. The digest is the same either way, so a node that pulls through its cluster's
+ * relay fetches exactly the content the publishing registry named, and a controller and a node can
+ * never disagree about the reference. The workload is read as a wire value, so one whose members
+ * this contract refuses is refused here rather than by a member read.
+ */
+export const buildRuntimeAssignmentImageReference = (
+  workloadArg: IRuntimeAssignment['workload'],
+): string => {
+  if (!isExactRecord(workloadArg, workloadKeys, optionalWorkloadKeys)) {
+    fail(workloadSchemaMessage);
+  }
+  const endpoint = Object.hasOwn(workloadArg, 'pullEndpoint')
+    ? workloadArg.pullEndpoint : workloadArg.registryHost;
+  if (typeof endpoint !== 'string' || typeof workloadArg.repository !== 'string'
+    || !isDigest(workloadArg.imageDigest)) {
+    fail(workloadSchemaMessage);
+  }
+  return buildDigestPinnedImageReference(endpoint, workloadArg.repository, workloadArg.imageDigest);
+};
+
 /** True when a value is exactly a canonical authority list drawn from the authority vocabulary. */
 export const isResolvedWorkloadAuthorities = (
   valueArg: unknown,
@@ -152,18 +189,24 @@ const isPositiveInteger = (valueArg: unknown): valueArg is number =>
 const isDigest = (valueArg: unknown): valueArg is TSha256Digest =>
   typeof valueArg === 'string' && isSha256Digest(valueArg);
 
-/** Reject accessors before reading any fields; do not run input-owned code. */
+/**
+ * Reject accessors before reading any fields; do not run input-owned code.
+ *
+ * Absence stays absence: a stated optional key is read, an omitted one is not defaulted, so a
+ * controller that stated nothing is distinguishable from one that stated a value.
+ */
 const isExactRecord = (
   valueArg: unknown,
   keysArg: readonly string[],
+  optionalKeysArg: readonly string[] = [],
 ): valueArg is Record<string, unknown> => {
   if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) return false;
   const prototype = Object.getPrototypeOf(valueArg);
   if (prototype !== Object.prototype && prototype !== null) return false;
   const keys = Reflect.ownKeys(valueArg);
-  return keys.length === keysArg.length && keys.every((keyArg) => {
+  return keysArg.every((keyArg) => keys.includes(keyArg)) && keys.every((keyArg) => {
     const descriptor = Object.getOwnPropertyDescriptor(valueArg, keyArg);
-    return typeof keyArg === 'string' && keysArg.includes(keyArg)
+    return typeof keyArg === 'string' && (keysArg.includes(keyArg) || optionalKeysArg.includes(keyArg))
       && descriptor?.enumerable === true && Object.hasOwn(descriptor, 'value');
   });
 };
@@ -183,6 +226,8 @@ const isAssignmentReference = (valueArg: unknown): valueArg is IRuntimeAssignmen
 /** The workload's exact members, read by the authority vocabulary and by the snapshot alike. */
 const workloadKeys = ['registryHost', 'repository', 'imageDigest', 'platform',
   'config', 'network', 'secrets', 'storage'] as const;
+/** Stated only by a controller that sends the node somewhere else for the image bytes. */
+const optionalWorkloadKeys = ['pullEndpoint'] as const;
 const workloadSchemaMessage = 'runtime assignment workload must use exact immutable references';
 
 const assignmentKeys = [
@@ -213,8 +258,10 @@ const assertAssignment = (valueArg: unknown): IRuntimeAssignment => {
     fail('runtime assignment must bind its exact preceding generation');
   }
   const workload = valueArg.workload;
-  if (!isExactRecord(workload, workloadKeys)
+  if (!isExactRecord(workload, workloadKeys, optionalWorkloadKeys)
     || typeof workload.registryHost !== 'string' || workload.registryHost.length > 253
+    || (Object.hasOwn(workload, 'pullEndpoint')
+      && (typeof workload.pullEndpoint !== 'string' || workload.pullEndpoint.length > 253))
     || typeof workload.repository !== 'string' || workload.repository.length > 255
     || !isDigest(workload.imageDigest)
     || !['linux/amd64', 'linux/arm64'].includes(workload.platform as string)
@@ -227,6 +274,12 @@ const assertAssignment = (valueArg: unknown): IRuntimeAssignment => {
   }
   buildDigestPinnedImageReference(workload.registryHost as string,
     workload.repository as string, workload.imageDigest as TSha256Digest);
+  // The pull endpoint is an OCI registry host like the publishing one, so the same reference the
+  // node builds proves it: an endpoint no reference can name is refused where it is written.
+  if (Object.hasOwn(workload, 'pullEndpoint')) {
+    buildDigestPinnedImageReference(workload.pullEndpoint as string,
+      workload.repository as string, workload.imageDigest as TSha256Digest);
+  }
   let previousId = '';
   for (let index = 0; index < (workload.storage as unknown[]).length; index++) {
     const descriptor = Object.getOwnPropertyDescriptor(workload.storage, String(index));

package/ts/platform/storage.ts

@@ -1,3 +1,4 @@
+import type { TAppStoreStorageRequest } from '../appstore/types.js';
 import type { TSecretManagementScope } from '../data/secret.js';
 import {
   canonicalizeStrictJson,
@@ -253,7 +254,31 @@ const fail = (reasonArg: string): never => {
   throw new StorageContractError(reasonArg);
 };
 
-const { normalizeStorageRequest } = createStorageContractReaders(fail);
+const { normalizeStorageRequest: readStorageRequest } =
+  createStorageContractReaders(fail);
+
+/**
+ * The one judgement of what a storage request is: the request read against its exact schema and
+ * returned in its contract shape — required members present, optional members carried only when
+ * the request declares them, and every value within the bounds an adapter can fulfil.
+ *
+ * A control plane that admits requests, a fulfillment adapter that provisions them, and an App
+ * Store front end that assembles them all have to agree on the same acceptance rules; a second
+ * copy of them anywhere is a second answer to which requests exist, and the digest one side issues
+ * would name a request the other never accepted. `canonicalizeStorageRequest` and
+ * `createStorageRequestSha256` are derived from this function rather than the other way round, so
+ * a consumer that needs the judged request itself does not have to re-parse its own canonical
+ * bytes.
+ *
+ * The returned request is a fresh value; the input is never read again after normalization and
+ * never mutated. Anything that is not a storage request is refused with `StorageContractError`,
+ * whose message names the failing field so a consumer can map it to its own status vocabulary.
+ */
+export const normalizeStorageRequest = (
+  valueArg: unknown,
+): TAppStoreStorageRequest => {
+  return readStorageRequest(valueArg, 'storage request');
+};
 
 /**
  * The exact bytes a storage request's digest is taken over: the request normalized to its contract
@@ -264,10 +289,7 @@ const { normalizeStorageRequest } = createStorageContractReaders(fail);
  * unjudged body would name a request no adapter could fulfil.
  */
 export const canonicalizeStorageRequest = (valueArg: unknown): string => {
-  return canonicalizeStrictJson(
-    normalizeStorageRequest(valueArg, 'storage request'),
-    fail,
-  );
+  return canonicalizeStrictJson(normalizeStorageRequest(valueArg), fail);
 };
 
 /**

package/ts/private/networkcontract.ts

@@ -89,6 +89,17 @@ export const networkDigest = (value: unknown): TSha256Digest => {
 export const networkSignature = (value: unknown): string => {
   requireNetwork(typeof value === 'string' && /^[a-f0-9]{128}$/.test(value)); return value;
 };
+/**
+ * One encoding for every Noise key this contract carries — the managed VPN credential's, a relay's
+ * hub advertisement and a cluster's VPN network: canonical 32-byte base64, never the all-zero key.
+ * Key agreement and key-pair validation belong to the native Noise implementation, not to a reader.
+ */
+export const networkNoiseKey = (value: unknown): string => {
+  requireNetwork(typeof value === 'string' && /^[A-Za-z0-9+/]{43}=$/.test(value));
+  const decoded = atob(value as string);
+  requireNetwork(decoded.length === 32 && btoa(decoded) === value && [...decoded].some(byte => byte.charCodeAt(0) !== 0));
+  return value as string;
+};
 export const networkController = (value: unknown): IRuntimeController => {
   const item = networkRecord(value, ['kind', 'id', 'epoch']);
   requireNetwork(item.kind === 'cloudly' || item.kind === 'onebox');

package/ts/requests/cluster.ts

@@ -1,5 +1,6 @@
 import * as userInterfaces from '../data/user.js';
 import * as clusterInterfaces from '../data/cluster.js';
+import type * as clusterVpnInterfaces from '../data/clustervpn.js';
 import type { IClusterRuntime, TClusterRuntimeBlocker } from '../data/clusterruntime.js';
 import type { IServiceRuntimeAssignmentView } from '../data/serviceruntime.js';
 import type * as leaseInterfaces from '../data/networklease.js';
@@ -168,6 +169,40 @@ export interface IReq_Cloudly_Relay_HoldRuntimeNetworkDnsLeaseRenewals extends p
   response: leaseInterfaces.IHoldRuntimeNetworkDnsLeaseRenewalsResponse;
 }
 
+/**
+ * Cloudly pushes one cluster's complete managed VPN to that cluster's relay.
+ *
+ * The relay is its cluster's own hub: it runs the managed VPN server every node of the cluster
+ * dials, so this is the whole authority that hub serves, never a patch. It rides the relay's
+ * already registered session, which is why no cluster is named — the socket names it. The relay
+ * answers with what its hub applied, and refuses a network for another authority or a revision it
+ * has passed with one of `data.applyClusterVpnNetworkRefusals`.
+ */
+export interface IReq_Cloudly_Relay_ApplyClusterVpnNetwork extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Relay_ApplyClusterVpnNetwork
+> {
+  method: 'applyClusterVpnNetwork';
+  request: clusterVpnInterfaces.IApplyClusterVpnNetworkRequest;
+  response: clusterVpnInterfaces.IApplyClusterVpnNetworkResponse;
+}
+
+/**
+ * The relay asks Cloudly for its cluster's current managed VPN.
+ *
+ * A hub daemon starts empty and its lifetime is the relay's own, invisible to Cloudly, so a relay
+ * that just bound its hub pulls the current network instead of waiting for the next push. The
+ * answer is `null` while the cluster has none.
+ */
+export interface IReq_Relay_Cloudly_GetClusterVpnNetwork extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Relay_Cloudly_GetClusterVpnNetwork
+> {
+  method: 'getClusterVpnNetwork';
+  request: clusterVpnInterfaces.TGetClusterVpnNetworkRequest;
+  response: clusterVpnInterfaces.IGetClusterVpnNetworkResponse;
+}
+
 /**
  * deletes a cluster
  */