@databricks/appkit 0.39.0 → 0.40.0

package/dist/type-generator/query-registry.js

@@ -1,7 +1,9 @@
 import { createLogger } from "../logging/logger.js";
 import { CACHE_VERSION, hashSQL, loadCache, saveCache } from "./cache.js";
+import { decidePreflight } from "./preflight.js";
 import { Spinner } from "./spinner.js";
 import { sqlTypeToHelper, sqlTypeToMarker } from "./types.js";
+import { getWarehouseState, startWarehouse, waitUntilRunning } from "./warehouse-status.js";
 import { WorkspaceClient } from "@databricks/sdk-experimental";
 import pc from "picocolors";
 import fs from "node:fs/promises";
@@ -10,6 +12,12 @@ import path from "node:path";
 //#region src/type-generator/query-registry.ts
 const logger = createLogger("type-generator:query-registry");
 /**
+* Upper bound on how long a `blocking`-mode preflight will wait for a starting
+* warehouse to reach RUNNING before giving up (~5 min). Generous enough to ride
+* out a cold start without hanging an interactive CLI invocation indefinitely.
+*/
+const PREFLIGHT_WAIT_MAX_MS = 3e5;
+/**
 * Regex breakdown:
 *   '(?:[^']|'')*'   — matches a SQL string literal, including escaped '' pairs
 *   |                 — alternation: whichever branch matches first at a position wins
@@ -58,6 +66,83 @@ function parseError(raw) {
 	} catch {}
 	return { message: raw };
 }
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+function getErrorMessage(error) {
+	if (error instanceof Error) return error.message;
+	if (isObject(error) && typeof error.message === "string") return error.message;
+	return String(error);
+}
+function getErrorDiagnostic(error) {
+	const seen = /* @__PURE__ */ new Set();
+	const messages = [];
+	const stack = [error];
+	while (stack.length > 0) {
+		const current = stack.pop();
+		if (current === void 0 || seen.has(current)) continue;
+		seen.add(current);
+		const message = getErrorMessage(current);
+		if (message && message !== "[object Object]" && !messages.includes(message)) messages.push(message);
+		const code = getErrorCode(current);
+		if (code && !messages.includes(code)) messages.push(code);
+		stack.push(...getErrorChildren(current));
+	}
+	return messages.length > 0 ? messages.join(": ") : getErrorMessage(error);
+}
+function getErrorCode(error) {
+	if (!isObject(error)) return void 0;
+	const code = error.code ?? error.errno;
+	return typeof code === "string" ? code : void 0;
+}
+function getErrorStatus(error) {
+	if (!isObject(error)) return void 0;
+	const direct = error.status ?? error.statusCode;
+	if (typeof direct === "number") return direct;
+	if (isObject(error.response) && typeof error.response.status === "number") return error.response.status;
+}
+function getErrorChildren(error) {
+	if (!isObject(error)) return [];
+	const children = [];
+	if ("cause" in error) children.push(error.cause);
+	if (error instanceof AggregateError) children.push(...error.errors);
+	return children;
+}
+const CONNECTIVITY_ERROR_CODES = new Set([
+	"ECONNREFUSED",
+	"ECONNRESET",
+	"ENOTFOUND",
+	"ETIMEDOUT",
+	"EAI_AGAIN",
+	"EAI_NODATA",
+	"EAI_NONAME",
+	"EHOSTUNREACH",
+	"ENETUNREACH",
+	"CERT_HAS_EXPIRED",
+	"DEPTH_ZERO_SELF_SIGNED_CERT",
+	"ERR_TLS_CERT_ALTNAME_INVALID",
+	"SELF_SIGNED_CERT_IN_CHAIN",
+	"UNABLE_TO_VERIFY_LEAF_SIGNATURE"
+]);
+function isConnectivityMessage(message) {
+	return /\bconnection (?:refused|reset|timed out)\b/i.test(message) || /\bsocket hang up\b/i.test(message) || /\bnetwork error\b/i.test(message) || /\bcan'?t connect to\b/i.test(message) || /\bcertificate has expired\b/i.test(message) || /\bunable to verify the first certificate\b/i.test(message) || /\bupstream connect error or disconnect\/reset before headers\b/i.test(message);
+}
+function isConnectivityError(error) {
+	const seen = /* @__PURE__ */ new Set();
+	const stack = [error];
+	while (stack.length > 0) {
+		const current = stack.pop();
+		if (current === void 0 || seen.has(current)) continue;
+		seen.add(current);
+		const code = getErrorCode(current);
+		if (code && (CONNECTIVITY_ERROR_CODES.has(code) || code.startsWith("UND_ERR_"))) return true;
+		const status = getErrorStatus(current);
+		if (status === 502 || status === 503 || status === 504) return true;
+		if (isConnectivityMessage(getErrorMessage(current))) return true;
+		stack.push(...getErrorChildren(current));
+	}
+	return false;
+}
 /**
 * Extract parameters from a SQL query
 * @param sql - the SQL query to extract parameters from
@@ -120,6 +205,16 @@ function generateUnknownResultQuery(sql, queryName) {
     result: unknown;
   }`;
 }
+/**
+* Degrade gracefully when DESCRIBE can't produce a fresh schema (transient
+* connectivity outage, or a warehouse that's reachable but not ready). Reuse
+* the last-good cached type when the SQL hash is unchanged, otherwise emit
+* `unknown` from SQL alone. Never persists `result: unknown`.
+*/
+function degradedType(cache, queryName, sql, sqlHash) {
+	const prior = cache.queries[queryName];
+	return prior?.hash === sqlHash && !prior.retry ? prior.type : generateUnknownResultQuery(sql, queryName);
+}
 function extractParameterTypes(sql) {
 	const paramTypes = {};
 	const matches = sql.matchAll(/--\s*@param\s+(\w+)\s+(STRING|NUMERIC|DECIMAL|BIGINT|TINYINT|SMALLINT|INT|FLOAT|DOUBLE|BOOLEAN|DATE|TIMESTAMP_NTZ|TIMESTAMP|BINARY)\b/gi);
@@ -167,10 +262,15 @@ function inferParameterTypes(sql, ranges) {
 * @param warehouseId - the warehouse id to use for schema analysis
 * @param options - options for the query generation
 * @param options.noCache - if true, skip the cache and regenerate all types
+* @param options.mode - preflight policy: "non-blocking" never probes the
+*   warehouse and never describes (emits cached/`unknown` types and returns
+*   immediately), "blocking" waits for a starting warehouse and starts (then
+*   waits for) a stopped one, treating only a deleted/deleting warehouse as
+*   fatal. Defaults to "non-blocking".
 * @returns an array of query schemas
 */
 async function generateQueriesFromDescribe(queryFolder, warehouseId, options = {}) {
-	const { noCache = false, concurrency: rawConcurrency = 10 } = options;
+	const { noCache = false, concurrency: rawConcurrency = 10, mode = "non-blocking" } = options;
 	const concurrency = typeof rawConcurrency === "number" && Number.isFinite(rawConcurrency) ? Math.max(1, Math.floor(rawConcurrency)) : 10;
 	const [allFiles, cache] = await Promise.all([fs.readdir(queryFolder), noCache ? {
 		version: CACHE_VERSION,
@@ -231,105 +331,212 @@ async function generateQueriesFromDescribe(queryFolder, warehouseId, options = {
 		}
 	}
 	const freshResults = [];
+	const syntaxErrors = [];
+	const fatalErrors = [];
 	if (uncachedQueries.length > 0) {
-		let completed = 0;
-		const total = uncachedQueries.length;
-		spinner.start(`Describing ${total} ${total === 1 ? "query" : "queries"} (0/${total})`);
-		const describeOne = async ({ index, queryName, sql, sqlHash, cleanedSql }) => {
-			const result = await client.statementExecution.executeStatement({
-				statement: `DESCRIBE QUERY ${cleanedSql}`,
-				warehouse_id: warehouseId
-			});
-			completed++;
-			spinner.update(`Describing ${total} ${total === 1 ? "query" : "queries"} (${completed}/${total})`);
-			logger.debug("DESCRIBE result for %s: state=%s, rows=%d", queryName, result.status.state, result.result?.data_array?.length ?? 0);
-			if (result.status.state === "FAILED") {
-				const sqlError = result.status.error?.message || "Query execution failed";
-				logger.warn("DESCRIBE failed for %s: %s", queryName, sqlError);
-				const type = generateUnknownResultQuery(sql, queryName);
-				return {
-					status: "fail",
+		let decision = "proceed";
+		let fatalMessage = "";
+		if (mode === "non-blocking") decision = "degradeAll";
+		else try {
+			const state = await getWarehouseState(client, warehouseId);
+			decision = decidePreflight(state, mode);
+			if (decision === "fatal") fatalMessage = `warehouse ${warehouseId} is ${state}`;
+			if (decision === "startWaitProceed") {
+				await startWarehouse(client, warehouseId);
+				const final = await waitUntilRunning(client, warehouseId, {
+					maxMs: PREFLIGHT_WAIT_MAX_MS,
+					treatStoppedAsTransient: true
+				});
+				if (final === "RUNNING") decision = "proceed";
+				else {
+					decision = "fatal";
+					fatalMessage = `warehouse ${warehouseId} did not reach RUNNING (now ${final})`;
+				}
+			}
+			if (decision === "waitThenProceed") {
+				const final = await waitUntilRunning(client, warehouseId, { maxMs: PREFLIGHT_WAIT_MAX_MS });
+				if (final === "RUNNING") decision = "proceed";
+				else {
+					decision = "fatal";
+					fatalMessage = `warehouse ${warehouseId} did not reach RUNNING (now ${final})`;
+				}
+			}
+		} catch (err) {
+			if (isConnectivityError(err)) decision = "degradeAll";
+			else {
+				decision = "fatal";
+				fatalMessage = `warehouse ${warehouseId}: ${getErrorDiagnostic(err)}`;
+			}
+		}
+		if (decision !== "proceed") {
+			const kind = decision === "fatal" ? "fatal" : "connectivity";
+			for (const { index, queryName, sql, sqlHash } of uncachedQueries) {
+				freshResults.push({
 					index,
 					schema: {
 						name: queryName,
-						type
-					},
-					cacheEntry: {
-						hash: sqlHash,
-						type,
-						retry: true
-					},
-					error: parseError(sqlError)
-				};
-			}
-			const { type, hasResults } = convertToQueryType(result, sql, queryName);
-			return {
-				status: "ok",
-				index,
-				schema: {
-					name: queryName,
-					type
-				},
-				cacheEntry: {
-					hash: sqlHash,
-					type,
-					retry: !hasResults
-				}
-			};
-		};
-		const processBatchResults = (settled, batchOffset) => {
-			for (let i = 0; i < settled.length; i++) {
-				const entry = settled[i];
-				const { queryName } = uncachedQueries[batchOffset + i];
-				if (entry.status === "fulfilled") {
-					const res = entry.value;
-					freshResults.push({
-						index: res.index,
-						schema: res.schema
+						type: degradedType(cache, queryName, sql, sqlHash)
+					}
+				});
+				if (decision === "fatal") {
+					fatalErrors.push({
+						name: queryName,
+						message: fatalMessage
 					});
-					cache.queries[queryName] = res.cacheEntry;
 					logEntries.push({
 						queryName,
 						status: "MISS",
-						failed: res.status === "fail",
-						error: res.status === "fail" ? res.error : void 0
+						kind,
+						error: { message: fatalMessage }
 					});
-				} else {
-					const { sql, sqlHash, index } = uncachedQueries[batchOffset + i];
-					const reason = entry.reason instanceof Error ? entry.reason.message : String(entry.reason);
-					logger.warn("DESCRIBE rejected for %s: %s", queryName, reason);
-					const type = generateUnknownResultQuery(sql, queryName);
-					freshResults.push({
+				} else logEntries.push({
+					queryName,
+					status: "MISS",
+					kind
+				});
+			}
+		} else {
+			let completed = 0;
+			const total = uncachedQueries.length;
+			spinner.start(`Describing ${total} ${total === 1 ? "query" : "queries"} (0/${total})`);
+			const describeOne = async ({ index, queryName, sql, sqlHash, cleanedSql }) => {
+				const result = await client.statementExecution.executeStatement({
+					statement: `DESCRIBE QUERY ${cleanedSql}`,
+					warehouse_id: warehouseId
+				});
+				completed++;
+				spinner.update(`Describing ${total} ${total === 1 ? "query" : "queries"} (${completed}/${total})`);
+				logger.debug("DESCRIBE result for %s: state=%s, rows=%d", queryName, result.status.state, result.result?.data_array?.length ?? 0);
+				if (result.status.state === "FAILED") {
+					const sqlError = result.status.error?.message || "Query execution failed";
+					return {
+						status: "syntax",
 						index,
 						schema: {
 							name: queryName,
-							type
-						}
-					});
-					cache.queries[queryName] = {
+							type: generateUnknownResultQuery(sql, queryName)
+						},
+						error: parseError(sqlError)
+					};
+				}
+				if (result.status.state !== "SUCCEEDED") return {
+					status: "unavailable",
+					index,
+					schema: {
+						name: queryName,
+						type: degradedType(cache, queryName, sql, sqlHash)
+					}
+				};
+				const { type, hasResults } = convertToQueryType(result, sql, queryName);
+				if (!hasResults) return {
+					status: "empty",
+					index,
+					schema: {
+						name: queryName,
+						type
+					}
+				};
+				return {
+					status: "ok",
+					index,
+					schema: {
+						name: queryName,
+						type
+					},
+					cacheEntry: {
 						hash: sqlHash,
 						type,
-						retry: true
-					};
-					logEntries.push({
-						queryName,
-						status: "MISS",
-						failed: true,
-						error: parseError(reason)
-					});
+						retry: false
+					}
+				};
+			};
+			const processBatchResults = (settled, batchOffset) => {
+				for (let i = 0; i < settled.length; i++) {
+					const entry = settled[i];
+					const { queryName } = uncachedQueries[batchOffset + i];
+					if (entry.status === "fulfilled") {
+						const res = entry.value;
+						freshResults.push({
+							index: res.index,
+							schema: res.schema
+						});
+						if (res.status === "ok") {
+							cache.queries[queryName] = res.cacheEntry;
+							logEntries.push({
+								queryName,
+								status: "MISS"
+							});
+						} else if (res.status === "syntax") {
+							syntaxErrors.push({
+								name: queryName,
+								message: res.error.message
+							});
+							logEntries.push({
+								queryName,
+								status: "MISS",
+								kind: "syntax",
+								error: res.error
+							});
+						} else if (res.status === "empty") logEntries.push({
+							queryName,
+							status: "MISS",
+							kind: "empty"
+						});
+						else logEntries.push({
+							queryName,
+							status: "MISS",
+							kind: "connectivity"
+						});
+					} else {
+						completed++;
+						spinner.update(`Describing ${total} ${total === 1 ? "query" : "queries"} (${completed}/${total})`);
+						const { sql, sqlHash, index } = uncachedQueries[batchOffset + i];
+						const reason = getErrorDiagnostic(entry.reason);
+						const error = parseError(reason);
+						const priorEntry = cache.queries[queryName];
+						const canReusePrior = priorEntry?.hash === sqlHash && !priorEntry.retry;
+						const type = degradedType(cache, queryName, sql, sqlHash);
+						freshResults.push({
+							index,
+							schema: {
+								name: queryName,
+								type
+							}
+						});
+						if (!isConnectivityError(entry.reason)) {
+							fatalErrors.push({
+								name: queryName,
+								message: error.message
+							});
+							logEntries.push({
+								queryName,
+								status: "MISS",
+								kind: "fatal",
+								error
+							});
+							continue;
+						}
+						logger.warn("DESCRIBE unreachable for %s: %s — %s", queryName, reason, canReusePrior ? "reusing last cached type" : "emitting unknown (no matching cache)");
+						logEntries.push({
+							queryName,
+							status: "MISS",
+							kind: "connectivity",
+							error
+						});
+					}
 				}
+			};
+			if (uncachedQueries.length > concurrency) for (let b = 0; b < uncachedQueries.length; b += concurrency) {
+				const batch = uncachedQueries.slice(b, b + concurrency);
+				processBatchResults(await Promise.allSettled(batch.map(describeOne)), b);
+				await saveCache(cache);
 			}
-		};
-		if (uncachedQueries.length > concurrency) for (let b = 0; b < uncachedQueries.length; b += concurrency) {
-			const batch = uncachedQueries.slice(b, b + concurrency);
-			processBatchResults(await Promise.allSettled(batch.map(describeOne)), b);
-			await saveCache(cache);
-		}
-		else {
-			processBatchResults(await Promise.allSettled(uncachedQueries.map(describeOne)), 0);
-			await saveCache(cache);
+			else {
+				processBatchResults(await Promise.allSettled(uncachedQueries.map(describeOne)), 0);
+				await saveCache(cache);
+			}
+			spinner.stop("");
 		}
-		spinner.stop("");
 	}
 	const elapsed = ((performance.now() - startTime) / 1e3).toFixed(2);
 	if (logEntries.length > 0) {
@@ -339,23 +546,48 @@ async function generateQueriesFromDescribe(queryFolder, warehouseId, options = {
 		console.log(`  ${pc.bold("Typegen Queries")} ${pc.dim(`(${logEntries.length})`)}`);
 		console.log(`  ${separator}`);
 		for (const entry of logEntries) {
-			const tag = entry.failed ? pc.bold(pc.red("ERROR")) : entry.status === "HIT" ? `cache ${pc.bold(pc.green("HIT  "))}` : `cache ${pc.bold(pc.yellow("MISS "))}`;
+			let tag;
+			switch (entry.kind) {
+				case "syntax":
+					tag = pc.bold(pc.red("SQL ERR"));
+					break;
+				case "connectivity":
+					tag = pc.bold(pc.yellow("OFFLINE"));
+					break;
+				case "empty":
+					tag = pc.dim("EMPTY  ");
+					break;
+				case "fatal":
+					tag = pc.bold(pc.red("FATAL "));
+					break;
+				default: tag = entry.status === "HIT" ? `cache ${pc.bold(pc.green("HIT  "))}` : `cache ${pc.bold(pc.yellow("MISS "))}`;
+			}
 			const rawName = entry.queryName.padEnd(maxNameLen);
-			const name = entry.failed ? pc.dim(pc.strikethrough(rawName)) : rawName;
+			const name = entry.kind === "syntax" || entry.kind === "fatal" ? pc.dim(pc.strikethrough(rawName)) : rawName;
 			const errorCode = entry.error?.message.match(/\[([^\]]+)\]/)?.[1];
 			const reason = errorCode ? `  ${pc.dim(errorCode)}` : "";
 			console.log(`  ${tag}  ${name}${reason}`);
 		}
-		const newCount = logEntries.filter((e) => e.status === "MISS" && !e.failed).length;
-		const cacheCount = logEntries.filter((e) => e.status === "HIT" && !e.failed).length;
-		const errorCount = logEntries.filter((e) => e.failed).length;
+		const newCount = logEntries.filter((e) => e.status === "MISS" && !e.kind).length;
+		const cacheCount = logEntries.filter((e) => e.status === "HIT").length;
+		const syntaxCount = logEntries.filter((e) => e.kind === "syntax").length;
+		const offlineCount = logEntries.filter((e) => e.kind === "connectivity").length;
+		const emptyCount = logEntries.filter((e) => e.kind === "empty").length;
+		const fatalCount = logEntries.filter((e) => e.kind === "fatal").length;
 		console.log(`  ${separator}`);
 		const parts = [`${newCount} new`, `${cacheCount} from cache`];
-		if (errorCount > 0) parts.push(`${errorCount} ${errorCount === 1 ? "error" : "errors"}`);
+		if (syntaxCount > 0) parts.push(`${syntaxCount} SQL ${syntaxCount === 1 ? "error" : "errors"}`);
+		if (offlineCount > 0) parts.push(`${offlineCount} degraded`);
+		if (emptyCount > 0) parts.push(`${emptyCount} empty`);
+		if (fatalCount > 0) parts.push(`${fatalCount} fatal ${fatalCount === 1 ? "error" : "errors"}`);
 		console.log(`  ${parts.join(", ")}. ${pc.dim(`${elapsed}s`)}`);
 		console.log("");
 	}
-	return [...cachedResults, ...freshResults].sort((a, b) => a.index - b.index).map((r) => r.schema);
+	return {
+		schemas: [...cachedResults, ...freshResults].sort((a, b) => a.index - b.index).map((r) => r.schema),
+		syntaxErrors,
+		fatalErrors
+	};
 }
 /**
 * Normalize query name by removing the .obo extension