feat(grpc-web): support grpc-web on the REST host:port via a base-path prefix

Add a configurable gRPC base-path prefix so the client can talk to a grpc-web
endpoint multiplexed onto the REST host:port (the production wire contract:
grpc-web served under "/grpc-web/" via an in-process transcoder).

- 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 grpc-web
  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 the
  native channel options stay byte-for-byte unchanged.
- weaviate-python-grpc-web: the shim's channel factories read that option and
  GrpcWebChannel prepends the prefix, so requests go to
  <scheme>://<host>:<port><prefix>/weaviate.v1.Weaviate/<Method>.

Tested: new ConnectionParams unit tests (collision relaxed only with a prefix;
native same-port still raises; option forwarded/omitted) and grpc-web transport
tests for the prefixed/normalized URL. End-to-end verified against a vanguard
transcoder on a shared host:port (insert_many/fetch_objects/aggregate over
grpc-web with grpc_host == http_host == localhost:8090).

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

Author: g-despot

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

@@ -125,12 +125,16 @@ def __init__(
         target: Optional[str],
         secure: bool,
         options: Any = None,
+        path_prefix: str = "",
         sender: Optional[Sender] = None,
     ) -> None:
         if not target:
             raise ValueError("GrpcWebChannel requires a target (host:port)")
         scheme = "https" if secure else "http"
         self._base_url = f"{scheme}://{target}"
