From 0a534debbd35ab8b1be7e67ae9c6ac775f8d5357 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Fri, 13 Nov 2026 23:01:51 +0000 Subject: [PATCH 01/37] Complete configured Volume operations in the native backend Signed-off-by: Aakash Saravanan --- CHANGELOG.md | 2 + CONNECTION_PARAMETERS.md | 8 +++- lib/DBSQLSession.ts | 15 +++++-- lib/contracts/IOperationBackend.ts | 2 + lib/kernel/KernelErrorMapping.ts | 24 ++++++++++- lib/kernel/KernelOperationBackend.ts | 36 ++++++++++++++-- lib/kernel/KernelSessionBackend.ts | 14 +------ native/kernel/index.d.ts | 4 ++ tests/unit/DBSQLSession.test.ts | 16 +++++++ .../kernel/KernelOperationBackend.test.ts | 42 +++++++++++++++++++ tests/unit/kernel/error-mapping.test.ts | 17 ++++++++ tests/unit/kernel/execution.test.ts | 10 +++-- 12 files changed, 167 insertions(+), 23 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 938983a3..c7e372c8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ - 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. - Reduce result chunking and `fetchAll()` overhead for large query results. +- Support Volume file transfers on the kernel backend when `stagingAllowedLocalPath` is supplied. Symlink targets must remain within configured allowed roots; in-root symlinks are permitted. + - Thrift CloudFetch downloads are now bounded end to end by `retriesTimeout` (default 15 minutes), including every attempt and retry backoff. Previously a stalled download, where the response headers or body never arrived, blocked the fetch forever. A download still running when the deadline expires is aborted and fails with `RetryError` (`TIMEOUT_EXCEEDED`, message `CloudFetch result download failed: Retry timeout exceeded`). (#520) - Thrift connections made through `proxy` now apply `checkServerCertificate`, `customCaCert` and `clientCert`/`clientKey`. Previously the proxied path ignored them and verified against Node's process-wide trust store, so a certificate outside the configured trust set could be accepted. **Compatibility:** proxied connections now verify unless `checkServerCertificate: false` is set; as on direct connections, `NODE_TLS_REJECT_UNAUTHORIZED=0` no longer turns verification off. For an `https` proxy these options also apply to the proxy's own certificate. (#485) - Honor the client `useCloudFetch: false` default on the kernel backend so complete results can be fetched without cloud-storage downloads. (#574) diff --git a/CONNECTION_PARAMETERS.md b/CONNECTION_PARAMETERS.md index edba6002..679b54cc 100644 --- a/CONNECTION_PARAMETERS.md +++ b/CONNECTION_PARAMETERS.md @@ -213,7 +213,7 @@ telemetry implementation, so only the options explicitly forwarded by | `maxRows` | `number \| bigint \| Int64 \| null` | ✅ | ❌ | `100000` / — | Thrift uses it for the initial Direct Results row count; `null` disables Direct Results. Kernel does not retain or forward the supplied value. | | `useCloudFetch` | `boolean` | ✅ | ❌ | `true` / — | Kernel logs and ignores this per-statement hint; Kernel result fetching owns its CloudFetch behavior. | | `useLZ4Compression` | `boolean` | ✅ | ❌ | `true` / — | Thrift uses it when supported and when the result is not CloudFetch. Kernel owns and auto-detects result compression. | -| `stagingAllowedLocalPath` | `string \| string[]` | ✅ | ❌ | — | Local allowlist for Thrift volume/staging operations. Kernel volume operations are unsupported. | +| `stagingAllowedLocalPath` | `string \| string[]` | ✅ | ✅ | — | Local allowlist for Volume operations. Kernel also requires resolved symlink targets within allowed roots; links within those roots are permitted. | | `namedParameters` | `Record` | ✅ | ✅ | — | Named SQL parameters. Cannot be combined with non-empty `ordinalParameters`. Thrift requires a protocol that supports parameterized queries. | | `ordinalParameters` | `Array` | ✅ | ✅ | — | Positional SQL parameters. Cannot be combined with non-empty `namedParameters`. | | `queryTags` | `Record` | ✅ | ✅ | — | Serialized into the per-statement `query_tags` conf overlay on both. | @@ -252,3 +252,9 @@ independent TLS hostname verification, optional U2M disk caching, and per-statement `rowLimit`/`statementConf`. The Kernel path remains internal and unstable; its behavior may change. + +With the kernel backend, supplying `stagingAllowedLocalPath` completes Volume +transfers before `executeStatement` resolves and consumes instruction rows. +Omitting the option returns raw instructions without file effects. Unlike the +Thrift backend’s lexical path check, the kernel also rejects symlink targets +outside the configured roots while permitting symlinks within them. diff --git a/lib/DBSQLSession.ts b/lib/DBSQLSession.ts index 5bca61d6..7633990f 100644 --- a/lib/DBSQLSession.ts +++ b/lib/DBSQLSession.ts @@ -109,11 +109,20 @@ export default class DBSQLSession implements IDBSQLSession { // operation, everything will work as usual. In a case of staging operation, it will be processed like any // other query - it will be possible to get data from it as usual, or use other operation methods. if (options.stagingAllowedLocalPath !== undefined) { + const allowedLocalPath = Array.isArray(options.stagingAllowedLocalPath) + ? options.stagingAllowedLocalPath + : [options.stagingAllowedLocalPath]; + if (opBackend.completeStagingOperation) { + try { + await this.runBackend(() => opBackend.completeStagingOperation!(allowedLocalPath)); + return operation; + } catch (error) { + await operation.close().catch(() => {}); + throw error; + } + } const metadata = await operation.getResultMetadata(); if (metadata.isStagingOperation) { - const allowedLocalPath = Array.isArray(options.stagingAllowedLocalPath) - ? options.stagingAllowedLocalPath - : [options.stagingAllowedLocalPath]; return this.handleStagingOperation(operation, allowedLocalPath, metadata); } } diff --git a/lib/contracts/IOperationBackend.ts b/lib/contracts/IOperationBackend.ts index 109de87e..791008d3 100644 --- a/lib/contracts/IOperationBackend.ts +++ b/lib/contracts/IOperationBackend.ts @@ -113,6 +113,8 @@ export default interface IOperationBackend { */ getCachedResultMetadata?(): ResultMetadata | undefined; + completeStagingOperation?(allowedPaths: string[]): Promise; + /** Cancel the operation. */ cancel(): Promise; diff --git a/lib/kernel/KernelErrorMapping.ts b/lib/kernel/KernelErrorMapping.ts index d83d7e59..fcd2f35b 100644 --- a/lib/kernel/KernelErrorMapping.ts +++ b/lib/kernel/KernelErrorMapping.ts @@ -1,3 +1,5 @@ +import { constants } from 'node:os'; +import { getSystemErrorName } from 'node:util'; import HiveDriverError from '../errors/HiveDriverError'; import AuthenticationError from '../errors/AuthenticationError'; import OperationStateError, { OperationStateErrorCode } from '../errors/OperationStateError'; @@ -311,7 +313,27 @@ export function decodeNapiKernelError(err: unknown): Error { const msg = envelope.message as string; const sqlState = typeof envelope.sqlState === 'string' ? envelope.sqlState : undefined; - const jsErr = mapKernelErrorToJsError({ code, message: msg, sqlstate: sqlState }); + let jsErr = mapKernelErrorToJsError({ code, message: msg, sqlstate: sqlState }); + if (typeof envelope.localPath === 'string' && typeof envelope.localErrorKind === 'string') { + const kindCodes: Record = { + NotFound: 'ENOENT', + PermissionDenied: 'EACCES', + AlreadyExists: 'EEXIST', + NotADirectory: 'ENOTDIR', + IsADirectory: 'EISDIR', + DirectoryNotEmpty: 'ENOTEMPTY', + }; + const raw = typeof envelope.localOsError === 'number' ? envelope.localOsError : undefined; + const localCode = + process.platform !== 'win32' && raw + ? getSystemErrorName(-Math.abs(raw)) + : kindCodes[envelope.localErrorKind] ?? 'EIO'; + jsErr = Object.assign(new Error(msg), { + code: localCode, + errno: -((constants.errno as Record)[localCode] ?? Math.abs(raw ?? constants.errno.EIO)), + path: envelope.localPath, + }); + } const meta = buildKernelMetadata(envelope); // Skip the namespace attachment entirely when no fields validated diff --git a/lib/kernel/KernelOperationBackend.ts b/lib/kernel/KernelOperationBackend.ts index 81647ece..05eb54b0 100644 --- a/lib/kernel/KernelOperationBackend.ts +++ b/lib/kernel/KernelOperationBackend.ts @@ -46,6 +46,8 @@ import { LogLevel } from '../contracts/IDBSQLLogger'; import { RowMode } from '../contracts/IDBSQLSession'; import Status from '../dto/Status'; import HiveDriverError from '../errors/HiveDriverError'; +import StagingError from '../errors/StagingError'; +import ParameterError from '../errors/ParameterError'; import OperationStateError, { OperationStateErrorCode } from '../errors/OperationStateError'; import ArrowResultConverter from '../result/ArrowResultConverter'; import ResultSlicer from '../result/ResultSlicer'; @@ -84,7 +86,10 @@ export type KernelOperationStatement = KernelStatementHandle & Partial; +type KernelFetchHandle = Pick< + KernelStatement, + 'fetchNextBatch' | 'schema' | 'isVolumeOperation' | 'completeVolumeOperation' +>; /** * The rich operation-status surface the kernel exposes on a terminal sync @@ -220,6 +225,8 @@ export default class KernelOperationBackend implements IOperationBackend { // already-terminal statement. Drives both fetch and result-metadata. private fetchHandlePromise?: Promise; + private volumeCompleted = false; + // Async path only: set once the kernel reported the statement Succeeded (a // status poll, or `awaitResult()` resolving). The kernel exposes no // synchronous terminal-state accessor, so the observed success is retained. @@ -260,7 +267,7 @@ export default class KernelOperationBackend implements IOperationBackend { // drop-guard fires whenever this handle is eventually GC'd. this.lifecycleHandle = cancellableExecution ? { - cancel: () => cancellableExecution.cancel(), + cancel: () => (this.blockingStatement ? this.blockingStatement.cancel() : cancellableExecution.cancel()), close: () => (this.blockingStatement ? this.blockingStatement.close() : cancellableExecution.cancel()), } : ((asyncStatement ?? statement) as KernelStatementHandle); @@ -308,6 +315,27 @@ export default class KernelOperationBackend implements IOperationBackend { // Fetch / metadata (owned by the kernel-results pipeline). // --------------------------------------------------------------------------- + public async completeStagingOperation(allowedPaths: string[]): Promise { + failIfNotActive(this.lifecycle); + try { + const handle = await this.getFetchHandle(); + const outcome = await handle.completeVolumeOperation(allowedPaths, true); + if (outcome === 'needs_input_stream') { + throw new StagingError('Volume PUT requires a local file path'); + } + this.volumeCompleted = outcome === 'completed'; + } catch (err) { + const mapped = decodeNapiKernelError(err); + if ( + mapped instanceof ParameterError || + (mapped as { kernelMetadata?: { httpStatus?: number } }).kernelMetadata?.httpStatus + ) { + throw new StagingError(mapped.message); + } + throw mapped; + } + } + public async fetchChunk({ limit, disableBuffering, @@ -320,6 +348,7 @@ export default class KernelOperationBackend implements IOperationBackend { // Cancel-mid-fetch propagation: if cancel() has flipped the // lifecycle flag, fail locally without a wire round-trip. failIfNotActive(this.lifecycle); + if (this.volumeCompleted) return []; // Cooperative cancel (parity with ThriftOperationBackend): the facade // supplies `isClosed` and re-checks `failIfClosed()` after we return, so // bailing with `[]` at a yield point is the contract-correct way for a @@ -340,6 +369,7 @@ export default class KernelOperationBackend implements IOperationBackend { public async hasMore(): Promise { failIfNotActive(this.lifecycle); + if (this.volumeCompleted) return false; try { // `hasMore()` prefetches the next batch, so it fails like `fetchChunk()`. const slicer = await this.getResultSlicer(); @@ -383,7 +413,7 @@ export default class KernelOperationBackend implements IOperationBackend { // `arrowSchema` doesn't hit apache-arrow@13's `Unrecognized type // "Duration" (18)`. Matches what the per-batch fetch path already does. arrowSchema: patchIpcBytes(arrowSchemaIpc.ipcBytes), - isStagingOperation: false, + isStagingOperation: Boolean(handle.isVolumeOperation), }; this.metadata = meta; return meta; diff --git a/lib/kernel/KernelSessionBackend.ts b/lib/kernel/KernelSessionBackend.ts index dd55dd4c..92966ac2 100644 --- a/lib/kernel/KernelSessionBackend.ts +++ b/lib/kernel/KernelSessionBackend.ts @@ -151,7 +151,7 @@ export default class KernelSessionBackend implements ISessionBackend { * Still rejected (genuinely unsupported on kernel, rather than silently * dropped): `useCloudFetch` (governed by the kernel `ResultConfig`, not a * per-statement knob), `useLZ4Compression` (kernel owns result compression), - * and `stagingAllowedLocalPath` (volume operations). `maxRows` is applied by + * while `stagingAllowedLocalPath` is applied by the facade. `maxRows` is applied by * the facade at fetch time, so it is intentionally not handled here. */ public async executeStatement(statement: string, options: ExecuteStatementOptions): Promise { @@ -160,8 +160,7 @@ export default class KernelSessionBackend implements ISessionBackend { // Per-statement options the kernel backend doesn't honour are treated as // NO-OPs (logged at warn), not errors — so call sites written for the Thrift // backend are drop-in on the kernel path. These are perf/format hints the - // kernel governs internally (useCloudFetch / useLZ4Compression) or a feature - // it doesn't expose yet (staging); ignoring them cannot change query results. + // kernel governs internally (useCloudFetch / useLZ4Compression). // NB: parameter binding (compound/BINARY) is deliberately NOT no-op'd — a // dropped param would silently change results, so it still throws. if (options.useCloudFetch !== undefined) { @@ -180,15 +179,6 @@ export default class KernelSessionBackend implements ISessionBackend { 'kernel executeStatement: ignoring per-statement `useLZ4Compression` — result compression is governed by the kernel (no-op on kernel).', ); } - if (options.stagingAllowedLocalPath !== undefined) { - this.context - .getLogger() - .log( - LogLevel.warn, - 'kernel executeStatement: ignoring `stagingAllowedLocalPath` — volume/staging operations are not yet supported on the kernel backend (no-op).', - ); - } - // `runAsync` selects the kernel execution path. NOTE: this is a kernel- // specific use of the option — the Thrift backend hardcodes `runAsync: true` // on the wire and never reads `options.runAsync`, so the field is a no-op diff --git a/native/kernel/index.d.ts b/native/kernel/index.d.ts index 87640ca0..b531ff13 100644 --- a/native/kernel/index.d.ts +++ b/native/kernel/index.d.ts @@ -18,6 +18,8 @@ * post-close contract. */ export declare class AsyncResultHandle { + get isVolumeOperation(): boolean; + completeVolumeOperation(allowedPaths: Array, removeNotFoundIsSuccess?: boolean | undefined | null): Promise; /** * Server-issued statement id. Cached at construction; readable * for log correlation. Matches the parent `AsyncStatement`'s @@ -438,6 +440,8 @@ export declare class Connection { * disposed statement can still read them. */ export declare class Statement { + get isVolumeOperation(): boolean; + completeVolumeOperation(allowedPaths: Array, removeNotFoundIsSuccess?: boolean | undefined | null): Promise; /** * Server-issued statement id. Cached at construction; readable * even after `close()` so JS-side log lines can correlate against diff --git a/tests/unit/DBSQLSession.test.ts b/tests/unit/DBSQLSession.test.ts index 00498c54..7c73c1c0 100644 --- a/tests/unit/DBSQLSession.test.ts +++ b/tests/unit/DBSQLSession.test.ts @@ -7,6 +7,7 @@ import Status from '../../lib/dto/Status'; import DBSQLOperation from '../../lib/DBSQLOperation'; import { PrimaryKeysRequest } from '../../lib/contracts/IDBSQLSession'; import ISessionBackend from '../../lib/contracts/ISessionBackend'; +import IOperationBackend from '../../lib/contracts/IOperationBackend'; import ParameterError from '../../lib/errors/ParameterError'; import { DBSQLParameter } from '../../lib/DBSQLParameter'; import { TSessionHandle, TProtocolVersion, TOperationState, TStatusCode } from '../../thrift/TCLIService_types'; @@ -883,3 +884,18 @@ describe('DBSQLSession', () => { }); }); }); + +describe('DBSQLSession native staging dispatch', () => { + for (const configured of [false, true]) { + it(`calls native completion only when local paths are ${configured ? 'configured' : 'omitted'}`, async () => { + const completeStagingOperation = sinon.stub().resolves(); + const op = { id: 'volume-operation', completeStagingOperation } as unknown as IOperationBackend; + const session = new DBSQLSession({ + backend: { id: 'volume-session', executeStatement: async () => op } as unknown as ISessionBackend, + context: new ClientContextStub(), + }); + await session.executeStatement('REMOVE remote', configured ? { stagingAllowedLocalPath: [] } : {}); + expect(completeStagingOperation.callCount).to.equal(configured ? 1 : 0); + }); + } +}); diff --git a/tests/unit/kernel/KernelOperationBackend.test.ts b/tests/unit/kernel/KernelOperationBackend.test.ts index 972de4fc..695e82f7 100644 --- a/tests/unit/kernel/KernelOperationBackend.test.ts +++ b/tests/unit/kernel/KernelOperationBackend.test.ts @@ -389,3 +389,45 @@ describe('KernelOperationBackend — M0 datatype round-trip via napi → ArrowRe expect(stub.closed).to.equal(true); }); }); + +describe('KernelOperationBackend Volume completion', () => { + it('routes cancellation to the statement after SQL completes', async () => { + const schema = new Schema([withTypeName(new Field('x', new Int32(), true), 'INT')]); + const statement = new StatementStub(ipcSchemaOnly(schema), []); + let executionCancelled = false; + const execution = { + result: async () => statement, + cancel: async () => { + executionCancelled = true; + }, + }; + const backend = new KernelOperationBackend({ + cancellableExecution: execution as any, + context: new ClientContextStub(), + }); + await backend.getResultMetadata(); + await backend.cancel(); + expect(statement.cancelled).to.equal(true); + expect(executionCancelled).to.equal(false); + }); + + for (const outcome of ['completed', 'not_volume']) { + it(`${ + outcome === 'completed' ? 'consumes completed instructions' : 'preserves raw instruction rows' + }`, async () => { + const schema = new Schema([withTypeName(new Field('x', new Int32(), true), 'INT')]); + const stub = new StatementStub(ipcSchemaOnly(schema), [ipcFromColumns(schema, { x: [1] })]); + const completeVolumeOperation = async (paths: string[], remove404: boolean) => { + expect(paths).to.deep.equal(['/allowed']); + expect(remove404).to.equal(true); + return outcome; + }; + Object.assign(stub, { isVolumeOperation: true, completeVolumeOperation }); + const backend = new KernelOperationBackend({ statement: stub, context: new ClientContextStub() }); + expect((await backend.getResultMetadata()).isStagingOperation).to.equal(true); + await backend.completeStagingOperation(['/allowed']); + expect((await backend.fetchChunk({ limit: 100 })).length).to.equal(outcome === 'completed' ? 0 : 1); + expect(await backend.hasMore()).to.equal(false); + }); + } +}); diff --git a/tests/unit/kernel/error-mapping.test.ts b/tests/unit/kernel/error-mapping.test.ts index fefa8f2a..855c4b58 100644 --- a/tests/unit/kernel/error-mapping.test.ts +++ b/tests/unit/kernel/error-mapping.test.ts @@ -372,3 +372,20 @@ describe('KernelErrorMapping.decodeNapiKernelError — cause chain', () => { expect(err.cause).to.equal(undefined); }); }); + +it('preserves local file error code and path from native completion', () => { + const error = decodeNapiKernelError( + new Error( + `__databricks_error__:${JSON.stringify({ + code: 'NotFound', + message: 'Local file does not exist', + localOsError: 2, + localErrorKind: 'NotFound', + localPath: '/allowed/missing', + })}`, + ), + ) as NodeJS.ErrnoException; + expect(error.code).to.equal('ENOENT'); + expect(error.path).to.equal('/allowed/missing'); + expect(error.errno).to.be.lessThan(0); +}); diff --git a/tests/unit/kernel/execution.test.ts b/tests/unit/kernel/execution.test.ts index 9aae43f5..ef064b87 100644 --- a/tests/unit/kernel/execution.test.ts +++ b/tests/unit/kernel/execution.test.ts @@ -41,6 +41,12 @@ import { DBSQLParameter, DBSQLParameterType } from '../../../lib/DBSQLParameter' // ----------------------------------------------------------------------------- class FakeNativeStatement implements KernelStatement { + public readonly isVolumeOperation = false; + + public async completeVolumeOperation(): Promise { + return 'not_volume'; + } + public closed = false; public cancelled = false; @@ -1152,13 +1158,11 @@ describe('KernelSessionBackend', () => { // Unsupported-on-kernel per-statement HINTS are NO-OPs (not errors) so Thrift- // targeted call sites are drop-in on the kernel path. They are kernel-governed - // perf/format hints (useCloudFetch / useLZ4Compression) or an unexposed feature - // (staging); ignoring them can't change results. (Parameter binding is NOT here + // perf/format hints (useCloudFetch / useLZ4Compression). (Parameter binding is NOT here // — a dropped param would change results, so it still throws; asserted above.) for (const { name, options } of [ { name: 'useCloudFetch', options: { useCloudFetch: true } }, { name: 'useLZ4Compression', options: { useLZ4Compression: true } }, - { name: 'stagingAllowedLocalPath', options: { stagingAllowedLocalPath: '/tmp' } }, ] as const) { it(`executeStatement ignores unsupported ${name} (no-op, does not throw)`, async () => { const connection = new FakeNativeConnection(); From 47e379e1c25ad5802889041c320b9f063f44fb27 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Fri, 13 Nov 2026 23:25:05 +0000 Subject: [PATCH 02/37] Retain inline results for configured Volume transfers Signed-off-by: Aakash Saravanan --- lib/contracts/IDBSQLSession.ts | 3 ++- lib/kernel/KernelSessionBackend.ts | 4 +++- tests/unit/kernel/execution.test.ts | 14 ++++++++++++++ 3 files changed, 19 insertions(+), 2 deletions(-) diff --git a/lib/contracts/IDBSQLSession.ts b/lib/contracts/IDBSQLSession.ts index 12d7d6c2..da5a01b1 100644 --- a/lib/contracts/IDBSQLSession.ts +++ b/lib/contracts/IDBSQLSession.ts @@ -32,7 +32,8 @@ export type ExecuteStatementOptions = { * `false`/unset (default) runs the blocking direct-results path (faster, * cancellable mid-compute); `true` submits and polls (returns a pending * handle before completion). Default is sync, matching the python - * connector's `cursor.execute()`. + * connector's `cursor.execute()`. With `stagingAllowedLocalPath` configured, + * execution waits for staging completion regardless of this option. */ runAsync?: boolean; maxRows?: number | bigint | Int64 | null; diff --git a/lib/kernel/KernelSessionBackend.ts b/lib/kernel/KernelSessionBackend.ts index 92966ac2..a074d4b2 100644 --- a/lib/kernel/KernelSessionBackend.ts +++ b/lib/kernel/KernelSessionBackend.ts @@ -202,7 +202,9 @@ export default class KernelSessionBackend implements ISessionBackend { // the backend polls `status()` to terminal in `waitUntilReady()` and // materialises results via `awaitResult()`. `queryTimeout` is a no-op // here too. - const runAsync = options.runAsync ?? false; + // Configured staging completes before the facade returns, so retain inline + // results even when the caller requests asynchronous execution. + const runAsync = (options.runAsync ?? false) && options.stagingAllowedLocalPath === undefined; // `queryTimeout` is a NO-OP on the kernel (kernel) backend. It is the JDBC // `setQueryTimeout` knob which — per the option's JSDoc — is effective only // on Compute clusters; SQL Warehouses (what kernel targets) use the diff --git a/tests/unit/kernel/execution.test.ts b/tests/unit/kernel/execution.test.ts index ef064b87..93c0150e 100644 --- a/tests/unit/kernel/execution.test.ts +++ b/tests/unit/kernel/execution.test.ts @@ -970,6 +970,20 @@ describe('KernelSessionBackend', () => { expect(op.id).to.be.a('string').and.have.length.greaterThan(0); }); + for (const stagingAllowedLocalPath of [[], '/tmp']) { + it(`retains inline results for configured async staging paths ${JSON.stringify( + stagingAllowedLocalPath, + )}`, async () => { + const connection = new FakeNativeConnection(); + const direct = sinon.spy(connection, 'executeStatementDirect'); + const submit = sinon.spy(connection, 'submitStatement'); + const session = makeSession(connection); + await session.executeStatement('REMOVE remote', { runAsync: true, stagingAllowedLocalPath }); + expect(direct.calledOnce).to.equal(true); + expect(submit.called).to.equal(false); + }); + } + it('executeStatement (sync default) routes a still-running query through the AsyncStatement arm', async () => { // The directResults Running arm — a query that did NOT finish within the // server inline wait comes back as an AsyncStatement (poll/cancel handle). From f48292418db596f09a41a60243fe630d623594b2 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Fri, 13 Nov 2026 23:38:01 +0000 Subject: [PATCH 03/37] Correct Volume backend support documentation Signed-off-by: Aakash Saravanan --- CONNECTION_PARAMETERS.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONNECTION_PARAMETERS.md b/CONNECTION_PARAMETERS.md index 679b54cc..d8fe8d76 100644 --- a/CONNECTION_PARAMETERS.md +++ b/CONNECTION_PARAMETERS.md @@ -244,8 +244,7 @@ session parameter surface. Thrift-only capabilities include custom/token-provider authentication, custom OAuth persistence, SOCKS proxies, authenticated/driver-buffer telemetry knobs, -query timeout, Direct Results `maxRows`, per-statement CloudFetch/LZ4 hints, and -volume operations. +query timeout, Direct Results `maxRows`, and per-statement CloudFetch/LZ4 hints. Kernel-only capabilities include connection-pool sizing, proxy bypass hosts, independent TLS hostname verification, optional U2M disk caching, and From c1f0821639da9eaf0898305f3e4b5f83ce3c5097 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Sat, 14 Nov 2026 00:07:10 +0000 Subject: [PATCH 04/37] Pin the native source for Volume completion Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index 18337b65..f85bb468 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -dac32e2bf44468bdab06747dad4f289d1c0a18bd +bdc4d35693ab94ee1991799d12a40503fdf66670 From 9d95ba0ac115ea72af1570ac422e308955d7bb11 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Sat, 14 Nov 2026 00:15:38 +0000 Subject: [PATCH 05/37] Select the Volume kernel and format its path option Signed-off-by: Aakash Saravanan --- CONNECTION_PARAMETERS.md | 2 +- KERNEL_REV | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CONNECTION_PARAMETERS.md b/CONNECTION_PARAMETERS.md index d8fe8d76..71163721 100644 --- a/CONNECTION_PARAMETERS.md +++ b/CONNECTION_PARAMETERS.md @@ -213,7 +213,7 @@ telemetry implementation, so only the options explicitly forwarded by | `maxRows` | `number \| bigint \| Int64 \| null` | ✅ | ❌ | `100000` / — | Thrift uses it for the initial Direct Results row count; `null` disables Direct Results. Kernel does not retain or forward the supplied value. | | `useCloudFetch` | `boolean` | ✅ | ❌ | `true` / — | Kernel logs and ignores this per-statement hint; Kernel result fetching owns its CloudFetch behavior. | | `useLZ4Compression` | `boolean` | ✅ | ❌ | `true` / — | Thrift uses it when supported and when the result is not CloudFetch. Kernel owns and auto-detects result compression. | -| `stagingAllowedLocalPath` | `string \| string[]` | ✅ | ✅ | — | Local allowlist for Volume operations. Kernel also requires resolved symlink targets within allowed roots; links within those roots are permitted. | +| `stagingAllowedLocalPath` | `string \| string[]` | ✅ | ✅ | — | Local allowlist for Volume operations. Kernel also requires resolved symlink targets within allowed roots; links within those roots are permitted. | | `namedParameters` | `Record` | ✅ | ✅ | — | Named SQL parameters. Cannot be combined with non-empty `ordinalParameters`. Thrift requires a protocol that supports parameterized queries. | | `ordinalParameters` | `Array` | ✅ | ✅ | — | Positional SQL parameters. Cannot be combined with non-empty `namedParameters`. | | `queryTags` | `Record` | ✅ | ✅ | — | Serialized into the per-statement `query_tags` conf overlay on both. | diff --git a/KERNEL_REV b/KERNEL_REV index f85bb468..a34a99f0 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -bdc4d35693ab94ee1991799d12a40503fdf66670 +c22bd606abc48599ab780a65a1389d141c3414bf From f6de7d37e75a6bb9a0be4f56ab6f339658de18ef Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Sat, 14 Nov 2026 00:32:32 +0000 Subject: [PATCH 06/37] Regenerate Volume completion declarations from the pinned kernel Signed-off-by: Aakash Saravanan --- native/kernel/index.d.ts | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/native/kernel/index.d.ts b/native/kernel/index.d.ts index b531ff13..460cf061 100644 --- a/native/kernel/index.d.ts +++ b/native/kernel/index.d.ts @@ -18,8 +18,9 @@ * post-close contract. */ export declare class AsyncResultHandle { - get isVolumeOperation(): boolean; - completeVolumeOperation(allowedPaths: Array, removeNotFoundIsSuccess?: boolean | undefined | null): Promise; + get isVolumeOperation(): boolean + /** Complete a server-marked file transfer while retaining its instruction rows. */ + completeVolumeOperation(allowedPaths: Array, removeNotFoundIsSuccess?: boolean | undefined | null): Promise /** * Server-issued statement id. Cached at construction; readable * for log correlation. Matches the parent `AsyncStatement`'s @@ -440,8 +441,9 @@ export declare class Connection { * disposed statement can still read them. */ export declare class Statement { - get isVolumeOperation(): boolean; - completeVolumeOperation(allowedPaths: Array, removeNotFoundIsSuccess?: boolean | undefined | null): Promise; + get isVolumeOperation(): boolean + /** Complete a server-marked file transfer while retaining its instruction rows. */ + completeVolumeOperation(allowedPaths: Array, removeNotFoundIsSuccess?: boolean | undefined | null): Promise /** * Server-issued statement id. Cached at construction; readable * even after `close()` so JS-side log lines can correlate against From 973bad3c236aedadcbd42a6d0e872d095685a765 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Sat, 14 Nov 2026 02:42:18 +0000 Subject: [PATCH 07/37] Preserve SQL execution errors during Volume completion Signed-off-by: Aakash Saravanan --- lib/kernel/KernelOperationBackend.ts | 2 +- tests/unit/DBSQLSession.test.ts | 20 ++++++++ .../kernel/KernelOperationBackend.test.ts | 46 +++++++++++++++++++ 3 files changed, 67 insertions(+), 1 deletion(-) diff --git a/lib/kernel/KernelOperationBackend.ts b/lib/kernel/KernelOperationBackend.ts index 05eb54b0..bf8673fa 100644 --- a/lib/kernel/KernelOperationBackend.ts +++ b/lib/kernel/KernelOperationBackend.ts @@ -317,8 +317,8 @@ export default class KernelOperationBackend implements IOperationBackend { public async completeStagingOperation(allowedPaths: string[]): Promise { failIfNotActive(this.lifecycle); + const handle = await this.getFetchHandle(); try { - const handle = await this.getFetchHandle(); const outcome = await handle.completeVolumeOperation(allowedPaths, true); if (outcome === 'needs_input_stream') { throw new StagingError('Volume PUT requires a local file path'); diff --git a/tests/unit/DBSQLSession.test.ts b/tests/unit/DBSQLSession.test.ts index 7c73c1c0..505e1b4f 100644 --- a/tests/unit/DBSQLSession.test.ts +++ b/tests/unit/DBSQLSession.test.ts @@ -886,6 +886,26 @@ describe('DBSQLSession', () => { }); describe('DBSQLSession native staging dispatch', () => { + it('closes a failed native operation and preserves its error when close also fails', async () => { + const error = new Error('completion failed'); + const close = sinon.stub().rejects(new Error('close failed')); + const op = { + id: 'volume-operation', + completeStagingOperation: sinon.stub().rejects(error), + close, + } as unknown as IOperationBackend; + const session = new DBSQLSession({ + backend: { id: 'volume-session', executeStatement: async () => op } as unknown as ISessionBackend, + context: new ClientContextStub(), + }); + const actual = await session.executeStatement('GET remote TO local', { stagingAllowedLocalPath: [] }).then( + () => expect.fail('completion should fail'), + (failure) => failure, + ); + expect(actual).to.equal(error); + expect(close.callCount).to.equal(1); + }); + for (const configured of [false, true]) { it(`calls native completion only when local paths are ${configured ? 'configured' : 'omitted'}`, async () => { const completeStagingOperation = sinon.stub().resolves(); diff --git a/tests/unit/kernel/KernelOperationBackend.test.ts b/tests/unit/kernel/KernelOperationBackend.test.ts index 695e82f7..ba34ac45 100644 --- a/tests/unit/kernel/KernelOperationBackend.test.ts +++ b/tests/unit/kernel/KernelOperationBackend.test.ts @@ -40,6 +40,8 @@ import { import KernelOperationBackend from '../../../lib/kernel/KernelOperationBackend'; import { TTypeId } from '../../../thrift/TCLIService_types'; import ClientContextStub from '../.stubs/ClientContextStub'; +import ParameterError from '../../../lib/errors/ParameterError'; +import StagingError from '../../../lib/errors/StagingError'; // Minimal stub of the napi `Statement` surface that emits a precomputed // Arrow IPC payload per `fetchNextBatch()` call. Used to feed @@ -391,6 +393,50 @@ describe('KernelOperationBackend — M0 datatype round-trip via napi → ArrowRe }); describe('KernelOperationBackend Volume completion', () => { + it('preserves SQL execution errors with HTTP metadata', async () => { + const error = Object.assign(new ParameterError('invalid SQL parameter'), { + sqlState: '22023', + kernelMetadata: { httpStatus: 400 }, + }); + const backend = new KernelOperationBackend({ + cancellableExecution: { + result: async () => { + throw error; + }, + } as any, + context: new ClientContextStub(), + }); + const actual = await backend.completeStagingOperation(['/allowed']).then( + () => expect.fail('execution should fail'), + (failure) => failure, + ); + expect(actual).to.equal(error); + expect(actual.sqlState).to.equal('22023'); + }); + + for (const error of [ + new ParameterError('path is not allowed'), + Object.assign(new Error('storage HTTP 403'), { kernelMetadata: { httpStatus: 403 } }), + Object.assign(new Error('source is missing'), { code: 'ENOENT', path: '/allowed/missing' }), + ]) { + it(`classifies transfer failure: ${error.message}`, async () => { + const schema = new Schema([withTypeName(new Field('x', new Int32(), true), 'INT')]); + const statement = new StatementStub(ipcSchemaOnly(schema), []); + Object.assign(statement, { + completeVolumeOperation: async () => { + throw error; + }, + }); + const backend = new KernelOperationBackend({ statement, context: new ClientContextStub() }); + const actual = await backend.completeStagingOperation(['/allowed']).then( + () => expect.fail('transfer should fail'), + (failure) => failure, + ); + if ('code' in error) expect(actual).to.equal(error); + else expect(actual).to.be.instanceOf(StagingError).with.property('message', error.message); + }); + } + it('routes cancellation to the statement after SQL completes', async () => { const schema = new Schema([withTypeName(new Field('x', new Int32(), true), 'INT')]); const statement = new StatementStub(ipcSchemaOnly(schema), []); From 66a4c6116654212d632a3d9b9d39a90004d8736b Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Sat, 14 Nov 2026 02:53:00 +0000 Subject: [PATCH 08/37] Pin native Volume storage retry and terminal response fixes Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index a34a99f0..8a2f8e59 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -c22bd606abc48599ab780a65a1389d141c3414bf +22f96facc276836bcac7230c8a2c0987f734f2c7 From 81c00ae878526862357828c729d066549c460f95 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Sat, 14 Nov 2026 03:32:04 +0000 Subject: [PATCH 09/37] Cover portable native local file error decoding Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- tests/unit/kernel/error-mapping.test.ts | 44 ++++++++++++++++--------- 2 files changed, 29 insertions(+), 17 deletions(-) diff --git a/KERNEL_REV b/KERNEL_REV index 8a2f8e59..47d2f1c8 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -22f96facc276836bcac7230c8a2c0987f734f2c7 +08a921377dd79e5a301e007da7290c1984140952 diff --git a/tests/unit/kernel/error-mapping.test.ts b/tests/unit/kernel/error-mapping.test.ts index 855c4b58..3f606c6e 100644 --- a/tests/unit/kernel/error-mapping.test.ts +++ b/tests/unit/kernel/error-mapping.test.ts @@ -373,19 +373,31 @@ describe('KernelErrorMapping.decodeNapiKernelError — cause chain', () => { }); }); -it('preserves local file error code and path from native completion', () => { - const error = decodeNapiKernelError( - new Error( - `__databricks_error__:${JSON.stringify({ - code: 'NotFound', - message: 'Local file does not exist', - localOsError: 2, - localErrorKind: 'NotFound', - localPath: '/allowed/missing', - })}`, - ), - ) as NodeJS.ErrnoException; - expect(error.code).to.equal('ENOENT'); - expect(error.path).to.equal('/allowed/missing'); - expect(error.errno).to.be.lessThan(0); -}); +for (const [raw, kind, expected] of [ + [2, 'NotFound', 'ENOENT'], + [undefined, 'PermissionDenied', 'EACCES'], + [0, 'PermissionDenied', 'EACCES'], + [undefined, 'Unrecognized', 'EIO'], +] as const) { + it(`preserves local file error code and path for ${kind}/${raw}`, () => { + const error = decodeNapiKernelError( + new Error( + `__databricks_error__:${JSON.stringify({ + code: 'NotFound', + message: 'Local file does not exist', + localOsError: raw, + localErrorKind: kind, + localPath: '/allowed/missing', + sqlState: 'HY000', + queryId: 'query-id', + })}`, + ), + ) as NodeJS.ErrnoException; + expect(error.code).to.equal(expected); + expect(error.path).to.equal('/allowed/missing'); + expect(error.errno).to.be.lessThan(0); + expect(error).to.have.property('kernelMetadata').with.property('queryId', 'query-id'); + expect(error).to.have.property('cause').that.is.instanceOf(Error); + expect(error).not.to.have.property('sqlState'); + }); +} From e080abd048b8cd60103f3465cb1b2be2d30740fc Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Sat, 14 Nov 2026 05:19:17 +0000 Subject: [PATCH 10/37] Preserve deferred Volume instruction HTTP errors Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- lib/kernel/KernelOperationBackend.ts | 7 ++-- .../kernel/KernelOperationBackend.test.ts | 34 ++++++++++++++++++- 3 files changed, 38 insertions(+), 5 deletions(-) diff --git a/KERNEL_REV b/KERNEL_REV index 47d2f1c8..bc57504b 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -08a921377dd79e5a301e007da7290c1984140952 +855847bdca71e07285cfc60332fb2f33f8e47786 diff --git a/lib/kernel/KernelOperationBackend.ts b/lib/kernel/KernelOperationBackend.ts index bf8673fa..844a6e36 100644 --- a/lib/kernel/KernelOperationBackend.ts +++ b/lib/kernel/KernelOperationBackend.ts @@ -53,7 +53,7 @@ import ArrowResultConverter from '../result/ArrowResultConverter'; import ResultSlicer from '../result/ResultSlicer'; import KernelResultsProvider from './KernelResultsProvider'; import { arrowSchemaToThriftSchema, decodeIpcSchema, patchIpcBytes } from './KernelArrowIpc'; -import { decodeNapiKernelError } from './KernelErrorMapping'; +import { decodeNapiKernelError, ErrorWithSqlState } from './KernelErrorMapping'; import { KernelStatement, KernelNativeAsyncStatement, @@ -326,9 +326,10 @@ export default class KernelOperationBackend implements IOperationBackend { this.volumeCompleted = outcome === 'completed'; } catch (err) { const mapped = decodeNapiKernelError(err); + const metadata = (mapped as ErrorWithSqlState).kernelMetadata; if ( - mapped instanceof ParameterError || - (mapped as { kernelMetadata?: { httpStatus?: number } }).kernelMetadata?.httpStatus + (mapped instanceof ParameterError && !metadata?.httpStatus) || + metadata?.errorCode === 'VOLUME_STORAGE_HTTP_ERROR' ) { throw new StagingError(mapped.message); } diff --git a/tests/unit/kernel/KernelOperationBackend.test.ts b/tests/unit/kernel/KernelOperationBackend.test.ts index ba34ac45..5b0a6c71 100644 --- a/tests/unit/kernel/KernelOperationBackend.test.ts +++ b/tests/unit/kernel/KernelOperationBackend.test.ts @@ -41,6 +41,7 @@ import KernelOperationBackend from '../../../lib/kernel/KernelOperationBackend'; import { TTypeId } from '../../../thrift/TCLIService_types'; import ClientContextStub from '../.stubs/ClientContextStub'; import ParameterError from '../../../lib/errors/ParameterError'; +import AuthenticationError from '../../../lib/errors/AuthenticationError'; import StagingError from '../../../lib/errors/StagingError'; // Minimal stub of the napi `Statement` surface that emits a precomputed @@ -416,7 +417,9 @@ describe('KernelOperationBackend Volume completion', () => { for (const error of [ new ParameterError('path is not allowed'), - Object.assign(new Error('storage HTTP 403'), { kernelMetadata: { httpStatus: 403 } }), + Object.assign(new Error('storage HTTP 403'), { + kernelMetadata: { httpStatus: 403, errorCode: 'VOLUME_STORAGE_HTTP_ERROR' }, + }), Object.assign(new Error('source is missing'), { code: 'ENOENT', path: '/allowed/missing' }), ]) { it(`classifies transfer failure: ${error.message}`, async () => { @@ -437,6 +440,35 @@ describe('KernelOperationBackend Volume completion', () => { }); } + for (const error of [ + Object.assign(new AuthenticationError('instruction session expired'), { + sqlState: '08003', + kernelMetadata: { httpStatus: 401, errorCode: 'SESSION_EXPIRED' }, + }), + Object.assign(new ParameterError('invalid instruction request'), { + sqlState: '22023', + kernelMetadata: { httpStatus: 400 }, + }), + ]) { + it(`preserves deferred instruction errors: ${error.message}`, async () => { + const schema = new Schema([withTypeName(new Field('x', new Int32(), true), 'INT')]); + const statement = new StatementStub(ipcSchemaOnly(schema), []); + Object.assign(statement, { + completeVolumeOperation: async () => { + throw error; + }, + }); + const backend = new KernelOperationBackend({ statement, context: new ClientContextStub() }); + const actual = await backend.completeStagingOperation(['/allowed']).then( + () => expect.fail('instruction fetch should fail'), + (failure) => failure, + ); + expect(actual).to.equal(error); + expect(actual.sqlState).to.equal(error.sqlState); + expect(actual.kernelMetadata).to.equal(error.kernelMetadata); + }); + } + it('routes cancellation to the statement after SQL completes', async () => { const schema = new Schema([withTypeName(new Field('x', new Int32(), true), 'INT')]); const statement = new StatementStub(ipcSchemaOnly(schema), []); From 3ec62f55b038f1aacba6c3dc8639ba4e6ba0ea30 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Sat, 14 Nov 2026 05:39:29 +0000 Subject: [PATCH 11/37] Preserve portable file error fallback for unknown errno values Signed-off-by: Aakash Saravanan --- lib/kernel/KernelErrorMapping.ts | 5 ++--- tests/unit/kernel/error-mapping.test.ts | 2 ++ 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/lib/kernel/KernelErrorMapping.ts b/lib/kernel/KernelErrorMapping.ts index fcd2f35b..ac78d2d8 100644 --- a/lib/kernel/KernelErrorMapping.ts +++ b/lib/kernel/KernelErrorMapping.ts @@ -324,10 +324,9 @@ export function decodeNapiKernelError(err: unknown): Error { DirectoryNotEmpty: 'ENOTEMPTY', }; const raw = typeof envelope.localOsError === 'number' ? envelope.localOsError : undefined; + const systemCode = process.platform !== 'win32' && raw ? getSystemErrorName(-Math.abs(raw)) : undefined; const localCode = - process.platform !== 'win32' && raw - ? getSystemErrorName(-Math.abs(raw)) - : kindCodes[envelope.localErrorKind] ?? 'EIO'; + systemCode && /^E[A-Z0-9]+$/.test(systemCode) ? systemCode : kindCodes[envelope.localErrorKind] ?? 'EIO'; jsErr = Object.assign(new Error(msg), { code: localCode, errno: -((constants.errno as Record)[localCode] ?? Math.abs(raw ?? constants.errno.EIO)), diff --git a/tests/unit/kernel/error-mapping.test.ts b/tests/unit/kernel/error-mapping.test.ts index 3f606c6e..00038b89 100644 --- a/tests/unit/kernel/error-mapping.test.ts +++ b/tests/unit/kernel/error-mapping.test.ts @@ -378,6 +378,8 @@ for (const [raw, kind, expected] of [ [undefined, 'PermissionDenied', 'EACCES'], [0, 'PermissionDenied', 'EACCES'], [undefined, 'Unrecognized', 'EIO'], + [1000000, 'NotFound', 'ENOENT'], + [1000000, 'Unrecognized', 'EIO'], ] as const) { it(`preserves local file error code and path for ${kind}/${raw}`, () => { const error = decodeNapiKernelError( From 240c70f47830e667dd91c9859c55c41f8544a899 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Sat, 14 Nov 2026 23:54:43 +0000 Subject: [PATCH 12/37] build(kernel): select corrected Volume completion Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index bc57504b..53687ee1 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -855847bdca71e07285cfc60332fb2f33f8e47786 +a543bbc572b627f059461fce351713da8cb59df9 From 69cc1422a6a78625bf0422116e62e9a6ea1c1c66 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Sun, 15 Nov 2026 01:48:44 +0000 Subject: [PATCH 13/37] build: select native Volume cancellation and error handling Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index 53687ee1..3232e69a 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -a543bbc572b627f059461fce351713da8cb59df9 +566fe7f0a8a2fa246db95045a7000136ee6070d5 From 8b6e7fd8551a810b664ee132c2b58ba83b92f136 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Sun, 15 Nov 2026 05:35:54 +0000 Subject: [PATCH 14/37] build: use native root authorization fix Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index 3232e69a..e0f04c9a 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -566fe7f0a8a2fa246db95045a7000136ee6070d5 +de28034ec75aa6773a5e4e904d77f85511e1aa78 From 8bfa89c02e6b98b22d139f78d5a3118b27ef2fea Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Sun, 15 Nov 2026 07:56:57 +0000 Subject: [PATCH 15/37] build: update kernel source for replayable uploads Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index e0f04c9a..a85af789 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -de28034ec75aa6773a5e4e904d77f85511e1aa78 +8dd87c0ec0199cae6b3e5bf9cd973e7025409b45 From 13b0e6024415ebe4726fb13313a39f73230dcd92 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Sun, 15 Nov 2026 08:21:05 +0000 Subject: [PATCH 16/37] build: update kernel for local stream close Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index a85af789..e3eed1aa 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -8dd87c0ec0199cae6b3e5bf9cd973e7025409b45 +5b2b1da9aef7444f614d99f05cd7512a1afbe075 From 7f8736de3d5df20db1d71eb4b6a54d045357e906 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Sun, 15 Nov 2026 23:44:25 +0000 Subject: [PATCH 17/37] fix(volume): select replayable file uploads and tighten validation Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index e3eed1aa..d7abc8c7 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -5b2b1da9aef7444f614d99f05cd7512a1afbe075 +1347031d3c66e9179cec0a404efebe3685c26802 From f2e3d68d1dd08160230af9d9f46454cd65898f2c Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Mon, 16 Nov 2026 00:49:22 +0000 Subject: [PATCH 18/37] fix(kernel): use permission-preserving Volume downloads Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- lib/kernel/KernelSessionBackend.ts | 7 +++---- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/KERNEL_REV b/KERNEL_REV index d7abc8c7..8707bb23 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -1347031d3c66e9179cec0a404efebe3685c26802 +f265b7d78e045d7d28f082084d60e2b0dd3ba367 diff --git a/lib/kernel/KernelSessionBackend.ts b/lib/kernel/KernelSessionBackend.ts index a074d4b2..3fe5919f 100644 --- a/lib/kernel/KernelSessionBackend.ts +++ b/lib/kernel/KernelSessionBackend.ts @@ -148,10 +148,9 @@ export default class KernelSessionBackend implements ISessionBackend { * `query_tags` key (the same wire shape Thrift's `serializeQueryTags` * produces), merged with any explicit `statementConf`. * - * Still rejected (genuinely unsupported on kernel, rather than silently - * dropped): `useCloudFetch` (governed by the kernel `ResultConfig`, not a - * per-statement knob), `useLZ4Compression` (kernel owns result compression), - * while `stagingAllowedLocalPath` is applied by the facade. `maxRows` is applied by + * `useCloudFetch` and `useLZ4Compression` are logged and ignored because the + * kernel owns result fetching and compression. `stagingAllowedLocalPath` is + * applied by the facade. `maxRows` is applied by * the facade at fetch time, so it is intentionally not handled here. */ public async executeStatement(statement: string, options: ExecuteStatementOptions): Promise { From 5658cb516a7311834e52f57ba37e44345616bdaa Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Mon, 16 Nov 2026 01:05:06 +0000 Subject: [PATCH 19/37] build(kernel): select sanitized storage redirects Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index 8707bb23..2df78f70 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -f265b7d78e045d7d28f082084d60e2b0dd3ba367 +de19f0dd234c5dc0894c6267001630c923901f32 From a8029e01295865b2f580a0661f1c54f10e5d7bf7 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Mon, 16 Nov 2026 06:54:01 +0000 Subject: [PATCH 20/37] Clarify Volume cancellation and consolidate routing coverage Signed-off-by: Aakash Saravanan --- lib/kernel/KernelOperationBackend.ts | 5 ++--- tests/unit/kernel/execution.test.ts | 22 +++++++++------------- 2 files changed, 11 insertions(+), 16 deletions(-) diff --git a/lib/kernel/KernelOperationBackend.ts b/lib/kernel/KernelOperationBackend.ts index 844a6e36..1aa3f573 100644 --- a/lib/kernel/KernelOperationBackend.ts +++ b/lib/kernel/KernelOperationBackend.ts @@ -258,9 +258,8 @@ export default class KernelOperationBackend implements IOperationBackend { this.cancellableExecution = cancellableExecution; this.blockingStatement = statement; // Lifecycle surface. The async/metadata handles expose both cancel/close. - // The sync-execute path uses a composite: `cancel()` always routes to the - // cancellable execution (lock-free, interrupts a running `result()` - // mid-compute and is a no-op once terminal); `close()` closes the resolved + // The sync-execute path uses a composite so SQL execution and subsequent + // transfer completion remain cancellable. `close()` closes the resolved // terminal statement once `result()` produced it, OR — if `result()` is // still in flight — proactively cancels the running execution so the server // stops computing immediately rather than running on until the kernel's diff --git a/tests/unit/kernel/execution.test.ts b/tests/unit/kernel/execution.test.ts index 93c0150e..97c22e12 100644 --- a/tests/unit/kernel/execution.test.ts +++ b/tests/unit/kernel/execution.test.ts @@ -970,19 +970,15 @@ describe('KernelSessionBackend', () => { expect(op.id).to.be.a('string').and.have.length.greaterThan(0); }); - for (const stagingAllowedLocalPath of [[], '/tmp']) { - it(`retains inline results for configured async staging paths ${JSON.stringify( - stagingAllowedLocalPath, - )}`, async () => { - const connection = new FakeNativeConnection(); - const direct = sinon.spy(connection, 'executeStatementDirect'); - const submit = sinon.spy(connection, 'submitStatement'); - const session = makeSession(connection); - await session.executeStatement('REMOVE remote', { runAsync: true, stagingAllowedLocalPath }); - expect(direct.calledOnce).to.equal(true); - expect(submit.called).to.equal(false); - }); - } + it('retains inline results for configured async staging paths', async () => { + const connection = new FakeNativeConnection(); + const direct = sinon.spy(connection, 'executeStatementDirect'); + const submit = sinon.spy(connection, 'submitStatement'); + const session = makeSession(connection); + await session.executeStatement('REMOVE remote', { runAsync: true, stagingAllowedLocalPath: [] }); + expect(direct.calledOnce).to.equal(true); + expect(submit.called).to.equal(false); + }); it('executeStatement (sync default) routes a still-running query through the AsyncStatement arm', async () => { // The directResults Running arm — a query that did NOT finish within the From baf8c7d49f95c9fc04abfeb6036692220e7bc3c4 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Mon, 16 Nov 2026 07:12:39 +0000 Subject: [PATCH 21/37] Validate native file error numbers and select shared completion Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- lib/kernel/KernelErrorMapping.ts | 5 ++++- tests/unit/kernel/error-mapping.test.ts | 2 ++ 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/KERNEL_REV b/KERNEL_REV index 2df78f70..cc9fd909 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -de19f0dd234c5dc0894c6267001630c923901f32 +30c8d8e7ae45b72cf2ff6b6333356a6b37fd533f diff --git a/lib/kernel/KernelErrorMapping.ts b/lib/kernel/KernelErrorMapping.ts index ac78d2d8..2239444b 100644 --- a/lib/kernel/KernelErrorMapping.ts +++ b/lib/kernel/KernelErrorMapping.ts @@ -323,7 +323,10 @@ export function decodeNapiKernelError(err: unknown): Error { IsADirectory: 'EISDIR', DirectoryNotEmpty: 'ENOTEMPTY', }; - const raw = typeof envelope.localOsError === 'number' ? envelope.localOsError : undefined; + const raw = + typeof envelope.localOsError === 'number' && Number.isSafeInteger(envelope.localOsError) + ? envelope.localOsError + : undefined; const systemCode = process.platform !== 'win32' && raw ? getSystemErrorName(-Math.abs(raw)) : undefined; const localCode = systemCode && /^E[A-Z0-9]+$/.test(systemCode) ? systemCode : kindCodes[envelope.localErrorKind] ?? 'EIO'; diff --git a/tests/unit/kernel/error-mapping.test.ts b/tests/unit/kernel/error-mapping.test.ts index 00038b89..f739eae0 100644 --- a/tests/unit/kernel/error-mapping.test.ts +++ b/tests/unit/kernel/error-mapping.test.ts @@ -380,6 +380,8 @@ for (const [raw, kind, expected] of [ [undefined, 'Unrecognized', 'EIO'], [1000000, 'NotFound', 'ENOENT'], [1000000, 'Unrecognized', 'EIO'], + [1.5, 'NotFound', 'ENOENT'], + [Number.MAX_SAFE_INTEGER + 1, 'Unrecognized', 'EIO'], ] as const) { it(`preserves local file error code and path for ${kind}/${raw}`, () => { const error = decodeNapiKernelError( From a35f7e1b1c4f10f58cb63933d962f8d899699d1c Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Mon, 16 Nov 2026 19:28:55 +0000 Subject: [PATCH 22/37] Pin kernel with statement lifecycle cleanup Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index cc9fd909..1b8d987f 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -30c8d8e7ae45b72cf2ff6b6333356a6b37fd533f +728f6cf0931a9e3c321f63534fce240115bdb2f5 From d54e1afd48a94b2b6c52e5e5d4e941eda29e4632 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Mon, 16 Nov 2026 21:17:15 +0000 Subject: [PATCH 23/37] build: select kernel with async result cleanup Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index 1b8d987f..d6c502ff 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -728f6cf0931a9e3c321f63534fce240115bdb2f5 +029c59cc42727d0294e1a2dc378c78929030a919 From c4b5c4cb3fd5464b1c7774844b9124c82766991e Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Mon, 16 Nov 2026 21:51:17 +0000 Subject: [PATCH 24/37] build: select kernel with Volume instruction error telemetry Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index d6c502ff..d5bed17a 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -029c59cc42727d0294e1a2dc378c78929030a919 +ab4f133620fce52f9932508f0b245db630a57c48 From ec92b5bd617cc1372b015de53f83cadf0554e826 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Mon, 16 Nov 2026 23:57:03 +0000 Subject: [PATCH 25/37] build: pin kernel with complete Volume instruction handling Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index d5bed17a..28a4d122 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -ab4f133620fce52f9932508f0b245db630a57c48 +d9fcf834d36dc7f3de1621225db716200151fa0f From 3be7f970402509bb3efe3248de7c32507e6243c2 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Tue, 17 Nov 2026 00:14:56 +0000 Subject: [PATCH 26/37] fix(kernel): preserve ordinary post-SQL cancellation routing Signed-off-by: Aakash Saravanan --- lib/kernel/KernelOperationBackend.ts | 7 ++-- .../kernel/KernelOperationBackend.test.ts | 39 ++++++++++--------- 2 files changed, 25 insertions(+), 21 deletions(-) diff --git a/lib/kernel/KernelOperationBackend.ts b/lib/kernel/KernelOperationBackend.ts index 1aa3f573..2b578d6e 100644 --- a/lib/kernel/KernelOperationBackend.ts +++ b/lib/kernel/KernelOperationBackend.ts @@ -200,8 +200,8 @@ export default class KernelOperationBackend implements IOperationBackend { // The cancel/close surface — whichever handle backs this operation. Both // `AsyncStatement` and `Statement` expose `cancel()` / `close()`; the - // sync-execute path uses a composite that routes `cancel()` to the - // cancellable execution (mid-compute) and `close()` to the resolved statement. + // sync-execute path keeps the execution canceller for SQL and uses the + // resolved statement to cancel marked transfers after SQL completes. private readonly lifecycleHandle: KernelStatementHandle; private readonly context: IClientContext; @@ -266,7 +266,8 @@ export default class KernelOperationBackend implements IOperationBackend { // drop-guard fires whenever this handle is eventually GC'd. this.lifecycleHandle = cancellableExecution ? { - cancel: () => (this.blockingStatement ? this.blockingStatement.cancel() : cancellableExecution.cancel()), + cancel: () => + this.blockingStatement?.isVolumeOperation ? this.blockingStatement.cancel() : cancellableExecution.cancel(), close: () => (this.blockingStatement ? this.blockingStatement.close() : cancellableExecution.cancel()), } : ((asyncStatement ?? statement) as KernelStatementHandle); diff --git a/tests/unit/kernel/KernelOperationBackend.test.ts b/tests/unit/kernel/KernelOperationBackend.test.ts index 5b0a6c71..3d60ac27 100644 --- a/tests/unit/kernel/KernelOperationBackend.test.ts +++ b/tests/unit/kernel/KernelOperationBackend.test.ts @@ -469,25 +469,28 @@ describe('KernelOperationBackend Volume completion', () => { }); } - it('routes cancellation to the statement after SQL completes', async () => { - const schema = new Schema([withTypeName(new Field('x', new Int32(), true), 'INT')]); - const statement = new StatementStub(ipcSchemaOnly(schema), []); - let executionCancelled = false; - const execution = { - result: async () => statement, - cancel: async () => { - executionCancelled = true; - }, - }; - const backend = new KernelOperationBackend({ - cancellableExecution: execution as any, - context: new ClientContextStub(), + for (const isVolumeOperation of [false, true]) { + it(`routes ${isVolumeOperation ? 'Volume' : 'ordinary'} cancellation after SQL completes`, async () => { + const schema = new Schema([withTypeName(new Field('x', new Int32(), true), 'INT')]); + const statement = new StatementStub(ipcSchemaOnly(schema), []); + Object.assign(statement, { isVolumeOperation }); + let executionCancelled = false; + const execution = { + result: async () => statement, + cancel: async () => { + executionCancelled = true; + }, + }; + const backend = new KernelOperationBackend({ + cancellableExecution: execution as any, + context: new ClientContextStub(), + }); + await backend.getResultMetadata(); + await backend.cancel(); + expect(statement.cancelled).to.equal(isVolumeOperation); + expect(executionCancelled).to.equal(!isVolumeOperation); }); - await backend.getResultMetadata(); - await backend.cancel(); - expect(statement.cancelled).to.equal(true); - expect(executionCancelled).to.equal(false); - }); + } for (const outcome of ['completed', 'not_volume']) { it(`${ From a7c7fd19b4b2efb296fe75faa75699bbddf19217 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Tue, 17 Nov 2026 19:30:05 +0000 Subject: [PATCH 27/37] build: use corrected kernel volume completion Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index 28a4d122..d90f708d 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -d9fcf834d36dc7f3de1621225db716200151fa0f +4e90b0d058469dcb9cc67a8114edcbea1d2d6831 From 1f87603176207a2fa05381730435ee2c2b64bf52 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Tue, 17 Nov 2026 22:00:51 +0000 Subject: [PATCH 28/37] build: select kernel with origin-safe Volume redirects Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index d90f708d..9faa7f3b 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -4e90b0d058469dcb9cc67a8114edcbea1d2d6831 +eaf1382d605dc18a0e5c220c3e502f9cbd7e9546 From 0b4d434b753376871dfca59c5d1825d84f55cf73 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Tue, 17 Nov 2026 22:29:51 +0000 Subject: [PATCH 29/37] build: select kernel with normalized upload lengths Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index 9faa7f3b..496a772e 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -eaf1382d605dc18a0e5c220c3e502f9cbd7e9546 +d3b85c23183c2415b2dbb4385b348f3fed6e21ae From c89456feaaf98a4b7a526ade38a6cef5c9714cbf Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Tue, 17 Nov 2026 23:25:53 +0000 Subject: [PATCH 30/37] docs: keep unreleased changelog entries in one list Signed-off-by: Aakash Saravanan --- CHANGELOG.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c7e372c8..8fd334f0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,6 @@ - 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. - Reduce result chunking and `fetchAll()` overhead for large query results. - Support Volume file transfers on the kernel backend when `stagingAllowedLocalPath` is supplied. Symlink targets must remain within configured allowed roots; in-root symlinks are permitted. - - Thrift CloudFetch downloads are now bounded end to end by `retriesTimeout` (default 15 minutes), including every attempt and retry backoff. Previously a stalled download, where the response headers or body never arrived, blocked the fetch forever. A download still running when the deadline expires is aborted and fails with `RetryError` (`TIMEOUT_EXCEEDED`, message `CloudFetch result download failed: Retry timeout exceeded`). (#520) - Thrift connections made through `proxy` now apply `checkServerCertificate`, `customCaCert` and `clientCert`/`clientKey`. Previously the proxied path ignored them and verified against Node's process-wide trust store, so a certificate outside the configured trust set could be accepted. **Compatibility:** proxied connections now verify unless `checkServerCertificate: false` is set; as on direct connections, `NODE_TLS_REJECT_UNAUTHORIZED=0` no longer turns verification off. For an `https` proxy these options also apply to the proxy's own certificate. (#485) - Honor the client `useCloudFetch: false` default on the kernel backend so complete results can be fetched without cloud-storage downloads. (#574) From 52c78ca827e881357814c6bd5bfca54d3f987e09 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Tue, 17 Nov 2026 23:56:09 +0000 Subject: [PATCH 31/37] build: pin kernel completion telemetry correction Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index 496a772e..085b4541 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -d3b85c23183c2415b2dbb4385b348f3fed6e21ae +7af876f6782418f9c90d3d0c7dbf96fab278f75a From 2870cfe7ebcf092e21320568e18182b8f2981acc Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Wed, 18 Nov 2026 03:33:18 +0000 Subject: [PATCH 32/37] build: select kernel with restricted-directory GET support Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index 085b4541..9c0856a4 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -7af876f6782418f9c90d3d0c7dbf96fab278f75a +21856dea28e87fdf61d328e7f21d5484d7b618b4 From c7a9e46e42e31d4d21c46e70ae436816479f9682 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Wed, 18 Nov 2026 03:56:29 +0000 Subject: [PATCH 33/37] fix(kernel): cancel pending result waits before close Signed-off-by: Aakash Saravanan --- lib/kernel/KernelOperationBackend.ts | 5 +++ tests/unit/kernel/operation-lifecycle.test.ts | 40 +++++++++++++++++++ 2 files changed, 45 insertions(+) diff --git a/lib/kernel/KernelOperationBackend.ts b/lib/kernel/KernelOperationBackend.ts index 2b578d6e..2867c00c 100644 --- a/lib/kernel/KernelOperationBackend.ts +++ b/lib/kernel/KernelOperationBackend.ts @@ -499,7 +499,12 @@ export default class KernelOperationBackend implements IOperationBackend { } public async close(): Promise { + const wasCloseRequested = this.closeRequested; this.closeRequested = true; + if (!wasCloseRequested && this.asyncStatement && this.fetchHandlePromise && !this.asyncSucceeded) { + // Native close queues behind awaitResult; the detached canceller interrupts it. + await this.asyncStatement.cancel().catch(() => {}); + } return kernelClose(this.lifecycle, this.lifecycleHandle, this.context, this._id); } diff --git a/tests/unit/kernel/operation-lifecycle.test.ts b/tests/unit/kernel/operation-lifecycle.test.ts index 290d343e..3bf37bfb 100644 --- a/tests/unit/kernel/operation-lifecycle.test.ts +++ b/tests/unit/kernel/operation-lifecycle.test.ts @@ -700,6 +700,46 @@ describe('DBSQLSession over KernelSessionBackend — close right after execution expect(session['operations']['items'].size).to.equal(1); }); + for (const cancelFails of [false, true]) { + it(`closes pending staging execution when cancel ${cancelFails ? 'fails' : 'succeeds'}`, async () => { + const { session, connection, asyncStatement } = kernelSession('Running'); + const cancelled = new OperationStateError(OperationStateErrorCode.Canceled); + let rejectResult!: (error: Error) => void; + const pendingResult = new Promise((_, reject) => { + rejectResult = reject; + }); + let started!: () => void; + const awaitingResult = new Promise((resolve) => { + started = resolve; + }); + asyncStatement.awaitResult.callsFake(() => { + started(); + return pendingResult; + }); + asyncStatement.cancel.callsFake(async () => { + rejectResult(cancelled); + if (cancelFails) throw new Error('cancel response failed'); + }); + asyncStatement.close.callsFake(async () => { + await pendingResult.catch(() => {}); + }); + const executing = session.executeStatement('SELECT slow', { stagingAllowedLocalPath: ['/allowed'] }).then( + () => expect.fail('execution should be cancelled'), + (error) => error, + ); + await awaitingResult; + await session.close(); + await session.close(); + + expect(await executing).to.equal(cancelled); + expect(asyncStatement.cancel.calledOnce).to.equal(true); + expect(asyncStatement.cancel.calledBefore(asyncStatement.close)).to.equal(true); + expect(asyncStatement.close.calledOnce).to.equal(true); + expect(connection.close.calledOnce).to.equal(true); + expect(session['operations']['items'].size).to.equal(0); + }); + } + it('retains success observed by status() on a running statement', async () => { const { session, connection, asyncStatement } = kernelSession('Succeeded'); const operation = await session.executeStatement('SELECT slow'); From 887d7d86dc0c150c1245389815e9b0f1c3b4fc8f Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Wed, 18 Nov 2026 04:11:44 +0000 Subject: [PATCH 34/37] fix(kernel): await shared statement disposal on close Signed-off-by: Aakash Saravanan --- lib/kernel/KernelOperationBackend.ts | 24 +++++++++++++------ tests/unit/kernel/operation-lifecycle.test.ts | 23 ++++++++++++++++-- 2 files changed, 38 insertions(+), 9 deletions(-) diff --git a/lib/kernel/KernelOperationBackend.ts b/lib/kernel/KernelOperationBackend.ts index 2867c00c..3e2de9bf 100644 --- a/lib/kernel/KernelOperationBackend.ts +++ b/lib/kernel/KernelOperationBackend.ts @@ -236,6 +236,8 @@ export default class KernelOperationBackend implements IOperationBackend { // kernel closes the result handle either way. private closeRequested = false; + private closePromise?: Promise; + constructor({ asyncStatement, statement, @@ -498,14 +500,22 @@ export default class KernelOperationBackend implements IOperationBackend { return kernelCancel(this.lifecycle, this.lifecycleHandle, this.context, this._id); } - public async close(): Promise { - const wasCloseRequested = this.closeRequested; - this.closeRequested = true; - if (!wasCloseRequested && this.asyncStatement && this.fetchHandlePromise && !this.asyncSucceeded) { - // Native close queues behind awaitResult; the detached canceller interrupts it. - await this.asyncStatement.cancel().catch(() => {}); + public close(): Promise { + if (!this.closePromise) { + const wasCloseRequested = this.closeRequested; + this.closeRequested = true; + this.closePromise = (async () => { + if (!wasCloseRequested && this.asyncStatement && this.fetchHandlePromise && !this.asyncSucceeded) { + // Native close queues behind awaitResult; the detached canceller interrupts it. + await this.asyncStatement.cancel().catch(() => {}); + } + return kernelClose(this.lifecycle, this.lifecycleHandle, this.context, this._id); + })().catch((error) => { + this.closePromise = undefined; + throw error; + }); } - return kernelClose(this.lifecycle, this.lifecycleHandle, this.context, this._id); + return this.closePromise; } // --------------------------------------------------------------------------- diff --git a/tests/unit/kernel/operation-lifecycle.test.ts b/tests/unit/kernel/operation-lifecycle.test.ts index 3bf37bfb..dc8150a3 100644 --- a/tests/unit/kernel/operation-lifecycle.test.ts +++ b/tests/unit/kernel/operation-lifecycle.test.ts @@ -698,6 +698,7 @@ describe('DBSQLSession over KernelSessionBackend — close right after execution expect(thrown).to.be.instanceOf(Error); expect(connection.close.called).to.equal(false); expect(session['operations']['items'].size).to.equal(1); + expect(asyncStatement.close.calledTwice).to.equal(true); }); for (const cancelFails of [false, true]) { @@ -712,24 +713,42 @@ describe('DBSQLSession over KernelSessionBackend — close right after execution const awaitingResult = new Promise((resolve) => { started = resolve; }); + let releaseClose!: () => void; + const nativeClosed = new Promise((resolve) => { + releaseClose = resolve; + }); + let closingStarted!: () => void; + const nativeClosing = new Promise((resolve) => { + closingStarted = resolve; + }); asyncStatement.awaitResult.callsFake(() => { started(); return pendingResult; }); asyncStatement.cancel.callsFake(async () => { rejectResult(cancelled); + await new Promise((resolve) => setImmediate(resolve)); if (cancelFails) throw new Error('cancel response failed'); }); asyncStatement.close.callsFake(async () => { await pendingResult.catch(() => {}); + closingStarted(); + await nativeClosed; }); const executing = session.executeStatement('SELECT slow', { stagingAllowedLocalPath: ['/allowed'] }).then( () => expect.fail('execution should be cancelled'), (error) => error, ); await awaitingResult; - await session.close(); - await session.close(); + const closing = session.close(); + await nativeClosing; + await new Promise((resolve) => setImmediate(resolve)); + try { + expect(connection.close.called).to.equal(false); + } finally { + releaseClose(); + } + await closing; expect(await executing).to.equal(cancelled); expect(asyncStatement.cancel.calledOnce).to.equal(true); From f877311e562b35b74c898040b5ade1688c979386 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Wed, 18 Nov 2026 21:24:27 +0000 Subject: [PATCH 35/37] Finalize concurrent operation cleanup once Signed-off-by: Aakash Saravanan --- lib/DBSQLOperation.ts | 12 +- lib/kernel/KernelOperationBackend.ts | 12 +- .../kernel/KernelOperationBackend.test.ts | 107 +++++++----------- tests/unit/kernel/operation-lifecycle.test.ts | 100 ++++++++++++++-- 4 files changed, 146 insertions(+), 85 deletions(-) diff --git a/lib/DBSQLOperation.ts b/lib/DBSQLOperation.ts index 30f095ef..9402a9d1 100644 --- a/lib/DBSQLOperation.ts +++ b/lib/DBSQLOperation.ts @@ -58,6 +58,8 @@ export default class DBSQLOperation implements IOperation { private cancelled: boolean = false; + private closePromise?: Promise; + public readonly _data?: unknown; private metadata?: ResultMetadata; @@ -219,8 +221,14 @@ export default class DBSQLOperation implements IOperation { * is logged and reported in the returned status's `info` instead of thrown. * @throws {StatusError} */ - public async close(): Promise { - return this.withErrorTelemetry(() => this.closeInternal()); + public close(): Promise { + if (!this.closePromise) { + this.closePromise = this.withErrorTelemetry(() => this.closeInternal()).catch((error) => { + this.closePromise = undefined; + throw error; + }); + } + return this.closePromise; } private async closeInternal(): Promise { diff --git a/lib/kernel/KernelOperationBackend.ts b/lib/kernel/KernelOperationBackend.ts index 3e2de9bf..d04ec87d 100644 --- a/lib/kernel/KernelOperationBackend.ts +++ b/lib/kernel/KernelOperationBackend.ts @@ -200,8 +200,8 @@ export default class KernelOperationBackend implements IOperationBackend { // The cancel/close surface — whichever handle backs this operation. Both // `AsyncStatement` and `Statement` expose `cancel()` / `close()`; the - // sync-execute path keeps the execution canceller for SQL and uses the - // resolved statement to cancel marked transfers after SQL completes. + // sync-execute path uses a composite that routes `cancel()` to the + // cancellable execution (mid-compute) and `close()` to the resolved statement. private readonly lifecycleHandle: KernelStatementHandle; private readonly context: IClientContext; @@ -260,16 +260,16 @@ export default class KernelOperationBackend implements IOperationBackend { this.cancellableExecution = cancellableExecution; this.blockingStatement = statement; // Lifecycle surface. The async/metadata handles expose both cancel/close. - // The sync-execute path uses a composite so SQL execution and subsequent - // transfer completion remain cancellable. `close()` closes the resolved + // The sync-execute path uses a composite: `cancel()` always routes to the + // cancellable execution (lock-free, interrupts a running `result()` + // mid-compute and is a no-op once terminal); `close()` closes the resolved // terminal statement once `result()` produced it, OR — if `result()` is // still in flight — proactively cancels the running execution so the server // stops computing immediately rather than running on until the kernel's // drop-guard fires whenever this handle is eventually GC'd. this.lifecycleHandle = cancellableExecution ? { - cancel: () => - this.blockingStatement?.isVolumeOperation ? this.blockingStatement.cancel() : cancellableExecution.cancel(), + cancel: () => cancellableExecution.cancel(), close: () => (this.blockingStatement ? this.blockingStatement.close() : cancellableExecution.cancel()), } : ((asyncStatement ?? statement) as KernelStatementHandle); diff --git a/tests/unit/kernel/KernelOperationBackend.test.ts b/tests/unit/kernel/KernelOperationBackend.test.ts index 3d60ac27..9d03ef4f 100644 --- a/tests/unit/kernel/KernelOperationBackend.test.ts +++ b/tests/unit/kernel/KernelOperationBackend.test.ts @@ -400,8 +400,8 @@ describe('KernelOperationBackend Volume completion', () => { kernelMetadata: { httpStatus: 400 }, }); const backend = new KernelOperationBackend({ - cancellableExecution: { - result: async () => { + asyncStatement: { + awaitResult: async () => { throw error; }, } as any, @@ -415,42 +415,34 @@ describe('KernelOperationBackend Volume completion', () => { expect(actual.sqlState).to.equal('22023'); }); - for (const error of [ - new ParameterError('path is not allowed'), - Object.assign(new Error('storage HTTP 403'), { - kernelMetadata: { httpStatus: 403, errorCode: 'VOLUME_STORAGE_HTTP_ERROR' }, - }), - Object.assign(new Error('source is missing'), { code: 'ENOENT', path: '/allowed/missing' }), - ]) { - it(`classifies transfer failure: ${error.message}`, async () => { - const schema = new Schema([withTypeName(new Field('x', new Int32(), true), 'INT')]); - const statement = new StatementStub(ipcSchemaOnly(schema), []); - Object.assign(statement, { - completeVolumeOperation: async () => { - throw error; - }, - }); - const backend = new KernelOperationBackend({ statement, context: new ClientContextStub() }); - const actual = await backend.completeStagingOperation(['/allowed']).then( - () => expect.fail('transfer should fail'), - (failure) => failure, - ); - if ('code' in error) expect(actual).to.equal(error); - else expect(actual).to.be.instanceOf(StagingError).with.property('message', error.message); - }); - } - - for (const error of [ - Object.assign(new AuthenticationError('instruction session expired'), { - sqlState: '08003', - kernelMetadata: { httpStatus: 401, errorCode: 'SESSION_EXPIRED' }, - }), - Object.assign(new ParameterError('invalid instruction request'), { - sqlState: '22023', - kernelMetadata: { httpStatus: 400 }, - }), + for (const { error, staging } of [ + { error: new ParameterError('path is not allowed'), staging: true }, + { + error: Object.assign(new Error('storage HTTP 403'), { + kernelMetadata: { httpStatus: 403, errorCode: 'VOLUME_STORAGE_HTTP_ERROR' }, + }), + staging: true, + }, + { + error: Object.assign(new Error('source is missing'), { code: 'ENOENT', path: '/allowed/missing' }), + staging: false, + }, + { + error: Object.assign(new AuthenticationError('instruction session expired'), { + sqlState: '08003', + kernelMetadata: { httpStatus: 401, errorCode: 'SESSION_EXPIRED' }, + }), + staging: false, + }, + { + error: Object.assign(new ParameterError('invalid instruction request'), { + sqlState: '22023', + kernelMetadata: { httpStatus: 400 }, + }), + staging: false, + }, ]) { - it(`preserves deferred instruction errors: ${error.message}`, async () => { + it(`maps completion failure: ${error.message}`, async () => { const schema = new Schema([withTypeName(new Field('x', new Int32(), true), 'INT')]); const statement = new StatementStub(ipcSchemaOnly(schema), []); Object.assign(statement, { @@ -460,41 +452,22 @@ describe('KernelOperationBackend Volume completion', () => { }); const backend = new KernelOperationBackend({ statement, context: new ClientContextStub() }); const actual = await backend.completeStagingOperation(['/allowed']).then( - () => expect.fail('instruction fetch should fail'), + () => expect.fail('completion should fail'), (failure) => failure, ); - expect(actual).to.equal(error); - expect(actual.sqlState).to.equal(error.sqlState); - expect(actual.kernelMetadata).to.equal(error.kernelMetadata); - }); - } - - for (const isVolumeOperation of [false, true]) { - it(`routes ${isVolumeOperation ? 'Volume' : 'ordinary'} cancellation after SQL completes`, async () => { - const schema = new Schema([withTypeName(new Field('x', new Int32(), true), 'INT')]); - const statement = new StatementStub(ipcSchemaOnly(schema), []); - Object.assign(statement, { isVolumeOperation }); - let executionCancelled = false; - const execution = { - result: async () => statement, - cancel: async () => { - executionCancelled = true; - }, - }; - const backend = new KernelOperationBackend({ - cancellableExecution: execution as any, - context: new ClientContextStub(), - }); - await backend.getResultMetadata(); - await backend.cancel(); - expect(statement.cancelled).to.equal(isVolumeOperation); - expect(executionCancelled).to.equal(!isVolumeOperation); + if (staging) { + expect(actual).to.be.instanceOf(StagingError).with.property('message', error.message); + } else { + expect(actual).to.equal(error); + if ('sqlState' in error) expect(actual.sqlState).to.equal(error.sqlState); + if ('kernelMetadata' in error) expect(actual.kernelMetadata).to.equal(error.kernelMetadata); + } }); } for (const outcome of ['completed', 'not_volume']) { it(`${ - outcome === 'completed' ? 'consumes completed instructions' : 'preserves raw instruction rows' + outcome === 'completed' ? 'consumes completed instructions' : 'preserves ordinary result rows' }`, async () => { const schema = new Schema([withTypeName(new Field('x', new Int32(), true), 'INT')]); const stub = new StatementStub(ipcSchemaOnly(schema), [ipcFromColumns(schema, { x: [1] })]); @@ -503,9 +476,9 @@ describe('KernelOperationBackend Volume completion', () => { expect(remove404).to.equal(true); return outcome; }; - Object.assign(stub, { isVolumeOperation: true, completeVolumeOperation }); + Object.assign(stub, { isVolumeOperation: outcome === 'completed', completeVolumeOperation }); const backend = new KernelOperationBackend({ statement: stub, context: new ClientContextStub() }); - expect((await backend.getResultMetadata()).isStagingOperation).to.equal(true); + expect((await backend.getResultMetadata()).isStagingOperation).to.equal(outcome === 'completed'); await backend.completeStagingOperation(['/allowed']); expect((await backend.fetchChunk({ limit: 100 })).length).to.equal(outcome === 'completed' ? 0 : 1); expect(await backend.hasMore()).to.equal(false); diff --git a/tests/unit/kernel/operation-lifecycle.test.ts b/tests/unit/kernel/operation-lifecycle.test.ts index dc8150a3..30d4b93a 100644 --- a/tests/unit/kernel/operation-lifecycle.test.ts +++ b/tests/unit/kernel/operation-lifecycle.test.ts @@ -46,6 +46,10 @@ import KernelOperationBackend from '../../../lib/kernel/KernelOperationBackend'; import OperationStateError, { OperationStateErrorCode } from '../../../lib/errors/OperationStateError'; import HiveDriverError from '../../../lib/errors/HiveDriverError'; import { TOperationState } from '../../../thrift/TCLIService_types'; +import TelemetryEventEmitter from '../../../lib/telemetry/TelemetryEventEmitter'; +import MetricsAggregator from '../../../lib/telemetry/MetricsAggregator'; +import DatabricksTelemetryExporter from '../../../lib/telemetry/DatabricksTelemetryExporter'; +import { TelemetryEventType } from '../../../lib/telemetry/types'; class TestLogger implements IDBSQLLogger { public readonly entries: Array<{ level: LogLevel; message: string }> = []; @@ -647,7 +651,7 @@ describe('DBSQLSession over KernelSessionBackend — close right after execution const context = new ClientContextStub(); const backend = new KernelSessionBackend({ connection: connection as unknown as KernelConnection, context }); const session = new DBSQLSession({ backend, context }); - return { session, connection, terminalStatement, asyncStatement }; + return { session, connection, terminalStatement, asyncStatement, context }; } it('closes the operation and session when execution returned a completed statement', async () => { @@ -703,10 +707,23 @@ describe('DBSQLSession over KernelSessionBackend — close right after execution for (const cancelFails of [false, true]) { it(`closes pending staging execution when cancel ${cancelFails ? 'fails' : 'succeeds'}`, async () => { - const { session, connection, asyncStatement } = kernelSession('Running'); + const { session, connection, asyncStatement, context } = kernelSession('Running'); + context.configOverrides.telemetryEnabled = true; + const exporter = sinon.createStubInstance(DatabricksTelemetryExporter); + const aggregator = new MetricsAggregator(context, exporter); + const emitter = new TelemetryEventEmitter(context); + for (const type of Object.values(TelemetryEventType)) { + emitter.on(type, (event) => aggregator.processEvent(event)); + } + context.telemetryEmitter = emitter; + context.telemetryAggregator = aggregator; + const completion = sinon.spy(emitter, 'emitStatementComplete'); const cancelled = new OperationStateError(OperationStateErrorCode.Canceled); + const handle = { ...emptyResultHandle(), completeVolumeOperation: sinon.stub().resolves('not_volume') }; + let resolveResult!: (value: typeof handle) => void; let rejectResult!: (error: Error) => void; - const pendingResult = new Promise((_, reject) => { + const pendingResult = new Promise((resolve, reject) => { + resolveResult = resolve; rejectResult = reject; }); let started!: () => void; @@ -726,7 +743,7 @@ describe('DBSQLSession over KernelSessionBackend — close right after execution return pendingResult; }); asyncStatement.cancel.callsFake(async () => { - rejectResult(cancelled); + if (!cancelFails) rejectResult(cancelled); await new Promise((resolve) => setImmediate(resolve)); if (cancelFails) throw new Error('cancel response failed'); }); @@ -735,12 +752,25 @@ describe('DBSQLSession over KernelSessionBackend — close right after execution closingStarted(); await nativeClosed; }); - const executing = session.executeStatement('SELECT slow', { stagingAllowedLocalPath: ['/allowed'] }).then( - () => expect.fail('execution should be cancelled'), - (error) => error, - ); + const settled = sinon.spy(); + const executing = session + .executeStatement('SELECT slow', { stagingAllowedLocalPath: ['/allowed'] }) + .then( + (operation) => operation, + (error) => error, + ) + .then((outcome) => { + settled(); + return outcome; + }); await awaitingResult; const closing = session.close(); + if (cancelFails) { + await new Promise((resolve) => setImmediate(resolve)); + expect(settled.called).to.equal(false); + expect(connection.close.called).to.equal(false); + resolveResult(handle); + } await nativeClosing; await new Promise((resolve) => setImmediate(resolve)); try { @@ -749,8 +779,23 @@ describe('DBSQLSession over KernelSessionBackend — close right after execution releaseClose(); } await closing; - - expect(await executing).to.equal(cancelled); + const outcome = await executing; + await aggregator.close(); + + if (cancelFails) { + expect(outcome).to.be.instanceOf(DBSQLOperation); + expect((outcome as DBSQLOperation)['cancelled']).to.equal(false); + expect(handle.completeVolumeOperation.calledOnceWith(['/allowed'], true)).to.equal(true); + } else { + expect(outcome).to.equal(cancelled); + } + expect(completion.callCount).to.equal(1); + expect( + exporter.export + .getCalls() + .flatMap((call) => call.args[0]) + .filter((metric) => metric.metricType === 'statement'), + ).to.have.lengthOf(1); expect(asyncStatement.cancel.calledOnce).to.equal(true); expect(asyncStatement.cancel.calledBefore(asyncStatement.close)).to.equal(true); expect(asyncStatement.close.calledOnce).to.equal(true); @@ -759,6 +804,41 @@ describe('DBSQLSession over KernelSessionBackend — close right after execution }); } + it('finalizes close when polling observes closure before native disposal finishes', async () => { + const { session, asyncStatement, context } = kernelSession('Running'); + context.configOverrides.telemetryEnabled = true; + const emitter = sinon.createStubInstance(TelemetryEventEmitter); + const aggregator = sinon.createStubInstance(MetricsAggregator); + context.telemetryEmitter = emitter; + context.telemetryAggregator = aggregator; + let releaseClose!: () => void; + asyncStatement.close.returns( + new Promise((resolve) => { + releaseClose = resolve; + }), + ); + const operation = await session.executeStatement('SELECT slow'); + let polled!: () => void; + const firstPoll = new Promise((resolve) => { + polled = resolve; + }); + const polling = operation.finished({ callback: () => polled() }).catch((error) => error); + await firstPoll; + const closing = operation.close(); + try { + expect(await polling) + .to.be.instanceOf(OperationStateError) + .with.property('errorCode', OperationStateErrorCode.Closed); + } finally { + releaseClose(); + } + await closing; + expect(emitter.emitStatementComplete.calledOnce).to.equal(true); + expect(aggregator.completeStatement.calledOnceWith(operation.id)).to.equal(true); + expect(session['operations']['items'].size).to.equal(0); + await session.close(); + }); + it('retains success observed by status() on a running statement', async () => { const { session, connection, asyncStatement } = kernelSession('Succeeded'); const operation = await session.executeStatement('SELECT slow'); From 38edc92d289807f72100aa460723df6c09e510d9 Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Wed, 18 Nov 2026 22:15:30 +0000 Subject: [PATCH 36/37] build: pin kernel with bounded symlink resolution Signed-off-by: Aakash Saravanan --- KERNEL_REV | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/KERNEL_REV b/KERNEL_REV index 9c0856a4..8896a687 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -21856dea28e87fdf61d328e7f21d5484d7b618b4 +3c5342771df2df19d8a898c4deea2974e5c2383e From ca22ba19e2efd9b5a6ce4ee1b34ba73728f31d8e Mon Sep 17 00:00:00 2001 From: Aakash Saravanan Date: Thu, 19 Nov 2026 04:03:08 +0000 Subject: [PATCH 37/37] refactor(volume): reduce staging completion plumbing Signed-off-by: Aakash Saravanan --- CONNECTION_PARAMETERS.md | 4 +- KERNEL_REV | 2 +- lib/DBSQLOperation.ts | 12 +- lib/DBSQLSession.ts | 9 +- lib/kernel/KernelOperationBackend.ts | 21 +-- native/kernel/index.d.ts | 23 +-- native/kernel/index.js | 1 + tests/unit/DBSQLSession.test.ts | 20 --- .../kernel/KernelOperationBackend.test.ts | 12 -- tests/unit/kernel/error-mapping.test.ts | 4 - tests/unit/kernel/execution.test.ts | 5 +- tests/unit/kernel/operation-lifecycle.test.ts | 141 +----------------- 12 files changed, 28 insertions(+), 226 deletions(-) diff --git a/CONNECTION_PARAMETERS.md b/CONNECTION_PARAMETERS.md index 71163721..e7c19dbd 100644 --- a/CONNECTION_PARAMETERS.md +++ b/CONNECTION_PARAMETERS.md @@ -254,6 +254,4 @@ The Kernel path remains internal and unstable; its behavior may change. With the kernel backend, supplying `stagingAllowedLocalPath` completes Volume transfers before `executeStatement` resolves and consumes instruction rows. -Omitting the option returns raw instructions without file effects. Unlike the -Thrift backend’s lexical path check, the kernel also rejects symlink targets -outside the configured roots while permitting symlinks within them. +Omitting the option returns raw instructions without file effects. diff --git a/KERNEL_REV b/KERNEL_REV index 8896a687..bc49f880 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -3c5342771df2df19d8a898c4deea2974e5c2383e +2fe28af460d0db6eeb8c653e52eede954c90374c diff --git a/lib/DBSQLOperation.ts b/lib/DBSQLOperation.ts index 9402a9d1..30f095ef 100644 --- a/lib/DBSQLOperation.ts +++ b/lib/DBSQLOperation.ts @@ -58,8 +58,6 @@ export default class DBSQLOperation implements IOperation { private cancelled: boolean = false; - private closePromise?: Promise; - public readonly _data?: unknown; private metadata?: ResultMetadata; @@ -221,14 +219,8 @@ export default class DBSQLOperation implements IOperation { * is logged and reported in the returned status's `info` instead of thrown. * @throws {StatusError} */ - public close(): Promise { - if (!this.closePromise) { - this.closePromise = this.withErrorTelemetry(() => this.closeInternal()).catch((error) => { - this.closePromise = undefined; - throw error; - }); - } - return this.closePromise; + public async close(): Promise { + return this.withErrorTelemetry(() => this.closeInternal()); } private async closeInternal(): Promise { diff --git a/lib/DBSQLSession.ts b/lib/DBSQLSession.ts index 7633990f..95024946 100644 --- a/lib/DBSQLSession.ts +++ b/lib/DBSQLSession.ts @@ -113,13 +113,8 @@ export default class DBSQLSession implements IDBSQLSession { ? options.stagingAllowedLocalPath : [options.stagingAllowedLocalPath]; if (opBackend.completeStagingOperation) { - try { - await this.runBackend(() => opBackend.completeStagingOperation!(allowedLocalPath)); - return operation; - } catch (error) { - await operation.close().catch(() => {}); - throw error; - } + await this.runBackend(() => opBackend.completeStagingOperation!(allowedLocalPath)); + return operation; } const metadata = await operation.getResultMetadata(); if (metadata.isStagingOperation) { diff --git a/lib/kernel/KernelOperationBackend.ts b/lib/kernel/KernelOperationBackend.ts index d04ec87d..4dffdf2b 100644 --- a/lib/kernel/KernelOperationBackend.ts +++ b/lib/kernel/KernelOperationBackend.ts @@ -236,8 +236,6 @@ export default class KernelOperationBackend implements IOperationBackend { // kernel closes the result handle either way. private closeRequested = false; - private closePromise?: Promise; - constructor({ asyncStatement, statement, @@ -500,22 +498,9 @@ export default class KernelOperationBackend implements IOperationBackend { return kernelCancel(this.lifecycle, this.lifecycleHandle, this.context, this._id); } - public close(): Promise { - if (!this.closePromise) { - const wasCloseRequested = this.closeRequested; - this.closeRequested = true; - this.closePromise = (async () => { - if (!wasCloseRequested && this.asyncStatement && this.fetchHandlePromise && !this.asyncSucceeded) { - // Native close queues behind awaitResult; the detached canceller interrupts it. - await this.asyncStatement.cancel().catch(() => {}); - } - return kernelClose(this.lifecycle, this.lifecycleHandle, this.context, this._id); - })().catch((error) => { - this.closePromise = undefined; - throw error; - }); - } - return this.closePromise; + public async close(): Promise { + this.closeRequested = true; + return kernelClose(this.lifecycle, this.lifecycleHandle, this.context, this._id); } // --------------------------------------------------------------------------- diff --git a/native/kernel/index.d.ts b/native/kernel/index.d.ts index 460cf061..b5a315dc 100644 --- a/native/kernel/index.d.ts +++ b/native/kernel/index.d.ts @@ -20,7 +20,7 @@ export declare class AsyncResultHandle { get isVolumeOperation(): boolean /** Complete a server-marked file transfer while retaining its instruction rows. */ - completeVolumeOperation(allowedPaths: Array, removeNotFoundIsSuccess?: boolean | undefined | null): Promise + completeVolumeOperation(allowedPaths: Array, removeNotFoundIsSuccess?: boolean | undefined | null): Promise /** * Server-issued statement id. Cached at construction; readable * for log correlation. Matches the parent `AsyncStatement`'s @@ -152,9 +152,8 @@ export declare class AsyncStatement { * re-attempting the wire call. The kernel's own `Drop` * fire-and-forget retry runs once in the background. * - * Also invalidates the handles `awaitResult()` returned: their - * `fetchNextBatch()` then rejects with `InvalidStatementHandle`, - * unless a fetch was in progress when `close()` ran. + * Also invalidates the handles `awaitResult()` returned. An operation + * already in flight may finish before its handle is cleared. */ close(): Promise } @@ -443,7 +442,7 @@ export declare class Connection { export declare class Statement { get isVolumeOperation(): boolean /** Complete a server-marked file transfer while retaining its instruction rows. */ - completeVolumeOperation(allowedPaths: Array, removeNotFoundIsSuccess?: boolean | undefined | null): Promise + completeVolumeOperation(allowedPaths: Array, removeNotFoundIsSuccess?: boolean | undefined | null): Promise /** * Server-issued statement id. Cached at construction; readable * even after `close()` so JS-side log lines can correlate against @@ -1060,11 +1059,11 @@ export interface ConnectionOptions { */ proxy?: ProxyInput /** - * Per-connection socket read timeout, in milliseconds. Caps how - * long a single HTTP round-trip may block waiting on the server - * before the request errors out. Maps onto the kernel + * Per-connection HTTP request deadline, in milliseconds. Caps a single + * request through response-body completion. Maps onto the kernel * [`HttpConfig::request_timeout`] (the internal reqwest - * `Client::timeout`). + * `Client::timeout`). Does not bound Volume storage requests or configure + * their inactivity limit. Storage connection setup has a separate timeout. * * Omitted ⇒ kernel default (120 000 ms / 120 s). Napi-rs * serialises `u32` as JS `number`; the largest representable value @@ -1331,3 +1330,9 @@ export interface TypedValueInput { * loaded?" probe for the JS-side loader's structured diagnostics. */ export declare function version(): string + +export declare const enum VolumeCompletion { + NotVolume = 'not_volume', + NeedsInputStream = 'needs_input_stream', + Completed = 'completed' +} diff --git a/native/kernel/index.js b/native/kernel/index.js index 6902ddee..511f20a1 100644 --- a/native/kernel/index.js +++ b/native/kernel/index.js @@ -711,3 +711,4 @@ module.exports.kernelLoggingStats = nativeBinding.kernelLoggingStats module.exports.openSession = nativeBinding.openSession module.exports.setKernelLogLevel = nativeBinding.setKernelLogLevel module.exports.version = nativeBinding.version +module.exports.VolumeCompletion = nativeBinding.VolumeCompletion diff --git a/tests/unit/DBSQLSession.test.ts b/tests/unit/DBSQLSession.test.ts index 505e1b4f..7c73c1c0 100644 --- a/tests/unit/DBSQLSession.test.ts +++ b/tests/unit/DBSQLSession.test.ts @@ -886,26 +886,6 @@ describe('DBSQLSession', () => { }); describe('DBSQLSession native staging dispatch', () => { - it('closes a failed native operation and preserves its error when close also fails', async () => { - const error = new Error('completion failed'); - const close = sinon.stub().rejects(new Error('close failed')); - const op = { - id: 'volume-operation', - completeStagingOperation: sinon.stub().rejects(error), - close, - } as unknown as IOperationBackend; - const session = new DBSQLSession({ - backend: { id: 'volume-session', executeStatement: async () => op } as unknown as ISessionBackend, - context: new ClientContextStub(), - }); - const actual = await session.executeStatement('GET remote TO local', { stagingAllowedLocalPath: [] }).then( - () => expect.fail('completion should fail'), - (failure) => failure, - ); - expect(actual).to.equal(error); - expect(close.callCount).to.equal(1); - }); - for (const configured of [false, true]) { it(`calls native completion only when local paths are ${configured ? 'configured' : 'omitted'}`, async () => { const completeStagingOperation = sinon.stub().resolves(); diff --git a/tests/unit/kernel/KernelOperationBackend.test.ts b/tests/unit/kernel/KernelOperationBackend.test.ts index 9d03ef4f..1a0da3b3 100644 --- a/tests/unit/kernel/KernelOperationBackend.test.ts +++ b/tests/unit/kernel/KernelOperationBackend.test.ts @@ -41,7 +41,6 @@ import KernelOperationBackend from '../../../lib/kernel/KernelOperationBackend'; import { TTypeId } from '../../../thrift/TCLIService_types'; import ClientContextStub from '../.stubs/ClientContextStub'; import ParameterError from '../../../lib/errors/ParameterError'; -import AuthenticationError from '../../../lib/errors/AuthenticationError'; import StagingError from '../../../lib/errors/StagingError'; // Minimal stub of the napi `Statement` surface that emits a precomputed @@ -423,17 +422,6 @@ describe('KernelOperationBackend Volume completion', () => { }), staging: true, }, - { - error: Object.assign(new Error('source is missing'), { code: 'ENOENT', path: '/allowed/missing' }), - staging: false, - }, - { - error: Object.assign(new AuthenticationError('instruction session expired'), { - sqlState: '08003', - kernelMetadata: { httpStatus: 401, errorCode: 'SESSION_EXPIRED' }, - }), - staging: false, - }, { error: Object.assign(new ParameterError('invalid instruction request'), { sqlState: '22023', diff --git a/tests/unit/kernel/error-mapping.test.ts b/tests/unit/kernel/error-mapping.test.ts index f739eae0..6a1506c8 100644 --- a/tests/unit/kernel/error-mapping.test.ts +++ b/tests/unit/kernel/error-mapping.test.ts @@ -376,12 +376,8 @@ describe('KernelErrorMapping.decodeNapiKernelError — cause chain', () => { for (const [raw, kind, expected] of [ [2, 'NotFound', 'ENOENT'], [undefined, 'PermissionDenied', 'EACCES'], - [0, 'PermissionDenied', 'EACCES'], [undefined, 'Unrecognized', 'EIO'], [1000000, 'NotFound', 'ENOENT'], - [1000000, 'Unrecognized', 'EIO'], - [1.5, 'NotFound', 'ENOENT'], - [Number.MAX_SAFE_INTEGER + 1, 'Unrecognized', 'EIO'], ] as const) { it(`preserves local file error code and path for ${kind}/${raw}`, () => { const error = decodeNapiKernelError( diff --git a/tests/unit/kernel/execution.test.ts b/tests/unit/kernel/execution.test.ts index 97c22e12..8dd40ad9 100644 --- a/tests/unit/kernel/execution.test.ts +++ b/tests/unit/kernel/execution.test.ts @@ -24,6 +24,7 @@ import DBSQLSession from '../../../lib/DBSQLSession'; import DBSQLOperation from '../../../lib/DBSQLOperation'; import asyncDisposable from '../../../lib/asyncDisposable'; import { KernelNativeBinding, KernelConnection, KernelStatement } from '../../../lib/kernel/KernelNativeLoader'; +import { VolumeCompletion } from '../../../native/kernel'; import IClientContext, { ClientConfig } from '../../../lib/contracts/IClientContext'; import { CrossReferenceRequest, PrimaryKeysRequest } from '../../../lib/contracts/IDBSQLSession'; import IDBSQLLogger, { LogLevel } from '../../../lib/contracts/IDBSQLLogger'; @@ -43,8 +44,8 @@ import { DBSQLParameter, DBSQLParameterType } from '../../../lib/DBSQLParameter' class FakeNativeStatement implements KernelStatement { public readonly isVolumeOperation = false; - public async completeVolumeOperation(): Promise { - return 'not_volume'; + public async completeVolumeOperation(): Promise { + return VolumeCompletion.NotVolume; } public closed = false; diff --git a/tests/unit/kernel/operation-lifecycle.test.ts b/tests/unit/kernel/operation-lifecycle.test.ts index 30d4b93a..290d343e 100644 --- a/tests/unit/kernel/operation-lifecycle.test.ts +++ b/tests/unit/kernel/operation-lifecycle.test.ts @@ -46,10 +46,6 @@ import KernelOperationBackend from '../../../lib/kernel/KernelOperationBackend'; import OperationStateError, { OperationStateErrorCode } from '../../../lib/errors/OperationStateError'; import HiveDriverError from '../../../lib/errors/HiveDriverError'; import { TOperationState } from '../../../thrift/TCLIService_types'; -import TelemetryEventEmitter from '../../../lib/telemetry/TelemetryEventEmitter'; -import MetricsAggregator from '../../../lib/telemetry/MetricsAggregator'; -import DatabricksTelemetryExporter from '../../../lib/telemetry/DatabricksTelemetryExporter'; -import { TelemetryEventType } from '../../../lib/telemetry/types'; class TestLogger implements IDBSQLLogger { public readonly entries: Array<{ level: LogLevel; message: string }> = []; @@ -651,7 +647,7 @@ describe('DBSQLSession over KernelSessionBackend — close right after execution const context = new ClientContextStub(); const backend = new KernelSessionBackend({ connection: connection as unknown as KernelConnection, context }); const session = new DBSQLSession({ backend, context }); - return { session, connection, terminalStatement, asyncStatement, context }; + return { session, connection, terminalStatement, asyncStatement }; } it('closes the operation and session when execution returned a completed statement', async () => { @@ -702,141 +698,6 @@ describe('DBSQLSession over KernelSessionBackend — close right after execution expect(thrown).to.be.instanceOf(Error); expect(connection.close.called).to.equal(false); expect(session['operations']['items'].size).to.equal(1); - expect(asyncStatement.close.calledTwice).to.equal(true); - }); - - for (const cancelFails of [false, true]) { - it(`closes pending staging execution when cancel ${cancelFails ? 'fails' : 'succeeds'}`, async () => { - const { session, connection, asyncStatement, context } = kernelSession('Running'); - context.configOverrides.telemetryEnabled = true; - const exporter = sinon.createStubInstance(DatabricksTelemetryExporter); - const aggregator = new MetricsAggregator(context, exporter); - const emitter = new TelemetryEventEmitter(context); - for (const type of Object.values(TelemetryEventType)) { - emitter.on(type, (event) => aggregator.processEvent(event)); - } - context.telemetryEmitter = emitter; - context.telemetryAggregator = aggregator; - const completion = sinon.spy(emitter, 'emitStatementComplete'); - const cancelled = new OperationStateError(OperationStateErrorCode.Canceled); - const handle = { ...emptyResultHandle(), completeVolumeOperation: sinon.stub().resolves('not_volume') }; - let resolveResult!: (value: typeof handle) => void; - let rejectResult!: (error: Error) => void; - const pendingResult = new Promise((resolve, reject) => { - resolveResult = resolve; - rejectResult = reject; - }); - let started!: () => void; - const awaitingResult = new Promise((resolve) => { - started = resolve; - }); - let releaseClose!: () => void; - const nativeClosed = new Promise((resolve) => { - releaseClose = resolve; - }); - let closingStarted!: () => void; - const nativeClosing = new Promise((resolve) => { - closingStarted = resolve; - }); - asyncStatement.awaitResult.callsFake(() => { - started(); - return pendingResult; - }); - asyncStatement.cancel.callsFake(async () => { - if (!cancelFails) rejectResult(cancelled); - await new Promise((resolve) => setImmediate(resolve)); - if (cancelFails) throw new Error('cancel response failed'); - }); - asyncStatement.close.callsFake(async () => { - await pendingResult.catch(() => {}); - closingStarted(); - await nativeClosed; - }); - const settled = sinon.spy(); - const executing = session - .executeStatement('SELECT slow', { stagingAllowedLocalPath: ['/allowed'] }) - .then( - (operation) => operation, - (error) => error, - ) - .then((outcome) => { - settled(); - return outcome; - }); - await awaitingResult; - const closing = session.close(); - if (cancelFails) { - await new Promise((resolve) => setImmediate(resolve)); - expect(settled.called).to.equal(false); - expect(connection.close.called).to.equal(false); - resolveResult(handle); - } - await nativeClosing; - await new Promise((resolve) => setImmediate(resolve)); - try { - expect(connection.close.called).to.equal(false); - } finally { - releaseClose(); - } - await closing; - const outcome = await executing; - await aggregator.close(); - - if (cancelFails) { - expect(outcome).to.be.instanceOf(DBSQLOperation); - expect((outcome as DBSQLOperation)['cancelled']).to.equal(false); - expect(handle.completeVolumeOperation.calledOnceWith(['/allowed'], true)).to.equal(true); - } else { - expect(outcome).to.equal(cancelled); - } - expect(completion.callCount).to.equal(1); - expect( - exporter.export - .getCalls() - .flatMap((call) => call.args[0]) - .filter((metric) => metric.metricType === 'statement'), - ).to.have.lengthOf(1); - expect(asyncStatement.cancel.calledOnce).to.equal(true); - expect(asyncStatement.cancel.calledBefore(asyncStatement.close)).to.equal(true); - expect(asyncStatement.close.calledOnce).to.equal(true); - expect(connection.close.calledOnce).to.equal(true); - expect(session['operations']['items'].size).to.equal(0); - }); - } - - it('finalizes close when polling observes closure before native disposal finishes', async () => { - const { session, asyncStatement, context } = kernelSession('Running'); - context.configOverrides.telemetryEnabled = true; - const emitter = sinon.createStubInstance(TelemetryEventEmitter); - const aggregator = sinon.createStubInstance(MetricsAggregator); - context.telemetryEmitter = emitter; - context.telemetryAggregator = aggregator; - let releaseClose!: () => void; - asyncStatement.close.returns( - new Promise((resolve) => { - releaseClose = resolve; - }), - ); - const operation = await session.executeStatement('SELECT slow'); - let polled!: () => void; - const firstPoll = new Promise((resolve) => { - polled = resolve; - }); - const polling = operation.finished({ callback: () => polled() }).catch((error) => error); - await firstPoll; - const closing = operation.close(); - try { - expect(await polling) - .to.be.instanceOf(OperationStateError) - .with.property('errorCode', OperationStateErrorCode.Closed); - } finally { - releaseClose(); - } - await closing; - expect(emitter.emitStatementComplete.calledOnce).to.equal(true); - expect(aggregator.completeStatement.calledOnceWith(operation.id)).to.equal(true); - expect(session['operations']['items'].size).to.equal(0); - await session.close(); }); it('retains success observed by status() on a running statement', async () => {