設定

Config

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

メイン設定構造体。DefaultConfig() で安全なデフォルト値を取得します。

サブ設定はポインタ

v1.5.1 以降、5 つのサブ設定はすべてポインタ型です。DefaultConfig() およびすべてのプリセット関数（SecureConfig、PerformanceConfig など）はこれらのポインタを非 nil の構造体に自動初期化するため、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 やロングポーリングなど、レスポンス時間を延長する必要があるシナリオに適しています。トランスポート層のハードリミットが必要な場合（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 // DoH キャッシュ TTL。デフォルト 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              // SSRF 免除 CIDR
    ValidateURL             bool                  // URL 検証。デフォルト true
    ValidateHeaders         bool                  // リクエストヘッダー検証。デフォルト true
    StrictContentLength     bool                  // 厳格な Content-Length。デフォルト true
    CookieSecurity          *CookieSecurityConfig // Cookie セキュリティ検証
    CertificatePinner       CertificatePinner     // 証明書固定（SPKI ハッシュ/公開鍵）。デフォルト nil（無効）
    RedirectWhitelist       []string              // リダイレクトホワイトリストドメイン
}

証明書固定（CertificatePinner）

CertificatePinner は証明書固定を有効にします。サーバーが固定された鍵/証明書を提示しない場合、TLS ハンドシェイクが拒否され、信頼された CA が侵害されていても中間者攻撃を防げます。デフォルトは nil（無効）。以下のコンストラクタで作成します。

コンストラクタ	説明
`NewSPKIHashPinner(hashes ...string) (CertificatePinner, error)`	1 つ以上の 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] レベルの警告を出力します（警告の種類ごとにプロセス単位で最大 1 回まで出力）。デフォルトの出力先は os.Stderr です。io.Discard を渡すことで警告を完全に抑制でき、テスト時や安全性が確認された内部シナリオでのサイレント実行に便利です。

// テストでセキュリティ警告を抑制
httpc.SetSecurityWarnOutput(io.Discard)
cfg := httpc.TestingConfig()

影響範囲

この設定はプロセスレベルのグローバル状態であり、以降に作成されるすべてのクライアントに影響します。TestingConfig と InsecureSkipVerify の 2 種類の警告はそれぞれ独立してカウントされます（互いのトリガーに影響しません）が、同じ出力 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`	Cookie に Secure 属性の設定を要求
RequireHttpOnly	`bool`	Cookie に HttpOnly 属性の設定を要求
RequireSameSite	`string`	要求する SameSite 値（例：`"Strict"`、`"Lax"`）。空文字列はチェックなし
AllowSameSiteNone	`bool`	SameSite=None を許可するかどうか
RequireSecureForSameSiteNone	`bool`	SameSite=None の場合に Secure 属性を要求（デフォルト `true`）

DefaultCookieSecurityConfig

func DefaultCookieSecurityConfig() *CookieSecurityConfig

デフォルトの Cookie セキュリティ設定。Secure/HttpOnly/SameSite 属性は要求しませんが、SameSite=None の Cookie には Secure の設定を強制します。

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 ​

設定