@serve.zone/interfaces 31.8.0 → 31.9.0

package/ts/private/networkcontract.ts

@@ -149,6 +149,20 @@ export const networkPrefixBounds = (value: string): [number, number] => {
   const [address, bits] = value.split('/'), first = networkIpv4Number(address);
   return [first, first + 2 ** (32 - Number(bits)) - 1];
 };
+/** A canonical IPv4 prefix: a dotted quad whose host bits are zero. */
+export const networkPrefix = (value: unknown): string => {
+  requireNetwork(typeof value === 'string' && value.length <= 18);
+  const parts = value.split('/');
+  requireNetwork(parts.length === 2 && /^(?:[0-9]|[12][0-9]|3[0-2])$/.test(parts[1]));
+  requireNetwork(networkIpv4Number(networkIpv4(parts[0])) % 2 ** (32 - Number(parts[1])) === 0);
+  return value;
+};
+/** A canonical prefix inside the RFC 1918 private ranges. */
+export const networkPrivatePrefix = (value: unknown): string => {
+  const prefix = networkPrefix(value);
+  requireNetwork(['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16'].some(range => networkContains(range, prefix)));
+  return prefix;
+};
 export const networkContains = (outer: string, inner: string): boolean => {
   const [a, b] = networkPrefixBounds(outer), [c, d] = networkPrefixBounds(inner); return a <= c && b >= d;
 };

package/ts/private/producercontract.ts

@@ -0,0 +1,19 @@
+import { requireNetwork } from './networkcontract.js';
+
+/**
+ * The runtime producer records read decoded input with the network family's strict JSON readers,
+ * and every producer snapshot runs inside `producerSafe`: whichever rule refused, a caller sees
+ * this one rejection and learns nothing about which field failed.
+ */
+export const failProducer = (): never => { throw new Error('Runtime producer contract rejected.'); };
+export const producerSafe = <T>(operation: () => T): T => { try { return operation(); } catch { return failProducer(); } };
+
+/** Membership in a closed union whose members are listed once, as the array the union is derived from. */
+export const isOneOf = <T extends string>(members: readonly T[], value: unknown): value is T =>
+  (members as readonly unknown[]).includes(value);
+
+/** The tag of a captured tagged record, read before the record's exact keys are known. */
+export const variantOf = (value: unknown, tag: string): unknown => {
+  requireNetwork(value !== null && typeof value === 'object' && !Array.isArray(value));
+  return (value as Record<string, unknown>)[tag];
+};

package/ts/private/runtimepolicy.ts

