moloapp/plans/08-clients-openapi.md

# 08 - Clients, OpenAPI, Test Client

Title: Clients, OpenAPI, Test Client
Scope: plan.md sections 2, 6, 8 partial, 10 step 5 partial.
Topics: HTTP/REST client, REST standards, OpenAPI generation, test client.

## 1. Purpose and philosophy

This file plans the outbound and introspection side of MoloApp: the modern
async HTTP/API/REST client, the REST conventions every app follows, automatic
OpenAPI document generation from routers plus validation models, and the test
client that drives the real stack without real network I/O.

Philosophy:

- One client core. `Client` owns pooling, timeouts, retries, auth, cookies,
  proxy, TLS, logging. Convenience free functions exist only for one-off
  scripts and never pool.
- Client parity. Everything the framework serves ships a client. This file
  owns HTTP/REST; realtime clients live in 06-realtime.md and reuse the
  timeout, retry, auth, logging and backoff behavior defined here.
- Transport injection. Real network, in-process app dispatch, and scripted
  mocks are all `Transport` implementations behind one interface. Tests swap
  the transport, never the calling code.
- Spec from code. Routers plus validation models are the single source of
  truth; the OpenAPI document is derived, never hand-maintained.
- Tests through the real stack. The test client runs routing, middleware,
  validation, views and DB for real; only the socket is fake.

## 2. Best practices (from research)

1. Reuse connections via a long-lived client. Top-level one-shot request APIs
   open a new connection per call; a `Client` instance pools and reuses TCP
   connections to the same host, cutting latency, CPU and congestion. Client
   instances additionally carry cookie persistence, shared config, proxying
   and HTTP/2 support (httpx Clients doc).
2. Separate timeout phases. Configure connect, read, write and pool timeouts
   independently with a sane default total, so slow servers and slow networks
   fail fast in the right place (httpx Timeouts/Clients docs).
3. Retry only what is safe. Retry connect errors and idempotent methods on
   429/502/503/504 with exponential backoff and jitter; never auto-retry
   non-idempotent bodies unless explicitly enabled (httpx Transports doc on
   connection retries; Microsoft REST guidance on throttling with Retry-After).
4. Design resources, not RPC. Nouns in URIs, verbs in HTTP methods, plural
   collection names, stateless requests, standard status codes, versioning by
   path or media type, pagination/filtering/sorting as query parameters, and
   `Retry-After` plus problem-detail bodies on errors (Microsoft API design
   best practices).
5. Generate OpenAPI from code annotations. FastAPI derives paths, parameters,
   request/response schemas (JSON Schema), security schemes and examples from
   route decorators plus Pydantic models, serves `openapi.json` plus Swagger
   UI/ReDoc, and allows app-level overrides of the generated document
   (FastAPI OpenAPI docs).
6. Emit OpenAPI 3.1. The 3.1.x line aligns schemas fully with JSON Schema
   (draft 2020-12), uses `openapi: 3.1.x`, `info`, `paths`, `components`,
   `tags`, `servers` and `security` top-level objects, and path templating
   with `{param}` expressions (OpenAPI Specification v3.1.0).
7. Test through the app object. Starlette/FastAPI `TestClient` wraps an HTTP
   client whose transport calls the ASGI app in-process: same routing,
   middleware, validation and responses as production, no socket. Lifespan
   events run via context-manager entry (FastAPI Testing tutorial; httpx
   ASGI/WSGI/Mock transports doc).

## 3. Structure

Directories (one class or concern per file, deep over flat):

