@serve.zone/interfaces 32.35.0 → 32.36.1

package/ts/data/runtimelocalvolumearchive.ts

@@ -0,0 +1,207 @@
+import type * as plugins from '../plugins.js';
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
+import type { IRuntimeLocalStorageClaim } from './runtimelocalstorageclaim.js';
+import {
+  getRuntimeLocalStorageClaimReference, snapshotRuntimeLocalStorageClaim, validateRuntimeLocalStorageClaim,
+} from './runtimelocalstorageclaim.js';
+import type { IRuntimeSessionBinding } from './runtimesession.js';
+import { snapshotRuntimeSessionBinding } from './runtimesession.js';
+import {
+  captureNetwork, networkDigest, networkEqual, networkRecord, networkReference, requireNetwork,
+} from '../private/networkcontract.js';
+
+/**
+ * The one archive format a volume travels in: a POSIX.1-2001 pax archive of the volume's tree.
+ *
+ * The first entry is the volume's root, `./`, and every other name is relative below it. An entry is
+ * a directory, a regular file, a symbolic link (stored, never followed), a hard link to an earlier
+ * entry of the same archive, or a FIFO. Ownership is numeric: `uid` and `gid`, never user or group
+ * names, so the tree means the same on every host. Mode bits, including setuid, setgid and sticky,
+ * and the modification time travel exactly. A socket carries no bytes and belongs to the process
+ * that created it, so it is omitted; a device node, extended attributes and ACLs are not part of
+ * the format, and a volume that holds a device node is refused. The archive ends with the format's
+ * two zero blocks, so its length is a whole number of 512-byte blocks.
+ */
+export type TRuntimeLocalVolumeArchiveFormat = 'pax';
+
+/**
+ * A local controller reads one volume as an archive. The node refuses while a running container
+ * holds the volume: it reads a volume no container holds, or one whose holding container is
+ * stopped, which a node never restarts, and no container is granted the volume while it reads.
+ */
+export interface IReadRuntimeLocalVolumeArchiveRequest {
+  session: IRuntimeSessionBinding;
+  /** The reference of the node's current generation of a bound `directory` claim. */
+  claim: IRuntimeAuthorityReference;
+}
+
+/**
+ * The archive arrives on the stream the TypedRequest answers beside this body. `holder` states
+ * whether the volume was read unheld or under a stopped holder. The stream carries no integrity:
+ * the node learns the archive's length and digest only while it writes it.
+ */
+export interface IReadRuntimeLocalVolumeArchiveResponse {
+  claim: IRuntimeAuthorityReference;
+  format: TRuntimeLocalVolumeArchiveFormat;
+  holder: 'none' | 'stopped';
+}
+
+/**
+ * A local controller writes one archive as the bytes of an `import` claim that waits in
+ * `import-required`: the online form of an operator's offline import. The node receives the stream
+ * beside this body, whose integrity must be exactly `byteLength` and `digest`, unpacks it into a
+ * private staging tree, and publishes that tree as the volume only after the whole archive
+ * verified. The tree keeps the ownership the archive carries, as every imported tree does.
+ */
+export interface IWriteRuntimeLocalVolumeArchiveRequest {
+  session: IRuntimeSessionBinding;
+  claim: IRuntimeAuthorityReference;
+  format: TRuntimeLocalVolumeArchiveFormat;
+  byteLength: number;
+  digest: TSha256Digest;
+}
+
+/**
+ * `receiving` permits sending and confirms nothing more. The stream's acceptance receipt is what
+ * confirms that the node published the volume as `ready`; a rejected or aborted stream leaves the
+ * claim in `import-required` with nothing published.
+ */
+export interface IWriteRuntimeLocalVolumeArchiveResponse {
+  claim: IRuntimeAuthorityReference;
+  status: 'receiving';
+}
+
+/**
+ * Volume archives are a local controller's alone (`controller.kind: 'onebox'`), on the connection
+ * that holds its session, and a node moves one archive per volume at a time: a read or write of a
+ * volume that is already moving one is refused.
+ */
+export const runtimeLocalVolumeArchiveContract = Object.freeze({
+  error: 'Runtime local volume archive contract rejected.',
+  controllerKind: 'onebox',
+  format: 'pax',
+  entryKinds: ['directory', 'file', 'symlink', 'hardlink', 'fifo'],
+  omittedEntryKinds: ['socket'],
+  ownership: 'numeric-uid-gid',
+  blockBytes: 512,
+  /** The shortest archive: the root directory's header and the two closing zero blocks. */
+  minimumArchiveBytes: 1536,
+  concurrency: 'one-archive-per-volume',
+} as const);
+
+const fail = (): never => { throw new Error(runtimeLocalVolumeArchiveContract.error); };
+const safe = <T>(operationArg: () => T): T => { try { return operationArg(); } catch { return fail(); } };
+
+const archiveBytesOf = (valueArg: unknown): number => {
+  requireNetwork(typeof valueArg === 'number' && Number.isSafeInteger(valueArg)
+    && valueArg >= runtimeLocalVolumeArchiveContract.minimumArchiveBytes
+    && valueArg % runtimeLocalVolumeArchiveContract.blockBytes === 0);
+  return valueArg;
+};
+
+export const snapshotReadRuntimeLocalVolumeArchiveRequest = (
+  valueArg: unknown,
+): IReadRuntimeLocalVolumeArchiveRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['session', 'claim']);
+  return { session: snapshotRuntimeSessionBinding(value.session), claim: networkReference(value.claim) };
+});
+
+export const snapshotReadRuntimeLocalVolumeArchiveResponse = (
+  valueArg: unknown,
+): IReadRuntimeLocalVolumeArchiveResponse => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['claim', 'format', 'holder']);
+  requireNetwork(value.format === 'pax' && (value.holder === 'none' || value.holder === 'stopped'));
+  return { claim: networkReference(value.claim), format: 'pax', holder: value.holder };
+});
+
+export const snapshotWriteRuntimeLocalVolumeArchiveRequest = (
+  valueArg: unknown,
+): IWriteRuntimeLocalVolumeArchiveRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['session', 'claim', 'format', 'byteLength', 'digest']);
+  requireNetwork(value.format === 'pax');
+  return {
+    session: snapshotRuntimeSessionBinding(value.session), claim: networkReference(value.claim), format: 'pax',
+    byteLength: archiveBytesOf(value.byteLength), digest: networkDigest(value.digest),
+  };
+});
+
+export const snapshotWriteRuntimeLocalVolumeArchiveResponse = (
+  valueArg: unknown,
+): IWriteRuntimeLocalVolumeArchiveResponse => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['claim', 'status']);
+  requireNetwork(value.status === 'receiving');
+  return { claim: networkReference(value.claim), status: 'receiving' };
+});
+
+/** The exact integrity the write's stream must carry: the request's length and digest. */
+export const getRuntimeLocalVolumeArchiveIntegrity = (
+  requestArg: unknown,
+): plugins.typedrequestInterfaces.IVirtualStreamIntegrity => {
+  const request = snapshotWriteRuntimeLocalVolumeArchiveRequest(requestArg);
+  return { algorithm: 'sha256', byteLength: request.byteLength, digest: request.digest };
+};
+
+/**
+ * The claim a request names must be the node's current generation of a bound `directory` claim of
+ * the session's controller, cluster, node and runtime namespace, and the session must be a local
+ * controller's current one.
+ */
+const bindClaim = async (
+  requestArg: { session: IRuntimeSessionBinding; claim: IRuntimeAuthorityReference },
+  claimArg: unknown, trustedSessionArg: unknown,
+): Promise<IRuntimeLocalStorageClaim> => {
+  const trustedSession = safe(() => snapshotRuntimeSessionBinding(trustedSessionArg));
+  const claim = safe(() => snapshotRuntimeLocalStorageClaim(claimArg));
+  if ((await validateRuntimeLocalStorageClaim(claim)).length) fail();
+  safe(() => requireNetwork(networkEqual(requestArg.session, trustedSession)
+    && trustedSession.controller.kind === runtimeLocalVolumeArchiveContract.controllerKind
+    && networkEqual(requestArg.claim, getRuntimeLocalStorageClaimReference(claim))
+    && claim.lifecycle === 'bound' && claim.source.kind === 'directory'
+    && networkEqual(claim.controller, trustedSession.controller)
+    && claim.clusterId === trustedSession.clusterId
+    && claim.nodeId === trustedSession.nodeId
+    && claim.runtimeNamespace === trustedSession.runtimeNamespace));
+  return claim;
+};
+
+/**
+ * Node-side content binding, not authentication. `claimArg` is the node's current generation of the
+ * named claim and `trustedSessionArg` its CURRENT session, on whose own connection the request must
+ * have arrived. Whether the volume is `ready` and who holds it are the node's ledger checks.
+ */
+export const bindReadRuntimeLocalVolumeArchiveRequest = async (
+  valueArg: unknown, claimArg: unknown, trustedSessionArg: unknown,
+): Promise<{ request: IReadRuntimeLocalVolumeArchiveRequest; claim: IRuntimeLocalStorageClaim }> => {
+  const request = snapshotReadRuntimeLocalVolumeArchiveRequest(valueArg);
+  return { request, claim: await bindClaim(request, claimArg, trustedSessionArg) };
+};
+
+/**
+ * As the read binding, and the claim must be an `import` claim. That it still waits in
+ * `import-required` is the node's ledger check.
+ */
+export const bindWriteRuntimeLocalVolumeArchiveRequest = async (
+  valueArg: unknown, claimArg: unknown, trustedSessionArg: unknown,
+): Promise<{ request: IWriteRuntimeLocalVolumeArchiveRequest; claim: IRuntimeLocalStorageClaim }> => {
+  const request = snapshotWriteRuntimeLocalVolumeArchiveRequest(valueArg);
+  const claim = await bindClaim(request, claimArg, trustedSessionArg);
+  if (claim.initialization !== 'import') fail();
+  return { request, claim };
+};
+
+export const bindReadRuntimeLocalVolumeArchiveResponse = (
+  valueArg: unknown, requestArg: unknown,
+): IReadRuntimeLocalVolumeArchiveResponse => safe(() => {
+  const response = snapshotReadRuntimeLocalVolumeArchiveResponse(valueArg);
+  requireNetwork(networkEqual(response.claim, snapshotReadRuntimeLocalVolumeArchiveRequest(requestArg).claim));
+  return response;
+});
+
+export const bindWriteRuntimeLocalVolumeArchiveResponse = (
+  valueArg: unknown, requestArg: unknown,
+): IWriteRuntimeLocalVolumeArchiveResponse => safe(() => {
+  const response = snapshotWriteRuntimeLocalVolumeArchiveResponse(valueArg);
+  requireNetwork(networkEqual(response.claim, snapshotWriteRuntimeLocalVolumeArchiveRequest(requestArg).claim));
+  return response;
+});

