fix(grpc-web): guard grpc-web mode (shim+async required), tighten timeout/fallback

Addresses the second Copilot review on #2056:

- base.py: grpc_path_prefix now fails fast in _grpc_channel when used on a sync client
  or when the weaviate-python-grpc-web shim is not active, instead of silently building
  a native grpcio channel that ignores the prefix.
- helpers.py: connect_to_custom (sync) rejects a non-empty grpc_path_prefix and points
  to use_async_with_custom; the docstring is clarified that grpc-web is async-only.
- _channel.py: _encode_timeout rounds the grpc-timeout up (math.ceil) so we never
  advertise a shorter deadline than requested.
- proto/v1/__init__.py: the grpcio metadata fallback is restricted to Emscripten, so a
  broken/partial grpcio install on a normal platform surfaces as PackageNotFoundError
  instead of being masked by a fallback stub version.

Tests added/updated (sync/no-shim rejection, off-emscripten raise, grpc-timeout
round-up). End-to-end against a vanguard transcoder on a shared host:port still passes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: g-despot

packages/grpc-web/src/weaviate_grpc_web/_channel.py

@@ -14,6 +14,7 @@
 
 import asyncio
 import base64
+import math
 import urllib.parse
 from typing import Any, Callable, Dict, Optional
 
@@ -37,10 +38,12 @@ def get_sender() -> Sender:
 
 def _encode_timeout(seconds: float) -> str:
     """Encode a timeout as a grpc-timeout header value (``<positive int><unit>``)."""
-    millis = max(1, int(seconds * 1000))
+    # Round up so we never advertise a shorter deadline than requested (which would risk
+    # premature server-side cancellation); grpc-timeout takes a positive integer + unit.
+    millis = max(1, math.ceil(seconds * 1000))
     if millis < 100_000_000:
         return f"{millis}m"
-    return f"{max(1, int(seconds))}S"
+    return f"{max(1, math.ceil(seconds))}S"
 
 
 def _fold_metadata(headers: Dict[str, str], metadata: Any) -> None:

packages/grpc-web/tests/test_transport.py

@@ -180,6 +180,15 @@ def test_malformed_grpc_status_maps_to_internal():
     assert excinfo.value.code() is StatusCode.INTERNAL
 
 
+def test_grpc_timeout_header_rounds_up():
+    sender = FakeSender(body=_ok_response(b"x"))
+    channel = _channel(sender)
+    mc = channel.unary_unary("/svc/M", lambda x: x, lambda b: b)
+    # 123.4ms must round UP to 124ms (never advertise a shorter deadline than requested).
+    asyncio.run(mc(b"q", timeout=0.1234))
+    assert sender.calls[0][1]["grpc-timeout"] == "124m"
+
+
 def test_close_is_awaitable_noop():
     channel = _channel(FakeSender())
     assert asyncio.run(channel.close()) is None

proto_test/test_proto.py

@@ -60,12 +60,32 @@ def raises(pkg: str) -> str:
         raise PackageNotFoundError(pkg)
 
     monkeypatch.setattr(mod, "metadata_version", raises)
+    monkeypatch.setattr("sys.platform", "emscripten")
 
     assert str(mod.get_version("grpcio")) == "1.72.1"
     with pytest.raises(PackageNotFoundError):
         mod.get_version("protobuf")
 
 
