@scaleway/sdk-instance 1.0.2

package/dist/v1/api.utils.cjs

@@ -0,0 +1,277 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const sdkClient = require("@scaleway/sdk-client");
+const api_gen = require("./api.gen.cjs");
+const content_gen = require("./content.gen.cjs");
+const validateNotUndefined = (obj) => {
+  if (obj === void 0) throw new TypeError(`object was found undefined`);
+  return obj;
+};
+class InstanceV1UtilsAPI extends api_gen.API {
+  /**
+   * Waits for {@link Image} to be in a final state.
+   *
+   * @param request - The request {@link GetImageRequest}
+   * @param options - The waiting options
+   * @returns A Promise of Image
+   */
+  waitForImage = (request, options) => sdkClient.tryAtIntervals(
+    async () => {
+      const value = await this.getImage(request).then(
+        (res) => res.image
+      );
+      return {
+        done: !content_gen.IMAGE_TRANSIENT_STATUSES.includes(value.state),
+        value
+      };
+    },
+    sdkClient.createExponentialBackoffStrategy(
+      options?.minDelay ?? 1,
+      options?.maxDelay ?? 30
+    ),
+    options?.timeout
+  );
+  /**
+   * Waits for {@link PrivateNIC} to be in a final state.
+   *
+   * @param request - The request {@link GetPrivateNICRequest}
+   * @param options - The waiting options
+   * @returns A Promise of PrivateNIC
+   */
+  waitForPrivateNIC = (request, options) => sdkClient.tryAtIntervals(
+    async () => {
+      const value = await this.getPrivateNIC(request).then(
+        (res) => res.privateNic
+      );
+      return {
+        done: !content_gen.PRIVATE_NIC_TRANSIENT_STATUSES.includes(value.state),
+        value
+      };
+    },
+    sdkClient.createExponentialBackoffStrategy(
+      options?.minDelay ?? 1,
+      options?.maxDelay ?? 30
+    ),
+    options?.timeout
+  );
+  /**
+   * Waits for {@link Server} to be in a final state.
+   *
+   * @param request - The request {@link GetServerRequest}
+   * @param options - The waiting options
+   * @returns A Promise of Server
+   */
+  waitForServer = (request, options) => sdkClient.tryAtIntervals(
+    async () => {
+      const value = await this.getServer(request).then(
+        (res) => res.server
+      );
+      return {
+        done: !content_gen.SERVER_TRANSIENT_STATUSES.includes(value.state),
+        value
+      };
+    },
+    sdkClient.createExponentialBackoffStrategy(
+      options?.minDelay ?? 1,
+      options?.maxDelay ?? 30
+    ),
+    options?.timeout
+  );
+  /**
+   * Waits for {@link Server} to be in a final state.
+   *
+   * @param request - The request {@link GetServerRequest}
+   * @param options - The waiting options
+   * @returns A Promise of Server
+   */
+  waitForSnapshot = (request, options) => sdkClient.tryAtIntervals(
+    async () => {
+      const value = await this.getSnapshot(request).then(
+        (res) => res.snapshot
+      );
+      return {
+        done: !content_gen.SNAPSHOT_TRANSIENT_STATUSES.includes(value.state),
+        value
+      };
+    },
+    sdkClient.createExponentialBackoffStrategy(
+      options?.minDelay ?? 1,
+      options?.maxDelay ?? 30
+    ),
+    options?.timeout
+  );
+  /**
+   * Waits for {@link Volume} to be in a final state.
+   *
+   * @param request - The request {@link GetVolumeRequest}
+   * @param options - The waiting options
+   * @returns A Promise of Volume
+   */
+  waitForVolume = (request, options) => sdkClient.tryAtIntervals(
+    async () => {
+      const value = await this.getVolume(request).then(
+        (res) => res.volume
+      );
+      return {
+        done: !content_gen.VOLUME_TRANSIENT_STATUSES.includes(value.state),
+        value
+      };
+    },
+    sdkClient.createExponentialBackoffStrategy(
+      options?.minDelay ?? 1,
+      options?.maxDelay ?? 30
+    ),
+    options?.timeout
+  );
+  /**
+   * Updates a server.
+   *
+   * @param request - The request {@link UpdateServerRequest}
+   * @returns A Promise of UpdateServerResponse
+   */
+  updateServer = (request) => this._updateServer(request);
+  /**
+   * Creates a server.
+   *
+   * @param request - The request {@link CreateServerRequest}
+   * @returns A Promise of CreateServerResponse
+   */
+  createServer = (request) => this._createServer(request);
+  /**
+   * Starts an action and wait for the server to be in the correct "terminal
+   * state" expected by this action.
+   *
+   * @param request - The request {@link ServerActionRequest}
+   * @returns A Promise of Server
+   */
+  serverActionAndWait = async (request, options) => {
+    const finalServer = await this.serverAction(request).then(
+      () => this.waitForServer(
+        {
+          serverId: request.serverId,
+          zone: request.zone
+        },
+        options
+      )
+    );
+    let expectedState;
+    switch (request.action) {
+      case "poweron":
+      case "reboot":
+        expectedState = "running";
+        break;
+      case "poweroff":
+        expectedState = "stopped";
+        break;
+      case "stop_in_place":
+        expectedState = "stopped in place";
+        break;
+    }
+    if (expectedState && finalServer.state !== expectedState) {
+      throw new Error(
+        `expected state ${expectedState} but found ${finalServer.state}: ${finalServer.stateDetail}`
+      );
+    }
+    return finalServer;
+  };
+  /**
+   * Attaches a volume to a server.
+   *
+   * @param request - The request {@link AttachVolumeRequest}
+   * @returns A Promise of AttachVolumeResponse
+   */
+  attachVolume = async (request) => {
+    const volumes = await this.getServer({
+      serverId: request.serverId,
+      zone: request.zone
+    }).then((res) => validateNotUndefined(res.server?.volumes));
+    const newVolumes = {};
+    for (const [key, server] of Object.entries(volumes)) {
+      newVolumes[key] = { id: server.id, name: server.name };
+    }
+    let found = false;
+    const volumesLength = Object.keys(volumes).length;
+    for (let index = 0; index <= volumesLength; index += 1) {
+      const key = index.toString();
+      if (!(key in newVolumes)) {
+        newVolumes[key] = {
+          id: request.volumeId,
+          name: request.volumeId
+          // name is ignored on this PATCH
+        };
+        found = true;
+        break;
+      }
+    }
+    if (!found) {
+      throw new Error(`could not find key to attach volume ${request.volumeId}`);
+    }
+    return this.updateServer({
+      serverId: request.serverId,
+      volumes: newVolumes,
+      zone: request.zone
+    }).then((obj) => obj);
+  };
+  /**
+   * Detaches a volume from a server.
+   *
+   * @param request - The request {@link DetachVolumeRequest}
+   * @returns A Promise of DetachVolumeResponse
+   */
+  detachVolume = async (request) => {
+    const server = await this.getVolume({
+      volumeId: request.volumeId,
+      zone: request.zone
+    }).then((res) => validateNotUndefined(res.volume?.server?.id)).then(
+      (serverId) => this.getServer({
+        serverId,
+        zone: request.zone
+      })
+    ).then((res) => validateNotUndefined(res.server));
+    const newVolumes = {};
+    for (const [key, volume] of Object.entries(server.volumes)) {
+      if (volume.id !== request.volumeId) {
+        newVolumes[key] = { id: volume.id, name: volume.name };
+      }
+    }
+    return this.updateServer({
+      serverId: server.id,
+      volumes: newVolumes,
+      zone: request.zone
+    }).then((obj) => obj);
+  };
+  /**
+   * Get the content of a user data on a server for the given key.
+   *
+   * @param request - The request {@link GetServerUserDataRequest}
+   * @returns The content of the key
+   */
+  getServerUserData = (request) => this.client.fetch({
+    method: "GET",
+    path: `/instance/v1/zones/${sdkClient.validatePathParam(
+      "zone",
+      request.zone ?? this.client.settings.defaultZone
+    )}/servers/${sdkClient.validatePathParam(
+      "serverId",
+      request.serverId
+    )}/user_data/${sdkClient.validatePathParam("key", request.key)}`
+  });
+  /**
+   * Sets the content of a user data on a server for the given key.
+   *
+   * @param request - The request {@link SetServerUserDataRequest}
+   */
+  setServerUserData = (request) => this.client.fetch({
+    body: request.content,
+    headers: { "Content-Type": "text/plain" },
+    method: "PATCH",
+    path: `/instance/v1/zones/${sdkClient.validatePathParam(
+      "zone",
+      request.zone ?? this.client.settings.defaultZone
+    )}/servers/${sdkClient.validatePathParam(
+      "serverId",
+      request.serverId
+    )}/user_data/${sdkClient.validatePathParam("key", request.key)}`
+  });
+}
+exports.InstanceV1UtilsAPI = InstanceV1UtilsAPI;

