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

package/src/clientinfo/clientinfo.ts

@@ -0,0 +1,129 @@
+/**
+ * Collects information about the client and its environment into an
+ * immutable {@link ClientInfo} value.
+ *
+ * {@link ClientInfo.with} derives a new value with additional key/value
+ * segments; it never mutates the original.
+ *
+ * @module
+ */
+
+export type ClientInfoErrorCode =
+  | 'INVALID_KEY'
+  | 'INVALID_VALUE'
+  | 'INVALID_VERSION';
+
+export class ClientInfoError extends Error {
+  readonly code: ClientInfoErrorCode;
+
+  constructor(code: ClientInfoErrorCode, message: string) {
+    super(message);
+    this.name = 'ClientInfoError';
+    this.code = code;
+  }
+}
+
+interface Segment {
+  readonly key: string;
+  readonly value: string;
+}
+
+const SEMVER_CORE = String.raw`(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)`;
+
+const SEMVER_PRERELEASE = String.raw`(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?`;
+
+const SEMVER_BUILDMETADATA = String.raw`(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?`;
+
+const REGEXP_SEMVER = new RegExp(
+  '^' + SEMVER_CORE + SEMVER_PRERELEASE + SEMVER_BUILDMETADATA + '$'
+);
+const REGEXP_VALID_SEGMENT = /^[-0-9A-Za-z_.+]+$/;
+const REGEXP_INVALID_SEGMENT_CHAR = /[^-0-9A-Za-z_.+]/g;
+
+export function isSemVer(s: string): boolean {
+  return REGEXP_SEMVER.test(s);
+}
+
+export function isValidSegment(s: string): boolean {
+  return REGEXP_VALID_SEGMENT.test(s);
+}
+
+/**
+ * Replaces characters that are not valid in segment values with
+ * hyphens. Used for environment-sourced values (runtime version,
+ * upstream) that we do not control and cannot reject.
+ */
+export function sanitize(s: string): string {
+  return s.replace(REGEXP_INVALID_SEGMENT_CHAR, '-');
+}
+
+/**
+ * ClientInfo is an immutable, ordered list of key/value segments. Use
+ * {@link ClientInfo.with} to derive new values with additional segments.
+ */
+export class ClientInfo {
+  static readonly EMPTY = new ClientInfo();
+
+  readonly segments: readonly Segment[];
+
+  private constructor(
+    segments: readonly {readonly key: string; readonly value: string}[] = []
+  ) {
+    this.segments = [...segments];
+  }
+
+  /**
+   * Returns a new {@link ClientInfo} with the given items appended. Accepts
+   * either individual key/value pairs or another {@link ClientInfo} whose
+   * segments are merged in order. The original is not modified; mixing the
+   * two forms in a single call is supported.
+   *
+   * Keys and values on pair arguments must contain only alphanumeric
+   * characters plus `_`, `.`, `+`, or `-`. Exact key+value duplicates are
+   * silently ignored. On error, an exception is thrown (all-or-nothing).
+   *
+   * @example
+   * ```ts
+   * base.with({key: 'partner', value: 'acme'});
+   * base.with(pkgClientInfo);
+   * base.with(pkgClientInfo, {key: 'sdk-feature', value: 'pagination'});
+   * ```
+   */
+  with(...items: (ClientInfo | Segment)[]): ClientInfo {
+    if (items.length === 0) {
+      return this;
+    }
+
+    const newSegments: Segment[] = [...this.segments];
+
+    for (const item of items) {
+      const pairs = item instanceof ClientInfo ? item.segments : [item];
+      for (const {key, value} of pairs) {
+        if (!isValidSegment(key)) {
+          throw new ClientInfoError('INVALID_KEY', `Invalid key: ${key}.`);
+        }
+        if (!isValidSegment(value)) {
+          throw new ClientInfoError(
+            'INVALID_VALUE',
+            `Invalid value for "${key}": ${value}.`
+          );
+        }
+        if (newSegments.some(s => s.key === key && s.value === value)) {
+          continue;
+        }
+        newSegments.push({key, value});
+      }
+    }
+
+    return new ClientInfo(newSegments);
+  }
+
+  /**
+   * Returns a string representation of the client info suitable for
+   * inclusion in HTTP headers. Key/value pairs are formatted as
+   * "key/value" and joined by spaces in the order they were inserted.
+   */
+  toString(): string {
+    return this.segments.map(s => `${s.key}/${s.value}`).join(' ');
+  }
+}

package/src/clientinfo/default.browser.ts

