Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .claude/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
plans/
skills/
commands/
agents/
hooks/
93 changes: 93 additions & 0 deletions .claude/CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# 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.
10 changes: 10 additions & 0 deletions .claude/rules/go-conventions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
paths:
- "**/*.go"
---

# Code conventions (go-openapi)

- All files must have SPDX license headers (Apache-2.0).
- Go version policy: support the 2 latest stable Go minor versions.
- Commits require DCO sign-off (`git commit -s`).
17 changes: 17 additions & 0 deletions .claude/rules/linting.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
---
paths:
- "**/*.go"
---

# Linting conventions (go-openapi)

```sh
golangci-lint run
```

Config: `.golangci.yml` — posture is `default: all` with explicit disables.
See `docs/STYLE.md` for the rationale behind each disabled linter.

Key rules:
- Every `//nolint` directive **must** have an inline comment explaining why.
- Prefer disabling a linter over scattering `//nolint` across the codebase.
47 changes: 47 additions & 0 deletions .claude/rules/testing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
paths:
- "**/*_test.go"
---

# Testing conventions (go-openapi)

## Running tests

**Single module repos:**

```sh
go test ./...
```

**Mono-repos (with `go.work`):**

```sh
# All modules
go test work ./...

# Single module
go test ./conv/...
```

Note: in mono-repos, plain `go test ./...` only tests the root module.
The `work` pattern expands to all modules listed in `go.work`.

CI runs tests on `{ubuntu, macos, windows} x {stable, oldstable}` with `-race` via `gotestsum`.

## Fuzz tests

```sh
# List all fuzz targets
go test -list Fuzz ./...

# Run a specific target (go test -fuzz cannot span multiple packages)
go test -fuzz=Fuzz -run='FuzzTargetName$' -fuzztime=1m30s ./package
```

Fuzz corpus lives in `testdata/fuzz/` within each package. CI runs each fuzz target for 1m30s
with a 5m minimize timeout.

## Test framework

`github.com/go-openapi/testify/v2` — a zero-dep fork of `stretchr/testify`.
Because it's a fork, `testifylint` does not work.
Loading
Loading