@origincloud/compute 0.0.0-stage → 0.3.0

package/src/v1beta1/instance.ts

@@ -0,0 +1,541 @@
+// Code generated by the SDK's generator (generator/). DO NOT EDIT.
+// source: origincloud/compute/v1beta1/instance.proto
+
+import {
+  type CallOptions,
+  type Client,
+  type Empty,
+  type LongrunningOperation,
+  Operation,
+  type Service,
+  newRequestId,
+  pathValue,
+  query,
+} from "@origincloud/core";
+import type { OperationMetadata } from "../longrunning/v1beta1/operations.js";
+
+/**
+ * Calls InstanceService.
+ *
+ * Instances: virtual machines in one zone, booted from an image onto a
+ * durable boot volume, with network interfaces created beforehand with the
+ * network service.
+ */
+export class InstanceClient {
+  /**
+   * The endpoint the client sends its calls to, which also serves the
+   * operations its methods answer with.
+   */
+  readonly service: Service;
+
+  /** A client of InstanceService that sends its calls through `client`. */
+  constructor(client: Client) {
+    this.service = client.service("compute", true);
+  }
+
+  /**
+   * Returns an instance. A terminated instance can be read by name for a
+   * day after it was terminated.
+   */
+  async getInstance(request: GetInstanceRequest, options?: CallOptions): Promise<Instance> {
+    const p0 = pathValue("name", request.name, "projects/*/zones/*/instances/*");
+    return this.service.call<Instance>(
+      {
+        method: "GET",
+        path: `/v1beta1/${p0}`,
+        query: query(request, ["name"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Lists the instances in a zone, oldest first. A terminated instance is
+   * listed for two hours after it was terminated. For every zone's
+   * instances, list the zones whose `services` name `compute` with the
+   * location service (`location.origincloudapis.eu`), then each zone's
+   * instances.
+   */
+  async listInstances(request: ListInstancesRequest, options?: CallOptions): Promise<ListInstancesResponse> {
+    const p0 = pathValue("parent", request.parent, "projects/*/zones/*");
+    return this.service.call<ListInstancesResponse>(
+      {
+        method: "GET",
+        path: `/v1beta1/${p0}/instances`,
+        query: query(request, ["parent"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Iterates over everything listInstances lists from the request's page on,
+   * fetching the next page as the loop reaches it. A page that fails ends
+   * the iteration with its error.
+   */
+  async *allInstances(request: ListInstancesRequest, options?: CallOptions): AsyncGenerator<Instance, void, undefined> {
+    for (let page = request; ; ) {
+      const response = await this.listInstances(page, options);
+      yield* response.instances ?? [];
+      if (!response.nextPageToken) return;
+      page = { ...page, pageToken: response.nextPageToken };
+    }
+  }
+
+  /**
+   * Launches an instance. The operation is done once the instance is
+   * `RUNNING`, or failed once it is `FAILED`, with the reason in
+   * `stateReason`; a failed instance still exists, and can be started
+   * again or deleted.
+   *
+   * It answers with an operation to wait on, whose result is the Instance.
+   */
+  async createInstance(request: CreateInstanceRequest, options?: CallOptions): Promise<Operation<Instance, OperationMetadata>> {
+    if (!request.requestId) request = { ...request, requestId: newRequestId() };
+    const p0 = pathValue("parent", request.parent, "projects/*/zones/*");
+    const op = await this.service.call<LongrunningOperation>(
+      {
+        method: "POST",
+        path: `/v1beta1/${p0}/instances`,
+        body: request.instance,
+        query: query(request, ["parent", "instance"]),
+        idempotent: true,
+      },
+      options,
+    );
+    return new Operation<Instance, OperationMetadata>(this.service, op, "origincloud.compute.v1beta1.Instance");
+  }
+
+  /**
+   * Changes an instance's type or tags. A new `instanceType` needs the
+   * instance `STOPPED`, and is refused with `FAILED_PRECONDITION`
+   * otherwise; it takes effect at the next start. A larger type is checked
+   * against the same vCPU quota a launch is. The operation is done once the
+   * instance shows the change.
+   *
+   * It answers with an operation to wait on, whose result is the Instance.
+   */
+  async updateInstance(request: UpdateInstanceRequest, options?: CallOptions): Promise<Operation<Instance, OperationMetadata>> {
+    if (!request.requestId) request = { ...request, requestId: newRequestId() };
+    const p0 = pathValue("instance.name", request.instance?.name, "projects/*/zones/*/instances/*");
+    const op = await this.service.call<LongrunningOperation>(
+      {
+        method: "PATCH",
+        path: `/v1beta1/${p0}`,
+        body: request.instance,
+        query: query(request, ["instance.name", "instance"]),
+        idempotent: true,
+      },
+      options,
+    );
+    return new Operation<Instance, OperationMetadata>(this.service, op, "origincloud.compute.v1beta1.Instance");
+  }
+
+  /**
+   * Terminates an instance: its guest is stopped for good, its network
+   * interfaces are released, `AVAILABLE` again with their addresses (one
+   * created for it at launch is deleted), and
+   * its boot volume is deleted with it unless a snapshot of it exists.
+   * Other attached volumes are detached and kept.
+   * Terminating a terminated instance changes nothing. The operation is
+   * done once the instance is `TERMINATED`.
+   *
+   * It answers with an operation to wait on, which has no result.
+   */
+  async deleteInstance(request: DeleteInstanceRequest, options?: CallOptions): Promise<Operation<Empty, OperationMetadata>> {
+    if (!request.requestId) request = { ...request, requestId: newRequestId() };
+    const p0 = pathValue("name", request.name, "projects/*/zones/*/instances/*");
+    const op = await this.service.call<LongrunningOperation>(
+      {
+        method: "DELETE",
+        path: `/v1beta1/${p0}`,
+        query: query(request, ["name"]),
+        idempotent: true,
+      },
+      options,
+    );
+    return new Operation<Empty, OperationMetadata>(this.service, op, "google.protobuf.Empty");
+  }
+
+  /**
+   * Starts a `STOPPED` or `FAILED` instance. It keeps its name, its
+   * addresses and its volumes, and may come back on another machine.
+   * Starting a running instance changes nothing; it is refused while the
+   * instance is `INITIALIZING`, `STOPPING` or `SHUTTING_DOWN`. The
+   * operation is done once the instance is `RUNNING`, or failed once it is
+   * `FAILED`.
+   *
+   * It answers with an operation to wait on, whose result is the Instance.
+   */
+  async startInstance(request: StartInstanceRequest, options?: CallOptions): Promise<Operation<Instance, OperationMetadata>> {
+    if (!request.requestId) request = { ...request, requestId: newRequestId() };
+    const p0 = pathValue("name", request.name, "projects/*/zones/*/instances/*");
+    const op = await this.service.call<LongrunningOperation>(
+      {
+        method: "POST",
+        path: `/v1beta1/${p0}:start`,
+        body: request,
+        idempotent: true,
+      },
+      options,
+    );
+    return new Operation<Instance, OperationMetadata>(this.service, op, "origincloud.compute.v1beta1.Instance");
+  }
+
+  /**
+   * Stops a running instance: its guest is shut down, and it keeps its
+   * volumes and addresses. Stopping a stopped instance changes nothing. The
+   * operation is done once the instance is `STOPPED`, or failed once it is
+   * `FAILED`.
+   *
+   * It answers with an operation to wait on, whose result is the Instance.
+   */
+  async stopInstance(request: StopInstanceRequest, options?: CallOptions): Promise<Operation<Instance, OperationMetadata>> {
+    if (!request.requestId) request = { ...request, requestId: newRequestId() };
+    const p0 = pathValue("name", request.name, "projects/*/zones/*/instances/*");
+    const op = await this.service.call<LongrunningOperation>(
+      {
+        method: "POST",
+        path: `/v1beta1/${p0}:stop`,
+        body: request,
+        idempotent: true,
+      },
+      options,
+    );
+    return new Operation<Instance, OperationMetadata>(this.service, op, "origincloud.compute.v1beta1.Instance");
+  }
+}
+
+/** A virtual machine in one zone. */
+export interface Instance {
+  /** The instance's resource name. */
+  name?: string;
+  /**
+   * The instance's URN, the identifier access policies and the audit log
+   * use.
+   */
+  urn?: string;
+  /**
+   * The instance type, `instanceTypes/{instance_type}`, such as
+   * `instanceTypes/gp1.core.2`: one whose `available` is true. Changing it
+   * needs the instance `STOPPED`.
+   */
+  instanceType?: string;
+  /**
+   * The image the boot volume is created from, in the instance's zone: one
+   * of the project's own, `projects/{project}/zones/{zone}/images/{image}`,
+   * or a public one, `zones/{zone}/images/{image}`. Set exactly one of
+   * `image` and `imageFamily`; launched from a family, this is the public
+   * image the family resolved to.
+   */
+  image?: string;
+  /**
+   * The image family to launch the current public image of,
+   * `imageFamilies/{image_family}`. Set exactly one of `image` and
+   * `imageFamily`. Empty when the instance was launched from an image.
+   */
+  imageFamily?: string;
+  /**
+   * The key pair whose public key is installed for `loginUser`, in the
+   * instance's project.
+   */
+  keyPair?: string;
+  /**
+   * The account to log in as: a user created at first boot that holds the
+   * key pair. A POSIX user name of at most 32 lowercase letters, digits,
+   * underscores and hyphens, starting with a letter or an underscore, and
+   * not `root`. The image's `defaultUser` when left empty.
+   */
+  loginUser?: string;
+  /**
+   * The boot volume: its size and storage class at launch, and the volume.
+   * The image's size on the default storage class when left out.
+   */
+  bootVolume?: BootVolume;
+  /**
+   * The network interfaces, in device order, the boot interface first;
+   * exactly one today. Each is an existing interface in the instance's
+   * project and zone that nothing else holds, created with the network
+   * service: its subnet and security groups are the instance's.
+   * Terminating the instance releases it, and it stays. An instance
+   * launched before interfaces were named at launch shows the interface
+   * created for it, which is deleted with the instance.
+   */
+  networkInterfaces?: string[];
+  /** Where the instance is in its lifecycle. */
+  state?: Instance_State;
+  /**
+   * Why the instance is `FAILED`, or why a `STOPPED` instance went down
+   * when the machine it ran on failed; empty otherwise.
+   */
+  stateReason?: string;
+  /**
+   * Whether the platform can currently confirm the instance is working,
+   * which `state` doesn't say: a `RUNNING` instance on a machine that
+   * stopped answering is still `RUNNING`.
+   */
+  health?: InstanceHealth;
+  /** When the instance was launched. */
+  createTime?: string;
+  /**
+   * The principal that launched the instance, such as `user:<id>` or
+   * `service_account:<id>`.
+   */
+  creator?: string;
+  /**
+   * Labels of your own, at most 50. The `origin:name` tag is the name the
+   * console shows.
+   */
+  tags?: Record<string, string>;
+  /**
+   * Each network interface's private addresses, in the order of
+   * `networkInterfaces`; an interface not attached yet has none.
+   */
+  interfaceAddresses?: InterfaceAddresses[];
+}
+
+/** Where the instance is in its lifecycle. */
+export const Instance_State = {
+  /** Not set. */
+  STATE_UNSPECIFIED: "STATE_UNSPECIFIED",
+  /**
+   * Its boot volume and network interface are being created; it starts
+   * on its own once they are ready.
+   */
+  INITIALIZING: "INITIALIZING",
+  /** Being placed on a machine and booted. */
+  PENDING: "PENDING",
+  /** Running. */
+  RUNNING: "RUNNING",
+  /** Shutting down, to `STOPPED`. */
+  STOPPING: "STOPPING",
+  /**
+   * Stopped: it holds its volumes and addresses, and no compute capacity
+   * is charged.
+   */
+  STOPPED: "STOPPED",
+  /** Being terminated. */
+  SHUTTING_DOWN: "SHUTTING_DOWN",
+  /** Terminated. Readable by name for a day. */
+  TERMINATED: "TERMINATED",
+  /**
+   * A start, a stop or the launch failed; `stateReason` says why. Start
+   * it again, or delete it.
+   */
+  FAILED: "FAILED",
+} as const;
+
+/** Where the instance is in its lifecycle. */
+export type Instance_State = (typeof Instance_State)[keyof typeof Instance_State];
+
+/** An instance's boot volume. */
+export interface BootVolume {
+  /**
+   * The size in GiB the volume was created with, at least the image's
+   * size; the image's size when left at 0. Grow the volume itself to
+   * resize it; this keeps the size at launch.
+   */
+  sizeGib?: number;
+  /**
+   * The storage class, `storageClasses/{storage_class}` of the persistent
+   * volume service; the default class when left empty.
+   */
+  storageClass?: string;
+  /** The volume, in the instance's project and zone. */
+  volume?: string;
+}
+
+/** The private addresses of one of an instance's network interfaces. */
+export interface InterfaceAddresses {
+  /** The network interface. */
+  networkInterface?: string;
+  /** Its private IPv4 address. */
+  ipv4Address?: string;
+  /** Its IPv6 address. */
+  ipv6Address?: string;
+}
+
+/** An instance's health: each check, and their summary. */
+export interface InstanceHealth {
+  /**
+   * The summary of `checks`, for a listing that shows one value per
+   * instance. Only the checks say whether a problem is the platform's or
+   * the instance's own.
+   */
+  availability?: InstanceHealth_Availability;
+  /**
+   * Every check, always all of them: one with nothing to report is
+   * `NOT_APPLICABLE` or `INSUFFICIENT_DATA`, never left out.
+   */
+  checks?: HealthCheck[];
+}
+
+/** The summary of the checks. */
+export const InstanceHealth_Availability = {
+  /** Not set. */
+  AVAILABILITY_UNSPECIFIED: "AVAILABILITY_UNSPECIFIED",
+  /** Every check that applies passed. */
+  AVAILABLE: "AVAILABLE",
+  /** A check failed. */
+  IMPAIRED: "IMPAIRED",
+  /** A check that applies has no recent observation. */
+  UNKNOWN: "UNKNOWN",
+  /** No check applies, as for a stopped instance. */
+  NOT_APPLICABLE: "NOT_APPLICABLE",
+} as const;
+
+/** The summary of the checks. */
+export type InstanceHealth_Availability = (typeof InstanceHealth_Availability)[keyof typeof InstanceHealth_Availability];
+
+/** One health check of an instance. */
+export interface HealthCheck {
+  /** What the check observes. */
+  kind?: HealthCheck_Kind;
+  /** Whose the subject is, derived from `kind`. */
+  category?: HealthCheck_Category;
+  /** Its outcome. */
+  outcome?: HealthCheck_Outcome;
+  /** When the check came to `outcome`; empty while nothing has observed it. */
+  changeTime?: string;
+}
+
+/** What a check observes. */
+export const HealthCheck_Kind = {
+  /** Not set. */
+  KIND_UNSPECIFIED: "KIND_UNSPECIFIED",
+  /** The machine the instance runs on answers. */
+  HOST_REACHABLE: "HOST_REACHABLE",
+  /** The machine reports the virtual machine in the state it should be in. */
+  DOMAIN_STATE: "DOMAIN_STATE",
+  /** The instance answers on its network interface. */
+  NETWORK_REACHABLE: "NETWORK_REACHABLE",
+  /** The agent in the guest answers. */
+  GUEST_AGENT: "GUEST_AGENT",
+  /** The virtual machine exists on its machine. */
+  GUEST_PRESENT: "GUEST_PRESENT",
+} as const;
+
+/** What a check observes. */
+export type HealthCheck_Kind = (typeof HealthCheck_Kind)[keyof typeof HealthCheck_Kind];
+
+/** Whose a check's subject is. */
+export const HealthCheck_Category = {
+  /** Not set. */
+  CATEGORY_UNSPECIFIED: "CATEGORY_UNSPECIFIED",
+  /** The platform underneath the instance. */
+  SYSTEM: "SYSTEM",
+  /** The instance's own operating system and network configuration. */
+  INSTANCE: "INSTANCE",
+} as const;
+
+/** Whose a check's subject is. */
+export type HealthCheck_Category = (typeof HealthCheck_Category)[keyof typeof HealthCheck_Category];
+
+/** A check's outcome. */
+export const HealthCheck_Outcome = {
+  /** Not set. */
+  OUTCOME_UNSPECIFIED: "OUTCOME_UNSPECIFIED",
+  /** Passed. */
+  OK: "OK",
+  /** Failed. */
+  IMPAIRED: "IMPAIRED",
+  /** No recent observation. */
+  INSUFFICIENT_DATA: "INSUFFICIENT_DATA",
+  /** The check doesn't apply now. */
+  NOT_APPLICABLE: "NOT_APPLICABLE",
+} as const;
+
+/** A check's outcome. */
+export type HealthCheck_Outcome = (typeof HealthCheck_Outcome)[keyof typeof HealthCheck_Outcome];
+
+/** The request for GetInstance. */
+export interface GetInstanceRequest {
+  /** The instance to return. */
+  name?: string;
+}
+
+/** The request for ListInstances. */
+export interface ListInstancesRequest {
+  /** The zone whose instances to list, `projects/{project}/zones/{zone}`. */
+  parent?: string;
+  /**
+   * The most instances to return; the server clamps it, and 0 means its
+   * default.
+   */
+  pageSize?: number;
+  /** A previous response's `nextPageToken`, for the page after it. */
+  pageToken?: string;
+}
+
+/** The response for ListInstances. */
+export interface ListInstancesResponse {
+  /** The instances on this page. */
+  instances?: Instance[];
+  /** The token for the next page; empty on the last one. */
+  nextPageToken?: string;
+}
+
+/** The request for CreateInstance. */
+export interface CreateInstanceRequest {
+  /** The zone to launch the instance in, `projects/{project}/zones/{zone}`. */
+  parent?: string;
+  /**
+   * The instance to launch: its type, its image or image family, its key
+   * pair and its network interface, and optionally its login user, boot
+   * volume and tags.
+   */
+  instance?: Instance;
+  /**
+   * A UUID; a repeat with the same id returns the first request's
+   * operation instead of launching a second instance.
+   */
+  requestId?: string;
+}
+
+/** The request for UpdateInstance. */
+export interface UpdateInstanceRequest {
+  /** The instance, by its name, with the fields to change. */
+  instance?: Instance;
+  /** The fields to change: `instanceType`, `tags`, or both. `*` is both. */
+  updateMask?: string;
+  /**
+   * A UUID; a repeat with the same id returns the first request's
+   * operation instead of changing the instance again.
+   */
+  requestId?: string;
+}
+
+/** The request for DeleteInstance. */
+export interface DeleteInstanceRequest {
+  /** The instance to terminate. */
+  name?: string;
+  /**
+   * A UUID; a repeat with the same id returns the first request's
+   * operation.
+   */
+  requestId?: string;
+}
+
+/** The request for StartInstance. */
+export interface StartInstanceRequest {
+  /** The instance to start. */
+  name?: string;
+  /**
+   * A UUID; a repeat with the same id returns the first request's
+   * operation.
+   */
+  requestId?: string;
+}
+
+/** The request for StopInstance. */
+export interface StopInstanceRequest {
+  /** The instance to stop. */
+  name?: string;
+  /**
+   * A UUID; a repeat with the same id returns the first request's
+   * operation.
+   */
+  requestId?: string;
+}