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

http_client/config.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+import httpx
+from httpx._config import DEFAULT_MAX_REDIRECTS
+
+if TYPE_CHECKING:
+    import ssl
+
+    from httpx._types import AuthTypes, TimeoutTypes, URLTypes
+
+    from .types import RequestHook, ResponseHook, SendDecorator, StreamRequestDecorator
+
+DEFAULT_OCTET_STREAM_LOG_MAXLENGTH = 1024
+
+
+@dataclass(kw_only=True, slots=True)
+class HttpClientConfig:
+    """Transport settings collected by options before creating the HTTP client."""
+
+    base_url: URLTypes
+    verify: ssl.SSLContext | str | bool = True
+    auth: AuthTypes | None = None
+    timeout: TimeoutTypes = field(default_factory=lambda: httpx.Timeout(60))
+    url_suffix: str = ""
+    request_hooks: list[RequestHook] = field(default_factory=list)
+    response_hooks: list[ResponseHook] = field(default_factory=list)
+    send_decorators: list[SendDecorator] = field(default_factory=list)
+    stream_decorators: list[StreamRequestDecorator] = field(default_factory=list)
+    follow_redirects: bool = False
+    max_redirects: int = DEFAULT_MAX_REDIRECTS
+
+
+@dataclass(kw_only=True)
+class LoggingConfig:
+    """HTTP log formatting and length limit settings."""
+
+    log_level: int = logging.INFO
+    json_indent: int | None = None
+    use_line_breaks: bool = False
+    octet_stream_log_maxlength: int | None = DEFAULT_OCTET_STREAM_LOG_MAXLENGTH
+    plain_text_log_maxlength: int | None = None
+    json_log_maxlength: int | None = None
+
+
+LOGGING_CONFIG = LoggingConfig()
+
+
+def configure_logging(options: LoggingConfig | None = None) -> None:
+    """Configure HTTP log formatting using environment variables.
+
+    :param options: Default logging settings
+    """
+    settings = options or LoggingConfig()
+    if log_level_env := os.getenv("HTTP_CLIENT_LOG_LEVEL", None):
+        LOGGING_CONFIG.log_level = int(log_level_env)
+    else:
+        LOGGING_CONFIG.log_level = settings.log_level
+    if use_line_breaks_env := os.getenv("HTTP_CLIENT_USE_LINE_BREAKS", None):
+        LOGGING_CONFIG.use_line_breaks = use_line_breaks_env.lower() in ["true", "y", "yes", "on"]
+    else:
+        LOGGING_CONFIG.use_line_breaks = settings.use_line_breaks
+    if json_indent_env := os.getenv("HTTP_CLIENT_JSON_INDENT", None):
+        LOGGING_CONFIG.json_indent = int(json_indent_env)
+    else:
+        LOGGING_CONFIG.json_indent = settings.json_indent
+    if octet_stream_log_maxlength_env := os.getenv("HTTP_CLIENT_OCTET_STREAM_LOG_MAXLENGTH", None):
+        LOGGING_CONFIG.octet_stream_log_maxlength = int(octet_stream_log_maxlength_env)
+    else:
+        LOGGING_CONFIG.octet_stream_log_maxlength = settings.octet_stream_log_maxlength
+    if plain_text_log_maxlength_env := os.getenv("HTTP_CLIENT_PLAIN_TEXT_LOG_MAXLENGTH", None):
+        LOGGING_CONFIG.plain_text_log_maxlength = int(plain_text_log_maxlength_env)
+    else:
+        LOGGING_CONFIG.plain_text_log_maxlength = settings.plain_text_log_maxlength
+    if json_log_maxlength_env := os.getenv("HTTP_CLIENT_JSON_LOG_MAXLENGTH", None):
+        LOGGING_CONFIG.json_log_maxlength = int(json_log_maxlength_env)
+    else:
+        LOGGING_CONFIG.json_log_maxlength = settings.json_log_maxlength

http_client/event_hooks.py

