cloudru-qa-http-client-structlog 1.0.0__py3-none-any.whl

cloudru_qa_http_client_structlog-1.0.0.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: cloudru-qa-http-client-structlog
+Version: 1.0.0
+Summary: Структурированные логи для HTTP-клиента
+Project-URL: Repository, https://github.com/cloud-ru-tech/qa-libraries
+Project-URL: Issues, https://github.com/cloud-ru-tech/qa-libraries/issues
+Author-email: Алексей Кирютин <ayukiryutin@cloud.ru>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: cloudru-qa-http-client<2,>=1.0.0
+Requires-Dist: structlog>=26.1.0
+Description-Content-Type: text/markdown
+
+# Structured logs for the HTTP client
+
+[![PyPI](https://img.shields.io/pypi/v/cloudru-qa-http-client-structlog)](https://pypi.org/project/cloudru-qa-http-client-structlog/)
+[![Python](https://img.shields.io/pypi/pyversions/cloudru-qa-http-client-structlog)](https://pypi.org/project/cloudru-qa-http-client-structlog/)
+[![License](https://img.shields.io/pypi/l/cloudru-qa-http-client-structlog)](https://github.com/cloud-ru-tech/qa-libraries/blob/master/LICENSE)
+
+English | [Русский](README.ru.md)
+
+The `with_structlogger` option for the [HTTP client](https://github.com/cloud-ru-tech/qa-libraries/tree/master/packages/http-client)
+logs all requests and responses through [structlog](https://www.structlog.org/en/stable/index.html).
+
+The standard http-client logger puts the request in one text string. This option logs the method, URL,
+headers, body, and other data as separate fields, visible in the console during debugging
+and available for searching and filtering in collected logs.
+
+- [Installation](#installation)
+- [Skills for AI agents](#skills-for-ai-agents)
+- [Usage](#usage)
+- [Asynchronous client](#asynchronous-client)
+- [Masking secrets](#masking-secrets)
+- [Parameters](#parameters)
+- [Development](#development)
+
+## Installation
+
+Requires Python 3.13 or later.
+
+```shell
+pip install cloudru-qa-http-client-structlog
+```
+
+Import the library as `http_client_structlog`. A compatible version of
+[`cloudru-qa-http-client`](https://github.com/cloud-ru-tech/qa-libraries/tree/master/packages/http-client)
+is installed with it.
+
+## Skills for AI agents
+
+The package includes the [`http-client-structlog-usage`](https://github.com/cloud-ru-tech/qa-libraries/blob/master/.agents/skills/http-client-structlog-usage/SKILL.md) skill
+with examples and usage rules for AI agents. Install the library
+in your project environment, then run this from its root (requires [`uv`](https://docs.astral.sh/uv/)):
+
+```shell
+uvx library-skills install --skill http-client-structlog-usage --yes
+```
+
+For Claude Code, add `--claude`. The instructions are shipped with the library version.
+
+## Usage
+
+Pass the option to the client constructor; logging is then automatic:
+
+```python
+import structlog
+
+from http_client import HttpClient
+from http_client_structlog import with_structlogger
+
+
+class OrdersClient(HttpClient):
+    def get_order(self, order_id: str):
+        request = self.client.build_request("GET", f"/orders/{order_id}")
+        return self.send(request)
+
+
+with OrdersClient("https://api.example.com", with_structlogger(structlog.get_logger("orders"))) as client:
+    client.get_order("42")
+```
+
+The request is logged as an `http request sent` event, the response as `http response received`.
+A shared `trace_id` field links them.
+
+Structured logs for automated tests can look like this:
+
+![structlogs](https://raw.githubusercontent.com/cloud-ru-tech/qa-libraries/master/packages/http-client-structlog/assets/image.png)
+
+## Asynchronous client
+
+Use the same option without extra configuration:
+
+```python
+from http_client import AsyncHttpClient
+
+
+class AsyncOrdersClient(AsyncHttpClient):
+    async def get_order(self, order_id: str):
+        request = self.client.build_request("GET", f"/orders/{order_id}")
+        return await self.send(request)
+
+
+async with AsyncOrdersClient("https://api.example.com", with_structlogger(logger)) as client:
+    await client.get_order("42")
+```
+
+## Masking secrets
+
+Fields with common secret names — `authorization`, `cookie`, `token`, `password`, `api_key`, and others
+from `http_client.event_hooks.DEFAULT_SANITIZE_KEYS` — are masked **by default at every depth**,
+including nested objects and array items.
+
+Add your own fields with `sanitize_keys`. These are exact paths in
+[glom](https://glom.readthedocs.io/en/latest/) format, applied to headers, query parameters,
+and the JSON body. They extend the default list rather than replacing it:
+
+```python
+with_structlogger(
+    logger,
+    sanitize_keys=["user.password", "items.*.token"],
+)
+```
+
+Write header names in lowercase: `"authorization"`, not `"Authorization"`.
+
+Disable the default list explicitly with `use_default_sanitize_keys=False`.
+
+## Parameters
+
+| Parameter | Type | Purpose |
+|---|---|---|
+| `logger` | `structlog.stdlib.BoundLogger` | where to write |
+| `sanitize_keys` | `Sequence[str] \| None` | glom paths to fields replaced with `****` |
+| `json_indent` | `int \| None` | indentation width for JSON properties |
+| `log_level` | `int \| None` | record level; `INFO` by default |
+| `use_default_sanitize_keys` | `bool` | mask common secrets at every depth; `True` by default |
+
+Set the level and indentation for the whole project with `http_client.configure_logging(...)`
+or `HTTP_CLIENT_*` environment variables. Values passed to `with_structlogger` override shared settings.
+
+## Development
+
+The library is developed in the [qa-libraries](https://github.com/cloud-ru-tech/qa-libraries) monorepo
+alongside the other `cloudru-qa-*` libraries. You need [`uv`](https://docs.astral.sh/uv/), GNU Make,
+and [`checkmake`](https://github.com/checkmake/checkmake).
+Run commands from the repository root:
+
+```shell
+make sync                              # install dependencies for all libraries from uv.lock
+make test-http-client-structlog        # tests for this library
+make typecheck-http-client-structlog   # mypy for this library
+make check                             # formatting, ruff, mypy, and tests for the entire workspace
+```
+
+Tests run on Python 3.13 and 3.14. Create a separate environment for another version:
+`make sync test-http-client-structlog PYTHON_VERSION=3.14`.
+
+Publish a release with the git tag `http-client-structlog/v<version>`. The tag version must match
+the version in `packages/http-client-structlog/pyproject.toml`.

cloudru_qa_http_client_structlog-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+http_client_structlog/__init__.py,sha256=JFrlU8OlVVPWgB-8J_Zv4m7oTWzWMBlv7q3GHBqpusU,71
+http_client_structlog/event_hooks.py,sha256=YrDHzVCRU_kMowOblESTZUrykpQTuKho3VbHycXlSTw,2429
+http_client_structlog/option.py,sha256=81M4dNSxhzM59F-mObXKvSVTzorvlRYVYNYyPWvj04g,2131
+http_client_structlog/parser.py,sha256=-NmAu7LNNEeyY_EGsXdx0ZmnVaG0WGk37ISJvd9ybvc,6177
+http_client_structlog/py.typed,sha256=2V-BXHpFdhiPP7ymH5gngkCEyIkBSKRBl5jxiG1YHEM,81
+http_client_structlog/sanitizer.py,sha256=9yQtmIg1xq70kgzaOAjT41Jip9CiyLOWnRpqMDa4hRY,1984
+http_client_structlog/.agents/skills/http-client-structlog-usage/SKILL.md,sha256=vKvXpGC7meflakWcSUCGEdv8Aqb7cOOGswuhfCv1P_U,6552
+http_client_structlog/.agents/skills/http-client-structlog-usage/references/fields.md,sha256=jkZz3NQn8yD7WmyFup4R_OJVlrdRIe7pQ8L04kP6Xqc,6127
+http_client_structlog/.agents/skills/http-client-structlog-usage/references/pitfalls.md,sha256=LUgW2MYaxJdY_5lmTk47sKi1Mrb3G1n5mkjTr-VRmYE,5791
+cloudru_qa_http_client_structlog-1.0.0.dist-info/METADATA,sha256=00TSXNDxY9JWhEPIAG1OUxAHVPPtP1NbQjuk1RioY-I,6680
+cloudru_qa_http_client_structlog-1.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+cloudru_qa_http_client_structlog-1.0.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+cloudru_qa_http_client_structlog-1.0.0.dist-info/RECORD,,

cloudru_qa_http_client_structlog-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cloudru_qa_http_client_structlog-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

http_client_structlog/.agents/skills/http-client-structlog-usage/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: http-client-structlog-usage
+description: Structured request/response logging for the http_client library — the with_structlogger option that writes every HTTP call into structlog as separate fields instead of one text line, with secret masking on by default. Use when a project imports http_client_structlog, when wiring structlog into an HTTP client, or when tuning what ends up in the access log (fields, masking, level, JSON indent, streaming, async). Key names are with_structlogger, sanitize_keys, use_default_sanitize_keys, trace_id.
+license: Apache-2.0
+metadata:
+  library-version: "1.0.0"
+  source: packages/http-client-structlog
+---
+
+# Structured logging for http_client
+
+The library exports exactly one name: `with_structlogger`. It is a `ClientOption` that replaces
+`http_client.options.with_logger`. Instead of one text line per call, every attribute — method, URL,
+headers, body, status — becomes its own [structlog](https://www.structlog.org) field, so logs can be
+filtered and searched by field rather than by substring.
+
+Everything else — building the client, endpoints, timeouts, auth, decorators — is plain `http_client`.
+This library adds no client of its own and no way to log outside of the option.
+
+## Hard rules
+
+1. Install **one** logging option. `with_structlogger` and `options.with_logger` each append their own
+   hooks; passing both logs every request twice.
+2. Pass it as a constructor option, exactly like the built-in ones. There is no post-construction setup.
+3. Requires `http-client` **2.1 or newer**. Earlier versions lack the public log helpers this library
+   imports, and the async client will fail on import.
+4. `sanitize_keys` holds **exact glom paths**; the default secret list works **by field name at any
+   depth**. They are two different mechanisms — see `references/fields.md` before adding a path.
+5. Write header names lowercase (`"authorization"`) — httpx lowercases them before the hook sees them.
+6. Do not turn off `use_default_sanitize_keys` to "clean up" the log. It unmasks passwords and tokens.
+
+Before debugging odd output, read `references/pitfalls.md` — it covers the non-obvious behaviour.
+
+## Usage
+
+```python
+import httpx
+import structlog
+from http_client import HttpClient
+from http_client_structlog import with_structlogger
+
+
+class OrdersClient(HttpClient):
+    def get_order(self, order_id: str) -> httpx.Response:
+        request = self.client.build_request("GET", f"/orders/{order_id}")
+        return self.send(request)
+
+
+with OrdersClient("https://api.example.com", with_structlogger(structlog.get_logger("orders"))) as client:
+    client.get_order("42")
+```
+
+Combines with any other option:
+
+```python
+from http_client import options
+from httpx import BasicAuth
+
+client = OrdersClient(
+    "https://api.example.com",
+    options.with_auth(BasicAuth("admin", "PazzW0rD")),
+    options.with_timeout(30),
+    with_structlogger(logger, json_indent=2),
+)
+```
+
+## Async client
+
+Same option, same arguments. The right response hook — sync or async — is picked from the client type
+inside the option, so nothing extra is configured:
+
+```python
+from http_client import AsyncHttpClient
+
+
+class AsyncOrdersClient(AsyncHttpClient):
+    async def get_order(self, order_id: str) -> httpx.Response:
+        request = self.client.build_request("GET", f"/orders/{order_id}")
+        return await self.send(request)
+
+
+async with AsyncOrdersClient("https://api.example.com", with_structlogger(logger)) as client:
+    await client.get_order("42")
+```
+
+## What lands in the log
+
+Two events per call, linked by `trace_id`:
+
+| Field | Event | Value |
+|---|---|---|
+| `event` | both | `http request sent` / `http response received` |
+| `method` | request | uppercase HTTP method |
+| `url` | request | `scheme://host/path`, without the query string |
+| `query_params` | request | JSON string; omitted when the URL has no query |
+| `headers` | both | JSON string |
+| `body` | both | rendered by `Content-Type`; omitted when there is no body |
+| `status_code` | response | `int` |
+| `trace_id` | both | UUID4 generated per request |
+
+`status_code` is the only non-string field: composite values are serialized to JSON strings, not passed
+as nested dicts. The full catalog — body rendering per content type, truncation, streaming placeholders,
+parse errors — is in `references/fields.md`.
+
+`trace_id` is an internal request↔response link stored in `request.extensions["trace_id"]`. It has
+nothing to do with server-side tracing; for that use `options.with_autogenerated_traceparent()`.
+
+## Masking
+
+Fields whose **name** is a common secret — `authorization`, `cookie`, `token`, `password`, `api_key`
+and the rest of `http_client.event_hooks.DEFAULT_SANITIZE_KEYS` — are replaced with `****` by default,
+**at any depth**, including inside nested objects and array elements.
+
+Project-specific fields go into `sanitize_keys` as [glom](https://glom.readthedocs.io/en/latest/) paths.
+They apply to headers, query parameters, and the JSON body, and they **add to** the default list rather
+than replacing it:
+
+```python
+with_structlogger(logger, sanitize_keys=["user.internal_id", "items.*.card_number"])
+```
+
+| Path | What it masks |
+|---|---|
+| `x-tenant-key` | a header (lowercase name) |
+| `user.internal_id` | a nested body field |
+| `items.*.card_number` | a field in every array element |
+| `*.owner.email` | a field when the body itself is an array |
+
+A path that matches nothing is skipped silently. Masking never touches the response object the caller
+gets back — only the copy that goes into the log.
+
+## Parameters
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `logger` | `structlog.stdlib.BoundLogger` | where to write |
+| `sanitize_keys` | `Sequence[str] \| None` | glom paths replaced with `****` |
+| `json_indent` | `int \| None` | indent used when serializing JSON fields |
+| `log_level` | `int \| None` | record level, defaults to `INFO` |
+| `use_default_sanitize_keys` | `bool` | mask common secret names at any depth, default `True` |
+
+`log_level` and `json_indent` fall back to the global `http_client` settings when omitted — set them
+once for the whole project with `http_client.configure_logging(...)` or the `HTTP_CLIENT_*` environment
+variables. An argument passed to `with_structlogger` wins over the global value.
+
+## References
+
+- `references/fields.md` — the field catalog, body rendering rules, global defaults and env variables.
+- `references/pitfalls.md` — JSON strings vs nested values, streaming, auth retries, typing of `logger`.

http_client_structlog/.agents/skills/http-client-structlog-usage/references/fields.md

@@ -0,0 +1,131 @@
+# Field catalog and configuration
+
+Two records per HTTP call. Field sets differ; `headers`, `body` and `trace_id` are shared.
+
+## Request — `http request sent`
+
+| Field | Type | Value |
+|---|---|---|
+| `method` | `str` | uppercase method |
+| `url` | `str` | `scheme://host/path` — no query string, it lives in `query_params` |
+| `query_params` | `str` | JSON object of the query; **absent** when the URL carries no query |
+| `headers` | `str` | JSON object of the headers, after masking |
+| `body` | `str` | rendered by `Content-Type`; **absent** when the request has no body |
+| `trace_id` | `str` | UUID4 written into `request.extensions["trace_id"]` |
+
+## Response — `http response received`
+
+| Field | Type | Value |
+|---|---|---|
+| `status_code` | `int` | HTTP status |
+| `headers` | `str` | JSON object of the response headers, after masking |
+| `body` | `str` | rendered by `Content-Type`; **absent** when the response has no body |
+| `trace_id` | `str` | the value taken from the request; `<without trace_id>` if the request never passed the request hook |
+
+`status_code` is the only field that is not a string. Composite values (headers, query, JSON body) are
+serialized into JSON strings — see `pitfalls.md` for why that matters to the renderer.
+
+A response is not logged at all when the request fails before a response exists — a connect error or
+timeout raises out of `httpx` and only the request record remains. Catch those in the calling code;
+the option does not log exceptions.
+
+## Body rendering
+
+The body is chosen by the `Content-Type` header:
+
+| `Content-Type` | `body` holds |
+|---|---|
+| `application/json` | the parsed, masked, re-serialized body |
+| `text/plain` | the text, decoded using the `charset` parameter of the header |
+| `application/octet-stream` | the decoded text, or `<binary content (N bytes)>` when it is not text |
+| anything else | `<not logged, content-type: application/pdf>` |
+| header absent, or empty body | the field is omitted entirely |
+
+So a missing `body` means there was nothing to log; `<not logged, ...>` means there was a body and its
+type is not rendered. Only `application/json` is masked — the other types are logged verbatim, so do
+not put secrets into a `text/plain` body.
+
+### Truncation
+
+Length limits come from the global `http_client` config and are applied per content type:
+
+| Content type | Limit | Default |
+|---|---|---|
+| `application/json` | `json_log_maxlength` | unlimited |
+| `text/plain` | `plain_text_log_maxlength` | unlimited |
+| `application/octet-stream` | `octet_stream_log_maxlength` | 1024 characters |
+
+Truncation cuts the **middle** and inserts `...`, keeping the head and tail — the start of a payload
+and its end both stay visible. These limits cannot be set per client, only globally.
+
+### Streaming
+
+| Case | `body` holds |
+|---|---|
+| response obtained via `stream()` / `stream_request()` and not yet read | `<streamed content>` |
+| request with a streaming body (generator, file object) | `<streamed content>` |
+
+Reading either one inside the hook would consume the stream before the caller gets it, so the
+placeholder is by design, not a failure. Everything else about the record — status, headers, masking of
+those headers — is logged normally.
+
+### Parse errors
+
+Any failure while building a field is caught and replaced with `<Error parse: TypeError>` — the
+exception class only. The message is dropped deliberately: it can carry fragments of the body or URL.
+
+Each part is protected independently, so a broken glom path in `sanitize_keys` spoils `headers` while
+`body` and the rest stay intact. The request itself never fails because of logging.
+
+## Masking mechanics
+
+Two independent passes run over every value, path-based first, name-based second:
+
+| Mechanism | Source | Matches |
+|---|---|---|
+| glom paths | `sanitize_keys` | the exact path only — `user.password` does not match `order.user.password` |
+| secret names | `DEFAULT_SANITIZE_KEYS` | a field with that name at any depth, including inside arrays |
+
+Both replace the value with `****`. Name matching is case-insensitive; glom paths are literal, and httpx
+lowercases header names before the hook runs, so paths that point at headers must be lowercase too.
+
+Default names: `authorization`, `proxy-authorization`, `cookie`, `set-cookie`, `x-api-key`, `api-key`,
+`api_key`, `access_token`, `refresh_token`, `password`, `secret`, `token`.
+
+Name-based masking replaces the whole value, so a nested object under a key named `token` disappears
+entirely rather than being walked into.
+
+## Global defaults
+
+`log_level` and `json_indent` fall back to `http_client.config.LOGGING_CONFIG` whenever they are not
+passed to `with_structlogger`. Fill that singleton once at startup:
+
+```python
+import logging
+
+from http_client import configure_logging
+from http_client.config import LoggingConfig
+
+configure_logging(options=LoggingConfig(log_level=logging.DEBUG, json_indent=2, json_log_maxlength=4096))
+```
+
+Environment variables **override** the arguments of that function:
+
+| Variable | Field | Used by this library |
+|---|---|---|
+| `HTTP_CLIENT_LOG_LEVEL` | `log_level` | yes |
+| `HTTP_CLIENT_JSON_INDENT` | `json_indent` | yes |
+| `HTTP_CLIENT_JSON_LOG_MAXLENGTH` | `json_log_maxlength` | yes |
+| `HTTP_CLIENT_PLAIN_TEXT_LOG_MAXLENGTH` | `plain_text_log_maxlength` | yes |
+| `HTTP_CLIENT_OCTET_STREAM_LOG_MAXLENGTH` | `octet_stream_log_maxlength` | yes |
+| `HTTP_CLIENT_USE_LINE_BREAKS` | `use_line_breaks` | no — text-log only setting |
+
+Precedence for level and indent: argument of `with_structlogger` → env variable → `configure_logging`
+argument → library default. `configure_logging` must be called before the client is constructed only
+for values you rely on; the hooks read the singleton at call time, so later changes do take effect.
+
+## Event names
+
+`http request sent` and `http response received`, exported as `event_hooks.REQUEST_EVENT` and
+`event_hooks.RESPONSE_EVENT`. They are not part of the public API (`__init__` exports `with_structlogger`
+only) — filter by them in log queries, but do not import them into production code.

http_client_structlog/.agents/skills/http-client-structlog-usage/references/pitfalls.md

@@ -0,0 +1,115 @@
+# Pitfalls
+
+Non-obvious behaviour that costs time when you hit it unprepared.
+
+## Composite fields are JSON strings, not nested values
+
+`headers`, `query_params` and a JSON `body` reach structlog already serialized. In a console renderer
+that reads fine; under `JSONRenderer` the field is a string with escaped quotes inside the outer JSON:
+
+```json
+{"event": "http request sent", "body": "{\"user\": \"admin\"}"}
+```
+
+This is deliberate — nested structures would collide with field names of the surrounding application
+context and would explode the index of a log store. If a collector must see the body as an object, parse
+that string in a structlog processor of your own, do not expect the library to hand over a `dict`.
+
+Consequence for `json_indent`: it puts real newlines inside those strings. Useful when a human reads the
+console, harmful for a line-based collector — leave it unset in production.
+
+## `logger` is annotated as the stdlib bound logger
+
+The parameter type is `structlog.stdlib.BoundLogger`, but the hooks only ever call `.log(level, event, **fields)`,
+which the default `structlog.get_logger()` also provides. It works at runtime; only the type checker
+complains. Either configure structlog with `wrapper_class=structlog.stdlib.BoundLogger`, or accept the
+mypy error at the call site.
+
+## structlog does its own level filtering
+
+`log_level` is just the level handed to `.log()`. If structlog (or the stdlib logging behind it) is
+configured above that level, the record is dropped and the option looks broken. Lowering `log_level` to
+`DEBUG` requires lowering the structlog threshold as well.
+
+## Two logging options log everything twice
+
+`with_structlogger` and `options.with_logger` append to the same hook lists and neither is aware of the
+other. Both installed means two records per request in two different formats. Pick one.
+
+## Every attempt is a separate pair of records
+
+A retry inside `httpx.Auth.auth_flow`, or any send decorator that calls through more than once, re-runs
+the request hook — with a **new** `trace_id` each time:
+
+```
+http request sent      trace_id=ae8ad3f7…
+http response received trace_id=ae8ad3f7…   401
+http request sent      trace_id=f0f27880…
+http response received trace_id=f0f27880…   200
+```
+
+Each request pairs with its own response, but there is no field tying the attempts together into one
+logical call. Add your own correlation field (e.g. `options.with_autogenerated_request_id()`, whose
+header is generated per attempt too, or a bound context variable) if you need that.
+
+## The request hook mutates the request
+
+`request.extensions["trace_id"]` is written by the hook. Comparing `extensions` before and after a send
+in a test will show the difference; it is not a stray mutation.
+
+## The async hook reads the response body
+
+An httpx response hook fires **before** the client has read the body, and on the async client the stream
+is only reachable through `await`. So `parse_response_async` awaits `aread()` for buffered responses
+before building the record. The caller sees no difference — httpx would have read the same body a moment
+later — and a streamed response is skipped and stays unread.
+
+This is why the library requires `http-client` 2.1: the helpers that tell a streamed response from a
+buffered one became public API in that version.
+
+## The hook is chosen by `isinstance(client, AsyncHttpClient)`
+
+The option picks the sync or async response hook from the client type at construction time. A custom
+async client that does not inherit from `AsyncHttpClient` gets the sync hook and fails on the first
+response with `RuntimeError: Attempted to call a sync iterator on an async stream`. Inherit from
+`AsyncHttpClient`.
+
+## Masking never touches the response the caller receives
+
+Every masking pass builds a copy. `response.json()` and `response.content` still hold the real values —
+`****` exists only in the log. Do not use the option as a way to strip secrets out of the payload.
+
+## `sanitize_keys` and the default list are not the same mechanism
+
+`sanitize_keys` are exact glom paths: `user.password` masks that one field and nothing else. The default
+list matches **by name at any depth**, so `password` anywhere in the body is already masked without any
+configuration. Adding a default name to `sanitize_keys` is redundant, and adding a glom path expecting
+name semantics ("mask `card_number` everywhere") does not work — the path must spell out the location,
+`items.*.card_number`.
+
+A path that matches nothing is skipped silently, so a typo in a path shows up as an unmasked field, not
+as an error.
+
+## Only JSON bodies are masked
+
+`text/plain` and `application/octet-stream` bodies land in the log as they are. A token inside a plain
+text body will be logged in full.
+
+## A broken masking path shows up in one field only
+
+Each part of the record is built inside its own `try`, so a glom path that raises spoils exactly one
+field — `headers` becomes `<Error parse: ValueError>` while `body` stays correct. Do not read a single
+`<Error parse: …>` as "logging is dead"; and note the exception message is dropped on purpose, so
+diagnosing it means reproducing the path against the payload by hand.
+
+## An absent `body` field is not an empty body
+
+The field is omitted when there is nothing to log at all. An unsupported content type gives
+`<not logged, content-type: …>`, an unread stream gives `<streamed content>`. Three different states, so
+a log query filtering on `body` will silently skip bodiless records.
+
+## Only `with_structlogger` is public API
+
+`__init__` exports that one name. `event_hooks`, `parser`, `sanitizer` and the constants inside them are
+internal: they moved in 1.0.0 and can move again. Filter logs by the event strings if you must, but do
+not import them.

http_client_structlog/__init__.py

@@ -0,0 +1,3 @@
+from .option import with_structlogger
+
+__all__ = ["with_structlogger"]

http_client_structlog/event_hooks.py

@@ -0,0 +1,79 @@
+import httpx
+from http_client.config import LOGGING_CONFIG as CFG
+from http_client.types import RequestHook, ResponseHook
+from structlog.stdlib import BoundLogger
+
+from .parser import parse_request, parse_response, parse_response_async
+from .sanitizer import Sanitizer
+
+REQUEST_EVENT = "http request sent"
+RESPONSE_EVENT = "http response received"
+
+
+def request_logger_hook(
+    logger: BoundLogger,
+    sanitizer: Sanitizer,
+    json_indent: int | None = None,
+    log_level: int | None = None,
+) -> RequestHook:
+    """Build a structured HTTP request logging hook."""
+
+    def log_request_hook(request: httpx.Request) -> None:
+        request_params = parse_request(
+            request=request,
+            sanitizer=sanitizer,
+            json_indent=_indent(json_indent),
+        )
+        logger.log(_level(log_level), REQUEST_EVENT, **request_params)
+
+    return log_request_hook
+
+
+def response_logger_hook(
+    logger: BoundLogger,
+    sanitizer: Sanitizer,
+    json_indent: int | None = None,
+    log_level: int | None = None,
+) -> ResponseHook:
+    """Build a structured HTTP response logging hook."""
+
+    def log_response_hook(response: httpx.Response) -> None:
+        response_params = parse_response(
+            response=response,
+            sanitizer=sanitizer,
+            json_indent=_indent(json_indent),
+        )
+        logger.log(_level(log_level), RESPONSE_EVENT, **response_params)
+
+    return log_response_hook
+
+
+def async_response_logger_hook(
+    logger: BoundLogger,
+    sanitizer: Sanitizer,
+    json_indent: int | None = None,
+    log_level: int | None = None,
+) -> ResponseHook:
+    """Build a response logging hook for an asynchronous client.
+
+    A separate implementation is needed: when the hook runs, the asynchronous
+    response body has not been read and its stream is only accessible through await.
+    """
+
+    async def log_response_hook(response: httpx.Response) -> None:
+        response_params = await parse_response_async(
+            response=response,
+            sanitizer=sanitizer,
+            json_indent=_indent(json_indent),
+        )
+        logger.log(_level(log_level), RESPONSE_EVENT, **response_params)
+
+    return log_response_hook
+
+
+def _level(log_level: int | None) -> int:
+    return log_level if log_level is not None else CFG.log_level
+
+
+def _indent(json_indent: int | None) -> int | None:
+    return json_indent if json_indent is not None else CFG.json_indent

http_client_structlog/option.py

@@ -0,0 +1,58 @@
+from collections.abc import Sequence
+
+from http_client import AsyncHttpClient, BaseHttpClient, ClientOption
+from http_client.event_hooks import DEFAULT_SANITIZE_KEYS
+from structlog.stdlib import BoundLogger
+
+from .event_hooks import async_response_logger_hook, request_logger_hook, response_logger_hook
+from .sanitizer import Sanitizer
+
+
+def with_structlogger(
+    logger: BoundLogger,
+    sanitize_keys: Sequence[str] | None = None,
+    json_indent: int | None = None,
+    log_level: int | None = None,
+    *,
+    use_default_sanitize_keys: bool = True,
+) -> ClientOption:
+    """Set a structured logger for HTTP client requests and responses.
+
+    :param logger: Structured logger
+    :param sanitize_keys: Paths in [glom](https://glom.readthedocs.io/en/latest/) format
+                          to fields to mask
+    :param json_indent: JSON log indentation width (no indentation by default)
+    :param log_level: HTTP client log level, INFO by default
+    :param use_default_sanitize_keys: Whether to mask fields with common secret names
+                                      (see `http_client.event_hooks.DEFAULT_SANITIZE_KEYS`)
+                                      at any depth, in addition to `sanitize_keys`
+    :returns: Option that sets the HTTP client logger and hooks
+    """
+    sanitizer = Sanitizer(
+        glom_paths=sanitize_keys or (),
+        secret_names=DEFAULT_SANITIZE_KEYS if use_default_sanitize_keys else (),
+    )
+
+    def option(client: BaseHttpClient) -> None:
+        client.add_request_hook(
+            request_logger_hook(
+                logger=logger,
+                sanitizer=sanitizer,
+                json_indent=json_indent,
+                log_level=log_level,
+            )
+        )
+
+        build_response_hook = (
+            async_response_logger_hook if isinstance(client, AsyncHttpClient) else response_logger_hook
+        )
+        client.add_response_hook(
+            build_response_hook(
+                logger=logger,
+                sanitizer=sanitizer,
+                json_indent=json_indent,
+                log_level=log_level,
+            )
+        )
+
+    return option

http_client_structlog/parser.py

@@ -0,0 +1,182 @@
+import json
+import logging
+from contextlib import suppress
+from typing import cast
+from uuid import uuid4
+
+import httpx
+from http_client.config import LOGGING_CONFIG as CFG
+from http_client.utils.logutils import decode, is_buffered, is_streamed, parse_error, to_json, trim
+
+from .sanitizer import Sanitizer
+
+STREAMED_CONTENT = "<streamed content>"
+UNKNOWN_TRACE_ID = "<without trace_id>"
+_logger = logging.getLogger(__name__)
+
+
+def parse_request(
+    request: httpx.Request,
+    sanitizer: Sanitizer,
+    json_indent: int | None = None,
+) -> dict[str, object]:
+    """Parse fields for a structured HTTP request log.
+
+    :param request: Request containing data to log
+    :param sanitizer: Sensitive data masking rules
+    :param json_indent: JSON log indentation width
+    :return: Structured request log fields
+    """
+    # NOTE: trace_id here only correlates the request and response.
+    # It is unrelated to the trace_id of a server with telemetry enabled.
+    trace_id = str(uuid4())
+    extensions = cast("dict[str, object]", request.extensions)
+    extensions["trace_id"] = trace_id
+
+    properties: dict[str, object] = {
+        "method": request.method.upper(),
+        "url": f"{request.url.scheme}://{request.url.host}{request.url.path}",
+        "headers": _parse_headers(request, sanitizer, json_indent),
+        "trace_id": trace_id,
+    }
+
+    if request.url.params:
+        properties["query_params"] = _parse_query_params(request, sanitizer, json_indent)
+
+    if (body := _parse_body(request, sanitizer, json_indent)) is not None:
+        properties["body"] = body
+
+    return properties
+
+
+def parse_response(
+    response: httpx.Response,
+    sanitizer: Sanitizer,
+    json_indent: int | None = None,
+) -> dict[str, object]:
+    """Parse fields for a structured HTTP response log.
+
+    :param response: Response containing data to log
+    :param sanitizer: Sensitive data masking rules
+    :param json_indent: JSON log indentation width
+    :return: Structured response log fields
+    """
+    properties: dict[str, object] = {
+        "status_code": response.status_code,
+        "headers": _parse_headers(response, sanitizer, json_indent),
+        "trace_id": cast("dict[str, object]", response.request.extensions).get("trace_id", UNKNOWN_TRACE_ID),
+    }
+
+    if (body := _parse_body(response, sanitizer, json_indent)) is not None:
+        properties["body"] = body
+
+    return properties
+
+
+async def parse_response_async(
+    response: httpx.Response,
+    sanitizer: Sanitizer,
+    json_indent: int | None = None,
+) -> dict[str, object]:
+    """Parse fields for a structured asynchronous client response log.
+
+    The httpx response hook runs before the client finishes reading the body, so
+    an asynchronous response still has an asynchronous stream that cannot use synchronous read().
+
+    :return: Structured response log fields
+    """
+    await _aread_buffered(response)
+    return parse_response(response, sanitizer, json_indent)
+
+
+async def _aread_buffered(response: httpx.Response) -> None:
+    """Finish reading a non-streaming response body."""
+    if is_streamed(response):
+        return
+
+    # Logging must not fail the request: _parse_body handles unreadable bodies.
+    with suppress(Exception):
+        await response.aread()
+
+
+def _parse_headers(
+    r: httpx.Request | httpx.Response,
+    sanitizer: Sanitizer,
+    json_indent: int | None,
+) -> str:
+    try:
+        return to_json(sanitizer.apply(dict[str, str](r.headers)), json_indent)
+    except Exception as error:
+        _logger.exception(  # noqa: LOG007 — A traceback may expose request contents
+            "Не удалось подготовить поле HTTP лога: %s",
+            type(error).__name__,
+            exc_info=False,
+        )
+        return parse_error(error)
+
+
+def _parse_query_params(
+    request: httpx.Request,
+    sanitizer: Sanitizer,
+    json_indent: int | None,
+) -> str:
+    try:
+        return to_json(sanitizer.apply(dict[str, str](request.url.params)), json_indent)
+    except Exception as error:
+        _logger.exception(  # noqa: LOG007 — A traceback may expose request contents
+            "Не удалось подготовить поле HTTP лога: %s",
+            type(error).__name__,
+            exc_info=False,
+        )
+        return parse_error(error)
+
+
+def _parse_body(
+    value: httpx.Request | httpx.Response,
+    sanitizer: Sanitizer,
+    json_indent: int | None = None,
+) -> str | None:
+    if isinstance(value, cast("type[object]", httpx.Response)):
+        streamed = is_streamed(cast("httpx.Response", value))
+    else:
+        streamed = not is_buffered(cast("httpx.Request", value))
+    if streamed:
+        return STREAMED_CONTENT
+
+    try:
+        content = value.read()
+        content_type = cast("str", value.headers.get("Content-Type", "")).lower()
+        return _render_content(content, content_type, value, sanitizer, json_indent)
+    except Exception as error:
+        _logger.exception(  # noqa: LOG007 — A traceback may expose request contents
+            "Не удалось подготовить тело HTTP лога: %s",
+            type(error).__name__,
+            exc_info=False,
+        )
+        return parse_error(error)
+
+
+def _render_content(
+    content: bytes,
+    content_type: str,
+    value: httpx.Request | httpx.Response,
+    sanitizer: Sanitizer,
+    json_indent: int | None,
+) -> str | None:
+    if not content:
+        return None
+    if content_type.startswith("application/json"):
+        sanitized_body = sanitizer.apply(cast("object", json.loads(content)))
+        return trim(to_json(sanitized_body, json_indent), CFG.json_log_maxlength)
+    if content_type.startswith("text/plain"):
+        return trim(decode(value), CFG.plain_text_log_maxlength)
+    if content_type.startswith("application/octet-stream"):
+        return _render_octet_stream(content)
+    return f"<not logged, content-type: {content_type}>" if content_type else None
+
+
+def _render_octet_stream(content: bytes) -> str:
+    try:
+        return trim(content.decode(), CFG.octet_stream_log_maxlength)
+    except UnicodeDecodeError:
+        return f"<binary content ({len(content)} bytes)>"

http_client_structlog/py.typed

@@ -0,0 +1 @@
+This marker file indicates that the package supports type checking under PEP 561

http_client_structlog/sanitizer.py

@@ -0,0 +1,56 @@
+from collections.abc import Iterable, Sequence
+from typing import cast
+
+from http_client.utils.sanitizer import sanitize
+
+MASKED_VALUE = "****"
+
+
+class Sanitizer:
+    """Rules for masking sensitive data in logs.
+
+    Exact paths and common names need different lookups. The path `user.password` selects one
+    specific field, while `password` from the common secrets list must match at any
+    depth: secrets are equally sensitive at the body root and in nested objects.
+    """
+
+    def __init__(
+        self,
+        glom_paths: Sequence[str] = (),
+        secret_names: Iterable[str] = (),
+    ) -> None:
+        """Create an instance with the supplied settings."""
+        self._glom_paths = tuple(glom_paths)
+        self._secret_names = frozenset(name.lower() for name in secret_names)
+
+    def apply(self, value: object) -> object:
+        """Return a copy of the value with sensitive data masked."""
+        return self._mask_by_name(self._mask_by_path(value))
+
+    def _mask_by_path(self, value: object) -> object:
+        if not self._glom_paths:
+            return value
+
+        # The branches match, but sanitize uses a TypeVar with two allowed types,
+        # so it cannot accept the dict | list union.
+        if isinstance(value, dict):
+            return sanitize(cast("dict[str, object]", value), self._glom_paths)
+        if isinstance(value, list):
+            return sanitize(cast("list[object]", value), self._glom_paths)
+
+        return value
+
+    def _mask_by_name(self, value: object) -> object:
+        if not self._secret_names:
+            return value
+
+        if isinstance(value, dict):
+            return {
+                key: MASKED_VALUE if str(key).lower() in self._secret_names else self._mask_by_name(item)
+                for key, item in cast("dict[object, object]", value).items()
+            }
+
+        if isinstance(value, list):
+            return [self._mask_by_name(item) for item in cast("list[object]", value)]
+
+        return value