@databricks/sdk-uc-volumes 0.0.0-dev → 0.1.0-dev.1

package/src/v1/model.ts

@@ -0,0 +1,404 @@
+// Code generated from API definition by Databricks SDK Generator. DO NOT EDIT.
+
+import {z} from 'zod';
+
+export enum SseEncryptionAlgorithm {
+  SSE_ENCRYPTION_ALGORITHM_UNSPECIFIED = 'SSE_ENCRYPTION_ALGORITHM_UNSPECIFIED',
+  AWS_SSE_S3 = 'AWS_SSE_S3',
+  AWS_SSE_KMS = 'AWS_SSE_KMS',
+}
+
+export enum VolumeType {
+  MANAGED = 'MANAGED',
+  EXTERNAL = 'EXTERNAL',
+}
+
+export interface CreateVolumeRequest {
+  /** The name of the volume */
+  name?: string | undefined;
+  /** The name of the catalog where the schema and the volume are */
+  catalogName?: string | undefined;
+  /** The name of the schema where the volume is */
+  schemaName?: string | undefined;
+  /**
+   * The type of the volume. An external volume is located in the specified external location.
+   * A managed volume is located in the default location which is specified by the parent schema, or the parent catalog, or the Metastore.
+   * [Learn more](https://docs.databricks.com/aws/en/volumes/managed-vs-external)
+   */
+  volumeType?: VolumeType | undefined;
+  /** The storage location on the cloud */
+  storageLocation?: string | undefined;
+  /** The identifier of the user who owns the volume */
+  owner?: string | undefined;
+  /** The comment attached to the volume */
+  comment?: string | undefined;
+  /** The three-level (fully qualified) name of the volume */
+  fullName?: string | undefined;
+  /** The unique identifier of the volume */
+  volumeId?: string | undefined;
+  /** The unique identifier of the metastore */
+  metastoreId?: string | undefined;
+  createdAt?: bigint | undefined;
+  /** The identifier of the user who created the volume */
+  createdBy?: string | undefined;
+  updatedAt?: bigint | undefined;
+  /** The identifier of the user who updated the volume last time */
+  updatedBy?: string | undefined;
+  /** The AWS access point to use when accesing s3 for this external location. */
+  accessPoint?: string | undefined;
+  encryptionDetails?: EncryptionDetails | undefined;
+  /** Indicates whether the principal is limited to retrieving metadata for the associated object through the BROWSE privilege when include_browse is enabled in the request. */
+  browseOnly?: boolean | undefined;
+}
+
+export interface DeleteVolumeRequest {
+  /** The three-level (fully qualified) name of the volume */
+  fullNameArg?: string | undefined;
+}
+
+// eslint-disable-next-line @typescript-eslint/naming-convention, @typescript-eslint/no-empty-object-type -- Proto-style nested message name.
+export interface DeleteVolumeRequest_Response {}
+
+/** Encryption options that apply to clients connecting to cloud storage. */
+export interface EncryptionDetails {
+  encryptionDetailsType?:
+    | {
+        $case: 'sseEncryptionDetails';
+        /** Server-Side Encryption properties for clients communicating with AWS s3. */
+        sseEncryptionDetails: SseEncryptionDetails;
+      }
+    | undefined;
+}
+
+export interface GetVolumeRequest {
+  /** The three-level (fully qualified) name of the volume */
+  fullNameArg?: string | undefined;
+  /** Whether to include volumes in the response for which the principal can only access selective metadata for */
+  includeBrowse?: boolean | undefined;
+}
+
+export interface ListVolumesRequest {
+  /** The identifier of the catalog */
+  catalogName?: string | undefined;
+  /** The identifier of the schema */
+  schemaName?: string | undefined;
+  /** Whether to include volumes in the response for which the principal can only access selective metadata for */
+  includeBrowse?: boolean | undefined;
+  /**
+   * Maximum number of volumes to return (page length).
+   *
+   * If not set, the page length is set to a server configured value (10000, as of 1/29/2024).
+   * - when set to a value greater than 0, the page length is the minimum of this value and a server configured value (10000, as of 1/29/2024);
+   * - when set to 0, the page length is set to a server configured value (10000, as of 1/29/2024) (recommended);
+   * - when set to a value less than 0, an invalid parameter error is returned;
+   *
+   * Note: this parameter controls only the maximum number of volumes to return. The actual number of volumes returned in a page
+   * may be smaller than this value, including 0, even if there are more pages.
+   */
+  maxResults?: number | undefined;
+  /** Opaque token returned by a previous request. It must be included in the request to retrieve the next page of results (pagination). */
+  pageToken?: string | undefined;
+}
+
+// eslint-disable-next-line @typescript-eslint/naming-convention -- Proto-style nested message name.
+export interface ListVolumesRequest_Response {
+  volumes?: VolumeInfo[] | undefined;
+  /**
+   * Opaque token to retrieve the next page of results. Absent if there are no more pages.
+   * __page_token__ should be set to this value for the next request to retrieve the next page of results.
+   */
+  nextPageToken?: string | undefined;
+}
+
+/** Server-Side Encryption properties for clients communicating with AWS s3. */
+export interface SseEncryptionDetails {
+  /** Sets the value of the 'x-amz-server-side-encryption' header in S3 request. */
+  algorithm?: SseEncryptionAlgorithm | undefined;
+  /**
+   * Optional. The ARN of the SSE-KMS key used with the S3 location, when algorithm = "SSE-KMS".
+   * Sets the value of the 'x-amz-server-side-encryption-aws-kms-key-id' header.
+   */
+  awsKmsKeyArn?: string | undefined;
+}
+
+export interface UpdateVolumeRequest {
+  /** The three-level (fully qualified) name of the volume */
+  fullNameArg?: string | undefined;
+  /** New name for the volume. */
+  newName?: string | undefined;
+  /** The name of the volume */
+  name?: string | undefined;
+  /** The name of the catalog where the schema and the volume are */
+  catalogName?: string | undefined;
+  /** The name of the schema where the volume is */
+  schemaName?: string | undefined;
+  /**
+   * The type of the volume. An external volume is located in the specified external location.
+   * A managed volume is located in the default location which is specified by the parent schema, or the parent catalog, or the Metastore.
+   * [Learn more](https://docs.databricks.com/aws/en/volumes/managed-vs-external)
+   */
+  volumeType?: VolumeType | undefined;
+  /** The storage location on the cloud */
+  storageLocation?: string | undefined;
+  /** The identifier of the user who owns the volume */
+  owner?: string | undefined;
+  /** The comment attached to the volume */
+  comment?: string | undefined;
+  /** The three-level (fully qualified) name of the volume */
+  fullName?: string | undefined;
+  /** The unique identifier of the volume */
+  volumeId?: string | undefined;
+  /** The unique identifier of the metastore */
+  metastoreId?: string | undefined;
+  createdAt?: bigint | undefined;
+  /** The identifier of the user who created the volume */
+  createdBy?: string | undefined;
+  updatedAt?: bigint | undefined;
+  /** The identifier of the user who updated the volume last time */
+  updatedBy?: string | undefined;
+  /** The AWS access point to use when accesing s3 for this external location. */
+  accessPoint?: string | undefined;
+  encryptionDetails?: EncryptionDetails | undefined;
+  /** Indicates whether the principal is limited to retrieving metadata for the associated object through the BROWSE privilege when include_browse is enabled in the request. */
+  browseOnly?: boolean | undefined;
+}
+
+export interface VolumeInfo {
+  /** The name of the volume */
+  name?: string | undefined;
+  /** The name of the catalog where the schema and the volume are */
+  catalogName?: string | undefined;
+  /** The name of the schema where the volume is */
+  schemaName?: string | undefined;
+  /**
+   * The type of the volume. An external volume is located in the specified external location.
+   * A managed volume is located in the default location which is specified by the parent schema, or the parent catalog, or the Metastore.
+   * [Learn more](https://docs.databricks.com/aws/en/volumes/managed-vs-external)
+   */
+  volumeType?: VolumeType | undefined;
+  /** The storage location on the cloud */
+  storageLocation?: string | undefined;
+  /** The identifier of the user who owns the volume */
+  owner?: string | undefined;
+  /** The comment attached to the volume */
+  comment?: string | undefined;
+  /** The three-level (fully qualified) name of the volume */
+  fullName?: string | undefined;
+  /** The unique identifier of the volume */
+  volumeId?: string | undefined;
+  /** The unique identifier of the metastore */
+  metastoreId?: string | undefined;
+  createdAt?: bigint | undefined;
+  /** The identifier of the user who created the volume */
+  createdBy?: string | undefined;
+  updatedAt?: bigint | undefined;
+  /** The identifier of the user who updated the volume last time */
+  updatedBy?: string | undefined;
+  /** The AWS access point to use when accesing s3 for this external location. */
+  accessPoint?: string | undefined;
+  encryptionDetails?: EncryptionDetails | undefined;
+  /** Indicates whether the principal is limited to retrieving metadata for the associated object through the BROWSE privilege when include_browse is enabled in the request. */
+  browseOnly?: boolean | undefined;
+}
+
+// eslint-disable-next-line @typescript-eslint/naming-convention -- Proto-style nested message name.
+export const unmarshalDeleteVolumeRequest_ResponseSchema: z.ZodType<DeleteVolumeRequest_Response> =
+  z.object({});
+
+export const unmarshalEncryptionDetailsSchema: z.ZodType<EncryptionDetails> = z
+  .object({
+    sse_encryption_details: z
+      .lazy(() => unmarshalSseEncryptionDetailsSchema)
+      .optional(),
+  })
+  .transform(d => ({
+    encryptionDetailsType:
+      d.sse_encryption_details !== undefined
+        ? {
+            $case: 'sseEncryptionDetails' as const,
+            sseEncryptionDetails: d.sse_encryption_details,
+          }
+        : undefined,
+  }));
+
+// eslint-disable-next-line @typescript-eslint/naming-convention -- Proto-style nested message name.
+export const unmarshalListVolumesRequest_ResponseSchema: z.ZodType<ListVolumesRequest_Response> =
+  z
+    .object({
+      volumes: z.array(z.lazy(() => unmarshalVolumeInfoSchema)).optional(),
+      next_page_token: z.string().optional(),
+    })
+    .transform(d => ({
+      volumes: d.volumes,
+      nextPageToken: d.next_page_token,
+    }));
+
+export const unmarshalSseEncryptionDetailsSchema: z.ZodType<SseEncryptionDetails> =
+  z
+    .object({
+      algorithm: z.enum(SseEncryptionAlgorithm).optional(),
+      aws_kms_key_arn: z.string().optional(),
+    })
+    .transform(d => ({
+      algorithm: d.algorithm,
+      awsKmsKeyArn: d.aws_kms_key_arn,
+    }));
+
+export const unmarshalVolumeInfoSchema: z.ZodType<VolumeInfo> = z
+  .object({
+    name: z.string().optional(),
+    catalog_name: z.string().optional(),
+    schema_name: z.string().optional(),
+    volume_type: z.enum(VolumeType).optional(),
+    storage_location: z.string().optional(),
+    owner: z.string().optional(),
+    comment: z.string().optional(),
+    full_name: z.string().optional(),
+    volume_id: z.string().optional(),
+    metastore_id: z.string().optional(),
+    created_at: z
+      .union([z.number(), z.bigint()])
+      .transform(v => BigInt(v))
+      .optional(),
+    created_by: z.string().optional(),
+    updated_at: z
+      .union([z.number(), z.bigint()])
+      .transform(v => BigInt(v))
+      .optional(),
+    updated_by: z.string().optional(),
+    access_point: z.string().optional(),
+    encryption_details: z
+      .lazy(() => unmarshalEncryptionDetailsSchema)
+      .optional(),
+    browse_only: z.boolean().optional(),
+  })
+  .transform(d => ({
+    name: d.name,
+    catalogName: d.catalog_name,
+    schemaName: d.schema_name,
+    volumeType: d.volume_type,
+    storageLocation: d.storage_location,
+    owner: d.owner,
+    comment: d.comment,
+    fullName: d.full_name,
+    volumeId: d.volume_id,
+    metastoreId: d.metastore_id,
+    createdAt: d.created_at,
+    createdBy: d.created_by,
+    updatedAt: d.updated_at,
+    updatedBy: d.updated_by,
+    accessPoint: d.access_point,
+    encryptionDetails: d.encryption_details,
+    browseOnly: d.browse_only,
+  }));
+
+export const marshalCreateVolumeRequestSchema: z.ZodType = z
+  .object({
+    name: z.string().optional(),
+    catalogName: z.string().optional(),
+    schemaName: z.string().optional(),
+    volumeType: z.enum(VolumeType).optional(),
+    storageLocation: z.string().optional(),
+    owner: z.string().optional(),
+    comment: z.string().optional(),
+    fullName: z.string().optional(),
+    volumeId: z.string().optional(),
+    metastoreId: z.string().optional(),
+    createdAt: z.bigint().optional(),
+    createdBy: z.string().optional(),
+    updatedAt: z.bigint().optional(),
+    updatedBy: z.string().optional(),
+    accessPoint: z.string().optional(),
+    encryptionDetails: z.lazy(() => marshalEncryptionDetailsSchema).optional(),
+    browseOnly: z.boolean().optional(),
+  })
+  .transform(d => ({
+    name: d.name,
+    catalog_name: d.catalogName,
+    schema_name: d.schemaName,
+    volume_type: d.volumeType,
+    storage_location: d.storageLocation,
+    owner: d.owner,
+    comment: d.comment,
+    full_name: d.fullName,
+    volume_id: d.volumeId,
+    metastore_id: d.metastoreId,
+    created_at: d.createdAt,
+    created_by: d.createdBy,
+    updated_at: d.updatedAt,
+    updated_by: d.updatedBy,
+    access_point: d.accessPoint,
+    encryption_details: d.encryptionDetails,
+    browse_only: d.browseOnly,
+  }));
+
+export const marshalEncryptionDetailsSchema: z.ZodType = z
+  .object({
+    encryptionDetailsType: z
+      .discriminatedUnion('$case', [
+        z.object({
+          $case: z.literal('sseEncryptionDetails'),
+          sseEncryptionDetails: z.lazy(() => marshalSseEncryptionDetailsSchema),
+        }),
+      ])
+      .optional(),
+  })
+  .transform(d => ({
+    ...(d.encryptionDetailsType?.$case === 'sseEncryptionDetails' && {
+      sse_encryption_details: d.encryptionDetailsType.sseEncryptionDetails,
+    }),
+  }));
+
+export const marshalSseEncryptionDetailsSchema: z.ZodType = z
+  .object({
+    algorithm: z.enum(SseEncryptionAlgorithm).optional(),
+    awsKmsKeyArn: z.string().optional(),
+  })
+  .transform(d => ({
+    algorithm: d.algorithm,
+    aws_kms_key_arn: d.awsKmsKeyArn,
+  }));
+
+export const marshalUpdateVolumeRequestSchema: z.ZodType = z
+  .object({
+    fullNameArg: z.string().optional(),
+    newName: z.string().optional(),
+    name: z.string().optional(),
+    catalogName: z.string().optional(),
+    schemaName: z.string().optional(),
+    volumeType: z.enum(VolumeType).optional(),
+    storageLocation: z.string().optional(),
+    owner: z.string().optional(),
+    comment: z.string().optional(),
+    fullName: z.string().optional(),
+    volumeId: z.string().optional(),
+    metastoreId: z.string().optional(),
+    createdAt: z.bigint().optional(),
+    createdBy: z.string().optional(),
+    updatedAt: z.bigint().optional(),
+    updatedBy: z.string().optional(),
+    accessPoint: z.string().optional(),
+    encryptionDetails: z.lazy(() => marshalEncryptionDetailsSchema).optional(),
+    browseOnly: z.boolean().optional(),
+  })
+  .transform(d => ({
+    full_name_arg: d.fullNameArg,
+    new_name: d.newName,
+    name: d.name,
+    catalog_name: d.catalogName,
+    schema_name: d.schemaName,
+    volume_type: d.volumeType,
+    storage_location: d.storageLocation,
+    owner: d.owner,
+    comment: d.comment,
+    full_name: d.fullName,
+    volume_id: d.volumeId,
+    metastore_id: d.metastoreId,
+    created_at: d.createdAt,
+    created_by: d.createdBy,
+    updated_at: d.updatedAt,
+    updated_by: d.updatedBy,
+    access_point: d.accessPoint,
+    encryption_details: d.encryptionDetails,
+    browse_only: d.browseOnly,
+  }));

