Конфигурация

Config

type Config struct {
    Timeouts   *TimeoutConfig
    Connection *ConnectionConfig
    Security   *SecurityConfig
    Retry      *RetryConfig
    Middleware *MiddlewareConfig
}

Основная структура конфигурации. Получите безопасные значения по умолчанию через DefaultConfig().

Подконфигурации как указатели

Начиная с v1.5.1 все пять подконфигураций являются типами-указателями. DefaultConfig() и все функции предустановок (SecureConfig, PerformanceConfig и др.) автоматически инициализируют эти указатели непустыми структурами, поэтому обращения к полям вида cfg.Timeouts.Request, cfg.Security.AllowPrivateIPs и т. п. можно использовать напрямую. При ручном конструировании литерала Config{} значения нужно присваивать в виде &httpc.TimeoutConfig{...}, а перед использованием убедиться, что указатель не равен nil.

cfg := httpc.DefaultConfig()
cfg.Timeouts.Request = 60 * time.Second
cfg.Retry.MaxRetries = 5
client, err := httpc.New(cfg)

TimeoutConfig

type TimeoutConfig struct {
    Request        time.Duration // Общий таймаут запроса (включая повторы), по умолчанию 180s
    Dial           time.Duration // Таймаут TCP-соединения, по умолчанию 10s
    TLSHandshake   time.Duration // Таймаут TLS-рукопожатия, по умолчанию 10s
    ResponseHeader time.Duration // Таймаут ожидания заголовков ответа, по умолчанию 0 (отключено, зависит от контекста)
    IdleConn       time.Duration // Время удержания простаивающих соединений, по умолчанию 90s
}

Поле	Значение по умолчанию	Максимум
Request	180s	30min
Dial	10s	30min
TLSHandshake	10s	30min
ResponseHeader	0	30min
IdleConn	90s	30min

Значение 0 означает отсутствие таймаута (не рекомендуется для продакшена).

Дизайн ResponseHeader

ResponseHeader по умолчанию равен 0 (отключен), при этом используется TimeoutConfig.Request или WithTimeout() как единственный механизм таймаута, что обеспечивает полный контроль WithTimeout() над длительностью запроса. Этот дизайн подходит для AI API и long-polling, где требуется увеличенное время ответа. Устанавливайте положительное значение только при необходимости жёсткого ограничения транспортного уровня (например, для защиты от атак Slowloris), но учтите, что это переопределит WithTimeout.

ConnectionConfig

type ConnectionConfig struct {
    MaxIdleConns           int           // Глобальное максимальное число простаивающих соединений, по умолчанию 50
    MaxConnsPerHost        int           // Максимум соединений на хост, по умолчанию 10
    ProxyURL               string        // Адрес прокси, например "http://proxy:8080"
    EnableSystemProxy      bool          // Автообнаружение системного прокси, по умолчанию false
    EnableHTTP2            bool          // Включить HTTP/2, по умолчанию true
    EnableCookies          bool          // Включить управление Cookie, по умолчанию false
    EnableDoH              bool          // Включить DNS-over-HTTPS, по умолчанию false
    DoHCacheTTL            time.Duration // TTL кэша DoH, по умолчанию 5min
    MaxResponseHeaderBytes int64         // Максимальный размер заголовков ответа в байтах, по умолчанию 0 (используется стандартное значение Go 10MB)
}

DNS-over-HTTPS

Включение DoH снижает задержку разрешения DNS и предотвращает перехват DNS:

cfg := httpc.DefaultConfig()
cfg.Connection.EnableDoH = true
cfg.Connection.DoHCacheTTL = 5 * time.Minute

Провайдеры DoH по умолчанию (по приоритету): Cloudflare → Google → AliDNS. Подробнее см. Пул соединений и прокси.

SecurityConfig