+@pytest.mark.skipif(
+    _INCOMPATIBLE_GRPC_PB,
+    reason="weaviate.proto.v1 cannot be imported with an incompatible grpcio/protobuf "
+    "pair (CI version-gate matrix); the gate is covered by test_proto_import and the "
+    "fallback is exercised in every compatible cell",
+)
+def test_grpcio_missing_metadata_raises_off_emscripten(monkeypatch):
+    """Off Emscripten, missing grpcio metadata surfaces instead of being masked."""
+    mod = importlib.import_module("weaviate.proto.v1")
+
+    def raises(pkg: str) -> str:
+        raise PackageNotFoundError(pkg)
+
+    monkeypatch.setattr(mod, "metadata_version", raises)
+    monkeypatch.setattr("sys.platform", "linux")
+    with pytest.raises(PackageNotFoundError):
+        mod.get_version("grpcio")
+
+
 @pytest.mark.skipif(
     _INCOMPATIBLE_GRPC_PB,
     reason="weaviate.proto.v1 cannot be imported with an incompatible grpcio/protobuf "

test/test_connection_params.py

@@ -3,6 +3,7 @@
 
 import weaviate.connect.base as base_mod
 from weaviate.connect.base import ConnectionParams
+from weaviate.exceptions import WeaviateInvalidInputError
 
 
 def test_same_host_port_raises_without_prefix() -> None:
@@ -88,6 +89,8 @@ def fake_insecure_channel(target, options=None, **kwargs):
         return "CHANNEL"
 
     monkeypatch.setattr(base_mod.grpc.aio, "insecure_channel", fake_insecure_channel)
+    # grpc-web mode requires the shim to be active; simulate it being installed.
+    monkeypatch.setattr(base_mod.grpc, "__weaviate_grpc_web_shim__", True, raising=False)
 
     params = ConnectionParams.from_params(
         http_host="localhost",
@@ -105,6 +108,48 @@ def fake_insecure_channel(target, options=None, **kwargs):
     assert ("grpc-web.path_prefix", "/grpc-web") in captured["options"]
 
 
+def _grpc_web_params() -> ConnectionParams:
+    return ConnectionParams.from_params(
+        http_host="localhost",
+        http_port=8090,
+        http_secure=False,
+        grpc_host="localhost",
+        grpc_port=8090,
+        grpc_secure=False,
+        grpc_path_prefix="/grpc-web",
+    )
+
+
+def test_grpc_channel_rejects_prefix_without_shim(monkeypatch) -> None:
+    # No grpc-web shim active -> must fail fast instead of silently building a native
+    # grpcio channel that ignores the prefix.
+    monkeypatch.delattr(base_mod.grpc, "__weaviate_grpc_web_shim__", raising=False)
+    with pytest.raises(WeaviateInvalidInputError, match="weaviate-python-grpc-web"):
+        _grpc_web_params()._grpc_channel(proxies={}, grpc_msg_size=None, is_async=True)
+
+
+def test_grpc_channel_rejects_prefix_for_sync_client() -> None:
+    # grpc-web is async-only; a sync channel with a prefix must be rejected.
+    with pytest.raises(WeaviateInvalidInputError, match="async"):
+        _grpc_web_params()._grpc_channel(proxies={}, grpc_msg_size=None, is_async=False)
+
+
+def test_connect_to_custom_rejects_grpc_web_prefix() -> None:
+    # The synchronous helper must reject grpc-web up front (before connecting).
+    import weaviate
+
+    with pytest.raises(WeaviateInvalidInputError, match="async-only"):
+        weaviate.connect_to_custom(
+            http_host="localhost",
+            http_port=8080,
+            http_secure=False,
+            grpc_host="localhost",
+            grpc_port=8080,
+            grpc_secure=False,
+            grpc_path_prefix="/grpc-web",
+        )
+
+
 def test_grpc_channel_omits_option_without_prefix(monkeypatch) -> None:
     captured: dict = {}
 

weaviate/connect/base.py

@@ -9,6 +9,7 @@
 from pydantic import BaseModel, field_validator, model_validator
 
 from weaviate.config import GrpcConfig, Proxies
+from weaviate.exceptions import WeaviateInvalidInputError
 from weaviate.types import NUMBER
 from weaviate.util import is_weaviate_domain
 
@@ -160,10 +161,24 @@ def _grpc_channel(
         if grpc_config is not None and grpc_config.channel_options is not None:
             options.extend(grpc_config.channel_options)
 
-        # In grpc-web mode, forward the base-path prefix to the transport via channel
-        # options (consumed by the weaviate-python-grpc-web shim). Not added for native
-        # gRPC, so the native channel options stay byte-for-byte unchanged.
+        # grpc-web mode (prefix set): only valid for an async client, and only when the
+        # weaviate-python-grpc-web shim has replaced the grpc module (it consumes the
+        # grpc-web.path_prefix option). Fail fast otherwise — a native grpcio channel
+        # would silently ignore the option and route over native gRPC, a confusing
+        # misconfiguration. Nothing is added for native gRPC, so its channel options stay
+        # byte-for-byte unchanged.
         if (prefix := self._grpc_web_path_prefix) != "":
+            if not is_async:
+                raise WeaviateInvalidInputError(
+                    "grpc_path_prefix (grpc-web) is only supported for async clients; "
+                    "use use_async_with_custom(...) / WeaviateAsyncClient"
+                )
+            if not getattr(grpc, "__weaviate_grpc_web_shim__", False):
+                raise WeaviateInvalidInputError(
+                    "grpc_path_prefix enables grpc-web, which requires the "
+                    "'weaviate-python-grpc-web' package (it installs a grpc shim before "
+                    "'import weaviate'); it is not active in this environment"
+                )
             options.append(("grpc-web.path_prefix", prefix))
 
         if is_async:

weaviate/connect/helpers.py

@@ -17,6 +17,7 @@
 from weaviate.config import AdditionalConfig
 from weaviate.connect.base import ConnectionParams, ProtocolParams
 from weaviate.embedded import WEAVIATE_VERSION, EmbeddedOptions
+from weaviate.exceptions import WeaviateInvalidInputError
 from weaviate.util import docstring_deprecated
 from weaviate.validator import _validate_input, _ValidateArgument
 from weaviate.warnings import _Warnings
@@ -313,11 +314,11 @@ def connect_to_custom(
             a bearer token, in which case use `weaviate.classes.init.Auth.bearer_token()`, a client secret, in which case use `weaviate.classes.init.Auth.client_credentials()`
             or a username and password, in which case use `weaviate.classes.init.Auth.client_password()`.
         skip_init_checks: Whether to skip the initialization checks when connecting to Weaviate.
-        grpc_path_prefix: Optional base-path prefix for a grpc-web endpoint served on the
-            same host:port as REST (e.g. "/grpc-web"). When set, gRPC requests are sent
-            over grpc-web to ``<scheme>://<grpc_host>:<grpc_port><prefix>/...`` and sharing
-            the REST host:port is allowed. Requires the ``weaviate-python-grpc-web``
-            package. Defaults to None (native gRPC).
+        grpc_path_prefix: grpc-web base-path prefix. grpc-web is async-only, so it is NOT
+            supported by the synchronous ``connect_to_custom`` — passing a non-empty value
+            raises ``WeaviateInvalidInputError``. Use
+            ``use_async_with_custom(..., grpc_path_prefix=...)`` instead. Defaults to None
+            (native gRPC).
 
     Returns:
         The client connected to the instance with the required parameters set appropriately.
@@ -350,6 +351,11 @@ def connect_to_custom(
         True
         >>> # The connection is automatically closed when the context is exited.
     """
+    if grpc_path_prefix:
+        raise WeaviateInvalidInputError(
+            "grpc_path_prefix enables grpc-web, which is async-only; use "
+            "use_async_with_custom(...) instead of connect_to_custom(...)"
+        )
     return __connect(
         WeaviateClient(
             ConnectionParams.from_params(

weaviate/proto/v1/__init__.py

@@ -1,3 +1,4 @@
+import sys
 import warnings
 
 
@@ -19,16 +20,18 @@
 # This happens under Pyodide/Emscripten, where grpcio has no wheel and is excluded
 # via the `sys_platform != "emscripten"` marker in setup.cfg; the grpc module itself
 # is provided there by a pure-Python shim (see the weaviate-python-grpc-web package).
-# On every normal install grpcio's metadata is present and the real version is used,
-# so this branch is not taken. Restricted to grpcio so that a genuinely missing
-# protobuf (which is required and pure-Python under Pyodide) is never masked.
+# On every normal install grpcio's metadata is present and the real version is used, so
+# this branch is not taken. Restricted to grpcio AND to Emscripten, so that a broken or
+# partial grpcio install on a normal platform (metadata missing) still surfaces as
+# PackageNotFoundError instead of silently selecting a fallback stub, and so a genuinely
+# missing protobuf (required and pure-Python under Pyodide) is never masked.
 _GRPCIO_FALLBACK_VERSION = "1.72.1"
 
 def get_version(pkg: str) -> version.Version:
     try:
         return version.parse(metadata_version(pkg))
     except PackageNotFoundError:
-        if pkg == "grpcio":
+        if pkg == "grpcio" and sys.platform == "emscripten":
             return version.parse(_GRPCIO_FALLBACK_VERSION)
         raise