@@ -0,0 +1,24 @@
+/**
+ * Browser-compatible {@link createDefault}. Contains no Node.js-specific
+ * APIs (no `process.version`, `process.platform`, or `process.env`); only
+ * the segments registered via {@link setProduct}, {@link setPartner}, and
+ * {@link addToDefault} are returned, plus the core SDK identity.
+ *
+ * @module
+ */
+
+import {ClientInfo} from './clientinfo';
+import {MODULE_NAME, VERSION, getBase} from './base';
+
+/**
+ * Returns a {@link ClientInfo} populated with SDK metadata and segments
+ * registered via {@link addToDefault}. Unlike the Node.js variant, this
+ * does not auto-detect runtime, OS, CI/CD, or agent because those signals
+ * are not available in a browser.
+ */
+export function createDefault(): ClientInfo {
+  return ClientInfo.EMPTY.with(
+    {key: MODULE_NAME, value: VERSION},
+    ...getBase().segments
+  );
+}

package/src/clientinfo/default.ts

@@ -0,0 +1,128 @@
+import {ClientInfo, sanitize} from './clientinfo';
+import {MODULE_NAME, VERSION, getBase} from './base';
+import {agentProvider} from './agent';
+
+interface EnvCheck {
+  readonly name: string;
+  readonly expectedValue: string;
+}
+
+interface CicdDef {
+  readonly name: string;
+  readonly envVars: readonly EnvCheck[];
+}
+
+const CICD_PROVIDERS: readonly CicdDef[] = [
+  {
+    name: 'github',
+    envVars: [{name: 'GITHUB_ACTIONS', expectedValue: 'true'}],
+  },
+  {
+    name: 'gitlab',
+    envVars: [{name: 'GITLAB_CI', expectedValue: 'true'}],
+  },
+  {name: 'jenkins', envVars: [{name: 'JENKINS_URL', expectedValue: ''}]},
+  {
+    name: 'azure-devops',
+    envVars: [{name: 'TF_BUILD', expectedValue: 'True'}],
+  },
+  {
+    name: 'circle',
+    envVars: [{name: 'CIRCLECI', expectedValue: 'true'}],
+  },
+  {name: 'travis', envVars: [{name: 'TRAVIS', expectedValue: 'true'}]},
+  {
+    name: 'bitbucket',
+    envVars: [{name: 'BITBUCKET_BUILD_NUMBER', expectedValue: ''}],
+  },
+  {
+    name: 'google-cloud-build',
+    envVars: [
+      {name: 'PROJECT_ID', expectedValue: ''},
+      {name: 'BUILD_ID', expectedValue: ''},
+      {name: 'PROJECT_NUMBER', expectedValue: ''},
+      {name: 'LOCATION', expectedValue: ''},
+    ],
+  },
+  {
+    name: 'aws-code-build',
+    envVars: [{name: 'CODEBUILD_BUILD_ARN', expectedValue: ''}],
+  },
+  {name: 'tf-cloud', envVars: [{name: 'TFC_RUN_ID', expectedValue: ''}]},
+];
+
+function detectCicd(): string {
+  for (const p of CICD_PROVIDERS) {
+    const allMatch = p.envVars.every(ev => {
+      const v = process.env[ev.name];
+      return (
+        v !== undefined && (ev.expectedValue === '' || v === ev.expectedValue)
+      );
+    });
+    if (allMatch) {
+      return p.name;
+    }
+  }
+  return '';
+}
+
+/**
+ * Converts a Node.js version string (e.g., "v22.0.0") into a bare
+ * semver string (e.g., "22.0.0").
+ */
+export function normalizeNodeVersion(raw: string): string {
+  if (!raw.startsWith('v')) {
+    return '0.0.0-dev';
+  }
+  return raw.slice(1);
+}
+
+// Computed once at module load because process.version never changes
+// during a process lifetime.
+export const CACHED_NODE_VERSION = normalizeNodeVersion(process.version);
+
+/**
+ * Returns a {@link ClientInfo} populated with SDK metadata, runtime
+ * information, segments registered via {@link addToDefault}, and
+ * automatically detected environment properties.
+ */
+export function createDefault(): ClientInfo {
+  const pairs: {key: string; value: string}[] = [
+    {key: MODULE_NAME, value: VERSION},
+    {key: 'node', value: CACHED_NODE_VERSION},
+    {key: 'os', value: process.platform},
+    ...getBase().segments,
+  ];
+
+  // DATABRICKS_SDK_UPSTREAM and DATABRICKS_SDK_UPSTREAM_VERSION are set
+  // by tools built on top of this SDK (e.g. Terraform provider, Pulumi)
+  // to identify themselves as the upstream product. Both must be present
+  // for the upstream segment to be included.
+  const upstream = process.env.DATABRICKS_SDK_UPSTREAM;
+  if (upstream !== undefined) {
+    const upstreamVersion = process.env.DATABRICKS_SDK_UPSTREAM_VERSION;
+    if (upstreamVersion !== undefined) {
+      pairs.push(
+        {key: 'upstream', value: sanitize(upstream)},
+        {key: 'upstream-version', value: sanitize(upstreamVersion)}
+      );
+    }
+  }
+
+  const cicd = detectCicd();
+  if (cicd !== '') {
+    pairs.push({key: 'cicd', value: cicd});
+  }
+
+  const runtime = process.env.DATABRICKS_RUNTIME_VERSION;
+  if (runtime !== undefined && runtime !== '') {
+    pairs.push({key: 'runtime', value: sanitize(runtime)});
+  }
+
+  const agent = agentProvider();
+  if (agent !== '') {
+    pairs.push({key: 'agent', value: agent});
+  }
+
+  return ClientInfo.EMPTY.with(...pairs);
+}

