tokenmeter-sdk 0.2.0__py3-none-any.whl

tokenmeter/_transport.py

@@ -0,0 +1,82 @@
+"""HTTP transport: POST /v1/events:batch (PRD §7.5). stdlib only -- no requests/httpx
+dependency for what a dozen lines of urllib does.
+"""
+from __future__ import annotations
+
+import gzip
+import json
+import logging
+import urllib.error
+import urllib.request
+from typing import List
+
+from ._ids import uuid7_str
+
+logger = logging.getLogger("tokenmeter")
+
+SDK_NAME = "python"
+SDK_VERSION = "0.2.0"
+SCHEMA_HASH = "v1"  # ponytail: bump when the wire event shape changes; not computed, just pinned
+
+
+class Transport:
+    def __init__(self, ingest_key: str, endpoint: str, timeout_s: float = 15.0) -> None:
+        self.ingest_key = ingest_key
+        self.endpoint = endpoint.rstrip("/") + "/v1/events:batch"
+        self.timeout_s = timeout_s
+
+    def send(self, events: List[dict], dropped_events: int) -> None:
+        """Raises on failure -- callers (Flusher) are responsible for swallowing.
+        Keeping this method "honest" (it raises) is what makes the
+        never-throws-into-host-code test meaningful: the guarantee is enforced at
+        the buffer/flusher boundary, not by this function lying about success.
+        """
+        body = {
+            "batch_id": uuid7_str(),
+            "sdk": {"name": SDK_NAME, "version": SDK_VERSION, "schema_hash": SCHEMA_HASH},
+            "dropped_since_last_ack": dropped_events,
+            "events": events,
+        }
+        payload = gzip.compress(json.dumps(body, default=str).encode("utf-8"))
+        req = urllib.request.Request(
+            self.endpoint,
+            data=payload,
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self.ingest_key}",
+                "Content-Type": "application/json",
+                "Content-Encoding": "gzip",
+                # PRD §7.1: drops are shipped visibly, never silent -- header too,
+                # so a proxy/log line can see it without parsing the gzip body.
+                "X-TL-Dropped-Events": str(dropped_events),
+            },
+        )
+        with urllib.request.urlopen(req, timeout=self.timeout_s) as resp:
+            if resp.status >= 300:
+                raise RuntimeError(f"tokenmeter ingest returned HTTP {resp.status}")
+
+    def ping(self) -> dict:
+        """Used by diagnose(): a zero-event batch, whose only purpose is to
+        surface auth failures loudly. Raises urllib.error.HTTPError on 401/403.
+
+        Ingest authenticates the key before it reads the body, then rejects an
+        empty events array with 400 invalid_envelope (packages/shared
+        batchEnvelope.ts). So that 400 is the expected answer for a valid key:
+        auth passed and nothing was written. Any other 400 still raises.
+        """
+        try:
+            self.send(events=[], dropped_events=0)
+            return {"ok": True, "endpoint": self.endpoint, "status": 202}
+        except urllib.error.HTTPError as e:
+            if e.code == 400 and _error_code(e) == "invalid_envelope":
+                return {"ok": True, "endpoint": self.endpoint, "status": 400}
+            raise
+
+
+def _error_code(e: urllib.error.HTTPError) -> str:
+    """The `error` field of an ingest error body ({"error": code, ...}), or ""."""
+    try:
+        body = json.loads(e.read().decode("utf-8"))
+    except Exception:
+        return ""
+    return body.get("error", "") if isinstance(body, dict) else ""