vgi-python 0.44.0__tar.gz → 0.45.0__tar.gz

{vgi_python-0.44.0 → vgi_python-0.45.0}/.github/workflows/ci.yml

@@ -129,7 +129,7 @@ jobs:
   hosted-protocols:
     # vgi-rpc's cross-SDK hosted-protocols group: the fixture workers must host
     # vgi.v2 then conformance.Secondary.v1 on stdio, unix and HTTP, and pass the
-    # Identity.v1 groups over HTTP (vgi-fixture-http --identity).
+    # Identity.v2 groups over HTTP (vgi-fixture-http --identity).
     name: Hosted-protocols conformance
     runs-on: ubuntu-latest
     steps:

{vgi_python-0.44.0 → vgi_python-0.45.0}/.github/workflows/tailnet-integration.yml

@@ -33,12 +33,12 @@ jobs:
     steps:
       - uses: actions/checkout@v7
 
-      - name: Checkout unreleased vgi-rpc identity layer
+      - name: Checkout vgi-rpc (Identity.v2)
         uses: actions/checkout@v7
         with:
           repository: Query-farm/vgi-rpc-python
           path: .tailnet/vgi-rpc
-          ref: 04f19147625b4f643b38a687151d8233daa8997c
+          ref: e04ddfa56c19b4cd7cc1e3729d165c763b0d98c7  # v0.52.0 (Identity.v2)
 
       - name: Check kernel networking support
         run: |

{vgi_python-0.44.0 → vgi_python-0.45.0}/CLAUDE.md

@@ -302,7 +302,7 @@ vgi-client --input data.parquet --function sum_all_columns --worker vgi-fixture-
 | `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_RPC_GRANT_KEYS` | Comma-separated base64 32-byte sealed-grant keys (first mints, all verify); enables grants as HTTP bearers. Also `VGI_RPC_GRANT_AUDIENCE`, `VGI_RPC_GRANT_MAX_TTL_SECONDS` |
