ultimate_json_rpc 1.0.0

data/examples/mcp_server.rb

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# MCP server exposing Ruby methods as AI tools
+#
+# Run:  ruby examples/mcp_server.rb
+# Use:  Configure as an MCP server in Claude Desktop, Cursor, etc.
+#
+# claude_desktop_config.json:
+#   {
+#     "mcpServers": {
+#       "calculator": {
+#         "command": "ruby",
+#         "args": ["examples/mcp_server.rb"]
+#       }
+#     }
+#   }
+
+require "ultimate_json_rpc"
+require "ultimate_json_rpc/extras/mcp"
+
+module MathTools
+  def self.add(a, b) = a + b
+  def self.subtract(a, b) = a - b
+  def self.multiply(a, b) = a * b
+  def self.divide(a, b)
+    raise ArgumentError, "Division by zero" if b.zero?
+
+    a.to_f / b
+  end
+end
+
+server = UltimateJsonRpc::Server.new(name: "Math Tools", version: "1.0")
+server.expose(MathTools,
+              descriptions: { add: "Add two numbers", subtract: "Subtract b from a",
+                              multiply: "Multiply two numbers", divide: "Divide a by b" },
+              params_schema: { add: { a: { "type" => "number" }, b: { "type" => "number" } },
+                               subtract: { a: { "type" => "number" }, b: { "type" => "number" } },
+                               multiply: { a: { "type" => "number" }, b: { "type" => "number" } },
+                               divide: { a: { "type" => "number" }, b: { "type" => "number" } } })
+
+UltimateJsonRpc::Extras::MCP.new(server).run

data/examples/multi_namespace.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Multi-namespace composition and API versioning
+#
+# Run: ruby examples/multi_namespace.rb
+
+require "ultimate_json_rpc"
+require "json"
+
+module Auth
+  def self.login(username:, password:) = { token: "tok_#{username}", expires: 3600 }
+  def self.logout(token:) = { revoked: true }
+end
+
+module Users
+  def self.list = [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]
+  def self.get(id:) = { id:, name: id == 1 ? "Alice" : "Bob" }
+end
+
+# Compose multiple objects into a single endpoint
+server = UltimateJsonRpc::Server.new(name: "My API", version: "1.0")
+server.expose(Auth, namespace: "auth", descriptions: { login: "Authenticate user", logout: "Revoke token" })
+server.expose(Users, namespace: "users", descriptions: { list: "List all users", get: "Get user by ID" })
+
+# API versioning via namespaces
+module CalcV1
+  def self.add(a, b) = a + b
+end
+
+module CalcV2
+  def self.add(a, b) = { result: a + b, version: 2 }
+end
+
+server.expose(CalcV1, namespace: "v1.calc")
+server.expose(CalcV2, namespace: "v2.calc")
+
+# Test it
+puts "Methods: #{server.methods_list.join(", ")}"
+puts
+
+[
+  { "jsonrpc" => "2.0", "method" => "auth.login", "params" => { "username" => "alice", "password" => "secret" }, "id" => 1 },
+  { "jsonrpc" => "2.0", "method" => "users.list", "id" => 2 },
+  { "jsonrpc" => "2.0", "method" => "v1.calc.add", "params" => [2, 3], "id" => 3 },
+  { "jsonrpc" => "2.0", "method" => "v2.calc.add", "params" => [2, 3], "id" => 4 }
+].each do |req|
+  puts "#{req["method"]} => #{server.handle(JSON.generate(req))}"
+end

data/examples/rack_server.ru

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Basic Rack/Puma JSON-RPC server
+#
+# Run:  bundle exec rackup examples/rack_server.ru
+# Test: curl -X POST http://localhost:9292 \
+#         -H "Content-Type: application/json" \
+#         -d '{"jsonrpc":"2.0","method":"add","params":[2,3],"id":1}'
+
+require "ultimate_json_rpc"
+require "ultimate_json_rpc/transport/rack"
+
+module Calculator
+  def self.add(a, b) = a + b
+  def self.multiply(a, b) = a * b
+end
+
+server = UltimateJsonRpc::Server.new(name: "Calculator API", version: "1.0")
+server.expose(Calculator, descriptions: {
+  add: "Add two numbers",
+  multiply: "Multiply two numbers"
+})
+
+run UltimateJsonRpc::Transport::Rack.new(server)

