hotdata 0.2.5__tar.gz → 0.3.0__tar.gz

{hotdata-0.2.5 → hotdata-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hotdata
-Version: 0.2.5
+Version: 0.3.0
 Summary: Hotdata API
 Author-email: Hotdata <developers@hotdata.dev>
 License: MIT

{hotdata-0.2.5 → hotdata-0.3.0}/hotdata/__init__.py

@@ -51,6 +51,9 @@ __all__ = [
     "ApiKeyError",
     "ApiAttributeError",
     "ApiException",
+    "AddManagedSchemaRequest",
+    "AddManagedTableDecl",
+    "AddManagedTableRequest",
     "ApiErrorDetail",
     "ApiErrorResponse",
     "AsyncQueryResponse",
@@ -140,6 +143,8 @@ __all__ = [
     "ListWorkspacesResponse",
     "LoadManagedTableRequest",
     "LoadManagedTableResponse",
+    "ManagedSchemaResponse",
+    "ManagedTableResponse",
     "NumericProfileDetail",
     "QueryRequest",
     "QueryResponse",
@@ -216,6 +221,9 @@ from hotdata.exceptions import ApiAttributeError as ApiAttributeError
 from hotdata.exceptions import ApiException as ApiException
 
 # import models into sdk package
+from hotdata.models.add_managed_schema_request import AddManagedSchemaRequest as AddManagedSchemaRequest
+from hotdata.models.add_managed_table_decl import AddManagedTableDecl as AddManagedTableDecl
+from hotdata.models.add_managed_table_request import AddManagedTableRequest as AddManagedTableRequest
 from hotdata.models.api_error_detail import ApiErrorDetail as ApiErrorDetail
 from hotdata.models.api_error_response import ApiErrorResponse as ApiErrorResponse
 from hotdata.models.async_query_response import AsyncQueryResponse as AsyncQueryResponse
@@ -305,6 +313,8 @@ from hotdata.models.list_uploads_response import ListUploadsResponse as ListUplo
 from hotdata.models.list_workspaces_response import ListWorkspacesResponse as ListWorkspacesResponse
 from hotdata.models.load_managed_table_request import LoadManagedTableRequest as LoadManagedTableRequest
 from hotdata.models.load_managed_table_response import LoadManagedTableResponse as LoadManagedTableResponse
+from hotdata.models.managed_schema_response import ManagedSchemaResponse as ManagedSchemaResponse
+from hotdata.models.managed_table_response import ManagedTableResponse as ManagedTableResponse
 from hotdata.models.numeric_profile_detail import NumericProfileDetail as NumericProfileDetail
 from hotdata.models.query_request import QueryRequest as QueryRequest
 from hotdata.models.query_response import QueryResponse as QueryResponse

hotdata-0.3.0/hotdata/_auth.py

@@ -0,0 +1,233 @@
+"""Transparent API-token -> JWT exchange for the Hotdata Python SDK.
+
+Hotdata is moving API authentication to short-lived JWTs. Users still configure
+the SDK with their long-lived ``hd_`` API token, but every request should carry
+a fresh JWT instead. This module is the hand-written, regeneration-immune piece
+that makes that happen behind the scenes: :class:`_TokenManager` exchanges the
+API token for a JWT at ``POST {host}/v1/auth/jwt`` and keeps it fresh, mirroring
+the CLI's ``jwt.rs`` logic so the CLI and SDK behave identically.
+
+OpenAPI Generator only rewrites the files it generates, so a hand-added module
+like this one (precedent: :mod:`hotdata.arrow`) survives regeneration. It is
+additionally listed in ``.openapi-generator-ignore`` as belt-and-suspenders.
+
+Key behaviors:
+
+* **Pass-through** -- a credential that already looks like a JWT (``eyJ``
+  prefix, matching the Gateway's own ``^Bearer eyJ.*`` detection) is returned
+  unchanged and never exchanged. Every other (opaque) credential is treated as
+  an API token and exchanged; set ``HOTDATA_DISABLE_JWT_EXCHANGE`` to force a
+  raw, non-JWT credential through as-is (local/dev setups, rollback).
+* **Opt-out** -- if ``HOTDATA_DISABLE_JWT_EXCHANGE`` is set to an affirmative
+  value (``1``/``true``/``yes``/``on``), the credential is always returned
+  as-is (hard escape hatch for rollout); ``0``/``false``/empty do not opt out.
+* **In-memory cache only** -- no disk writes. The server already de-duplicates
+  mints (keyed by ``sha256(api_token)``), so per-process caching is sufficient.
+* **Thread-safe** -- a :class:`threading.Lock` with single-flight mint covers
+  the case where a shared ``ApiClient`` is hit from many threads at once.
+* **Refresh, then re-mint** -- prefer the refresh token when available; on
+  refresh failure, re-mint from the held API token (always possible since the
+  SDK holds it). Matches the CLI.
+* **TLS/proxy reuse** -- the exchange call reuses the SDK's configured TLS,
+  client cert and proxy settings (see :func:`_pool_from_config`) so it behaves
+  like every other SDK request, with a bounded timeout so a stalled token
+  endpoint fails fast instead of hanging every call.
+"""
+
+import json
+import os
+import ssl
+import threading
+import time
+from urllib.parse import urlencode
+
+import urllib3
+
+_LEEWAY = 30          # refresh when <30s of life remains
+_TIMEOUT = 30.0       # seconds -- never let a stalled token endpoint hang every request
+_CLIENT_ID = "hotdata-python-sdk"
+
+# Env var that disables exchange entirely. Used as a hard escape hatch during
+# the rollout window and for local/dev setups. Only affirmative values opt out
+# (see _DISABLE_VALUES) so that ``=0`` / ``=false`` do NOT silently disable it.
+_DISABLE_ENV = "HOTDATA_DISABLE_JWT_EXCHANGE"
+_DISABLE_VALUES = {"1", "true", "yes", "on"}
+
+# The SOCKS schemes urllib3 routes through SOCKSProxyManager rather than the
+# plain ProxyManager. Mirrors hotdata/rest.py's SUPPORTED_SOCKS_PROXIES.
+_SUPPORTED_SOCKS_PROXIES = {"socks5", "socks5h", "socks4", "socks4a"}
+
+
+class TokenExchangeError(Exception):
+    """Raised when an API token cannot be exchanged for a JWT.
+
+    Surfacing ``invalid_grant`` (expired/revoked API token) here keeps the
+    failure clear instead of a confusing downstream 401.
+    """
+
+
+def _is_socks_proxy_url(url):
+    # Mirror hotdata/rest.py.is_socks_proxy_url so the exchange pool routes
+    # SOCKS proxies the same way the generated REST client does.
+    if url is None:
+        return False
+    split_section = url.split("://")
+    if len(split_section) < 2:
+        return False
+    return split_section[0].lower() in _SUPPORTED_SOCKS_PROXIES
+
+
+def _pool_from_config(configuration):
+    """Build a urllib3 pool manager from the SDK's TLS/proxy configuration.
+
+    Deliberately parallels ``RESTClientObject.__init__`` in
+    :mod:`hotdata.rest` so the token-exchange call honors the same
+    ``ssl_ca_cert`` / ``ca_cert_data`` / ``cert_file`` / ``key_file`` /
+    ``proxy`` / ``verify_ssl`` settings as every other SDK request. We build a
+    fresh, lightweight pool here rather than reaching into the ``ApiClient``'s
+    REST client (which the ``Configuration`` does not hold a reference to).
+    """
+    # cert_reqs -- honor verify_ssl exactly as the generated client does.
+    if configuration.verify_ssl:
+        cert_reqs = ssl.CERT_REQUIRED
+    else:
+        cert_reqs = ssl.CERT_NONE
+
+    pool_args = {
+        "cert_reqs": cert_reqs,
+        "ca_certs": configuration.ssl_ca_cert,
+        "cert_file": configuration.cert_file,
+        "key_file": configuration.key_file,
+        "ca_cert_data": configuration.ca_cert_data,
+    }
+    # Mirror rest.py's hostname/SNI handling so the exchange call does not
+    # silently fail for users who customize them (corporate MITM proxies set
+    # assert_hostname; some gateways require an explicit tls_server_name/SNI).
+    if configuration.assert_hostname is not None:
+        pool_args["assert_hostname"] = configuration.assert_hostname
+    if configuration.tls_server_name:
+        pool_args["server_hostname"] = configuration.tls_server_name
+    if configuration.socket_options is not None:
+        pool_args["socket_options"] = configuration.socket_options
+    # `retries`/`maxsize` are intentionally not mirrored: the exchange is a
+    # single bounded-timeout request that fails fast rather than retrying.
+
+    if configuration.proxy:
+        if _is_socks_proxy_url(configuration.proxy):
+            from urllib3.contrib.socks import SOCKSProxyManager
+            pool_args["proxy_url"] = configuration.proxy
+            pool_args["headers"] = configuration.proxy_headers
+            return SOCKSProxyManager(**pool_args)
+        pool_args["proxy_url"] = configuration.proxy
+        pool_args["proxy_headers"] = configuration.proxy_headers
+        return urllib3.ProxyManager(**pool_args)
+
+    return urllib3.PoolManager(**pool_args)
+
+
+class _TokenManager:
+    """Exchanges an API token for short-lived JWTs and keeps them fresh.
+
+    A credential that already looks like a JWT (``eyJ`` prefix) is passed
+    through unchanged, as is any credential when
+    ``HOTDATA_DISABLE_JWT_EXCHANGE`` is set; every other (opaque) API token is
+    exchanged.
+    """
+
+    def __init__(self, credential, configuration, pool=None):
+        self._credential = credential
+        self._config = configuration      # read host + TLS lazily at mint time
+        self._pool = pool                 # injected in tests; else built from config TLS
+        self._lock = threading.Lock()
+        self._jwt = None
+        self._exp = 0.0
+        self._refresh = None
+
+    @property
+    def _needs_exchange(self):
+        # Opt-out wins outright: an affirmative HOTDATA_DISABLE_JWT_EXCHANGE
+        # (1/true/yes/on) means send the credential as-is, never touching the
+        # token endpoint. Other values (incl. 0/false/empty) do not opt out.
+        if os.environ.get(_DISABLE_ENV, "").strip().lower() in _DISABLE_VALUES:
+            return False
+        # A compact JWT always starts with "eyJ" (base64 of '{"'), matching the
+        # Gateway's own ``^Bearer eyJ.*`` detection -- those already are what we
+        # want on the wire, so pass them through. Everything else is an opaque
+        # API token to be exchanged. (Hotdata API tokens are bare hex; the
+        # ``hd_`` prefix seen in docs/comments is cosmetic and not enforced by
+        # the server, so we must not gate on it.) Use HOTDATA_DISABLE_JWT_EXCHANGE
+        # to force a raw, non-JWT credential through unchanged (local/dev).
+        return isinstance(self._credential, str) and not self._credential.startswith("eyJ")
+
+    def bearer_value(self):
+        """Return a live JWT (exchanging + caching), or the credential as-is.
+
+        Returns the credential unchanged when it is already a JWT or when
+        exchange is disabled; otherwise returns a cached JWT, refreshing or
+        re-minting it when it is within ``_LEEWAY`` seconds of expiry.
+        """
+        if not self._needs_exchange:
+            return self._credential            # already a JWT (or opt-out) -> unchanged
+        with self._lock:
+            # Fast path: a still-valid cached JWT, no network call.
+            if self._jwt and time.time() < self._exp - _LEEWAY:
+                return self._jwt
+            # Prefer the refresh token; on failure, drop it and re-mint below.
+            if self._refresh and not self._mint(
+                {"grant_type": "refresh_token", "refresh_token": self._refresh}
+            ):
+                self._refresh = None           # refresh failed -> fall through to re-mint
+            # Re-mint from the held API token if we still lack a fresh JWT.
+            if not self._jwt or time.time() >= self._exp - _LEEWAY:
+                self._mint({"grant_type": "api_token", "api_token": self._credential})
+            return self._jwt
+
+    def _mint(self, params):
+        # Returns True on success. The refresh path is best-effort: ANY failure
+        # -- a non-200, a transport error, or a malformed/missing-token body --
+        # returns False so the caller re-mints from the held API token. An
+        # api_token mint instead raises TokenExchangeError on any failure, since
+        # there is no further fallback.
+        params["client_id"] = _CLIENT_ID
+        is_refresh = params["grant_type"] == "refresh_token"
+        try:
+            pool = self._pool or _pool_from_config(self._config)   # reuses ssl_ca_cert/cert/proxy
+            host = self._config.host.rstrip("/")                   # read host lazily -- may be set post-construct
+            resp = pool.request(
+                "POST",
+                f"{host}/v1/auth/jwt",
+                body=urlencode(params),
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                timeout=_TIMEOUT,
+            )
+            if resp.status != 200:
+                raise TokenExchangeError(
+                    f"token exchange failed: {resp.status} {resp.data[:200]!r}"
+                )
+            data = json.loads(resp.data)
+            token = data["access_token"]
+            expires_in = float(data.get("expires_in", 300))
+        except (
+            TokenExchangeError,
+            urllib3.exceptions.HTTPError,
+            ValueError,
+            TypeError,
+            KeyError,
+        ) as exc:
+            if is_refresh:
+                return False               # let caller re-mint from the API token
+            if isinstance(exc, TokenExchangeError):
+                raise
+            raise TokenExchangeError(f"token exchange failed: {exc!r}") from exc
+        self._jwt = token
+        self._exp = time.time() + expires_in
+        self._refresh = data.get("refresh_token") or self._refresh
+        return True
+
+
+__all__ = [
+    "TokenExchangeError",
+    "_TokenManager",
+    "_CLIENT_ID",
+    "_pool_from_config",
+]