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

clients_021/httpx2.py

@@ -0,0 +1,93 @@
+"""An observed httpx2 transport, for SDKs built on httpx2 (Anthropic, OpenAI and others).
+
+    from anthropic import AsyncAnthropic, DefaultAsyncHttpxClient
+    from clients_021.httpx2 import ObservedTransport
+
+    transport = ObservedTransport(obs, dependency="anthropic")
+    client = AsyncAnthropic(http_client=DefaultAsyncHttpxClient(transport=transport))
+
+Needs the `httpx2` extra. Records the same `http.client.request.*` instruments and CLIENT
+span as 021-python-observability's httpx transport, under `dependency`, with method,
+status and a bounded error type; never the URL. Trace context is not sent by default: these
+are third-party APIs (`propagate=True` sends `traceparent` to services you own).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+
+import httpx2
+from observability_021 import Observability
+from observability_021.config import identifier
+from opentelemetry.trace import SpanKind, StatusCode
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "POST", "PUT", "PATCH", "DELETE"})
+
+
+class ObservedTransport(httpx2.AsyncBaseTransport):
+    def __init__(
+        self,
+        obs: Observability,
+        *,
+        dependency: str,
+        transport: httpx2.AsyncBaseTransport | None = None,
+        propagate: bool = False,
+    ) -> None:
+        self._obs = obs
+        self._dependency = identifier(dependency)
+        self._transport = transport if transport is not None else httpx2.AsyncHTTPTransport()
+        self._propagate = propagate
+
+    async def handle_async_request(self, request: httpx2.Request) -> httpx2.Response:
+        method = request.method if request.method in _METHODS else "_OTHER"
+        attributes: dict[str, str | int] = {
+            "dependency": self._dependency,
+            "http.request.method": method,
+        }
+        started = time.perf_counter()
+        tracer = self._obs.tracer
+        with tracer.start_as_current_span(
+            f"HTTP {self._dependency}",
+            kind=SpanKind.CLIENT,
+            attributes=attributes,
+            record_exception=False,
+            set_status_on_exception=False,
+        ) as span:
+            if self._propagate:
+                # Replace the whole pair: the new parent may have no tracestate.
+                request.headers.pop("traceparent", None)
+                request.headers.pop("tracestate", None)
+                carrier: dict[str, str] = {}
+                TraceContextTextMapPropagator().inject(carrier)
+                for key, value in carrier.items():
+                    request.headers[key] = value
+            try:
+                response = await self._transport.handle_async_request(request)
+            except BaseException as error:
+                attributes["error.type"] = (
+                    "cancelled"
+                    if isinstance(error, asyncio.CancelledError)
+                    else "timeout"
+                    if isinstance(error, httpx2.TimeoutException)
+                    else "connection_error"
+                    if isinstance(
+                        error, httpx2.NetworkError | httpx2.RemoteProtocolError | httpx2.ProxyError
+                    )
+                    else type(error).__name__
+                )
+                span.set_status(StatusCode.ERROR)
+                raise
+            else:
+                attributes["http.response.status_code"] = response.status_code
+                if response.status_code >= 400:
+                    span.set_status(StatusCode.ERROR)
+                return response
+            finally:
+                span.set_attributes(attributes)
+                self._obs.client_requests.add(1, attributes)
+                self._obs.client_duration.record(time.perf_counter() - started, attributes)
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()

clients_021/kms.py

@@ -0,0 +1,178 @@
+"""AWS KMS, observed: encrypt, decrypt and data keys, always bound to an encryption context.
+
+    from clients_021.kms import KmsClient
+
+    keys = KmsClient.create(obs, settings.session_key_id, region="us-east-1")
+    context = {"purpose": "session", "tenant": tenant_id}
+    blob = await keys.encrypt(secret, context=context)
+    secret = await keys.decrypt(blob, context=context)
+    envelope = await keys.seal(large_payload, context=context)   # any size, AES-256-GCM
+    large_payload = await keys.unseal(envelope, context=context)
+
+Needs the `aws` extra. The encryption context is required: decrypting with another context
+fails, so a ciphertext only opens for the purpose it was made for. KMS logs it in CloudTrail
+in plaintext: it identifies the purpose, it is never a secret. Calls record
+`crypto.client.operation.*` with `operation` (`encrypt`, `decrypt`, `generate_data_key`) and
+a span with `rpc.service=KMS`; never key ids, contexts, plaintext or ciphertext.
+Timeouts, connection failures, throttling and 5xx raise DependencyUnavailable. Access
+denied, a disabled key, a wrong context or a tampered ciphertext (`InvalidCiphertextException`)
+and a ciphertext from another key (`IncorrectKeyException`) keep their botocore type.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import struct
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+import boto3
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from observability_021 import Observability
+from observability_021.config import identifier
+
+from clients_021 import _aws
+from clients_021._observe import observed
+
+if TYPE_CHECKING:
+    from mypy_boto3_kms import KMSClient
+else:
+    KMSClient = Any
+
+SYSTEM = {"rpc.system": "aws-api", "rpc.service": "KMS"}
+# Envelope layout: version (1 byte), wrapped key length (2 bytes, big endian), wrapped key,
+# nonce (12 bytes), AES-256-GCM ciphertext and tag. The header and context are the AAD.
+_ENVELOPE = struct.Struct(">BH")
+_VERSION = 1
+_NONCE = 12
+_TAG = 16
+
+
+@dataclass(frozen=True, repr=False)
+class DataKey:
+    """A data key: use `plaintext` locally and drop it; store only `ciphertext`."""
+
+    plaintext: bytes
+    ciphertext: bytes
+
+    def __repr__(self) -> str:
+        return "DataKey(<redacted>)"
+
+
+def _context(context: Mapping[str, str]) -> dict[str, str]:
+    if not context or not all(context):
+        raise ValueError("context must be a non-empty mapping with non-empty keys")
+    return dict(context)
+
+
+def _aad(header: bytes, context: dict[str, str]) -> bytes:
+    canonical = json.dumps(context, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    return header + canonical.encode()
+
+
+class KmsClient:
+    def __init__(
+        self, obs: Observability, client: KMSClient, key_id: str, *, dependency: str = "kms"
+    ) -> None:
+        if not key_id:
+            raise ValueError("key_id is required")
+        self._obs = obs
+        self._client = client
+        self._key_id = key_id
+        self.dependency = identifier(dependency)
+
+    @classmethod
+    def create(
+        cls,
+        obs: Observability,
+        key_id: str,
+        *,
+        region: str | None = None,
+        endpoint_url: str | None = None,
+        dependency: str = "kms",
+        timeout_seconds: float = 5.0,
+    ) -> KmsClient:
+        client: KMSClient = boto3.client(  # pyright: ignore[reportUnknownMemberType]
+            "kms",
+            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, key_id, dependency=dependency)
+
+    def _observed(self, operation: str):  # noqa: ANN202 - an async context manager
+        return observed(
+            self._obs,
+            family="crypto",
+            system=SYSTEM,
+            dependency=self.dependency,
+            operation=operation,
+            classify=_aws.classify,
+        )
+
+    async def encrypt(self, plaintext: bytes, *, context: Mapping[str, str]) -> bytes:
+        """Up to 4096 bytes (a KMS limit); use `seal` for anything larger."""
+        encryption_context = _context(context)
+        async with self._observed("encrypt"):
+            response = await asyncio.to_thread(
+                self._client.encrypt,
+                KeyId=self._key_id,
+                Plaintext=plaintext,
+                EncryptionContext=encryption_context,
+            )
+        return response["CiphertextBlob"]
+
+    async def decrypt(self, ciphertext: bytes, *, context: Mapping[str, str]) -> bytes:
+        """Names the key, as KMS recommends: a ciphertext from another key is rejected."""
+        encryption_context = _context(context)
+        async with self._observed("decrypt"):
+            response = await asyncio.to_thread(
+                self._client.decrypt,
+                KeyId=self._key_id,
+                CiphertextBlob=ciphertext,
+                EncryptionContext=encryption_context,
+            )
+        return response["Plaintext"]
+
+    async def generate_data_key(self, *, context: Mapping[str, str]) -> DataKey:
+        """A fresh AES-256 key, in plaintext and wrapped under this client's KMS key."""
+        encryption_context = _context(context)
+        async with self._observed("generate_data_key"):
+            response = await asyncio.to_thread(
+                self._client.generate_data_key,
+                KeyId=self._key_id,
+                KeySpec="AES_256",
+                EncryptionContext=encryption_context,
+            )
+        return DataKey(response["Plaintext"], response["CiphertextBlob"])
+
+    async def seal(self, plaintext: bytes, *, context: Mapping[str, str]) -> bytes:
+        """Envelope encryption: a new data key per call (one KMS request), AES-256-GCM locally."""
+        encryption_context = _context(context)
+        key = await self.generate_data_key(context=encryption_context)
+        header = _ENVELOPE.pack(_VERSION, len(key.ciphertext)) + key.ciphertext
+        nonce = os.urandom(_NONCE)
+        sealed = AESGCM(key.plaintext).encrypt(nonce, plaintext, _aad(header, encryption_context))
+        return header + nonce + sealed
+
+    async def unseal(self, envelope: bytes, *, context: Mapping[str, str]) -> bytes:
+        """Raises ValueError for a malformed envelope, cryptography's InvalidTag if tampered."""
+        encryption_context = _context(context)
+        if len(envelope) < _ENVELOPE.size:
+            raise ValueError("not a sealed envelope")
+        version, size = _ENVELOPE.unpack_from(envelope)
+        end = _ENVELOPE.size + size
+        if version != _VERSION or size == 0 or len(envelope) < end + _NONCE + _TAG:
+            raise ValueError("not a sealed envelope")
+        key = await self.decrypt(envelope[_ENVELOPE.size : end], context=encryption_context)
+        nonce, sealed = envelope[end : end + _NONCE], envelope[end + _NONCE :]
+        return AESGCM(key).decrypt(nonce, sealed, _aad(envelope[:end], encryption_context))
+
+    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/queue/__init__.py

@@ -0,0 +1,6 @@
+"""Queue providers grouped by capability, with provider-specific delivery models.
+
+Import `SqsClient` from `clients_021.queue.sqs` (requires the `aws` extra) or
+`QStashClient` from `clients_021.queue.qstash` (no extra). SQS is polled by consumers;
+QStash delivers to HTTP endpoints. Importing this package loads neither provider SDK.
+"""

clients_021/queue/qstash.py

@@ -0,0 +1,219 @@
+"""QStash JSON publishing over the shared HTTP client; no optional SDK is required.
+
+Publishing is one POST. Delivery retries belong to QStash; publication retries belong
+to the caller, which must reuse the same deduplication id after an uncertain outcome.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, cast
+from urllib.parse import urlsplit
+
+import httpx
+from observability_021 import Observability
+from observability_021.config import identifier
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+from clients_021._observe import observed
+from clients_021.errors import DependencyUnavailable
+from clients_021.http import HttpClient, HttpResponse
+
+_SYSTEM = {"messaging.system": "upstash_qstash"}
+_HEADER_NAME = re.compile(r"[!#$%&'*+.^_`|~0-9a-zA-Z-]+")
+_TRACE_HEADERS = {"traceparent", "tracestate"}
+
+
+@dataclass(frozen=True)
+class PublishedMessage:
+    message_id: str
+    deduplicated: bool
+
+
+class QStashResponseError(Exception):
+    """A rejected request or invalid acknowledgement, without the provider's body."""
+
+    def __init__(self, status_code: int, *, reason: str = "rejected") -> None:
+        super().__init__(f"QStash publish: {reason} (HTTP {status_code})")
+        self.status_code = status_code
+        self.reason = reason
+
+
+def _classify(error: BaseException) -> str | None:
+    if isinstance(error, DependencyUnavailable):
+        return error.reason
+    if isinstance(error, QStashResponseError):
+        if error.status_code == 429:
+            return "throttled"
+        if 500 <= error.status_code < 600:
+            return f"status_{error.status_code}"
+    return None
+
+
+def _url(value: str, *, name: str, base: bool = False) -> str:
+    try:
+        parsed = urlsplit(value)
+        port = parsed.port  # Invalid ports must fail before a request is constructed.
+        valid = (
+            parsed.scheme in {"https", "http"}
+            and parsed.hostname
+            and parsed.username is None
+            and parsed.password is None
+            and not parsed.fragment
+            and not (base and parsed.query)
+            and (port is None or port > 0)
+            and not any(char.isspace() or ord(char) < 32 or ord(char) == 127 for char in value)
+        )
+    except ValueError:
+        valid = False
+    if not valid:
+        raise ValueError(f"{name} must be an HTTP(S) URL without credentials or a fragment")
+    return value.rstrip("/") if base else value
+
+
+def _header_value(value: str, *, name: str) -> str:
+    if (
+        not value
+        or value != value.strip()
+        or not value.isascii()
+        or any(ord(char) < 32 or ord(char) == 127 for char in value)
+    ):
+        raise ValueError(f"{name} must be a non-empty printable ASCII header value")
+    return value
+
+
+def _integer(value: int, *, name: str, minimum: int) -> None:
+    if type(value) is not int or value < minimum:
+        raise ValueError(f"{name} must be an integer of at least {minimum}")
+
+
+def _published(response: HttpResponse) -> PublishedMessage:
+    try:
+        data: Any = response.json()
+    except (ValueError, UnicodeDecodeError):
+        raise QStashResponseError(response.status_code, reason="invalid_response") from None
+    if not isinstance(data, dict):
+        raise QStashResponseError(response.status_code, reason="invalid_response")
+    payload = cast(dict[str, Any], data)
+    message_id = payload.get("messageId")
+    deduplicated = payload.get("deduplicated", response.status_code == 202)
+    if (
+        not isinstance(message_id, str)
+        or not message_id.strip()
+        or not isinstance(deduplicated, bool)
+    ):
+        raise QStashResponseError(response.status_code, reason="invalid_response")
+    return PublishedMessage(message_id, deduplicated)
+
+
+class QStashClient:
+    def __init__(
+        self,
+        obs: Observability,
+        *,
+        token: str,
+        base_url: str,
+        timeout_seconds: float,
+        dependency: str = "qstash",
+        propagate: bool = True,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self.dependency = identifier(dependency)
+        self._base_url = _url(base_url, name="base_url", base=True)
+        self._token = _header_value(token, name="token")
+        self._obs = obs
+        self._propagate = propagate
+        self._closed = False
+        self._http = HttpClient(
+            obs, timeout_seconds=timeout_seconds, retries=0, transport=transport
+        )
+
+    async def publish_json(
+        self,
+        destination: str,
+        body: Any,
+        *,
+        deduplication_id: str,
+        delivery_retries: int = 3,
+        delivery_timeout_seconds: int = 60,
+        delay_seconds: int = 0,
+        label: str | None = None,
+        forward_headers: Mapping[str, str] | None = None,
+    ) -> PublishedMessage:
+        """Accept JSON for delivery to one URL, preserving the supplied deduplication id.
+
+        Delivery options affect QStash's calls to the destination, not this POST.
+        Trace headers are owned by this client; propagate=False omits forwarded tracing.
+        """
+        if self._closed:
+            raise RuntimeError("QStashClient is closed")
+        destination = _url(destination, name="destination")
+        _integer(delivery_retries, name="delivery_retries", minimum=0)
+        _integer(delivery_timeout_seconds, name="delivery_timeout_seconds", minimum=1)
+        _integer(delay_seconds, name="delay_seconds", minimum=0)
+        deduplication_id = _header_value(deduplication_id, name="deduplication_id")
+        if ":" in deduplication_id:
+            raise ValueError("deduplication_id must not contain ':'")
+        content = json.dumps(
+            body, ensure_ascii=False, allow_nan=False, separators=(",", ":")
+        ).encode()
+        headers = {
+            "Authorization": f"Bearer {self._token}",
+            "Content-Type": "application/json",
+            "Upstash-Method": "POST",
+            "Upstash-Deduplication-Id": deduplication_id,
+            "Upstash-Retries": str(delivery_retries),
+            "Upstash-Timeout": f"{delivery_timeout_seconds}s",
+            "Upstash-Delay": f"{delay_seconds}s",
+        }
+        if label is not None:
+            headers["Upstash-Label"] = _header_value(label, name="label")
+        for key, value in (forward_headers or {}).items():
+            if not _HEADER_NAME.fullmatch(key):
+                raise ValueError("forward_headers contains an invalid header name")
+            name = key.lower()
+            if name in _TRACE_HEADERS:
+                continue
+            if name in {
+                "content-type",
+                "content-length",
+                "host",
+                "transfer-encoding",
+                "connection",
+            }:
+                raise ValueError(
+                    "forward_headers cannot override HTTP framing or JSON content type"
+                )
+            headers[f"Upstash-Forward-{name}"] = _header_value(value, name="forwarded value")
+        async with observed(
+            self._obs,
+            family="messaging",
+            system=_SYSTEM,
+            dependency=self.dependency,
+            operation="publish",
+            classify=_classify,
+        ):
+            if self._propagate:
+                carrier: dict[str, str] = {}
+                TraceContextTextMapPropagator().inject(carrier)
+                headers.update({f"Upstash-Forward-{key}": value for key, value in carrier.items()})
+            # QStash forwards this URL's query. Quoting the whole destination turns
+            # the query into a literal path at the consumer instead.
+            response = await self._http.request(
+                "POST",
+                f"{self._base_url}/v2/publish/{destination}",
+                dependency=self.dependency,
+                headers=headers,
+                content=content,
+            )
+            if not 200 <= response.status_code < 300:
+                raise QStashResponseError(response.status_code)
+            return _published(response)
+
+    async def aclose(self) -> None:
+        """Release the HTTP pool and injected transport after in-flight calls finish."""
+        self._closed = True
+        await self._http.aclose()

clients_021/queue/sqs.py

@@ -0,0 +1,177 @@
+"""SQS, observed, with the trace carried inside each message.
+
+    from clients_021.queue.sqs import SqsClient
+
+    queue = SqsClient.create(obs, queue_url, region="us-east-1")
+    await queue.send(body, attributes={"type": "notes.created.v1"})
+    for message in await queue.receive(max_messages=10, wait_seconds=20):
+        with tracer.start_as_current_span("handle", context=message.trace_context()):
+            ...
+        await queue.delete(message.receipt)
+
+Needs the `aws` extra. `send` adds `traceparent` (and `tracestate`) as message attributes,
+so the consumer's span continues the producer's trace. Calls record
+`messaging.client.operation.*` with `dependency` and `operation` (`send`, `receive`,
+`delete`, `change_visibility`). Timeouts, connection failures, throttling and 5xx raise
+DependencyUnavailable; access denied or a missing queue keep their botocore type.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+import boto3
+from observability_021 import Observability
+from observability_021.config import identifier
+from opentelemetry.context import Context
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+from clients_021 import _aws
+from clients_021._observe import observed
+
+if TYPE_CHECKING:
+    from mypy_boto3_sqs import SQSClient
+else:
+    SQSClient = Any
+
+SYSTEM = {"messaging.system": "aws_sqs"}
+_TRACE_KEYS = ("traceparent", "tracestate")
+MAX_BATCH = 10
+
+
+@dataclass(frozen=True)
+class ReceivedMessage:
+    id: str
+    body: str
+    receipt: str
+    # How many times SQS has handed this message out (1 on the first delivery).
+    receive_count: int
+    attributes: Mapping[str, str] = field(default_factory=dict[str, str])
+
+    def trace_context(self) -> Context:
+        """The producer's trace, to start the consumer's span in."""
+        return TraceContextTextMapPropagator().extract(
+            {k: v for k, v in self.attributes.items() if k in _TRACE_KEYS}
+        )
+
+
+class SqsClient:
+    def __init__(
+        self, obs: Observability, client: SQSClient, queue_url: str, *, dependency: str = "sqs"
+    ) -> None:
+        self._obs = obs
+        self._client = client
+        self._queue_url = queue_url
+        self.dependency = identifier(dependency)
+
+    @classmethod
+    def create(
+        cls,
+        obs: Observability,
+        queue_url: str,
+        *,
+        region: str | None = None,
+        endpoint_url: str | None = None,
+        dependency: str = "sqs",
+        timeout_seconds: float = 5.0,
+    ) -> SqsClient:
+        # Long polling waits up to 20 s server-side: the read timeout must outlast it.
+        client: SQSClient = boto3.client(  # pyright: ignore[reportUnknownMemberType]
+            "sqs",
+            region_name=region,
+            endpoint_url=endpoint_url,
+            config=_aws.config(connect_seconds=timeout_seconds, read_seconds=20 + timeout_seconds),
+        )
+        return cls(obs, client, queue_url, dependency=dependency)
+
+    def _observed(self, operation: str):  # noqa: ANN202 - an async context manager
+        return observed(
+            self._obs,
+            family="messaging",
+            system=SYSTEM,
+            dependency=self.dependency,
+            operation=operation,
+            classify=_aws.classify,
+        )
+
+    async def send(
+        self, body: str, *, attributes: Mapping[str, str] | None = None, delay_seconds: int = 0
+    ) -> str:
+        """Returns the message id. Attributes are strings; the trace context is added here."""
+        carrier: dict[str, str] = {}
+        message_attributes: dict[str, Any] = {
+            key: {"DataType": "String", "StringValue": value}
+            for key, value in (attributes or {}).items()
+            if key not in _TRACE_KEYS
+        }
+        async with self._observed("send"):
+            TraceContextTextMapPropagator().inject(carrier)
+            for key, value in carrier.items():
+                message_attributes[key] = {"DataType": "String", "StringValue": value}
+            response = await asyncio.to_thread(
+                self._client.send_message,
+                QueueUrl=self._queue_url,
+                MessageBody=body,
+                MessageAttributes=message_attributes,
+                DelaySeconds=delay_seconds,
+            )
+        return response["MessageId"]
+
+    async def receive(
+        self,
+        *,
+        max_messages: int = MAX_BATCH,
+        wait_seconds: int = 20,
+        visibility_timeout: int | None = None,
+    ) -> list[ReceivedMessage]:
+        extra: dict[str, Any] = {}
+        if visibility_timeout is not None:
+            extra["VisibilityTimeout"] = visibility_timeout
+        async with self._observed("receive"):
+            response = await asyncio.to_thread(
+                self._client.receive_message,
+                QueueUrl=self._queue_url,
+                MaxNumberOfMessages=max(1, min(max_messages, MAX_BATCH)),
+                WaitTimeSeconds=wait_seconds,
+                MessageAttributeNames=["All"],
+                MessageSystemAttributeNames=["ApproximateReceiveCount"],
+                **extra,
+            )
+        return [
+            ReceivedMessage(
+                id=message.get("MessageId", ""),
+                body=message.get("Body", ""),
+                receipt=message.get("ReceiptHandle", ""),
+                receive_count=int(
+                    message.get("Attributes", {}).get("ApproximateReceiveCount", "1")
+                ),
+                attributes={
+                    key: str(value.get("StringValue", ""))
+                    for key, value in message.get("MessageAttributes", {}).items()
+                },
+            )
+            for message in response.get("Messages", [])
+        ]
+
+    async def delete(self, receipt: str) -> None:
+        async with self._observed("delete"):
+            await asyncio.to_thread(
+                self._client.delete_message, QueueUrl=self._queue_url, ReceiptHandle=receipt
+            )
+
+    async def change_visibility(self, receipt: str, *, seconds: int) -> None:
+        """Hands the message back after `seconds` (0: now), for an earlier or later retry."""
+        async with self._observed("change_visibility"):
+            await asyncio.to_thread(
+                self._client.change_message_visibility,
+                QueueUrl=self._queue_url,
+                ReceiptHandle=receipt,
+                VisibilityTimeout=seconds,
+            )
+
+    async def aclose(self) -> None:
+        """Release the underlying SDK connection pools after in-flight calls finish."""
+        await asyncio.to_thread(self._client.close)