package/dist/v1/api.utils.d.ts

@@ -0,0 +1,95 @@
+import type { WaitForOptions } from '@scaleway/sdk-client';
+import { API } from './api.gen';
+import type { CreateServerRequest, GetImageRequest, GetPrivateNICRequest, GetServerRequest, GetSnapshotRequest, GetVolumeRequest, Image, PrivateNIC, Server, ServerActionRequest, Snapshot, UpdateServerRequest, Volume } from './types.gen';
+import type { AttachVolumeRequest, AttachVolumeResponse, DetachVolumeRequest, DetachVolumeResponse, GetServerUserDataRequest, SetServerUserDataRequest } from './types.utils';
+export declare class InstanceV1UtilsAPI extends API {
+    /**
+     * Waits for {@link Image} to be in a final state.
+     *
+     * @param request - The request {@link GetImageRequest}
+     * @param options - The waiting options
+     * @returns A Promise of Image
+     */
+    waitForImage: (request: Readonly<GetImageRequest>, options?: Readonly<WaitForOptions<Image>>) => Promise<Image>;
+    /**
+     * Waits for {@link PrivateNIC} to be in a final state.
+     *
+     * @param request - The request {@link GetPrivateNICRequest}
+     * @param options - The waiting options
+     * @returns A Promise of PrivateNIC
+     */
+    waitForPrivateNIC: (request: Readonly<GetPrivateNICRequest>, options?: Readonly<WaitForOptions<PrivateNIC>>) => Promise<PrivateNIC>;
+    /**
+     * Waits for {@link Server} to be in a final state.
+     *
+     * @param request - The request {@link GetServerRequest}
+     * @param options - The waiting options
+     * @returns A Promise of Server
+     */
+    waitForServer: (request: Readonly<GetServerRequest>, options?: Readonly<WaitForOptions<Server>>) => Promise<Server>;
+    /**
+     * Waits for {@link Server} to be in a final state.
+     *
+     * @param request - The request {@link GetServerRequest}
+     * @param options - The waiting options
+     * @returns A Promise of Server
+     */
+    waitForSnapshot: (request: Readonly<GetSnapshotRequest>, options?: Readonly<WaitForOptions<Snapshot>>) => Promise<Snapshot>;
+    /**
+     * Waits for {@link Volume} to be in a final state.
+     *
+     * @param request - The request {@link GetVolumeRequest}
+     * @param options - The waiting options
+     * @returns A Promise of Volume
+     */
+    waitForVolume: (request: Readonly<GetVolumeRequest>, options?: Readonly<WaitForOptions<Volume>>) => Promise<Volume>;
+    /**
+     * Updates a server.
+     *
+     * @param request - The request {@link UpdateServerRequest}
+     * @returns A Promise of UpdateServerResponse
+     */
+    updateServer: (request: UpdateServerRequest) => Promise<import("./types.gen").UpdateServerResponse>;
+    /**
+     * Creates a server.
+     *
+     * @param request - The request {@link CreateServerRequest}
+     * @returns A Promise of CreateServerResponse
+     */
+    createServer: (request: Readonly<CreateServerRequest>) => Promise<import("./types.gen").CreateServerResponse>;
+    /**
+     * Starts an action and wait for the server to be in the correct "terminal
+     * state" expected by this action.
+     *
+     * @param request - The request {@link ServerActionRequest}
+     * @returns A Promise of Server
+     */
+    serverActionAndWait: (request: ServerActionRequest, options?: Readonly<WaitForOptions<Server>>) => Promise<Server>;
+    /**
+     * Attaches a volume to a server.
+     *
+     * @param request - The request {@link AttachVolumeRequest}
+     * @returns A Promise of AttachVolumeResponse
+     */
+    attachVolume: (request: Readonly<AttachVolumeRequest>) => Promise<AttachVolumeResponse>;
+    /**
+     * Detaches a volume from a server.
+     *
+     * @param request - The request {@link DetachVolumeRequest}
+     * @returns A Promise of DetachVolumeResponse
+     */
+    detachVolume: (request: DetachVolumeRequest) => Promise<DetachVolumeResponse>;
+    /**
+     * Get the content of a user data on a server for the given key.
+     *
+     * @param request - The request {@link GetServerUserDataRequest}
+     * @returns The content of the key
+     */
+    getServerUserData: (request: Readonly<GetServerUserDataRequest>) => Promise<string>;
+    /**
+     * Sets the content of a user data on a server for the given key.
+     *
+     * @param request - The request {@link SetServerUserDataRequest}
+     */
+    setServerUserData: (request: Readonly<SetServerUserDataRequest>) => Promise<void>;
+}

