discovery

package
v8.0.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 8, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package discovery provides local network mDNS / DNS-SD service advertising and discovery capabilities for CLIProxyAPI (CPA).

Index

Constants

View Source
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"
)
View Source
const (
	// DefaultInstancePrefix is the prefix used for default instance names.
	DefaultInstancePrefix = "CPA-"
)

Variables

View Source
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

func FilterInterfaces(include, exclude []string) ([]net.Interface, error)

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

func FormatInstanceName(customName, instanceID string) string

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

func GetOrGenerateInstanceID(stateDir string) string

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

func ParseTXTRecords(txt []string) map[string]string

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

func BuildServiceSpec(cfg *config.Config, port int, tlsEnabled bool) (ServiceSpec, error)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL