vars-client 0.1.0__py3-none-any.whl

vars_client/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.1.0"
+
+
+def hello() -> str:
+    return "Hello from vars-client!"

vars_client/auth/jwt_bootstrap.py

@@ -0,0 +1,92 @@
+"""Shared machinery for auth schemes that exchange a credential for a
+short-lived Bearer JWT (the pattern used by Annosaurus/VampireSquid/Oni/
+Panoptes' `/auth` endpoint and Raziel's `/config/auth` endpoint).
+
+Subclasses only need to say *what* credential to send and *where* to send
+it; caching, proactive refresh, and concurrency-safe re-exchange are handled
+here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from abc import abstractmethod
+from datetime import datetime, timedelta
+from typing import Any
+
+import httpx
+from kiota_abstractions.authentication import AuthenticationProvider
+from kiota_abstractions.request_information import RequestInformation
+
+AUTHORIZATION_HEADER = "Authorization"
+
+DEFAULT_TOKEN_LIFETIME = timedelta(hours=24)
+DEFAULT_REFRESH_BUFFER = timedelta(minutes=5)
+
+
+class JWTBootstrapAuthProvider(AuthenticationProvider):
+    """Exchanges a credential for a Bearer JWT, caches it, and refreshes it
+    proactively before expiry. Call `invalidate()` to force re-exchange on
+    the next request (e.g. after a 401 from the resource server).
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        exchange_path: str,
+        token_field: str = "token",
+        *,
+        token_lifetime: timedelta = DEFAULT_TOKEN_LIFETIME,
+        refresh_buffer: timedelta = DEFAULT_REFRESH_BUFFER,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._exchange_url = base_url.rstrip("/") + exchange_path
+        self._token_field = token_field
+        self._token_lifetime = token_lifetime
+        self._refresh_buffer = refresh_buffer
+        self._http_client = http_client or httpx.AsyncClient()
+        self._token: str | None = None
+        self._issued_at: datetime | None = None
+        self._lock = asyncio.Lock()
+
+    @abstractmethod
+    def _exchange_headers(self) -> dict[str, str]:
+        """Headers carrying the initial credential for the exchange request."""
+
+    def invalidate(self) -> None:
+        """Discard the cached token, forcing a fresh exchange on next use."""
+        self._token = None
+        self._issued_at = None
+
+    def _is_stale(self) -> bool:
+        if self._token is None or self._issued_at is None:
+            return True
+        age = datetime.now() - self._issued_at
+        return age >= self._token_lifetime - self._refresh_buffer
+
+    async def _refresh(self) -> None:
+        async with self._lock:
+            if not self._is_stale():
+                return  # another waiter already refreshed
+            response = await self._http_client.post(
+                self._exchange_url, headers=self._exchange_headers()
+            )
+            response.raise_for_status()
+            self._token = response.json()[self._token_field]
+            self._issued_at = datetime.now()
+
+    async def get_token(self) -> str:
+        if self._is_stale():
+            await self._refresh()
+        assert self._token is not None
+        return self._token
+
+    async def authenticate_request(
+        self,
+        request: RequestInformation,
+        additional_authentication_context: dict[str, Any] | None = None,
+    ) -> None:
+        if request.headers.contains(AUTHORIZATION_HEADER):
+            request.headers.remove(AUTHORIZATION_HEADER)
+        token = await self.get_token()
+        request.headers.add(AUTHORIZATION_HEADER, f"Bearer {token}")

vars_client/auth/jwt_exchange.py

@@ -0,0 +1,30 @@
+"""Auth provider for the API-key JWT exchange used by Annosaurus, Vampire
+Squid, Oni, and Panoptes: `Authorization: APIKEY <key>` -> JWT.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from vars_client.auth.jwt_bootstrap import JWTBootstrapAuthProvider
+
+
+class JWTExchangeAuthProvider(JWTBootstrapAuthProvider):
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        exchange_path: str = "/v1/auth",
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(
+            base_url,
+            exchange_path,
+            token_field="access_token",
+            http_client=http_client,
+        )
+        self._api_key = api_key
+
+    def _exchange_headers(self) -> dict[str, str]:
+        return {"Authorization": f"APIKEY {self._api_key}"}

vars_client/auth/middleware.py

@@ -0,0 +1,30 @@
+"""HTTP middleware pairing with JWTBootstrapAuthProvider to retry a request
+once, with a freshly exchanged token, if the resource server rejects the
+cached one with a 401.
+"""
+
+from __future__ import annotations
+
+import httpx
+from kiota_http.middleware import BaseMiddleware
+
+from vars_client.auth.jwt_bootstrap import AUTHORIZATION_HEADER, JWTBootstrapAuthProvider
+
+
+class RefreshOnUnauthorizedMiddleware(BaseMiddleware):
+    def __init__(self, auth_provider: JWTBootstrapAuthProvider) -> None:
+        super().__init__()
+        self._auth_provider = auth_provider
+
+    async def send(
+        self, request: httpx.Request, transport: httpx.AsyncBaseTransport
+    ) -> httpx.Response:
+        response = await super().send(request, transport)
+        if response.status_code != 401:
+            return response
+
+        self._auth_provider.invalidate()
+        token = await self._auth_provider.get_token()
+        request.headers[AUTHORIZATION_HEADER] = f"Bearer {token}"
+        await response.aclose()
+        return await super().send(request, transport)

vars_client/auth/raziel.py

@@ -0,0 +1,80 @@
+"""Auth provider for Raziel's two-stage bootstrap:
+
+1. POST Basic-encoded credentials to `/config/auth` -> JWT.
+2. GET `/config/endpoints` with that JWT as Bearer -> per-service base URLs
+   and secrets for the rest of the VARS stack.
+
+Stage 1 is handled by the inherited JWTBootstrapAuthProvider machinery.
+Stage 2 (`get_endpoints`) is a one-off config fetch, not a per-request auth
+attachment, so it lives here as an extra method beyond the
+AuthenticationProvider interface.
+
+Both username and password are optional: Raziel's `/config/endpoints` works
+fine without an Authorization header, it just omits the `secret` field from
+each entry. This lets institutions that only need read-only access skip
+credentials entirely.
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+import httpx
+from kiota_abstractions.request_information import RequestInformation
+
+from vars_client.auth.jwt_bootstrap import JWTBootstrapAuthProvider
+
+
+class RazielAuthProvider(JWTBootstrapAuthProvider):
+    def __init__(
+        self,
+        base_url: str,
+        username: str | None = None,
+        password: str | None = None,
+        *,
+        exchange_path: str = "/config/auth",
+        endpoints_path: str = "/config/endpoints",
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(
+            base_url,
+            exchange_path,
+            token_field="accessToken",
+            http_client=http_client,
+        )
+        self._username = username
+        self._password = password
+        self._endpoints_url = base_url.rstrip("/") + endpoints_path
+
+    @property
+    def is_anonymous(self) -> bool:
+        return self._username is None or self._password is None
+
+    def _exchange_headers(self) -> dict[str, str]:
+        credentials = base64.b64encode(f"{self._username}:{self._password}".encode()).decode()
+        return {"Authorization": f"Basic {credentials}"}
+
+    async def authenticate_request(
+        self,
+        request: RequestInformation,
+        additional_authentication_context: dict[str, Any] | None = None,
+    ) -> None:
+        if self.is_anonymous:
+            return
+        await super().authenticate_request(request, additional_authentication_context)
+
+    async def get_endpoints(self, *, internal: bool = False) -> list[dict]:
+        """Fetch service base URLs from Raziel's config endpoint. Secrets are
+        only included in the response when authenticated.
+        """
+        headers = {}
+        if not self.is_anonymous:
+            headers["Authorization"] = f"Bearer {await self.get_token()}"
+        response = await self._http_client.get(
+            self._endpoints_url,
+            headers=headers,
+            params={"internal": internal},
+        )
+        response.raise_for_status()
+        return response.json()

vars_client/auth/static_key.py

@@ -0,0 +1,25 @@
+"""Auth provider for Beholder: every request just carries a static
+`X-Api-Key` header, no exchange or expiry involved.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kiota_abstractions.authentication import AuthenticationProvider
+from kiota_abstractions.request_information import RequestInformation
+
+
+class StaticKeyAuthProvider(AuthenticationProvider):
+    def __init__(self, api_key: str, *, header_name: str = "X-Api-Key") -> None:
+        self._api_key = api_key
+        self._header_name = header_name
+
+    async def authenticate_request(
+        self,
+        request: RequestInformation,
+        additional_authentication_context: dict[str, Any] | None = None,
+    ) -> None:
+        if request.headers.contains(self._header_name):
+            request.headers.remove(self._header_name)
+        request.headers.add(self._header_name, self._api_key)

vars_client/client.py

@@ -0,0 +1,114 @@
+"""Top-level session object: resolves a ConfigProvider's endpoints once and
+wires each generated service client to a Kiota RequestAdapter with the auth
+provider appropriate for that service.
+"""
+
+from __future__ import annotations
+
+from kiota_abstractions.authentication import AnonymousAuthenticationProvider
+from kiota_http.httpx_request_adapter import HttpxRequestAdapter
+from kiota_http.kiota_client_factory import KiotaClientFactory
+
+from vars_client.auth.jwt_exchange import JWTExchangeAuthProvider
+from vars_client.auth.middleware import RefreshOnUnauthorizedMiddleware
+from vars_client.auth.static_key import StaticKeyAuthProvider
+from vars_client.config import ConfigProvider, RazielConfigProvider, ServiceEndpoint
+from vars_client.generated import (
+    AnnosaurusClient,
+    BeholderClient,
+    OniClient,
+    PanoptesClient,
+    RazielClient,
+    VampireSquidClient,
+)
+from vars_client.skimmer import SkimmerClient
+
+# service name -> (generated client class, JWT-exchange path)
+JWT_EXCHANGE_SERVICES = {
+    "annosaurus": (AnnosaurusClient, "/v1/auth"),
+    "vampire_squid": (VampireSquidClient, "/v1/auth"),
+    "oni": (OniClient, "/v1/auth"),
+    "panoptes": (PanoptesClient, "/panoptes/v1/auth"),
+}
+
+
+def _adapter(auth_provider, base_url: str, *, http_client=None) -> HttpxRequestAdapter:
+    # HttpxRequestAdapter's `base_url` constructor kwarg is a no-op (it's
+    # only ever read from `http_client.base_url` at init time) -- the
+    # property setter is the only thing that actually takes effect.
+    adapter = HttpxRequestAdapter(auth_provider, http_client=http_client)
+    adapter.base_url = base_url
+    return adapter
+
+
+def _strip_versioned_suffix(url: str, exchange_path: str) -> str:
+    # Raziel's registered service URLs already include the versioned path
+    # prefix (e.g. ".../anno/v1") that's also baked into each service's
+    # OpenAPI paths ("/v1/health", "/v1/auth", ...). Combining them as-is
+    # double-versions the URL and 404s, so strip the prefix back off. A
+    # ConfigProvider that already supplies the bare service root (no
+    # version suffix) is left untouched.
+    prefix = exchange_path.rsplit("/", 1)[0]  # "/v1/auth" -> "/v1", "/panoptes/v1/auth" -> "/panoptes/v1"
+    url = url.rstrip("/")
+    return url[: -len(prefix)] if prefix and url.endswith(prefix) else url
+
+
+def _jwt_exchange_adapter(endpoint: ServiceEndpoint, exchange_path: str) -> HttpxRequestAdapter:
+    base_url = _strip_versioned_suffix(endpoint.url, exchange_path)
+
+    # No secret configured -> build an anonymous client rather than refusing
+    # to connect. Every service's read endpoints work unauthenticated; only
+    # writes require a Bearer token, and those will simply fail at the point
+    # of use if attempted without one.
+    if not endpoint.secret:
+        return _adapter(AnonymousAuthenticationProvider(), base_url)
+
+    auth_provider = JWTExchangeAuthProvider(base_url, endpoint.secret, exchange_path=exchange_path)
+    http_client = KiotaClientFactory.create_with_custom_middleware(
+        [*KiotaClientFactory.get_default_middleware(None), RefreshOnUnauthorizedMiddleware(auth_provider)]
+    )
+    return _adapter(auth_provider, base_url, http_client=http_client)
+
+
+class VARSClient:
+    """`await VARSClient(config).connect()` then use `.annosaurus`,
+    `.vampire_squid`, `.oni`, `.panoptes`, `.beholder`, `.raziel`, and
+    `.skimmer`. Attributes stay `None` for services the ConfigProvider
+    didn't return an endpoint for.
+    """
+
+    def __init__(self, config: ConfigProvider) -> None:
+        self._config = config
+        self.annosaurus: AnnosaurusClient | None = None
+        self.vampire_squid: VampireSquidClient | None = None
+        self.oni: OniClient | None = None
+        self.panoptes: PanoptesClient | None = None
+        self.beholder: BeholderClient | None = None
+        self.raziel: RazielClient | None = None
+        self.skimmer: SkimmerClient | None = None
+
+    async def connect(self) -> VARSClient:
+        endpoints = await self._config.get_endpoints()
+
+        for name, (client_cls, exchange_path) in JWT_EXCHANGE_SERVICES.items():
+            if name in endpoints:
+                setattr(self, name, client_cls(_jwt_exchange_adapter(endpoints[name], exchange_path)))
+
+        if (endpoint := endpoints.get("beholder")) is not None:
+            # Every Beholder capture endpoint requires the key except
+            # /health, which still works anonymously.
+            auth_provider = (
+                StaticKeyAuthProvider(endpoint.secret)
+                if endpoint.secret
+                else AnonymousAuthenticationProvider()
+            )
+            self.beholder = BeholderClient(_adapter(auth_provider, endpoint.url))
+
+        if (endpoint := endpoints.get("skimmer")) is not None:
+            self.skimmer = SkimmerClient(endpoint.url)
+
+        if isinstance(self._config, RazielConfigProvider):
+            adapter = _adapter(self._config.auth, self._config.base_url)
+            self.raziel = RazielClient(adapter)
+
+        return self

vars_client/config.py

@@ -0,0 +1,113 @@
+"""Decouples "where do I find each service's base URL and secret" from
+Raziel specifically, so institutions not running Raziel can still use the
+library by supplying config directly (YAML/dict) or via environment
+variables.
+"""
+
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+import httpx
+import yaml
+
+from vars_client.auth.raziel import RazielAuthProvider
+
+SERVICE_NAMES = ("raziel", "annosaurus", "vampire_squid", "oni", "panoptes", "beholder")
+
+
+@dataclass(frozen=True)
+class ServiceEndpoint:
+    name: str
+    url: str
+    secret: str | None = None
+
+
+class ConfigProvider(ABC):
+    @abstractmethod
+    async def get_endpoints(self) -> dict[str, ServiceEndpoint]:
+        """Return known service endpoints keyed by service name."""
+
+
+class RazielConfigProvider(ConfigProvider):
+    """Discovers endpoints at runtime via Raziel's `/config/endpoints`.
+
+    `username`/`password` are optional -- without them, endpoints are
+    discovered anonymously and come back without secrets, which is enough
+    for read-only access to the services that allow it.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        username: str | None = None,
+        password: str | None = None,
+        *,
+        internal: bool = False,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.base_url = base_url
+        self.auth = RazielAuthProvider(base_url, username, password, http_client=http_client)
+        self._internal = internal
+
+    async def get_endpoints(self) -> dict[str, ServiceEndpoint]:
+        raw = await self.auth.get_endpoints(internal=self._internal)
+        return {
+            # Raziel names services with hyphens (e.g. "vampire-squid");
+            # normalize to underscores to match the identifiers used
+            # everywhere else in this library (JWT_EXCHANGE_SERVICES,
+            # SERVICE_NAMES, VARSClient attributes).
+            (name := entry["name"].replace("-", "_")): ServiceEndpoint(
+                name=name, url=entry["url"], secret=entry.get("secret")
+            )
+            for entry in raw
+        }
+
+
+class StaticConfigProvider(ConfigProvider):
+    """Fixed endpoints supplied directly, for institutions not running Raziel."""
+
+    def __init__(self, endpoints: dict[str, ServiceEndpoint]) -> None:
+        self._endpoints = endpoints
+
+    async def get_endpoints(self) -> dict[str, ServiceEndpoint]:
+        return dict(self._endpoints)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, dict[str, str]]) -> StaticConfigProvider:
+        endpoints = {
+            name: ServiceEndpoint(name=name, url=entry["url"], secret=entry.get("secret"))
+            for name, entry in data.items()
+        }
+        return cls(endpoints)
+
+    @classmethod
+    def from_yaml(cls, path: str) -> StaticConfigProvider:
+        with open(path) as f:
+            data = yaml.safe_load(f)
+        return cls.from_dict(data)
+
+
+class EnvConfigProvider(ConfigProvider):
+    """Reads `{prefix}_{SERVICE}_URL` / `{prefix}_{SERVICE}_SECRET` env vars.
+
+    e.g. VARS_ANNOSAURUS_URL, VARS_ANNOSAURUS_SECRET. Services with no URL
+    set are omitted, not errored on.
+    """
+
+    def __init__(self, services: tuple[str, ...] = SERVICE_NAMES, *, prefix: str = "VARS") -> None:
+        self._services = services
+        self._prefix = prefix
+
+    async def get_endpoints(self) -> dict[str, ServiceEndpoint]:
+        endpoints = {}
+        for name in self._services:
+            env_key = name.upper()
+            url = os.environ.get(f"{self._prefix}_{env_key}_URL")
+            if url is None:
+                continue
+            secret = os.environ.get(f"{self._prefix}_{env_key}_SECRET")
+            endpoints[name] = ServiceEndpoint(name=name, url=url, secret=secret)
+        return endpoints

