zeroconf

package module
v3.0.0-...-bf75283 Latest Latest
Warning

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

 Go to latest Published: Apr 10, 2026 License: MIT Imports: 17 Imported by: 0

README

ZeroConf: Service Discovery with mDNS

ZeroConf is a pure Golang library that employs Multicast DNS-SD for

  • browsing and resolving services in your network
  • registering own services

in the local network.

It basically implements aspects of the standards RFC 6762 (mDNS) and RFC 6763 (DNS-SD). Though it does not support all requirements yet, the aim is to provide a compliant solution in the long-term with the community.

By now, it should be compatible to Avahi (tested) and Apple's Bonjour (untested). Target environments: private LAN/Wifi, small or isolated networks.

GoDoc Go Report Card Tests

Install

Nothing is as easy as that:

$ go get -u github.com/enbility/zeroconf/v3

Browse for services in your local network

entries := make(chan *zeroconf.ServiceEntry)
removed := make(chan *zeroconf.ServiceEntry)

go func() {
    for {
        select {
        case entry := <-entries:
            log.Println("Found:", entry)
        case entry := <-removed:
            log.Println("Removed:", entry)
        }
    }
}()

ctx, cancel := context.WithTimeout(context.Background(), time.Second*15)
defer cancel()
// Discover all services on the network (e.g. _workstation._tcp)
err := zeroconf.Browse(ctx, "_workstation._tcp", "local.", entries, removed)
if err != nil {
    log.Fatalln("Failed to browse:", err.Error())
}

<-ctx.Done()

A subtype may added to service name to narrow the set of results. E.g. to browse _workstation._tcp with subtype _windows, use_workstation._tcp,_windows.

See https://github.com/enbility/zeroconf/blob/master/examples/resolv/client.go.

Lookup a specific service instance

entries := make(chan *zeroconf.ServiceEntry)

go func() {
    for entry := range entries {
        log.Println("Found:", entry)
    }
}()

ctx, cancel := context.WithTimeout(context.Background(), time.Second*15)
defer cancel()
// Lookup a specific service instance by name
err := zeroconf.Lookup(ctx, "MyService", "_workstation._tcp", "local.", entries)
if err != nil {
    log.Fatalln("Failed to lookup:", err.Error())
}

<-ctx.Done()

Register a service

server, err := zeroconf.Register("GoZeroconf", "_workstation._tcp", "local.", 42424, []string{"txtv=0", "lo=1", "la=2"}, nil)
if err != nil {
    panic(err)
}
defer server.Shutdown()

// Clean exit.
sig := make(chan os.Signal, 1)
signal.Notify(sig, os.Interrupt, syscall.SIGTERM)
select {
case <-sig:
    // Exit by user
case <-time.After(time.Second * 120):
    // Exit by timeout
}

log.Println("Shutting down.")

Multiple subtypes may be added to service name, separated by commas. E.g _workstation._tcp,_windows has subtype _windows.

See https://github.com/enbility/zeroconf/blob/master/examples/register/server.go.

Testing Support (v3)

Version 3 introduces interface-based abstractions for improved testability. You can inject mock connections for unit testing without requiring real network access:

// Create mock connections using the provided interfaces
mockFactory := &MyMockConnectionFactory{}

// Client with mock connections
client, err := zeroconf.NewClient(zeroconf.WithClientConnFactory(mockFactory))

// Server with mock connections
server, err := zeroconf.RegisterProxy(
    "MyService", "_http._tcp", "local.", 8080,
    "myhost.local.", []string{"192.168.1.100"},
    []string{"txtvers=1"},
    nil, // interfaces
    zeroconf.WithServerConnFactory(mockFactory),
)

See the api/ package for interface definitions and mocks/ for mockery-generated mocks.

Features and ToDo's

This list gives a quick impression about the state of this library. See what needs to be done and submit a pull request :)

  • Browse / Lookup / Register services
  • Multiple IPv6 / IPv4 addresses support
  • Send multiple probes (exp. back-off) if no service answers (*)
  • Timestamp entries for TTL checks
  • Service removal notifications via removed channel
  • Interface-based abstractions for testability (v3)
  • Compare new multicasts with already received services

Notes:

(*) The denoted features might not be perfectly standards compliant, but shouldn't cause any problems. Some tests showed improvements in overall robustness and performance with the features enabled.

Credits

Great thanks to hashicorp and to oleksandr and all contributing authors for the code this projects bases upon. Large parts of the code are still the same.

However, there are several reasons why I decided to create a fork of the original project: The previous project seems to be unmaintained. There are several useful pull requests waiting. I merged most of them in this project. Still, the implementation has some bugs and lacks some other features that make it quite unreliable in real LAN environments when running continously. Last but not least, the aim for this project is to build a solution that targets standard conformance in the long term with the support of the community. Though, resiliency should remain a top goal.

