spikard 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ddca560615174394e71fc0066ee7749daa3fcc5e91c8387c3abcc6e8685c7f82
-  data.tar.gz: 273523e0e3aa0068e95b660744bf4278cfc6b157d61a9d935ac6953da7431fb9
+  metadata.gz: b6d3ace9a6aa31de25bf31238a3a2425546c5137f85036cce599ac251cf63e25
+  data.tar.gz: b60af042fe08fca1e779d15fea771e6f29c864491cad98260fd3c1aa4887f538
 SHA512:
-  metadata.gz: 0b6005c4cc1e6f32e2e5b5157874b76b0d797931a792c12bf07324f04a83ba17210fd56ff8a495534056a7ac85bd07bcbc6af487c071c41ff0f6aa76dbfe6e67
-  data.tar.gz: 342a8ed2c1d180180701aedb5cc01467eadb3da8317310678b4b9857a002ba09231b5b1c5d6a85fc0f07c1e432a6cb45a97a92fe30c583a5abe406b625494dd2
+  metadata.gz: 8786dce5521a0d9d4c38dbcb4c433bed930bc77dba34ad149a42a00d03803ffba58318f87c44abee93175d842ba2d94bb3af0b3c6a0e156179d431c441921473
+  data.tar.gz: 6cf9e10315120acf2593693f9a998487e0c3613ba50a3c4693ae408747f7b9efae82cc57a4962c9d32eb337745593e70fbc00bd2cb1e57949d72363db0da265b

data/ext/spikard_rb/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "spikard-rb-ext"
-version = "0.11.0"
+version = "0.12.0"
 edition = "2024"
 license = "MIT"
 authors = ["Na'aman Hirschfeld <nhirschfeld@gmail.com>"]

data/lib/spikard/config.rb

@@ -340,6 +340,37 @@ module Spikard
     end
   end
 
+  # JSON-RPC endpoint configuration.
+  class JsonRpcConfig
+    attr_accessor :enabled, :endpoint_path, :enable_batch, :max_batch_size
+
+    # @param enabled [Boolean] Enable JSON-RPC endpoint registration (default: true)
+    # @param endpoint_path [String] JSON-RPC endpoint path (default: "/rpc")
+    # @param enable_batch [Boolean] Enable JSON-RPC batch support (default: true)
+    # @param max_batch_size [Integer] Maximum batch size (default: 100)
+    def initialize(enabled: true, endpoint_path: '/rpc', enable_batch: true, max_batch_size: 100)
+      @enabled = normalize_boolean('enabled', enabled)
+      @endpoint_path = endpoint_path
+      @enable_batch = normalize_boolean('enable_batch', enable_batch)
+      @max_batch_size = normalize_positive_integer('max_batch_size', max_batch_size)
+    end
+
+    private
+
+    def normalize_boolean(name, value)
+      return value if [true, false].include?(value)
+
+      raise ArgumentError, "#{name} must be a boolean"
+    end
+
+    def normalize_positive_integer(name, value)
+      raise ArgumentError, "#{name} must be an Integer" unless value.is_a?(Integer)
+      return value if value.positive?
+
+      raise ArgumentError, "#{name} must be > 0"
+    end
+  end
+
   # Complete server configuration for Spikard.
   #
   # This is the main configuration object that controls all aspects of the server
@@ -369,7 +400,7 @@ module Spikard
                   :enable_request_id, :max_body_size, :request_timeout,
                   :compression, :rate_limit, :jwt_auth, :api_key_auth,
                   :static_files, :graceful_shutdown, :shutdown_timeout,
-                  :openapi
+                  :openapi, :jsonrpc
 
     # @param host [String] Host address to bind to (default: "127.0.0.1")
     # @param port [Integer] Port number to listen on (default: 8000, range: 1-65535)
@@ -385,6 +416,7 @@ module Spikard
     # @param graceful_shutdown [Boolean] Enable graceful shutdown (default: true)
     # @param shutdown_timeout [Integer] Graceful shutdown timeout in seconds (default: 30)
     # @param openapi [OpenApiConfig, nil] OpenAPI configuration (default: nil/disabled)
+    # @param jsonrpc [JsonRpcConfig, nil] JSON-RPC configuration (default: nil/disabled)
     def initialize(
       host: '127.0.0.1',
       port: 8000,
@@ -399,7 +431,8 @@ module Spikard
       static_files: [],
       graceful_shutdown: true,
       shutdown_timeout: 30,
-      openapi: nil
+      openapi: nil,
+      jsonrpc: nil
     )
       @host = host
       @port = normalize_port(port)
@@ -415,6 +448,7 @@ module Spikard
       @graceful_shutdown = normalize_boolean('graceful_shutdown', graceful_shutdown)
       @shutdown_timeout = normalize_timeout('shutdown_timeout', shutdown_timeout)
       @openapi = openapi
+      @jsonrpc = jsonrpc
     end
 
     private

data/lib/spikard/testing.rb

@@ -6,6 +6,8 @@ require 'timeout'
 module Spikard
   # Testing helpers that wrap the native Ruby extension.
   module Testing
+    GRAPHQL_WS_MAX_CONTROL_MESSAGES = 32
+
     module_function
 
     def create_test_client(app, config: nil)
@@ -45,6 +47,7 @@ module Spikard
     end
 
     # High level wrapper around the native test client.