data/examples/testing_patterns.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Testing patterns with UltimateJsonRpc
+#
+# Run: ruby examples/testing_patterns.rb
+
+require "ultimate_json_rpc"
+require "ultimate_json_rpc/extras/test_helpers"
+require "ultimate_json_rpc/extras/recorder"
+require "ultimate_json_rpc/extras/profiler"
+require "json"
+
+# === 1. Test Helpers ===
+puts "=== Test Helpers ==="
+
+module Calculator
+  def self.add(a, b) = a + b
+end
+
+server = UltimateJsonRpc::Server.new
+server.expose(Calculator)
+
+include UltimateJsonRpc::Extras::TestHelpers # rubocop:disable Style/MixinUsage
+
+response = rpc_call(server, "add", params: [2, 3])
+puts "rpc_call result: #{response["result"]}"
+
+error_response = rpc_call(server, "nonexistent")
+puts "rpc_call error: #{error_response["error"]["code"]}"
+
+# === 2. Recorder ===
+puts "\n=== Recorder ==="
+
+recorder = UltimateJsonRpc::Extras::Recorder.new(server)
+server.handle('{"jsonrpc":"2.0","method":"add","params":[10,20],"id":1}')
+server.handle('{"jsonrpc":"2.0","method":"add","params":[5,5],"id":2}')
+
+puts "Recorded #{recorder.size} exchanges:"
+recorder.exchanges.each { |e| puts "  #{e["method"]}(#{e["params"]}) => #{e["result"]} (#{e["duration"]}s)" }
+
+# === 3. Profiler ===
+puts "\n=== Profiler ==="
+
+profiler = UltimateJsonRpc::Extras::Profiler.new(server)
+50.times { |i| server.handle(JSON.generate({ "jsonrpc" => "2.0", "method" => "add", "params" => [i, 1], "id" => i })) }
+
+stats = profiler["add"]
+puts "add: #{stats[:count]} calls, avg=#{stats[:avg]}s, p99=#{stats[:p99]}s"

data/examples/websocket_server.ru

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# WebSocket JSON-RPC server using faye-websocket
+#
+# Setup: gem install faye-websocket puma
+# Run:   bundle exec rackup examples/websocket_server.ru
+#
+# Test with wscat (npm install -g wscat):
+#   wscat -c ws://localhost:9292
+#   > {"jsonrpc":"2.0","method":"add","params":[2,3],"id":1}
+#   < {"jsonrpc":"2.0","result":5,"id":1}
+#
+# Or test with JavaScript:
+#   const ws = new WebSocket("ws://localhost:9292");
+#   ws.onmessage = (e) => console.log(e.data);
+#   ws.onopen = () => ws.send('{"jsonrpc":"2.0","method":"add","params":[2,3],"id":1}');
+
+require "ultimate_json_rpc"
+require "ultimate_json_rpc/transport/websocket"
+require "faye/websocket"
+
+module Calculator
+  def self.add(a, b) = a + b
+  def self.multiply(a, b) = a * b
+end
+
+server = UltimateJsonRpc::Server.new(name: "Calculator WS", version: "1.0")
+server.expose(Calculator)
+ws_handler = UltimateJsonRpc::Transport::WebSocket.new(server)
+
+app = lambda do |env|
+  if Faye::WebSocket.websocket?(env)
+    ws = Faye::WebSocket.new(env)
+    ws_handler.call(env, ws)
+    ws.on(:close) { ws = nil }
+    ws.rack_response
+  else
+    [200, { "content-type" => "text/plain" }, ["WebSocket JSON-RPC server. Connect via ws://localhost:9292"]]
+  end
+end
+
+run app

