021-python-clients 0.2.0__tar.gz → 0.4.0__tar.gz

{021_python_clients-0.2.0 → 021_python_clients-0.4.0}/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes are recorded here by release-please from Conventional Commits.
 
+## [0.4.0](https://github.com/from021-io/python-clients/compare/v0.3.0...v0.4.0) (2026-10-22)
+
+
+### Features
+
+* **compute:** add Kubernetes Jobs client over the HTTP client ([9b3c369](https://github.com/from021-io/python-clients/commit/9b3c36930f6a070d3fee9844e86c0d27f871346b))
+* **llm:** add observed Bedrock Runtime client for SDKs ([5216293](https://github.com/from021-io/python-clients/commit/52162939416f58c610f4f4e217d911f5e5efdea9))
+* **secrets:** add observed Secrets Manager client ([f14042f](https://github.com/from021-io/python-clients/commit/f14042f064ca61e8d267b338b033a12fd41690eb))
+
+## [0.3.0](https://github.com/from021-io/python-clients/compare/v0.2.0...v0.3.0) (2026-10-21)
+
+
+### ⚠ BREAKING CHANGES
+
+* **http:** HTTP durations include body consumption and cleanup, counts emit at completion and all HTTP series gain http.response.body.complete. Attempt failure logs are enabled by default. See CONTRACT.md for dashboard and consumer migration notes.
+
+### Features
+
+* **http:** observe complete response bodies and streams ([333cece](https://github.com/from021-io/python-clients/commit/333cece69c41a9ef16828f83e303be4183a5a187))
+
+
+### Refactors
+
+* **http:** group clients and transports by capability ([1a7b41a](https://github.com/from021-io/python-clients/commit/1a7b41a5dba214fb109acccc9e3e08a9d123e3ee))
+
 ## [0.2.0](https://github.com/from021-io/python-clients/compare/v0.1.0...v0.2.0) (2026-10-21)
 
 
@@ -22,10 +47,14 @@ All notable changes are recorded here by release-please from Conventional Commit
 
 ### Added
 
+- Add `HttpClient.stream` and a native httpx `ObservedTransport` for incremental bodies with explicit lifetime and no streaming retries.
+
 - Add an optional Vercel Blob client with observed CRUD, explicit public/private access, bounded operations and SDK-native metadata/errors.
 
 ### Changed
 
+- **Breaking — HTTP telemetry:** HTTP/httpx2 spans and request durations now include body consumption and resource close. Counters are emitted at completion, gain `http.response.body.complete`, and failures produce sanitized attempt logs. QStash/Resend retain one logical failure log. Cancellation closes resources before propagating; closed HTTP clients cannot reopen.
+
 - Group Redis, S3 and KMS under cache, storage and crypto, retaining the 0.1.0 imports as compatibility aliases.
 
 ## 0.1.0 (2026-10-21)

021_python_clients-0.4.0/CONTRACT.md

@@ -0,0 +1,319 @@
+# Contract
+
+What dashboards, alerts and services may rely on. Changing a name, a label or the error
+semantics below is a breaking change.
+
+## Imports and capability packages
+
+Queue providers live in `clients_021.queue.sqs` (`SqsClient`, `ReceivedMessage`) and
+`clients_021.queue.qstash` (`QStashClient`, `PublishedMessage`, `QStashResponseError`).
+Use these imports in place of the initial draft's root-level `clients_021.sqs` and
+`clients_021.qstash` paths. These capability paths shipped in 0.1.0.
+Importing `clients_021.queue` or its QStash module does not require the `aws` extra.
+
+The queue package groups providers by purpose. SQS owns polling, receipts and visibility;
+QStash owns HTTP delivery. Their public methods and observability contracts remain distinct.
+Shared email types and the interchangeable `EmailSender` protocol live in `clients_021.email`.
+
+Redis lives in `clients_021.cache.redis`, S3 in `clients_021.storage.s3`, KMS in
+`clients_021.crypto.kms`, Secrets Manager in `clients_021.secrets.secrets_manager`, Bedrock
+in `clients_021.llm.bedrock` and Kubernetes Jobs in `clients_021.compute.kubernetes`, which
+needs no extra. The 0.1.0 root modules (`redis`, `s3`, `kms`) continue to re-export
+the same clients and result types (`ObjectInfo`, `DataKey`). Existing call signatures,
+metric/span names and error semantics are unchanged. Capability package imports do not
+load optional SDKs. HTTP implementations live in `clients_021.http.httpx` and
+`clients_021.http.httpx2`. `clients_021.http` retains `HttpClient`, `HttpResponse`,
+`HttpMethod`, `IDEMPOTENT_METHODS` and `RETRY_STATUS`; the root `clients_021` exports remain
+unchanged. `clients_021.httpx2.ObservedTransport` re-exports the same class as the new path.
+Importing `clients_021.http` does not require the `httpx2` extra.
+
+## Metrics
+
+All on the service's `Observability` meter, so they carry its resource (service name,
+version, environment). Durations use 021-python-observability's buckets.
+
+| Instrument | Type / unit | Labels | Clients |
+| --- | --- | --- | --- |
+| `db.client.operation.count` | Counter / `{operation}` | dependency, operation, status, error.type | Redis (shared with SQL from 021-python-observability, which has no `operation`) |
+| `db.client.operation.duration` | Histogram / `s` | same | Redis |
+| `messaging.client.operation.count` | Counter / `{operation}` | dependency, operation, status, error.type | SQS, QStash, email (Resend, SES) |
+| `messaging.client.operation.duration` | Histogram / `s` | same | SQS, QStash, email (Resend, SES) |
+| `storage.client.operation.count` | Counter / `{operation}` | dependency, operation, status, error.type | S3, Vercel Blob |
+| `storage.client.operation.duration` | Histogram / `s` | same | S3, Vercel Blob |
+| `crypto.client.operation.count` | Counter / `{operation}` | dependency, operation, status, error.type | KMS |
+| `crypto.client.operation.duration` | Histogram / `s` | same | KMS |
+| `secrets.client.operation.count` | Counter / `{operation}` | dependency, operation, status, error.type | Secrets Manager |
+| `secrets.client.operation.duration` | Histogram / `s` | same | Secrets Manager |
+| `llm.client.operation.count` | Counter / `{operation}` | dependency, operation, status, error.type | Bedrock |
+| `llm.client.operation.duration` | Histogram / `s` | same | Bedrock |
+| `llm.client.token.usage` | Counter / `{token}` | dependency, operation, token.type | Bedrock (Converse and ConverseStream) |
+| `compute.client.operation.count` | Counter / `{operation}` | dependency, operation, status, error.type | Kubernetes Jobs |
+| `compute.client.operation.duration` | Histogram / `s` | same | Kubernetes Jobs |
+| `http.client.request.count` | Counter / `{request}` | dependency, http.request.method, http.response.status_code, error.type, http.response.body.complete | HTTP, httpx2, QStash transport, Resend (its HTTP request) |
+| `http.client.request.duration` | Histogram / `s` | same | HTTP, httpx2, QStash transport, Resend (its HTTP request) |
+
+- `status`: `ok` or `error`. `error.type` only on errors.
+- `operation`: a fixed set per client. Redis: `get_json`, `set_json`, `take_json`,
+  `delete`, `incr_window`, `ping`. SQS: `send`, `receive`, `delete`, `change_visibility`.
+  S3 and Vercel Blob: `put`, `get`, `head`, `delete`. QStash: `publish`.
+  Email (Resend, SES): `send`. KMS:
+  `encrypt`, `decrypt`, `generate_data_key`; `seal` and `unseal` record the KMS call they make
+  (`generate_data_key`, `decrypt`), not the local AES work. Secrets Manager: `get`.
+  Bedrock: `converse`, `converse_stream`, `invoke_model`, `invoke_model_with_response_stream`,
+  `count_tokens`. A streaming operation ends when its event stream is exhausted, fails or is
+  closed, not when the call returns. Kubernetes Jobs: `create`, `get`, `delete`; each also
+  records its HTTP request (`http.client.request.*`) under the same `dependency`. A missing
+  Job (`get`, `delete`) and an existing one (`create`) are `status=ok`.
+- `token.type`: `input`, `output`, `cache_read`, `cache_write`, as reported by Bedrock in
+  the Converse response or the ConverseStream `metadata` event. InvokeModel bodies are
+  model-specific and are not read.
+- Redis/SQS/S3/Vercel Blob/QStash/email/KMS/Secrets Manager/Bedrock/Kubernetes Jobs `error.type`: `timeout`, `connection_error`, `throttled`,
+  `status_<5xx>`, `cancelled`, or the exception class name for errors that are not outages
+  (`EmailRejected` for every email rejection; botocore's class, such as `ClientError` or
+  `NotFoundException`, for KMS).
+- Resend records two levels: the `send` operation (`messaging.client.operation.*`) and,
+  inside it, its HTTP request (`http.client.request.*`), both under the same `dependency`.
+- HTTP transport metrics use the bounded labels (`timeout`, `cancelled`,
+  `connection_error` or `internal_error`). These describe the transport exception, while
+  `DependencyUnavailable.reason` describes the failure returned to the caller.
+- httpx2 uses `timeout`, `connection_error`, `cancelled`, or the exception class name.
+  HTTP status errors set the span's ERROR status and status-code label, with no `error.type`.
+- A missing S3/Blob object or Redis key is `status=ok`.
+- `dependency` is a static identifier, validated consistently with 021-python-observability.
+  User ids, tenant ids and request-derived values are forbidden even if they match its syntax.
+
+## Spans
+
+CLIENT spans named `<dependency> <operation>` (`HTTP <dependency>` for HTTP), with the
+metric labels plus `db.system.name=redis`, `messaging.system=aws_sqs`,
+`messaging.system=upstash_qstash`, `messaging.system=resend`, `messaging.system=aws_ses`, or
+`rpc.system=aws-api` + `rpc.service=S3` / `rpc.service=KMS` / `rpc.service=SecretsManager` /
+`rpc.service=BedrockRuntime` (plus `gen_ai.system=aws.bedrock`), `rpc.system=vercel-blob`, or
+`rpc.system=kubernetes` + `rpc.service=Job`. Kubernetes Jobs' `HTTP <dependency>` span is a
+child of its `<dependency> <operation>` span.
+Resend's `HTTP <dependency>` span is a child of its `<dependency> send` span. Status ERROR on failure (and on HTTP
+status ≥ 400).
+Cancellation propagates unchanged and records ERROR with `error.type=cancelled`.
+HTTP transports measure from sending the request through response-body EOF and resource
+close, or explicit early close. Uploads and incremental downloads are included, as are
+consumer pauses between chunks and cleanup latency. Each attempt ends its span and emits
+one count and one duration exactly once. An HTTP 200 followed by a body timeout is ERROR
+with status code 200 and `error.type=timeout`; the status code describes the headers only.
+
+`http.response.body.complete` is a boolean on HTTP spans and metric points: true after
+response-body EOF, false when no response arrived or it was closed before EOF. It does not
+imply success: an HTTP rejection or close failure can still set ERROR. An intentional
+partial close without an error does not set ERROR. Cancellation sets `error.type=cancelled`,
+including cancellation while reading, closing or waiting between chunks in a stream context.
+
+The HTTP span is current only while sending, reading, closing and emitting its log. It is
+not left attached while a caller processes a chunk; interleaved and cross-task consumers
+keep their own context. All HTTP attempt spans retain the parent active at request start.
+
+QStash adds one logical `publish` operation around the HTTP transport request. The
+messaging duration includes reading and validating the acknowledgement; the nested HTTP
+span includes reading and closing the response body. Both use the configured static dependency name.
+Local input validation occurs before either operation is recorded.
+
+## Logging and coverage limits
+
+Redis, SQS, QStash, S3, Vercel Blob, Resend, SES, KMS, Secrets Manager, Bedrock and Kubernetes Jobs emit a structured
+`dependency.call_failed` warning when an observed remote operation raises an exception.
+Fields are `dependency`, `operation` and `error_type`; provider messages and exception
+chains are not logged. Successful calls and cancellation do not emit this warning;
+cancellation still records an error span and metrics.
+
+HTTP and httpx2 emit one `dependency.call_failed` warning per failed attempt (transport,
+body or close exception, cancellation, or HTTP status >= 400). Fields are only `dependency`,
+`operation` (normalized method) and `error_type`. HTTP rejection logs use `status_<code>`;
+the metric still uses only its status-code label for that case. The logger runs within the
+HTTP span so configured log processors can attach its trace/span IDs. Successful completed
+attempts emit no log. Intentional partial close emits `dependency.stream_closed` at INFO
+with dependency and operation; it is not an outage.
+
+`log_failures=False` suppresses these HTTP attempt logs without disabling metrics or spans.
+QStash, Resend and Kubernetes Jobs set this option because their logical operation already emits a failure
+warning; they do not log the same failure at both levels. SDK retry loops can produce one
+warning per failed attempt. HTTP counters measure attempts, not logical API/SDK calls.
+
+The transport observes network bytes and connection cleanup. Parsing JSON, SSE events,
+model output, content decoding above the raw stream, and application errors while processing
+chunks belong to the caller/SDK operation. A 200 SSE response containing an application
+error event is not detected by an HTTP transport.
+S3 presigning and local AES work in KMS are outside remote-operation telemetry.
+
+Instrumentation takes effect only when applications use these wrappers. The application
+must also configure logging, exporters and shutdown/flush through 021-python-observability.
+Defining a client in this package does not migrate existing SDK usage or guarantee that
+telemetry reaches an external backend.
+
+## Trace propagation
+
+- HTTP (`HttpClient`, `http.httpx.ObservedTransport`): the current `traceparent` and
+  `tracestate` replace the caller's trace pair, and a bound `x-request-id` is sent.
+  A native httpx transport can disable injection with `propagate=False`.
+- httpx2 (`ObservedTransport`): no context is injected unless `propagate=True`.
+  With injection disabled, caller-supplied headers are left as supplied.
+  When enabled, both caller-supplied trace headers are replaced with the current context.
+- Resend: nothing is sent. The `traceparent`, `tracestate` and `x-request-id` headers that
+  the HTTP transport adds are removed before the request leaves.
+- SES, KMS, Secrets Manager, Bedrock and Vercel Blob: nothing is sent by the default transports.
+- SQS: `traceparent` and `tracestate` are message attributes; `ReceivedMessage.trace_context()`
+  returns the producer's context. Caller-supplied values for both trace attributes are
+  replaced with the current context.
+- QStash: the `publish` span's context is sent as `Upstash-Forward-traceparent` and
+  `Upstash-Forward-tracestate` for delivery to the consumer. `propagate=False` removes
+  both forwarded trace headers. Caller values never override them. The request to QStash
+  itself still uses the HTTP transport's propagation policy.
+
+## Errors
+
+`DependencyUnavailable(dependency, operation, reason)` with `reason` one of `timeout`,
+`connection_error`, `throttled`, `status_<5xx>`. Raised only when retrying later may work.
+`HttpClient.request`: only after the last attempt; HTTP statuses are returned, never raised.
+`HttpClient.stream`: exactly one attempt; transport/body failures use the same conversion,
+with no replay after headers or a partial body. Native httpx/httpx2 `ObservedTransport`
+instances preserve SDK exceptions and never retry.
+HTTP local protocol/unsupported protocol errors and Redis authentication
+or authorization errors retain their native type and are not treated as outages.
+
+QStash maps HTTP 429 to `throttled`, 5xx to `status_<code>`, and transport outages to
+`timeout` or `connection_error`, with operation `publish`. Other non-2xx responses raise
+`QStashResponseError(status_code, reason="rejected")`. A 2xx response must contain a
+non-empty `messageId` and, if present, a boolean `deduplicated`; otherwise it raises
+`QStashResponseError` with `reason="invalid_response"`. A missing deduplication flag
+is inferred from status 202. Neither error includes the provider response body.
+`PublishedMessage(message_id, deduplicated)` represents acceptance, not completed delivery.
+
+The exception's message and fields contain only the static dependency, operation and reason.
+The chained provider exception is preserved for debugging and is not sanitized.
+
+Email: `EmailRejected(dependency, status, code)` when the provider refused the message or
+the credentials, for both senders. `status` is the HTTP status; `code` is Resend's error
+`name` or the SES error code, reduced to `unknown` unless it is a short identifier. Its
+message is `<dependency> send: rejected (<status> <code>)`; never the provider's message.
+Resend: 429 is `throttled`, 5xx is `status_<5xx>`, transport timeouts and connection
+failures are `timeout` / `connection_error`; every other non-2xx is `EmailRejected` (409
+`concurrent_idempotent_requests` included: the first request is still running). SES: the
+shared AWS classification, and every other `ClientError` becomes `EmailRejected` chained to
+it. Resend's request is sent once; `idempotency_key` becomes its `Idempotency-Key` header
+(1–256 characters, kept by Resend for 24 hours). SES has no idempotency key: the argument is
+validated and ignored.
+
+KMS: throttling, 5xx (`KMSInternalException`, `DependencyTimeoutException`,
+`KeyUnavailableException`), timeouts and connection failures are `DependencyUnavailable`.
+Access denied, disabled or missing keys, invalid key state, a wrong encryption context or a
+tampered ciphertext (`InvalidCiphertextException`) and a ciphertext from another key
+(`IncorrectKeyException`) keep their botocore type. `decrypt` always names the client's key.
+Every call requires a non-empty encryption context. `unseal` raises `ValueError` for a
+malformed envelope and `cryptography.exceptions.InvalidTag` when the payload was altered.
+
+Secrets Manager: throttling, 5xx (`InternalServiceError`), timeouts and connection failures
+are `DependencyUnavailable`. A missing secret (`ResourceNotFoundException`), access denied,
+a value KMS cannot decrypt (`DecryptionFailure`), a secret scheduled for deletion
+(`InvalidRequestException`) and invalid parameters keep their botocore type. `get` is a read:
+retrying it is safe. A version with neither `SecretString` nor `SecretBinary` raises
+`ValueError`.
+
+Bedrock: throttling (`ThrottlingException`, and `throttlingException` inside an event stream),
+5xx, `ModelNotReadyException` (`throttled`), the stream errors `serviceUnavailableException`,
+`internalServerException` and `modelStreamErrorException`, timeouts and connection failures
+are `DependencyUnavailable`. Access denied, validation errors, a missing model or profile and
+quota limits (`ServiceQuotaExceededException`) keep their botocore type. Leaving a stream
+early or calling its `close()` ends the operation as `ok` and logs `dependency.stream_closed`
+at INFO. A model call is not idempotent in cost: botocore's retries bill each attempt.
+
+Kubernetes Jobs: 429 is `throttled`, 5xx `status_<5xx>`, transport timeouts and connection
+failures `timeout` / `connection_error`, all `DependencyUnavailable`. A 409 whose reason is
+`AlreadyExists` on `create` and a 404 on `get` or `delete` are results, not errors. Any other
+non-success status raises `KubernetesApiError(status_code, reason)`, where `reason` is the
+Status object's machine-readable reason (`Forbidden`, `Invalid`, `Conflict`, ...) or
+`Unknown`; a 201 whose name does not match raises it with `InvalidResponse`. POST is sent
+once; GET and DELETE retry 502/503/504 and network failures once. Local validation (DNS-label
+names and namespace, `metadata.name` required, `generateName` refused, `kind` must be Job)
+happens before any request.
+
+Vercel Blob (`clients_021.storage.vercel_blob`): HTTP 429 maps to `throttled`; 5xx to
+`status_<code>`; HTTP timeouts and total deadlines to `timeout`; network/remote protocol
+failures to `connection_error`. Known transport causes wrapped by the SDK are classified
+without inspecting provider messages. Other errors retain their SDK type, including
+`BlobAccessError`, `BlobStoreNotFoundError`, `BlobPreconditionFailedError`, and
+`BlobStreamError` for malformed acknowledgements. Only `BlobNotFoundError` becomes `None`
+for `get`/`head`, counted as success. `put` returns the SDK's `PutResult` (exported as
+`BlobUpload`); `head` returns its `HeadResult` (`BlobInfo`). These types are provider-specific.
+SDK validation and credential failures can produce an error span but perform no network I/O.
+
+## Sealed envelope format
+
+`KmsClient.seal` output is stored data, so its layout is part of this contract: version
+byte `0x01`, wrapped data key length (2 bytes, big endian), the wrapped key (KMS
+`GenerateDataKey`, `AES_256`, same encryption context), a 12-byte random nonce, then the
+AES-256-GCM ciphertext and 16-byte tag. The GCM additional data is the header (version,
+length and wrapped key) followed by the encryption context as compact JSON with sorted keys.
+A new data key is generated for every envelope.
+
+## Lifecycle and retry limits
+
+HTTP, Redis, SQS, QStash, S3, Vercel Blob, Resend, SES, KMS, Secrets Manager, Bedrock and Kubernetes
+Jobs expose `aclose()` (Bedrock also `close()`). Close them after
+in-flight calls complete; the wrapper owns the underlying client, including one supplied
+through the constructor.
+AWS factories configure three total attempts; injected clients retain their own policy.
+Cancellation of an AWS await does not cancel its worker thread or undo a remote write.
+A transient failure does not guarantee that replaying a non-idempotent operation is safe.
+
+QStash publishes once, never automatically replays a POST, and preserves the required
+deduplication key exactly. Keys containing `:` fail locally, matching the provider
+restriction without lossy normalization. Delivery retries, delay and delivery timeout are separate
+provider options. The publication timeout is mandatory and finite. Consumers remain
+responsible for idempotency and signature verification. A closed QStash client cannot
+publish again.
+
+`HttpClient.request` and `HttpClient.stream` accept at most one of `json`, `form` or raw byte `content`. Passing
+more than one non-None body format raises `ValueError` before sending a request.
+
+`HttpClient.stream` is an async context manager yielding a native httpx response; it does
+not buffer the response and also accepts an async iterable of upload bytes. Use `async with`
+and `aiter_bytes`, `aiter_lines` or `aiter_raw`. SDK callers using manual `send(stream=True)`
+must eventually call `response.aclose()`; an abandoned response cannot finalize its
+telemetry or free its connection. Client shutdown does not replace closing active responses.
+Close responses and finish consumers before closing the client/Observability.
+
+Body resources close once on EOF, read failure or explicit close. Cleanup is shielded from
+cancellation and awaited; cancellation is then re-raised. A secondary cleanup failure does
+not replace a read failure. These async clients run on asyncio. Custom transports must implement a terminating `aclose()`.
+Timeouts remain per network I/O, not a total stream deadline. `HttpClient` closes an injected
+transport once even when multiple dependency pools borrow it; closed clients cannot reopen.
+
+Vercel Blob uses the optional `vercel-blob>=0.5,<0.6` SDK and explicit read-write credentials,
+store ID and access mode. It owns a shared transport; each operation borrows it in a separate
+SDK session. No environment credentials or global SDK client perform requests. The total
+operation deadline defaults to 10 seconds and includes buffered downloads. Timeout and
+cancellation do not imply a remote write was undone. Neither this wrapper nor the SDK
+retries operations; an injected transport must respect this policy. Overwrite and random
+suffixes default to false. Callers decide whether a repeated write is safe. A closed client
+cannot reopen its pool. No additional HTTP metrics are emitted by this client.
+
+## Migration from 0.2.x
+
+This is a breaking telemetry change, released with the next pre-1.0 minor version. HTTP
+metric names and span names stay the same, but their durations now include bodies, consumer
+backpressure and close; counts are emitted at completion instead of at headers. Existing
+series gain `http.response.body.complete`. Revisit latency thresholds, filter/aggregate the
+new label and expect long-lived streams to report only when they complete or close. Native
+transport logs are now enabled by default; use the explicit opt-out when an enclosing
+logical operation already owns the warning. Do not add a second observed transport around
+these clients, or each request would be counted twice.
+
+## Never recorded
+
+Keys, URLs, query strings, bodies, message ids, receipts, object names, bucket or queue
+names, provider error messages. Email: sender, recipient and reply-to addresses, subjects,
+text and HTML bodies, tags, idempotency keys, API keys, configuration set names. KMS: key
+ids, ARNs and aliases, encryption contexts, plaintext, ciphertext and data keys. Secrets
+Manager: secret ids, names and ARNs, version ids, version stages and secret values. Bedrock:
+model ids, inference profile ARNs, prompts, system prompts, outputs, tool arguments and
+results, request ids and guardrail details. Kubernetes Jobs: namespaces, Job names, labels,
+manifests, API server addresses, service account tokens and Status messages.
+
+Vercel Blob: read-write tokens, store IDs, pathnames, delivery URLs, content and ETags.

{021_python_clients-0.2.0 → 021_python_clients-0.4.0}/CONTRIBUTING.md

@@ -8,23 +8,27 @@ not need to be reimplemented here.
 ## Layout and public API
 
 Group domain clients by capability, with a module per provider even when the package
-currently has one provider. HTTP transports are cross-cutting infrastructure and stay at
-the root. Tests stay in `tests/test_<provider>.py`.
+currently has one provider. HTTP implementations live under `http/`, with explicit
+imports for optional transports. Tests stay in `tests/test_<provider>.py`.
 
 ```text
 clients_021/
   email/          # _message.py (shared protocol/types), resend.py, ses.py
   queue/          # sqs.py, qstash.py
-  http.py
-  httpx2.py
+  http/           # httpx.py (HttpClient/ObservedTransport), httpx2.py (ObservedTransport)
   cache/          # redis.py
   storage/        # s3.py, vercel_blob.py
   crypto/         # kms.py
+  secrets/        # secrets_manager.py
+  llm/            # bedrock.py
+  compute/        # kubernetes.py (over the shared HTTP client, no extra)
 ```
 
 The original `clients_021.redis`, `clients_021.s3` and `clients_021.kms` imports remain
 compatibility re-exports of the same classes and result types. New code uses the capability
-paths. Do not remove compatibility modules without a breaking release.
+paths. `clients_021.http` re-exports its existing types from `http.httpx`, and the original
+`clients_021.httpx2` remains an alias for `http.httpx2`. Keep `clients_021.HttpClient`
+available too. Do not remove compatibility modules without a breaking release.
 
 Public result and exception types live beside their provider unless they are truly shared.
 A common protocol requires interchangeable operations and semantics: `EmailSender.send`
@@ -61,10 +65,16 @@ Each implementation must make these decisions explicit in README.md and CONTRACT
 | Telemetry | Choose a metric family, fixed operations and system attribute. Never record URLs, credentials, bodies, object names or request-derived ids. |
 | Propagation | State the default and opt-out. Replace `traceparent` and `tracestate` together, including removing stale state. |
 
-Use `_observe.observed` for a logical cache, messaging, storage or crypto operation. HTTP-backed
+Use `_observe.observed` for a logical cache, messaging, storage or crypto operation, and
+`_observe.Call` for synchronous SDK calls or operations that end after the call returns
+(event streams). HTTP-backed
 clients may also emit the transport's HTTP span/metrics: one logical operation and one
 network request are different measurements. Do not sum those counters as distinct
-business operations. Disable exception recording when provider errors can contain data.
+business operations. Disable nested HTTP attempt logs with `log_failures=False` when the
+logical operation owns the failure log. HTTP transport duration includes raw-body consumption
+and resource close; keep measurement once-only, incremental, and detached from consumer
+context between chunks. Test read/close errors, cancellation (including repeated cancellation
+while closing), early close, and cross-task consumption. Disable exception recording when provider errors can contain data.
 The safe wrapper message does not make a native chained exception safe to log.
 
 Expose small, stable results when the caller needs them. Validate acknowledgements before