fingerly 0.1.0__py3-none-any.whl

fingerly/__init__.py

@@ -0,0 +1,45 @@
+"""Server-side Fingerly SDK: event reads and webhook verification.
+
+Two clients share one API: :class:`Fingerly` for synchronous code such as
+Django and Flask, and :class:`AsyncFingerly` for asyncio code such as FastAPI
+and Starlette.
+
+Example:
+    >>> from fingerly import Fingerly
+    >>> fingerly = Fingerly(secret_key=os.environ["FINGERLY_SECRET_KEY"])
+    >>> event = fingerly.events.get("01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4")
+"""
+
+from __future__ import annotations
+
+from ._client import AsyncEvents, AsyncFingerly, Events, Fingerly
+from ._errors import (
+    FingerlyAPIError,
+    FingerlyConnectionError,
+    FingerlyError,
+    FingerlyEventPendingError,
+    FingerlyTimeoutError,
+)
+from ._models import Event, EventPage, EventTrigger
+from ._proxy import FingerlyProxy, ProxyRequest
+from ._version import __version__
+from ._webhooks import verify_webhook
+
+__all__ = [
+    "AsyncEvents",
+    "AsyncFingerly",
+    "Event",
+    "EventPage",
+    "EventTrigger",
+    "Events",
+    "Fingerly",
+    "FingerlyAPIError",
+    "FingerlyConnectionError",
+    "FingerlyError",
+    "FingerlyEventPendingError",
+    "FingerlyProxy",
+    "FingerlyTimeoutError",
+    "ProxyRequest",
+    "__version__",
+    "verify_webhook",
+]

fingerly/_asgi.py

