bugfixes nov2025 pt4 (#7)

* Add mDNS resolution.
* Update the website and documentation

internal/config/config.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"fmt"
 	"os"
+	"strings"
 	"time"
 
 	"gopkg.in/yaml.v3"
@@ -31,6 +32,13 @@ type Config struct {
 	Contexts    []Context        `yaml:"contexts"`
 	HealthCheck *HealthCheckSpec `yaml:"healthCheck,omitempty"`
 	Reliability *ReliabilitySpec `yaml:"reliability,omitempty"`
+	MDNS        *MDNSSpec        `yaml:"mdns,omitempty"`
+}
+
+// MDNSSpec configures mDNS (multicast DNS) hostname publishing
+// When enabled, forwards with aliases can be accessed via <alias>.local hostnames
+type MDNSSpec struct {
+	Enabled bool `yaml:"enabled"` // Enable mDNS hostname publishing
 }
 
 // HealthCheckSpec configures health check behavior
@@ -133,6 +141,11 @@ func (c *Config) GetDialTimeout() time.Duration {
 	return parseDurationOrDefault(c.Reliability.DialTimeout, DefaultDialTimeout)
 }
 
+// IsMDNSEnabled returns whether mDNS hostname publishing is enabled
+func (c *Config) IsMDNSEnabled() bool {
+	return c.MDNS != nil && c.MDNS.Enabled
+}
+
 // Context represents a Kubernetes context with its namespaces
 type Context struct {
 	Name       string      `yaml:"name"`
@@ -199,6 +212,25 @@ func (f *Forward) GetNamespace() string {
 	return f.namespaceName
 }
 
+// GetMDNSAlias returns the alias to use for mDNS hostname registration.
+// If an explicit alias is set, it returns that.
+// Otherwise, it generates one from the resource name (e.g., "service/logto" -> "logto").
+func (f *Forward) GetMDNSAlias() string {
+	if f.Alias != "" {
+		return f.Alias
+	}
+
+	// Generate alias from resource name
+	// Format is "type/name" (e.g., "service/logto", "pod/my-app")
+	parts := strings.SplitN(f.Resource, "/", 2)
+	if len(parts) == 2 && parts[1] != "" {
+		return parts[1]
+	}
+
+	// Fallback: can't generate a valid alias (e.g., "pod" with selector)
+	return ""
+}
+
 // LoadConfig loads and parses the configuration file from the given path.
 func LoadConfig(path string) (*Config, error) {
 	// Validate file size before reading

internal/config/validator.go

@@ -61,6 +61,11 @@ func (v *Validator) ValidateConfig(cfg *Config) []ValidationError {
 	// Check for duplicate local ports
 	errs = append(errs, v.validateDuplicatePorts(cfg)...)
 
+	// Validate mDNS configuration
+	if cfg.IsMDNSEnabled() {
+		errs = append(errs, v.validateMDNS(cfg)...)
+	}
+
 	return errs
 }
 
@@ -270,3 +275,85 @@ func FormatValidationErrors(errs []ValidationError) string {
 
 	return sb.String()
 }
+
+// validateMDNS validates mDNS configuration when enabled.
+// It checks that aliases used for mDNS hostnames are valid and unique.
+// This includes both explicit aliases and auto-generated ones from resource names.
+func (v *Validator) validateMDNS(cfg *Config) []ValidationError {
+	var errs []ValidationError
+
+	aliasMap := make(map[string][]string) // alias -> list of forward IDs using it
+
+	for _, ctx := range cfg.Contexts {
+		for _, ns := range ctx.Namespaces {
+			for _, fwd := range ns.Forwards {
+				// Get the mDNS alias (explicit or generated from resource name)
+				mdnsAlias := fwd.GetMDNSAlias()
+				if mdnsAlias == "" {
+					// No alias available (e.g., "pod" with selector only)
+					continue
+				}
+
+				// Validate alias is a valid hostname (RFC 1123)
+				if !isValidHostname(mdnsAlias) {
+					errs = append(errs, ValidationError{
+						Field:   "alias",
+						Message: fmt.Sprintf("Forward %s has invalid mDNS hostname '%s' (must be a valid RFC 1123 hostname)", fwd.ID(), mdnsAlias),
+					})
+				}
+
+				aliasMap[mdnsAlias] = append(aliasMap[mdnsAlias], fwd.ID())
+			}
+		}
+	}
+
+	// Check for duplicate aliases (would cause mDNS conflicts)
+	for alias, forwards := range aliasMap {
+		if len(forwards) > 1 {
+			errs = append(errs, ValidationError{
+				Field:   "alias",
+				Message: fmt.Sprintf("Duplicate mDNS hostname '%s' used by multiple forwards (would cause conflict)", alias),
+				Context: map[string]string{
+					"alias":    alias,
+					"forwards": strings.Join(forwards, ", "),
+				},
+			})
+		}
+	}
+
+	return errs
+}
+
+// isValidHostname checks if a string is a valid RFC 1123 hostname.
+// Hostnames must start with alphanumeric, contain only alphanumeric and hyphens,
+// and be 1-63 characters long.
+func isValidHostname(name string) bool {
+	if len(name) == 0 || len(name) > 63 {
+		return false
+	}
+
+	// Must start with alphanumeric
+	if !isAlphanumeric(name[0]) {
+		return false
+	}
+
+	// Must end with alphanumeric
+	if !isAlphanumeric(name[len(name)-1]) {
+		return false
+	}
+
+	// Check all characters
+	for i := 0; i < len(name); i++ {
+		c := name[i]
+		if !isAlphanumeric(c) && c != '-' {
+			return false
+		}
+	}
+
+	return true
+}
+
+// isAlphanumeric returns true if the character is a letter or digit.
+func isAlphanumeric(c byte) bool {
+	return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9')
+}

internal/config/validator_test.go

@@ -701,3 +701,274 @@ func TestValidator_ValidateStructure(t *testing.T) {
 		})
 	}
 }
