flareon 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0608731021754226390a8859a3dea917b95f5fb25a3018cce0983ce3ba930fe1'
-  data.tar.gz: 205aaf7ccaa2402e8f487d9ef9cda4c3083370536ab6947c98af433f0125c543
+  metadata.gz: 1e500b30389aad18ef70b1c0b15fcd6ea7c3fe0d629eb51ef53f0e192b6c5758
+  data.tar.gz: 53721d0eb570b20d56b12e036dfd148f0212596d97193c2356662c6f76774d2c
 SHA512:
-  metadata.gz: 7cf81f22465686432fd86642b503c22f8871961b42607a57bb7784c2e4167ad561022536420f0e9edb5a61fc9d64f157cc95d321e970c55eba1effbf76506235
-  data.tar.gz: d15903463d8ce1e44507c0deafda46f3761fc0c149c8119c1cd7fef894c5ebd6bdbf324040a74e78e1ab9e4ce3c84eee45cb267e6029c0293ea4f31b680f6df1
+  metadata.gz: 9efdbe774d2f0ceeeb533e118dccb3af36b3c21728cdf48a0acca17b3294016793fabece71a9ffc513bdfcaaa2446a4265ddba7d66b6da07f904c29ba6c94c2f
+  data.tar.gz: 074e44b83f6fc9301fcc36886393353a9344de613d0390b751b3b5ddb8f7c1cb2f2c712d5532d4f99e62024160271579287155bc04ca8a960a89728795bfa6c8

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    flareon (1.0.0)
+    flareon (1.0.1)
       httparty (~> 0.16.2)
 
 GEM

data/README.md

@@ -1,5 +1,11 @@
 # Flareon
