neverbounce-cli 1.0.0

data/lib/never_bounce/cli/script/request_maker.rb

@@ -0,0 +1,169 @@
+
+require "never_bounce/cli/script/table"
+require "never_bounce/cli/user_config"
+
+require_relative "meaningful"
+
+module NeverBounce; module CLI; module Script
+  # An API request maker script base class.
+  class RequestMaker < Meaningful
+    attr_writer :api_key, :request, :request_curl, :response, :server_raw, :session, :user_config
+
+    envar "API_KEY*", "API key", ["2ed45186c72f9319dc64338cdf16ab76b44cf3d1"]
+    envar "API_URL", "Custom API URL", ["https://staging-api.isp.com/v5"]
+    envar "CURL", "Print cURL request and exit", ["y", default: "N"]
+    envar "RAW", "Print raw response body", ["y", default: "N"]
+
+    # Shared envar defaults.
+    SHARED_ENVARS = {
+      "AUTO_START" => ["Start processing the job immediately after parsing", ["y", "n"]],
+      "RUN_SAMPLE" => ["Run this job as a sample", ["y", "n"]],
+    }
+
+    # @!attribute api_key
+    # @return [String]
+    def api_key
+      @api_key ||= env["API_KEY"] || user_config.api_key or raise UsageError, "API key not given, use `API_KEY=`"
+    end
+
+    # @!attribute api_url
+    # @return [String]
+    def api_url
+      @api_url ||= igetset(:api_url) do
+        env["API_URL"] || user_config.api_url
+      end
+    end
+
+    # An instance of <tt>API::Request::Base</tt> successor.
+    # @abstract
+    # @!attribute request
+    # @return [Object]
+    def request
+      @request or raise NotImplementedError, "Redefine `request` in your class: #{self.class}"
+    end
+
+    # Request's cURL representation. Default is <tt>request.to_curl</tt>
+    # @!attribute request_curl
+    # @return [Array]
+    def request_curl
+      require_attr(:request).to_curl
+    end
+
+    # An <tt>API::Response::Base</tt> successor instance.
+    # @!attribute response
+    # @return [Object]
+    def response
+      @response ||= require_attr(:session).response
+    end
+
+    # Raw server response text. Default is <tt>session.server_raw</tt>.
+    # This attribute is used by <tt>RAW=y</tt> mode only.
+    # @!attribute server_raw
+    # @return [String]
+    def server_raw
+      @server_raw ||= require_attr(:session).server_raw
+    end
+
+    # An instance of <tt>API::Session</tt> built around {#request}.
+    # @!attribute session
+    # @return [Object]
+    def session
+      @session ||= API::Session.new(request: require_attr(:request))
+    end
+
+    # @!attribute user_config
+    # @return [UserConfig]
+    def user_config
+      @user_config ||= UserConfig.new
+    end
+
+    #--------------------------------------- Misc
+
+    # Extract response's value according to a heading spec.
+    #
+    #   get_table_value(reasponse, ["ID", :id, :right])
+    def get_table_value(r, hspec)
+      if (m = hspec[1]).is_a? Proc
+        m.(r)
+      else
+        r.public_send(m)
+      end
+    end
+    private :get_table_value
+
+    # "Inspect or nil" -- format a scalar for table-friendly output.
+    #
+    #   inil(5)     # => "5"
+    #   inil(nil)   # => "-"
+    #
+    # @return [String]
+    def inil(v)
+      v.nil?? "-" : v.inspect
+    end
+    private :inil
+
+    # Print request as a ready-to-run cURL command. Return 0.
+    def print_curl_request
+      stdout.puts "curl #{request_curl.map(&:shellescape).join(' ')}"
+      0
+    end
+
+    # Print error response as a standard table. Return 1.
+    #
+    #   return print_error_response if response_error?
+    def print_error_response
+      "ErrorResponse".tap do |label|
+        headings = [
+          ["Status", :status, :center],
+          ["Message", :message],
+          ["ExecTime", :execution_time, :right],
+        ]
+
+        table = Table.new(
+          headings: headings.map { |ar| ar[0] },
+          rows: [headings.map { |ar| get_table_value(response, ar) }],
+        ).align!(headings)
+
+        stdout.puts "\n#{label}:"
+        stdout.puts table
+      end
+
+      1
+    end
+
+    # Print raw response. Return 0.
+    #
+    #   return print_raw_response if env_truthy? "RAW"
+    def print_server_raw
+      stdout.puts server_raw
+      0
+    end
+
+    #--------------------------------------- Main
+
+    def slim_main1
+      # Perform common boilerplate actions.
+      return print_curl_request if env_truthy? "CURL"
+
+      # Any of these, unless during tests, touch `response`, which triggers the actual request.
+      return print_server_raw if env_truthy? "RAW"
+      return print_error_response if response.error?
+
+      call_slim_main(0)
+    end
+  end
+end; end; end
+
+#
+# Implementation notes:
+#
+# * See `def request` for a cool testing hack: `@request || raise`.
+#   It makes it possible to test abstract's class functionality without having to create successors
+#   just to stub an attribute.
+# * Column output order in all scripts is logical+alphabetical.
+#   Most meaningful attributes are output first, the rest are loosely grouped based on decreasing
+#   importance.
+# * We deliberately don't use `OptionParser` in final scripts, using "meta-documented" env variables
+#   instead. See `envar` and stuff.
+# * `manifest` is an instance method to simplify its usage in output code. `self.class.manifest` is
+#   clunky and thus less smart.