+
+func TestValidator_ValidateMDNS(t *testing.T) {
+	validator := NewValidator()
+
+	tests := []struct {
+		name          string
+		config        *Config
+		expectErrors  bool
+		errorContains []string
+	}{
+		{
+			name: "mDNS disabled - no validation",
+			config: &Config{
+				Contexts: []Context{
+					{
+						Name: "dev",
+						Namespaces: []Namespace{
+							{
+								Name: "default",
+								Forwards: []Forward{
+									{Resource: "pod/app", Port: 8080, LocalPort: 8080, Alias: "invalid_alias", contextName: "dev", namespaceName: "default"},
+								},
+							},
+						},
+					},
+				},
+			},
+			expectErrors: false,
+		},
+		{
+			name: "mDNS enabled - valid aliases",
+			config: &Config{
+				MDNS: &MDNSSpec{Enabled: true},
+				Contexts: []Context{
+					{
+						Name: "dev",
+						Namespaces: []Namespace{
+							{
+								Name: "default",
+								Forwards: []Forward{
+									{Resource: "pod/app1", Port: 8080, LocalPort: 8080, Alias: "my-app", contextName: "dev", namespaceName: "default"},
+									{Resource: "pod/app2", Port: 8081, LocalPort: 8081, Alias: "my-service", contextName: "dev", namespaceName: "default"},
+								},
+							},
+						},
+					},
+				},
+			},
+			expectErrors: false,
+		},
+		{
+			name: "mDNS enabled - no alias (allowed)",
+			config: &Config{
+				MDNS: &MDNSSpec{Enabled: true},
+				Contexts: []Context{
+					{
+						Name: "dev",
+						Namespaces: []Namespace{
+							{
+								Name: "default",
+								Forwards: []Forward{
+									{Resource: "pod/app", Port: 8080, LocalPort: 8080, contextName: "dev", namespaceName: "default"},
+								},
+							},
+						},
+					},
+				},
+			},
+			expectErrors: false,
+		},
+		{
+			name: "mDNS enabled - invalid alias with underscore",
+			config: &Config{
+				MDNS: &MDNSSpec{Enabled: true},
+				Contexts: []Context{
+					{
+						Name: "dev",
+						Namespaces: []Namespace{
+							{
+								Name: "default",
+								Forwards: []Forward{
+									{Resource: "pod/app", Port: 8080, LocalPort: 8080, Alias: "my_app", contextName: "dev", namespaceName: "default"},
+								},
+							},
+						},
+					},
+				},
+			},
+			expectErrors:  true,
+			errorContains: []string{"invalid mDNS hostname", "RFC 1123"},
+		},
+		{
+			name: "mDNS enabled - alias starts with hyphen",
+			config: &Config{
+				MDNS: &MDNSSpec{Enabled: true},
+				Contexts: []Context{
+					{
+						Name: "dev",
+						Namespaces: []Namespace{
+							{
+								Name: "default",
+								Forwards: []Forward{
+									{Resource: "pod/app", Port: 8080, LocalPort: 8080, Alias: "-myapp", contextName: "dev", namespaceName: "default"},
+								},
+							},
+						},
+					},
+				},
+			},
+			expectErrors:  true,
+			errorContains: []string{"invalid mDNS hostname"},
+		},
+		{
+			name: "mDNS enabled - alias ends with hyphen",
+			config: &Config{
+				MDNS: &MDNSSpec{Enabled: true},
+				Contexts: []Context{
+					{
+						Name: "dev",
+						Namespaces: []Namespace{
+							{
+								Name: "default",
+								Forwards: []Forward{
+									{Resource: "pod/app", Port: 8080, LocalPort: 8080, Alias: "myapp-", contextName: "dev", namespaceName: "default"},
+								},
+							},
+						},
+					},
+				},
+			},
+			expectErrors:  true,
+			errorContains: []string{"invalid mDNS hostname"},
+		},
+		{
+			name: "mDNS enabled - duplicate aliases",
+			config: &Config{
+				MDNS: &MDNSSpec{Enabled: true},
+				Contexts: []Context{
+					{
+						Name: "dev",
+						Namespaces: []Namespace{
+							{
+								Name: "default",
+								Forwards: []Forward{
+									{Resource: "pod/app1", Port: 8080, LocalPort: 8080, Alias: "myapp", contextName: "dev", namespaceName: "default"},
+									{Resource: "pod/app2", Port: 8081, LocalPort: 8081, Alias: "myapp", contextName: "dev", namespaceName: "default"},
+								},
+							},
+						},
+					},
+				},
+			},
+			expectErrors:  true,
+			errorContains: []string{"Duplicate mDNS hostname", "conflict"},
+		},
+		{
+			name: "mDNS enabled - duplicate aliases across contexts",
+			config: &Config{
+				MDNS: &MDNSSpec{Enabled: true},
+				Contexts: []Context{
+					{
+						Name: "cluster1",
+						Namespaces: []Namespace{
+							{
+								Name: "default",
+								Forwards: []Forward{
+									{Resource: "pod/app1", Port: 8080, LocalPort: 8080, Alias: "shared-name", contextName: "cluster1", namespaceName: "default"},
+								},
+							},
+						},
+					},
+					{
+						Name: "cluster2",
+						Namespaces: []Namespace{
+							{
+								Name: "default",
+								Forwards: []Forward{
+									{Resource: "pod/app2", Port: 8081, LocalPort: 8081, Alias: "shared-name", contextName: "cluster2", namespaceName: "default"},
+								},
+							},
+						},
+					},
+				},
+			},
+			expectErrors:  true,
+			errorContains: []string{"Duplicate mDNS hostname", "shared-name"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			errs := validator.ValidateConfig(tt.config)
+
+			if tt.expectErrors {
+				assert.NotEmpty(t, errs, "expected validation errors")
+
+				// Check that expected error messages are present
+				for _, expectedMsg := range tt.errorContains {
+					found := false
+					for _, err := range errs {
+						if strings.Contains(err.Message, expectedMsg) {
+							found = true
+							break
+						}
+					}
+					assert.True(t, found, "expected error message '%s' not found in errors: %v", expectedMsg, errs)
+				}
+			} else {
+				assert.Empty(t, errs, "expected no validation errors, got: %v", errs)
+			}
+		})
+	}
+}
+
+func TestIsValidHostname(t *testing.T) {
+	tests := []struct {
+		name     string
+		hostname string
+		valid    bool
+	}{
+		{"valid simple", "myservice", true},
+		{"valid with hyphen", "my-service", true},
+		{"valid with numbers", "service123", true},
+		{"valid mixed", "my-service-123", true},
+		{"valid uppercase", "MyService", true},
+		{"valid single char", "a", true},
+		{"valid single digit", "1", true},
+		{"valid max length (63)", "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", true},
+		{"invalid empty", "", false},
+		{"invalid too long (64)", "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", false},
+		{"invalid starts with hyphen", "-myservice", false},
+		{"invalid ends with hyphen", "myservice-", false},
+		{"invalid underscore", "my_service", false},
+		{"invalid dot", "my.service", false},
+		{"invalid space", "my service", false},
+		{"invalid special char", "my@service", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := isValidHostname(tt.hostname)
+			assert.Equal(t, tt.valid, result, "isValidHostname(%q) = %v, want %v", tt.hostname, result, tt.valid)
+		})
+	}
+}
+
+func TestIsAlphanumeric(t *testing.T) {
+	tests := []struct {
+		char  byte
+		valid bool
+	}{
+		{'a', true},
+		{'z', true},
+		{'A', true},
+		{'Z', true},
+		{'0', true},
+		{'9', true},
+		{'-', false},
+		{'_', false},
+		{'.', false},
+		{' ', false},
+		{'@', false},
+	}
+
+	for _, tt := range tests {
+		t.Run(string(tt.char), func(t *testing.T) {
+			result := isAlphanumeric(tt.char)
+			assert.Equal(t, tt.valid, result, "isAlphanumeric(%q) = %v, want %v", tt.char, result, tt.valid)
+		})
+	}
+}

