@serve.zone/interfaces 32.11.0 → 32.13.0

package/ts/data/index.ts

@@ -17,6 +17,7 @@ export * from './docker.js';
 export * from './domain.js';
 export * from './event.js';
 export * from './externalregistry.js';
+export * from './fleetcutover.js';
 export * from './gateway.js';
 export * from './hostedapp.js';
 export * from './image.js';

package/ts/data/serviceruntime.ts

@@ -70,6 +70,8 @@ export const serviceRuntimeContract = Object.freeze({
   /** A node can run workloads only as an egress member of the protected authority, which admits at most this many. */
   maximumPinnedNodes: runtimeNetworkAuthorityContract.maximumEgressAuthorities,
   maximumPlatformEndpoints: runtimeNetworkAuthorityContract.maximumPlatformEndpoints,
+  /** The largest `limit` `getServiceRuntimeSpecs` accepts; Cloudly refuses a larger one. */
+  maximumSpecPageSize: 256,
   /** The largest `limit` `getClusterRuntimeAssignments` accepts; Cloudly refuses a larger one. */
   maximumAssignmentPageSize: 256,
 } as const);

package/ts/requests/fleetcutover.ts

@@ -0,0 +1,136 @@
+import * as plugins from '../plugins.js';
+import type { IIdentityCredential } from '../data/user.js';
+import type { IClusterRuntime } from '../data/clusterruntime.js';
+import type { IServiceRuntimeSpec } from '../data/serviceruntime.js';
+import type {
+  IFleetCutoverAcceptedEvidenceReference,
+  IFleetCutoverCorestoreAdoptionReceipt,
+  IFleetCutoverIngressAuthority,
+  IFleetCutoverScope,
+  IFleetCutoverScopeClassificationRequest,
+  IFleetCutoverVolumeHandoffIntent,
+  TFleetCutoverPhaseAdvance,
+  TFleetCutoverRuntimeSpecRelease,
+  TFleetCutoverVolumeFence,
+} from '../data/fleetcutover.js';
+
+export interface IReq_Any_Cloudly_GetFleetCutoverScope
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetFleetCutoverScope
+> {
+  method: 'getFleetCutoverScope';
+  request: { identity: IIdentityCredential; clusterId: string };
+  response: { scope: IFleetCutoverScope | null };
+}
+
+/**
+ * The administrator classifies the exact current census candidate. Cloudly compares every entry
+ * with its current service, platform-service, credential, and storage authority before it may
+ * persist a complete scope; the request itself is no proof of those facts.
+ */
+export interface IReq_Admin_Cloudly_ClassifyFleetCutoverScope
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_Cloudly_ClassifyFleetCutoverScope
+> {
+  method: 'classifyFleetCutoverScope';
+  request: {
+    identity: IIdentityCredential;
+    classification: IFleetCutoverScopeClassificationRequest;
+  };
+  response: { scope: IFleetCutoverScope };
+}
+
+/**
+ * Forward-only legal phase CAS. All receipt references are dereferenced by Cloudly in the same
+ * transaction; caller-supplied records or booleans never satisfy a cutover condition.
+ */
+export interface IReq_Admin_Cloudly_AdvanceFleetCutoverPhase
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_Cloudly_AdvanceFleetCutoverPhase
+> {
+  method: 'advanceFleetCutoverPhase';
+  request: { identity: IIdentityCredential; advance: TFleetCutoverPhaseAdvance };
+  response: { runtime: IClusterRuntime; replayed: boolean };
+}
+
+/**
+ * The only cutover-specific hold release. Ingress releases first under an accepted empty public
+ * port policy; applications require the accepted ingress/port/route authority assembled later.
+ */
+export interface IReq_Admin_Cloudly_ReleaseFleetCutoverRuntimeSpec
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_Cloudly_ReleaseFleetCutoverRuntimeSpec
+> {
+  method: 'releaseFleetCutoverRuntimeSpec';
+  request: { identity: IIdentityCredential; release: TFleetCutoverRuntimeSpecRelease };
+  response: { spec: IServiceRuntimeSpec; replayed: boolean };
+}
+
+export interface IReq_Any_Cloudly_GetFleetCutoverIngressAuthority
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetFleetCutoverIngressAuthority
+> {
+  method: 'getFleetCutoverIngressAuthority';
+  request: { identity: IIdentityCredential; clusterId: string };
+  response: { authority: IFleetCutoverIngressAuthority | null };
+}
+
+/** Root-local only. Holding an intent creates negative storage authority and no runtime session. */
+export interface IReq_PalletLocal_Pallet_HoldFleetCutoverVolumeFence
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_PalletLocal_Pallet_HoldFleetCutoverVolumeFence
+> {
+  method: 'holdFleetCutoverVolumeFence';
+  request: { fenceId: string; handoffIntent: IFleetCutoverVolumeHandoffIntent };
+  response: { fence: Extract<TFleetCutoverVolumeFence, { state: 'held' }> };
+}
+
+export interface IReq_PalletLocal_Pallet_GetFleetCutoverVolumeFence
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_PalletLocal_Pallet_GetFleetCutoverVolumeFence
+> {
+  method: 'getFleetCutoverVolumeFence';
+  request: { fenceId: string };
+  response: { fence: TFleetCutoverVolumeFence | null };
+}
+
+/**
+ * Pallet consumes the local fence only around a current accepted Corestore adoption result. The
+ * receipt carries the real ready storage-claim reference; the earlier handoff intent does not.
+ */
+export interface IReq_PalletLocal_Pallet_ConsumeFleetCutoverVolumeFence
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_PalletLocal_Pallet_ConsumeFleetCutoverVolumeFence
+> {
+  method: 'consumeFleetCutoverVolumeFence';
+  request: {
+    fence: IFleetCutoverAcceptedEvidenceReference;
+    adoption: IFleetCutoverCorestoreAdoptionReceipt;
+  };
+  response: { fence: Extract<TFleetCutoverVolumeFence, { state: 'consumed' }> };
+}
+
+/**
+ * Corestore owns the one-shot initial lineage/RWO CAS. The local caller supplies the held fence
+ * and server-owned handoff intent; Corestore returns the claim only after its provider is ready.
+ */
+export interface IReq_Pallet_Corestore_AdoptFleetCutoverVolume
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Pallet_Corestore_AdoptFleetCutoverVolume
+> {
+  method: 'adoptFleetCutoverVolume';
+  request: {
+    handoffIntent: IFleetCutoverVolumeHandoffIntent;
+    palletFence: Extract<TFleetCutoverVolumeFence, { state: 'held' }>;
+  };
+  response: { adoption: IFleetCutoverCorestoreAdoptionReceipt };
+}

