dns-sd 0.1.0

data/README.md

@@ -0,0 +1,130 @@
+[DNS-SD](https://tools.ietf.org/html/rfc6763) is a method of laying out
+standard DNS records in such a way that permits service discovery and
+enumeration, high availability, load balancing, and failover of arbitrary
+services.  Whilst it is often used in concert with [Multicast DNS
+(mDNS)](https://tools.ietf.org/html/rfc67621), it works just as well with
+regular DNS services, and that is what this package is focused on.  If
+you're interested in mDNS-based DNS-SD interaction, the [similarly-named
+dnssd gem](https://rubygems.org/gems/dnssd) might be more to your liking.
+
+
+# Installation
+
+It's a gem:
+
+    gem install dns-sd
+
+There's also the wonders of [the Gemfile](http://bundler.io):
+
+    gem 'dns-sd'
+
+If you're the sturdy type that likes to run from git:
+
+    rake install
+
+Or, if you've eschewed the convenience of Rubygems entirely, then you
+presumably know what to do already.
+
+
+# Usage
+
+The basic class, DNSSD, is the usual entrypoint for everything:
+
+    require 'dns-sd'
+
+    dnssd = DNSSD.new("example.com")
+
+From there, you can connect directly to a service instance, get a service
+type so you can ask it for all available instances, or even ask for all
+services in the domain.
+
+The sub-sections below show some common usage patterns.  If your specific
+use case isn't covered, the per-class documentation may be more
+enlightening.
+
+
+## Connecting to a service instance
+
+If you know what service and instance you're interested in, you can go
+straight there:
+
+    my_printer = dnssd.service_instance("My Printer", "ipp", :TCP)
+
+Then get the connection targets and even try connecting to them:
+
+    targets = my_printer.targets
+
+    sock = begin
+      break nil if targets.empty?
+      t = targets.shift
+      TCPSocket.new(t.hostname, t.port)
+    rescue SystemCallError
+      # Automatically go on to the next server
+      retry
+    end
+
+    if sock.nil?
+      $stderr.puts "Failed to connect to My Printer"
+    else
+      # Work with `sock` as required
+    end
+
+If there's more than one target registered for a given service instance
+(common in high-availability and load-balanced systems), every time you call
+DNSSD::ServiceInstance#targets, you'll get the server list in a different
+order, respecting the priorities and weights of the constituent SRV records.
+
+The SRV record lookups (like all DNS records) are cached, so if you wish
+to connect to a service instance repeatedly, you should call #targets on
+your service instance object each time you want to make a connection, rather
+than re-using the result of a single call to #target.  As long as you're
+operating against the same DNSSD::ServiceInstance object and the record TTLs
+haven't expired, successive calls to #target should be very efficient.
+
+
+## Enumerating all instances of a service
+
+If you know you want a printer, but aren't sure which one, you can ask for
+the IPP service, and then enumerate all the service instances:
+
+    dnssd.service("ipp", :TCP).each do |name, instance|
+      puts "I found a printer named #{name}"
+      puts "Its targets are #{instance.targets.map { |t| "#{t.hostname}:#{t.port}" }.join(", ")}"
+    end
+
+## Enumerating all services
+
+If you're just curious about what might be on a domain, you can try the
+"Service Type Enumeration" endpoint:
+
+    dnssd.services.each do |name, svc|
+      puts "I found a service named #{name}"
+      puts "It has instances of #{svc.instances.map { |i| i.name }.join(", ")}"
+    end
+
+
+# Contributing
+
+Bug reports should be sent to the [Github issue
+tracker](https://github.com/discourse/dns-sd/issues).  Patches can be sent as a
+[Github pull request](https://github.com/discourse/dns-sd/pulls).
+
+
+# Licence
+
+Unless otherwise stated, everything in this repo is covered by the following
+copyright notice:
+
+    Copyright (C) 2017 Civilzed Discourse Construction Kit, Inc.
+
+    This program is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License version 3, as
+    published by the Free Software Foundation.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/dns-sd.gemspec

@@ -0,0 +1,40 @@
+begin
+  require 'git-version-bump'
+rescue LoadError
+  nil
+end
+
+Gem::Specification.new do |s|
+  s.name = "dns-sd"
+
+  s.version = GVB.version rescue "0.0.0.1.NOGVB"
+  s.date    = GVB.date    rescue Time.now.strftime("%Y-%m-%d")
+
+  s.platform = Gem::Platform::RUBY
+
+  s.summary  = "Query RFC6763 DNS-SD records"
+  s.description = <<~EOF
+    If you need to retrieve and work with DNS-SD records, this is the library
+    you've been waiting for.
+  EOF
+
+  s.authors  = ["Matt Palmer"]
+  s.email    = ["matt.palmer@discourse.org"]
+  s.homepage = "https://github.com/discourse/dns-sd"
+
+  s.files = `git ls-files -z`.split("\0").reject { |f| f =~ /^(G|spec|Rakefile)/ }
+
+  s.required_ruby_version = ">= 2.3.0"
+
+  s.add_development_dependency 'bundler'
+  s.add_development_dependency 'github-release'
+  s.add_development_dependency 'git-version-bump'
+  s.add_development_dependency 'guard-rspec'
+  s.add_development_dependency 'guard-rubocop'
+  s.add_development_dependency 'rake', "~> 12.0"
+  s.add_development_dependency 'redcarpet'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'rubocop'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'yard'
+end

data/lib/dns-sd.rb

@@ -0,0 +1,110 @@
+require 'dns-sd/resource_cache'
+require 'dns-sd/service'
+
+require 'resolv'
+
+# Interact with RFC6763 DNS-SD records.
+#
+# Given a domain to work in, instances of this class use the standard Ruby DNS
+# resolution mechanisms to look up services, service instances, and the
+# individual servers that make up service instances.  You can also obtain the
+# "metadata" associated with service instances.
+#
+# If you know the service, or even service instance, you wish to connect to,
+# you can go straight there, using #service or #service_instance (as
+# appropriate).  Otherwise, if you're just curious about what is available, you
+# can use #services to get a list of everything advertised under the "Service
+# Type Enumeration" record for the domain.
+#
+class DNSSD
+  include DNSSD::ResourceCache
+
+  # Create a new DNS-SD instance.
+  #
+  # @param domain [String, Resolv::DNS::Name] Specify the base domain under
+  #   which all the records we're interested in are registered.
+  #
+  def initialize(domain)
+    @domain = if domain.is_a?(Resolv::DNS::Name)
+      domain
+    else
+      Resolv::DNS::Name.create(domain)
+    end
+  end
+
+  # The current search domain.
+  #
+  # @return [String]
+  #
+  def domain
+    @domain.to_s
+  end
+
+  # Create a new instance of DNSSD::Service for this given name and protocol.
+  #
+  # If you know the name and protocol of the service you wish to query for,
+  # this is the method for you!  Note that just calling this method doesn't
+  # make any DNS requests, so you may get a service that has no instances.
+  #
+  # @param name [String] the name of the service, *without* the leading
+  #   underscore that goes into the DNS name.
+  #
+  # @param protocol [Symbol] One of `:TCP` or `:UDP`, to indicate that you want
+  #   to talk to a TCP or non-TCP service, respectively.  Yes, `:UDP` means
+  #   "non-TCP"; for more laughs, read RFC6763 s. 7.
+  #
+  # @return [DNSSD::Service]
+  #
+  def service(name, protocol)
+    proto = case protocol
+            when :TCP
+              "_tcp"
+            when :UDP
+              "_udp"
+            else
+              raise ArgumentError,
+                "Invalid protocol (must be one of :TCP or :UDP)"
+    end
+
+    DNSSD::Service.new(Resolv::DNS::Name.new(["_#{name}", proto] + @domain.to_a))
+  end
+
+  # Create a new DNSSD::ServiceInstance.
+  #
+  # If you know everything about what you're trying to talk to except the
+  # server list, you can go straight to the boss level with this method.
+  #
+  # @param name [String] the name of the service instance.
+  #
+  # @param service_name [String] the generic name of the service which the
+  #   desired instance implements, *without* the leading underscore that
+  #   is in the DNS name.
+  #
+  # @param service_protocol [Symbol] one of `:TCP` or `:UDP`.
+  #
+  # @return [DNSSD::ServiceInstance]
+  #
+  def service_instance(name, service_name, service_protocol)
+    service(service_name, service_protocol).instance(name)
+  end
+
+  # Enumerate all known services in the domain.
+  #
+  # RFC6763 s. 9 provides a special "Service Type Enumeration" DNS record,
+  # `_services._dns-sd._udp.<domain>`, which is a list of PTR records for
+  # the services available in the domain.  If your DNS-SD registration system
+  # provisions names in there, you can use this to enumerate the available
+  # services.
+  #
+  # @return [Hash<String, DNSSD::Service>] the list of services, indexed by
+  #   the service name.
+  #
+  def services
+    {}.tap do |services|
+      cached_resources(Resolv::DNS::Name.new(["_services", "_dns-sd", "_udp"] + @domain.to_a), Resolv::DNS::Resource::IN::PTR).each do |ptr|
+        svc = DNSSD::Service.new(ptr.name)
+        services[svc.name] = svc
+      end
+    end
+  end
+end

data/lib/dns-sd/resource_cache.rb

@@ -0,0 +1,47 @@
+require 'resolv'
+
+class DNSSD
+  # A mix-in to provide a TTL-respecting caching layer.
+  module ResourceCache
+    private
+
+    # Return a list of resource records.
+    #
+    # We'll ask the DNS, via `Resolv::DNS`, for DNS records matching the
+    # given FQDN and type, unless we've recently seen a response for the
+    # same query, in which case we'll just give that back instead.
+    #
+    # Note that we don't currently implement negative caching, but it's
+    # not a massive optimisation for our use-case, anyway.
+    #
+    # @param fqdn [Resolv::DNS::Name] the name to look up resources at.
+    #
+    # @param type [Resolv::DNS::Resource] the type of resource to request.
+    #
+    # @return [Array<Resolv::DNS::Resource>]
+    #
+    def cached_resources(fqdn, type)
+      @rrcache ||= {}
+
+      k = [fqdn, type]
+
+      if @rrcache[k] && @rrcache[k][:expiry] > Time.now
+        @rrcache[k][:records].dup
+      else
+        Resolv::DNS.new.getresources(fqdn, type).tap do |rrs|
+          @rrcache[k] = { records: rrs.dup, expiry: Time.now + rrs.map { |rr| rr.ttl }.min }
+        end
+      end
+    end
+
+    def entry_expiry_time(fqdn, type)
+      k = [fqdn, type]
+
+      if @rrcache && @rrcache[k]
+        @rrcache[k][:expiry].dup
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/dns-sd/service.rb

@@ -0,0 +1,96 @@
+require 'dns-sd/resource_cache'
+require 'dns-sd/service_instance'
+
+require 'resolv'
+
+class DNSSD
+  # The generic service.
+  #
+  # Allows you to get the list of instances of a given service.
+  #
+  class Service
+    include DNSSD::ResourceCache
+
+    # The name of the service, without the leading underscore.
+    #
+    # @return [String]
+    #
+    attr_reader :name
+
+    # The protocol of the service.
+    #
+    # @return [Symbol] `:TCP` or `:UDP`.
+    #
+    attr_reader :protocol
+
+    # Create the service.
+    #
+    # @param fqdn [Resolv::DNS::Name]
+    #
+    def initialize(fqdn)
+      unless fqdn.is_a?(Resolv::DNS::Name)
+        raise ArgumentError,
+          "FQDN must be a Resolv::DNS::Name (got an instance of #{fqdn.class})"
+      end
+
+      @fqdn = fqdn
+
+      if fqdn[0].to_s =~ /\A_([A-Za-z0-9][A-Za-z0-9-]+)\z/
+        @name = $1
+      else
+        raise ArgumentError,
+          "Invalid service name #{fqdn[0].inspect}; see RFC6763 s. 7"
+      end
+
+      @protocol = case fqdn[1].to_s.downcase
+                  when "_tcp"
+                    :TCP
+                  when "_udp"
+                    :UDP
+                  else
+                    raise ArgumentError,
+                      "Invalid service protocol #{@protocol}, must be '_tcp' or '_udp'"
+      end
+    end
+
+    # Create an object for a specific instance of this service.
+    #
+    # @param name [String] the name of the service instance.
+    #
+    # @return [DNSSD::ServiceInstance]
+    #
+    def instance(name)
+      DNSSD::ServiceInstance.new(Resolv::DNS::Name.new([name] + @fqdn.to_a))
+    end
+
+    # Enumerate all existing instances of this service.
+    #
+    # @return [Hash<String, DNSSD::ServiceInstance>] objects for all the
+    #   service instances, indexed by their names.
+    #
+    def instances
+      {}.tap do |instances|
+        cached_resources(@fqdn, Resolv::DNS::Resource::IN::PTR).each do |rr|
+          i = DNSSD::ServiceInstance.new(rr.name)
+          instances[i.name] = i
+        end
+      end
+    end
+
+    # Let us know how long until the cache expires.
+    #
+    # This can be handy if you've got something that wants to poll the record
+    # repeatedly; this way we can be a bit more intelligent about when to
+    # retry, since if we re-poll too often, we'll just get the cached data back
+    # again anyway.
+    #
+    # @return [Time, nil] if the entry is currently cached, a Time instance
+    #   will be returned indicating when the entry will expire (potentially
+    #   this could be in the past, if the cache has expired).  If we have no
+    #   knowledge of the entry, `nil` will be returned.
+    #
+    def cached_until
+      entry_expiry_time(@fqdn, Resolv::DNS::Resource::IN::PTR)
+    end
+  end
+end

data/lib/dns-sd/service_instance.rb

@@ -0,0 +1,154 @@
+require 'dns-sd/resource_cache'
+require 'dns-sd/service'
+require 'dns-sd/target'
+
+require 'resolv'
+
+class DNSSD
+  # A single instance of a service.
+  #
+  # This is where the rubber hits the road: servers to talk to, and instance
+  # metadata, is all under here.
+  #
+  class ServiceInstance
+    include DNSSD::ResourceCache
+
+    # The name of this service instance.
+    #
+    # This is just the left-most component of the service instance FQDN, and
+    # can, as such, contain practically anything at all.
+    #
+    # @return [String]
+    #
+    attr_reader :name
+
+    # The FQDN of this service instance.
+    #
+    # @return [Resolv::DNS::Name]
+    #
+    attr_reader :fqdn
+
+    # The generic service which this instance implements.
+    #
+    # If you happen to forget what protocol to use, this might come in
+    # handy.
+    #
+    # @return [DNSSD::Service]
+    #
+    attr_reader :service
+
+    # Create the service instance.
+    #
+    # @param fqdn [Resolv::DNS::Name]
+    #
+    def initialize(fqdn)
+      unless fqdn.is_a?(Resolv::DNS::Name)
+        raise ArgumentError,
+          "FQDN must be a Resolv::DNS::Name (got an instance of #{fqdn.class})"
+      end
+
+      @fqdn = fqdn
+
+      @name = fqdn[0].to_s
+      @service = DNSSD::Service.new(Resolv::DNS::Name.new(fqdn[1..-1]))
+    end
+
+    # Return the metadata for the service instance.
+    #
+    # RFC6763 s. 6 describes a means by which specially formatted TXT records
+    # can be used to provide metadata for a service instance.  If your
+    # services populate such data, you can access it here.
+    #
+    # @return [Hash<String, String or nil>] the key-value metadata, presented
+    #   as a nice hash for your looking-up convenience.  If your metadata
+    #   contains "Attribute present, with no value" tags, then the value of
+    #   the associated key will be `nil`, whereas "Attribute present, with
+    #   empty value" will have a value of the empty string (`""`).
+    #
+    def data
+      {}.tap do |data|
+        cached_resources(@fqdn, Resolv::DNS::Resource::IN::TXT).each do |rr|
+          rr.strings.each do |s|
+            s =~ /\A([^=]+)(=(.*))?$/
+            data[$1.to_sym] = $3
+          end
+        end
+      end
+    end
+
+    # The things to connect to for this service instance.
+    #
+    # This is what you're here for, I'll bet.  Everything comes down to this.
+    # Each DNSSD::Target object in this list contains an FQDN (`#hostname`) and
+    # port (`#port`) to connect to, which you can walk in order in order to
+    # get to something that will talk to you.
+    #
+    # Every time you call this method, even if the records are cached, you may
+    # get the targets in a different order.  This is because we automatically
+    # sort the list of targets according to the rules for SRV record priority
+    # and weight.  Thus, it is recommended that every time you want to make a
+    # connection to the service instance, you call `#targets` again, both
+    # because the DNS records may have expired (and thus will be re-queried),
+    # but also because it'll ensure that the weight-based randomisation of the
+    # server list is respected.
+    #
+    # @return [Array<DNSSD::Target>]
+    def targets
+      [].tap do |list|
+        left = cached_resources(@fqdn, Resolv::DNS::Resource::IN::SRV)
+
+        # Happily, this algorithm, whilst a bit involved, maps quite directly
+        # to the description from RFC2782, page 4, of which parts are quoted as
+        # appropriate below.  A practical example of how this process runs is
+        # described in the test suite, also, which might help explain what's
+        # happening.
+        #
+        # > This process is repeated for each Priority.
+        until left.empty?
+          # > A client MUST attempt to contact the target host with the
+          # > lowest-numbered priority it can reach; target hosts with the
+          # > same priority SHOULD be tried in an order defined by the weight
+          # > field.
+          prio = left.map { |rr| rr.priority }.uniq.min
+
+          # > The following algorithm SHOULD be used to order the SRV RRs of the
+          # > same priority:
+          candidates = left.select { |rr| rr.priority == prio }
+          left -= candidates
+
+          # > arrange all SRV RRs (that have not been ordered yet) in any
+          # > order, except that all those with weight 0 are placed at the
+          # > beginning of the list.
+          #
+          # Because it makes it easier to test, I like to sort by weight and
+          # name (<lawyer>it counts as "any order"</lawyer>).  This does mean
+          # that all the zero-weight entries come back in name order, but
+          # if you don't want that behaviour, it's easy enough to give
+          # everything weight=1 and they'll be properly randomised.
+          candidates.sort_by! { |rr| [rr.weight, rr.target.to_s] }
+
+          # > Continue the ordering process until there are no unordered SRV
+          # > RRs.
+          until candidates.empty?
+            # > Compute the sum of the weights of those RRs, and with each RR
+            # > associate the running sum in the selected order. Then choose a
+            # > uniform random number between 0 and the sum computed
+            # > (inclusive)
+            selector = rand(candidates.inject(1) { |n, rr| n + rr.weight })
+
+            # > select the RR whose running sum value is the first in the
+            # > selected order which is greater than or equal to the random
+            # > number selected
+            chosen = candidates.inject(0) do |n, rr|
+              break rr if n + rr.weight >= selector
+              n + rr.weight
+            end
+            # > Remove this SRV RR from the set of the unordered SRV RRs
+            candidates.delete(chosen)
+            list << DNSSD::Target.new(chosen.target.to_s, chosen.port)
+          end
+        end
+      end
+    end
+  end
+end