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, error)
- 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 ProtocolFromSubtype(subtype 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" // SubtypeCompletions identifies the legacy text Completions API protocol. SubtypeCompletions = "_completions" // SubtypeResponsesWS identifies the persistent WebSocket Responses stream. SubtypeResponsesWS = "_responses-ws" // SubtypeRealtime identifies realtime WebSocket / WebRTC sessions. SubtypeRealtime = "_realtime" // SubtypeImages identifies image generation and editing. SubtypeImages = "_images" // SubtypeVideos identifies video generation, editing, and retrieval. SubtypeVideos = "_videos" // SubtypeAudio identifies speech synthesis. SubtypeAudio = "_audio" // SubtypeCountTokens identifies standalone token counting. SubtypeCountTokens = "_count-tokens" // SubtypeSearch identifies agentic web/code search. SubtypeSearch = "_search" // 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, error)
BuildTXTRecords constructs the draft-su-ai-gateway-discovery-00 TXT record. Required attributes are always emitted first; optional attributes are skipped when they would exceed the 255-byte string or 400-byte record budget.
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 "key=value" strings into a map with lowercase keys. Per RFC 6763 §6.4, only the first occurrence of a key is used.
func ProtocolFromSubtype ¶ added in v8.0.44
ProtocolFromSubtype converts a DNS-SD subtype label (e.g. "_responses") to its protocol token.
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"`
// InterfaceIndex separates identical service names observed on different links.
InterfaceIndex int `json:"interface_index,omitempty"`
// IPv6Zones maps link-local address strings to their receiving interface names.
IPv6Zones map[string]string `json:"ipv6_zones,omitempty"`
// Path is the gateway mount path from the TXT path key; empty for legacy advertisers.
Path string `json:"path,omitempty"`
TLS bool `json:"tls"`
Protocols []string `json:"protocols,omitempty"`
Product string `json:"product,omitempty"`
InstanceID string `json:"instance_id,omitempty"`
AuthRequired bool `json:"auth_required"`
AuthMethods []string `json:"auth_methods,omitempty"`
// Endpoints maps each advertised protocol token to its route on the gateway origin.
Endpoints map[string]string `json:"endpoints,omitempty"`
NodeRole string `json:"node_role,omitempty"`
// Version is the discovery TXT schema version (txtvers, or legacy version).
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 {
Path string
Product string
Protocols []string
TLS bool
AuthRequired bool
AuthMethods []string
InstanceID string
NodeRole string
}
TXTOptions contains input fields for generating 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.