@saptools/cf-hana 0.4.1 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,70 @@
 
 <!-- cspell:words VARCHAR -->
 
+## 0.5.1 - 2026-07-25
+
+- **Security fix:** a `WITH`-prefixed write (e.g. `WITH x AS (...) DELETE
+  FROM ...`) and a bare `CALL <procedure>()` both previously slipped past
+  the `--read-only` and destructive-statement guards entirely — the former
+  was always classified as a harmless `SELECT` regardless of what it
+  actually did, and the latter was never classified as destructive at all,
+  so it ran with no `--allow-destructive` confirmation even in the default
+  (non-read-only) mode. Both are now correctly classified and guarded.
+  Anyone relying on `--read-only` or the destructive-statement guard as a
+  hard trust boundary should treat this as the release that closes that gap.
+  The automatic pre-write backup now also correctly recognizes and protects
+  a `WITH`-prefixed `UPDATE`/`DELETE`/`UPSERT`/`MERGE`, matching what a
+  non-`WITH` equivalent write already produced.
+- Disable SAP HANA Cloud's reactive mid-auth redirect on every connection
+  (direct and tunneled): on a genuine multi-node HANA Cloud instance, the
+  server can redirect an already-established connection to an internal
+  per-node hostname that isn't reachable outside SAP's own network, which
+  previously defeated the SSH-tunnel fallback by silently abandoning the
+  tunnel for a fresh, untunneled connection that failed the same way the
+  original direct connection did.
+- Fix the SSH-tunnel fallback's candidate discovery calling `cf apps`
+  (measured at up to ~20s against a large space) before ever trying the
+  already-known target app or a cached "last worked" app, which could
+  starve the entire shared fallback budget before a working candidate got a
+  chance. Known candidates are now always tried first; `cf apps` is only
+  called if none of them work, and is bounded to whatever budget remains
+  rather than retried on its own separate timeout/retry policy.
+- Cap the direct-connect attempt's own timeout to the tunnel fallback's
+  per-candidate ceiling whenever a fallback is available, so a silently
+  hanging (rather than actively refused) direct connection can no longer
+  consume its full configured timeout before the tunnel path gets a chance
+  — lowering the documented worst-case latency from ~85s to ~40s.
+- Fix `--refresh-tunnel` leaking the SSH process it superseded; the old
+  tunnel is now terminated instead of running until its keepalive elapses.
+- Surface a failed tunnel candidate's actual stderr (e.g. "SSH disabled for
+  this app") via the existing connectivity status output on stderr, instead
+  of discarding it silently.
+- Fix a freshly-established or reused tunnel being cached as usable even
+  when its own post-connect setup failed in a way that looked like a
+  dropped connection rather than a genuine, actionable HANA rejection.
+- Bound how long a process waits for another concurrent invocation to
+  finish establishing the same host's tunnel, so the entire shared deadline
+  can no longer be spent waiting on a leader whose owning process has
+  already died.
+
+## 0.5.0 - 2026-07-25
+
+- Add an SSH-tunnel fallback for HANA Cloud hosts unreachable directly (e.g.
+  IP-allowlisted landscapes): on a classified connectivity failure, discover
+  a jump-host app in the same org/space via `cf apps`, open a local
+  `cf ssh -L` port-forward, and retry through it. Zero behavior change when
+  the direct connection succeeds.
+- Add `--tunnel` to skip the direct attempt and connect via a tunnel
+  immediately, and `--refresh-tunnel` to bypass a cached/live tunnel and
+  force a fresh attempt. No disable switch: the fallback can only help or
+  no-op, and rethrows the original connection error unchanged on total
+  failure.
+- Persist and reuse the live tunnel under `~/.saptools/cf-hana/tunnel/`
+  across every connection this CLI's pool opens and across separate
+  invocations run in a row against the same host, with a race-free
+  concurrent-establishment marker and automatic reaping of dead or
+  cross-org tunnels.
+
 ## 0.4.0 - 2026-07-14
 
 - Back up `REPLACE` and matched `MERGE INTO` pre-images, cap backup size, and

package/README.md

@@ -105,7 +105,8 @@ cf-hana result  <command>                   Inspect saved query refs
 
 Common options: `--refresh` (deprecated compatibility flag; binding discovery is already live), `--role <runtime|hdi>`, `--binding <name>` /
 `--binding-index <n>`, `--timeout <ms>`, `--read-only`, `--allow-destructive`,
