@stackonward/cli 1.6.0 → 1.8.0

package/dist/resources/templates/go-backend/internal/integrations/onex/v1/client_test.go

@@ -0,0 +1,772 @@
+package v1
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"go.uber.org/zap"
+
+	"{{module}}/internal/common/types"
+	"{{module}}/internal/core/httpclient"
+)
+
+type signerFixture struct{}
+
+func (signerFixture) AuthHeaders(context.Context) (map[string]string, error) {
+	return map[string]string{"Authorization": "Bearer signed-service-token"}, nil
+}
+
+func (signerFixture) AuthorizeRequest(context.Context, *http.Request) error { return nil }
+
+type recordingRetryWaiter struct{ delays []time.Duration }
+
+func (waiter *recordingRetryWaiter) Wait(_ context.Context, delay time.Duration) error {
+	waiter.delays = append(waiter.delays, delay)
+	return nil
+}
+
+type signerHeadersFixture map[string]string
+
+func (fixture signerHeadersFixture) AuthHeaders(context.Context) (map[string]string, error) {
+	return fixture, nil
+}
+
+func (signerHeadersFixture) AuthorizeRequest(context.Context, *http.Request) error { return nil }
+
+type failingSignerFixture struct{ err error }
+
+func (fixture failingSignerFixture) AuthHeaders(context.Context) (map[string]string, error) {
+	return nil, fixture.err
+}
+
+func (failingSignerFixture) AuthorizeRequest(context.Context, *http.Request) error { return nil }
+
+func TestClientAddsTrustedHeadersAndStrictlyDecodesResponse(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		if request.URL.Path != "/internal/v1/entitlements/decisions" || request.Header.Get("Authorization") != "Bearer signed-service-token" || request.Header.Get(types.HeaderOneXProductCode) != "sample_product" || request.Header.Get(types.HeaderInternalUserID) != "42" || request.Header.Get(types.HeaderIdempotencyKey) != "command_1234567890" || request.Header.Get("Idempotency-Key") != "" || request.Header.Get(types.HeaderRequestID) != "request-01" {
+			t.Fatalf("trusted request contract mismatch: path=%q headers=%v", request.URL.Path, request.Header)
+		}
+		writer.Header().Set("Content-Type", "application/json")
+		writer.WriteHeader(http.StatusOK)
+		_, _ = writer.Write([]byte(`{"value":"accepted"}`))
+	}))
+	defer server.Close()
+
+	client, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, Config{BaseURL: server.URL + "/internal/v1", ProductCode: "sample_product"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output struct {
+		Value string `json:"value"`
+	}
+	err = client.Do(context.Background(), Call{Method: http.MethodPost, Path: "/entitlements/decisions", UserID: 42, RequestID: "request-01", IdempotencyKey: "command_1234567890", Body: struct{}{}, ExpectedStatuses: []int{http.StatusOK}}, &output)
+	if err != nil || output.Value != "accepted" {
+		t.Fatalf("Do() = %#v, %v", output, err)
+	}
+}
+
+func TestClientRetriesOnlyConfiguredSafeGET(t *testing.T) {
+	var attempts atomic.Int32
+	var requestIDs []string
+	waiter := &recordingRetryWaiter{}
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		attempt := attempts.Add(1)
+		requestIDs = append(requestIDs, request.Header.Get(types.HeaderRequestID))
+		writer.Header().Set("Content-Type", "application/json")
+		if attempt < 3 {
+			writer.WriteHeader(http.StatusServiceUnavailable)
+			_, _ = writer.Write([]byte(`{"error":{"type":"api_error","code":"service_unavailable","message":"Unavailable"}}`))
+			return
+		}
+		_, _ = writer.Write([]byte(`{"value":"accepted"}`))
+	}))
+	t.Cleanup(server.Close)
+
+	client, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, Config{
+		BaseURL: server.URL + "/internal/v1", ProductCode: "sample_product", Timeout: time.Second,
+		SafeReadRetry: SafeReadRetryConfig{MaxRetries: 2, InitialBackoff: time.Millisecond, MaxBackoff: 2 * time.Millisecond},
+		RetryWaiter:   waiter,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output struct {
+		Value string `json:"value"`
+	}
+	if err := client.Do(context.Background(), Call{Method: http.MethodGet, Path: "/capabilities/opaque", RequestID: "request-safe-read", ExpectedStatuses: []int{http.StatusOK}}, &output); err != nil {
+		t.Fatal(err)
+	}
+	if attempts.Load() != 3 || len(waiter.delays) != 2 || output.Value != "accepted" {
+		t.Fatalf("attempts=%d delays=%v output=%#v", attempts.Load(), waiter.delays, output)
+	}
+	for _, requestID := range requestIDs {
+		if requestID != "request-safe-read" {
+			t.Fatalf("request IDs = %#v", requestIDs)
+		}
+	}
+}
+
+func TestClientHonorsRetryAfterForSafeGET(t *testing.T) {
+	var attempts atomic.Int32
+	waiter := &recordingRetryWaiter{}
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, _ *http.Request) {
+		writer.Header().Set("Content-Type", "application/json")
+		if attempts.Add(1) == 1 {
+			writer.Header().Set(types.HeaderRetryAfter, "2")
+			writer.WriteHeader(http.StatusTooManyRequests)
+			_, _ = writer.Write([]byte(`{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limited"}}`))
+			return
+		}
+		_, _ = writer.Write([]byte(`{"value":"accepted"}`))
+	}))
+	t.Cleanup(server.Close)
+
+	client, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, Config{
+		BaseURL: server.URL + "/internal/v1", ProductCode: "sample_product", Timeout: 5 * time.Second,
+		SafeReadRetry: SafeReadRetryConfig{MaxRetries: 1, InitialBackoff: time.Millisecond, MaxBackoff: time.Millisecond},
+		RetryWaiter:   waiter,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output struct {
+		Value string `json:"value"`
+	}
+	if err := client.Do(context.Background(), Call{Method: http.MethodGet, Path: "/capabilities/opaque", ExpectedStatuses: []int{http.StatusOK}}, &output); err != nil {
+		t.Fatal(err)
+	}
+	if attempts.Load() != 2 || len(waiter.delays) != 1 || waiter.delays[0] != 2*time.Second {
+		t.Fatalf("attempts=%d delays=%v", attempts.Load(), waiter.delays)
+	}
+}
+
+func TestClientRetriesSafeGETConnectionFailure(t *testing.T) {
+	var attempts atomic.Int32
+	waiter := &recordingRetryWaiter{}
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, _ *http.Request) {
+		if attempts.Add(1) == 1 {
+			hijacker, ok := writer.(http.Hijacker)
+			if !ok {
+				t.Fatal("response writer cannot be hijacked")
+			}
+			connection, _, err := hijacker.Hijack()
+			if err != nil {
+				t.Fatal(err)
+			}
+			_ = connection.Close()
+			return
+		}
+		writer.Header().Set("Content-Type", "application/json")
+		_, _ = writer.Write([]byte(`{"value":"accepted"}`))
+	}))
+	t.Cleanup(server.Close)
+
+	client, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, Config{
+		BaseURL: server.URL + "/internal/v1", ProductCode: "sample_product", Timeout: time.Second,
+		SafeReadRetry: SafeReadRetryConfig{MaxRetries: 1, InitialBackoff: time.Nanosecond, MaxBackoff: time.Nanosecond},
+		RetryWaiter:   waiter,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output struct {
+		Value string `json:"value"`
+	}
+	if err := client.Do(context.Background(), Call{Method: http.MethodGet, Path: "/capabilities/opaque", ExpectedStatuses: []int{http.StatusOK}}, &output); err != nil {
+		t.Fatal(err)
+	}
+	if attempts.Load() != 2 || len(waiter.delays) != 1 || output.Value != "accepted" {
+		t.Fatalf("attempts=%d delays=%v output=%#v", attempts.Load(), waiter.delays, output)
+	}
+}
+
+func TestClientDoesNotRetryOtherHTTPStatuses(t *testing.T) {
+	tests := []struct {
+		status    int
+		errorType string
+		code      string
+		wantKind  ErrorKind
+	}{
+		{status: http.StatusBadRequest, errorType: "invalid_request_error", code: "invalid_parameters", wantKind: ErrorKindValidation},
+		{status: http.StatusUnauthorized, errorType: "authentication_error", code: "unauthorized", wantKind: ErrorKindUnauthenticated},
+		{status: http.StatusForbidden, errorType: "authorization_error", code: "access_denied", wantKind: ErrorKindForbidden},
+		{status: http.StatusNotFound, errorType: "not_found_error", code: "resource_not_found", wantKind: ErrorKindNotFound},
+		{status: http.StatusConflict, errorType: "invalid_request_error", code: "invalid_operation", wantKind: ErrorKindConflict},
+		{status: http.StatusInternalServerError, errorType: "api_error", code: "internal_error", wantKind: ErrorKindUnavailable},
+	}
+	for _, test := range tests {
+		t.Run(http.StatusText(test.status), func(t *testing.T) {
+			var attempts atomic.Int32
+			server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, _ *http.Request) {
+				attempts.Add(1)
+				writer.Header().Set("Content-Type", "application/json")
+				writer.WriteHeader(test.status)
+				_, _ = writer.Write([]byte(`{"error":{"type":"` + test.errorType + `","code":"` + test.code + `","message":"Safe summary"}}`))
+			}))
+			t.Cleanup(server.Close)
+			client, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, Config{
+				BaseURL: server.URL + "/internal/v1", ProductCode: "sample_product", Timeout: time.Second,
+				SafeReadRetry: SafeReadRetryConfig{MaxRetries: 2, InitialBackoff: time.Nanosecond, MaxBackoff: time.Nanosecond},
+			})
+			if err != nil {
+				t.Fatal(err)
+			}
+			var output struct{ Value string }
+			err = client.Do(context.Background(), Call{Method: http.MethodGet, Path: "/capabilities/opaque", ExpectedStatuses: []int{http.StatusOK}}, &output)
+			var typed *Error
+			if !errors.As(err, &typed) || typed.Kind != test.wantKind || typed.ErrorType != test.errorType || typed.Code != test.code {
+				t.Fatalf("error = %#v", err)
+			}
+			if attempts.Load() != 1 {
+				t.Fatalf("attempts = %d", attempts.Load())
+			}
+		})
+	}
+}
+
+func TestClientNeverRetriesPOSTAndMarksTransportResultUnknown(t *testing.T) {
+	var attempts atomic.Int32
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, _ *http.Request) {
+		attempts.Add(1)
+		hijacker, ok := writer.(http.Hijacker)
+		if !ok {
+			t.Fatal("response writer cannot be hijacked")
+		}
+		connection, _, err := hijacker.Hijack()
+		if err != nil {
+			t.Fatal(err)
+		}
+		_ = connection.Close()
+	}))
+	t.Cleanup(server.Close)
+
+	client, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, Config{
+		BaseURL: server.URL + "/internal/v1", ProductCode: "sample_product", Timeout: time.Second,
+		SafeReadRetry: SafeReadRetryConfig{MaxRetries: 2, InitialBackoff: time.Nanosecond, MaxBackoff: time.Nanosecond},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output struct {
+		Value string `json:"value"`
+	}
+	err = client.Do(context.Background(), Call{Method: http.MethodPost, Path: "/commands", Body: struct{}{}, ExpectedStatuses: []int{http.StatusOK}}, &output)
+	var typed *Error
+	if !errors.As(err, &typed) || typed.Kind != ErrorKindResultUnknown || typed.Code != "onex_result_unknown" || !typed.Retryable {
+		t.Fatalf("error = %#v", err)
+	}
+	if attempts.Load() != 1 {
+		t.Fatalf("POST attempts = %d", attempts.Load())
+	}
+}
+
+func TestClientOperationDeadlineIsTypedByMethod(t *testing.T) {
+	for _, method := range []string{http.MethodGet, http.MethodPost} {
+		t.Run(method, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, _ *http.Request) {
+				time.Sleep(50 * time.Millisecond)
+				writer.Header().Set("Content-Type", "application/json")
+				_, _ = writer.Write([]byte(`{"value":"accepted"}`))
+			}))
+			t.Cleanup(server.Close)
+			client, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, Config{BaseURL: server.URL + "/internal/v1", ProductCode: "sample_product", Timeout: time.Second})
+			if err != nil {
+				t.Fatal(err)
+			}
+			var output struct {
+				Value string `json:"value"`
+			}
+			call := Call{Method: method, Path: "/capabilities/opaque", Timeout: 10 * time.Millisecond, ExpectedStatuses: []int{http.StatusOK}}
+			if method == http.MethodPost {
+				call.Body = struct{}{}
+			}
+			err = client.Do(context.Background(), call, &output)
+			var typed *Error
+			if !errors.As(err, &typed) {
+				t.Fatalf("error = %#v", err)
+			}
+			wantKind := ErrorKindUnavailable
+			if method == http.MethodPost {
+				wantKind = ErrorKindResultUnknown
+			}
+			if typed.Kind != wantKind || !errors.Is(err, context.DeadlineExceeded) {
+				t.Fatalf("error = %#v, want kind %s deadline", err, wantKind)
+			}
+		})
+	}
+}
+
+func TestClientRejectsNonCanonicalSignerHeaders(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {
+		t.Fatal("request must not be sent")
+	}))
+	t.Cleanup(server.Close)
+	for _, headers := range []signerHeadersFixture{
+		{"Authorization": "Basic admin-session"},
+		{"Authorization": "Bearer service-token", "Cookie": "admin_session=secret"},
+		{"Authorization": "Bearer service-token", types.HeaderSessionID: "99"},
+	} {
+		client, err := NewClient(httpclient.New(zap.NewNop()), headers, Config{BaseURL: server.URL + "/internal/v1", ProductCode: "sample_product"})
+		if err != nil {
+			t.Fatal(err)
+		}
+		var output struct {
+			Value string `json:"value"`
+		}
+		err = client.Do(context.Background(), Call{Method: http.MethodGet, Path: "/capabilities/opaque", ExpectedStatuses: []int{http.StatusOK}}, &output)
+		var typed *Error
+		if !errors.As(err, &typed) || typed.Kind != ErrorKindContract || typed.Code != "onex_authentication_contract_invalid" {
+			t.Fatalf("headers=%v error=%#v", headers, err)
+		}
+	}
+}
+
+func TestClientMapsSignerFailuresWithoutLeakingCredentials(t *testing.T) {
+	for _, test := range []struct {
+		name     string
+		ctx      context.Context
+		err      error
+		wantKind ErrorKind
+	}{
+		{name: "unavailable", ctx: context.Background(), err: errors.New("credential secret"), wantKind: ErrorKindUnavailable},
+		{name: "canceled", ctx: canceledContext(), err: context.Canceled, wantKind: ErrorKindCanceled},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			client, err := NewClient(httpclient.New(zap.NewNop()), failingSignerFixture{err: test.err}, Config{BaseURL: "https://onex.example/internal/v1", ProductCode: "sample_product"})
+			if err != nil {
+				t.Fatal(err)
+			}
+			var output struct{ Value string }
+			err = client.Do(test.ctx, Call{Method: http.MethodGet, Path: "/capabilities/opaque", ExpectedStatuses: []int{http.StatusOK}}, &output)
+			var typed *Error
+			if !errors.As(err, &typed) || typed.Kind != test.wantKind || typed.Error() == "credential secret" {
+				t.Fatalf("error = %#v", err)
+			}
+		})
+	}
+}
+
+func canceledContext() context.Context {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	return ctx
+}
+
+func TestNewClientRejectsUnboundedOrInvalidSafeReadRetry(t *testing.T) {
+	tests := []Config{
+		{BaseURL: "https://onex.example/internal/v1", ProductCode: "sample_product", SafeReadRetry: SafeReadRetryConfig{MaxRetries: 1, InitialBackoff: time.Millisecond, MaxBackoff: time.Millisecond}},
+		{BaseURL: "https://onex.example/internal/v1", ProductCode: "sample_product", Timeout: time.Second, SafeReadRetry: SafeReadRetryConfig{MaxRetries: 11, InitialBackoff: time.Millisecond, MaxBackoff: time.Millisecond}},
+		{BaseURL: "https://onex.example/internal/v1", ProductCode: "sample_product", Timeout: time.Second, SafeReadRetry: SafeReadRetryConfig{MaxRetries: 1, InitialBackoff: time.Second, MaxBackoff: time.Millisecond}},
+		{BaseURL: "https://onex.example/internal/v1", ProductCode: "sample_product", Timeout: time.Second, OperationRetries: map[string]int{"storage.get_asset": 2}},
+		{BaseURL: "https://onex.example/internal/v1", ProductCode: "sample_product", Timeout: time.Second, OperationRetries: map[string]int{"storage.bad.operation": 1}},
+	}
+	for _, config := range tests {
+		if _, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, config); err == nil {
+			t.Fatalf("config %#v was accepted", config)
+		}
+	}
+}
+
+func TestSafeReadRetryPolicyUsesOnlyCanonicalStatusesAndDelays(t *testing.T) {
+	for _, status := range []int{http.StatusTooManyRequests, http.StatusBadGateway, http.StatusServiceUnavailable, http.StatusGatewayTimeout} {
+		if !shouldRetrySafeReadStatus(status) {
+			t.Fatalf("status %d is not retryable", status)
+		}
+	}
+	for _, status := range []int{http.StatusBadRequest, http.StatusUnauthorized, http.StatusConflict, http.StatusInternalServerError} {
+		if shouldRetrySafeReadStatus(status) {
+			t.Fatalf("status %d is retryable", status)
+		}
+	}
+	now := time.Date(2026, time.September, 14, 12, 0, 0, 0, time.UTC)
+	if delay := safeReadRetryDelay(SafeReadRetryConfig{InitialBackoff: time.Second, MaxBackoff: 2 * time.Second}, 3, "", now); delay != 2*time.Second {
+		t.Fatalf("capped delay = %s", delay)
+	}
+	if delay := safeReadRetryDelay(SafeReadRetryConfig{InitialBackoff: time.Second, MaxBackoff: time.Second}, 1, "3", now); delay != 3*time.Second {
+		t.Fatalf("seconds Retry-After = %s", delay)
+	}
+	if delay := safeReadRetryDelay(SafeReadRetryConfig{InitialBackoff: time.Second, MaxBackoff: time.Second}, 1, now.Add(4*time.Second).Format(http.TimeFormat), now); delay != 4*time.Second {
+		t.Fatalf("date Retry-After = %s", delay)
+	}
+	if _, ok := parseRetryAfter("invalid", now); ok {
+		t.Fatal("invalid Retry-After was accepted")
+	}
+	if delay, ok := parseRetryAfter("-1", now); ok || delay != 0 {
+		t.Fatalf("negative Retry-After = %s, %v", delay, ok)
+	}
+	jittered := safeReadRetryDelay(SafeReadRetryConfig{InitialBackoff: time.Second, MaxBackoff: time.Second, JitterRatio: 0.25}, 1, "", now)
+	if jittered < 750*time.Millisecond || jittered > time.Second {
+		t.Fatalf("jittered delay = %s", jittered)
+	}
+}
+
+func TestTimerRetryWaiterHonorsCompletionAndCancellation(t *testing.T) {
+	waiter := timerRetryWaiter{}
+	if err := waiter.Wait(context.Background(), time.Nanosecond); err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	if err := waiter.Wait(ctx, time.Second); !errors.Is(err, context.Canceled) {
+		t.Fatalf("error = %#v", err)
+	}
+}
+
+type dependencyExecutorFixture struct {
+	attempt bool
+	err     error
+	key     string
+}
+
+func (f *dependencyExecutorFixture) Execute(ctx context.Context, key string, operation func(context.Context) error) (bool, error) {
+	f.key = key
+	if !f.attempt {
+		return false, f.err
+	}
+	return true, operation(ctx)
+}
+
+func TestClientAppliesDependencyExecutorToCompleteResponseContract(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, _ *http.Request) {
+		writer.Header().Set("Content-Type", "application/json")
+		writer.WriteHeader(http.StatusServiceUnavailable)
+		_, _ = writer.Write([]byte(`{"error":{"type":"api_error","code":"service_unavailable","message":"unavailable"}}`))
+	}))
+	t.Cleanup(server.Close)
+	executor := &dependencyExecutorFixture{attempt: true}
+	client, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, Config{
+		BaseURL: server.URL + "/internal/v1", ProductCode: "sample_product", Timeout: time.Second, Dependency: executor,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output struct{ Value string }
+	err = client.Do(context.Background(), Call{
+		Method: http.MethodGet, Path: "/assets/one", Dependency: "storage", Operation: "get_asset", ExpectedStatuses: []int{http.StatusOK},
+	}, &output)
+	var typed *Error
+	if !errors.As(err, &typed) || typed.Kind != ErrorKindUnavailable || executor.key != "storage.get_asset" {
+		t.Fatalf("error=%#v key=%q", err, executor.key)
+	}
+}
+
+func TestClientDefaultResponseLimitAcceptsMaximumConfirmedObjectEnvelope(t *testing.T) {
+	body := strings.Repeat("A", maximumConfirmedObjectEncodedBytes)
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, _ *http.Request) {
+		writer.Header().Set("Content-Type", "application/json")
+		_, _ = fmt.Fprintf(writer, `{"body":%q}`, body)
+	}))
+	t.Cleanup(server.Close)
+	client, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, Config{
+		BaseURL: server.URL + "/internal/v1", ProductCode: "sample_product",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output struct {
+		Body string `json:"body"`
+	}
+	if err := client.Do(context.Background(), Call{
+		Method: http.MethodGet, Path: "/storage/assets/test/content", ExpectedStatuses: []int{http.StatusOK},
+	}, &output); err != nil {
+		t.Fatal(err)
+	}
+	if output.Body != body {
+		t.Fatalf("decoded body length = %d, want %d", len(output.Body), len(body))
+	}
+}
+
+func TestClientMapsCircuitRejectionAsNotAttemptedForMutation(t *testing.T) {
+	executor := &dependencyExecutorFixture{err: errors.New("circuit open")}
+	client, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, Config{
+		BaseURL: "https://onex.example/internal/v1", ProductCode: "sample_product", Timeout: time.Second, Dependency: executor,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output struct{ Value string }
+	err = client.Do(context.Background(), Call{
+		Method: http.MethodPost, Path: "/commands", Body: struct{}{}, Dependency: "mediagen", Operation: "submit_execution", ExpectedStatuses: []int{http.StatusOK},
+	}, &output)
+	var typed *Error
+	if !errors.As(err, &typed) || typed.Kind != ErrorKindUnavailable || typed.Code != "onex_dependency_unavailable" {
+		t.Fatalf("error=%#v", err)
+	}
+}
+
+func TestClientRejectsPartialDependencyOperation(t *testing.T) {
+	client, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, Config{BaseURL: "https://onex.example/internal/v1", ProductCode: "sample_product"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output struct{ Value string }
+	err = client.Do(context.Background(), Call{Method: http.MethodGet, Path: "/assets/one", Dependency: "storage", ExpectedStatuses: []int{http.StatusOK}}, &output)
+	var typed *Error
+	if !errors.As(err, &typed) || typed.Kind != ErrorKindValidation || typed.Code != "onex_dependency_operation_invalid" {
+		t.Fatalf("error=%#v", err)
+	}
+}
+
+func TestClientUsesOperationSpecificSafeReadRetryBudget(t *testing.T) {
+	var attempts atomic.Int32
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, _ *http.Request) {
+		current := attempts.Add(1)
+		writer.Header().Set("Content-Type", "application/json")
+		if current < 3 {
+			writer.WriteHeader(http.StatusServiceUnavailable)
+			_, _ = writer.Write([]byte(`{"error":{"type":"api_error","code":"service_unavailable","message":"unavailable"}}`))
+			return
+		}
+		_, _ = writer.Write([]byte(`{"value":"accepted"}`))
+	}))
+	t.Cleanup(server.Close)
+	client, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, Config{
+		BaseURL: server.URL + "/internal/v1", ProductCode: "sample_product", Timeout: time.Second,
+		SafeReadRetry:    SafeReadRetryConfig{InitialBackoff: time.Nanosecond, MaxBackoff: time.Nanosecond},
+		OperationRetries: map[string]int{"storage.get_asset": 2},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output struct {
+		Value string `json:"value"`
+	}
+	err = client.Do(context.Background(), Call{
+		Method: http.MethodGet, Path: "/assets/one", Dependency: "storage", Operation: "get_asset", ExpectedStatuses: []int{http.StatusOK},
+	}, &output)
+	if err != nil || output.Value != "accepted" || attempts.Load() != 3 {
+		t.Fatalf("error=%#v output=%#v attempts=%d", err, output, attempts.Load())
+	}
+}
+
+func TestClientRejectsInvalidBoundaryConfigurationAndCalls(t *testing.T) {
+	baseConfig := Config{BaseURL: "https://onex.example/internal/v1", ProductCode: "sample_product"}
+	if _, err := NewClient(nil, signerFixture{}, baseConfig); err == nil {
+		t.Fatal("nil HTTP client was accepted")
+	}
+	if _, err := NewClient(httpclient.New(zap.NewNop()), nil, baseConfig); err == nil {
+		t.Fatal("nil signer was accepted")
+	}
+	for _, config := range []Config{
+		{BaseURL: "https://user@example.com/internal/v1", ProductCode: "sample_product"},
+		{BaseURL: "https://onex.example/internal/v2", ProductCode: "sample_product"},
+		{BaseURL: "https://onex.example/internal/v1", ProductCode: "SampleProduct"},
+		{BaseURL: "https://onex.example/internal/v1", ProductCode: "sample_product", Timeout: -time.Second},
+		{BaseURL: "https://onex.example/internal/v1", ProductCode: "sample_product", MaxResponseBytes: 512},
+	} {
+		if _, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, config); err == nil {
+			t.Fatalf("config %#v was accepted", config)
+		}
+	}
+
+	client, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, baseConfig)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output struct{ Value string }
+	var nilClient *Client
+	if err := nilClient.Do(context.Background(), Call{}, &output); err == nil {
+		t.Fatal("nil client call was accepted")
+	}
+	invalidCalls := []Call{
+		{Method: http.MethodDelete, Path: "/capabilities/opaque", ExpectedStatuses: []int{http.StatusOK}},
+		{Method: http.MethodGet, Path: "capabilities/opaque", ExpectedStatuses: []int{http.StatusOK}},
+		{Method: http.MethodGet, Path: "/capabilities//opaque", ExpectedStatuses: []int{http.StatusOK}},
+		{Method: http.MethodGet, Path: "/capabilities/opaque", UserID: -1, ExpectedStatuses: []int{http.StatusOK}},
+		{Method: http.MethodGet, Path: "/capabilities/opaque", ExpectedStatuses: nil},
+		{Method: http.MethodGet, Path: "/capabilities/opaque", ExpectedStatuses: []int{http.StatusOK}, Timeout: -time.Second},
+		{Method: http.MethodGet, Path: "/capabilities/opaque", Body: struct{}{}, ExpectedStatuses: []int{http.StatusOK}},
+		{Method: http.MethodGet, Path: "/capabilities/opaque", IdempotencyKey: "write-only", ExpectedStatuses: []int{http.StatusOK}},
+		{Method: http.MethodGet, Path: "/capabilities/opaque", RequestID: "embedded\nnewline", ExpectedStatuses: []int{http.StatusOK}},
+		{Method: http.MethodGet, Path: "/capabilities/opaque", RequestID: string(make([]byte, maximumRequestIDBytes+1)), ExpectedStatuses: []int{http.StatusOK}},
+	}
+	for _, call := range invalidCalls {
+		if err := client.Do(context.Background(), call, &output); err == nil {
+			t.Fatalf("call %#v was accepted", call)
+		}
+	}
+	encodingFailure := Call{
+		Method: http.MethodPost, Path: "/commands", Body: func() {}, ExpectedStatuses: []int{http.StatusOK},
+	}
+	if err := client.Do(context.Background(), encodingFailure, &output); err == nil {
+		t.Fatal("unencodable request was accepted")
+	}
+}
+
+func TestClientRejectsUnknownResponseFields(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, _ *http.Request) {
+		writer.Header().Set("Content-Type", "application/json")
+		_, _ = writer.Write([]byte(`{"value":"accepted","provider":"must-not-leak"}`))
+	}))
+	defer server.Close()
+
+	client, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, Config{BaseURL: server.URL + "/internal/v1", ProductCode: "sample_product"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output struct {
+		Value string `json:"value"`
+	}
+	err = client.Do(context.Background(), Call{Method: http.MethodGet, Path: "/mediagen/generations/gen_12345678", ExpectedStatuses: []int{http.StatusOK}}, &output)
+	var typed *Error
+	if !errors.As(err, &typed) || typed.Kind != ErrorKindContract || typed.Code != "onex_response_contract_invalid" {
+		t.Fatalf("error = %#v", err)
+	}
+}
+
+func TestClientEncodesClonedQueryValues(t *testing.T) {
+	requestStarted := make(chan struct{})
+	releaseSigner := make(chan struct{})
+	signer := blockingSignerFixture{started: requestStarted, release: releaseSigner}
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		if request.URL.RawQuery != "product_reference_id=attempt_01&tag=a&tag=b" {
+			t.Errorf("raw query = %q", request.URL.RawQuery)
+		}
+		writer.Header().Set("Content-Type", "application/json")
+		_, _ = writer.Write([]byte(`{"value":"accepted"}`))
+	}))
+	t.Cleanup(server.Close)
+	client, err := NewClient(httpclient.New(zap.NewNop()), signer, Config{BaseURL: server.URL + "/internal/v1", ProductCode: "sample_product"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	query := url.Values{"tag": {"a", "b"}, "product_reference_id": {"attempt_01"}}
+	done := make(chan error, 1)
+	go func() {
+		var output struct {
+			Value string `json:"value"`
+		}
+		done <- client.Do(context.Background(), Call{Method: http.MethodGet, Path: "/capabilities/opaque", Query: query, ExpectedStatuses: []int{http.StatusOK}}, &output)
+	}()
+	<-requestStarted
+	query.Set("product_reference_id", "mutated")
+	query["tag"][0] = "mutated"
+	close(releaseSigner)
+	if err := <-done; err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestClientQueryValidation(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		if request.URL.RawQuery != "" {
+			t.Errorf("empty query encoded as %q", request.URL.RawQuery)
+		}
+		writer.Header().Set("Content-Type", "application/json")
+		_, _ = writer.Write([]byte(`{"value":"accepted"}`))
+	}))
+	t.Cleanup(server.Close)
+	client, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, Config{BaseURL: server.URL + "/internal/v1", ProductCode: "sample_product"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output struct {
+		Value string `json:"value"`
+	}
+	if err := client.Do(context.Background(), Call{Method: http.MethodGet, Path: "/capabilities/opaque", Query: url.Values{}, ExpectedStatuses: []int{http.StatusOK}}, &output); err != nil {
+		t.Fatal(err)
+	}
+	tooManyKeys := make(url.Values, 17)
+	for index := range 17 {
+		tooManyKeys[fmt.Sprintf("key_%02d", index)] = []string{"value"}
+	}
+	tooManyValues := make([]string, 65)
+	for index := range tooManyValues {
+		tooManyValues[index] = "value"
+	}
+	for _, call := range []Call{
+		{Method: http.MethodGet, Path: "/capabilities/opaque?embedded=true", ExpectedStatuses: []int{http.StatusOK}},
+		{Method: http.MethodGet, Path: "/capabilities/opaque#fragment", ExpectedStatuses: []int{http.StatusOK}},
+		{Method: http.MethodGet, Path: "/capabilities/opaque", Query: url.Values{"": {"value"}}, ExpectedStatuses: []int{http.StatusOK}},
+		{Method: http.MethodGet, Path: "/capabilities/opaque", Query: url.Values{"key": {}}, ExpectedStatuses: []int{http.StatusOK}},
+		{Method: http.MethodGet, Path: "/capabilities/opaque", Query: url.Values{"key": {"line\nbreak"}}, ExpectedStatuses: []int{http.StatusOK}},
+		{Method: http.MethodGet, Path: "/capabilities/opaque", Query: url.Values{strings.Repeat("k", 129): {"value"}}, ExpectedStatuses: []int{http.StatusOK}},
+		{Method: http.MethodGet, Path: "/capabilities/opaque", Query: url.Values{"key": {strings.Repeat("v", 1025)}}, ExpectedStatuses: []int{http.StatusOK}},
+		{Method: http.MethodGet, Path: "/capabilities/opaque", Query: tooManyKeys, ExpectedStatuses: []int{http.StatusOK}},
+		{Method: http.MethodGet, Path: "/capabilities/opaque", Query: url.Values{"key": tooManyValues}, ExpectedStatuses: []int{http.StatusOK}},
+	} {
+		if err := client.Do(context.Background(), call, &output); err == nil {
+			t.Fatalf("call %#v was accepted", call)
+		}
+	}
+}
+
+type blockingSignerFixture struct {
+	started chan<- struct{}
+	release <-chan struct{}
+}
+
+func (fixture blockingSignerFixture) AuthHeaders(context.Context) (map[string]string, error) {
+	close(fixture.started)
+	<-fixture.release
+	return map[string]string{"Authorization": "Bearer signed-service-token"}, nil
+}
+
+func (blockingSignerFixture) AuthorizeRequest(context.Context, *http.Request) error { return nil }
+
+func TestClientValidatesRequiredResponseHeadersBeforeBodyDecode(t *testing.T) {
+	for _, test := range []struct {
+		name       string
+		header     string
+		body       string
+		wantCode   string
+		wantOutput string
+	}{
+		{name: "missing header", body: `{"value":"accepted","unknown":true}`, wantCode: "onex_response_headers_invalid"},
+		{name: "wrong header", header: "public, max-age=60", body: `{"value":"accepted"}`, wantCode: "onex_response_headers_invalid"},
+		{name: "body checked after header", header: "private, no-store", body: `{"value":"accepted","unknown":true}`, wantCode: "onex_response_contract_invalid"},
+		{name: "accepted", header: "private, no-store", body: `{"value":"accepted"}`, wantOutput: "accepted"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, _ *http.Request) {
+				writer.Header().Set("Content-Type", "application/json")
+				if test.header != "" {
+					writer.Header().Set("Cache-Control", test.header)
+				}
+				_, _ = writer.Write([]byte(test.body))
+			}))
+			defer server.Close()
+
+			client, err := NewClient(httpclient.New(zap.NewNop()), signerFixture{}, Config{BaseURL: server.URL + "/internal/v1", ProductCode: "sample_product"})
+			if err != nil {
+				t.Fatal(err)
+			}
+			var output struct {
+				Value string `json:"value"`
+			}
+			err = client.Do(context.Background(), Call{
+				Method: http.MethodGet, Path: "/capabilities/opaque",
+				ExpectedStatuses: []int{http.StatusOK}, RequiredResponseHeaders: map[string]string{"Cache-Control": "private, no-store"},
+			}, &output)
+			if test.wantCode == "" {
+				if err != nil || output.Value != test.wantOutput {
+					t.Fatalf("Do() = %#v, %v", output, err)
+				}
+				return
+			}
+			var typed *Error
+			if !errors.As(err, &typed) || typed.Code != test.wantCode {
+				t.Fatalf("error = %#v", err)
+			}
+		})
+	}
+}
+
+func TestDecodeStrictRejectsDuplicateFieldsAndTrailingValues(t *testing.T) {
+	for _, body := range [][]byte{[]byte(`{"value":1,"value":2}`), []byte(`{"value":1}{"value":2}`)} {
+		var output struct {
+			Value int `json:"value"`
+		}
+		if err := DecodeStrict(body, &output); err == nil {
+			t.Fatalf("DecodeStrict(%s) accepted malformed contract", body)
+		}
+	}
+}