Sub2API v1.0 - AI API 网关（二开初始版本，基于上游 Wei-Shaw/sub2api）

backend/internal/pkg/servertiming/collector.go

@@ -0,0 +1,349 @@
+package servertiming
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+const (
+	HeaderName       = "Server-Timing"
+	AdminUIHeader    = "X-Admin-UI-Request"
+	UserUIHeader     = "X-User-UI-Request"
+	MetricDatabase   = "db"
+	MetricRedis      = "redis"
+	dependencyPrefix = "dep_"
+
+	maxMetricNameLength = 48
+	maxIntervals        = 2048
+	maxHeaderLength     = 4096
+)
+
+type contextKey struct{}
+
+type interval struct {
+	start time.Time
+	end   time.Time
+}
+
+type metric struct {
+	count     int64
+	intervals []interval
+}
+
+// Collector stores request-scoped timing samples. It is safe for concurrent use.
+type Collector struct {
+	startedAt time.Time
+
+	mu          sync.Mutex
+	metrics     map[string]*metric
+	cacheStatus string
+}
+
+// New creates a collector whose total duration starts at startedAt.
+func New(startedAt time.Time) *Collector {
+	if startedAt.IsZero() {
+		startedAt = time.Now()
+	}
+	return &Collector{
+		startedAt: startedAt,
+		metrics:   make(map[string]*metric),
+	}
+}
+
+// WithCollector attaches a collector to a context.
+func WithCollector(ctx context.Context, collector *Collector) context.Context {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	if collector == nil {
+		return ctx
+	}
+	return context.WithValue(ctx, contextKey{}, collector)
+}
+
+// FromContext returns the request timing collector, when one is active.
+func FromContext(ctx context.Context) (*Collector, bool) {
+	if ctx == nil {
+		return nil, false
+	}
+	collector, ok := ctx.Value(contextKey{}).(*Collector)
+	return collector, ok && collector != nil
+}
+
+// Active reports whether timing collection is enabled for this request.
+func Active(ctx context.Context) bool {
+	_, ok := FromContext(ctx)
+	return ok
+}
+
+// Record adds a completed interval and operation count to a metric.
+func Record(ctx context.Context, name string, startedAt, endedAt time.Time, count int) {
+	collector, ok := FromContext(ctx)
+	if !ok {
+		return
+	}
+	collector.Record(name, startedAt, endedAt, count)
+}
+
+// RecordInterval adds timing without incrementing the operation count. It is
+// useful when one logical operation has multiple blocking driver calls.
+func RecordInterval(ctx context.Context, name string, startedAt, endedAt time.Time) {
+	collector, ok := FromContext(ctx)
+	if !ok {
+		return
+	}
+	collector.record(name, startedAt, endedAt, 0)
+}
+
+// Record adds a completed interval directly to the collector.
+func (c *Collector) Record(name string, startedAt, endedAt time.Time, count int) {
+	if count <= 0 {
+		count = 1
+	}
+	c.record(name, startedAt, endedAt, count)
+}
+
+func (c *Collector) record(name string, startedAt, endedAt time.Time, count int) {
+	name = normalizeMetricName(name)
+	if c == nil || name == "" || startedAt.IsZero() || endedAt.Before(startedAt) {
+		return
+	}
+	if count < 0 {
+		count = 0
+	}
+
+	c.mu.Lock()
+	m := c.metrics[name]
+	if m == nil {
+		m = &metric{}
+		c.metrics[name] = m
+	}
+	m.count += int64(count)
+	if len(m.intervals) < maxIntervals {
+		m.intervals = append(m.intervals, interval{start: startedAt, end: endedAt})
+	}
+	c.mu.Unlock()
+}
+
+// Observe starts a metric span and returns an idempotent completion function.
+func Observe(ctx context.Context, name string) func() {
+	collector, ok := FromContext(ctx)
+	name = normalizeMetricName(name)
+	if !ok || name == "" {
+		return func() {}
+	}
+	startedAt := time.Now()
+	var once sync.Once
+	return func() {
+		once.Do(func() {
+			collector.Record(name, startedAt, time.Now(), 1)
+		})
+	}
+}
+
+// ObserveDependency starts a named external dependency span.
+func ObserveDependency(ctx context.Context, module string) func() {
+	return Observe(ctx, dependencyMetricName(module))
+}
+
+// RecordDependency records a completed external dependency interval.
+func RecordDependency(ctx context.Context, module string, startedAt, endedAt time.Time) {
+	Record(ctx, dependencyMetricName(module), startedAt, endedAt, 1)
+}
+
+// SetCacheStatus records the response-cache outcome for the request.
+func SetCacheStatus(ctx context.Context, status string) {
+	collector, ok := FromContext(ctx)
+	if !ok {
+		return
+	}
+	status = normalizeCacheStatus(status)
+	if status == "" {
+		return
+	}
+	collector.mu.Lock()
+	collector.cacheStatus = status
+	collector.mu.Unlock()
+}
+
+// HeaderValue renders a bounded, deterministic Server-Timing header.
+func HeaderValue(ctx context.Context, endedAt time.Time, cacheStatus string) string {
+	collector, ok := FromContext(ctx)
+	if !ok {
+		return ""
+	}
+	return collector.HeaderValue(endedAt, cacheStatus)
+}
+
+// HeaderValue renders a bounded, deterministic Server-Timing header.
+func (c *Collector) HeaderValue(endedAt time.Time, cacheStatus string) string {
+	if c == nil {
+		return ""
+	}
+	if endedAt.IsZero() {
+		endedAt = time.Now()
+	}
+	if endedAt.Before(c.startedAt) {
+		endedAt = c.startedAt
+	}
+
+	c.mu.Lock()
+	metrics := make(map[string]metric, len(c.metrics))
+	allIntervals := make([]interval, 0)
+	dependencyIntervals := make([]interval, 0)
+	var dependencyCount int64
+	for name, source := range c.metrics {
+		copied := metric{count: source.count, intervals: append([]interval(nil), source.intervals...)}
+		metrics[name] = copied
+		allIntervals = append(allIntervals, copied.intervals...)
+		if strings.HasPrefix(name, dependencyPrefix) {
+			dependencyIntervals = append(dependencyIntervals, copied.intervals...)
+			dependencyCount += copied.count
+		}
+	}
+	storedCacheStatus := c.cacheStatus
+	c.mu.Unlock()
+
+	total := endedAt.Sub(c.startedAt)
+	blocked := unionDuration(allIntervals, c.startedAt, endedAt)
+	app := total - blocked
+	if app < 0 {
+		app = 0
+	}
+
+	cacheStatus = normalizeCacheStatus(cacheStatus)
+	if cacheStatus == "" {
+		cacheStatus = normalizeCacheStatus(storedCacheStatus)
+	}
+	if cacheStatus == "" {
+		cacheStatus = "bypass"
+	}
+
+	database := metrics[MetricDatabase]
+	redisMetric := metrics[MetricRedis]
+	parts := []string{
+		"total;dur=" + formatDuration(total),
+		"app;dur=" + formatDuration(app),
+		fmt.Sprintf("db;dur=%s;desc=\"queries=%d\"", formatDuration(unionDuration(database.intervals, c.startedAt, endedAt)), database.count),
+		fmt.Sprintf("redis;dur=%s;desc=\"commands=%d\"", formatDuration(unionDuration(redisMetric.intervals, c.startedAt, endedAt)), redisMetric.count),
+		"cache;desc=\"" + cacheStatus + "\"",
+		fmt.Sprintf("deps;dur=%s;desc=\"calls=%d\"", formatDuration(unionDuration(dependencyIntervals, c.startedAt, endedAt)), dependencyCount),
+	}
+
+	dependencyNames := make([]string, 0)
+	for name := range metrics {
+		if strings.HasPrefix(name, dependencyPrefix) {
+			dependencyNames = append(dependencyNames, name)
+		}
+	}
+	sort.Strings(dependencyNames)
+	for _, name := range dependencyNames {
+		m := metrics[name]
+		part := fmt.Sprintf("%s;dur=%s;desc=\"calls=%d\"", name, formatDuration(unionDuration(m.intervals, c.startedAt, endedAt)), m.count)
+		candidate := strings.Join(append(parts, part), ", ")
+		if len(candidate) > maxHeaderLength {
+			break
+		}
+		parts = append(parts, part)
+	}
+
+	return strings.Join(parts, ", ")
+}
+
+func dependencyMetricName(module string) string {
+	module = normalizeMetricName(module)
+	module = strings.TrimPrefix(module, dependencyPrefix)
+	if module == "" {
+		module = "http"
+	}
+	return dependencyPrefix + module
+}
+
+func normalizeMetricName(name string) string {
+	name = strings.ToLower(strings.TrimSpace(name))
+	if name == "" {
+		return ""
+	}
+	var b strings.Builder
+	b.Grow(min(len(name), maxMetricNameLength))
+	for _, r := range name {
+		if b.Len() >= maxMetricNameLength {
+			break
+		}
+		switch {
+		case r >= 'a' && r <= 'z', r >= '0' && r <= '9':
+			_, _ = b.WriteRune(r)
+		case r == '_' || r == '-':
+			_ = b.WriteByte('_')
+		}
+	}
+	return strings.Trim(b.String(), "_")
+}
+
+func normalizeCacheStatus(status string) string {
+	switch strings.ToLower(strings.TrimSpace(status)) {
+	case "hit":
+		return "hit"
+	case "miss":
+		return "miss"
+	case "bypass":
+		return "bypass"
+	default:
+		return ""
+	}
+}
+
+func unionDuration(intervals []interval, lowerBound, upperBound time.Time) time.Duration {
+	if len(intervals) == 0 || !upperBound.After(lowerBound) {
+		return 0
+	}
+	normalized := make([]interval, 0, len(intervals))
+	for _, item := range intervals {
+		start := item.start
+		end := item.end
+		if start.Before(lowerBound) {
+			start = lowerBound
+		}
+		if end.After(upperBound) {
+			end = upperBound
+		}
+		if end.After(start) {
+			normalized = append(normalized, interval{start: start, end: end})
+		}
+	}
+	if len(normalized) == 0 {
+		return 0
+	}
+	sort.Slice(normalized, func(i, j int) bool {
+		return normalized[i].start.Before(normalized[j].start)
+	})
+
+	currentStart := normalized[0].start
+	currentEnd := normalized[0].end
+	var total time.Duration
+	for _, item := range normalized[1:] {
+		if !item.start.After(currentEnd) {
+			if item.end.After(currentEnd) {
+				currentEnd = item.end
+			}
+			continue
+		}
+		total += currentEnd.Sub(currentStart)
+		currentStart = item.start
+		currentEnd = item.end
+	}
+	total += currentEnd.Sub(currentStart)
+	return total
+}
+
+func formatDuration(value time.Duration) string {
+	if value < 0 {
+		value = 0
+	}
+	return strconv.FormatFloat(float64(value)/float64(time.Millisecond), 'f', 1, 64)
+}

