ultimate_json_rpc 1.0.0

data/lib/ultimate_json_rpc/core/response.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module UltimateJsonRpc
+  module Core
+    module Response
+      def self.success(result, id)
+        {
+          "jsonrpc" => "2.0",
+          "result" => result,
+          "id" => id
+        }
+      end
+
+      def self.error(code, id, data: nil, message: nil)
+        err = {
+          "code" => code,
+          "message" => message || ERROR_MESSAGES.fetch(code, "Unknown error")
+        }
+        err["data"] = data unless data.nil?
+        {
+          "jsonrpc" => "2.0",
+          "error" => err,
+          "id" => id
+        }
+      end
+    end
+  end
+end

data/lib/ultimate_json_rpc/extras/docs.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module UltimateJsonRpc
+  module Extras
+    class Docs
+      def initialize(server, json: JSON)
+        @server = server
+        @json = json
+      end
+
+      def to_markdown
+        lines = []
+        lines << title_section
+        lines << methods_section
+        lines << errors_section
+        lines.compact.join("\n")
+      end
+
+      private
+
+      def discover
+        @discover ||= begin
+          request = { "jsonrpc" => "2.0", "method" => "rpc.discover", "id" => 1 }
+          result = @json.parse(@server.handle(@json.generate(request)))
+          raise "rpc.discover returned an error: #{result["error"]&.inspect}" unless result.key?("result")
+
+          result["result"]
+        end
+      end
+
+      def title_section
+        info = discover["info"]
+        return "# API Reference\n" unless info
+
+        lines = []
+        lines << "# #{info["title"] || "API Reference"}\n"
+        lines << "#{info["description"]}\n" if info["description"]
+        lines << "**Version:** #{info["version"]}\n" if info["version"]
+        lines.join("\n")
+      end
+
+      def methods_section
+        methods = discover["methods"]
+        return nil if methods.nil? || methods.empty?
+
+        lines = ["## Methods\n"]
+        methods.each { |m| lines << method_entry(m) }
+        lines.join("\n")
+      end
+
+      def method_entry(method)
+        lines = ["### `#{method["name"]}`\n"]
+        append_method_metadata(lines, method)
+        lines.join("\n")
+      end
+
+      def append_method_metadata(lines, method)
+        lines << "#{method["description"]}\n" if method["description"]
+        lines << "*Deprecated: #{deprecation_text(method["deprecated"])}*\n" if method["deprecated"]
+        lines << params_table(method["params"]) if method["params"]&.any?
+        lines << return_section(method["result"]) if method["result"]
+      end
+
+      def deprecation_text(value)
+        value == true ? "This method is deprecated." : value.to_s
+      end
+
+      def params_table(params)
+        lines = ["**Parameters:**\n"]
+        lines << "| Name | Required | Type |"
+        lines << "|------|----------|------|"
+        params.each do |p|
+          required = p["required"] ? "Yes" : "No"
+          type = escape_cell(p.dig("schema", "type") || "-")
+          lines << "| `#{escape_cell(p["name"])}` | #{required} | #{type} |"
+        end
+        lines << ""
+        lines.join("\n")
+      end
+
+      def return_section(result)
+        type = result["type"] || result.dig("schema", "type")
+        return nil unless type
+
+        "**Returns:** `#{type}`\n"
+      end
+
+      def escape_cell(text)
+        text.to_s.gsub("|", "\\|").gsub(/\r?\n/, " ")
+      end
+
+      def errors_section
+        errors = discover.dig("components", "errors")
+        return nil unless errors&.any?
+
+        lines = ["## Error Codes\n"]
+        lines << "| Code | Name | Description |"
+        lines << "|------|------|-------------|"
+        errors.each do |e|
+          lines << "| #{e["code"]} | #{escape_cell(e["message"])} | #{escape_cell(e["data"] || "-")} |"
+        end
+        lines << ""
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/ultimate_json_rpc/extras/logging.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module UltimateJsonRpc
+  module Extras
+    class Logging
+      def initialize(server, logger, level: :info)
+        server.on(:response) do |request, _result, duration|
+          logger.public_send(level, "UltimateJsonRpc") do
+            "#{request.method_name} (#{format("%.1f", duration * 1000)}ms)"
+          end
+        end
+
+        server.on(:error) do |request, error, duration|
+          logger.error("UltimateJsonRpc") do
+            "#{request.method_name} #{error.class} (#{format("%.1f", duration * 1000)}ms)"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ultimate_json_rpc/extras/mcp.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require_relative "../transport/stdio"
+
+module UltimateJsonRpc
+  module Extras
+    class MCP
+      PROTOCOL_VERSION = "2024-11-05"
+
+      def initialize(server, input: $stdin, output: $stdout, json: JSON)
+        @app_server = server
+        @app_server.freeze
+        @json = json
+        @methods_cache = server.methods_info
+        @methods_index = @methods_cache.to_h { |m| [m["name"], m] }
+        @mcp_server = build_mcp_server
+        @input = input
+        @output = output
+        @stdio = nil
+        @call_id = 0
+      end
+
+      def run
+        @stdio = Transport::Stdio.new(@mcp_server, input: @input, output: @output)
+        @stdio.run
+      end
+
+      def stop
+        @stdio&.stop
+      end
+
+      def running?
+        @stdio&.running? || false
+      end
+
+      private
+
+      def build_mcp_server
+        mcp = Server.new(name: @app_server.name, version: @app_server.version, json: @json)
+        mcp.expose_method("initialize") { mcp_initialize }
+        mcp.expose_method("notifications/initialized") { nil }
+        mcp.expose_method("tools/list") { mcp_tools_list }
+        mcp.expose_method("tools/call") { |name:, arguments: {}| mcp_tools_call(name, arguments) }
+        mcp
+      end
+
+      def mcp_initialize
+        {
+          "protocolVersion" => PROTOCOL_VERSION,
+          "capabilities" => { "tools" => {} },
+          "serverInfo" => {
+            "name" => @app_server.name || "UltimateJsonRpc MCP Server",
+            "version" => @app_server.version || "0.0.0"
+          }
+        }
+      end
+
+      def mcp_tools_list
+        { "tools" => @methods_cache.map { |m| to_mcp_tool(m) } }
+      end
+
+      def mcp_tools_call(name, arguments)
+        request = build_call_request(name, arguments)
+        raw = @app_server.handle_parsed(request)
+        unless raw
+          return { "content" => [{ "type" => "text", "text" => "No response from server" }], "isError" => true }
+        end
+
+        response = @json.parse(raw)
+        format_call_response(response)
+      rescue StandardError => e
+        { "content" => [{ "type" => "text", "text" => e.message }], "isError" => true }
+      end
+
+      def to_mcp_tool(method_info)
+        tool = { "name" => method_info["name"] }
+        tool["description"] = method_info["description"] if method_info["description"]
+        tool["inputSchema"] = method_info["params"] ? build_input_schema(method_info["params"]) : { "type" => "object" }
+        tool
+      end
+
+      def build_input_schema(params)
+        schema = { "type" => "object" }
+        properties = {}
+        required = []
+
+        params.each do |p|
+          next if p["variadic"]
+
+          properties[p["name"]] = p.fetch("schema", {})
+          required << p["name"] if p["required"]
+        end
+
+        schema["properties"] = properties unless properties.empty?
+        schema["required"] = required unless required.empty?
+        schema
+      end
+
+      def build_call_request(name, arguments)
+        @call_id += 1
+        request = { "jsonrpc" => "2.0", "method" => name, "id" => "mcp-#{@call_id}" }
+        return request if arguments.nil? || arguments.empty?
+
+        method_info = @methods_index[name]
+        request["params"] = convert_arguments(arguments, method_info)
+        request
+      end
+
+      def convert_arguments(arguments, method_info)
+        params = method_info&.dig("params")
+        return arguments unless params
+
+        arguments = arguments.transform_keys(&:to_s)
+        return arguments if params.any? { |p| p["keyword"] }
+
+        convert_to_positional(arguments, params)
+      end
+
+      def convert_to_positional(arguments, params)
+        params.reject { |p| p["variadic"] }.map do |p|
+          validate_required_argument!(arguments, p)
+          arguments[p["name"]]
+        end
+      end
+
+      def validate_required_argument!(arguments, param)
+        name = param["name"]
+        return if name.empty? || !param["required"] || arguments.key?(name)
+
+        raise ArgumentError, "missing required argument: #{name}"
+      end
+
+      def format_call_response(response)
+        if response&.key?("error")
+          { "content" => [{ "type" => "text", "text" => response.dig("error", "message").to_s }], "isError" => true }
+        else
+          result = response&.fetch("result", nil)
+          text = result.is_a?(String) ? result : @json.generate(result)
+          { "content" => [{ "type" => "text", "text" => text }] }
+        end
+      end
+    end
+  end
+end