+        # Normalize to a single leading slash and no trailing slash; "" == native path.
+        cleaned = (path_prefix or "").strip("/")
+        self._path_prefix = f"/{cleaned}" if cleaned else ""
         self._sender: Sender = sender or get_sender()
 
     def unary_unary(
@@ -173,7 +177,7 @@ async def _unary(
         if timeout is not None:
             headers["grpc-timeout"] = _encode_timeout(timeout)
 
-        url = self._base_url + path
+        url = self._base_url + self._path_prefix + path
         status, resp_headers, body = await self._sender(
             url, headers, encode_message(payload), timeout
         )

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

@@ -170,20 +170,38 @@ def _sync_channel_unsupported(*_args: Any, **_kwargs: Any) -> "AioChannel":
     raise RuntimeError(_ASYNC_ONLY_MESSAGE)
 
 
+def _path_prefix_from_options(options: Any) -> str:
+    """Extract the ``("grpc-web.path_prefix", prefix)`` channel option, or "" if absent."""
+    for item in options or ():
+        if isinstance(item, (tuple, list)) and len(item) == 2 and item[0] == "grpc-web.path_prefix":
+            return item[1] or ""
+    return ""
+
+
 def _aio_secure_channel(
     target: Optional[str] = None, credentials: Any = None, options: Any = None, **_kw: Any
 ) -> AioChannel:
     from ._channel import GrpcWebChannel
 
-    return GrpcWebChannel(target=target, secure=True, options=options)
+    return GrpcWebChannel(
+        target=target,
+        secure=True,
+        options=options,
+        path_prefix=_path_prefix_from_options(options),
+    )
 
 
 def _aio_insecure_channel(
     target: Optional[str] = None, options: Any = None, **_kw: Any
 ) -> AioChannel:
     from ._channel import GrpcWebChannel
 
-    return GrpcWebChannel(target=target, secure=False, options=options)
+    return GrpcWebChannel(
+        target=target,
+        secure=False,
+        options=options,
+        path_prefix=_path_prefix_from_options(options),
+    )
 
 
 def _noop(*_args: Any, **_kwargs: Any) -> None:

packages/grpc-web/tests/test_transport.py

@@ -144,6 +144,48 @@ def test_close_is_awaitable_noop():
     assert asyncio.run(channel.close()) is None
 
 
+def test_path_prefix_prepended_to_url():
+    sender = FakeSender(body=_ok_response(b"r"))
+    channel = GrpcWebChannel(
+        "example.com:8090", secure=False, sender=sender, path_prefix="/grpc-web"
+    )
+    mc = channel.unary_unary("/weaviate.v1.Weaviate/Search", lambda x: x, lambda b: b)
+    asyncio.run(mc(b"q"))
+    assert sender.calls[0][0] == "http://example.com:8090/grpc-web/weaviate.v1.Weaviate/Search"
+
+
+@pytest.mark.parametrize(
+    "raw,expected_url",
+    [
+        ("grpc-web", "http://h:1/grpc-web/svc/M"),
+        ("/grpc-web/", "http://h:1/grpc-web/svc/M"),
+        ("/a/b", "http://h:1/a/b/svc/M"),
+        ("", "http://h:1/svc/M"),
+    ],
+)
+def test_path_prefix_normalized_in_url(raw, expected_url):
+    sender = FakeSender(body=_ok_response(b"r"))
+    channel = GrpcWebChannel("h:1", secure=False, sender=sender, path_prefix=raw)
+    mc = channel.unary_unary("/svc/M", lambda x: x, lambda b: b)
+    asyncio.run(mc(b"q"))
+    assert sender.calls[0][0] == expected_url
+
+
+def test_shim_factory_extracts_path_prefix_option():
+    from weaviate_grpc_web._shim import _aio_insecure_channel
+
+    with_prefix = _aio_insecure_channel(
+        target="h:1",
+        options=[("grpc.max_send_message_length", 1), ("grpc-web.path_prefix", "/grpc-web")],
+    )
+    assert with_prefix._path_prefix == "/grpc-web"
+
+    without_prefix = _aio_insecure_channel(
+        target="h:1", options=[("grpc.max_send_message_length", 1)]
+    )
+    assert without_prefix._path_prefix == ""
+
+
 def test_set_sender_overrides_default():
     sender = FakeSender(body=_ok_response(b"y"))
     set_sender(sender)

test/test_connection_params.py

@@ -0,0 +1,128 @@
+import pytest
+from pydantic import ValidationError
+
+import weaviate.connect.base as base_mod
+from weaviate.connect.base import ConnectionParams
+
+
+def test_same_host_port_raises_without_prefix() -> None:
+    with pytest.raises(ValidationError, match="must be different"):
+        ConnectionParams.from_params(
+            http_host="localhost",
+            http_port=8090,
+            http_secure=False,
+            grpc_host="localhost",
+            grpc_port=8090,
+            grpc_secure=False,
+        )
+
+
+def test_from_url_same_host_port_raises_without_prefix() -> None:
+    with pytest.raises(ValidationError, match="must be different"):
+        ConnectionParams.from_url("http://localhost:8090", grpc_port=8090)
+
+
+def test_same_host_port_allowed_with_grpc_web_prefix() -> None:
+    params = 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",
+    )
+    assert params._grpc_web_path_prefix == "/grpc-web"
+
+
+def test_from_url_same_host_port_allowed_with_prefix() -> None:
+    params = ConnectionParams.from_url(
+        "http://localhost:8090", grpc_port=8090, grpc_path_prefix="/grpc-web"
+    )
+    assert params._grpc_web_path_prefix == "/grpc-web"
+
+
+def test_different_ports_still_ok_without_prefix() -> None:
+    params = ConnectionParams.from_params(
+        http_host="localhost",
+        http_port=8080,
+        http_secure=False,
+        grpc_host="localhost",
+        grpc_port=50051,
+        grpc_secure=False,
+    )
+    assert params._grpc_web_path_prefix == ""
+
+
+@pytest.mark.parametrize(
+    "raw,expected",
+    [
+        (None, ""),
+        ("", ""),
+        ("/", ""),
+        ("grpc-web", "/grpc-web"),
+        ("/grpc-web", "/grpc-web"),
+        ("grpc-web/", "/grpc-web"),
+        ("/a/b/", "/a/b"),
+    ],
+)
+def test_path_prefix_normalization(raw, expected) -> None:
+    params = ConnectionParams.from_params(
+        http_host="h",
+        http_port=8080,
+        http_secure=False,
+        grpc_host="g",
+        grpc_port=50051,
+        grpc_secure=False,
+        grpc_path_prefix=raw,
+    )
+    assert params._grpc_web_path_prefix == expected
+
+
+def test_grpc_channel_forwards_path_prefix_option(monkeypatch) -> None:
+    captured: dict = {}
+
+    def fake_insecure_channel(target, options=None, **kwargs):
+        captured["target"] = target
+        captured["options"] = options
+        return "CHANNEL"
+
+    monkeypatch.setattr(base_mod.grpc.aio, "insecure_channel", fake_insecure_channel)
+
+    params = 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",
+    )
+    channel = params._grpc_channel(proxies={}, grpc_msg_size=None, is_async=True)
+
+    assert channel == "CHANNEL"
+    assert captured["target"] == "localhost:8090"
+    assert ("grpc-web.path_prefix", "/grpc-web") in captured["options"]
+
+
+def test_grpc_channel_omits_option_without_prefix(monkeypatch) -> None:
+    captured: dict = {}
+
+    def fake_insecure_channel(target, options=None, **kwargs):
+        captured["options"] = options
+        return "CHANNEL"
+
+    monkeypatch.setattr(base_mod.grpc.aio, "insecure_channel", fake_insecure_channel)
+
+    params = ConnectionParams.from_params(
+        http_host="localhost",
+        http_port=8080,
+        http_secure=False,
+        grpc_host="localhost",
+        grpc_port=50051,
+        grpc_secure=False,
+    )
+    params._grpc_channel(proxies={}, grpc_msg_size=None, is_async=True)
+
+    option_keys = [key for key, _ in captured["options"]]
+    assert "grpc-web.path_prefix" not in option_keys

weaviate/connect/base.py

@@ -47,9 +47,19 @@ def is_gcp(self) -> bool:
 class ConnectionParams(BaseModel):
     http: ProtocolParams
     grpc: ProtocolParams