package/dist/v1/api.utils.js

@@ -0,0 +1,277 @@
+import { tryAtIntervals, createExponentialBackoffStrategy, validatePathParam } from "@scaleway/sdk-client";
+import { API } from "./api.gen.js";
+import { IMAGE_TRANSIENT_STATUSES, PRIVATE_NIC_TRANSIENT_STATUSES, SERVER_TRANSIENT_STATUSES, SNAPSHOT_TRANSIENT_STATUSES, VOLUME_TRANSIENT_STATUSES } from "./content.gen.js";
+const validateNotUndefined = (obj) => {
+  if (obj === void 0) throw new TypeError(`object was found undefined`);
+  return obj;
+};
+class InstanceV1UtilsAPI extends API {
+  /**
+   * Waits for {@link Image} to be in a final state.
+   *
+   * @param request - The request {@link GetImageRequest}
+   * @param options - The waiting options
+   * @returns A Promise of Image
+   */
+  waitForImage = (request, options) => tryAtIntervals(
+    async () => {
+      const value = await this.getImage(request).then(
+        (res) => res.image
+      );
+      return {
+        done: !IMAGE_TRANSIENT_STATUSES.includes(value.state),
+        value
+      };
+    },
+    createExponentialBackoffStrategy(
+      options?.minDelay ?? 1,
+      options?.maxDelay ?? 30
+    ),
+    options?.timeout
+  );
+  /**
+   * Waits for {@link PrivateNIC} to be in a final state.
+   *
+   * @param request - The request {@link GetPrivateNICRequest}
+   * @param options - The waiting options
+   * @returns A Promise of PrivateNIC
+   */
+  waitForPrivateNIC = (request, options) => tryAtIntervals(
+    async () => {
+      const value = await this.getPrivateNIC(request).then(
+        (res) => res.privateNic
+      );
+      return {
+        done: !PRIVATE_NIC_TRANSIENT_STATUSES.includes(value.state),
+        value
+      };
+    },
+    createExponentialBackoffStrategy(
+      options?.minDelay ?? 1,
+      options?.maxDelay ?? 30
+    ),
+    options?.timeout
+  );
+  /**
+   * Waits for {@link Server} to be in a final state.
+   *
+   * @param request - The request {@link GetServerRequest}
+   * @param options - The waiting options
+   * @returns A Promise of Server
+   */
+  waitForServer = (request, options) => tryAtIntervals(
+    async () => {
+      const value = await this.getServer(request).then(
+        (res) => res.server
+      );
+      return {
+        done: !SERVER_TRANSIENT_STATUSES.includes(value.state),
+        value
+      };
+    },
+    createExponentialBackoffStrategy(
+      options?.minDelay ?? 1,
+      options?.maxDelay ?? 30
+    ),
+    options?.timeout
+  );
+  /**
+   * Waits for {@link Server} to be in a final state.
+   *
+   * @param request - The request {@link GetServerRequest}
+   * @param options - The waiting options
+   * @returns A Promise of Server
+   */
+  waitForSnapshot = (request, options) => tryAtIntervals(
+    async () => {
+      const value = await this.getSnapshot(request).then(
+        (res) => res.snapshot
+      );
+      return {
+        done: !SNAPSHOT_TRANSIENT_STATUSES.includes(value.state),
+        value
+      };
+    },
+    createExponentialBackoffStrategy(
+      options?.minDelay ?? 1,
+      options?.maxDelay ?? 30
+    ),
+    options?.timeout
+  );
+  /**
+   * Waits for {@link Volume} to be in a final state.
+   *
+   * @param request - The request {@link GetVolumeRequest}
+   * @param options - The waiting options
+   * @returns A Promise of Volume
+   */
+  waitForVolume = (request, options) => tryAtIntervals(
+    async () => {
+      const value = await this.getVolume(request).then(
+        (res) => res.volume
+      );
+      return {
+        done: !VOLUME_TRANSIENT_STATUSES.includes(value.state),
+        value
+      };
+    },
+    createExponentialBackoffStrategy(
+      options?.minDelay ?? 1,
+      options?.maxDelay ?? 30
+    ),
+    options?.timeout
+  );
+  /**
+   * Updates a server.
+   *
+   * @param request - The request {@link UpdateServerRequest}
+   * @returns A Promise of UpdateServerResponse
+   */
+  updateServer = (request) => this._updateServer(request);
+  /**
+   * Creates a server.
+   *
+   * @param request - The request {@link CreateServerRequest}
+   * @returns A Promise of CreateServerResponse
+   */
+  createServer = (request) => this._createServer(request);
+  /**
+   * Starts an action and wait for the server to be in the correct "terminal
+   * state" expected by this action.
+   *
+   * @param request - The request {@link ServerActionRequest}
+   * @returns A Promise of Server
+   */
+  serverActionAndWait = async (request, options) => {
+    const finalServer = await this.serverAction(request).then(
+      () => this.waitForServer(
+        {
+          serverId: request.serverId,
+          zone: request.zone
+        },
+        options
+      )
+    );
+    let expectedState;
+    switch (request.action) {
+      case "poweron":
+      case "reboot":
+        expectedState = "running";
+        break;
+      case "poweroff":
+        expectedState = "stopped";
+        break;
+      case "stop_in_place":
+        expectedState = "stopped in place";
+        break;
+    }
+    if (expectedState && finalServer.state !== expectedState) {
+      throw new Error(
+        `expected state ${expectedState} but found ${finalServer.state}: ${finalServer.stateDetail}`
+      );
+    }
+    return finalServer;
+  };
+  /**
+   * Attaches a volume to a server.
+   *
+   * @param request - The request {@link AttachVolumeRequest}
+   * @returns A Promise of AttachVolumeResponse
+   */
+  attachVolume = async (request) => {
+    const volumes = await this.getServer({
+      serverId: request.serverId,
+      zone: request.zone
+    }).then((res) => validateNotUndefined(res.server?.volumes));
+    const newVolumes = {};
+    for (const [key, server] of Object.entries(volumes)) {
+      newVolumes[key] = { id: server.id, name: server.name };
+    }
+    let found = false;
+    const volumesLength = Object.keys(volumes).length;
+    for (let index = 0; index <= volumesLength; index += 1) {
+      const key = index.toString();
+      if (!(key in newVolumes)) {
+        newVolumes[key] = {
+          id: request.volumeId,
+          name: request.volumeId
+          // name is ignored on this PATCH
+        };
+        found = true;
+        break;
+      }
+    }
+    if (!found) {
+      throw new Error(`could not find key to attach volume ${request.volumeId}`);
+    }
+    return this.updateServer({
+      serverId: request.serverId,
+      volumes: newVolumes,
+      zone: request.zone
+    }).then((obj) => obj);
+  };
+  /**
+   * Detaches a volume from a server.
+   *
+   * @param request - The request {@link DetachVolumeRequest}
+   * @returns A Promise of DetachVolumeResponse
+   */
+  detachVolume = async (request) => {
+    const server = await this.getVolume({
+      volumeId: request.volumeId,
+      zone: request.zone
+    }).then((res) => validateNotUndefined(res.volume?.server?.id)).then(
+      (serverId) => this.getServer({
+        serverId,
+        zone: request.zone
+      })
+    ).then((res) => validateNotUndefined(res.server));
+    const newVolumes = {};
+    for (const [key, volume] of Object.entries(server.volumes)) {
+      if (volume.id !== request.volumeId) {
+        newVolumes[key] = { id: volume.id, name: volume.name };
+      }
+    }
+    return this.updateServer({
+      serverId: server.id,
+      volumes: newVolumes,
+      zone: request.zone
+    }).then((obj) => obj);
+  };
+  /**
+   * Get the content of a user data on a server for the given key.
+   *
+   * @param request - The request {@link GetServerUserDataRequest}
+   * @returns The content of the key
+   */
+  getServerUserData = (request) => this.client.fetch({
+    method: "GET",
+    path: `/instance/v1/zones/${validatePathParam(
+      "zone",
+      request.zone ?? this.client.settings.defaultZone
+    )}/servers/${validatePathParam(
+      "serverId",
+      request.serverId
+    )}/user_data/${validatePathParam("key", request.key)}`
+  });
+  /**
+   * Sets the content of a user data on a server for the given key.
+   *
+   * @param request - The request {@link SetServerUserDataRequest}
+   */
+  setServerUserData = (request) => this.client.fetch({
+    body: request.content,
+    headers: { "Content-Type": "text/plain" },
+    method: "PATCH",
+    path: `/instance/v1/zones/${validatePathParam(
+      "zone",
+      request.zone ?? this.client.settings.defaultZone
+    )}/servers/${validatePathParam(
+      "serverId",
+      request.serverId
+    )}/user_data/${validatePathParam("key", request.key)}`
+  });
+}
+export {
+  InstanceV1UtilsAPI
+};

