quadkit-http 0.0.42__tar.gz → 0.0.44__tar.gz

quadkit_http-0.0.44/.gitignore

@@ -0,0 +1,24 @@
+# Generated public-repository ignore rules.
+# Private monorepo paths are intentionally not referenced here.
+
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+build/
+dist/
+*.log
+.DS_Store
+.idea/
+.vscode/

{quadkit_http-0.0.42 → quadkit_http-0.0.44}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quadkit-http
-Version: 0.0.42
+Version: 0.0.44
 Summary: Outbound HTTP client for the Quadkit Framework
 Project-URL: Homepage, https://dbtinoy-.github.io/quadkit
 Project-URL: Repository, https://github.com/dbtinoy-/quadkit
@@ -57,7 +57,7 @@ DI integration.
 
 This package focuses on making **outbound** HTTP requests — for inbound web servers,
 use `quadkit-web`. Resilience patterns (retry, circuit breaker) are layered in
-through `quadkit-resilience`, not built in by default.
+through `the optional provider`, not built in by default.
 
 
 > Full documentation: [docs.quadkit.dev](https://docs.quadkit.dev)

{quadkit_http-0.0.42 → quadkit_http-0.0.44}/README.md

@@ -13,7 +13,7 @@ DI integration.
 
 This package focuses on making **outbound** HTTP requests — for inbound web servers,
 use `quadkit-web`. Resilience patterns (retry, circuit breaker) are layered in
-through `quadkit-resilience`, not built in by default.
+through `the optional provider`, not built in by default.
 
 
 > Full documentation: [docs.quadkit.dev](https://docs.quadkit.dev)

{quadkit_http-0.0.42 → quadkit_http-0.0.44}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quadkit-http"
-version = "0.0.42"
+version = "0.0.44"
 description = "Outbound HTTP client for the Quadkit Framework"
 readme = "README.md"
 requires-python = ">=3.11"

{quadkit_http-0.0.42 → quadkit_http-0.0.44}/src/quadkit/http/client/http_client.py

@@ -133,7 +133,7 @@ class HTTPClient(
         pool: Optional pre-configured :class:`ConnectionPool`.  Created from
             *config* when not provided.
         retry_policy: Retry policy for transient failures.  Defaults to a
-            :class:`~quadkit.resilience.RetryPolicy` with framework defaults.
+            :class:`~the optional provider module` with framework defaults.
         circuit_breaker: Optional circuit breaker; disabled when ``None``.
         interceptors: Zero or more interceptors applied to every request.
         resilience: Optional :class:`ResiliencePipelineProtocol` that combines

{quadkit_http-0.0.42 → quadkit_http-0.0.44}/src/quadkit/http/retry/policy.py

@@ -1,6 +1,6 @@
 """Retry policy for HTTP client requests.
 
-Local implementation to avoid cross-package imports from quadkit.resilience.
+Local implementation to avoid cross-package imports from the optional provider module.
 """
 
 from __future__ import annotations
@@ -63,7 +63,7 @@ class RetryPolicy:
 
     Executes an async callable with configurable retry logic, exponential
     backoff, and per-exception filtering.  Decision semantics follow the
-    canonical :mod:`quadkit.resilience` retry implementation for the
+    canonical :mod:`the optional provider module` retry implementation for the
     shared :class:`~quadkit.contracts.infra.resilience.models.RetryConfig`:
 
     * ``max_attempts`` is the *total* number of attempts including the

{quadkit_http-0.0.42 → quadkit_http-0.0.44}/tests/unit/test_http_client_verbs.py

@@ -278,9 +278,9 @@ class TestTimeoutNormalization:
     async def test_get_normalises_aiohttp_connection_error(self):
         """aiohttp.ClientError (connect refused/DNS/reset) → Err(HTTPConnectionError).
 
-        Regression (QK-USE-3, gatewai probe adoption): raw aiohttp errors used
+        Detail (QK-USE-3, probe adoption): raw aiohttp errors used
         to escape `get()` instead of mapping to the documented connection-error
-        Result — unreachable hosts crashed callers that expected `Err`.
+        Result — unreachable hosts reach callers that expected `Err`.
         """
         client = HTTPClientImpl(
             config=HTTPClientConfig(enforce_url_safety=False),

quadkit_http-0.0.42/.gitignore

@@ -1,214 +0,0 @@
-*
-!tests/
-!tests/**
-!README.md
-!AGENTS.md
-!DEVELOPMENT.md
-!QUICKGUIDE.md
-!MILESTONE*.md
-!TESTS*.md
-!CHANGELOG.md
-!AUDIT*.md
-!REF*.md
-!AUDIT*.json
-!LICENSE
-!LICENSE-MIT.txt
-!NOTICE
-!TRADEMARK.md
-!conftest.py
-!CONTRIBUTING.md
-!CODE_OF_CONDUCT.md
-!SECURITY.md
-!GOVERNANCE.md
-!pyproject.toml
-!uv.lock
-!docker-compose.yml
-!.env.example
-!.env.full.example
-!.importlinter
-!.superpowers/
-!.superpowers/**
-!.gitattributes
-!.editorconfig
-!Makefile
-!docker-compose.test.yml
-!quadkit.yaml.example
-!.github/
-!.github/workflows/
-!.github/workflows/**
-!.github/dependabot.yml
-!.devcontainer/
-!.devcontainer/**
-!tools/
-!tools/**
-!*example.yaml
-
-# Quadkit Packages
-!quadkit*/
-!quadkit*/pyproject.toml
-!quadkit*/CHANGELOG.md
-!quadkit*/README.md
-!quadkit*/alembic.ini
-!quadkit*/mypy.ini
-!quadkit*/*.yaml.example
-!quadkit*/src/
-!quadkit*/src/**
-!quadkit*/docs/
-!quadkit*/docs/**
-!quadkit*/tests/
-!quadkit*/tests/**
-
-# Keep quadkit docs
-!/docs/
-!docs/**
-
-# Session / cutover plans at the repo root
-!plans/
-!plans/**
-
-# Keep example files for README examples
-!/examples/
-!/examples/**
-
-# Re-ignore these AFTER negations (last match wins)
-*.tape
-examples/*/runs/
-__pycache__/
-*.pyc
-*.pyo
-*.egg-info/
-dist/
-build/
-.eggs/
-*.egg
-.pytest_cache/
-.mypy_cache/
-.ruff_cache/
-htmlcov/
-.coverage
-coverage.xml
-test.db
-!quadkit*/tests/fixtures/test.db
-*.log
-*.tmp
-
-# Company-specific files (keep private, do not commit)
-.company/
-COMPANY_*.md
-company-config/
-internal-docs/
-# Editor swap files
-*.swp
-
-!core/
-!packages/
-!core/quadkit*/
-!packages/quadkit*/
-!core/quadkit*/pyproject.toml
-!packages/quadkit*/pyproject.toml
-!core/quadkit*/CHANGELOG.md
-!packages/quadkit*/CHANGELOG.md
-!core/quadkit*/README.md
-!packages/quadkit*/README.md
-!core/quadkit*/alembic.ini
-!packages/quadkit*/alembic.ini
-!core/quadkit*/mypy.ini
-!packages/quadkit*/mypy.ini
-!core/quadkit*/*.yaml.example
-!packages/quadkit*/*.yaml.example
-!core/quadkit*/src/
-!core/quadkit*/src/**
-!packages/quadkit*/src/
-!packages/quadkit*/src/**
-!core/quadkit*/tests/
-!core/quadkit*/tests/**
-!packages/quadkit*/tests/
-!packages/quadkit*/tests/**
-!core/quadkit*/docs/
-!core/quadkit*/docs/**
-!packages/quadkit*/docs/
-!packages/quadkit*/docs/**
-
-# dev/
-!dev/
-!dev/**
-
-# Admin dev playground (committed dev asset; local SQLite files stay ignored)
-!packages/quadkit-admin/playground/
-!packages/quadkit-admin/playground/serve.py
-
-# gatewai apps
-!apps/
-!apps/**
-!apps/gatewai/
-!apps/gatewai/**
-apps/**/node_modules/
-apps/**/dist/
-apps/**/__pycache__/
-apps/**/*.pyc
-apps/**/*.db
-apps/**/*.db-wal
-apps/**/*.db-shm
-apps/**/.env
-apps/**/.env.*
-!apps/**/.env.example
-!apps/**/.env.full.example
-
-# Piccolina — nested app tracked in this monorepo (standalone .git removed).
-# Keep marketing packages and deployment secrets out of the tree.
-apps/piccolina/piccolina-marketing/
-apps/piccolina/piccolina-marketing-plans/
-apps/piccolina/secrets/
-apps/piccolina/**/secrets/
-apps/piccolina/**/*.pem
-apps/piccolina/**/*.key
-apps/piccolina/**/.venv/
-apps/piccolina/**/node_modules/
-apps/piccolina/**/__pycache__/
-apps/piccolina/**/*.pyc
-apps/piccolina/**/*.pbf
-apps/piccolina/**/.open-next/
-apps/piccolina/**/storage/
-apps/piccolina/**/.deploy-host
-
-# Re-exclude private content under the tiered paths.
-# MUST come after the !...docs/** negations above — last match wins.
-core/quadkit*/docs/plans/
-packages/quadkit*/docs/plans/
-core/quadkit*/docs/**/
-packages/quadkit*/docs/**/
-
-# Re-exclude tooling artifacts under the tiered paths
-__pycache__/
-*.pyc
-*.pyo
-*.egg-info/
-.pytest_cache/
-.mypy_cache/
-.ruff_cache/
-htmlcov/
-.coverage
-coverage.xml
-test.db
-*.tmp
-*.log
-!core/quadkit*/tests/fixtures/test.db
-!packages/quadkit*/tests/fixtures/test.db
-
-# Allow the generated example gifs to be tracked (README hero images).
-!core/quadkit*/docs/gifs/
-!core/quadkit*/docs/gifs/**
-!packages/*/quadkit*/docs/gifs/
-!packages/*/quadkit*/docs/gifs/**
-examples/*/screenshot.png
-!banner*
-apps/quadkit-playground/**/node_modules/
-apps/quadkit-playground/**/dist/
-apps/quadkit-playground/**/__pycache__/
-apps/quadkit-playground/**/*.pyc
-apps/quadkit-playground/**/*.db
-apps/quadkit-playground/**/*.db-wal
-apps/quadkit-playground/**/*.db-shm
-apps/quadkit-playground/projects/
-apps/quadkit-playground/quadkit/
-docs/superpowers/

quadkit_http-0.0.42/docs/ARCHITECTURE.md

@@ -1,250 +0,0 @@
-# Architecture
-
-Internal design of the `quadkit-http` package.
-
----
-
-## Role in the System
-
-```mermaid
-flowchart BT
-    Contracts[quadkit-contracts<br/>HTTPClientProtocol · InterceptorProtocol<br/>HttpResponse · HttpStatusError]
-    Core[quadkit<br/>DI · Provider · Module · Config · Result]
-    Http[quadkit-http<br/>HTTPClient · ConnectionPool · Retry · Interceptors]
-    Resilience[quadkit-resilience<br/>RetryPolicyProtocol · CircuitBreakerProtocol]
-    Consumers["Application code<br/>(LLM adapters, API clients)"]
-
-    Http --> Core
-    Http --> Contracts
-    Http -.->|optional| Resilience
-    Consumers --> Http
-```
-
-`quadkit-http` depends on `quadkit` and `quadkit-contracts`. Resilience is optional — resolved from the container at boot. Consumer code communicates through `HTTPClientProtocol`.
-
----
-
-## Client Architecture
-
-```mermaid
-flowchart LR
-    subgraph Public
-        HC[HTTPClient<br/>get · post · put · delete · patch · head]
-        BHC[BaseURLHTTPClient<br/>Base URL · default headers]
-    end
-    subgraph Internal
-        CP[ConnectionPool<br/>aiohttp TCPConnector]
-        RP[RetryPolicy<br/>Exponential backoff]
-        INT[Interceptor chain]
-    end
-    subgraph Optional
-        CB[CircuitBreakerProtocol]
-        RES[ResiliencePipelineProtocol]
-    end
-    HC --> CP & RP & INT
-    HC -.-> CB & RES
-    BHC --> HC
-```
-
-`HTTPClient` exposes a `request()` method (raises exceptions) and Result-returning verb methods for domain code. `BaseURLHTTPClient` wraps `HTTPClient` with base-URL resolution and default headers — designed for SDK-style callers.
-
-### ConnectionPool
-
-Wraps `aiohttp.TCPConnector` with configurable limits. Supports `warm_up(urls)` to pre-establish TLS handshakes for critical endpoints.
-
-### RetryPolicy
-
-Local implementation. Exponential backoff with optional jitter:
-
-```python
-config = RetryConfig(
-    max_attempts=3, base_delay=1.0,
-    max_delay=30.0, backoff_factor=2.0,
-    jitter=0.5, retry_on=(TimeoutError, ConnectionError),
-)
-```
-
-### Interceptors
-
-Receive typed `RequestContext` and raw response objects:
-
-```python
-class LoggingInterceptor:
-    async def intercept_request(self, ctx: RequestContext) -> RequestContext:
-        logger.info("http.request", method=ctx.method, url=ctx.url)
-        return ctx
-    async def intercept_response(self, response: Any) -> Any:
-        logger.info("http.response", status=getattr(response, "status", None))
-        return response
-```
-
----
-
-## Request/Response Model
-
-```mermaid
-sequenceDiagram
-    actor C as Caller
-    participant HC as HTTPClient
-    participant I as Interceptors
-    participant CB as CircuitBreaker
-    participant RP as RetryPolicy
-    participant S as Remote Server
-
-    C->>HC: get(url)
-    HC->>I: intercept_request(ctx)
-    HC->>CB: check state
-    alt circuit open
-        CB-->>HC: Raise HTTPCircuitOpenError
-    else
-        HC->>RP: execute(_execute)
-        RP->>S: HTTP request
-        S-->>RP: Response
-    end
-    HC->>I: intercept_response(raw)
-    HC->>HC: to HttpResponse
-    alt status >= 400
-        HC-->>C: Err(HTTPStatusError)
-    else
-        HC-->>C: Ok(HttpResponse)
-    end
-```
-
-All consumers receive `HttpResponse` (from `quadkit-contracts`) — a dataclass decoupling them from `aiohttp`:
-
-```python
-@dataclass(frozen=True)
-class HttpResponse:
-    status: int
-    headers: dict[str, str]
-    body: bytes
-    text: str                    # UTF-8 decoded
-    json: Any | None             # Parsed JSON
-    url: str
-    method: str
-    content_length: int | None
-```
-
-The client also provides `stream()` for byte-level streaming and `sse()` for `text/event-stream` parsing.
-
----
-
-## Authentication
-
-`quadkit-http` has no built-in auth handlers. Authentication uses standard HTTP header mechanisms:
-
-| Approach | Implementation |
-|----------|---------------|
-| **Bearer token** | `Authorization: Bearer <token>` header per-request or via `BaseURLHTTPClient` defaults |
-| **Basic auth** | `Authorization: Basic <base64>` directly |
-| **API key** | Custom header (e.g. `X-API-Key`) per request |
-| **OAuth 2.0** | Implement token-refresh interceptor using `InterceptorProtocol` |
-| **Custom** | Implement `InterceptorProtocol.intercept_request()` to mutate `RequestContext.headers` |
-
-```python
-# Bearer token via BaseURLHTTPClient
-client = BaseURLHTTPClient(
-    base_url="https://api.example.com/v1",
-    headers={"Authorization": "Bearer eyJhbGci..."},
-)
-
-# API key via interceptor
-class ApiKeyInterceptor:
-    async def intercept_request(self, ctx: RequestContext) -> RequestContext:
-        ctx.headers["X-API-Key"] = self._api_key
-        return ctx
-    async def intercept_response(self, response: Any) -> Any:
-        return response
-```
-
----
-
-## Error Handling
-
-Two-layer error strategy:
-
-- **Infrastructure** (`request()`) — raises `HTTPCircuitOpenError`, `HTTPRetryExhaustedError`
-- **Domain** (verb methods) — returns `Result[HttpResponse, HTTPClientError]`
-
-```
-HTTPClientError (QK_ERR_HTTP_001)
-  ├── HTTPConnectionError (002)   HTTPTimeoutError (003)
-  ├── HTTPInterceptorError (004)  HTTPCircuitOpenError (005)
-  ├── HTTPRetryExhaustedError (006)
-  └── HTTPStatusError (007)       # 4xx/5xx
-```
-
-Verb methods map 4xx/5xx to `Err(HTTPStatusError)` and transport failures to `Err(HTTPConnectionError | HTTPTimeoutError)`. Circuit-breaker open and retry-exhausted always propagate as exceptions.
-
----
-
-## Contracts Used
-
-| Protocol / Type | Source | Purpose |
-|----------------|--------|---------|
-| `HTTPClientProtocol` | `quadkit.contracts.web.http_protocols` | Outbound HTTP client interface |
-| `InterceptorProtocol` | `quadkit.contracts.web.http_protocols` | Request/response interception |
-| `InterceptorChainProtocol` | `quadkit.contracts.web.http_protocols` | Interceptor chain management |
-| `HttpResponse` | `quadkit.contracts.web.http_models` | Transport-agnostic response |
-| `HttpStatusError` | `quadkit.contracts.web.http_models` | 4xx/5xx error with response |
-| `HTTPSessionProtocol` | `quadkit.contracts.web.http_protocols` | HTTP session abstraction |
-| `ServerSentEvent` | `quadkit.contracts.web.sse` | SSE event dataclass |
-| `RetryPolicyProtocol` | `quadkit.contracts.infra.resilience` | Retry policy (optional DI) |
-| `CircuitBreakerProtocol` | `quadkit.contracts.infra.resilience` | Circuit breaker (optional DI) |
-| `ResiliencePipelineProtocol` | `quadkit.contracts.infra.resilience` | Composable resilience (optional DI) |
-| `MetricsRecorderProtocol` | `quadkit.contracts.observability` | Request metrics (optional DI) |
-
----
-
-## Extension Points
-
-| Point | Interface | Default | Customise by |
-|-------|-----------|---------|--------------|
-| Request interceptor | `InterceptorProtocol.intercept_request()` | None | Implement protocol, inject via constructor |
-| Response interceptor | `InterceptorProtocol.intercept_response()` | None | Implement protocol, inject via constructor |
-| Retry policy | `RetryPolicyProtocol` | Local `RetryPolicy` with defaults | Inject via constructor or register before boot |
-| Circuit breaker | `CircuitBreakerProtocol` | None | Register `CircuitBreakerRegistryProtocol` before boot |
-| Resilience pipeline | `ResiliencePipelineProtocol` | None | Register before boot |
-| Metrics | `MetricsRecorderProtocol` | None | Inject via constructor |
-
-All resilience dependencies are **optional** — the client works without them.
-
----
-
-## DI Registration
-
-```python
-class HTTPProvider(Provider):
-    name = "http"
-    priority = ProviderPriority.INFRASTRUCTURE
-
-    def __init__(self, config: HTTPClientConfig | None = None) -> None:
-        self._config = config or HTTPClientConfig()
-        self._client: HTTPClient | None = None
-
-    async def register(self, container: ContainerRegistrarProtocol) -> None:
-        container.singleton(HTTPClient, self._get_client)
-        container.singleton(HTTPClientProtocol, self._get_client)
-
-    async def boot(self, container: ContainerResolverProtocol) -> None:
-        retry = await _try_resolve(container, RetryPolicyProtocol)
-        cb = await _try_resolve_circuit_breaker(container)
-        resilience = await _try_resolve(container, ResiliencePipelineProtocol)
-        self._client = HTTPClient(config=self._config, retry_policy=retry, circuit_breaker=cb, resilience=resilience)
-        await self._client.start()
-
-    async def shutdown(self) -> None:
-        if self._client:
-            await self._client.stop()
-```
-
-Module registration:
-
-```python
-from quadkit.http import HTTPModule
-
-app.add_module(HTTPModule.configure())  # defaults
-app.add_module(HTTPModule.configure(    # custom
-    HTTPClientConfig(pool=ConnectionPoolConfig(timeout=60.0))
-))
-```

quadkit_http-0.0.42/docs/CONFIGURATION.md

@@ -1,50 +0,0 @@
----
-title: quadkit-http Configuration
-description: Every configuration key for the HTTP client
----
-
-Config section: `http`  
-Env prefix: `QK_HTTP__`  
-Config model: `HTTPClientConfig`
-
-## Top-level
-
-| Key | Type | Default | Env var | Description |
-|-----|------|---------|---------|-------------|
-| `pool` | `ConnectionPoolConfig` | — | `QK_HTTP__POOL__*` | Connection pool settings |
-| `proxy` | `str \| None` | `None` | `QK_HTTP__PROXY` | HTTP/HTTPS proxy URL |
-| `trust_env` | `bool` | `True` | `QK_HTTP__TRUST_ENV` | Read proxy from env vars |
-| `cookie_jar` | `bool` | `True` | `QK_HTTP__COOKIE_JAR` | Enable in-memory cookie jar |
-
-## ConnectionPoolConfig
-
-| Key | Type | Default | Env var | Description |
-|-----|------|---------|---------|-------------|
-| `max_connections` | `int` | `10` | `QK_HTTP__POOL__MAX_CONNECTIONS` | Total concurrent connections |
-| `max_keepalive_connections` | `int` | `5` | `QK_HTTP__POOL__MAX_KEEPALIVE_CONNECTIONS` | Keep-alive per host |
-| `max_connections_per_host` | `int` | `10` | `QK_HTTP__POOL__MAX_CONNECTIONS_PER_HOST` | Max per host |
-| `timeout` | `float` | `30.0` | `QK_HTTP__POOL__TIMEOUT` | Request timeout (seconds) |
-| `ttl_dns_cache` | `int` | `300` | `QK_HTTP__POOL__TTL_DNS_CACHE` | DNS cache TTL (seconds) |
-| `force_close` | `bool` | `False` | `QK_HTTP__POOL__FORCE_CLOSE` | Force-close connections after use |
-
-## Example YAML
-
-```yaml
-http:
-  pool:
-    max_connections: 50
-    max_keepalive_connections: 20
-    timeout: 10.0
-    ttl_dns_cache: 60
-  proxy: http://proxy.example.com:8080
-  trust_env: true
-  cookie_jar: true
-```
-
-Env var override form:
-
-```bash
-export QK_HTTP__POOL__TIMEOUT=5.0
-export QK_HTTP__POOL__MAX_CONNECTIONS=100
-export QK_HTTP__PROXY=http://proxy.internal:8080
-```