chain-sdk 1.0.0.pre

data/lib/chain/connection.rb

@@ -0,0 +1,187 @@
+require 'json'
+require 'net/http'
+require 'net/https'
+require 'openssl'
+require 'thread'
+
+require_relative './batch_response'
+require_relative './errors'
+require_relative './version'
+
+module Chain
+  class Connection
+
+    # Parameters to the retry exponential backoff function.
+    MAX_RETRIES = 10
+    RETRY_BASE_DELAY_MS = 40
+    RETRY_MAX_DELAY_MS = 4000
+
+    NETWORK_ERRORS = [
+      InvalidRequestIDError,
+      SocketError,
+      EOFError,
+      IOError,
+      Timeout::Error,
+      Errno::ECONNABORTED,
+      Errno::ECONNRESET,
+      Errno::ETIMEDOUT,
+      Errno::EHOSTUNREACH,
+      Errno::ECONNREFUSED,
+    ]
+
+    def initialize(opts)
+      @opts = opts
+      @url = URI(@opts[:url])
+      @access_token = @opts[:access_token] || @url.userinfo
+      @http_mutex = Mutex.new
+    end
+
+    # Returns a copy of the configuration options
+    def opts
+      @opts.dup
+    end
+
+    def request(path, body = {})
+      _request_with_retries(path, body)[:body]
+    end
+
+    def batch_request(path, body = {}, &translate)
+      res = _request_with_retries(path, body)
+      body = res[:body]
+      response = res[:response]
+
+      successes = {}
+      errors = {}
+
+      body.each_with_index do |item, i|
+        if !!item['code']
+          errors[i] = APIError.new(item, response)
+        else
+          successes[i] = translate.call(item)
+        end
+      end
+
+      BatchResponse.new(
+        successes: successes,
+        errors: errors,
+        response: response,
+      )
+    end
+
+    def singleton_batch_request(path, body = {}, &translate)
+      batch = batch_request(path, body, &translate)
+
+      if batch.size != 1
+        raise "Invalid response, expected a single response object but got #{batch.items.size}"
+      end
+
+      raise batch.errors.values.first if batch.errors.size == 1
+
+      batch.successes.values.first
+    end
+
+    private
+
+    def _request_with_retries(path, body)
+      attempts = 0
+
+      begin
+        attempts += 1
+
+        # If this is a retry and not the first attempt, sleep before making the
+        # retry request.
+        sleep(backoff_delay(attempts)) if attempts > 1
+
+        _single_request(path, body)
+      rescue *NETWORK_ERRORS => e
+        raise e if attempts > MAX_RETRIES
+        retry
+      rescue APIError => e
+        raise e if attempts > MAX_RETRIES
+        retry if e.retriable?
+        raise e
+      end
+    end
+
+    def _single_request(path, body)
+      @http_mutex.synchronize do
+        # Timeout configuration
+        [:open_timeout, :read_timeout, :ssl_timeout].each do |k|
+          next unless @opts.key?(k)
+          http.send "#{k}=", @opts[k]
+        end
+
+        req = Net::HTTP::Post.new(@url.request_uri + path)
+        req['Accept'] = 'application/json'
+        req['Content-Type'] = 'application/json'
+        req['User-Agent'] = 'chain-sdk-ruby/' + Chain::VERSION
+        req.body = JSON.dump(body)
+
+        if @access_token
+          user, pass = @access_token.split(':')
+          req.basic_auth(user, pass)
+        end
+
+        response = http.request(req)
+
+        req_id = response['Chain-Request-ID']
+        unless req_id.is_a?(String) && req_id.size > 0
+          raise InvalidRequestIDError.new(response)
+        end
+
+        status = Integer(response.code)
+        parsed_body = nil
+
+        if status != 204 # No Content
+          begin
+            parsed_body = JSON.parse(response.body)
+          rescue JSON::JSONError
+            raise JSONError.new(req_id, response)
+          end
+        end
+
+        if status / 100 != 2
+          klass = status == 401 ? UnauthorizedError : APIError
+          raise klass.new(parsed_body, response)
+        end
+
+        {body: parsed_body, response: response}
+      end
+    end
+
+    private
+
+    MILLIS_TO_SEC = 0.001
+
+    def backoff_delay(attempt)
+      max = RETRY_BASE_DELAY_MS * 2**(attempt-1)
+      max = [max, RETRY_MAX_DELAY_MS].min
+      millis = rand(max) + 1
+      millis * MILLIS_TO_SEC
+    end
+
+    def http
+      return @http if @http
+
+      args = [@url.host, @url.port]
+
+      # Proxy configuration
+      if @opts.key?(:proxy_addr)
+        args += [@opts[:proxy_addr], @opts[:proxy_port]]
+        if @opts.key?(:proxy_user)
+          args += [@opts[:proxy_user], @opts[:proxy_pass]]
+        end
+      end
+
+      @http = Net::HTTP.new(*args)
+
+      @http.set_debug_output($stdout) if ENV['DEBUG']
+      if @url.scheme == 'https'
+        @http.use_ssl = true
+        @http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      end
+
+      @http
+    end
+  end
+end