vars_client/generated/__init__.py

@@ -0,0 +1,23 @@
+"""Hand-maintained convenience re-exports of the generated service clients.
+
+This file is never touched by scripts/generate.sh — Kiota writes only into
+the per-service subdirectories below, not this top-level package.
+"""
+
+from vars_client.generated.annosaurus.annosaurus_client import AnnosaurusClient
+from vars_client.generated.beholder.beholder_client import BeholderClient
+from vars_client.generated.oni.oni_client import OniClient
+from vars_client.generated.panoptes.panoptes_client import PanoptesClient
+from vars_client.generated.raziel.raziel_client import RazielClient
+from vars_client.generated.vampire_squid.vampire_squid_client import (
+    VampireSquidClient,
+)
+
+__all__ = [
+    "AnnosaurusClient",
+    "BeholderClient",
+    "OniClient",
+    "PanoptesClient",
+    "RazielClient",
+    "VampireSquidClient",
+]

vars_client/generated/annosaurus/.kiota.log

@@ -0,0 +1,2 @@
+Warning: KiotaBuilder OpenAPI warning: #/ - A servers entry (v3) or host + basePath + schemes properties (v2) was not present in the OpenAPI description. The root URL will need to be set manually with the request adapter.
+Warning: KiotaBuilder No server url found in the OpenAPI document. The base url will need to be set when using the client.