package/src/clientinfo/index.browser.ts

@@ -0,0 +1,4 @@
+export type {ClientInfoErrorCode} from './clientinfo';
+export {ClientInfo, ClientInfoError} from './clientinfo';
+export {addToDefault, setPartner, setProduct} from './base';
+export {createDefault} from './default.browser';

package/src/clientinfo/index.ts

@@ -0,0 +1,4 @@
+export type {ClientInfoErrorCode} from './clientinfo';
+export {ClientInfo, ClientInfoError} from './clientinfo';
+export {addToDefault, setPartner, setProduct} from './base';
+export {createDefault} from './default';

package/src/http/http.ts

@@ -0,0 +1,75 @@
+/**
+ * HTTP transport primitives. Defines the {@link HttpClient} interface and a
+ * {@link newFetchHttpClient} implementation backed by the Fetch API.
+ *
+ * @module
+ */
+
+/** HttpRequest represents an outgoing HTTP request. */
+export interface HttpRequest {
+  /** The URL to send the request to. */
+  url: string;
+
+  /** The HTTP method (GET, POST, etc.). */
+  method: string;
+
+  /** The request headers. */
+  headers: Headers;
+
+  /** The request body. */
+  body?: string | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array> | null;
+
+  /** An optional signal to abort the request. */
+  signal?: AbortSignal;
+}
+
+/** HttpResponse represents the response from an HTTP request. */
+export interface HttpResponse {
+  /** The HTTP status code. */
+  statusCode: number;
+
+  /** The response headers. */
+  headers: Headers;
+
+  /** The raw response body stream. */
+  body: ReadableStream<Uint8Array> | null;
+}
+
+/**
+ * HttpClient sends HTTP requests and returns responses.
+ */
+export interface HttpClient {
+  /** Sends an HTTP request and returns the response. */
+  send(request: HttpRequest): Promise<HttpResponse>;
+}
+
+/**
+ * Creates a new HttpClient that uses the Fetch API as its transport.
+ */
+export function newFetchHttpClient(): HttpClient {
+  return {
+    async send(request: HttpRequest): Promise<HttpResponse> {
+      const init: RequestInit = {
+        method: request.method,
+        headers: request.headers,
+      };
+      if (request.body !== undefined) {
+        init.body = request.body;
+        // The Fetch spec requires duplex: 'half' for streaming request bodies.
+        // See https://fetch.spec.whatwg.org/#dom-requestinit-duplex.
+        if (request.body instanceof ReadableStream) {
+          init.duplex = 'half';
+        }
+      }
+      if (request.signal !== undefined) {
+        init.signal = request.signal;
+      }
+      const response = await fetch(request.url, init);
+      return {
+        statusCode: response.status,
+        headers: response.headers,
+        body: response.body,
+      };
+    },
+  };
+}

package/src/http/index.ts

@@ -0,0 +1,8 @@
+/**
+ * HTTP transport primitives.
+ *
+ * @packageDocumentation
+ */
+
+export {newFetchHttpClient} from './http';
+export type {HttpClient, HttpRequest, HttpResponse} from './http';

package/src/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Databricks core library.
+ *
+ * @packageDocumentation
+ */

package/src/logger/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Logger interface and built-in implementations.
+ *
+ * @packageDocumentation
+ */
+
+export type {Level, Logger} from './logger';
+export {NoOpLogger, LogLevel} from './logger';

