# `mgf-http` — scope policy

> `mgf-http`'s **scope policy** (federation rule family **SP**) — what belongs in
> this async HTTP-client adapter. A proposed addition is in scope only if it
> passes the §3 gate.

## §1 In scope (SP-01)

A thin, typed **async HTTP client** for mgf-common consumers — a safe-defaults
wrapper over `httpx`:

- typed async client (`AsyncHttpClient`) over `httpx.AsyncClient`
- retries with exponential backoff + jitter + `Retry-After` honouring (`RetryPolicy`)
- per-request timeouts, connection-pool defaults, `verify_tls` footgun guard
- header/secret + URL-userinfo redaction for safe logging
- streaming downloads with atomic write + resume (`DownloadResult`)
- OTel-aware structured request logging
- a typed transport-error hierarchy (`HttpTransportError`, `IntegrityError`)

The boundary: **safe, typed, observable wiring over httpx.** Consumers own their
endpoints, payloads, and auth.

## §2 Out of scope (SP-02) — with reasons

| Not here | Why | Where instead |
|---|---|---|
| The HTTP protocol implementation | that's httpx's job; we wrap it | `httpx` |
| A synchronous client | async-only by charter | `httpx` (sync) directly |
| A typed REST/GraphQL SDK generator | beyond an adapter; per-API | `openapi-generator` / hand-rolled |
| A response cache / rate-limiter store | consumer/infra concern | `mgf-common` rate_limit / a cache sibling |
| Server-side / ASGI | this is a client | `mgf-fastapi` |
| Auth token acquisition (OAuth flows) | consumer-owned | the consumer app |

## §3 Scope-creep gate (SP-03)

A PR adding a module/helper MUST answer: (1) does it need httpx/async transport
types (else → `mgf-common`)? (2) is it safe-defaults wiring, not a new protocol
or a consumer domain concern? (3) is there a consumer demand signal, or speculative?
Any "no/unclear" blocks it.

## §4 Adjacent scope (SP-04)

Adjacent (not yet in): circuit-breaker, response caching, request signing helpers,
a sync façade. Move adjacent → in only on a documented consumer-demand signal
(a `FEEDBACK.md` paper / real sibling need), never speculatively.

## §5 Alternatives for out-of-scope needs (SP-05)

Protocol/transport → `httpx`; sync → `httpx` sync; SDK codegen → OpenAPI tooling;
caching/rate-limit → `mgf-common` primitives; server-side → `mgf-fastapi`.

## §6 Revisiting scope (SP-06)

Revisited at every **MAJOR** boundary (0.x → 1.0, later majors). A major bump
re-justifies the whole surface against §1/§2 and re-affirms the async-only,
adapter-not-SDK invariant.
