async-dns 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82551b95c437170352dfde80210008c1a9df9bebcbf750b1d5b51e064f0b8f43
-  data.tar.gz: e02fdbd72153bee022c157d9855a60a10db6da9b7067a5159db089ebc8fd63b4
+  metadata.gz: 87d280ed7be9505a629d09e7ffad5135723a80cee1ac849fa8d19597a833eb09
+  data.tar.gz: d2a037310e59fbefb715cbf6c369be55f2eb567636066605b82ede388886ec04
 SHA512:
-  metadata.gz: c4de0e486a37755904384a41685aabd850a9a86f41bb7371f1c2986779bbad06c4bbb3488e2f9e47724bb11832867efbc04c3d1676fa28c737266416b8336215
-  data.tar.gz: 7093b96f0f8bcf457ac88e03fff520298a359ed55d99f69b05453410d0e89703e7e6090720583ac223bf29b3f0e9300f31e46eab91f86f862ccf671cbe7ea824
+  metadata.gz: 685fdcd3685e465742bd2c47d53937a332739c9bc337ac3542d30d2d5fd6e4f213482498b0780be7a666b7c5956596dfdb51a6b213687772c4d3e52c3222d298
+  data.tar.gz: 68af6b3a768695e02a5be1a71a162ba528ff68b01988aa67c3c41552b67af5c6d06054515ec20920ac959fe2cf551919535fff9fbcde30c08aa5406b53b8f285

data/lib/async/dns/cache.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2017-2025, by Samuel Williams.
+
+module Async
+	module DNS
+		# Provides a local in-memory cache for DNS resources.
+		class Cache
+			Entry = Struct.new(:timestamp, :name, :resource_class, :resource) do
+				def age(now)
+					now - timestamp
+				end
+				
+				def fresh?(now = Async::Clock.now)
+					if ttl = resource.ttl
+						self.age(now) <= ttl
+					else
+						true
+					end
+				end
+			end
+			
+			# Create a new cache.
+			def initialize
+				@store = {}
+			end
+			
+			# Fetch a resource from the cache, or if it is not present, yield to the block to fetch it.
+			#
+			# @parameter name [String] The name of the resource.
+			# @parameter resource_classes [Array(Class(Resolv::DNS::Resource))] The classes of the resources to fetch.
+			# @yields {|name, resource_class| ...} The block to fetch the resource, it should call {#store} to store the resource in the cache.
+			def fetch(name, resource_classes)
+				now = Async::Clock.now
+				
+				resource_classes.map do |resource_class|
+					key = [name, resource_class]
+					
+					if entries = @store[key]
+						entries.delete_if do |entry|
+							!entry.fresh?(now)
+						end
+					else
+						entries = (@store[key] = [])
+					end
+					
+					if entries.empty?
+						yield(name, resource_class)
+					end
+					
+					entries
+				end.flatten.map(&:resource)
+			end
+			
+			# Store a resource in the cache.
+			#
+			# @parameter name [String] The name of the resource.
+			# @parameter resource_class [Class(Resolv::DNS::Resource)] The class of the resource.
+			# @parameter resource [Resolv::DNS::Resource] The resource to store.
+			def store(name, resource_class, resource)
+				key = [name, resource_class]
+				entries = (@store[key] ||= [])
+				
+				entries << Entry.new(Async::Clock.now, name, resource_class, resource)
+			end
+		end
+	end
+end

data/lib/async/dns/chunked.rb

@@ -1,22 +1,7 @@
-# Copyright, 2009, 2012, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2015-2024, by Samuel Williams.
 
 module Async::DNS
 	# Produces an array of arrays of binary data with each sub-array a maximum of chunk_size bytes.

data/lib/async/dns/endpoint.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024-2025, by Samuel Williams.
+
+module Async
+	module DNS
+		# DNS endpoint helpers.
+		module Endpoint
+			# Get a list of standard nameserver connections which can be used for querying any standard servers that the system has been configured with.
+			def self.for(nameservers, port: 53, **options)
+				connections = []
+				
+				Array(nameservers).each do |host|
+					connections << IO::Endpoint.udp(host, port, **options)
+					connections << IO::Endpoint.tcp(host, port, **options)
+				end
+				
+				return IO::Endpoint.composite(*connections)
+			end
+		end
+	end
+end