data/lib/chain/constants.rb

@@ -0,0 +1,4 @@
+module Chain
+  DEFAULT_API_HOST = 'http://localhost:1999'
+  MAX_BLOCK_HEIGHT = (2 ** 63) - 1
+end

data/lib/chain/control_program.rb

@@ -0,0 +1,10 @@
+require_relative './response_object'
+
+module Chain
+  class ControlProgram < ResponseObject
+    # @!attribute [r] control_program
+    # Hex-encoded string representation of the control program.
+    # @return [String]
+    attrib :control_program
+  end
+end

data/lib/chain/errors.rb

@@ -0,0 +1,80 @@
+module Chain
+
+  # Base class for all errors raised by the Chain SDK.
+  class BaseError < StandardError; end
+
+  # InvalidRequestIDError arises when an HTTP response is received, but it does
+  # not contain headers that are included in all Chain API responses. This
+  # could arise due to a badly-configured proxy, or other upstream network
+  # issues.
+  class InvalidRequestIDError < BaseError
+    attr_accessor :response
+
+    def initialize(response)
+      super "Response HTTP header field Chain-Request-ID is unset. There may be network issues. Please check your local network settings."
+      self.response = response
+    end
+  end
+
+  # JSONError should be very rare, and will only arise if there is a bug in the
+  # Chain API, or if the upstream server is spoofing common Chain API response
+  # headers.
+  class JSONError < BaseError
+    attr_accessor :request_id
+    attr_accessor :response
+
+    def initialize(request_id, response)
+      super "Error decoding JSON response. Request-ID: #{request_id}"
+      self.request_id = request_id
+      self.response = response
+    end
+  end
+
+  # APIError describes errors that are codified by the Chain API. They have
+  # an error code, a message, and an optional detail field that provides
+  # additional context for the error.
+  class APIError < BaseError
+    RETRIABLE_STATUS_CODES = [
+      408, # Request Timeout
+      429, # Too Many Requests
+      500, # Internal Server Error
+      502, # Bad Gateway
+      503, # Service Unavailable
+      504, # Gateway Timeout
+      509, # Bandwidth Limit Exceeded
+    ]
+
+    attr_accessor :code, :chain_message, :detail, :data, :temporary, :request_id, :response
+
+    def initialize(body, response)
+      self.code = body['code']
+      self.chain_message = body['message']
+      self.detail = body['detail']
+      self.temporary = body['temporary']
+
+      self.response = response
+      self.request_id = response['Chain-Request-ID'] if response
+
+      super self.class.format_error_message(code, chain_message, detail, request_id)
+    end
+
+    def retriable?
+      temporary || (response && RETRIABLE_STATUS_CODES.include?(Integer(response.code)))
+    end
+
+    def self.format_error_message(code, message, detail, request_id)
+      tokens = []
+      tokens << "Code: #{code}" if code.is_a?(String) && code.size > 0
+      tokens << "Message: #{message}"
+      tokens << "Detail: #{detail}" if detail.is_a?(String) && detail.size > 0
+      tokens << "Request-ID: #{request_id}"
+      tokens.join(' ')
+    end
+  end
+
+  # UnauthorizedError is a special case of APIError, and is raised when the
+  # response status code is 401. This is a common error case, so a discrete
+  # exception type is provided for convenience.
+  class UnauthorizedError < APIError; end
+
+end

