moby/vendor/github.com/go-openapi/runtime/client/runtime.go

// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
// SPDX-License-Identifier: Apache-2.0

package client

import (
	"context"
	"fmt"
	"mime"
	"net/http"
	"net/http/httputil"
	"strings"
	"sync"
	"time"

	"github.com/go-openapi/runtime"
	"github.com/go-openapi/runtime/client/internal/request"
	"github.com/go-openapi/runtime/logger"
	"github.com/go-openapi/runtime/middleware"
	"github.com/go-openapi/runtime/server-middleware/mediatype"
	"github.com/go-openapi/runtime/yamlpc"
	"github.com/go-openapi/strfmt"
)

const (
	schemeHTTP  = "http"
	schemeHTTPS = "https"
)

// DefaultTimeout the default request timeout.
var DefaultTimeout = 30 * time.Second

// Runtime represents an API client that uses the transport
// to make [http] requests based on a swagger specification.
type Runtime struct {
	DefaultMediaType      string
	DefaultAuthentication runtime.ClientAuthInfoWriter
	Consumers             map[string]runtime.Consumer
	Producers             map[string]runtime.Producer

	Transport http.RoundTripper
	Jar       http.CookieJar
	// Spec      *spec.Document
	Host     string
	BasePath string
	Formats  strfmt.Registry
	// Deprecated: prefer [runtime.ContextualTransport.SubmitContext] to pass the request context explicitly.
	Context context.Context //nolint:containedctx  // we precisely want this type to contain the request context

	Debug bool

	// Trace enables connection-level diagnostic output via
	// [net/http/httptrace]. When true, the runtime narrates the
	// connection lifecycle of every request through r.logger.Debugf:
	// DNS, dial, TLS handshake, idle-pool reuse, request body
	// transfer, time-to-first-byte, response body transfer, and a
	// trailing per-request summary line.
	//
	// Trace is orthogonal to Debug: Debug dumps wire bytes (request
	// and response headers and body), Trace narrates how the
	// connection got there. Both may be enabled independently.
	//
	// Trace is not coupled to the SWAGGER_DEBUG / DEBUG environment
	// variables: it defaults to false and is only enabled by
	// explicit assignment.
	//
	// Trace is primarily intended as a problem-investigation tool
	// (the local equivalent of curl -vvv), not an always-on tracer.
	// For distributed-trace correlation, use the OpenTelemetry
	// integration ([Runtime.WithOpenTelemetry]).
	Trace bool

	logger logger.Logger

	// MatchSuffix enables RFC 6839 structured-syntax suffix tolerance
	// for codec lookup. When true, a response with Content-Type
	// "application/problem+json" finds the JSON consumer registered
	// under "application/json"; with the default false, the lookup
	// is strict and falls through to the "*/*" wildcard if present.
	// See [mediatype.AllowSuffix] for the semantics.
	MatchSuffix bool

	clientOnce *sync.Once
	client     *http.Client
	schemes    []string
	response   ClientResponseFunc
}

var _ runtime.ContextualTransport = &Runtime{}

