http

package
v1.0.64 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 25, 2025 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package http provides HTTP client utilities and helpers for AI providers.

Package http provides HTTP client utilities and helpers for AI providers. It includes reusable HTTP clients with retry logic, metrics, and interceptors.

Package http provides HTTP client utilities and helpers for AI providers. It includes reusable HTTP clients with retry logic, metrics, and interceptors.

Package http provides HTTP client utilities and helpers for AI providers. It includes reusable HTTP clients with retry logic, metrics, and interceptors.

Package http provides HTTP client utilities and helpers for AI providers.

Example (BuilderWithTransport)

Example_builderWithTransport demonstrates using the builder pattern with transport configuration 

package main

import (
	"context"
	"fmt"
	"net/http"
	"time"

	httputil "github.com/cecil-the-coder/ai-provider-kit/internal/http"
)

func main() {
	client := httputil.NewHTTPClientBuilder().
		WithTimeout(30*time.Second).
		WithRetry(3, time.Second).
		WithTransportConfig(300, 30, 100).
		WithIdleConnTimeout(60 * time.Second).
		WithTLSHandshakeTimeout(5 * time.Second).
		Build()

	req, _ := http.NewRequest("GET", "https://api.example.com/data", nil)
	resp, err := client.Do(context.Background(), req)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}
	defer func() { _ = resp.Body.Close() }() //nolint:errcheck // Example code

	fmt.Printf("Status: %d\n", resp.StatusCode)
}
Example (CustomTransportConfig)

Example_customTransportConfig demonstrates creating an HTTP client with custom connection pool settings 

package main

import (
	"context"
	"fmt"
	"net/http"
	"time"

	httputil "github.com/cecil-the-coder/ai-provider-kit/internal/http"
)

func main() {
	client := httputil.NewHTTPClient(httputil.HTTPClientConfig{
		Timeout:             30 * time.Second,
		MaxIdleConns:        200,
		MaxIdleConnsPerHost: 20,
		MaxConnsPerHost:     50,
		IdleConnTimeout:     120 * time.Second,
		TLSHandshakeTimeout: 15 * time.Second,
	})

	req, _ := http.NewRequest("GET", "https://api.example.com/data", nil)
	resp, err := client.Do(context.Background(), req)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}
	defer func() { _ = resp.Body.Close() }() //nolint:errcheck // Example code

	fmt.Printf("Status: %d\n", resp.StatusCode)
}
Example (DefaultClient)

Example_defaultClient demonstrates creating an HTTP client with default transport settings 

package main

import (
	"context"
	"fmt"
	"net/http"
	"time"

	httputil "github.com/cecil-the-coder/ai-provider-kit/internal/http"
)

func main() {
	client := httputil.NewHTTPClient(httputil.HTTPClientConfig{
		Timeout: 30 * time.Second,
	})

	req, _ := http.NewRequest("GET", "https://api.example.com/data", nil)
	resp, err := client.Do(context.Background(), req)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}
	defer func() { _ = resp.Body.Close() }() //nolint:errcheck // Example code

	fmt.Printf("Status: %d\n", resp.StatusCode)
}
Example (HighConcurrencyClient)

Example_highConcurrencyClient demonstrates creating a client optimized for high concurrency 

package main

import (
	"context"
	"fmt"
	"net/http"
	"time"

	httputil "github.com/cecil-the-coder/ai-provider-kit/internal/http"
)

func main() {
	// High concurrency client with 500 max idle connections
	client := httputil.NewHighConcurrencyHTTPClient(httputil.HTTPClientConfig{
		Timeout:    10 * time.Second,
		MaxRetries: 3,
	})

	req, _ := http.NewRequest("GET", "https://api.example.com/data", nil)
	resp, err := client.Do(context.Background(), req)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}
	defer func() { _ = resp.Body.Close() }() //nolint:errcheck // Example code

	fmt.Printf("Status: %d\n", resp.StatusCode)
}

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func AuthHeaders 

func AuthHeaders(method, token string) map[string]string

AuthHeaders creates authentication headers for different methods

