@nirvana-labs/nirvana 1.98.1 → 1.98.2

package/src/internal/qs/utils.ts

@@ -0,0 +1,265 @@
+import { RFC1738 } from './formats';
+import type { DefaultEncoder, Format } from './types';
+import { isArray } from '../utils/values';
+
+export let has = (obj: object, key: PropertyKey): boolean => (
+  (has = (Object as any).hasOwn ?? Function.prototype.call.bind(Object.prototype.hasOwnProperty)),
+  has(obj, key)
+);
+
+const hex_table = /* @__PURE__ */ (() => {
+  const array = [];
+  for (let i = 0; i < 256; ++i) {
+    array.push('%' + ((i < 16 ? '0' : '') + i.toString(16)).toUpperCase());
+  }
+
+  return array;
+})();
+
+function compact_queue<T extends Record<string, any>>(queue: Array<{ obj: T; prop: string }>) {
+  while (queue.length > 1) {
+    const item = queue.pop();
+    if (!item) continue;
+
+    const obj = item.obj[item.prop];
+
+    if (isArray(obj)) {
+      const compacted: unknown[] = [];
+
+      for (let j = 0; j < obj.length; ++j) {
+        if (typeof obj[j] !== 'undefined') {
+          compacted.push(obj[j]);
+        }
+      }
+
+      // @ts-ignore
+      item.obj[item.prop] = compacted;
+    }
+  }
+}
+
+function array_to_object(source: any[], options: { plainObjects: boolean }) {
+  const obj = options && options.plainObjects ? Object.create(null) : {};
+  for (let i = 0; i < source.length; ++i) {
+    if (typeof source[i] !== 'undefined') {
+      obj[i] = source[i];
+    }
+  }
+
+  return obj;
+}
+
+export function merge(
+  target: any,
+  source: any,
+  options: { plainObjects?: boolean; allowPrototypes?: boolean } = {},
+) {
+  if (!source) {
+    return target;
+  }
+
+  if (typeof source !== 'object') {
+    if (isArray(target)) {
+      target.push(source);
+    } else if (target && typeof target === 'object') {
+      if ((options && (options.plainObjects || options.allowPrototypes)) || !has(Object.prototype, source)) {
+        target[source] = true;
+      }
+    } else {
+      return [target, source];
+    }
+
+    return target;
+  }
+
+  if (!target || typeof target !== 'object') {
+    return [target].concat(source);
+  }
+
+  let mergeTarget = target;
+  if (isArray(target) && !isArray(source)) {
+    // @ts-ignore
+    mergeTarget = array_to_object(target, options);
+  }
+
+  if (isArray(target) && isArray(source)) {
+    source.forEach(function (item, i) {
+      if (has(target, i)) {
+        const targetItem = target[i];
+        if (targetItem && typeof targetItem === 'object' && item && typeof item === 'object') {
+          target[i] = merge(targetItem, item, options);
+        } else {
+          target.push(item);
+        }
+      } else {
+        target[i] = item;
+      }
+    });
+    return target;
+  }
+
+  return Object.keys(source).reduce(function (acc, key) {
+    const value = source[key];
+
+    if (has(acc, key)) {
+      acc[key] = merge(acc[key], value, options);
+    } else {
+      acc[key] = value;
+    }
+    return acc;
+  }, mergeTarget);
+}
+
+export function assign_single_source(target: any, source: any) {
+  return Object.keys(source).reduce(function (acc, key) {
+    acc[key] = source[key];
+    return acc;
+  }, target);
+}
+
+export function decode(str: string, _: any, charset: string) {
+  const strWithoutPlus = str.replace(/\+/g, ' ');
+  if (charset === 'iso-8859-1') {
+    // unescape never throws, no try...catch needed:
+    return strWithoutPlus.replace(/%[0-9a-f]{2}/gi, unescape);
+  }
+  // utf-8
+  try {
+    return decodeURIComponent(strWithoutPlus);
+  } catch (e) {
+    return strWithoutPlus;
+  }
+}
+
+const limit = 1024;
+
+export const encode: (
+  str: any,
+  defaultEncoder: DefaultEncoder,
+  charset: string,
+  type: 'key' | 'value',
+  format: Format,
+) => string = (str, _defaultEncoder, charset, _kind, format: Format) => {
+  // This code was originally written by Brian White for the io.js core querystring library.
+  // It has been adapted here for stricter adherence to RFC 3986
+  if (str.length === 0) {
+    return str;
+  }
+
+  let string = str;
+  if (typeof str === 'symbol') {
+    string = Symbol.prototype.toString.call(str);
+  } else if (typeof str !== 'string') {
+    string = String(str);
+  }
+
+  if (charset === 'iso-8859-1') {
+    return escape(string).replace(/%u[0-9a-f]{4}/gi, function ($0) {
+      return '%26%23' + parseInt($0.slice(2), 16) + '%3B';
+    });
+  }
+
+  let out = '';
+  for (let j = 0; j < string.length; j += limit) {
+    const segment = string.length >= limit ? string.slice(j, j + limit) : string;
+    const arr = [];
+
+    for (let i = 0; i < segment.length; ++i) {
+      let c = segment.charCodeAt(i);
+      if (
+        c === 0x2d || // -
+        c === 0x2e || // .
+        c === 0x5f || // _
+        c === 0x7e || // ~
+        (c >= 0x30 && c <= 0x39) || // 0-9
+        (c >= 0x41 && c <= 0x5a) || // a-z
+        (c >= 0x61 && c <= 0x7a) || // A-Z
+        (format === RFC1738 && (c === 0x28 || c === 0x29)) // ( )
+      ) {
+        arr[arr.length] = segment.charAt(i);
+        continue;
+      }
+
+      if (c < 0x80) {
+        arr[arr.length] = hex_table[c];
+        continue;
+      }
+
+      if (c < 0x800) {
+        arr[arr.length] = hex_table[0xc0 | (c >> 6)]! + hex_table[0x80 | (c & 0x3f)];
+        continue;
+      }
+
+      if (c < 0xd800 || c >= 0xe000) {
+        arr[arr.length] =
+          hex_table[0xe0 | (c >> 12)]! + hex_table[0x80 | ((c >> 6) & 0x3f)] + hex_table[0x80 | (c & 0x3f)];
+        continue;
+      }
+
+      i += 1;
+      c = 0x10000 + (((c & 0x3ff) << 10) | (segment.charCodeAt(i) & 0x3ff));
+
+      arr[arr.length] =
+        hex_table[0xf0 | (c >> 18)]! +
+        hex_table[0x80 | ((c >> 12) & 0x3f)] +
+        hex_table[0x80 | ((c >> 6) & 0x3f)] +
+        hex_table[0x80 | (c & 0x3f)];
+    }
+
+    out += arr.join('');
+  }
+
+  return out;
+};
+
+export function compact(value: any) {
+  const queue = [{ obj: { o: value }, prop: 'o' }];
+  const refs = [];
+
+  for (let i = 0; i < queue.length; ++i) {
+    const item = queue[i];
+    // @ts-ignore
+    const obj = item.obj[item.prop];
+
+    const keys = Object.keys(obj);
+    for (let j = 0; j < keys.length; ++j) {
+      const key = keys[j]!;
+      const val = obj[key];
+      if (typeof val === 'object' && val !== null && refs.indexOf(val) === -1) {
+        queue.push({ obj: obj, prop: key });
+        refs.push(val);
+      }
+    }
+  }
+
+  compact_queue(queue);
+
+  return value;
+}
+
+export function is_regexp(obj: any) {
+  return Object.prototype.toString.call(obj) === '[object RegExp]';
+}
+
+export function is_buffer(obj: any) {
+  if (!obj || typeof obj !== 'object') {
+    return false;
+  }
+
+  return !!(obj.constructor && obj.constructor.isBuffer && obj.constructor.isBuffer(obj));
+}
+
+export function combine(a: any, b: any) {
+  return [].concat(a, b);
+}
+
+export function maybe_map<T>(val: T[], fn: (v: T) => T) {
+  if (isArray(val)) {
+    const mapped = [];
+    for (let i = 0; i < val.length; i += 1) {
+      mapped.push(fn(val[i]!));
+    }
+    return mapped;
+  }
+  return fn(val);
+}