@@ -0,0 +1,220 @@
+"""The ASGI adapter: read a request, write a response.
+
+Every decision belongs to :class:`~fingerly._proxy.FingerlyProxy`. This module
+only translates between ASGI messages and the proxy's own request and response
+types, so the two standards cannot drift apart.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections.abc import Awaitable, MutableMapping
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+from ._proxy import BodyTooLargeError, Headers, ProxyRequest, ProxyResponse
+
+if TYPE_CHECKING:
+    from ._proxy import FingerlyProxy
+
+Scope = MutableMapping[str, Any]
+Receive = Callable[[], Awaitable[MutableMapping[str, Any]]]
+Send = Callable[[MutableMapping[str, Any]], Awaitable[None]]
+
+
+class ASGIProxy:
+    """ASGI application serving the browser SDK's same-origin requests.
+
+    Reached as ``proxy.asgi``. Route the dashboard-issued path to it under
+    FastAPI, Starlette, Django 3+, Quart, Litestar or any other ASGI
+    framework::
+
+        app.add_route("/k7x2qm4a", proxy.asgi)
+    """
+
+    def __init__(self, proxy: FingerlyProxy) -> None:
+        self._proxy = proxy
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Serves one ASGI connection."""
+        kind = scope.get("type")
+        if kind == "lifespan":
+            await _acknowledge_lifespan(receive, send)
+            return
+        if kind != "http":
+            # A websocket cannot be a browser SDK call; refuse without opening it.
+            if kind == "websocket":
+                await send({"type": "websocket.close", "code": 1000})
+            return
+
+        request = _request_from(scope)
+        screening = self._proxy.screen(request)
+        if screening.refusal is not None:
+            await _send(send, screening.refusal)
+            return
+
+        try:
+            body = await _read_body(receive, self._proxy.max_body_bytes)
+        except BodyTooLargeError:
+            await _send(send, self._proxy.too_large())
+            return
+        if body is None:
+            await self._answer_nobody(send)
+            return
+
+        response = await _forward_unless_gone(
+            self._proxy.aforward(screening, request, body), receive
+        )
+        if response is None:
+            await self._answer_nobody(send)
+        else:
+            await _send(send, response)
+
+    async def _answer_nobody(self, send: Send) -> None:
+        """Finishes a request whose visitor has already gone.
+
+        Nobody reads this, but an app that ends without a response is an error
+        to Starlette's ``BaseHTTPMiddleware``, which would log a traceback for
+        every tab closed during an identification.
+        """
+        # ASGI 2.4 lets a server refuse a send on a closed connection.
+        with contextlib.suppress(OSError):
+            await _send(send, self._proxy.client_gone())
+
+
+async def _forward_unless_gone(
+    forwarding: Awaitable[ProxyResponse], receive: Receive
+) -> Optional[ProxyResponse]:
+    """Forwards, but gives up the moment the visitor disconnects.
+
+    Without this, a visitor who left would still hold an upstream connection
+    until the API answered, so connections opened and dropped in a loop would
+    pile up upstream work nobody reads.
+
+    Returns:
+        The response, or None when the visitor went away first.
+    """
+    forward = asyncio.ensure_future(forwarding)
+    gone = asyncio.ensure_future(_disconnected(receive))
+    try:
+        await asyncio.wait({forward, gone}, return_when=asyncio.FIRST_COMPLETED)
+    finally:
+        if not forward.done() and not gone.done():
+            # Cancelled from outside: take both down with us.
+            forward.cancel()
+        gone.cancel()
+        await asyncio.gather(gone, return_exceptions=True)
+    if forward.done():
+        return forward.result()
+    forward.cancel()
+    await asyncio.gather(forward, return_exceptions=True)
+    return None
+
+
+async def _disconnected(receive: Receive) -> None:
+    """Returns when the server reports the client gone.
+
+    Once the body has been read, ``receive`` blocks until the client
+    disconnects. A server that answers it with anything else is not reporting
+    a disconnect, so this then waits until cancelled.
+    """
+    message = await receive()
+    if message.get("type") != "http.disconnect":
+        await asyncio.Event().wait()
+
+
+def _request_from(scope: Scope) -> ProxyRequest:
+    """Builds the neutral request from an ASGI scope."""
+    client = scope.get("client")
+    return ProxyRequest(
+        method=scope.get("method", ""),
+        path=_app_path(scope),
+        headers=Headers(
+            (name.decode("latin-1"), value.decode("latin-1"))
+            for name, value in scope.get("headers", ())
+        ),
+        peer_host=client[0] if client else None,
+        mount=str(scope.get("root_path", "")),
+        raw_path=_raw_path(scope),
+    )
+
+
+def _raw_path(scope: Scope) -> Optional[str]:
+    """The path as the client sent it, when the server reports it."""
+    raw = scope.get("raw_path")
+    if not isinstance(raw, (bytes, bytearray)):
+        return None
+    return bytes(raw).decode("latin-1").split("?", 1)[0]
+
+
+def _app_path(scope: Scope) -> str:
+    """Recovers the request path as the mounted application sees it.
+
+    ASGI servers disagree about ``path`` under a mount. Starlette 0.47 and
+    newer leave it whole and report the prefix separately in ``root_path``,
+    while older versions and some routers strip the prefix off it. Both are
+    permitted, so detect which one this is instead of assuming, and answer
+    with the application-relative path either way.
+
+    Keeping the mount in would break a deployment under a sub-URI, where
+    ``root_path`` also carries a prefix that the configured ``path`` knows
+    nothing about. This is the same rule Rack's ``PATH_INFO`` and ASP.NET
+    Core's ``Request.Path`` already follow.
+    """
+    path = str(scope.get("path", ""))
+    root_path = str(scope.get("root_path", ""))
+    if not root_path:
+        return path
+    if path == root_path:
+        return ""
+    return path[len(root_path) :] if path.startswith(root_path + "/") else path
+
+
+async def _read_body(receive: Receive, max_bytes: int) -> Optional[bytes]:
+    """Reads the request body without buffering more than the limit.
+
+    Returns:
+        The bytes, or None when the client disconnected first.
+
+    Raises:
+        BodyTooLargeError: As soon as the limit is passed, before the rest arrives.
+    """
+    chunks: list[bytes] = []
+    size = 0
+    while True:
+        message = await receive()
+        if message["type"] == "http.disconnect":
+            return None
+        chunk = message.get("body", b"")
+        size += len(chunk)
+        if size > max_bytes:
+            raise BodyTooLargeError
+        chunks.append(chunk)
+        if not message.get("more_body", False):
+            return b"".join(chunks)
+
+
+async def _send(send: Send, response: ProxyResponse) -> None:
+    """Writes one response as the two ASGI messages it is made of."""
+    await send(
+        {
+            "type": "http.response.start",
+            "status": response.status,
+            "headers": [
+                (name.encode("latin-1"), value.encode("latin-1"))
+                for name, value in response.headers
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": response.body})
+
+
+async def _acknowledge_lifespan(receive: Receive, send: Send) -> None:
+    """Answers startup and shutdown, so the app is safe to mount as a root."""
+    while True:
+        message = await receive()
+        if message["type"] == "lifespan.startup":
+            await send({"type": "lifespan.startup.complete"})
+        elif message["type"] == "lifespan.shutdown":
+            await send({"type": "lifespan.shutdown.complete"})
+            return

fingerly/_client.py

@@ -0,0 +1,368 @@
+"""The synchronous and asyncio clients, and the event reads they expose."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import warnings
+from collections.abc import Mapping
+from datetime import datetime
+from types import TracebackType
+from typing import Any, Optional, TypeVar, Union
+
+import httpx
+
+from ._config import (
+    DEFAULT_ENDPOINT,
+    Secret,
+    no_cookies,
+    normalize_api_version,
+    normalize_endpoint,
+    parse_key,
+    positive_seconds,
+)
+from ._errors import FingerlyAPIError, FingerlyConnectionError, FingerlyTimeoutError
+from ._http import MAX_RESPONSE_BYTES, AsyncPool, Reply, ResponseTooLargeError, SyncPool
+from ._models import Event, EventPage, parse_event, parse_page
+from ._transport import (
+    KeyAuth,
+    api_error,
+    decode_json,
+    event_path,
+    headers_for,
+    list_params,
+)
+
+DEFAULT_TIMEOUT = 10.0
+
+_Self = TypeVar("_Self", bound="_BaseFingerly")
+
+
+class _BaseFingerly:
+    """Configuration shared by :class:`Fingerly` and :class:`AsyncFingerly`."""
+
+    def __init__(
+        self,
+        secret_key: str,
+        endpoint: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        api_version: str = "v1",
+    ) -> None:
+        """Validates every option before any client is built.
+
+        Args:
+            secret_key: A server-only key, ``fly_sk_{environment}_…``. Its
+                prefix names the environment read.
+            endpoint: Overrides the Fingerly API origin, for a local API.
+            timeout: One deadline, in seconds, over the whole request:
+                connecting, sending, the response headers and the body.
+            api_version: API route version; the server must support it.
+
+        Raises:
+            TypeError: If any option is invalid. Nothing is sent until then.
+        """
+        # Validate the key even when an endpoint is given, so a public, proxy
+        # or management key can never reach an API that would accept it.
+        parse_key(secret_key, "sk")
+        origin = DEFAULT_ENDPOINT if endpoint is None else normalize_endpoint(endpoint)
+        self._secret_key = Secret(secret_key)
+        self._base_url = f"{origin}/api/{normalize_api_version(api_version)}"
+        self._timeout = positive_seconds(timeout, "timeout")
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(endpoint={self._base_url!r}, "
+            f"secret_key={self._secret_key!r})"
+        )
+
+    def _interpret(self, response: Reply) -> Mapping[str, Any]:
+        """Turns a response into a decoded body or the matching error.
+
+        Raises:
+            FingerlyAPIError: On any non-2xx response, redirects included:
+                requests never follow one, so a 3xx is not an answer.
+        """
+        if not 200 <= response.status < 300:
+            raise api_error(
+                response.status,
+                response.body,
+                self._secret_key,
+                response.headers.get("retry-after"),
+            )
+        return decode_json(response.body, response.status)
+
+
+class Events:
+    """Synchronous event reads. Reached as ``fingerly.events``."""
+
+    def __init__(self, client: Fingerly) -> None:
+        self._client = client
+
+    def get(self, request_id: str) -> Event:
+        """Fetches one event by request id.
+
+        Args:
+            request_id: The ``request_id`` returned by identification.
+
+        Raises:
+            FingerlyEventPendingError: ``404 event_pending`` when the
+                request id was accepted but the event is not recorded yet;
+                ``retry_after`` says when to try again. Not retried here.
+            FingerlyAPIError: ``404 event_not_found`` when the request id was
+                never issued or the event is past retention, and any other
+                non-2xx answer.
+            FingerlyTimeoutError: If the request exceeds the client timeout.
+        """
+        return parse_event(self._client._request(event_path(request_id)))
+
+    def list(
+        self,
+        from_: Union[datetime, str, None] = None,
+        to: Union[datetime, str, None] = None,
+        page: int = 1,
+        limit: int = 10,
+        visitor: Optional[str] = None,
+        level: Optional[str] = None,
+    ) -> EventPage:
+        """Lists events within the retention window, newest first.
+
+        Args:
+            from_: Start of the window. Defaults to 24 hours ago.
+            to: End of the window. Defaults to now.
+            page: 1-based page number.
+            limit: Rows per page, at most 200.
+            visitor: Restrict to one exact visitor id.
+            level: Restrict to ``low``, ``medium`` or ``high``.
+
+        Raises:
+            TypeError: If a bound, page or limit is unusable.
+            FingerlyAPIError: On any non-2xx response.
+        """
+        params = list_params(from_, to, page, limit, visitor, level)
+        return parse_page(self._client._request("/events", params))
+
+
+class AsyncEvents:
+    """Asyncio event reads. Reached as ``fingerly.events``."""
+
+    def __init__(self, client: AsyncFingerly) -> None:
+        self._client = client
+
+    async def get(self, request_id: str) -> Event:
+        """Fetches one event by request id.
+
+        See :meth:`Events.get`; this coroutine takes the same arguments.
+        """
+        return parse_event(await self._client._request(event_path(request_id)))
+
+    async def list(
+        self,
+        from_: Union[datetime, str, None] = None,
+        to: Union[datetime, str, None] = None,
+        page: int = 1,
+        limit: int = 10,
+        visitor: Optional[str] = None,
+        level: Optional[str] = None,
+    ) -> EventPage:
+        """Lists events within the retention window, newest first.
+
+        See :meth:`Events.list`; this coroutine takes the same arguments.
+        """
+        params = list_params(from_, to, page, limit, visitor, level)
+        return parse_page(await self._client._request("/events", params))
+
+
+class Fingerly(_BaseFingerly):
+    """The Fingerly server SDK for synchronous code.
+
+    Use it in Django, Flask, scripts and Celery tasks. Build one client and
+    reuse it: each holds a pooled connection. Secret keys belong in
+    server-side code only.
+
+    Example:
+        >>> with Fingerly(secret_key=os.environ["FINGERLY_SECRET_KEY"]) as fingerly:
+        ...     page = fingerly.events.list(level="high", limit=50)
+    """
+
+    def __init__(
+        self,
+        secret_key: str,
+        endpoint: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        api_version: str = "v1",
+        transport: Optional[httpx.BaseTransport] = None,
+        limits: Optional[httpx.Limits] = None,
+    ) -> None:
+        """See :class:`_BaseFingerly` for the shared arguments.
+
+        Args:
+            transport: Replacement httpx transport, for tests or a host with
+                its own HTTP stack. It is used as given, as one pool.
+            limits: Connections this client may hold across its pools. The
+                default lets 256 concurrent reads reuse connections.
+        """
+        super().__init__(secret_key, endpoint, timeout, api_version)
+
+        def build(pool_transport: Optional[httpx.BaseTransport]) -> httpx.Client:
+            return httpx.Client(
+                base_url=self._base_url,
+                headers=headers_for(),
+                auth=KeyAuth(self._secret_key),
+                timeout=self._timeout,
+                follow_redirects=False,
+                cookies=no_cookies(),
+                transport=pool_transport,
+            )
+
+        self._pool = SyncPool(build, self._timeout, limits, transport)
+        self.events = Events(self)
+
+    def close(self) -> None:
+        """Closes the pooled connections. Safe to call more than once."""
+        self._pool.close()
+
+    def __enter__(self: _Self) -> _Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None:
+        self.close()
+
+    def _request(
+        self, path: str, params: Optional[Mapping[str, str]] = None
+    ) -> Mapping[str, Any]:
+        """Performs one GET and decodes its body. Never retries.
+
+        Raises:
+            FingerlyTimeoutError: If the request exceeds the client timeout.
+            FingerlyConnectionError: If the API could not be reached.
+            FingerlyAPIError: On any non-2xx response.
+        """
+        _warn_if_on_an_event_loop()
+        try:
+            reply = self._pool.request("GET", path, params=params)
+        except httpx.TimeoutException as error:
+            raise FingerlyTimeoutError() from error
+        except httpx.HTTPError as error:
+            raise FingerlyConnectionError("Could not reach the Fingerly API") from error
+        except ResponseTooLargeError as error:
+            raise _too_large(error) from None
+        return self._interpret(reply)
+
+
+class AsyncFingerly(_BaseFingerly):
+    """The Fingerly server SDK for asyncio code.
+
+    Use it in FastAPI, Starlette, aiohttp and Quart. Build one client per
+    event loop and reuse it.
+
+    Example:
+        >>> async with AsyncFingerly(secret_key=key) as fingerly:
+        ...     event = await fingerly.events.get(request_id)
+    """
+
+    def __init__(
+        self,
+        secret_key: str,
+        endpoint: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        api_version: str = "v1",
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+        limits: Optional[httpx.Limits] = None,
+    ) -> None:
+        """See :class:`_BaseFingerly` for the shared arguments.
+
+        Args:
+            transport: Replacement httpx transport, for tests or a host with
+                its own HTTP stack. It is used as given, as one pool.
+            limits: Connections this client may hold across its pools. The
+                default lets 256 concurrent reads reuse connections.
+        """
+        super().__init__(secret_key, endpoint, timeout, api_version)
+
+        def build(
+            pool_transport: Optional[httpx.AsyncBaseTransport],
+        ) -> httpx.AsyncClient:
+            return httpx.AsyncClient(
+                base_url=self._base_url,
+                headers=headers_for(),
+                auth=KeyAuth(self._secret_key),
+                timeout=self._timeout,
+                follow_redirects=False,
+                cookies=no_cookies(),
+                transport=pool_transport,
+            )
+
+        self._pool = AsyncPool(build, self._timeout, limits, transport)
+        self.events = AsyncEvents(self)
+
+    async def aclose(self) -> None:
+        """Closes the pooled connections. Safe to call more than once."""
+        await self._pool.aclose()
+
+    async def __aenter__(self: _Self) -> _Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None:
+        await self.aclose()
+
+    async def _request(
+        self, path: str, params: Optional[Mapping[str, str]] = None
+    ) -> Mapping[str, Any]:
+        """Performs one GET and decodes its body. Never retries.
+
+        Raises:
+            FingerlyTimeoutError: If the request exceeds the client timeout.
+            FingerlyConnectionError: If the API could not be reached.
+            FingerlyAPIError: On any non-2xx response.
+        """
+        try:
+            reply = await self._pool.request("GET", path, params=params)
+        except httpx.TimeoutException as error:
+            raise FingerlyTimeoutError() from error
+        except httpx.HTTPError as error:
+            raise FingerlyConnectionError("Could not reach the Fingerly API") from error
+        except ResponseTooLargeError as error:
+            raise _too_large(error) from None
+        return self._interpret(reply)
+
+
+_warned_about_event_loop = threading.Event()
+
+
+def _warn_if_on_an_event_loop() -> None:
+    """Warns, once per process, when the sync client blocks an event loop.
+
+    Called from ``async def`` code, every read stops the loop, and with it
+    every other request on that worker, until the API answers.
+    """
+    if _warned_about_event_loop.is_set():
+        return
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return
+    _warned_about_event_loop.set()
+    warnings.warn(
+        "Fingerly is blocking a running event loop; use AsyncFingerly in async code",
+        RuntimeWarning,
+        stacklevel=4,
+    )
+
+
+def _too_large(error: ResponseTooLargeError) -> FingerlyAPIError:
+    """The error for a response body over the cap; the body is never read."""
+    return FingerlyAPIError(
+        f"Fingerly API response is larger than {MAX_RESPONSE_BYTES // 1048576} MiB",
+        error.status,
+        code="response_too_large",
+    )