data/lib/ultimate_json_rpc/extras/profiler.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module UltimateJsonRpc
+  module Extras
+    class Profiler
+      DEFAULT_MAX_SAMPLES = 10_000
+
+      def initialize(server, max_samples: DEFAULT_MAX_SAMPLES)
+        @data = {}
+        @mutex = Mutex.new
+        @max_samples = max_samples
+        attach(server)
+      end
+
+      def [](method_name)
+        entry_copy = @mutex.synchronize do
+          entry = @data[method_name]
+          return nil unless entry
+
+          snapshot_entry(entry)
+        end
+        build_stats(entry_copy)
+      end
+
+      def tracked_methods
+        @mutex.synchronize { @data.keys.sort }
+      end
+      alias method_names tracked_methods
+
+      def stats
+        entries = @mutex.synchronize { @data.to_h { |name, entry| [name, snapshot_entry(entry)] } }
+        entries.transform_values { |entry| build_stats(entry) }
+      end
+
+      def reset
+        @mutex.synchronize { @data.clear }
+      end
+
+      private
+
+      def attach(server)
+        server.on(:response) { |request, _result, duration| record(request.method_name, duration) }
+        server.on(:error) { |request, _error, duration| record(request.method_name, duration) }
+      end
+
+      def record(method_name, duration)
+        @mutex.synchronize do
+          entry = (@data[method_name] ||= { count: 0, total: 0.0, min: Float::INFINITY, max: 0.0, durations: [] })
+          entry[:count] += 1
+          entry[:total] += duration
+          entry[:min] = duration if duration < entry[:min]
+          entry[:max] = duration if duration > entry[:max]
+          entry[:durations] << duration
+          entry[:durations].shift if entry[:durations].size > @max_samples
+        end
+      end
+
+      def snapshot_entry(entry)
+        { count: entry[:count], total: entry[:total], min: entry[:min], max: entry[:max],
+          durations: entry[:durations].dup }
+      end
+
+      def build_stats(entry)
+        sorted = entry[:durations].sort
+        timing_stats(entry).merge(percentile_stats(sorted))
+      end
+
+      def timing_stats(entry)
+        avg = entry[:count].zero? ? 0.0 : entry[:total] / entry[:count]
+        { count: entry[:count], total: entry[:total].round(6),
+          min: entry[:min].round(6), max: entry[:max].round(6), avg: avg.round(6),
+          samples: entry[:durations].size }
+      end
+
+      def percentile_stats(sorted)
+        { p50: percentile(sorted, 50), p95: percentile(sorted, 95), p99: percentile(sorted, 99) }
+      end
+
+      def percentile(sorted, pct)
+        return 0.0 if sorted.empty?
+
+        k = ((pct / 100.0) * sorted.size).ceil - 1
+        sorted[[k, 0].max].round(6)
+      end
+    end
+  end
+end