Documentation

Overview

Package zeroconf is a pure Golang library that employs Multicast DNS-SD for browsing and resolving services in your network and registering own services in the local network.

It basically implements aspects of the standards RFC 6762 (mDNS) and RFC 6763 (DNS-SD). Though it does not support all requirements yet, the aim is to provide a complient solution in the long-term with the community.

By now, it should be compatible to [Avahi](http://avahi.org/) (tested) and Apple's Bonjour (untested). Should work in the most office, home and private environments.

Index

Constants

View Source 
const (
	WSAENETDOWN      syscall.Errno = 10050 // Network is down
	WSAEADDRNOTAVAIL syscall.Errno = 10049 // Cannot assign requested address
	WSAEINVAL        syscall.Errno = 10022 // Invalid argument
)

Windows socket error codes (not in standard syscall package). These constants are safe to define cross-platform because errors.Is() performs type comparison - on non-Windows systems, these simply won't match.

Variables

This section is empty.

Functions

func Browse 

func Browse(ctx context.Context, service, domain string, entries, removed chan<- *ServiceEntry, opts ...ClientOption) error

Browse for all services of a given type in a given domain. Received entries are sent on the entries channel. It blocks until the context is canceled (or an error occurs).

func Lookup 

func Lookup(ctx context.Context, instance, service, domain string, entries chan<- *ServiceEntry, opts ...ClientOption) error

Lookup a specific service by its name and type in a given domain. Received entries are sent on the entries channel. It blocks until the context is canceled (or an error occurs).

func NewConnectionFactory 

func NewConnectionFactory() api.ConnectionFactory

NewConnectionFactory creates a new default connection factory.

func NewInterfaceProvider 

func NewInterfaceProvider() api.InterfaceProvider

NewInterfaceProvider creates a new default interface provider.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client structure encapsulates both IPv4/IPv6 UDP connections.

func NewClient 

func NewClient(opts ...ClientOption) (*Client, error)

NewClient creates a new mDNS client with the given options. This is the low-level constructor. For most use cases, prefer Browse() or Lookup().

type ClientOption 

type ClientOption func(*clientOpts)

ClientOption fills the option struct to configure intefaces, etc.

func SelectIPTraffic 

func SelectIPTraffic(t IPType) ClientOption

SelectIPTraffic selects the type of IP packets (IPv4, IPv6, or both) this instance listens for. This does not guarantee that only mDNS entries of this sepcific type passes. E.g. typical mDNS packets distributed via IPv4, may contain both DNS A and AAAA entries.

func SelectIfaces 

func SelectIfaces(ifaces []net.Interface) ClientOption

SelectIfaces selects the interfaces to query for mDNS records

func WithClientConnFactory 

func WithClientConnFactory(factory api.ConnectionFactory) ClientOption

WithClientConnFactory sets a custom connection factory for the client. This is primarily useful for testing with mock connections.

func WithClientInterfaceProvider 

func WithClientInterfaceProvider(provider api.InterfaceProvider) ClientOption

WithClientInterfaceProvider sets a custom interface provider for the client. This is primarily useful for testing with mock interface lists.

type IPType 

type IPType uint8

IPType specifies the IP traffic the client listens for. This does not guarantee that only mDNS entries of this sepcific type passes. E.g. typical mDNS packets distributed via IPv4, often contain both DNS A and AAAA entries. 

const (
	IPv4        IPType = 0x01
	IPv6        IPType = 0x02
	IPv4AndIPv6        = IPv4 | IPv6 // default option
)

Options for IPType.

type InterfaceManager 

type InterfaceManager struct {
	// contains filtered or unexported fields
}

InterfaceManager tracks active and failed interfaces for one IP version. Thread-safe. Create separate instances for IPv4 and IPv6.

Concurrency model:

  • ActiveIndices() returns a snapshot; iteration is lock-free
  • MarkFailed() is idempotent; safe to call even if already removed
  • Sync() runs periodically in background; updates are atomic

func NewInterfaceManager 

func NewInterfaceManager(initial []net.Interface, requested []string) *InterfaceManager

NewInterfaceManager creates a manager with initial interfaces. If requested is nil, dynamic mode is used (accepts new interfaces). If requested is non-nil, only those interface names are ever used.

func (*InterfaceManager) Activate 

func (m *InterfaceManager) Activate(iface net.Interface)

Activate adds an interface to the active set. Called after successful JoinGroup. Clears failure history. Handles the case where interface reconnected with a different index.

func (*InterfaceManager) ActiveIndices 

func (m *InterfaceManager) ActiveIndices() []int

ActiveIndices returns current active interface indices. Call this in send loops - never cache the result.

The returned slice is a snapshot. The caller iterates over it while the sync goroutine may modify the active map. This is safe because:

  • Sends to removed indices fail fast and call MarkFailed (idempotent)
  • New indices are picked up on the next ActiveIndices() call

func (*InterfaceManager) GetActiveInterfaces 

func (m *InterfaceManager) GetActiveInterfaces() []net.Interface

GetActiveInterfaces returns full interface objects for all active indices. Used for IP address collection (avoids race between ActiveIndices and lookup).

func (*InterfaceManager) MarkFailed 

func (m *InterfaceManager) MarkFailed(ifIndex int, err error) bool

MarkFailed removes an interface from active set if error indicates it's gone. Uses adaptive backoff: first failure = 1s, second = 5s, third+ = 30s.

This method is IDEMPOTENT: safe to call even if the interface was already removed by a concurrent Sync() call.

Returns true if the error indicated the interface is gone.

func (*InterfaceManager) SetBackoff 

func (m *InterfaceManager) SetBackoff(ifName string)

SetBackoff marks an interface as temporarily failed (e.g., JoinGroup failed). Increments the failure counter for adaptive backoff.

func (*InterfaceManager) Sync 

func (m *InterfaceManager) Sync(current []net.Interface) []net.Interface

Sync updates state based on currently available interfaces. Returns interfaces that were recovered and need JoinGroup calls.

Handles:

  • Disappeared interfaces (removes from active, sets backoff)
  • Index changes (interface reconnects with different index)
  • New interfaces in dynamic mode
  • Recovery after backoff expires

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server structure encapsulates both IPv4/IPv6 UDP connections

func Register 

func Register(instance, service, domain string, port int, text []string, ifaces []net.Interface, opts ...ServerOption) (*Server, error)

Register a service by given arguments. This call will take the system's hostname and lookup IP by that hostname.

func RegisterProxy 

func RegisterProxy(instance, service, domain string, port int, host string, ips []string, text []string, ifaces []net.Interface, opts ...ServerOption) (*Server, error)

RegisterProxy registers a service proxy. This call will skip the hostname/IP lookup and will use the provided values.

func (*Server) SetText 

func (s *Server) SetText(text []string)

SetText updates and announces the TXT records

func (*Server) Shutdown 

func (s *Server) Shutdown()

Shutdown closes all udp connections and unregisters the service

type ServerOption 

type ServerOption func(*serverOpts)

ServerOption fills the option struct.

func TTL 

func TTL(ttl uint32) ServerOption

TTL sets the TTL for DNS replies.

func WithServerConnFactory 

func WithServerConnFactory(factory api.ConnectionFactory) ServerOption

WithServerConnFactory sets a custom connection factory for the server. This is primarily useful for testing with mock connections.

func WithServerInterfaceProvider 

func WithServerInterfaceProvider(provider api.InterfaceProvider) ServerOption

WithServerInterfaceProvider sets a custom interface provider for the server. This is primarily useful for testing with mock interface lists.

type ServiceEntry 

type ServiceEntry struct {
	ServiceRecord
	HostName string    `json:"hostname"` // Host machine DNS name
	Port     int       `json:"port"`     // Service Port
	Text     []string  `json:"text"`     // Service info served as a TXT record
	Expiry   time.Time `json:"expiry"`   // Expiry of the service entry, will be converted to a TTL value
	AddrIPv4 []net.IP  `json:"-"`        // Host machine IPv4 address
	AddrIPv6 []net.IP  `json:"-"`        // Host machine IPv6 address
}

ServiceEntry represents a browse/lookup result for client API. It is also used to configure service registration (server API), which is used to answer multicast queries.

type ServiceRecord 

type ServiceRecord struct {
	Instance string   `json:"name"`     // Instance name (e.g. "My web page")
	Service  string   `json:"type"`     // Service name (e.g. _http._tcp.)
	Subtypes []string `json:"subtypes"` // Service subtypes
	Domain   string   `json:"domain"`   // If blank, assumes "local"
	// contains filtered or unexported fields
}

ServiceRecord contains the basic description of a service, which contains instance name, service type & domain

func (*ServiceRecord) ServiceInstanceName 

func (s *ServiceRecord) ServiceInstanceName() string

ServiceInstanceName returns a complete service instance name (e.g. MyDemo\ Service._foobar._tcp.local.), which is composed from service instance name, service name and a domain.

func (*ServiceRecord) ServiceName 

func (s *ServiceRecord) ServiceName() string

ServiceName returns a complete service name (e.g. _foobar._tcp.local.), which is composed of a service name (also referred as service type) and a domain.

func (*ServiceRecord) ServiceTypeName 

func (s *ServiceRecord) ServiceTypeName() string

ServiceTypeName returns the complete identifier for a DNS-SD query.

Source Files

View all Source files

Directories

Path Synopsis
Package api defines the core interfaces for the zeroconf library.
 Package api defines the core interfaces for the zeroconf library.
examples
proxyservice command
register command
resolv command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.