feat(grpc-web): Pyodide/WASM grpc-web transport for the async client

[g-despot]

What & why

Lets the async client run inside Pyodide/WebAssembly (marimo notebooks, browser, WASM workers), where grpcio has no wheel and sockets don't exist. gRPC is re-routed over grpc-web (fetch), REST over the browser's fetch — against Weaviate core's native /v1/grpc-web endpoint (default-on since 1.38.3) or any grpc-web transcoder (Envoy, vanguard).

Quickstart (Pyodide / marimo)

# install once (until release: use the wheels built from this branch)
import micropip
await micropip.install(["weaviate-client", "weaviate-client-web"])

import weaviate  # bootstraps the grpc-web transport automatically under WASM
from weaviate.classes.config import Configure, DataType, Property

client = weaviate.use_async_with_custom(
    http_host="weaviate.example.com", http_port=443, http_secure=True,
    grpc_host="weaviate.example.com", grpc_port=443, grpc_secure=True,
    grpc_path_prefix="/v1/grpc-web",  # core-native grpc-web endpoint (server ≥ 1.38.3)
)
await client.connect()

await client.collections.create(
    "Article",
    vector_config=Configure.Vectors.self_provided(),
    properties=[Property(name="title", data_type=DataType.TEXT)],
)
articles = client.collections.get("Article")

await articles.data.insert_many([{"title": f"Article {i}"} for i in range(10)])

res = await articles.query.bm25("article", limit=3)
for o in res.objects:
    print(o.properties["title"])

await client.close()

Only use_async_with_custom(..., grpc_path_prefix="/v1/grpc-web") reaches Weaviate's native grpc-web endpoint (server ≥ 1.38.3, on the REST port). use_async_with_local / use_async_with_weaviate_cloud have no grpc_path_prefix and therefore only work with a grpc-web transcoder (Envoy/vanguard) at the root of grpc_host:grpc_port.

Key pieces

packages/web/ — new companion distribution weaviate-client-web (the Python counterpart of the TS web client @weaviate/web), reuses the client's generated protobuf stubs (no codegen fork):