data/lib/ultimate_json_rpc/core/errors.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module UltimateJsonRpc
+  module Core
+    PARSE_ERROR = -32_700
+    INVALID_REQUEST = -32_600
+    METHOD_NOT_FOUND = -32_601
+    INVALID_PARAMS = -32_602
+    INTERNAL_ERROR = -32_603
+
+    # Implementation-defined server error range (-32000 to -32099)
+    SERVER_ERROR_MIN = -32_099
+    SERVER_ERROR_MAX = -32_000
+
+    ERROR_MESSAGES = {
+      PARSE_ERROR => "Parse error",
+      INVALID_REQUEST => "Invalid Request",
+      METHOD_NOT_FOUND => "Method not found",
+      INVALID_PARAMS => "Invalid params",
+      INTERNAL_ERROR => "Internal error"
+    }.freeze
+
+    # Reserved range for JSON-RPC protocol errors (-32768 to -32000)
+    RESERVED_ERROR_MIN = -32_768
+    RESERVED_ERROR_MAX = -32_000
+
+    class InvalidRequest < Error; end
+
+    # Protocol-level parameter validation error (JSON-RPC -32602).
+    # Raised by the framework when params fail schema checks (type mismatch, enum violation).
+    # NOT intended for application-level business validation — use ApplicationError for that.
+    # Message is gated by expose_errors, same as InvalidRequest and ArgumentError.
+    class InvalidParams < Error; end
+
+    class MethodNotFound < Error
+      attr_reader :method_name
+
+      def initialize(method_name)
+        @method_name = method_name
+        super("Method not found: #{method_name}")
+      end
+    end
+
+    class ApplicationError < Error
+      attr_reader :code, :rpc_data
+
+      def initialize(code:, message:, data: nil)
+        raise ArgumentError, "error code must be an Integer, got #{code.class}" unless code.is_a?(Integer)
+
+        if code.between?(RESERVED_ERROR_MIN, RESERVED_ERROR_MAX)
+          hint = code.between?(SERVER_ERROR_MIN, SERVER_ERROR_MAX) ? "; use ServerError for server error codes" : ""
+          raise ArgumentError,
+                "error code #{code} is in the reserved range (#{RESERVED_ERROR_MIN}..#{RESERVED_ERROR_MAX})#{hint}"
+        end
+
+        @code = code
+        @rpc_data = data
+        super(message)
+      end
+    end
+
+    class ServerError < Error
+      attr_reader :code, :rpc_data
+
+      def initialize(code:, message:, data: nil)
+        unless code.is_a?(Integer) && code.between?(SERVER_ERROR_MIN, SERVER_ERROR_MAX)
+          raise ArgumentError,
+                "server error code must be in range (#{SERVER_ERROR_MIN}..#{SERVER_ERROR_MAX}), got #{code}"
+        end
+
+        @code = code
+        @rpc_data = data
+        super(message)
+      end
+    end
+
+    REQUEST_TIMEOUT = -32_001
+
+    class RequestTimeout < ServerError
+      def initialize(_message = nil)
+        super(code: REQUEST_TIMEOUT, message: "Request timeout")
+      end
+    end
+  end
+end

