Skip to content

Commit

Permalink
Documentation improvements. (#22)
Browse files Browse the repository at this point in the history
  • Loading branch information
postmodern authored Feb 6, 2023
1 parent 8878bc7 commit c7162e6
Show file tree
Hide file tree
Showing 3 changed files with 52 additions and 28 deletions.
35 changes: 17 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,34 +25,33 @@ Or install it yourself as:
Here is a simple example showing how to use the resolver:

``` ruby
Async::Reactor.run do
resolver = Async::DNS::Resolver.new([[:udp, "8.8.8.8", 53], [:tcp, "8.8.8.8", 53]])
Async::Reactor.run do
resolver = Async::DNS::Resolver.new([[:udp, "8.8.8.8", 53], [:tcp, "8.8.8.8", 53]])

addresses = resolver.addresses_for("www.google.com.")
addresses = resolver.addresses_for("www.google.com.")

puts addresses.inspect
end
=> [#<Resolv::IPv4 202.124.127.240>, #<Resolv::IPv4 202.124.127.216>, #<Resolv::IPv4 202.124.127.223>, #<Resolv::IPv4 202.124.127.227>, #<Resolv::IPv4 202.124.127.234>, #<Resolv::IPv4 202.124.127.230>, #<Resolv::IPv4 202.124.127.208>, #<Resolv::IPv4 202.124.127.249>, #<Resolv::IPv4 202.124.127.219>, #<Resolv::IPv4 202.124.127.218>, #<Resolv::IPv4 202.124.127.212>, #<Resolv::IPv4 202.124.127.241>, #<Resolv::IPv4 202.124.127.238>, #<Resolv::IPv4 202.124.127.245>, #<Resolv::IPv4 202.124.127.251>, #<Resolv::IPv4 202.124.127.229>]
puts addresses.inspect
end
# [#<Resolv::IPv4 202.124.127.240>, #<Resolv::IPv4 202.124.127.216>, #<Resolv::IPv4 202.124.127.223>, #<Resolv::IPv4 202.124.127.227>, #<Resolv::IPv4 202.124.127.234>, #<Resolv::IPv4 202.124.127.230>, #<Resolv::IPv4 202.124.127.208>, #<Resolv::IPv4 202.124.127.249>, #<Resolv::IPv4 202.124.127.219>, #<Resolv::IPv4 202.124.127.218>, #<Resolv::IPv4 202.124.127.212>, #<Resolv::IPv4 202.124.127.241>, #<Resolv::IPv4 202.124.127.238>, #<Resolv::IPv4 202.124.127.245>, #<Resolv::IPv4 202.124.127.251>, #<Resolv::IPv4 202.124.127.229>]
```

### Server

Here is a simple example showing how to use the server:

``` ruby
require 'async/dns'

class TestServer < Async::DNS::Server
def process(name, resource_class, transaction)
@resolver ||= Async::DNS::Resolver.new([[:udp, '8.8.8.8', 53], [:tcp, '8.8.8.8', 53]])

transaction.passthrough!(@resolver)
end
require 'async/dns'

class TestServer < Async::DNS::Server
def process(name, resource_class, transaction)
@resolver ||= Async::DNS::Resolver.new([[:udp, '8.8.8.8', 53], [:tcp, '8.8.8.8', 53]])

transaction.passthrough!(@resolver)
end
server = TestServer.new([[:udp, '127.0.0.1', 2346]])
server.run
end

server = TestServer.new([[:udp, '127.0.0.1', 2346]])
server.run
```

Then to test you could use `dig` like so:
Expand Down
43 changes: 34 additions & 9 deletions lib/async/dns/server.rb
Original file line number Diff line number Diff line change
Expand Up @@ -24,30 +24,55 @@
require_relative 'transaction'

module Async::DNS
#
# Base class for defining asynchronous DNS servers.
#
# ## Example
#
# require 'async/dns'
#
# class TestServer < Async::DNS::Server
# def process(name, resource_class, transaction)
# @resolver ||= Async::DNS::Resolver.new([[:udp, '8.8.8.8', 53], [:tcp, '8.8.8.8', 53]])
#
# transaction.passthrough!(@resolver)
# end
# end
#
# server = TestServer.new([[:udp, '127.0.0.1', 2346]])
# server.run
#
class Server
# The default server interfaces
# The default server interfaces.
DEFAULT_ENDPOINTS = [[:udp, "0.0.0.0", 53], [:tcp, "0.0.0.0", 53]]

# Instantiate a server with a block
#
# server = Server.new do
# match(/server.mydomain.com/, IN::A) do |transaction|
# transaction.respond!("1.2.3.4")
# end
# end
# Instantiate a server with a block.
#
# @param endpoints [Array<(Symbol, String, Integer)>] The endpoints to listen on.
# @param origin [String] The default origin to resolve domains within.
# @param logger [Console::Logger] The logger to use.
def initialize(endpoints = DEFAULT_ENDPOINTS, origin: '.', logger: Console.logger)
@endpoints = endpoints
@origin = origin
@logger = logger
end

# Records are relative to this origin:
# Records are relative to this origin.
#
# @return [String]
attr_accessor :origin

# The logger to use.
#
# @return [Console::Logger]
attr_accessor :logger

# Give a name and a record type, try to match a rule and use it for processing the given arguments.
#
# @param name [String] The resource name.
# @param resource_class [Class<Resolv::DNS::Resource>] The requested resource class.
# @param transaction [Transaction] The transaction object.
# @abstract
def process(name, resource_class, transaction)
raise NotImplementedError.new
end
Expand Down
2 changes: 1 addition & 1 deletion lib/async/dns/transaction.rb
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,7 @@ def add(resources, options = {})
end
end

# This function indicates that there was a failure to resolve the given question. The single argument must be an integer error code, typically given by the constants in {Resolv::DNS::RCode}.
# This function indicates that there was a failure to resolve the given question. The single argument must be an integer error code, typically given by the constants in `Resolv::DNS::RCode`.
#
# The easiest way to use this function it to simply supply a symbol. Here is a list of the most commonly used ones:
#
Expand Down

0 comments on commit c7162e6

Please sign in to comment.