Ask Bjørn Hansen
694f8ba1d3
- Add package-level documentation with usage examples and architecture details - Document all public types, functions, and methods following godoc conventions - Remove unused logger.Error type and NewError function - Apply consistent documentation style across all packages Packages updated: - apitls: TLS certificate management with automatic renewal - config: Environment-based configuration system - config/depenv: Deployment environment handling - ekko: Enhanced Echo web framework wrapper - kafka: Kafka client wrapper with TLS support - logger: Structured logging with OpenTelemetry integration - tracing: OpenTelemetry distributed tracing setup - types: Shared data structures for NTP Pool project - xff/fastlyxff: Fastly CDN IP range management All tests pass after documentation changes.
103 lines
3.4 KiB
Go
103 lines
3.4 KiB
Go
// Package fastlyxff provides Fastly CDN IP range management for trusted proxy handling.
|
|
//
|
|
// This package parses Fastly's public IP ranges JSON file and generates Echo framework
|
|
// trust options for proper client IP extraction from X-Forwarded-For headers.
|
|
// It's designed specifically for services deployed behind Fastly's CDN that need
|
|
// to identify real client IPs for logging, rate limiting, and security purposes.
|
|
//
|
|
// Fastly publishes their edge server IP ranges in a JSON format that this package
|
|
// consumes to automatically configure trusted proxy ranges. This ensures that
|
|
// X-Forwarded-For headers are only trusted when they originate from legitimate
|
|
// Fastly edge servers.
|
|
//
|
|
// Key features:
|
|
// - Automatic parsing of Fastly's IP ranges JSON format
|
|
// - Support for both IPv4 and IPv6 address ranges
|
|
// - Echo framework integration via TrustOption generation
|
|
// - CIDR notation parsing and validation
|
|
//
|
|
// The JSON file typically contains IP ranges in this format:
|
|
//
|
|
// {
|
|
// "addresses": ["23.235.32.0/20", "43.249.72.0/22", ...],
|
|
// "ipv6_addresses": ["2a04:4e40::/32", "2a04:4e42::/32", ...]
|
|
// }
|
|
package fastlyxff
|
|
|
|
import (
|
|
"encoding/json"
|
|
"net"
|
|
"net/netip"
|
|
"os"
|
|
|
|
"github.com/labstack/echo/v4"
|
|
)
|
|
|
|
// FastlyXFF represents Fastly's published IP ranges for their CDN edge servers.
|
|
// This structure matches the JSON format provided by Fastly for their public IP ranges.
|
|
// It contains separate lists for IPv4 and IPv6 CIDR ranges.
|
|
type FastlyXFF struct {
|
|
IPv4 []string `json:"addresses"` // IPv4 CIDR ranges (e.g., "23.235.32.0/20")
|
|
IPv6 []string `json:"ipv6_addresses"` // IPv6 CIDR ranges (e.g., "2a04:4e40::/32")
|
|
}
|
|
|
|
// TrustedNets holds parsed network prefixes for efficient IP range checking.
|
|
// This type is currently unused but reserved for future optimizations
|
|
// where frequent IP range lookups might benefit from pre-parsed prefixes.
|
|
type TrustedNets struct {
|
|
prefixes []netip.Prefix // Parsed network prefixes for efficient lookups
|
|
}
|
|
|
|
// New loads and parses Fastly IP ranges from a JSON file.
|
|
// The file should contain Fastly's published IP ranges in their standard JSON format.
|
|
//
|
|
// Parameters:
|
|
// - fileName: Path to the Fastly IP ranges JSON file
|
|
//
|
|
// Returns the parsed FastlyXFF structure or an error if the file cannot be
|
|
// read or the JSON format is invalid.
|
|
func New(fileName string) (*FastlyXFF, error) {
|
|
b, err := os.ReadFile(fileName)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
|
|
d := FastlyXFF{}
|
|
|
|
err = json.Unmarshal(b, &d)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
|
|
return &d, nil
|
|
}
|
|
|
|
// EchoTrustOption converts Fastly IP ranges into Echo framework trust options.
|
|
// This method generates trust configurations that tell Echo to accept X-Forwarded-For
|
|
// headers only from Fastly's edge servers, ensuring accurate client IP extraction.
|
|
//
|
|
// The generated trust options should be used with Echo's IP extractor:
|
|
//
|
|
// options, err := fastlyRanges.EchoTrustOption()
|
|
// if err != nil {
|
|
// return err
|
|
// }
|
|
// e.IPExtractor = echo.ExtractIPFromXFFHeader(options...)
|
|
//
|
|
// Returns a slice of Echo trust options or an error if any CIDR range cannot be parsed.
|
|
func (xff *FastlyXFF) EchoTrustOption() ([]echo.TrustOption, error) {
|
|
ranges := []echo.TrustOption{}
|
|
|
|
for _, s := range append(xff.IPv4, xff.IPv6...) {
|
|
_, cidr, err := net.ParseCIDR(s)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
|
|
trust := echo.TrustIPRange(cidr)
|
|
ranges = append(ranges, trust)
|
|
}
|
|
|
|
return ranges, nil
|
|
}
|