Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium — The changelog claims HTTP/2 negotiation and enableHttp2: false work, but the platform packages are pinned to 1.4.0, which has no such field in this diff. Add the published-package caveat and the kernel change reference, or land the pin bump with the entry.

🔀 Found by Claude Opus 5.5 · confirmed by the judge


- 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.
Expand Down
1 change: 1 addition & 0 deletions CONNECTION_PARAMETERS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string>` | ✅ | ✅ | — | 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`. |
Expand Down
7 changes: 7 additions & 0 deletions lib/contracts/IDBSQLClient.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 7 additions & 0 deletions lib/kernel/KernelAuth.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
Expand Down Expand Up @@ -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;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 High — enableHttp2 is forwarded to the native binding, but every optionalDependency is still pinned to 1.4.0 and this diff doesn't bump them. An older binding drops the unknown field silently, so enableHttp2: false does nothing. Bump all platform pins to a binding that has the field, or add a capability check.

🔀 Found by Claude Opus 5.5 · confirmed by the judge

}
// Per-connection socket read timeout (ms). The public `socketTimeout`
// ConnectionOption maps onto the kernel napi `socketTimeoutMs`
// (kernel `HttpConfig::request_timeout` / reqwest `Client::timeout`).
Expand Down
2 changes: 2 additions & 0 deletions native/kernel/index.d.ts

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

19 changes: 19 additions & 0 deletions tests/unit/kernel/connectionOptions.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, unknown>) => ({ ...PAT, ...extra } as unknown as ConnectionOptions);
Expand Down
2 changes: 2 additions & 0 deletions tests/unit/kernel/execution.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -544,6 +544,7 @@ describe('KernelBackend', () => {
path: '/sql/1.0/warehouses/xyz',
token: 'dapi-token',
enableGeoSpatialSupport: false,
enableHttp2: false,
} as ConnectionOptions);

await backend.openSession({});
Expand All @@ -562,6 +563,7 @@ describe('KernelBackend', () => {
token: 'dapi-token',
intervalsAsString: true,
enableGeoSpatialSupport: false,
enableHttp2: false,
});
});

Expand Down
Loading