@dbx-tools/databricks 0.1.9

package/README.md

@@ -0,0 +1,69 @@
+# @dbx-tools/node-databricks
+
+Generic Node-side Databricks workspace and cloud infrastructure helpers.
+
+Import this package when backend code needs workspace URL/id discovery, cloud
+provider/region lookup, DNS resolution, or public-IP discovery without requiring
+an AppKit plugin runtime.
+
+Key features:
+
+- Workspace URL and numeric workspace id resolution from AppKit context,
+  Databricks SDK config, env, and config files.
+- Cloud provider/region detection by resolving workspace hosts against public
+  AWS, Azure, and GCP IP feeds.
+- In-process and on-disk caching for cloud IP range feeds.
+- DNS A/AAAA lookup helpers for Databricks and adjacent service hosts.
+- Memoized outbound public-IP discovery for setup and diagnostics.
+
+## Resolve Workspace Identity
+
+```ts
+import { workspace } from "@dbx-tools/node-databricks";
+
+const url = await workspace.getWorkspaceUrl();
+const id = await workspace.getWorkspaceId();
+```
+
+`workspace.getWorkspaceUrl()` checks the active AppKit execution context when
+present, then a default Databricks SDK client, then environment/config. Use it in
+libraries that should work inside an AppKit request and from a standalone
+script.
+
+## Detect Cloud Provider And Region
+
+```ts
+import { cloud } from "@dbx-tools/node-databricks";
+
+const location = await cloud.resolveCloudLocation("https://adb-123.azuredatabricks.net");
+```
+
+`cloud.resolveCloudLocation()` DNS-resolves the workspace host and matches its
+IPs against AWS, Azure, and GCP public range feeds. Feeds are cached on disk and
+in process for 24 hours. Use this when constructing region-specific service URLs
+or routing workspace-adjacent traffic.
+
+Cloud detection is best-effort. It is intended for endpoint construction and
+developer diagnostics, not for security policy decisions.
+
+## Resolve Network Details
+
+```ts
+import { net } from "@dbx-tools/node-databricks";
+
+const ips = await net.resolveHostIps("https://example.cloud.databricks.com");
+const publicIp = await net.getPublicIp();
+```
+
+`net.resolveHostIps()` accepts the same URL-like values as
+`@dbx-tools/shared-core` `net.urlBuilder()`. `net.getPublicIp()` is memoized for
+short-lived reuse.
+
+## Modules
+
+- `workspace` - workspace URL and numeric id resolution.
+- `cloud` - provider/region detection from public cloud IP ranges.
+- `net` - DNS A/AAAA resolution and outbound public-IP discovery.
+
+Zerobus endpoint construction builds on these helpers in
+[`@dbx-tools/node-databricks-zerobus`](../databricks-zerobus).

package/index.ts

@@ -0,0 +1,8 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as cloud from "./src/cloud";
+export * as net from "./src/net";
+export * as workspace from "./src/workspace";
+export type { CloudLocation } from "./src/cloud";

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@dbx-tools/databricks",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "workspaces/node/databricks"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@databricks/sdk-experimental": "^0.17.0",
+    "@dbx-tools/appkit": "0.1.9",
+    "@dbx-tools/core": "0.1.9",
+    "@dbx-tools/shared-core": "0.1.9"
+  },
+  "main": "index.ts",
+  "license": "UNLICENSED",
+  "version": "0.1.9",
+  "types": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "dbxToolsConfig": {
+    "tags": [
+      "node"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  }
+}

package/src/cloud.ts