// New creates a new default runtime for a swagger api runtime.Client.
func New(host, basePath string, schemes []string) *Runtime {
	var rt Runtime
	rt.DefaultMediaType = runtime.JSONMime

	// Enhancement proposal: https://github.com/go-openapi/runtime/issues/385
	rt.Consumers = map[string]runtime.Consumer{
		runtime.YAMLMime:           yamlpc.YAMLConsumer(),
		runtime.JSONMime:           runtime.JSONConsumer(),
		runtime.XMLMime:            runtime.XMLConsumer(),
		runtime.TextMime:           runtime.TextConsumer(),
		runtime.HTMLMime:           runtime.TextConsumer(),
		runtime.CSVMime:            runtime.CSVConsumer(),
		runtime.MultipartFormMime:  runtime.ByteStreamConsumer(),
		runtime.URLencodedFormMime: runtime.ByteStreamConsumer(),
		runtime.DefaultMime:        runtime.ByteStreamConsumer(),
	}
	rt.Producers = map[string]runtime.Producer{
		runtime.YAMLMime:    yamlpc.YAMLProducer(),
		runtime.JSONMime:    runtime.JSONProducer(),
		runtime.XMLMime:     runtime.XMLProducer(),
		runtime.TextMime:    runtime.TextProducer(),
		runtime.HTMLMime:    runtime.TextProducer(),
		runtime.CSVMime:     runtime.CSVProducer(),
		runtime.DefaultMime: runtime.ByteStreamProducer(),
	}
	rt.Transport = http.DefaultTransport
	rt.Jar = nil
	rt.Host = host
	rt.BasePath = basePath
	rt.Context = context.Background()
	rt.clientOnce = new(sync.Once)
	if !strings.HasPrefix(rt.BasePath, "/") {
		rt.BasePath = "/" + rt.BasePath
	}

	rt.Debug = logger.DebugEnabled()
	rt.logger = logger.StandardLogger{}
	rt.response = newResponse

	if len(schemes) > 0 {
		rt.schemes = schemes
	}
	return &rt
}

// NewWithClient allows you to create a new transport with a configured [http.Client].
func NewWithClient(host, basePath string, schemes []string, client *http.Client) *Runtime {
	rt := New(host, basePath, schemes)
	if client != nil {
		rt.clientOnce.Do(func() {
			rt.client = client
		})
	}
	return rt
}

// EnableConnectionReuse drains the remaining body from a response
// so that go will reuse the TCP connections.
//
// This is not enabled by default because there are servers where
// the response never gets closed and that would make the code hang forever.
// So instead it's provided as a [http] client [middleware] that can be used to override
// any request.
func (r *Runtime) EnableConnectionReuse() {
	if r.client == nil {
		r.Transport = KeepAliveTransport(
			transportOrDefault(r.Transport, http.DefaultTransport),
		)
		return
	}

	r.client.Transport = KeepAliveTransport(
		transportOrDefault(r.client.Transport,
			transportOrDefault(r.Transport, http.DefaultTransport),
		),
	)
}

// CreateHTTPRequestContext creates the requests and bind the parameters, but does not send it over the wire
// like [Runtime.SubmitContext].
//
// The [http.Request] is complete with authentication, headers and body (including streamed body) and ready for callers
// to submit it to a [http.Client] of their choice, then consume the [http.Response].
//
// Most users would simply use [Runtime.SubmitContext], which wraps all these operations in one call.
func (r *Runtime) CreateHTTPRequestContext(ctx context.Context, operation *runtime.ClientOperation) (req *http.Request, cancel context.CancelFunc, err error) {
	req, cancel, err = r.createHTTPRequestContext(ctx, operation)
	return
}

// CreateHttpRequest builds the [http.Request] for the given operation, using
// [context.Background] as the request context.
//
// Any per-operation timeout declared by the operation's [runtime.ClientRequestWriter]
// is silently ignored here, which can leak a context-cancellation channel if the
// caller relies on it.
//
// Deprecated: use [Runtime.CreateHTTPRequestContext] instead, with explicit
// control over the request context and its cancellation.
func (r *Runtime) CreateHttpRequest(operation *runtime.ClientOperation) (req *http.Request, err error) { //nolint:revive
	req, _, err = r.createHTTPRequestContext(context.Background(), operation)
	return
}

// Submit a request and when there is a body on success it will turn that into the result
// all other things are turned into an api error for swagger which retains the status code.
//
// This call inherits the context possibly put in the operation, otherwise the one possibly put in the [Runtime].
// If none are set, use [context.Background].
//
// Any timeout set by parameters is honored.
func (r *Runtime) Submit(operation *runtime.ClientOperation) (any, error) {
	return r.SubmitContext(r.ensureContext(operation), operation)
}