type SecurityConfig struct {
    TLSConfig               *tls.Config    // Пользовательская конфигурация TLS
    MinTLSVersion           uint16                // Минимальная версия TLS, по умолчанию TLS 1.2
    MaxTLSVersion           uint16                // Максимальная версия TLS, по умолчанию TLS 1.3
    InsecureSkipVerify      bool                  // Пропуск проверки сертификата (только для тестов)
    MaxResponseBodySize     int64                 // Лимит размера тела ответа, по умолчанию 10MB
    MaxRequestBodySize      int64                 // Лимит размера тела запроса, по умолчанию 0 (без ограничения размера тела запроса; в отличие от MaxResponseBodySize автоматического отката нет)
    MaxDecompressedBodySize int64                 // Лимит размера после распаковки, по умолчанию 100MB
    AllowPrivateIPs         bool                  // Разрешить приватные IP, по умолчанию false
    SSRFExemptCIDRs         []string              // Исключения CIDR для SSRF
    ValidateURL             bool                  // Валидация URL, по умолчанию true
    ValidateHeaders         bool                  // Валидация заголовков запроса, по умолчанию true
    StrictContentLength     bool                  // Строгий Content-Length, по умолчанию true
    CookieSecurity          *CookieSecurityConfig // Проверка безопасности Cookie
    CertificatePinner       CertificatePinner     // Пиннинг сертификатов (SPKI-хэш/публичный ключ), по умолчанию nil (отключено)
    RedirectWhitelist       []string              // Белый список доменов для перенаправлений
}

Пиннинг сертификатов (CertificatePinner)

CertificatePinner включает пиннинг сертификатов: TLS-рукопожатие отклоняется, если сервер не предоставил закреплённый ключ/сертификат, что защищает от атак типа «человек посередине» даже при компрометации доверенного УЦ. По умолчанию nil (отключено). Создаётся следующими конструкторами:

Конструктор	Описание
`NewSPKIHashPinner(hashes ...string) (CertificatePinner, error)`	Создаётся из одного или нескольких base64-кодированных SPKI SHA-256-хэшей (наиболее распространён, поддерживает ротацию ключей)
`NewPublicKeyPinner(publicKeys ...[]byte) (CertificatePinner, error)`	Создаётся из DER-кодированных публичных ключей PKIX (внутренне вычисляется SHA-256)
`NewCertificatePinnerChain(pinners ...CertificatePinner) CertificatePinner`	Объединяет несколько pinner; принимается, если проходит хотя бы один

pinner, err := httpc.NewSPKIHashPinner(
    "YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2fuihg=", // Текущий ключ
    "C5+lpZ7tcVwmwQIMcRtPbsQtWLABXhQzejna0wHFr8M=", // Резервный ключ (ротация)
)
if err != nil {
    log.Fatal(err)
}

cfg := httpc.DefaultConfig()
cfg.Security.CertificatePinner = pinner
client, err := httpc.New(cfg)

Стоимость поддержки