backend/internal/pkg/servertiming/collector_test.go

@@ -0,0 +1,129 @@
+package servertiming
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestCollectorHeaderValueAggregatesIntervals(t *testing.T) {
+	startedAt := time.Unix(100, 0)
+	collector := New(startedAt)
+	collector.Record(MetricDatabase, startedAt.Add(10*time.Millisecond), startedAt.Add(40*time.Millisecond), 2)
+	collector.Record(MetricRedis, startedAt.Add(30*time.Millisecond), startedAt.Add(50*time.Millisecond), 3)
+	collector.Record(dependencyMetricName("openai"), startedAt.Add(70*time.Millisecond), startedAt.Add(100*time.Millisecond), 1)
+	collector.Record(dependencyMetricName("github"), startedAt.Add(60*time.Millisecond), startedAt.Add(90*time.Millisecond), 1)
+
+	got := collector.HeaderValue(startedAt.Add(120*time.Millisecond), "miss")
+	want := `total;dur=120.0, app;dur=40.0, db;dur=30.0;desc="queries=2", redis;dur=20.0;desc="commands=3", cache;desc="miss", deps;dur=40.0;desc="calls=2", dep_github;dur=30.0;desc="calls=1", dep_openai;dur=30.0;desc="calls=1"`
+	if got != want {
+		t.Fatalf("HeaderValue() = %q, want %q", got, want)
+	}
+}
+
+func TestRecordIntervalDoesNotIncrementCount(t *testing.T) {
+	startedAt := time.Unix(200, 0)
+	collector := New(startedAt)
+	ctx := WithCollector(context.Background(), collector)
+
+	Record(ctx, MetricDatabase, startedAt.Add(10*time.Millisecond), startedAt.Add(20*time.Millisecond), 1)
+	RecordInterval(ctx, MetricDatabase, startedAt.Add(30*time.Millisecond), startedAt.Add(40*time.Millisecond))
+
+	header := HeaderValue(ctx, startedAt.Add(100*time.Millisecond), "hit")
+	if !strings.Contains(header, `db;dur=20.0;desc="queries=1"`) {
+		t.Fatalf("header %q does not contain one query with both blocking intervals", header)
+	}
+	if !strings.Contains(header, "app;dur=80.0") {
+		t.Fatalf("header %q does not subtract the interval union from app time", header)
+	}
+}
+
+func TestCollectorCacheStatusFallback(t *testing.T) {
+	startedAt := time.Unix(300, 0)
+	collector := New(startedAt)
+	ctx := WithCollector(context.Background(), collector)
+
+	SetCacheStatus(ctx, " HIT ")
+	if got := HeaderValue(ctx, startedAt.Add(time.Millisecond), "invalid"); !strings.Contains(got, `cache;desc="hit"`) {
+		t.Fatalf("HeaderValue() = %q, want stored cache hit", got)
+	}
+
+	other := New(startedAt)
+	if got := other.HeaderValue(startedAt.Add(time.Millisecond), "invalid"); !strings.Contains(got, `cache;desc="bypass"`) {
+		t.Fatalf("HeaderValue() = %q, want cache bypass", got)
+	}
+}
+
+func TestCollectorSanitizesDependencyMetric(t *testing.T) {
+	startedAt := time.Unix(400, 0)
+	collector := New(startedAt)
+	ctx := WithCollector(context.Background(), collector)
+	RecordDependency(ctx, "GitHub API\r\nInjected;dur=999", startedAt, startedAt.Add(time.Millisecond))
+
+	header := HeaderValue(ctx, startedAt.Add(2*time.Millisecond), "bypass")
+	if strings.ContainsAny(header, "\r\n") || strings.Contains(header, ";dur=999") {
+		t.Fatalf("unsafe metric content reached header: %q", header)
+	}
+	if !strings.Contains(header, "dep_githubapiinjecteddur999;dur=1.0") {
+		t.Fatalf("sanitized dependency metric missing from header: %q", header)
+	}
+}
+
+func TestCollectorBoundsHeaderLength(t *testing.T) {
+	startedAt := time.Unix(500, 0)
+	collector := New(startedAt)
+	for i := 0; i < 300; i++ {
+		collector.Record(
+			dependencyMetricName(fmt.Sprintf("module_%03d_with_a_deliberately_long_name", i)),
+			startedAt,
+			startedAt.Add(time.Millisecond),
+			1,
+		)
+	}
+
+	header := collector.HeaderValue(startedAt.Add(2*time.Millisecond), "bypass")
+	if len(header) > maxHeaderLength {
+		t.Fatalf("header length = %d, want <= %d", len(header), maxHeaderLength)
+	}
+	if !strings.Contains(header, "total;dur=2.0") || !strings.Contains(header, "deps;dur=1.0") {
+		t.Fatalf("bounded header lost fixed metrics: %q", header)
+	}
+}
+
+func TestCollectorConcurrentRecording(t *testing.T) {
+	startedAt := time.Now()
+	collector := New(startedAt)
+	ctx := WithCollector(context.Background(), collector)
+
+	const workers = 25
+	const recordsPerWorker = 100
+	var wg sync.WaitGroup
+	wg.Add(workers)
+	for i := 0; i < workers; i++ {
+		go func() {
+			defer wg.Done()
+			for j := 0; j < recordsPerWorker; j++ {
+				Record(ctx, MetricDatabase, startedAt, startedAt.Add(time.Microsecond), 1)
+			}
+		}()
+	}
+	wg.Wait()
+
+	header := HeaderValue(ctx, startedAt.Add(time.Millisecond), "bypass")
+	want := fmt.Sprintf(`queries=%d`, workers*recordsPerWorker)
+	if !strings.Contains(header, want) {
+		t.Fatalf("header %q does not contain %q", header, want)
+	}
+}
+
+func TestContextHelpersHandleMissingCollector(t *testing.T) {
+	if Active(context.Background()) {
+		t.Fatal("context without collector reported active")
+	}
+	if got := HeaderValue(context.Background(), time.Now(), "hit"); got != "" {
+		t.Fatalf("HeaderValue() = %q without collector, want empty", got)
+	}
+}

