@serve.zone/interfaces 32.44.0 → 32.46.0

package/ts/data/runtimeassignment.ts

@@ -164,6 +164,15 @@ export const runtimeImagePullRefusalReasons = ['unauthorized', 'not-found', 'tls
   'unavailable', 'other'] as const;
 export type TRuntimeImagePullRefusalReason = typeof runtimeImagePullRefusalReasons[number];
 
+/**
+ * Why a node refused to start a run before any runtime effect of it, as the node names it:
+ * `unsupported-readiness` a readiness probe the run's network cannot carry (a TCP or HTTP probe of
+ * a run without network authority), `unresolved-authority` a workload authority the node cannot
+ * resolve, and `invalid` an assignment or configuration the node cannot read.
+ */
+export const runtimeAssignmentRefusalReasons = ['unsupported-readiness', 'unresolved-authority', 'invalid'] as const;
+export type TRuntimeAssignmentRefusalReason = typeof runtimeAssignmentRefusalReasons[number];
+
 /**
  * Why a run failed, as its node can name it. Value-free: it carries a cause word and at most a
  * bounded status number, never a runtime message, a registry, a reference or a path.
@@ -176,17 +185,31 @@ export type TRuntimeImagePullRefusalReason = typeof runtimeImagePullRefusalReaso
  * - `runtime-absent`: the runtime holds no sandbox or container of a run that should be running.
  * - `network-epoch-ended`: the run's network attachment belongs to a network epoch that has ended,
  *   so the node stopped it rather than leave it running without its network.
+ * - `refused`: the node refused the run before any runtime effect of it, for `reason`, so the
+ *   observation carries no runtime identity.
+ * - `container-refused`: the runtime deterministically refused to create the run's container
+ *   (CRI `CreateContainer`), so no container of the run exists and the observation carries no
+ *   runtime identity. `grpcCode` is the runtime's gRPC status code (1..16).
  *
- * The cause explains the failure; it changes nothing about it. Every failed run is replaced the same
- * way, whichever cause it states.
+ * The cause explains the failure. Every failed run is replaced the same way, whichever cause it
+ * states, with one exception: a `refused` run is never re-placed with an identical configuration,
+ * because the node refuses the same input the same way. The controller places a new attempt only
+ * after the service's runtime spec or another input of the assignment changed.
  */
 export type TRuntimeAssignmentFailureCause =
   | { kind: 'image-pull-refused'; reason: TRuntimeImagePullRefusalReason; grpcCode: number }
   | { kind: 'exited'; exitCode: number | null }
   | { kind: 'runtime-absent' }
-  | { kind: 'network-epoch-ended' };
+  | { kind: 'network-epoch-ended' }
+  | { kind: 'refused'; reason: TRuntimeAssignmentRefusalReason }
+  | { kind: 'container-refused'; grpcCode: number };
 export const runtimeAssignmentFailureCauseKinds = ['image-pull-refused', 'exited', 'runtime-absent',
-  'network-epoch-ended'] as const satisfies readonly TRuntimeAssignmentFailureCause['kind'][];
+  'network-epoch-ended', 'refused', 'container-refused'] as const satisfies readonly TRuntimeAssignmentFailureCause['kind'][];
+
+/** The causes of a run of which nothing ever existed, so their observation names no runtime identity. */
+const causesWithoutRuntime: readonly TRuntimeAssignmentFailureCause['kind'][] = [
+  'image-pull-refused', 'refused', 'container-refused',
+];
 
 /** Value-free execution evidence. Receipt/acceptance alone never means ready. */
 export interface IRuntimeAssignmentObservation {
@@ -483,6 +506,11 @@ const isFailureCause = (valueArg: unknown): valueArg is TRuntimeAssignmentFailur
     case 'runtime-absent':
     case 'network-epoch-ended':
       return isExactRecord(valueArg, ['kind']);
+    case 'refused':
+      return isExactRecord(valueArg, ['kind', 'reason'])
+        && runtimeAssignmentRefusalReasons.some((reasonArg) => reasonArg === valueArg.reason);
+    case 'container-refused':
+      return isExactRecord(valueArg, ['kind', 'grpcCode']) && isBoundedInteger(valueArg.grpcCode, 1, 16);
     default:
       return false;
   }