package/src/v1/transport.ts

@@ -0,0 +1,73 @@
+// Code generated from API definition by Databricks SDK Generator. DO NOT EDIT.
+
+import type {Credentials} from '@databricks/sdk-auth';
+import {defaultCredentials} from '@databricks/sdk-auth/credentials';
+import type {
+  HttpClient,
+  HttpRequest,
+  HttpResponse,
+} from '@databricks/sdk-core/http';
+import {newFetchHttpClient} from '@databricks/sdk-core/http';
+import type {ClientOptions} from '@databricks/sdk-options/client';
+
+/** Creates a new HTTP client with the given options. */
+export function newHttpClient(options?: ClientOptions): HttpClient {
+  const opts = options ?? {};
+
+  // If an HTTP client is provided, use it as-is. Throw if other options are
+  // also set, since they would be silently ignored.
+  if (opts.httpClient !== undefined) {
+    if (opts.credentials !== undefined || opts.timeout !== undefined) {
+      throw new Error(
+        'httpClient cannot be combined with credentials or timeout'
+      );
+    }
+    return opts.httpClient;
+  }
+
+  const credentials = opts.credentials ?? defaultCredentials();
+
+  const base = newFetchHttpClient();
+  let client: HttpClient = new AuthHttpClient(base, credentials);
+
+  if (opts.timeout !== undefined) {
+    client = new TimeoutHttpClient(client, opts.timeout);
+  }
+
+  return client;
+}
+
+/** Wraps an HttpClient and adds authentication headers to requests. */
+class AuthHttpClient implements HttpClient {
+  constructor(
+    private readonly base: HttpClient,
+    private readonly credentials: Credentials
+  ) {}
+
+  async send(request: HttpRequest): Promise<HttpResponse> {
+    const authHeaders = await this.credentials.authHeaders();
+    // Do not modify the original request.
+    const headers = new Headers(request.headers);
+    for (const h of authHeaders) {
+      headers.set(h.key, h.value);
+    }
+    return this.base.send({...request, headers});
+  }
+}
+
+/** Wraps an HttpClient and applies a default timeout to requests. */
+class TimeoutHttpClient implements HttpClient {
+  constructor(
+    private readonly base: HttpClient,
+    private readonly timeout: number
+  ) {}
+
+  async send(request: HttpRequest): Promise<HttpResponse> {
+    const timeoutSignal = AbortSignal.timeout(this.timeout);
+    const signal =
+      request.signal !== undefined
+        ? AbortSignal.any([request.signal, timeoutSignal])
+        : timeoutSignal;
+    return this.base.send({...request, signal});
+  }
+}

