260718-go-pkg-clientip

README

clientip

clientip 从 net/http 请求中安全提取客户端 IP。只有 TCP 对端命中显式配置的可信代理集合时，才会读取启用的 Forwarded、X-Forwarded-For 或 X-Real-IP。

包不负责 IP 策略、HTTP middleware、拒绝响应或 context 注入；调用方负责将提取结果组合到自己的访问控制流程。

extractor, err := clientip.New(clientip.Config{
	TrustedProxies: []string{"172.18.0.0/16"},
	Headers: []clientip.Header{
		clientip.HeaderForwarded,
		clientip.HeaderXForwardedFor,
	},
})
if err != nil {
	return err
}

info, err := extractor.Extract(request)
if err != nil {
	return err
}
// info.Addr is the selected client address; info.Peer, Header and Chain are
// available for audit and diagnostics.

转发链从右向左剥离可信代理。格式错误、重复 X-Real-IP、unknown、obfuscated node、超过 Header 大小或代理跳数上限的请求都会 fail closed。零值 Config 只接受 TCP 对端，不读取转发头。

Config 保留 JSON 与 desc 标签，方便调用方绑定配置和命令行 flag。默认限制为 8 KiB Header 和 16 个代理跳。

go test ./...
go test -race ./...
go vet ./...