// SubmitContext submits a request and returns the result.
//
// Errors are turned into an api error for swagger which retains the status code.
//
// Unlike [Submit], [SubmitContext] only injects the context provided by the caller:
// contexts possibly cached in operation or runtime are ignored.
//
// On the other hand, a timeout set by parameters is honored.
func (r *Runtime) SubmitContext(parentCtx context.Context, operation *runtime.ClientOperation) (any, error) {
	req, cancel, err := r.createHTTPRequestContext(parentCtx, operation)
	if err != nil {
		return nil, err
	}
	defer cancel()

	r.ensureClient()

	if err := r.dumpRequest(req); err != nil {
		return nil, err
	}

	// Attach the trace session before Do so the httptrace hooks
	// fire during the round-trip. The session emits its trailing
	// summary on finish; the response body is consumed by
	// ReadResponse downstream, after which finish is called.
	var trace *traceSession
	if r.Trace {
		trace = newTraceSession(r.logger, req.Method, req.URL.String(),
			introspectTLSConfig(r.pickClient(operation)))
		//nolint:contextcheck // We intentionally derive from req.Context() to layer the trace hooks onto the existing request context.
		req = req.WithContext(trace.attach(req.Context()))
		if req.Body != nil {
			req.Body = trace.wrapRequestBody(req.Body)
		}
		defer trace.finish()
	}

	res, err := r.pickClient(operation).Do(req)
	if err != nil {
		if trace != nil {
			trace.onRoundTripError(err)
		}
		return nil, err
	}
	defer res.Body.Close()

	if trace != nil {
		trace.onResponse(res.StatusCode)
		res.Body = trace.wrapResponseBody(res.Body)
	}

	ct := res.Header.Get(runtime.HeaderContentType)
	if ct == "" { // this should really never occur
		ct = r.DefaultMediaType
	}

	if err := r.dumpResponse(res, ct); err != nil {
		return nil, err
	}

	cons, err := r.resolveConsumer(ct)
	if err != nil {
		return nil, err
	}

	return operation.Reader.ReadResponse(r.response(res), cons)
}

// SetDebug changes the debug flag.
// It ensures that client and middlewares have the set debug level.
func (r *Runtime) SetDebug(debug bool) {
	r.Debug = debug
	middleware.Debug = debug
}

// SetLogger changes the logger stream.
// It ensures that client and middlewares use the same logger.
func (r *Runtime) SetLogger(logger logger.Logger) {
	r.logger = logger
	middleware.Logger = logger
}

type ClientResponseFunc = func(*http.Response) runtime.ClientResponse //nolint:revive

// SetResponseReader changes the response reader implementation.
func (r *Runtime) SetResponseReader(f ClientResponseFunc) {
	if f == nil {
		return
	}
	r.response = f
}

func (r *Runtime) ensureContext(operation *runtime.ClientOperation) context.Context {
	switch {
	case operation.Context != nil: //nolint:staticcheck // kept for backward compatibility
		return operation.Context
	case r.Context != nil:
		return r.Context
	default:
		return context.Background()
	}
}

func (r *Runtime) pickScheme(schemes []string) string {
	if v := r.selectScheme(r.schemes); v != "" {
		return v
	}
	if v := r.selectScheme(schemes); v != "" {
		return v
	}
	return schemeHTTP
}

func (r *Runtime) selectScheme(schemes []string) string {
	schLen := len(schemes)
	if schLen == 0 {
		return ""
	}

	scheme := schemes[0]
	// prefer https, but skip when not possible
	if scheme != schemeHTTPS && schLen > 1 {
		for _, sch := range schemes {
			if sch == schemeHTTPS {
				scheme = sch
				break
			}
		}
	}
	return scheme
}

func transportOrDefault(left, right http.RoundTripper) http.RoundTripper {
	if left == nil {
		return right
	}
	return left
}