@@ -0,0 +1,159 @@
+import logging
+from collections.abc import Sequence
+from uuid import uuid4
+
+from httpx import Request, Response
+
+from .config import LOGGING_CONFIG as CFG
+from .types import RequestHook, ResponseHook
+from .utils import logutils, traceparent
+
+REQUEST_ID_HEADER = "X-Request-ID"
+TRACEPARENT_HEADER = "Traceparent"
+
+# Always mask these: leaking a single secret in logs is far worse
+# than an unnecessary asterisk.
+DEFAULT_SANITIZE_KEYS: tuple[str, ...] = (
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "set-cookie",
+    "x-api-key",
+    "api-key",
+    "api_key",
+    "access_token",
+    "refresh_token",
+    "password",
+    "secret",
+    "token",
+)
+
+
+def request_logger_hook(
+    logger: logging.Logger,
+    sanitize_keys: Sequence[str],
+    *,
+    json_indent: int | None = None,
+    use_line_breaks: bool | None = None,
+    log_level: int | None = None,
+) -> RequestHook:
+    """Create a hook for safe HTTP request logging.
+
+    :param logger: Log record recipient
+    :param sanitize_keys: Fields to mask
+    :param json_indent: JSON indentation
+    :param use_line_breaks: Multiline formatting
+    :param log_level: Log level
+    :returns: Request hook
+    """
+
+    def log_request_hook(request: Request) -> None:
+        log_msg = logutils.create_request_log(
+            r=request,
+            sanitize_keys=sanitize_keys,
+            json_indent=_indent(json_indent),
+            use_line_breaks=_line_breaks(use_line_breaks=use_line_breaks),
+        )
+        logger.log(level=_level(log_level), msg=log_msg)
+
+    return log_request_hook
+
+
+def response_logger_hook(
+    logger: logging.Logger,
+    sanitize_keys: Sequence[str],
+    *,
+    json_indent: int | None = None,
+    use_line_breaks: bool | None = None,
+    log_level: int | None = None,
+) -> ResponseHook:
+    """Create a hook for safe HTTP response logging.
+
+    :param logger: Log record recipient
+    :param sanitize_keys: Fields to mask
+    :param json_indent: JSON indentation
+    :param use_line_breaks: Multiline formatting
+    :param log_level: Log level
+    :returns: Response hook
+    """
+
+    def log_response_hook(response: Response) -> None:
+        log_msg = logutils.create_response_log(
+            r=response,
+            sanitize_keys=sanitize_keys,
+            json_indent=_indent(json_indent),
+            use_line_breaks=_line_breaks(use_line_breaks=use_line_breaks),
+        )
+        logger.log(level=_level(log_level), msg=log_msg)
+
+    return log_response_hook
+
+
+def async_response_logger_hook(
+    logger: logging.Logger,
+    sanitize_keys: Sequence[str],
+    *,
+    json_indent: int | None = None,
+    use_line_breaks: bool | 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: Response) -> None:
+        log_msg = await logutils.create_response_log_async(
+            r=response,
+            sanitize_keys=sanitize_keys,
+            json_indent=_indent(json_indent),
+            use_line_breaks=_line_breaks(use_line_breaks=use_line_breaks),
+        )
+        logger.log(level=_level(log_level), msg=log_msg)
+
+    return log_response_hook
+
+
+def request_id_hook(request: Request) -> None:
+    """Set a request ID if it is missing.
+
+    Preserve the existing value deliberately. The hook runs every time a request object
+    is sent, and retries send the same object: overwriting the ID would give
+    each attempt a new ID, preventing correlation in logs. For the same reason,
+    preserve the ID supplied by the caller.
+    """
+    request.headers.setdefault(REQUEST_ID_HEADER, str(uuid4()))
+
+
+def traceparent_hook(request: Request) -> None:
+    """Set traceparent if it is missing. See :func:`request_id_hook` for details."""
+    request.headers.setdefault(TRACEPARENT_HEADER, traceparent.generate())
+
+
+def add_default_headers_hook(headers: dict[str, str]) -> RequestHook:
+    """Create a hook to add missing request headers.
+
+    :param headers: Default headers
+    :returns: Request hook
+    """
+    defaults = dict(headers)
+
+    def add_default_headers(request: Request) -> None:
+        for name, value in defaults.items():
+            if name not in request.headers:
+                request.headers[name] = value
+
+    return add_default_headers
+
+
+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
+
+
+def _line_breaks(*, use_line_breaks: bool | None) -> bool:
+    return use_line_breaks if use_line_breaks is not None else CFG.use_line_breaks

