@blaxel/core 0.3.13 → 0.3.18-dev.283

package/dist/cjs/sandbox/sandbox.js

@@ -67,6 +67,23 @@ const TRANSIENT_SANDBOX_STATUSES = new Set([
 ]);
 const TRANSIENT_STATUS_MAX_WAIT_MS = 30_000;
 const TRANSIENT_STATUS_POLL_MS = 500;
+// Archiving a filesystem, and restoring it, take as long as that filesystem is
+// big — minutes for a few gigabytes.
+const ARCHIVE_MAX_WAIT_MS = 1_800_000;
+const ARCHIVE_WAIT_POLL_MS = 2_000;
+// An archive is done when the sandbox is ARCHIVED; it is still under way while
+// the record holds one of these.
+const ARCHIVING_STATUSES = new Set(["ARCHIVING"]);
+// A restore is done when the sandbox is DEPLOYED again; the instance is recreated
+// before the archived filesystem is written back over its image.
+const UNARCHIVING_STATUSES = new Set(["UNARCHIVING", "DEPLOYING", "BUILDING", "UPLOADING"]);
+// The status the sandbox holds before the operation moves it, tolerated only
+// while the operation is starting: an archive that fails hands the sandbox back
+// as DEPLOYED and a restore that fails leaves it ARCHIVED, so reading the entry
+// status once the operation has begun means it is over, not still running.
+const ARCHIVE_ENTRY_STATUS = "DEPLOYED";
+const UNARCHIVE_ENTRY_STATUS = "ARCHIVED";
+const ARCHIVE_ENTRY_MAX_WAIT_MS = 30_000;
 // A create that outlives the edge's 60s origin-read timeout gets a 504 from
 // CloudFront while the control plane keeps deploying the sandbox for up to
 // 300s (ENG-3662 timeout ladder inversion). The 504 body is edge HTML with no
@@ -206,6 +223,24 @@ class SandboxInstance {
             throwOnError: true,
         });
     }