func CalculateBackoff 

func CalculateBackoff(config BackoffConfig, attempt int) time.Duration

CalculateBackoff returns the delay for a given attempt number using exponential backoff attempt is 1-indexed (first retry is attempt 1)

func Clear added in v1.0.60 

func Clear()

Clear removes all cached clients from the pool. This is primarily useful for testing or when you need to reset connection state. Note: This does not close existing connections, just removes the references.

func CloseIdleConnections added in v1.0.60 

func CloseIdleConnections()

CloseIdleConnections closes all idle connections in all clients in the pool. This is useful for releasing resources without removing the clients from the pool.

func CommonHTTPHeaders 

func CommonHTTPHeaders() map[string]string

CommonHTTPHeaders returns commonly used HTTP headers for AI providers

func NewJSONRequest 

func NewJSONRequest(method, url string, body interface{}) (*http.Request, error)

NewJSONRequest creates a JSON HTTP request with proper headers

func RemoveClient added in v1.0.60 

func RemoveClient(baseURL string)

RemoveClient removes a specific client from the pool by base URL. Note: This does not close the client's connections, just removes the reference.

func Shutdown added in v1.0.60 

func Shutdown(ctx context.Context) error

Shutdown gracefully closes all connections in the pool. This should be called when shutting down the application to ensure all connections are properly closed.

func Size added in v1.0.60 

func Size() int

Size returns the number of clients currently in the pool.

func StartGlobalSessionWarmup added in v1.0.60 

func StartGlobalSessionWarmup()

StartGlobalSessionWarmup explicitly starts the global session warmup. This is optional - the warmup will start automatically on the first MarkUsed call.

func StopGlobalSessionWarmup added in v1.0.60 

func StopGlobalSessionWarmup()

StopGlobalSessionWarmup stops the global session warmup background goroutine. This should be called during application shutdown.

Types

type APIError 

type APIError struct {
	StatusCode int
	Message    string
	Type       string
	Code       string
	RawBody    string
	Timestamp  time.Time
}

APIError represents a standardized API error with context

func (*APIError) Error 

func (e *APIError) Error() string

type BackoffConfig 

type BackoffConfig struct {
	BaseDelay   time.Duration // Initial delay for the first retry
	MaxDelay    time.Duration // Maximum delay cap
	Multiplier  float64       // Exponential multiplier (typically 2.0)
	MaxAttempts int           // Maximum number of retry attempts
}

BackoffConfig configures exponential backoff behavior

func DefaultBackoffConfig 

func DefaultBackoffConfig() BackoffConfig

DefaultBackoffConfig returns sensible defaults for exponential backoff

type ClientMetrics 

type ClientMetrics struct {
	TotalRequests   int64         `json:"total_requests"`
	SuccessfulReqs  int64         `json:"successful_requests"`
	FailedReqs      int64         `json:"failed_requests"`
	AvgLatency      time.Duration `json:"avg_latency"`
	P95Latency      time.Duration `json:"p95_latency"`
	LastRequestTime time.Time     `json:"last_request_time"`
	RetryCount      int64         `json:"retry_count"`
	ErrorsByType    map[int]int64 `json:"errors_by_type"`
	// Connection-level metrics (aggregated across all requests)
	ConnectionMetricsSummary *ConnectionMetricsSummary `json:"connection_metrics_summary,omitempty"`
}

ClientMetrics tracks HTTP client performance

type ClientPool added in v1.0.60 

type ClientPool struct {
	// contains filtered or unexported fields
}

ClientPool manages shared HTTP clients keyed by base URL. This enables HTTP/2 connection sharing across providers targeting the same host, reducing TLS handshakes and improving resource utilization.

func GetPool added in v1.0.60 

func GetPool() *ClientPool

GetPool returns the global client pool instance. This can be used for advanced operations or testing.

type ClientStatEntry added in v1.0.60 

type ClientStatEntry struct {
	BaseURL      string        `json:"base_url"`
	RequestCount int64         `json:"request_count"`
	SuccessCount int64         `json:"success_count"`
	ErrorCount   int64         `json:"error_count"`
	AvgLatency   time.Duration `json:"avg_latency"`
}

