discovery

package
v8.0.49 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 24 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"
	// 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"
)
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, 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

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 "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

func ProtocolFromSubtype(subtype string) string

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

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 {
	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.

Jump to

Keyboard shortcuts

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