radiator 0.3.0dev2 → 0.3.0dev3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e876d3ec41bf655bc3bfc4494f22d862b71f4442
-  data.tar.gz: 65bec4acf06c108bd56ca239c9cdb660332c91a9
+  metadata.gz: 768d130d67520d82f31a14a1ce99236e5b17688b
+  data.tar.gz: 6da4c36f9d54a3de922ac26ec4ed8f70aee0def1
 SHA512:
-  metadata.gz: 9e1f48eb220ecd006335906909f88e493f7d806a4147e5443f1f9b8663c0ea941d6239bb1a610180414c514e85e9c1b084309d21cc698d0f20e730f9e292f546
-  data.tar.gz: 5e8c2376494c49046e0f18ef34b7a0e235e8230bbc5acbf76515adbced6e17de80942cdfb1214340e41c2ccecf9c4f85684b959fc00f99e65ae787b5afeb7bc0
+  metadata.gz: 2c8507502286b7d4f07c6705bbbd8fdd0bfc04d5a6187747b1573a9714bcdf58ecf5dcb12e615fa2eb3218ef91a1b934470c70c0da742f0fdb6fdb448697a12f
+  data.tar.gz: 86d7090a11dbd508db65305bccf71d3c6c1533a962cbdc66c8b4c9b42105470341274d81010fd8aed902e43085fbae3fa7f06fbd9561cfd6800c9f986a39975c

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    radiator (0.3.0dev2)
+    radiator (0.3.0dev3)
       bitcoin-ruby (= 0.0.11)
       ffi (= 1.9.18)
       hashie (~> 3.5, >= 3.5.5)

data/README.md