-| `VGI_INTROSPECT_PRINCIPALS` | Comma-separated principals permitted to call `vgi_rpc.Identity.v1`'s `introspect_token`. Required — no permissive default — whenever the worker implements `resolve_token()` (see below) |
+| `VGI_INTROSPECT_PRINCIPALS` | Comma-separated principals permitted to call `vgi_rpc.Identity.v2`'s `introspect_token`. Required — no permissive default — whenever the worker implements `resolve_token()` (see below) |
 | `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) |
@@ -426,7 +426,7 @@ Also available on `Worker.main --http` and the fixture server. Under
 
 ### Token Introspection (`resolve_token`)
 
-A worker may optionally host the `vgi_rpc.Identity.v1` protocol, whose
+A worker may optionally host the `vgi_rpc.Identity.v2` protocol, whose
 `introspect_token` method 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.
@@ -509,7 +509,9 @@ one. Allowlist rules are unchanged. See `docs/authentication.md` and
 
 ### Attach Tickets (`vgi.attach_tickets.v1`)
 
-`seal_attach` seals a user's ATTACH (catalog name, options incl. secrets,
+Protocol version `2.0.0`: `AttachTicket.expires_at` is nullable
+`timestamp[us, tz="UTC"]` (`datetime | None`, null = no expiry); `1.0.0` was a
+float64 with `+inf`. `seal_attach` seals a user's ATTACH (catalog name, options incl. secrets,
 version specs) into a `vgia1.` ticket under `VGI_SIGNING_KEY`, AAD
 `"vgi.attach_ticket.v1\0" + principal` (principal only, not domain). A runner
 holding the user's grant reattaches with the single option `vgi_attach_ticket`;

{vgi_python-0.44.0 → vgi_python-0.45.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.44.0
+Version: 0.45.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: httpx2>=2.12.0
 Requires-Dist: platformdirs
 Requires-Dist: pyarrow
 Requires-Dist: typer>=0.9
-Requires-Dist: vgi-rpc>=0.51.1
+Requires-Dist: vgi-rpc>=0.52.0
 Provides-Extra: azure
 Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
 Requires-Dist: pymssql>=2.3.0; extra == 'azure'

{vgi_python-0.44.0 → vgi_python-0.45.0}/docs/api/auth.md

@@ -18,7 +18,7 @@ require `pip install vgi-python[http]`; JWT authentication additionally requires
 `principal` plus an optional `token_name`. It lives in a private `vgi-rpc` module, so `vgi.auth`
 re-exports it — a worker that implements `resolve_token` never has to name a private import path.
 
-As of vgi-rpc 0.46.0 introspection is the `vgi_rpc.Identity.v1` protocol hosted on the RPC server,
+As of vgi-rpc 0.46.0 introspection is the `vgi_rpc.Identity.v2` protocol hosted on the RPC server,
 not an HTTP JSON route, so clients discover it through reflection. VGI hosts it on HTTP only, the
 transport that authenticates callers: its allowlist names principals, which stdin/stdout, AF_UNIX
 and TCP do not have. `TokenIdentity` and `TokenResolver` are no longer gated on the `[http]` extra.

{vgi_python-0.44.0 → vgi_python-0.45.0}/docs/api/worker.md

@@ -72,7 +72,7 @@ overriding the same hook stop it at startup.
 
 Reflection (`list_protocols`) reports protocols in this order:
 
-| Transport | `vgi.v2` | `hosted_protocols()` | `vgi_rpc.Reflection.v1` | `vgi_rpc.Identity.v1` |
+| Transport | `vgi.v2` | `hosted_protocols()` | `vgi_rpc.Reflection.v1` | `vgi_rpc.Identity.v2` |
 | --- | --- | --- | --- | --- |
 | stdin/stdout | yes | yes | yes | no |
 | AF_UNIX / named pipe | yes | yes | yes | no |

{vgi_python-0.44.0 → vgi_python-0.45.0}/docs/authentication.md

@@ -41,7 +41,7 @@ lookup.
 
 ## Grants and resolved tokens as bearer credentials
 
-`vgi_rpc.Identity.v1`'s `issue_grant` mints a standing credential that
+`vgi_rpc.Identity.v2`'s `issue_grant` mints a standing credential that
 unattended automation later presents as an ordinary bearer. Over HTTP the
 worker accepts two kinds of identity credential after the deployment's own
 authenticator:

{vgi_python-0.44.0 → vgi_python-0.45.0}/docs/protocol/vgi-attach-tickets.md

@@ -1,7 +1,11 @@
 # VGI Attach Tickets
 
 **Status:** Normative. Reference implementation: vgi-python `vgi/attach_ticket.py`.
-**Protocol:** `vgi.attach_tickets.v1`, version `1.0.0`. No change to `vgi.v2`.
+**Protocol:** `vgi.attach_tickets.v1`, version `2.0.0`. No change to `vgi.v2`.
+**Revision 2026-10-17 (`2.0.0`):** `AttachTicket.expires_at` changed from
+`float64` unix seconds (`+inf` = no expiry) to nullable
+`timestamp[us, tz="UTC"]` (null = no expiry). The sealed payload (§2) is
+unchanged; the exact major.minor version check rejects a `1.0.0` peer.
 **Vectors:** [`vgi/_test_fixtures/attach_ticket_vectors.json`](https://github.com/Query-farm/vgi-python/blob/main/vgi/_test_fixtures/attach_ticket_vectors.json)
 
 An SDK implements attach tickets from this page alone. The words MUST, MUST
@@ -17,7 +21,7 @@ this worker can open. Later a runner attaches with one option,
 `vgi_attach_ticket`, and the worker restores the original attach before any
 catalog code runs.
 
-A ticket says *what* to attach. A sealed grant (`vgi_rpc.Identity.v1`
+A ticket says *what* to attach. A sealed grant (`vgi_rpc.Identity.v2`
 `issue_grant`) says *who* attaches. The two are separate on purpose:
 
 - **A ticket carries no authority.** It opens only under the caller's
@@ -133,7 +137,7 @@ from `vgi_rpc.Reflection.v1` `list_protocols`):
    is useless without a grant.
 
 It is hosted beside `vgi.v2` and never changes how a `vgi.v2` request is
-dispatched. Wire name `vgi.attach_tickets.v1`, `protocol_version = "1.0.0"`.
+dispatched. Wire name `vgi.attach_tickets.v1`, `protocol_version = "2.0.0"`.
 
 ### 5.2 Shapes
 
@@ -154,7 +158,7 @@ One unary method, `seal_attach(request: SealAttachRequest) -> AttachTicket`.
 | Field | Arrow type | Meaning |
 | --- | --- | --- |
 | `ticket` | `utf8` not null | The `vgia1.` text |
-| `expires_at` | `float64` not null | Unix seconds; `+inf` when the ticket has no expiry |
+| `expires_at` | `timestamp[us, tz="UTC"]` nullable | The UTC instant the ticket expires (the sealed `expires_at` seconds × 1 000 000 µs); null when the ticket has no expiry |
 
 ### 5.3 Rules
 
@@ -194,7 +198,7 @@ In this order:
 
    So the two halves of a held entry (grant and ticket) expire together.
 5. **Seal** per §2 with a fresh `ticket_id` and nonce. Return the text and
-   `expires_at` (`+inf` for `0`).
+   `expires_at` (null for `0`).
 
 A worker MAY refuse by policy with `action_denied`.
 

{vgi_python-0.44.0 → vgi_python-0.45.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.44.0"
+version = "0.45.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.51.1",
+    "vgi-rpc>=0.52.0",
     "httpx2>=2.12.0",
 ]
 

{vgi_python-0.44.0 → vgi_python-0.45.0}/scripts/hosted_protocols_conformance.sh

@@ -6,7 +6,7 @@
 #
 #   stdio  vgi-fixture-worker                       (MetaWorker.serve, pipe)
 #   unix   vgi-fixture-worker --unix <sock>         (the DuckDB launcher path)
-#   http   vgi-fixture-http --identity              (+ the Identity.v1 groups)
+#   http   vgi-fixture-http --identity              (+ the Identity.v2 groups)
 #
 # Every worker must host, in order, vgi.v2 then conformance.Secondary.v1.
 #

{vgi_python-0.44.0 → vgi_python-0.45.0}/tests/test_attach_ticket.py

@@ -22,9 +22,9 @@ from __future__ import annotations
 import base64
 import importlib.util
 import json
-import math
 import time
 from collections.abc import Iterator
+from datetime import UTC, datetime, timedelta
 from pathlib import Path
 from typing import Annotated, Any
 
@@ -68,7 +68,7 @@ _DEFAULTS = _VECTORS["defaults"]
 
 _GRANT_KEY_B64 = base64.b64encode(bytes(range(32))).decode()
 _SIGNING_KEY = b"attach-ticket-test-signing-key-1"
-_IDENTITY = "vgi_rpc.Identity.v1"
+_IDENTITY = "vgi_rpc.Identity.v2"
 
 
 @pytest.fixture(autouse=True)
@@ -293,7 +293,7 @@ class _MintingWorker(TicketProbeWorker):
     @classmethod
     def mint_grant(cls, principal: str, purpose: str, scopes: list[str], ttl_seconds: int) -> IssuedGrant:
         """Mint grant."""
-        return IssuedGrant(token=f"own-{principal}", expires_at=time.time() + ttl_seconds)
+        return IssuedGrant(token=f"own-{principal}", expires_at=datetime.now(UTC) + timedelta(seconds=ttl_seconds))
 
 
 def _server(worker: Any, *, transport: str = "http", configured: bool = True, keys: bool = True) -> Any:
@@ -469,15 +469,15 @@ class TestSealAttach:
         [(0, 3600, 3600), (60, 3600, 60), (99999, 3600, 3600), (0, None, None), (60, None, 60)],
     )
     def test_lifetime(self, ttl: int, ceiling: int | None, expected: int | None) -> None:
-        """expires_at = min(requested, grant maximum); 0 asks for the maximum; no maximum is +inf."""
+        """expires_at = min(requested, grant maximum); 0 asks for the maximum; no maximum is null."""
         before = int(time.time())
         ticket = _seal(_impl(ceiling), ttl_seconds=ttl)
         claims = open_attach_ticket(_SIGNING_KEY, ticket.ticket, principal="alice")
         if expected is None:
-            assert claims.expires_at == 0 and math.isinf(ticket.expires_at)
+            assert claims.expires_at == 0 and ticket.expires_at is None
         else:
             assert before + expected <= claims.expires_at <= int(time.time()) + expected
-            assert ticket.expires_at == claims.expires_at
+            assert ticket.expires_at == datetime.fromtimestamp(claims.expires_at, tz=UTC)
 
     def test_max_ttl_from_grant_keys_and_env(self, monkeypatch: pytest.MonkeyPatch) -> None:
         """Max ttl from grant keys and env."""
@@ -666,7 +666,8 @@ class TestEndToEnd:
         with http_connect(Identity, client=user) as identity:  # type: ignore[type-abstract]
             grant = identity.issue_grant(purpose="vgi.unattended", scopes=[], ttl_seconds=600)
         assert sealed.ticket.startswith("vgia1.") and "sk-live-secret" not in sealed.ticket
-        assert sealed.expires_at <= time.time() + 7 * 24 * 3600 + 5
+        assert sealed.expires_at is not None
+        assert sealed.expires_at <= datetime.now(UTC) + timedelta(days=7, seconds=5)
 
         runner = _SyncTestClient(app, default_headers={"Authorization": f"Bearer {grant.token}"})
         reattached = _attach_over_http(runner, {"vgi_attach_ticket": sealed.ticket})
@@ -738,3 +739,28 @@ def test_fixture_http_server_hosts_attach_tickets_when_keyed(http_worker: Any) -
     with http_connect(Reflection, base_url) as reflection:  # type: ignore[type-abstract]
         hosted = {p.protocol for p in reflection.list_protocols().protocols}
     assert ATTACH_TICKETS_PROTOCOL_NAME in hosted
+
+
+class TestAttachTicketWireShape:
+    """Protocol ``2.0.0``: ``expires_at`` is a nullable UTC microsecond timestamp."""
+
+    def test_protocol_version(self) -> None:
+        """The exact major.minor check rejects a ``1.0.0`` (float64 ``expires_at``) peer."""
+        assert AttachTickets.protocol_version == "2.0.0"
+
+    def test_expires_at_is_a_nullable_utc_timestamp(self) -> None:
+        """``timestamp[us, tz="UTC"]``, nullable; null replaces ``+inf``."""
+        field = AttachTicket.ARROW_SCHEMA.field("expires_at")
+        assert field.type == pa.timestamp("us", tz="UTC")
+        assert field.nullable
+
+    @pytest.mark.parametrize("when", [None, datetime(2026, 9, 21, 12, 0, 0, 123456, tzinfo=UTC)])
+    def test_round_trip(self, when: datetime | None) -> None:
+        """Null and a microsecond-precision instant both survive the wire."""
+        got = AttachTicket.deserialize_from_bytes(AttachTicket(ticket="vgia1.x", expires_at=when).serialize_to_bytes())
+        assert got.expires_at == when
+
+    def test_a_naive_datetime_is_refused(self) -> None:
+        """Arrow would read a naive value as UTC, silently shifting local time."""
+        with pytest.raises(ValueError, match="timezone-aware"):
+            AttachTicket(ticket="vgia1.x", expires_at=datetime(2026, 1, 1))

{vgi_python-0.44.0 → vgi_python-0.45.0}/tests/test_generated_cpp_records.py

@@ -109,7 +109,7 @@ def test_known_shapes() -> None:
 
 def test_enum_wire_values_are_member_names_in_order() -> None:
     """Enumerator order is the wire dictionary order; the wire value is the member name."""
-    from vgi.protocol import TableInOutFunctionInitPhase
+    from vgi.table_function import TableInOutFunctionInitPhase
 
     phase = cpp_records.build_model().enums["VgiInitPhase"]
     assert [m.wire_name for m in phase.members] == [m.name for m in TableInOutFunctionInitPhase]

{vgi_python-0.44.0 → vgi_python-0.45.0}/tests/test_grant_auth.py

@@ -2,7 +2,7 @@
 
 """Identity credentials accepted as HTTP bearers: sealed grants and ``resolve_token``.
 
-vgi-rpc's ``Identity.v1`` mints grants "presented later by unattended
+vgi-rpc's ``Identity.v2`` mints grants "presented later by unattended
 automation as an ordinary bearer". These tests close that loop through
 vgi-python's own HTTP surface (``create_app``), not vgi-rpc in isolation:
 
@@ -42,7 +42,7 @@ from vgi.serve import create_app
 _KEY_B64 = base64.b64encode(bytes(range(32))).decode()
 _OTHER_KEY_B64 = base64.b64encode(bytes(range(32, 64))).decode()
 _SIGNING_KEY = b"grant-auth-test-signing-key-0001"
-_IDENTITY = "vgi_rpc.Identity.v1"
+_IDENTITY = "vgi_rpc.Identity.v2"
 _GRANT_ENV = (GRANT_KEYS_ENV, "VGI_RPC_GRANT_AUDIENCE", "VGI_RPC_GRANT_MAX_TTL_SECONDS")
 
 _VECTORS = json.loads(files("vgi_rpc.conformance").joinpath("grant_token_vectors.json").read_text(encoding="utf-8"))

{vgi_python-0.44.0 → vgi_python-0.45.0}/tests/test_hosted_protocols.py

@@ -38,7 +38,7 @@ _REPO_ROOT = Path(__file__).resolve().parent.parent
 
 _EXTRAS = ["vgi_test.Echo.v1", "vgi_test.Counter.v1"]
 _EXPECTED = ["vgi.v2", *_EXTRAS, "vgi_rpc.Reflection.v1"]
-_IDENTITY = "vgi_rpc.Identity.v1"
+_IDENTITY = "vgi_rpc.Identity.v2"
 
 # Protocol classes are abstract to mypy; the connect helpers want concrete types.
 _REFLECTION: type[Any] = Reflection
@@ -49,7 +49,7 @@ _POSIX_ONLY = pytest.mark.skipif(sys.platform == "win32", reason="AF_UNIX launch
 
 
 class _IdentityHostingWorker(HostingWorker):
-    """Opts into ``vgi_rpc.Identity.v1`` as well."""
+    """Opts into ``vgi_rpc.Identity.v2`` as well."""
 
     @classmethod
     def resolve_token(cls, token: str) -> TokenIdentity | None:

{vgi_python-0.44.0 → vgi_python-0.45.0}/tests/test_serve.py

@@ -10,6 +10,7 @@ import subprocess
 import sys
 import textwrap
 import time
+from datetime import UTC, datetime, timedelta
 from typing import TYPE_CHECKING, Annotated, Any
 
 import pyarrow as pa
@@ -499,7 +500,7 @@ class _MintingWorker(Worker):
         ttl = min(ttl_seconds, 3600)
         return IssuedGrant(
             token=f"sealed:{principal}:{':'.join(scopes)}:{purpose}",
-            expires_at=1_000_000.0 + ttl,
+            expires_at=datetime.fromtimestamp(1_000_000, tz=UTC) + timedelta(seconds=ttl),
             grant_id="grant-1",
         )
 
@@ -509,7 +510,9 @@ class _BothWorker(_IntrospectingWorker):
 
     @classmethod
     def mint_grant(cls, principal: str, purpose: str, scopes: list[str], ttl_seconds: int) -> IssuedGrant:
-        return IssuedGrant(token=f"sealed:{principal}", expires_at=1_000_000.0, grant_id="g")
+        return IssuedGrant(
+            token=f"sealed:{principal}", expires_at=datetime.fromtimestamp(1_000_000, tz=UTC), grant_id="g"
+        )
 
 
 class TestIntrospectResolverDetection:
@@ -582,7 +585,7 @@ def _hosted_protocols(worker_cls: type[Worker]) -> frozenset[str]:
 
 
 class TestTokenIntrospection:
-    """``vgi_rpc.Identity.v1`` — unhosted unless a worker implements the hook.
+    """``vgi_rpc.Identity.v2`` — unhosted unless a worker implements the hook.
 
     Identity was an HTTP JSON route (``POST {prefix}/__introspect_token__``)
     through vgi-rpc 0.45.x. As of 0.46.0 it is an RPC-layer protocol hosted on
@@ -615,7 +618,7 @@ class TestTokenIntrospection:
 
     def test_protocol_not_hosted_without_hook(self) -> None:
         """The server built for such a worker hosts no identity protocol."""
-        assert "vgi_rpc.Identity.v1" not in _hosted_protocols(_SingleWorker)
+        assert "vgi_rpc.Identity.v2" not in _hosted_protocols(_SingleWorker)
 
     def test_identity_built_with_hook(self) -> None:
         """Implementing the hook is what builds the implementation."""
@@ -638,7 +641,7 @@ class TestTokenIntrospection:
         with pytest.MonkeyPatch.context() as mp:
             mp.setenv("VGI_INTROSPECT_PRINCIPALS", "proxy-a")
             hosted = _hosted_protocols(_IntrospectingWorker)
-        assert "vgi_rpc.Identity.v1" in hosted
+        assert "vgi_rpc.Identity.v2" in hosted
 
     def test_resolver_answers_through_the_implementation(self) -> None:
         """The worker's own lookup is what the hosted protocol calls."""
@@ -697,7 +700,7 @@ class TestTokenIntrospection:
 
 
 class TestGrantMinting:
-    """``issue_grant`` — the other half of ``vgi_rpc.Identity.v1``.
+    """``issue_grant`` — the other half of ``vgi_rpc.Identity.v2``.
 
     Guarded very differently from ``introspect_token``, and deliberately so.
     Introspection answers a question about *somebody else's* credential, so it
@@ -729,7 +732,7 @@ class TestGrantMinting:
 
     def test_minting_alone_hosts_the_protocol(self) -> None:
         """A worker may mint without resolving — the two are independent."""
-        assert "vgi_rpc.Identity.v1" in _hosted_protocols(_MintingWorker)
+        assert "vgi_rpc.Identity.v2" in _hosted_protocols(_MintingWorker)
 
     def test_minting_alone_offers_only_issue_grant(self) -> None:
         """The protocol describes what the worker does, not what it could do."""
@@ -774,7 +777,7 @@ class TestGrantMinting:
         grant = identity.issue_grant(  # type: ignore[attr-defined]
             "long", [], 86_400, _minting_ctx("alice")
         )
-        assert grant.expires_at == 1_000_000.0 + 3600
+        assert grant.expires_at == datetime.fromtimestamp(1_000_000 + 3600, tz=UTC)
 
     def test_stale_authentication_cannot_mint(self) -> None:
         """Minting while the user is present is enforced, not just documented."""