package/ts/data/user.ts

@@ -13,6 +13,11 @@ export type TServiceDeploymentCapability =
   | 'deployment:adopt-existing'
   | 'deployment:status'
   | 'deployment:create-greenfield'
+  /**
+   * Reserve a greenfield successor whose image Cloudly imports from an attested legacy service,
+   * and have Cloudly import it. Granted on an organization-service-slot grant only.
+   */
+  | 'deployment:import-legacy'
   | 'deployment:promote-route'
   | 'deployment:rollback-image'
   | 'deployment:rollback-route'
@@ -53,6 +58,7 @@ const serviceDeploymentCapabilities = new Set<TServiceDeploymentCapability>([
   'deployment:adopt-existing',
   'deployment:status',
   'deployment:create-greenfield',
+  'deployment:import-legacy',
   'deployment:promote-route',
   'deployment:rollback-image',
   'deployment:rollback-route',
@@ -106,6 +112,10 @@ export const validateServiceDeploymentGrant = (
     && capabilities.includes('deployment:adopt-existing')) {
     errors.push('deployment:adopt-existing requires an existing-service grant');
   }
+  if (capabilities && grant.scope !== 'organization-service-slot'
+    && capabilities.includes('deployment:import-legacy')) {
+    errors.push('deployment:import-legacy requires an organization-service-slot grant');
+  }
   return errors;
 };
 

package/ts/requests/runtimesession.ts

@@ -9,6 +9,10 @@ import type * as assignmentSecret from '../runtime.assignmentsecret.js';
 import type * as fleet from '../data/fleetcutover.js';
 import type { IRuntimeStorageClaim } from '../data/runtimestorageclaim.js';
 import type * as localStorage from '../data/runtimelocalstorageclaim.js';
+import type * as logs from '../data/runtimeassignmentlogs.js';
+import type * as stats from '../data/runtimeassignmentstats.js';
+import type * as exec from '../data/runtimeassignmentexec.js';
+import type * as volumeArchive from '../data/runtimelocalvolumearchive.js';
 
 /** Current-peer, exact-projection authorization; response contains secret keys. */
 export interface IReq_Pallet_Controller_GetRuntimeManagedVpnCredential extends plugins.typedrequestInterfaces.implementsTR<
@@ -215,6 +219,104 @@ export interface IReq_Pallet_Controller_ReportRuntimeAssignmentTerminalReceipt e
   response: terminal.IReportRuntimeAssignmentTerminalReceiptResponse;
 }
 