data/lib/ultimate_json_rpc/core/handler.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+module UltimateJsonRpc
+  module Core
+    # @api private
+    VARIADIC_DEFAULTS = { rest: "args", keyrest: "kwargs" }.freeze
+    private_constant :VARIADIC_DEFAULTS
+
+    DANGEROUS_METHODS = %w[
+      eval instance_eval class_eval module_eval
+      send public_send __send__
+      system exec spawn fork
+      define_method remove_method undef_method
+      binding method_missing respond_to_missing?
+      exit exit! abort
+      require require_relative load
+      open
+      instance_variable_get instance_variable_set
+      class_variable_get class_variable_set
+      const_get const_set remove_const
+      method
+      include extend prepend
+      attr_accessor attr_reader attr_writer
+      public private protected
+    ].freeze
+    private_constant :DANGEROUS_METHODS
+
+    TYPE_CHECKS = {
+      "string" => String, "number" => Numeric, "integer" => Integer,
+      "boolean" => [TrueClass, FalseClass], "array" => Array,
+      "object" => Hash, "null" => NilClass
+    }.freeze
+    private_constant :TYPE_CHECKS
+
+    JSON_TYPE_NAMES = {
+      String => "string", Integer => "integer", Float => "number",
+      TrueClass => "boolean", FalseClass => "boolean",
+      Array => "array", Hash => "object", NilClass => "null"
+    }.freeze
+    private_constant :JSON_TYPE_NAMES
+
+    PARAM_FLAGS = {
+      req: { "required" => true }, keyreq: { "required" => true, "keyword" => true },
+      opt: {}, key: { "keyword" => true },
+      rest: { "variadic" => true }, keyrest: { "variadic" => true, "keyword" => true }
+    }.freeze
+    private_constant :PARAM_FLAGS
+
+    module ParamValidator
+      private
+
+      def validate_params!(callable, params, schema)
+        return unless schema
+
+        case params
+        when Array then validate_positional!(callable, params, schema)
+        when Hash then validate_keyword!(params, schema)
+        end
+      end
+
+      def validate_positional!(callable, params, schema)
+        names = callable.parameters.filter_map { |type, pname| pname&.to_s unless type == :block }
+        params.each_with_index do |value, index|
+          validate_value!(names[index], value, schema[names[index]]) if names[index] && schema[names[index]]
+        end
+      end
+
+      def validate_keyword!(params, schema)
+        params.each { |k, v| validate_value!(k.to_s, v, schema[k.to_s]) if schema.key?(k.to_s) }
+      end
+
+      def validate_value!(name, value, pschema)
+        check_param_type!(name, value, pschema)
+        check_param_enum!(name, value, pschema)
+      end
+
+      def check_param_type!(name, value, pschema)
+        type = pschema["type"]
+        return unless type
+
+        expected = TYPE_CHECKS[type]
+        return unless expected
+        return unless Array(expected).none? { |k| value.is_a?(k) }
+
+        raise InvalidParams, "parameter '#{name}' must be #{type}, " \
+                             "got #{JSON_TYPE_NAMES.fetch(value.class, value.class.name)}"
+      end
+
+      def check_param_enum!(name, value, pschema)
+        return unless (enum = pschema["enum"]) && !enum.include?(value)
+
+        raise InvalidParams, "parameter '#{name}' must be one of: #{enum.map(&:inspect).join(", ")}"
+      end
+    end
+    private_constant :ParamValidator
+
+    class Handler
+      include ParamValidator
+
+      Entry = Struct.new(:callable, :description, :returns, :deprecated, :params_schema)
+      private_constant :Entry
+
+      def initialize
+        @entries = {}
+      end
+
+      def expose(target, namespace: nil, only: nil, except: nil, descriptions: nil, returns: nil, deprecated: nil,
+                 params_schema: nil)
+        validate_expose_args!(target, only, except)
+        prefix = namespace.to_s.then { |ns| ns.empty? ? "" : "#{ns}." }
+        methods = filter_methods(callable_methods(target), only: only, except: except)
+        Kernel.warn "UltimateJsonRpc: expose registered 0 methods from #{target.inspect}" if methods.empty?
+        methods.each do |m|
+          register_exposed(prefix:, method_name: m, target:, descriptions:, returns:, deprecated:, params_schema:)
+        end
+      end
+
+      def expose_method(name, callable = nil, description: nil, returns: nil, deprecated: nil, params_schema: nil,
+                        &block)
+        callable = resolve_callable(callable, block)
+        name = name.to_s
+        validate_method_name!(name)
+        @entries[name] = Entry.new(
+          callable: callable,
+          description: description&.to_s,
+          returns: returns,
+          deprecated: normalize_deprecated(deprecated),
+          params_schema: params_schema&.transform_keys(&:to_s)
+        )
+      end
+
+      def call(method_name, params)
+        entry = @entries[method_name]
+        raise MethodNotFound, method_name unless entry
+
+        validate_params!(entry.callable, params, entry.params_schema)
+        invoke_callable(entry.callable, params)
+      end
+
+      def method?(method_name) = @entries.key?(method_name)
+      def methods_list = @entries.keys.sort
+      def methods_info = @entries.keys.sort.map { |name| method_info(name) }
+      def size = @entries.size
+      def empty? = @entries.empty?
+
+      def freeze
+        @entries.each_value(&:freeze)
+        @entries.freeze
+        super
+      end
+
+      private
+
+      def method_info(name)
+        entry = @entries[name]
+        info = { "name" => name }
+        add_method_metadata(info:, entry:)
+        info
+      end
+
+      def add_method_metadata(info:, entry:)
+        info["description"] = entry.description if entry.description
+        add_params(info:, entry:)
+        info["result"] = build_result(entry.returns) if entry.returns
+        info["deprecated"] = entry.deprecated if entry.deprecated
+      end
+
+      def add_params(info:, entry:)
+        schema = entry.params_schema
+        params = entry.callable.parameters.filter_map { |type, pname| param_descriptor(type:, pname:, schema:) }
+        info["params"] = params unless params.empty?
+      end
+
+      def build_result(returns)
+        case returns
+        when Hash then { "name" => "result" }.merge(returns)
+        when String then { "name" => "result", "schema" => { "type" => returns } }
+        else { "name" => "result", "schema" => returns }
+        end
+      end
+
+      def param_descriptor(type:, pname:, schema:)
+        return if type == :block
+
+        name = pname&.to_s || VARIADIC_DEFAULTS.fetch(type, "arg")
+        desc = { "name" => name }.merge(PARAM_FLAGS.fetch(type, {}))
+        desc["schema"] = schema[name] if schema&.key?(name)
+        desc
+      end
+
+      def register_exposed(prefix:, method_name:, target:, descriptions:, returns:, deprecated:, params_schema:)
+        full_name = "#{prefix}#{method_name}"
+        validate_method_name!(full_name)
+        @entries[full_name] = Entry.new(
+          callable: target.method(method_name.to_sym),
+          description: extract_metadata(descriptions, method_name)&.to_s,
+          returns: extract_metadata(returns, method_name),
+          deprecated: normalize_deprecated(extract_metadata(deprecated, method_name)),
+          params_schema: extract_metadata(params_schema, method_name)&.then { |v| v.transform_keys(&:to_s) }
+        )
+      end
+
+      def normalize_deprecated(value)
+        return nil unless value
+
+        value == true ? true : value.to_s
+      end
+
+      def extract_metadata(source, method_name)
+        return nil unless source.is_a?(Hash)
+
+        sym_key = method_name.to_sym
+        return source[sym_key] if source.key?(sym_key)
+
+        source[method_name.to_s]
+      end
+
+      def callable_methods(target)
+        if target.is_a?(Module)
+          target.singleton_methods(false).map(&:to_s)
+        else
+          ((target.class.public_instance_methods(false) - Object.public_instance_methods) |
+           target.singleton_methods(false)).map(&:to_s)
+        end
+      end
+
+      def filter_methods(methods, only:, except:)
+        if only
+          allowed = Array(only).map(&:to_s)
+          methods.select { |m| allowed.include?(m) }
+        elsif except
+          blocked = Array(except).map(&:to_s)
+          methods.reject { |m| blocked.include?(m) }
+        else
+          methods
+        end
+      end
+
+      def validate_expose_args!(target, only, except)
+        raise ArgumentError, "target must not be nil" if target.nil?
+        raise ArgumentError, "cannot use both :only and :except" if only && except
+      end
+
+      def validate_method_name!(name)
+        raise ArgumentError, "method name must not be empty" if name.empty?
+        raise ArgumentError, "method names starting with 'rpc.' are reserved" if name.start_with?("rpc.")
+
+        validate_segments!(name)
+        raise ArgumentError, "method '#{name}' is already registered" if @entries.key?(name)
+      end
+
+      def validate_segments!(name)
+        segments = name.include?(".") ? name.split(".", -1) : [name]
+        segments.each do |segment|
+          raise ArgumentError, "method name contains empty segment" if segment.empty?
+          raise ArgumentError, "method name '#{segment}' is dangerous" if DANGEROUS_METHODS.include?(segment)
+        end
+      end
+
+      def resolve_callable(callable, block)
+        raise ArgumentError, "provide either a callable or a block, not both" if callable && block
+        raise ArgumentError, "a callable or block is required" unless callable || block
+
+        (callable || block).tap do |resolved|
+          raise ArgumentError, "callable must respond to #call" unless resolved.respond_to?(:call)
+        end
+      end
+
+      DISPATCH_ARG_ERROR = /\Awrong number of arguments\b|\Amissing keywords?: /
+      private_constant :DISPATCH_ARG_ERROR
+
+      def invoke_callable(callable, params)
+        case params
+        when Array then callable.call(*params)
+        when Hash  then callable.call(**safe_symbolize_keys(callable, params))
+        when nil   then callable.call
+        else raise InvalidParams, "params must be an Array, Hash, or nil"
+        end
+      rescue ArgumentError => e
+        raise InvalidParams, e.message if e.message.match?(DISPATCH_ARG_ERROR)
+
+        raise
+      end
+
+      def safe_symbolize_keys(callable, params)
+        return params.transform_keys(&:to_sym) if accepts_keyrest?(callable)
+
+        known = known_keyword_params(callable)
+        params.each_with_object({}) do |(k, v), h|
+          key = k.to_s
+          raise InvalidParams, "unknown keyword: #{key}" unless known.key?(key)
+
+          h[known[key]] = v
+        end
+      end
+
+      def known_keyword_params(callable)
+        callable.parameters.each_with_object({}) do |(type, name), map|
+          map[name.to_s] = name if name && %i[key keyreq].include?(type)
+        end
+      end
+
+      def accepts_keyrest?(callable)
+        callable.parameters.any? { |type, _| type == :keyrest }
+      end
+    end
+  end
+end