+    /**
+     * Restore this sandbox to one of its own snapshots. The sandbox keeps its
+     * name, its URLs and its previews: the running instance is torn down and
+     * rebuilt from the snapshot, so everything written since it was taken is
+     * lost unless it was snapshotted too.
+     *
+     * The restore is asked for without waiting on the guest, the same way a fork
+     * is: connections to a sandbox still resuming are retried by the gateway.
+     *
+     * @param snapshotId - ID of the snapshot to restore this sandbox to.
+     */
+    async restore(snapshotId) {
+        const { data } = await (0, index_js_1.restoreSandboxSnapshot)({
+            path: { sandboxName: this.metadata.name, snapshotId },
+            throwOnError: true,
+        });
+        return data;
+    }
     /**
      * Fork this sandbox into a new sandbox or application.
      *
@@ -354,6 +389,95 @@ class SandboxInstance {
         }
         return instance;
     }
+    /**
+     * Archive a sandbox: keep its filesystem, stop the sandbox.
+     *
+     * The filesystem changes made over the image are exported to the archive store
+     * and the sandbox is shut down; memory and running processes are lost, and the
+     * saved processes start again from their configuration when the sandbox is
+     * unarchived. The export runs in the background: this waits until the sandbox
+     * is ARCHIVED, pass `{ wait: false }` to return as soon as it is launched.
+     */
+    static async archive(sandboxName, options = {}) {
+        const { data } = await (0, index_js_1.archiveSandbox)({
+            path: { sandboxName },
+            throwOnError: true,
+        });
+        return SandboxInstance.waitForArchiveStatus(sandboxName, data, "ARCHIVED", ARCHIVING_STATUSES, ARCHIVE_ENTRY_STATUS, "archive", options);
+    }
+    /**
+     * Archive this sandbox: keep its filesystem, stop the sandbox.
+     *
+     * @see SandboxInstance.archive
+     */
+    async archive(options = {}) {
+        const instance = await SandboxInstance.archive(this.metadata.name, options);
+        this.refreshFrom(instance);
+        return this;
+    }
+    /**
+     * Recreate an archived sandbox from its archive.
+     *
+     * The sandbox is started again from its image, and the archived filesystem is
+     * written back over it. The sandbox answers, and its terminal is reachable, while the archived
+     * filesystem is written back over its image. This waits until the restore is
+     * done and the saved processes are running again; pass `{ wait: false }` to
+     * return while the sandbox is still UNARCHIVING.
+     */
+    static async unarchive(sandboxName, options = {}) {
+        const { data } = await (0, index_js_1.unarchiveSandbox)({
+            path: { sandboxName },
+            throwOnError: true,
+        });
+        return SandboxInstance.waitForArchiveStatus(sandboxName, data, "DEPLOYED", UNARCHIVING_STATUSES, UNARCHIVE_ENTRY_STATUS, "unarchive", options);
+    }
+    /**
+     * Recreate this sandbox from its archive.
+     *
+     * @see SandboxInstance.unarchive
+     */
+    async unarchive(options = {}) {
+        const instance = await SandboxInstance.unarchive(this.metadata.name, options);
+        this.refreshFrom(instance);
+        return this;
+    }
+    // The subsystems (fs, process, previews, ...) hold the configuration object
+    // this instance was built with, so a refresh writes into it rather than
+    // replacing it. Anything the read did not carry, the forced URL of a session
+    // above all, is kept.
+    refreshFrom(instance) {
+        Object.assign(this.sandbox, instance.sandbox);
+    }
+    static async waitForArchiveStatus(sandboxName, launched, target, pending, entry, action, { wait = true, maxWait = ARCHIVE_MAX_WAIT_MS, interval = ARCHIVE_WAIT_POLL_MS }) {
+        if (!wait || launched.status === target) {
+            return SandboxInstance.attachH2Session(new SandboxInstance(launched));
+        }
+        const deadline = Date.now() + maxWait;
+        // The status the sandbox is given back at is tolerated while the operation
+        // turns into a status change, but never past the wait the caller asked for.
+        const entryDeadline = Date.now() + Math.min(ARCHIVE_ENTRY_MAX_WAIT_MS, maxWait);
+        let started = false;
+        for (;;) {
+            await new Promise((resolve) => setTimeout(resolve, interval));
+            const instance = await SandboxInstance.get(sandboxName);
+            const status = instance.status;
+            if (status === target) {
+                return instance;
+            }
+            if (pending.has(status ?? "")) {
+                started = true;
+            }
+            else if (status === entry && !started && Date.now() < entryDeadline) {
+                continue;
+            }
+            if (!pending.has(status ?? "")) {
+                throw new Error(`Sandbox ${sandboxName} is ${status} while it should ${action}`);
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`Sandbox ${sandboxName} is still ${status} after waiting ${Math.round(maxWait / 1000)}s for it to ${action}`);
+            }
+        }
+    }
     static async get(sandboxName) {
         const { data } = await (0, index_js_1.getSandbox)({
             path: {

package/dist/cjs/types/client/sdk.gen.d.ts

@@ -1,5 +1,5 @@
 import type { Options as ClientOptions, TDataShape, Client } from '@hey-api/client-fetch';
-import type { ListAgentsData, CreateAgentData, DeleteAgentData, GetAgentData, UpdateAgentData, ListAgentRevisionsData, ListApplicationsData, CreateApplicationData, DeleteApplicationData, GetApplicationData, UpdateApplicationData, CreateApplicationCustomDomainData, ListApplicationRevisionsData, GetChangelogData, GetConfigurationData, ListCustomDomainsData, CreateCustomDomainData, DeleteCustomDomainData, GetCustomDomainData, UpdateCustomDomainData, ListCustomDomainSharesData, ShareCustomDomainData, UnshareCustomDomainData, VerifyCustomDomainData, ListDrivesData, CreateDriveData, DeleteDriveData, GetDriveData, UpdateDriveData, CreateDriveAccessTokenData, GetDriveByExternalIdData, GetDriveJwksData, ListAllEgressGatewaysData, GetEgressGatewayUsageData, ListAllEgressIpsData, GetWorkspaceFeaturesData, TestFeatureFlagData, ListFunctionsData, CreateFunctionData, DeleteFunctionData, GetFunctionData, UpdateFunctionData, ListFunctionRevisionsData, CleanupImagesData, ListImagesData, CreateImageData, DeleteImageData, GetImageData, ListImageSharesData, ShareImageData, ShareImageResponse, UnshareImageData, DeleteImageTagData, GetIntegrationData, ListIntegrationConnectionsData, CreateIntegrationConnectionData, DeleteIntegrationConnectionData, GetIntegrationConnectionData, UpdateIntegrationConnectionData, GetIntegrationConnectionModelEndpointConfigurationsData, ListIntegrationConnectionModelsData, GetIntegrationConnectionModelData, ListJobsData, CreateJobData, DeleteJobData, GetJobData, UpdateJobData, ListJobExecutionsData, CreateJobExecutionData, DeleteJobExecutionData, GetJobExecutionData, ListJobExecutionTasksData, ListJobRevisionsData, ListLocationsData, ListMcpHubDefinitionsData, ListModelsData, CreateModelData, DeleteModelData, GetModelData, UpdateModelData, ListModelRevisionsData, ListPendingImageSharesData, AcceptImageShareData, DeclineImageShareData, ListPoliciesData, CreatePolicyData, DeletePolicyData, GetPolicyData, UpdatePolicyData, GetPolicyUsagesData, ListPublicIpsData, ListSandboxHubDefinitionsData, ListSandboxesData, CreateSandboxData, DeleteSandboxData, GetSandboxData, UpdateSandboxData, ForkSandboxData, ListSandboxPreviewsData, CreateSandboxPreviewData, DeleteSandboxPreviewData, GetSandboxPreviewData, UpdateSandboxPreviewData, ListSandboxPreviewTokensData, CreateSandboxPreviewTokenData, DeleteSandboxPreviewTokenData, ListSandboxScheduleExecutionsData, ListSandboxSchedulesData, CreateSandboxScheduleData, DeleteSandboxScheduleData, GetSandboxScheduleData, UpdateSandboxScheduleData, ListSandboxSnapshotsData, CreateSandboxSnapshotData, DeleteSandboxSnapshotData, GetSandboxByExternalIdData, GetWorkspaceServiceAccountsData, CreateWorkspaceServiceAccountData, DeleteWorkspaceServiceAccountData, UpdateWorkspaceServiceAccountData, ListApiKeysForServiceAccountData, CreateApiKeyForServiceAccountData, DeleteApiKeyForServiceAccountData, ListTemplatesData, GetTemplateData, ListWorkspaceUsersData, InviteWorkspaceUserData, RemoveWorkspaceUserData, UpdateWorkspaceUserRoleData, ListVolumeTemplatesData, CreateVolumeTemplateData, DeleteVolumeTemplateData, GetVolumeTemplateData, UpdateVolumeTemplateData, DeleteVolumeTemplateVersionData, ListVolumesData, CreateVolumeData, DeleteVolumeData, GetVolumeData, UpdateVolumeData, GetVolumeByExternalIdData, ListVpcsData, CreateVpcData, DeleteVpcData, GetVpcData, ListEgressGatewaysData, CreateEgressGatewayData, DeleteEgressGatewayData, GetEgressGatewayData, ListEgressIpsData, CreateEgressIpData, DeleteEgressIpData, GetEgressIpData, ListWorkspacesData, CreateWorkspaceData, DeleteWorkspaceData, GetWorkspaceData, UpdateWorkspaceData, LeaveWorkspaceData, CheckWorkspaceAvailabilityData } from './types.gen.js';
+import type { ListAgentsData, CreateAgentData, DeleteAgentData, GetAgentData, UpdateAgentData, ListAgentRevisionsData, ListApplicationsData, CreateApplicationData, DeleteApplicationData, GetApplicationData, UpdateApplicationData, CreateApplicationCustomDomainData, ListApplicationRevisionsData, GetChangelogData, GetConfigurationData, ListCustomDomainsData, CreateCustomDomainData, DeleteCustomDomainData, GetCustomDomainData, UpdateCustomDomainData, ListCustomDomainSharesData, ShareCustomDomainData, UnshareCustomDomainData, VerifyCustomDomainData, ListDrivesData, CreateDriveData, DeleteDriveData, GetDriveData, UpdateDriveData, CreateDriveAccessTokenData, GetDriveByExternalIdData, GetDriveJwksData, ListAllEgressGatewaysData, GetEgressGatewayUsageData, ListAllEgressIpsData, GetWorkspaceFeaturesData, TestFeatureFlagData, ListFunctionsData, CreateFunctionData, DeleteFunctionData, GetFunctionData, UpdateFunctionData, ListFunctionRevisionsData, CleanupImagesData, ListImagesData, CreateImageData, DeleteImageData, GetImageData, ListImageSharesData, ShareImageData, ShareImageResponse, UnshareImageData, DeleteImageTagData, GetIntegrationData, ListIntegrationConnectionsData, CreateIntegrationConnectionData, DeleteIntegrationConnectionData, GetIntegrationConnectionData, UpdateIntegrationConnectionData, GetIntegrationConnectionModelEndpointConfigurationsData, ListIntegrationConnectionModelsData, GetIntegrationConnectionModelData, ListJobsData, CreateJobData, DeleteJobData, GetJobData, UpdateJobData, ListJobExecutionsData, CreateJobExecutionData, DeleteJobExecutionData, GetJobExecutionData, ListJobExecutionTasksData, ListJobRevisionsData, ListLocationsData, ListMcpHubDefinitionsData, ListModelsData, CreateModelData, DeleteModelData, GetModelData, UpdateModelData, ListModelRevisionsData, ListPendingImageSharesData, AcceptImageShareData, DeclineImageShareData, ListPoliciesData, CreatePolicyData, DeletePolicyData, GetPolicyData, UpdatePolicyData, GetPolicyUsagesData, ListPublicIpsData, ListSandboxHubDefinitionsData, ListSandboxesData, CreateSandboxData, DeleteSandboxData, GetSandboxData, UpdateSandboxData, ArchiveSandboxData, ForkSandboxData, ListSandboxPreviewsData, CreateSandboxPreviewData, DeleteSandboxPreviewData, GetSandboxPreviewData, UpdateSandboxPreviewData, ListSandboxPreviewTokensData, CreateSandboxPreviewTokenData, DeleteSandboxPreviewTokenData, ListSandboxScheduleExecutionsData, ListSandboxSchedulesData, CreateSandboxScheduleData, DeleteSandboxScheduleData, GetSandboxScheduleData, UpdateSandboxScheduleData, ListSandboxSnapshotsData, CreateSandboxSnapshotData, DeleteSandboxSnapshotData, RestoreSandboxSnapshotData, UnarchiveSandboxData, GetSandboxByExternalIdData, ListScheduleExecutionsData, ListSchedulesData, GetSandboxScheduleMetricsData, GetWorkspaceServiceAccountsData, CreateWorkspaceServiceAccountData, DeleteWorkspaceServiceAccountData, UpdateWorkspaceServiceAccountData, ListApiKeysForServiceAccountData, CreateApiKeyForServiceAccountData, DeleteApiKeyForServiceAccountData, ListTemplatesData, GetTemplateData, ListWorkspaceUsersData, InviteWorkspaceUserData, RemoveWorkspaceUserData, UpdateWorkspaceUserRoleData, ListVolumeTemplatesData, CreateVolumeTemplateData, DeleteVolumeTemplateData, GetVolumeTemplateData, UpdateVolumeTemplateData, DeleteVolumeTemplateVersionData, ListVolumesData, CreateVolumeData, DeleteVolumeData, GetVolumeData, UpdateVolumeData, GetVolumeByExternalIdData, ListVpcsData, CreateVpcData, DeleteVpcData, GetVpcData, ListEgressGatewaysData, CreateEgressGatewayData, DeleteEgressGatewayData, GetEgressGatewayData, ListEgressIpsData, CreateEgressIpData, DeleteEgressIpData, GetEgressIpData, ListWorkspacesData, CreateWorkspaceData, DeleteWorkspaceData, GetWorkspaceData, UpdateWorkspaceData, LeaveWorkspaceData, CheckWorkspaceAvailabilityData } from './types.gen.js';
 export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean> = ClientOptions<TData, ThrowOnError> & {
     /**
      * You can provide a client instance returned by `createClient()` instead of
@@ -516,6 +516,11 @@ export declare const getSandbox: <ThrowOnError extends boolean = false>(options:
  * Updates a sandbox's configuration. Note that certain changes (like image or memory) may reset the sandbox state. Use lifecycle policies to control automatic cleanup.
  */
 export declare const updateSandbox: <ThrowOnError extends boolean = false>(options: Options<UpdateSandboxData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen.js").Sandbox, import("./types.gen.js")._Error, ThrowOnError>;
+/**
+ * Archive sandbox
+ * Archives a sandbox. The changes its filesystem accumulated over its image are exported to the archive store, then the sandbox is shut down while its definition is kept, so it can be recreated later with the same disk. Memory and running processes are not preserved, processes are started again from their configuration when the sandbox is unarchived.
+ */
+export declare const archiveSandbox: <ThrowOnError extends boolean = false>(options: Options<ArchiveSandboxData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen.js").Sandbox, import("./types.gen.js")._Error, ThrowOnError>;
 /**
  * Fork sandbox
  * Forks a sandbox into a new sandbox or application. When forking to a sandbox, the target must not already exist (409 if it does). When forking to an application, a new revision is added if the app already exists, or a new application is created. This is a WIP endpoint — the full implementation depends on the execution plane.
@@ -608,11 +613,36 @@ export declare const createSandboxSnapshot: <ThrowOnError extends boolean = fals
  * Deletes a snapshot of a sandbox by its ID.
  */
 export declare const deleteSandboxSnapshot: <ThrowOnError extends boolean = false>(options: Options<DeleteSandboxSnapshotData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<void, import("./types.gen.js")._Error, ThrowOnError>;
+/**
+ * Restore sandbox from snapshot
+ * Restores a sandbox to one of its own snapshots. The running sandbox is torn down and rebuilt from the snapshot under the same name and URLs, so everything it held since the snapshot was taken is lost unless it was itself snapshotted.
+ */
+export declare const restoreSandboxSnapshot: <ThrowOnError extends boolean = false>(options: Options<RestoreSandboxSnapshotData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen.js").SandboxRestoreResponse, import("./types.gen.js")._Error, ThrowOnError>;
+/**
+ * Unarchive sandbox
+ * Recreates an archived sandbox from its archive. The recreated sandbox runs the current generation whatever generation it was archived from, restores the archived filesystem before anything starts, and starts the saved processes again with new process identifiers.
+ */
+export declare const unarchiveSandbox: <ThrowOnError extends boolean = false>(options: Options<UnarchiveSandboxData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen.js").Sandbox, import("./types.gen.js")._Error, ThrowOnError>;
 /**
  * Get sandbox by external ID
  * Returns the most recent non-terminated sandbox matching the given external ID. If no active sandbox is found, returns 404.
  */
 export declare const getSandboxByExternalId: <ThrowOnError extends boolean = false>(options: Options<GetSandboxByExternalIdData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen.js").Sandbox, import("./types.gen.js")._Error, ThrowOnError>;
+/**
+ * List Workspace Schedule Executions
+ * Returns schedule execution submissions across the workspace, newest first by default. Status describes submission acceptance, not process completion. since and until are inclusive RFC 3339 bounds on creation time.
+ */
+export declare const listScheduleExecutions: <ThrowOnError extends boolean = false>(options?: Options<ListScheduleExecutionsData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen.js").SandboxScheduleExecutionList, unknown, ThrowOnError>;
+/**
+ * List Workspace Schedules
+ * Returns schedule definitions across the workspace, newest first by default.
+ */
+export declare const listSchedules: <ThrowOnError extends boolean = false>(options?: Options<ListSchedulesData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen.js").SandboxScheduleEntryList, unknown, ThrowOnError>;
+/**
+ * Get Sandbox Scheduling Metrics
+ * Returns active sandbox and scheduling metrics for a UTC minute window. since is inclusive and until is exclusive. The default window is the last 24 hours and the maximum is 7 days. Execution status describes submission acceptance, not process completion. Execution totals begin accumulating when metrics collection is enabled and can lag recent firings briefly.
+ */
+export declare const getSandboxScheduleMetrics: <ThrowOnError extends boolean = false>(options?: Options<GetSandboxScheduleMetricsData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen.js").SandboxScheduleMetrics, unknown, ThrowOnError>;
 /**
  * List service accounts
  * Returns all service accounts in the workspace. Service accounts are machine identities for external systems to authenticate with Blaxel via OAuth or API keys.