From 7dba3f892d7411485cfd78c95b47c651fdf554ec Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Mon, 25 May 2026 18:29:35 +0200 Subject: [PATCH] refactor(client): promote ContextualTransport to runtime package Move ContextualTransport from client/ to the runtime root package so it sits side-by-side with ClientTransport, its canonical home. Update WithOpenTelemetry/WithOpenTracing return types and the submitWrapped type assertion to use the qualified name. Mark the cached Context fields on runtime.ClientOperation and client.Runtime as Deprecated, redirecting callers to ContextualTransport.SubmitContext. The internal ensureContext fallback keeps reading the legacy field under an explicit //nolint:staticcheck. Refresh stale commented signatures on ClientTransport.Submit and ContextualTransport.SubmitContext with short modern docstrings. Co-Authored-By: Claude Opus 4.7 (1M context) Signed-off-by: Frederic BIDON --- client/opentelemetry.go | 10 +++++----- client/runtime.go | 23 +++++------------------ client_operation.go | 24 +++++++++++++++++++++--- 3 files changed, 31 insertions(+), 26 deletions(-) diff --git a/client/opentelemetry.go b/client/opentelemetry.go index 65b72a80..e422f83c 100644 --- a/client/opentelemetry.go +++ b/client/opentelemetry.go @@ -29,12 +29,12 @@ const ( // A new client span is created for each request. // The provided opts are applied to each spans - for example to add global tags. // -// The returned transport satisfies [ContextualTransport]: callers +// The returned transport satisfies [runtime.ContextualTransport]: callers // should prefer [openTelemetryTransport.SubmitContext] over the // legacy [runtime.ClientOperation.Context] field. Setting that // field is still honored on the [openTelemetryTransport.Submit] // compatibility path. -func (r *Runtime) WithOpenTelemetry(opts ...OpenTelemetryOpt) ContextualTransport { +func (r *Runtime) WithOpenTelemetry(opts ...OpenTelemetryOpt) runtime.ContextualTransport { return newOpenTelemetryTransport(r, r.Host, opts) } @@ -58,7 +58,7 @@ func (r *Runtime) WithOpenTelemetry(opts ...OpenTelemetryOpt) ContextualTranspor // usual opentracing options and opentracing-enabled transport. // // Passed options are ignored unless they are of type [OpenTelemetryOpt]. -func (r *Runtime) WithOpenTracing(opts ...any) ContextualTransport { +func (r *Runtime) WithOpenTracing(opts ...any) runtime.ContextualTransport { otelOpts := make([]OpenTelemetryOpt, 0, len(opts)) for _, o := range opts { otelOpt, ok := o.(OpenTelemetryOpt) @@ -179,7 +179,7 @@ func (t *openTelemetryTransport) Submit(op *runtime.ClientOperation) (any, error // transport's SubmitContext call. The legacy // [runtime.ClientOperation.Context] field is not consulted. // -// When the wrapped transport implements [ContextualTransport], ctx is +// When the wrapped transport implements [runtime.ContextualTransport], ctx is // forwarded directly via its SubmitContext. Otherwise, the legacy // Submit path is used: ctx is stamped onto op.Context for the // duration of that call and restored afterwards, so the wrapped @@ -228,7 +228,7 @@ func (t *openTelemetryTransport) SubmitContext(ctx context.Context, op *runtime. //nolint:contextcheck // ctx is forwarded verbatim; the legacy Submit branch only stamps it onto op.Context for the wrapped transport. func (t *openTelemetryTransport) submitWrapped(ctx context.Context, op *runtime.ClientOperation) (any, error) { - if sc, ok := t.transport.(ContextualTransport); ok { + if sc, ok := t.transport.(runtime.ContextualTransport); ok { return sc.SubmitContext(ctx, op) } prev := op.Context diff --git a/client/runtime.go b/client/runtime.go index ac993ea5..604fb0ea 100644 --- a/client/runtime.go +++ b/client/runtime.go @@ -44,7 +44,8 @@ type Runtime struct { Host string BasePath string Formats strfmt.Registry - Context context.Context //nolint:containedctx // we precisely want this type to contain the request context + // 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 @@ -85,6 +86,8 @@ type Runtime struct { 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 @@ -188,22 +191,6 @@ func (r *Runtime) CreateHttpRequest(operation *runtime.ClientOperation) (req *ht return } -// ContextualTransport extends [runtime.ClientTransport] with an -// explicit context-aware submission method. -// -// [Runtime] satisfies it via [Runtime.SubmitContext]. Wrappers such -// as the OpenTelemetry transport type-assert to this interface so -// they can forward an explicit context to the underlying transport -// without setting the cached [runtime.ClientOperation.Context] field. -// -// In v2, SubmitContext will be folded into [runtime.ClientTransport] -// itself and the cached context field removed; this interface is the -// v0.x bridge. -type ContextualTransport interface { - runtime.ClientTransport - SubmitContext(context.Context, *runtime.ClientOperation) (any, error) -} - // 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. // @@ -309,7 +296,7 @@ func (r *Runtime) SetResponseReader(f ClientResponseFunc) { func (r *Runtime) ensureContext(operation *runtime.ClientOperation) context.Context { switch { - case operation.Context != nil: + case operation.Context != nil: //nolint:staticcheck // kept for backward compatibility return operation.Context case r.Context != nil: return r.Context diff --git a/client_operation.go b/client_operation.go index ad7277e0..61f6ead3 100644 --- a/client_operation.go +++ b/client_operation.go @@ -19,12 +19,30 @@ type ClientOperation struct { AuthInfo ClientAuthInfoWriter Params ClientRequestWriter Reader ClientResponseReader - Context context.Context //nolint:containedctx // we precisely want this type to contain the request context - Client *http.Client + // Deprecated: prefer [ContextualTransport.SubmitContext] to pass the request context explicitly. + Context context.Context //nolint:containedctx // we precisely want this type to contain the request context + Client *http.Client } // A ClientTransport implementor knows how to submit Request objects to some destination. type ClientTransport interface { - // Submit(string, RequestWriter, ResponseReader, AuthInfoWriter) (interface{}, error) + // Submit the operation and return the deserialized response or an error. Submit(*ClientOperation) (any, error) } + +// ContextualTransport extends [ClientTransport] with an explicit +// context-aware submission method. +// +// Wrappers such as the OpenTelemetry transport type-assert to this +// interface so they can forward an explicit context to the underlying +// transport without setting the cached [ClientOperation.Context] field. +// +// In v2, SubmitContext will be folded into [ClientTransport] itself +// and the cached [ClientOperation.Context] field removed; this interface +// is the v0.x bridge. +type ContextualTransport interface { + ClientTransport + + // SubmitContext submits the operation using ctx as the request context. + SubmitContext(ctx context.Context, operation *ClientOperation) (any, error) +}