+    # rubocop:disable Metrics/ClassLength
     class TestClient
       def initialize(native)
         @native = native
@@ -77,6 +80,118 @@ module Spikard
         SseStream.new(native_sse)
       end
 
+      def graphql(query, variables = nil, operation_name = nil, path: '/graphql')
+        payload = { query: query }
+        payload[:variables] = variables unless variables.nil?
+        payload[:operationName] = operation_name unless operation_name.nil?
+        request('POST', path, nil, nil, json: payload)
+      end
+
+      def graphql_with_status(query, variables = nil, operation_name = nil, path: '/graphql')
+        response = graphql(query, variables, operation_name, path: path)
+        [response.status, response]
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/BlockLength, Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/MethodLength, Metrics/PerceivedComplexity
+      def graphql_subscription(query, variables = nil, operation_name = nil, path: '/graphql')
+        operation_id = 'spikard-subscription-1'
+        payload = { query: query }
+        payload[:variables] = variables unless variables.nil?
+        payload[:operationName] = operation_name unless operation_name.nil?
+
+        ws = websocket(path)
+        ws.send_json({ 'type' => 'connection_init' })
+
+        acknowledged = false
+        GRAPHQL_WS_MAX_CONTROL_MESSAGES.times do
+          message = websocket_protocol_message(ws.receive_json)
+          message_type = websocket_field(message, :type)
+
+          if message_type == 'connection_ack'
+            acknowledged = true
+            break
+          end
+
+          if message_type == 'ping'
+            pong = { 'type' => 'pong' }
+            pong['payload'] = websocket_field(message, :payload) if message.key?('payload') || message.key?(:payload)
+            ws.send_json(pong)
+            next
+          end
+
+          if %w[connection_error error].include?(message_type)
+            raise "GraphQL subscription rejected during init: #{message}"
+          end
+        end
+
+        raise 'No GraphQL connection_ack received' unless acknowledged
+
+        ws.send_json({
+                       'id' => operation_id,
+                       'type' => 'subscribe',
+                       'payload' => payload
+                     })
+
+        event = nil
+        errors = []
+        complete_received = false
+
+        GRAPHQL_WS_MAX_CONTROL_MESSAGES.times do
+          message = websocket_protocol_message(ws.receive_json)
+          message_type = websocket_field(message, :type)
+          message_id = websocket_field(message, :id)
+          id_matches = message_id.nil? || message_id == operation_id
+
+          if message_type == 'next' && id_matches
+            event = websocket_field(message, :payload)
+            ws.send_json({ 'id' => operation_id, 'type' => 'complete' })
+
+            begin
+              maybe_complete = websocket_protocol_message(ws.receive_json)
+              complete_type = websocket_field(maybe_complete, :type)
+              complete_id = websocket_field(maybe_complete, :id)
+              complete_received = complete_type == 'complete' && (complete_id.nil? || complete_id == operation_id)
+            rescue StandardError
+              # Some servers close immediately after client complete.
+            end
+            break
+          end
+
+          if message_type == 'error'
+            errors << (websocket_field(message, :payload) || message)
+            break
+          end
+
+          if message_type == 'complete' && id_matches
+            complete_received = true
+            break
+          end
+
+          next unless message_type == 'ping'
+
+          pong = { 'type' => 'pong' }
+          pong['payload'] = websocket_field(message, :payload) if message.key?('payload') || message.key?(:payload)
+          ws.send_json(pong)
+        end
+
+        if event.nil? && errors.empty? && !complete_received
+          raise 'No GraphQL subscription event received before timeout'
+        end
+
+        {
+          'operation_id' => operation_id,
+          'acknowledged' => true,
+          'event' => event,
+          'errors' => errors,
+          'complete_received' => complete_received
+        }
+      ensure
+        ws&.close
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/PerceivedComplexity
+      # rubocop:enable Metrics/AbcSize, Metrics/BlockLength, Metrics/CyclomaticComplexity
+
       def close
         @native.close
       end
@@ -123,7 +238,28 @@ module Spikard
         payload[:files] = files if files
         payload
       end
+
+      def websocket_protocol_message(raw)
+        case raw
+        when String
+          parsed = JSON.parse(raw)
+          raise 'Expected GraphQL WebSocket JSON object message' unless parsed.is_a?(Hash)
+
+          parsed
+        when Hash
+          raw
+        else
+          raise "Expected GraphQL WebSocket message object, got #{raw.class}"
+        end
+      rescue JSON::ParserError => e
+        raise "Invalid GraphQL WebSocket message: #{e.message}"
+      end
+
+      def websocket_field(message, key)
+        message[key.to_s] || message[key.to_sym]
+      end
     end
+    # rubocop:enable Metrics/ClassLength
 
     # WebSocket test connection wrapper
     class WebSocketTestConnection

data/lib/spikard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Spikard
-  VERSION = '0.11.0'
+  VERSION = '0.12.0'
 end

data/lib/spikard.rb

@@ -45,10 +45,6 @@ if defined?(Spikard::Native::TestClient) && !Spikard::Native::TestClient.method_
   end
 end
 
-# Convenience aliases and methods at top level
-module Spikard
-  TestClient = Testing::TestClient
-
-  # Handler wrapper utilities
-  extend HandlerWrapper
-end
+# Convenience aliases and methods
+Spikard::TestClient = Spikard::Testing::TestClient
+Spikard.extend Spikard::HandlerWrapper