internal/forward/manager.go

@@ -10,6 +10,7 @@ import (
 	"github.com/nvm/kportal/internal/healthcheck"
 	"github.com/nvm/kportal/internal/k8s"
 	"github.com/nvm/kportal/internal/logger"
+	"github.com/nvm/kportal/internal/mdns"
 )
 
 // StatusUpdater is an interface for updating forward status
@@ -30,6 +31,7 @@ type Manager struct {
 	portChecker   *PortChecker
 	healthChecker *healthcheck.Checker
 	watchdog      *Watchdog
+	mdnsPublisher *mdns.Publisher
 	verbose       bool
 	currentConfig *config.Config
 	statusUI      StatusUpdater
@@ -117,6 +119,11 @@ func (m *Manager) SetStatusUI(ui StatusUpdater) {
 	m.statusUI = ui
 }
 
+// SetMDNSPublisher sets the mDNS publisher for the manager
+func (m *Manager) SetMDNSPublisher(publisher *mdns.Publisher) {
+	m.mdnsPublisher = publisher
+}
+
 // Start initializes and starts all port-forwards from the configuration.
 func (m *Manager) Start(cfg *config.Config) error {
 	if cfg == nil {
@@ -186,6 +193,11 @@ func (m *Manager) Stop() {
 	m.healthChecker.Stop()
 	m.watchdog.Stop()
 
+	// Stop mDNS publisher
+	if m.mdnsPublisher != nil {
+		m.mdnsPublisher.Stop()
+	}
+
 	m.workersMu.Lock()
 	workers := make([]*ForwardWorker, 0, len(m.workers))
 	for _, worker := range m.workers {
@@ -391,6 +403,22 @@ func (m *Manager) startWorker(fwd config.Forward) error {
 	// Store worker
 	m.workers[fwd.ID()] = worker
 
+	// Register mDNS hostname if enabled
+	// Uses explicit alias if set, otherwise generates from resource name
+	if m.mdnsPublisher != nil {
+		mdnsAlias := fwd.GetMDNSAlias()
+		if mdnsAlias != "" {
+			if err := m.mdnsPublisher.Register(fwd.ID(), mdnsAlias, fwd.LocalPort); err != nil {
+				logger.Warn("Failed to register mDNS hostname", map[string]interface{}{
+					"forward_id": fwd.ID(),
+					"alias":      mdnsAlias,
+					"error":      err.Error(),
+				})
+				// Don't fail the forward start - mDNS is optional
+			}
+		}
+	}
+
 	return nil
 }
 
@@ -414,6 +442,11 @@ func (m *Manager) stopWorkerInternal(id string, removeFromUI bool) error {
 	m.healthChecker.Unregister(id)
 	m.watchdog.UnregisterWorker(id)
 
+	// Unregister mDNS hostname
+	if m.mdnsPublisher != nil {
+		m.mdnsPublisher.Unregister(id)
+	}
+
 	// Notify UI - either remove or update to disabled status
 	if m.statusUI != nil {
 		if removeFromUI {

internal/forward/worker.go

@@ -85,7 +85,16 @@ func (w *ForwardWorker) Start() {
 func (w *ForwardWorker) Stop() {
 	w.cancel()
 	close(w.stopChan)
-	<-w.doneChan // Wait for worker to finish
+
+	// Wait for worker to finish with timeout to prevent blocking forever
+	select {
+	case <-w.doneChan:
+		// Worker finished gracefully
+	case <-time.After(3 * time.Second):
+		// Worker didn't finish in time, but we've cancelled its context
+		// so it will clean up eventually
+		log.Printf("[%s] Worker stop timed out, continuing...", w.forward.ID())
+	}
 }
 
 // run is the main worker loop that handles retries.

internal/mdns/publisher.go

@@ -0,0 +1,220 @@
+package mdns
+
+import (
+	"fmt"
+	"net"
+	"sync"
+	"time"
+
+	"github.com/grandcat/zeroconf"
+	"github.com/nvm/kportal/internal/logger"
+)
+
+const (
+	// shutdownTimeout is the maximum time to wait for mDNS server shutdown
+	shutdownTimeout = 2 * time.Second
+
+	// mdnsDomain is the standard mDNS domain (RFC 6762)
+	// This is always ".local" for multicast DNS - it's not configurable
+	// and is different from your network's DNS search domain
+	mdnsDomain = "local"
+)
+
+// Publisher manages mDNS hostname registrations for port forwards.
+// It allows forwards with aliases to be accessible via <alias>.local hostnames.
+type Publisher struct {
+	mu       sync.RWMutex
+	servers  map[string]*zeroconf.Server // forwardID -> server
+	aliases  map[string]string           // forwardID -> alias (for logging)
+	enabled  bool
+	localIPs []string
+}
+
+// NewPublisher creates a new mDNS Publisher.
+// If enabled is false, all registration calls will be no-ops.
+func NewPublisher(enabled bool) *Publisher {
+	p := &Publisher{
+		servers:  make(map[string]*zeroconf.Server),
+		aliases:  make(map[string]string),
+		enabled:  enabled,
+		localIPs: getLocalIPs(),
+	}
+
+	if enabled {
+		logger.Info("mDNS publisher initialized", map[string]interface{}{
+			"domain":    mdnsDomain,
+			"local_ips": p.localIPs,
+		})
+	}
+
+	return p
+}
+
+// Register publishes an mDNS hostname for a forward.
+// The hostname will be <alias>.local and will resolve to 127.0.0.1.
+// If the forward has no alias or mDNS is disabled, this is a no-op.
+func (p *Publisher) Register(forwardID, alias string, localPort int) error {
+	if !p.enabled || alias == "" {
+		return nil
+	}
+
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	// Check if already registered
+	if _, exists := p.servers[forwardID]; exists {
+		logger.Debug("mDNS hostname already registered", map[string]interface{}{
+			"forward_id": forwardID,
+			"alias":      alias,
+		})
+		return nil
+	}
+
+	// Register the mDNS service
+	// We use a generic service type and rely on the hostname registration
+	server, err := zeroconf.RegisterProxy(
+		alias,                 // Instance name (shown in service discovery)
+		"_kportal._tcp",       // Service type (custom for kportal)
+		"local.",              // Domain
+		localPort,             // Port
+		alias,                 // Hostname (will be <alias>.local)
+		[]string{"127.0.0.1"}, // IPs to resolve to
+		[]string{fmt.Sprintf("forward=%s", forwardID)}, // TXT records
+		nil, // interfaces (nil = all)
+	)
+	if err != nil {
+		return fmt.Errorf("failed to register mDNS for %s: %w", alias, err)
+	}
+
+	p.servers[forwardID] = server
+	p.aliases[forwardID] = alias
+
+	logger.Info("mDNS hostname registered", map[string]interface{}{
+		"forward_id": forwardID,
+		"hostname":   GetHostname(alias),
+		"port":       localPort,
+	})
+
+	return nil
+}
+
+// Unregister removes the mDNS hostname for a forward.
+func (p *Publisher) Unregister(forwardID string) {
+	if !p.enabled {
+		return
+	}
+
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	server, exists := p.servers[forwardID]
+	if !exists {
+		return
+	}
+
+	alias := p.aliases[forwardID]
+	shutdownWithTimeout(server, forwardID)
+	delete(p.servers, forwardID)
+	delete(p.aliases, forwardID)
+
+	logger.Info("mDNS hostname unregistered", map[string]interface{}{
+		"forward_id": forwardID,
+		"hostname":   GetHostname(alias),
+	})
+}
+
+// Stop shuts down all mDNS registrations.
+func (p *Publisher) Stop() {
+	if !p.enabled {
+		return
+	}
+
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	// Shutdown all servers concurrently with timeout
+	var wg sync.WaitGroup
+	for forwardID, server := range p.servers {
+		wg.Add(1)
+		go func(id string, srv *zeroconf.Server) {
+			defer wg.Done()
+			shutdownWithTimeout(srv, id)
+		}(forwardID, server)
+	}
+
+	// Wait for all shutdowns to complete (or timeout)
+	wg.Wait()
+
+	p.servers = make(map[string]*zeroconf.Server)
+	p.aliases = make(map[string]string)
+
+	logger.Info("mDNS publisher stopped", nil)
+}
+
+// shutdownWithTimeout attempts to shutdown a zeroconf server with a timeout.
+// If shutdown hangs, it logs a warning and returns anyway.
+func shutdownWithTimeout(server *zeroconf.Server, forwardID string) {
+	done := make(chan struct{})
+
+	go func() {
+		server.Shutdown()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		// Shutdown completed successfully
+	case <-time.After(shutdownTimeout):
+		logger.Warn("mDNS shutdown timed out, continuing anyway", map[string]interface{}{
+			"forward_id": forwardID,
+			"timeout":    shutdownTimeout.String(),
+		})
+	}
+}
+
+// IsEnabled returns whether mDNS publishing is enabled.
+func (p *Publisher) IsEnabled() bool {
+	return p.enabled
+}
+
+// GetDomain returns the mDNS domain being used (always "local" per RFC 6762).
+func (p *Publisher) GetDomain() string {
+	return mdnsDomain
+}
+
+// GetHostname returns the full mDNS hostname for an alias.
+// Example: GetHostname("myapp") returns "myapp.local"
+func GetHostname(alias string) string {
+	return alias + "." + mdnsDomain
+}
+
+// GetRegisteredCount returns the number of currently registered hostnames.
+func (p *Publisher) GetRegisteredCount() int {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	return len(p.servers)
+}
+
+// getLocalIPs returns the local IP addresses for logging purposes.
+func getLocalIPs() []string {
+	var ips []string
+
+	addrs, err := net.InterfaceAddrs()
+	if err != nil {
+		return []string{"127.0.0.1"}
+	}
+
+	for _, addr := range addrs {
+		if ipnet, ok := addr.(*net.IPNet); ok && !ipnet.IP.IsLoopback() {
+			if ipnet.IP.To4() != nil {
+				ips = append(ips, ipnet.IP.String())
+			}
+		}
+	}
+
+	if len(ips) == 0 {
+		return []string{"127.0.0.1"}
+	}
+
+	return ips
+}

internal/mdns/publisher_test.go

@@ -0,0 +1,154 @@
+package mdns
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// Note: Tests that actually register mDNS services require network I/O
+// and can be slow or hang in CI environments. We test the logic paths
+// without actually calling zeroconf for most tests.
+
+func TestNewPublisher_Disabled(t *testing.T) {
+	p := NewPublisher(false)
+
+	assert.False(t, p.IsEnabled())
+	assert.Equal(t, 0, p.GetRegisteredCount())
+}
+
+func TestNewPublisher_Enabled(t *testing.T) {
+	p := NewPublisher(true)
+
+	assert.True(t, p.IsEnabled())
+	assert.Equal(t, 0, p.GetRegisteredCount())
+}
+
+func TestRegister_WhenDisabled_NoOp(t *testing.T) {
+	p := NewPublisher(false)
+
+	err := p.Register("forward-1", "test-alias", 8080)
+
+	assert.NoError(t, err)
+	assert.Equal(t, 0, p.GetRegisteredCount())
+}
+
+func TestRegister_EmptyAlias_NoOp(t *testing.T) {
+	p := NewPublisher(true)
+
+	err := p.Register("forward-1", "", 8080)
+
+	assert.NoError(t, err)
+	assert.Equal(t, 0, p.GetRegisteredCount())
+}
+
+func TestUnregister_WhenDisabled_NoOp(t *testing.T) {
+	p := NewPublisher(false)
+
+	// Should not panic
+	p.Unregister("forward-1")
+}
+
+func TestUnregister_NotRegistered_NoOp(t *testing.T) {
+	p := NewPublisher(true)
+
+	// Should not panic
+	p.Unregister("non-existent")
+	assert.Equal(t, 0, p.GetRegisteredCount())
+}
+
+func TestStop_WhenDisabled_NoOp(t *testing.T) {
+	p := NewPublisher(false)
+
+	// Should not panic
+	p.Stop()
+}
+
+func TestStop_WhenNoRegistrations(t *testing.T) {
+	p := NewPublisher(true)
+
+	// Should not panic
+	p.Stop()
+	assert.Equal(t, 0, p.GetRegisteredCount())
+}
+
+func TestGetLocalIPs(t *testing.T) {
+	ips := getLocalIPs()
+
+	// Should return at least one IP
+	assert.NotEmpty(t, ips, "getLocalIPs should return at least one IP")
+
+	// All IPs should be non-empty strings
+	for _, ip := range ips {
+		assert.NotEmpty(t, ip, "IP address should not be empty")
+	}
+}
+
+// Integration tests - only run when explicitly requested
+// These tests actually register mDNS services and require network access
+
+func TestRegister_Integration(t *testing.T) {
+	if testing.Short() {
+		t.Skip("Skipping mDNS integration test in short mode")
+	}
+
+	p := NewPublisher(true)
+	defer p.Stop()
+
+	err := p.Register("forward-1", "test-service", 8080)
+
+	assert.NoError(t, err)
+	assert.Equal(t, 1, p.GetRegisteredCount())
+}
+
+func TestRegister_Duplicate_Idempotent_Integration(t *testing.T) {
+	if testing.Short() {
+		t.Skip("Skipping mDNS integration test in short mode")
+	}
+
+	p := NewPublisher(true)
+	defer p.Stop()
+
+	// First registration
+	err := p.Register("forward-1", "test-service", 8080)
+	assert.NoError(t, err)
+	assert.Equal(t, 1, p.GetRegisteredCount())
+
+	// Second registration with same ID should be idempotent
+	err = p.Register("forward-1", "test-service", 8080)
+	assert.NoError(t, err)
+	assert.Equal(t, 1, p.GetRegisteredCount())
+}
+
+func TestRegister_MultipleForwards_Integration(t *testing.T) {
+	if testing.Short() {
+		t.Skip("Skipping mDNS integration test in short mode")
+	}
+
+	p := NewPublisher(true)
+	defer p.Stop()
+
+	err1 := p.Register("forward-1", "service-a", 8080)
+	err2 := p.Register("forward-2", "service-b", 8081)
+	err3 := p.Register("forward-3", "service-c", 8082)
+
+	assert.NoError(t, err1)
+	assert.NoError(t, err2)
+	assert.NoError(t, err3)
+	assert.Equal(t, 3, p.GetRegisteredCount())
+}
+
+func TestUnregister_Success_Integration(t *testing.T) {
+	if testing.Short() {
+		t.Skip("Skipping mDNS integration test in short mode")
+	}
+
+	p := NewPublisher(true)
+	defer p.Stop()
+
+	p.Register("forward-1", "test-service", 8080)
+	assert.Equal(t, 1, p.GetRegisteredCount())
+
+	p.Unregister("forward-1")
+	assert.Equal(t, 0, p.GetRegisteredCount())
+}