clamo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: debb0ed8e3b749ff9e0213c9c97e821668f45d179c7e72d1f4a1a506cd710b75
+  data.tar.gz: dcd24d91533bfe8c50bb5456745b342fc35cab1d38714b3552df36e2fdf34df0
+SHA512:
+  metadata.gz: 7e2df3792feceedc6c98c92b29ddb25e67db2a57972ee08b20e71b13327b4c1296269ef7c873b7e9181aa042d03a2ab7849dde8498750088d2419789a1e33254
+  data.tar.gz: c49ce4742815d16fab1b9cbcf30f621ae2429b515bab8e245f43c069a9be70bbbfe519b6cd8868cf5275c29dd3d1f7e2aa3f54f57e1973b2557c3203871c3614

data/.rubocop.yml

@@ -0,0 +1,18 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.0
+
+Metrics/MethodLength:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/README.md

@@ -0,0 +1,29 @@
+# Clamo
+
+JSON-RPC protocol toolkit for Ruby.
+
+Consume, Serve or test JSON-RPC endpoints with Clamo.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add clamo
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install clamo
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rubakas/clamo

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/clamo/client.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Client
+  ANSWER = 42
+end

data/lib/clamo/jsonrpc.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Clamo
+  module JSONRPC
+    PROTOCOL_VERSION_PRAGMA = { jsonrpc: "2.0" }.freeze
+
+    module ProtocolErrors
+      ErrorDescriptor = Data.define(:code, :message)
+      SERVER_ERROR_CODE_RANGE = ((-32_099)..(-32_000))
+
+      PARSE_ERROR       = ErrorDescriptor.new(code: -32_700, message: "Parse error")
+      INVALID_REQUEST   = ErrorDescriptor.new(code: -32_600, message: "Invalid request")
+      METHOD_NOT_FOUND  = ErrorDescriptor.new(code: -32_601, message: "Method not found")
+      INVALID_PARAMS    = ErrorDescriptor.new(code: -32_602, message: "Invalid params")
+      INTERNAL_ERROR    = ErrorDescriptor.new(code: -32_603, message: "Internal error")
+      SERVER_ERROR      = ErrorDescriptor.new(code: -32_000, message: "Server error")
+    end
+
+    class << self
+      def proper_pragma?(request)
+        request["jsonrpc"] == "2.0"
+      end
+
+      def proper_method?(request)
+        request["method"].is_a?(String)
+      end
+
+      def proper_id_if_any?(request)
+        if request.key?("id")
+          request["id"].is_a?(String) ||
+            request["id"].is_a?(Integer) ||
+            request["id"].is_a?(NilClass)
+        else
+          true
+        end
+      end
+
+      def proper_params_if_any?(request)
+        if request.key?("params")
+          request["params"].is_a?(Array)
+        else
+          true
+        end
+      end
+
+      def valid_request?(request)
+        request.is_a?(Hash) &&
+          proper_pragma?(request) &&
+          proper_method?(request) &&
+          proper_id_if_any?(request) &&
+          proper_params_if_any?(request)
+      end
+
+      def build_request **opts
+        # raise if no method present
+        # raise if params present, but not an array
+        { jsonrpc: "2.0",
+          method: opts[:method] }
+          .merge({ params: opts[:params] })
+          .merge(opts.key?(:id) ? { id: opts[:id] } : {})
+      end
+
+      def build_result_response(id:, result:)
+        {}.merge(PROTOCOL_VERSION_PRAGMA)
+          .merge({ result: result })
+          .merge({ id: id })
+      end
+
+      def build_error_response **opts
+        # raise if no error code present
+        # raise if no error message present
+        { jsonrpc: "2.0",
+          id: opts[:id],
+          error: {
+            code: opts.dig(:error, :code),
+            message: opts.dig(:error, :message),
+            data: opts.dig(:error, :data)
+          }.reject { |k, _| k == :data && !opts[:error].key?(:data) } }
+      end
+
+      def build_error_response_from **opts
+        # raise unless opts[:descriptor]
+        opts.merge(
+          { error:
+            { code: opts[:descriptor].code,
+              message: opts[:descriptor].message } }
+        )
+            .then { |hash| build_error_response(**hash) }
+      end
+
+      def build_error_response_parse_error **opts
+        opts.merge(
+          { error:
+            { code: ProtocolErrors::PARSE_ERROR.code,
+              message: ProtocolErrors::PARSE_ERROR.message } }
+        )
+            .then { |hash| build_error_response(**hash) }
+      end
+    end
+  end
+end