package/dist/v1/content.gen.cjs

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const IMAGE_TRANSIENT_STATUSES = ["creating"];
+const IP_TRANSIENT_STATUSES = ["pending"];
+const PRIVATE_NIC_TRANSIENT_STATUSES = ["syncing"];
+const SECURITY_GROUP_TRANSIENT_STATUSES = [
+  "syncing"
+];
+const SERVER_IP_TRANSIENT_STATUSES = ["pending"];
+const SERVER_TRANSIENT_STATUSES = ["starting", "stopping"];
+const SNAPSHOT_TRANSIENT_STATUSES = [
+  "snapshotting",
+  "importing",
+  "exporting"
+];
+const TASK_TRANSIENT_STATUSES = [
+  "pending",
+  "started",
+  "retry"
+];
+const VOLUME_SERVER_TRANSIENT_STATUSES = [
+  "snapshotting",
+  "fetching",
+  "resizing",
+  "saving",
+  "hotsyncing"
+];
+const VOLUME_TRANSIENT_STATUSES = [
+  "snapshotting",
+  "fetching",
+  "resizing",
+  "saving",
+  "hotsyncing"
+];
+exports.IMAGE_TRANSIENT_STATUSES = IMAGE_TRANSIENT_STATUSES;
+exports.IP_TRANSIENT_STATUSES = IP_TRANSIENT_STATUSES;
+exports.PRIVATE_NIC_TRANSIENT_STATUSES = PRIVATE_NIC_TRANSIENT_STATUSES;
+exports.SECURITY_GROUP_TRANSIENT_STATUSES = SECURITY_GROUP_TRANSIENT_STATUSES;
+exports.SERVER_IP_TRANSIENT_STATUSES = SERVER_IP_TRANSIENT_STATUSES;
+exports.SERVER_TRANSIENT_STATUSES = SERVER_TRANSIENT_STATUSES;
+exports.SNAPSHOT_TRANSIENT_STATUSES = SNAPSHOT_TRANSIENT_STATUSES;
+exports.TASK_TRANSIENT_STATUSES = TASK_TRANSIENT_STATUSES;
+exports.VOLUME_SERVER_TRANSIENT_STATUSES = VOLUME_SERVER_TRANSIENT_STATUSES;
+exports.VOLUME_TRANSIENT_STATUSES = VOLUME_TRANSIENT_STATUSES;