data/lib/ultimate_json_rpc/extras/rate_limit.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module UltimateJsonRpc
+  module Extras
+    class RateLimiter
+      def initialize(server, max:, period:, key: nil, code: 429, message: "Rate limit exceeded", only: nil, except: nil)
+        validate_code!(code)
+        @max = max
+        @period = period
+        @key_fn = build_key_fn(key)
+        @code = code
+        @message = message
+        @windows = {}
+        @mutex = Mutex.new
+        server.use(only:, except:) do |request, next_call|
+          check!(@key_fn.call(request))
+          next_call.call
+        end
+      end
+
+      private
+
+      def build_key_fn(key)
+        case key
+        when nil then ->(_) { :global }
+        when Symbol then ->(req) { req.context.fetch(key, :unknown) }
+        when Proc then key
+        else raise ArgumentError, "key must be nil, a Symbol, or a Proc"
+        end
+      end
+
+      def check!(bucket)
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @mutex.synchronize do
+          window = (@windows[bucket] ||= [])
+          window.reject! { |t| now - t > @period }
+          raise Core::ApplicationError.new(code: @code, message: @message) if window.size >= @max
+
+          window << now
+          evict_stale!(now)
+        end
+      end
+
+      def evict_stale!(now)
+        @windows.delete_if { |_, w| w.none? { |t| now - t <= @period } } if @windows.size > 20
+      end
+
+      def validate_code!(code)
+        raise ArgumentError, "code must be an Integer" unless code.is_a?(Integer)
+        return unless code.between?(Core::RESERVED_ERROR_MIN, Core::RESERVED_ERROR_MAX)
+
+        raise ArgumentError,
+              "code #{code} is in the reserved JSON-RPC range (#{Core::RESERVED_ERROR_MIN}..#{Core::RESERVED_ERROR_MAX})"
+      end
+    end
+  end
+end