data/lib/chain/hsm_signer.rb

@@ -0,0 +1,91 @@
+require_relative './connection'
+require_relative './errors'
+require_relative './mock_hsm'
+require_relative './transaction'
+
+module Chain
+  class HSMSigner
+
+    def initialize
+      @xpubs_by_signer = {}
+    end
+
+    def add_key(xpub_or_key, signer_conn)
+      xpub = xpub_or_key.is_a?(MockHSM::Key) ? xpub_or_key.xpub : xpub_or_key
+      @xpubs_by_signer[signer_conn] ||= []
+      @xpubs_by_signer[signer_conn] << xpub
+      @xpubs_by_signer[signer_conn].uniq!
+    end
+
+    def sign(tx_template)
+      return tx_template if @xpubs_by_signer.empty?
+
+      @xpubs_by_signer.each do |signer_conn, xpubs|
+        tx_template = signer_conn.singleton_batch_request(
+          '/sign-transaction',
+          transactions: [tx_template],
+          xpubs: xpubs,
+        ) { |item| Transaction::Template.new(item) }
+      end
+
+      tx_template
+    end
+
+    def sign_batch(tx_templates)
+      if @xpubs_by_signer.empty?
+        # Treat all templates as if signed successfully.
+        successes = tx_templates.each_with_index.reduce({}) do |memo, (t, i)|
+          memo[i] = t
+          memo
+        end
+        BatchResponse.new(successes: successes)
+      end
+
+      # We need to work towards a single, final BatchResponse that uses the
+      # original indexes. For the next cycle, we should retain only those
+      # templates for which the most recent sign response was successful, and
+      # maintain a mapping of each template's index in the upcoming request
+      # to its original index.
+
+      orig_index = (0...tx_templates.size).to_a
+      errors = {}
+
+      @xpubs_by_signer.each do |signer_conn, xpubs|
+        next_tx_templates = []
+        next_orig_index = []
+
+        batch = signer_conn.batch_request(
+          '/sign-transaction',
+          transactions: tx_templates,
+          xpubs: xpubs,
+        ) { |item| Transaction::Template.new(item) }
+
+        batch.successes.each do |i, template|
+          next_tx_templates << template
+          next_orig_index << orig_index[i]
+        end
+
+        batch.errors.each do |i, err|
+          errors[orig_index[i]] = err
+        end
+
+        tx_templates = next_tx_templates
+        orig_index = next_orig_index
+
+        # Early-exit if all templates have encountered an error.
+        break if tx_templates.empty?
+      end
+
+      successes = tx_templates.each_with_index.reduce({}) do |memo, (t, i)|
+        memo[orig_index[i]] = t
+        memo
+      end
+
+      BatchResponse.new(
+        successes: successes,
+        errors: errors,
+      )
+    end
+
+  end
+end

data/lib/chain/mock_hsm.rb

@@ -0,0 +1,65 @@
+require_relative './client_module'
+require_relative './connection'
+require_relative './query'
+require_relative './response_object'
+
+module Chain
+  class MockHSM
+
+    class ClientModule < Chain::ClientModule
+      # @return [Key::ClientModule]
+      def keys
+        @keys_module ||= Key::ClientModule.new(client)
+      end
+
+      # @return [Connection]
+      def signer_conn
+        return @signer_conn if @signer_conn
+
+        opts = client.conn.opts
+        opts[:url] += '/mockhsm'
+
+        @signer_conn = Connection.new(opts)
+      end
+    end
+
+    class Key < ResponseObject
+      # @!attribute [r] alias
+      # User specified, unique identifier of the key.
+      # @return [String]
+      attrib :alias
+
+      # @!attribute [r] xpub
+      # Hex-encoded string representation of the key.
+      # @return [String]
+      attrib :xpub
+
+      class ClientModule < Chain::ClientModule
+
+        # Creates a key object.
+        # @param [Hash] opts
+        # @return [Key]
+        def create(opts = {})
+          Key.new(client.conn.request('mockhsm/create-key', opts))
+        end
+
+        # @param [Hash] query
+        # @return [Query]
+        def query(query = {})
+          Query.new(client, query)
+        end
+      end
+
+      class Query < Chain::Query
+        def fetch(query)
+          client.conn.request('mockhsm/list-keys', query)
+        end
+
+        def translate(obj)
+          Key.new(obj)
+        end
+      end
+    end
+
+  end
+end

