021-python-clients 0.1.0__py3-none-any.whl

clients_021/_observe.py

@@ -0,0 +1,106 @@
+"""One CLIENT span and two instruments per call, under a stable dependency name.
+
+The `db` family reuses the instruments 021-python-observability already creates for SQL
+(`db.client.operation.*`), so Redis and Postgres share dashboards. `messaging` (SQS, email),
+`storage` (S3) and `crypto` (KMS) get their own pair on the same meter. Attributes are
+bounded: dependency, operation, status and error.type; never keys, URLs, bodies or ids.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import AsyncGenerator, Callable
+from contextlib import asynccontextmanager
+from typing import Literal
+from weakref import WeakKeyDictionary
+
+from observability_021 import Observability, get_logger
+from opentelemetry.metrics import Counter, Histogram
+from opentelemetry.trace import SpanKind, StatusCode
+
+from clients_021.errors import DependencyUnavailable
+
+Family = Literal["db", "messaging", "storage", "crypto"]
+# Returns the reason when an exception means "the dependency failed", None for a bug.
+Classifier = Callable[[BaseException], str | None]
+
+logger = get_logger(__name__)
+_UNITS = {
+    "db": "{operation}",
+    "messaging": "{operation}",
+    "storage": "{operation}",
+    "crypto": "{operation}",
+}
+_cache: WeakKeyDictionary[Observability, dict[Family, tuple[Counter, Histogram]]] = (
+    WeakKeyDictionary()
+)
+
+
+def instruments(obs: Observability, family: Family) -> tuple[Counter, Histogram]:
+    per_obs = _cache.setdefault(obs, {})
+    pair = per_obs.get(family)
+    if pair is None:
+        if family == "db":
+            pair = (obs.db_requests, obs.db_duration)
+        else:
+            meter = obs.meter
+            pair = (
+                meter.create_counter(f"{family}.client.operation.count", unit=_UNITS[family]),
+                meter.create_histogram(f"{family}.client.operation.duration", unit="s"),
+            )
+        per_obs[family] = pair
+    return pair
+
+
+@asynccontextmanager
+async def observed(
+    obs: Observability,
+    *,
+    family: Family,
+    system: dict[str, str],
+    dependency: str,
+    operation: str,
+    classify: Classifier,
+) -> AsyncGenerator[None]:
+    """Wraps one call. Dependency failures leave as DependencyUnavailable; bugs as they are."""
+    attributes: dict[str, str] = {"dependency": dependency, "operation": operation}
+    count, duration = instruments(obs, family)
+    started = time.perf_counter()
+    tracer = obs.tracer
+    with tracer.start_as_current_span(
+        f"{dependency} {operation}",
+        kind=SpanKind.CLIENT,
+        attributes={**system, **attributes},
+        record_exception=False,
+        set_status_on_exception=False,
+    ) as span:
+        try:
+            yield
+        except asyncio.CancelledError:
+            attributes["status"] = "error"
+            attributes["error.type"] = "cancelled"
+            span.set_status(StatusCode.ERROR)
+            span.set_attributes(attributes)
+            raise
+        except BaseException as error:
+            reason = classify(error)
+            attributes["status"] = "error"
+            attributes["error.type"] = reason or type(error).__name__
+            span.set_status(StatusCode.ERROR)
+            span.set_attributes(attributes)
+            logger.warning(
+                "dependency.call_failed",
+                dependency=dependency,
+                operation=operation,
+                error_type=attributes["error.type"],
+            )
+            if reason is None:
+                raise
+            raise DependencyUnavailable(dependency, operation, reason) from error
+        else:
+            attributes["status"] = "ok"
+            span.set_attributes(attributes)
+        finally:
+            count.add(1, attributes)
+            duration.record(time.perf_counter() - started, attributes)

clients_021/email/__init__.py

@@ -0,0 +1,16 @@
+"""Transactional email behind one protocol: Resend (no extra) or SES (`clients_021.email.ses`).
+
+    from clients_021.email import EmailMessage, EmailSender, ResendSender
+
+    email: EmailSender = ResendSender(obs, settings.resend_api_key)
+    await email.send(EmailMessage(sender=..., to=..., subject=..., text=...))
+
+Every sender records `messaging.client.operation.*` with `operation=send`, raises
+DependencyUnavailable when retrying later may work and EmailRejected when the provider refused
+the message or the credentials. Addresses, subjects and bodies are never recorded.
+"""
+
+from clients_021.email._message import EmailMessage, EmailRejected, EmailSender
+from clients_021.email.resend import ResendSender
+
+__all__ = ["EmailMessage", "EmailRejected", "EmailSender", "ResendSender"]

clients_021/email/_message.py

@@ -0,0 +1,77 @@
+"""What every email sender shares: the message, the sender protocol and the rejection."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Protocol
+
+# Resend and SES accept the same tag syntax: ASCII letters, digits, `_` and `-`, ≤ 256 chars.
+_TAG = re.compile(r"[A-Za-z0-9_-]{1,256}")
+# A provider error code is a short identifier; anything else is reported as `unknown`.
+_CODE = re.compile(r"[A-Za-z][A-Za-z0-9_.-]{0,63}")
+MAX_IDEMPOTENCY_KEY = 256
+
+
+@dataclass(frozen=True)
+class EmailMessage:
+    """One email. `to` and `reply_to` accept one address or several; bodies stay out of repr."""
+
+    sender: str
+    to: Sequence[str]
+    subject: str
+    text: str | None = field(default=None, repr=False)
+    html: str | None = field(default=None, repr=False)
+    reply_to: Sequence[str] = ()
+    # Provider tags for analytics and webhooks: bounded names and values, never personal data.
+    tags: Mapping[str, str] = field(default_factory=dict[str, str])
+
+    def __post_init__(self) -> None:
+        if not self.sender:
+            raise ValueError("sender is required")
+        to = _addresses(self.to, "to")
+        if not to:
+            raise ValueError("to needs at least one recipient")
+        if self.text is None and self.html is None:
+            raise ValueError("text or html is required")
+        if not all(_TAG.fullmatch(k) and _TAG.fullmatch(v) for k, v in self.tags.items()):
+            raise ValueError("tag names and values must be 1-256 ASCII letters, digits, _ or -")
+        object.__setattr__(self, "to", to)
+        object.__setattr__(self, "reply_to", _addresses(self.reply_to, "reply_to"))
+        object.__setattr__(self, "tags", dict(self.tags))
+
+
+def _addresses(value: str | Sequence[str], name: str) -> tuple[str, ...]:
+    addresses = (value,) if isinstance(value, str) else tuple(value)
+    if not all(addresses):
+        raise ValueError(f"{name} contains an empty address")
+    return addresses
+
+
+def check_idempotency_key(key: str | None) -> str | None:
+    if key is not None and not 1 <= len(key) <= MAX_IDEMPOTENCY_KEY:
+        raise ValueError(f"idempotency_key must be 1-{MAX_IDEMPOTENCY_KEY} characters")
+    return key
+
+
+class EmailSender(Protocol):
+    async def send(self, message: EmailMessage, *, idempotency_key: str | None = None) -> str:
+        """Hands the message to the provider and returns the provider's message id."""
+        ...
+
+
+class EmailRejected(Exception):  # noqa: N818 - the name says what the caller handles
+    """The provider refused the message or the credentials; sending it again will not help.
+
+    `status` is the HTTP status and `code` the provider's error name (`validation_error`,
+    `MessageRejected`, ...). Like DependencyUnavailable it never carries addresses, subjects,
+    bodies or the provider's message, so it is safe to log; the chained exception is not.
+    """
+
+    def __init__(self, dependency: str, status: int, code: str) -> None:
+        code = code if _CODE.fullmatch(code) else "unknown"
+        super().__init__(f"{dependency} send: rejected ({status} {code})")
+        self.dependency = dependency
+        self.status = status
+        self.code = code