ClientStatEntry represents statistics for a single client in the pool.

type ClientStats added in v1.0.60 

type ClientStats struct {
	ClientCount int               `json:"client_count"`
	Clients     []ClientStatEntry `json:"clients,omitempty"`
}

ClientStats returns statistics about the client pool.

func GetStats added in v1.0.60 

func GetStats() ClientStats

GetStats returns statistics about all clients in the pool.

type ConnectionMetrics added in v1.0.60 

type ConnectionMetrics struct {
	// DNS lookup duration
	DNSLookupDuration time.Duration `json:"dns_lookup_duration"`
	// TCP connect duration
	TCPConnectDuration time.Duration `json:"tcp_connect_duration"`
	// TLS handshake duration (for HTTPS)
	TLSHandshakeDuration time.Duration `json:"tls_handshake_duration"`
	// Time to first byte (TTFB)
	TimeToFirstByte time.Duration `json:"time_to_first_byte"`
	// Total connection time
	TotalConnectionTime time.Duration `json:"total_connection_time"`
}

ConnectionMetrics holds detailed connection timing for a single request

type ConnectionMetricsSummary added in v1.0.60 

type ConnectionMetricsSummary struct {
	// Number of requests with connection metrics
	TotalMeasurements int64 `json:"total_measurements"`
	// Average DNS lookup duration
	AvgDNSLookupDuration time.Duration `json:"avg_dns_lookup_duration"`
	// Average TCP connect duration
	AvgTCPConnectDuration time.Duration `json:"avg_tcp_connect_duration"`
	// Average TLS handshake duration
	AvgTLSHandshakeDuration time.Duration `json:"avg_tls_handshake_duration"`
	// Average TTFB
	AvgTimeToFirstByte time.Duration `json:"avg_time_to_first_byte"`
	// Average total connection time
	AvgTotalConnectionTime time.Duration `json:"avg_total_connection_time"`
	// Min/Max for each metric
	MinDNSLookupDuration    time.Duration `json:"min_dns_lookup_duration"`
	MaxDNSLookupDuration    time.Duration `json:"max_dns_lookup_duration"`
	MinTCPConnectDuration   time.Duration `json:"min_tcp_connect_duration"`
	MaxTCPConnectDuration   time.Duration `json:"max_tcp_connect_duration"`
	MinTLSHandshakeDuration time.Duration `json:"min_tls_handshake_duration"`
	MaxTLSHandshakeDuration time.Duration `json:"max_tls_handshake_duration"`
	MinTimeToFirstByte      time.Duration `json:"min_time_to_first_byte"`
	MaxTimeToFirstByte      time.Duration `json:"max_time_to_first_byte"`
	MinTotalConnectionTime  time.Duration `json:"min_total_connection_time"`
	MaxTotalConnectionTime  time.Duration `json:"max_total_connection_time"`
}

ConnectionMetricsSummary aggregates connection metrics across multiple requests

type DefaultConfigProvider 

type DefaultConfigProvider struct{}

DefaultConfigProvider provides configuration for common AI providers

func (*DefaultConfigProvider) GetHTTPConfig 

func (d *DefaultConfigProvider) GetHTTPConfig(providerType types.ProviderType) HTTPClientConfig

GetHTTPConfig returns HTTP configuration for different provider types

type ErrorResponse 

type ErrorResponse struct {
	Error struct {
		Type    string `json:"type"`
		Message string `json:"message"`
		Code    string `json:"code,omitempty"`
	} `json:"error"`
	Details map[string]interface{} `json:"details,omitempty"`
}

ErrorResponse represents a standardized error response

type HTTPClient 

type HTTPClient struct {
	// contains filtered or unexported fields
}

HTTPClient provides a reusable HTTP client with common patterns for AI providers

func DefaultClient 

func DefaultClient(providerType types.ProviderType) *HTTPClient

DefaultClient creates an HTTP client with sensible defaults for AI providers

func GetClient added in v1.0.60 

