Skip to content

copilot-instructions.md

Latest commit

 

History

History
68 lines (52 loc) · 3.47 KB

copilot-instructions.md

File metadata and controls

68 lines (52 loc) · 3.47 KB

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
client-middleware/opentracing Optional OpenTracing middleware for client transport

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, content negotiation, parameter binding, validation, security, Swagger UI / RapiDoc
middleware/denco Internal path-pattern router
middleware/header HTTP header parsing utilities
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.

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.