protocol

type CloudflareTrace struct {
	ProviderName string                  // name of the detection protocol
	URL          map[ipnet.Family]string // trace endpoint URL per family
}

type DNSOverHTTPS struct {
	ProviderName string // name of the protocol
	Param        map[ipnet.Family]DNSOverHTTPSParam
	// Rejecter is an optional hook called after the IP is parsed from the DNS
	// response. If it rejects the IP, the result is treated as unavailable.
	// This allows provider-specific validation (e.g., rejecting Cloudflare
	// egress IPs) without breaking the generic protocol type.
	Rejecter ipnet.RawIPRejecter
}

type DNSOverHTTPSParam = struct {
	URL   string           // the DoH server
	Name  string           // domain name to query
	Class dnsmessage.Class // DNS class to query
}

type DetectionResult struct {
	// Available reports whether the raw data is known for this run.
	// When it is false, the reconciliation intent is "abort" (raw data
	// unavailable); the current algorithm preserves existing managed content.
	// See docs/designs/features/reconciliation-algorithm.markdown for intent handling.
	//
	// When it is true, RawEntries stores the current deterministic raw-data carrier.
	// Each entry is an IP address with prefix length (host bits are preserved).
	// An empty list is the explicit-empty intent ("clear").
	Available  bool
	RawEntries []ipnet.RawEntry
}

type File struct {
	// ProviderName is the name of the detection protocol.
	ProviderName string

	// Path is the absolute path to the file containing IP addresses.
	Path string
}

type HTTP struct {
	ProviderName            string                  // name of the protocol
	URL                     map[ipnet.Family]string // URL of the page for detection
	ForcedTransportIPFamily *ipnet.Family
}

type LocalAuto struct {
	// Name of the detection protocol.
	ProviderName string

	// The target of the hypothetical UDP packet to be sent.
	RemoteUDPAddr string
}

type LocalWithInterface struct {
	// Name of the detection protocol.
	ProviderName string

	// The name of the network interface
	InterfaceName string
}

type Static struct {
	// Name of the detection protocol.
	ProviderName string

	// The raw IP addresses with prefix lengths. Config-side constructors
	// canonicalize these for stable naming. Runtime normalization still runs
	// in GetRawData because the provider contract is enforced per requested
	// family at the point the raw data is consumed.
	RawEntries []ipnet.RawEntry
}

type Unavailable struct {
	// Name of the detection protocol.
	ProviderName string
}