package/src/logger/logger.ts

@@ -0,0 +1,99 @@
+/** Logger interface and built-in implementations. */
+
+/** Supported log levels in order of increasing severity. */
+export type Level = 'debug' | 'info' | 'warn' | 'error' | 'off';
+
+/**
+ * A logger that receives messages at different severity levels.
+ *
+ * The method signatures are intentionally compatible with the global
+ * {@link Console} object so that `console` can be used as a Logger when level
+ * filtering is not needed.
+ */
+export interface Logger {
+  /** Logs a debug-level message. */
+  debug(message: string, ...args: unknown[]): void;
+
+  /** Logs an info-level message. */
+  info(message: string, ...args: unknown[]): void;
+
+  /** Logs a warn-level message. */
+  warn(message: string, ...args: unknown[]): void;
+
+  /** Logs an error-level message. */
+  error(message: string, ...args: unknown[]): void;
+}
+
+/** A logger that silently discards all messages. */
+export class NoOpLogger implements Logger {
+  debug(): void {
+    // Intentionally empty.
+  }
+
+  info(): void {
+    // Intentionally empty.
+  }
+
+  warn(): void {
+    // Intentionally empty.
+  }
+
+  error(): void {
+    // Intentionally empty.
+  }
+}
+
+// Numeric severity used by LogLevel to gate calls.
+const LEVEL_SEVERITY: Record<Level, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  off: 4,
+};
+
+/**
+ * A decorator that adds level filtering to any {@link Logger}.
+ *
+ * Only messages at or above the configured minimum level are forwarded to the
+ * underlying logger. The default underlying logger is `console`.
+ *
+ * @example
+ * ```typescript
+ * // Only warn and error go to console.
+ * const logger = new LogLevel('warn');
+ * ```
+ */
+export class LogLevel implements Logger {
+  private readonly threshold: number;
+  private readonly logger: Logger;
+
+  constructor(level: Level, logger: Logger = console) {
+    this.threshold = LEVEL_SEVERITY[level];
+    this.logger = logger;
+  }
+
+  debug(message: string, ...args: unknown[]): void {
+    if (this.threshold <= LEVEL_SEVERITY.debug) {
+      this.logger.debug(message, ...args);
+    }
+  }
+
+  info(message: string, ...args: unknown[]): void {
+    if (this.threshold <= LEVEL_SEVERITY.info) {
+      this.logger.info(message, ...args);
+    }
+  }
+
+  warn(message: string, ...args: unknown[]): void {
+    if (this.threshold <= LEVEL_SEVERITY.warn) {
+      this.logger.warn(message, ...args);
+    }
+  }
+
+  error(message: string, ...args: unknown[]): void {
+    if (this.threshold <= LEVEL_SEVERITY.error) {
+      this.logger.error(message, ...args);
+    }
+  }
+}

package/src/profiles/errors.ts

@@ -0,0 +1,28 @@
+/**
+ * Error types for Databricks configuration profile operations.
+ *
+ * @module
+ */
+
+/** Discriminant codes for {@link ProfileError}. */
+export type ProfileErrorCode =
+  | 'CONFIG_FILE_NOT_FOUND'
+  | 'PROFILE_NOT_FOUND'
+  | 'EMPTY_PATH'
+  | 'EMPTY_PROFILE'
+  | 'INVALID_PROFILE_NAME';
+
+/**
+ * Error thrown by profile operations.
+ *
+ * Use the {@link ProfileError.code} field to distinguish between error causes.
+ */
+export class ProfileError extends Error {
+  readonly code: ProfileErrorCode;
+
+  constructor(code: ProfileErrorCode, message: string) {
+    super(message);
+    this.name = 'ProfileError';
+    this.code = code;
+  }
+}

package/src/profiles/index.browser.ts

@@ -0,0 +1,10 @@
+/**
+ * Browser entry point for the profiles module.
+ *
+ * @packageDocumentation
+ */
+
+export {ProfileError} from './errors';
+export type {ProfileErrorCode} from './errors';
+export type {Profile, ResolveOptions} from './profile';
+export {Secret} from './secret';

package/src/profiles/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Utility to resolve Databricks configuration profiles.
+ *
+ * A profile is a named collection of configuration values. It is typically
+ * stored in a file called ~/.databrickscfg. Profiles can be resolved from the
+ * file and/or environment variables using the {@link resolve} function.
+ *
+ * @packageDocumentation
+ */
+
+export {ProfileError} from './errors';
+export type {ProfileErrorCode} from './errors';
+export type {Profile, ResolveOptions} from './profile';
+export {defaultConfigFile, listProfiles, resolve} from './resolve';
+export {Secret} from './secret';