package/ts/requests/index.ts

@@ -16,6 +16,7 @@ import * as deploymentRequests from './deployment.js';
 import * as dnsRequests from './dns.js';
 import * as domainRequests from './domain.js';
 import * as externalRegistryRequests from './externalregistry.js';
+import * as fleetCutoverRequests from './fleetcutover.js';
 import * as gatewayRequests from './gateway.js';
 import * as hostedAppRequests from './hostedapp.js';
 import * as identityRequests from './identity.js';
@@ -55,6 +56,7 @@ export {
   dnsRequests as dns,
   domainRequests as domain,
   externalRegistryRequests as externalRegistry,
+  fleetCutoverRequests as fleetcutover,
   gatewayRequests as gateway,
   hostedAppRequests as hostedapp,
   identityRequests as identity,

package/ts/requests/service.ts

@@ -393,9 +393,10 @@ extends plugins.typedrequestInterfaces.implementsTR<
 /**
  * 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.
+ * `expectedRevision` is the revision the caller read for the target `(serviceId, spec.clusterId)`,
+ * or `null` when that target 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
+ * target-local revision.
  */
 export interface IRequest_Any_Cloudly_SetServiceRuntimeSpec
 extends plugins.typedrequestInterfaces.implementsTR<
@@ -415,8 +416,20 @@ extends plugins.typedrequestInterfaces.implementsTR<
 }
 
 /**
- * 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.
+ * The named refusal data when a scalar runtime-spec read finds more than one cluster target.
+ *
+ * This travels as `TypedResponseError.errorData`. The condition needs an explicit cluster or the
+ * paged read, never a retry of the same ambiguous request.
+ */
+export interface IServiceRuntimeSpecAmbiguityErrorData {
+  code: 'service-runtime-spec-ambiguous';
+  retryable: false;
+}
+
+/**
+ * The only runtime spec of a service and the producer's verdict on it. Zero targets answer both
+ * members as `null`; one target answers it, with `status: null` until the producer first decides it.
+ * More than one target refuses with `IServiceRuntimeSpecAmbiguityErrorData`; Cloudly never picks one.
  */
 export interface IRequest_Any_Cloudly_GetServiceRuntimeSpec
 extends plugins.typedrequestInterfaces.implementsTR<
@@ -433,6 +446,71 @@ extends plugins.typedrequestInterfaces.implementsTR<
     | { spec: IServiceRuntimeSpec; status: IServiceRuntimeStatus | null };
 }
 
+/** One service's runtime spec for one exact cluster target, or no such target. */
+export interface IRequest_Any_Cloudly_GetServiceRuntimeSpecForCluster
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_GetServiceRuntimeSpecForCluster
+> {
+  method: 'getServiceRuntimeSpecForCluster';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+    clusterId: string;
+  };
+  response:
+    | { spec: null; status: null }
+    | { spec: IServiceRuntimeSpec; status: IServiceRuntimeStatus | null };
+}
+
+/**
+ * Every cluster target of one service, ordered by cluster id and read a bounded page at a time.
+ * `cursor` is opaque and `limit` runs from 1 through `serviceRuntimeContract.maximumSpecPageSize`;
+ * Cloudly refuses any other limit. A returned status belongs to the spec beside it.
+ */
+export interface IRequest_Any_Cloudly_GetServiceRuntimeSpecs
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_GetServiceRuntimeSpecs
+> {
+  method: 'getServiceRuntimeSpecs';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+    cursor: string | null;
+    limit: number;
+  };
+  response: {
+    entries: Array<{ spec: IServiceRuntimeSpec; status: IServiceRuntimeStatus | null }>;
+    nextCursor: string | null;
+  };
+}
+
+/**
+ * Removes one exact cluster target at the revision the administrator read.
+ *
+ * Cloudly derives every safety fact itself and fences them in the removal transaction: the current
+ * spec revision equals `expectedRevision`, that spec is held, every slot of this service on this
+ * cluster is fully settled and released, and the cluster's current phase still gives the spec
+ * producer authority. The caller supplies no phase, settlement, release or authority proof.
+ */
+export interface IRequest_Any_Cloudly_RemoveServiceRuntimeSpecForCluster
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_RemoveServiceRuntimeSpecForCluster
+> {
+  method: 'removeServiceRuntimeSpecForCluster';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+    clusterId: string;
+    expectedRevision: number;
+  };
+  response: {
+    removed: true;
+  };
+}
+
 /** Every current runtime assignment of one service, one per replica slot. */
 export interface IRequest_Any_Cloudly_GetServiceRuntimeAssignments
 extends plugins.typedrequestInterfaces.implementsTR<