```
src/client/
  client.h, client.cpp            # molo::client::Client, config + verbs
  request.h, request.cpp          # ClientRequest builder (method, URL, headers, body)
  response.h, response.cpp        # ClientResponse (status, headers, body, json/xml/form)
  url.h, url.cpp                  # URL parse, join, query encode
  headers.h                       # shared header map helpers (thin, delegates to runtime)
  cookies.h, cookies.cpp          # CookieJar, persistence across requests
  auth.h, auth.cpp                # Basic, Bearer, ApiKey, custom Auth base
  timeouts.h                      # Timeout phases struct
  retry.h, retry.cpp              # RetryPolicy, backoff with jitter
  pool.h, pool.cpp                # connection pool (delegates sockets to 01-runtime.md)
  proxy.h, proxy.cpp              # proxy selection incl. NO_PROXY matching
  transport.h                     # Transport interface
  transports/
    http_transport.h, .cpp        # real network via runtime event loop
    mock_transport.h, .cpp        # scripted request->response double
    app_transport.h, .cpp         # in-process dispatch into Application (test client base)
  body/
    json_body.h, .cpp
    form_body.h, .cpp             # urlencoded + multipart, file upload parts
    xml_body.h, .cpp
    stream_body.h, .cpp           # chunked upload/download with backpressure
  rest/
    resource.h, .cpp              # Resource fluent helper (CRUD over a base path)
    paginator.h, .cpp             # page/limit/offset/cursor iteration
    errors.h, .cpp                # raise-for-status, ProblemDetails parse
src/openapi/
  document.h, .cpp                # OpenAPI document model, serialize JSON (+YAML)
  builder.h, .cpp                 # builds document from routers + validation models
  schema.h, .cpp                  # validation-model to JSON Schema converter
  routes.h                        # serves /openapi.json, /docs (Swagger UI), /redoc
  extensions.h                    # x- vendor extensions, app overrides hook
src/testing/
  test_client.h, .cpp             # TestClient: Client preset with AppTransport
  fixtures.h, .cpp                # DB/ORM fixtures, seeded app factory
  time.h, .cpp                    # frozen/manual clock injected into runtime + ORM
  assertions.h, .cpp              # status/json/header/schema assertion helpers
```

Namespaces: `molo::client`, `molo::client::transports`, `molo::client::rest`,
`molo::openapi`, `molo::testing`.

Key classes:

- `client::Client`: coroutine verbs `get/post/put/patch/delete/head/options`,
  `send(ClientRequest)`, shared `ClientConfig`, owns pool + jar + transport.
- `client::Transport`: `send(request) -> response` coroutine interface.
- `client::RetryPolicy`: max attempts, backoff base/cap, jitter, retryable
  status set, idempotency gate.
- `rest::Resource`: `collection("users").get(id)`, `.list(query)`,
  `.create(doc)`, `.update(id, doc)`, `.remove(id)`.
- `openapi::Builder`: `from_app(const App&) -> Document`, deterministic
  output, app override hook `extend(Document&)`.
- `testing::TestClient`: `Client` subclass fixed to `AppTransport`,
  lifespan helpers, fixture + clock wiring.

## 4. Rules (hard, numbered)

1. All outbound HTTP from handlers, tasks and CLI goes through
   `client::Client`; raw socket HTTP is forbidden outside `http_transport`.
2. Every request has an explicit effective timeout (phases plus total); no
   request may wait unbounded.
3. Retries apply only to idempotent methods (GET, HEAD, OPTIONS, PUT, DELETE)
   plus POST explicitly marked idempotent (Idempotency-Key header or policy
   flag); anything else retries only connect-phase failures, never a sent
   body.
4. Backoff is exponential with jitter and a static cap; max attempts is a
   static ceiling (default 3 total tries).
5. Redirects are followed only for GET/HEAD by default, max 5 hops, and never
   forward Authorization across hosts.
6. Cookie jar is per-Client, opt-in persistent, honors Secure/HttpOnly/
   SameSite semantics on read-back.
7. REST surface rules: plural noun collections, no verbs in paths, correct
   method semantics (POST create, GET read, PUT full replace, PATCH partial,
   DELETE remove), standard status codes (200/201/204/400/401/403/404/409/
   422/429/500), errors as RFC 9457 problem details (`application/problem+json`).
8. OpenAPI output is OpenAPI 3.1.x only; no 2.0/3.0 emitters.
9. Generated OpenAPI is deterministic: stable key order, stable schema names,
   byte-identical output for identical app input.
10. Test client runs the real stack (routing, middleware, auth, validation,
    views, DB). Tests that bypass routing to call views directly are
    forbidden except for documented error-path probes.
11. All caps in section 6 are static constants, never autotuned.

## 5. Development guidelines

- Build order inside this file: URL + headers + bodies, then Transport +
  Client + pool + timeouts, then retry/auth/cookies/proxy, then REST helpers,
  then OpenAPI model + builder + schema converter + doc routes, then test
  client + fixtures + clock.
- Reuse, do not reimplement: sockets, TLS, HTTP/1.1+H2 framing and
  compression come from 01-runtime.md; auth/session semantics from
  03-security.md; validation models from 05-request-routing.md; logging,
  metrics, traces from 02-observability.md.
- Every public client API has sync (blocking on internal loop bridge for CLI
  use) and coroutine forms sharing one implementation; the coroutine form is
  primary.
- Streaming is first-class: uploads and downloads support bounded buffers
  with backpressure; files over 1 MB must be able to stream without full
  buffering.