backend/internal/pkg/servertiming/http.go

@@ -0,0 +1,104 @@
+package servertiming
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"time"
+)
+
+type dependencyModuleKey struct{}
+
+type timingRoundTripper struct {
+	base http.RoundTripper
+}
+
+// WithDependencyModule overrides the safe module name used for an outbound call.
+func WithDependencyModule(ctx context.Context, module string) context.Context {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	module = strings.TrimPrefix(normalizeMetricName(module), dependencyPrefix)
+	if module == "" {
+		return ctx
+	}
+	return context.WithValue(ctx, dependencyModuleKey{}, module)
+}
+
+// WrapRoundTripper records outbound response-header latency for active requests.
+func WrapRoundTripper(base http.RoundTripper) http.RoundTripper {
+	if base == nil {
+		base = http.DefaultTransport
+	}
+	if _, ok := base.(*timingRoundTripper); ok {
+		return base
+	}
+	return &timingRoundTripper{base: base}
+}
+
+// InstrumentClient returns a shallow client copy with an instrumented transport.
+func InstrumentClient(client *http.Client) *http.Client {
+	if client == nil {
+		client = &http.Client{}
+	}
+	copyClient := *client
+	copyClient.Transport = WrapRoundTripper(copyClient.Transport)
+	return &copyClient
+}
+
+// Do records response-header latency without changing the client's transport
+// type. Use it for clients whose callers inspect or configure *http.Transport.
+func Do(client *http.Client, req *http.Request) (*http.Response, error) {
+	if client == nil {
+		client = http.DefaultClient
+	}
+	if req == nil || !Active(req.Context()) {
+		return client.Do(req)
+	}
+	startedAt := time.Now()
+	response, err := client.Do(req)
+	RecordDependency(req.Context(), dependencyModule(req), startedAt, time.Now())
+	return response, err
+}
+
+func (t *timingRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
+	if req == nil || !Active(req.Context()) {
+		return t.base.RoundTrip(req)
+	}
+	startedAt := time.Now()
+	response, err := t.base.RoundTrip(req)
+	RecordDependency(req.Context(), dependencyModule(req), startedAt, time.Now())
+	return response, err
+}
+
+func dependencyModule(req *http.Request) string {
+	if req != nil {
+		if module, ok := req.Context().Value(dependencyModuleKey{}).(string); ok && module != "" {
+			return module
+		}
+	}
+	if req == nil || req.URL == nil {
+		return "http"
+	}
+	host := strings.ToLower(req.URL.Hostname())
+	switch {
+	case strings.Contains(host, "github"):
+		return "github"
+	case strings.Contains(host, "openai"):
+		return "openai"
+	case strings.Contains(host, "anthropic"):
+		return "anthropic"
+	case strings.Contains(host, "generativelanguage") || strings.Contains(host, "gemini"):
+		return "gemini"
+	case strings.Contains(host, "cloudcode") || strings.Contains(host, "antigravity"):
+		return "antigravity"
+	case strings.Contains(host, "googleapis") || strings.Contains(host, "google"):
+		return "google"
+	case strings.Contains(host, "amazonaws") || strings.Contains(host, "cloudflarestorage") || strings.Contains(host, "s3"):
+		return "s3"
+	case strings.Contains(host, "stripe") || strings.Contains(host, "airwallex") || strings.Contains(host, "alipay") || strings.Contains(host, "wechatpay") || strings.Contains(host, "paypal"):
+		return "payment"
+	default:
+		return "http"
+	}
+}

