# 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 two modules:

| Module | Purpose |
|--------|---------|
| `.` (root) | Core runtime library |
| `client-middleware/opentracing` | Optional OpenTracing middleware for client transport |

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, content negotiation, parameter binding, validation, security, Swagger UI / RapiDoc serving |
| `middleware/denco` | Internal path-pattern router |
| `middleware/header` | HTTP header parsing utilities |
| `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
- `Spec()`, `SwaggerUI()`, `RapiDoc()` — spec and documentation serving middleware

### 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.
