vgi-python 0.24.0__tar.gz → 0.25.0__tar.gz

{vgi_python-0.24.0 → vgi_python-0.25.0}/.github/workflows/ci.yml

@@ -83,8 +83,8 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v8.2.0
 
-      - name: Set up Python 3.13
-        run: uv python install 3.13
+      - name: Set up Python 3.14
+        run: uv python install 3.14
 
       - name: Install dependencies
         run: uv sync --all-extras --group docs
@@ -141,8 +141,8 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v8.2.0
 
-      - name: Set up Python 3.13
-        run: uv python install 3.13
+      - name: Set up Python 3.14
+        run: uv python install 3.14
 
       - name: Install test dependencies
         run: |
@@ -150,7 +150,7 @@ jobs:
           # local vgi-rpc checkout with the s3/external extras plus boto3.
           # Subsequent uv run calls must pass --no-sync or uv re-syncs the
           # env to the lockfile and drops the overlay.
-          uv sync --all-extras --python 3.13
+          uv sync --all-extras --python 3.14
           uv pip install './vgi-rpc[http,s3,external]' boto3
 
       - name: Create test bucket in LocalStack

{vgi_python-0.24.0 → vgi_python-0.25.0}/.github/workflows/docs.yml

@@ -21,7 +21,7 @@ jobs:
         uses: astral-sh/setup-uv@v8.2.0
 
       - name: Set up Python
-        run: uv python install 3.13
+        run: uv python install 3.14
 
       - name: Install dependencies
         run: uv sync --group docs

{vgi_python-0.24.0 → vgi_python-0.25.0}/.github/workflows/integration.yml

@@ -78,11 +78,11 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v8.2.0
 
-      - name: Set up Python 3.13
-        run: uv python install 3.13
+      - name: Set up Python 3.14
+        run: uv python install 3.14
 
       - name: Install dependencies (vgi + fixtures + all extras)
-        run: uv sync --all-extras --python 3.13
+        run: uv sync --all-extras --python 3.14
 
       - name: Download haybarn-unittest
         run: |

{vgi_python-0.24.0 → vgi_python-0.25.0}/CLAUDE.md

@@ -297,6 +297,11 @@ vgi-client --input data.parquet --function sum_all_columns --worker vgi-fixture-
 | `VGI_OAUTH_DEVICE_CODE_CLIENT_ID` | Client ID for device-code flow (optional, URL-safe chars only) |
 | `VGI_OAUTH_DEVICE_CODE_CLIENT_SECRET` | Client secret for device-code flow (optional, URL-safe chars only) |
 | `VGI_OAUTH_USE_ID_TOKEN` | When `1`/`true`/`yes`, clients use OIDC `id_token` as Bearer instead of `access_token` |
+| `VGI_INTROSPECT_PRINCIPALS` | Comma-separated principals permitted to call `__introspect_token__`. Required — no permissive default — whenever the worker implements `resolve_token()` (see below) |
+| `VGI_INTROSPECT_RATE_LIMIT` | Introspection requests allowed per caller per second (default 20) |
+| `VGI_WORKER_ACCESS_LOG_SAMPLE` | Fraction of *successful* calls to keep in the access log, `0.0`–`1.0`. Errors are always kept; the decision is per call, so every record of one stream shares a fate |
+| `VGI_WORKER_ACCESS_LOG_ASYNC` | When `1`/`true`/`yes`, emit access-log records from a listener thread. Bounded queue; full means drop, and a crash loses whatever is queued |
+| `VGI_WORKER_ACCESS_LOG_QUEUE_SIZE` | Bound on the async access-log queue (default 10000) |
 | `VGI_OTEL_ENABLED` | Enable OpenTelemetry instrumentation (`1`/`true`/`yes`) |
 | `VGI_OTEL_CUSTOM_ATTRIBUTES` | Comma-separated `key=value` pairs for custom span/metric attributes |
 | `VGI_OTEL_CLAIM_ATTRIBUTES` | Comma-separated `claim_key=span_attr_name` pairs for claim extraction |
