cloudru-qa-grpc-client 1.0.0__tar.gz

cloudru_qa_grpc_client-1.0.0/.agents/skills/grpc-client-usage/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: grpc-client-usage
+description: Building gRPC clients on the grpc_client library — a grpcio wrapper providing constructor options, four send_*_request methods, response objects that never raise on a non-OK status, lazy streams, parsed google.rpc.Status details, token injection and request logging with secret masking. Use when writing a client for a gRPC service, adding a service method to an existing client, or configuring TLS, timeouts, metadata, authentication, streaming or logging in a project that imports grpc_client. Key names are GRPCClient, AsyncGRPCClient, GRPCResponse, GRPCStreamResponse, CallOptions, Metadata, ClientOption, options.with_*, stub_class, send_unary_unary_request.
+license: Apache-2.0
+metadata:
+  library-version: "1.0.0"
+  source: packages/grpc-client
+---
+
+# Building clients on grpc_client
+
+`grpc_client` is a wrapper around `grpcio`. It adds exactly four things:
+
+1. **Constructor options** (`ClientOption`) — configuration is passed as positional arguments to a factory method instead of channel plumbing spread over the call site.
+2. **Response objects** — a failed call comes back as a `GRPCResponse` with a status code instead of raising. In tests a rejection is an expected result, not an accident.
+3. **Lazy streams** — `GRPCStreamResponse` reads messages as they arrive, with `collect()` when the whole batch is wanted.
+4. **Interceptors out of the box** — auth token injection, `x-request-id`, `traceparent`, and request/response logging with secret masking.
+
+Everything else (`grpc.StatusCode`, `grpc.Compression`, `grpc.ChannelCredentials`, `grpc.CallCredentials`, the generated `*_pb2` messages and `*_pb2_grpc` stubs) is plain grpcio and protobuf. Do not invent your own wrappers around what they already provide.
+
+## Hard rules
+
+1. Subclass `GRPCClient` or `AsyncGRPCClient` and implement the `stub_class` property. `BaseGRPCClient` is abstract and owns no channel; never subclass it directly.
+2. Inside a service method call `self.send_*_request(...)`, **not** `self.stub.Method(...)`. The direct call skips the client's timeout, default metadata and compression — interceptors still run, since they live on the channel.
+3. Configure through options passed to `from_addr` / `from_channel`. Channel-level settings (`secure`, TLS credentials, channel options, interceptors) are frozen once the channel exists, so assigning them afterwards silently does nothing.
+4. Do not treat a non-OK call as an exception. Check `response.ok` / `response.status_code`, or call `raise_for_status()` when an exception really is wanted.
+5. Never determine success with `isinstance(outcome, grpc.RpcError)`. grpcio stream call objects implement `grpc.Call` and `grpc.RpcError` at the same time, even on a healthy call. Use `grpc_client.interceptors.base.outcome_code`.
+6. Never write a retry loop, backoff or circuit breaker by hand. grpcio has retries built in — configure them through `with_channel_options` and `grpc.service_config`.
+7. Do not add dependencies to the library itself — it must stay lightweight.
+
+Before claiming something cannot be done, check `references/pitfalls.md` — it documents the non-obvious behaviour that trips people up.
+
+## Canonical client (sync)
+
+```python
+# Modules generated from the service .proto files
+from api import example_pb2, example_pb2_grpc
+from grpc_client import CallOptions, GRPCClient, GRPCResponse, MetadataType
+
+
+class OrdersClient(GRPCClient[example_pb2_grpc.OrdersStub]):
+    """Client for the orders service."""
+
+    @property
+    def stub_class(self) -> type[example_pb2_grpc.OrdersStub]:
+        return example_pb2_grpc.OrdersStub
+
+    def get_order(
+        self,
+        request: example_pb2.GetOrderRequest,
+        metadata: MetadataType | None = None,
+        options: CallOptions | None = None,
+    ) -> GRPCResponse[example_pb2.Order]:
+        """Fetch a single order.
+
+        :param request: request message
+        :param metadata: request metadata (the gRPC counterpart of HTTP headers)
+        :param options: per-call options overriding the client settings
+        :return: response carrying the order
+        """
+        return self.send_unary_unary_request(request, self.stub.GetOrder, metadata, options)
+```
+
+Three things make this work:
+
+1. The stub class in square brackets types `self.stub`, so `self.stub.GetOrder` is checked.
+2. The `stub_class` property returns the same class — the base client instantiates it over the channel.
+3. Each service method wraps one of the four send methods.
+
+Assembly:
+
+```python
+import logging
+
+from grpc_client import options
+
+client = OrdersClient.from_addr(
+    "orders.example.com:443",
+    options.with_timeout(30),
+    options.with_auth(my_auth),
+    options.with_logger(logging.getLogger("orders")),
+    options.with_autogenerated_request_id(),
+)
+```
+
+Order matters: interceptors run in the order they were added, so `with_logger` goes **after** `with_auth` for the log to show the request that was actually sent.
+
+## Canonical client (async)
+
+Same shape; the send methods are awaited and stream responses are async.
+
+```python
+from grpc_client import AsyncGRPCClient, AsyncGRPCStreamResponse, GRPCResponse
+
+
+class AsyncOrdersClient(AsyncGRPCClient[example_pb2_grpc.OrdersStub]):
+    @property
+    def stub_class(self) -> type[example_pb2_grpc.OrdersStub]:
+        return example_pb2_grpc.OrdersStub
+
+    async def get_order(self, request: example_pb2.GetOrderRequest) -> GRPCResponse[example_pb2.Order]:
+        return await self.send_unary_unary_request(request, self.stub.GetOrder)
+```
+
+Differences from the sync client:
+
+- send methods are coroutines, including the ones returning a stream;
+- streams are `AsyncGRPCStreamResponse`: read with `async for`, and status/metadata are coroutines — `await stream.status_code()`. There is no `ok` property;
+- closing is `await client.close()` or `async with`;
+- `from_channel()` **raises `ValueError`** when any interceptor-adding option is passed (`with_auth`, `with_logger`, `with_autogenerated_*`, `with_interceptor`). `grpc.aio` accepts interceptors only at channel creation — build the channel yourself with `grpc.aio.insecure_channel(..., interceptors=[...])`, or use `from_addr()`;
+- `with_auth` needs an `AsyncClientAuth` implementation, where `token()` and `refresh()` are coroutines. Passing a sync one raises `TypeError`.
+
+The option set is shared: `options.with_logger(...)` picks the sync or async interceptor by the client it is applied to.
+
+## Choosing how to send
+
+| gRPC call type | Method | Returns |
+|---|---|---|
+| unary → unary | `send_unary_unary_request(msg, method, ...)` | `GRPCResponse[T]` |
+| stream → unary (client streaming) | `send_stream_unary_request(iterator, method, ...)` | `GRPCResponse[T]` |
+| unary → stream (server streaming) | `send_unary_stream_request(msg, method, ...)` | `GRPCStreamResponse[T]` |
+| stream → stream (bidirectional) | `send_stream_stream_request(iterator, method, ...)` | `GRPCStreamResponse[T]` |
+
+All four take `(payload, method, metadata=None, options=None)`. Request streams are plain `Iterator[Message]` (`iter([msg1, msg2])` is enough); the async client also accepts an `AsyncIterator`.
+
+## Releasing the channel
+
+A client built with `from_addr` owns its channel and must close it. Prefer the context manager:
+
+```python
+with OrdersClient.from_addr("localhost:9000", options.with_insecure_channel()) as client:
+    client.get_order(request)
+
+async with AsyncOrdersClient.from_addr("localhost:9000", options.with_insecure_channel()) as client:
+    await client.get_order(request)
+```
+
+In pytest:
+
+```python
+@pytest.fixture
+def orders_client() -> Iterator[OrdersClient]:
+    with OrdersClient.from_addr("localhost:9000", options.with_insecure_channel()) as client:
+        yield client
+```
+
+A channel passed to `from_channel` is **not** closed by the client — its lifetime belongs to the caller.
+
+## Options
+
+The full catalog with exact signatures is in `references/options.md`. Summary:
+
+| Option | Purpose |
+|---|---|
+| `with_timeout(timeout)` | default per-call deadline; `None` disables it |
+| `with_insecure_channel()` | plaintext channel (the channel is encrypted by default) |
+| `with_ssl_credentials(credentials)` | custom TLS channel credentials |
+| `with_root_certificates(pem_bytes)` | root certificate for server verification |
+| `with_channel_options(options)` | low-level grpcio channel options, including `grpc.service_config` |
+| `with_compression(compression)` | message compression |
+| `with_default_metadata(metadata)` | metadata attached to every request |
+| `with_auth(auth, retry_on_unauthenticated=True)` | access-token injection |
+| `with_logger(logger, ...)` | request and response logging as text |
+| `with_log_sink(sink, ...)` | the same logging through your own record receiver |
+| `with_autogenerated_request_id(key=None)` | `x-request-id` |
+| `with_autogenerated_traceparent(key=None)` | `traceparent` (W3C Trace Context) |
+| `with_interceptor(*interceptors)` | your own grpcio interceptors |
+
+### Writing your own option
+
+`ClientOption` is `Callable[[BaseGRPCClient[Any]], None]`. Options run inside `__init__` **before** the channel is created, so they may set the client fields but must not touch `client.channel` or `client.stub`.
+
+```python
+from typing import Any
+
+from grpc_client import ClientOption
+from grpc_client.base_client import BaseGRPCClient
+
+
+def with_tenant(tenant: str) -> ClientOption:
+    def option(client: BaseGRPCClient[Any]) -> None:
+        client.default_metadata = (*client.default_metadata, ("x-tenant", tenant))
+
+    return option
+```
+
+Prefer composing from the built-ins (`with_default_metadata`, `with_interceptor`) over reaching into private fields.
+
+## Working with the response
+
+```python
+response = client.get_order(request)
+
+response.ok  # bool — status is OK
+response.status_code  # grpc.StatusCode
+response.details  # str — server-supplied explanation, usually only on failure
+response.message()  # the response message; raises MessageUndefinedError when there is none
+response.initial_metadata  # Metadata received before the body
+response.trailing_metadata  # Metadata received after the body (`metadata` is an alias)
+response.error  # the original grpc.RpcError, when the call failed
+response.error_status  # ErrorStatus parsed from google.rpc.Status, when the service sent one
+response.raise_for_status()  # raises ResponseStatusError unless the status is OK; returns self
+```
+
+A failure is an ordinary result:
+
+```python
+response = client.get_order(request)
+
+assert response.status_code == grpc.StatusCode.NOT_FOUND
+assert response.details == "order not found"
+```
+
+`with_parser()` attaches a conversion for the response message and yields a `GRPCResponseWithParser`, whose `parse()` runs it — useful for mapping onto a pydantic model or picking one field out.
+
+Details on streams, `ErrorStatus`, metadata and the exception hierarchy are in `references/responses.md`.
+
+## Per-call options
+
+Client settings apply to every request; a single call is tuned with `CallOptions`:
+
+```python
+from grpc_client import CallOptions
+
+response = client.get_order(
+    request,
+    options=CallOptions(
+        timeout=120,  # a longer deadline for a slow method
+        metadata={"x-attempt": "2"},
+        wait_for_ready=True,  # wait for the channel instead of failing UNAVAILABLE
+        compression=grpc.Compression.Gzip,
+    ),
+)
+```
+
+`timeout=None` means "no deadline at all"; an omitted `timeout` means "take the client's". They are different — the sentinel `USE_CLIENT_DEFAULT` exists precisely to tell them apart.
+
+## Metadata
+
+Pass a dict, or a sequence of pairs when a key needs several values:
+
+```python
+client.get_order(request, metadata={"x-order-id": "A-1024"})
+client.get_order(request, metadata=[("x-feature", "search"), ("x-feature", "ranking")])
+```
+
+Responses carry a `Metadata` mapping: dict-like, but it preserves order and repeated keys and compares key names case-insensitively.
+
+```python
+response.trailing_metadata["x-request-id"]  # first value for the key
+response.trailing_metadata.get_all("x-feature")  # every value for the key
+response.trailing_metadata.pairs()  # every pair, repeats included
+```
+
+Binary values are allowed only for keys ending in `-bin` — a gRPC requirement, not a library one.
+
+## Authentication
+
+The library does not know where a token comes from; it declares the contract:
+
+```python
+class ClientAuth(Protocol):
+    def token(self) -> str: ...
+    def refresh(self, rejected_token: str) -> str: ...
+```
+
+The implementation owns issuing, caching and expiry. The client owns the rest: it adds `authorization: Bearer <token>` to every request, and on `UNAUTHENTICATED` calls `refresh(rejected_token)` and repeats the call. The rejected token is passed so the implementation can tell "the token really expired" from "a neighbouring request already refreshed it while this one waited on the lock".
+
+Retry happens for **unary calls only** — a request stream is exhausted after the first send, and a response stream reveals its status only once consumed. Switch it off with `options.with_auth(my_auth, retry_on_unauthenticated=False)`.
+
+If the caller supplies its own `authorization` metadata, the interceptor stays out entirely: no token is requested and no retry is made.
+
+Ready-made IAM authentication lives in [`grpc-client-auth`](https://github.com/cloud-ru-tech/qa-libraries/tree/master/packages/grpc-client-auth).
+
+## Logging
+
+```python
+options.with_logger(
+    logging.getLogger("orders"),
+    sanitize_keys=["user.password", "items.*.token"],
+    json_indent=2,
+)
+```
+
+All four call types are logged. For streams the log carries the final status and the message count — the messages themselves are not logged, because reading them for the log would change the call's behaviour.
+
+Masking rules differ by target:
+
+- **metadata** — matched on the whole key name, case-insensitively;
+- **message body** — a key with no separators (`password`) masks that field at any nesting depth, including list elements; a key containing `.`, `*`, `[` or `(` (`user.password`, `items.*.token`) is applied as a [glom path](https://glom.readthedocs.io/en/latest/).
+
+Field names are compared up to naming style, so `access_token` also hides `accessToken` (protobuf serializes to camelCase), while a differently-worded field like `sec_ret` is left alone.
+
+Common secrets (`authorization`, `cookie`, `password`, `token` and friends) are masked always, on top of `sanitize_keys`; turn that off with `use_default_sanitize_keys=False`.
+
+Global defaults come from `grpc_client.configure_logging(...)` and can be overridden by `GRPC_CLIENT_*` environment variables. The full list is in `references/options.md`.
+
+### A log that is not a text line
+
+`with_logger` writes one string per call. To get the same data in another shape, hand the client a `LogSink` instead:
+
+```python
+options.with_log_sink(MySink())
+```
+
+The interceptor builds a `RequestRecord` / `ResponseRecord` and picks the level; the sink decides where the record goes and how it looks — including masking and formatting, which is why `with_log_sink` takes no formatting parameters. Read the outcome off `record.succeeded` and `record.is_stream` rather than re-deriving it from `status_code` / `messages_count`.
+
+A sink is called from several threads and on the hot path, and its exceptions are swallowed rather than propagated — the call survives, the record does not. Details and record shapes are in `references/options.md`.
+
+For structlog this already exists: [`grpc-client-structlog`](https://github.com/cloud-ru-tech/qa-libraries/tree/master/packages/grpc-client-structlog).
+
+## Custom interceptors
+
+Interceptors are written against the plain grpcio API. When the job is just adding metadata, subclass `MetadataInterceptor` — it covers all four call types:
+
+```python
+from typing import Any
+
+from grpc_client.interceptors import MetadataInterceptor
+from grpc_client.types import MetadataItems
+
+
+class TenantInterceptor(MetadataInterceptor):
+    """Adds the tenant id to every request."""
+
+    def __init__(self, tenant: str):
+        self._tenant = tenant
+
+    def metadata_to_add(self, call_details: Any) -> MetadataItems:
+        return (("x-tenant", self._tenant),)
+
+
+client = OrdersClient.from_addr("localhost:9000", options.with_interceptor(TenantInterceptor("warehouse-42")))
+```
+
+`AsyncMetadataInterceptor` is the same contract with `metadata_to_add` as a coroutine.
+
+Helpers in `grpc_client.interceptors.base`: `outcome_code(outcome)` for the status of a finished call, `with_metadata` / `aio_call_details` to build augmented call details, `method_name(call_details)` for the `/package.Service/Method` string, `call_detail(call_details, name, default)` for a field grpcio may not provide.
+
+An async interceptor implementing several interfaces is split into per-interface adapters when it is added — see `references/pitfalls.md` for why, and for what that means when inspecting the client.
+
+## Known pitfalls
+
+Before debugging "strange" behaviour, read `references/pitfalls.md`. It covers the 60-second default deadline, stream consumption rules, when a stream raises instead of returning a response, async log draining on close, and the metadata merge order.

cloudru_qa_grpc_client-1.0.0/.agents/skills/grpc-client-usage/references/options.md

@@ -0,0 +1,260 @@
+# Option catalog and configuration
+
+All options live in `grpc_client.options`. Each one returns a `ClientOption` — a callable applied to the client inside `__init__`, before the channel is created.
+
+## Channel and transport
+
+### `with_timeout(timeout: float | None) -> ClientOption`
+
+Default deadline for every call, in seconds. `None` means no deadline.
+
+The default is `BaseGRPCClient.DEFAULT_TIMEOUT_SEC` — **60 seconds**. Bare grpcio has no default deadline; this library imposes one so a hung call cannot hold a test run until the CI job times out. Override it per client with this option, per subclass by redefining `DEFAULT_TIMEOUT_SEC`, or per call with `CallOptions(timeout=...)`.
+
+### `with_insecure_channel() -> ClientOption`
+
+Plaintext channel. Everything on the wire, access tokens included, is unprotected — local debugging and test stands only.
+
+The channel is encrypted by default: without this option the client builds a secure channel with `grpc.ssl_channel_credentials()`.
+
+### `with_ssl_credentials(credentials: grpc.ChannelCredentials) -> ClientOption`
+
+Custom TLS channel credentials, e.g. carrying a corporate root certificate. Also forces `secure = True`, so combining it with `with_insecure_channel()` makes the outcome depend on the order — the later option wins.
+
+### `with_root_certificates(root_certificates: bytes) -> ClientOption`
+
+Shorthand for `with_ssl_credentials(grpc.ssl_channel_credentials(root_certificates=...))`. Takes the contents of a PEM file, not a path.
+
+### `with_channel_options(options: ChannelOptions) -> ClientOption`
+
+Low-level grpcio channel options. Replaces the whole tuple rather than appending, so pass every option in one call.
+
+This is where grpcio's built-in retries are configured — do not hand-roll a retry loop:
+
+```python
+import json
+
+options.with_channel_options(
+    [
+        ("grpc.enable_retries", 1),
+        (
+            "grpc.service_config",
+            json.dumps(
+                {
+                    "methodConfig": [
+                        {
+                            "name": [{"service": "example.Orders"}],
+                            "retryPolicy": {
+                                "maxAttempts": 4,
+                                "initialBackoff": "0.1s",
+                                "maxBackoff": "1s",
+                                "backoffMultiplier": 2,
+                                "retryableStatusCodes": ["UNAVAILABLE"],
+                            },
+                        }
+                    ],
+                }
+            ),
+        ),
+    ]
+)
+```
+
+### `with_compression(compression: grpc.Compression) -> ClientOption`
+
+Message compression. Applied both when creating the channel and as the default for each call, so a per-call `CallOptions(compression=...)` overrides it.
+
+## Metadata
+
+### `with_default_metadata(metadata: MetadataType) -> ClientOption`
+
+Metadata appended to every request. Accumulates: applying the option twice keeps both sets, in order of application.
+
+These pairs go in front of any per-call metadata. Interceptor-added metadata is appended after both, since interceptors run on the channel.
+
+### `with_autogenerated_request_id(key: str | None = None) -> ClientOption`
+
+Adds a UUID4 under `x-request-id`. The key can be changed by argument or by the `GRPC_CLIENT_REQUEST_ID_KEY` environment variable.
+
+If the request already carries that key, the existing value is kept.
+
+### `with_autogenerated_traceparent(key: str | None = None) -> ClientOption`
+
+Adds a W3C Trace Context value `00-<32 hex>-<16 hex>-01` under `traceparent`. Key overridable by argument or by `GRPC_CLIENT_TRACEPARENT_KEY`.
+
+This is standalone generation, not an OpenTelemetry integration: no context is picked up from a current span. An existing value is kept.
+
+## Authentication
+
+### `with_auth(auth: ClientAuth | AsyncClientAuth, *, retry_on_unauthenticated: bool = True) -> ClientOption`
+
+Injects `authorization: Bearer <token>` into every request.
+
+The implementation is picked by client type, and the two protocols are told apart by whether `token()` is a coroutine function — they declare identical method names, so `isinstance` cannot distinguish them (which is why neither protocol is `runtime_checkable`). A mismatch raises `TypeError` at client construction:
+
+- sync client + async implementation → `Синхронному клиенту нужна синхронная реализация ClientAuth`
+- async client + sync implementation → `Асинхронному клиенту нужна асинхронная реализация AsyncClientAuth`
+
+With `retry_on_unauthenticated=True` (default) an `UNAUTHENTICATED` reply triggers `refresh(rejected_token)` and one repeat — **unary calls only**.
+
+The key and scheme are fixed at `authorization` / `Bearer` in the option. For other values instantiate `AuthInterceptor(auth, key=..., scheme=...)` directly and pass it via `with_interceptor`.
+
+## Interceptors
+
+### `with_interceptor(*interceptors: object) -> ClientOption`
+
+Adds grpcio interceptors, sync or async depending on the client. They are applied in the order added.
+
+For an async client each interceptor goes through `split_async_interceptor()` first — see `pitfalls.md`.
+
+## Logging
+
+### `with_logger(logger, *, sanitize_keys=None, log_level=None, err_log_level=None, json_indent=None, use_line_breaks=None, payload_maxlength=None, use_default_sanitize_keys=True) -> ClientOption`
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `logger` | `logging.Logger` | where records are written |
+| `sanitize_keys` | `Sequence[str] \| None` | metadata key names and message-body paths whose values become `****` |
+| `log_level` | `int \| None` | level for successful calls; defaults to the global config |
+| `err_log_level` | `int \| None` | level for failed calls; defaults to the global config |
+| `json_indent` | `int \| None` | indent for the JSON parts of a record |
+| `use_line_breaks` | `bool \| None` | newlines between record parts instead of spaces |
+| `payload_maxlength` | `int \| None` | maximum message-body length in a record |
+| `use_default_sanitize_keys` | `bool` | also mask the built-in secret list (default `True`) |
+
+Record shapes:
+
+```
+GRPC request sent: id=<uuid> Method: /package.Service/Method Payload: {...} Metadata: {...}
+GRPC response received: id=<uuid> Status: 0 (OK) Method: /package.Service/Method Payload: {...} Metadata: {...}
+GRPC stream finished: id=<uuid> Status: 0 (OK) Method: /package.Service/Method Messages: 12 Metadata: {...}
+GRPC error occurred: id=<uuid> Status: 5 (NOT_FOUND) Method: /package.Service/Method Error: <details> Metadata: {...}
+```
+
+`id` links a request to its response. It is generated per call by the interceptor and has nothing to do with server-side tracing — for that use `with_autogenerated_traceparent`.
+
+Notes on what lands in a record:
+
+- a client request stream logs `Payload: <поток сообщений>` — the iterator is not consumed for the log;
+- a server response stream logs no payload at all, only the final status and message count;
+- a body that cannot be rendered becomes `<не удалось подготовить тело сообщения>`; a body over `payload_maxlength` is cut with `... <обрезано>`;
+- a repeated metadata key is rendered as a list of its values, so the record matches what was actually sent;
+- when the logger is disabled for both levels the interceptor short-circuits: no id is generated and streams are not wrapped for counting.
+
+### `with_log_sink(sink, log_level=None, err_log_level=None) -> ClientOption`
+
+The extension point behind `with_logger`. The interceptor decides **what happened** — it builds a record and picks the level — and the sink decides **where and in what shape** it lands.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `sink` | `LogSink` | receiver of the records |
+| `log_level` | `int \| None` | level for successful calls; defaults to the global config |
+| `err_log_level` | `int \| None` | level for failed calls; defaults to the global config |
+
+`LogSink` is a `Protocol` — three methods, no base class required, though subclassing it explicitly buys you mypy signature checks and an error on a forgotten method:
+
+```python
+class LogSink(Protocol):
+    def is_enabled_for(self, level: int) -> bool: ...
+    def write_request(self, level: int, record: RequestRecord) -> None: ...
+    def write_response(self, level: int, record: ResponseRecord) -> None: ...
+```
+
+`RequestRecord` is `(trace_id, method, message, metadata)`; `message` is `None` when the request body was a stream.
+
+`ResponseRecord` is `(trace_id, method, status_code, message, details, metadata, messages_count)` and covers all three outcomes with one shape:
+
+| Outcome | `status_code` | `message` | `details` | `messages_count` |
+|---|---|---|---|---|
+| unary success | `OK` | the response | `""` | `None` |
+| stream finished | `OK` | `None` | `""` | count |
+| any failure | the error code | `None` | service error text | count for streams, `None` for unary |
+
+Do not re-derive the outcome from that combination — the record answers it: `record.succeeded` (status is `OK`) and `record.is_stream` (`messages_count` is set). `TextLogSink` picks its three text shapes off exactly those two.
+
+`is_enabled_for` is asked **before** the record is built — assembling a body costs `MessageToDict` plus masking plus `json.dumps`, the question does not. When both levels answer `False` the interceptor short-circuits entirely: no `trace_id`, no stream wrapper.
+
+Three constraints on an implementation:
+
+- **it is called from several threads** — the final stream log comes from a grpcio channel thread, the async one from an event-loop task;
+- **it is called on the hot path** — the request record is written before the call is sent, so slow work inside the sink delays the call itself;
+- **it must not count on being able to fail** — an exception is swallowed and reported to the `grpc_client.interceptors.logging` logger, the call goes through, and that one record is lost.
+
+Formatting is the sink's own business, so `with_log_sink` has no `sanitize_keys` / `json_indent` / `payload_maxlength` parameters. `grpc_client.LogFormat.from_config(...)` builds the rules with the `configure_logging` values filled in for anything left `None`, and `grpc_client.utils.logutils` exposes the helpers that turn a record into text.
+
+`TextLogSink(logger, log_format=None)` is the built-in implementation; `with_logger(...)` is shorthand for constructing it. `grpc_client.resolve_log_levels(log_level, err_log_level)` returns the pair of levels the interceptor will use — needed when a sink must reject an unusable level before the client is built.
+
+### Masking
+
+Built-in secret list (`grpc_client.utils.sanitizer.DEFAULT_SANITIZE_KEYS`): `authorization`, `proxy-authorization`, `cookie`, `set-cookie`, `x-api-key`, `api-key`, `api_key`, `access_token`, `refresh_token`, `password`, `secret`, `token`. Anything in `sanitize_keys` is added on top; turn the defaults off only with `use_default_sanitize_keys=False`.
+
+Metadata and message bodies are masked by different rules:
+
+| Target | Rule |
+|---|---|
+| metadata | whole key name, case-insensitive; no path parsing, because gRPC metadata is flat and its keys may contain dots |
+| body, key without separators (`password`) | that field name at any nesting depth, list elements included |
+| body, key with `.` `*` `[` `(` (`user.password`, `items.*.token`) | applied as a glom path |
+
+Name matching is style-insensitive, resolved by normalizing to snake_case: `access_token` also hides `accessToken`, `APIKey`, `token2FA`. Word boundaries are respected, so `secret` does not match `sec_ret` and `token` does not match `tokenizer`. A compound name ending in a secret does match: `user_password` and `client_secret` are masked by `password` and `secret`.
+
+Body traversal is depth-limited at 64 levels; anything deeper is replaced with `<превышена глубина вложенности>` rather than passed through, since it may still hold a secret.
+
+Masking covers the records this library writes. It does not cover grpcio's own exception text.
+
+### `configure_logging(...)` — global defaults
+
+```python
+from grpc_client import configure_logging
+
+configure_logging(
+    log_level=logging.INFO,
+    err_log_level=logging.ERROR,
+    json_indent=None,
+    use_line_breaks=False,
+    payload_log_maxlength=4096,
+)
+```
+
+Writes to the module-level singleton `grpc_client.config.LOGGING_CONFIG`, which the interceptors read whenever the matching `with_logger` argument was omitted.
+
+**Environment variables override the function arguments**, not the other way round:
+
+| Variable | Field |
+|---|---|
+| `GRPC_CLIENT_LOG_LEVEL` | `log_level` (integer) |
+| `GRPC_CLIENT_ERR_LOG_LEVEL` | `err_log_level` (integer) |
+| `GRPC_CLIENT_JSON_INDENT` | `json_indent` |
+| `GRPC_CLIENT_USE_LINE_BREAKS` | `use_line_breaks` (`true`/`y`/`yes`/`on`/`1`) |
+| `GRPC_CLIENT_PAYLOAD_LOG_MAXLENGTH` | `payload_log_maxlength` |
+
+Two more variables are read by the observability interceptors, not by `configure_logging`: `GRPC_CLIENT_REQUEST_ID_KEY` and `GRPC_CLIENT_TRACEPARENT_KEY`.
+
+## Utilities
+
+`grpc_client.utils.sanitizer`
+- `sanitize(value, sensitive_keys)` — masks a dict or list by the rules above; returns a copy, leaves the original untouched.
+- `sanitize_metadata(metadata, sensitive_keys)` — the same for metadata pairs.
+- `DEFAULT_SANITIZE_KEYS`, `MASK`, `MAX_DEPTH`.
+
+`grpc_client.utils.traceparent`
+- `generate(flags=FLAGS_SAMPLED)` — a W3C Trace Context string.
+
+`grpc_client.utils.logutils`
+- `request_log`, `response_log`, `stream_response_log`, `error_log` — build the same strings by hand, e.g. from a logger on a different backend.
+- `LogFormat` — the formatting rules those four take.
+
+## Client attributes
+
+| Attribute | Where it is set | Purpose |
+|---|---|---|
+| `DEFAULT_TIMEOUT_SEC` | class attribute, overridable in a subclass | default deadline, `60.0` |
+| `timeout` | `with_timeout`, read per call | current default deadline |
+| `secure` | `with_insecure_channel` / `with_ssl_credentials` | whether the channel is encrypted |
+| `ssl_credentials` | `with_ssl_credentials` | TLS channel credentials |
+| `compression` | `with_compression` | default compression |
+| `channel_options` | `with_channel_options` | grpcio channel options |
+| `default_metadata` | `with_default_metadata` | metadata added to every request |
+| `channel` | built in `__init__` | the underlying `grpc.Channel` / `grpc.aio.Channel` |
+| `stub` | built in `__init__` | the generated stub over that channel |
+
+`timeout`, `default_metadata` and `compression` are read when a call is assembled, so changing them after construction does take effect — but do it through options anyway, since the channel-level fields around them do not behave that way.