restless-sdk 0.1.0__tar.gz

restless_sdk-0.1.0/LICENSE

@@ -0,0 +1,18 @@
+Copyright © 2026 Restless
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

restless_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: restless-sdk
+Version: 0.1.0
+Summary: Capture API traffic and send it to Restless. WSGI and ASGI: Flask, Django, FastAPI, Starlette.
+Author: Restless
+License: MIT
+Project-URL: Homepage, https://restless.ai
+Keywords: restless,api,logging,observability,wsgi,asgi,flask,fastapi
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# restless-sdk
+
+Capture your API traffic and send it to [Restless](https://restless.ai).
+
+Works with any **WSGI** app (Flask, Django, Pyramid, Bottle) or **ASGI** app
+(FastAPI, Starlette, Quart). Python 3.8+. No dependencies.
+
+## Install
+
+```sh
+pip install restless-sdk
+```
+
+## Use
+
+```python
+import os
+import restless
+
+client = restless.Restless(os.environ["RESTLESS_KEY"])
+
+@client.setup
+def _(request):
+    return {
+        "api_key": client.mask(request.headers.get("authorization")),
+        "owner": {
+            # Permanent and immutable. A workspace id or database primary
+            # key, never an API key, email, or anything else that rotates:
+            # the dashboard pins a project's whole log history to this.
+            "id": workspace_id_for(request),
+            # Runs once per owner id, then caches. Put the expensive lookup
+            # here, not in the fields above.
+            "enrich": lambda owner_id: {
+                "label": db.workspaces.get(owner_id).name,
+                "email": db.workspaces.get(owner_id).admin_emails,
+            },
+        },
+    }
+```
+
+Then wrap your app:
+
+```python
+# Flask / Django / any WSGI
+app.wsgi_app = client.wsgi(app.wsgi_app)
+
+# FastAPI / Starlette / any ASGI
+app = client.asgi(app)
+```
+
+## The request view
+
+The callback receives a read-only `RequestInfo`, identical under WSGI and
+ASGI, so the same callback works whichever you are on.
+
+| accessor | what |
+|---|---|
+| `request.header(name)` | One header, case-insensitive. `request["authorization"]` is an alias. |
+| `request.headers` | All of them, as a case-insensitive mapping. |
+| `request.method` | `"GET"`, `"POST"`, ... |
+| `request.path` | Path, including any mount prefix. |
+| `request.query_string` | Raw query string, without the `?`. |
+| `request.url` | Full URL, as the capture records it. |
+| `request.environ` / `request.scope` | The raw WSGI environ or ASGI scope; the other is `None`. |
+
+Nothing is hidden by the wrapper: anything it does not model is still on
+`request.environ` / `request.scope`.
+
+`request.route` is normally `None` here. The callback runs before your
+application, so no router has matched yet. The captured log still gets the
+real route, read after the response.
+
+## What you get
+
+- **Lazy owner enrichment.** The `enrich` callback runs on the first request
+  from each owner id and then caches, so 100 requests from one workspace do
+  not mean 100 database lookups.
+- **Safe by default.** `Authorization`, `Cookie`, `password`, `token`, `ssn`
+  and friends are redacted before anything leaves your process. Bodies with
+  nothing to redact are passed through untouched, so your payloads are not
+  reserialized on the way out.
+- **Error triage.** 4xx/5xx responses get `x-log-url` and `x-debug` headers
+  and a `debug` block in the JSON body. If someone attaches a "next steps"
+  message to an error in the dashboard, the SDK injects it as
+  `debug.recovery`, read synchronously from an in-process cache, never
+  blocking the response on a network call.
+- **Blocking.** Return `{"block": True}` from the setup callback to reject a
+  request before your handler runs.
+
+## Never breaks your API
+
+Observability must not take down a production request path. Upload failures,
+callback exceptions, unserializable bodies and malformed input are all caught
+and swallowed (surfaced only under `DEBUG=restless`). Uploads happen on a
+background thread.
+
+## Environment variables
+
+| variable | purpose |
+|---|---|
+| `RESTLESS_KEY` | Your project API key, if you do not pass one explicitly. |
+| `RESTLESS_BASE_URL` | Override the ingest URL (self-hosted or staging). |
+| `DEBUG=restless` | Print upload diagnostics to stderr. |
+
+## Conformance
+
+This SDK implements version 1.0.0 of the Restless SDK Contract at level L2,
+and is verified against the shared cross-language conformance vectors. See
+[CONFORMANCE.md](./CONFORMANCE.md).
+
+## License
+MIT

restless_sdk-0.1.0/README.md

@@ -0,0 +1,112 @@
+# restless-sdk
+
+Capture your API traffic and send it to [Restless](https://restless.ai).
+
+Works with any **WSGI** app (Flask, Django, Pyramid, Bottle) or **ASGI** app
+(FastAPI, Starlette, Quart). Python 3.8+. No dependencies.
+
+## Install
+
+```sh
+pip install restless-sdk
+```
+
+## Use
+
+```python
+import os
+import restless
+
+client = restless.Restless(os.environ["RESTLESS_KEY"])
+
+@client.setup
+def _(request):
+    return {
+        "api_key": client.mask(request.headers.get("authorization")),
+        "owner": {
+            # Permanent and immutable. A workspace id or database primary
+            # key, never an API key, email, or anything else that rotates:
+            # the dashboard pins a project's whole log history to this.
+            "id": workspace_id_for(request),
+            # Runs once per owner id, then caches. Put the expensive lookup
+            # here, not in the fields above.
+            "enrich": lambda owner_id: {
+                "label": db.workspaces.get(owner_id).name,
+                "email": db.workspaces.get(owner_id).admin_emails,
+            },
+        },
+    }
+```
+
+Then wrap your app:
+
+```python
+# Flask / Django / any WSGI
+app.wsgi_app = client.wsgi(app.wsgi_app)
+
+# FastAPI / Starlette / any ASGI
+app = client.asgi(app)
+```
+
+## The request view
+
+The callback receives a read-only `RequestInfo`, identical under WSGI and
+ASGI, so the same callback works whichever you are on.
+
+| accessor | what |
+|---|---|
+| `request.header(name)` | One header, case-insensitive. `request["authorization"]` is an alias. |
+| `request.headers` | All of them, as a case-insensitive mapping. |
+| `request.method` | `"GET"`, `"POST"`, ... |
+| `request.path` | Path, including any mount prefix. |
+| `request.query_string` | Raw query string, without the `?`. |
+| `request.url` | Full URL, as the capture records it. |
+| `request.environ` / `request.scope` | The raw WSGI environ or ASGI scope; the other is `None`. |
+
+Nothing is hidden by the wrapper: anything it does not model is still on
+`request.environ` / `request.scope`.
+
+`request.route` is normally `None` here. The callback runs before your
+application, so no router has matched yet. The captured log still gets the
+real route, read after the response.
+
+## What you get
+
+- **Lazy owner enrichment.** The `enrich` callback runs on the first request
+  from each owner id and then caches, so 100 requests from one workspace do
+  not mean 100 database lookups.
+- **Safe by default.** `Authorization`, `Cookie`, `password`, `token`, `ssn`
+  and friends are redacted before anything leaves your process. Bodies with
+  nothing to redact are passed through untouched, so your payloads are not
+  reserialized on the way out.
+- **Error triage.** 4xx/5xx responses get `x-log-url` and `x-debug` headers
+  and a `debug` block in the JSON body. If someone attaches a "next steps"
+  message to an error in the dashboard, the SDK injects it as
+  `debug.recovery`, read synchronously from an in-process cache, never
+  blocking the response on a network call.
+- **Blocking.** Return `{"block": True}` from the setup callback to reject a
+  request before your handler runs.
+
+## Never breaks your API
+
+Observability must not take down a production request path. Upload failures,
+callback exceptions, unserializable bodies and malformed input are all caught
+and swallowed (surfaced only under `DEBUG=restless`). Uploads happen on a
+background thread.
+
+## Environment variables
+
+| variable | purpose |
+|---|---|
+| `RESTLESS_KEY` | Your project API key, if you do not pass one explicitly. |
+| `RESTLESS_BASE_URL` | Override the ingest URL (self-hosted or staging). |
+| `DEBUG=restless` | Print upload diagnostics to stderr. |
+
+## Conformance
+
+This SDK implements version 1.0.0 of the Restless SDK Contract at level L2,
+and is verified against the shared cross-language conformance vectors. See
+[CONFORMANCE.md](./CONFORMANCE.md).
+
+## License
+MIT

restless_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "restless-sdk"
+version = "0.1.0"
+description = "Capture API traffic and send it to Restless. WSGI and ASGI: Flask, Django, FastAPI, Starlette."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Restless" }]
+keywords = ["restless", "api", "logging", "observability", "wsgi", "asgi", "flask", "fastapi"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://restless.ai"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+# install.md ships INSIDE the package, not just in the sdist. The `api` CLI
+# points installing agents at it with
+#   python -c "import restless, pathlib; print(pathlib.Path(restless.__file__).parent)"
+# and pip installs the wheel, so a root-level file (or a MANIFEST.in entry,
+# which only reaches the sdist) would leave that pointer resolving to nothing.
+# The Node SDK ships its equivalent the same way, via package.json `files`.
+restless = ["py.typed", "install.md"]

restless_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

restless_sdk-0.1.0/src/restless/__init__.py

@@ -0,0 +1,161 @@
+"""Restless Python SDK.
+
+Capture your API traffic and send it to Restless.
+
+    import restless
+
+    client = restless.Restless(os.environ["RESTLESS_KEY"])
+
+    @client.setup
+    def _(request):
+        return {
+            "api_key": client.mask(request.headers.get("authorization")),
+            "owner": {
+                "id": current_workspace_id(),
+                "enrich": lambda owner_id: {"label": lookup_name(owner_id)},
+            },
+        }
+
+    app.wsgi_app = client.wsgi(app.wsgi_app)
+
+Conformance: implements spec version 1.0.0 of the Restless SDK Contract at
+level L2. Run the shared harness against ``python -m restless._conformance``
+to verify. See CONFORMANCE.md.
+"""
+
+import os
+import sys
+from typing import Any, Callable, Dict, List, Optional
+
+from ._capture import CaptureEngine
+from ._mask import mask
+from ._request import Headers, RequestInfo
+from ._request_id import (
+    format_request_id,
+    is_valid_request_id,
+    new_request_id,
+    strip_request_id_prefix,
+)
+from ._settings import load_settings, resolve_api
+from ._uploader import is_test_run, resolve_base_url
+from ._version import CONFORMANCE_LEVEL, SDK_NAME, SDK_VERSION, SPEC_VERSION
+
+__all__ = [
+    "Restless",
+    "restless",
+    "mask",
+    "RequestInfo",
+    "Headers",
+    "new_request_id",
+    "format_request_id",
+    "strip_request_id_prefix",
+    "is_valid_request_id",
+    "SDK_NAME",
+    "SDK_VERSION",
+    "SPEC_VERSION",
+    "CONFORMANCE_LEVEL",
+]
+
+__version__ = SDK_VERSION
+
+
+class Restless:
+    """A Restless client.
+
+    Naming here is idiomatic Python rather than a transliteration of the Node
+    SDK. CONTRACT.md section 14 makes the public surface explicitly
+    per-language: what is normative is the SEMANTIC surface (construct with
+    an explicit key, register a per-request callback, mask a key, flush), not
+    the method names.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        api: Optional[str] = None,
+        redact: Optional[Dict[str, List[str]]] = None,
+        base_url: Optional[str] = None,
+        transport: Optional[Callable] = None,
+    ):
+        # CONFIG-001. Explicit key wins, then RESTLESS_KEY, then README_API_KEY.
+        resolved = (
+            api_key
+            or os.environ.get("RESTLESS_KEY")
+            or os.environ.get("README_API_KEY")
+            or ""
+        )
+        # CONFIG-002. Capture still runs; only upload is disabled.
+        if not resolved and not is_test_run():
+            print(
+                "[restless] no API key found - set RESTLESS_KEY in your environment "
+                "or pass it to Restless(). Captured requests will not be uploaded.",
+                file=sys.stderr,
+            )
+
+        request_id_prefix = None
+        settings_redact = None
+        entry = resolve_api(load_settings(), api)  # CONFIG-013/014 may raise
+        if entry:
+            request_id_prefix = entry.get("requestIdPrefix")
+            settings_redact = entry.get("redact")
+
+        # REDACT-015. Both sources are additive on top of the defaults.
+        merged: Dict[str, List[str]] = {}
+        for field in ("headers", "bodyKeys", "queryParams"):
+            merged[field] = list((settings_redact or {}).get(field) or []) + list(
+                (redact or {}).get(field) or []
+            )
+
+        self.engine = CaptureEngine(
+            api_key=resolved,
+            base_url=resolve_base_url(base_url),
+            request_id_prefix=request_id_prefix,
+            redact=merged,
+            transport=transport,
+        )
+
+    # ------------------------------------------------------------ public API
+
+    @staticmethod
+    def mask(api_key: Optional[str]) -> Optional[str]:
+        """Mask an end-user API key (MASK-001).
+
+        Pass the raw header value straight through. Do NOT substitute a
+        placeholder like ``"anonymous"``: its last 4 characters would become
+        the tail and cluster unrelated callers together.
+        """
+        return mask(api_key)
+
+    def setup(self, callback: Callable) -> Callable:
+        """Register the per-request callback. Usable as a decorator.
+
+        The callback receives the framework-native request object and returns
+        a dict: ``api_key`` (masked), ``owner`` (``id`` plus ``enrich``), and
+        optionally ``block``.
+        """
+        self.engine.set_callback(callback)
+        return callback
+
+    def flush(self) -> None:
+        """Force-upload the queued batch. Call before process exit if you
+        care about in-flight captures."""
+        self.engine.flush()
+
+    # ------------------------------------------------------------- adapters
+
+    def wsgi(self, app: Callable) -> Callable:
+        """Wrap a WSGI app (Flask, Django, Pyramid, Bottle)."""
+        from .adapters.wsgi import wrap_wsgi
+
+        return wrap_wsgi(app, self.engine)
+
+    def asgi(self, app: Callable) -> Callable:
+        """Wrap an ASGI app (FastAPI, Starlette, Quart)."""
+        from .adapters.asgi import wrap_asgi
+
+        return wrap_asgi(app, self.engine)
+
+
+def restless(api_key: Optional[str] = None, **kwargs: Any) -> Restless:
+    """Functional constructor, mirroring the Node SDK's ``restless(key)``."""
+    return Restless(api_key, **kwargs)

restless_sdk-0.1.0/src/restless/_caches.py

@@ -0,0 +1,128 @@
+"""In-process caches.
+
+Implements CONTRACT.md section 11.
+"""
+
+import time
+from typing import Any, Dict, Optional
+
+# CACHE-004, CACHE-014
+_ENRICH_TTL_MS = 60 * 60 * 1000
+_RECOVERY_TTL_MS = 60 * 60 * 1000
+_RECOVERY_NEGATIVE_TTL_MS = 5 * 60 * 1000
+
+
+def _now_ms() -> float:
+    return time.monotonic() * 1000.0
+
+
+class EnrichCache:
+    """CACHE-001..007.
+
+    Stores the enriched VALUE, not merely a freshness flag (CACHE-003). Every
+    upload has to carry owner metadata, including uploads that skipped the
+    callback, because the ingest cannot backfill it: without the value, every
+    request after the first would land in the dashboard as unauthenticated.
+    """
+
+    def __init__(self, ttl_ms: float = _ENRICH_TTL_MS):
+        self._cache: Dict[str, Any] = {}
+        self._ttl_ms = ttl_ms
+
+    def get(self, key: str) -> Optional[Dict[str, Any]]:
+        entry = self._cache.get(key)
+        if entry is None:
+            return None
+        value, ts = entry
+        if _now_ms() - ts > self._ttl_ms:
+            self._cache.pop(key, None)
+            return None
+        return value
+
+    def set(self, key: str, value: Dict[str, Any]) -> None:
+        self._cache[key] = (value, _now_ms())
+
+    def invalidate(self, key: str) -> None:
+        """CACHE-006. Next request from this key re-runs enrich."""
+        self._cache.pop(key, None)
+
+    def clear(self) -> None:
+        self._cache.clear()
+
+    def size(self) -> int:
+        return len(self._cache)
+
+
+class RecoveryCache:
+    """CACHE-010..015. Fingerprint key to recovery message.
+
+    Every read is synchronous and in-process. The lookup sits on the hot path
+    of every 4xx/5xx, so it never performs I/O and never blocks the response;
+    a cold miss simply injects nothing.
+
+    "No message for this fingerprint" is itself cached (as ``None``) so a cold
+    miss does not stay a cold miss on every subsequent request. The negative
+    TTL is shorter so a freshly-attached dashboard message starts working
+    within minutes.
+    """
+
+    def __init__(
+        self,
+        ttl_ms: float = _RECOVERY_TTL_MS,
+        negative_ttl_ms: float = _RECOVERY_NEGATIVE_TTL_MS,
+    ):
+        self._cache: Dict[str, Any] = {}
+        self._ttl_ms = ttl_ms
+        self._negative_ttl_ms = negative_ttl_ms
+
+    _MISS = object()
+
+    def get(self, key: str) -> Any:
+        """Returns the message, ``None`` for a confirmed absence, or ``_MISS``.
+
+        The three-way result matters: ``None`` means the server told us there
+        is no message (do not ask again yet), while ``_MISS`` means we have
+        never asked.
+        """
+        entry = self._cache.get(key)
+        if entry is None:
+            return self._MISS
+        message, ts = entry
+        ttl = self._negative_ttl_ms if message is None else self._ttl_ms
+        if _now_ms() - ts > ttl:
+            self._cache.pop(key, None)
+            return self._MISS
+        return message
+
+    def set(self, key: str, message: Optional[str]) -> None:
+        self._cache[key] = (message, _now_ms())
+
+    def lookup(self, key: str) -> Optional[str]:
+        """CACHE-010. The hot-path read: a message to inject, or None."""
+        value = self.get(key)
+        return value if isinstance(value, str) else None
+
+    def invalidate(self, key: str) -> None:
+        self._cache.pop(key, None)
+
+    def clear(self) -> None:
+        self._cache.clear()
+
+    def size(self) -> int:
+        return len(self._cache)
+
+
+class Blocklist:
+    """Masked keys to reject. O(1) lookup, per-process state."""
+
+    def __init__(self) -> None:
+        self._blocked = set()
+
+    def replace(self, masked_keys) -> None:
+        self._blocked = set(masked_keys)
+
+    def has(self, masked_key: Optional[str]) -> bool:
+        return bool(masked_key) and masked_key in self._blocked
+
+    def size(self) -> int:
+        return len(self._blocked)