@@ -0,0 +1,283 @@
+/**
+ * Best-effort geolocation of a host to the cloud provider and region it
+ * runs in. Resolves the host to its IP address(es) via DNS, then matches
+ * those addresses against the public IP-range feeds each hyperscaler
+ * publishes (AWS, Azure, GCP). Handy for placing a Databricks workspace
+ * URL, but works for any host.
+ *
+ * The range feeds are large and change slowly, so each provider's feed
+ * is cached for {@link RANGE_CACHE_TTL_MS} (24 hours) at two layers: an
+ * on-disk copy under the OS temp dir (survives process restarts, shared
+ * across processes) plus an in-process memoized parse. A provider whose
+ * feed fails to load is skipped rather than failing the whole lookup -
+ * the other providers still answer.
+ *
+ * Server-only: DNS resolution needs `node:dns` (via `./net.ts`), the
+ * disk cache needs `node:fs` / `node:os` / `node:path`, and the feeds
+ * are fetched with the global `fetch`.
+ */
+
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { error, functionModule, hash, http, log, net } from "@dbx-tools/shared-core";
+import { project } from "@dbx-tools/core";
+import { resolveHostIps } from "./net";
+
+const logger = log.logger("cloud");
+
+/** How long a fetched provider IP-range feed is reused before refetch. */
+export const RANGE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** AWS publishes a single stable, unauthenticated ranges feed. */
+const AWS_RANGES_URL = "https://ip-ranges.amazonaws.com/ip-ranges.json";
+/** GCP publishes a single stable, unauthenticated ranges feed. */
+const GCP_RANGES_URL = "https://www.gstatic.com/ipranges/cloud.json";
+/**
+ * Azure has no stable feed URL - the JSON download link (with a
+ * rotating date stamp) lives on this human-facing download page and
+ * must be scraped out. See {@link fetchAzureRanges}.
+ */
+const AZURE_DOWNLOAD_PAGE = "https://www.microsoft.com/en-us/download/details.aspx?id=56519";
+/** Regex that plucks the current `ServiceTags_Public_<date>.json` link off the Azure page. */
+const AZURE_JSON_LINK =
+  /https:\/\/download\.microsoft\.com\/download\/[^"']*ServiceTags_Public_\d+\.json/;
+
+/** Cloud hyperscaler a host resolves into. */
+export enum CloudProvider {
+  Aws = "aws",
+  Azure = "azure",
+  Gcp = "gcp",
+}
+
+/**
+ * Where a host lives: the {@link CloudProvider}, the provider-native
+ * `region` string (whatever the provider's feed calls it, e.g.
+ * `"us-east-1"` on AWS, `"eastus2"` on Azure, `"us-east1"` on GCP), the
+ * resolved `ip` that matched, and the `cidr` block it fell in.
+ */
+export interface CloudLocation {
+  provider: CloudProvider;
+  region: string;
+  ip: string;
+  cidr: string;
+}
+
+/** A parsed CIDR block tagged with the region it belongs to. */
+interface RegionCidr extends net.Cidr {
+  region: string;
+}
+
+/** One provider's parsed, region-tagged range table. */
+interface ProviderRanges {
+  provider: CloudProvider;
+  ranges: RegionCidr[];
+}
+
+/**
+ * Resolve `input`'s host to a {@link CloudLocation}, or `null` when the
+ * host can't be resolved or none of its IPs match a known cloud range.
+ * `input` is any {@link net.UrlLike} - a URL, a bare host, or a `{ url }`
+ * wrapper.
+ *
+ * The provider range feeds are cached for {@link RANGE_CACHE_TTL_MS}, so
+ * only the first call in a 24-hour window pays the fetch cost; the DNS
+ * lookup happens on every call.
+ *
+ * @example
+ * await resolveCloudLocation("https://adb-1234567890.7.azuredatabricks.net");
+ * // { provider: CloudProvider.Azure,
+ * //   region: "eastus2", ip: "...", cidr: "..." }
+ *
+ * await resolveCloudLocation("dbc-abc123.cloud.databricks.com");
+ * // { provider: CloudProvider.Aws,
+ * //   region: "us-west-2", ip: "...", cidr: "..." }
+ */
+export async function resolveCloudLocation(input: net.UrlLike): Promise<CloudLocation | null> {
+  const ips = await resolveHostIps(input);
+  if (ips.length === 0) {
+    logger.debug("no ips resolved", { input: String(input) });
+    return null;
+  }
+  const providers = await loadProviderRanges();
+  for (const ip of ips) {
+    const parsed = net.parseIp(ip);
+    if (!parsed) continue;
+    for (const { provider, ranges } of providers) {
+      const match = net.findContainingCidr(parsed, ranges);
+      if (match) {
+        return { provider, region: match.region, ip, cidr: match.cidr };
+      }
+    }
+  }
+  logger.debug("no cloud range matched", { ips });
+  return null;
+}
+
+/**
+ * Load every provider's region-tagged range table, each cached for
+ * {@link RANGE_CACHE_TTL_MS}. Providers are loaded in parallel and a
+ * feed that fails to fetch or parse is dropped (logged, not thrown) so
+ * a single flaky feed never sinks the whole lookup. Exposed for callers
+ * that want to match many IPs against one cached snapshot without a DNS
+ * step per address.
+ */
+export async function loadProviderRanges(): Promise<ProviderRanges[]> {
+  const settled = await Promise.allSettled([loadAwsRanges(), loadAzureRanges(), loadGcpRanges()]);
+  const out: ProviderRanges[] = [];
+  for (const result of settled) {
+    if (result.status === "fulfilled") out.push(result.value);
+    else logger.warn("provider range load failed", { error: error.errorMessage(result.reason) });
+  }
+  return out;
+}
+
+// ────────────────────────────────────────────────────────────────
+// Per-provider cached loaders
+// ────────────────────────────────────────────────────────────────
+
+const loadAwsRanges = functionModule.memoize(fetchAwsRanges, { ttlMs: RANGE_CACHE_TTL_MS });
+const loadAzureRanges = functionModule.memoize(fetchAzureRanges, { ttlMs: RANGE_CACHE_TTL_MS });
+const loadGcpRanges = functionModule.memoize(fetchGcpRanges, { ttlMs: RANGE_CACHE_TTL_MS });
+
+// ────────────────────────────────────────────────────────────────
+// Provider feed fetch + parse
+// ────────────────────────────────────────────────────────────────
+
+interface AwsFeed {
+  prefixes?: { ip_prefix?: string; region?: string }[];
+  ipv6_prefixes?: { ipv6_prefix?: string; region?: string }[];
+}
+
+/**
+ * AWS `ip-ranges.json`: a flat list of IPv4 (`prefixes`) and IPv6
+ * (`ipv6_prefixes`) blocks, each already tagged with a `region` such
+ * as `"us-east-1"` (or `"GLOBAL"` for edge ranges).
+ */
+async function fetchAwsRanges(): Promise<ProviderRanges> {
+  const feed = await fetchJson<AwsFeed>(AWS_RANGES_URL);
+  const ranges: RegionCidr[] = [];
+  for (const entry of feed.prefixes ?? []) {
+    addRange(ranges, entry.ip_prefix, entry.region);
+  }
+  for (const entry of feed.ipv6_prefixes ?? []) {
+    addRange(ranges, entry.ipv6_prefix, entry.region);
+  }
+  logger.debug("loaded aws ranges", { count: ranges.length });
+  return { provider: CloudProvider.Aws, ranges };
+}
+
+interface GcpFeed {
+  prefixes?: { ipv4Prefix?: string; ipv6Prefix?: string; scope?: string }[];
+}
+
+/**
+ * GCP `cloud.json`: a list of blocks each carrying an `ipv4Prefix` or
+ * `ipv6Prefix` and a `scope` that is the region (`"us-east1"`) or
+ * `"global"` for non-regional ranges.
+ */
+async function fetchGcpRanges(): Promise<ProviderRanges> {
+  const feed = await fetchJson<GcpFeed>(GCP_RANGES_URL);
+  const ranges: RegionCidr[] = [];
+  for (const entry of feed.prefixes ?? []) {
+    addRange(ranges, entry.ipv4Prefix ?? entry.ipv6Prefix, entry.scope);
+  }
+  logger.debug("loaded gcp ranges", { count: ranges.length });
+  return { provider: CloudProvider.Gcp, ranges };
+}
+
+interface AzureFeed {
+  values?: {
+    name?: string;
+    properties?: { region?: string; addressPrefixes?: string[] };
+  }[];
+}
+
+/**
+ * Azure service tags: Microsoft ships no stable feed URL, so scrape the
+ * current `ServiceTags_Public_<date>.json` link off the download page
+ * and fetch it. Only the regional `AzureCloud.<region>` aggregates
+ * (which have a non-empty `region`) are kept; the cloud-wide
+ * `AzureCloud` tag and per-service tags are ignored so an address maps
+ * cleanly to one region.
+ */
+async function fetchAzureRanges(): Promise<ProviderRanges> {
+  const page = await fetchText(AZURE_DOWNLOAD_PAGE);
+  const jsonUrl = page.match(AZURE_JSON_LINK)?.[0];
+  if (!jsonUrl) {
+    throw new Error("could not find ServiceTags JSON link on Azure download page");
+  }
+  const feed = await fetchJson<AzureFeed>(jsonUrl);
+  const ranges: RegionCidr[] = [];
+  for (const value of feed.values ?? []) {
+    const region = value.properties?.region;
+    if (!region || !value.name?.startsWith("AzureCloud.")) continue;
+    for (const prefix of value.properties?.addressPrefixes ?? []) {
+      addRange(ranges, prefix, region);
+    }
+  }
+  logger.debug("loaded azure ranges", { count: ranges.length });
+  return { provider: CloudProvider.Azure, ranges };
+}
+
+// ────────────────────────────────────────────────────────────────
+// Helpers
+// ────────────────────────────────────────────────────────────────
+
+/** Parse `cidr` and, when valid and `region` is set, push a tagged range. */
+function addRange(ranges: RegionCidr[], cidr?: string, region?: string): void {
+  if (!cidr || !region) return;
+  const parsed = net.parseCidr(cidr);
+  if (parsed) ranges.push({ ...parsed, region });
+}
+
+async function fetchJson<T>(url: string): Promise<T> {
+  const text = await fetchText(url);
+  return JSON.parse(text) as T;
+}
+
+/**
+ * Fetch `url` as text with a 24h on-disk cache under the OS temp dir
+ * (keyed by an FNV hash of the URL). A fresh cache file is returned
+ * directly; a miss/expiry fetches, writes to a unique temp file, and
+ * atomically renames it into place so concurrent callers never observe
+ * a half-written cache entry.
+ */
+async function fetchText(url: string): Promise<string> {
+  const cacheDir = join(tmpdir(), "dbx-tools", "shared", "cloud");
+  const cacheDirCreated = await mkdir(cacheDir, { recursive: true });
+  const cachePath = join(cacheDir, `fetch-${hash.fnvHash(url)}.txt`);
+  const createdAt = cacheDirCreated ? undefined : await getCreated(cachePath);
+  if (createdAt) {
+    const expiresAt = new Date(createdAt.getTime() + RANGE_CACHE_TTL_MS);
+    if (expiresAt > new Date()) {
+      logger.debug("cached fetch hit", { url, cachePath });
+      return await readFile(cachePath, "utf8");
+    }
+  }
+  let tempPath: string | null = join(cacheDir, `${hash.id()}.txt`);
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw await http.createFetchError(response, url);
+    }
+    const responseText = await response.text();
+    await mkdir(dirname(tempPath), { recursive: true });
+    await writeFile(tempPath, responseText);
+
+    await rename(tempPath, cachePath);
+    logger.debug("cached fetch load", { url, cachePath });
+    tempPath = null;
+    return responseText;
+  } finally {
+    if (tempPath) {
+      await unlink(tempPath);
+    }
+  }
+}
+
+/** Birth time of `path`, or `undefined` when it doesn't exist yet. */
+async function getCreated(path: string): Promise<Date | undefined> {
+  return (await project.stat(path))?.birthtime;
+}

