@hanzo/runtime 0.0.0-dev

package/src/Snapshot.ts

@@ -0,0 +1,260 @@
+/*
+ * Copyright 2025 Daytona Platforms Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ObjectStorageApi, SnapshotDto, SnapshotsApi, SnapshotState, CreateSnapshot } from '@daytonaio/api-client'
+import { DaytonaError } from './errors/DaytonaError'
+import { ObjectStorage } from './ObjectStorage'
+import { Image } from './Image'
+import { Resources } from './Daytona'
+import { processStreamingResponse } from './utils/Stream'
+
+const SNAPSHOTS_FETCH_LIMIT = 200
+
+/**
+ * Represents a Daytona Snapshot which is a pre-configured sandbox.
+ *
+ * @property {string} id - Unique identifier for the Snapshot.
+ * @property {string} organizationId - Organization ID that owns the Snapshot.
+ * @property {boolean} general - Whether the Snapshot is general.
+ * @property {string} name - Name of the Snapshot.
+ * @property {string} imageName - Name of the Image of the Snapshot.
+ * @property {boolean} enabled - Whether the Snapshot is enabled.
+ * @property {SnapshotState} state - Current state of the Snapshot.
+ * @property {number} size - Size of the Snapshot.
+ * @property {string[]} entrypoint - Entrypoint of the Snapshot.
+ * @property {number} cpu - CPU of the Snapshot.
+ * @property {number} gpu - GPU of the Snapshot.
+ * @property {number} mem - Memory of the Snapshot in GiB.
+ * @property {number} disk - Disk of the Snapshot in GiB.
+ * @property {string} errorReason - Error reason of the Snapshot.
+ * @property {Date} createdAt - Timestamp when the Snapshot was created.
+ * @property {Date} updatedAt - Timestamp when the Snapshot was last updated.
+ * @property {Date} lastUsedAt - Timestamp when the Snapshot was last used.
+ */
+export type Snapshot = SnapshotDto & { __brand: 'Snapshot' }
+
+/**
+ * Parameters for creating a new snapshot.
+ *
+ * @property {string} name - Name of the snapshot.
+ * @property {string | Image} image - Image of the snapshot. If a string is provided, it should be available on some registry.
+ * If an Image instance is provided, it will be used to create a new image in Daytona.
+ * @property {Resources} resources - Resources of the snapshot.
+ * @property {string[]} entrypoint - Entrypoint of the snapshot.
+ */
+export type CreateSnapshotParams = {
+  name: string
+  image: string | Image
+  resources?: Resources
+  entrypoint?: string[]
+}
+
+/**
+ * Service for managing Daytona Snapshots. Can be used to list, get, create and delete Snapshots.
+ *
+ * @class
+ */
+export class SnapshotService {
+  constructor(
+    private snapshotsApi: SnapshotsApi,
+    private objectStorageApi: ObjectStorageApi,
+  ) {}
+
+  /**
+   * List all Snapshots.
+   *
+   * @returns {Promise<Snapshot[]>} List of all Snapshots accessible to the user
+   *
+   * @example
+   * const daytona = new Daytona();
+   * const snapshots = await daytona.snapshot.list();
+   * console.log(`Found ${snapshots.length} snapshots`);
+   * snapshots.forEach(snapshot => console.log(`${snapshot.name} (${snapshot.imageName})`));
+   */
+  async list(): Promise<Snapshot[]> {
+    let response = await this.snapshotsApi.getAllSnapshots(undefined, SNAPSHOTS_FETCH_LIMIT)
+    if (response.data.total > SNAPSHOTS_FETCH_LIMIT) {
+      response = await this.snapshotsApi.getAllSnapshots(undefined, response.data.total)
+    }
+    return response.data.items as Snapshot[]
+  }
+
+  /**
+   * Gets a Snapshot by its name.
+   *
+   * @param {string} name - Name of the Snapshot to retrieve
+   * @returns {Promise<Snapshot>} The requested Snapshot
+   * @throws {Error} If the Snapshot does not exist or cannot be accessed
+   *
+   * @example
+   * const daytona = new Daytona();
+   * const snapshot = await daytona.snapshot.get("snapshot-name");
+   * console.log(`Snapshot ${snapshot.name} is in state ${snapshot.state}`);
+   */
+  async get(name: string): Promise<Snapshot> {
+    const response = await this.snapshotsApi.getSnapshot(name)
+    return response.data as Snapshot
+  }
+
+  /**
+   * Deletes a Snapshot.
+   *
+   * @param {Snapshot} snapshot - Snapshot to delete
+   * @returns {Promise<void>}
+   * @throws {Error} If the Snapshot does not exist or cannot be deleted
+   *
+   * @example
+   * const daytona = new Daytona();
+   * const snapshot = await daytona.snapshot.get("snapshot-name");
+   * await daytona.snapshot.delete(snapshot);
+   * console.log("Snapshot deleted successfully");
+   */
+  async delete(snapshot: Snapshot): Promise<void> {
+    await this.snapshotsApi.removeSnapshot(snapshot.id)
+  }
+
+  /**
+   * Creates and registers a new snapshot from the given Image definition.
+   *
+   * @param {CreateSnapshotParams} params - Parameters for snapshot creation.
+   * @param {object} options - Options for the create operation.
+   * @param {boolean} options.onLogs - This callback function handles snapshot creation logs.
+   * @param {number} options.timeout - Default is no timeout. Timeout in seconds (0 means no timeout).
+   * @returns {Promise<void>}
+   *
+   * @example
+   * const image = Image.debianSlim('3.12').pipInstall('numpy');
+   * await daytona.snapshot.create({ name: 'my-snapshot', image: image }, { onLogs: console.log });
+   */
+  public async create(
+    params: CreateSnapshotParams,
+    options: { onLogs?: (chunk: string) => void; timeout?: number } = {},
+  ): Promise<Snapshot> {
+    const createSnapshotReq: CreateSnapshot = {
+      name: params.name,
+    }
+
+    if (typeof params.image === 'string') {
+      createSnapshotReq.imageName = params.image
+      createSnapshotReq.entrypoint = params.entrypoint
+    } else {
+      const contextHashes = await SnapshotService.processImageContext(this.objectStorageApi, params.image)
+      createSnapshotReq.buildInfo = {
+        contextHashes,
+        dockerfileContent: params.entrypoint
+          ? params.image.entrypoint(params.entrypoint).dockerfile
+          : params.image.dockerfile,
+      }
+    }
+
+    if (params.resources) {
+      createSnapshotReq.cpu = params.resources.cpu
+      createSnapshotReq.gpu = params.resources.gpu
+      createSnapshotReq.memory = params.resources.memory
+      createSnapshotReq.disk = params.resources.disk
+    }
+
+    let createdSnapshot = (
+      await this.snapshotsApi.createSnapshot(createSnapshotReq, undefined, {
+        timeout: (options.timeout || 0) * 1000,
+      })
+    ).data
+
+    if (!createdSnapshot) {
+      throw new DaytonaError("Failed to create snapshot. Didn't receive a snapshot from the server API.")
+    }
+
+    const terminalStates: SnapshotState[] = [SnapshotState.ACTIVE, SnapshotState.ERROR, SnapshotState.BUILD_FAILED]
+    const logTerminalStates: SnapshotState[] = [
+      ...terminalStates,
+      SnapshotState.PENDING_VALIDATION,
+      SnapshotState.VALIDATING,
+    ]
+    const snapshotRef = { createdSnapshot: createdSnapshot }
+    let streamPromise: Promise<void> | undefined
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    const startLogStreaming = async (onChunk: (chunk: string) => void = () => {}) => {
+      if (!streamPromise) {
+        streamPromise = processStreamingResponse(
+          () => this.snapshotsApi.getSnapshotBuildLogs(createdSnapshot.id, undefined, true, { responseType: 'stream' }),
+          (chunk) => onChunk(chunk.trimEnd()),
+          async () => logTerminalStates.includes(snapshotRef.createdSnapshot.state),
+        )
+      }
+    }
+
+    if (options.onLogs) {
+      options.onLogs(`Creating snapshot ${createdSnapshot.name} (${createdSnapshot.state})`)
+
+      if (createdSnapshot.state !== SnapshotState.BUILD_PENDING) {
+        await startLogStreaming(options.onLogs)
+      }
+    }
+
+    let previousState = createdSnapshot.state
+    while (!terminalStates.includes(createdSnapshot.state)) {
+      if (options.onLogs && previousState !== createdSnapshot.state) {
+        if (createdSnapshot.state !== SnapshotState.BUILD_PENDING && !streamPromise) {
+          await startLogStreaming(options.onLogs)
+        }
+        options.onLogs(`Creating snapshot ${createdSnapshot.name} (${createdSnapshot.state})`)
+        previousState = createdSnapshot.state
+      }
+      await new Promise((resolve) => setTimeout(resolve, 1000))
+      createdSnapshot = await this.get(createdSnapshot.name)
+      snapshotRef.createdSnapshot = createdSnapshot
+    }
+
+    if (options.onLogs) {
+      if (streamPromise) {
+        await streamPromise
+      }
+      if (createdSnapshot.state === SnapshotState.ACTIVE) {
+        options.onLogs(`Created snapshot ${createdSnapshot.name} (${createdSnapshot.state})`)
+      }
+    }
+
+    if (createdSnapshot.state === SnapshotState.ERROR || createdSnapshot.state === SnapshotState.BUILD_FAILED) {
+      const errMsg = `Failed to create snapshot. Name: ${createdSnapshot.name} Reason: ${createdSnapshot.errorReason}`
+      throw new DaytonaError(errMsg)
+    }
+
+    return createdSnapshot as Snapshot
+  }
+
+  /**
+   * Processes the image contexts by uploading them to object storage
+   *
+   * @private
+   * @param {Image} image - The Image instance.
+   * @returns {Promise<string[]>} The list of context hashes stored in object storage.
+   */
+  static async processImageContext(objectStorageApi: ObjectStorageApi, image: Image): Promise<string[]> {
+    if (!image.contextList || !image.contextList.length) {
+      return []
+    }
+
+    const pushAccessCreds = (await objectStorageApi.getPushAccess()).data
+    const objectStorage = new ObjectStorage({
+      endpointUrl: pushAccessCreds.storageUrl,
+      accessKeyId: pushAccessCreds.accessKey,
+      secretAccessKey: pushAccessCreds.secret,
+      sessionToken: pushAccessCreds.sessionToken,
+      bucketName: pushAccessCreds.bucket,
+    })
+
+    const contextHashes = []
+    for (const context of image.contextList) {
+      const contextHash = await objectStorage.upload(
+        context.sourcePath,
+        pushAccessCreds.organizationId,
+        context.archivePath,
+      )
+      contextHashes.push(contextHash)
+    }
+
+    return contextHashes
+  }
+}