// ensureClient lazily initializes r.client from r.Transport and r.Jar
// on first use. Safe under concurrent calls via sync.Once.
func (r *Runtime) ensureClient() {
	r.clientOnce.Do(func() {
		r.client = &http.Client{
			Transport: r.Transport,
			Jar:       r.Jar,
		}
	})
}

// pickClient returns the http.Client to use for this operation: the
// per-operation override if set, else the runtime's shared client.
func (r *Runtime) pickClient(operation *runtime.ClientOperation) *http.Client {
	if operation.Client != nil {
		return operation.Client
	}
	return r.client
}

// dumpRequest writes the outgoing request to the debug logger when
// r.Debug is enabled. No-op otherwise. Returns the dump error so the
// caller can decide whether to abort the submit.
func (r *Runtime) dumpRequest(req *http.Request) error {
	if !r.Debug {
		return nil
	}
	b, err := httputil.DumpRequestOut(req, true)
	if err != nil {
		return err
	}
	r.logger.Debugf("%s\n", string(b))
	return nil
}

// dumpResponse writes the incoming response to the debug logger when
// r.Debug is enabled. The body is omitted for runtime.DefaultMime
// (binary blob). No-op otherwise.
func (r *Runtime) dumpResponse(res *http.Response, ct string) error {
	if !r.Debug {
		return nil
	}
	printBody := ct != runtime.DefaultMime // Spare the terminal from a binary blob.
	b, err := httputil.DumpResponse(res, printBody)
	if err != nil {
		return err
	}
	r.logger.Debugf("%s\n", string(b))
	return nil
}

// resolveConsumer parses ct and returns the registered Consumer for
// that media type. Lookup is alias-aware (RFC 9512 §2.1 — yaml
// aliases) and, when [Runtime.MatchSuffix] is true, also tolerates
// RFC 6839 structured-syntax suffix media types (+json, +xml, +yaml).
// Falls back to the "*/*" entry if no match found.
func (r *Runtime) resolveConsumer(ct string) (runtime.Consumer, error) {
	if _, _, err := mime.ParseMediaType(ct); err != nil {
		return nil, fmt.Errorf("parse content type: %w", err)
	}
	if cons, ok := mediatype.Lookup(r.Consumers, ct, r.matchOpts()...); ok {
		return cons, nil
	}
	if cons, ok := r.Consumers["*/*"]; ok {
		return cons, nil
	}
	// scream about not knowing what to do
	return nil, fmt.Errorf("no consumer: %q", ct)
}

// matchOpts builds the mediatype.MatchOption slice for codec
// lookups on the Runtime, currently just the AllowSuffix opt-in.
func (r *Runtime) matchOpts() []mediatype.MatchOption {
	if !r.MatchSuffix {
		return nil
	}

	return []mediatype.MatchOption{mediatype.AllowSuffix()}
}

// createHTTPRequestContext is the context-aware builder of a [http.Request].
//
// The returned [http.Request] carries a context derived from parentCtx that
// honors the per-request timeout set during WriteToRequest. Callers must
// invoke cancel once the response is fully read.
func (r *Runtime) createHTTPRequestContext(parentCtx context.Context, operation *runtime.ClientOperation) (*http.Request, context.CancelFunc, error) {
	req, cmt, auth, err := r.prepareRequest(operation)
	if err != nil {
		return nil, nil, err
	}

	httpReq, cancel, err := req.BuildHTTPContext(parentCtx, cmt, r.BasePath, r.Producers, r.Formats, auth)
	if err != nil {
		return nil, nil, err
	}

	r.applyHostScheme(httpReq, operation)

	return httpReq, cancel, nil
}