package/src/internal/utils/query.ts

@@ -1,23 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { NirvanaLabsError } from '../../core/error';
+import * as qs from '../qs/stringify';
 
-/**
- * Basic re-implementation of `qs.stringify` for primitive types.
- */
 export function stringifyQuery(query: object | Record<string, unknown>) {
-  return Object.entries(query)
-    .filter(([_, value]) => typeof value !== 'undefined')
-    .map(([key, value]) => {
-      if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
-        return `${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
-      }
-      if (value === null) {
-        return `${encodeURIComponent(key)}=`;
-      }
-      throw new NirvanaLabsError(
-        `Cannot stringify type ${typeof value}; Expected string, number, boolean, or null. If you need to pass nested query parameters, you can manually encode them, e.g. { query: { 'foo[key1]': value1, 'foo[key2]': value2 } }, and please open a GitHub issue requesting better support for your use case.`,
-      );
-    })
-    .join('&');
+  return qs.stringify(query, { arrayFormat: 'comma' });
 }

package/src/resources/compute/api.md

@@ -46,6 +46,29 @@ Methods:
 
 - <code title="get /v1/compute/vms/os_images">client.compute.vms.osImages.<a href="./src/resources/compute/vms/os-images.ts">list</a>({ ...params }) -> OSImagesCursor</code>
 
+### Metrics
+
+Types:
+
+- <code><a href="./src/resources/compute/vms/metrics.ts">VMMetricPoint</a></code>
+- <code><a href="./src/resources/compute/vms/metrics.ts">VMMetricSeries</a></code>
+- <code><a href="./src/resources/compute/vms/metrics.ts">VMMetrics</a></code>
+
+Methods:
+
+- <code title="get /v1/compute/vms/{vm_id}/metrics">client.compute.vms.metrics.<a href="./src/resources/compute/vms/metrics.ts">list</a>(vmID, { ...params }) -> VMMetrics</code>
+
+### MetricDescriptors
+
+Types:
+
+- <code><a href="./src/resources/compute/vms/metric-descriptors.ts">VMMetricDescriptor</a></code>
+- <code><a href="./src/resources/compute/vms/metric-descriptors.ts">VMMetricDescriptorList</a></code>
+
+Methods:
+
+- <code title="get /v1/compute/metric_descriptors">client.compute.vms.metricDescriptors.<a href="./src/resources/compute/vms/metric-descriptors.ts">list</a>() -> VMMetricDescriptorList</code>
+
 ## Volumes
 
 Types:

package/src/resources/compute/vms/index.ts

@@ -2,6 +2,18 @@
 
 export { Availability, type AvailabilityCreateParams, type AvailabilityUpdateParams } from './availability';
 export { Cost, type CostCreateParams, type CostUpdateParams } from './cost';
+export {
+  MetricDescriptors,
+  type VMMetricDescriptor,
+  type VMMetricDescriptorList,
+} from './metric-descriptors';
+export {
+  Metrics,
+  type VMMetricPoint,
+  type VMMetricSeries,
+  type VMMetrics,
+  type MetricListParams,
+} from './metrics';
 export { OSImages, type OSImageListParams } from './os-images';
 export {
   VMs,

package/src/resources/compute/vms/metric-descriptors.ts

@@ -0,0 +1,77 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as Shared from '../../shared';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+
+export class MetricDescriptors extends APIResource {
+  /**
+   * Describe every metric a VM reports: its name, unit, the range its values fall
+   * in, and whether a value can be null. Read this instead of holding a list of
+   * metric names, so a metric published later is picked up without a client change.
+   *
+   * @example
+   * ```ts
+   * const vmMetricDescriptorList =
+   *   await client.compute.vms.metricDescriptors.list();
+   * ```
+   */
+  list(options?: RequestOptions): APIPromise<VMMetricDescriptorList> {
+    return this._client.get('/v1/compute/metric_descriptors', options);
+  }
+}
+
+/**
+ * Describes one metric a VM reports: how to name it, what its values mean, and the
+ * range they fall in.
+ */
+export interface VMMetricDescriptor {
+  /**
+   * What the metric measures.
+   */
+  description: string;
+
+  /**
+   * Highest value the metric reports, or null when it has no ceiling of its own.
+   */
+  max_value: number | null;
+
+  /**
+   * Fully-qualified name of the metric, and the only spelling the metric query
+   * parameter accepts.
+   */
+  metric: string;
+
+  /**
+   * Lowest value the metric reports.
+   */
+  min_value: number;
+
+  /**
+   * Whether a point's value can be null. A null means the VM reported no observation
+   * for that period, which is what a stopped VM looks like.
+   */
+  nullable: boolean;
+
+  /**
+   * Unit the values are expressed in.
+   */
+  unit: Shared.VMMetricUnit;
+}
+
+export interface VMMetricDescriptorList {
+  items: Array<VMMetricDescriptor>;
+
+  /**
+   * Pagination response details.
+   */
+  pagination: Shared.Pagination;
+}
+
+export declare namespace MetricDescriptors {
+  export {
+    type VMMetricDescriptor as VMMetricDescriptor,
+    type VMMetricDescriptorList as VMMetricDescriptorList,
+  };
+}

package/src/resources/compute/vms/metrics.ts

@@ -0,0 +1,149 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as Shared from '../../shared';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+export class Metrics extends APIResource {
+  /**
+   * Read a VM's resource metrics over an interval. Every series covers the same
+   * periods, so they line up index for index, and a period the VM reported no
+   * observation for carries a null value.
+   *
+   * @example
+   * ```ts
+   * const vmMetrics = await client.compute.vms.metrics.list(
+   *   'vm_id',
+   * );
+   * ```
+   */
+  list(
+    vmID: string,
+    query: MetricListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<VMMetrics> {
+    return this._client.get(path`/v1/compute/vms/${vmID}/metrics`, { query, ...options });
+  }
+}
+
+/**
+ * One period's value.
+ */
+export interface VMMetricPoint {
+  /**
+   * End of the period the value covers, so a point timestamped 00:05 over
+   * five-minute periods describes 00:00 through 00:05.
+   */
+  timestamp: string;
+
+  /**
+   * Value over the period, in the series' unit. Null means the VM reported no
+   * observation for this period, which is what a stopped VM looks like.
+   */
+  value: number | null;
+}
+
+/**
+ * One metric's values over the interval served.
+ */
+export interface VMMetricSeries {
+  /**
+   * Fully-qualified name of the metric.
+   */
+  metric: string;
+
+  /**
+   * Values over the interval, oldest first. Every series in a response covers the
+   * same periods, so they line up index for index.
+   */
+  points: Array<VMMetricPoint>;
+
+  /**
+   * Unit the values are expressed in.
+   */
+  unit: Shared.VMMetricUnit;
+}
+
+/**
+ * A VM's metrics over an interval: one series per metric, on a shared grid of
+ * periods.
+ */
+export interface VMMetrics {
+  /**
+   * How the samples inside one period were folded into a single value.
+   */
+  aggregation: 'mean' | 'max' | 'min';
+
+  /**
+   * End of the interval served, exclusive.
+   */
+  end_time: string;
+
+  /**
+   * One series per requested metric, in the order they were requested.
+   */
+  metrics: Array<VMMetricSeries>;
+
+  /**
+   * Width of one period, and so the spacing between consecutive points.
+   */
+  period: '5m' | '15m' | '1h' | '6h' | '24h';
+
+  /**
+   * Start of the interval served, inclusive. It can be later than the requested
+   * start when the request asked for more than the available history.
+   */
+  start_time: string;
+
+  /**
+   * ID of the VM the series belong to.
+   */
+  vm_id: string;
+}
+
+export interface MetricListParams {
+  /**
+   * How the samples inside one period are folded into a single value.
+   */
+  aggregation?: 'mean' | 'max' | 'min';
+
+  /**
+   * End of the interval, exclusive, as an RFC 3339 timestamp. Defaults to now.
+   */
+  end_time?: string;
+
+  /**
+   * Metric to return. Repeat the parameter for several; every metric is returned
+   * when it is left out.
+   */
+  metric?: Array<
+    | 'compute.nirvanalabs.io/vm/cpu/used_cores'
+    | 'compute.nirvanalabs.io/vm/cpu/utilization'
+    | 'compute.nirvanalabs.io/vm/memory/used_bytes'
+    | 'compute.nirvanalabs.io/vm/memory/utilization'
+  >;
+
+  /**
+   * Width of one period, and so the spacing between points. An interval holding more
+   * than 1440 periods is rejected; the error names a period that fits.
+   */
+  period?: '5m' | '15m' | '1h' | '6h' | '24h';
+
+  /**
+   * Start of the interval, inclusive, as an RFC 3339 timestamp. Defaults to an hour
+   * before end_time. A start older than the 30 days of history kept is served from
+   * where that history begins.
+   */
+  start_time?: string;
+}
+
+export declare namespace Metrics {
+  export {
+    type VMMetricPoint as VMMetricPoint,
+    type VMMetricSeries as VMMetricSeries,
+    type VMMetrics as VMMetrics,
+    type MetricListParams as MetricListParams,
+  };
+}

package/src/resources/compute/vms/os-images.ts

@@ -29,7 +29,25 @@ export class OSImages extends APIResource {
   }
 }
 
-export interface OSImageListParams extends CursorParams {}
+export interface OSImageListParams extends CursorParams {
+  /**
+   * Filter by a case-insensitive substring of the OS Image display name
+   */
+  display_name?: string;
+
+  /**
+   * Filter by a case-insensitive substring of the OS Image name
+   */
+  name?: string;
+
+  /**
+   * Comma-separated sort terms in precedence order, each field:asc or field:desc.
+   * Fields: created_at, name, display_name, position. An image name embeds its
+   * version, so name:asc is lexicographic rather than newest-first; position is the
+   * catalog's intended display order.
+   */
+  sort?: string;
+}
 
 export declare namespace OSImages {
   export { type OSImageListParams as OSImageListParams };

package/src/resources/compute/vms/vms.ts

@@ -7,6 +7,10 @@ import * as AvailabilityAPI from './availability';
 import { Availability, AvailabilityCreateParams, AvailabilityUpdateParams } from './availability';
 import * as CostAPI from './cost';
 import { Cost, CostCreateParams, CostUpdateParams } from './cost';
+import * as MetricDescriptorsAPI from './metric-descriptors';
+import { MetricDescriptors, VMMetricDescriptor, VMMetricDescriptorList } from './metric-descriptors';
+import * as MetricsAPI from './metrics';
+import { MetricListParams, Metrics, VMMetricPoint, VMMetricSeries, VMMetrics } from './metrics';
 import * as OSImagesAPI from './os-images';
 import { OSImageListParams, OSImages } from './os-images';
 import * as VolumesAPI from './volumes';
@@ -22,6 +26,10 @@ export class VMs extends APIResource {
   cost: CostAPI.Cost = new CostAPI.Cost(this._client);
   volumes: VolumesAPI.Volumes = new VolumesAPI.Volumes(this._client);
   osImages: OSImagesAPI.OSImages = new OSImagesAPI.OSImages(this._client);
+  metrics: MetricsAPI.Metrics = new MetricsAPI.Metrics(this._client);
+  metricDescriptors: MetricDescriptorsAPI.MetricDescriptors = new MetricDescriptorsAPI.MetricDescriptors(
+    this._client,
+  );
 
   /**
    * Create a VM
@@ -408,12 +416,56 @@ export interface VMListParams extends CursorParams {
    * Project ID of resources to request
    */
   project_id: string;
+
+  /**
+   * Filter by a case-insensitive substring of the VM name
+   */
+  name?: string;
+
+  /**
+   * Filter by whether a public IP is enabled
+   */
+  public_ip_enabled?: boolean;
+
+  /**
+   * Filter by region
+   */
+  region?: string;
+
+  /**
+   * Comma-separated sort terms in precedence order, each field:asc or field:desc.
+   * Fields: created_at, updated_at, name, status, vcpu, memory
+   */
+  sort?: string;
+
+  /**
+   * Filter by VM status
+   */
+  status?: 'pending' | 'creating' | 'updating' | 'ready' | 'deleting' | 'error';
+
+  /**
+   * Filter by the subnet the VM is attached to
+   */
+  subnet_id?: string;
+
+  /**
+   * Filter by tags. Repeat the parameter to require several tags; a VM must carry
+   * all of them.
+   */
+  tags?: Array<string>;
+
+  /**
+   * Filter by the VPC the VM is attached to
+   */
+  vpc_id?: string;
 }
 
 VMs.Availability = Availability;
 VMs.Cost = Cost;
 VMs.Volumes = Volumes;
 VMs.OSImages = OSImages;
+VMs.Metrics = Metrics;
+VMs.MetricDescriptors = MetricDescriptors;
 
 export declare namespace VMs {
   export {
@@ -444,4 +496,18 @@ export declare namespace VMs {
   export { Volumes as Volumes, type VolumeListParams as VolumeListParams };
 
   export { OSImages as OSImages, type OSImageListParams as OSImageListParams };
+
+  export {
+    Metrics as Metrics,
+    type VMMetricPoint as VMMetricPoint,
+    type VMMetricSeries as VMMetricSeries,
+    type VMMetrics as VMMetrics,
+    type MetricListParams as MetricListParams,
+  };
+
+  export {
+    MetricDescriptors as MetricDescriptors,
+    type VMMetricDescriptor as VMMetricDescriptor,
+    type VMMetricDescriptorList as VMMetricDescriptorList,
+  };
 }