backend/internal/pkg/servertiming/http_test.go

@@ -0,0 +1,168 @@
+package servertiming
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+)
+
+type roundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return f(req)
+}
+
+type trackingBody struct {
+	read bool
+}
+
+func (b *trackingBody) Read(_ []byte) (int, error) {
+	b.read = true
+	return 0, io.EOF
+}
+
+func (b *trackingBody) Close() error { return nil }
+
+func TestWrapRoundTripperRecordsResponseHeaderLatency(t *testing.T) {
+	startedAt := time.Now()
+	collector := New(startedAt)
+	body := &trackingBody{}
+	baseCalled := false
+	base := roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		baseCalled = true
+		return &http.Response{
+			StatusCode: http.StatusOK,
+			Body:       body,
+			Header:     make(http.Header),
+			Request:    req,
+		}, nil
+	})
+	req, err := http.NewRequestWithContext(WithCollector(context.Background(), collector), http.MethodGet, "https://api.github.com/repos/example/project", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	resp, err := WrapRoundTripper(base).RoundTrip(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if !baseCalled {
+		t.Fatal("base RoundTripper was not called")
+	}
+	if body.read {
+		t.Fatal("RoundTripper instrumentation read the response body; timing must stop at response headers")
+	}
+	header := collector.HeaderValue(time.Now(), "bypass")
+	if !strings.Contains(header, `dep_github;dur=`) || !strings.Contains(header, `deps;dur=`) {
+		t.Fatalf("dependency metrics missing from header: %q", header)
+	}
+}
+
+func TestWrapRoundTripperUsesContextModuleOverride(t *testing.T) {
+	collector := New(time.Now())
+	ctx := WithDependencyModule(WithCollector(context.Background(), collector), "data-managementd")
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://private.example.test/path", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	base := roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody, Header: make(http.Header), Request: req}, nil
+	})
+
+	if _, err := WrapRoundTripper(base).RoundTrip(req); err != nil {
+		t.Fatal(err)
+	}
+	header := collector.HeaderValue(time.Now(), "bypass")
+	if !strings.Contains(header, "dep_data_managementd") {
+		t.Fatalf("module override missing from header: %q", header)
+	}
+	if strings.Contains(header, "private.example") {
+		t.Fatalf("raw host leaked into header: %q", header)
+	}
+}
+
+func TestWrapRoundTripperSkipsInactiveContext(t *testing.T) {
+	called := false
+	base := roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		called = true
+		return &http.Response{StatusCode: http.StatusNoContent, Body: http.NoBody, Header: make(http.Header), Request: req}, nil
+	})
+	req, err := http.NewRequest(http.MethodGet, "https://api.openai.com/v1/models", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := WrapRoundTripper(base).RoundTrip(req); err != nil {
+		t.Fatal(err)
+	}
+	if !called {
+		t.Fatal("inactive request did not reach base RoundTripper")
+	}
+}
+
+func TestDoRecordsWithoutChangingTransportType(t *testing.T) {
+	base := roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody, Header: make(http.Header), Request: req}, nil
+	})
+	client := &http.Client{Transport: base}
+	collector := New(time.Now())
+	req, err := http.NewRequestWithContext(WithCollector(context.Background(), collector), http.MethodGet, "https://api.openai.com/v1/models", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := Do(client, req); err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := client.Transport.(roundTripFunc); !ok {
+		t.Fatalf("Do changed client transport type to %T", client.Transport)
+	}
+	if header := collector.HeaderValue(time.Now(), "bypass"); !strings.Contains(header, "dep_openai;dur=") {
+		t.Fatalf("dependency metric missing from header: %q", header)
+	}
+}
+
+func TestDependencyModuleClassification(t *testing.T) {
+	tests := map[string]string{
+		"https://api.github.com/repos/a/b":                    "github",
+		"https://api.openai.com/v1/models":                    "openai",
+		"https://api.anthropic.com/v1/messages":               "anthropic",
+		"https://generativelanguage.googleapis.com/v1/models": "gemini",
+		"https://cloudcode-pa.googleapis.com/v1internal":      "antigravity",
+		"https://storage.googleapis.com/bucket/object":        "google",
+		"https://bucket.s3.amazonaws.com/object":              "s3",
+		"https://api.stripe.com/v1/refunds":                   "payment",
+		"https://dependency.example.test/path":                "http",
+	}
+	for rawURL, want := range tests {
+		req, err := http.NewRequest(http.MethodGet, rawURL, nil)
+		if err != nil {
+			t.Fatalf("NewRequest(%q): %v", rawURL, err)
+		}
+		if got := dependencyModule(req); got != want {
+			t.Errorf("dependencyModule(%q) = %q, want %q", rawURL, got, want)
+		}
+	}
+}
+
+func TestClientInstrumentationDoesNotMutateOriginal(t *testing.T) {
+	base := roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody, Header: make(http.Header), Request: req}, nil
+	})
+	original := &http.Client{Transport: base, Timeout: time.Second}
+	instrumented := InstrumentClient(original)
+	if instrumented == original {
+		t.Fatal("InstrumentClient returned the original client")
+	}
+	if _, ok := original.Transport.(roundTripFunc); !ok {
+		t.Fatalf("InstrumentClient mutated the original transport to %T", original.Transport)
+	}
+	if instrumented.Timeout != original.Timeout {
+		t.Fatal("InstrumentClient did not preserve client settings")
+	}
+	if WrapRoundTripper(instrumented.Transport) != instrumented.Transport {
+		t.Fatal("WrapRoundTripper wrapped an already instrumented transport twice")
+	}
+}