package/src/v1/utils.ts

@@ -0,0 +1,156 @@
+// Code generated from API definition by Databricks SDK Generator. DO NOT EDIT.
+
+import type {Call, Options} from '@databricks/sdk-core/api';
+import {execute} from '@databricks/sdk-core/api';
+import {ApiError} from '@databricks/sdk-core/apierror';
+import type {
+  HttpClient,
+  HttpRequest,
+  HttpResponse,
+} from '@databricks/sdk-core/http';
+import type {Logger} from '@databricks/sdk-core/logger';
+import type {CallOptions} from '@databricks/sdk-options/call';
+import JSONBig from 'json-bigint';
+import type {z} from 'zod';
+
+// JSON codec that preserves int64 precision. On the way in, large integer
+// literals come back as bigint instead of being rounded to JS Number. On the
+// way out, bigint values are emitted as raw JSON number digits.
+const jsonBigint = JSONBig({useNativeBigInt: true});
+
+export interface HttpCallOptions {
+  readonly request: HttpRequest;
+  readonly httpClient: HttpClient;
+  readonly logger: Logger;
+}
+
+/**
+ * Translates public CallOptions to the internal Options shape accepted by
+ * execute(). Even though the shapes match today, this isolates the public
+ * API from the executor's internal type so they can diverge.
+ */
+export async function executeCall(
+  call: Call,
+  options?: CallOptions
+): Promise<void> {
+  const opts: Options = {
+    ...(options?.retrier !== undefined && {retrier: options.retrier}),
+    ...(options?.rateLimiter !== undefined && {
+      rateLimiter: options.rateLimiter,
+    }),
+    ...(options?.timeout !== undefined && {timeout: options.timeout}),
+  };
+  return execute(options?.signal, call, opts);
+}
+
+async function readAll(
+  body: ReadableStream<Uint8Array> | null
+): Promise<Uint8Array> {
+  if (body === null) {
+    return new Uint8Array(0);
+  }
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  for (;;) {
+    const {done, value} = await reader.read();
+    if (done) {
+      break;
+    }
+    chunks.push(value);
+  }
+  const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return result;
+}
+
+export async function executeHttpCall(
+  opts: HttpCallOptions
+): Promise<Uint8Array> {
+  opts.logger.debug('HTTP request', {
+    method: opts.request.method,
+    url: opts.request.url,
+  });
+
+  let resp: HttpResponse;
+  try {
+    resp = await opts.httpClient.send(opts.request);
+  } catch (e: unknown) {
+    opts.logger.debug('HTTP request failed');
+    throw e;
+  }
+
+  const body = await readAll(resp.body);
+
+  opts.logger.debug('HTTP response', {
+    statusCode: resp.statusCode,
+    body: new TextDecoder().decode(body),
+  });
+
+  const apiErr = ApiError.fromHttpError(resp.statusCode, resp.headers, body);
+  if (apiErr !== undefined) {
+    throw apiErr;
+  }
+
+  return body;
+}
+
+export function buildHttpRequest(
+  method: string,
+  url: string,
+  headers: Headers,
+  signal?: AbortSignal,
+  body?: string | ReadableStream<Uint8Array>
+): HttpRequest {
+  const req: HttpRequest = {url, method, headers};
+  if (body !== undefined) {
+    req.body = body;
+  }
+  if (signal !== undefined) {
+    req.signal = signal;
+  }
+  return req;
+}
+
+export function parseResponse<T>(body: Uint8Array, schema: z.ZodType<T>): T {
+  const text = new TextDecoder().decode(body);
+  const parsed: unknown = jsonBigint.parse(text);
+  return schema.parse(parsed);
+}
+
+export function marshalRequest(data: unknown, schema: z.ZodType): string {
+  return jsonBigint.stringify(schema.parse(data));
+}
+
+export function flattenQueryParams(
+  prefix: string,
+  value: unknown,
+  params: URLSearchParams
+): void {
+  if (value === null || value === undefined) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    // arrays of objects are not yet supported
+    for (const item of value) {
+      params.append(prefix, String(item));
+    }
+  } else if (typeof value === 'object') {
+    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+      flattenQueryParams(`${prefix}.${key}`, val, params);
+    }
+  } else if (
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean' ||
+    typeof value === 'bigint'
+  ) {
+    params.append(prefix, String(value));
+  } else {
+    throw new Error(`Unsupported query parameter type: ${typeof value}`);
+  }
+}

package/README.md

@@ -1 +0,0 @@
-This is a placeholder release used to enable OIDC trusted publishing. Real code lands in a later version.

package/index.js

@@ -1 +0,0 @@
-module.exports = {};