260718-go-pkg-ipallow

README

ipallow

ipallow 是协议无关的 IP 来源允许列表匹配器。它支持精确 IP、CIDR 和通过正向 A/AAAA 解析的域名规则。

包只负责判断地址是否属于策略，不负责 HTTP、用户认证、响应协议或是否启用限制。规则编译为不可变 Policy，Matcher 负责共享有界 DNS 缓存。

Rule 只包含 ID 和 Value；Compile 会自动识别并规范化 IP、CIDR 或域名。形似 IPv4 但不是合法地址的值会直接报错，不会降级为域名查询。

config := ipallow.DefaultConfig()
config.Enabled = true
config.Rules = []ipallow.Rule{
	{ID: "office", Value: "10.42.0.0/16"},
	{ID: "relay", Value: "relay.example.net"},
}

policy, err := ipallow.Compile(config.Rules)
if err != nil {
	return err
}
matcher, err := ipallow.NewMatcher(ctx, config.DNS)
if err != nil {
	return err
}
defer matcher.Close()

result, err := matcher.Match(ctx, policy, source)
if err != nil || !result.Allowed {
	// The caller decides the fail-closed response and audit protocol.
}

域名查询按成功、失败和 stale TTL 缓存；同一域名并发查询会合并，缓存使用 LRU 限制在 MaxHosts 内。默认 StaleTTL 为零，严格 fail-closed。规则变更时重新 Compile，同一个 Matcher 可以复用。

Config、DNSConfig 和 Rule 保留 JSON 与 desc 标签，方便调用方直接绑定配置和命令行 flag；Enabled 只供调用方解释，库本身不会读取它。

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