data/lib/async/dns/extensions/resolv.rb

@@ -1,27 +1,15 @@
-# Copyright, 2009, 2012, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# frozen_string_literal: true
 
-require 'resolv'
+# Released under the MIT License.
+# Copyright, 2015-2024, by Samuel Williams.
 
+require "resolv"
+
+# @namespace
 class Resolv
+	# @namespace
 	class DNS
+		# Extensions to the `Resolv::DNS::Message` class.
 		class Message
 			# Merge the given message with this message. A number of heuristics are applied in order to ensure that the result makes sense. For example, If the current message is not recursive but is being merged with a message that was recursive, this bit is maintained. If either message is authoritive, then the result is also authoritive.
 			#
@@ -46,19 +34,17 @@ class Resolv
 			end
 		end
 		
+		# Represents a failure to construct a fullly qualified name due to a mismatched origin.
 		class OriginError < ArgumentError
 		end
 		
+		# Extensions to the `Resolv::DNS::Name` class.
 		class Name
-			def to_s
-				"#{@labels.join('.')}#{@absolute ? '.' : ''}"
-			end
-			
-			def inspect
-				"#<#{self.class}: #{self.to_s}>"
-			end
-			
-			# Return the name, typically absolute, with the specified origin as a suffix. If the origin is nil, don't change the name, but change it to absolute (as specified).
+			# Computes the name, typically absolute, with the specified origin as a suffix. If the origin is nil, don't change the name, but change it to absolute (as specified).
+			#
+			# @parameter origin [Array | String] The origin to append to the name.
+			# @parameter absolute [Boolean] If true, the name will be made absolute.
+			# @returns The name, with the origin suffix.
 			def with_origin(origin, absolute = true)
 				return self.class.new(@labels, absolute) if origin == nil
 				
@@ -67,7 +53,12 @@ class Resolv
 				return self.class.new(@labels + origin, absolute)
 			end
 			
-			# Return the name, typically relative, without the specified origin suffix. If the origin is nil, don't change the name, but change it to absolute (as specified).
+			# Compute the name, typically relative, without the specified origin suffix. If the origin is nil, don't change the name, but change it to absolute (as specified). 
+			#
+			# @parameter origin [Array | String] The origin to remove from the name.
+			# @parameter absolute [Boolean] If true, the name will be made absolute.
+			# @returns The name, without the origin suffix.
+			# @raises [OriginError] If the name does not end with the specified origin.
 			def without_origin(origin, absolute = false)
 				return self.class.new(@labels, absolute) if origin == nil
 				
@@ -81,55 +72,4 @@ class Resolv
 			end
 		end
 	end
-	
-	if RUBY_VERSION == "2.3.0"
-		# Clearly, the Ruby 2.3.0 release was throughly tested.
-		class IPv6
-			def self.create(arg)
-				case arg
-				when IPv6
-					return arg
-				when String
-					address = ''.b
-					if Regex_8Hex =~ arg
-						arg.scan(/[0-9A-Fa-f]+/) {|hex| address << [hex.hex].pack('n')}
-					elsif Regex_CompressedHex =~ arg
-						prefix = $1
-						suffix = $2
-						a1 = ''.b
-						a2 = ''.b
-						prefix.scan(/[0-9A-Fa-f]+/) {|hex| a1 << [hex.hex].pack('n')}
-						suffix.scan(/[0-9A-Fa-f]+/) {|hex| a2 << [hex.hex].pack('n')}
-						omitlen = 16 - a1.length - a2.length
-						address << a1 << "\0" * omitlen << a2
-					elsif Regex_6Hex4Dec =~ arg
-						prefix, a, b, c, d = $1, $2.to_i, $3.to_i, $4.to_i, $5.to_i
-						if (0..255) === a && (0..255) === b && (0..255) === c && (0..255) === d
-							prefix.scan(/[0-9A-Fa-f]+/) {|hex| address << [hex.hex].pack('n')}
-							address << [a, b, c, d].pack('CCCC')
-						else
-							raise ArgumentError.new("not numeric IPv6 address: " + arg)
-						end
-					elsif Regex_CompressedHex4Dec =~ arg
-						prefix, suffix, a, b, c, d = $1, $2, $3.to_i, $4.to_i, $5.to_i, $6.to_i
-						if (0..255) === a && (0..255) === b && (0..255) === c && (0..255) === d
-							a1 = ''.b
-							a2 = ''.b
-							prefix.scan(/[0-9A-Fa-f]+/) {|hex| a1 << [hex.hex].pack('n')}
-							suffix.scan(/[0-9A-Fa-f]+/) {|hex| a2 << [hex.hex].pack('n')}
-							omitlen = 12 - a1.length - a2.length
-							address << a1 << "\0" * omitlen << a2 << [a, b, c, d].pack('CCCC')
-						else
-							raise ArgumentError.new("not numeric IPv6 address: " + arg)
-						end
-					else
-						raise ArgumentError.new("not numeric IPv6 address: " + arg)
-					end
-					return IPv6.new(address)
-				else
-					raise ArgumentError.new("cannot interpret as IPv6 address: #{arg.inspect}")
-				end
-			end
-		end
-	end
-end
+end