@@ -508,7 +536,7 @@ const assertObservation = (valueArg: unknown): IRuntimeAssignmentObservation =>
     fail('runtime observation readiness and identity contradict its phase');
   }
   if (Object.hasOwn(valueArg, 'cause') && (valueArg.phase !== 'failed' || !isFailureCause(valueArg.cause)
-    || (valueArg.cause.kind === 'image-pull-refused' && valueArg.runtime !== null))) {
+    || (causesWithoutRuntime.includes(valueArg.cause.kind) && valueArg.runtime !== null))) {
     fail('runtime observation failure cause must be exact and belong to a failed run');
   }
   canonical(valueArg);

package/ts/data/serviceplatformownership.ts

@@ -0,0 +1,95 @@
+import { captureNetwork, networkCounter, networkId, networkRecord, requireNetwork } from '../private/networkcontract.js';
+
+/**
+ * Which authority writes a service's runtime network policy, decided by whether the service is
+ * platform-owned.
+ *
+ * A service of an idp.global organization is that organization's: its published ports are written
+ * only by a federated sign-in holding the organization's freshly introspected `owner` role, and an
+ * infrastructure administrator does not substitute for it. A platform-owned service belongs to no
+ * idp.global organization — the cluster ingress, a platform call router — so no organization owner
+ * exists who could authorize it. An infrastructure administrator designates such a service
+ * platform-owned, and from then on only a verified administrator reads and writes its published
+ * ports, as only an administrator writes its egress and its runtime spec. The designation names
+ * the authority and nothing else: it grants no port, egress or placement by itself.
+ *
+ * Only a service of a platform organization (`isPlatformOrganizationId`) is ever designated, so the
+ * federated owner rule stays the only rule for every other service, including any whose
+ * organization id is not a canonical identifier at all. Withdrawing the designation hands the
+ * ports back to the organization-owner rule, and a platform organization has no idp.global owner:
+ * the service's published ports then have no writer, and stay as they are, until an administrator
+ * designates it again.
+ */
+export interface IServicePlatformOwnership {
+  organizationId: string;
+  serviceId: string;
+  /** The administrator who designated the service. */
+  actorId: string;
+  /** Unix milliseconds on Cloudly's clock. */
+  designatedAt: number;
+}
+
+/**
+ * Every reason Cloudly answers instead of designating a service platform-owned or withdrawing the
+ * designation. Each travels by name as a `TypedResponseError`, and a refused request changes
+ * nothing.
+ */
+export const servicePlatformOwnershipRefusals = Object.freeze([
+  /** No service of that id belongs to the named organization. */
+  'service-unknown',
+  /** The service's deletion has begun; no new authority outlives it. */
+  'service-deleting',
+  /**
+   * The named organization is not a platform organization (`isPlatformOrganizationId`): an
+   * idp.global organization, whose owner keeps the authority over its runtime network policy, or an
+   * id that is no canonical identifier.
+   */
+  'organization-not-platform',
+  /** Another write changed the service's designation first: read it again. */
+  'conflict',
+] as const);
+
+/** One of the reasons Cloudly answers instead of a designation change. */
+export type TServicePlatformOwnershipRefusal = typeof servicePlatformOwnershipRefusals[number];
+
+export const servicePlatformOwnershipContract = Object.freeze({
+  error: 'Service platform ownership contract rejected.',
+} as const);
+
+/**
+ * Whether an organization id names a platform organization, the only kind whose service an
+ * administrator may designate platform-owned.
+ *
+ * Every organization Cloudly assigns outside idp.global is namespaced with `:` — a legacy service's
+ * own `legacy:Service:<id>`, a platform `Organization:<id>` — while idp.global names an
+ * organization by a 21-character nanoid in the URL alphabet (`A-Za-z0-9_-`), which never carries
+ * `:`. An id is a platform organization's exactly when it is a canonical identifier (an ASCII
+ * letter or digit, then up to 199 of letters, digits, `:`, `.`, `_` and `-`) and carries `:`.
+ * Everything else is not: an idp.global id, whichever character it starts with, and any value that
+ * is not a canonical identifier — empty, whitespace, a non-string. The answer fails closed: an id
+ * this rule cannot read never gains administrator authority.
+ */
+export const isPlatformOrganizationId = (organizationId: string): boolean => {
+  try {
+    return networkId(organizationId).includes(':');
+  } catch {
+    return false;
+  }
+};
+
+/** Detached exact-schema snapshot of a stored or answered designation. */
+export const snapshotServicePlatformOwnership = (value: unknown): IServicePlatformOwnership => {
+  try {
+    const item = networkRecord(captureNetwork(value), ['organizationId', 'serviceId', 'actorId', 'designatedAt']);
+    const organizationId = networkId(item.organizationId);
+    requireNetwork(isPlatformOrganizationId(organizationId));
+    return {
+      organizationId,
+      serviceId: networkId(item.serviceId),
+      actorId: networkId(item.actorId),
+      designatedAt: networkCounter(item.designatedAt),
+    };
+  } catch {
+    throw new Error(servicePlatformOwnershipContract.error);
+  }
+};