data/lib/never_bounce/cli/script/single_check.rb

@@ -0,0 +1,146 @@
+
+require "neverbounce"
+
+require_relative "request_maker"
+
+module NeverBounce; module CLI; module Script
+  class SingleCheck < RequestMaker
+    attr_writer :address_info, :email, :credits_info, :timeout
+
+    envar "ADDRESS_INFO", "Request additional address info", ["y", "n"]
+    envar "EMAIL*", "E-mail to check", ["alice@isp.com", "bob.smith+1@domain.com"]
+    envar "CREDITS_INFO", "Request additional credits info", ["y", "n"]
+    envar "TIMEOUT", "Timeout in seconds to verify the address", ["5"]
+
+    # @return [true]
+    # @return [false]
+    # @return [nil]
+    def address_info
+      igetset(:address_info) do
+        if env.has_key?(k = "ADDRESS_INFO")
+          env_truthy?(k)
+        end
+      end
+    end
+
+    # @return [true]
+    # @return [false]
+    # @return [nil]
+    def credits_info
+      igetset(:credits_info) do
+        if env.has_key?(k = "CREDITS_INFO")
+          env_truthy?(k)
+        end
+      end
+    end
+
+    def email
+      @email ||= env[k = "EMAIL"] or raise UsageError, "E-mail address not given, use `#{k}=`"
+    end
+
+    # An <tt>API::Request::SingleCheck</tt>.
+    # @!attribute request
+    # @return [Object]
+    def request
+      @request ||= API::Request::SingleCheck.new({
+        address_info: address_info,
+        api_key: api_key,
+        credits_info: credits_info,
+        email: email,
+        timeout: timeout,
+      })
+    end
+
+    def timeout
+      igetset(:timeout) do
+        if (v = env["TIMEOUT"])
+          begin
+            Integer(v)
+          rescue ArgumentError => e
+            raise UsageError, e.message
+          end
+        end
+      end
+    end
+
+    #--------------------------------------- Manifest
+
+    # @!attribute manifest
+    # @return [Manifest]
+    def manifest
+      @manifest ||= Manifest.new(
+        name: "nb-single-check",
+        function: "Check a single e-mail",
+        cmdline: "[options] [VAR1=value] [VAR2=value] ...",
+      )
+    end
+
+    #--------------------------------------- Main
+
+    # @return [Integer]
+    def slim_main
+      "Response".tap do |label|
+        headings = [
+          ["Result", :result, :center],
+          [
+            "Flags",
+            ->(r) { r.flags.sort.join("\n") },
+          ],
+          ["SuggCorr", :suggested_correction],
+
+          ["ExecTime", :execution_time, :right],
+        ]
+
+        table = Table.new(
+          headings: headings.map { |ar| ar[0] },
+          rows: [headings.map { |ar| get_table_value(response, ar) }],
+        ).align!(headings)
+
+        stdout.puts "\n#{label}:"
+        stdout.puts table
+      end
+
+      response.address_info? and "AddressInfo".tap do |label|
+        headings = [
+          ["Addr", :addr],
+          ["Alias", :alias],
+          ["Domain", :domain],
+          ["FQDN", :fqdn],
+          ["Host", :host],
+          ["NormEmail", :normalized_email],
+          ["OrigEmail", :original_email],
+          ["Subdomain", :subdomain],
+          ["TLD", :tld],
+        ]
+
+        table = Table.new(
+          headings: headings.map { |ar| ar[0] },
+          rows: [headings.map { |ar| get_table_value(response.address_info, ar) }],
+        ).align!(headings)
+
+        stdout.puts "\n#{label}:"
+        stdout.puts table
+      end # response.address_info?
+
+      response.credits_info? and "CreditsInfo".tap do |label|
+        headings = [
+          ["FreeRmn", :free_credits_remaining, :right],
+          ["FreeUsed", :free_credits_used, :right],
+          (["MonthlyUsage", :monthly_api_usage, :right] if response.credits_info.monthly?),
+          (["PaidRmn", :paid_credits_remaining, :right] if response.credits_info.paid?),
+          (["PaidUsed", :paid_credits_used, :right] if response.credits_info.paid?),
+        ].compact
+
+        table = Table.new(
+          headings: headings.map { |ar| ar[0] },
+          rows: [headings.map { |ar| get_table_value(response.credits_info, ar) }],
+        ).align!(headings)
+
+        stdout.puts "\n#{label}:"
+        stdout.puts table
+      end # response.credits_info?
+
+      0
+    end
+  end
+end; end; end