data/lib/async/dns/extensions/string.rb

@@ -1,25 +1,11 @@
-# Copyright, 2009, 2012, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# frozen_string_literal: true
 
-require_relative '../chunked'
+# Released under the MIT License.
+# Copyright, 2015-2024, by Samuel Williams.
 
+require_relative "../chunked"
+
+# Extensions for the String class.
 class String
 	# Chunk a string which is required for the TEXT `resource_class`.
 	def chunked(chunk_size = 255)

data/lib/async/dns/handler.rb

@@ -1,39 +1,43 @@
-# Copyright, 2009, 2012, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# frozen_string_literal: true
 
-require 'async/io/stream'
+# Released under the MIT License.
+# Copyright, 2015-2025, by Samuel Williams.
+# Copyright, 2021, by Mike Perham.
 
-require_relative 'transport'
+require "resolv"
+require_relative "extensions/resolv"
+
+require_relative "transport"
 
 module Async::DNS
+	# The maximum size of a normal DNS packet (excluding EDNS).
+	UDP_REASONABLE_SIZE = 512
+	
+	# The maximum size of a UDP packet.
+	UDP_MAXIMUM_SIZE = 2**16
+	
+	# A generic handler for DNS queries.
 	class GenericHandler
+		# Create a new handler.
+		#
+		# @parameter server [Server] The server to handle queries for.
+		# @parameter socket [Socket] The socket to read/write data from/to.
 		def initialize(server, socket)
 			@server = server
 			@socket = socket
-			
-			@logger = @server.logger || Console.logger
 		end
 		
+		# @attribute [Server] The server that will process incoming queries.
 		attr :server
+		
+		# @attribute [Socket] The socket to read/write data from/to.
 		attr :socket
 		
+		# Create a new error response.
+		#
+		# @parameter query [Resolv::DNS::Message] The query that caused the error.
+		# @parameter code [Integer] The error code to return.
+		# @returns [Resolv::DNS::Message] The error response.
 		def error_response(query = nil, code = Resolv::DNS::RCode::ServFail)
 			# Encoding may fail, so we need to handle this particular case:
 			server_failure = Resolv::DNS::Message::new(query ? query.id : 0)
@@ -50,43 +54,50 @@ module Async::DNS
 			return server_failure
 		end
 		
-		def process_query(data, options)
-			@logger.debug "<> Receiving incoming query (#{data.bytesize} bytes) to #{self.class.name}..."
-			query = nil
-
+		# Process an incoming query.
+		#
+		# @parameter data [String] The incoming query data.
+		# @parameter options [Hash] Additional options to pass to the server.
+		def process_query(data, **options)
+			Console.debug "Receiving incoming query (#{data.bytesize} bytes) to #{self.class.name}..."
+			
 			begin
-				query = Async::DNS::decode_message(data)
+				query = Resolv::DNS::Message.decode(data)
 				
-				return @server.process_query(query, options)
-			rescue StandardError => error
-				@logger.error(self) { error }
+				return @server.process_query(query, **options)
+			rescue => error
+				Console.error(self, "Failed to process query!", error: error)
 				
 				return error_response(query)
 			end
 		end
 	end
 	
-	# Handling incoming UDP requests, which are single data packets, and pass them on to the given server.
+	# Handle incoming UDP requests, which are single data packets, and pass them on to the given server.
 	class DatagramHandler < GenericHandler