package/ts/data/serviceruntime.ts

@@ -91,7 +91,8 @@ const serviceRuntimeRefusals = [
   'volume-placement-unsupported', 'volume-initialization-unknown', 'volume-ownership-unknown',
   'objectstorage-endpoint-missing', 'objectstorage-binding-invalid', 'objectstorage-environment-conflict',
   'objectstorage-endpoint-unselected', 'database-endpoint-missing', 'database-endpoint-unselected',
-  'published-port-reserved', 'published-port-symmetric-without-egress',
+  'published-port-reserved', 'published-port-symmetric-without-egress', 'readiness-network-unsupported',
+  'cluster-relay-missing', 'cluster-ingress-environment-conflict',
 ] as const;
 
 /**
@@ -158,6 +159,22 @@ export type TServiceRuntimeWaitingReason = typeof serviceRuntimeWaitingReasons[n
  * which the handoff leases' `runtimeNetworkHandoffSnatPortRange` owns; a document written before
  * that rule can hold one. `published-port-symmetric-without-egress` is a `symmetric` entry in a
  * document whose `publicEgress` is false, which a projection endpoint refuses.
+ *
+ * `readiness-network-unsupported` is a spec whose network is `isolated` and whose readiness probe is
+ * `tcp` or `http`: an isolated workload has no address its node can dial, so the probe could never
+ * pass and the node refuses the run (`TRuntimeAssignmentFailureCause` `refused` for
+ * `unsupported-readiness`). `isServiceRuntimeReadinessReachable` is this rule; a producer answers
+ * what it returns. The spec snapshot still reads such a spec, so a stored one stays readable and
+ * is answered with this refusal rather than refused as data.
+ *
+ * The two `cluster-` refusals name why the environment of a cluster's designated ingress service
+ * cannot be composed (`composeClusterIngressEnvironment`); a service no designation names is never
+ * judged by them. `cluster-relay-missing` is a cluster that states no valid relay
+ * (`IClusterRelay`): the ingress registers through its relay's exact origin, so without one it has
+ * nothing to start with, and an administrator enables the relay (`enableClusterRelay`).
+ * `cluster-ingress-environment-conflict` is an ingress service whose own environment already sets
+ * one of `clusterIngressEnvironmentNames`: Cloudly owns those names, and a service value would
+ * otherwise silently replace Cloudly's or be replaced by it.
  */
 export type TServiceRuntimeRefusal = typeof serviceRuntimeRefusals[number];
 