data/lib/never_bounce/cli/script/table.rb

@@ -0,0 +1,43 @@
+
+require "terminal-table"
+
+module NeverBounce; module CLI; module Script
+  # Our custom table class.
+  class Table < Terminal::Table
+    # Align table rows according to headings spec.
+    #
+    #   headings = [
+    #     ["Status", :status],
+    #     ["Completed", :completed, :right],
+    #     ["Processing", :processing, :right],
+    #   ]
+    #
+    #   table = Table.new(headings: ..., rows: ...).align!(headings)
+    #   puts table
+    #
+    # NOTE: Invoke <b>after</b> adding row data.
+    #
+    # @return [self]
+    def align!(headings)
+      headings.each_with_index do |ar, i|
+        if (v = ar[2])
+          align_column(i, v)
+        end
+      end
+
+      self
+    end
+
+    # Center-align headings by default.
+    # @return [void]
+    def headings=(ar)
+      super(ar.map do |item|
+        if item.is_a? String
+          {value: item, alignment: :center}
+        else
+          item
+        end
+      end)
+    end
+  end
+end; end; end

data/lib/never_bounce/cli/user_config/file_content.rb

@@ -0,0 +1,66 @@
+
+require "yaml"
+
+require "never_bounce/cli/feature/basic_initialize"
+
+require_relative "../user_config"
+
+module NeverBounce; module CLI; class UserConfig
+  # User's configuration file content.
+  # @see #filename
+  # @see UserConfig
+  # @see CLI::Feature::BasicInitialize
+  class FileContent
+    CLI::Feature::BasicInitialize.load(self)
+
+    attr_writer :body, :body_hash, :env, :filename
+
+    # YAML configuration, source text.
+    # @!attribute body
+    # @return [String]
+    def body
+      @body ||= begin
+        File.read(filename)
+      rescue Errno::ENOENT    # Missing file is okay, let other exceptions manifest.
+        ""
+      end
+    end
+
+    # YAML configuration, parsed.
+    # @!attribute body_hash
+    # @return [Hash]
+    def body_hash
+      @body_hash ||= body.to_s.empty?? {} : YAML.load(body)
+    end
+
+    # A copy of environment for read purposes. Default is <tt>ENV.to_h</tt>.
+    # @return [Hash]
+    def env
+      @env ||= ENV.to_h
+    end
+
+    # Configuration filename. Default is <tt>$HOME/.neverbounce.yml</tt>.
+    # @return [String]
+    def filename
+      @filename ||= File.join(env["HOME"], ".neverbounce.yml")
+    end
+
+    #---------------------------------------
+
+    # Fetch a value.
+    #
+    #   config_file["api_key"]
+    #   config_file[:api_key]   # Same as above.
+    def [](k)
+      body_hash[k.to_s]
+    end
+
+    # <tt>true</tt> if key is set.
+    #
+    #   has_key?("api_key")
+    #   has_key?(:api_key)      # Identical to the previous one.
+    def has_key?(k)
+      body_hash.has_key? k.to_s
+    end
+  end
+end; end; end

data/lib/never_bounce/cli/user_config.rb

@@ -0,0 +1,51 @@
+
+require "never_bounce/cli/feature/eigencache"
+
+module NeverBounce; module CLI
+  # User's configuration values.
+  # @see UserConfig::FileContent
+  class UserConfig
+    require_relative "user_config/file_content"
+
+    CLI::Feature::BasicInitialize.load(self)
+    CLI::Feature::Eigencache.load(self)
+
+    attr_writer :api_key, :api_url
+
+    # API key.
+    # @return [String]
+    def api_key
+      @api_key ||= fc[:api_key]
+    end
+
+    # API URL.
+    # @return [String]
+    def api_url
+      @api_url ||= fc[:api_url]
+    end
+
+    #---------------------------------------
+
+    # @!attribute fc
+    # @return [FileContent]
+    def fc
+      _cache[:fc] ||= FileContent.new
+    end
+
+    def fc=(obj)
+      _cache[:fc] = obj
+    end
+
+    # "Touch" all attributes by loading them.
+    # @return [self]
+    def touch
+      api_key; api_url
+      self
+    end
+  end
+end; end
+
+#
+# Implementation notes:
+#
+# * `api_url` has got no default here, it isn't a config responsibility.