@@ -392,6 +397,96 @@ Set `SENTRY_DSN` (and install `vgi[sentry]`) to forward unhandled exceptions to
 
 The same enrichment applies to OTel spans when `VGI_OTEL_ENABLED=1` — both backends read from the same `VgiTracer.set_current_span_attributes()` call sites in `vgi/otel.py`. Either, neither, or both can be active in a process.
 
+### Serving Behind a Load Balancer
+
+`--max-externalized-response-bytes` caps a single *externalized* response — the
+payload uploaded to blob storage and replaced on the wire by a pointer. Set it
+to whatever the load balancer, API gateway, or object-store policy in front of
+the worker will actually carry.
+
+```bash
+vgi-serve my.worker:MyWorker --http --max-externalized-response-bytes 67108864
+```
+
+Unlike `--max-stream-response-bytes`, which governs the wire and is *soft* for
+producer streams (a continuation token carries the overshoot to the next turn),
+this cap is **hard on every method type with no continuation escape** — bytes
+already uploaded cannot be un-uploaded. Default is no cap. When set, the value
+is advertised as `VGI-Max-Externalized-Response-Bytes` so clients can size their
+own expectations.
+
+Also available on `Worker.main --http` and the fixture server. Under
+`--server granian` it travels to worker processes through `export_serve_config`.
+
+### Token Introspection (`resolve_token`)
+
+A worker may optionally expose `POST {prefix}/__introspect_token__`, which
+resolves an opaque bearer credential to a principal — for a reverse proxy that
+terminates the only public listener and must know the caller's identity before
+it can authorize anything.
+
+```python
+from vgi.auth import AuthUnavailableError, TokenIdentity
+from vgi.worker import Worker
+
+class MyWorker(Worker):
+    functions = [...]
+
+    @classmethod
+    def resolve_token(cls, token: str) -> TokenIdentity | None:
+        try:
+            row = api_keys.lookup(token)          # your own store
+        except ConnectionError as exc:
+            # "I could not find out" — 503 + Retry-After, not 401.
+            raise AuthUnavailableError(str(exc)) from exc
+        if row is None:
+            return None                           # "the credential is unknown"
+        return TokenIdentity(principal=row.principal, token_name=row.label)
+```
+
+**The route does not exist until `resolve_token` is overridden** — absent, not
+routed-and-refusing. That is what keeps a dependency upgrade from growing a
+credential-to-identity oracle on every existing worker.
+
+Enabling it also requires an allowlist of principals permitted to ask, via
+`--introspect-principals` or `VGI_INTROSPECT_PRINCIPALS`. There is no permissive
+default and a worker that overrides the hook without one **refuses to start**:
+authenticating and introspecting are different capabilities, and "any
+authenticated caller" lets any user resolve any other user's credential to its
+owner. `--introspect-rate-limit` (default 20/caller/second) bounds, rather than
+closes, the oracle an allowlisted-but-compromised caller still has.
+
+Return `None` for "the store answered and this credential is unknown"; raise
+`AuthUnavailableError` for "the answer is not knowable". A caller that
+negative-caches the first must not cache the second. Never return claims — a
+pass-through claims field would let a worker choose its caller's tenant routing
+and policy branch.
+
+`AuthUnavailableError` is worth reaching for in any custom `authenticate`
+callback too, not just here: it is deliberately **not** a `ValueError`, because
+`chain_authenticate` advances to the next authenticator on `ValueError` — so a
+sidecar outage raised as one is read as "not my credential, try the next" and
+ends up a 401 from the end of the chain, restarting every session in the fleet
+over a thirty-second blip.
+
+### Access Log Sampling and Async Emission
+
+`--access-log-sample 0.05` keeps 5% of *successful* calls. Errors are always
+kept, and the decision is made per call so every record belonging to one stream
+shares a fate. `--access-log-async` moves formatting and writing to a listener
+thread so disk latency stays off the request path; the queue is bounded
+(`--access-log-queue-size`, default 10000), full means drop, and the next record
+through carries `dropped_records` so a gap is never silent. A crash loses
+whatever is still queued — that is the trade.
+
+Both apply only to `vgi_rpc.access`, which gets its own handler for the purpose.
+They are deliberately not applied to the diagnostic loggers: dropping half of a
+traceback is not a saving.
+
+**Trace correlation needs no configuration.** vgi-rpc reads whatever span is
+current when it emits a record, so `trace_id` / `span_id` appear on every access
+record as soon as `VGI_OTEL_ENABLED=1`.
+
 ### Key Constraints for Scalar Functions:
 - **1:1 row mapping**: Output must have exactly the same number of rows as input
 - **Single column output**: Output schema has exactly one column named "result"

