refactor(client): promote ContextualTransport to runtime package

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

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

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)
+}