+/**
+ * Pallet pushes one batch of one attempt's captured output over its current session and sends the
+ * next only after this one is acknowledged (`runtimeAssignmentLogContract`). The controller owns
+ * log persistence; the node's capture files are disposable transport artifacts.
+ */
+export interface IReq_Pallet_Controller_ReportRuntimeAssignmentLogs extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Pallet_Controller_ReportRuntimeAssignmentLogs
+> {
+  method: 'reportRuntimeAssignmentLogs';
+  request: logs.IReportRuntimeAssignmentLogsRequest;
+  response: logs.IReportRuntimeAssignmentLogsResponse;
+}
+
+/** Controller read of one resource sample of one attempt, over the node's current session. */
+export interface IReq_Controller_Pallet_ReadRuntimeAssignmentStats extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Controller_Pallet_ReadRuntimeAssignmentStats
+> {
+  method: 'readRuntimeAssignmentStats';
+  request: stats.IReadRuntimeAssignmentStatsRequest;
+  response: stats.IReadRuntimeAssignmentStatsResponse;
+}
+
+/**
+ * A local controller runs one command in one running attempt's container
+ * (`runtimeAssignmentExecContract`). The controller sends standard input on `stdin`, or states
+ * `null` for none. The node answers once the process runs: `stdout` carries a `tty` session's
+ * whole output, and `stderr` is `null` exactly for a `tty` session. The streams outlive this
+ * request and end when the process's output ends or the session ends.
+ */
+export interface IReq_Onebox_Pallet_OpenRuntimeAssignmentExec extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Onebox_Pallet_OpenRuntimeAssignmentExec
+> {
+  method: 'openRuntimeAssignmentExec';
+  request: {
+    exec: exec.IOpenRuntimeAssignmentExecRequest;
+    /** Requester sends standard input; the TypedHandler receives the opposite endpoint. */
+    stdin: plugins.typedrequestInterfaces.TVirtualStream<'send'> | null;
+  };
+  response: {
+    exec: exec.IOpenRuntimeAssignmentExecResponse;
+    /** Requester receives output; the TypedHandler returns sender endpoints. */
+    stdout: plugins.typedrequestInterfaces.TVirtualStream<'receive'>;
+    stderr: plugins.typedrequestInterfaces.TVirtualStream<'receive'> | null;
+  };
+}
+
+/** A local controller resizes the terminal of one `tty` exec session. */
+export interface IReq_Onebox_Pallet_ResizeRuntimeAssignmentExec extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Onebox_Pallet_ResizeRuntimeAssignmentExec
+> {
+  method: 'resizeRuntimeAssignmentExec';
+  request: exec.IResizeRuntimeAssignmentExecRequest;
+  response: exec.IResizeRuntimeAssignmentExecResponse;
+}
+
+/** A local controller ends one exec session, releases its slot and learns how it ended. */
+export interface IReq_Onebox_Pallet_CloseRuntimeAssignmentExec extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Onebox_Pallet_CloseRuntimeAssignmentExec
+> {
+  method: 'closeRuntimeAssignmentExec';
+  request: exec.ICloseRuntimeAssignmentExecRequest;
+  response: exec.ICloseRuntimeAssignmentExecResponse;
+}
+
+/**
+ * A local controller reads one node-local volume as a pax archive
+ * (`runtimeLocalVolumeArchiveContract`). The archive arrives on `archive`, which outlives this
+ * request; the node's completion of that stream is the end of the archive.
+ */
+export interface IReq_Onebox_Pallet_ReadRuntimeLocalVolumeArchive extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Onebox_Pallet_ReadRuntimeLocalVolumeArchive
+> {
+  method: 'readRuntimeLocalVolumeArchive';
+  request: volumeArchive.IReadRuntimeLocalVolumeArchiveRequest;
+  response: {
+    volume: volumeArchive.IReadRuntimeLocalVolumeArchiveResponse;
+    /** Requester receives archive bytes; the TypedHandler returns a sender endpoint. */
+    archive: plugins.typedrequestInterfaces.TVirtualStream<'receive'>;
+  };
+}
+
+/**
+ * A local controller writes one pax archive as the bytes of an `import` claim waiting in
+ * `import-required`. The stream's integrity is `getRuntimeLocalVolumeArchiveIntegrity(volume)`;
+ * its acceptance receipt confirms that the node published the volume as `ready`.
+ */
+export interface IReq_Onebox_Pallet_WriteRuntimeLocalVolumeArchive extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Onebox_Pallet_WriteRuntimeLocalVolumeArchive
+> {
+  method: 'writeRuntimeLocalVolumeArchive';
+  request: {
+    volume: volumeArchive.IWriteRuntimeLocalVolumeArchiveRequest;
+    /** Requester sends archive bytes; the TypedHandler receives the opposite endpoint. */
+    archive: plugins.typedrequestInterfaces.TVirtualStream<'send'>;
+  };
+  response: volumeArchive.IWriteRuntimeLocalVolumeArchiveResponse;
+}
+
 /** Current-peer, exact current assignment authorization; response is secret material. */
 export interface IReq_Pallet_Controller_GetRuntimeRegistryCredential extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,

