@serve.zone/interfaces 32.4.0 → 32.5.0

package/ts/data/runtimeassignment.ts

@@ -3,6 +3,7 @@ import { buildDigestPinnedImageReference, isSha256Digest } from './immutableimag
 import {
   canonicalizeStrictJson, compareWireTokens, createCanonicalJsonSha256Hex,
 } from '../private/canonicaljson.js';
+import { isClusterNodeId } from '../private/nodeidentifier.js';
 import { isCanonicalTokenList } from '../private/tokenlist.js';
 
 export interface IRuntimeController {
@@ -184,6 +185,27 @@ export const runtimeAssignmentContract = Object.freeze({
 const fail: (messageArg: string) => never = (messageArg) => { throw new Error(messageArg); };
 const isIdentifier = (valueArg: unknown): valueArg is string =>
   typeof valueArg === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(valueArg);
+/** The index of a replica slot: counted from zero by its producer, never zero-padded. */
+const isReplicaIndex = (valueArg: string): boolean => /^(?:0|[1-9][0-9]{0,8})$/.test(valueArg);
+
+/**
+ * True when a value is exactly a replica id.
+ *
+ * A producer names a replica slot after the node that runs it — `<node id>.<index>`, counted from
+ * zero — so a replica id that carries an index is read by decomposition: the part before the last
+ * dot in the node vocabulary, the index on its own. Reading the composed form as one canonical
+ * identifier would refuse every replica of a node whose id begins with `-` or `_`, a node these
+ * contracts themselves enrol and register. A name that carries no such index — a zero-padded index
+ * among them — is an opaque slot name and is read whole in the canonical identifier vocabulary, as
+ * it always was.
+ */
+export const isRuntimeReplicaId = (valueArg: unknown): valueArg is string => {
+  if (typeof valueArg !== 'string') return false;
+  const separator = valueArg.lastIndexOf('.');
+  return separator > 0 && isReplicaIndex(valueArg.slice(separator + 1))
+    ? isClusterNodeId(valueArg.slice(0, separator))
+    : isIdentifier(valueArg);
+};
 const isPositiveInteger = (valueArg: unknown): valueArg is number =>
   typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg > 0;
 const isDigest = (valueArg: unknown): valueArg is TSha256Digest =>
@@ -244,10 +266,11 @@ const assertAssignment = (valueArg: unknown): IRuntimeAssignment => {
     || !['run', 'stop-preserve', 'remove-runtime-preserve-storage'].includes(
       valueArg.disposition as string,
     )) fail('runtime assignment must use its exact schema');
-  for (const key of ['organizationId', 'nodeId', 'runtimeNamespace', 'assignmentId',
-    'serviceId', 'replicaId', 'attemptId']) {
+  for (const key of ['organizationId', 'runtimeNamespace', 'assignmentId', 'serviceId', 'attemptId']) {
     if (!isIdentifier(valueArg[key])) fail(`runtime assignment ${key} must be a canonical identifier`);
   }
+  if (!isClusterNodeId(valueArg.nodeId)) fail('runtime assignment nodeId must be a node id');
+  if (!isRuntimeReplicaId(valueArg.replicaId)) fail('runtime assignment replicaId must be a replica id');
   for (const key of ['workerGroupId', 'siteId']) {
     if (valueArg[key] !== null && !isIdentifier(valueArg[key])) fail('invalid runtime topology ID');
   }
@@ -357,7 +380,7 @@ export const evaluateRuntimeAssignment = async (
     acceptedArg = acceptedArg === null ? null : snapshotRuntimeAssignment(acceptedArg);
     if (!isExactRecord(trustedScopeArg, ['controller', 'organizationId', 'nodeId', 'runtimeNamespace'])
       || !isController(trustedScopeArg.controller)
-      || !isIdentifier(trustedScopeArg.organizationId) || !isIdentifier(trustedScopeArg.nodeId)
+      || !isIdentifier(trustedScopeArg.organizationId) || !isClusterNodeId(trustedScopeArg.nodeId)
       || !isIdentifier(trustedScopeArg.runtimeNamespace)) return { status: 'reject', reason: 'invalid' };
     trustedScopeArg = JSON.parse(canonical(trustedScopeArg)) as IRuntimeAssignmentScope;
   } catch {

package/ts/data/runtimesession.ts

@@ -12,6 +12,7 @@ import { negotiateProtocol, readProtocolOffer, type IProtocolOffer } from '../pr
 import type { IRuntimeConfig } from './runtimeconfig.js';
 import { bindRuntimeConfigToAssignment, snapshotRuntimeConfig } from './runtimeconfig.js';
 import { canonicalizeStrictJson } from '../private/canonicaljson.js';
+import { isClusterNodeId } from '../private/nodeidentifier.js';
 
 /**
  * Server-issued public binding for the current authenticated physical connection.
@@ -178,8 +179,8 @@ const identifier = (valueArg: unknown): string => {
   return valueArg;
 };
 const nodeId = (valueArg: unknown): string => {
-  requireValue(typeof valueArg === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(valueArg));
-  return valueArg;
+  requireValue(isClusterNodeId(valueArg));
+  return valueArg as string;
 };
 /** One node process, in the same canonical form as the native boot UUID. */
 const nodeInstanceNonce = (valueArg: unknown): string => {

package/ts/data/serviceruntime.ts

@@ -3,7 +3,7 @@ import type {
 } from './runtimeassignment.js';
 import type { IRuntimeConfigLogPolicy, TRuntimeConfigReadiness } from './runtimeconfig.js';
 import { runtimeNetworkAuthorityContract } from './networkauthority.js';
-import { captureNetwork, networkCanonical, networkCounter, networkId, networkList, networkRecord, networkSorted,
+import { captureNetwork, networkCanonical, networkCounter, networkId, networkList, networkNodeId, networkRecord, networkSorted,
   requireNetwork } from '../private/networkcontract.js';
 import { failProducer, isOneOf, producerSafe, variantOf } from '../private/producercontract.js';
 import { assertRuntimeReadiness, isBoundedInteger, isRuntimeCpuMillis, isRuntimeIdentityNumber, isRuntimeLogPolicy,
@@ -138,8 +138,9 @@ export interface IServiceRuntimeAssignmentView {
   delivery: TServiceRuntimeAssignmentDelivery;
 }
 
-const sortedIds = (value: unknown, maximum: number): string[] =>
-  networkSorted(networkList(value, maximum, networkId), id => id);
+/** Sorted, duplicate-free and read by the vocabulary the ids belong to: a node's, or the canonical one. */
+const sortedIds = (value: unknown, maximum: number, read: (item: unknown) => string): string[] =>
+  networkSorted(networkList(value, maximum, read), id => id);
 
 const placementOf = (value: unknown): TServiceRuntimePlacement => {
   const kind = variantOf(value, 'kind');
@@ -148,7 +149,7 @@ const placementOf = (value: unknown): TServiceRuntimePlacement => {
     return { kind };
   }
   requireNetwork(kind === 'nodes');
-  const nodeIds = sortedIds(networkRecord(value, ['kind', 'nodeIds']).nodeIds, serviceRuntimeContract.maximumPinnedNodes);
+  const nodeIds = sortedIds(networkRecord(value, ['kind', 'nodeIds']).nodeIds, serviceRuntimeContract.maximumPinnedNodes, networkNodeId);
   requireNetwork(nodeIds.length > 0);
   return { kind, nodeIds };
 };
@@ -182,7 +183,7 @@ const networkOf = (value: unknown): TServiceRuntimeNetwork => {
   const item = networkRecord(value, ['mode', 'publicEgress', 'platformEndpointIds']);
   requireNetwork(typeof item.publicEgress === 'boolean');
   return { mode, publicEgress: item.publicEgress,
-    platformEndpointIds: sortedIds(item.platformEndpointIds, serviceRuntimeContract.maximumPlatformEndpoints) };
+    platformEndpointIds: sortedIds(item.platformEndpointIds, serviceRuntimeContract.maximumPlatformEndpoints, networkId) };
 };
 
 /**

package/ts/data/sparknodereport.ts

@@ -1,5 +1,6 @@
 import { isReleaseVersion } from '../private/releaseversion.js';
 import { readExactDataRecord } from '../private/dataproperties.js';
+import { isClusterNodeId } from '../private/nodeidentifier.js';
 import { protocolRefusalHttpStatus, readProtocolOffer, type IProtocolOffer } from '../protocol.js';
 
 /** Host observations only. Container and workload readiness belong to Pallet. */
@@ -80,6 +81,10 @@ const text = (valueArg: unknown, patternArg: RegExp, maxLengthArg: number): stri
     && valueArg.match(patternArg)?.[0] === valueArg);
   return valueArg;
 };
+// The shared vocabulary, not a copy of it: the id on this wire is the id the node enrolled under.
+const nodeId = (valueArg: unknown): string => (
+  isClusterNodeId(valueArg) ? valueArg : fail()
+);
 // The shared grammar, not a copy of it: a stored bundle version has to be one the release
 // comparison can order, and a second rule here would be a second answer to that question.
 const releaseVersion = (valueArg: unknown): string => (
@@ -131,7 +136,7 @@ export const snapshotSparkNodeReport = (valueArg: unknown): ISparkNodeReport =>
 export const snapshotSparkNodeHeartbeatRequest = (valueArg: unknown): ISparkNodeHeartbeatRequest => {
   const value = record(valueArg, ['nodeId', 'nodeToken', 'protocol', 'report']);
   return Object.freeze({
-    nodeId: text(value.nodeId, /^[A-Za-z0-9_-]+$/, 128),
+    nodeId: nodeId(value.nodeId),
     // Both freshly enrolled and explicitly adopted credentials use this bearer format.
     nodeToken: text(value.nodeToken, /^secureToken[a-f0-9]{64}$/, 75),
     protocol: readProtocolOffer(value),
@@ -144,7 +149,7 @@ export const snapshotSparkNodeHeartbeatReceipt = (valueArg: unknown): ISparkNode
     'sessionEpoch', 'acceptedAt', 'protocol']);
   requireValue(value.accepted === true);
   return Object.freeze({
-    accepted: true, nodeId: text(value.nodeId, /^[A-Za-z0-9_-]+$/, 128),
+    accepted: true, nodeId: nodeId(value.nodeId),
     credentialGeneration: integer(value.credentialGeneration, 1),
     sessionEpoch: integer(value.sessionEpoch, 0), acceptedAt: integer(value.acceptedAt, 1),
     protocol: readProtocolOffer(value),

package/ts/private/networkcontract.ts

@@ -3,6 +3,7 @@ import type { IRuntimeAuthorityReference, IRuntimeController } from '../data/run
 import type { IRuntimeNetworkDnsLeaseRenewal } from '../data/networklease.js';
 import type { IRuntimeNetworkDnsWindow, IRuntimeNetworkNodeScope, IRuntimeNetworkProjection } from '../data/networkprojection.js';
 import { canonicalizeStrictJson, createCanonicalJsonSha256Hex } from './canonicaljson.js';
+import { isClusterNodeId } from './nodeidentifier.js';
 
 export const failNetwork = (): never => { throw new Error('Runtime network projection contract rejected.'); };
 export function requireNetwork(value: unknown): asserts value { if (!value) failNetwork(); }
@@ -79,6 +80,10 @@ export const networkSorted = <T>(values: T[], key: (item: T) => string): T[] =>
 export const networkId = (value: unknown): string => {
   requireNetwork(typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(value)); return value;
 };
+/** A node id is read in the node vocabulary here as everywhere else, never in the canonical one. */
+export const networkNodeId = (value: unknown): string => {
+  requireNetwork(isClusterNodeId(value)); return value as string;
+};
 export const networkCounter = (value: unknown, maximum = Number.MAX_SAFE_INTEGER - 1): number => {
   requireNetwork(typeof value === 'number' && Number.isSafeInteger(value) && value > 0 && value <= maximum); return value;
 };
@@ -106,7 +111,7 @@ export const networkController = (value: unknown): IRuntimeController => {
   return { kind: item.kind, id: networkId(item.id), epoch: networkId(item.epoch) };
 };
 export const networkScope = (item: Record<string, unknown>): IRuntimeNetworkNodeScope => ({
-  controller: networkController(item.controller), nodeId: networkId(item.nodeId), runtimeNamespace: networkId(item.runtimeNamespace),
+  controller: networkController(item.controller), nodeId: networkNodeId(item.nodeId), runtimeNamespace: networkId(item.runtimeNamespace),
 });
 export const networkSameScope = (left: IRuntimeNetworkNodeScope, right: IRuntimeNetworkNodeScope): boolean =>
   networkEqual(left.controller, right.controller) && left.nodeId === right.nodeId && left.runtimeNamespace === right.runtimeNamespace;

package/ts/private/nodeidentifier.ts

@@ -0,0 +1,25 @@
+/**
+ * The one vocabulary a node of a cluster is named in.
+ *
+ * It lives beside the canonical JSON and data-property helpers rather than in a contract module
+ * because every family reads it — the node's enrollment, its runtime session, the Spark wire, its
+ * assignments, the private network contract and the relay block — and a second spelling of the rule
+ * is a second answer to which nodes exist.
+ */
+
+/**
+ * True when a value is exactly a node id: the URL alphabet, a leading `-` or `_` included,
+ * one to 128 characters.
+ *
+ * These contracts disagreed with themselves about what a node may be called: enrollment, the
+ * session registration and the Spark wire admit a separator-led node id, which makes this the
+ * vocabulary a stored node id is written in, while the assignment and the network members read
+ * that same id by the canonical identifier vocabulary — whose first character must be
+ * alphanumeric — and refuse it, and with it the assignment, the runtime network and, because one
+ * refused egress owner fails the whole pass, its entire cluster's protected authority. A
+ * controller now keeps the first character alphanumeric where it mints, so the ids this one
+ * vocabulary serves are the ones already stored under the members that admit them.
+ */
+export const isClusterNodeId = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(valueArg)
+);

package/ts/requests/corestore.ts

@@ -1,6 +1,7 @@
 import * as plugins from '../plugins.js';
 import type { IIdentity } from '../data/user.js';
 import { hasExactKeys } from '../private/dataproperties.js';
+import { isClusterNodeId } from '../private/nodeidentifier.js';
 
 /**
  * A provisioned corestore resource (NoSQLDB database or ObjectStorage bucket)
@@ -189,9 +190,8 @@ export const validateClusterCorestoreInventory = (
     return [`${pathArg} must use its exact schema`];
   }
   const errors: string[] = [];
-  if (typeof valueArg.nodeId !== 'string'
-    || !clusterCorestoreInventoryIdentifierPattern.test(valueArg.nodeId)) {
-    errors.push(`${pathArg} nodeId must be a bounded identifier`);
+  if (!isClusterNodeId(valueArg.nodeId)) {
+    errors.push(`${pathArg} nodeId must be a node id`);
   }
   if (!Number.isSafeInteger(valueArg.checkedAt) || (valueArg.checkedAt as number) < 0) {
     errors.push(`${pathArg} checkedAt must be a non-negative safe integer`);

package/ts/runtime.ts

@@ -29,6 +29,7 @@ import {
 } from './data/clusternode.js';
 import { isCoreflowRuntimeCapabilityList, isSha256Digest } from './data/immutableimage.js';
 import { hasExactKeys } from './private/dataproperties.js';
+import { isClusterNodeId } from './private/nodeidentifier.js';
 import type {
   IWorkloadInitActiveApprovalAuthority,
   IWorkloadInitApprovalAuthorityReference,
@@ -759,8 +760,10 @@ const validateRuntimeTargets = (
       errors.push(`${pathArg}[${index}] must use its exact schema`);
       continue;
     }
-    if (!isRuntimeIdentifier(targetArg.cloudlyNodeId)
-      || !isRuntimeIdentifier(targetArg.swarmClusterId)
+    if (!isClusterNodeId(targetArg.cloudlyNodeId)) {
+      errors.push(`${pathArg}[${index}].cloudlyNodeId must be a node id`);
+    }
+    if (!isRuntimeIdentifier(targetArg.swarmClusterId)
       || !isRuntimeIdentifier(targetArg.swarmNodeId)
       || !isRuntimeIdentifier(targetArg.nodeName)) {
       errors.push(`${pathArg}[${index}] node identity must be canonical`);
@@ -768,7 +771,7 @@ const validateRuntimeTargets = (
     if (!runtimePlatforms.has(targetArg.platform as TImmutableContainerPlatform)) {
       errors.push(`${pathArg}[${index}].platform must be supported`);
     }
-    if (isRuntimeIdentifier(targetArg.cloudlyNodeId)
+    if (isClusterNodeId(targetArg.cloudlyNodeId)
       && isRuntimeIdentifier(targetArg.swarmClusterId)
       && isRuntimeIdentifier(targetArg.swarmNodeId)
       && isRuntimeIdentifier(targetArg.nodeName)