@saptools/cf-hana 0.4.1 → 0.5.0

package/dist/cli.js

@@ -5,7 +5,7 @@ import { Command } from "commander";
 
 // src/config.ts
 var CLI_NAME = "cf-hana";
-var CLI_VERSION = "0.4.0";
+var CLI_VERSION = "0.5.0";
 var ENV_PREFIX = "CF_HANA";
 var DEFAULT_QUERY_TIMEOUT_MS = 6e4;
 var DEFAULT_CONNECT_TIMEOUT_MS = 6e4;
@@ -18,6 +18,27 @@ var DEFAULT_RESULT_TTL_MINUTES = 10080;
 var DEFAULT_RESULT_SEARCH_LIMIT = 20;
 var DEFAULT_MAX_RESULT_STORE_BYTES = 256 * 1024 * 1024;
 var MAX_RESULT_STORE_BYTES = resolveMaxResultStoreBytes();
+function resolvePositiveIntEnv(suffix, defaultValue) {
+  const raw = readEnv(envName(suffix));
+  if (raw === void 0) {
+    return defaultValue;
+  }
+  const parsed = Number(raw);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : defaultValue;
+}
+var DEFAULT_TUNNEL_FALLBACK_BUDGET_MS = resolvePositiveIntEnv(
+  "TUNNEL_FALLBACK_BUDGET_MS",
+  25e3
+);
+var DEFAULT_TUNNEL_CANDIDATE_TIMEOUT_MS = resolvePositiveIntEnv(
+  "TUNNEL_CANDIDATE_TIMEOUT_MS",
+  15e3
+);
+var DEFAULT_TUNNEL_MAX_CANDIDATES = resolvePositiveIntEnv("TUNNEL_MAX_CANDIDATES", 3);
+var DEFAULT_TUNNEL_KEEPALIVE_SECONDS = resolvePositiveIntEnv(
+  "TUNNEL_KEEPALIVE_SECONDS",
+  1200
+);
 function resolveMaxResultStoreBytes() {
   if (readEnv(envName("DRIVER")) !== "fake") {
     return DEFAULT_MAX_RESULT_STORE_BYTES;
@@ -1852,6 +1873,16 @@ async function cfEnvDirect(appName) {
   delete env["SAP_PASSWORD"];
   return await execWithRetries(bin, [...argsPrefix, "env", appName], env);
 }
+async function cfApps(ctx) {
+  return await runCf(["apps"], ctx);
+}
+async function cfAppsDirect() {
+  const { bin, argsPrefix } = resolveCfBin();
+  const env = { ...process.env };
+  delete env["SAP_EMAIL"];
+  delete env["SAP_PASSWORD"];
+  return await execWithRetries(bin, [...argsPrefix, "apps"], env);
+}
 async function readCurrentCfTarget() {
   const { bin, argsPrefix } = resolveCfBin();
   const env = { ...process.env };
@@ -1901,6 +1932,26 @@ function parseTargetFields(stdout) {
   }
   return map;
 }
+function parseCfAppsOutput(stdout) {
+  const lines = stdout.split(/\r?\n/);
+  const headerIndex = lines.findIndex((line) => /^\s*name\s+\S/i.test(line));
+  if (headerIndex === -1) {
+    return [];
+  }
+  const rows = [];
+  for (const line of lines.slice(headerIndex + 1)) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+    const [name, state] = trimmed.split(/\s+/);
+    if (name === void 0 || state === void 0) {
+      continue;
+    }
+    rows.push({ name, state });
+  }
+  return rows;
+}
 function formatCurrentCfAppSelector(target, appName) {
   const name = appName.trim();
   if (!name) {
@@ -2212,7 +2263,10 @@ async function resolveAppBindings(rawSelector, options) {
     source: "live",
     selectorSource: target.selectorSource,
     regionConfirmed: target.regionConfirmed,
-    selectorCanBePinned: target.selectorCanBePinned
+    selectorCanBePinned: target.selectorCanBePinned,
+    apiEndpoint: target.apiEndpoint,
+    orgName: target.orgName,
+    spaceName: target.spaceName
   };
 }
 async function readExplicitBindings(target, options) {
@@ -2278,6 +2332,7 @@ function toConnectionTarget(binding, role) {
 // src/driver/fake.ts
 import { appendFile } from "fs/promises";
 var catalogFailureInjected = false;
+var connectFailureInjectedOnce = false;
 function catalogObjects() {
   return [
     { SCHEMA_NAME: "APP_SCHEMA", OBJECT_NAME: "EXISTING_TABLE", OBJECT_TYPE: "TABLE" },
@@ -2486,10 +2541,28 @@ var FakeConnection = class {
     return this.closed;
   }
 };
+function maybeFailConnect() {
+  const mode = readEnv(envName("FAKE_FAIL_CONNECT"));
+  if (mode !== "once" && mode !== "always") {
+    return;
+  }
+  if (mode === "once" && connectFailureInjectedOnce) {
+    return;
+  }
+  connectFailureInjectedOnce = true;
+  const cause = Object.assign(
+    new Error("Could not connect to any host: [ fake-host:443 - forced fixture failure ]"),
+    { code: "EHDBOPENCONN" }
+  );
+  throw new CfHanaError("CONNECTION", `Failed to connect to HANA: ${cause.message}`, { cause });
+}
 function createFakeDriver() {
   return {
     name: "fake",
-    connect: (_params) => Promise.resolve(new FakeConnection())
+    connect: (_params) => {
+      maybeFailConnect();
+      return Promise.resolve(new FakeConnection());
+    }
   };
 }
 
@@ -2714,7 +2787,8 @@ async function connectHdb(params) {
     user: params.user,
     password: params.password,
     ca: params.certificate,
-    useTLS: true
+    useTLS: true,
+    ...params.servername === void 0 ? {} : { servername: params.servername }
   });
   await openClient(client, params.connectTimeoutMs);
   try {
@@ -2995,6 +3069,605 @@ function applyAutoLimit(sql, limit) {
   };
 }
 
+// src/tunnel/cache.ts
+import { createHash as createHash2 } from "crypto";
+import { mkdir as mkdir4, readdir as readdir2, readFile as readFile2, rename as rename2, rm as rm5, writeFile as writeFile3 } from "fs/promises";
+import { homedir as homedir4 } from "os";
+import { join as join6 } from "path";
+
+// src/tunnel/process.ts
+import { spawn } from "child_process";
+import { mkdtemp as mkdtemp2, rm as rm4 } from "fs/promises";
+import { connect as netConnect, createServer } from "net";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join5 } from "path";
+var PORT_POLL_INTERVAL_MS = 100;
+var DEFAULT_PORT_PROBE_TIMEOUT_MS = 500;
+function assertPositiveSafeInteger(label, value) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new CfHanaError("CONFIG", `${label} must be a positive integer`);
+  }
+}
+async function allocateLocalPort() {
+  return await new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      server.close(() => {
+        if (address === null || typeof address === "string") {
+          reject(new CfHanaError("CONNECTION", "Could not allocate a local port for a tunnel"));
+          return;
+        }
+        resolve(address.port);
+      });
+    });
+  });
+}
+function probeLocalPort(port, timeoutMs = DEFAULT_PORT_PROBE_TIMEOUT_MS) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const socket = netConnect({ host: "127.0.0.1", port });
+    const finish = (result) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(result);
+    };
+    const timer = setTimeout(() => {
+      finish(false);
+    }, timeoutMs);
+    timer.unref();
+    socket.once("connect", () => {
+      finish(true);
+    });
+    socket.once("error", () => {
+      finish(false);
+    });
+  });
+}
+function killTunnelProcess(pid) {
+  if (pid === void 0) {
+    return;
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+  }
+}
+async function withScopedCfSession(selectorSource, target, sapCredentials, work) {
+  if (selectorSource === "ambient") {
+    return await work();
+  }
+  if (sapCredentials === void 0) {
+    throw new CredentialsNotFoundError(
+      "SAP credentials are required to open a tunnel session for an explicit selector"
+    );
+  }
+  const cfHome = await mkdtemp2(join5(tmpdir2(), "saptools-cf-hana-tunnel-"));
+  try {
+    const ctx = { cfHome };
+    await cfApi(target.apiEndpoint, ctx);
+    await cfAuth(sapCredentials.email, sapCredentials.password, ctx);
+    await cfTargetSpace(target.orgName, target.spaceName, ctx);
+    return await work(ctx);
+  } finally {
+    await rm4(cfHome, { recursive: true, force: true });
+  }
+}
+function raceTunnelReadiness(child, localPort, boundMs, probePort, killProcess) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const timers = {};
+    const finish = (result) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearInterval(timers.poll);
+      clearTimeout(timers.deadline);
+      child.removeListener("exit", onAbort);
+      child.removeListener("error", onAbort);
+      if (result === void 0) {
+        killProcess(child.pid);
+      } else {
+        child.unref();
+      }
+      resolve(result);
+    };
+    function onAbort() {
+      finish();
+    }
+    child.on("exit", onAbort);
+    child.on("error", onAbort);
+    timers.poll = setInterval(() => {
+      void probePort(localPort).then((open) => {
+        if (open && child.pid !== void 0) {
+          finish({ localPort, pid: child.pid });
+        }
+      });
+    }, PORT_POLL_INTERVAL_MS);
+    timers.deadline = setTimeout(finish, boundMs);
+  });
+}
+async function spawnTunnel(params, deps = {}) {
+  assertPositiveSafeInteger("tunnel keepalive seconds", params.keepaliveSeconds);
+  const remainingMs = params.deadline - Date.now();
+  if (remainingMs <= 0) {
+    return void 0;
+  }
+  const boundMs = Math.min(remainingMs, params.candidateTimeoutMs);
+  const spawnProcess = deps.spawnProcess ?? spawn;
+  const probePort = deps.probePort ?? probeLocalPort;
+  const allocatePort = deps.allocatePort ?? allocateLocalPort;
+  const killProcess = deps.killProcess ?? killTunnelProcess;
+  const localPort = await allocatePort();
+  const { bin, argsPrefix } = resolveCfBin();
+  const forward = `${String(localPort)}:${params.hanaHost}:${String(params.hanaPort)}`;
+  const args = [
+    ...argsPrefix,
+    "ssh",
+    params.app,
+    "-L",
+    forward,
+    "-c",
+    `sleep ${String(params.keepaliveSeconds)}`
+  ];
+  const env = params.cfHome === void 0 ? { ...process.env } : { ...process.env, CF_HOME: params.cfHome };
+  const child = spawnProcess(bin, args, { detached: true, stdio: "ignore", env });
+  return await raceTunnelReadiness(child, localPort, boundMs, probePort, killProcess);
+}
+
+// src/tunnel/cache.ts
+var DEFAULT_ESTABLISHING_STALE_MS = 2 * DEFAULT_TUNNEL_FALLBACK_BUDGET_MS;
+var DEFAULT_POLL_INTERVAL_MS = 300;
+function isRecord3(value) {
+  return typeof value === "object" && value !== null;
+}
+function defaultIsProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return isRecord3(error) && error["code"] !== "ESRCH";
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+function tunnelCacheRoot(saptoolsRoot) {
+  return join6(saptoolsRoot ?? join6(homedir4(), ".saptools"), "cf-hana", "tunnel");
+}
+function tunnelCacheKey(host) {
+  return createHash2("sha256").update(host).digest("hex");
+}
+function tunnelCachePath(host, saptoolsRoot) {
+  return join6(tunnelCacheRoot(saptoolsRoot), `${tunnelCacheKey(host)}.json`);
+}
+function isOrgKey(value) {
+  return isRecord3(value) && typeof value["apiEndpoint"] === "string" && typeof value["orgName"] === "string";
+}
+function hasEstablishingFields(value) {
+  return value["status"] === "establishing" && typeof value["host"] === "string" && typeof value["startedAt"] === "string" && typeof value["ownerPid"] === "number" && isOrgKey(value["orgKey"]);
+}
+function hasReadyFields(value) {
+  return value["status"] === "ready" && typeof value["host"] === "string" && typeof value["localPort"] === "number" && typeof value["pid"] === "number" && typeof value["app"] === "string" && typeof value["expiresAt"] === "string" && isOrgKey(value["orgKey"]);
+}
+function isTunnelCacheRecord(value) {
+  return isRecord3(value) && value["version"] === 1 && (hasEstablishingFields(value) || hasReadyFields(value));
+}
+async function parseTunnelCacheFile(path) {
+  try {
+    const raw = JSON.parse(await readFile2(path, "utf8"));
+    return isTunnelCacheRecord(raw) ? raw : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function readTunnelCacheEntry(host, options = {}) {
+  const entry = await parseTunnelCacheFile(tunnelCachePath(host, options.saptoolsRoot));
+  return entry?.host === host ? entry : void 0;
+}
+function isExpired(entry, now) {
+  const expiresAt = Date.parse(entry.expiresAt);
+  return !Number.isFinite(expiresAt) || now.getTime() >= expiresAt;
+}
+async function isTunnelUsable(entry, options = {}) {
+  const isAlive = options.isProcessAlive ?? defaultIsProcessAlive;
+  if (!isAlive(entry.pid)) {
+    return false;
+  }
+  if (isExpired(entry, options.now?.() ?? /* @__PURE__ */ new Date())) {
+    return false;
+  }
+  const probePort = options.probePort ?? probeLocalPort;
+  return await probePort(entry.localPort);
+}
+function isEstablishingStale(entry, options) {
+  const isAlive = options.isProcessAlive ?? defaultIsProcessAlive;
+  if (!isAlive(entry.ownerPid)) {
+    return true;
+  }
+  const startedAt = Date.parse(entry.startedAt);
+  if (!Number.isFinite(startedAt)) {
+    return true;
+  }
+  const now = options.now?.() ?? /* @__PURE__ */ new Date();
+  const staleAfterMs = options.staleAfterMs ?? DEFAULT_ESTABLISHING_STALE_MS;
+  return now.getTime() - startedAt >= staleAfterMs;
+}
+async function writeEstablishingMarker(host, ownerPid, orgKey, options) {
+  const root = tunnelCacheRoot(options.saptoolsRoot);
+  await mkdir4(root, { recursive: true, mode: 448 });
+  const record = {
+    version: 1,
+    status: "establishing",
+    host,
+    startedAt: (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString(),
+    ownerPid,
+    orgKey
+  };
+  try {
+    await writeFile3(tunnelCachePath(host, options.saptoolsRoot), `${JSON.stringify(record)}
+`, {
+      encoding: "utf8",
+      mode: 384,
+      flag: "wx"
+    });
+    return true;
+  } catch (error) {
+    if (isRecord3(error) && error["code"] === "EEXIST") {
+      return false;
+    }
+    throw error;
+  }
+}
+async function claimEstablishing(host, ownerPid, orgKey, options = {}) {
+  if (await writeEstablishingMarker(host, ownerPid, orgKey, options)) {
+    return { outcome: "claimed" };
+  }
+  const existing = await readTunnelCacheEntry(host, options);
+  if (existing === void 0) {
+    return await writeEstablishingMarker(host, ownerPid, orgKey, options) ? { outcome: "claimed" } : { outcome: "wait" };
+  }
+  if (existing.status === "ready") {
+    return { outcome: "already-ready", record: existing };
+  }
+  if (!isEstablishingStale(existing, options)) {
+    return { outcome: "wait" };
+  }
+  await rm5(tunnelCachePath(host, options.saptoolsRoot), { force: true });
+  return await writeEstablishingMarker(host, ownerPid, orgKey, options) ? { outcome: "claimed" } : { outcome: "wait" };
+}
+async function waitForEstablishment(host, deadline, pollIntervalMs = DEFAULT_POLL_INTERVAL_MS, options = {}) {
+  for (; ; ) {
+    const entry = await readTunnelCacheEntry(host, options);
+    if (entry === void 0) {
+      return void 0;
+    }
+    if (entry.status === "ready") {
+      return entry;
+    }
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      return void 0;
+    }
+    await sleep(Math.min(pollIntervalMs, remainingMs));
+  }
+}
+async function finalizeEstablishingReady(host, record, options = {}) {
+  const root = tunnelCacheRoot(options.saptoolsRoot);
+  const path = tunnelCachePath(host, options.saptoolsRoot);
+  const tempPath = `${path}.tmp-${String(process.pid)}`;
+  const stored = { version: 1, status: "ready", host, ...record };
+  await mkdir4(root, { recursive: true, mode: 448 });
+  await rm5(tempPath, { force: true });
+  await writeFile3(tempPath, `${JSON.stringify(stored)}
+`, { encoding: "utf8", mode: 384 });
+  await rename2(tempPath, path);
+}
+async function finalizeEstablishingFailed(host, options = {}) {
+  await rm5(tunnelCachePath(host, options.saptoolsRoot), { force: true });
+}
+async function evictTunnelCache(host, options = {}) {
+  await rm5(tunnelCachePath(host, options.saptoolsRoot), { force: true });
+}
+function sameOrg(a, b) {
+  return a.apiEndpoint === b.apiEndpoint && a.orgName === b.orgName;
+}
+async function reapOneFile(path, currentOrgKey, options) {
+  const entry = await parseTunnelCacheFile(path);
+  if (entry === void 0) {
+    return;
+  }
+  const killProcess = options.killProcess ?? killTunnelProcess;
+  if (entry.status === "establishing") {
+    if (isEstablishingStale(entry, options)) {
+      await rm5(path, { force: true });
+    }
+    return;
+  }
+  const isAlive = options.isProcessAlive ?? defaultIsProcessAlive;
+  if (!isAlive(entry.pid)) {
+    await rm5(path, { force: true });
+    return;
+  }
+  const now = options.now?.() ?? /* @__PURE__ */ new Date();
+  if (isExpired(entry, now) || !sameOrg(entry.orgKey, currentOrgKey)) {
+    killProcess(entry.pid);
+    await rm5(path, { force: true });
+  }
+}
+async function reapStaleAndCrossOrgTunnels(currentOrgKey, options = {}) {
+  const root = tunnelCacheRoot(options.saptoolsRoot);
+  let files;
+  try {
+    files = await readdir2(root);
+  } catch {
+    return;
+  }
+  await Promise.all(
+    files.filter((file) => file.endsWith(".json")).map(async (file) => {
+      await reapOneFile(join6(root, file), currentOrgKey, options);
+    })
+  );
+}
+
+// src/tunnel/candidates.ts
+var RUNNING_STATE = "started";
+var VALID_APP_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function isValidAppName(name) {
+  return VALID_APP_NAME.test(name);
+}
+function discoveredAppNames(stdout, targetAppName) {
+  if (stdout === void 0) {
+    return [];
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const names = [];
+  for (const row of parseCfAppsOutput(stdout)) {
+    if (row.state !== RUNNING_STATE) {
+      continue;
+    }
+    if (row.name === targetAppName || seen.has(row.name)) {
+      continue;
+    }
+    if (!isValidAppName(row.name)) {
+      continue;
+    }
+    seen.add(row.name);
+    names.push(row.name);
+  }
+  return names;
+}
+function buildCandidateList(targetAppName, discoveredStdout, maxCandidates) {
+  const discovered = discoveredAppNames(discoveredStdout, targetAppName);
+  return [targetAppName, ...discovered.slice(0, maxCandidates)];
+}
+
+// src/tunnel/classifier.ts
+var CONNECT_TIMEOUT_MESSAGE = "HANA connection timed out";
+var OPEN_CONNECTION_CODE = "EHDBOPENCONN";
+var MAX_CAUSE_DEPTH = 5;
+function causeCode(value) {
+  return typeof value === "object" && value !== null ? value.code : void 0;
+}
+function causeOf(value) {
+  return typeof value === "object" && value !== null ? value.cause : void 0;
+}
+function hasOpenConnectionCause(cause, depth) {
+  if (depth > MAX_CAUSE_DEPTH) {
+    return false;
+  }
+  if (causeCode(cause) === OPEN_CONNECTION_CODE) {
+    return true;
+  }
+  return hasOpenConnectionCause(causeOf(cause), depth + 1);
+}
+function isConnectivityFailure(error) {
+  if (!(error instanceof CfHanaError)) {
+    return false;
+  }
+  if (error.code === "TIMEOUT") {
+    return error.message.includes(CONNECT_TIMEOUT_MESSAGE);
+  }
+  if (error.code !== "CONNECTION") {
+    return false;
+  }
+  return hasOpenConnectionCause(error.cause, 0);
+}
+
+// src/tunnel/fallback.ts
+var EXPIRY_SAFETY_MARGIN_MS = 3e4;
+function directParamsOf(config) {
+  return {
+    host: config.host,
+    port: config.port,
+    user: config.user,
+    password: config.password,
+    schema: config.schema,
+    certificate: config.certificate,
+    connectTimeoutMs: config.connectTimeoutMs
+  };
+}
+function tunneledParams(directParams, localPort) {
+  return { ...directParams, host: "127.0.0.1", port: localPort, servername: directParams.host };
+}
+function orgKeyOf(config) {
+  return { apiEndpoint: config.apiEndpoint, orgName: config.orgName };
+}
+function tunnelExpiryIso() {
+  return new Date(
+    Date.now() + DEFAULT_TUNNEL_KEEPALIVE_SECONDS * 1e3 - EXPIRY_SAFETY_MARGIN_MS
+  ).toISOString();
+}
+async function discardQuietly(work) {
+  await work.catch(() => {
+  });
+}
+async function tryReadyRecord(record, driver, config, directParams, cacheOptions) {
+  try {
+    const connection = await driver.connect(tunneledParams(directParams, record.localPort));
+    config.onTunnelStatus?.(`connected via SSH tunnel through ${record.app}`);
+    return connection;
+  } catch (error) {
+    if (isConnectivityFailure(error)) {
+      await discardQuietly(evictTunnelCache(config.host, cacheOptions));
+      return void 0;
+    }
+    throw error;
+  }
+}
+async function discoverAppsStdout(ctx) {
+  try {
+    return ctx === void 0 ? await cfAppsDirect() : await cfApps(ctx);
+  } catch {
+    return;
+  }
+}
+async function buildCandidates(config, ctx, hintApp) {
+  const stdout = await discoverAppsStdout(ctx);
+  const base = buildCandidateList(config.appName, stdout, DEFAULT_TUNNEL_MAX_CANDIDATES);
+  return hintApp === void 0 || base.includes(hintApp) ? base : [hintApp, ...base];
+}
+async function finalizeCandidateConnection(app, spawned, driver, config, directParams, cacheOptions) {
+  const readyRecord = {
+    localPort: spawned.localPort,
+    pid: spawned.pid,
+    app,
+    orgKey: orgKeyOf(config),
+    expiresAt: tunnelExpiryIso()
+  };
+  try {
+    const connection = await driver.connect(tunneledParams(directParams, spawned.localPort));
+    await discardQuietly(finalizeEstablishingReady(config.host, readyRecord, cacheOptions));
+    config.onTunnelStatus?.(`connected via SSH tunnel through ${app}`);
+    return connection;
+  } catch (error) {
+    if (isConnectivityFailure(error)) {
+      await discardQuietly(finalizeEstablishingFailed(config.host, cacheOptions));
+      killTunnelProcess(spawned.pid);
+      return void 0;
+    }
+    await discardQuietly(finalizeEstablishingReady(config.host, readyRecord, cacheOptions));
+    throw error;
+  }
+}
+async function tryCandidate(app, ctx, driver, config, directParams, deadline, overrides) {
+  const cacheOptions = overrides.cache ?? {};
+  config.onTunnelStatus?.(`trying to reach ${config.host} via app ${app}...`);
+  const claim = await claimEstablishing(config.host, process.pid, orgKeyOf(config), cacheOptions);
+  if (claim.outcome === "already-ready") {
+    return await tryReadyRecord(claim.record, driver, config, directParams, cacheOptions);
+  }
+  if (claim.outcome === "wait") {
+    const ready = await waitForEstablishment(config.host, deadline, void 0, cacheOptions);
+    return ready === void 0 ? void 0 : await tryReadyRecord(ready, driver, config, directParams, cacheOptions);
+  }
+  const spawned = await spawnTunnel(
+    {
+      cfHome: ctx?.cfHome,
+      app,
+      hanaHost: config.host,
+      hanaPort: config.port,
+      keepaliveSeconds: DEFAULT_TUNNEL_KEEPALIVE_SECONDS,
+      deadline,
+      candidateTimeoutMs: DEFAULT_TUNNEL_CANDIDATE_TIMEOUT_MS
+    },
+    overrides.process ?? {}
+  );
+  if (spawned === void 0) {
+    await discardQuietly(finalizeEstablishingFailed(config.host, cacheOptions));
+    return void 0;
+  }
+  return await finalizeCandidateConnection(app, spawned, driver, config, directParams, cacheOptions);
+}
+async function tryCachedTunnel(driver, config, directParams, cacheOptions) {
+  if (config.refreshTunnel) {
+    await discardQuietly(evictTunnelCache(config.host, cacheOptions));
+    return { connection: void 0, hintApp: void 0 };
+  }
+  const entry = await readTunnelCacheEntry(config.host, cacheOptions);
+  if (entry?.status !== "ready") {
+    return { connection: void 0, hintApp: void 0 };
+  }
+  if (!await isTunnelUsable(entry, cacheOptions)) {
+    await discardQuietly(evictTunnelCache(config.host, cacheOptions));
+    return { connection: void 0, hintApp: entry.app };
+  }
+  const connection = await tryReadyRecord(entry, driver, config, directParams, cacheOptions);
+  return { connection, hintApp: entry.app };
+}
+async function tryDirectConnect(driver, config, directParams) {
+  if (config.tunnelMode !== "auto") {
+    return { connection: void 0, directError: void 0 };
+  }
+  try {
+    return { connection: await driver.connect(directParams), directError: void 0 };
+  } catch (error) {
+    if (!isConnectivityFailure(error)) {
+      throw error;
+    }
+    return { connection: void 0, directError: error };
+  }
+}
+function buildExhaustionError(host, directError, candidates) {
+  if (directError !== void 0) {
+    return directError;
+  }
+  return new CfHanaError(
+    "CONNECTION",
+    `Could not establish an SSH tunnel to ${host} through any candidate app (tried: ${candidates.length > 0 ? candidates.join(", ") : "none"})`
+  );
+}
+async function runCandidateLoop(ctx, driver, config, directParams, deadline, hintApp, overrides) {
+  const candidatesTried = await buildCandidates(config, ctx, hintApp);
+  for (const app of candidatesTried) {
+    if (Date.now() >= deadline) {
+      break;
+    }
+    const connection = await tryCandidate(app, ctx, driver, config, directParams, deadline, overrides);
+    if (connection !== void 0) {
+      return { connection, candidatesTried };
+    }
+  }
+  return { connection: void 0, candidatesTried };
+}
+async function connectWithTunnelFallback(driver, config, overrides = {}) {
+  const directParams = directParamsOf(config);
+  const cacheOptions = overrides.cache ?? {};
+  await discardQuietly(reapStaleAndCrossOrgTunnels(orgKeyOf(config), cacheOptions));
+  const cached = await tryCachedTunnel(driver, config, directParams, cacheOptions);
+  if (cached.connection !== void 0) {
+    return cached.connection;
+  }
+  const direct = await tryDirectConnect(driver, config, directParams);
+  if (direct.connection !== void 0) {
+    return direct.connection;
+  }
+  const deadline = Date.now() + DEFAULT_TUNNEL_FALLBACK_BUDGET_MS;
+  const target = {
+    apiEndpoint: config.apiEndpoint,
+    orgName: config.orgName,
+    spaceName: config.spaceName
+  };
+  const loopResult = await withScopedCfSession(
+    config.selectorSource,
+    target,
+    config.sapCredentials,
+    (ctx) => runCandidateLoop(ctx, driver, config, directParams, deadline, cached.hintApp, overrides)
+  );
+  if (loopResult.connection !== void 0) {
+    return loopResult.connection;
+  }
+  throw buildExhaustionError(config.host, direct.directError, loopResult.candidatesTried);
+}
+
 // src/connection.ts
 function assertValidAutoLimit(value) {
   if (value !== false && (!Number.isSafeInteger(value) || value <= 0 || value >= Number.MAX_SAFE_INTEGER)) {
@@ -3088,15 +3761,7 @@ var Connection = class _Connection {
   driverConnection;
   config;
   static async open(driver, config) {
-    const driverConnection = await driver.connect({
-      host: config.host,
-      port: config.port,
-      user: config.user,
-      password: config.password,
-      schema: config.schema,
-      certificate: config.certificate,
-      connectTimeoutMs: config.connectTimeoutMs
-    });
+    const driverConnection = await connectWithTunnelFallback(driver, config);
     return new _Connection(driverConnection, config);
   }
   async query(sql, params, options) {
@@ -3378,6 +4043,31 @@ function toPoolOptions(options) {
   }
   return options.pool ?? {};
 }
+function buildConnectionConfig(resolved, target, options) {
+  const sapCredentials = readSapCredentials({ email: options.email, password: options.password });
+  return {
+    host: target.host,
+    port: target.port,
+    user: target.user,
+    password: target.password,
+    schema: target.schema,
+    certificate: target.certificate,
+    connectTimeoutMs: options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS,
+    queryTimeoutMs: options.queryTimeoutMs ?? DEFAULT_QUERY_TIMEOUT_MS,
+    readOnly: options.readOnly ?? false,
+    allowDestructive: options.allowDestructive ?? false,
+    autoLimit: options.autoLimit ?? DEFAULT_AUTO_LIMIT,
+    appName: resolved.appName,
+    orgName: resolved.orgName,
+    spaceName: resolved.spaceName,
+    apiEndpoint: resolved.apiEndpoint,
+    selectorSource: resolved.selectorSource,
+    tunnelMode: options.tunnel === true ? "always" : "auto",
+    refreshTunnel: options.refreshTunnel ?? false,
+    ...sapCredentials === void 0 ? {} : { sapCredentials },
+    ...options.onTunnelStatus === void 0 ? {} : { onTunnelStatus: options.onTunnelStatus }
+  };
+}
 function toSelectedBindingInfo(bindings, selected) {
   const availableBindingNames = bindings.flatMap(
     (binding) => binding.name === void 0 ? [] : [binding.name]
@@ -3405,19 +4095,7 @@ var HanaClient = class _HanaClient {
     const bindingInfo = toSelectedBindingInfo(resolved.bindings, binding);
     const target = toConnectionTarget(binding, role);
     const driver = createDriver();
-    const config = {
-      host: target.host,
-      port: target.port,
-      user: target.user,
-      password: target.password,
-      schema: target.schema,
-      certificate: target.certificate,
-      connectTimeoutMs: options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS,
-      queryTimeoutMs: options.queryTimeoutMs ?? DEFAULT_QUERY_TIMEOUT_MS,
-      readOnly: options.readOnly ?? false,
-      allowDestructive: options.allowDestructive ?? false,
-      autoLimit: options.autoLimit ?? DEFAULT_AUTO_LIMIT
-    };
+    const config = buildConnectionConfig(resolved, target, options);
     const poolOptions = toPoolOptions(options);
     const info = {
       selector: resolved.selector,
@@ -3614,7 +4292,7 @@ async function connect(selector, options) {
 }
 
 // src/cli-results.ts
-import { writeFile as writeFile4 } from "fs/promises";
+import { writeFile as writeFile5 } from "fs/promises";
 
 // src/result-inspect.ts
 function assertPositiveInteger(name, value) {
@@ -3886,19 +4564,19 @@ function searchResultSession(session, searchTerm, options) {
 
 // src/result-store.ts
 import { randomBytes } from "crypto";
-import { mkdir as mkdir4, readFile as readFile2, readdir as readdir2, rename as rename2, rm as rm4, writeFile as writeFile3 } from "fs/promises";
-import { homedir as homedir4 } from "os";
-import { join as join5 } from "path";
+import { mkdir as mkdir5, readFile as readFile3, readdir as readdir3, rename as rename3, rm as rm6, writeFile as writeFile4 } from "fs/promises";
+import { homedir as homedir5 } from "os";
+import { join as join7 } from "path";
 var RESULT_REF_PATTERN = /^q[0-9a-f]{8}$/;
 var MANIFEST_FILE_NAME = "manifest.json";
 function resultsRoot(saptoolsRoot) {
-  return join5(saptoolsRoot ?? join5(homedir4(), ".saptools"), "cf-hana", "results");
+  return join7(saptoolsRoot ?? join7(homedir5(), ".saptools"), "cf-hana", "results");
 }
 function sessionDirectory(ref, saptoolsRoot) {
-  return join5(resultsRoot(saptoolsRoot), ref);
+  return join7(resultsRoot(saptoolsRoot), ref);
 }
 function manifestPath(ref, saptoolsRoot) {
-  return join5(sessionDirectory(ref, saptoolsRoot), MANIFEST_FILE_NAME);
+  return join7(sessionDirectory(ref, saptoolsRoot), MANIFEST_FILE_NAME);
 }
 function encodeCell(value) {
   if (value === null) {
@@ -3997,11 +4675,11 @@ function toStoredSession(input, ref, now) {
     result: encodeResult(input.result)
   };
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isStoredSession(value) {
-  if (!isRecord3(value) || !isRecord3(value["result"]) || !isRecord3(value["info"])) {
+  if (!isRecord4(value) || !isRecord4(value["result"]) || !isRecord4(value["info"])) {
     return false;
   }
   const result = value["result"];
@@ -4009,7 +4687,7 @@ function isStoredSession(value) {
 }
 async function readStoredSession(path) {
   try {
-    const parsed = JSON.parse(await readFile2(path, "utf8"));
+    const parsed = JSON.parse(await readFile3(path, "utf8"));
     return isStoredSession(parsed) ? parsed : void 0;
   } catch (error) {
     if (error.code === "ENOENT") {
@@ -4028,7 +4706,7 @@ function toSession(stored, saptoolsRoot) {
 }
 async function listSessionRefs(saptoolsRoot) {
   try {
-    const entries = await readdir2(resultsRoot(saptoolsRoot), { withFileTypes: true });
+    const entries = await readdir3(resultsRoot(saptoolsRoot), { withFileTypes: true });
     return entries.filter((entry) => entry.isDirectory() && RESULT_REF_PATTERN.test(entry.name)).map((entry) => entry.name);
   } catch (error) {
     if (error.code === "ENOENT") {
@@ -4049,17 +4727,17 @@ async function createResultSession(input, options = {}) {
   const root = resultsRoot(options.saptoolsRoot);
   const finalDirectory = sessionDirectory(ref, options.saptoolsRoot);
   const tempDirectory = `${finalDirectory}.tmp-${process.pid.toString()}`;
-  await mkdir4(root, { recursive: true, mode: 448 });
-  await rm4(tempDirectory, { recursive: true, force: true });
-  await mkdir4(tempDirectory, { mode: 448 });
+  await mkdir5(root, { recursive: true, mode: 448 });
+  await rm6(tempDirectory, { recursive: true, force: true });
+  await mkdir5(tempDirectory, { mode: 448 });
   try {
-    await writeFile3(join5(tempDirectory, MANIFEST_FILE_NAME), serialized, {
+    await writeFile4(join7(tempDirectory, MANIFEST_FILE_NAME), serialized, {
       encoding: "utf8",
       mode: 384
     });
-    await rename2(tempDirectory, finalDirectory);
+    await rename3(tempDirectory, finalDirectory);
   } catch (error) {
-    await rm4(tempDirectory, { recursive: true, force: true });
+    await rm6(tempDirectory, { recursive: true, force: true });
     throw error;
   }
   return toSession(stored, options.saptoolsRoot);
@@ -4102,7 +4780,7 @@ async function pruneResultSessions(options = {}) {
   for (const ref of refs) {
     const stored = await readStoredSession(manifestPath(ref, options.saptoolsRoot));
     if (stored === void 0 || Date.parse(stored.expiresAt) <= now) {
-      await rm4(sessionDirectory(ref, options.saptoolsRoot), { recursive: true, force: true });
+      await rm6(sessionDirectory(ref, options.saptoolsRoot), { recursive: true, force: true });
       removed += 1;
     }
   }
@@ -4112,7 +4790,7 @@ async function clearResultSessions(options = {}) {
   const refs = await listSessionRefs(options.saptoolsRoot);
   await Promise.all(
     refs.map(async (ref) => {
-      await rm4(sessionDirectory(ref, options.saptoolsRoot), { recursive: true, force: true });
+      await rm6(sessionDirectory(ref, options.saptoolsRoot), { recursive: true, force: true });
     })
   );
   return refs.length;
@@ -4282,7 +4960,7 @@ async function runExport(ref, options) {
   }
   const session = await readResultSession(ref);
   const selected = selectResultCell(session, options.row, options.column);
-  await writeFile4(options.output, cellExportValue(selected.value, selected.typeName), {
+  await writeFile5(options.output, cellExportValue(selected.value, selected.typeName), {
     mode: 384
   });
   print(`wrote=${options.output}`);
@@ -4350,8 +5028,12 @@ function printResolvedTarget(info) {
 `
   );
 }
+function printTunnelStatus(message) {
+  process.stderr.write(`${CLI_NAME}: ${message}
+`);
+}
 async function connectForCli(selector, options) {
-  const client = await connect(selector, options);
+  const client = await connect(selector, { ...options, onTunnelStatus: printTunnelStatus });
   printResolvedTarget(client.info);
   return client;
 }
@@ -4416,6 +5098,8 @@ function toConnectOptions(opts) {
     readOnly: opts.readOnly,
     allowDestructive: opts.allowDestructive,
     autoLimit: opts.autoLimit ? opts.limit ?? DEFAULT_AUTO_LIMIT : false,
+    tunnel: opts.tunnel,
+    refreshTunnel: opts.refreshTunnel,
     ...opts.binding === void 0 ? {} : { bindingName: opts.binding },
     ...opts.bindingIndex === void 0 ? {} : { bindingIndex: opts.bindingIndex },
     ...opts.timeout === void 0 ? {} : { queryTimeoutMs: opts.timeout, connectTimeoutMs: opts.timeout }
@@ -4512,7 +5196,15 @@ function formatInfo(info) {
   ].join("\n");
 }
 function withConnectionOptions(command) {
-  return command.option("--refresh", "deprecated compatibility flag; binding discovery is already live", false).option("--role <role>", "HANA user role: runtime or hdi", "runtime").option("--binding <name>", "select a HANA binding by service name").option("--binding-index <n>", "select a HANA binding by index", parseIntOption2).option("--read-only", "block every DML and DDL statement", false).option("--allow-destructive", "permit destructive statements", false).option("--timeout <ms>", "connection and query timeout in milliseconds", parseIntOption2).option("--limit <n>", "row cap auto-applied to bare SELECT statements", parseIntOption2).option("--no-auto-limit", "disable the automatic SELECT row cap").option("--refresh-metadata", "bypass the 30-minute table/view metadata suggestion cache", false);
+  return command.option("--refresh", "deprecated compatibility flag; binding discovery is already live", false).option("--role <role>", "HANA user role: runtime or hdi", "runtime").option("--binding <name>", "select a HANA binding by service name").option("--binding-index <n>", "select a HANA binding by index", parseIntOption2).option("--read-only", "block every DML and DDL statement", false).option("--allow-destructive", "permit destructive statements", false).option("--timeout <ms>", "connection and query timeout in milliseconds", parseIntOption2).option("--limit <n>", "row cap auto-applied to bare SELECT statements", parseIntOption2).option("--no-auto-limit", "disable the automatic SELECT row cap").option("--refresh-metadata", "bypass the 30-minute table/view metadata suggestion cache", false).option(
+    "--tunnel",
+    "skip the direct connection attempt and connect via an SSH tunnel immediately",
+    false
+  ).option(
+    "--refresh-tunnel",
+    "bypass a cached/live SSH tunnel and force a fresh establishment attempt",
+    false
+  );
 }
 function withFormattedConnectionOptions(command) {
   return withConnectionOptions(command).option(