@serve.zone/interfaces 31.8.0 → 32.0.0

package/ts/data/runtimeconfig.ts

@@ -1,6 +1,6 @@
 import type {
-  IImmutableContainerInvocationPlatformEvidenceV1,
-  IImmutableContainerInvocationV1,
+  IImmutableContainerInvocation,
+  IImmutableContainerInvocationPlatformEvidence,
   TSha256Digest,
 } from './immutableimage.js';
 import {
@@ -9,12 +9,16 @@ import {
   validateImmutableContainerInvocation,
   verifyImmutableContainerInvocationDigest,
 } from './immutableimage.js';
-import type { IRuntimeAssignmentV1, IRuntimeAuthorityReferenceV1 } from './runtimeassignment.js';
-import { snapshotRuntimeAssignmentV1, validateRuntimeAssignmentV1 } from './runtimeassignment.js';
+import type { IRuntimeAssignment, IRuntimeAuthorityReference } from './runtimeassignment.js';
+import { snapshotRuntimeAssignment, validateRuntimeAssignment } from './runtimeassignment.js';
 import { canonicalizeStrictJson, createCanonicalJsonSha256Hex } from '../private/canonicaljson.js';
+import {
+  assertRuntimeReadiness, isBoundedInteger, isExactRecord, isRuntimeCpuMillis, isRuntimeIdentityNumber,
+  isRuntimeLogPolicy, isRuntimeMemoryBytes, isRuntimePortName, runtimePolicyLimits,
+} from '../private/runtimepolicy.js';
 
 /** A container target only; declaration does not publish a host or gateway port. */
-export interface IRuntimeConfigTargetPortV1 {
+export interface IRuntimeConfigTargetPort {
   name: string;
   port: number;
   /** Inclusive; equal to port for a single port. */
@@ -22,7 +26,7 @@ export interface IRuntimeConfigTargetPortV1 {
   protocol: 'tcp' | 'udp';
 }
 
-export interface IRuntimeConfigReadinessTimingV1 {
+export interface IRuntimeConfigReadinessTiming {
   /** Measured from the evidenced container start; no probes before this delay. */
   initialDelayMs: number;
   /** Failures during this startup grace cannot mark the workload unhealthy. */
@@ -37,7 +41,7 @@ export interface IRuntimeConfigReadinessTimingV1 {
   failureThreshold: number;
 }
 
-export type TRuntimeConfigReadinessV1 = IRuntimeConfigReadinessTimingV1 & (
+export type TRuntimeConfigReadiness = IRuntimeConfigReadinessTiming & (
   | { kind: 'process' }
   | { kind: 'tcp'; targetPort: string; port: number }
   | {
@@ -60,7 +64,7 @@ export type TRuntimeConfigReadinessV1 = IRuntimeConfigReadinessTimingV1 & (
   }
 );
 
-export interface IRuntimeConfigLogPolicyV1 {
+export interface IRuntimeConfigLogPolicy {
   /** Maximum UTF-8 bytes in one captured stdout/stderr line. */
   maximumLineBytes: number;
   /** Maximum bytes waiting for delivery; overflow requires explicit evidence. */
@@ -76,8 +80,7 @@ export interface IRuntimeConfigLogPolicyV1 {
  * Secrets, network identity and storage claims remain separately assignment-bound
  * owner references. This document contains no registry credentials or host paths.
  */
-export interface IRuntimeConfigV1 extends IRuntimeAuthorityReferenceV1 {
-  schemaVersion: 1;
+export interface IRuntimeConfig extends IRuntimeAuthorityReference {
   organizationId: string;
   serviceId: string;
   image: {
@@ -85,7 +88,7 @@ export interface IRuntimeConfigV1 extends IRuntimeAuthorityReferenceV1 {
     repository: string;
     /** Root descriptor digest, which may be an OCI platform index. */
     imageDigest: TSha256Digest;
-    invocation: IImmutableContainerInvocationV1;
+    invocation: IImmutableContainerInvocation;
   };
   /** Complete effective public environment; secret values must never be inlined. */
   environment: Record<string, string>;
@@ -106,50 +109,38 @@ export interface IRuntimeConfigV1 extends IRuntimeAuthorityReferenceV1 {
   /** Numeric override paired with runAsUser, or null for the image identity policy. */
   runAsGroup: number | null;
   /** Sorted unique names, with no overlapping ranges for the same transport. */
-  targetPorts: IRuntimeConfigTargetPortV1[];
-  readiness: TRuntimeConfigReadinessV1;
+  targetPorts: IRuntimeConfigTargetPort[];
+  readiness: TRuntimeConfigReadiness;
   /**
    * SmartData owns log metadata and SmartBucket owns archived payloads. This
    * policy does not authorize persistent local files. Any CRI log capture uses
    * disposable process-local transport artifacts and must evidence bounded
    * buffering, backpressure and lost data; it must not silently truncate logs.
    */
-  logs: IRuntimeConfigLogPolicyV1;
+  logs: IRuntimeConfigLogPolicy;
 }
 
-export interface IRuntimeConfigAssignmentBindingV1 {
-  config: IRuntimeConfigV1;
-  assignment: IRuntimeAssignmentV1;
-  platformEvidence: IImmutableContainerInvocationPlatformEvidenceV1;
+export interface IRuntimeConfigAssignmentBinding {
+  config: IRuntimeConfig;
+  assignment: IRuntimeAssignment;
+  platformEvidence: IImmutableContainerInvocationPlatformEvidence;
 }
 
-export const runtimeConfigV1Contract = Object.freeze({
-  digestDomain: 'serve.zone/runtime-config-v1',
+export const runtimeConfigContract = Object.freeze({
+  digestDomain: 'serve.zone/runtime-config',
   maximumCanonicalBytes: 262_144,
   maximumEnvironmentEntries: 128,
   maximumTargetPorts: 64,
-  maximumReadinessDurationMs: 3_600_000,
-  maximumLogRetentionMs: 31_536_000_000,
+  maximumReadinessDurationMs: runtimePolicyLimits.maximumReadinessDurationMs,
+  maximumLogRetentionMs: runtimePolicyLimits.maximumLogRetentionMs,
 } as const);
 
 const fail: (messageArg: string) => never = (messageArg) => { throw new Error(messageArg); };
 const encoder = new TextEncoder();
-const isInteger = (valueArg: unknown, minimumArg: number, maximumArg: number): valueArg is number =>
-  typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && !Object.is(valueArg, -0)
-  && valueArg >= minimumArg && valueArg <= maximumArg;
 const isIdentifier = (valueArg: unknown): valueArg is string =>
   typeof valueArg === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(valueArg);
 const isDigest = (valueArg: unknown): valueArg is TSha256Digest =>
   typeof valueArg === 'string' && isSha256Digest(valueArg);
-const isPortName = (valueArg: unknown): valueArg is string =>
-  typeof valueArg === 'string' && /^[a-z0-9][a-z0-9_.-]{0,62}$/.test(valueArg);
-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));
-};
 
 /**
  * Bound traversal before canonicalization and copy descriptor values so input
@@ -161,9 +152,9 @@ const snapshotBoundedJson = (valueArg: unknown): unknown => {
   let stringBytes = 0;
   const ancestors = new Set<object>();
   const accountString = (value: string): void => {
-    if (value.length > runtimeConfigV1Contract.maximumCanonicalBytes) fail('runtime config string is oversized');
+    if (value.length > runtimeConfigContract.maximumCanonicalBytes) fail('runtime config string is oversized');
     stringBytes += encoder.encode(value).byteLength;
-    if (stringBytes > runtimeConfigV1Contract.maximumCanonicalBytes) fail('runtime config is oversized');
+    if (stringBytes > runtimeConfigContract.maximumCanonicalBytes) fail('runtime config is oversized');
   };
   const copy = (value: unknown, depth: number): unknown => {
     if (++nodes > 8192 || depth > 12) fail('runtime config exceeds structural bounds');
@@ -183,7 +174,7 @@ const snapshotBoundedJson = (valueArg: unknown): unknown => {
       if (array) {
         const lengthDescriptor = Object.getOwnPropertyDescriptor(value, 'length');
         const length = lengthDescriptor?.value;
-        if (!isInteger(length, 0, 256) || keys.length !== length + 1) {
+        if (!isBoundedInteger(length, 0, 256) || keys.length !== length + 1) {
           fail('runtime config requires bounded dense arrays');
         }
         const result: unknown[] = [];
@@ -210,68 +201,20 @@ const snapshotBoundedJson = (valueArg: unknown): unknown => {
     } finally { ancestors.delete(value); }
   };
   const canonical = canonicalizeStrictJson(copy(valueArg, 0), fail);
-  if (encoder.encode(canonical).byteLength > runtimeConfigV1Contract.maximumCanonicalBytes) {
+  if (encoder.encode(canonical).byteLength > runtimeConfigContract.maximumCanonicalBytes) {
     fail('runtime config canonical JSON is oversized');
   }
   return JSON.parse(canonical);
 };
 
-const timingKeys = ['initialDelayMs', 'startupGraceMs', 'intervalMs', 'timeoutMs',
-  'successThreshold', 'failureThreshold'] as const;
-const assertReadiness = (valueArg: unknown, portsArg: IRuntimeConfigTargetPortV1[]): void => {
-  if (!valueArg || typeof valueArg !== 'object') fail('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'] : [];
-  if (keys.length === 0 || !isExactRecord(value, keys)
-    || !isInteger(value.initialDelayMs, 0, runtimeConfigV1Contract.maximumReadinessDurationMs)
-    || !isInteger(value.startupGraceMs, 0, runtimeConfigV1Contract.maximumReadinessDurationMs)
-    || !isInteger(value.intervalMs, 100, runtimeConfigV1Contract.maximumReadinessDurationMs)
-    || !isInteger(value.timeoutMs, 1, 60_000)
-    || !isInteger(value.successThreshold, 1, 100)
-    || !isInteger(value.failureThreshold, 1, 100)
-    || value.timeoutMs > value.intervalMs || value.initialDelayMs > value.startupGraceMs) {
-    fail('runtime config readiness must use explicit bounded timing and exact schema');
-  }
-  if (value.kind === 'process') return;
-  const target = portsArg.find((portArg) => portArg.name === value.targetPort);
-  if (!isPortName(value.targetPort) || !target || target.protocol !== 'tcp'
-    || !isInteger(value.port, target.port, target.portEnd)) {
-    fail('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) {
-    fail('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) fail('runtime config HTTP path must be canonical');
-  let previousCode = 0;
-  for (const code of value.expectedStatusCodes) {
-    if (!isInteger(code, 200, 599) || code <= previousCode) {
-      fail('runtime config HTTP status expectations must be sorted unique final codes');
-    }
-    previousCode = code;
-  }
-};
-
-const assertConfig = (valueArg: unknown): IRuntimeConfigV1 => {
-  if (!isExactRecord(valueArg, ['schemaVersion', 'id', 'generation', 'organizationId', 'serviceId',
+const assertConfig = (valueArg: unknown): IRuntimeConfig => {
+  if (!isExactRecord(valueArg, ['id', 'generation', 'organizationId', 'serviceId',
     'image', 'environment', 'workingDirectory', 'cpuMillis', 'memoryBytes', 'readonlyRootfs',
     'runAsUser', 'runAsGroup', 'targetPorts', 'readiness', 'logs', 'digest'])
-    || valueArg.schemaVersion !== 1 || !isIdentifier(valueArg.id)
-    || !isInteger(valueArg.generation, 1, Number.MAX_SAFE_INTEGER)
+    || !isIdentifier(valueArg.id)
+    || !isBoundedInteger(valueArg.generation, 1, Number.MAX_SAFE_INTEGER)
     || !isIdentifier(valueArg.organizationId) || !isIdentifier(valueArg.serviceId)
-    || !isDigest(valueArg.digest)) fail('runtime config must use its exact v1 schema');
+    || !isDigest(valueArg.digest)) fail('runtime config must use its exact schema');
   const image = valueArg.image;
   if (!isExactRecord(image, ['registryHost', 'repository', 'imageDigest', 'invocation'])
     || typeof image.registryHost !== 'string' || image.registryHost.length > 253
@@ -284,7 +227,7 @@ const assertConfig = (valueArg: unknown): IRuntimeConfigV1 => {
     image.imageDigest as TSha256Digest);
   const environment = valueArg.environment;
   if (!environment || typeof environment !== 'object' || Array.isArray(environment)
-    || Object.keys(environment).length > runtimeConfigV1Contract.maximumEnvironmentEntries) {
+    || Object.keys(environment).length > runtimeConfigContract.maximumEnvironmentEntries) {
     fail('runtime config requires an explicit bounded nonsecret environment');
   }
   for (const [key, value] of Object.entries(environment)) {
@@ -297,69 +240,66 @@ const assertConfig = (valueArg: unknown): IRuntimeConfigV1 => {
   if (typeof directory !== 'string' || !directory.startsWith('/')
     || encoder.encode(directory).byteLength > 4096 || /[\u0000-\u001f\u007f]/.test(directory)
     || (directory !== '/' && directory.split('/').slice(1).some((partArg) => !partArg || partArg === '.' || partArg === '..'))
-    || !(valueArg.cpuMillis === null || isInteger(valueArg.cpuMillis, 1, 1_000_000))
-    || !isInteger(valueArg.memoryBytes, 16 * 1024 * 1024, 2 ** 50)
+    || !isRuntimeCpuMillis(valueArg.cpuMillis)
+    || !isRuntimeMemoryBytes(valueArg.memoryBytes)
     || typeof valueArg.readonlyRootfs !== 'boolean'
     || !((valueArg.runAsUser === null && valueArg.runAsGroup === null)
-      || (isInteger(valueArg.runAsUser, 0, 2 ** 31 - 1) && isInteger(valueArg.runAsGroup, 0, 2 ** 31 - 1)))) {
+      || (isRuntimeIdentityNumber(valueArg.runAsUser) && isRuntimeIdentityNumber(valueArg.runAsGroup)))) {
     fail('runtime config requires canonical directory and explicit resource and identity policies');
   }
   const ports = valueArg.targetPorts;
-  if (!Array.isArray(ports) || ports.length > runtimeConfigV1Contract.maximumTargetPorts) {
+  if (!Array.isArray(ports) || ports.length > runtimeConfigContract.maximumTargetPorts) {
     fail('runtime config target ports must be a bounded array');
   }
   let previousName = '';
-  const validatedPorts: IRuntimeConfigTargetPortV1[] = [];
+  const validatedPorts: IRuntimeConfigTargetPort[] = [];
   for (const port of ports) {
     if (!isExactRecord(port, ['name', 'port', 'portEnd', 'protocol'])
-      || !isPortName(port.name) || port.name <= previousName
-      || !isInteger(port.port, 1, 65535) || !isInteger(port.portEnd, port.port, 65535)
+      || !isRuntimePortName(port.name) || port.name <= previousName
+      || !isBoundedInteger(port.port, 1, 65535) || !isBoundedInteger(port.portEnd, port.port, 65535)
       || (port.protocol !== 'tcp' && port.protocol !== 'udp')
       || validatedPorts.some((previousArg) => previousArg.protocol === port.protocol
         && (port.port as number) <= previousArg.portEnd && (port.portEnd as number) >= previousArg.port)) {
       fail('runtime config target ports require sorted unique names and nonoverlapping transport ranges');
     }
     previousName = port.name;
-    validatedPorts.push(port as unknown as IRuntimeConfigTargetPortV1);
+    validatedPorts.push(port as unknown as IRuntimeConfigTargetPort);
   }
-  assertReadiness(valueArg.readiness, validatedPorts);
-  const logs = valueArg.logs;
-  if (!isExactRecord(logs, ['maximumLineBytes', 'maximumBufferedBytes', 'retentionMs'])
-    || !isInteger(logs.maximumLineBytes, 1, 1_048_576)
-    || !isInteger(logs.maximumBufferedBytes, 1, 67_108_864)
-    || logs.maximumBufferedBytes < logs.maximumLineBytes
-    || !isInteger(logs.retentionMs, 1, runtimeConfigV1Contract.maximumLogRetentionMs)) {
+  assertRuntimeReadiness(valueArg.readiness, (targetPortArg, portArg) => validatedPorts.some((targetArg) =>
+    targetArg.name === targetPortArg && targetArg.protocol === 'tcp'
+    && portArg >= targetArg.port && portArg <= targetArg.portEnd), fail);
+  if (!isRuntimeLogPolicy(valueArg.logs)) {
     fail('runtime config logs require explicit bounded line, buffer and retention limits');
   }
-  return valueArg as unknown as IRuntimeConfigV1;
+  return valueArg as unknown as IRuntimeConfig;
 };
 
 /**
  * Detached exact-schema snapshot for synchronous persistence assertions. Digest
  * integrity, scope authorization, admission and runtime readiness are not implied.
  */
-export const snapshotRuntimeConfigV1 = (valueArg: unknown): IRuntimeConfigV1 =>
+export const snapshotRuntimeConfig = (valueArg: unknown): IRuntimeConfig =>
   assertConfig(snapshotBoundedJson(valueArg));
 
 /** Domain-separated canonical JSON excludes only the config's own digest. */
-export const computeRuntimeConfigV1Digest = async (configArg: IRuntimeConfigV1): Promise<TSha256Digest> => {
-  const { digest: _digest, ...payload } = snapshotRuntimeConfigV1(configArg);
+export const computeRuntimeConfigDigest = async (configArg: IRuntimeConfig): Promise<TSha256Digest> => {
+  const { digest: _digest, ...payload } = snapshotRuntimeConfig(configArg);
   return `sha256:${await createCanonicalJsonSha256Hex(canonicalizeStrictJson({
-    domain: runtimeConfigV1Contract.digestDomain, payload,
+    domain: runtimeConfigContract.digestDomain, payload,
   }, fail), fail)}`;
 };
 
-const validateSnapshot = async (configArg: IRuntimeConfigV1): Promise<string[]> => {
+const validateSnapshot = async (configArg: IRuntimeConfig): Promise<string[]> => {
   if (!await verifyImmutableContainerInvocationDigest(configArg.image.invocation)) {
     return ['runtime config immutable invocation digest does not match'];
   }
-  return configArg.digest === await computeRuntimeConfigV1Digest(configArg)
+  return configArg.digest === await computeRuntimeConfigDigest(configArg)
     ? [] : ['runtime config digest does not match'];
 };
 
-export const validateRuntimeConfigV1 = async (valueArg: unknown): Promise<string[]> => {
-  try { return await validateSnapshot(snapshotRuntimeConfigV1(valueArg)); }
-  catch { return ['runtime config must use its exact canonical v1 schema']; }
+export const validateRuntimeConfig = async (valueArg: unknown): Promise<string[]> => {
+  try { return await validateSnapshot(snapshotRuntimeConfig(valueArg)); }
+  catch { return ['runtime config must use its exact canonical schema']; }
 };
 
 /**
@@ -369,13 +309,13 @@ export const validateRuntimeConfigV1 = async (valueArg: unknown): Promise<string
  * controller, durably admit the attempt, resolve other owner references, and
  * verify runtime and readiness evidence before effects or route publication.
  */
-export const bindRuntimeConfigV1ToAssignment = async (
+export const bindRuntimeConfigToAssignment = async (
   configArg: unknown, assignmentArg: unknown,
-): Promise<IRuntimeConfigAssignmentBindingV1> => {
-  const config = snapshotRuntimeConfigV1(configArg);
-  const assignment = snapshotRuntimeAssignmentV1(snapshotBoundedJson(assignmentArg));
+): Promise<IRuntimeConfigAssignmentBinding> => {
+  const config = snapshotRuntimeConfig(configArg);
+  const assignment = snapshotRuntimeAssignment(snapshotBoundedJson(assignmentArg));
   if ((await validateSnapshot(config)).length !== 0
-    || (await validateRuntimeAssignmentV1(assignment)).length !== 0) {
+    || (await validateRuntimeAssignment(assignment)).length !== 0) {
     fail('runtime config binding requires valid config, invocation and assignment digests');
   }
   const reference = assignment.workload.config;