vendor/github.com/grandcat/zeroconf/README.md

   1 ZeroConf: Service Discovery with mDNS
   2 =====================================
   3 ZeroConf is a pure Golang library that employs Multicast DNS-SD for
   4
   5 * browsing and resolving services in your network
   6 * registering own services
   7
   8 in the local network.
   9
  10 It basically implements aspects of the standards
  11 [RFC 6762](https://tools.ietf.org/html/rfc6762) (mDNS) and
  12 [RFC 6763](https://tools.ietf.org/html/rfc6763) (DNS-SD).
  13 Though it does not support all requirements yet, the aim is to provide a complient solution in the long-term with the community.
  14
  15 By now, it should be compatible to [Avahi](http://avahi.org/) (tested) and Apple's Bonjour (untested).
  16 Target environments: private LAN/Wifi, small or isolated networks.
  17
  18 [![GoDoc](https://godoc.org/github.com/grandcat/zeroconf?status.svg)](https://godoc.org/github.com/grandcat/zeroconf)
  19 [![Go Report Card](https://goreportcard.com/badge/github.com/grandcat/zeroconf)](https://goreportcard.com/report/github.com/grandcat/zeroconf)
  20
  21 ## Install
  22 Nothing is as easy as that:
  23 ```bash
  24 $ go get -u github.com/grandcat/zeroconf
  25 ```
  26 This package requires **Go 1.7** (context in std lib) or later.
  27
  28 ## Browse for services in your local network
  29
  30 ```go
  31 // Discover all services on the network (e.g. _workstation._tcp)
  32 resolver, err := zeroconf.NewResolver(nil)
  33 if err != nil {
  34     log.Fatalln("Failed to initialize resolver:", err.Error())
  35 }
  36
  37 entries := make(chan *zeroconf.ServiceEntry)
  38 go func(results <-chan *zeroconf.ServiceEntry) {
  39     for entry := range results {
  40         log.Println(entry)
  41     }
  42     log.Println("No more entries.")
  43 }(entries)
  44
  45 ctx, cancel := context.WithTimeout(context.Background(), time.Second*15)
  46 defer cancel()
  47 err = resolver.Browse(ctx, "_workstation._tcp", "local.", entries)
  48 if err != nil {
  49     log.Fatalln("Failed to browse:", err.Error())
  50 }
  51
  52 <-ctx.Done()
  53 ```
  54 See https://github.com/grandcat/zeroconf/blob/master/examples/resolv/client.go.
  55
  56 ## Lookup a specific service instance
  57
  58 ```go
  59 // Example filled soon.
  60 ```
  61
  62 ## Register a service
  63
  64 ```go
  65 server, err := zeroconf.Register("GoZeroconf", "_workstation._tcp", "local.", 42424, []string{"txtv=0", "lo=1", "la=2"}, nil)
  66 if err != nil {
  67     panic(err)
  68 }
  69 defer server.Shutdown()
  70
  71 // Clean exit.
  72 sig := make(chan os.Signal, 1)
  73 signal.Notify(sig, os.Interrupt, syscall.SIGTERM)
  74 select {
  75 case <-sig:
  76     // Exit by user
  77 case <-time.After(time.Second * 120):
  78     // Exit by timeout
  79 }
  80
  81 log.Println("Shutting down.")
  82 ```
  83 See https://github.com/grandcat/zeroconf/blob/master/examples/register/server.go.
  84
  85 ## Features and ToDo's
  86 This list gives a quick impression about the state of this library.
  87 See what needs to be done and submit a pull request :)
  88
  89 * [x] Browse / Lookup / Register services
  90 * [x] Multiple IPv6 / IPv4 addresses support
  91 * [x] Send multiple probes (exp. back-off) if no service answers (*)
  92 * [ ] Timestamp entries for TTL checks
  93 * [ ] Compare new multicasts with already received services
  94
  95 _Notes:_
  96
  97 (*) The denoted functionalities might not be 100% standard conform, but should not be a deal breaker.
  98     Some test scenarios demonstrated that the overall robustness and performance increases when applying the suggested improvements.
  99
 100 ## Credits
 101 Great thanks to [hashicorp](https://github.com/hashicorp/mdns) and to [oleksandr](https://github.com/oleksandr/bonjour) and all contributing authors for the code this projects bases upon.
 102 Large parts of the code are still the same.
 103
 104 However, there are several reasons why I decided to create a fork of the original project:
 105 The previous project seems to be unmaintained. There are several useful pull requests waiting. I merged most of them in this project.
 106 Still, the implementation has some bugs and lacks some other features that make it quite unreliable in real LAN environments when running continously.
 107 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.
 108 Though, resiliency should remain a top goal.