@serve.zone/interfaces 7.14.0 → 7.16.0

package/changelog.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 2026-06-10 - 7.16.0
+
+### Features
+
+- add archive pruning and external backup tier interfaces (backup)
+  - Add backup record metadata for cache/external tiers and offload timestamps
+  - Define archive retention/prune result interfaces and coreflowPruneNodeArchive typed request
+  - Add settings for external backup targets and node cache retention
+
+## 2026-06-10 - 7.15.0
+
+### Features
+
+- add service migration interfaces and requests (migration)
+  - Add service migration data models and export them from the data index
+  - Add TypedRequest contracts for starting, listing, and pushing service migration updates
+  - Add service placement metadata for pinned, replicated, and held services
+
 ## 2026-06-10 - 7.14.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '7.14.0',
+    version: '7.16.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/data/backup.d.ts

@@ -62,6 +62,14 @@ export interface IBackupRecord {
     trigger: TBackupTrigger;
     snapshots: TBackupSnapshot[];
     replication?: IBackupReplicationResult;
+    /**
+     * Storage tier of the replicated archive: 'cache' = the platform S3
+     * binding next to cloudly; 'external' = the configured long-term target
+     * (external S3, NFS path, SMB). Offload moves cache -> external and then
+     * deletes the cache copy.
+     */
+    tier?: 'cache' | 'external';
+    offloadedAt?: number;
     createdAt: number;
     updatedAt: number;
     completedAt?: number;
@@ -70,3 +78,17 @@ export interface IBackupRecord {
     restoreHistory?: IBackupRestoreEvent[];
     tags?: Record<string, string>;
 }
+/** Retention policy understood by containerarchive prune. */
+export interface IArchiveRetentionPolicy {
+    keepLast?: number;
+    keepDays?: number;
+    keepWeeks?: number;
+    keepMonths?: number;
+}
+export interface IArchivePruneResult {
+    removedSnapshots: number;
+    removedPacks: number;
+    rewrittenPacks: number;
+    freedBytes: number;
+    dryRun: boolean;
+}

package/dist_ts/data/index.d.ts

@@ -2,6 +2,7 @@ export * from './cloudlyconfig.js';
 export * from './cluster.js';
 export * from './config.js';
 export * from './deployment.js';
+export * from './migration.js';
 export * from './dns.js';
 export * from './docker.js';
 export * from './domain.js';

package/dist_ts/data/index.js

@@ -2,6 +2,7 @@ export * from './cloudlyconfig.js';
 export * from './cluster.js';
 export * from './config.js';
 export * from './deployment.js';
+export * from './migration.js';
 export * from './dns.js';
 export * from './docker.js';
 export * from './domain.js';
@@ -25,4 +26,4 @@ export * from './taskexecution.js';
 export * from './traffic.js';
 export * from './user.js';
 export * from './version.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLFVBQVUsQ0FBQztBQUN6QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsY0FBYyxDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxjQUFjLENBQUMifQ==

package/dist_ts/data/migration.d.ts

@@ -0,0 +1,31 @@
+export type TServiceMigrationStatus = 'running' | 'completed' | 'failed';
+export type TServiceMigrationStepStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+export type TServiceMigrationStepKey = 'validate' | 'stop-source' | 'snapshot' | 'restore' | 'deploy-target' | 'verify';
+export interface IServiceMigrationStep {
+    key: TServiceMigrationStepKey;
+    label: string;
+    status: TServiceMigrationStepStatus;
+    startedAt?: number;
+    finishedAt?: number;
+    message?: string;
+}
+/**
+ * A node-to-node service migration orchestrated by Cloudly:
+ * gracefully stop everywhere -> snapshot data on the source ->
+ * restore on the target -> deploy pinned to the target -> verify.
+ * On failure before deploy, placement rolls back to the source.
+ */
+export interface IServiceMigration {
+    id: string;
+    serviceId: string;
+    serviceName: string;
+    sourceNodeName: string;
+    targetNodeName: string;
+    /** Backup archive id used for the data move (migration-<id>). */
+    backupId?: string;
+    status: TServiceMigrationStatus;
+    steps: IServiceMigrationStep[];
+    startedAt: number;
+    finishedAt?: number;
+    error?: string;
+}

package/dist_ts/data/migration.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWlncmF0aW9uLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9taWdyYXRpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9

package/dist_ts/data/service.d.ts

@@ -17,6 +17,23 @@ export interface IServiceVolume {
     /** Driver-specific options forwarded to Docker's VolumeDriver.Create request. */
     options?: Record<string, string>;
 }
+/**
+ * Where a service is allowed to run.
+ * - absent or mode 'replicated': the service runs on every node (legacy
+ *   full-replication behavior).
+ * - mode 'pinned' + nodeName: the service runs only on that swarm node;
+ *   other nodes stop it but preserve local data (volumes, corestore
+ *   resources) so a migration can move it safely.
+ * - hold: the service is stopped on all nodes with data preserved; used by
+ *   the migration orchestrator between the stop and deploy phases.
+ */
+export interface IServicePlacement {
+    mode: 'pinned' | 'replicated';
+    /** Swarm node hostname for pinned mode. */
+    nodeName?: string;
+    /** When true, no node runs the service (data preserved everywhere). */
+    hold?: boolean;
+}
 export type TServiceReconciliationStatus = 'running' | 'ready' | 'degraded' | 'failed';
 export interface IServiceReconciliationStageStatus {
     stage: string;
@@ -47,6 +64,7 @@ export interface IService {
          * and archived before a replacement deployment starts.
          */
         rollingCapable?: boolean;
+        placement?: IServicePlacement;
         appTemplateId?: string;
         appTemplateVersion?: string;
         appStoreUpgradePolicy?: 'manual' | 'notify' | 'auto';

package/dist_ts/data/settings.d.ts

@@ -6,6 +6,9 @@ export interface ICloudlySettings {
     hetznerToken?: string;
     cloudflareToken?: string;
     deploymentArchiveRetentionDays?: string;
+    backupExternalTargetType?: string;
+    backupExternalTargetConfig?: string;
+    backupNodeCacheKeepDays?: string;
     baseosJoinToken?: string;
     corebuildWorkerUrl?: string;
     corebuildWorkerToken?: string;

package/dist_ts/requests/backup.d.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../plugins.js';
-import type { IBackupArchiveManifest, IBackupArchiveObject, IBackupRecord, IBackupReplicationResult, TBackupSnapshot } from '../data/backup.js';
+import type { IArchivePruneResult, IArchiveRetentionPolicy, IBackupArchiveManifest, IBackupArchiveObject, IBackupRecord, IBackupReplicationResult, TBackupSnapshot } from '../data/backup.js';
 import type { IService } from '../data/service.js';
 import type { IIdentity } from '../data/user.js';
 export interface IReq_Any_Cloudly_CreateServiceBackup extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_CreateServiceBackup> {
@@ -135,3 +135,14 @@ export interface IReq_Coreflow_Cloudly_DownloadBackupArchiveObject extends plugi
         contentsBase64: string;
     };
 }
+export interface IReq_Cloudly_Coreflow_PruneNodeArchive extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Coreflow_PruneNodeArchive> {
+    method: 'coreflowPruneNodeArchive';
+    request: {
+        retention: IArchiveRetentionPolicy;
+        dryRun?: boolean;
+    };
+    response: {
+        found: boolean;
+        result?: IArchivePruneResult;
+    };
+}

package/dist_ts/requests/index.d.ts

@@ -18,6 +18,7 @@ import * as imageRequests from './image.js';
 import * as informRequests from './inform.js';
 import * as logRequests from './log.js';
 import * as mailRequests from './mail.js';
+import * as migrationRequests from './migration.js';
 import * as networkRequests from './network.js';
 import * as nodeRequests from './node.js';
 import * as platformRequests from './platform.js';
@@ -30,7 +31,7 @@ import * as settingsRequests from './settings.js';
 import * as statusRequests from './status.js';
 import * as taskRequests from './task.js';
 import * as versionRequests from './version.js';
-export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, corestoreRequests as corestore, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, gatewayRequests as gateway, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, mailRequests as mail, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
+export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, corestoreRequests as corestore, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, gatewayRequests as gateway, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, mailRequests as mail, migrationRequests as migration, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
 export * from './inform.js';
 export * from './hostedapp.js';
 export * from './mail.js';

package/dist_ts/requests/index.js

@@ -19,6 +19,7 @@ import * as imageRequests from './image.js';
 import * as informRequests from './inform.js';
 import * as logRequests from './log.js';
 import * as mailRequests from './mail.js';
+import * as migrationRequests from './migration.js';
 import * as networkRequests from './network.js';
 import * as nodeRequests from './node.js';
 import * as platformRequests from './platform.js';
@@ -31,8 +32,8 @@ import * as settingsRequests from './settings.js';
 import * as statusRequests from './status.js';
 import * as taskRequests from './task.js';
 import * as versionRequests from './version.js';
-export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, corestoreRequests as corestore, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, gatewayRequests as gateway, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, mailRequests as mail, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
+export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, corestoreRequests as corestore, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, gatewayRequests as gateway, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, mailRequests as mail, migrationRequests as migration, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
 export * from './inform.js';
 export * from './hostedapp.js';
 export * from './mail.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9yZXF1ZXN0cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUV6QyxPQUFPLEtBQUssYUFBYSxNQUFNLFlBQVksQ0FBQztBQUM1QyxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxpQkFBaUIsTUFBTSxnQkFBZ0IsQ0FBQztBQUNwRCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssbUJBQW1CLE1BQU0sa0JBQWtCLENBQUM7QUFDeEQsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLGlCQUFpQixNQUFNLGdCQUFnQixDQUFDO0FBQ3BELE9BQU8sS0FBSyxrQkFBa0IsTUFBTSxpQkFBaUIsQ0FBQztBQUN0RCxPQUFPLEtBQUssV0FBVyxNQUFNLFVBQVUsQ0FBQztBQUN4QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssd0JBQXdCLE1BQU0sdUJBQXVCLENBQUM7QUFDbEUsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGlCQUFpQixNQUFNLGdCQUFnQixDQUFDO0FBQ3BELE9BQU8sS0FBSyxnQkFBZ0IsTUFBTSxlQUFlLENBQUM7QUFDbEQsT0FBTyxLQUFLLGFBQWEsTUFBTSxZQUFZLENBQUM7QUFDNUMsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLFdBQVcsTUFBTSxVQUFVLENBQUM7QUFDeEMsT0FBTyxLQUFLLFlBQVksTUFBTSxXQUFXLENBQUM7QUFDMUMsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLFlBQVksTUFBTSxXQUFXLENBQUM7QUFDMUMsT0FBTyxLQUFLLGdCQUFnQixNQUFNLGVBQWUsQ0FBQztBQUNsRCxPQUFPLEtBQUssZUFBZSxNQUFNLGNBQWMsQ0FBQztBQUNoRCxPQUFPLEtBQUssb0JBQW9CLE1BQU0sbUJBQW1CLENBQUM7QUFDMUQsT0FBTyxLQUFLLG1CQUFtQixNQUFNLGtCQUFrQixDQUFDO0FBQ3hELE9BQU8sS0FBSyxjQUFjLE1BQU0sYUFBYSxDQUFDO0FBQzlDLE9BQU8sS0FBSyxlQUFlLE1BQU0sY0FBYyxDQUFDO0FBQ2hELE9BQU8sS0FBSyxnQkFBZ0IsTUFBTSxlQUFlLENBQUM7QUFDbEQsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLFlBQVksTUFBTSxXQUFXLENBQUM7QUFDMUMsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFFaEQsT0FBTyxFQUNMLGFBQWEsSUFBSSxLQUFLLEVBQ3RCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsaUJBQWlCLElBQUksU0FBUyxFQUM5QixjQUFjLElBQUksTUFBTSxFQUN4QixjQUFjLElBQUksTUFBTSxFQUN4QixtQkFBbUIsSUFBSSxXQUFXLEVBQ2xDLGVBQWUsSUFBSSxPQUFPLEVBQzFCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLGlCQUFpQixJQUFJLFNBQVMsRUFDOUIsa0JBQWtCLElBQUksVUFBVSxFQUNoQyxXQUFXLElBQUksR0FBRyxFQUNsQixjQUFjLElBQUksTUFBTSxFQUN4Qix3QkFBd0IsSUFBSSxnQkFBZ0IsRUFDNUMsZUFBZSxJQUFJLE9BQU8sRUFDMUIsaUJBQWlCLElBQUksU0FBUyxFQUM5QixnQkFBZ0IsSUFBSSxRQUFRLEVBQzVCLGFBQWEsSUFBSSxLQUFLLEVBQ3RCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLFdBQVcsSUFBSSxHQUFHLEVBQ2xCLFlBQVksSUFBSSxJQUFJLEVBQ3BCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLFlBQVksSUFBSSxJQUFJLEVBQ3BCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsZUFBZSxJQUFJLE9BQU8sRUFDMUIsb0JBQW9CLElBQUksWUFBWSxFQUNwQyxtQkFBbUIsSUFBSSxXQUFXLEVBQ2xDLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsWUFBWSxJQUFJLElBQUksRUFDcEIsZUFBZSxJQUFJLE9BQU8sR0FDM0IsQ0FBQztBQUVGLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxXQUFXLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9yZXF1ZXN0cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUV6QyxPQUFPLEtBQUssYUFBYSxNQUFNLFlBQVksQ0FBQztBQUM1QyxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxpQkFBaUIsTUFBTSxnQkFBZ0IsQ0FBQztBQUNwRCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssbUJBQW1CLE1BQU0sa0JBQWtCLENBQUM7QUFDeEQsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLGlCQUFpQixNQUFNLGdCQUFnQixDQUFDO0FBQ3BELE9BQU8sS0FBSyxrQkFBa0IsTUFBTSxpQkFBaUIsQ0FBQztBQUN0RCxPQUFPLEtBQUssV0FBVyxNQUFNLFVBQVUsQ0FBQztBQUN4QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssd0JBQXdCLE1BQU0sdUJBQXVCLENBQUM7QUFDbEUsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGlCQUFpQixNQUFNLGdCQUFnQixDQUFDO0FBQ3BELE9BQU8sS0FBSyxnQkFBZ0IsTUFBTSxlQUFlLENBQUM7QUFDbEQsT0FBTyxLQUFLLGFBQWEsTUFBTSxZQUFZLENBQUM7QUFDNUMsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLFdBQVcsTUFBTSxVQUFVLENBQUM7QUFDeEMsT0FBTyxLQUFLLFlBQVksTUFBTSxXQUFXLENBQUM7QUFDMUMsT0FBTyxLQUFLLGlCQUFpQixNQUFNLGdCQUFnQixDQUFDO0FBQ3BELE9BQU8sS0FBSyxlQUFlLE1BQU0sY0FBYyxDQUFDO0FBQ2hELE9BQU8sS0FBSyxZQUFZLE1BQU0sV0FBVyxDQUFDO0FBQzFDLE9BQU8sS0FBSyxnQkFBZ0IsTUFBTSxlQUFlLENBQUM7QUFDbEQsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLG9CQUFvQixNQUFNLG1CQUFtQixDQUFDO0FBQzFELE9BQU8sS0FBSyxtQkFBbUIsTUFBTSxrQkFBa0IsQ0FBQztBQUN4RCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssZUFBZSxNQUFNLGNBQWMsQ0FBQztBQUNoRCxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxjQUFjLE1BQU0sYUFBYSxDQUFDO0FBQzlDLE9BQU8sS0FBSyxZQUFZLE1BQU0sV0FBVyxDQUFDO0FBQzFDLE9BQU8sS0FBSyxlQUFlLE1BQU0sY0FBYyxDQUFDO0FBRWhELE9BQU8sRUFDTCxhQUFhLElBQUksS0FBSyxFQUN0QixnQkFBZ0IsSUFBSSxRQUFRLEVBQzVCLGlCQUFpQixJQUFJLFNBQVMsRUFDOUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsbUJBQW1CLElBQUksV0FBVyxFQUNsQyxlQUFlLElBQUksT0FBTyxFQUMxQixjQUFjLElBQUksTUFBTSxFQUN4QixpQkFBaUIsSUFBSSxTQUFTLEVBQzlCLGtCQUFrQixJQUFJLFVBQVUsRUFDaEMsV0FBVyxJQUFJLEdBQUcsRUFDbEIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsd0JBQXdCLElBQUksZ0JBQWdCLEVBQzVDLGVBQWUsSUFBSSxPQUFPLEVBQzFCLGlCQUFpQixJQUFJLFNBQVMsRUFDOUIsZ0JBQWdCLElBQUksUUFBUSxFQUM1QixhQUFhLElBQUksS0FBSyxFQUN0QixjQUFjLElBQUksTUFBTSxFQUN4QixXQUFXLElBQUksR0FBRyxFQUNsQixZQUFZLElBQUksSUFBSSxFQUNwQixpQkFBaUIsSUFBSSxTQUFTLEVBQzlCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLFlBQVksSUFBSSxJQUFJLEVBQ3BCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsZUFBZSxJQUFJLE9BQU8sRUFDMUIsb0JBQW9CLElBQUksWUFBWSxFQUNwQyxtQkFBbUIsSUFBSSxXQUFXLEVBQ2xDLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsWUFBWSxJQUFJLElBQUksRUFDcEIsZUFBZSxJQUFJLE9BQU8sR0FDM0IsQ0FBQztBQUVGLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxXQUFXLENBQUMifQ==

package/dist_ts/requests/migration.d.ts

@@ -0,0 +1,35 @@
+import * as plugins from '../plugins.js';
+import type { IServiceMigration } from '../data/migration.js';
+import type { IIdentity } from '../data/user.js';
+export interface IReq_Any_Cloudly_MigrateServiceToNode extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_MigrateServiceToNode> {
+    method: 'migrateServiceToNode';
+    request: {
+        identity: IIdentity;
+        serviceId: string;
+        /** Swarm node hostname holding the authoritative data copy. */
+        sourceNodeName: string;
+        /** Swarm node hostname the service moves to. */
+        targetNodeName: string;
+    };
+    response: {
+        migration: IServiceMigration;
+    };
+}
+export interface IReq_Any_Cloudly_GetServiceMigrations extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_GetServiceMigrations> {
+    method: 'getServiceMigrations';
+    request: {
+        identity: IIdentity;
+        /** Limit to one service; absent returns all migrations. */
+        serviceId?: string;
+    };
+    response: {
+        migrations: IServiceMigration[];
+    };
+}
+export interface IReq_Cloudly_Any_PushServiceMigrationUpdate extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Any_PushServiceMigrationUpdate> {
+    method: 'pushServiceMigrationUpdate';
+    request: {
+        migration: IServiceMigration;
+    };
+    response: Record<string, never>;
+}

package/dist_ts/requests/migration.js

@@ -0,0 +1,2 @@
+import * as plugins from '../plugins.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWlncmF0aW9uLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvcmVxdWVzdHMvbWlncmF0aW9uLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sZUFBZSxDQUFDIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "7.14.0",
+  "version": "7.16.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '7.14.0',
+  version: '7.16.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/data/backup.ts

@@ -86,6 +86,14 @@ export interface IBackupRecord {
   trigger: TBackupTrigger;
   snapshots: TBackupSnapshot[];
   replication?: IBackupReplicationResult;
+  /**
+   * Storage tier of the replicated archive: 'cache' = the platform S3
+   * binding next to cloudly; 'external' = the configured long-term target
+   * (external S3, NFS path, SMB). Offload moves cache -> external and then
+   * deletes the cache copy.
+   */
+  tier?: 'cache' | 'external';
+  offloadedAt?: number;
   createdAt: number;
   updatedAt: number;
   completedAt?: number;
@@ -94,3 +102,19 @@ export interface IBackupRecord {
   restoreHistory?: IBackupRestoreEvent[];
   tags?: Record<string, string>;
 }
+
+/** Retention policy understood by containerarchive prune. */
+export interface IArchiveRetentionPolicy {
+  keepLast?: number;
+  keepDays?: number;
+  keepWeeks?: number;
+  keepMonths?: number;
+}
+
+export interface IArchivePruneResult {
+  removedSnapshots: number;
+  removedPacks: number;
+  rewrittenPacks: number;
+  freedBytes: number;
+  dryRun: boolean;
+}

package/ts/data/index.ts

@@ -2,6 +2,7 @@ export * from './cloudlyconfig.js';
 export * from './cluster.js';
 export * from './config.js';
 export * from './deployment.js';
+export * from './migration.js';
 export * from './dns.js';
 export * from './docker.js';
 export * from './domain.js';

package/ts/data/migration.ts

@@ -0,0 +1,41 @@
+export type TServiceMigrationStatus = 'running' | 'completed' | 'failed';
+
+export type TServiceMigrationStepStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+
+export type TServiceMigrationStepKey =
+  | 'validate'
+  | 'stop-source'
+  | 'snapshot'
+  | 'restore'
+  | 'deploy-target'
+  | 'verify';
+
+export interface IServiceMigrationStep {
+  key: TServiceMigrationStepKey;
+  label: string;
+  status: TServiceMigrationStepStatus;
+  startedAt?: number;
+  finishedAt?: number;
+  message?: string;
+}
+
+/**
+ * A node-to-node service migration orchestrated by Cloudly:
+ * gracefully stop everywhere -> snapshot data on the source ->
+ * restore on the target -> deploy pinned to the target -> verify.
+ * On failure before deploy, placement rolls back to the source.
+ */
+export interface IServiceMigration {
+  id: string;
+  serviceId: string;
+  serviceName: string;
+  sourceNodeName: string;
+  targetNodeName: string;
+  /** Backup archive id used for the data move (migration-<id>). */
+  backupId?: string;
+  status: TServiceMigrationStatus;
+  steps: IServiceMigrationStep[];
+  startedAt: number;
+  finishedAt?: number;
+  error?: string;
+}

package/ts/data/service.ts

@@ -19,6 +19,24 @@ export interface IServiceVolume {
   options?: Record<string, string>;
 }
 
+/**
+ * Where a service is allowed to run.
+ * - absent or mode 'replicated': the service runs on every node (legacy
+ *   full-replication behavior).
+ * - mode 'pinned' + nodeName: the service runs only on that swarm node;
+ *   other nodes stop it but preserve local data (volumes, corestore
+ *   resources) so a migration can move it safely.
+ * - hold: the service is stopped on all nodes with data preserved; used by
+ *   the migration orchestrator between the stop and deploy phases.
+ */
+export interface IServicePlacement {
+  mode: 'pinned' | 'replicated';
+  /** Swarm node hostname for pinned mode. */
+  nodeName?: string;
+  /** When true, no node runs the service (data preserved everywhere). */
+  hold?: boolean;
+}
+
 export type TServiceReconciliationStatus = 'running' | 'ready' | 'degraded' | 'failed';
 
 export interface IServiceReconciliationStageStatus {
@@ -53,6 +71,7 @@ export interface IService {
      * and archived before a replacement deployment starts.
      */
     rollingCapable?: boolean;
+    placement?: IServicePlacement;
     appTemplateId?: string;
     appTemplateVersion?: string;
     appStoreUpgradePolicy?: 'manual' | 'notify' | 'auto';

package/ts/data/settings.ts

@@ -12,6 +12,18 @@ export interface ICloudlySettings {
   // Retention for archived deployment records in days (default 90)
   deploymentArchiveRetentionDays?: string;
 
+  // Long-term backup target. Type 's3' | 'nfs' | 'smb'; config is a JSON
+  // object string with the matching connection fields (s3: endpoint,
+  // accessKey, secretKey, bucket, port?, useSsl?, region?; nfs: path
+  // mounted into the cloudly container; smb: host, share, username?,
+  // password?, domain?, port?). Absent = no offload, backups stay on the
+  // cache tier.
+  backupExternalTargetType?: string;
+  backupExternalTargetConfig?: string;
+
+  // Node-local archive cache retention in days (corestore prune; default 30)
+  backupNodeCacheKeepDays?: string;
+
   // BaseOS enrollment
   baseosJoinToken?: string;
 

package/ts/requests/backup.ts

@@ -1,5 +1,7 @@
 import * as plugins from '../plugins.js';
 import type {
+  IArchivePruneResult,
+  IArchiveRetentionPolicy,
   IBackupArchiveManifest,
   IBackupArchiveObject,
   IBackupRecord,
@@ -196,3 +198,19 @@ extends plugins.typedrequestInterfaces.implementsTR<
     contentsBase64: string;
   };
 }
+
+export interface IReq_Cloudly_Coreflow_PruneNodeArchive
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Coreflow_PruneNodeArchive
+> {
+  method: 'coreflowPruneNodeArchive';
+  request: {
+    retention: IArchiveRetentionPolicy;
+    dryRun?: boolean;
+  };
+  response: {
+    found: boolean;
+    result?: IArchivePruneResult;
+  };
+}

package/ts/requests/index.ts

@@ -20,6 +20,7 @@ import * as imageRequests from './image.js';
 import * as informRequests from './inform.js';
 import * as logRequests from './log.js';
 import * as mailRequests from './mail.js';
+import * as migrationRequests from './migration.js';
 import * as networkRequests from './network.js';
 import * as nodeRequests from './node.js';
 import * as platformRequests from './platform.js';
@@ -54,6 +55,7 @@ export {
   informRequests as inform,
   logRequests as log,
   mailRequests as mail,
+  migrationRequests as migration,
   networkRequests as network,
   nodeRequests as node,
   platformRequests as platform,

package/ts/requests/migration.ts

@@ -0,0 +1,50 @@
+import * as plugins from '../plugins.js';
+import type { IServiceMigration } from '../data/migration.js';
+import type { IIdentity } from '../data/user.js';
+
+export interface IReq_Any_Cloudly_MigrateServiceToNode
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_MigrateServiceToNode
+> {
+  method: 'migrateServiceToNode';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+    /** Swarm node hostname holding the authoritative data copy. */
+    sourceNodeName: string;
+    /** Swarm node hostname the service moves to. */
+    targetNodeName: string;
+  };
+  response: {
+    migration: IServiceMigration;
+  };
+}
+
+export interface IReq_Any_Cloudly_GetServiceMigrations
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetServiceMigrations
+> {
+  method: 'getServiceMigrations';
+  request: {
+    identity: IIdentity;
+    /** Limit to one service; absent returns all migrations. */
+    serviceId?: string;
+  };
+  response: {
+    migrations: IServiceMigration[];
+  };
+}
+
+export interface IReq_Cloudly_Any_PushServiceMigrationUpdate
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Any_PushServiceMigrationUpdate
+> {
+  method: 'pushServiceMigrationUpdate';
+  request: {
+    migration: IServiceMigration;
+  };
+  response: Record<string, never>;
+}