- Mock transport matches on method + path template + headers/body predicates
  and asserts unconsumed expectations at teardown.
- OpenAPI builder reads route metadata (method, path template, summary,
  tags, auth guards, validation models for params/body/response, status
  codes). Anything not declared in code appears as `description: TBD`, never
  as invented detail.
- Serve Swagger UI and ReDoc from embedded assets (see 09-cli-ops.md
  embedder); docs routes are disabled by default in production config.
- Test client API mirrors the real client verb-for-verb so tests read like
  production call sites.

## 6. Specifications (concrete behaviors, caps, formats)

Client:

- Protocols: HTTP/1.1 and HTTP/2 (via 01-runtime.md). H2 enabled per-client
  flag, default on for https URLs.
- Timeout defaults: connect 5s, read 30s, write 30s, pool acquire 5s, total
  60s. All overridable per request.
- Pool caps: max 100 connections per Client, max 20 per host, max keepalive
  60s, max idle 10 per host. Queue wait bounded by pool-acquire timeout.
- Retry defaults: 3 total attempts, base 200ms, cap 5s, full jitter,
  retryable statuses {429, 502, 503, 504}, honor `Retry-After` (seconds and
  HTTP-date) up to cap.
- Redirects: max 5, GET/HEAD auto, 307/308 preserve method+body, strip
  Authorization on cross-host.
- Body caps: in-memory body max 10 MB default; larger requires streaming
  API. Multipart file part max 512 MB, total request max 1 GB (static caps,
  lowered by server policy in 03-security.md).
- Content helpers: `json<T>()` (serialize/parse via validation framework),
  `form()`, `multipart()`, `xml()`, `bytes()`, `stream()`.
- Proxy: `HTTP_PROXY/HTTPS_PROXY/NO_PROXY` honored, per-client override,
  wildcard + suffix + CIDR NO_PROXY match.
- Observability: every request emits span + metrics (duration, status,
  retries, bytes) and debug log with correlation ID; disabled paths compile
  near-zero per 02-observability.md.

REST standards:

- URI style: `/v1/users/{id}`, lowercase, hyphenated, plural collections,
  query for filter/sort/page (`?page=&per_page=&sort=&filter=`).
- Pagination: default page+per_page (max per_page 100, default 20); cursor
  alternative for large sets. Envelope: `{data, meta:{page,per_page,total}, links}`.
- Errors: RFC 9457 `{type,title,status,detail,instance}` plus optional
  `errors[]` for field failures (422 with field paths from validation).
- Versioning: path prefix `/v{n}`; breaking change requires new version.
- Idempotency: `Idempotency-Key` header supported on POST create endpoints;
  server stores keyed result 24h (see 04-data.md KV).

OpenAPI:

- Version string `3.1.0` minimum; generator stamps `x-molo-framework-version`.
- Served at `/openapi.json` (JSON, canonical) and `/openapi.yaml`; UI at
  `/docs` (Swagger) and `/redoc`.
- Schemas: every validation model becomes `#/components/schemas/<Name>`;
  path/query/header/cookie params from binding declarations; security
  schemes from auth guards (http/bearer, http/basic, apiKey, oauth2 as
  configured); examples from model examples.
- Generation cap: max 5000 paths, max 2000 schemas, document max 10 MB;
  beyond that the builder errors with a clear message.

Test client:

- `TestClient(App)` issues requests through `AppTransport`: no TCP, real
  everything else. Lifespan via `test_client.lifespan()` guard.
- Fixtures: per-test DB reset (SQLite in-memory or isolated Postgres
  schema), seeded objects factory, ORM session bound to request scope.
- Clock: frozen time default in tests (`testing::Clock::freeze(t)`), manual
  advance `clock.advance(d)`; runtime timers and ORM timestamps read it.
- Assertions: `expect_status`, `expect_json`, `expect_json_schema(name)`
  validated against the generated OpenAPI schemas, `expect_header`.

## 7. Execution steps (in build order)

1. URL parser, header map, request/response value types with JSON/form/XML
   bodies (unit-covered via test client loopback only).
2. Transport interface plus mock transport; Client verbs over injected
   transport; timeout phases enforced.
3. Real HTTP transport on the 01-runtime.md loop: HTTP/1.1 first, then H2;
   pooling honoring caps; cookie jar; proxy incl. NO_PROXY.
4. Retry policy with backoff/jitter/Retry-After; auth providers; redirect
   handling; streaming upload/download.
