fix(grpc-web): round-2 review fixes — REST under Pyodide, OIDC refresh backoff, batch exit semantics

[g-despot]

Stacked on #2056 — merges into feat/grpc-web-wasm-transport. Fixes from a second deep review of that PR at 524a27a6 (code review of both the companion and the base-client changes, plus hands-on probes in Pyodide 314.0.4 against Weaviate 1.39.0).

What's here

• REST under Pyodide crashed on every HEAD/204 (a344c896) — the companion deferred to Pyodide's bundled httpx transport, which reads Response.body unconditionally (null for HEAD and 204), so data.exists/update/delete_by_id/reference_delete and tenants.exists raised a raw AttributeError; it also doesn't enforce sub-5 s REST timeouts end to end. The package transport is now always installed under Emscripten, builds stream-backed responses (reference_add_many reads .elapsed), takes the deadline from the read timeout only, and rounds the AbortSignal up with an int32 cap. The import hook only says "install weaviate-client-web" when the companion itself is missing. The e2e gains a transport self-check plus HEAD/204 and reference steps — an A/B run with the previous transport fails them.
• Framing / deadline hardening + diagnostics (e9c81bec) — non-finite deadlines send no grpc-timeout; units escalate m → S → M and never H (Weaviate's transcoder rejects anything above 8H); LF-only trailer lines and non-ASCII keys are accepted; an unknown frame flag, a message after the trailer, or more than one message frame in a unary response is INTERNAL instead of silently mis-read; metadata with CR/LF/NUL is rejected before I/O. An HTTP 405 and a missing grpc_path_prefix under Emscripten both name the fix; a truncated body is reported as truncated, not as a wrong path.
• README (1ffa2a05) — use_async_with_custom(..., grpc_path_prefix="/v1/grpc-web") on the REST port is the example; the previous use_async_with_local one cannot reach core-native grpc-web (no prefix → the shim POSTs to the native gRPC port → 63 s of retries). Full list of headers a CORS allow-list must carry; no more skip_init_checks recommendation.
• OIDC refresh backoff, close(), timeouts (b950e39a, all platforms) — a permanent OAuth failure (invalid_grant) made the async refresher POST to the IdP every second until close(), while the sync thread died silently on the same error. Both colours now retry with a capped exponential backoff (1 s → 60 s, reset on success; Con001 reworded). Async close() awaits the cancelled task; the sync thread waits on the Event it was started with, so close() ends it promptly and a reconnect leaves no second refresher. Non-finite timeouts mean "no deadline" for every REST/gRPC hand-off (the Emscripten connect-timeout arm is gone — the package transport reads only read); the grpc-web prefix guards run at construction; a RuntimeError maps to WeaviateClosedClientError only when the http client is actually closed.
• Batch stream exit (c099eb3c) — leaving with/async with client.batch.stream() never replaces the caller's exception (CancelledError included) with a background failure; both colours raise WeaviateBatchStreamError when the workers failed or data was left unsent, saying how much (the sync colour previously swallowed this); _BatchStreamShutdownError joins the taxonomy; WeaviateBatchError carries the gRPC details only.
• CI (8a18975e) — pyright and flake8 now cover packages/web.

Behaviour changes worth a second look

Sync refresher catches any exception and backs off (was: HTTPError only, then dies); sync batch.stream() exit raises like async; Timeout(...=inf) means no deadline; the prefix guard fires at construction instead of inside connect().

Key areas for review

• packages/web/…/_httpx_fetch.py — the ByteStream hand-off and _pick_timeout reading only read (nothing in the client relies on connect/pool standing in for a missing read timeout).
• weaviate/connect/v4.py — _cancel_background_token_refresh / async close(): same-loop task is awaited with return_exceptions=True, an other-loop task is only scheduled for cancel; _token_refresh_backoff and both refresh loops (reset on success, never below 1 s).
• weaviate/collections/batch/batch_wrapper.py __exit__/__aexit__ — the e is not exc_val identity check is what stops the propagating exception being logged twice; sync.py:_wait copies results before raising so failed_objects stays inspectable.
• packages/web/…/_channel.py — _encode_timeout unit bounds and the frame-error → diagnostic mapping (unknown flag vs truncated decides what a user sees).
• weaviate/__init__.py — the ModuleNotFoundError.name == "weaviate_client_web" test lets a companion with a broken dependency surface its own error.

Verification

554 unit + mock + proto tests (from 521) and 141 companion tests (from 87); ruff, flake8 and pyright clean including packages/web; every fix has a test that fails without it (mutation-checked). Real-Pyodide e2e 22/22 against Weaviate 1.39.0 core-native /v1/grpc-web. Hands-on under Pyodide: the HEAD/204 calls above pass, Timeout(query|insert|init=inf) work, Timeout(query=0.001) on REST now raises WeaviateTimeoutError, a 30 MB insert_many is no longer cut at ~5 s, wrong-prefix and 405 errors are diagnosable. On CPython (native gRPC): OIDC backoff observed as 4 refresh POSTs in 12 s (1/2/4/8 s), close() prompt in both colours; sync + async smoke and batch-stream context exit unchanged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HZqnMkJBKrb7mUxhzCWmeB

[orca-security-eu]

Orca Security Scan Summary

Status	Check	Issues by priority
Passed	Secrets	0   0   0   0	View in Orca