func GetClient(baseURL string) *HTTPClient

GetClient returns an HTTP client for the given base URL, creating if needed. This ensures that providers targeting the same base URL share the same HTTP client, enabling HTTP/2 connection pooling and reducing resource usage.

func GetClientForURL added in v1.0.60 

func GetClientForURL(fullURL string) *HTTPClient

GetClientForURL extracts the base URL from a full URL and returns the appropriate client. This is a convenience function that automatically extracts the scheme and host.

func GetClientWithConfig added in v1.0.60 

func GetClientWithConfig(baseURL string, config HTTPClientConfig) *HTTPClient

GetClientWithConfig returns an HTTP client for the given base URL with custom config. If a client already exists for the base URL, the existing client is returned and the custom config is not applied (first caller wins). Use this when you need specific timeout or retry behavior.

func GetClientWithTimeout added in v1.0.60 

func GetClientWithTimeout(baseURL string, timeout time.Duration) *HTTPClient

GetClientWithTimeout returns an HTTP client for the given base URL with a specific timeout. If a client already exists for the base URL, it will be returned regardless of timeout. This is a convenience wrapper around GetClientWithConfig.

func NewHTTPClient 

func NewHTTPClient(config HTTPClientConfig) *HTTPClient

NewHTTPClient creates a new HTTP client with common configurations

func NewHighConcurrencyHTTPClient added in v1.0.40 

func NewHighConcurrencyHTTPClient(config HTTPClientConfig) *HTTPClient

NewHighConcurrencyHTTPClient creates an HTTP client optimized for high-concurrency scenarios. It uses increased connection pool limits suitable for applications making many parallel requests.

func (*HTTPClient) Client added in v1.0.40 

func (c *HTTPClient) Client() *http.Client

Client returns the underlying http.Client

func (*HTTPClient) Do 

func (c *HTTPClient) Do(ctx context.Context, req *http.Request) (*http.Response, error)

Do executes an HTTP request with retry logic and metrics

func (*HTTPClient) DoJSON 

func (c *HTTPClient) DoJSON(ctx context.Context, method, url string, body interface{}) (*http.Response, error)

DoJSON sends a JSON request with specified method

func (*HTTPClient) DoWithFullResponse 

func (c *HTTPClient) DoWithFullResponse(ctx context.Context, req *http.Request) (string, *http.Response, error)

DoWithFullResponse executes request and returns response body as string

func (*HTTPClient) GetLastRequestInfo added in v1.0.60 

func (c *HTTPClient) GetLastRequestInfo() LastRequestInfo

GetLastRequestInfo returns info about the last request made.

func (*HTTPClient) GetMetrics 

func (c *HTTPClient) GetMetrics() ClientMetrics

GetMetrics returns current client metrics

func (*HTTPClient) PostJSON 

func (c *HTTPClient) PostJSON(ctx context.Context, url string, body interface{}) (*http.Response, error)

PostJSON sends a JSON POST request

func (*HTTPClient) PreWarmConnections added in v1.0.60 

func (c *HTTPClient) PreWarmConnections(ctx context.Context, targets []string, count int) error

PreWarmConnections establishes connections to the given targets before actual requests

func (*HTTPClient) ResetMetrics 

func (c *HTTPClient) ResetMetrics()

ResetMetrics resets all metrics

type HTTPClientBuilder 

type HTTPClientBuilder struct {
	// contains filtered or unexported fields
}

HTTPClientBuilder provides a builder pattern for HTTPClient

func NewHTTPClientBuilder 

func NewHTTPClientBuilder() *HTTPClientBuilder

NewHTTPClientBuilder creates a new builder

func (*HTTPClientBuilder) Build 

func (b *HTTPClientBuilder) Build() *HTTPClient

Build creates the HTTP client

func (*HTTPClientBuilder) WithExpectContinueTimeout added in v1.0.40 

func (b *HTTPClientBuilder) WithExpectContinueTimeout(timeout time.Duration) *HTTPClientBuilder

WithExpectContinueTimeout sets the expect continue timeout