5. REST helpers: Resource fluent API, paginator, problem-details errors,
   idempotency-key sender.
6. OpenAPI document model + JSON/YAML serializers; schema converter from
   validation models; builder from routers; doc routes + embedded UI.
7. Test client on AppTransport with lifespan; fixtures; frozen clock;
   assertion helpers; OpenAPI schema-conformance assertion.
8. Living-example coverage: REST client flows, OpenAPI endpoints, and one
   full test-client suite per 10-workflow-example.md.

## 8. Validation (how to verify each step)

1. URL/body round-trips: parse/serialize vectors incl. encoding edges;
   loopback test-client echo returns identical bodies.
2. Mock-transport suite: scripted responses, predicate matching, timeout
   injection fires the right phase error, unconsumed-expectation failure.
3. Real-transport suite against local test server: keep-alive reuse proven
   by connection counter, pool caps enforced under burst, H2 negotiated on
   TLS fixture, proxy + NO_PROXY routing matrix.
4. Retry matrix: each retryable status retried then succeeding; POST without
   idempotency key not retried after body sent; Retry-After honored; redirect
   Authorization-strip test; 50 MB streamed download under 16 MB RSS growth.
5. REST conformance: golden problem-details bodies; paginator walks a 250
   item set; idempotent POST replay returns original result.
6. OpenAPI: generated document validates against the official 3.1 JSON
   schema; byte-determinism check (generate twice, diff empty); snapshot of
   example app reviewed; UI routes return 200 in dev, 404 in prod default.
7. Test client: full suite runs with loopback transport only (assert zero
   real sockets via pool counter); lifespan startup/shutdown observed;
   frozen-clock test proves identical timestamps; schema-conformance
   assertion passes for every example route.

## 9. References

Depends on:

- 01-runtime.md: event loop, HTTP/1.1+H2 framing, TLS hooks, compression,
  connection primitives the pool and HTTP transport build on.
- 02-observability.md: spans, metrics, log format, correlation IDs, zero-cost
  macros used by every request.
- 03-security.md: auth/session semantics, TLS via wolfSSL, body/upload caps,
  redirect Authorization rules.
- 04-data.md: KV for idempotency keys, DB fixtures base for test client.
- 05-request-routing.md: routers, validation models, response hierarchy,
  error mapping; OpenAPI builder inputs.

Feeds / defers to:

- 06-realtime.md: owns WebSocket/SSE/Socket.IO/WebDAV clients; reuses this
  file's timeout/retry/auth/logging/backoff contracts.
- 09-cli-ops.md: AI harness CLI is built on this HTTP client; embedder packs
  Swagger/ReDoc UI assets; dev server hosts doc routes.
- 10-workflow-example.md: owns test-file layout/naming and living-example
  gates; this file provides the TestClient mechanism it standardizes on.

## 10. Open questions

1. H2 for cleartext (h2c) in the client: prior-knowledge only, or upgrade
   handshake too? Proposal: prior-knowledge with opt-in upgrade.
2. Should the OpenAPI builder also emit AsyncAPI fragments for WS/SSE
   routes, or stay HTTP-only and let 06-realtime.md define its own export?
   Proposal: HTTP-only here, cross-link.
3. Idempotency-key storage backend default: in-memory with documented loss
   on restart, or KV-backed always? Proposal: KV-backed, in-memory only for
   single-process dev.

## 11. Sources

1. OpenAPI Initiative - OpenAPI Specification v3.1.0 (2021-02-15):
   https://spec.openapis.org/oas/v3.1.0 (retrieved 2026-10-23).
2. httpx documentation - Clients (Client pooling, config sharing):
   https://www.python-httpx.org/advanced/clients/ (retrieved 2026-10-23).
3. httpx documentation - QuickStart (verbs, bodies, timeouts, auth):
   https://www.python-httpx.org/quickstart/ (retrieved 2026-10-23).
4. httpx documentation - Transports (HTTP/ASGI/WSGI/Mock, retries, mounts):
   https://www.python-httpx.org/advanced/transports/ (retrieved 2026-10-23).
5. FastAPI documentation - Testing (TestClient through app):
   https://fastapi.tiangolo.com/tutorial/testing/ (retrieved 2026-10-23).
6. FastAPI documentation - Extending OpenAPI (code-first generation):
   https://fastapi.tiangolo.com/how-to/extending-openapi/ (retrieved 2026-10-23).
7. Microsoft Learn - Web API design best practices (REST guidance):
   https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design (retrieved 2026-10-23).