data/lib/chain/query.rb

@@ -0,0 +1,50 @@
+module Chain
+  class Query
+    include ::Enumerable
+
+    # @return [Client]
+    attr_reader :client
+
+    def initialize(client, first_query)
+      @client = client
+      @first_query = first_query
+    end
+
+    # Iterate through objects in response, fetching the next page of results
+    # from the API as needed.
+    #
+    # Implements required method
+    # {https://ruby-doc.org/core/Enumerable.html Enumerable#each}.
+    # @return [void]
+    def each
+      page = fetch(@first_query)
+
+      loop do
+        if page['items'].empty? # we consume this array as we iterate
+          break if page['last_page']
+          page = fetch(page['next'])
+
+          # The second predicate (empty?) *should* be redundant, but we check it
+          # anyway as a defensive measure.
+          break if page['items'].empty?
+        end
+
+        item = page['items'].shift
+        yield translate(item)
+      end
+    end
+
+    # @abstract
+    def fetch(query)
+      raise NotImplementedError
+    end
+
+    # Overwrite to translate API response data to a different Ruby object.
+    # @abstract
+    def translate(response_object)
+      raise NotImplementedError
+    end
+
+    alias_method :all, :to_a
+  end
+end

data/lib/chain/response_object.rb

@@ -0,0 +1,81 @@
+require 'json'
+require 'time'
+
+module Chain
+  class ResponseObject
+    def initialize(raw_attribs)
+      raw_attribs.each do |k, v|
+        next unless self.class.has_attrib?(k)
+        self[k] = self.class.translate(k, v) unless v.nil?
+      end
+    end
+
+    def to_h
+      self.class.attrib_opts.keys.reduce({}) do |memo, name|
+        memo[name] = instance_variable_get("@#{name}")
+        memo
+      end
+    end
+
+    def to_json(opts = nil)
+      to_h.to_json(opts)
+    end
+
+    def [](attrib_name)
+      attrib_name = attrib_name.to_sym
+      raise KeyError.new("key not found: #{attrib_name}") unless self.class.attrib_opts.key?(attrib_name)
+
+      instance_variable_get "@{attrib_name}"
+    end
+
+    def []=(attrib_name, value)
+      attrib_name = attrib_name.to_sym
+      raise KeyError.new("key not found: #{attrib_name}") unless self.class.attrib_opts.key?(attrib_name)
+
+      instance_variable_set "@#{attrib_name}", value
+    end
+
+    # @!visibility private
+    def self.attrib_opts
+      @attrib_opts ||= {}
+    end
+
+    # @!visibility private
+    def self.attrib(attrib_name, &translate)
+      attrib_opts[attrib_name.to_sym] = {translate: translate}
+      attr_accessor attrib_name
+    end
+
+    # @!visibility private
+    def self.has_attrib?(attrib_name)
+      attrib_opts.key?(attrib_name.to_sym)
+    end
+
+    # @!visibility private
+    def self.translate(attrib_name, raw_value)
+      attrib_name = attrib_name.to_sym
+      opts = attrib_opts[attrib_name]
+      return raw_value if opts[:translate].nil?
+
+      begin
+        opts[:translate].call raw_value
+      rescue => e
+        raise TranslateError.new(attrib_name, raw_value, e)
+      end
+    end
+
+    class TranslateError < StandardError
+      attr_reader :attrib_name
+      attr_reader :raw_value
+      attr_reader :source
+
+      def initialize(attrib_name, raw_value, source)
+        super "Translation error for attrib #{attrib_name}: #{source}"
+        @attrib_name = attrib_name
+        @raw_value = raw_value
+        @source = source
+      end
+    end
+
+  end
+end