Repository navigation
Complete configured Volume transfers through the native backend - #613
aakash-saravanan-db wants to merge 24 commits into
Conversation
|
Thanks for your contribution! To satisfy the DCO policy in our contributing guide every commit message must include a sign-off message. One or more of your commits is missing this message. You can reword previous commit messages with an interactive rebase ( |
ad49367 to
7b276d7
Compare
7b276d7 to
12876fc
Compare
There was a problem hiding this comment.
Verdict: 1 Medium · 1 Low
Mostly sound, with one medium issue: on the kernel path, the new StagingError wrapping can also catch the statement's own execution errors, not just transfer errors. Nits: there is a stray blank line in the CHANGELOG entry, and the constructor comment in KernelOperationBackend still says cancel() "always routes to the cancellable execution". Follow-up (not caused by this PR): executeStatement waits for the transfer before it returns the operation, so a caller can only interrupt an in-flight transfer by closing the session.
| expect(executionCancelled).to.equal(false); | ||
| }); | ||
|
|
||
| for (const outcome of ['completed', 'not_volume']) { |
There was a problem hiding this comment.
🔵 Low — The new tests cover only the completed and not_volume outcomes and the cancel routing. These new branches in completeStagingOperation have no unit test:
- the
needs_input_stream→StagingErrorpath - reclassifying
ParameterErrorandhttpStatuserrors asStagingError - passing other errors through unchanged (for example local fs errors decoded with
code/path)
No test checks that DBSQLSession closes the operation when completion fails either. The error-classification branch is where F1 lives, so a test there would have caught it.
There was a problem hiding this comment.
Verdict: 2 Low
Mostly sound, with 2 low findings: the native completion API is called without feature detection, and the needs_input_stream branch has no test. Nits: the KernelOperationBackend constructor comment still says cancel() always goes to the cancellable execution, but after result() resolves it now goes to the statement. The rewritten KernelSessionBackend.executeStatement JSDoc sentence reads awkwardly. The CHANGELOG entry adds a blank line that splits the bullet list.
| failIfNotActive(this.lifecycle); | ||
| const handle = await this.getFetchHandle(); | ||
| try { | ||
| const outcome = await handle.completeVolumeOperation(allowedPaths, true); |
There was a problem hiding this comment.
🔵 Low — completeStagingOperation calls handle.completeVolumeOperation(...) with no check that the method exists. DBSQLSession sends every kernel executeStatement that has stagingAllowedLocalPath set through this path, including ordinary SELECTs, because KernelOperationBackend always defines completeStagingOperation.
The PR description says published native 1.4.0 has no completion API. With that binding (or any stale cached .node), these calls now fail with TypeError: handle.completeVolumeOperation is not a function, and the operation gets closed. Before this change, the option was logged and ignored, and the statement worked normally.
assertBindingShape was written to catch exactly this kind of drift, but it doesn't check the new surface. Two possible fixes:
- check
typeof handle.completeVolumeOperation !== 'function'here and throw a clear error, or skip completion; - or add the method to the binding shape check so a mismatched binding is rejected when it loads.
There was a problem hiding this comment.
Published native 1.4.0 is incompatible; the compatible native versions, all eight platform pins/locks and clean installed-package ordinary-query/Volume checks remain required before merge. This is a coordinated release dependency, with no older-native fallback in the chosen contract. The source pin selects the current kernel, and source-built checks do not complete the package gate. Checking an old binding at load time could improve its diagnostic, but cannot make it compatible or replace that gate.
There was a problem hiding this comment.
Agreed that the version pins are the real compatibility gate, and that a shape check can't make an old binding work. My concern is narrower: what happens when the pin gate is bypassed by a stale cached .node, a source build, or a hand-installed platform package. In that case every kernel executeStatement with stagingAllowedLocalPath set fails, including ordinary SELECTs, and the error is an opaque TypeError. Adding completeVolumeOperation to assertBindingShape is a one-line change. It would turn that into a clear error when the binding loads, which is the kind of drift that check exists to catch. The code at line 318 is unchanged, so I'm leaving this open for the maintainers to decide on. It's still low severity and doesn't block the coordinated release.
| try { | ||
| const outcome = await handle.completeVolumeOperation(allowedPaths, true); | ||
| if (outcome === 'needs_input_stream') { | ||
| throw new StagingError('Volume PUT requires a local file path'); |
There was a problem hiding this comment.
🔵 Low — The needs_input_stream outcome, which should throw StagingError('Volume PUT requires a local file path'), has no test. The new suite covers completed and not_volume, plus thrown errors. It doesn't cover this branch, or the fact that the StagingError thrown inside the try goes through decodeNapiKernelError and the reclassification check before reaching the caller. A one-case addition to the existing for (const outcome of [...]) loop would cover it.
There was a problem hiding this comment.
Confirmed that this rejection branch has no dedicated test. Node exposes file PUT rather than a BinaryIO API; reaching it requires a server instruction for the stream sentinel. The branch throws an existing StagingError, and decodeNapiKernelError returns that non-envelope error unchanged. No runtime defect is established. A third row in the existing test table remains optional branch hardening; the required file lifecycle, completion/raw modes and error-origin paths retain unit and actual-driver coverage.
There was a problem hiding this comment.
Thanks for confirming. I agree the branch is hard to reach from Node's file-PUT API and that decodeNapiKernelError should pass a non-envelope StagingError through unchanged, and I'm not claiming a runtime defect. The finding is about the missing test, though, and that test is still missing. Your claim that decodeNapiKernelError and the reclassification check leave this error alone is exactly what a third needs_input_stream row in the existing outcome loop would prove. Without it, a later change to either one could quietly turn this rejection into a different error type. The fix is small and low priority, so I'll leave the thread open for a maintainer to decide whether to add it.
Signed-off-by: Aakash Saravanan <aakash.saravanan@databricks.com>
There was a problem hiding this comment.
Verdict: 1 Low
Looks good overall, with one low-severity concern. If the native layer returns a completion outcome this code doesn't recognise, the call succeeds with no transfer and no error. Two nits: CHANGELOG.md has a stray blank line in the middle of the bullet list, and when a ParameterError or storage error is turned into a StagingError, the kernel metadata (httpStatus/errorCode) and the cause are lost. That matches Thrift's StagingError, but it's worth noting.
| if (outcome === 'needs_input_stream') { | ||
| throw new StagingError('Volume PUT requires a local file path'); | ||
| } | ||
| this.volumeCompleted = outcome === 'completed'; |
There was a problem hiding this comment.
🔵 Low — The native binding returns completeVolumeOperation outcomes as a bare string. This code handles 'needs_input_stream' and 'completed'. Every other value, including one a future kernel adds or one that is misspelled, gets the same treatment as 'not_volume': executeStatement resolves without an error and the caller gets the raw instruction rows. The user configured stagingAllowedLocalPath, so a transfer can silently not happen. A failure-loud check would fix this: accept only 'completed' and 'not_volume', and throw a StagingError such as Unexpected Volume completion outcome: ${outcome} for anything else.
There was a problem hiding this comment.
The compatible pinned NAPI producer maps the closed VolumeCompletion enum directly through as_str: its only outputs are not_volume, needs_input_stream and completed (src/volume.rs, napi/src/statement.rs, napi/src/async_statement.rs). This adapter handles all three, so no current native path produces the proposed unexpected value. A defensive check for a future or mismatched binding remains optional; compatible platform package pins/locks and clean installation are still required before merge.
The review-body nits remain acknowledged: preserving cause/extra metadata could improve StagingError diagnostics, while the current shape follows the audited Thrift error; the changelog blank line is cosmetic.
There was a problem hiding this comment.
Agreed that the pinned NAPI producer emits only not_volume, needs_input_stream and completed, and that all three are handled today. The concern was about a mismatched or future binding. Line 322 still treats any unrecognized string as not_volume and resolves without an error, and nothing in this package enforces the native enum, since the binding is typed as string and the platform packages are versioned separately. Throwing a StagingError when the outcome isn't completed or not_volume costs two lines and turns a silent skipped transfer into a visible error. It's still Low and optional, so I'm leaving the thread open for the maintainers to decide.
Signed-off-by: Aakash Saravanan <aakash.saravanan@databricks.com>
There was a problem hiding this comment.
Verdict: 1 Medium · 1 Low
Mostly sound, with one medium blocker: Volume completion calls a native API that the pinned native 1.4.0 binding doesn't have. As a result, every kernel statement that sets stagingAllowedLocalPath, including a plain SELECT, now fails with a TypeError. Before this change the option was logged and ignored. Nit: the constructor comment saying cancel() "always routes to the cancellable execution" is out of date now that cancel() goes to the resolved statement.
| failIfNotActive(this.lifecycle); | ||
| const handle = await this.getFetchHandle(); | ||
| try { | ||
| const outcome = await handle.completeVolumeOperation(allowedPaths, true); |
There was a problem hiding this comment.
🟡 Medium — completeStagingOperation calls handle.completeVolumeOperation(...) without checking that the loaded binding has it. The optional dependencies are still pinned to native 1.4.0, which has no completion API, so on the kernel backend every executeStatement with stagingAllowedLocalPath now fails, including a plain SELECT. The error is TypeError: handle.completeVolumeOperation is not a function. decodeNapiKernelError passes it through unchanged, and the facade closes the operation.
Before this PR the option was logged and ignored, so callers that set it globally and run ordinary queries break.
The facade check if (opBackend.completeStagingOperation) doesn't prevent this. That method exists on every KernelOperationBackend instance, so the check is always true. The check needs to be on the native handle. If typeof handle.completeVolumeOperation !== 'function', either keep the earlier behaviour (do nothing and return the raw instruction rows) or throw a clear HiveDriverError that names the minimum native version. Alternatively, bump the dependency pins in this PR.
There was a problem hiding this comment.
Published native 1.4.0 is incompatible. The actual compatible versions, all eight platform dependency pins/locks, and clean installed ordinary-query/metadata/Volume proof remain required before merge; a source SHA pin does not satisfy those requirements. This is a coordinated-release dependency, with no older-native fallback in the selected contract. A stale-binding method check could improve the load/runtime diagnostic, but cannot make the missing API compatible or replace the package gate. The PR remains blocked on that gate.
There was a problem hiding this comment.
Agreed, a method check on the handle can't make native 1.4.0 compatible, and bumping the pins is the real fix. That's still outstanding, though: line 318 calls handle.completeVolumeOperation with no guard, and the optional dependencies still point to 1.4.0. I'm leaving this thread open until the new versions are published and all eight platform pins and locks are bumped. That way it stays in the unresolved queue as the visible merge gate. If the release slips and this branch gets installed against 1.4.0, a typeof guard that throws a HiveDriverError naming the minimum native version would still be cheap. It would replace an unclear TypeError on a plain SELECT.
| (mapped instanceof ParameterError && !metadata?.httpStatus) || | ||
| metadata?.errorCode === 'VOLUME_STORAGE_HTTP_ERROR' | ||
| ) { | ||
| throw new StagingError(mapped.message); |
There was a problem hiding this comment.
🔵 Low — When a policy or storage-HTTP failure is re-thrown as new StagingError(mapped.message), the decoded error's kernelMetadata, including httpStatus, errorCode (VOLUME_STORAGE_HTTP_ERROR) and queryId, is thrown away, along with its sqlState and cause. Callers then can't tell a storage 403 from a 404 or correlate the failure with a query, even though the PR keeps this metadata on the other error paths. Copying kernelMetadata and cause onto the StagingError (for example with Object.assign or Object.defineProperty, matching how KernelErrorMapping attaches them) keeps the established error class and the diagnostics.
There was a problem hiding this comment.
Additional metadata/cause on StagingError would improve diagnostics. The current mapping deliberately retains the established Thrift staging error class/shape, while SQL instruction errors keep their decoded metadata. Native storage HTTP failures retain their specific Volume storage request failed: HTTP ... diagnostic, so the storage-origin deletion check does not depend on discarded metadata or accept a generic statement 404. This remains an acknowledged optional diagnostic enhancement.
The review-body constructor comment is also a valid optional wording improvement: cancellation uses the cancellable execution while pending and the resolved statement afterward. Existing cancellation/lifetime behavior is preserved.
There was a problem hiding this comment.
Understood that keeping the established StagingError class is deliberate, and I'm fine with that part. My suggestion was never to change the class, only to attach the diagnostics to it. The code at line 330 still builds a new StagingError from the message alone. The HTTP ... text in the message helps a human reading it, but queryId, errorCode, sqlState and cause are still lost, so callers have nothing structured to branch on or use for correlation. This is Low severity and fine to defer. I'm leaving the thread open so the follow-up stays visible: one Object.defineProperty for kernelMetadata/cause on the new error would fix it without changing its class or shape.
Signed-off-by: Aakash Saravanan <aakash.saravanan@databricks.com>
There was a problem hiding this comment.
Verdict: 2 Low · 1 Nit
Mostly sound, with three low-severity robustness gaps: no check that the native completion API exists, unknown completion outcomes treated as success, and unchecked OS error numbers. Nits: CHANGELOG.md adds a stray blank line inside the bullet list, and the new error-mapping tests sit at the top level instead of inside a describe block. Follow-up (dependency, not a defect in this diff): releasing still needs native pins that include completeVolumeOperation, and forcing sync execution whenever stagingAllowedLocalPath is set also applies to long non-Volume statements.
Other findings
- ⚪ Nit — Every outcome other than
'completed'and'needs_input_stream'is treated the same as'not_volume': no error, and the raw instruction rows stay visible. If the kernel adds an outcome later, or returns an unexpected string, the caller gets no file effect and no error even though they configuredstagingAllowedLocalPath. Consider treating only'not_volume'as the pass-through case and throwing aStagingErrorfor any other unrecognised value.
| failIfNotActive(this.lifecycle); | ||
| const handle = await this.getFetchHandle(); | ||
| try { | ||
| const outcome = await handle.completeVolumeOperation(allowedPaths, true); |
There was a problem hiding this comment.
🔵 Low — completeVolumeOperation is called without checking that it exists. The PR says published native 1.4.0 lacks the completion APIs, and the backend's own statement type is Partial<KernelStatement>. On a binding without the method, every kernel executeStatement that sets stagingAllowedLocalPath fails with TypeError: handle.completeVolumeOperation is not a function, and DBSQLSession then closes the operation. That includes ordinary SELECT/DML statements that aren't Volume operations; before this PR they ran with a warning. A typeof handle.completeVolumeOperation !== 'function' guard would fix it. It could throw a clear HiveDriverError/StagingError saying the native binding is too old, or fall back to the previous behaviour for non-volume statements (isVolumeOperation falsy).
There was a problem hiding this comment.
The incompatible-package concern is valid and remains a required merge gate: compatible native platform versions, all dependency pins/locks, and clean installed SELECT/metadata/Volume proof. Native 1.4.0 lacks these APIs. The source build selects kernel30c8d8e7; both the rebuilt sync/async lifecycle comparisons and ordinary-query controls pass. Coordinated native uptake is required, so we are retaining direct calls rather than adding an older-native compatibility path. This PR is not ready to merge until that release gate passes.
There was a problem hiding this comment.
Thanks for confirming. Requiring a coordinated native release instead of adding a compatibility path is a reasonable choice. The code at this line still calls completeVolumeOperation directly, though. Until the published native dependency is pinned to a version that has the completion APIs, an install that pulls native 1.4.0 will still fail ordinary statements that set stagingAllowedLocalPath. I'll leave this thread open so the release gate stays in the unresolved queue. It can be closed once the pin and lockfile point to a compatible native release, or once a guard is added.
Signed-off-by: Aakash Saravanan <aakash.saravanan@databricks.com>
|
Disposition of the remaining optional review suggestions: the pinned native completion result has the three declared outcomes, and native errors reject; an added outcome requires a coordinated binding/type update. No unexpected-outcome path is reachable with the selected native, so an additional future-outcome guard remains optional. The existing table tests have unique case names and assertions; wrapping them or changing the changelog spacing would add no behavior coverage. The configured-path execution choice preserves the existing staging contract. Compatible released platform packages, pins/locks, clean installs and named scheduled execution remain open gates. |
There was a problem hiding this comment.
Verdict: 2 Low
Looks good overall, with 2 low findings: error metadata is dropped when failures are re-wrapped as StagingError, and the needs_input_stream outcome has no test. The wiring between DBSQLSession, the kernel backend and native completion is consistent, and cleanup on failure is correct. One nit: the CHANGELOG entry is followed by a stray blank line that splits the bullet list.
| (mapped instanceof ParameterError && !metadata?.httpStatus) || | ||
| metadata?.errorCode === 'VOLUME_STORAGE_HTTP_ERROR' | ||
| ) { | ||
| throw new StagingError(mapped.message); |
There was a problem hiding this comment.
🔵 Low — When a transfer failure is re-wrapped as new StagingError(mapped.message), the error loses kernelMetadata (including queryId and httpStatus/errorCode) and the non-enumerable cause that decodeNapiKernelError attaches. Other paths now keep these fields; the PR description says deferred instruction errors keep their metadata, and the tests check that too. For storage HTTP failures (VOLUME_STORAGE_HTTP_ERROR), callers can no longer see the HTTP status or the query id needed to match the failure in server logs. Consider copying kernelMetadata and cause onto the StagingError, for example with Object.defineProperty as the mapper already does. This keeps the error class callers expect and still preserves the diagnostics.
There was a problem hiding this comment.
The diagnostic loss is real and remains the previously acknowledged optional enhancement. Keeping kernelMetadata/cause would improve storage-error correlation without changing the StagingError class. The current class/message follows the audited Thrift staging contract; deferred SQL instruction failures retain their decoded metadata. The specific storage diagnostic is retained, and the strict deletion oracle rejects generic statement/instruction 404s without relying on dropped metadata. This finding remains visible; no required baseline behavior or newly demonstrated failure calls for another adapter change.
There was a problem hiding this comment.
Thanks for confirming the diagnostic loss is real. Keeping the StagingError class and message for the Thrift staging contract makes sense, and the fix I suggested doesn't change that. It only adds the non-enumerable kernelMetadata/cause properties to the same error. The code at line 329 still drops them, so storage HTTP failures can't be matched to server logs by queryId or httpStatus. This is Low severity and isn't blocking. I'm leaving the thread open so the optional fix stays in the queue for someone to pick up later.
| failIfNotActive(this.lifecycle); | ||
| const handle = await this.getFetchHandle(); | ||
| try { | ||
| const outcome = await handle.completeVolumeOperation(allowedPaths, true); |
There was a problem hiding this comment.
🔵 Low — The needs_input_stream branch has no unit test. Its StagingError is thrown inside the try, so it also goes through decodeNapiKernelError and the classification logic, and no test confirms it comes out unchanged. Any other unrecognised outcome string from a future native version is also treated silently as 'not completed', and the raw instruction rows are returned. Add a test case for needs_input_stream. Also consider throwing or logging when the outcome is not one of the known values (completed / not_volume / needs_input_stream).
There was a problem hiding this comment.
The sentinel instruction can reach this branch; it is not unreachable. Node has no input-stream upload API, so needs_input_stream produces the explicit StagingError. decodeNapiKernelError returns that ordinary Error unchanged, and it cannot satisfy either remapping condition. No incorrect branch behavior is established. An additional test of this direct rejection remains optional; core handshake/owned-byte coverage and distinct Node storage/instruction/error/lifecycle coverage remain. Unknown future outcomes retain the earlier optional disposition; supported native inputs require coordinated platform pins/locks.
There was a problem hiding this comment.
You're right that this branch is reachable, and your explanation of why decodeNapiKernelError should pass the StagingError through unchanged makes sense. My concern was never that the branch behaves wrongly today. It was that nothing locks that behavior in. If someone later changes the catch classification, this rejection could get wrapped or remapped without any test failing, and a single mocked completeVolumeOperation returning 'needs_input_stream' would cover that cheaply. For unknown future outcome strings, coordinated platform pins lower the risk but don't remove it: a version mismatch would still silently report "not completed". I'm leaving this open at Low severity for a human to decide whether to add the test and an else throw or log. No code change is needed to keep the current behavior correct.
Signed-off-by: Aakash Saravanan <aakash.saravanan@databricks.com>
There was a problem hiding this comment.
Verdict: 1 Medium · 2 Low
Mostly sound, with 1 medium concern: there is no feature check on the native completion API while the published 1.4.0 binary that package.json still pins lacks it. Session dispatch, cleanup on failure, cancel routing and errno decoding look correct. Nit: the CHANGELOG entry adds a stray blank line inside the bullet list.
| failIfNotActive(this.lifecycle); | ||
| const handle = await this.getFetchHandle(); | ||
| try { | ||
| const outcome = await handle.completeVolumeOperation(allowedPaths, true); |
There was a problem hiding this comment.
🟡 Medium — handle.completeVolumeOperation(...) is called without checking that the loaded binding has it. The packages declared in package.json are still 1.4.0, and per the PR description that version has no completion API. With that binary installed, any kernel executeStatement that passes stagingAllowedLocalPath fails with TypeError: handle.completeVolumeOperation is not a function. That includes a plain SELECT. Before this change the option was logged and ignored. decodeNapiKernelError returns non-envelope errors unchanged, and DBSQLSession then closes the operation and rethrows, so callers see the raw TypeError.
The PR does say merge depends on updated pins. Until that happens, though, every environment that installs from npm gets this regression. Either guard with typeof handle.completeVolumeOperation === 'function' and throw a clear StagingError or HiveDriverError (or keep the old no-op), as readStatusFieldsFrom does for older bindings, or block the merge on the pin bump.
There was a problem hiding this comment.
Agreed: compatible native packages, all eight platform pins/locks and clean installed SELECT, metadata and Volume proof are required before this PR can merge. The declared 1.4.0 inputs do not satisfy the new API contract, and the source SHA pin is not released-package proof. This gate remains open in the PR description. Coordinated native uptake is required; an older-binding no-op/fallback would conceal unsupported Volume behavior and is not the selected contract. No merge-ready or complete-parity claim is made.
There was a problem hiding this comment.
Thanks, blocking the merge on the native package bump is one of the resolutions I suggested, and choosing it over a silent no-op makes sense. Line 317 still calls handle.completeVolumeOperation with no guard, though, and package.json still pins 1.4.0. So the regression is real at current head. I'll leave this thread open as the visible merge gate. It can be resolved once the eight platform pins and lockfile point at a released binding that ships the completion API.
| metadata?.errorCode === 'VOLUME_STORAGE_HTTP_ERROR' | ||
| ) { | ||
| throw new StagingError(mapped.message); | ||
| } |
There was a problem hiding this comment.
🔵 Low — When a transfer error is reclassified as StagingError, only message is kept. The decoded error's kernelMetadata (queryId, httpStatus, errorCode) and its non-enumerable cause are lost. A storage VOLUME_STORAGE_HTTP_ERROR then reaches the caller with no status code or query id to correlate, even though decodeNapiKernelError worked to attach them. Copying kernelMetadata and cause onto the new StagingError, for example with Object.defineProperty as the mapping module does, would keep the type change without losing diagnostics.
There was a problem hiding this comment.
The metadata/cause loss is real and remains the previously acknowledged optional diagnostic enhancement. The StagingError class and message follow the audited Thrift staging contract; SQL/instruction-side failures keep their decoded metadata. Genuine storage failures retain the specific storage diagnostic, and deletion verification rejects generic instruction/statement 404s without depending on discarded metadata. This repeats the earlier disposition; no new required behavior failure is established.
There was a problem hiding this comment.
Thanks. We agree on the facts: the loss of kernelMetadata and cause is real, and this is a Low-severity diagnostic issue, not a functional failure. Line 329 still builds new StagingError(mapped.message) with nothing else attached. So for a VOLUME_STORAGE_HTTP_ERROR, the caller never sees the httpStatus, queryId or errorCode that the decoder already extracted. Copying those fields onto the new error wouldn't change its class or message, so it wouldn't conflict with the Thrift staging contract. I'm leaving this open so a maintainer can decide whether to add the fields in this PR or track it separately.
| const handle = await this.getFetchHandle(); | ||
| try { | ||
| const outcome = await handle.completeVolumeOperation(allowedPaths, true); | ||
| if (outcome === 'needs_input_stream') { |
There was a problem hiding this comment.
🔵 Low — No unit test covers the 'needs_input_stream' outcome. That branch throws a StagingError inside the try, which is then decoded again and run through the reclassification check. The Volume completion tests only exercise 'completed', 'not_volume' and thrown errors. Please add a case asserting that 'needs_input_stream' rejects with StagingError('Volume PUT requires a local file path').
There was a problem hiding this comment.
The sentinel branch is reachable and intentionally rejects with StagingError('Volume PUT requires a local file path'). decodeNapiKernelError returns an ordinary non-envelope Error unchanged, and this StagingError satisfies neither remapping condition, so its class/message survive. This repeats the existing branch-test disposition. The extra mocked assertion remains optional; the distinct storage/instruction/error/lifecycle tests remain. No behavior defect is demonstrated.
There was a problem hiding this comment.
I agree with your reasoning about the runtime behaviour. decodeNapiKernelError passes a plain non-envelope Error through unchanged, and this StagingError matches neither remapping condition, so it should reach the caller as is. My finding wasn't about a bug, though. It was about the missing regression test, and there's still no test under tests/ that mentions needs_input_stream or the message "Volume PUT requires a local file path". That makes the class and message you've described an unenforced contract: if the catch block's decode or reclassification logic changes later, nothing will catch it. One mocked completeVolumeOperation returning 'needs_input_stream' would cover it. It's low priority, so I'll leave the thread open for you to decide whether to add it before merge.
Signed-off-by: Aakash Saravanan <aakash.saravanan@databricks.com>
There was a problem hiding this comment.
Verdict: 1 Low
Looks good overall, with one low concern: when transfer failures are turned into StagingError, the kernel's diagnostic metadata is dropped. Native dispatch, closing the operation on failure, consuming instruction rows, forcing inline execution, and decoding errno values all look correct, and unit tests cover them. Nit: the CHANGELOG adds a stray blank line inside the bullet list.
| (mapped instanceof ParameterError && !metadata?.httpStatus) || | ||
| metadata?.errorCode === 'VOLUME_STORAGE_HTTP_ERROR' | ||
| ) { | ||
| throw new StagingError(mapped.message); |
There was a problem hiding this comment.
🔵 Low — When a transfer failure is reclassified, new StagingError(mapped.message) keeps only the message. The decoded error's kernelMetadata is dropped, including httpStatus, errorCode: 'VOLUME_STORAGE_HTTP_ERROR' and queryId, and so is its non-enumerable cause. Every other kernel error keeps that metadata, and the PR description says HTTP errors and their metadata stay intact. A caller that hits a storage 403/404 therefore gets a StagingError whose status can only be recovered by parsing the message, and there's no query id to correlate with the server.
A contained fix is to copy kernelMetadata (and cause) from mapped onto the new StagingError before throwing it. The tests could then assert that kernelMetadata.httpStatus survives in the VOLUME_STORAGE_HTTP_ERROR case.
There was a problem hiding this comment.
This is the acknowledged optional storage-diagnostic enhancement. Storage failures retain the audited StagingError class and the specific storage diagnostic; deferred SQL instruction HTTP failures retain decoded metadata as stated in the description. The comparator’s REMOVE verification in databricks/databricks-driver-test#2122 requires storage-origin evidence and rejects generic instruction/statement 404s independently of these dropped properties. Copying kernelMetadata/cause would improve correlation, but no required Thrift behavior or newly demonstrated incorrect transfer/error outcome requires an adapter change.
There was a problem hiding this comment.
Thanks for clarifying. I accept that the PR description's metadata promise covers deferred SQL instruction HTTP failures rather than storage failures, and that the comparator in databricks-driver-test#2122 checks for storage-origin evidence without needing these properties. The code at line 329 still rebuilds the error from mapped.message alone, though, so a caller who catches the StagingError loses httpStatus, errorCode and queryId. The only way to recover the status is to parse the message, and there's no query id to correlate with the server. This stays Low and doesn't need to block the merge. I'll leave the thread open so a human can decide whether to copy kernelMetadata and cause over now or in a follow-up.
Signed-off-by: Aakash Saravanan <aakash.saravanan@databricks.com>
There was a problem hiding this comment.
Verdict: 3 Low
Mostly sound. Native completion is called only on kernel backends, failed completions close the operation, and errno decoding is defensive. I found three low-severity issues: the StagingError rewrap loses diagnostic metadata, unknown completion outcomes succeed without a transfer, and the PUT-without-local-path branch has no test. Nits: a stray blank line inside the CHANGELOG list after the new entry, and IOperationBackend.completeStagingOperation has no JSDoc describing its contract, unlike its neighbouring methods.
| (mapped instanceof ParameterError && !metadata?.httpStatus) || | ||
| metadata?.errorCode === 'VOLUME_STORAGE_HTTP_ERROR' | ||
| ) { | ||
| throw new StagingError(mapped.message); |
There was a problem hiding this comment.
🔵 Low — Converting a tagged storage HTTP error or a local-policy ParameterError into new StagingError(mapped.message) drops everything the decoder attached: kernelMetadata (including httpStatus, errorCode: 'VOLUME_STORAGE_HTTP_ERROR' and queryId) and the non-enumerable cause.
After the rewrap, a caller cannot tell a 403 from a 404 except by parsing the message, and cannot link the failure to its statement. The deferred instruction errors next to this path keep their metadata intact (the tests check this), so these two error kinds now behave differently.
Consider copying kernelMetadata and cause onto the new StagingError, for example with Object.assign or Object.defineProperty, so the error type changes but the diagnostics survive.
There was a problem hiding this comment.
This is the acknowledged optional storage-diagnostic enhancement. Storage failures retain the audited StagingError class and the specific storage diagnostic; deferred SQL instruction HTTP failures retain decoded metadata as stated in the description. The comparator’s REMOVE verification in databricks/databricks-driver-test#2122 requires storage-origin evidence and rejects generic instruction/statement 404s independently of these dropped properties. Copying kernelMetadata/cause would improve correlation, but no required Thrift behavior or newly demonstrated incorrect transfer/error outcome requires an adapter change.
There was a problem hiding this comment.
Understood, and I agree this is Low severity and doesn't change Thrift behavior or transfer outcomes. Your reply also confirms the diagnostics are lost: line 329 still builds a bare new StagingError(mapped.message), so httpStatus, errorCode and queryId are gone for storage failures but kept for deferred instruction failures. The comparator in databricks-driver-test#2122 can work without them, but driver callers outside that harness can't. This is a two-line change that keeps the StagingError class: Object.assign(err, { kernelMetadata: metadata }) and define cause on the new error. I'll leave the thread open so a maintainer can decide whether to take it now or track it as a follow-up.
| const handle = await this.getFetchHandle(); | ||
| try { | ||
| const outcome = await handle.completeVolumeOperation(allowedPaths, true); | ||
| if (outcome === 'needs_input_stream') { |
There was a problem hiding this comment.
🔵 Low — No test covers the 'needs_input_stream' branch. In particular, nothing checks that the StagingError thrown inside the try passes through decodeNapiKernelError and the reclassification logic unchanged. The Volume completion tests cover only 'completed' and 'not_volume'.
There is also no tests/e2e/ coverage of kernel Volume PUT/GET/REMOVE, even though the change has visible effects on files and storage. The PR description mentions out-of-tree comparisons only.
There was a problem hiding this comment.
The sentinel branch is reachable, and the plain StagingError is passed through by decodeNapiKernelError; it matches neither remapping condition in this catch. The additional mocked assertion remains optional, with no incorrect runtime outcome established. Distinct native owned-input, adapter error/cancellation/lifecycle and real-driver transfer groups remain.
The shared end-to-end workflows are in databricks/databricks-driver-test#2122, tests/comparator-tests/node/config/thrift-vs-sea.yaml. The retained source-built sync/async DBSQL comparisons at kernel029c59cc have two matches, 20 successful positive steps and zero differences, including initial/changed bytes and storage-origin removal. Compatible installed-native and named scheduled proof remain open; duplicating that shared journey in another connector matrix would not close either gate.
There was a problem hiding this comment.
Pointing to the shared comparator workflows in databricks-driver-test#2122 is a fair answer to the e2e half of this, and I'm not claiming the current code behaves incorrectly. The unit-test gap is still open, though. The 'needs_input_stream' branch is reachable, but no test exercises it. That means nothing would catch a future change to decodeNapiKernelError or to the reclassification conditions that starts remapping or wrapping this StagingError. A small mocked test would cover it: stub completeVolumeOperation to resolve 'needs_input_stream', then assert that a StagingError with this message is rejected and that volumeCompleted stays false. This is Low severity, so I'll leave it to the maintainers whether it blocks the PR.
Feature or gap
Kernel-backed sessions need to complete server-marked Volume PUT, GET and REMOVE operations through the existing staging API.
What this PR addresses
Delegate authorized transfers to native completion and preserve raw instructions otherwise. Validate native errno values before OS lookup so malformed envelopes retain file-error codes and paths. Keep deferred SQL instruction HTTP errors and their metadata intact, map tagged storage HTTP and local policy failures to the established staging error type, and preserve portable file-error codes when the host does not recognize a native errno.
Both requested paths and resolved targets must lie within configured allowed roots. Symlinks between authorized roots remain supported; escaped targets are rejected, stricter than the Thrift handler’s lexical path checks.
Dependencies
Builds select databricks/databricks-sql-kernel#465 at ab4f133620fce52f9932508f0b245db630a57c48. Merge and release require compatible platform versions, updated dependency pins/locks, and clean installed-package validation. Published native 1.4.0 lacks completion APIs.
Tests and validation
237 focused kernel/session/error tests, TypeScript, lint and formatting checks pass. Source-built sync/async staging comparisons at kernel
029c59ccmatch Thrift on DBSQL CURRENT: two matching workflows and zero differences, with initial and changed bytes, removal and owned cleanup verified. The comparison verifies its loaded native library and covers the unchanged successful-transfer paths. Retained performance evidence keeps its recorded build qualification. Clean installed-package and scheduled activation remain open.