{vgi_python-0.24.0 → vgi_python-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vgi-python
-Version: 0.24.0
+Version: 0.25.0
 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: httpx>=0.24
 Requires-Dist: platformdirs
 Requires-Dist: pyarrow
 Requires-Dist: typer>=0.9
-Requires-Dist: vgi-rpc>=0.33.0
+Requires-Dist: vgi-rpc>=0.39.1
 Provides-Extra: azure
 Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
 Requires-Dist: pymssql>=2.3.0; extra == 'azure'

{vgi_python-0.24.0 → vgi_python-0.25.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.24.0"
+version = "0.25.0"
 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.33.0",
+    "vgi-rpc>=0.39.1",
     "httpx>=0.24",
 ]
 

{vgi_python-0.24.0 → vgi_python-0.25.0}/tests/test_serve.py

@@ -270,6 +270,203 @@ class TestCreateApp:
         assert isinstance(app, falcon.App)
 
 
+def _capability_headers(app: object) -> dict[str, str]:
+    """Read the capability headers a served app advertises on ``/health``.
+
+    Args:
+        app: The Falcon app under test.
+
+    Returns:
+        Response headers, lowercased.
+
+    """
+    import falcon.testing
+
+    resp = falcon.testing.TestClient(app).simulate_get("/vgi/health")
+    assert resp.status_code == 200
+    return {k.lower(): v for k, v in resp.headers.items()}
+
+
+class TestMaxExternalizedResponseBytes:
+    """The externalized-response cap, for workers behind a size-limited proxy."""
+
+    def test_advertised_when_set(self) -> None:
+        """The cap reaches the wire, so a client can size its own expectations."""
+        app = create_app(_SingleWorker, prefix="/vgi", describe=False, max_externalized_response_bytes=65536)
+        assert _capability_headers(app)["vgi-max-externalized-response-bytes"] == "65536"
+
+    def test_absent_by_default(self) -> None:
+        """No cap unless one is configured.
+
+        The header's absence is what tells a client there is no ceiling; a
+        default value here would be a ceiling nobody chose.
+        """
+        app = create_app(_SingleWorker, prefix="/vgi", describe=False)
+        assert "vgi-max-externalized-response-bytes" not in _capability_headers(app)
+
+
+class _IntrospectingWorker(Worker):
+    """Worker that implements the optional token-introspection hook."""
+
+    functions = [_DoubleFunc]
+
+    @classmethod
+    def resolve_token(cls, token: str) -> object | None:
+        from vgi.auth import TokenIdentity
+
+        if token == "good-token":
+            return TokenIdentity(principal="alice", token_name="deploy-key-1")
+        return None
+
+
+class TestIntrospectResolverDetection:
+    """``resolve_token`` presence is detected by override, not by a flag."""
+
+    def test_base_worker_has_no_resolver(self) -> None:
+        """A worker that never wrote the lookup gets no endpoint."""
+        assert _SingleWorker._introspect_resolver() is None
+
+    def test_override_is_detected(self) -> None:
+        """Implementing the hook is what enables it."""
+        resolver = _IntrospectingWorker._introspect_resolver()
+        assert resolver is not None
+        assert resolver("good-token") is not None
+        assert resolver("nope") is None
+
+
+class TestTokenIntrospection:
+    """``POST /__introspect_token__`` — absent unless a worker implements it."""
+
+    @staticmethod
+    def _client(worker_cls: type[Worker], **env: str) -> object:
+        import falcon.testing
+
+        from vgi.serve import _resolve_authenticate
+
+        with pytest.MonkeyPatch.context() as mp:
+            for key in ("VGI_INTROSPECT_PRINCIPALS", "VGI_INTROSPECT_RATE_LIMIT", "VGI_BEARER_TOKENS"):
+                mp.delenv(key, raising=False)
+            for key, value in env.items():
+                mp.setenv(key, value)
+            app = create_app(
+                worker_cls,
+                prefix="/vgi",
+                describe=False,
+                authenticate=_resolve_authenticate(),
+            )
+        return falcon.testing.TestClient(app)
+
+    def test_route_absent_without_hook(self) -> None:
+        """Not "routed and refusing" — absent.
+
+        This is the property that keeps a dependency upgrade from silently
+        growing a credential-to-identity oracle on every existing worker.
+        """
+        client = self._client(_SingleWorker)
+        resp = client.simulate_post("/vgi/__introspect_token__", json={"token": "x"})  # type: ignore[attr-defined]
+        assert resp.status_code == 404
+
+    def test_capability_not_advertised_without_hook(self) -> None:
+        """A proxy preflighting at boot learns this worker cannot answer."""
+        app = create_app(_SingleWorker, prefix="/vgi", describe=False)
+        assert "vgi-token-introspection" not in _capability_headers(app)
+
+    def test_capability_advertised_with_hook(self) -> None:
+        """A proxy can discover support at boot rather than at first login."""
+        with pytest.MonkeyPatch.context() as mp:
+            mp.setenv("VGI_INTROSPECT_PRINCIPALS", "proxy-a")
+            app = create_app(_IntrospectingWorker, prefix="/vgi", describe=False)
+        assert _capability_headers(app)["vgi-token-introspection"] == "true"
+
+    def test_allowlisted_caller_resolves(self) -> None:
+        """The endpoint answers with a principal and never with claims."""
+        client = self._client(
+            _IntrospectingWorker,
+            VGI_INTROSPECT_PRINCIPALS="proxy-a",
+            VGI_BEARER_TOKENS="ptok=proxy-a",
+        )
+        resp = client.simulate_post(  # type: ignore[attr-defined]
+            "/vgi/__introspect_token__",
+            json={"token": "good-token"},
+            headers={"Authorization": "Bearer ptok"},
+        )
+        assert resp.status_code == 200
+        assert resp.json == {"principal": "alice", "token_name": "deploy-key-1", "ttl_seconds": 300}
+        assert "claims" not in resp.json
+
+    def test_unresolvable_token_is_404(self) -> None:
+        """Unknown credential and unknown route answer alike, on purpose."""
+        client = self._client(
+            _IntrospectingWorker,
+            VGI_INTROSPECT_PRINCIPALS="proxy-a",
+            VGI_BEARER_TOKENS="ptok=proxy-a",
+        )
+        resp = client.simulate_post(  # type: ignore[attr-defined]
+            "/vgi/__introspect_token__",
+            json={"token": "nope"},
+            headers={"Authorization": "Bearer ptok"},
+        )
+        assert resp.status_code == 404
+
+    def test_non_allowlisted_caller_refused(self) -> None:
+        """Authenticating is not the same capability as introspecting.
+
+        Without this, any user holding a valid credential could resolve any
+        other user's credential to its owner.
+        """
+        client = self._client(
+            _IntrospectingWorker,
+            VGI_INTROSPECT_PRINCIPALS="proxy-a",
+            VGI_BEARER_TOKENS="ptok=proxy-a,utok=user-b",
+        )
+        resp = client.simulate_post(  # type: ignore[attr-defined]
+            "/vgi/__introspect_token__",
+            json={"token": "good-token"},
+            headers={"Authorization": "Bearer utok"},
+        )
+        assert resp.status_code == 403
+
+    def test_hook_without_allowlist_refuses_to_start(self) -> None:
+        """Fail closed and loud, rather than defaulting to an open oracle."""
+        with pytest.MonkeyPatch.context() as mp:
+            mp.delenv("VGI_INTROSPECT_PRINCIPALS", raising=False)
+            with pytest.raises(SystemExit) as exc:
+                create_app(_IntrospectingWorker, prefix="/vgi", describe=False)
+        assert exc.value.code == 1
+
+    @pytest.mark.parametrize("bad", ["nonsense", "0", "-5"])
+    def test_bad_rate_limit_refuses_to_start(self, bad: str) -> None:
+        """A typo must not silently become "refuse everything" or "no bound"."""
+        with pytest.MonkeyPatch.context() as mp:
+            mp.setenv("VGI_INTROSPECT_PRINCIPALS", "proxy-a")
+            mp.setenv("VGI_INTROSPECT_RATE_LIMIT", bad)
+            with pytest.raises(SystemExit):
+                create_app(_IntrospectingWorker, prefix="/vgi", describe=False)
+
+
+class TestAuthUnavailableReExport:
+    """``AuthUnavailableError`` is reachable without naming a vgi_rpc module."""
+
+    def test_importable_from_vgi_auth(self) -> None:
+        """Worker authors reach it from ``vgi.auth`` like every other auth type."""
+        from vgi_rpc.http import AuthUnavailableError as Upstream
+
+        from vgi.auth import AuthUnavailableError
+
+        assert AuthUnavailableError is Upstream
+
+    def test_is_not_a_value_error(self) -> None:
+        """The whole point: ``chain_authenticate`` must not swallow it.
+
+        The chain advances to the next authenticator on ``ValueError``, so an
+        outage raised as one is read as "not my credential, try the next" and
+        ends up a 401 — restarting every session in the fleet over a blip.
+        """
+        from vgi.auth import AuthUnavailableError
+
+        assert not issubclass(AuthUnavailableError, ValueError)
+
+
 # ---------------------------------------------------------------------------
 # Tests: env var helpers
 # ---------------------------------------------------------------------------

vgi_python-0.25.0/tests/test_worker_cli.py

@@ -0,0 +1,200 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Tests for Worker.main() CLI logging options."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import pytest
+
+from vgi.logging_config import (
+    _KNOWN_LOGGERS,
+    ACCESS_LOGGER,
+    LogFormat,
+    LogLevel,
+    configure_worker_logging,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+# All known logger names from the registry
+_ALL_LOGGER_NAMES = [name for name, _, _ in _KNOWN_LOGGERS]
+
+
+@pytest.fixture(autouse=False)
+def _reset_loggers() -> Iterator[None]:
+    """Save and restore logger handlers, levels and propagation after each test.
+
+    ``propagate`` is restored too because the access-log options turn it off on
+    ``vgi_rpc.access``; leaving that set would silently suppress access records
+    for every later test in the session.
+    """
+    saved: dict[str, tuple[int, list[logging.Handler], bool]] = {}
+    for name in _ALL_LOGGER_NAMES:
+        logger = logging.getLogger(name)
+        saved[name] = (logger.level, list(logger.handlers), logger.propagate)
+    yield
+    for name in _ALL_LOGGER_NAMES:
+        logger = logging.getLogger(name)
+        level, handlers, propagate = saved[name]
+        logger.handlers[:] = handlers
+        logger.setLevel(level)
+        logger.propagate = propagate
+
+
+class TestConfigureWorkerLogging:
+    """Tests for configure_worker_logging() options."""
+
+    def test_debug_flag(self, _reset_loggers: None) -> None:
+        """``--debug`` sets vgi + vgi_rpc loggers to DEBUG."""
+        configure_worker_logging(debug=True)
+        for name in ("vgi", "vgi_rpc"):
+            logger = logging.getLogger(name)
+            assert logger.level == logging.DEBUG
+            assert len(logger.handlers) == 1
+
+    def test_log_level_option(self, _reset_loggers: None) -> None:
+        """``--log-level WARNING`` sets correct level."""
+        configure_worker_logging(log_level=LogLevel.WARNING)
+        for name in ("vgi", "vgi_rpc"):
+            logger = logging.getLogger(name)
+            assert logger.level == logging.WARNING
+
+    def test_log_logger_targeting(self, _reset_loggers: None) -> None:
+        """``--log-logger vgi.worker`` targets only that logger."""
+        configure_worker_logging(log_level=LogLevel.DEBUG, log_loggers=["vgi.worker"])
+        target = logging.getLogger("vgi.worker")
+        assert target.level == logging.DEBUG
+        assert len(target.handlers) == 1
+        # Root vgi logger should not have been modified
+        root = logging.getLogger("vgi")
+        assert root.handlers == [] or root.level != logging.DEBUG
+
+    def test_log_format_json(self, _reset_loggers: None) -> None:
+        """``--log-format json`` uses VgiJsonFormatter."""
+        from vgi_rpc.logging_utils import VgiJsonFormatter
+
+        configure_worker_logging(debug=True, log_format=LogFormat.json)
+        logger = logging.getLogger("vgi")
+        assert any(isinstance(h.formatter, VgiJsonFormatter) for h in logger.handlers)
+
+    def test_debug_overrides_log_level(self, _reset_loggers: None) -> None:
+        """``--debug --log-level INFO`` resolves to DEBUG."""
+        configure_worker_logging(debug=True, log_level=LogLevel.INFO)
+        logger = logging.getLogger("vgi")
+        assert logger.level == logging.DEBUG
+
+    def test_unknown_logger_warning(self, _reset_loggers: None, capsys: pytest.CaptureFixture[str]) -> None:
+        """Unrecognized logger name warns on stderr."""
+        configure_worker_logging(log_level=LogLevel.DEBUG, log_loggers=["not.a.real.logger"])
+        captured = capsys.readouterr()
+        assert "warning: unknown logger 'not.a.real.logger'" in captured.err
+
+    def test_configure_idempotent(self, _reset_loggers: None) -> None:
+        """Calling configure_worker_logging() twice doesn't duplicate handlers."""
+        configure_worker_logging(debug=True)
+        configure_worker_logging(debug=True)
+        logger = logging.getLogger("vgi")
+        assert len(logger.handlers) == 1
+
+    def test_returns_effective_level(self, _reset_loggers: None) -> None:
+        """Return value is the numeric log level."""
+        level = configure_worker_logging(log_level=LogLevel.WARNING)
+        assert level == logging.WARNING
+
+        level = configure_worker_logging(debug=True, log_level=LogLevel.WARNING)
+        assert level == logging.DEBUG
+
+    def test_text_format_has_timestamp(self, _reset_loggers: None) -> None:
+        """Text format includes asctime in the formatter."""
+        configure_worker_logging(log_format=LogFormat.text)
+        logger = logging.getLogger("vgi")
+        assert len(logger.handlers) == 1
+        fmt = logger.handlers[0].formatter
+        assert fmt is not None
+        assert fmt._fmt is not None
+        assert "asctime" in fmt._fmt
+
+
+class TestAccessLogOptions:
+    """Sampling and async emission for ``vgi_rpc.access``."""
+
+    def test_untouched_by_default(self, _reset_loggers: None) -> None:
+        """No options means no dedicated handler — records still propagate."""
+        configure_worker_logging(debug=True)
+        access = logging.getLogger(ACCESS_LOGGER)
+        assert access.handlers == []
+        assert access.propagate is True
+
+    def test_sampling_attaches_filter(self, _reset_loggers: None) -> None:
+        """A sample rate below 1.0 installs the sampler on the access logger."""
+        from vgi_rpc.logging_utils import AccessLogSampler
+
+        configure_worker_logging(debug=True, access_log_sample=0.25)
+        access = logging.getLogger(ACCESS_LOGGER)
+        assert len(access.handlers) == 1
+        assert any(isinstance(f, AccessLogSampler) for f in access.handlers[0].filters)
+
+    def test_sampling_does_not_touch_diagnostic_loggers(self, _reset_loggers: None) -> None:
+        """Dropping a fraction of tracebacks is not a saving.
+
+        The access logger gets its own handler precisely so the sampler cannot
+        reach ``vgi`` / ``vgi_rpc``, which share the stderr handler.
+        """
+        from vgi_rpc.logging_utils import AccessLogSampler
+
+        configure_worker_logging(debug=True, access_log_sample=0.25)
+        for name in ("vgi", "vgi_rpc"):
+            for handler in logging.getLogger(name).handlers:
+                assert not any(isinstance(f, AccessLogSampler) for f in handler.filters)
+
+    def test_sampling_stops_propagation(self, _reset_loggers: None) -> None:
+        """Otherwise every surviving record is written twice."""
+        configure_worker_logging(debug=True, access_log_sample=0.5)
+        assert logging.getLogger(ACCESS_LOGGER).propagate is False
+
+    def test_async_uses_queue_handler(self, _reset_loggers: None) -> None:
+        """Async emission puts a bounded queue on the request thread's path."""
+        from vgi_rpc.logging_utils import DroppingQueueHandler
+
+        configure_worker_logging(debug=True, access_log_async=True, access_log_queue_size=64)
+        access = logging.getLogger(ACCESS_LOGGER)
+        assert len(access.handlers) == 1
+        assert isinstance(access.handlers[0], DroppingQueueHandler)
+
+    def test_json_format_carries_to_access_handler(self, _reset_loggers: None) -> None:
+        """The dedicated handler must not silently revert to text output."""
+        from vgi_rpc.logging_utils import VgiJsonFormatter
+
+        configure_worker_logging(debug=True, log_format=LogFormat.json, access_log_sample=0.5)
+        access = logging.getLogger(ACCESS_LOGGER)
+        assert isinstance(access.handlers[0].formatter, VgiJsonFormatter)
+
+    @pytest.mark.parametrize("rate", [-0.1, 1.5])
+    def test_out_of_range_sample_rate_exits(self, _reset_loggers: None, rate: float) -> None:
+        """A typo here silently changes how much of the audit trail survives."""
+        with pytest.raises(SystemExit):
+            configure_worker_logging(debug=True, access_log_sample=rate)
+
+    def test_non_positive_queue_size_exits(self, _reset_loggers: None) -> None:
+        """A zero-length queue would drop every record."""
+        with pytest.raises(SystemExit):
+            configure_worker_logging(debug=True, access_log_async=True, access_log_queue_size=0)
+
+    def test_env_overrides_win(self, _reset_loggers: None, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Reachable without owning argv, like the other VGI_WORKER_LOG_* vars."""
+        from vgi_rpc.logging_utils import AccessLogSampler
+
+        monkeypatch.setenv("VGI_WORKER_ACCESS_LOG_SAMPLE", "0.1")
+        configure_worker_logging(debug=True)
+        access = logging.getLogger(ACCESS_LOGGER)
+        assert any(isinstance(f, AccessLogSampler) for f in access.handlers[0].filters)
+
+    def test_malformed_env_exits(self, _reset_loggers: None, monkeypatch: pytest.MonkeyPatch) -> None:
+        """A typo must not leave sampling silently off."""
+        monkeypatch.setenv("VGI_WORKER_ACCESS_LOG_SAMPLE", "half")
+        with pytest.raises(SystemExit):
+            configure_worker_logging(debug=True)

{vgi_python-0.24.0 → vgi_python-0.25.0}/uv.lock

@@ -2352,7 +2352,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.24.0"
+version = "0.25.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },
@@ -2467,7 +2467,7 @@ requires-dist = [
     { name = "vgi-python", extras = ["test-fixtures"], marker = "extra == 'test-fixtures-writable'" },
     { name = "vgi-python", extras = ["test-fixtures", "test-fixtures-writable", "http", "oauth", "otel", "sentry", "azure"], marker = "extra == 'dev'" },
     { name = "vgi-python", extras = ["transactor"], marker = "extra == 'test-fixtures-writable'" },
-    { name = "vgi-rpc", specifier = ">=0.33.0" },
+    { name = "vgi-rpc", specifier = ">=0.39.1" },
     { name = "vgi-rpc", extras = ["conformance", "external", "http", "oauth", "otel", "sentry"], marker = "extra == 'dev'" },
     { name = "vgi-rpc", extras = ["http"], marker = "extra == 'granian'" },
     { name = "vgi-rpc", extras = ["http"], marker = "extra == 'http'" },
@@ -2497,7 +2497,7 @@ docs = [
 
 [[package]]
 name = "vgi-rpc"
-version = "0.33.0"
+version = "0.39.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "docstring-parser" },
@@ -2505,9 +2505,9 @@ dependencies = [
     { name = "pywin32", marker = "sys_platform == 'win32'" },
     { name = "tzdata", marker = "sys_platform == 'win32'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/06/5f/8510cc6494dc9183711141b544840f087cfb68ddb3c01d907610101669b3/vgi_rpc-0.33.0.tar.gz", hash = "sha256:90e6221ce481d43fcf45d07d011c3d13cbcb6103a64675dae3fdf0c25e09dd11", size = 986710, upload-time = "2026-08-04T00:20:02.458Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/7d/a4dc94670c7b29eb0d55f3965909d627e4a5e4beadf7787622a049197db7/vgi_rpc-0.39.1.tar.gz", hash = "sha256:3eb71657f34ddc608db817785b596f2653d35341ec57c40481a9fa37ceefe1e7", size = 1060176, upload-time = "2026-08-05T04:22:33.766Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/57/c5/06b7b105abb26667eb47224aa3fb730bd1664686f0794f106b7017f3a8dc/vgi_rpc-0.33.0-py3-none-any.whl", hash = "sha256:1a3ac9e190b4c4625f7d60caf5f85a8a94586ab5786494c9197f080e62c25513", size = 443084, upload-time = "2026-08-04T00:20:00.259Z" },
+    { url = "https://files.pythonhosted.org/packages/60/18/d29ffcb0e3b69ca8d8d7950f99ba5ee6ad9c68e07ce70457bba6567f9859/vgi_rpc-0.39.1-py3-none-any.whl", hash = "sha256:dc2baab02dfc7df37456688e6d4c6cde7c7428bbbb2733e37511b1e950754aca", size = 482199, upload-time = "2026-08-05T04:22:31.935Z" },
 ]
 
 [package.optional-dependencies]

{vgi_python-0.24.0 → vgi_python-0.25.0}/vgi/_test_fixtures/http_server.py

@@ -179,6 +179,14 @@ def main() -> None:
             "--demo-storage",
             help="Enable in-process blob storage for externalized payloads (no S3 required)",
         ),
+        max_externalized_response_bytes: int | None = typer.Option(  # noqa: B008
+            None,
+            "--max-externalized-response-bytes",
+            help=(
+                "Cap on a single externalized response. Hard on every method type, "
+                "with no continuation escape. Default: no cap."
+            ),
+        ),
         port_file: str | None = typer.Option(
             None,
             "--port-file",
@@ -379,6 +387,7 @@ def main() -> None:
             upload_url_provider=upload_url_provider,
             max_upload_bytes=max_upload_bytes if upload_url_provider is not None else None,
             max_request_bytes=max_request_bytes,
+            max_externalized_response_bytes=max_externalized_response_bytes,
             authenticate=authenticate,
             oauth_resource_metadata=oauth_metadata,
             enable_landing_page=False,