@databricks/sdk-core 0.0.0-dev → 0.1.0-dev.2

package/src/apierror/apierror.ts

@@ -0,0 +1,253 @@
+import {z} from 'zod';
+
+import {Code, codeFromString} from './codes';
+import type {ErrorDetails} from './details';
+import {parseErrorDetails} from './details';
+
+// Reusable schema fragment for nullish string fields.
+const nullishString = z
+  .string()
+  .nullish()
+  .transform(v => v ?? '');
+
+// Zod schema for parsing the JSON error response body. The schema is lenient
+// to handle the various Databricks API error formats (standard, legacy, SCIM).
+const errorResponseSchema = z.object({
+  message: nullishString,
+  details: z
+    .array(z.unknown())
+    .nullish()
+    .transform(v => v ?? []),
+  // Some Databricks APIs incorrectly return the HTTP status code as an
+  // integer rather than the actual error code as a string.
+  error_code: z.unknown().optional(),
+  // Legacy Databricks APIs (e.g. version 1.2 and earlier) used "error"
+  // instead of "message".
+  error: nullishString,
+  // SCIM error fields (RFC7644 section 3.7.3).
+  // The "status" field is intentionally omitted; it duplicates HTTP status.
+  detail: nullishString,
+  scimType: nullishString,
+});
+
+// Constructor options for ApiError.
+interface ApiErrorOptions {
+  code: Code;
+  message: string;
+  details: ErrorDetails;
+  httpStatusCode?: number | undefined;
+  httpHeader?: Headers | undefined;
+  httpBody?: Uint8Array | undefined;
+  cause?: unknown;
+}
+
+/** ApiError is a transport-agnostic error representing a Databricks API error. */
+export class ApiError extends Error {
+  /** The canonical error code of the error. */
+  readonly code: Code;
+
+  /**
+   * The structured error details of the error. This is left empty if the
+   * error response is not a standard Databricks API error.
+   */
+  readonly details: ErrorDetails;
+
+  // The raw HTTP error details, undefined if this is not an HTTP error.
+  private readonly httpErr?: {
+    readonly statusCode: number;
+    readonly header: Headers | undefined;
+    readonly body: Uint8Array | undefined;
+  };
+
+  /**
+   * Do not use this constructor directly. Use {@link ApiError.fromHttpError}
+   * instead. This constructor is only meant for internal and testing use.
+   * TODO: Make this constructor private.
+   *
+   * @private
+   */
+  constructor(options: ApiErrorOptions) {
+    super(options.message, {cause: options.cause});
+    this.name = 'ApiError';
+    this.code = options.code;
+    this.details = options.details;
+    if (options.httpStatusCode !== undefined) {
+      this.httpErr = {
+        statusCode: options.httpStatusCode,
+        header: options.httpHeader,
+        body: options.httpBody,
+      };
+    }
+  }
+
+  /**
+   * Returns the ApiError's HTTP status code. If the ApiError is not an HTTP
+   * error, returns -1.
+   */
+  get httpStatusCode(): number {
+    if (this.httpErr === undefined) {
+      return -1;
+    }
+    return this.httpErr.statusCode;
+  }
+
+  /**
+   * Returns the ApiError's HTTP headers. If the ApiError is not an HTTP
+   * error, returns undefined.
+   */
+  get httpHeader(): Headers | undefined {
+    if (this.httpErr === undefined) {
+      return undefined;
+    }
+    return this.httpErr.header;
+  }
+
+  /**
+   * Returns the ApiError's HTTP body. If the ApiError is not an HTTP error,
+   * returns undefined.
+   */
+  get httpBody(): Uint8Array | undefined {
+    if (this.httpErr === undefined) {
+      return undefined;
+    }
+    return this.httpErr.body;
+  }
+
+  /**
+   * Parses an HTTP error response into an ApiError. Returns undefined if the
+   * status code is 2xx.
+   */
+  static fromHttpError(
+    statusCode: number,
+    header: Headers | undefined,
+    body: Uint8Array | undefined
+  ): ApiError | undefined {
+    if (statusCode >= 200 && statusCode < 300) {
+      return undefined;
+    }
+
+    const emptyDetails: ErrorDetails = {unknownDetails: []};
+
+    if (body === undefined || body.length === 0) {
+      return new ApiError({
+        code: toCode(statusCode),
+        message: '',
+        details: emptyDetails,
+        httpStatusCode: statusCode,
+        httpHeader: header,
+        httpBody: body,
+      });
+    }
+
+    // Decode the body to a string for JSON parsing.
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(new TextDecoder().decode(body));
+    } catch (e: unknown) {
+      // The JSON error is simply swallowed, this typically happens when the
+      // error does not come directly from a Databricks API. A typical example
+      // is when the error is returned by a proxy.
+      return new ApiError({
+        code: toCode(statusCode),
+        message: '',
+        details: emptyDetails,
+        httpStatusCode: statusCode,
+        httpHeader: header,
+        httpBody: body,
+        cause: e instanceof Error ? e : undefined,
+      });
+    }
+
+    const result = errorResponseSchema.safeParse(parsed);
+    if (!result.success) {
+      return new ApiError({
+        code: toCode(statusCode),
+        message: '',
+        details: emptyDetails,
+        httpStatusCode: statusCode,
+        httpHeader: header,
+        httpBody: body,
+        cause: result.error,
+      });
+    }
+
+    const errResp = result.data;
+
+    // Error codes may be missing or be an integer (legacy APIs). In such
+    // cases, defer to the HTTP status code to infer the closest canonical
+    // error code.
+    let errorCode: Code;
+    if (typeof errResp.error_code === 'string') {
+      errorCode = codeFromString(errResp.error_code);
+    } else {
+      errorCode = toCode(statusCode);
+    }
+
+    // Determine the error message from available fields.
+    let errorMessage = '';
+    if (errResp.message !== '') {
+      errorMessage = errResp.message;
+    } else if (errResp.error !== '') {
+      errorMessage = errResp.error;
+    } else if (errResp.detail !== '') {
+      errorMessage = errResp.detail;
+    } else if (errResp.scimType !== '') {
+      errorMessage = errResp.scimType;
+    }
+
+    return new ApiError({
+      code: errorCode,
+      message: errorMessage,
+      details: parseErrorDetails(errResp.details),
+      httpStatusCode: statusCode,
+      httpHeader: header,
+      httpBody: body,
+    });
+  }
+}
+
+// Maps an HTTP status code to the closest canonical error code.
+export function toCode(httpCode: number): Code {
+  // Canonical mappings.
+  switch (httpCode) {
+    case 200:
+      return Code.OK;
+    case 400:
+      return Code.INVALID_ARGUMENT;
+    case 401:
+      return Code.UNAUTHENTICATED;
+    case 403:
+      return Code.PERMISSION_DENIED;
+    case 404:
+      return Code.NOT_FOUND;
+    case 409:
+      return Code.ABORTED;
+    case 416:
+      return Code.OUT_OF_RANGE;
+    case 429:
+      return Code.RESOURCE_EXHAUSTED;
+    case 501:
+      return Code.UNIMPLEMENTED;
+    case 503:
+      return Code.UNAVAILABLE;
+    case 504:
+      return Code.DEADLINE_EXCEEDED;
+    default:
+      break;
+  }
+
+  // Fallback for status codes without a direct canonical mapping.
+  if (httpCode >= 200 && httpCode < 300) {
+    return Code.OK;
+  }
+  if (httpCode >= 400 && httpCode < 500) {
+    // Most non-canonical 4xx status codes are state related and map
+    // to the definition of FailedPrecondition.
+    return Code.FAILED_PRECONDITION;
+  }
+  if (httpCode >= 500 && httpCode < 600) {
+    return Code.INTERNAL;
+  }
+
+  return Code.UNKNOWN;
+}