func (*HTTPClientBuilder) WithHeaders 

func (b *HTTPClientBuilder) WithHeaders(headers map[string]string) *HTTPClientBuilder

WithHeaders sets default headers

func (*HTTPClientBuilder) WithIdleConnTimeout added in v1.0.40 

func (b *HTTPClientBuilder) WithIdleConnTimeout(timeout time.Duration) *HTTPClientBuilder

WithIdleConnTimeout sets the idle connection timeout

func (*HTTPClientBuilder) WithMetrics 

func (b *HTTPClientBuilder) WithMetrics(enabled bool) *HTTPClientBuilder

WithMetrics enables metrics collection

func (*HTTPClientBuilder) WithRequestInterceptor 

func (b *HTTPClientBuilder) WithRequestInterceptor(interceptor RequestInterceptor) *HTTPClientBuilder

WithRequestInterceptor sets a request interceptor

func (*HTTPClientBuilder) WithResponseHeaderTimeout added in v1.0.64 

func (b *HTTPClientBuilder) WithResponseHeaderTimeout(timeout time.Duration) *HTTPClientBuilder

WithResponseHeaderTimeout sets the response header timeout

func (*HTTPClientBuilder) WithResponseInterceptor 

func (b *HTTPClientBuilder) WithResponseInterceptor(interceptor ResponseInterceptor) *HTTPClientBuilder

WithResponseInterceptor sets a response interceptor

func (*HTTPClientBuilder) WithRetry 

func (b *HTTPClientBuilder) WithRetry(maxRetries int, baseDelay time.Duration) *HTTPClientBuilder

WithRetry sets retry configuration

func (*HTTPClientBuilder) WithTLSHandshakeTimeout added in v1.0.40 

func (b *HTTPClientBuilder) WithTLSHandshakeTimeout(timeout time.Duration) *HTTPClientBuilder

WithTLSHandshakeTimeout sets the TLS handshake timeout

func (*HTTPClientBuilder) WithTimeout 

func (b *HTTPClientBuilder) WithTimeout(timeout time.Duration) *HTTPClientBuilder

WithTimeout sets the timeout

func (*HTTPClientBuilder) WithTransportConfig added in v1.0.40 

func (b *HTTPClientBuilder) WithTransportConfig(maxIdleConns, maxIdleConnsPerHost, maxConnsPerHost int) *HTTPClientBuilder

WithTransportConfig sets transport configuration for connection pooling

func (*HTTPClientBuilder) WithUserAgent 

func (b *HTTPClientBuilder) WithUserAgent(userAgent string) *HTTPClientBuilder

WithUserAgent sets the user agent

type HTTPClientConfig 

type HTTPClientConfig struct {
	Timeout               time.Duration       `json:"timeout,omitempty"`
	MaxRetries            int                 `json:"max_retries,omitempty"`
	BaseRetryDelay        time.Duration       `json:"base_retry_delay,omitempty"`
	MaxRetryDelay         time.Duration       `json:"max_retry_delay,omitempty"`
	BackoffMultiplier     float64             `json:"backoff_multiplier,omitempty"`
	RetryableErrors       []string            `json:"retryable_errors,omitempty"`
	Headers               map[string]string   `json:"headers,omitempty"`
	UserAgent             string              `json:"user_agent,omitempty"`
	EnableMetrics         bool                `json:"enable_metrics,omitempty"`
	EnableConnectionTrace bool                `json:"enable_connection_trace,omitempty"` // Opt-in connection-level tracing
	RequestInterceptor    RequestInterceptor  `json:"-"`
	ResponseInterceptor   ResponseInterceptor `json:"-"`
	// Transport configuration
	MaxIdleConns          int           `json:"max_idle_conns,omitempty"`
	MaxIdleConnsPerHost   int           `json:"max_idle_conns_per_host,omitempty"`
	MaxConnsPerHost       int           `json:"max_conns_per_host,omitempty"`
	IdleConnTimeout       time.Duration `json:"idle_conn_timeout,omitempty"`
	TLSHandshakeTimeout   time.Duration `json:"tls_handshake_timeout,omitempty"`
	ExpectContinueTimeout time.Duration `json:"expect_continue_timeout,omitempty"`
	ResponseHeaderTimeout time.Duration `json:"response_header_timeout,omitempty"`
}