// prepareRequest performs the operation-to-request setup that is
// independent of how the http.Request is finally assembled: parameters,
// headers, default authentication, and consumes-media-type selection.
func (r *Runtime) prepareRequest(operation *runtime.ClientOperation) (*request.Request, string, runtime.ClientAuthInfoWriter, error) {
	params, _, auth := operation.Params, operation.Reader, operation.AuthInfo

	req := request.New(operation.Method, operation.PathPattern, params)
	_ = req.SetTimeout(DefaultTimeout) // the timeout may be overridden by ClientRequestWriter
	req.SetConsumes(operation.ConsumesMediaTypes)

	accept := make([]string, 0, len(operation.ProducesMediaTypes))
	accept = append(accept, operation.ProducesMediaTypes...)
	if err := req.SetHeaderParam(runtime.HeaderAccept, accept...); err != nil {
		return nil, "", nil, err
	}

	if auth == nil && r.DefaultAuthentication != nil {
		auth = runtime.ClientAuthInfoWriterFunc(func(req runtime.ClientRequest, reg strfmt.Registry) error {
			if req.GetHeaderParams().Get(runtime.HeaderAuthorization) != "" {
				return nil
			}
			return r.DefaultAuthentication.AuthenticateRequest(req, reg)
		})
	}

	cmt := pickConsumesMediaType(operation.ConsumesMediaTypes, r.Producers, r.DefaultMediaType, r.matchOpts()...)
	if _, ok := mediatype.Lookup(r.Producers, cmt, r.matchOpts()...); !ok && cmt != runtime.MultipartFormMime && cmt != runtime.URLencodedFormMime {
		return nil, "", nil, fmt.Errorf("none of producers: %v registered. try %s", r.Producers, cmt)
	}

	return req, cmt, auth, nil
}

// applyHostScheme stamps the runtime's host and the operation-selected
// scheme onto the freshly built http.Request.
func (r *Runtime) applyHostScheme(httpReq *http.Request, operation *runtime.ClientOperation) {
	httpReq.URL.Scheme = r.pickScheme(operation.Schemes)
	httpReq.URL.Host = r.Host
	httpReq.Host = r.Host
}

// pickConsumesMediaType selects which Content-Type the client will send.
//
// Selection rules, in priority order:
//
//  1. multipart/form-data if any consumes entry advertises it (it streams
//     and preserves per-file Content-Type, regardless of codegen ordering;
//     resolves issue #286);
//  2. the first non-empty entry whose mime is either structural
//     (multipart/form-data or application/x-www-form-urlencoded — these
//     do not need a producer in the map) or has a producer registered in
//     producers — this lets the client gracefully skip unregistered
//     spec entries instead of erroring at the gate that follows;
//  3. the first non-empty entry overall (preserves the historical error
//     path: the gate at the call site reports "none of producers" with
//     the unregistered mime, so the diagnostic is unchanged when nothing
//     in consumes is registered);
//  4. def, if consumes is empty or all empty strings.
//
// Step 2 closes part of issues #32 and #386: an operation declaring
// `consumes: [application/x-vendor, application/json]` with no vendor
// producer registered now silently uses JSON instead of erroring.
func pickConsumesMediaType(consumes []string, producers map[string]runtime.Producer, def string, opts ...mediatype.MatchOption) string {
	for _, mt := range consumes {
		if strings.EqualFold(mt, runtime.MultipartFormMime) {
			return mt
		}
	}
	var firstNonEmpty string
	for _, mt := range consumes {
		if mt == "" {
			continue
		}
		if firstNonEmpty == "" {
			firstNonEmpty = mt
		}
		if isStructuralMime(mt) {
			return mt
		}
		if _, ok := mediatype.Lookup(producers, mt, opts...); ok {
			return mt
		}
	}
	if firstNonEmpty != "" {
		return firstNonEmpty
	}
	return def
}

// isStructuralMime reports whether mt is a media type whose body shape
// is owned by the runtime (multipart envelope, urlencoded form). These
// do not require an entry in the producers map.
func isStructuralMime(mt string) bool {
	return strings.EqualFold(mt, runtime.MultipartFormMime) ||
		strings.EqualFold(mt, runtime.URLencodedFormMime)
}