-`--limit <n>`, `--no-auto-limit`. The `query` command also accepts
+`--limit <n>`, `--no-auto-limit`, `--tunnel`, `--refresh-tunnel` (see
+[Connectivity fallback](#connectivity-fallback)). The `query` command also accepts
 `--param <value>` (repeatable), `--cell-limit <n>`, `--save`, `--no-auto-save`,
 `--format <table|json|json-compact|csv>`, `--result-ttl-minutes <n>`, and
 `--refresh-metadata`. `tables` and `columns` support the same four format values.
@@ -351,6 +352,95 @@ mode `0600`.
 The guard is a convenience, not a security control: always pass values as bound
 parameters.
 
+## Connectivity fallback
+
+HANA Cloud instances are frequently IP-allowlisted to only accept connections
+from inside the same Cloud Foundry landscape. When a direct connection fails
+in a way that means the initial socket could never be established — not an
+authentication, privilege, or query failure — `cf-hana` can retry through an
+SSH port-forward opened via `cf ssh` against another app in the same org/space,
+which usually can reach the host even when your machine cannot.
+
+- **`auto` (default)**: tries the direct connection first, with zero added
+  behavior when it succeeds. Only a classified connectivity failure triggers
+  the fallback: discover a jump-host app (the target app itself, then a few
+  other started apps via `cf apps`), open a local port-forward, and retry
+  through `127.0.0.1`.
+- **`--tunnel`**: skips the direct attempt and connects via a tunnel
+  immediately — for a host already known to be unreachable directly, so you
+  are not paying the connect-timeout cost (up to 60s) on every invocation.
+- **`--refresh-tunnel`**: bypasses a cached/live tunnel and forces a fresh
+  establishment attempt.
+
+There is deliberately no flag to disable this capability: a tunnel attempt
+only ever engages after a direct failure (or when explicitly requested via
+`--tunnel`), and on total failure it rethrows the original connection error
+unchanged, so it can only help or no-op.
+
+The live tunnel is reused — both across every connection this CLI's own pool
+opens in one invocation, and across separate `cf-hana` invocations run in a
+row against the same host (this CLI's realistic dominant usage pattern, e.g.
+an AI agent running several queries back to back) — instead of re-negotiating
+SSH on every single command. State lives at `~/.saptools/cf-hana/tunnel/`
+(mode `0700`/`0600`, no credentials). A cached tunnel is closed immediately,
+regardless of its remaining lifetime, the moment a later invocation targets a
+different Cloud Foundry org — a different client's landscape never keeps an
+unattended live SSH path open just because its keepalive has not lapsed.
+
+In the worst case (a silently-dropping network path, so the direct attempt
+runs its full connect timeout, and no candidate app works either), `auto`
+mode takes roughly 15s (direct, capped once a tunnel fallback is available —
+see below) + 25s (tunnel budget) ≈ 40s before surfacing a final error —
+bounded and predictable, not open-ended. Use `--tunnel` to skip the direct
+cost entirely for a host you already know is unreachable.
+
+Whenever a tunnel fallback is available at all (`auto` mode, the default),
+the direct attempt's own timeout is capped at the tunnel side's own
+per-candidate ceiling (15s by default) even if a longer timeout is
+configured — a silently-hanging (rather than actively refused) direct
+connection would otherwise consume its entire configured timeout before the
+tunnel path got a chance at all. This only ever shortens an
+otherwise-hanging attempt; it never affects a host that refuses quickly, or
+a configured timeout that is already shorter.
+
+`cf-hana` also disables SAP HANA Cloud's reactive mid-auth redirect (used
+for per-node/pod locality routing) on every connection, direct or tunneled:
+without this, a multi-node HANA Cloud instance can redirect an
+already-established connection to a different internal hostname that isn't
+reachable outside SAP's own network, silently abandoning a working SSH
+tunnel for a fresh, untunneled connection that fails for the same reason the
+original direct connection did. The original bound host is always a real,
+working endpoint for your binding, so this has no effect on which schema,
+user, or data you reach.
+
+### Known limitations
+
+- **Cross-org reaper and concurrent processes.** Every connection attempt
+  closes any cached tunnel tagged for a different Cloud Foundry org than the
+  current target, regardless of remaining lifetime — intentional hygiene so
+  switching orgs never leaves a stale tunnel open. On a shared machine, this
+  can also close another, unrelated, concurrently-running invocation's
+  active tunnel to a different org; there is no portable, low-cost way to
+  detect "is this port actively in use by someone else" from outside that
+  TCP session.
+- **Stale-tunnel reaping trusts the recorded pid.** The reaper terminates a
+  dead or expired tunnel's process by its recorded pid, with no additional
+  identity check (e.g. confirming the pid still refers to a `cf ssh`
+  process). On a long-uptime machine, pid reuse could in principle target an
+  unrelated process; this is a narrow race not worth a platform-specific
+  check for.
+- **Programmatic (non-CLI) pool usage can strand idle connections.** The
+  connection pool reuses the most-recently-released idle connection first
+  (LIFO); a long-lived process that opens a burst of connections and then
+  settles into serial one-at-a-time use can leave earlier connections
+  idle-but-unreaped for the pool's lifetime. The CLI itself always drains
+  its pool at the end of every command, so this only affects long-lived
+  programmatic use of the library.
+- **Pre-write backups are never pruned.** Unlike SQL history (5-day
+  retention) and saved query results (TTL plus `result prune`/`result
+  clear`), files under `~/.saptools/cf-hana/backups/` accumulate
+  indefinitely with no retention policy or cleanup command.
+
 ## Requirements
 
 - Node.js >= 20.