@@ -0,0 +1,105 @@
+import type { IRuntimeConfigLogPolicyV1 } from '../data/runtimeconfig.js';
+
+/**
+ * The execution policy a runtime config seals and a service runtime profile states ahead of it.
+ * Both validators apply these timing, HTTP request, CPU, memory, identity and log rules. Only the
+ * service's target ports decide whether a readiness target exists, which a profile cannot know.
+ *
+ * Every check here reads captured plain data only, the output of `snapshotBoundedJson` or
+ * `captureNetwork`: on live input a getter could pass a check and then hand the caller another value.
+ */
+export const runtimePolicyLimits = Object.freeze({
+  minimumMemoryBytes: 16 * 1024 * 1024,
+  maximumMemoryBytes: 2 ** 50,
+  maximumCpuMillis: 1_000_000,
+  maximumIdentityNumber: 2 ** 31 - 1,
+  maximumReadinessDurationMs: 3_600_000,
+  maximumLogRetentionMs: 31_536_000_000,
+} as const);
+
+export type TRuntimePolicyFailure = (messageArg: string) => never;
+
+export const isBoundedInteger = (valueArg: unknown, minimumArg: number, maximumArg: number): valueArg is number =>
+  typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && !Object.is(valueArg, -0)
+  && valueArg >= minimumArg && valueArg <= maximumArg;
+export const isRuntimePortName = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && /^[a-z0-9][a-z0-9_.-]{0,62}$/.test(valueArg);
+export const isExactRecord = (
+  valueArg: unknown, keysArg: readonly string[],
+): valueArg is Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) return false;
+  const keys = Object.keys(valueArg);
+  return keys.length === keysArg.length && keys.every((keyArg) => keysArg.includes(keyArg));
+};
+
+/** null explicitly requests no CPU quota; zero is never a quota. */
+export const isRuntimeCpuMillis = (valueArg: unknown): valueArg is number | null =>
+  valueArg === null || isBoundedInteger(valueArg, 1, runtimePolicyLimits.maximumCpuMillis);
+export const isRuntimeMemoryBytes = (valueArg: unknown): valueArg is number =>
+  isBoundedInteger(valueArg, runtimePolicyLimits.minimumMemoryBytes, runtimePolicyLimits.maximumMemoryBytes);
+export const isRuntimeIdentityNumber = (valueArg: unknown): valueArg is number =>
+  isBoundedInteger(valueArg, 0, runtimePolicyLimits.maximumIdentityNumber);
+
+export const isRuntimeLogPolicy = (valueArg: unknown): valueArg is IRuntimeConfigLogPolicyV1 =>
+  isExactRecord(valueArg, ['maximumLineBytes', 'maximumBufferedBytes', 'retentionMs'])
+  && isBoundedInteger(valueArg.maximumLineBytes, 1, 1_048_576)
+  && isBoundedInteger(valueArg.maximumBufferedBytes, 1, 67_108_864)
+  && valueArg.maximumBufferedBytes >= valueArg.maximumLineBytes
+  && isBoundedInteger(valueArg.retentionMs, 1, runtimePolicyLimits.maximumLogRetentionMs);
+
+const timingKeys = ['initialDelayMs', 'startupGraceMs', 'intervalMs', 'timeoutMs',
+  'successThreshold', 'failureThreshold'] as const;
+
+/**
+ * Readiness policy. `selectsTcpTargetArg` decides whether a probe's named target and port exist:
+ * a config answers from its own target ports, a profile ahead of any config cannot know them.
+ */
+export const assertRuntimeReadiness = (
+  valueArg: unknown,
+  selectsTcpTargetArg: (targetPortArg: string, portArg: number) => boolean,
+  failArg: TRuntimePolicyFailure,
+): void => {
+  if (!valueArg || typeof valueArg !== 'object') failArg('runtime config readiness is required');
+  const value = valueArg as Record<string, unknown>;
+  const keys = value.kind === 'process' ? ['kind', ...timingKeys]
+    : value.kind === 'tcp' ? ['kind', ...timingKeys, 'targetPort', 'port']
+      : value.kind === 'http' ? ['kind', ...timingKeys, 'targetPort', 'port',
+        'scheme', 'host', 'path', 'expectedStatusCodes', 'followRedirects'] : [];
+  const maximumDurationMs = runtimePolicyLimits.maximumReadinessDurationMs;
+  if (keys.length === 0 || !isExactRecord(value, keys)
+    || !isBoundedInteger(value.initialDelayMs, 0, maximumDurationMs)
+    || !isBoundedInteger(value.startupGraceMs, 0, maximumDurationMs)
+    || !isBoundedInteger(value.intervalMs, 100, maximumDurationMs)
+    || !isBoundedInteger(value.timeoutMs, 1, 60_000)
+    || !isBoundedInteger(value.successThreshold, 1, 100)
+    || !isBoundedInteger(value.failureThreshold, 1, 100)
+    || value.timeoutMs > value.intervalMs || value.initialDelayMs > value.startupGraceMs) {
+    failArg('runtime config readiness must use explicit bounded timing and exact schema');
+  }
+  if (value.kind === 'process') return;
+  if (!isRuntimePortName(value.targetPort) || !isBoundedInteger(value.port, 1, 65535)
+    || !selectsTcpTargetArg(value.targetPort, value.port)) {
+    failArg('runtime config readiness must select a declared TCP target and port');
+  }
+  if (value.kind === 'tcp') return;
+  if ((value.scheme !== 'http' && value.scheme !== 'https') || value.followRedirects !== false
+    || typeof value.host !== 'string' || value.host.length > 253
+    || !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/.test(value.host)
+    || typeof value.path !== 'string' || value.path.length > 4096
+    || !value.path.startsWith('/') || value.path.startsWith('//')
+    || /[^\x21-\x7e]|[\\#]/.test(value.path)
+    || /%(?![0-9A-F]{2})/.test(value.path)
+    || !Array.isArray(value.expectedStatusCodes) || value.expectedStatusCodes.length === 0
+    || value.expectedStatusCodes.length > 32) {
+    failArg('runtime config HTTP readiness must use an exact bounded request policy');
+  }
+  const parsed = new URL(value.path, 'http://runtime.invalid');
+  if (`${parsed.pathname}${parsed.search}` !== value.path) failArg('runtime config HTTP path must be canonical');
+  let previousCode = 0;
+  for (const code of value.expectedStatusCodes) {
+    if (!isBoundedInteger(code, 200, 599) || code <= previousCode) {
+      failArg('runtime config HTTP status expectations must be sorted unique final codes');
+    }
+    previousCode = code;
+  }
+};

package/ts/requests/cluster.ts

@@ -1,5 +1,7 @@
 import * as userInterfaces from '../data/user.js';
 import * as clusterInterfaces from '../data/cluster.js';
+import type { IClusterRuntime, TClusterRuntimeBlocker } from '../data/clusterruntime.js';
+import type { IServiceRuntimeAssignmentView } from '../data/serviceruntime.js';
 import type * as leaseInterfaces from '../data/networklease.js';
 import * as plugins from '../plugins.js';
 
@@ -182,3 +184,46 @@ export interface IReq_Any_Cloudly_DeleteClusterById extends plugins.typedrequest
     ok: boolean;
   };
 }