vars_client/generated/annosaurus/annosaurus_client.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+from collections.abc import Callable
+from kiota_abstractions.api_client_builder import enable_backing_store_for_serialization_writer_factory, register_default_deserializer, register_default_serializer
+from kiota_abstractions.base_request_builder import BaseRequestBuilder
+from kiota_abstractions.get_path_parameters import get_path_parameters
+from kiota_abstractions.request_adapter import RequestAdapter
+from kiota_abstractions.serialization import ParseNodeFactoryRegistry, SerializationWriterFactoryRegistry
+from kiota_serialization_form.form_parse_node_factory import FormParseNodeFactory
+from kiota_serialization_form.form_serialization_writer_factory import FormSerializationWriterFactory
+from kiota_serialization_json.json_parse_node_factory import JsonParseNodeFactory
+from kiota_serialization_json.json_serialization_writer_factory import JsonSerializationWriterFactory
+from kiota_serialization_multipart.multipart_serialization_writer_factory import MultipartSerializationWriterFactory
+from kiota_serialization_text.text_parse_node_factory import TextParseNodeFactory
+from kiota_serialization_text.text_serialization_writer_factory import TextSerializationWriterFactory
+from typing import Any, Optional, TYPE_CHECKING, Union
+
+if TYPE_CHECKING:
+    from .v1.v1_request_builder import V1RequestBuilder
+
+class AnnosaurusClient(BaseRequestBuilder):
+    """
+    The main entry point of the SDK, exposes the configuration and the fluent API.
+    """
+    def __init__(self,request_adapter: RequestAdapter) -> None:
+        """
+        Instantiates a new AnnosaurusClient and sets the default values.
+        param request_adapter: The request adapter to use to execute the requests.
+        Returns: None
+        """
+        if request_adapter is None:
+            raise TypeError("request_adapter cannot be null.")
+        super().__init__(request_adapter, "{+baseurl}", None)
+        register_default_serializer(JsonSerializationWriterFactory)
+        register_default_serializer(TextSerializationWriterFactory)
+        register_default_serializer(FormSerializationWriterFactory)
+        register_default_serializer(MultipartSerializationWriterFactory)
+        register_default_deserializer(JsonParseNodeFactory)
+        register_default_deserializer(TextParseNodeFactory)
+        register_default_deserializer(FormParseNodeFactory)
+    
+    @property
+    def v1(self) -> V1RequestBuilder:
+        """
+        The v1 property
+        """
+        from .v1.v1_request_builder import V1RequestBuilder
+
+        return V1RequestBuilder(self.request_adapter, self.path_parameters)
+    
+

