feat: add active_queries and cancel_active_query for running SQL queries

[claudespice]

What

Adds Client::active_queries() and Client::cancel_active_query(), wrapping the runtime's GET /v1/sql/active and POST /v1/sql/{query_id}/cancel.

Why

Cancelling a running synchronous query — one started by sql(), FlightSQL, /v1/sql, NSQL, or search — was not reachable from this SDK. The existing cancel_query() cancels an async job via /v1/queries/{id}/cancel, which is a different thing and is gated on the runtime running in cluster mode. The two endpoints added here work on a default single-node runtime, so this closes a gap users hit today.

They ship as a pair deliberately: the runtime assigns a query_id to every synchronous query but does not return it to the client that submitted it, so active_queries() is the only way to discover the id that cancellation needs. Shipping cancel alone would leave it unreachable.

Both endpoints are scoped to the caller by the runtime, so a client only ever lists and cancels its own queries — that's reflected in the docs and in the NotFound error text, since an id belonging to another caller is reported as not found rather than cancelled.

Kept in a new active_query module rather than folded into query, so the sync/async distinction stays legible at the type level: ActiveQueryError carries only variants that can actually occur here (no ClusterModeRequired, no Expired).

Part of aligning query cancellation across the SDKs — no SDK had this, so this establishes the shape (active_queries / cancel_active_query, named after the runtime's own operation ids) for the others to mirror.

Verification

• cargo build
• cargo test --lib — 196 passed, including 5 new tests for response deserialization and error text
• cargo test --doc — 29 passed, including the new README example
• cargo fmt --all --check
• cargo clippy --all-features — clean
• Integration tests (cargo test) — not run: they need a live runtime on 127.0.0.1:50051 and no spice CLI is available in this environment. The 7 pre-existing failures there are all connection-refused and are unrelated to this change.

Review gate

Attests the review-fix commit 0206785, not the original feature work.

• Adversarial review: codex, two passes — 1c6a068 (verdict needs-attention) and the re-run after the approach changed. Findings triaged on the review threads:
  • Accepted: the corrected scope wording still misstated the boundary for mTLS-authenticated clients, and omitted the runtime-instance boundary. Both fixed.
  • Accepted, and the largest change here: the path-hardening covered only cancel_active_query, leaving QueryHttpClient::cancel / get_status / get_query / the chunk readers formatting a caller-supplied id into the path — reproduced as an authenticated POST landing on /v1/datasets/{name}/acceleration/refresh. All query-id routes now build URLs through build_url.
  • Deferred with an issue: cluster-wide active-query lookup is a runtime gap, not an SDK one — Active-query listing and cancellation only reach one runtime instance spiceai#13026.
• Security review: covered by the above — the diff is documentation plus URL construction, and the URL-construction defect is the security finding, reproduced and regression-tested rather than argued.
• Local gate: cargo fmt --check, cargo clippy --all-targets, cargo test --lib (206 passed), cargo test --doc (29 passed). The 7 client_test::tests::test_local_* failures need a running local runtime and fail identically with this diff stashed.

[claudespice]

@copilot review

[Copilot]

Pull request overview

Adds SDK support for listing and cancelling active synchronous queries.

Changes:

• Adds active-query models and errors.
• Implements HTTP endpoint wrappers and public client methods.
• Adds API documentation, examples, and deserialization tests.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/active_query.rs	Defines active-query types, errors, docs, and tests.
src/query.rs	Implements active-query HTTP requests.
src/client.rs	Exposes the new client methods.
src/lib.rs	Exports the new public API.
README.md	Documents listing and cancellation usage.

Suppressed comments (4)

src/active_query.rs:103

• The runtime sorts this response by started_at_ms ascending (then query ID), so callers receive the oldest query first. This public contract currently promises the opposite; either document the actual order or reverse the response before returning it.

    /// The active queries, most recently started first.

src/active_query.rs:65

• This variant is also returned when active_queries() receives a 403, but its message says cancellation failed. Use operation-neutral wording so listing failures are not misleading.

        "The configured API key does not allow cancelling queries. Use a key with write access."

src/client.rs:589

• Cancellation is scoped to the runtime principal, not the SDK client instance. Another client with the same API key—and any unauthenticated client in the shared public scope—can cancel the query, so this isolation guarantee needs qualification.

    /// Cancellation is scoped to this client: an id belonging to another caller is
    /// reported as not found rather than cancelled.

src/active_query.rs:53

• This message attributes NotFound to a different client, but client instances sharing an API key (or the unauthenticated public scope) are allowed to cancel each other's queries. Describe the actual principal boundary instead.

        "No active query '{query_id}' found. It may have already finished, or it was submitted by a different client."

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.