From f9cec834aba9813cfd46d885c5c419bfdf403f88 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Wed, 18 Nov 2026 03:07:52 +0000 Subject: [PATCH 1/4] feat(kernel): expose HTTP/2 negotiation control Signed-off-by: Aakash Saravanan --- CHANGELOG.md | 2 ++ CONNECTION_PARAMETERS.md | 8 ++++++++ lib/contracts/IDBSQLClient.ts | 7 +++++++ lib/kernel/KernelAuth.ts | 7 +++++++ native/kernel/index.d.ts | 2 ++ tests/unit/kernel/connectionOptions.test.ts | 19 +++++++++++++++++++ tests/unit/kernel/execution.test.ts | 2 ++ 7 files changed, 47 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 938983a3..28708476 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ ## Unreleased +- Add kernel-only `enableHttp2`: HTTPS negotiates HTTP/2 with HTTP/1.1 fallback; set `enableHttp2: false` to force HTTP/1.1 for all kernel-owned HTTPS requests. + - The Thrift token federation exchange (`enableTokenFederation`) now goes through the connection's agent, so `proxy`, `checkServerCertificate`, `customCaCert` and `clientCert`/`clientKey` apply to it. Previously it connected directly with Node's default agent, so behind a required proxy the exchange failed and the driver fell back to the original token. (#611) - Kernel backend: a failed status poll while waiting for a statement (a `runAsync: true` statement, or a default execution that outlives the server's inline wait) and a failed result fetch in `hasMoreRows()` now throw the mapped driver error, such as `HiveDriverError: HTTP 500: Internal Server Error` once retries on HTTP 5xx run out, instead of a raw `Error` whose message is the internal `__databricks_error__:{...}` envelope. As in `fetchChunk()`, a failed fetch in `hasMoreRows()` also closes the statement. (#608) - Honor `cloudFetchConcurrentDownloads` when opening kernel sessions, with a default window of 16 and explicit chunk-setting overrides. Values other than positive safe integers raise `HiveDriverError` at session open. diff --git a/CONNECTION_PARAMETERS.md b/CONNECTION_PARAMETERS.md index edba6002..4a738852 100644 --- a/CONNECTION_PARAMETERS.md +++ b/CONNECTION_PARAMETERS.md @@ -102,6 +102,14 @@ disabling verification. | `clientKey` | `Buffer \| string` | ✅ | ✅ | — | Public mTLS private key. Must be paired with `clientCert`; PKCS#8 is recommended for Kernel portability. | | `clientCertPem` / `clientKeyPem` (internal) | `Buffer \| string` | ❌ | ✅ | — | Runtime-only Kernel aliases for the public mTLS pair. They take precedence over `clientCert`/`clientKey` when both pairs are supplied. | +## HTTP protocol + +For kernel connections, `enableHttp2` is an optional boolean that defaults to +`true` in the kernel. HTTPS requests negotiate HTTP/2 and fall back to HTTP/1.1 +when the peer does not support HTTP/2. Set `enableHttp2: false` to force HTTP/1.1 +for all kernel-owned HTTPS requests, including authentication, SQL requests, +result downloads, and telemetry. + ## Plain HTTP transport Set `https: false` to connect to `host` over plain HTTP, for example through a diff --git a/lib/contracts/IDBSQLClient.ts b/lib/contracts/IDBSQLClient.ts index 5c302bb0..aa6cc158 100644 --- a/lib/contracts/IDBSQLClient.ts +++ b/lib/contracts/IDBSQLClient.ts @@ -198,6 +198,13 @@ export type ConnectionOptions = { */ enableGeoSpatialSupport?: boolean; + /** + * Kernel backend only. Negotiate HTTP/2 over HTTPS with HTTP/1.1 fallback. + * Defaults to true in the kernel. Set false to force HTTP/1.1 for all + * kernel-owned HTTPS requests, including authentication and downloads. + */ + enableHttp2?: boolean; + /** * Extra HTTP headers sent on every request to the workspace (session, * statement and metadata calls, on both backends) and on driver-owned diff --git a/lib/kernel/KernelAuth.ts b/lib/kernel/KernelAuth.ts index 8d900485..8657680e 100644 --- a/lib/kernel/KernelAuth.ts +++ b/lib/kernel/KernelAuth.ts @@ -238,6 +238,7 @@ export interface KernelTlsOptions { * the kernel folds last-wins). */ export interface KernelHttpOptions { + enableHttp2?: boolean; customHeaders?: Array<{ name: string; value: string }>; socketTimeoutMs?: number; } @@ -523,6 +524,12 @@ export function buildKernelHttpOptions(options: ConnectionOptions): KernelHttpOp headers.push({ name: 'User-Agent', value: buildUserAgentString(userAgentEntry) }); const http: KernelHttpOptions = { customHeaders: headers }; + if (options.enableHttp2 !== undefined) { + if (typeof options.enableHttp2 !== 'boolean') { + throw new HiveDriverError('kernel backend: `enableHttp2` must be a boolean.'); + } + http.enableHttp2 = options.enableHttp2; + } // Per-connection socket read timeout (ms). The public `socketTimeout` // ConnectionOption maps onto the kernel napi `socketTimeoutMs` // (kernel `HttpConfig::request_timeout` / reqwest `Client::timeout`). diff --git a/native/kernel/index.d.ts b/native/kernel/index.d.ts index 87640ca0..8ce12c70 100644 --- a/native/kernel/index.d.ts +++ b/native/kernel/index.d.ts @@ -777,6 +777,8 @@ export interface ConnectionOptions { * to SEA. */ enableGeoSpatialSupport?: boolean + /** Negotiate HTTP/2 over HTTPS by default. Set false to force HTTP/1.1. */ + enableHttp2?: boolean /** * Driver name reported in telemetry system configuration. Omitted ⇒ * kernel default. diff --git a/tests/unit/kernel/connectionOptions.test.ts b/tests/unit/kernel/connectionOptions.test.ts index 153e388f..6e26f455 100644 --- a/tests/unit/kernel/connectionOptions.test.ts +++ b/tests/unit/kernel/connectionOptions.test.ts @@ -24,6 +24,25 @@ import HiveDriverError from '../../../lib/errors/HiveDriverError'; const PAT = { host: 'h.databricks.com', path: '/sql/1.0/warehouses/abc', token: 'dapi-x' }; +describe('Kernel HTTP/2 configuration', () => { + it('leaves the protocol default to the kernel', () => { + expect(buildKernelConnectionOptions(PAT)).not.to.have.property('enableHttp2'); + }); + + for (const enableHttp2 of [true, false]) { + it(`preserves enableHttp2=${enableHttp2}`, () => { + expect(buildKernelConnectionOptions({ ...PAT, enableHttp2 }).enableHttp2).to.equal(enableHttp2); + }); + } + + for (const enableHttp2 of ['false', 0, 1, null]) { + it(`rejects enableHttp2=${JSON.stringify(enableHttp2)}`, () => { + const options = { ...PAT, enableHttp2 } as unknown as ConnectionOptions; + expect(() => buildKernelConnectionOptions(options)).to.throw(HiveDriverError, 'enableHttp2'); + }); + } +}); + // Cast helper: the kernel connection-tuning/TLS options live on the internal // surface, so tests build untyped option literals. const opts = (extra: Record) => ({ ...PAT, ...extra } as unknown as ConnectionOptions); diff --git a/tests/unit/kernel/execution.test.ts b/tests/unit/kernel/execution.test.ts index 9aae43f5..36e82052 100644 --- a/tests/unit/kernel/execution.test.ts +++ b/tests/unit/kernel/execution.test.ts @@ -544,6 +544,7 @@ describe('KernelBackend', () => { path: '/sql/1.0/warehouses/xyz', token: 'dapi-token', enableGeoSpatialSupport: false, + enableHttp2: false, } as ConnectionOptions); await backend.openSession({}); @@ -562,6 +563,7 @@ describe('KernelBackend', () => { token: 'dapi-token', intervalsAsString: true, enableGeoSpatialSupport: false, + enableHttp2: false, }); }); From 2c358c5681b995ca368bc4c39f4c7222e0b852a6 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Wed, 18 Nov 2026 20:00:08 +0000 Subject: [PATCH 2/4] docs: describe HTTP/1.1 behavior with proxies Signed-off-by: Aakash Saravanan --- CHANGELOG.md | 2 +- CONNECTION_PARAMETERS.md | 3 ++- lib/contracts/IDBSQLClient.ts | 1 + native/kernel/index.d.ts | 2 +- 4 files changed, 5 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 28708476..2c46c10f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ ## Unreleased -- Add kernel-only `enableHttp2`: HTTPS negotiates HTTP/2 with HTTP/1.1 fallback; set `enableHttp2: false` to force HTTP/1.1 for all kernel-owned HTTPS requests. +- Add kernel-only `enableHttp2`: HTTPS negotiates HTTP/2 with HTTP/1.1 fallback; set `enableHttp2: false` to force HTTP/1.1 for all kernel-owned HTTPS requests. Configured proxies force HTTP/1.1. - The Thrift token federation exchange (`enableTokenFederation`) now goes through the connection's agent, so `proxy`, `checkServerCertificate`, `customCaCert` and `clientCert`/`clientKey` apply to it. Previously it connected directly with Node's default agent, so behind a required proxy the exchange failed and the driver fell back to the original token. (#611) - Kernel backend: a failed status poll while waiting for a statement (a `runAsync: true` statement, or a default execution that outlives the server's inline wait) and a failed result fetch in `hasMoreRows()` now throw the mapped driver error, such as `HiveDriverError: HTTP 500: Internal Server Error` once retries on HTTP 5xx run out, instead of a raw `Error` whose message is the internal `__databricks_error__:{...}` envelope. As in `fetchChunk()`, a failed fetch in `hasMoreRows()` also closes the statement. (#608) diff --git a/CONNECTION_PARAMETERS.md b/CONNECTION_PARAMETERS.md index 4a738852..e4bc3a7c 100644 --- a/CONNECTION_PARAMETERS.md +++ b/CONNECTION_PARAMETERS.md @@ -108,7 +108,8 @@ For kernel connections, `enableHttp2` is an optional boolean that defaults to `true` in the kernel. HTTPS requests negotiate HTTP/2 and fall back to HTTP/1.1 when the peer does not support HTTP/2. Set `enableHttp2: false` to force HTTP/1.1 for all kernel-owned HTTPS requests, including authentication, SQL requests, -result downloads, and telemetry. +result downloads, and telemetry. Configured proxies force HTTP/1.1 for the +entire kernel client. ## Plain HTTP transport diff --git a/lib/contracts/IDBSQLClient.ts b/lib/contracts/IDBSQLClient.ts index aa6cc158..f638c391 100644 --- a/lib/contracts/IDBSQLClient.ts +++ b/lib/contracts/IDBSQLClient.ts @@ -202,6 +202,7 @@ export type ConnectionOptions = { * Kernel backend only. Negotiate HTTP/2 over HTTPS with HTTP/1.1 fallback. * Defaults to true in the kernel. Set false to force HTTP/1.1 for all * kernel-owned HTTPS requests, including authentication and downloads. + * Configured proxies force HTTP/1.1 for the entire kernel client. */ enableHttp2?: boolean; diff --git a/native/kernel/index.d.ts b/native/kernel/index.d.ts index 8ce12c70..c6f9c574 100644 --- a/native/kernel/index.d.ts +++ b/native/kernel/index.d.ts @@ -777,7 +777,7 @@ export interface ConnectionOptions { * to SEA. */ enableGeoSpatialSupport?: boolean - /** Negotiate HTTP/2 over HTTPS by default. Set false to force HTTP/1.1. */ + /** Negotiate HTTP/2 over HTTPS by default. False or a configured proxy forces HTTP/1.1. */ enableHttp2?: boolean /** * Driver name reported in telemetry system configuration. Omitted ⇒ From 4fb6fa01d49e954feafbd6207e807f8f65d690f6 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Wed, 18 Nov 2026 20:08:36 +0000 Subject: [PATCH 3/4] docs: clarify environment proxy protocol settings Signed-off-by: Aakash Saravanan --- CHANGELOG.md | 2 +- CONNECTION_PARAMETERS.md | 2 +- lib/contracts/IDBSQLClient.ts | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2c46c10f..cc569f2a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ ## Unreleased -- Add kernel-only `enableHttp2`: HTTPS negotiates HTTP/2 with HTTP/1.1 fallback; set `enableHttp2: false` to force HTTP/1.1 for all kernel-owned HTTPS requests. Configured proxies force HTTP/1.1. +- Add kernel-only `enableHttp2`: HTTPS negotiates HTTP/2 with HTTP/1.1 fallback; set `enableHttp2: false` to force HTTP/1.1 for all kernel-owned HTTPS requests. Configured proxies, including environment proxy variables, force HTTP/1.1. - The Thrift token federation exchange (`enableTokenFederation`) now goes through the connection's agent, so `proxy`, `checkServerCertificate`, `customCaCert` and `clientCert`/`clientKey` apply to it. Previously it connected directly with Node's default agent, so behind a required proxy the exchange failed and the driver fell back to the original token. (#611) - Kernel backend: a failed status poll while waiting for a statement (a `runAsync: true` statement, or a default execution that outlives the server's inline wait) and a failed result fetch in `hasMoreRows()` now throw the mapped driver error, such as `HiveDriverError: HTTP 500: Internal Server Error` once retries on HTTP 5xx run out, instead of a raw `Error` whose message is the internal `__databricks_error__:{...}` envelope. As in `fetchChunk()`, a failed fetch in `hasMoreRows()` also closes the statement. (#608) diff --git a/CONNECTION_PARAMETERS.md b/CONNECTION_PARAMETERS.md index e4bc3a7c..e4de5f36 100644 --- a/CONNECTION_PARAMETERS.md +++ b/CONNECTION_PARAMETERS.md @@ -108,7 +108,7 @@ For kernel connections, `enableHttp2` is an optional boolean that defaults to `true` in the kernel. HTTPS requests negotiate HTTP/2 and fall back to HTTP/1.1 when the peer does not support HTTP/2. Set `enableHttp2: false` to force HTTP/1.1 for all kernel-owned HTTPS requests, including authentication, SQL requests, -result downloads, and telemetry. Configured proxies force HTTP/1.1 for the +result downloads, and telemetry. Configured proxies, including environment proxy variables, force HTTP/1.1 for the entire kernel client. ## Plain HTTP transport diff --git a/lib/contracts/IDBSQLClient.ts b/lib/contracts/IDBSQLClient.ts index f638c391..ad44c2e0 100644 --- a/lib/contracts/IDBSQLClient.ts +++ b/lib/contracts/IDBSQLClient.ts @@ -202,7 +202,7 @@ export type ConnectionOptions = { * Kernel backend only. Negotiate HTTP/2 over HTTPS with HTTP/1.1 fallback. * Defaults to true in the kernel. Set false to force HTTP/1.1 for all * kernel-owned HTTPS requests, including authentication and downloads. - * Configured proxies force HTTP/1.1 for the entire kernel client. + * Configured proxies, including environment proxy variables, force HTTP/1.1 for the entire kernel client. */ enableHttp2?: boolean; From f3e4ce54f062c9604c2a8a49d21c5af36df983c6 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Wed, 18 Nov 2026 23:56:34 +0000 Subject: [PATCH 4/4] docs: clarify kernel HTTP protocol options Signed-off-by: Aakash Saravanan --- CHANGELOG.md | 2 +- CONNECTION_PARAMETERS.md | 10 +--------- lib/contracts/IDBSQLClient.ts | 7 +++---- 3 files changed, 5 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cc569f2a..a69b5b68 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ ## Unreleased -- Add kernel-only `enableHttp2`: HTTPS negotiates HTTP/2 with HTTP/1.1 fallback; set `enableHttp2: false` to force HTTP/1.1 for all kernel-owned HTTPS requests. Configured proxies, including environment proxy variables, force HTTP/1.1. +- Kernel HTTPS traffic negotiates HTTP/2 with HTTP/1.1 fallback. Set `enableHttp2: false` to force HTTP/1.1. Configured proxies also force HTTP/1.1. - The Thrift token federation exchange (`enableTokenFederation`) now goes through the connection's agent, so `proxy`, `checkServerCertificate`, `customCaCert` and `clientCert`/`clientKey` apply to it. Previously it connected directly with Node's default agent, so behind a required proxy the exchange failed and the driver fell back to the original token. (#611) - Kernel backend: a failed status poll while waiting for a statement (a `runAsync: true` statement, or a default execution that outlives the server's inline wait) and a failed result fetch in `hasMoreRows()` now throw the mapped driver error, such as `HiveDriverError: HTTP 500: Internal Server Error` once retries on HTTP 5xx run out, instead of a raw `Error` whose message is the internal `__databricks_error__:{...}` envelope. As in `fetchChunk()`, a failed fetch in `hasMoreRows()` also closes the statement. (#608) diff --git a/CONNECTION_PARAMETERS.md b/CONNECTION_PARAMETERS.md index e4de5f36..316aa756 100644 --- a/CONNECTION_PARAMETERS.md +++ b/CONNECTION_PARAMETERS.md @@ -79,6 +79,7 @@ Per-statement `useCloudFetch` overrides remain unsupported on the kernel backend | Option | Type | Thrift | Kernel | Default Value | Note | | --------------------------- | ------------------------ | :----: | :----: | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `socketTimeout` | `number` (ms) | ✅ | ⚠️ | `900000` / `120000` | Kernel forwards only positive values. `0` means no timeout on Thrift but is omitted on Kernel, which then keeps its 120-second default. | +| `enableHttp2` | `boolean` | ❌ | ✅ | `true` | Negotiate HTTP/2 for all kernel HTTPS traffic, with HTTP/1.1 fallback. `false` or an explicit/environment proxy forces HTTP/1.1, including bypassed hosts. | | `proxy` | `ProxyOptions` | ✅ | ⚠️ | — | `{protocol, host, port, auth}`. Kernel supports HTTP/HTTPS proxies only; Thrift also supports the declared SOCKS variants. | | `noProxy` (internal) | `string` | ❌ | ⚠️ | — | Runtime-only Kernel bypass list, forwarded as `bypassHosts` only when an explicit `proxy` is also supplied. | | `customHeaders` | `Record` | ✅ | ✅ | — | Sent on workspace, telemetry and feature-flag requests, not OAuth. Workspace calls ignore caller `Authorization`, `User-Agent`, `Content-Type`, `Content-Length`, `Transfer-Encoding`, `Connection`; Kernel also ignores `x-databricks-org-id`. | @@ -102,15 +103,6 @@ disabling verification. | `clientKey` | `Buffer \| string` | ✅ | ✅ | — | Public mTLS private key. Must be paired with `clientCert`; PKCS#8 is recommended for Kernel portability. | | `clientCertPem` / `clientKeyPem` (internal) | `Buffer \| string` | ❌ | ✅ | — | Runtime-only Kernel aliases for the public mTLS pair. They take precedence over `clientCert`/`clientKey` when both pairs are supplied. | -## HTTP protocol - -For kernel connections, `enableHttp2` is an optional boolean that defaults to -`true` in the kernel. HTTPS requests negotiate HTTP/2 and fall back to HTTP/1.1 -when the peer does not support HTTP/2. Set `enableHttp2: false` to force HTTP/1.1 -for all kernel-owned HTTPS requests, including authentication, SQL requests, -result downloads, and telemetry. Configured proxies, including environment proxy variables, force HTTP/1.1 for the -entire kernel client. - ## Plain HTTP transport Set `https: false` to connect to `host` over plain HTTP, for example through a diff --git a/lib/contracts/IDBSQLClient.ts b/lib/contracts/IDBSQLClient.ts index ad44c2e0..56d24b00 100644 --- a/lib/contracts/IDBSQLClient.ts +++ b/lib/contracts/IDBSQLClient.ts @@ -199,10 +199,9 @@ export type ConnectionOptions = { enableGeoSpatialSupport?: boolean; /** - * Kernel backend only. Negotiate HTTP/2 over HTTPS with HTTP/1.1 fallback. - * Defaults to true in the kernel. Set false to force HTTP/1.1 for all - * kernel-owned HTTPS requests, including authentication and downloads. - * Configured proxies, including environment proxy variables, force HTTP/1.1 for the entire kernel client. + * Negotiate HTTP/2 for all kernel HTTPS traffic, with HTTP/1.1 fallback. + * Defaults to true. False or a configured proxy forces HTTP/1.1, + * including bypassed destinations. Applies only with useKernel: true. */ enableHttp2?: boolean;