vars_client/generated/annosaurus/kiota-lock.json

@@ -0,0 +1,35 @@
+{
+  "descriptionHash": "EEF9DDCF9EC8646AF0A83C688745BD11A8D3B2C60A75BC838827474E2DBC87702E2CB5F214172F88CA24C16137E9099AB3FD8D976BF4324E79993F45DDD0813D",
+  "descriptionLocation": "../../../../specs/annosaurus.yaml",
+  "lockFileVersion": "1.0.0",
+  "kiotaVersion": "1.32.5",
+  "clientClassName": "AnnosaurusClient",
+  "typeAccessModifier": "Public",
+  "clientNamespaceName": "vars_client.generated.annosaurus",
+  "language": "Python",
+  "usesBackingStore": false,
+  "excludeBackwardCompatible": true,
+  "includeAdditionalData": true,
+  "disableSSLValidation": false,
+  "serializers": [
+    "Microsoft.Kiota.Serialization.Json.JsonSerializationWriterFactory",
+    "Microsoft.Kiota.Serialization.Text.TextSerializationWriterFactory",
+    "Microsoft.Kiota.Serialization.Form.FormSerializationWriterFactory",
+    "Microsoft.Kiota.Serialization.Multipart.MultipartSerializationWriterFactory"
+  ],
+  "deserializers": [
+    "Microsoft.Kiota.Serialization.Json.JsonParseNodeFactory",
+    "Microsoft.Kiota.Serialization.Text.TextParseNodeFactory",
+    "Microsoft.Kiota.Serialization.Form.FormParseNodeFactory"
+  ],
+  "structuredMimeTypes": [
+    "application/json",
+    "text/plain;q=0.9",
+    "application/x-www-form-urlencoded;q=0.2",
+    "multipart/form-data;q=0.1"
+  ],
+  "includePatterns": [],
+  "excludePatterns": [],
+  "disabledValidationRules": [],
+  "allowedExternalOrigins": []
+}