package/src/apierror/codes/codes.ts

@@ -0,0 +1,189 @@
+/**
+ * Defines error codes for API errors and their retry semantics.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Code is a numeric code for an error.
+ *
+ * The numeric values are stable and can be relied upon across SDK versions.
+ */
+enum Code {
+  /**
+   * Unknown indicates an error that cannot be classified.
+   *
+   * This code might be used for malformed error responses or error responses
+   * using an error code that cannot be mapped to a code in this package.
+   */
+  UNKNOWN = 0,
+
+  /** OK indicates the operation completed successfully. */
+  OK = 1,
+
+  /** Canceled indicates the operation was canceled (typically by the caller). */
+  CANCELED = 2,
+
+  /**
+   * InvalidArgument indicates the client specified an invalid argument.
+   *
+   * By contrast with FailedPrecondition, InvalidArgument indicates arguments
+   * that are problematic regardless of the state of the system. For example,
+   * a malformed request parameter.
+   */
+  INVALID_ARGUMENT = 3,
+
+  /**
+   * DeadlineExceeded means the operation expired before completion.
+   *
+   * For operations that modify the state of the system, this error may be
+   * returned even if the operation has completed successfully. For
+   * example, a successful response from a server could have been delayed
+   * long enough for the deadline to expire.
+   */
+  DEADLINE_EXCEEDED = 4,
+
+  /**
+   * NotFound means a requested entity (e.g. a resource or a file) was
+   * not found.
+   */
+  NOT_FOUND = 5,
+
+  /**
+   * AlreadyExists means an attempt to create an entity failed because one
+   * already exists.
+   */
+  ALREADY_EXISTS = 6,
+
+  /**
+   * PermissionDenied indicates the caller does not have permission to
+   * execute the specified operation.
+   *
+   * This is different from an error returned when the user has exhausted
+   * some resource (e.g. too many requests) which is a ResourceExhausted
+   * error.
+   */
+  PERMISSION_DENIED = 7,
+
+  /**
+   * ResourceExhausted indicates some resource has been exhausted, perhaps
+   * a per-user quota, or perhaps the entire file system is out of space.
+   */
+  RESOURCE_EXHAUSTED = 8,
+
+  /**
+   * FailedPrecondition indicates the operation was rejected because the
+   * system is not in a state required for the operation's execution.
+   * For example, directory to be deleted may be non-empty, an rmdir
+   * operation is applied to a non-directory, etc.
+   */
+  FAILED_PRECONDITION = 9,
+
+  /**
+   * Aborted indicates the operation was aborted, typically due to a
+   * concurrency issue like sequencer check failures, transaction aborts,
+   * etc.
+   */
+  ABORTED = 10,
+
+  /**
+   * OutOfRange means the operation was attempted past the valid range.
+   * E.g., seeking or reading past end of file.
+   *
+   * Unlike InvalidArgument, this error indicates a problem that may
+   * be fixed if the system state changes. For example, a 32-bit file
+   * system will generate InvalidArgument if asked to read at an
+   * offset that is not in the range [0,2^32-1], but it will generate
+   * OutOfRange if asked to read from an offset past the current
+   * file size.
+   *
+   * There is a fair bit of overlap between FailedPrecondition and
+   * OutOfRange. We recommend using OutOfRange (the more specific
+   * error) when it applies so that callers who are iterating through
+   * a space can easily look for an OutOfRange error to detect when
+   * they are done.
+   */
+  OUT_OF_RANGE = 11,
+
+  /**
+   * Unimplemented indicates the operation is not implemented or not
+   * supported/enabled in this service.
+   */
+  UNIMPLEMENTED = 12,
+
+  /**
+   * Internal indicates an internal error. This means some invariants
+   * expected by the underlying system have been broken. If you see
+   * this error, something is very broken.
+   */
+  INTERNAL = 13,
+
+  /**
+   * Unavailable indicates the service is currently unavailable.
+   *
+   * This is most likely a transient condition and may be corrected by
+   * retrying. Though, this might not always be safe to retry if the
+   * operation is non-idempotent.
+   *
+   * The Databricks SDK will generally automatically retry the request
+   * with a backoff when encountering this error.
+   */
+  UNAVAILABLE = 14,
+
+  /** DataLoss indicates unrecoverable data loss or corruption. */
+  DATA_LOSS = 15,
+
+  /**
+   * Unauthenticated indicates the request does not have valid
+   * authentication credentials for the operation.
+   */
+  UNAUTHENTICATED = 16,
+}
+
+// Maps Code values to their canonical string representation.
+const CODE_TO_STRING: ReadonlyMap<Code, string> = new Map([
+  [Code.UNKNOWN, 'UNKNOWN'],
+  [Code.OK, 'OK'],
+  [Code.CANCELED, 'CANCELLED'],
+  [Code.INVALID_ARGUMENT, 'INVALID_ARGUMENT'],
+  [Code.DEADLINE_EXCEEDED, 'DEADLINE_EXCEEDED'],
+  [Code.NOT_FOUND, 'NOT_FOUND'],
+  [Code.ALREADY_EXISTS, 'ALREADY_EXISTS'],
+  [Code.PERMISSION_DENIED, 'PERMISSION_DENIED'],
+  [Code.RESOURCE_EXHAUSTED, 'RESOURCE_EXHAUSTED'],
+  [Code.FAILED_PRECONDITION, 'FAILED_PRECONDITION'],
+  [Code.ABORTED, 'ABORTED'],
+  [Code.OUT_OF_RANGE, 'OUT_OF_RANGE'],
+  [Code.UNIMPLEMENTED, 'UNIMPLEMENTED'],
+  [Code.INTERNAL, 'INTERNAL'],
+  [Code.UNAVAILABLE, 'UNAVAILABLE'],
+  [Code.DATA_LOSS, 'DATA_LOSS'],
+  [Code.UNAUTHENTICATED, 'UNAUTHENTICATED'],
+]);
+
+// Maps canonical strings back to Code values.
+const STRING_TO_CODE: ReadonlyMap<string, Code> = new Map(
+  [...CODE_TO_STRING.entries()].map(([code, str]) => [str, code])
+);
+
+/**
+ * Returns the canonical string representation of an error code.
+ *
+ * If the code is not recognized, "UNKNOWN" is returned. Note that
+ * Code.CANCELED maps to "CANCELLED" (British spelling) to match the gRPC
+ * convention.
+ */
+function codeToString(code: Code): string {
+  return CODE_TO_STRING.get(code) ?? 'UNKNOWN';
+}
+
+/**
+ * Converts a string representation of an error code to its corresponding
+ * Code value. If the string does not match any known code, Code.UNKNOWN is
+ * returned.
+ */
+function codeFromString(s: string): Code {
+  return STRING_TO_CODE.get(s) ?? Code.UNKNOWN;
+}
+
+export {Code, codeToString, codeFromString};

package/src/apierror/codes/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Canonical error codes for Databricks API errors.
+ *
+ * @packageDocumentation
+ */
+
+export {Code, codeToString, codeFromString} from './codes';