[SEA-NodeJS] feat(kernel): proxy + socketTimeout ConnectionOptions on the kernel backend (#431)

* [SEA-NodeJS] feat(kernel): support the explicit proxy ConnectionOption on the kernel backend

Map the public Thrift-shaped `ConnectionOptions.proxy`
(`{protocol, host, port, auth}`) onto the kernel napi binding's
`proxy?: string`, so the SAME proxy connection option that works on the
Thrift backend now also routes kernel/SEA traffic through a proxy.

`buildKernelProxyOptions` composes `protocol://[user:pass@]host:port`,
percent-encoding any `auth.{username,password}` into the URL userinfo so
credentials with reserved characters survive; the kernel parses the
userinfo off and applies it as proxy basic-auth. Wired into
`buildKernelConnectionOptions` alongside the TLS / HTTP option builders.

The regenerated napi contract (`native/kernel/index.d.ts`) carries the
new `proxy?: string` and `socketTimeoutMs?: number` fields exposed by the
kernel PR (databricks/databricks-sql-kernel#129).

Note: env-var proxying (`HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`) already
worked on the kernel backend (reqwest honours it natively); this adds the
*programmatic* path for callers who cannot set process env vars.

Verified end-to-end via mitmproxy against a live serverless warehouse:
explicit `proxy` option (no env var) routes all SEA calls through the
proxy; a dead proxy port fails the connection (proving the proxy is used).

Co-authored-by: Isaac
Signed-off-by: Madhavendra Rathore <madhavendra.rathore@databricks.com>

* [SEA-NodeJS] feat(kernel): map the socketTimeout ConnectionOption onto the kernel

The kernel napi binding exposes `socketTimeoutMs` (kernel
`HttpConfig::request_timeout` / reqwest `Client::timeout`, kernel #129).
Map the public `socketTimeout` ConnectionOption (ms) onto it in
`buildKernelHttpOptions`, so the per-connection read timeout works on the
kernel backend just like the Thrift path.

Only a positive value is forwarded: `socketTimeout: 0` means "disabled /
wait indefinitely" on Thrift, but forwarding `0` would make reqwest time
out immediately, so it is omitted (kernel keeps its large default).

Verified directly against a live serverless warehouse: `socketTimeout: 1`
makes a SEA request time out.

Co-authored-by: Isaac
Signed-off-by: Madhavendra Rathore <madhavendra.rathore@databricks.com>

* [SEA-NodeJS] refactor(kernel): pass proxy to the kernel as a structured object

Change the kernel proxy mapping from a flattened URL string to the
structured napi `proxy` object (kernel #129), mirroring the kernel's
internal ProxyConfig: `{ url, username?, password?, bypassHosts? }`.

`buildKernelProxyOptions` now composes `url` from `protocol://host:port`
(no embedded credentials) and forwards `auth.{username,password}` as
separate basic-auth fields — eliminating the URL percent-encoding of
credentials. The `noProxy` host list is forwarded as `bypassHosts`
(previously unexpressible through the URL-string form).

Regenerated napi contract (native/kernel/index.d.ts) carries the new
`ProxyInput` object type.

Verified via mitmproxy (HttpProxyTests, SEA leg): http / https /
proxy-with-auth all route through the proxy and the query succeeds.

Co-authored-by: Isaac
Signed-off-by: Madhavendra Rathore <madhavendra.rathore@databricks.com>

* chore(kernel): bump KERNEL_REV to kernel v0.2.0 (0d46716)

Point the bundled kernel binding at the latest kernel main — the v0.2.0
beta release (databricks/databricks-sql-kernel@0d46716), which includes
the merged proxy + per-connection socketTimeout napi surface (#129) this
PR maps onto, plus the query-tags wire support (#150). The kernel-e2e CI
gate builds the napi from this SHA.

Verified: proxy routes through mitmproxy and SELECT round-trips on the
v0.2.0 binding.

Co-authored-by: Isaac
Signed-off-by: Madhavendra Rathore <madhavendra.rathore@databricks.com>

---------

Signed-off-by: Madhavendra Rathore <madhavendra.rathore@databricks.com>

Author: msrathore-db

KERNEL_REV

@@ -1 +1 @@
-34b4c202cc127021c923903d59c841daa2b44fef
+0d46716c466897148dfc1d2976ff03bdf097998c

lib/kernel/KernelAuth.ts

@@ -190,11 +190,32 @@ export interface KernelTlsOptions {
  */
 export interface KernelHttpOptions {
   customHeaders?: Array<{ name: string; value: string }>;
+  socketTimeoutMs?: number;
+}
+
+/**
+ * HTTP(S) proxy forwarded to the napi binding's `ConnectionOptions.proxy`
+ * (kernel `ProxyConfig`). The public `ConnectionOptions.proxy` is the
+ * Thrift-shaped `{protocol, host, port, auth}`; `buildKernelProxyOptions`
+ * maps it onto the kernel's structured proxy input — `url` composed from
+ * `protocol://host:port`, with `auth.{username,password}` forwarded as
+ * separate basic-auth fields (NOT embedded in the URL, so no percent-encoding
+ * footgun) and the `noProxy` host list forwarded as `bypassHosts`. The same
+ * connection option therefore works identically on both backends.
+ */
+export interface KernelProxyOptions {
+  proxy?: {
+    url: string;
+    username?: string;
+    password?: string;
+    bypassHosts?: string;
+  };
 }
 
 export type KernelNativeConnectionOptions = KernelSessionDefaults &
   KernelTlsOptions &
   KernelHttpOptions &
+  KernelProxyOptions &
   (
     | {
         hostName: string;
@@ -401,7 +422,7 @@ function validateHeaderToken(kind: 'name' | 'value', headerName: string, token:
 }
 
 export function buildKernelHttpOptions(options: ConnectionOptions): KernelHttpOptions {
-  const { customHeaders, userAgentEntry } = options;
+  const { customHeaders, userAgentEntry, socketTimeout } = options;
 
   const headers: Array<{ name: string; value: string }> = [];
   if (customHeaders) {
@@ -423,7 +444,18 @@ export function buildKernelHttpOptions(options: ConnectionOptions): KernelHttpOp
   // Python connector's unconditional `base_headers` append.
   headers.push({ name: 'User-Agent', value: buildUserAgentString(userAgentEntry) });
 
-  return { customHeaders: headers };
+  const http: KernelHttpOptions = { customHeaders: headers };
+  // Per-connection socket read timeout (ms). The public `socketTimeout`
+  // ConnectionOption maps onto the kernel napi `socketTimeoutMs`
+  // (kernel `HttpConfig::request_timeout` / reqwest `Client::timeout`).
+  // Only forward a POSITIVE value: `socketTimeout: 0` means "disabled / wait
+  // indefinitely" on the Thrift path, but forwarding `0` would make reqwest
+  // time out immediately, so we omit it and let the kernel keep its (large)
+  // default — preserving the "effectively no idle timeout" semantics.
+  if (typeof socketTimeout === 'number' && socketTimeout > 0) {
+    http.socketTimeoutMs = socketTimeout;
+  }
+  return http;
 }
 
 /**
@@ -514,6 +546,32 @@ export function buildKernelRetryOptions(config: {
   return out;
 }
 
+/**
+ * Map the public `ConnectionOptions.proxy` (`{protocol, host, port, auth}` —
+ * the same shape the Thrift backend accepts) onto the kernel's structured napi
+ * proxy input. The `url` is composed from `protocol://host:port` (no embedded
+ * credentials); `auth.{username,password}` are forwarded as separate
+ * basic-auth fields (the kernel applies them via reqwest `Proxy::basic_auth`),
+ * avoiding any URL percent-encoding footgun. The `noProxy` host list (a driver
+ * option, not on the published `.d.ts`) is forwarded as `bypassHosts`. The
+ * kernel accepts only `http://` / `https://`; a SOCKS protocol surfaces a clear
+ * kernel error at connect (reqwest SOCKS support is not compiled in).
+ */
+export function buildKernelProxyOptions(options: ConnectionOptions): KernelProxyOptions {
+  const { proxy } = options;
+  if (!proxy) {
+    return {};
+  }
+  const { noProxy } = options as ConnectionOptions & { noProxy?: string };
+  const out: NonNullable<KernelProxyOptions['proxy']> = {
+    url: `${proxy.protocol}://${proxy.host}:${proxy.port}`,
+  };
+  if (proxy.auth?.username !== undefined) out.username = proxy.auth.username;
+  if (proxy.auth?.password !== undefined) out.password = proxy.auth.password;
+  if (typeof noProxy === 'string' && noProxy.length > 0) out.bypassHosts = noProxy;
+  return { proxy: out };
+}
+
 export function buildKernelConnectionOptions(options: ConnectionOptions): KernelNativeConnectionOptions {
   const { authType } = options as { authType?: string };
 
@@ -523,7 +581,8 @@ export function buildKernelConnectionOptions(options: ConnectionOptions): Kernel
     intervalsAsString: boolean;
     maxConnections?: number;
   } & KernelTlsOptions &
-    KernelHttpOptions = {
+    KernelHttpOptions &
+    KernelProxyOptions = {
     hostName: options.host,
     httpPath: prependSlash(options.path),
     // Match the NodeJS Thrift driver, which surfaces INTERVAL columns as
@@ -539,6 +598,8 @@ export function buildKernelConnectionOptions(options: ConnectionOptions): Kernel
     ...buildKernelTlsOptions(options),
     // HTTP headers (caller `customHeaders` + composed `User-Agent`).
     ...buildKernelHttpOptions(options),
+    // HTTP(S) proxy — the same `ConnectionOptions.proxy` the Thrift path uses.
+    ...buildKernelProxyOptions(options),
   };
 
   // kernel-only pool sizing; read via cast to match how this function reads the