@@ -1,6 +1,7 @@
 [![Build Status](https://travis-ci.org/inertia186/radiator.svg?branch=master)](https://travis-ci.org/inertia186/radiator)
 [![Code Climate](https://codeclimate.com/github/inertia186/radiator/badges/gpa.svg)](https://codeclimate.com/github/inertia186/radiator)
 [![Test Coverage](https://codeclimate.com/github/inertia186/radiator/badges/coverage.svg)](https://codeclimate.com/github/inertia186/radiator)
+[![Inline docs](http://inch-ci.org/github/inertia186/radiator.svg?branch=master&style=shields)](http://inch-ci.org/github/inertia186/radiator)
 
 [radiator](https://github.com/inertia186/radiator)
 ========
@@ -29,6 +30,10 @@ Radiator is an API Client for interaction with the STEEM network using Ruby.
 
 ---
 
+Also see: [Documentation](http://www.rubydoc.info/gems/radiator)
+
+---
+
 ### Quick Start
 
 Add the gem to your Gemfile:

data/lib/radiator/api.rb

@@ -6,6 +6,130 @@ require 'openssl'
 require 'net/http/persistent'
 
 module Radiator
+  # Radiator::Api allows you to call remote methods to interact with the STEEM
+  # blockchain.  The `Api` class is a shortened name for
+  # `Radiator::DatabaseApi`.
+  #
+  # Examples:
+  #
+  #   api = Radiator::Api.new
+  #   response = api.get_dynamic_global_properties
+  #   virtual_supply = response.result.virtual_supply
+  #
+  # ... or ...
+  #
+  #   api = Radiator::Api.new
+  #   virtual_supply = api.get_dynamic_global_properties do |prop|
+  #     prop.virtual_supply
+  #   end
+  #
+  # If you need access to the `error` property, they can be accessed as follows:
+  #
+  #   api = Radiator::Api.new
+  #   response = api.get_dynamic_global_properties
+  #   if response.result.nil?
+  #     puts response.error
+  #     exit
+  #   end
+  #   
+  #   virtual_supply = response.result.virtual_supply
+  #
+  # ... or ...
+  #
+  #   api = Radiator::Api.new
+  #   virtual_supply = api.get_dynamic_global_properties do |prop, error|
+  #     if prop.nil?
+  #       puts error
+  #       exis
+  #     end
+  #     
+  #     prop.virtual_supply
+  #   end
+  #
+  # List of remote methods:
+  #
+  #   set_subscribe_callback
+  #   set_pending_transaction_callback
+  #   set_block_applied_callback
+  #   cancel_all_subscriptions
+  #   get_trending_tags
+  #   get_tags_used_by_author
+  #   get_post_discussions_by_payout
+  #   get_comment_discussions_by_payout
+  #   get_discussions_by_trending
+  #   get_discussions_by_trending30
+  #   get_discussions_by_created
+  #   get_discussions_by_active
+  #   get_discussions_by_cashout
+  #   get_discussions_by_payout
+  #   get_discussions_by_votes
+  #   get_discussions_by_children
+  #   get_discussions_by_hot
+  #   get_discussions_by_feed
+  #   get_discussions_by_blog
+  #   get_discussions_by_comments
+  #   get_discussions_by_promoted
+  #   get_block_header
+  #   get_block
+  #   get_ops_in_block
+  #   get_state
+  #   get_trending_categories
+  #   get_best_categories
+  #   get_active_categories
+  #   get_recent_categories
+  #   get_config
+  #   get_dynamic_global_properties
+  #   get_chain_properties
+  #   get_feed_history
+  #   get_current_median_history_price
+  #   get_witness_schedule
+  #   get_hardfork_version
+  #   get_next_scheduled_hardfork
+  #   get_accounts
+  #   get_account_references
+  #   lookup_account_names
+  #   lookup_accounts
+  #   get_account_count
+  #   get_conversion_requests
+  #   get_account_history
+  #   get_owner_history
+  #   get_recovery_request
+  #   get_escrow
+  #   get_withdraw_routes
+  #   get_account_bandwidth
+  #   get_savings_withdraw_from
+  #   get_savings_withdraw_to
+  #   get_order_book
+  #   get_open_orders
+  #   get_liquidity_queue
+  #   get_transaction_hex
+  #   get_transaction
+  #   get_required_signatures
+  #   get_potential_signatures
+  #   verify_authority
+  #   verify_account_authority
+  #   get_active_votes
+  #   get_account_votes
+  #   get_content
+  #   get_content_replies
+  #   get_discussions_by_author_before_date
+  #   get_replies_by_last_update
+  #   get_witnesses
+  #   get_witness_by_account
+  #   get_witnesses_by_vote
+  #   lookup_witness_accounts
+  #   get_witness_count
+  #   get_active_witnesses
+  #   get_miner_queue
+  #   get_reward_fund
+  #
+  # These methods and their characteristics are copied directly from methods
+  # marked as `database_api` in `steem-js`:
+  #
+  # https://raw.githubusercontent.com/steemit/steem-js/master/src/api/methods.js
+  #
+  # @see https://steemit.github.io/steemit-docs/#accounts
+  #
   class Api
     DEFAULT_URL = 'https://steemd.steemit.com'
     
@@ -21,10 +145,22 @@ module Radiator
       'https://rpc.steemliberator.com'
     ]
     
+    # @private
     POST_HEADERS = {
       'Content-Type' => 'application/json'
     }
     
+    # Cretes a new instance of Radiator::Api.
+    #
+    # Examples:
+    #
+    #   api = Radiator::Api.new(url: 'https://api.example.com')
+    #
+    # @param options [Hash] The attributes to initialize the Radiator::Api with.
+    # @option options [String] :url URL that points at a full node, like `https://steemd.steemit.com`.  Default from DEFAULT_URL.
+    # @option options [Array<String>] :failover_urls An array that contains one or more full nodes to fall back on.  Default from DEFAULT_FAILOVER_URLS.
+    # @option options [Logger] :logger An instance of `Logger` to send debug messages to.
+    # @option options [Boolean] :recover_transactions_on_error Have Radiator try to recover transactions that are accepted but could not be confirmed due to an error like network timeout.  Default: `true`
     def initialize(options = {})
       @user = options[:user]
       @password = options[:password]
@@ -51,20 +187,22 @@ module Radiator
       @api_options = options.dup
     end
     
-    def method_names
-      return @method_names if !!@method_names
-      
-      @method_names = Radiator::Api.methods(api_name).map do |e|
-        e['method'].to_sym
-      end
-    end
-    
-    def api_name
-      :database_api
-    end
-    
     # Get a specific block or range of blocks.
-    # 
+    #
+    # Example:
+    #
+    #   api = Radiator::Api.new
+    #   blocks = api.get_blocks(10..20)
+    #   transactions = blocks.flat_map(&:transactions)
+    #
+    # ... or ...
+    #
+    #   api = Radiator::Api.new
+    #   transactions = []
+    #   api.get_blocks(10..20) do |block|
+    #     transactions += block.transactions
+    #   end
+    #
     # @param block_number [Fixnum || Array<Fixnum>]
     # @param block the block to execute for each result, optional.
     # @return [Array]
@@ -82,7 +220,20 @@ module Radiator
       end
     end
     
-    # Find a specific block
+    # Find a specific block.
+    #
+    # Example:
+    #
+    #   api = Radiator::Api.new
+    #   block = api.find_block(12345678)
+    #   transactions = block.transactions
+    #
+    # ... or ...
+    #
+    #   api = Radiator::Api.new
+    #   transactions = api.find_block(12345678) do |block|
+    #     block.transactions
+    #   end
     # 
     # @param block_number [Fixnum]
     # @param block the block to execute for each result, optional.
@@ -95,6 +246,24 @@ module Radiator
       end
     end
     
+    # Find a specific account.
+    #
+    # Example:
+    #
+    #   api = Radiator::Api.new
+    #   ned = api.find_account('ned')
+    #   vesting_shares = ned.vesting_shares
+    #
+    # ... or ...
+    #
+    #   api = Radiator::Api.new
+    #   vesting_shares = api.find_account('ned') do |ned|
+    #     ned.vesting_shares
+    #   end
+    # 
+    # @param id [String] Name of the account to find.
+    # @param block the block to execute for each result, optional.
+    # @return [Hash]
     def find_account(id, &block)
       if !!block
         yield api.get_accounts([id]).result.first
@@ -103,6 +272,8 @@ module Radiator
       end
     end
     
+    # Returns the current base (STEEM) price in the vest asset (VESTS).
+    #
     def base_per_mvest
       api.get_dynamic_global_properties do |properties|
         total_vesting_fund_steem = properties.total_vesting_fund_steem.to_f
@@ -114,6 +285,8 @@ module Radiator
     
     alias steem_per_mvest base_per_mvest
     
+    # Returns the current base (STEEM) price in the debt asset (SBD).
+    #
     def base_per_debt
       get_feed_history do |feed_history|
         current_median_history = feed_history.current_median_history
@@ -121,17 +294,40 @@ module Radiator
         base = base.split(' ').first.to_f
         quote = current_median_history.quote
         quote = quote.split(' ').first.to_f
-
+        
         (base / quote) * steem_per_mvest
       end
     end
     
     alias steem_per_usd base_per_debt
     
+    # Stops the persistant http connections.
+    #
+    def shutdown
+      @http.shutdown if !!@http && defined?(@http.shutdown)
+      @http = nil
+    end
+    
+    # @private
+    def method_names
+      return @method_names if !!@method_names
+      
+      @method_names = Radiator::Api.methods(api_name).map do |e|
+        e['method'].to_sym
+      end
+    end
+    
+    # @private
+    def api_name
+      :database_api
+    end
+    
+    # @private
     def respond_to_missing?(m, include_private = false)
       method_names.include?(m.to_sym)
     end
     
+    # @private
     def method_missing(m, *args, &block)
       super unless respond_to_missing?(m)
       
@@ -161,39 +357,36 @@ module Radiator
             end
           end
           
-          response = request(options)
-          
           if response.nil?
-            @logger.error "No response, retrying ..."
-            backoff
-            redo
-          elsif !response.kind_of? Net::HTTPSuccess
-            @logger.warn "Unexpected response: #{response.inspect}"
-            backoff
-            redo
-          end
-          
-          response = case response.code
-          when '200'
-            body = response.body
-            response = JSON[body]
+            response = request(options)
             
-            if response.keys.include?('result') && response['result'].nil?
-              @logger.warn 'Invalid response from node, retrying ...'; nil
+            response = if response.nil?
+              @logger.error "No response, retrying ..."; nil
+            elsif !response.kind_of? Net::HTTPSuccess
+              @logger.warn "Unexpected response (code: #{response.code}): #{response.inspect}, retrying ..."; nil
             else
-              Hashie::Mash.new(response)
+              case response.code
+              when '200'
+                body = response.body
+                response = JSON[body]
+                
+                if response.keys.include?('result') && response['result'].nil?
+                  @logger.warn 'Invalid response from node, retrying ...'; nil
+                else
+                  Hashie::Mash.new(response)
+                end
+              when '400' then @logger.warn 'Code 400: Bad Request, retrying ...'; nil
+              when '502' then @logger.warn 'Code 502: Bad Gateway, retrying ...'; nil
+              when '503' then @logger.warn 'Code 503: Service Unavailable, retrying ...'; nil
+              when '504' then @logger.warn 'Code 504: Gateway Timeout, retrying ...'; nil
+              else
+                @logger.warn "Unknown code #{response.code}, retrying ..."
+                ap response
+              end
             end
-          when '400' then @logger.warn 'Code 400: Bad Request, retrying ...'; nil
-          when '502' then @logger.warn 'Code 502: Bad Gateway, retrying ...'; nil
-          when '503' then @logger.warn 'Code 503: Service Unavailable, retrying ...'; nil
-          when '504' then @logger.warn 'Code 504: Gateway Timeout, retrying ...'; nil
-          else
-            @logger.warn "Unknown code #{response.code}, retrying ..."
-            ap response
           end
         rescue Net::HTTP::Persistent::Error => e
-          @logger.warn "Unable to perform request: #{e} :: #{!!e.cause ? "cause: #{e.cause.message}" : ''}"
-          @wakka = true
+          @logger.warn "Unable to perform request: #{e} :: #{!!e.cause ? "cause: #{e.cause.message}" : ''}, retrying ..."
         rescue Errno::ECONNREFUSED => e
           @logger.warn 'Connection refused, retrying ...'
         rescue Errno::EADDRNOTAVAIL => e
@@ -211,7 +404,7 @@ module Radiator
         rescue JSON::ParserError => e
           @logger.warn "JSON Parse Error (#{e.message}), retrying ..."
         rescue => e
-          @logger.warn "Unknown exception from request ..."
+          @logger.warn "Unknown exception from request, retrying ..."
           ap e if defined? ap
         end
         
@@ -226,11 +419,6 @@ module Radiator
         backoff
       end # loop
     end
-    
-    def shutdown
-      @http.shutdown if !!@http && defined?(@http.shutdown)
-      @http = nil
-    end
   private
     def self.methods_json_path
       @methods_json_path ||= "#{File.dirname(__FILE__)}/methods.json"

data/lib/radiator/database_api.rb

@@ -1,4 +1,5 @@
 module Radiator
+  # @see Api
   class DatabaseApi < Api
   end
 end

data/lib/radiator/stream.rb

@@ -10,9 +10,17 @@ module Radiator
   #   stream.current_witness do |witness|
   #     puts witness
   #   end
+  #
+  # More importantly, full blocks, transactions, and operations can be streamed.
   class Stream < Api
+    
+    # @private
     INITIAL_TIMEOUT = 0.0200
+    
+    # @private
     MAX_TIMEOUT = 80
+    
+    # @private
     MAX_BLOCKS_PER_NODE = 100
     
     def initialize(options = {})
@@ -20,52 +28,12 @@ module Radiator
       @logger = @api_options[:logger] || Radiator.logger
     end
     
-    def api
-      @api ||= Api.new(@api_options)
-    end
-    
-    def method_names
-      @method_names ||= [
-        :head_block_number,
-        :head_block_id,
-        :time,
-        :current_witness,
-        :total_pow,
-        :num_pow_witnesses,
-        :virtual_supply,
-        :current_supply,
-        :confidential_supply,
-        :current_sbd_supply,
-        :confidential_sbd_supply,
-        :total_vesting_fund_steem,
-        :total_vesting_shares,
-        :total_reward_fund_steem,
-        :total_reward_shares2,
-        :total_activity_fund_steem,
-        :total_activity_fund_shares,
-        :sbd_interest_rate,
-        :average_block_size,
-        :maximum_block_size,
-        :current_aslot,
-        :recent_slots_filled,
-        :participation_count,
-        :last_irreversible_block_num,
-        :max_virtual_bandwidth,
-        :current_reserve_ratio,
-        :block_numbers,
-        :blocks
-      ].freeze
-    end
-    
-    def method_params(method)
-      case method
-      when :block_numbers then {head_block_number: nil}
-      when :blocks then {get_block: :head_block_number}
-      else; nil
-      end
-    end
-    
     # Returns the latest operations from the blockchain.
+    #
+    #   stream = Radiator::Stream.new
+    #   stream.operations do |op|
+    #     puts op.to_json
+    #   end
     # 
     # If symbol are passed, then only that operation is returned.  Expected
     # symbols are:
@@ -98,6 +66,13 @@ module Radiator
     #   pow
     #   custom
     #
+    # For example, to stream only votes:
+    #
+    #   stream = Radiator::Stream.new
+    #   stream.operations(:vote) do |vote|
+    #     puts vote.to_json
+    #   end
+    #
     # @param type [symbol || Array<symbol>] the type(s) of operation, optional.
     # @param start starting block
     # @param mode we have the choice between
@@ -127,7 +102,12 @@ module Radiator
     end
     
     # Returns the latest transactions from the blockchain.
-    # 
+    #
+    #   stream = Radiator::Stream.new
+    #   stream.transactions do |tx, trx_id|
+    #     puts "[#{trx_id}] #{tx.to_json}"
+    #   end
+    #
     # @param start starting block
     # @param mode we have the choice between
     #   * :head the last block
@@ -150,6 +130,11 @@ module Radiator
     end
     
     # Returns the latest blocks from the blockchain.
+    #
+    #   stream = Radiator::Stream.new
+    #   stream.blocks do |bk, num|
+    #     puts "[#{num}] #{bk.to_json}"
+    #   end
     # 
     # @param start starting block
     # @param mode we have the choice between
@@ -201,6 +186,65 @@ module Radiator
       end
     end
     
+    # Stops the persistant http connections.
+    #
+    def shutdown
+      begin
+        @api.shutdown
+      rescue => e
+        @logger.warn("Unable to shut down: #{e}")
+      end
+      
+      @api = nil
+    end
+    
+    # @private
+    def method_names
+      @method_names ||= [
+        :head_block_number,
+        :head_block_id,
+        :time,
+        :current_witness,
+        :total_pow,
+        :num_pow_witnesses,
+        :virtual_supply,
+        :current_supply,
+        :confidential_supply,
+        :current_sbd_supply,
+        :confidential_sbd_supply,
+        :total_vesting_fund_steem,
+        :total_vesting_shares,
+        :total_reward_fund_steem,
+        :total_reward_shares2,
+        :total_activity_fund_steem,
+        :total_activity_fund_shares,
+        :sbd_interest_rate,
+        :average_block_size,
+        :maximum_block_size,
+        :current_aslot,
+        :recent_slots_filled,
+        :participation_count,
+        :last_irreversible_block_num,
+        :max_virtual_bandwidth,
+        :current_reserve_ratio,
+        :block_numbers,
+        :blocks
+      ].freeze
+    end
+    
+    # @private
+    def method_params(method)
+      case method
+      when :block_numbers then {head_block_number: nil}
+      when :blocks then {get_block: :head_block_number}
+      else; nil
+      end
+    end
+  private
+    def api
+      @api ||= Api.new(@api_options)
+    end
+    
     def method_missing(m, *args, &block)
       super unless respond_to_missing?(m)
       
@@ -248,17 +292,5 @@ module Radiator
       @timeout = INITIAL_TIMEOUT if @timeout > MAX_TIMEOUT
       @timeout
     end
-    
-    # Stops the persistant http connections.
-    #
-    def shutdown
-      begin
-        @api.shutdown
-      rescue => e
-        @logger.warn("Unable to shut down: #{e}")
-      end
-      
-      @api = nil
-    end
   end
 end

data/lib/radiator/version.rb

@@ -1,3 +1,3 @@
 module Radiator
-  VERSION = '0.3.0dev2'
+  VERSION = '0.3.0dev3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: radiator
 version: !ruby/object:Gem::Version
-  version: 0.3.0dev2
+  version: 0.3.0dev3
 platform: ruby
 authors:
 - Anthony Martin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-29 00:00:00.000000000 Z
+date: 2017-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler