vgi-python 0.31.1__tar.gz → 0.31.3__tar.gz

vgi_python-0.31.3/.dockerignore

@@ -0,0 +1,15 @@
+.git
+.venv
+.mypy_cache
+.pytest_cache
+.ruff_cache
+site
+__pycache__
+*.pyc
+.tailnet/vgi-rpc/.git
+.env
+.env.*
+*.key
+*.pem
+*.p12
+*.pfx

vgi_python-0.31.3/.github/workflows/tailnet-integration.yml

@@ -0,0 +1,49 @@
+name: Real Tailnet authentication
+
+on:
+  workflow_dispatch:
+    inputs:
+      tailscale_channel:
+        description: Official Tailscale container channel
+        required: true
+        default: stable
+        type: choice
+        options: [stable, unstable]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: vgi-python-real-tailnet
+  cancel-in-progress: false
+
+jobs:
+  tailnet:
+    name: high-level worker / ${{ inputs.tailscale_channel }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    environment: tailnet-integration
+    env:
+      TAILSCALE_IMAGE: tailscale/tailscale:${{ inputs.tailscale_channel }}
+      TS_OAUTH_CLIENT_ID: ${{ secrets.TS_OAUTH_CLIENT_ID }}
+      TS_OAUTH_SECRET: ${{ secrets.TS_OAUTH_SECRET }}
+      TAILNET_ISSUER: ${{ vars.TAILNET_ISSUER }}
+      TAILNET_EXPECTED_CAPABILITY: ${{ vars.TAILNET_EXPECTED_CAPABILITY }}
+      TAILNET_EXPECTED_CLIENT_TAG: ${{ vars.TAILNET_EXPECTED_CLIENT_TAG }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Checkout unreleased vgi-rpc identity layer
+        uses: actions/checkout@v7
+        with:
+          repository: Query-farm/vgi-rpc-python
+          path: .tailnet/vgi-rpc
+          ref: 04f19147625b4f643b38a687151d8233daa8997c
+
+      - name: Check kernel networking support
+        run: |
+          test -c /dev/net/tun
+          docker compose version
+
+      - name: Run high-level Tailnet authentication matrix
+        run: tests/tailnet/run.sh

{vgi_python-0.31.1 → vgi_python-0.31.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.31.1
+Version: 0.31.3
 Summary: Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow
 Project-URL: Homepage, https://query.farm
 Project-URL: Repository, https://github.com/Query-farm/vgi-python
@@ -162,7 +162,7 @@ Requires-Dist: httpx2>=2.9.1
 Requires-Dist: platformdirs
 Requires-Dist: pyarrow
 Requires-Dist: typer>=0.9
-Requires-Dist: vgi-rpc>=0.44.1
+Requires-Dist: vgi-rpc>=0.45.1
 Provides-Extra: azure
 Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
 Requires-Dist: pymssql>=2.3.0; extra == 'azure'
@@ -198,6 +198,8 @@ Provides-Extra: haybarn
 Requires-Dist: haybarn>=1.5.5rc1; extra == 'haybarn'
 Provides-Extra: http
 Requires-Dist: vgi-rpc[http]; extra == 'http'
+Provides-Extra: iroh
+Requires-Dist: vgi-rpc[http,iroh]; extra == 'iroh'
 Provides-Extra: launch
 Requires-Dist: vgi-rpc[cli]; extra == 'launch'
 Provides-Extra: oauth

{vgi_python-0.31.1 → vgi_python-0.31.3}/ci/run-integration.sh

@@ -86,6 +86,10 @@ if [ "$TRANSPORT" = "http" ]; then
   #   * buffer_input/sizes.test — input buffering semantics differ over HTTP
   #     (same known limitation). (scale.test_slow is a .test_slow file and is
   #     never staged below, which only finds *.test.)
+  #   * database_worker/package.test — the packaged fixture is deliberately an
+  #     executable wrapper around VGI_TEST_WORKER. An HTTP URL is not an
+  #     executable artifact; the direct-exec lifecycle is covered by all three
+  #     process/socket lanes.
   # cache/revalidate.test now runs on http too: HTTP conditional revalidation is
   # implemented (C++ /init-request validators + vgi-rpc >=0.24.0 surfacing them to
   # the producer's first process()). It needs a community vgi extension carrying
@@ -96,6 +100,7 @@ if [ "$TRANSPORT" = "http" ]; then
     -not -name 'dynamic_filter.test'
     -not -name 'partitioned_sequence.test'
     -not -path './table_in_out/buffer_input/sizes.test'
+    -not -path './database_worker/package.test'
   )
 fi
 
@@ -120,6 +125,16 @@ mkdir -p "$STAGE/test/sql/integration"
     awk -v http="$AWK_HTTP" -f "$HERE/preprocess-require.awk" "$f" > "$STAGE/test/sql/integration/$f"
   done )
 
+# Some integration cases package an executable from the upstream support tree.
+# The staged suite runs with ``$STAGE`` as its working directory, so preserve
+# the relative path used by those SQL fixtures instead of making it depend on
+# the checkout layout outside the stage.
+if [ -f "$VGI_SRC/test/support/database_worker_fixture.sh" ]; then
+  mkdir -p "$STAGE/test/support"
+  cp "$VGI_SRC/test/support/database_worker_fixture.sh" "$STAGE/test/support/"
+  chmod +x "$STAGE/test/support/database_worker_fixture.sh"
+fi
+
 # Empty VGI_RPC_SHM_SIZE_BYTES must not reach the C++ client (it would try to
 # attach a zero-size segment); only a real value enables the shm side channel.
 [ -n "${VGI_RPC_SHM_SIZE_BYTES:-}" ] || unset VGI_RPC_SHM_SIZE_BYTES

{vgi_python-0.31.1 → vgi_python-0.31.3}/docs/how-to/http-auth.md

@@ -35,6 +35,25 @@ with Client(transport="http", base_url="http://localhost:8080", bearer_token="to
     ...  # same .scalar_function() / .table_function() calls as the subprocess transport
 ```
 
+The native client advertises a 256 MiB decoded-response limit on every RPC,
+including the short-lived connections used for catalog operations. Override it
+when the application has a smaller memory budget:
+
+```python
+with Client.from_http(
+    "http://localhost:8080",
+    accepted_max_response_bytes=32 * 1024 * 1024,
+) as client:
+    ...
+```
+
+The value must be an integer from 65536 through `2^53 - 1`. Configured clients
+discover server support before the first RPC and fail closed if it is absent.
+Passing `None` omits negotiation for compatibility with a legacy unbounded server;
+doing so is not recommended for externally reachable workers. Capability
+discovery reports the server's own effective response cap and whether it
+honors the client limit.
+
 ## Add authentication
 
 The quickest setup is static bearer tokens via an environment variable — comma-separated

vgi_python-0.31.3/docs/how-to/iroh.md

@@ -0,0 +1,91 @@
+# Serve and call a worker over Iroh
+
+VGI supports two authenticated Iroh endpoint forms:
+
+- `iroh://<endpoint-id>` keeps stream state on one connection.
+- `httpi://<endpoint-id>[/prefix]` preserves VGI's stateless HTTP exchanges,
+  continuation tokens, request/response budgets, authentication headers, and
+  externalized batches.
+
+Install the optional native client binding:
+
+```console
+pip install 'vgi-python[iroh]'
+```
+
+## Start a raw upstream
+
+The language-neutral `vgi-iroh-bridge` owns the public Iroh endpoint. The
+Python process binds only loopback and requires the bridge's PROXY-v2 identity
+preamble:
+
+```console
+vgi-serve my_worker.py \
+  --iroh-raw-upstream 127.0.0.1:9400 \
+  --iroh-issuer production
+```
+
+In another process:
+
+```console
+vgi-iroh-bridge \
+  --secret-key-file /run/secrets/vgi-iroh-key \
+  --raw-upstream tcp://127.0.0.1:9400
+```
+
+The bridge prints its EndpointId as the first stdout line. Development may use
+`--ephemeral`; a production endpoint must use a persistent secret key.
+The raw Iroh listener also enables standard RPC method description so
+standalone clients in other VGI languages can bootstrap directly.
+
+## Start an HTTP upstream
+
+HTTP-over-Iroh is the preferred mode for horizontally scaled workers:
+
+```console
+vgi-serve my_worker.py \
+  --http --host 127.0.0.1 --port 9401 \
+  --iroh-issuer production
+
+vgi-iroh-bridge \
+  --secret-key-file /run/secrets/vgi-iroh-key \
+  --http-upstream http://127.0.0.1:9401
+```
+
+`--iroh-issuer` makes the worker trust exactly `127.0.0.1` by default and
+promotes the bridge-verified EndpointId to `CallContext.auth`. Use repeated
+`--iroh-trusted-proxy <exact-ip>` when the immediate bridge address differs.
+Use `--iroh-observe` to expose evidence without authenticating from it.
+
+Never expose the bridge-facing listener as a general public HTTP or TCP
+listener. If another proxy sits between the bridge and worker, isolate that
+route, clear client-supplied `VGI-Forwarded-Iroh-Endpoint` fields on every other
+route, and configure the worker to trust only the intermediary's exact address.
+
+## Connect
+
+The same high-level client accepts both endpoint schemes:
+
+```python test="skip"
+from vgi.client import Client
+
+with Client.from_iroh("iroh://<endpoint-id>") as client:
+    print(client.catalogs())
+
+with Client.from_iroh("httpi://<endpoint-id>/vgi") as client:
+    print(client.catalogs())
+```
+
+For a private relay:
+
+```python test="skip"
+client = Client.from_iroh(
+    "httpi://<endpoint-id>/vgi",
+    relay_urls=["https://relay.example.com"],
+    remote_relay_url="https://relay.example.com",
+)
+```
+
+The local relay set and the remote relay hint are distinct. `no_relay=True`
+disables relays and requires a working direct path; it never falls back to the
+public relay network.

vgi_python-0.31.3/docs/how-to/tailnet.md

@@ -0,0 +1,195 @@
+---
+description: "How to connect the Python VGI client to workers through Tailscale over HTTPS, direct TCP, or userspace SOCKS5h."
+---
+
+# Run VGI through a Tailnet
+
+The VGI client uses ordinary HTTPS and TCP endpoints. It does not join a
+Tailnet, manage Tailscale credentials, or introduce a `tailscale://` URL
+scheme. Run Tailscale on the client host or in a sidecar and pass the worker's
+MagicDNS name to the normal client factory.
+
+Connectivity and authentication are separate. A client can reach a worker
+through a Tailnet without the worker using Tailnet identity. To authorize from
+the caller's verified Tailscale user, node, tags, or application capabilities,
+configure a peer-identity provider and an authentication policy on the worker.
+
+## Authenticate an HTTP worker
+
+When Tailscale Serve terminates HTTPS, trust its identity headers only from the
+exact local proxy addresses that can reach the application. `require_peer_identity`
+requires verified evidence but deliberately does not invent a stable principal
+for capability-only or login-scoped Serve requests:
+
+```python test="lint"
+from vgi_rpc.http import tailscale_serve_header_provider
+from vgi_rpc.rpc import require_peer_identity
+
+from my_worker import MyWorker
+from vgi.serve import create_app
+
+tailscale = tailscale_serve_header_provider(
+    issuer="tailnet:example",
+    trusted_proxy_addresses=("127.0.0.1", "::1"),
+)
+
+app = create_app(
+    MyWorker,
+    peer_identity_providers=(tailscale,),
+    peer_authentication_policy=require_peer_identity("tailscale"),
+)
+```
+
+Serve login names have `subject_stability="login"`; tagged clients may be
+capability-only and have no subject at all. Consequently, the built-in
+`peer_identity_primary("tailscale")` policy is intentionally unsuitable for
+Serve. If a deployment elects to authenticate from a Serve login, it must use
+an explicit application policy that accepts that weaker identity and scopes it
+to the configured issuer and trusted proxy boundary.
+
+For direct HTTP over a Tailnet, LocalAPI WhoIs can produce a stable user or
+node subject and therefore can be the primary authenticator:
+
+```python test="lint"
+from vgi_rpc.http import tailscale_localapi_provider
+from vgi_rpc.rpc import peer_identity_primary
+
+from my_worker import MyWorker
+from vgi.serve import create_app
+
+tailscale = tailscale_localapi_provider(issuer="tailnet:example")
+app = create_app(
+    MyWorker,
+    peer_identity_providers=(tailscale,),
+    peer_authentication_policy=peer_identity_primary("tailscale"),
+)
+```
+
+`create_app()` remains a standard WSGI application, so the same configuration
+works behind Waitress, Granian, gunicorn, Envoy, nginx, or a cloud HTTP load
+balancer. The provider determines which proxy evidence is trusted; merely
+placing the worker behind a proxy never makes forwarded identity trustworthy.
+
+Trusted-proxy validation must see the physical socket peer. Do not install
+`ProxyFix`, forwarded-address middleware, or an equivalent rewrite ahead of
+VGI's identity middleware: attacker-controlled `Forwarded` or
+`X-Forwarded-For` values must never become `REMOTE_ADDR` before the exact proxy
+allowlist is checked. Keep the backend unreachable except through those
+allowlisted proxies.
+
+## HTTPS through Tailscale Serve
+
+On a host using Tailscale's normal network interface, connect to a worker
+published with Tailscale Serve exactly like any other HTTPS worker:
+
+```python test="lint"
+from vgi.client import Client
+
+with Client.from_http("https://worker.example-tailnet.ts.net") as client:
+    catalogs = client.catalogs()
+```
+
+Tailscale terminates HTTPS and adds its verified Serve identity and application
+capability headers. The VGI server validates those headers against its trusted
+proxy configuration; the client neither constructs nor trusts identity
+headers. Do not send `Tailscale-*` headers from application code.
+
+For userspace networking, inject an HTTP client configured for Tailscale's
+SOCKS5 server. Install SOCKS support with `pip install 'httpx2[socks]'`:
+
+```python test="lint"
+import httpx2
+
+from vgi.client import Client
+
+url = "https://worker.example-tailnet.ts.net"
+with httpx2.Client(
+    base_url=url,
+    proxy="socks5h://127.0.0.1:1055",
+    trust_env=False,
+    timeout=httpx2.Timeout(60.0, connect=15.0),
+) as http_client, Client.from_http(url, httpx_client=http_client) as client:
+    catalogs = client.catalogs()
+```
+
+Using `socks5h` keeps MagicDNS resolution inside the Tailscale sidecar. A proxy
+failure is an error; this configuration does not fall back to a direct route.
+
+## Raw TCP through a Tailnet
+
+Start a high-level Worker with LocalAPI identity using `Worker.serve_tcp()`:
+
+```python test="lint"
+from vgi_rpc.http import tailscale_localapi_provider
+from vgi_rpc.rpc import peer_identity_primary
+
+from my_worker import MyWorker
+
+tailscale = tailscale_localapi_provider(issuer="tailnet:example")
+MyWorker().serve_tcp(
+    "0.0.0.0",
+    9400,
+    threaded=True,
+    max_connections=64,
+    peer_identity_providers=(tailscale,),
+    peer_authentication_policy=peer_identity_primary("tailscale"),
+)
+```
+
+The connection's verified stable Tailnet subject becomes `CallContext.auth` and
+is available to function parameters annotated with `Auth()`. Identity is
+snapshotted once for the stateful TCP connection.
+
+When `threaded=True`, all connections share the same Worker instance. Protect
+mutable subclass state with appropriate synchronization and never store
+per-caller authentication in shared instance attributes. Leave the default
+serial mode in place if the implementation is not safe for concurrent calls.
+
+Behind a Tailscale Service configured to emit PROXY protocol v2, require the
+preamble and name every immediate proxy address explicitly:
+
+```python test="lint"
+MyWorker().serve_tcp(
+    "127.0.0.1",
+    9400,
+    proxy_protocol="required",
+    trusted_proxy_addresses=("127.0.0.1", "::1"),
+    service_name="svc:vgi-worker",
+    peer_identity_providers=(tailscale,),
+    peer_authentication_policy=peer_identity_primary("tailscale"),
+)
+```
+
+Keep that backend unreachable except through the trusted proxy. The asserted
+source is accepted only after immediate-peer validation, and `service_name`
+selects destination-scoped application capabilities in LocalAPI WhoIs.
+
+Direct TCP works with a MagicDNS name when the client host has Tailscale's
+normal network interface:
+
+```python test="lint"
+from vgi.client import Client
+
+with Client.from_tcp("worker.example-tailnet.ts.net", 9400) as client:
+    catalogs = client.catalogs()
+```
+
+For a userspace Tailscale sidecar, use the explicit SOCKS5h option:
+
+```python test="lint"
+with Client.from_tcp(
+    "worker.example-tailnet.ts.net",
+    9400,
+    proxy="socks5h://127.0.0.1:1055",
+) as client:
+    catalogs = client.catalogs()
+```
+
+The proxy applies to ordinary function calls, additional worker connections,
+and catalog discovery. Target hostnames are passed untouched to SOCKS5h and
+are never resolved locally by VGI.
+
+Raw VGI TCP has no application-layer encryption. Tailscale encrypts the
+Tailnet path, but the worker port should remain reachable only through the
+Tailnet and should not be exposed directly to an untrusted network. Prefer
+HTTPS through Tailscale Serve at public or mixed-trust boundaries.

{vgi_python-0.31.1 → vgi_python-0.31.3}/mkdocs.yml

@@ -125,6 +125,8 @@ nav:
     - Expose a catalog: how-to/catalogs.md
     - Persist state across workers: how-to/state-storage.md
     - Serve over HTTP with auth: how-to/http-auth.md
+    - Connect through a Tailnet: how-to/tailnet.md
+    - Serve and connect over Iroh: how-to/iroh.md
     - Integrate with the optimizer: how-to/pushdown-and-statistics.md
     - Function Metadata: metadata.md
     - CLI: cli.md

{vgi_python-0.31.1 → vgi_python-0.31.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.31.1"
+version = "0.31.3"
 description = "Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow"
 readme = "README.md"
 keywords = [
@@ -40,7 +40,7 @@ dependencies = [
     "pyarrow",
     "typer>=0.9",
     "platformdirs",
-    "vgi-rpc>=0.44.1",
+    "vgi-rpc>=0.45.1",
     "httpx2>=2.9.1",
 ]
 
@@ -52,6 +52,7 @@ dependencies = [
 haybarn = ["haybarn>=1.5.5rc1"]
 duckdb = ["duckdb>=1.5.3"]
 http = ["vgi-rpc[http]"]
+iroh = ["vgi-rpc[http,iroh]"]
 # transport="launch": vgi_rpc.launcher imports filelock unconditionally at
 # module level, which lives behind vgi-rpc's own `cli` extra (alongside
 # typer, already a core dependency here, and httpx2, ditto) rather than in

{vgi_python-0.31.1 → vgi_python-0.31.3}/tests/catalog/test_example_worker_catalog.py

@@ -13,6 +13,7 @@ from vgi.catalog import (
     AttachOpaqueData,
     FunctionInfo,
     FunctionType,
+    IndexInfo,
     MacroInfo,
     MacroType,
     SchemaObjectType,
@@ -394,6 +395,37 @@ class TestExampleWorkerViews:
         assert view.comment is not None
 
 
+class TestExampleWorkerIndexes:
+    """Test ExampleWorker's index catalog entries."""
+
+    def test_schema_contents_returns_indexes_in_data(self) -> None:
+        """`data` has 2 real indexes on `numbers`.
+
+        Regression: `type=SchemaObjectType.INDEX` used to silently fall
+        through to the functions RPC (`catalog_schema_contents_functions`)
+        instead of the real `catalog_schema_contents_indexes` one.
+        """
+        client = Client(EXAMPLE_WORKER)
+        attach_result = client.catalog_attach(
+            name="example", options={}, data_version_spec=None, implementation_version=None
+        )
+
+        indexes = list(
+            client.schema_contents(
+                attach_opaque_data=attach_result.attach_opaque_data,
+                name="data",
+                type=SchemaObjectType.INDEX,
+            )
+        )
+
+        index_names = {i.name for i in indexes}
+        assert index_names == {"idx_numbers_value", "idx_numbers_value_unique"}
+        for index in indexes:
+            assert isinstance(index, IndexInfo)
+            assert index.table_name == "numbers"
+            assert index.expressions == ["value"]
+
+
 class TestExampleWorkerMacros:
     """Test ExampleWorker's macro catalog entries."""
 

vgi_python-0.31.3/tests/client/test_bind_and_join_keys.py

@@ -0,0 +1,134 @@
+# Copyright 2026 Query Farm LLC - https://query.farm
+
+# ruff: noqa: S101, D101, D102, D103
+"""`Client.bind()` and `Client.table_function(join_keys=...)`.
+
+Both were previously unreachable from `Client`:
+
+- Schema discovery for a bare (non-catalog) function name had no
+  standalone entry point — only `table_function(bind_result_callback=...)`,
+  which only fires as a side effect of a generator's first `next()`, by
+  which point `init()`/real execution has already started. `bind()` runs
+  only the `bind()` RPC.
+- `join_keys` (semi-join pushdown) has been carried on `InitRequest`/
+  `TableFunctionPlanRequest` and threaded through worker-side
+  `deserialize_filters(..., join_keys=...)` all along
+  (`vgi/table_filter_pushdown.py`), but `Client`'s public methods never
+  exposed a way to set it on the request.
+
+Exercised against `filter_echo` (`vgi/_test_fixtures/table/filters.py`),
+which auto-applies whatever filters it receives and echoes them back as
+SQL-like text in its `pushed_filters` column — the same fixture the
+`vgi_acero` filter-pushdown spike used, since it proves pushdown is real
+(server-side applied), not just correct final rows.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, cast
+
+import pyarrow as pa
+import pytest
+
+from vgi.arguments import Arguments
+
+MAIN = "main"
+
+
+@pytest.fixture
+def client(client_transport: Any) -> Any:
+    with client_transport() as c:
+        yield c
+
+
+def _join_keys_pushdown_filters_bytes(column_name: str, keys_column: str) -> bytes:
+    """Build `pushdown_filters` IPC bytes containing one `join_keys` filter spec.
+
+    Unlike `constant`/`in` specs, a `join_keys` spec carries no `value_ref` —
+    the actual key values travel separately as `Client.table_function`'s own
+    `join_keys=` argument, resolved worker-side by matching `keys_column`
+    against each join-key batch's column name (see
+    `PushdownFilters.get_join_keys_column`).
+    """
+    spec = {"column_name": column_name, "column_index": 0, "type": "join_keys", "keys_column": keys_column}
+    spec_field = pa.field("filter_spec", pa.string(), metadata={b"vgi_filter_version": b"1"})
+    batch = pa.record_batch({"filter_spec": [json.dumps([spec])]}, schema=pa.schema([spec_field]))
+
+    sink = pa.BufferOutputStream()
+    writer = pa.ipc.new_stream(sink, batch.schema)
+    writer.write_batch(batch)
+    writer.close()
+    return sink.getvalue().to_pybytes()
+
+
+class TestBind:
+    def test_bind_returns_the_bound_schema(self, client: Any) -> None:
+        resp = client.bind(
+            function_name="filter_echo",
+            schema_name=MAIN,
+            arguments=Arguments(positional=(pa.scalar(10),)),
+        )
+        assert resp.output_schema.names == ["n", "s", "pushed_filters"]
+
+    def test_bind_does_not_corrupt_the_connection_for_later_calls(self, client: Any) -> None:
+        """A `bind()` call must leave the connection usable for a real scan afterward.
+
+        This is the regression the old workaround (peek one batch via
+        `bind_result_callback` then `gen.close()`) could not satisfy — closing
+        a generator early desyncs the subprocess's lockstep RPC pipe for the
+        rest of that `Client`'s life. `bind()` never opens a stream at all.
+        """
+        client.bind(
+            function_name="filter_echo",
+            schema_name=MAIN,
+            arguments=Arguments(positional=(pa.scalar(10),)),
+        )
+        batches = list(
+            client.table_function(
+                function_name="filter_echo",
+                schema_name=MAIN,
+                arguments=Arguments(positional=(pa.scalar(5),)),
+            )
+        )
+        table = pa.Table.from_batches(batches)
+        assert table.num_rows == 5
+        assert sorted(cast("list[int]", table.column("n").to_pylist())) == [0, 1, 2, 3, 4]
+
+
+class TestJoinKeys:
+    def test_join_keys_filters_rows_server_side(self, client: Any) -> None:
+        pushdown_filters = _join_keys_pushdown_filters_bytes(column_name="n", keys_column="n")
+        join_keys = [pa.record_batch({"n": pa.array([3, 7], type=pa.int64())})]
+
+        batches = list(
+            client.table_function(
+                function_name="filter_echo",
+                schema_name=MAIN,
+                arguments=Arguments(positional=(pa.scalar(10),)),
+                pushdown_filters=pushdown_filters,
+                join_keys=join_keys,
+            )
+        )
+        table = pa.Table.from_batches(batches)
+
+        assert sorted(cast("list[int]", table.column("n").to_pylist())) == [3, 7]
+        # auto_apply_filters=True means the worker itself filtered — the
+        # echoed pushed_filters text is the proof it's a real server-side
+        # InFilter, not us post-filtering client-side.
+        for value in cast("list[str]", table.column("pushed_filters").to_pylist()):
+            assert "n IN" in value
+            assert "3" in value and "7" in value
+
+    def test_no_join_keys_returns_everything(self, client: Any) -> None:
+        """Sanity check: omitting join_keys behaves exactly like today (no filter)."""
+        batches = list(
+            client.table_function(
+                function_name="filter_echo",
+                schema_name=MAIN,
+                arguments=Arguments(positional=(pa.scalar(5),)),
+            )
+        )
+        table = pa.Table.from_batches(batches)
+        assert table.num_rows == 5
+        assert all(v == "(none)" for v in table.column("pushed_filters").to_pylist())