@@ -184,6 +201,38 @@ export type IServiceRuntimeStatus = IServiceRuntimeStatusBase & (
  */
 export type TServiceRuntimeAssignmentDelivery = 'undelivered' | 'delivered';
 
+/**
+ * Why one dispatch of an assignment revision to its node ended as it did.
+ *
+ * The node holds the revision: `accepted`, `replay` or `historical` is what the node answered to
+ * the push, and `acknowledged` a revision the node's current session acknowledged before, answered
+ * from that acknowledgement without pushing it again.
+ *
+ * The node does not hold it from this dispatch: `node-busy` while the node already carries its limit
+ * of pushes in flight, `node-not-connected` while no live peer holds a session for the node,
+ * `session-moved` when the session the dispatch began on is no longer the node's current one,
+ * `intent-not-current` when the revision is no longer the one the controller wants on that node,
+ * `request-unbound` when the request does not bind to the session it would travel on,
+ * `node-refused` when the node (or the relay carrying it) answered the push with a refusal,
+ * `push-failed` when the push got no answer in time or its carrier failed, and
+ * `acknowledgement-unbound` when the answer names another revision.
+ */
+export const assignmentDispatchReasons = [
+  'accepted', 'replay', 'historical', 'acknowledged',
+  'node-busy', 'node-not-connected', 'session-moved', 'intent-not-current', 'request-unbound', 'node-refused',
+  'push-failed', 'acknowledgement-unbound',
+] as const;
+export type TAssignmentDispatchReason = typeof assignmentDispatchReasons[number];
+
+/** The last dispatch of a slot's current assignment, as the controller recorded it. Value-free. */
+export interface IServiceRuntimeAssignmentDispatch {
+  /** Whether the node holds the revision after this dispatch. */
+  delivered: boolean;
+  reason: TAssignmentDispatchReason;
+  /** Unix milliseconds on the controller's clock when this dispatch ended. */
+  at: number;
+}
+
 /** One replica slot's current assignment, as an administrator reads it. */
 export interface IServiceRuntimeAssignmentView {
   serviceId: string;
@@ -200,6 +249,12 @@ export interface IServiceRuntimeAssignmentView {
   /** Joined stop and remove receipts of this attempt. */
   terminalReceiptCount: 0 | 1 | 2;
   delivery: TServiceRuntimeAssignmentDelivery;
+  /**
+   * The last dispatch of the current revision while the controller still remembers one, null when
+   * it remembers none. Absent from a controller that does not report dispatches. Dispatch is the
+   * controller's push; `delivery` stays the node's own evidence.
+   */
+  dispatch?: IServiceRuntimeAssignmentDispatch | null;
 }
 
 /** Sorted, duplicate-free and read by the vocabulary the ids belong to: a node's, or the canonical one. */
@@ -264,6 +319,28 @@ export const snapshotServiceRuntimeSpec = (value: unknown): IServiceRuntimeSpec
     profile: profileOf(item.profile), network: networkOf(item.network), revision: networkCounter(item.revision) };
 });
 