http_client/options.py

@@ -0,0 +1,226 @@
+import importlib
+import ssl
+from logging import Logger
+from typing import TYPE_CHECKING, Unpack, cast
+
+from httpx._config import DEFAULT_MAX_REDIRECTS
+from httpx._types import AuthTypes, TimeoutTypes
+
+from .client import AsyncHttpClient, BaseHttpClient, ClientOption, _reject_unknown_options
+from .event_hooks import (
+    DEFAULT_SANITIZE_KEYS,
+    add_default_headers_hook,
+    async_response_logger_hook,
+    request_id_hook,
+    request_logger_hook,
+    response_logger_hook,
+    traceparent_hook,
+)
+from .types import LoggingOptions, RequestHook, ResponseHook, SendDecorator, StreamRequestDecorator
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+def with_timeout(timeout: TimeoutTypes) -> ClientOption:
+    """Set the HTTP client timeout.
+
+    :param timeout: Timeout
+    :returns: Option that sets the HTTP client timeout
+    """
+
+    def option(client: BaseHttpClient) -> None:
+        client.timeout = timeout
+
+    return option
+
+
+def with_verify_context(*, verify: ssl.SSLContext | str | bool) -> ClientOption:
+    """Set the SSL certificate verification context for HTTPS connections.
+
+    `verify=False` disables certificate verification completely and makes the connection
+    vulnerable to man-in-the-middle attacks. Use it only for local debugging.
+
+    :param verify: SSL context, CA certificate path, or False to disable verification
+    :returns: Option that sets the HTTP client certificate verification context
+    """
+    # httpx deprecated string verify values in 0.28, so convert paths to contexts here.
+    context = ssl.create_default_context(cafile=verify) if isinstance(verify, str) else verify
+
+    def option(client: BaseHttpClient) -> None:
+        client.verify = context
+
+    return option
+
+
+def use_truststore() -> ClientOption:
+    """Use the system SSL certificate store to verify HTTPS connections.
+
+    :raises ImportError: If the truststore module is not installed
+    :return: Option that sets the certificate verification context using the system store.
+    """
+    try:
+        truststore = importlib.import_module("truststore")
+
+        context_factory = cast("Callable[[int], ssl.SSLContext]", truststore.SSLContext)
+        ctx = context_factory(ssl.PROTOCOL_TLS_CLIENT)
+        return with_verify_context(verify=ctx)
+    except ImportError:
+        message = "Для использования truststore установите cloudru-qa-http-client[truststore]"
+        raise ImportError(message) from None
+
+
+def with_auth(auth: AuthTypes) -> ClientOption:
+    """Set HTTP client authentication.
+
+    :param auth: Authentication credentials
+    :returns: Option that sets HTTP client authentication
+    """
+
+    def option(client: BaseHttpClient) -> None:
+        client.auth = auth
+
+    return option
+
+
+def with_autogenerated_request_id() -> ClientOption:
+    """Set an automatically generated ID for each HTTP client request.
+
+    :returns: Option that enables automatic request IDs for the HTTP client
+    """
+
+    def option(client: BaseHttpClient) -> None:
+        client.add_request_hook(request_id_hook, prepend=True)
+
+    return option
+
+
+def with_autogenerated_traceparent() -> ClientOption:
+    """Set an automatically generated trace ID for each HTTP client request.
+
+    :returns: Option that enables automatic trace IDs for the HTTP client
+    """
+
+    def option(client: BaseHttpClient) -> None:
+        client.add_request_hook(traceparent_hook, prepend=True)
+
+    return option
+
+
+def with_send_decorator(decorator: SendDecorator) -> ClientOption:
+    """Add a decorator to the HTTP client send method.
+
+    :param decorator: Decorator to apply to the send method
+    :returns: Option that adds a decorator to the HTTP client
+    """
+
+    def option(client: BaseHttpClient) -> None:
+        client.add_send_decorator(decorator)
+
+    return option
+
+
+def with_stream_decorator(decorator: StreamRequestDecorator) -> ClientOption:
+    """Add a decorator to the HTTP client stream_request method.
+
+    :param decorator: Decorator to apply to the stream_request method
+    :returns: Option that adds a decorator to the HTTP client
+    """
+
+    def option(client: BaseHttpClient) -> None:
+        client.add_stream_decorator(decorator)
+
+    return option
+
+
+def with_logger(logger: Logger, **settings: Unpack[LoggingOptions]) -> ClientOption:
+    """Set the logger for HTTP client requests and responses.
+
+    :param logger: Logger
+    :param sanitize_keys: Keys in [glom](https://glom.readthedocs.io/en/latest/) format
+                          to mask sensitive data
+    :param json_indent: JSON log indentation width (no indentation by default)
+    :param use_line_breaks: Whether to add line breaks between request properties (disabled by default)
+    :param log_level: HTTP client log level, INFO by default
+    :param use_default_sanitize_keys: Whether to mask common secrets
+                                      (see `DEFAULT_SANITIZE_KEYS`) in addition to `sanitize_keys`
+    :returns: Option that sets the HTTP client logger and hooks
+    """
+    _reject_unknown_options(settings, LoggingOptions.__optional_keys__)
+    sanitize_keys = settings.get("sanitize_keys")
+    json_indent = settings.get("json_indent")
+    use_line_breaks = settings.get("use_line_breaks")
+    log_level = settings.get("log_level")
+    use_default_sanitize_keys = settings.get("use_default_sanitize_keys", True)
+    keys = list(sanitize_keys or [])
+    if use_default_sanitize_keys:
+        keys.extend(key for key in DEFAULT_SANITIZE_KEYS if key not in keys)
+
+    def option(client: BaseHttpClient) -> None:
+        client.add_request_hook(
+            request_logger_hook(
+                logger=logger,
+                sanitize_keys=keys,
+                json_indent=json_indent,
+                use_line_breaks=use_line_breaks,
+                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,
+                sanitize_keys=keys,
+                json_indent=json_indent,
+                use_line_breaks=use_line_breaks,
+                log_level=log_level,
+            )
+        )
+
+    return option
+
+
+def with_default_headers(headers: dict[str, str]) -> ClientOption:
+    """Set default HTTP client headers.
+
+    :param headers: Header dictionary
+    :returns: Option that sets default HTTP client headers
+    """
+
+    def option(client: BaseHttpClient) -> None:
+        client.add_request_hook(add_default_headers_hook(headers))
+
+    return option
+
+
+def with_request_hook(hook: RequestHook) -> ClientOption:
+    """Set a hook to process HTTP requests before sending them."""
+
+    def option(client: BaseHttpClient) -> None:
+        client.add_request_hook(hook)
+
+    return option
+
+
+def with_response_hook(hook: ResponseHook) -> ClientOption:
+    """Set a hook to process HTTP responses after receiving them."""
+
+    def option(client: BaseHttpClient) -> None:
+        client.add_response_hook(hook)
+
+    return option
+
+
+def with_follow_redirects(max_redirects: int = DEFAULT_MAX_REDIRECTS) -> ClientOption:
+    """Enable HTTP client redirects.
+
+    :param max_redirects: Maximum number of redirects
+    :returns: Option that enables HTTP client redirects
+    """
+
+    def option(client: BaseHttpClient) -> None:
+        client.enable_redirects(max_redirects)
+
+    return option