data/lib/ultimate_json_rpc/extras/recorder.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module UltimateJsonRpc
+  module Extras
+    class Recorder
+      UNSET = Object.new.freeze
+      private_constant :UNSET
+
+      def initialize(server, output: nil, max_exchanges: nil, json: JSON)
+        @exchanges = []
+        @max_exchanges = max_exchanges
+        @output = output
+        @json = json
+        @mutex = Mutex.new
+        @output_mutex = Mutex.new
+        attach(server)
+      end
+
+      def exchanges
+        @mutex.synchronize { @exchanges.dup }
+      end
+
+      def clear
+        @mutex.synchronize { @exchanges.clear }
+      end
+
+      def size
+        @mutex.synchronize { @exchanges.size }
+      end
+
+      private
+
+      def attach(server)
+        server.on(:response) do |request, result, duration|
+          record(request, duration, result:)
+        end
+
+        server.on(:error) do |request, error, duration|
+          record(request, duration, error: { "class" => error.class.name, "message" => error.message })
+        end
+      end
+
+      def record(request, duration, result: UNSET, error: nil)
+        entry = { "method" => request.method_name, "params" => request.params,
+                  "duration" => duration.round(6) }
+        entry["result"] = result unless result.equal?(UNSET)
+        entry["error"] = error if error
+        @mutex.synchronize do
+          @exchanges << entry
+          @exchanges.shift if @max_exchanges && @exchanges.size > @max_exchanges
+        end
+        write_output(entry)
+      end
+
+      def write_output(entry)
+        return unless @output
+
+        @output_mutex.synchronize do
+          @output.puts(@json.generate(entry))
+          @output.flush
+        end
+      rescue IOError, SystemCallError
+        # Output broken; exchange still recorded in memory
+      end
+    end
+  end
+end

data/lib/ultimate_json_rpc/extras/test_helpers.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module UltimateJsonRpc
+  module Extras
+    module TestHelpers
+      def rpc_call(server, method, params: nil, id: 1)
+        json = rpc_json_adapter(server)
+        request = { "jsonrpc" => "2.0", "method" => method, "id" => id }
+        request["params"] = params if params
+        json.parse(server.handle(json.generate(request)))
+      end
+
+      def rpc_notify(server, method, params: nil)
+        json = rpc_json_adapter(server)
+        request = { "jsonrpc" => "2.0", "method" => method }
+        request["params"] = params if params
+        server.handle(json.generate(request))
+      end
+
+      def rpc_batch(server, *requests)
+        json = rpc_json_adapter(server)
+        result = server.handle(json.generate(requests))
+        result ? json.parse(result) : nil
+      end
+
+      def assert_rpc_success(response, expected: :__not_given__, msg: nil)
+        assert response.key?("result"), msg || "Expected success response but got error: #{response["error"]&.inspect}"
+        refute response.key?("error"), msg || "Expected no error but got: #{response["error"]&.inspect}"
+        return if expected == :__not_given__
+
+        expected.nil? ? assert_nil(response["result"], msg) : assert_equal(expected, response["result"], msg)
+      end
+
+      def assert_rpc_error(response, code: nil, message: nil, msg: nil)
+        assert response.key?("error"), msg || "Expected error response but got result: #{response["result"]&.inspect}"
+        refute response.key?("result"), msg || "Expected no result but got: #{response["result"]&.inspect}"
+        assert_equal code, response["error"]["code"], msg if code
+        assert_equal message, response["error"]["message"], msg if message
+      end
+
+      def assert_rpc_notification(server, method, params: nil, msg: nil)
+        result = rpc_notify(server, method, params: params)
+        assert_nil result, msg || "Expected nil for notification but got: #{result.inspect}"
+      end
+
+      private
+
+      def rpc_json_adapter(server)
+        server.json_adapter
+      end
+    end
+  end
+end