insider-python 0.1.0__py3-none-any.whl

insider/transport.py

@@ -0,0 +1,213 @@
+"""
+Background HTTP transport.
+
+The capture path is on the customer's request thread. Sending the beacon
+on that thread would add a network round-trip to every error response —
+that is exactly what we will not do. Instead:
+
+  1. `submit(beacon)` puts the beacon on a bounded in-memory queue
+     (`queue.Queue.put_nowait`).
+  2. If the queue is full we drop the beacon and increment a counter.
+     The customer's thread never blocks waiting on us.
+  3. A daemon worker thread loops on `queue.get()` and POSTs each beacon
+     to the beam endpoint. Any error during the POST is caught, logged,
+     and the beacon discarded. No retries in v1 (see docs/python-sdk-plan
+     -> Non-goals).
+  4. `atexit` registers `close()` so short-lived scripts and management
+     commands drain before exit (bounded by `flush_timeout`).
+
+The transport is the *only* place inside the SDK that talks to the
+network. Everything else is in-process work.
+"""
+
+from __future__ import annotations
+
+import json
+import queue
+import threading
+import time
+from typing import Any, Dict, Optional
+
+import urllib3
+
+from ._version import __version__
+from .dsn import DSN
+from .safety import debug
+
+
+_SENTINEL = object()
+
+
+class BackgroundTransport:
+    """
+    Bounded queue + daemon worker thread + urllib3 connection pool.
+
+    Public methods are thread-safe. `submit` is the only hot-path call.
+    """
+
+    def __init__(
+        self,
+        dsn: DSN,
+        *,
+        queue_size: int = 1000,
+        flush_timeout: float = 2.0,
+        connect_timeout: float = 2.0,
+        read_timeout: float = 5.0,
+    ) -> None:
+        self._dsn = dsn
+        self._flush_timeout = flush_timeout
+        self._queue: "queue.Queue[Any]" = queue.Queue(maxsize=queue_size)
+        self._pool: Optional[urllib3.PoolManager] = urllib3.PoolManager(
+            timeout=urllib3.Timeout(connect=connect_timeout, read=read_timeout),
+            retries=False,
+            maxsize=4,
+            block=False,
+        )
+        self._closed = threading.Event()
+
+        # Bookkeeping the customer can read for telemetry-on-telemetry.
+        self.submitted_total: int = 0
+        self.sent_total: int = 0
+        self.dropped_full: int = 0
+        self.dropped_error: int = 0
+
+        self._worker = threading.Thread(
+            target=self._run,
+            name="insider-transport",
+            daemon=True,
+        )
+        self._worker.start()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def submit(self, beacon: Dict[str, Any]) -> bool:
+        """
+        Enqueue a beacon. Returns True if accepted, False if dropped.
+        Never blocks the caller. Never raises.
+        """
+        if self._closed.is_set():
+            self.dropped_full += 1
+            return False
+        try:
+            self._queue.put_nowait(beacon)
+        except queue.Full:
+            self.dropped_full += 1
+            debug("queue full; dropping beacon")
+            return False
+        self.submitted_total += 1
+        return True
+
+    def flush(self, timeout: Optional[float] = None) -> bool:
+        """
+        Block until the queue drains or `timeout` elapses. Returns True
+        if drained, False otherwise. `timeout=None` uses `flush_timeout`.
+        """
+        deadline = time.monotonic() + (
+            timeout if timeout is not None else self._flush_timeout
+        )
+        while time.monotonic() < deadline:
+            if self._queue.unfinished_tasks == 0:
+                return True
+            time.sleep(0.01)
+        return self._queue.unfinished_tasks == 0
+
+    def close(self, timeout: Optional[float] = None) -> None:
+        """
+        Stop accepting new beacons, drain the queue, join the worker.
+        Idempotent. Bounded by `timeout` (defaults to `flush_timeout`).
+        """
+        if self._closed.is_set():
+            return
+        self._closed.set()
+        # Push sentinel even if queue is full — use put with timeout so we
+        # don't hang shutdown forever if a runaway producer is filling it.
+        try:
+            self._queue.put(_SENTINEL, timeout=1.0)
+        except queue.Full:
+            debug("close: queue full, sentinel may be late")
+        wait = timeout if timeout is not None else self._flush_timeout
+        self._worker.join(timeout=wait)
+        if self._pool is not None:
+            try:
+                self._pool.clear()
+            except Exception as exc:
+                debug(f"pool clear failed: {exc}")
+            self._pool = None
+
+    # ------------------------------------------------------------------
+    # Worker loop
+    # ------------------------------------------------------------------
+
+    def _run(self) -> None:
+        # Outer try guarantees the worker thread never dies on an unexpected
+        # exception. Losing the worker would silently leak beacons forever.
+        while True:
+            try:
+                item = self._queue.get()
+            except Exception as exc:
+                debug(f"queue.get failed: {exc}")
+                continue
+
+            try:
+                if item is _SENTINEL:
+                    return
+                self._send_one(item)
+            except Exception as exc:
+                self.dropped_error += 1
+                debug(f"send loop swallowed {type(exc).__name__}: {exc}")
+            finally:
+                try:
+                    self._queue.task_done()
+                except Exception:
+                    pass
+
+    def _send_one(self, beacon: Dict[str, Any]) -> None:
+        if self._pool is None:
+            self.dropped_error += 1
+            return
+        try:
+            body = json.dumps(beacon, default=str, ensure_ascii=False).encode("utf-8")
+        except Exception as exc:
+            # If we can't even serialize, ship a minimal fallback so the
+            # event isn't lost entirely.
+            self.dropped_error += 1
+            debug(f"json encode failed: {exc}; shipping minimal envelope")
+            body = json.dumps(
+                {
+                    "kind": "error",
+                    "level": "error",
+                    "occurred_at": beacon.get("occurred_at"),
+                    "message": "<beacon could not be serialized>",
+                    "payload": {"truncated": True, "encode_error": str(exc)},
+                },
+                default=str,
+            ).encode("utf-8")
+
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self._dsn.token}",
+            "User-Agent": f"insider-python/{__version__}",
+            "X-Insider-SDK": f"python/{__version__}",
+        }
+
+        try:
+            resp = self._pool.urlopen(
+                "POST",
+                self._dsn.beam_url,
+                body=body,
+                headers=headers,
+                retries=False,
+                preload_content=True,
+            )
+        except Exception as exc:
+            self.dropped_error += 1
+            debug(f"POST failed: {type(exc).__name__}: {exc}")
+            return
+
+        if resp.status == 202:
+            self.sent_total += 1
+        else:
+            self.dropped_error += 1
+            debug(f"server returned {resp.status}; dropping beacon")

