Documentation
¶
Overview ¶
Package discovery provides local network mDNS / DNS-SD service advertising and discovery capabilities for CLIProxyAPI (CPA).
Index ¶
- Constants
- Variables
- func BuildTXTRecords(opts TXTOptions) []string
- func FilterInterfaces(include, exclude []string) ([]net.Interface, error)
- func FormatInstanceName(customName, instanceID string) string
- func GetOrGenerateInstanceID(stateDir string) string
- func ParseTXTRecords(txt []string) map[string]string
- func ResetCachedInstanceID()
- func ResolveDiscoveryStateDir() string
- type Advertiser
- type Browser
- type DiscoveredService
- type ServiceSpec
- type TXTOptions
- type ZeroconfAdvertiser
- type ZeroconfBrowser
- func (b *ZeroconfBrowser) Browse(ctx context.Context, serviceType, domain string) ([]DiscoveredService, error)
- func (b *ZeroconfBrowser) BrowseWithFallback(ctx context.Context) ([]DiscoveredService, error)
- func (b *ZeroconfBrowser) BrowseWithFallbackServiceType(ctx context.Context, serviceType string) ([]DiscoveredService, error)
Constants ¶
const ( // DefaultServiceType is the proposed common service type for AI Gateways. DefaultServiceType = "_ai-gateway._tcp" // DefaultDomain is the link-local domain used by mDNS. DefaultDomain = "local." // SubtypeChatCompletions identifies the Chat Completions API protocol. SubtypeChatCompletions = "_chat-completions" // SubtypeResponses identifies the Responses API protocol. SubtypeResponses = "_responses" // SubtypeMessages identifies the Anthropic Messages API protocol. SubtypeMessages = "_messages" // SubtypeGenerateContent identifies the Gemini GenerateContent API protocol. SubtypeGenerateContent = "_generate-content" // SubtypeInteractions identifies the Interactions API protocol. SubtypeInteractions = "_interactions" // ProductCPA is the product identifier for CLIProxyAPI. ProductCPA = "cliproxyapi" )
const (
// DefaultInstancePrefix is the prefix used for default instance names.
DefaultInstancePrefix = "CPA-"
)
Variables ¶
var IgnoredInterfacePrefixes = []string{
"docker",
"veth",
"utun",
"tailscale",
"wg",
"tun",
"tap",
"br-",
"cni",
"flannel",
"virbr",
"vmnet",
"vboxnet",
"awdl",
"llw",
}
IgnoredInterfacePrefixes defines interface prefixes to exclude by default (virtual/container/VPN/P2P).
Functions ¶
func BuildTXTRecords ¶
func BuildTXTRecords(opts TXTOptions) []string
BuildTXTRecords constructs key=value TXT records strictly within 400 bytes total and 255 bytes per record (RFC 6763 §6.3), prioritizing essential routing metadata.
func FilterInterfaces ¶
FilterInterfaces selects qualified physical multicast-capable LAN interfaces according to Strategy C. If include is non-empty, only matching interface names are accepted. If exclude is non-empty, matching interface names are dropped.
func FormatInstanceName ¶
FormatInstanceName returns a DNS-SD instance name that always includes the persistent short ID, so LAN advertisements stay unique without a startup browse. An empty custom name becomes CPA-<ShortID>; a custom name becomes <name>-<ShortID>.
func GetOrGenerateInstanceID ¶
GetOrGenerateInstanceID retrieves the persistent instance ID from stateDir, or generates a new 4-character hex ID (e.g. "8F3B") and persists it atomically. Thread-safe, cached per stateDir, and protected against race conditions.
func ParseTXTRecords ¶
ParseTXTRecords parses a slice of "key=value" strings into a key-value map.
func ResetCachedInstanceID ¶
func ResetCachedInstanceID()
ResetCachedInstanceID resets in-memory cached IDs for test isolation.
func ResolveDiscoveryStateDir ¶
func ResolveDiscoveryStateDir() string
ResolveDiscoveryStateDir returns an absolute state directory for discovery metadata, avoiding writing relative paths into the current working directory.
Types ¶
type Advertiser ¶
type Advertiser interface {
Start(ctx context.Context, spec ServiceSpec) error
Stop() error
}
Advertiser defines the server-side mDNS advertisement lifecycle.
type Browser ¶
type Browser interface {
Browse(ctx context.Context, serviceType, domain string) ([]DiscoveredService, error)
BrowseWithFallback(ctx context.Context) ([]DiscoveredService, error)
BrowseWithFallbackServiceType(ctx context.Context, serviceType string) ([]DiscoveredService, error)
}
Browser defines the client-side mDNS browsing interface.
type DiscoveredService ¶
type DiscoveredService struct {
InstanceName string `json:"instance_name"`
ServiceType string `json:"service_type"`
Domain string `json:"domain"`
Host string `json:"host"`
Port int `json:"port"`
IPv4 []net.IP `json:"ipv4"`
IPv6 []net.IP `json:"ipv6"`
Protocols []string `json:"protocols,omitempty"`
Features []string `json:"features,omitempty"`
Product string `json:"product,omitempty"`
AuthRequired bool `json:"auth_required"`
AuthMethods []string `json:"auth_methods,omitempty"`
Endpoints map[string]string `json:"endpoints,omitempty"`
NodeRole string `json:"node_role,omitempty"`
Version string `json:"version,omitempty"`
RawTXT map[string]string `json:"raw_txt,omitempty"`
}
DiscoveredService describes a discovered AI gateway service on the LAN.
type ServiceSpec ¶
type ServiceSpec struct {
InstanceName string
ServiceType string
Domain string
Port int
Subtypes []string
TextRecords []string
Interfaces []net.Interface
AdvertisedIPs []string
}
ServiceSpec describes a service to be advertised on the local network.
func BuildServiceSpec ¶
BuildServiceSpec creates a ServiceSpec from configuration, port, and TLS setting.
type TXTOptions ¶
type TXTOptions struct {
Version string
Product string
Protocols []string
Features []string
APIPathOpenAI string
APIPathAnthropic string
APIPathGemini string
TLS bool
AuthRequired bool
AuthMethods []string
InstanceID string
NodeRole string
AdvertiseManagement bool
}
TXTOptions contains input fields for generating safe DNS-SD TXT records.
func DefaultTXTOptions ¶
func DefaultTXTOptions() TXTOptions
DefaultTXTOptions provides safe defaults for CPA TXT records.
type ZeroconfAdvertiser ¶
type ZeroconfAdvertiser struct {
// contains filtered or unexported fields
}
ZeroconfAdvertiser wraps libp2p/zeroconf/v2 Server with defensive lifecycle management.
func NewZeroconfAdvertiser ¶
func NewZeroconfAdvertiser() *ZeroconfAdvertiser
NewZeroconfAdvertiser returns a new ZeroconfAdvertiser.
func (*ZeroconfAdvertiser) Start ¶
func (a *ZeroconfAdvertiser) Start(ctx context.Context, spec ServiceSpec) (err error)
Start registers and starts mDNS advertisement for the primary service type and any configured API protocol subtypes.
func (*ZeroconfAdvertiser) Stop ¶
func (a *ZeroconfAdvertiser) Stop() error
Stop shuts down the mDNS advertisement server and sends goodbye packets.
type ZeroconfBrowser ¶
type ZeroconfBrowser struct {
// contains filtered or unexported fields
}
ZeroconfBrowser provides DNS-SD browsing with fallback support.
func NewZeroconfBrowser ¶
func NewZeroconfBrowser(ifaces ...net.Interface) *ZeroconfBrowser
NewZeroconfBrowser creates a new ZeroconfBrowser.
func (*ZeroconfBrowser) Browse ¶
func (b *ZeroconfBrowser) Browse(ctx context.Context, serviceType, domain string) ([]DiscoveredService, error)
Browse performs a standard mDNS browse query for the given service type.
func (*ZeroconfBrowser) BrowseWithFallback ¶
func (b *ZeroconfBrowser) BrowseWithFallback(ctx context.Context) ([]DiscoveredService, error)
BrowseWithFallback discovers all AI gateways on the LAN (_ai-gateway._tcp) and prioritizes CPA instances.
func (*ZeroconfBrowser) BrowseWithFallbackServiceType ¶
func (b *ZeroconfBrowser) BrowseWithFallbackServiceType(ctx context.Context, serviceType string) ([]DiscoveredService, error)
BrowseWithFallbackServiceType discovers services of the requested type and prioritizes CPA instances.