package/src/net.ts

@@ -0,0 +1,66 @@
+/**
+ * Server-side networking helpers that need Node builtins, layered over the
+ * browser-safe URL / IP toolkit in `@dbx-tools/shared-core`'s `net` module: DNS
+ * resolution ({@link resolveHostIps}, `node:dns`) and public-IP discovery
+ * ({@link getPublicIp}).
+ */
+
+import { lookup } from "node:dns/promises";
+import { functionModule, http, net } from "@dbx-tools/shared-core";
+
+/**
+ * This process's outbound public IP, cached for 5 minutes. Asks Cloudflare's
+ * `cdn-cgi/trace` first and falls back to ipify. Useful for allowlisting or for
+ * reasoning about egress from a Databricks App.
+ */
+export const getPublicIp = functionModule.memoize(
+  async () => {
+    const cloudflareResponse = await fetch("https://cloudflare.com/cdn-cgi/trace");
+    if (cloudflareResponse.ok) {
+      const trace = await cloudflareResponse.text();
+      const ipKey = "ip=";
+      const ip = trace
+        .split("\n")
+        .map((line) => line.trim())
+        .find((line) => line.startsWith(ipKey))
+        ?.slice(ipKey.length);
+      if (ip) return ip;
+    }
+    const ipifyResponse = await fetch("https://api.ipify.org?format=json");
+    if (!ipifyResponse.ok) {
+      throw await http.createFetchError(ipifyResponse);
+    }
+    const ipifyData = (await ipifyResponse.json()) as { ip?: string };
+    const ip = ipifyData?.ip;
+    if (ip) return ip;
+    throw new Error("Could not determine public IP");
+  },
+  { ttlMs: 1000 * 60 * 5 },
+);
+
+/**
+ * Resolve the host of `input` to its IP address(es) via the OS resolver
+ * (`dns.lookup` with `all: true`, so both A and AAAA records are returned when
+ * the host is dual-stacked). Accepts any `net.UrlLike` - a bare hostname, a full
+ * URL, or a `{ url }` wrapper - and returns the deduplicated list of literal
+ * addresses. Never throws: an unparseable input, an IP-literal host (returned
+ * as-is without a DNS round-trip), or a resolution failure all yield the
+ * appropriate list or `[]`.
+ *
+ * `dns.lookup` (not `resolve4` / `resolve6`) is used so `/etc/hosts` and the
+ * platform resolver order are honored, matching what an outbound connection to
+ * the host would actually use.
+ */
+export async function resolveHostIps(input: net.UrlLike): Promise<string[]> {
+  const host = net.urlBuilder(input)?.hostname;
+  if (!host) return [];
+  // WHATWG `URL.hostname` brackets IPv6 literals; strip before parsing.
+  const literal = net.parseIp(host.replace(/^\[|\]$/g, ""));
+  if (literal) return [host.replace(/^\[|\]$/g, "")];
+  try {
+    const results = await lookup(host, { all: true });
+    return [...new Set(results.map((r) => r.address))];
+  } catch {
+    return [];
+  }
+}