package/src/Volume.ts

@@ -0,0 +1,110 @@
+/*
+ * Copyright 2025 Daytona Platforms Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { VolumeDto, VolumesApi } from '@daytonaio/api-client'
+import { DaytonaNotFoundError } from './errors/DaytonaError'
+
+/**
+ * Represents a Daytona Volume which is a shared storage volume for Sandboxes.
+ *
+ * @property {string} id - Unique identifier for the Volume
+ * @property {string} name - Name of the Volume
+ * @property {string} organizationId - Organization ID that owns the Volume
+ * @property {string} state - Current state of the Volume
+ * @property {string} createdAt - Date and time when the Volume was created
+ * @property {string} updatedAt - Date and time when the Volume was last updated
+ * @property {string} lastUsedAt - Date and time when the Volume was last used
+ */
+export type Volume = VolumeDto & { __brand: 'Volume' }
+
+/**
+ * Service for managing Daytona Volumes.
+ *
+ * This service provides methods to list, get, create, and delete Volumes.
+ *
+ * @class
+ */
+export class VolumeService {
+  constructor(private volumesApi: VolumesApi) {}
+
+  /**
+   * Lists all available Volumes.
+   *
+   * @returns {Promise<Volume[]>} List of all Volumes accessible to the user
+   *
+   * @example
+   * const daytona = new Daytona();
+   * const volumes = await daytona.volume.list();
+   * console.log(`Found ${volumes.length} volumes`);
+   * volumes.forEach(vol => console.log(`${vol.name} (${vol.id})`));
+   */
+  async list(): Promise<Volume[]> {
+    const response = await this.volumesApi.listVolumes()
+    return response.data as Volume[]
+  }
+
+  /**
+   * Gets a Volume by its name.
+   *
+   * @param {string} name - Name of the Volume to retrieve
+   * @param {boolean} create - Whether to create the Volume if it does not exist
+   * @returns {Promise<Volume>} The requested Volume
+   * @throws {Error} If the Volume does not exist or cannot be accessed
+   *
+   * @example
+   * const daytona = new Daytona();
+   * const volume = await daytona.volume.get("volume-name", true);
+   * console.log(`Volume ${volume.name} is in state ${volume.state}`);
+   */
+  async get(name: string, create = false): Promise<Volume> {
+    try {
+      const response = await this.volumesApi.getVolumeByName(name)
+      return response.data as Volume
+    } catch (error) {
+      if (
+        error instanceof DaytonaNotFoundError &&
+        create &&
+        error.message.match(/Volume with name ([\w-]+) not found/)
+      ) {
+        return await this.create(name)
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Creates a new Volume with the specified name.
+   *
+   * @param {string} name - Name for the new Volume
+   * @returns {Promise<Volume>} The newly created Volume
+   * @throws {Error} If the Volume cannot be created
+   *
+   * @example
+   * const daytona = new Daytona();
+   * const volume = await daytona.volume.create("my-data-volume");
+   * console.log(`Created volume ${volume.name} with ID ${volume.id}`);
+   */
+  async create(name: string): Promise<Volume> {
+    const response = await this.volumesApi.createVolume({ name })
+    return response.data as Volume
+  }
+
+  /**
+   * Deletes a Volume.
+   *
+   * @param {Volume} volume - Volume to delete
+   * @returns {Promise<void>}
+   * @throws {Error} If the Volume does not exist or cannot be deleted
+   *
+   * @example
+   * const daytona = new Daytona();
+   * const volume = await daytona.volume.get("volume-name");
+   * await daytona.volume.delete(volume);
+   * console.log("Volume deleted successfully");
+   */
+  async delete(volume: Volume): Promise<void> {
+    await this.volumesApi.deleteVolume(volume.id)
+  }
+}