# Copilot Instructions

## 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
and for untyped OpenAPI/Swagger API usage.

## Modules

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

| Module | Purpose |
|--------|---------|
| `.` (root) | Core runtime library |
| `server-middleware` | Standalone, dependency-free server middleware (`mediatype`, `negotiate`, `negotiate/header`, `docui`) |
| `client-middleware/opentracing` | OpenTracing middleware for client transport (compatibility module; prefer the OpenTelemetry support built into `client.Runtime`) |

## Package Layout

| Package | Contents |
|---------|----------|
| `runtime` (root) | Core interfaces (`Consumer`, `Producer`, `Authenticator`, `Authorizer`, `OperationHandler`), content-type handlers (JSON, XML, CSV, text, bytestream), HTTP helpers |
| `client` | HTTP client transport (`Runtime`) with TLS, timeouts, proxy, keepalive, OpenTelemetry |
| `middleware` | Server request lifecycle: routing, parameter binding, validation, security, operation execution. Doc-UI and negotiation primitives moved to `server-middleware/*`; legacy entry points 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 handling |
| `security` | Auth implementations: Basic, API Key, Bearer/OAuth2 (with `*Ctx` variants) |
| `logger` | `Logger` interface; debug via `SWAGGER_DEBUG` or `DEBUG` env vars |
| `flagext` | CLI flag extensions (e.g. `ByteSize`) |
| `yamlpc` | YAML producer/consumer |

## Key API

- `Consumer` / `Producer` — request body binding and response serialization
- `Authenticator` / `Authorizer` — authentication and authorization strategies
- `OperationHandler` — matched API operation handler
- Built-in factories: `JSONConsumer()`, `JSONProducer()`, `XMLConsumer()`, `XMLProducer()`, `CSVConsumer()`, `CSVProducer()`, `TextConsumer()`, `TextProducer()`, `ByteStreamConsumer()`, `ByteStreamProducer()`
- `client.Runtime` — configurable HTTP transport (TLS, auth, OpenTelemetry)
- `middleware.Context` — server request lifecycle manager
- `middleware.NewRouter()` — builds a router from an analyzed OpenAPI spec

## Design Decisions

- Every core interface has a companion `*Func` adapter type (e.g. `ConsumerFunc`).
- Consumer/Producer are separate interfaces for per-content-type pluggability.
- Security functions come in pairs (`BasicAuth` / `BasicAuthCtx`) for context propagation.
- Server middleware pipeline: Router → Binder → Validator → Security → Executor → Responder.
- OpenTracing lives in a separate module to avoid pulling its dependency into the core.
- `server-middleware` is a separate module so any `net/http` app can use negotiation, media-type, and doc-UI primitives without inheriting the OpenAPI spec/loads/validate tree.

## Dependencies

- `go-openapi/analysis`, `errors`, `loads`, `spec`, `strfmt`, `swag/*`, `validate` — OpenAPI toolkit
- `go.opentelemetry.io/otel` — tracing
- `docker/go-units` — human-readable size parsing
- `go-openapi/testify/v2` — test-only (zero-dep fork of `stretchr/testify`)

## Conventions

- All `.go` files must have SPDX license headers (Apache-2.0).
- Commits require DCO sign-off (`git commit -s`).
- Formatting: `golangci-lint fmt` (not `gofmt` or `gofumpt`).
- Linting: `golangci-lint run` — config in `.golangci.yml` (posture: `default: all` with explicit disables).
- Every `//nolint` directive **must** have an inline comment explaining why.
- Tests: `go test work ./...` (all modules) or `go test ./...` (root only). CI runs with `-race` on `{ubuntu, macos, windows} x {stable, oldstable}`.
- Test framework: `github.com/go-openapi/testify/v2` (not `stretchr/testify`).

See `.github/copilot/` (symlinked to `.claude/rules/`) for detailed rules on Go conventions, linting, and testing.