Пиннинг сертификатов требует синхронного обновления закреплённых значений при смене серверного сертификата (например, при продлении Let's Encrypt). Рекомендуется закреплять несколько хэшей (текущий + резервный) и завести механизм обновления, чтобы ротация ключей не приводила к разрыву соединений.

Защита от SSRF

AllowPrivateIPs по умолчанию false, блокирует подключение к приватным/зарезервированным IP (127.0.0.1, 10.x, 192.168.x и др.). Устанавливайте true только при подключении к внутренним сервисам.

Пример исключений SSRF

cfg := httpc.DefaultConfig()
cfg.Security.SSRFExemptCIDRs = []string{
    "10.0.0.0/8",       // Внутренний VPC
    "100.64.0.0/10",    // Tailscale
}

RetryConfig

type RetryConfig struct {
    MaxRetries    int           // Максимальное число повторных попыток, по умолчанию 3
    Delay         time.Duration // Начальная задержка повтора, по умолчанию 1s
    BackoffFactor float64       // Множитель экспоненциальной задержки, по умолчанию 2.0
    EnableJitter  bool          // Включить джиттер, по умолчанию true
    MaxRetryDelay time.Duration // Максимальный предел задержки повтора, по умолчанию 30s
    CustomPolicy  RetryPolicy   // Пользовательская стратегия повторов
}

Поле	Значение по умолчанию	Диапазон
MaxRetries	3	0-10
Delay	1s	0-30min
BackoffFactor	2.0	1.0-10.0
MaxRetryDelay	30s	0-30min

Формула задержки повтора: min(Delay * BackoffFactor^attempt + jitter, MaxRetryDelay)

MiddlewareConfig

type MiddlewareConfig struct {
    Middlewares     []MiddlewareFunc // Список промежуточного ПО
    UserAgent       string           // User-Agent, по умолчанию "httpc/1.0"
    Headers         map[string]string // Заголовки по умолчанию
    FollowRedirects bool             // Следовать перенаправлениям, по умолчанию true
    MaxRedirects    int              // Максимальное число перенаправлений, по умолчанию 10
}

Предустановки конфигурации

DefaultConfig

func DefaultConfig() *Config

Безопасная конфигурация по умолчанию. Защита SSRF включена по умолчанию.

SecureConfig

func SecureConfig() *Config

Конфигурация с приоритетом безопасности. Более короткие таймауты, отключены автоматические перенаправления, строгая защита SSRF.

Параметр	Значение
Таймаут Request	15s
Таймаут Dial	5s
Таймаут TLSHandshake	5s
Таймаут ResponseHeader	10s (защита от Slowloris)
Таймаут IdleConn	30s
MaxIdleConns	20
MaxConnsPerHost	5
MaxResponseBodySize	5MB
MaxRetries	1
Delay	2s
EnableJitter	true
FollowRedirects	false

PerformanceConfig

func PerformanceConfig() *Config

Конфигурация для высокой пропускной способности. Увеличенный пул соединений, более длинные таймауты, с сохранением проверок безопасности.

TIP

PerformanceConfig сохраняет включёнными ValidateURL и ValidateHeaders для обеспечения безопасности. Если в доверенной среде требуется максимальная производительность, можно вручную отключить: cfg.Security.ValidateURL = false, но учитывайте риски безопасности (инъекции, SSRF).

Параметр	Значение
Таймаут Request	60s
Таймаут Dial	15s
Таймаут TLSHandshake	15s
Таймаут ResponseHeader	0 (отключено, используется таймаут Request)
Таймаут IdleConn	120s
MaxIdleConns	100
MaxConnsPerHost	20
EnableCookies	true
MaxResponseBodySize	50MB
StrictContentLength	false
ValidateURL	true
ValidateHeaders	true
Delay	500ms
BackoffFactor	1.5
EnableJitter	true

TestingConfig

func TestingConfig() *Config

Конфигурация для тестовой среды. Отключены проверки безопасности, короткие таймауты.

Параметр	Значение
Таймаут Dial	5s
Таймаут TLSHandshake	5s
Таймаут ResponseHeader	0 (отключено, используется таймаут Request)
Таймаут IdleConn	30s
MaxIdleConns	10
MaxConnsPerHost	5
EnableHTTP2	false
EnableCookies	true
InsecureSkipVerify	true
AllowPrivateIPs	true
ValidateURL	false
ValidateHeaders	false
MaxRetries	1
Delay	100ms
EnableJitter	false
UserAgent	httpc-test/1.0

DANGER

Эта конфигурация отключает проверку TLS и защиту SSRF, используйте только для тестов. Использование вне тестовой среды вызовет предупреждение безопасности (см. Вывод предупреждений безопасности).

MinimalConfig

func MinimalConfig() *Config

Лёгкая конфигурация. Отключены повторные попытки и перенаправления, минимальный пул соединений.

Параметр	Значение
Таймаут Dial	5s
Таймаут TLSHandshake	5s
Таймаут ResponseHeader	0 (отключено, используется таймаут Request)
Таймаут IdleConn	30s
MaxIdleConns	10
MaxConnsPerHost	2
MaxResponseBodySize	1MB
MaxRetries	0
Delay	0
BackoffFactor	1.0
EnableJitter	false
FollowRedirects	false

Вывод предупреждений безопасности

SetSecurityWarnOutput

func SetSecurityWarnOutput(w io.Writer)

Перенаправляет цель вывода предупреждений безопасности. При использовании TestingConfig() или установке SecurityConfig.InsecureSkipVerify (Config.Security) в true, httpc печатает в этот writer предупреждения уровня [SECURITY WARNING] (не более одного на каждое предупреждение на процесс). По умолчанию вывод направляется в os.Stderr; передача io.Discard полностью подавляет предупреждения, что удобно для тестов или тихого запуска в заведомо безопасных внутренних сценариях.

// Подавить предупреждения безопасности в тестах
httpc.SetSecurityWarnOutput(io.Discard)
cfg := httpc.TestingConfig()

Область действия

Эта настройка — глобальное состояние уровня процесса, влияющее на все впоследствии создаваемые клиенты. Предупреждения TestingConfig и InsecureSkipVerify учитываются независимо (не влияют на срабатывание друг друга), но используют общий writer вывода.

Валидация

ValidateConfig

func ValidateConfig(cfg *Config) error

Проверяет корректность конфигурации. New() вызывает автоматически, также можно вызывать явно.

cfg := httpc.DefaultConfig()
cfg.Retry.MaxRetries = 100 // вне диапазона

if err := httpc.ValidateConfig(cfg); err != nil {
    log.Fatal(err) // invalid retry configuration: Retry.MaxRetries must be 0-10, got 100
}

Config.String

func (c *Config) String() string

Возвращает безопасное строковое представление. Учётные данные ProxyURL маскируются, TLSConfig отображается как <configured> или <default>, Headers не выводятся.

cfg := httpc.DefaultConfig()
fmt.Println(cfg.String())
// Config{Timeouts:{Request: 3m0s, ...}, Security:{TLSConfig: <default>, ...}}

CookieSecurityConfig

type CookieSecurityConfig struct {
    RequireSecure                bool
    RequireHttpOnly              bool
    RequireSameSite              string
    AllowSameSiteNone            bool
    RequireSecureForSameSiteNone bool
}

Конфигурация проверки атрибутов безопасности Cookie.

Поле	Тип	Описание
RequireSecure	`bool`	Требовать установки атрибута Secure
RequireHttpOnly	`bool`	Требовать установки атрибута HttpOnly
RequireSameSite	`string`	Требуемое значение SameSite, например `"Strict"`, `"Lax"`; пустая строка — без проверки
AllowSameSiteNone	`bool`	Разрешить ли SameSite=None
RequireSecureForSameSiteNone	`bool`	Требовать атрибут Secure при SameSite=None (по умолчанию `true`)

DefaultCookieSecurityConfig

func DefaultCookieSecurityConfig() *CookieSecurityConfig

Конфигурация безопасности Cookie по умолчанию. Не требует атрибутов Secure/HttpOnly/SameSite, но принудительно требует Secure для Cookie с SameSite=None.

StrictCookieSecurityConfig

func StrictCookieSecurityConfig() *CookieSecurityConfig

Строгая конфигурация безопасности Cookie. Требует Secure, HttpOnly и SameSite=Strict.

cfg := httpc.DefaultConfig()
cfg.Security.CookieSecurity = httpc.StrictCookieSecurityConfig()

Конфигурация ​

Config ​

TimeoutConfig ​

ConnectionConfig ​

DNS-over-HTTPS ​

SecurityConfig ​

Пиннинг сертификатов (CertificatePinner) ​

Пример исключений SSRF ​

RetryConfig ​

MiddlewareConfig ​

Предустановки конфигурации ​

DefaultConfig ​

SecureConfig ​

PerformanceConfig ​

TestingConfig ​

MinimalConfig ​

Вывод предупреждений безопасности ​

SetSecurityWarnOutput ​

Валидация ​

ValidateConfig ​

Config.String ​

Безопасность Cookie ​

CookieSecurityConfig ​

DefaultCookieSecurityConfig ​

StrictCookieSecurityConfig ​