package/src/workspace.ts

@@ -0,0 +1,67 @@
+/**
+ * Resolve the current Databricks workspace's URL and numeric id from the active
+ * execution context (AppKit, when initialized), a default `WorkspaceClient`, or
+ * the environment. Server-only.
+ */
+
+import { functionModule, net } from "@dbx-tools/shared-core";
+import { appkit } from "@dbx-tools/appkit";
+import { type Config, WorkspaceClient } from "@databricks/sdk-experimental";
+
+/** Databricks workspace ids are a 10-20 digit run embedded in the host. */
+const WORKSPACE_ID_REGEX = /\d{10,20}/;
+
+/**
+ * Lazily-constructed default `WorkspaceClient` (env / profile auth), memoized so
+ * construction happens at most once per process. Used only when there's no
+ * AppKit execution context to borrow a client from.
+ */
+const getDefaultWorkspaceClient = functionModule.memoize(async () => new WorkspaceClient({}));
+
+/**
+ * The active workspace `Config`: the AppKit execution-context client's config
+ * when AppKit is initialized, else the default client's. Returns `undefined`
+ * (never throws) when neither is available.
+ */
+async function getWorkspaceConfig(): Promise<Config | undefined> {
+  let client = appkit.tryGetExecutionContext()?.client as WorkspaceClient | undefined;
+  if (!client) {
+    try {
+      client = await getDefaultWorkspaceClient();
+    } catch {
+      // no client available; fall back to the environment
+    }
+  }
+  return client?.config;
+}
+
+/**
+ * Resolve the current workspace host as a `net.UrlBuilder`: the workspace
+ * `Config` host first, then the `DATABRICKS_HOST` env var, else `undefined`.
+ */
+export async function getWorkspaceUrl(): Promise<net.UrlBuilder | undefined> {
+  const config = await getWorkspaceConfig();
+  if (config) {
+    const configHost = net.urlBuilder(await config.getHost());
+    if (configHost) return configHost;
+  }
+  const databricksHost = net.urlBuilder(process.env.DATABRICKS_HOST);
+  if (databricksHost) return databricksHost;
+  return undefined;
+}
+
+/**
+ * Resolve the numeric workspace id: the workspace `Config`'s `workspaceId`
+ * first, else the 10-20 digit run of `workspaceHost` (defaulting to
+ * {@link getWorkspaceUrl}'s host). `undefined` when neither yields an id.
+ */
+export async function getWorkspaceId(workspaceHost?: string): Promise<string | undefined> {
+  const workspaceId = (await getWorkspaceConfig())?.workspaceId;
+  if (workspaceId) return workspaceId;
+  workspaceHost = workspaceHost ?? (await getWorkspaceUrl())?.host;
+  if (workspaceHost) {
+    const match = workspaceHost.match(WORKSPACE_ID_REGEX)?.[0];
+    if (match) return match;
+  }
+  return undefined;
+}

package/tsconfig.json

@@ -0,0 +1,41 @@
+// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
+{
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib",
+    "alwaysStrict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "lib": [
+      "ES2022"
+    ],
+    "module": "ESNext",
+    "noEmitOnError": false,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "stripInternal": true,
+    "target": "ES2022",
+    "types": [
+      "node"
+    ],
+    "moduleResolution": "bundler",
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}