solana_rpc_ruby 1.0.0 → 1.1.2

data/README.md

@@ -1,4 +1,9 @@
-![specs](https://github.com/Block-Logic/solana-rpc-ruby/actions/workflows/specs.yml/badge.svg?branch=177580443_create_wrapper_for_solana_rpc)
+![specs](https://github.com/Block-Logic/solana-rpc-ruby/actions/workflows/specs.yml/badge.svg)
+![Maintained](https://img.shields.io/badge/Maintained%3F-yes-green.svg)
+![Last Commit](https://img.shields.io/github/last-commit/Block-Logic/solana-rpc-ruby)
+![Tag](https://img.shields.io/github/v/tag/Block-Logic/solana-rpc-ruby)
+![Stars](https://img.shields.io/github/stars/Block-Logic/solana-rpc-ruby.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 # solana_rpc_ruby
 A Solana RPC Client for Ruby. This gem provides a wrapper methods for Solana RPC JSON API https://docs.solana.com/developing/clients/jsonrpc-api.
 
@@ -6,7 +11,7 @@ A Solana RPC Client for Ruby. This gem provides a wrapper methods for Solana RPC
 
 ### Requirements
 
-This gem requires Ruby 2.6+ and h Rails 6.0+. It MIGHT work with lower versions, but was not tested againt them.
+This gem requires Ruby 2.6+ and h Rails 6.0+. It MIGHT work with lower versions, but was not tested with them.
 Add the following line to your Gemfile:
 
 ```ruby
@@ -35,13 +40,163 @@ end
 You can customize it to your needs.
 
 ### Usage examples
+
+#### JSON RPC API
 ```ruby
 # If you set default cluster you don't need to pass it every time.
-method_wrapper = SolanaRpcRuby::MethodsWrapper.new(cluster: 'https://api.testnet.solana.com')
+method_wrapper = SolanaRpcRuby::MethodsWrapper.new(
+  # optional, if not passed, default cluster from config will be used
+  cluster: 'https://api.testnet.solana.com',
+
+  # optional, if not passed, default random number 
+  # from range 1 to 99_999 will be used
+  id: 123 
+)
+
 response = method_wrapper.get_account_info(account_pubkey)
 puts response
+
+# You can check cluster and id that are used.
+method_wrapper.cluster
+method_wrapper.id
+```
+#### Subscription Websocket (BETA)
+```ruby
+ws_method_wrapper = SolanaRpcRuby::WebsocketsMethodsWrapper.new(
+  # optional, if not passed, default ws_cluster from config will be used
+  cluster: 'ws://api.testnet.solana.com',
+
+  # optional, if not passed, default random number 
+  # from range 1 to 99_999 will be used
+  id: 123 
+)
+
+# You should see stream of messages in your console.
+ws_method_wrapper.root_subscribe
+
+# You can pass a block to do something with websocket's messages, ie:
+block = Proc.new do |message|
+  json = JSON.parse(message)
+  puts json['params']
+end
+
+ws_method_wrapper.root_subscribe(&block)
+
+# You can check cluster and id that are used.
+ws_method_wrapper.cluster
+ws_method_wrapper.id
+```
+
+#### Websockets usage in Rails
+You can easily plug-in websockets connection to your rails app by using ActionCable.
+Here is an example for development environment.
+More explanation on Action Cable here: https://www.pluralsight.com/guides/updating-a-rails-app's-wall-feed-in-real-time-with-actioncable
+
+0. Make sure that you have action_cable and solana_rpc_ruby gems installed properly. Also install redis unless you have it.
+
+1. Mount action_cable in `routes.rb`.
+```ruby
+Rails.application.routes.draw do
+  mount ActionCable.server => '/cable'
+  ...
+end
 ```
 
+2. Update `config/environments/development.rb`.
+```ruby
+config.action_cable.url = "ws://localhost:3000/cable"
+config.action_cable.allowed_request_origins = [/http:\/\/*/, /https:\/\/*/]
+```
+
+3. Update adapter in `cable.yml`.
+```ruby
+development:
+  adapter: redis
+  url: <%= ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" } %>
+```
+
+4. Create a channel.
+```ruby
+rails g channel wall
+```
+
+5. Your `wall_channel.rb` should look like this:
+```ruby
+class WallChannel < ApplicationCable::Channel
+  def subscribed
+    stream_from "wall_channel"
+  end
+
+  def unsubscribed
+    # Any cleanup needed when channel is unsubscribed
+  end
+end
+```
+
+6. Your `wall_channel.js` should look like this (json keys are configured for `root_subscription` method response):
+```js
+import consumer from "./consumer"
+
+consumer.subscriptions.create("WallChannel", {
+  connected() {
+    console.log("Connected to WallChannel");
+    // Called when the subscription is ready for use on the server
+  },
+
+  disconnected() {
+    // Called when the subscription has been terminated by the server
+  },
+
+  received(data) {
+    let wall = document.getElementById('wall');
+
+    wall.innerHTML += "<p>Result: "+ data['message']['result'] + "</p>";
+    // Called when there's incoming data on the websocket for this channel
+  }
+});
+
+
+```
+
+7. Create placeholder somewhere in your view for messages.
+```html
+<div id='wall' style='overflow-y: scroll; height:400px;''>
+  <h1>Solana subscription messages</h1>
+</div>
+```
+
+8. Create a script with a block to run websockets (`script/websockets_solana.rb`).
+```ruby
+require_relative '../config/environment'
+
+ws_method_wrapper = SolanaRpcRuby::WebsocketsMethodsWrapper.new
+
+# Example of block that can be passed to the method to manipulate the data.
+block = Proc.new do |message|
+  json = JSON.parse(message)
+
+  ActionCable.server.broadcast(
+    "wall_channel",
+    {
+      message: json['params']
+    }
+  )
+end
+
+ws_method_wrapper.root_subscribe(&block)
+```
+9. Run `rails s`, open webpage where you put your placeholder.
+10. Open `http://localhost:3000/address_with_websockets_view`.
+11. Run `rails r script/websockets_solana.rb` in another terminal window.
+12. You should see incoming websocket messages on your webpage.
+### Demo scripts
+Gem is coming with demo scripts that you can run and test API and Websockets.
+
+1. Clone the repo
+2. Set the gemset
+3. Run `ruby demo.rb` or `ruby demo_ws_METHOD.rb` to see example output.
+4. Check the gem or Solana JSON RPC API docs to get more information about method usage and modify demo scripts loosely.
+
 All info about methods you can find in the docs on: https://www.rubydoc.info/github/Block-Logic/solana-rpc-ruby/main/SolanaRpcRuby
 
 Also, as a reference you can use docs from solana: https://docs.solana.com/developing/clients/jsonrpc-api

data/lib/generators/templates/solana_rpc_ruby_config.rb

@@ -5,6 +5,8 @@ SolanaRpcRuby.config do |c|
   # 
   # You can use this setting or pass cluster directly, check the docs.
   # c.cluster = 'https://api.testnet.solana.com'
+  # c.ws_cluster = 'ws://api.testnet.solana.com'
+
 
   # This one is mandatory.
   c.json_rpc_version = '2.0'

data/lib/solana_rpc_ruby/api_client.rb

@@ -45,12 +45,14 @@ module SolanaRpcRuby
            Net::HTTPNotFound,
            Net::HTTPClientException,
            Net::HTTPFatalError,
-           Net::ReadTimeout => e
-      fail ApiError.new(message: e.message)
+           Net::ReadTimeout,
+           Errno::ECONNREFUSED,
+           SocketError => e
+      fail ApiError.new(error_class: e.class, message: e.message)
     rescue StandardError => e
 
       message = "#{e.class} #{e.message}\n Backtrace: \n #{e.backtrace}"
-      fail ApiError.new(message: message)
+      fail ApiError.new(error_class: e.class, message: e.message)
     end
 
     private

data/lib/solana_rpc_ruby/api_error.rb

@@ -17,11 +17,22 @@ module SolanaRpcRuby
     # @param message [String]
     #
     # @return [SolanaRpcRuby::ApiError]
-    def initialize(code: nil, message:)
+    def initialize(message:, error_class: nil, code: nil)
       @code = code
       @message = message.to_s
+      @error_class = error_class
 
-      super message
+      additional_info
+
+      super @message
+    end
+
+    private
+    def additional_info
+      wrong_url_errors = [Errno::ECONNREFUSED, SocketError]
+      if wrong_url_errors.include?(@error_class)
+        @message += '. Check if the RPC url you provided is correct.'
+      end
     end
   end
 end

data/lib/solana_rpc_ruby/helper_methods.rb

@@ -12,5 +12,18 @@ module SolanaRpcRuby
   
       object.nil? || object.empty?
     end
+
+    # Creates method name to match names required by Solana RPC JSON.
+    # 
+    # @param method [String]
+    # 
+    # @return [String]
+    def create_method_name(method)
+      return '' unless method && (method.is_a?(String) || method.is_a?(Symbol))
+
+      method.to_s.split('_').map.with_index do |string, i|
+        i == 0 ? string : string.capitalize
+      end.join
+    end
   end
 end

data/lib/solana_rpc_ruby/methods_wrapper.rb

@@ -19,12 +19,24 @@ module SolanaRpcRuby
     # @return [String]
     attr_accessor :cluster
 
+    # Unique client-generated identifying integer.
+    # @return [Integer]
+    attr_accessor :id
+
     # Initialize object with cluster address where requests will be sent.
     #
     # @param api_client [ApiClient]
     # @param cluster [String] cluster where requests will be sent.
-    def initialize(api_client: ApiClient, cluster: SolanaRpcRuby.cluster)
+    # @param id [Integer] unique client-generated identifying integer.
+    def initialize(
+      api_client: ApiClient, 
+      cluster: SolanaRpcRuby.cluster,
+      id: rand(1...99_999)
+    )
+
       @api_client = api_client.new(cluster)
+      @cluster = cluster
+      @id = id
     end
 
     # @see https://docs.solana.com/developing/clients/jsonrpc-api#getaccountinfo
@@ -1309,13 +1321,5 @@ module SolanaRpcRuby
         return response
       end
     end
-
-    def create_method_name(method)
-      return '' unless method
-
-      method.to_s.split('_').map.with_index do |string, i|
-        i == 0 ? string : string.capitalize
-      end.join
-    end
   end
 end

data/lib/solana_rpc_ruby/request_body.rb

@@ -12,22 +12,27 @@ module SolanaRpcRuby
     # 
     # @param method [string] method name.
     # @param method_params [Array] ordered array with required and/or optional params.
+    # @param id [Integer] Unique client-generated identifying integer.
     # 
     # @return [Json] JSON string with body.
     # 
-    def create_json_body(method, method_params: [])
-      body = base_body
+    def create_json_body(method, method_params: [], id: @id)
+      body = base_body(id: id)
       body[:method] = method
       body[:params] = method_params if method_params.any?
       body.to_json
     end
 
     # Hash with default body params.
+    # @param id [Integer] Unique client-generated identifying integer.
+    # 
     # @return [Hash] hash with base params for every request.
-    def base_body
+    def base_body(id: 1)
+      raise ArgumentError, 'id must be an integer' unless id.is_a?(Integer)
+
       {
         "jsonrpc": SolanaRpcRuby.json_rpc_version,
-        "id": 1
+        "id": id
       }
     end
   end

data/lib/solana_rpc_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SolanaRpcRuby
-  VERSION = '1.0.0'
+  VERSION = '1.1.2'
 end

data/lib/solana_rpc_ruby/websocket_client.rb

@@ -0,0 +1,111 @@
+require 'net/http'
+require 'faye/websocket'
+module SolanaRpcRuby
+  ##
+  # WebsocketClient class serves as a websocket client for solana JSON RPC API.
+  # @see https://docs.solana.com/developing/clients/jsonrpc-api
+  class WebsocketClient
+    include RequestBody
+
+    KEEPALIVE_TIME = 60
+    SLEEP_TIME = 10
+    RETRIES_LIMIT = 3
+
+    # Determines which cluster will be used to send requests.
+    # @return [String]
+    attr_accessor :cluster
+
+    # Api client used to connect with API.
+    # @return [Object]
+    attr_accessor :client
+
+    # Initialize object with cluster address where requests will be sent.
+    #
+    # @param websocket_client [Object]
+    # @param cluster [String]
+    def initialize(websocket_client: Faye::WebSocket, cluster: nil)
+      @client = websocket_client
+      @cluster = cluster || SolanaRpcRuby.ws_cluster
+      @retries = 0
+
+      message = 'Websocket cluster is missing. Please provide default cluster in config or pass it to the client directly.'
+      raise ArgumentError, message unless @cluster
+    end
+
+    # Connects with cluster's websocket.
+    #
+    # @param body [String]
+    # @param &block [Proc]
+    #
+    # @return [String] # messages from websocket
+    def connect(body, &block)
+      EM.run {
+        # ping option sends some data to the server periodically, 
+        # which prevents the connection to go idle.
+        ws ||= Faye::WebSocket::Client.new(@cluster, nil)
+        EM::PeriodicTimer.new(KEEPALIVE_TIME) do
+          while !ws.ping
+            @retries += 1
+
+            unless @retries <= 3
+              puts '3 ping retries failed, close connection.'
+              ws.close
+              break
+            end
+
+            puts 'Ping failed, sleep for 10 seconds...'
+            sleep SLEEP_TIME
+          end
+        end
+
+        ws.on :open do |event|
+          p [:open]
+          p "Status: #{ws.status}"
+          ws.send(body)
+        end
+      
+        ws.on :message do |event|
+          # To run websocket_methods_wrapper_spec.rb, uncomment code below
+          # to return info about connection estabilished.
+          # Also, read the comment from the top of the mentioned file.
+          # 
+          # if ENV['test'] == 'true'
+          #   result = block_given? ? block.call(event.data) : event.data
+          #   return result
+          # end
+
+          if block_given?
+            block.call(event.data)
+          else
+            puts event.data
+          end
+        end
+
+        ws.on :close do |event|
+          p [:close, event.code, event.reason]
+
+          @retries += 1
+          if @retries <= RETRIES_LIMIT
+            puts 'Retry...'
+            # It restarts the websocket connection.
+            connect(body, &block) 
+          else
+            ws = nil
+            puts 'Retries limit reached, closing. Wrong cluster address or unhealthy node might be a reason, please check.'
+            EM.stop
+          end
+        end
+      }
+    rescue Timeout::Error,
+           Net::HTTPError,
+           Net::HTTPNotFound,
+           Net::HTTPClientException,
+           Net::HTTPFatalError,
+           Net::ReadTimeout => e
+      fail ApiError.new(message: e.message)
+    rescue StandardError => e
+      message = "#{e.class} #{e.message}\n Backtrace: \n #{e.backtrace}"
+      fail ApiError.new(message: message)
+    end
+  end
+end