HTTPClientConfig configures the HTTP client

type LastRequestInfo added in v1.0.60 

type LastRequestInfo struct {
	Request      *http.Request
	Response     *http.Response
	Attempts     int
	TotalLatency time.Duration
	Error        error
}

LastRequestInfo represents information about the last request for error handling. This can be used to enrich errors with request/response context.

type RequestBuilder 

type RequestBuilder struct {
	// contains filtered or unexported fields
}

RequestBuilder helps build HTTP requests with common patterns

func NewRequestBuilder 

func NewRequestBuilder(method, url string) *RequestBuilder

NewRequestBuilder creates a new request builder

func (*RequestBuilder) Build 

func (rb *RequestBuilder) Build() (*http.Request, error)

Build creates the HTTP request

func (*RequestBuilder) WithContext 

func (rb *RequestBuilder) WithContext(ctx context.Context) *RequestBuilder

WithContext sets the request context

func (*RequestBuilder) WithHeader 

func (rb *RequestBuilder) WithHeader(key, value string) *RequestBuilder

WithHeader adds a single header

func (*RequestBuilder) WithHeaders 

func (rb *RequestBuilder) WithHeaders(headers map[string]string) *RequestBuilder

WithHeaders adds headers to the request

func (*RequestBuilder) WithJSONBody 

func (rb *RequestBuilder) WithJSONBody(body interface{}) *RequestBuilder

WithJSONBody sets a JSON body

type RequestInterceptor 

type RequestInterceptor interface {
	Intercept(req *http.Request) error
}

RequestInterceptor allows modifying requests before sending

type ResponseInterceptor 

type ResponseInterceptor interface {
	Intercept(resp *http.Response) error
}

ResponseInterceptor allows processing responses after receiving

type RetryHandler 

type RetryHandler struct {
	// contains filtered or unexported fields
}

RetryHandler manages retry logic with exponential backoff

type SessionWarmup added in v1.0.60 

type SessionWarmup struct {
	// contains filtered or unexported fields
}

SessionWarmup provides automatic session-aware connection warmup for HTTP clients. It tracks which base URLs have been recently used and sends periodic keep-alive requests to maintain warm connections, reducing cold start latency.

func NewSessionWarmup added in v1.0.60 

func NewSessionWarmup(checkInterval, maxIdle time.Duration) *SessionWarmup

NewSessionWarmup creates a new SessionWarmup instance with the specified intervals. If checkInterval or maxIdle are zero, defaults of 30 seconds are used.

func (*SessionWarmup) Clear added in v1.0.60 

func (s *SessionWarmup) Clear()

Clear removes all tracked hosts. This is primarily useful for testing.

func (*SessionWarmup) GetActiveHosts added in v1.0.60 

func (s *SessionWarmup) GetActiveHosts() []string

GetActiveHosts returns a list of base URLs that are currently considered active (used within the maxIdle duration). This is primarily useful for testing and debugging.

func (*SessionWarmup) GetLastSeen added in v1.0.60 

func (s *SessionWarmup) GetLastSeen(baseURL string) time.Time

GetLastSeen returns the lastSeen timestamp for the given base URL. Returns zero time if the URL is not being tracked.

func (*SessionWarmup) MarkUsed added in v1.0.60 

func (s *SessionWarmup) MarkUsed(baseURL string)

MarkUsed marks a base URL as recently used, updating its lastSeen timestamp. This should be called on each request to track active sessions.

func (*SessionWarmup) Start added in v1.0.60 

func (s *SessionWarmup) Start()

Start begins the background goroutine that sends periodic keep-alive requests to recently used hosts. It should be called once during application initialization.

func (*SessionWarmup) Stop added in v1.0.60 

func (s *SessionWarmup) Stop()

Stop halts the background warmup goroutine and releases resources. It should be called during application shutdown.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.