diff --git a/CHANGELOG.md b/CHANGELOG.md index 938983a3..a69b5b68 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ ## Unreleased +- 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) - 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..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`. | diff --git a/lib/contracts/IDBSQLClient.ts b/lib/contracts/IDBSQLClient.ts index 5c302bb0..56d24b00 100644 --- a/lib/contracts/IDBSQLClient.ts +++ b/lib/contracts/IDBSQLClient.ts @@ -198,6 +198,13 @@ export type ConnectionOptions = { */ enableGeoSpatialSupport?: boolean; + /** + * 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; + /** * 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..c6f9c574 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. False or a configured proxy forces 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, }); });