clients_021/email/resend.py

@@ -0,0 +1,143 @@
+"""Resend, observed: one `send` per message over Resend's HTTP API.
+
+    from clients_021.email import EmailMessage, ResendSender
+
+    email = ResendSender(obs, settings.resend_api_key)
+    message_id = await email.send(
+        EmailMessage(sender="021 <hola@from021.io>", to="ana@example.com",
+                     subject="Your code", text="..."),
+        idempotency_key=f"login-code:{attempt_id}",
+    )
+
+Needs no extra. Calls record `messaging.client.operation.*` (`operation=send`) and a
+`<dependency> send` span with `messaging.system=resend`; the HTTP request below it records
+`http.client.request.*` through 021-python-observability's transport. No trace headers are
+sent to Resend. The request is sent once: with an idempotency key, retrying after
+DependencyUnavailable within Resend's 24 hours cannot send the email twice.
+429, 5xx, timeouts and connection failures raise DependencyUnavailable; any other non-2xx
+raises EmailRejected with the status and Resend's error name.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, cast
+
+import httpx
+from observability_021 import Observability
+from observability_021.config import identifier
+
+from clients_021 import __version__
+from clients_021._observe import observed
+from clients_021.email._message import EmailMessage, EmailRejected, check_idempotency_key
+from clients_021.errors import DependencyUnavailable
+from clients_021.http import HttpClient
+
+URL = "https://api.resend.com/emails"
+SYSTEM = {"messaging.system": "resend"}
+# Added by the observed transport; Resend is a third-party API, so they never leave.
+_TRACE_HEADERS = ("traceparent", "tracestate", "x-request-id")
+
+
+class _Status(Exception):
+    """A status that means Resend let us down; observed() turns it into DependencyUnavailable."""
+
+    def __init__(self, status: int) -> None:
+        super().__init__(f"status {status}")
+        self.status = status
+
+
+def _classify(error: BaseException) -> str | None:
+    if isinstance(error, DependencyUnavailable):
+        return error.reason
+    if isinstance(error, _Status):
+        return "throttled" if error.status == 429 else f"status_{error.status}"
+    return None
+
+
+def _error_name(body: bytes) -> str:
+    try:
+        data = json.loads(body)
+    except ValueError:
+        return "unknown"
+    name = cast(dict[str, Any], data).get("name") if isinstance(data, dict) else None
+    return name if isinstance(name, str) else "unknown"
+
+
+class _WithoutTraceHeaders(httpx.AsyncBaseTransport):
+    def __init__(self, transport: httpx.AsyncBaseTransport) -> None:
+        self._transport = transport
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        for name in _TRACE_HEADERS:
+            request.headers.pop(name, None)
+        return await self._transport.handle_async_request(request)
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+
+class ResendSender:
+    def __init__(
+        self,
+        obs: Observability,
+        api_key: str,
+        *,
+        dependency: str = "resend",
+        timeout_seconds: float = 10.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._obs = obs
+        self.dependency = identifier(dependency)
+        self._headers = {
+            "Authorization": f"Bearer {api_key}",
+            # Resend rejects requests without a User-Agent.
+            "User-Agent": f"021-python-clients/{__version__}",
+        }
+        inner = transport if transport is not None else httpx.AsyncHTTPTransport()
+        self._http = HttpClient(
+            obs, timeout_seconds=timeout_seconds, retries=0, transport=_WithoutTraceHeaders(inner)
+        )
+
+    async def send(self, message: EmailMessage, *, idempotency_key: str | None = None) -> str:
+        """Returns Resend's email id."""
+        headers = dict(self._headers)
+        key = check_idempotency_key(idempotency_key)
+        if key is not None:
+            headers["Idempotency-Key"] = key
+        body: dict[str, Any] = {
+            "from": message.sender,
+            "to": list(message.to),
+            "subject": message.subject,
+        }
+        if message.text is not None:
+            body["text"] = message.text
+        if message.html is not None:
+            body["html"] = message.html
+        if message.reply_to:
+            body["reply_to"] = list(message.reply_to)
+        if message.tags:
+            body["tags"] = [{"name": name, "value": value} for name, value in message.tags.items()]
+        async with observed(
+            self._obs,
+            family="messaging",
+            system=SYSTEM,
+            dependency=self.dependency,
+            operation="send",
+            classify=_classify,
+        ):
+            response = await self._http.request(
+                "POST", URL, dependency=self.dependency, headers=headers, json=body
+            )
+            status = response.status_code
+            if status == 429 or status >= 500:
+                raise _Status(status)
+            if not 200 <= status < 300:
+                raise EmailRejected(self.dependency, status, _error_name(response.body))
+            email_id: str = response.json()["id"]
+        return email_id
+
+    async def aclose(self) -> None:
+        await self._http.aclose()