-> A cloudflare DNS resolver client library.
+> A cloudflare DNS over HTTPs resolver client library.
+
+<p align="center">
+  <img alt="Pokemon, gott'a catch 'em all!" src="flareon.png"/>
+<p>
+
+Cloudflare’s DNS over HTTPs [endpoint](https://cloudflare-dns.com) supports [JSON format](https://developers.cloudflare.com/1.1.1.1/dns-over-https/json-format/) for querying [DNS](https://en.wikipedia.org/wiki/Domain_Name_System) data -- and this gem helps to use it!
 
 ## Installation
 
@@ -7,8 +13,9 @@
 
 ## Usage
 
+Perform a basic DNS query over HTTPs:
 ```ruby
-Flareon.resolve("google.com")
+Flareon.query("google.com")
 # => {
 #     "Status"=>0,
 #     "TC"=>false,
@@ -19,11 +26,71 @@ Flareon.resolve("google.com")
 #     "Question"=>[{"name"=>"google.com.", "type"=>1}],
 #     "Answer"=>[{"name"=>"google.com.", "type"=>1, "TTL"=>83, "data"=>"172.217.1.46"}]
 #    }
+```
+
+Get the raw JSON response:
+```ruby
+json = Flareon.query("google.com", json: true)
+```
+
+Specify [DNS query type](https://en.wikipedia.org/wiki/List_of_DNS_record_types):
+```ruby
+Flareon.query("google.com", type: "A")
+Flareon.query("google.com", type: "AAAA")
+Flareon.query("google.com", type: "MX")
+```
 
+The `nslookup` method is an alias for the `query` method:
+```ruby
+Flareon.nslookup("google.com")
+```
+
+The `dig` method is an alias for the `query` method:
+```ruby
+Flareon.dig("google.com")
+```
+
+Check if a given name is resolvable:
+```ruby
 Flareon.resolve?("google.com")
 # => true
 ```
 
+Resolve a given domain to an IP address:
+```ruby
+Flareon.resolve("google.com")
+# => "172.217.1.46"
+```
+
+Resolve a given domain to an IPv4 address:
+```ruby
+Flareon.resolve("google.com")
+Flareon.resolve("google.com", type: "A")
+Flareon.resolve("google.com", type: 1)
+```
+
+Resolve a given domain to an IPv6 address:
+```ruby
+Flareon.resolve("google.com", type: "AAAA")
+Flareon.resolve("google.com", type: 28)
+```
+
+Resolve a give domain to all IPv4 and IPv6 addresses:
+```ruby
+ip_address = Flareon.resolve_all("google.com")
+
+# or
+
+Flareon.resolve_all("google.com") do |ip_address|
+  # do something with each ip_address
+  puts ip_address
+end
+```
+
+## Inspiration
+
+Saw [hrbrmstr](https://github.com/hrbrmstr) working on [dnsflare](https://github.com/hrbrmstr/dnsflare) and wanted something similiar in Ruby.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/flareon.rb

@@ -2,11 +2,35 @@ require "httparty"
 require "flareon/version"
 
 module Flareon
+  # Base URL for cloudflare's DNS over HTTPs endpoint.
   URL    = "https://cloudflare-dns.com/dns-query".freeze
+  # Special *ct* value to add to every query.
   CT     = "application/dns-json".freeze
+  # Header sent in every query.
   HEADER = {'Content-Type': 'application/json'}
-  
-  def self.resolve(name, type: "A", json: false)
+
+  # Query the DNS over HTTPs endpoint.
+  # 
+  # == IPv4 DNS query
+  #   result = Flareon.query("google.com")
+  #   # or
+  #   result = Flareon.query("google.com", type: "A")
+  #   # or
+  #   result = Flareon.query("google.com", type: 1)
+  #
+  # == IPv6 DNS query
+  #   result = Flareon.query("google.com", type: "AAAA") 
+  #   # or
+  #   result = Flareon.query("google.com", type: 28)
+  #
+  # == Mail exchange record query
+  #   result = Flareon.query("google.com", type: "MX") 
+  #   # or
+  #   result = Flareon.query("google.com", type: 15)
+  # == Raw JSON response ( not parsed )
+  #   result = Flareon.query("google.com", json: true)
+  #
+  def self.query(name, type: "A", json: false)
     buffer = StringIO.new
     query  = { name: name, type: type, ct: CT }
     response = HTTParty.get(URL, stream_body: true, query: query, headers: HEADER) do |fragment|
@@ -24,10 +48,80 @@ module Flareon
     end
   end
 
+  # Alias the query method with both nslookup and dig.
+  # This keeps a similiar API to: github.com/hrbrmstr/dnsflare
+  class << self
+    alias nslookup query
+    alias dig query 
+  end
+
+  # Check if a given domain name is resolvable to an IPv4 or IPv6 address.
   def self.resolve?(name, type: "A", json: false)
-    Flareon.resolve(name, type: type, json: json)
-    return true
+    Flareon.resolve_all(name) do |ip|
+      return true
+    end
+    false
   rescue
     return false
   end
+
+  # Resolve a given domain name to a IP address. 
+  def self.resolve(name, type: "A")
+    unless type == "A" || type == "AAAA"
+      raise "Unsupported resolve type!" 
+    end
+    resp = Flareon.query(name, type: type)
+    if resp["Status"] == 0
+      return resp["Answer"][0]["data"]
+    else
+      raise resp 
+    end 
+  end
+
+  # Resolve a given domain name to all addresses (IPv4/IPv6). 
+  # 
+  # == Resolve all IP addresses
+  #   results = Flareon.resolve_all("google.com")
+  #   # or
+  #   results = Flareon.resolve_all("google.com", type: :both)
+  #   # or
+  #   Flareon.resolve_all("google.com") do |ip_address|
+  #     # do something with the ip_address
+  #     puts ip_address
+  #   end
+  # == Resolve all IPv4 addresses
+  #   results = Flareon.resolve_all("google.com", type: 1)
+  #   # or
+  #   results = Flareon.resolve_all("google.com", type: "A")
+  #
+  def self.resolve_all(name, type: :both)
+    unless type == "A" || type == "AAAA" || type == :both
+      raise "Unsupported resolve type!" 
+    end
+    results = [] unless block_given?
+    case type
+    when "A", "AAAA"
+      resp = Flareon.query(name, type: type)
+      if resp["Status"] == 0
+        resp["Answer"].each do |answer|
+          if block_given?
+            yield answer["data"]
+          else
+            results << answer["data"]
+          end
+        end
+      else
+        raise resp 
+      end
+    when :both
+      if block_given?
+        Flareon.resolve_all(name, type: "A")    { |ip| yield ip }
+        Flareon.resolve_all(name, type: "AAAA") { |ip| yield ip } 
+      else
+        Flareon.resolve_all(name, type: "A")    { |ip| results << ip }
+        Flareon.resolve_all(name, type: "AAAA") { |ip| results << ip }
+      end
+    end
+    return results unless block_given?
+  end
 end

data/lib/flareon/version.rb

@@ -1,3 +1,3 @@
 module Flareon
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flareon
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Kent 'picat' Gruber
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-04-01 00:00:00.000000000 Z
+date: 2018-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -86,6 +86,7 @@ files:
 - bin/setup
 - examples/debug.rb
 - flareon.gemspec
+- flareon.png
 - lib/flareon.rb
 - lib/flareon/version.rb
 homepage: https://github.com/picatz/flareon