+
+/**
+ * A cluster's runtime phase, and what still blocks it from leaving `swarm`.
+ *
+ * Cloudly refuses a cluster without a phase record as `cluster-runtime-missing` rather than
+ * assuming one. `blockers` is empty once nothing blocks the cutover.
+ */
+export interface IReq_Any_Cloudly_GetClusterRuntime extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetClusterRuntime
+> {
+  method: 'getClusterRuntime';
+  request: {
+    identity: userInterfaces.IIdentity;
+    clusterId: string;
+  };
+  response: {
+    runtime: IClusterRuntime;
+    blockers: TClusterRuntimeBlocker[];
+  };
+}
+
+/**
+ * Every current runtime assignment on one cluster's nodes, a page at a time: a cluster carries
+ * every node's slots of every service, which no single response bounds. `limit` runs from 1 to
+ * `serviceRuntimeContract.maximumAssignmentPageSize`; Cloudly refuses any other.
+ */
+export interface IReq_Any_Cloudly_GetClusterRuntimeAssignments extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetClusterRuntimeAssignments
+> {
+  method: 'getClusterRuntimeAssignments';
+  request: {
+    identity: userInterfaces.IIdentity;
+    clusterId: string;
+    cursor: string | null;
+    limit: number;
+  };
+  response: {
+    assignments: IServiceRuntimeAssignmentView[];
+    nextCursor: string | null;
+  };
+}

package/ts/requests/network.ts

@@ -1,5 +1,7 @@
 import * as plugins from '../plugins.js';
-import type { IIdentityCredential } from '../data/user.js';
+import type { IIdentity, IIdentityCredential } from '../data/user.js';
+import type { IRuntimeNetworkAddressPlan, TRuntimeNetworkAddressPlanWritableData } from '../data/networkaddressplan.js';
+import type { IRuntimeNetworkNodeReadiness, IRuntimeRouterIncarnation } from '../data/networknode.js';
 import type {
   IPrivateNetworkV1, IServicePrivateNetworksV1, ISetServicePrivateNetworksV1,
   TPrivateNetworkMutationV1,
@@ -98,3 +100,50 @@ export interface IRequest_Any_Cloudly_GetNetworkNodes {
     networkNodes: plugins.tsclass.network.INetworkNode[];
   };
 }