package/ts/requests/service.ts

@@ -17,6 +17,7 @@ import type {
   IServiceDeploymentStatus,
 } from '../data/deploymentoperation.js';
 import type { TSha256Digest } from '../data/immutableimage.js';
+import type { ILegacyServiceRuntimeAttestation } from '../data/deploymentlegacyimport.js';
 import type { IProtocolOffer } from '../protocol.js';
 import type {
   IServiceRuntimeAssignmentView,
@@ -324,6 +325,71 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+/**
+ * Captures durable evidence that a legacy `deployOnPush` service runs exactly the registry root its
+ * tag names: every required replica observed healthy on that one digest, with the root's platform
+ * manifests read from Cloudly's own registry. Administrators only, and only while the legacy
+ * runtime still runs — incomplete evidence is refused, never stored.
+ *
+ * `expectedRuntimeDigest`, when stated, is an assertion the observed digest must equal. Capturing
+ * again for an unchanged digest returns the attestation already stored.
+ */
+export interface IRequest_Any_Cloudly_CaptureLegacyServiceRuntimeAttestation
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_CaptureLegacyServiceRuntimeAttestation
+> {
+  method: 'captureLegacyServiceRuntimeAttestation';
+  request: {
+    identity: IIdentityCredential;
+    legacyServiceId: string;
+    expectedRuntimeDigest?: TSha256Digest;
+  };
+  response: {
+    attestation: ILegacyServiceRuntimeAttestation;
+  };
+}
+
+/** Every attestation Cloudly holds for one legacy service, oldest first. Administrators only. */
+export interface IRequest_Any_Cloudly_GetLegacyServiceRuntimeAttestations
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_GetLegacyServiceRuntimeAttestations
+> {
+  method: 'getLegacyServiceRuntimeAttestations';
+  request: {
+    identity: IIdentityCredential;
+    legacyServiceId: string;
+  };
+  response: {
+    attestations: ILegacyServiceRuntimeAttestation[];
+  };
+}
+
+/**
+ * Imports the attested legacy image of a reserved legacy-import operation into the operation's own
+ * repository and release tag. Cloudly does it from its own registry — nothing is pushed — and
+ * records release evidence of source `cloudly-legacy-import`; the operation then continues exactly
+ * like one whose image was pushed. Replaying it after the import returns the recorded release.
+ */
+export interface IRequest_Any_Cloudly_ImportServiceDeploymentLegacyImage
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_ImportServiceDeploymentLegacyImage
+> {
+  method: 'importServiceDeploymentLegacyImage';
+  request: {
+    identity: IIdentityCredential;
+    serviceId: string;
+    operationId: string;
+    expectedOperationRevision: number;
+  };
+  response: {
+    operation: IServiceDeploymentOperation;
+    release: IImageRelease;
+  };
+}
+
 export interface IRequest_Any_Cloudly_CreateService
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,