• src/weaviate_client_web/__init__.py — bootstrap: installs the shim (Emscripten-only) and forces the pure-Python protobuf runtime; a bare import weaviate triggers it automatically (see the hook below), importing the package explicitly first also works
• pyproject.toml — carries anyio ; sys_platform == "emscripten" (Pyodide's httpx build omits anyio, but authlib imports it directly)
• _shim.py — pure-Python grpc module shim into sys.modules; provides grpc.aio.Channel as a real base class and satisfies the generated stubs' version gates; never installs on a normal machine
• _channel.py — GrpcWebChannel: unary multicallables, per-call metadata (API key / OIDC bearer) → headers, grpc-web status/trailers → the client's normal AioRpcError codes (UNAVAILABLE retryable, DEADLINE_EXCEEDED on timeout, INTERNAL on missing grpc-status or protocol violations). grpc-timeout is emitted in the largest unit that fits the spec's 8 digits (m → S → M, never H — Weaviate's transcoder rejects >8H); non-finite deadlines send no header. Diagnostics name the fix for an HTTP 404/405 (server < 1.38.3 or wrong grpc_path_prefix) and for a missing prefix under WASM; a truncated body is reported as truncated, not as a wrong path
• _framing.py — grpc-web wire format: frame encode/split, trailer parsing (CRLF or LF, lenient keys), rejection of compressed/unknown-flag frames, a message after the trailer, or a second message frame in a unary reply
• _sender.py — pyodide.http.pyfetch sender (production) + an httpx sender (CPython integration testing)
• _httpx_fetch.py — routes the client's httpx REST calls over JS fetch under Emscripten and is always the active transport there (Pyodide's own httpx build is not used: it dereferences the response body unconditionally, which is null for HEAD/204 responses, and it does not enforce sub-5 s REST timeouts end to end). Timeouts map to an AbortSignal (rounded up, capped at 2³¹−1 ms); non-finite timeouts mean no deadline
• README.md — usage (use_async_with_custom(..., grpc_path_prefix="/v1/grpc-web") on the REST port; use_async_with_local/use_async_with_weaviate_cloud have no prefix and only work with a transcoder at the gRPC host:port root), the full CORS allow-list the client needs, what's not honored

Base client (no-ops on normal platforms except where noted):

• weaviate/__init__.py — a platform-guarded hook (dead code off-WASM) soft-imports the companion before anything else, so plain import weaviate works under Pyodide; a missing companion raises a clear install hint instead of ModuleNotFoundError: grpc, a broken one surfaces its own error
• setup.cfg — grpcio ; sys_platform != "emscripten" marker so micropip skips it
• weaviate/connect/base.py / helpers.py — grpc_path_prefix on ConnectionParams + use_async_with_custom (grpc-web on the REST host:port); fail-fast guards for sync-client / missing-shim misconfiguration run at client construction
• weaviate/connect/v4.py — sync client rejected at construction under WASM; the async OIDC refresher is an asyncio task instead of a daemon thread, cancelled and awaited by close() (fixes a leak where the thread survived close(); covered by mock_tests/test_auth.py); non-finite timeouts mean "no deadline" for every REST/gRPC hand-off
• weaviate/collections/batch/async_.py — batch.stream()/experimental() fail fast under grpc-web with a clear error pointing to insert_many() (bidi streaming is impossible over fetch)
• weaviate/proto/v1/__init__.py — grpcio version fallback when dist metadata is absent (Emscripten-only), drift-pinned by proto_test

CI / tests:

• ci/pyodide-e2e/ — run.mjs (Node runner: loads pinned Pyodide 314.0.4, micropip-installs the branch-built wheels), e2e.py (in-Pyodide e2e against core-native /v1/grpc-web: connect with init checks, insert_many, queries/filters/aggregations, tenants, HEAD/204 REST calls — data.exists/update/delete_by_id, tenants.exists — reference_add_many/reference_delete, error mapping, batch.stream() fail-fast, and a self-check that the package's fetch transport is the active one)
• .github/workflows/main.yaml — grpc-web-tests (package suite, 3.10–3.14) + pyodide-e2e (real WASM interpreter, no browser needed); ruff, flake8 and pyright cover packages/web; build-and-publish needs both new jobs
• test/test_wasm_compat.py, proto_test/test_proto.py — Emscripten guards + fallback-version drift pins

Changes that affect every platform

Not everything here is WASM-gated. These change behavior for existing users:

• connect/v4.py — the async OIDC refresher is an asyncio task rather than a daemon thread; close() cancels and awaits it (fixes a leak where the thread outlived close(); a client dropped without close() now surfaces the Con004 resource warning instead of a leaked thread).
• connect/v4.py — token refresh failures in both colours (sync thread and async task) are caught broadly (not just HTTPError) and retried with a capped exponential backoff (1 s → 2 → 4 → … → 60 s, reset on success). Previously the sync thread died silently on a non-HTTP error. Con001's text now states the interval and failure count; a refresher that dies outside that loop is surfaced as Con003.
• connect/v4.py — the sync refresher thread exits promptly on close() (event wait instead of sleep), and a close() → connect() cycle no longer leaves the previous refresher thread alive.
• connect/v4.py — connect() reports the underlying gRPC code and details instead of discarding them; both the sync and async native-gRPC connection errors gain one appended The gRPC call failed with: <CODE> - <details> line (type unchanged).
• connect/v4.py — httpx.TimeoutException subclasses (ConnectTimeout, WriteTimeout, PoolTimeout) raise WeaviateTimeoutError instead of escaping the exception taxonomy raw; connection-time REST error messages now include the exception type name.
• connect/v4.py — non-finite timeouts (Timeout(query=float("inf")), nan) mean "no deadline" everywhere (REST, gRPC, batch shutdown wait) instead of overflowing in a transport layer.
• connect/v4.py — a RuntimeError is rewritten to WeaviateClosedClientError only when the underlying httpx client is actually closed (previously: message-text match; other RuntimeErrors now propagate as-is).
• connect/base.py, connect/helpers.py — the grpc_path_prefix misconfiguration guards fire at client construction (both colours), not inside connect() after OIDC//v1/meta succeeded.
• collections/batch/async_.py, sync.py, batch_wrapper.py — flush() and __put() raise when background tasks die instead of spinning; leaving with/async with client.batch.stream() raises a WeaviateBatchStreamError if the background worker failed or data was left unsent — in both colours (the sync colour previously swallowed this). If your own block raised, your exception wins and the background failure is logged. _BatchStreamShutdownError is now a WeaviateBatchStreamError subclass; WeaviateBatchError messages carry the gRPC details only.
• client_executor.py — is_ready/is_live/gRPC-ping diagnostics moved from print() (stdout) to logger.warning() on the weaviate-client logger (stderr).

Testing

Package suite (141 tests) + base suites (554 unit/mock/proto) in CI, ruff/flake8/pyright clean including packages/web; real-Pyodide e2e (22 steps: connect w/ init checks, batch insert/delete, queries, aggregations, tenants, HEAD/204 REST calls, references, error mapping, stream fail-fast, transport self-check); the full client workflow also verified on CPython through the grpc-web path (httpx sender).

A second review round (#2137, merged here) fixed what the first e2e did not reach: under Pyodide every HEAD/204 REST call crashed in Pyodide's own httpx transport (fixed by always using the package transport), reference_add_many read an unset .elapsed, Timeout(...=inf) overflowed in the fetch layer, and the async OIDC refresher retried a permanent invalid_grant once a second. Verified hands-on in Pyodide 314.0.4 against 1.39.0: the HEAD/204 calls, Timeout(query|insert|init=inf), Timeout(query=0.001) on REST → WeaviateTimeoutError, a 30 MB insert_many no longer cut at ~5 s, API-key auth incl. a trailers-only error, 30-way concurrency, 8 MB blobs, 110 MB → clean RESOURCE_EXHAUSTED, cancellation, unicode round-trips; on CPython the OIDC backoff was observed as 4 refresh POSTs in 12 s.

Additionally verified against a live 1.39.0 server: the query surface over grpc-web (near_vector with distance/certainty, hybrid in both fusion modes with explain_score, near_object, two-level nested references, group_by, cursor paging, the complex-type matrix, generative); a 502 maps to UNAVAILABLE and is retried again (1 attempt -> 6); a 404 names both candidate causes (server older than 1.38.3, or a wrong grpc_path_prefix); and the ~5s REST cap under Pyodide is lifted (96MB insert: failed at 5.7s, now OK in 9.1s). Message ceiling over grpc-web is the server's own grpcMaxMessageSize, surfaced as RESOURCE_EXHAUSTED.

Verified in a real browser

A cross-origin run in Chrome (page on :8399, Weaviate on :8290) passes end to end. Weaviate 1.39.0 serves grpc-web CORS correctly with no configuration, including Access-Control-Expose-Headers: Grpc-Status, Grpc-Message, Grpc-Status-Details-Bin, so trailers-only errors are readable from browser JS. CORS_ALLOW_ORIGIN only narrows *. Two caveats: the server's allow-headers list is a closed allowlist, so a custom header passed via headers={...} breaks the browser preflight; and /v1/.well-known/ready sends no CORS headers at all (not on the client's browser path).

Deferred

Publish/lockstep versioning for weaviate-client-web — once it ships to PyPI, weaviate-client gains weaviate-client-web ; sys_platform == "emscripten" (after verifying micropip handles the dependency cycle), collapsing the WASM install to micropip.install("weaviate-client").

🤖 Generated with Claude Code

[orca-security-eu]

Orca Security Scan Summary

Status	Check	Issues by priority
Passed	Infrastructure as Code	0   0   0   0	View in Orca
Passed	SAST	0   0   0   0	View in Orca
Passed	Secrets	0   0   0   0	View in Orca
Passed	Vulnerabilities	0   0   0   0	View in Orca

[Copilot]

Pull request overview

This PR enables the async Weaviate Python client’s gRPC data path to run under Pyodide/WebAssembly by routing RPCs over grpc-web (fetch) and providing a companion weaviate-python-grpc-web package that supplies a pure-Python grpc shim plus a grpc-web grpc.aio.Channel implementation. It also makes base-package dependency/version selection behave correctly when grpcio cannot be installed on Emscripten.

Changes:

• Mark grpcio as not required on sys_platform == "emscripten" and add a narrow grpcio metadata fallback for proto variant selection.
• Add packages/grpc-web/ with a grpc shim (sys.modules install) and a unary-only grpc-web channel that maps grpc-web responses to AioRpcError.
• Add unit/integration-style tests for framing, transport behavior, and shim-based import weaviate in a subprocess.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
weaviate/proto/v1/init.py	Adds grpcio metadata fallback to select a compatible generated-proto variant when grpcio dist metadata is absent (Pyodide).
setup.cfg	Excludes grpcio dependency under Emscripten via environment marker.
proto_test/test_proto.py	Adds regression tests for the grpcio metadata fallback behavior.
packages/grpc-web/src/weaviate_grpc_web/init.py	Bootstraps shim install under Emscripten and forces pure-Python protobuf runtime.
packages/grpc-web/src/weaviate_grpc_web/_shim.py	Implements minimal pure-Python grpc API surface + grpc.aio.Channel base class for client imports/runtime.
packages/grpc-web/src/weaviate_grpc_web/_channel.py	Implements unary grpc-web channel/multicallables and response/status mapping.
packages/grpc-web/src/weaviate_grpc_web/_framing.py	Implements grpc-web frame encoding/splitting and trailer parsing.
packages/grpc-web/src/weaviate_grpc_web/_sender.py	Provides default pyfetch sender and an httpx sender for CPython tests/integration.
packages/grpc-web/src/weaviate_grpc_web/py.typed	Marks the package as typed.
packages/grpc-web/tests/conftest.py	Makes the grpc-web package importable in tests without editable install.
packages/grpc-web/tests/test_framing.py	Tests framing encode/split/trailer parsing and malformed/compressed rejection.
packages/grpc-web/tests/test_transport.py	Tests unary transport behavior, metadata folding, timeout header, and error mapping.
packages/grpc-web/tests/test_shim_install.py	Subprocess tests for shim install, import weaviate, and real-proto unary round-trip.
packages/grpc-web/README.md	Documents grpc-web transport usage and limitations.
packages/grpc-web/pyproject.toml	Defines the companion distribution metadata and packaging config.

---

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

[g-despot]

Follow-up commit: grpc-web on the REST host:port via a base-path prefix (99f5356e)

Builds on the transport in this PR to support the production wire contract from weaviate/weaviate#11673 — grpc-web multiplexed onto the REST host:port under a base-path prefix (e.g. /grpc-web, via an in-process vanguard transcoder).

Core client

• ConnectionParams gains grpc_path_prefix (threaded through from_params/from_url and the connect_to_custom / use_async_with_custom helpers). Normalized to a single leading slash, no trailing slash; None/"" == native gRPC.
• _check_port_collision no longer rejects the same host:port when a prefix is set. Native gRPC (no prefix) still raises — unchanged.
• _grpc_channel forwards the prefix to the transport as a ("grpc-web.path_prefix", prefix) channel option only in grpc-web mode, so native channel options stay byte-for-byte unchanged.

weaviate-python-grpc-web

• The shim's channel factories read that option; GrpcWebChannel prepends the prefix, so requests go to <scheme>://<host>:<port><prefix>/weaviate.v1.Weaviate/<Method>.

Verification

• Unit: new test/test_connection_params.py (collision relaxed only with a prefix; native same-port still raises; option forwarded/omitted) + new grpc-web transport cases for the prefixed/normalized URL.
• End-to-end against a vanguard transcoder with grpc_host == http_host == localhost:8090 and grpc_path_prefix="/grpc-web": insert_many / fetch_objects / aggregate round-trip over grpc-web with matching counts; the native same-host:port config still raises ValidationError.

The relaxation is strictly opt-in (keyed on the prefix), so native gRPC behavior is preserved.

[Copilot]

Pull request overview

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

[codecov-commenter]

Codecov Report

❌ Patch coverage is 94.56311% with 28 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.64%. Comparing base (95b5d76) to head (524a27a).
⚠️ Report is 79 commits behind head on main.

Files with missing lines	Patch %	Lines
weaviate/connect/v4.py	82.14%	20 Missing ⚠️
weaviate/collections/batch/async_.py	82.60%	4 Missing ⚠️
weaviate/exceptions.py	90.90%	2 Missing ⚠️
mock_tests/test_auth.py	98.52%	1 Missing ⚠️
test/test_batch_async.py	98.63%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2056      +/-   ##
==========================================
+ Coverage   86.64%   88.64%   +2.00%     
==========================================
  Files         300      307       +7     
  Lines       23172    23926     +754     
==========================================
+ Hits        20077    21209    +1132     
+ Misses       3095     2717     -378     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Copilot reviewed 41 out of 43 changed files in this pull request and generated 3 comments.

Suppressed comments (5)

weaviate/connect/v4.py:696

• The sync refresher also waits the full token lifetime before its first attempt, while later attempts use expires_in - 30. For normal long-lived tokens this creates an authentication gap at every initial connection; start this loop with the same 30-second lead time.
  packages/web/src/weaviate_client_web/_httpx_fetch.py:90
• An explicit zero timeout means an immediate timeout in native httpx and in this package's gRPC path (asyncio.wait_for(..., 0)), but this REST transport turns it into no deadline. Thus Timeout(query=0) can wait indefinitely only for REST calls under Pyodide. Preserve zero as an immediate AbortSignal and reserve None/non-finite values for no deadline.

    Zero, negative and non-finite timeouts all mean "no deadline". Rounded up so a
    sub-millisecond timeout never becomes an immediate abort.
    """
    if timeout is None or not math.isfinite(timeout) or timeout <= 0:
        return None
    return min(math.ceil(timeout * 1000), _MAX_ABORT_SIGNAL_MS)

packages/web/src/weaviate_client_web/_channel.py:435

• The standard HTTP-to-gRPC fallback mapping maps HTTP 504 (Gateway Timeout) to DEADLINE_EXCEEDED, not UNAVAILABLE. Returning UNAVAILABLE makes the client's retry layer repeat an operation that has already exceeded the gateway deadline and exposes the wrong status to callers.

        429: StatusCode.UNAVAILABLE,
        502: StatusCode.UNAVAILABLE,
        503: StatusCode.UNAVAILABLE,
        504: StatusCode.UNAVAILABLE,

weaviate/connect/helpers.py:711

• The PR description and quickstart contradict this public API: they pass grpc_path_prefix to use_async_with_custom() and state that the local/cloud helpers do not add a prefix, but this implementation exposes no such argument and automatically routes all three async helpers to /v1/grpc-web under Emscripten. As written, the advertised quickstart raises TypeError; update the PR description to match the implemented auto-routing contract.
  weaviate/connect/helpers.py:57
• When only grpc_secure differs, this warning is triggered but prints identical host:port strings, so users cannot see what was overridden. Include the TLS state in both endpoint values so the new warning accurately identifies the discarded configuration.