+/**
+ * Whether a spec's readiness probe can reach its workload: false exactly for an `isolated` network
+ * with a `tcp` or `http` probe, which the producer answers as `readiness-network-unsupported`. The
+ * spec is read through `snapshotServiceRuntimeSpec`, so a value that is no spec is refused with its
+ * rejection rather than judged.
+ */
+export const isServiceRuntimeReadinessReachable = (value: unknown): boolean => {
+  const { profile, network } = snapshotServiceRuntimeSpec(value);
+  return network.mode === 'attached' || profile.readiness.kind === 'process';
+};
+
+/** Exactly a recorded dispatch of an assignment: a known reason and a positive Unix millisecond time. */
+export const isServiceRuntimeAssignmentDispatch = (value: unknown): value is IServiceRuntimeAssignmentDispatch => {
+  try {
+    const item = networkRecord(captureNetwork(value), ['delivered', 'reason', 'at']);
+    networkCounter(item.at);
+    return typeof item.delivered === 'boolean' && isOneOf(assignmentDispatchReasons, item.reason);
+  } catch {
+    return false;
+  }
+};
+
 /** Structural snapshot for exact persistence: a reason belongs to exactly one state. */
 export const snapshotServiceRuntimeStatus = (value: unknown): IServiceRuntimeStatus => producerSafe(() => {
   const item = networkRecord(captureNetwork(value), ['id', 'specRevision', 'state', 'reason', 'changedAt']);

package/ts/requests/network.ts

@@ -9,6 +9,7 @@ import type {
 import type {
   IServiceNetworkEgress, IServicePublishedPorts, ISetServiceNetworkEgress, ISetServicePublishedPorts,
 } from '../data/networkprojection.js';
+import type { IServicePlatformOwnership } from '../data/serviceplatformownership.js';
 
 /** Current organization picker data. Entries are never cached authorization grants. */
 export interface IReq_Cloudly_ListOwnedOrganizations extends plugins.typedrequestInterfaces.implementsTR<
@@ -73,7 +74,14 @@ export interface IReq_Cloudly_SetServicePrivateNetworks extends plugins.typedreq
   response: { membership: IServicePrivateNetworks; replayed: boolean };
 }
 
-/** null means the service has never had a policy document, neither published ports nor egress. */
+/**
+ * null means the service has never had a policy document, neither published ports nor egress.
+ *
+ * The authority follows the service (`IServicePlatformOwnership`): a platform-owned service is read
+ * by a verified administrator, every other service by a federated sign-in holding the named
+ * organization's freshly introspected `owner` role. A caller without that authority, or naming no
+ * such service, is answered one denial text, whichever it is.
+ */
 export interface IReq_Cloudly_GetServicePublishedPorts extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_GetServicePublishedPorts
 > {
@@ -92,6 +100,15 @@ export interface IReq_Cloudly_GetServicePublishedPorts extends plugins.typedrequ
  * attached spec stating `publicEgress: false` and `platformEndpointIds: []` matches it and reaches
  * no public address and no platform endpoint; `network-policy-missing` means the service has no
  * document at all.
+ *
+ * The authority follows the service (`IServicePlatformOwnership`): a platform-owned service is
+ * written by a verified administrator, every other service by a federated sign-in holding the named
+ * organization's freshly introspected `owner` role, and an administrator does not substitute for
+ * that owner. A caller without that authority, or naming no such service, is answered one denial
+ * text, whichever it is. A designation that changes while the write is staged refuses it as the
+ * policy write's own `conflict`, the refusal a stale `expectedRevision` is also answered (read the
+ * document and the authority again); it is a service network policy refusal, not one of
+ * `servicePlatformOwnershipRefusals`.
  */
 export interface IReq_Cloudly_SetServicePublishedPorts extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_SetServicePublishedPorts
@@ -147,6 +164,53 @@ export interface IReq_Admin_Cloudly_SetServiceNetworkEgress extends plugins.type
   response: { networkEgress: IServiceNetworkEgress; replayed: boolean };
 }
 
+/**
+ * Designates one service platform-owned (`IServicePlatformOwnership`), so that a verified
+ * administrator, and no organization owner, holds the authority over its published ports.
+ *
+ * Only a verified administrator calls it. Cloudly designates only a service of a platform
+ * organization (`isPlatformOrganizationId`: a canonical identifier carrying `:`, such as
+ * `legacy:Service:<id>` or `Organization:<id>`) and refuses every other organization id, an
+ * idp.global one or one that is no canonical identifier, as `organization-not-platform` before it
+ * reads the service. It refuses a service that is not the named organization's (`service-unknown`)
+ * and a deleting one (`service-deleting`); refusals are `servicePlatformOwnershipRefusals`. A
+ * service already designated answers its stored designation unchanged with `changed: false`.
+ */
+export interface IReq_Admin_Cloudly_DesignatePlatformOwnedService extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_Cloudly_DesignatePlatformOwnedService
+> {
+  method: 'designatePlatformOwnedService';
+  request: { identity: IIdentityCredential; organizationId: string; serviceId: string };
+  response: { platformOwnership: IServicePlatformOwnership; changed: boolean };
+}
+
+/**
+ * Withdraws a service's platform-owned designation; its published ports stay as they are, and from
+ * then on the organization-owner rule governs them. A designated service is always a platform
+ * organization's, which has no idp.global owner, so after the withdrawal nobody writes or reads its
+ * published ports until an administrator designates it again: the authority fails closed.
+ *
+ * Only a verified administrator calls it. Refusals are `service-unknown` and `conflict`; a service
+ * without a designation answers `changed: false`.
+ */
+export interface IReq_Admin_Cloudly_UndesignatePlatformOwnedService extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_Cloudly_UndesignatePlatformOwnedService
+> {
+  method: 'undesignatePlatformOwnedService';
+  request: { identity: IIdentityCredential; organizationId: string; serviceId: string };
+  response: { platformOwnership: null; changed: boolean };
+}
+
+/** The service's platform-owned designation, or null when it has none. Only a verified administrator reads it. */
+export interface IReq_Admin_Cloudly_GetServicePlatformOwnership extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_Cloudly_GetServicePlatformOwnership
+> {
+  method: 'getServicePlatformOwnership';
+  /** Refused `service-unknown` when no service of that id belongs to the named organization. */
+  request: { identity: IIdentityCredential; organizationId: string; serviceId: string };
+  response: { platformOwnership: IServicePlatformOwnership | null };
+}
+
 export interface IRequest_Any_Cloudly_GetNetworkNodes {
   method: 'getNetworkNodes';
   request: {};