# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

`github.com/go-openapi/runtime` is the runtime library for the go-openapi toolkit.
It provides HTTP client and server components used by code generated by [go-swagger](https://github.com/go-swagger/go-swagger)
and for untyped OpenAPI/Swagger API usage.

See [docs/MAINTAINERS.md](../docs/MAINTAINERS.md) for CI/CD, release process, and repo structure details.

### Modules and Package layout

This is a mono-repo with a `go.work` workspace containing three modules:

| Module | Purpose |
|--------|---------|
| `.` (root) | Core runtime library |
| `server-middleware` | Standalone, dependency-free server middleware: `mediatype`, `negotiate`, `negotiate/header`, `docui`. No transitive dependency on `go-openapi/spec`, `loads`, or `validate`. |
| `client-middleware/opentracing` | Optional OpenTracing middleware for client transport (compatibility module; new code should use the OpenTelemetry support built into `client.Runtime`). |

Packages in the root module:

| Package | Contents |
|---------|----------|
| `runtime` (root) | Core interfaces (`Consumer`, `Producer`, `Authenticator`, `Authorizer`, `OperationHandler`), content-type handlers (JSON, XML, CSV, text, bytestream), HTTP request/response helpers |
| `client` | HTTP client transport: `Runtime` with TLS, timeouts, proxy, keepalive, OpenTelemetry tracing |
| `middleware` | Server-side request lifecycle: routing, parameter binding, validation, security, operation execution. Doc-UI and negotiation primitives have moved to `server-middleware/*`; the legacy entry points (`Spec`, `SwaggerUI`, `RapiDoc`, `Redoc`, `NegotiateContentType`, …) remain as deprecated shims in `seam.go`. |
| `middleware/denco` | Internal path-pattern router |
| `middleware/header` | Deprecated shim — re-exports `server-middleware/negotiate/header` |
| `middleware/untyped` | Untyped (reflection-based) API request/response handling |
| `security` | Auth scheme implementations: Basic, API Key, Bearer/OAuth2 (with `*Ctx` context-aware variants) |
| `logger` | `Logger` interface with `Printf`/`Debugf`; debug enabled via `SWAGGER_DEBUG` or `DEBUG` env vars |
| `flagext` | CLI flag extensions (e.g. `ByteSize`) |
| `yamlpc` | YAML producer/consumer support |
| `internal/testing` | Internal test utilities |

### Key API

Core interfaces (root package, `interfaces.go`):

- `Consumer` / `ConsumerFunc` — bind request body to a Go value
- `Producer` / `ProducerFunc` — serialize a Go value to the response body
- `Authenticator` / `AuthenticatorFunc` — authenticate a request, return a principal
- `Authorizer` / `AuthorizerFunc` — authorize a principal for a request
- `OperationHandler` / `OperationHandlerFunc` — handle a matched API operation
- `Validatable`, `ContextValidatable` — custom validation hooks for generated types

Built-in content-type factories: `JSONConsumer()`, `JSONProducer()`, `XMLConsumer()`, `XMLProducer()`,
`CSVConsumer()`, `CSVProducer()`, `TextConsumer()`, `TextProducer()`,
`ByteStreamConsumer()`, `ByteStreamProducer()`

Client transport (`client` package):

- `Runtime` — configurable HTTP transport (TLS, auth, timeout, OpenTelemetry)
- `TLSClientOptions` — mTLS / custom CA configuration

Server middleware (`middleware` package):

- `Context` — request lifecycle manager (routes, binds, validates, authenticates, executes)
- `NewRouter()` — builds a router from an analyzed OpenAPI spec

Standalone server middleware (`server-middleware` module):

- `mediatype.MediaType`, `mediatype.Set` — typed RFC 7231 media-type values + asymmetric matching
- `negotiate.ContentType()`, `negotiate.ContentEncoding()` — `Accept` / `Accept-Encoding` selection (honours MIME parameters by default; opt out with `WithIgnoreParameters`)
- `docui.SwaggerUI()`, `docui.RapiDoc()`, `docui.Redoc()`, `docui.ServeSpec()` — stdlib-only doc-UI and spec-serving handlers

### Dependencies

Key direct dependencies (`go.mod`):

| Dependency | Role |
|------------|------|
| `go-openapi/analysis` | OpenAPI spec analysis |
| `go-openapi/errors` | Structured API error types |
| `go-openapi/loads` | OpenAPI spec loading |
| `go-openapi/spec` | OpenAPI spec model types |
| `go-openapi/strfmt` | String format registry (date-time, UUID, etc.) |
| `go-openapi/swag/*` | Utilities: conv, fileutils, jsonutils, stringutils |
| `go-openapi/validate` | Spec-based validation |
| `go-openapi/testify/v2` | Test assertions (zero-dep fork of stretchr/testify) |
| `go.opentelemetry.io/otel` | OpenTelemetry tracing |
| `docker/go-units` | Human-readable size parsing |

### Notable historical design decisions

- **Functional adapter pattern**: every core interface has a companion `*Func` type
  (e.g. `ConsumerFunc`) so handlers can be plain functions or full structs.
- **Consumer/Producer split**: request deserialization and response serialization are
  decoupled behind separate interfaces, allowing per-content-type pluggability.
- **Context-aware auth variants**: security functions come in pairs (`BasicAuth` / `BasicAuthCtx`)
  to support both legacy and context-propagating call paths.
- **Middleware pipeline**: server processing flows through
  Router → Binder → Validator → Security → OperationExecutor → Responder,
  each stage composable via `middleware.Builder`.
- **OpenTracing kept in a separate module**: avoids pulling the OpenTracing dependency
  into consumers that only need the core runtime or use OpenTelemetry directly.
- **`server-middleware` extracted as a separate module**: lets any `net/http` application
  reuse the negotiation, media-type, and doc-UI primitives without inheriting the OpenAPI
  spec/loads/validate dependency tree. The root `middleware` package keeps deprecated
  shims for source compatibility.