data/lib/ultimate_json_rpc/core/request.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module UltimateJsonRpc
+  module Core
+    class Request
+      MAX_NESTING = 32
+
+      attr_reader :method_name, :params, :id, :context
+
+      def initialize(data)
+        validate!(data)
+        @method_name = data["method"].dup.freeze
+        @params = deep_freeze(deep_dup(data["params"]))
+        @id = data["id"].is_a?(String) ? data["id"].dup.freeze : data["id"]
+        @context = {}
+      end
+
+      def notification?
+        !@has_id
+      end
+
+      private
+
+      def validate!(data)
+        validate_structure!(data)
+        validate_params!(data["params"]) if data.key?("params")
+        @has_id = data.key?("id")
+        validate_id!(data["id"]) if @has_id
+      end
+
+      def validate_structure!(data)
+        raise InvalidRequest, "request must be a JSON object" unless data.is_a?(Hash)
+        raise InvalidRequest, "jsonrpc must be \"2.0\"" unless data["jsonrpc"] == "2.0"
+
+        valid_method = data["method"].is_a?(String) && !data["method"].empty?
+        raise InvalidRequest, "method must be a non-empty String" unless valid_method
+      end
+
+      def validate_params!(params)
+        return if params.is_a?(Array) || params.is_a?(Hash)
+
+        raise InvalidRequest, "params must be an Array or Object"
+      end
+
+      def validate_id!(id)
+        return if id.nil? || id.is_a?(String) || id.is_a?(Numeric)
+
+        raise InvalidRequest, "id must be a String, Number, or Null"
+      end
+
+      def deep_dup(obj)
+        case obj
+        when Hash then obj.to_h { |k, v| [k.frozen? ? k : k.dup, deep_dup(v)] }
+        when Array then obj.map { |v| deep_dup(v) }
+        else obj.frozen? ? obj : obj.dup
+        end
+      end
+
+      def deep_freeze(obj, depth = 0)
+        raise InvalidRequest, "params nesting too deep (max #{MAX_NESTING})" if depth > MAX_NESTING
+
+        case obj
+        when Hash
+          obj.each do |k, v|
+            k.freeze
+            deep_freeze(v, depth + 1)
+          end
+        when Array then obj.each { |v| deep_freeze(v, depth + 1) }
+        end
+        obj.freeze
+      end
+    end
+  end
+end