-		def run(task: Async::Task.current)
+		# Run the handler, processing incoming UDP requests.
+		#
+		# @parameter wrapper [Interface(:async)] The parent task to run the handler under.
+		def run(wrapper = ::IO::Endpoint::Wrapper.default)
 			while true
-				input_data, remote_address = @socket.recvmsg(UDP_TRUNCATION_SIZE)
+				input_data, remote_address = @socket.recvmsg(UDP_MAXIMUM_SIZE)
 				
-				task.async do
+				wrapper.async do
 					respond(@socket, input_data, remote_address)
 				end
 			end
 		end
 		
+		# Respond to an incoming query.
 		def respond(socket, input_data, remote_address)
 			response = process_query(input_data, remote_address: remote_address)
 			
 			output_data = response.encode
 			
-			@logger.debug "<#{response.id}> Writing #{output_data.bytesize} bytes response to client via UDP..."
+			Console.debug "Writing #{output_data.bytesize} bytes response to client via UDP...", response_id: response.id
 			
-			if output_data.bytesize > UDP_TRUNCATION_SIZE
-				@logger.warn "<#{response.id}> Response via UDP was larger than #{UDP_TRUNCATION_SIZE}!"
+			if output_data.bytesize > UDP_REASONABLE_SIZE
+				Console.warn "Response via UDP was larger than #{UDP_REASONABLE_SIZE}!", response_id: response.id
 				
 				# Reencode data with truncation flag marked as true:
 				truncation_error = Resolv::DNS::Message.new(response.id)
@@ -97,23 +108,30 @@ module Async::DNS
 			
 			socket.sendmsg(output_data, 0, remote_address)
 		rescue IOError => error
-			@logger.warn "<> UDP response failed: #{error.inspect}!"
+			Console.error(self, "UDP response failed!", error: error)
 		rescue EOFError => error
-			@logger.warn "<> UDP session ended prematurely: #{error.inspect}!"
-		rescue DecodeError
-			@logger.warn "<> Could not decode incoming UDP data!"
+			Console.error(self, "UDP session ended prematurely!", error: error)
+		rescue Resolv::DNS::DecodeError => error
+			Console.error(self, "Could not decode incoming UDP data!", error: error)
 		end
 	end
 	
+	# Handle incoming TCP requests, which are stream requests, and pass them on to the given server.
 	class StreamHandler < GenericHandler
-		def run(backlog = Socket::SOMAXCONN)
-			@socket.listen(backlog)
-			
-			@socket.accept_each do |client, address|
-				handle_connection(client)
+		# Run the handler, processing incoming TCP requests.
+		#
+		# @parameter wrapper [Interface(:async)] The parent task to run the handler under.
+		def run(wrapper = ::IO::Endpoint::Wrapper.default, **options)
+			wrapper.accept(@socket, **options) do |peer|
+				handle_connection(peer)
 			end
 		end
 		
+		# Handle an incoming TCP connection.
+		#
+		# Reads zero or more queries from the given socket and processes them.
+		#
+		# @parameter socket [Socket] The incoming TCP connection.
 		def handle_connection(socket)
 			transport = Transport.new(socket)
 			
@@ -121,16 +139,16 @@ module Async::DNS
 				response = process_query(input_data, remote_address: socket.remote_address)
 				length = transport.write_message(response)
 				
-				@logger.debug "<#{response.id}> Wrote #{length} bytes via TCP..."
+				Console.debug "Wrote #{length} bytes via TCP...", response_id: response.id
 			end
 		rescue EOFError => error
-			@logger.warn "<> Error: TCP session ended prematurely!"
+			Console.error(self, "TCP session ended prematurely!", error: error)
 		rescue Errno::ECONNRESET => error
-			@logger.warn "<> Error: TCP connection reset by peer!"
-		rescue Errno::EPIPE
-			@logger.warn "<> Error: TCP session failed due to broken pipe!"
-		rescue DecodeError
-			@logger.warn "<> Error: Could not decode incoming TCP data!"
+			Console.error(self, "TCP connection reset by peer!", error: error)
+		rescue Errno::EPIPE => error
+			Console.error(self, "TCP session failed due to broken pipe!", error: error)
+		rescue Resolv::DNS::DecodeError => error
+			Console.error(self, "Could not decode incoming TCP data!", error: error)
 		end
 	end
 end