clients_021/email/ses.py

@@ -0,0 +1,119 @@
+"""Amazon SES (API v2), observed: one `send` per message.
+
+    from clients_021.email import EmailMessage
+    from clients_021.email.ses import SesSender
+
+    email = SesSender.create(obs, region="us-east-1", configuration_set="transactional")
+    message_id = await email.send(EmailMessage(sender=..., to=..., subject=..., text=...))
+
+Needs the `aws` extra. Calls record `messaging.client.operation.*` (`operation=send`) and a
+`<dependency> send` span with `messaging.system=aws_ses`. Timeouts, connection failures,
+throttling (`TooManyRequestsException`) and 5xx raise DependencyUnavailable. Any other SES
+error (`MessageRejected`, an unverified sender, access denied, a missing configuration set)
+raises EmailRejected with the status and SES error code, chained to the botocore error, so a
+service handles one rejection type whichever sender it is configured with.
+SES has no idempotency key: the argument is validated like Resend's and then ignored, so
+deduplicate in the caller when a retry must not send twice.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+import boto3
+from botocore.exceptions import ClientError
+from observability_021 import Observability
+from observability_021.config import identifier
+
+from clients_021 import _aws
+from clients_021._observe import observed
+from clients_021.email._message import EmailMessage, EmailRejected, check_idempotency_key
+
+if TYPE_CHECKING:
+    from mypy_boto3_sesv2 import SESV2Client
+else:
+    SESV2Client = Any
+
+SYSTEM = {"messaging.system": "aws_ses"}
+_UTF8 = "UTF-8"
+
+
+class SesSender:
+    def __init__(
+        self,
+        obs: Observability,
+        client: SESV2Client,
+        *,
+        configuration_set: str | None = None,
+        dependency: str = "ses",
+    ) -> None:
+        self._obs = obs
+        self._client = client
+        self._configuration_set = configuration_set
+        self.dependency = identifier(dependency)
+
+    @classmethod
+    def create(
+        cls,
+        obs: Observability,
+        *,
+        region: str | None = None,
+        endpoint_url: str | None = None,
+        configuration_set: str | None = None,
+        dependency: str = "ses",
+        timeout_seconds: float = 10.0,
+    ) -> SesSender:
+        client: SESV2Client = boto3.client(  # pyright: ignore[reportUnknownMemberType]
+            "sesv2",
+            region_name=region,
+            endpoint_url=endpoint_url,
+            config=_aws.config(
+                connect_seconds=min(timeout_seconds, 3.0), read_seconds=timeout_seconds
+            ),
+        )
+        return cls(obs, client, configuration_set=configuration_set, dependency=dependency)
+
+    async def send(self, message: EmailMessage, *, idempotency_key: str | None = None) -> str:
+        """Returns the SES message id. `idempotency_key` is accepted for the protocol only."""
+        check_idempotency_key(idempotency_key)
+        body: dict[str, Any] = {}
+        if message.text is not None:
+            body["Text"] = {"Data": message.text, "Charset": _UTF8}
+        if message.html is not None:
+            body["Html"] = {"Data": message.html, "Charset": _UTF8}
+        request: dict[str, Any] = {
+            "FromEmailAddress": message.sender,
+            "Destination": {"ToAddresses": list(message.to)},
+            "Content": {
+                "Simple": {"Subject": {"Data": message.subject, "Charset": _UTF8}, "Body": body}
+            },
+        }
+        if message.reply_to:
+            request["ReplyToAddresses"] = list(message.reply_to)
+        if message.tags:
+            request["EmailTags"] = [
+                {"Name": name, "Value": value} for name, value in message.tags.items()
+            ]
+        if self._configuration_set is not None:
+            request["ConfigurationSetName"] = self._configuration_set
+        async with observed(
+            self._obs,
+            family="messaging",
+            system=SYSTEM,
+            dependency=self.dependency,
+            operation="send",
+            classify=_aws.classify,
+        ):
+            try:
+                response = await asyncio.to_thread(self._client.send_email, **request)
+            except ClientError as error:
+                if _aws.classify(error) is not None:
+                    raise
+                status = int(error.response.get("ResponseMetadata", {}).get("HTTPStatusCode", 0))
+                raise EmailRejected(self.dependency, status, _aws.error_code(error)) from error
+        return response["MessageId"]
+
+    async def aclose(self) -> None:
+        """Release the underlying SDK connection pools after in-flight calls finish."""
+        await asyncio.to_thread(self._client.close)

clients_021/errors.py

@@ -0,0 +1,20 @@
+"""The one failure type every client raises when the service it calls lets it down."""
+
+from __future__ import annotations
+
+
+class DependencyUnavailable(Exception):  # noqa: N818 - the name says what the caller handles
+    """The dependency timed out, refused the connection, throttled or failed (5xx).
+
+    Retrying later may work. It never carries keys, payloads, URLs or provider messages, so
+    its message and fields are safe to log and to map to a 503. The chained provider
+    exception is not sanitized and must not be logged. Errors that mean the request itself is
+    wrong (access denied, a missing bucket, a bad command) are not wrapped: they are bugs
+    or misconfiguration, and keep their original type.
+    """
+
+    def __init__(self, dependency: str, operation: str, reason: str) -> None:
+        super().__init__(f"{dependency} {operation}: {reason}")
+        self.dependency = dependency
+        self.operation = operation
+        self.reason = reason

clients_021/http.py

@@ -0,0 +1,131 @@
+"""Outbound HTTP: one httpx client per dependency, mandatory timeouts and bounded retries.
+
+    from clients_021.http import HttpClient
+
+    http = HttpClient(obs, timeout_seconds=10)
+    response = await http.request("GET", url, dependency="identity-provider")
+
+Every call goes through 021-python-observability's transport: `http.client.request.*`
+under the `dependency` name, a CLIENT span, and `traceparent` / `x-request-id` sent along.
+Methods in IDEMPOTENT_METHODS are retried on transport errors and 502/503/504 with
+backoff; POST and PATCH are sent once (send an Idempotency-Key and retry in the caller if
+the other side supports it). A transport failure after the last attempt raises
+DependencyUnavailable; any HTTP status is returned to the caller to judge.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json as jsonlib
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import httpx
+from observability_021 import Observability
+
+from clients_021.errors import DependencyUnavailable
+
+HttpMethod = Literal["GET", "HEAD", "OPTIONS", "POST", "PUT", "PATCH", "DELETE"]
+# Safe to send twice (RFC 9110, section 9.2.2): the only methods retried.
+IDEMPOTENT_METHODS: frozenset[HttpMethod] = frozenset({"GET", "HEAD", "OPTIONS", "PUT", "DELETE"})
+RETRY_STATUS = frozenset({502, 503, 504})
+
+
+@dataclass(frozen=True)
+class HttpResponse:
+    status_code: int
+    headers: Mapping[str, str]
+    body: bytes
+
+    def json(self) -> Any:
+        return jsonlib.loads(self.body)
+
+
+class HttpClient:
+    def __init__(
+        self,
+        obs: Observability,
+        *,
+        timeout_seconds: float,
+        retries: int = 2,
+        backoff_seconds: float = 0.2,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        if not math.isfinite(timeout_seconds) or timeout_seconds <= 0:
+            raise ValueError("timeout_seconds must be finite and greater than 0")
+        if type(retries) is not int or retries < 0:
+            raise ValueError("retries must be a non-negative integer")
+        if not math.isfinite(backoff_seconds) or backoff_seconds < 0:
+            raise ValueError("backoff_seconds must be finite and non-negative")
+        self._obs = obs
+        self._timeout = httpx.Timeout(timeout_seconds, connect=min(timeout_seconds, 3.0))
+        self._retries = retries
+        self._backoff = backoff_seconds
+        self._transport = transport
+        self._clients: dict[str, httpx.AsyncClient] = {}
+
+    def _client(self, dependency: str) -> httpx.AsyncClient:
+        # One client per dependency, so every call is measured under a fixed name.
+        client = self._clients.get(dependency)
+        if client is None:
+            client = httpx.AsyncClient(
+                timeout=self._timeout,
+                follow_redirects=False,
+                transport=self._obs.async_httpx_transport(
+                    dependency=dependency, transport=self._transport
+                ),
+            )
+            self._clients[dependency] = client
+        return client
+
+    async def request(
+        self,
+        method: HttpMethod,
+        url: str,
+        *,
+        dependency: str,
+        headers: Mapping[str, str] | None = None,
+        json: Any = None,
+        form: Mapping[str, str] | None = None,
+        content: bytes | None = None,
+    ) -> HttpResponse:
+        if sum(value is not None for value in (json, form, content)) > 1:
+            raise ValueError("provide only one of json, form or content")
+        attempts = 1 + (self._retries if method in IDEMPOTENT_METHODS else 0)
+        for attempt in range(attempts):
+            last = attempt == attempts - 1
+            try:
+                response = await self._client(dependency).request(
+                    method,
+                    url,
+                    headers=dict(headers or {}),
+                    json=json,
+                    data=dict(form) if form is not None else None,
+                    content=content,
+                )
+            except (
+                httpx.TimeoutException,
+                httpx.NetworkError,
+                httpx.RemoteProtocolError,
+                httpx.ProxyError,
+            ) as error:
+                if last:
+                    reason = (
+                        "timeout"
+                        if isinstance(error, httpx.TimeoutException)
+                        else "connection_error"
+                    )
+                    raise DependencyUnavailable(dependency, method, reason) from error
+            else:
+                if response.status_code not in RETRY_STATUS or last:
+                    return HttpResponse(
+                        response.status_code, dict(response.headers), response.content
+                    )
+            await asyncio.sleep(self._backoff * 2**attempt)
+        raise AssertionError("unreachable")
+
+    async def aclose(self) -> None:
+        await asyncio.gather(*(client.aclose() for client in self._clients.values()))
+        self._clients.clear()