data/lib/clamo/server.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Clamo
+  module Server
+    class << self
+      # Clamo::Server.unparsed_dispatch_to_object(
+      #   request:  request_body,
+      #   object:   MyModule
+      # )
+      def unparsed_dispatch_to_object(request:, object:, **opts)
+        # TODO: raise unless object is present?
+        begin
+          parsed = JSON.parse(request)
+        rescue JSON::JSONError # TODO: any error
+          return JSONRPC.build_error_response_parse_error
+        end
+
+        parsed_dispatch_to_object(request: parsed, object: object, **opts)
+      end
+
+      def parsed_dispatch_to_object(request:, object:, **opts)
+        response_for(request: request, object: object, **opts) do |method, params|
+          dispatch_to_ruby(
+            object: object,
+            method: method,
+            params: params # consider splating
+          )
+        end
+      end
+
+      def method_known?(object:, method:)
+        (object.public_methods - Object.methods)
+          .map(&:to_sym)
+          .include?(method.to_sym)
+      end
+
+      def dispatch_to_ruby(object:, method:, params:)
+        case params
+        when Array
+          object.send method.to_sym, *params
+        when Hash
+          object.send method.to_sym, **params
+        when NilClass
+          object.send method.to_sym
+        else
+          # TODO: raise
+          raise "WTF"
+        end
+      end
+
+      def response_for(request:, object:, **opts, &block)
+        case request
+        when Array # batch request
+          Parallel.map(request, **opts) do |item|
+            response_for_single_request(
+              request: item,
+              object: object,
+              block: block
+            )
+          end.compact
+        when Hash # single request
+          response_for_single_request(
+            request: request,
+            object: object,
+            block: block
+          )
+        else
+          JSONRPC.build_error_response_from(
+            id: nil,
+            descriptor: JSONRPC::ProtocolErrors::INVALID_REQUEST
+          )
+        end
+      end
+
+      def yield_to_execution(block:, method:, params:)
+        block.yield method, params
+      end
+
+      def response_for_single_request(request:, object:, block:)
+        unless JSONRPC.valid_request?(request)
+          return JSONRPC.build_error_response_from(
+            id: request["id"],
+            descriptor: JSONRPC::ProtocolErrors::INVALID_REQUEST
+          )
+        end
+
+        unless request.key?("id") # notification - no result needed
+          # TODO: block.call off the current thread
+          Thread.new do
+            yield_to_execution(
+              block: block,
+              method: request["method"],
+              params: request["params"]
+            )
+          rescue StandardError
+            # TODO: add exception handler
+            nil
+          end
+
+          return nil
+        end
+
+        unless method_known?(object: object, method: request["method"])
+          return JSONRPC.build_error_response_from(
+            id: request["id"],
+            descriptor: JSONRPC::ProtocolErrors::METHOD_NOT_FOUND
+          )
+        end
+
+        JSONRPC.build_result_response(
+          id: request["id"],
+          result: yield_to_execution(
+            block: block,
+            method: request["method"],
+            params: request["params"]
+          )
+        )
+      end
+    end
+  end
+end

data/lib/clamo/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Clamo
+  VERSION = "0.1.0"
+end

data/lib/clamo.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "clamo/version"
+require_relative "clamo/jsonrpc"
+require_relative "clamo/server"
+
+module Clamo
+  # class Error < StandardError; end
+end

data/sig/clamo.rbs

@@ -0,0 +1,4 @@
+module Clamo
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: clamo
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andriy Tyurnikov
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-05-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: parallel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.24.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.24.0
+description: JSON-RPC Client/Server tooling for Ruby
+email:
+- Andriy.Tyurnikov@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- README.md
+- Rakefile
+- lib/clamo.rb
+- lib/clamo/client.rb
+- lib/clamo/jsonrpc.rb
+- lib/clamo/server.rb
+- lib/clamo/version.rb
+- sig/clamo.rbs
+homepage: https://github.com/andriytyurnikov/clamo
+licenses: []
+metadata:
+  homepage_uri: https://github.com/andriytyurnikov/clamo
+  source_code_uri: https://github.com/andriytyurnikov/clamo
+  changelog_uri: https://github.com/andriytyurnikov/clamo
+  rubygems_mfa_required: 'false'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: JSON-RPC Client/Server tooling for Ruby
+test_files: []