insider_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: insider-python
+Version: 0.1.0
+Summary: Python SDK for Insider — ship Beacons to your Insider server.
+Author: Insider
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Insider-Inc/insider-python
+Keywords: insider,telemetry,errors,monitoring,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: urllib3>=1.26
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == "django"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-django>=4.8; extra == "dev"
+Requires-Dist: django>=4.2; extra == "dev"
+
+# insider-python
+
+The Python SDK for [Insider](https://insider.moraks.cloud/).
+
+Beam Beacons from your Python service to your Insider server with a
+one-line setup. No runtime overhead on your request path. Never raises
+into your code, no matter what.
+
+## Install
+
+```bash
+pip install insider-python
+```
+
+For the Django integration:
+
+```bash
+pip install "insider-python[django]"
+```
+
+## Quick start
+
+### Plain Python
+
+```python
+import insider
+
+insider.init(
+    dsn="https://<beacon_token>@insider.example.com/<project_uuid>",
+    environment="production",
+    release="1.2.3",
+)
+
+try:
+    risky()
+except Exception as exc:
+    insider.capture_exception(exc)
+
+insider.capture_message("cache miss spiked", level="warning")
+```
+
+### Django
+
+Add the integration to `INSTALLED_APPS` and configure via settings:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "insider.contrib.django",
+]
+
+MIDDLEWARE = [
+    # ...
+    "insider.contrib.django.middleware.InsiderMiddleware",
+]
+
+INSIDER_DSN = "https://<beacon_token>@insider.example.com/<project_uuid>"
+INSIDER_ENVIRONMENT = "production"
+INSIDER_RELEASE = "1.2.3"
+```
+
+That's the whole setup. Every unhandled exception in a view is now a
+Beacon in your dashboard.
+
+## Configuration
+
+Order of precedence (first wins):
+
+1. Keyword args to `insider.init(...)`.
+2. `INSIDER_*` environment variables.
+3. Django settings (when the Django integration is active).
+4. Hard-coded defaults.
+
+If no DSN is found anywhere, the SDK enters **disabled mode**: every
+public call is a no-op, no thread starts, no socket opens.
+
+| Option | Default | Notes |
+|--------|---------|-------|
+| `dsn` | env `INSIDER_DSN` | If absent, SDK is disabled |
+| `environment` | `"production"` | Top-level Beacon field |
+| `release` | `None` | Top-level Beacon field |
+| `send_default_pii` | `False` | Required to capture `user.id`, request bodies |
+| `before_send` | `None` | `(beacon) -> beacon | None` hook |
+| `scrub_keys` | `None` | Extra keys to filter (added to the default deny-list) |
+| `in_app_include` | `None` | Filename prefixes considered "your code" |
+| `transport_queue_size` | `1000` | Bounded; drops on overflow |
+| `transport_flush_timeout` | `2.0` | Seconds. Used by `close()` / `flush()` |
+| `debug` | `False` | Print SDK's own warnings to stderr |
+
+## Promise
+
+The SDK never raises into your code. Every public function catches
+`Exception` at its boundary; if something goes wrong inside the SDK,
+you get nothing back and a debug log (if enabled). Your app keeps
+running.
+
+## License
+
+MIT

insider_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+insider/__init__.py,sha256=DgDevX2wcy9lonZiHaq5dJLieD3_fp3p6l3lotuTpGE,781
+insider/_envelope.py,sha256=nxMumrnB_KXF51aOmSoPVlvJ_On7cQx2GS96YM64CB4,6583
+insider/_version.py,sha256=oPP6-Q8wh-D2EeEaYkiVm6AZMC4ipVMVwcqq2RJp7u8,246
+insider/client.py,sha256=NacSGY0FycPogWa9m6sZYMNWhn9BWAdr_sXjbhpmIRc,10797
+insider/dsn.py,sha256=S8BbRhmKKKU1N6W8cpMSQoyDO_EuUJ1PkcjhGrrf5hw,3009
+insider/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+insider/safety.py,sha256=mtzzWLujuvmd24W2VtVcMGO_81GPBbB2tYuVqU2KsuI,1910
+insider/scope.py,sha256=F1eMWt6uu14uBdncc5DC6Lh735EPcUv1yF4prBi--pc,1708
+insider/scrubbing.py,sha256=U8N3MS5VtDUNpIWN4PZ8bvrPqmjRRXq5hWGXxzoF5Gw,2853
+insider/stacktrace.py,sha256=i_Okdtu6ZLRicl7YBFzxe3B1likDIS4tK7GJG2iWKcw,5048
+insider/transport.py,sha256=8ncFb3C0LgF2hMRoj_fhxj49NIUD6hsVAHfPZKtNcn4,7292
+insider/contrib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+insider/contrib/django/__init__.py,sha256=UMGrJgVO-FqszZo9Cviw7oWS8PLdXVHt3hwXZ_YMj8A,680
+insider/contrib/django/apps.py,sha256=WOKn-fNp_SSPNyt8xXz_fXYVhkyepafAi1uxpWC9_Bo,1947
+insider/contrib/django/middleware.py,sha256=JWnP_p4JBGyKQMswevjWxoUBSE5o4xgLKYOm1Zrb30g,5365
+insider_python-0.1.0.dist-info/METADATA,sha256=xNxX_dGung9se-WnsdnbUJprcwYHZFXdB0lqB9YEKWI,3531
+insider_python-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+insider_python-0.1.0.dist-info/top_level.txt,sha256=g_YKp2jCaaefmasZ2nOa9capm0X8q2sAWI_eEClKIos,8
+insider_python-0.1.0.dist-info/RECORD,,

insider_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

insider_python-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+insider