+    # Optional base-path prefix for a grpc-web endpoint served on the REST host:port
+    # (e.g. "/grpc-web"). None/"" means native gRPC. When set, sharing the REST
+    # host:port is permitted and the prefix is forwarded to the grpc-web transport.
+    grpc_path_prefix: Optional[str] = None
 
     @classmethod
-    def from_url(cls, url: str, grpc_port: int, grpc_secure: bool = False) -> "ConnectionParams":
+    def from_url(
+        cls,
+        url: str,
+        grpc_port: int,
+        grpc_secure: bool = False,
+        grpc_path_prefix: Optional[str] = None,
+    ) -> "ConnectionParams":
         parsed_url = urlparse(url)
         if parsed_url.scheme not in ["http", "https"]:
             raise ValueError(f"Unsupported scheme: {parsed_url.scheme}")
@@ -69,6 +79,7 @@ def from_url(cls, url: str, grpc_port: int, grpc_secure: bool = False) -> "Conne
                 port=grpc_port,
                 secure=grpc_secure or parsed_url.scheme == "https",
             ),
+            grpc_path_prefix=grpc_path_prefix,
         )
 
     @classmethod
@@ -80,6 +91,7 @@ def from_params(
         grpc_host: str,
         grpc_port: int,
         grpc_secure: bool,
+        grpc_path_prefix: Optional[str] = None,
     ) -> "ConnectionParams":
         return cls(
             http=ProtocolParams(
@@ -92,14 +104,18 @@ def from_params(
                 port=grpc_port,
                 secure=grpc_secure,
             ),
+            grpc_path_prefix=grpc_path_prefix,
         )
 
     def is_gcp_on_wcd(self) -> bool:
         return "gcp" in self.http.host.lower() and is_weaviate_domain(self.http.host)
 
     @model_validator(mode="after")
     def _check_port_collision(self: T) -> T:
-        if self.http.host == self.grpc.host and self.http.port == self.grpc.port:
+        same_endpoint = self.http.host == self.grpc.host and self.http.port == self.grpc.port
+        # grpc-web can be multiplexed onto the REST port under a base-path prefix, so a
+        # shared host:port is only a conflict for native gRPC (no prefix configured).
+        if same_endpoint and self._grpc_web_path_prefix == "":
             raise ValueError("http.port and grpc.port must be different if using the same host")
         return self
 
@@ -111,6 +127,16 @@ def _grpc_address(self) -> Tuple[str, int]:
     def _grpc_target(self) -> str:
         return f"{self.grpc.host}:{self.grpc.port}"
 
+    @property
+    def _grpc_web_path_prefix(self) -> str:
+        """Return the normalized grpc-web base-path prefix; "" means native gRPC.
+
+        A configured prefix is returned with a single leading slash and no trailing
+        slash (e.g. "grpc-web/" -> "/grpc-web"); empty/None -> "" (native gRPC).
+        """
+        cleaned = (self.grpc_path_prefix or "").strip("/")
+        return f"/{cleaned}" if cleaned else ""
+
     def _grpc_channel(
         self,
         proxies: Dict[str, str],
@@ -134,6 +160,12 @@ 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.
+        if (prefix := self._grpc_web_path_prefix) != "":
+            options.append(("grpc-web.path_prefix", prefix))
+
         if is_async:
             mod = grpc.aio
         else:

weaviate/connect/helpers.py

@@ -290,6 +290,7 @@ def connect_to_custom(
     additional_config: Optional[AdditionalConfig] = None,
     auth_credentials: Optional[AuthCredentials] = None,
     skip_init_checks: bool = False,
+    grpc_path_prefix: Optional[str] = None,
 ) -> WeaviateClient:
     """Connect to a Weaviate instance with custom connection parameters.
 
@@ -312,6 +313,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).
 
     Returns:
         The client connected to the instance with the required parameters set appropriately.
@@ -353,6 +359,7 @@ def connect_to_custom(
                 grpc_host=grpc_host,
                 grpc_port=grpc_port,
                 grpc_secure=grpc_secure,
+                grpc_path_prefix=grpc_path_prefix,
             ),
             auth_client_secret=__parse_auth_credentials(auth_credentials),
             additional_headers=headers,
@@ -587,6 +594,7 @@ def use_async_with_custom(
     additional_config: Optional[AdditionalConfig] = None,
     auth_credentials: Optional[AuthCredentials] = None,
     skip_init_checks: bool = False,
+    grpc_path_prefix: Optional[str] = None,
 ) -> WeaviateAsyncClient:
     """Create an async client object ready to connect to a Weaviate instance with custom connection parameters.
 
@@ -609,6 +617,11 @@ def use_async_with_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).
 
     Returns:
         The client connected to the instance with the required parameters set appropriately.
@@ -652,6 +665,7 @@ def use_async_with_custom(
             grpc_host=grpc_host,
             grpc_port=grpc_port,
             grpc_secure=grpc_secure,
+            grpc_path_prefix=grpc_path_prefix,
         ),
         auth_client_secret=__parse_auth_credentials(auth_credentials),
         additional_headers=headers,