http_client/py.typed

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

http_client/types.py

@@ -0,0 +1,141 @@
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from contextlib import AbstractAsyncContextManager, AbstractContextManager
+from typing import Protocol, TypedDict
+
+import httpx
+from httpx._client import UseClientDefault
+from httpx._types import (
+    AuthTypes,
+    CookieTypes,
+    HeaderTypes,
+    QueryParamTypes,
+    RequestContent,
+    RequestFiles,
+    TimeoutTypes,
+)
+
+type EventHook[T = object] = Callable[[T], Awaitable[None] | None]
+type RequestHook = EventHook[httpx.Request]
+type ResponseHook = EventHook[httpx.Response]
+type RequestData = Mapping[str, object]
+
+
+class LoggingOptions(TypedDict, total=False):
+    """Named logging settings for an individual HTTP client."""
+
+    sanitize_keys: Sequence[str] | None
+    json_indent: int | None
+    use_line_breaks: bool | None
+    log_level: int | None
+    use_default_sanitize_keys: bool
+
+
+class QueryOptions(TypedDict, total=False):
+    """Named options for an HTTP request without a body."""
+
+    params: QueryParamTypes | None
+    headers: HeaderTypes | None
+    cookies: CookieTypes | None
+    auth: AuthTypes | None
+    follow_redirects: bool | None
+    timeout: TimeoutTypes | UseClientDefault
+    extensions: dict[str, object] | None
+    anonymous: bool
+
+
+class RequestOptions(QueryOptions, total=False):
+    """Named options for an HTTP request with a body."""
+
+    content: RequestContent | None
+    data: RequestData | None
+    files: RequestFiles | None
+    json: object
+
+
+class StreamOptions(TypedDict, total=False):
+    """Options for sending a prepared request in streaming mode."""
+
+    auth: AuthTypes | None
+    follow_redirects: bool | None
+    anonymous: bool
+
+
+class SendOptions(StreamOptions, total=False):
+    """Options for sending a prepared HTTP request."""
+
+    stream: bool
+
+
+class SyncSendMethod(Protocol):
+    """Protocol for a synchronous send method."""
+
+    def __call__(
+        self,
+        request: httpx.Request,
+        *,
+        stream: bool = False,
+        auth: AuthTypes | None = None,
+        follow_redirects: bool | None = None,
+        anonymous: bool = False,
+    ) -> httpx.Response:
+        """Send a prepared HTTP request and return the response."""
+        ...
+
+
+class AsyncSendMethod(Protocol):
+    """Protocol for an asynchronous send method."""
+
+    async def __call__(
+        self,
+        request: httpx.Request,
+        *,
+        stream: bool = False,
+        auth: AuthTypes | None = None,
+        follow_redirects: bool | None = None,
+        anonymous: bool = False,
+    ) -> httpx.Response:
+        """Send a prepared HTTP request asynchronously and return the response."""
+        ...
+
+
+class SyncStreamRequestMethod(Protocol):
+    """Protocol for a synchronous stream_request method."""
+
+    def __call__(
+        self,
+        request: httpx.Request,
+        *,
+        anonymous: bool = False,
+        auth: AuthTypes | None = None,
+        follow_redirects: bool | None = None,
+    ) -> AbstractContextManager[httpx.Response]:
+        """Open a streaming HTTP response context."""
+        ...
+
+
+class AsyncStreamRequestMethod(Protocol):
+    """Protocol for an asynchronous stream_request method."""
+
+    def __call__(
+        self,
+        request: httpx.Request,
+        *,
+        anonymous: bool = False,
+        auth: AuthTypes | None = None,
+        follow_redirects: bool | None = None,
+    ) -> AbstractAsyncContextManager[httpx.Response]:
+        """Open an asynchronous streaming HTTP response context."""
+        ...
+
+
+# Types for send method decorators
+SyncSendDecorator = Callable[[SyncSendMethod], SyncSendMethod]
+AsyncSendDecorator = Callable[[AsyncSendMethod], AsyncSendMethod]
+
+SendDecorator = SyncSendDecorator | AsyncSendDecorator
+
+# Types for stream_request method decorators
+SyncStreamRequestDecorator = Callable[[SyncStreamRequestMethod], SyncStreamRequestMethod]
+AsyncStreamRequestDecorator = Callable[[AsyncStreamRequestMethod], AsyncStreamRequestMethod]
+
+StreamRequestDecorator = SyncStreamRequestDecorator | AsyncStreamRequestDecorator