+
+/**
+ * Writes the runtime network's address plan.
+ *
+ * `expectedRevision` is the revision the caller read, or `null` when no plan exists yet. Cloudly
+ * validates the plan with `snapshotRuntimeNetworkAddressPlan`, decides the change with
+ * `admitRuntimeNetworkAddressPlanChange`, refuses the change while a resolver or platform endpoint
+ * it removes or changes is still referenced, and answers with the stored plan: at its new revision,
+ * or unchanged.
+ */
+export interface IReq_Any_Cloudly_SetRuntimeNetworkAddressPlan extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_SetRuntimeNetworkAddressPlan
+> {
+  method: 'setRuntimeNetworkAddressPlan';
+  request: { identity: IIdentity; expectedRevision: number | null; plan: TRuntimeNetworkAddressPlanWritableData };
+  response: { plan: IRuntimeNetworkAddressPlan };
+}
+
+/** `null` until an administrator sets the first plan; the runtime network stays unconfigured until then. */
+export interface IReq_Any_Cloudly_GetRuntimeNetworkAddressPlan extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_GetRuntimeNetworkAddressPlan
+> {
+  method: 'getRuntimeNetworkAddressPlan';
+  request: { identity: IIdentity };
+  response: { plan: IRuntimeNetworkAddressPlan | null };
+}
+
+/** Whether one node's runtime network is ready for workloads, and every condition still missing. */
+export interface IReq_Any_Cloudly_GetRuntimeNetworkNodeReadiness extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_GetRuntimeNetworkNodeReadiness
+> {
+  method: 'getRuntimeNetworkNodeReadiness';
+  request: { identity: IIdentity; nodeId: string };
+  response: IRuntimeNetworkNodeReadiness;
+}
+
+/**
+ * Advances one node's router incarnation, so the node producer reserves the router a fresh handoff.
+ * `expectedIncarnation` is the incarnation the caller read; any other refuses the request.
+ */
+export interface IReq_Any_Cloudly_ReincarnateRuntimeNetworkRouter extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_ReincarnateRuntimeNetworkRouter
+> {
+  method: 'reincarnateRuntimeNetworkRouter';
+  request: { identity: IIdentity; nodeId: string; expectedIncarnation: number };
+  response: { incarnation: IRuntimeRouterIncarnation };
+}

package/ts/requests/service.ts

@@ -16,6 +16,12 @@ import type {
   IServiceDeploymentStatus,
 } from '../data/deploymentoperation.js';
 import type { TSha256Digest } from '../data/immutableimage.js';
+import type {
+  IServiceRuntimeAssignmentView,
+  IServiceRuntimeSpec,
+  IServiceRuntimeStatus,
+  TServiceRuntimeSpecWritableData,
+} from '../data/serviceruntime.js';
 import type {
   IServiceDeploymentAdoptionInput,
   IServiceDeploymentAdoptionImagePromotionInput,
@@ -370,3 +376,78 @@ extends plugins.typedrequestInterfaces.implementsTR<
     success: boolean;
   };
 }
+
+/**
+ * Writes the complete runtime spec of one service.
+ *
+ * `expectedRevision` is the revision the caller read, or `null` when the service has never had a
+ * spec; any other stored revision refuses the write. Cloudly copies the organization from the
+ * service and answers with the stored spec at its new revision.
+ */
+export interface IRequest_Any_Cloudly_SetServiceRuntimeSpec
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_SetServiceRuntimeSpec
+> {
+  method: 'setServiceRuntimeSpec';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+    expectedRevision: number | null;
+    spec: TServiceRuntimeSpecWritableData;
+  };
+  response: {
+    spec: IServiceRuntimeSpec;
+  };
+}
+
+/**
+ * A service's runtime spec and the producer's verdict on it. Both are `null` before the first spec;
+ * a spec's status is `null` until the producer first decides it.
+ */
+export interface IRequest_Any_Cloudly_GetServiceRuntimeSpec
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_GetServiceRuntimeSpec
+> {
+  method: 'getServiceRuntimeSpec';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+  };
+  response:
+    | { spec: null; status: null }
+    | { spec: IServiceRuntimeSpec; status: IServiceRuntimeStatus | null };
+}
+
+/** Every current runtime assignment of one service, one per replica slot. */
+export interface IRequest_Any_Cloudly_GetServiceRuntimeAssignments
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_GetServiceRuntimeAssignments
+> {
+  method: 'getServiceRuntimeAssignments';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+  };
+  response: {
+    assignments: IServiceRuntimeAssignmentView[];
+  };
+}
+
+/**
+ * Cloudly -> admin UIs: a service's runtime spec, status or assignments changed. It carries no
+ * state, so a late or repeated push can never overwrite a newer read; the UI reads the views again.
+ */
+export interface IReq_Cloudly_Any_PushServiceRuntimeChanged
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Any_PushServiceRuntimeChanged
+> {
+  method: 'pushServiceRuntimeChanged';
+  request: {
+    serviceId: string;
+  };
+  response: Record<string, never>;
+}