flynn/docs/plans/2026-02-16-bonjour-mdns-discovery-checklist.md

Bonjour/mDNS Discovery Checklist

Date: 2026-02-16 Status: completed

Scope

• Add optional LAN service advertisement/discovery for the Flynn gateway.
• Keep discovery disabled by default and safe for production deployments.

Completed

• Added server.discovery config schema in src/config/schema.ts:
  • enabled (default false)
  • service_name (default flynn-gateway)
  • service_type (default _flynn._tcp)
  • txt (default {})
• Added gateway discovery runtime in src/gateway/discovery.ts:
  • starts mDNS advertisement via avahi-publish-service (Linux) with fallback to dns-sd (macOS)
  • supports graceful shutdown (SIGTERM with fallback SIGKILL)
• Wired discovery into gateway lifecycle in src/gateway/server.ts:
  • starts advertisement after gateway listen
  • stops advertisement during shutdown
  • injects non-secret TXT metadata (instance, version) plus optional config txt
  • skips advertisement when bound to loopback (server.localhost: true)
• Wired config into gateway construction in src/daemon/services.ts.
• Updated docs:
  • README.md with Bonjour/mDNS configuration and behavior notes
  • config/default.yaml with discovery defaults and LAN safety comment
• Added tests:
  • src/config/schema.test.ts (discovery defaults + custom config)
  • src/gateway/discovery.test.ts (spawn path, fallback path, hard failure path)
  • src/gateway/server.discovery.test.ts (gateway lifecycle start/stop + loopback skip)

Tests

Verification

• pnpm test:run src/config/schema.test.ts src/gateway/discovery.test.ts src/gateway/server.discovery.test.ts
• pnpm typecheck