package/src/profiles/ini.ts

@@ -0,0 +1,126 @@
+/**
+ * Minimal INI parser and writer for the Databricks config file format.
+ *
+ * This matches the behavior of {@link https://pkg.go.dev/gopkg.in/ini.v1 | go-ini}
+ * with `SpaceBeforeInlineComment: true`, which is how the Go SDK loads
+ * databrickscfg files. Key behavioral details:
+ *
+ * - Inline comments are only recognized when `#` or `;` is preceded by a
+ *   space. The parser checks for `" #"` first; only if absent does it check
+ *   for `" ;"`. This matches Go's `strings.Index` precedence.
+ * - Both `=` and `:` are key-value delimiters (Go default). Only the first
+ *   delimiter on a line splits key from value.
+ * - Section names are the raw text between `[` and the last `]` on the line,
+ *   with no trimming.
+ * - Keys and values are trimmed of surrounding whitespace.
+ * - Lines without a delimiter throw an error (matching go-ini default).
+ *
+ * @module
+ */
+
+/** Parsed INI data as an ordered map of section names to key-value maps. */
+export type IniData = Map<string, Map<string, string>>;
+
+/**
+ * Parses an INI-formatted string into structured data.
+ *
+ * Keys before any section header are assigned to the "DEFAULT" section.
+ */
+export function parseIni(content: string): IniData {
+  const result: IniData = new Map();
+  let currentSection = 'DEFAULT';
+  result.set(currentSection, new Map());
+
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+
+    // Skip empty lines and full-line comments.
+    if (line === '' || line.startsWith('#') || line.startsWith(';')) {
+      continue;
+    }
+
+    // Section header: text between '[' and the last ']'.
+    if (line.startsWith('[')) {
+      const closeIdx = line.lastIndexOf(']');
+      if (closeIdx === -1) {
+        throw new Error(`unclosed section: ${line}`);
+      }
+      const name = line.slice(1, closeIdx);
+      if (name === '') {
+        throw new Error('empty section name');
+      }
+      currentSection = name;
+      if (!result.has(currentSection)) {
+        result.set(currentSection, new Map());
+      }
+      continue;
+    }
+
+    // Key-value pair: first '=' or ':' splits key from value.
+    const eqIdx = line.indexOf('=');
+    const colonIdx = line.indexOf(':');
+    let delimIdx: number;
+    if (eqIdx === -1 && colonIdx === -1) {
+      throw new Error(`key-value delimiter not found: ${line}`);
+    } else if (eqIdx === -1) {
+      delimIdx = colonIdx;
+    } else if (colonIdx === -1) {
+      delimIdx = eqIdx;
+    } else {
+      delimIdx = Math.min(eqIdx, colonIdx);
+    }
+
+    const key = line.slice(0, delimIdx).trim();
+    if (key === '') {
+      throw new Error(`empty key name: ${line}`);
+    }
+    let value = line.slice(delimIdx + 1).trim();
+
+    // Strip inline comments matching go-ini's SpaceBeforeInlineComment
+    // precedence: try " #" first, then " ;" only if " #" is absent.
+    let commentIdx = value.indexOf(' #');
+    if (commentIdx === -1) {
+      commentIdx = value.indexOf(' ;');
+    }
+    if (commentIdx !== -1) {
+      value = value.slice(0, commentIdx).trimEnd();
+    }
+
+    if (!result.has(currentSection)) {
+      result.set(currentSection, new Map());
+    }
+    const section = result.get(currentSection);
+    if (section !== undefined) {
+      section.set(key, value);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Formats structured INI data back into a string.
+ *
+ * Each section's keys are aligned so that all `=` signs appear in the same
+ * column, matching the output format of go-ini's `PrettyFormat` default.
+ * Sections are separated by blank lines (`PrettySection` default).
+ */
+export function formatIni(data: IniData): string {
+  const sections: string[] = [];
+
+  for (const [name, keys] of data) {
+    const lines: string[] = [];
+    lines.push(`[${name}]`);
+
+    if (keys.size > 0) {
+      const maxKeyLen = Math.max(...[...keys.keys()].map(k => k.length));
+      for (const [key, value] of keys) {
+        lines.push(`${key.padEnd(maxKeyLen)} = ${value}`);
+      }
+    }
+
+    sections.push(lines.join('\n'));
+  }
+
+  return sections.join('\n\n') + '\n';
+}