{"id":34616606,"url":"https://github.com/joshuafuller/beacon","last_synced_at":"2026-06-01T07:32:15.232Z","repository":{"id":322401630,"uuid":"1089325333","full_name":"joshuafuller/beacon","owner":"joshuafuller","description":"Lightweight mDNS/DNS-SD library for Go - Service discovery for IoT, microservices, and local networks. Zero dependencies, RFC 6762 compliant.","archived":false,"fork":false,"pushed_at":"2025-11-04T09:14:56.000Z","size":2000,"stargazers_count":0,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-04T10:05:55.470Z","etag":null,"topics":["bonjour","dns-sd","golang","iot","mdns","microservices","networking","rfc6762","service-discovery","zeroconf"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/joshuafuller/beacon","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joshuafuller.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-04T07:31:44.000Z","updated_at":"2025-11-04T09:15:00.000Z","dependencies_parsed_at":"2025-11-04T10:06:04.335Z","dependency_job_id":null,"html_url":"https://github.com/joshuafuller/beacon","commit_stats":null,"previous_names":["joshuafuller/beacon"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/joshuafuller/beacon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshuafuller%2Fbeacon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshuafuller%2Fbeacon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshuafuller%2Fbeacon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshuafuller%2Fbeacon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joshuafuller","download_url":"https://codeload.github.com/joshuafuller/beacon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshuafuller%2Fbeacon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33765378,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bonjour","dns-sd","golang","iot","mdns","microservices","networking","rfc6762","service-discovery","zeroconf"],"created_at":"2025-12-24T14:39:10.932Z","updated_at":"2026-06-01T07:32:15.213Z","avatar_url":"https://github.com/joshuafuller.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Beacon - High-Performance mDNS Library for Go\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"image/Beacon_Logo_Large.PNG\" alt=\"Beacon mDNS\" width=\"300\" style=\"border-radius: 15px;\"\u003e\n\u003c/p\u003e\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/joshuafuller/beacon.svg)](https://pkg.go.dev/github.com/joshuafuller/beacon)\n[![Go Report Card](https://goreportcard.com/badge/github.com/joshuafuller/beacon)](https://goreportcard.com/report/github.com/joshuafuller/beacon)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/joshuafuller/beacon)\n[![RFC 6762 P0](https://img.shields.io/badge/RFC%206762%20P0-100%25-brightgreen?style=flat-square\u0026logo=checkmarx)](./archive/p0-documentation/RFC_COMPLIANCE_CERTIFICATE_v1.0.md)\n[![RFC 6762 Overall](https://img.shields.io/badge/RFC%206762-97.9%25-brightgreen?style=flat-square\u0026logo=checkmarx)](./archive/p0-documentation/RFC_COMPLIANCE_CERTIFICATE_v1.0.md)\n[![RFC 6763 P0](https://img.shields.io/badge/RFC%206763%20P0-100%25-brightgreen?style=flat-square\u0026logo=checkmarx)](./archive/p0-documentation/RFC6763_KEY_REQUIREMENTS.md)\n[![RFC 6763 Overall](https://img.shields.io/badge/RFC%206763-96.9%25-brightgreen?style=flat-square\u0026logo=checkmarx)](./archive/p0-documentation/RFC6763_KEY_REQUIREMENTS.md)\n\nBeacon is a lightweight, high-performance mDNS (Multicast DNS) library for Go, implementing [RFC 6762](https://www.rfc-editor.org/rfc/rfc6762.html) for service discovery on local networks.\n\n**Perfect for**: IoT devices, microservices, local network service discovery, replacing unmaintained alternatives.\n\n---\n\n## Features\n\n- **10,000x faster** - 4.8μs response latency vs ~50ms in alternatives\n- **100% RFC compliance (MUST requirements)** - 97.9% RFC 6762, 96.9% RFC 6763 overall\n- **Zero external dependencies** - Standard library only\n- **Production-tested** - 68.6% test coverage, 109,471 fuzz executions, 0 data races\n- **Automatic conflict resolution** - RFC 6762 §8.2 compliant\n- **SO_REUSEPORT** - Coexists with Avahi/Bonjour system services\n\n\u003e **Note**: Beacon achieves **100% compliance with all mandatory (MUST) requirements** for both RFC 6762 (Multicast DNS) and RFC 6763 (DNS-Based Service Discovery). The overall percentages (97.9%/96.9%) include optional (SHOULD/MAY) features. See [RFC Compliance Certificate](./archive/p0-documentation/RFC_COMPLIANCE_CERTIFICATE_v1.0.md) for details.\n\n[See detailed comparison with hashicorp/mdns →](docs/internals/analysis/HASHICORP_COMPARISON.md)\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\ngo get github.com/joshuafuller/beacon@latest\n```\n\n### Announce a Service\n\n```go\nimport \"github.com/joshuafuller/beacon/responder\"\n\nr, _ := responder.New(ctx)\ndefer r.Close()\n\nsvc := \u0026responder.Service{\n    Instance: \"My Web Server\",\n    Service:  \"_http._tcp\",\n    Domain:   \"local\",\n    Port:     8080,\n    TXT:      []string{\"path=/\"},\n}\n\nr.Register(ctx, svc) // Service is now announced on the network\n```\n\n### Discover Services\n\n```go\nimport \"github.com/joshuafuller/beacon/querier\"\n\nq, _ := querier.New()\ndefer q.Close()\n\nresults, _ := q.Query(ctx, \"_http._tcp.local\", querier.QueryTypePTR)\nfor _, rr := range results {\n    fmt.Printf(\"Found: %s\\n\", rr.Name)\n}\n```\n\n[More examples →](examples/)\n\n### Coexistence with System Services\n\nBeacon uses `SO_REUSEPORT` to peacefully coexist with system mDNS daemons:\n\n```bash\n# Both Beacon and Avahi/Bonjour can run simultaneously on port 5353\n$ sudo ss -ulnp 'sport = :5353'\nUNCONN  0.0.0.0:5353  users:((\"your-app\",pid=...))\nUNCONN  0.0.0.0:5353  users:((\"avahi-daemon\",pid=...))\n```\n\n**Tested with:**\n- ✅ Linux: Avahi\n- ✅ macOS: Bonjour (code-complete)\n- ✅ Windows: mDNS Service (code-complete)\n\n[Test it yourself →](tests/manual/avahi_coexistence.go)\n\n---\n\n## Why Beacon?\n\n### Built with Engineering Rigor\n\nBeacon is built on proven engineering principles:\n\n- **RFC Compliance First** - Every feature validated against [RFC 6762](https://www.rfc-editor.org/rfc/rfc6762.html)/[6763](https://www.rfc-editor.org/rfc/rfc6763.html)\n- **Specification-Driven** - No code without a spec ([Spec Kit](https://github.com/github/spec-kit) framework)\n- **Test-Driven Development** - Tests written first (RED → GREEN → REFACTOR)\n- **Automated Quality** - 25 [Semgrep rules](SEMGREP_RULES_SUMMARY.md) enforce compliance\n- **Constitutional Governance** - [Development principles](.specify/memory/constitution.md) enshrined\n\n### Measurable Results\n\n| Metric | hashicorp/mdns | Beacon | Improvement |\n|--------|----------------|--------|-------------|\n| Response Latency | ~50ms | 4.8μs | **10,000x faster** |\n| RFC Compliance (P0) | ~7% | 100% | **14x better** |\n| RFC Compliance (Overall) | ~7% | 97.9% | **14x better** |\n| Fuzz Testing | 0 tests | 109,471 execs | **∞ better** |\n| Test Coverage | ~10 tests | 247 tests | **25x better** |\n| Data Races | Known | 0 (verified) | **Production ready** |\n\n---\n\n## Documentation\n\n**📚 [Complete Documentation Hub →](docs/README.md)**\n\n### 👤 For Users\n\n**New to Beacon?** Start here: **[Getting Started Guide →](docs/guides/getting-started.md)**\n\n- **[Getting Started](docs/guides/getting-started.md)** - Installation and first steps (15 min)\n- **[Architecture Overview](docs/guides/architecture.md)** - How Beacon works (10 min)\n- **[Troubleshooting Guide](docs/guides/troubleshooting.md)** - Common issues and solutions\n- **[API Reference](docs/api/README.md)** - Complete API documentation\n- **[Examples](examples/)** - Working code samples\n\n### 🛠️ For Contributors\n\n- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute\n- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community standards\n- **[Security Policy](SECURITY.md)** - Reporting vulnerabilities\n\n### 🔬 For Researchers/Architects\n\n- **[RFC Compliance Certificate](./archive/p0-documentation/RFC_COMPLIANCE_CERTIFICATE_v1.0.md)** - 100% P0, 97.9% overall RFC 6762\n- **[hashicorp/mdns Comparison](docs/internals/analysis/HASHICORP_COMPARISON.md)** - Detailed performance comparison\n- **[Performance Analysis](specs/006-mdns-responder/PERFORMANCE_ANALYSIS.md)** - Benchmarks (Grade A+)\n- **[Security Audit](specs/006-mdns-responder/SECURITY_AUDIT.md)** - Security posture (STRONG)\n- **[Architecture Decision Records](docs/internals/architecture/decisions/)** - Why we made key decisions\n\n---\n\n## What's Implemented\n\n### mDNS Responder (Service Announcement)\n✅ RFC 6762 §8.1-8.3 Probing, Conflict Resolution, Announcing\n✅ RFC 6762 §6.2 Rate Limiting (1 response/sec per record)\n✅ RFC 6762 §7.1 Known-Answer Suppression (TTL ≥50%)\n✅ Multi-service support per responder\n\n### mDNS Querier (Service Discovery)\n✅ RFC 6762 §5 Query transmission\n✅ Context-aware, cancellable operations\n✅ Thread-safe concurrent queries\n\n### Platform Support\n✅ **Linux** - Full support\n⚠️ **macOS/Windows** - Code-complete, pending integration tests\n\n---\n\n## Roadmap\n\n**v0.1.0** (Current) - Production Ready\n**v0.2.0** - IPv6 support, Goodbye packets\n**v0.3.0** - Unicast response support\n**v0.4.0** - Service browsing\n\n[See RFC Compliance Matrix for detailed status →](docs/internals/rfc-compliance/RFC_COMPLIANCE_MATRIX.md)\n\n---\n\n## Requirements\n\n- **Go 1.21 or later**\n- **Standard library only** (zero external dependencies)\n\n---\n\n## Contributing\n\nContributions welcome! We value code, documentation, bug reports, and feature requests.\n\n**[Read the Contributing Guide →](CONTRIBUTING.md)**\n\nQuick checklist before submitting a PR:\n- [ ] Tests written first (TDD)\n- [ ] All tests pass with `-race`\n- [ ] Code coverage ≥80%\n- [ ] `make semgrep-check` passes\n- [ ] Documentation updated\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n---\n\n## License\n\n[MIT License](LICENSE) - Copyright (c) 2025 Joshua Fuller\n\n---\n\n## Acknowledgments\n\n- Inspired by the need for a modern alternative to [hashicorp/mdns](https://github.com/hashicorp/mdns)\n- Implements [RFC 6762](https://www.rfc-editor.org/rfc/rfc6762.html) and [RFC 6763](https://www.rfc-editor.org/rfc/rfc6763.html)\n- Built using [Spec Kit](https://github.com/github/spec-kit) framework\n\n---\n\n## Community \u0026 Support\n\n- **Questions?** [GitHub Discussions](https://github.com/joshuafuller/beacon/discussions)\n- **Bug Reports:** [GitHub Issues](https://github.com/joshuafuller/beacon/issues)\n- **Security Issues:** See [SECURITY.md](SECURITY.md)\n- **Email:** joshuafuller@gmail.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshuafuller%2Fbeacon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoshuafuller%2Fbeacon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshuafuller%2Fbeacon/lists"}