yolodice-client 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a3f9c18f4f343eb90b4b79ac9ea29947aa37e8cc
+  data.tar.gz: 79d786b072ff58a346805ce4c6ac57bf9af8f3f8
+SHA512:
+  metadata.gz: 4cd29705d3668b1fc29489fdc255efeb7b364085325cf482eb9e641aa95b7c242be4b7f90a36e30423029c120ce32658a1d6632999852975f21968f2b9b554db
+  data.tar.gz: 5af05d6cb39c7693ff7df81040a936cdad27820ef5a82161e1257c22b23d152d05055bd658ee951f233f762a384ea822d1799a7206c3957cb051ffdf43642878

data/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2017 Ethan White (YOLOdice.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.

data/README.md

@@ -0,0 +1,116 @@
+YOLOdice API Client for Ruby
+============================
+
+[YOLOdice](https://yolodice.com) is a simple online Bitcoin game you can play against the house. The game relies on a pseudorandom number generator that returns bet results used to determine if bets placed by players win or lose.
+
+This Ruby library contains a simple client that connects to the YOLOdice API endpoint:
+
+* client connects over secure SSL over TCP transport layer,
+* supports authentication,
+* handles any server-side methods via `method_missing` mechanism.
+
+Additional resources:
+
+* [dev.yolodice.com](https://dev.yolodice.com) Official YOLOdice API documentation,
+* [yolodice.com](https://yolodice.com) The YOLOdice site (take a look at [FAQ](https://yolodice.com/#faq)).
+
+## Installation
+
+    gem install yolodice-client
+
+
+## Usage
+
+Require the gem in your scripts:
+
+    require 'yolodice_client'
+
+
+## Generating API keys
+
+YOLOdice API requires authentication for most of it's methods. A Bitcoin key/address will be required to setup the API key and authenticate. Here is one way to do this:
+
+1. Generate an Bitcoin public and private key:
+
+    require 'bitcoin'
+
+    btc_key = Bitcoin::Key.generate
+    auth_key = btc_key.to_base58  # this is your secret code, store it in a secure place
+    auth_addr = btc_key.addr      # paste this in your YD settings as a new key
+
+2. Go to [YOLOdice account Settings](https://yolodice.com/#settings), create a new key and paste the `auth_addr` generated above. Set permissions as you wish.
+3. Use `auth_key` in your code to authenticate.
+
+Just a quick note — this address is used ONLY to authenticate. No coins will be ever sent to it.
+
+
+## Connecting
+
+    yd = YolodiceClient.new
+    yd.connect
+    yd.authenticate auth_key
+
+It's important to authenticate immediately after connecting. Otherwise the connection will be closed by the server.
+
+The client automatically sends a `ping` requests to the server every 30 seconds to prevent the connection from timing out.
+
+
+## Logging and debugging
+
+To preview the actuall messages sent back and forth you could provide your own logger object and set log level to `DEBUG` like this:
+
+    yd = YolodiceClient.new
+    logger = Logger.new STDERR
+    logger.level = Logger::DEBUG
+    yd.logger = logger
+
+    yd.connect
+    yd.authenticate auth_key
+
+This would result in the output similar to this:
+
+    DEBUG -- : Connecting to api.yolodice.dev:4444 over SSL
+    INFO  -- : Connected to api.yolodice.dev:4444
+    DEBUG -- : Listening thread started
+    DEBUG -- : Pinging thread started
+    DEBUG -- : Calling remote method generate_auth_challenge()
+    DEBUG -- : >>> {"id":1,"method":"generate_auth_challenge"}
+    DEBUG -- : <<< {"id":1,"result":"yd_login_26vEyvUUdgUy"}
+
+    DEBUG -- : Calling remote method auth_by_address({:address=>"n3kmufwdR3Zzgk3k6NYeeLBxB9SpHKe5Tc", :signature=>"IB5ITZHQZoApdXhUMGFFZ9AG4OtTw85jdaPMSVYNpOayEAG5LK9bsPhtCjwPEjDy/YDHqKk6gf1+aLzg0B63Qfk="})
+    DEBUG -- : >>> {"id":2,"method":"auth_by_address","params":{"address":"n3kmufwdR3Zzgk3k6NYeeLBxB9SpHKe5Tc","signature":"IB5ITZHQZoApdXhUMGFFZ9AG4OtTw85jdaPMSVYNpOayEAG5LK9bsPhtCjwPEjDy/YDHqKk6gf1+aLzg0B63Qfk="}}
+    DEBUG -- : <<< {"id":2,"result":{"id":1,"name":"sdafasfuiafu","created_at":1470085899.0356,"roles":["admin"]}}
+
+## Conventions, return values, errors
+
+By default whenever any Bitcoin amount is sent or received from the server, it is passed as an Integer with the amount of satoshis. Using this convention 1 BTC would be represented as an integer value or `100_000_000`.
+
+Whenever server responds with an Object, this client returns a Hash with keys being Strings.
+
+There are two error classes:
+
+* `YolodiceClient::Error` that inherits from `StandardError` and is used for errors thrown by the client itself,
+* `YolodiceClient::RemoteError` that inherits from `StandardError` that is used to pass errors from the remote server,
+* any errors from underlaying `TCPSocket` or `SSLSocket` are passed through.
+
+`RemoteError` has two extra attributes: `code` and `data` that are mapped to values in the error object returned from the server.
+
+## Another example
+
+Here is a script that connects to the server, authenticates, fetches user data, rolls a few 50% chance bets and reads user data again (make sure to use your own credential):
+
+    require 'yolodice_client'
+    require 'pp'
+
+    auth_key = 'cPFVHENWNjs5UKNXXynDSWiRkBEph8hcrjHKkXK5SW9QHxx7i4jC'
+    yd = YolodiceClient.new
+    yd.connect
+    user = yd.authenticate auth_key
+    user_data = yd.read_user_data selector: {id: user['id']}
+    puts "Your account balance is: #{user_data['balance']} satoshis."
+    10.times do
+      b = yd.create_bet attrs: {amount: 100, range: 'lo', target: 500000}
+      puts "Bet profit: #{b['profit']}"
+    end
+    user_data = yd.read_user_data selector: {id: user['id']}
+    puts "Your account balance is: #{user_data['balance']} satoshis."

data/lib/yolodice_client.rb

@@ -0,0 +1,220 @@
+require 'socket'
+require 'openssl'
+require 'thread'
+require 'logger'
+require 'json'
+require 'bitcoin'
+
+##
+# YolodiceClient is a simple JSON-RPC 2.0 client that connects to YOLOdice.com.
+
+class YolodiceClient
+
+  # <tt>OpenSSL::SSL::SSLSocket</tt> object created by the <tt>connect</tt> method.
+  attr_reader :connection
+
+  ##
+  # Initializes the client object. The method accepts an option hash with the following keys:
+  # * <tt>:host</tt> -- defaults to <tt>api.yolodice.com</tt>
+  # * <tt>:port</tt> -- defaults to <tt>4444</tt>
+  # * <tt>:ssl</tt> -- if SSL should be used, defaults to <tt>true</tt>
+
+  def initialize opts={}
+    @opts = {
+      host: 'api.yolodice.com',
+      port: 4444,
+      ssl: true
+    }.merge opts
+
+    @req_id_seq = 0
+    @current_requests = {}
+    @receive_queues = {}
+    @thread_semaphore = Mutex.new
+  end
+
+
+  ##
+  # Sets a logger for the object.
+
+  def logger=(logger)
+    @log = logger
+  end
+
+
+  ##
+  # Connects to the host.
+
+  def connect
+    @connection = if @opts[:ssl]
+                    log.debug "Connecting to #{@opts[:host]}:#{@opts[:port]} over SSL"
+                    socket = TCPSocket.open @opts[:host], @opts[:port]
+                    ssl_socket = OpenSSL::SSL::SSLSocket.new socket
+                    ssl_socket.sync_close = true
+                    ssl_socket.connect
+                    ssl_socket
+                  else
+                    log.debug "Connecting to #{@opts[:host]}:#{@opts[:port]}"
+                    TCPSocket.open @opts[:host], @opts[:port]
+                  end
+
+    log.info "Connected to #{@opts[:host]}:#{@opts[:port]}"
+    # Start a thread that keeps listening on the socket
+    @listening_thread = Thread.new do
+      log.debug 'Listening thread started'
+      loop do
+        msg = @connection.gets
+        log.debug{ "<<< #{msg}" }
+        message = JSON.parse msg
+        if message['id'] && (message.has_key?('result') || message.has_key?('error'))
+          # definitealy a response
+          callback = @thread_semaphore.synchronize{ @current_requests.delete message['id'] }
+          raise Error, "Unknown id in response" unless callback
+          if callback.is_a? Integer
+            # it's a thread
+            @receive_queues[callback] << message
+          elsif callback.is_a? Proc
+            # A thread pool would be better.
+            Thread.new do
+              callback.call message
+            end
+          end
+        else
+          if message['id']
+            # It must be a request from the server. We do not support it yet.
+          else
+            # No id, it must be a notification then. This can be implemented later.
+          end
+        end
+      end
+    end
+    # Start a thread that pings the server
+    @pinging_thread = Thread.new do
+      log.debug 'Pinging thread started'
+      loop do
+        sleep 30
+        call :ping
+      end
+    end
+    true
+  end
+
+
+  ##
+  # Closes connection to the host.
+
+  def close
+    log.debug "Closing connection"
+    # Stop threads
+    @connection.close
+    @listening_thread.exit
+    @pinging_thread.exit
+    true
+  end
+
+
+  ##
+  # Authenticates the connection by requesting a challenge message, signing it and sending the response back.
+  # 
+  # Parameters:
+  # * <tt>auth_key</tt> -- Base58 encoded private key for the API key
+  #
+  # Returns
+  # * <tt>false</tt> if authentication fails,
+  # * user object (Hash with public user attributes) when authentication succeeds.
+
+  def authenticate auth_key
+    auth_key = Bitcoin::Key.from_base58(auth_key) unless auth_key.is_a?(Bitcoin::Key)
+    challenge = generate_auth_challenge
+    user = auth_by_address address: auth_key.addr, signature: auth_key.sign_message(challenge)
+    raise Error, "Authentication failed" unless user
+    log.debug "Authenticated as user #{user['name']}(#{user['id']})"
+    user
+  end
+
+
+  ##
+  # Calls an arbitrary method on the server.
+  #
+  # Parameters:
+  # * <tt>method</tt> -- method name,
+  # * <tt>*arguments</tt> -- any arguments for the method, will be passed as the <tt>params</tt> object (optional),
+  # * <tt>&blk</tt> -- a callback (optional) to be called upon receiving a response for async calls. The callback will receive the response object.
+
+  def call method, *arguments, &blk
+    raise Error, "Not connected" unless @connection && !@connection.closed?
+    params = if arguments.count == 0
+               nil
+             elsif arguments.is_a?(Array) && arguments[0].is_a?(Hash)
+               arguments[0]
+             else
+               arguments
+             end
+    id = @thread_semaphore.synchronize{ @req_id_seq += 1 }
+    request = {
+      id: id,
+      method: method
+    }
+    request[:params] = params if params != nil
+    if blk
+      @thread_semaphore.synchronize{ @current_requests[id] = blk }
+      log.debug{ "Calling remote method #{method}(#{params.inspect if params != nil}) with an async callback" }
+      log.debug{ ">>> #{request.to_json}" }
+      @connection.puts request.to_json
+      nil
+    else
+      # a regular blocking request
+      @thread_semaphore.synchronize{ @current_requests[id] = Thread.current.object_id }
+      queue = (@receive_queues[Thread.current.object_id] ||= Queue.new)
+      log.debug{ "Calling remote method #{method}(#{params.inspect if params != nil})" }
+      log.debug{ ">>> #{request.to_json}" }
+      @connection.puts request.to_json
+      response = queue.pop
+      if response.has_key? 'result'
+        response['result']
+      elsif response['error']
+        raise RemoteError.new response['error']
+      end
+    end
+  end
+
+ 
+  ##
+  # Overloading the <tt>method_missing</tt> gives a convenience way to call server-side methods. This method calls the <tt>call</tt> with the same set of arguments.
+
+  def method_missing method, *args, &blk
+    call method, *args, &blk
+  end
+
+  def log
+    # no logging by default
+    @log ||= Logger.new '/dev/null'
+  end
+
+  private :log
+
+
+  ##
+  # Thrown whenever an error in the client occurs.
+
+  class Error < StandardError; end
+
+
+  ##
+  # Thrown when an error is received from the server. <tt>RemoteError</tt> has two extra attributes: <tt>code</tt> and <tt>data</tt> that correspond to the values returned in the error object in server response.
+
+  class RemoteError < StandardError
+    
+    # Error code, as returned from the server.
+    attr_accessor :code
+
+    # Optional data object, if returned by the server.
+    attr_accessor :data
+    
+    def initialize(error_obj = {'code' => -1, 'message' => "RPC Error"})
+      @code = error_obj['code'] || -1
+      @data = error_obj['data'] if error_obj['data']
+      super "#{@code}: #{error_obj['message']}"
+    end
+  end
+
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: yolodice-client
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- ethan_nx
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-02-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bitcoin-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.8
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.8
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.5.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.5.1
+description: A simple JSON-RPC2 client dedicated for YOLOdice.com API.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- lib/yolodice_client.rb
+homepage: https://github.com/ethan-nx/yolodice-client
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Ruby API client for YOLOdice.com
+test_files: []