Add gRPC-to-HTTP query fallback, fix test spicepod version, strengthen browser test assertions

[lukekim]

Summary

Four changes, from most to least significant:

1. SDK: fall back to HTTP when an Arrow Flight query fails mid-query

The Flight channel can initialize successfully but then fail on the query itself — observed as empty grpc-js status errors (undefined undefined: undefined) from the SDK running inside Vercel serverless functions, which made all Cloud Tests fail with 500s from the test app. Previously doQueryRequest only fell back to HTTP when channel initialization failed.

Now sql() falls back to HTTP on a failed Flight query, unless:

• flightOnly is set (no HTTP transport to fall back to), or
• partial results were already streamed to the caller's callback (fallback would deliver duplicate data).

sqlJson() in gRPC mode routes through sql() and inherits the same behavior. Falling back logs a warning through the configurable logger.

2. SDK: send raw SQL over HTTP unless parameters require the JSON envelope

Deploying fix 1 exposed a second bug: Spice Cloud's /v1/sql parses every request body as raw SQL and rejects the {sql, parameters} JSON envelope (introduced in #268) with 400 ParserError. The OSS runtime accepts both formats (verified against the runtime source and a local spiced).

• Queries without parameters are sent as text/plain raw SQL — the format every endpoint accepts, and the pre-Add Parameterized Queries #268 behavior.
• Parameterized queries keep the JSON envelope against the OSS runtime.
• Parameterized queries over HTTP against Spice Cloud fail fast with a clear error (parameter binding there requires Arrow Flight) instead of a cryptic server 400.

New unit tests in test/grpc-http-fallback.test.ts cover all paths (6 tests), wired into the Local Runtime CI job.

3. CI: fix test spicepod version (v1beta1 → v1)

CI installs the latest spiced release, which dropped support for v1beta1 spicepods — the runtime failed to start and all six Local Runtime jobs failed with ECONNREFUSED. Validated against a local spiced before pushing.

4. Tests: strengthen browser client assertions for HTTP request formats

• Plain sql() asserts the text/plain raw-SQL body; a new test asserts the JSON envelope for parameterized queries.
• sqlJson() test asserts Content-Type: text/plain with the raw SQL body and the application/vnd.spiceai.sql.v1+json Accept header.
• The config-logging test now sets SPICE_DEBUG=true (restored after), making it deterministic regardless of NODE_ENV.

Testing

• test/grpc-http-fallback.test.ts — 6 tests pass
• npm run test:browser — 62 tests pass
• Both body formats verified 200 OK against a local OSS spiced; the envelope-vs-raw behavior of Spice Cloud confirmed from CI logs (ParserError on {)
• Prettier clean; eslint delta on changed files is zero (repo-wide lint issues are pre-existing)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spice-js	Ready	Preview	Aug 1, 2026 6:42pm

[Copilot]

Pull request overview

This PR improves SDK robustness by falling back from Arrow Flight (gRPC) to HTTP when a query fails after the channel has initialized, and adjusts HTTP request formatting to match what Spice Cloud and the OSS runtime actually accept. It also updates CI/runtime fixtures and strengthens test assertions around request bodies/headers.

Changes:

• Add query-time gRPC → HTTP fallback in sql() with safeguards (no fallback in flightOnly or after partial streaming).
• Send raw SQL (text/plain) over HTTP when there are no parameters; keep JSON envelope for parameterized queries on OSS, and fail fast for parameterized HTTP on Spice Cloud.
• Update spicepod version for CI and add/strengthen unit + browser tests (and wire the new unit test into CI).

Reviewed changes

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

Show a summary per file

File	Description
src/client-common.ts	Adds query-time gRPC→HTTP fallback logic and conditional HTTP body/content-type selection (raw SQL vs JSON envelope).
test/grpc-http-fallback.test.ts	New unit tests covering fallback behavior and HTTP body formats (including Spice Cloud rejection for parameterized HTTP).
test/browser/client.test.ts	Tightens browser-side assertions for HTTP request formats and makes config logging test deterministic via SPICE_DEBUG.
test/scripts/spicepod.yaml	Updates spicepod schema version to v1 for compatibility with latest spiced.
.github/workflows/test.yml	Runs the new gRPC→HTTP fallback unit tests in the local runtime CI job.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.