carrot_rpc 0.2.3.pre

data/lib/carrot_rpc/cli.rb

@@ -0,0 +1,110 @@
+# Command-line interface for {CarrotRpc}
+module CarrotRpc::CLI
+  def self.add_common_options(option_parser)
+    option_parser.separator ""
+
+    option_parser.separator "Common options:"
+    option_parser.on("-h", "--help") do
+      puts option_parser.to_s
+      exit
+    end
+
+    option_parser.on("-v", "--version") do
+      puts CarrotRpc::VERSION
+      exit
+    end
+  end
+
+  # There are just too many options in the Process options category and they can't really be broken down more
+  # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+
+  # Add "Process options" to `option_parser`.
+  #
+  # @param option_parser [OptionParser]
+  # @return [OptionParser]
+  def self.add_process_options(option_parser)
+    option_parser.separator ""
+
+    option_parser.separator "Process options:"
+    option_parser.on("-d", "--daemonize", "run daemonized in the background (default: false)") do
+      CarrotRpc.configuration.daemonize = true
+    end
+
+    option_parser.on(" ", "--pidfile PIDFILE", "the pid filename") do |value|
+      CarrotRpc.configuration.pidfile = value
+    end
+
+    option_parser.on("-s", "--runloop_sleep VALUE", Float, "Configurable sleep time in the runloop") do |value|
+      CarrotRpc.configuration.runloop_sleep = value
+    end
+
+    option_parser.on(
+      " ",
+      "--autoload_rails value",
+      "loads rails env by default. Uses Rails Logger by default."
+    ) do |value|
+      pv = value == "false" ? false : true
+      CarrotRpc.configuration.autoload_rails = pv
+    end
+
+    option_parser.on(" ", "--logfile VALUE", "relative path and name for Log file. Overrides Rails logger.") do |value|
+      CarrotRpc.configuration.logfile = File.expand_path("../../#{value}", __FILE__)
+    end
+
+    option_parser.on(
+      " ",
+      "--loglevel VALUE",
+      "levels of loggin: DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN"
+    ) do |value|
+      CarrotRpc.configuration.loglevel = Logger.const_get(value) || 0
+    end
+
+    # Optional. Defaults to using the ENV['RABBITMQ_URL']
+    option_parser.on(
+      " ",
+      "--rabbitmq_url VALUE",
+      "connection string to RabbitMQ 'amqp://user:pass@host:10000/vhost'"
+    ) do |value|
+      CarrotRpc.configuration.bunny = Bunny.new(value)
+    end
+  end
+
+  def self.add_ruby_options(option_parser)
+    option_parser.separator ""
+
+    option_parser.separator "Ruby options:"
+
+    option_parser.on("-I", "--include PATH", "an additional $LOAD_PATH") do |value|
+      $LOAD_PATH.unshift(*value.split(":").map { |v| File.expand_path(v) })
+    end
+
+    option_parser.on("--debug", "set $DEBUG to true") do
+      $DEBUG = true
+    end
+
+    option_parser.on("--warn", "enable warnings") do
+      $-w = true
+    end
+  end
+
+  # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+  def self.option_parser
+    option_parser = OptionParser.new
+    option_parser.banner =  "RPC Server Runner for RabbitMQ RPC Services."
+    option_parser.separator ""
+    option_parser.separator "Usage: server [options]"
+
+    add_process_options(option_parser)
+    add_ruby_options(option_parser)
+    add_common_options(option_parser)
+
+    option_parser.separator ""
+
+    option_parser
+  end
+
+  def self.parse_options(args = ARGV)
+    option_parser.parse!(args)
+  end
+end

data/lib/carrot_rpc/client_server.rb

@@ -0,0 +1,25 @@
+# Common functionality for Client and Server.
+module CarrotRpc::ClientServer
+  # @overload queue_name(new_name)
+  #   @note Default naming not performed. Class must pass queue name.
+  #
+  #   Allows for class level definition of queue name.
+  #
+  #   @param new_name [String] the queue name for the class.
+  #   @return [String] `new_name`
+  #
+  # @overload queue_name
+  #   The current queue name previously set with `#queue_name(new_name)`.
+  #
+  #   @return [String]
+  def queue_name(*args)
+    if args.length == 0
+      @queue_name
+    elsif args.length == 1
+      @queue_name = args[0]
+    else
+      fail ArgumentError,
+           "queue_name(new_name) :: new_name or queue_name() :: current_name are the only ways to call queue_name"
+    end
+  end
+end

data/lib/carrot_rpc/configuration.rb

@@ -0,0 +1,17 @@
+# Global configuration for {CarrotRpc}.  Access with {CarrotRpc.configuration}.
+class CarrotRpc::Configuration
+  attr_accessor :logger, :logfile, :loglevel, :daemonize, :pidfile, :runloop_sleep, :autoload_rails, :bunny
+
+  # logfile - set logger to a file. overrides rails logger.
+
+  def initialize
+    @logfile = nil
+    @loglevel = Logger::DEBUG
+    @logger = nil
+    @daemonize = false
+    @pidfile = nil
+    @runloop_sleep = 0
+    @autoload_rails = true
+    @bunny = nil
+  end
+end

data/lib/carrot_rpc/error/code.rb

@@ -0,0 +1,17 @@
+# An enum of predefined {RpcServer::Server#code}
+module CarrotRpc::Error::Code
+  # Internal JSON-RPC error.
+  INTERNAL_ERROR   = -32_603
+
+  # Invalid method parameter(s).
+  INVALID_PARAMS   = -32_602
+
+  # The JSON sent is not a valid Request object.
+  INVALID_REQUEST  = -32_600
+
+  # The method does not exist / is not available.
+  METHOD_NOT_FOUND = -32_601
+
+  # Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.
+  PARSE_ERROR      = -32_700
+end

data/lib/carrot_rpc/error.rb

@@ -0,0 +1,43 @@
+# Error raised by an {RpcServer} method to signal that a
+# {http://www.jsonrpc.org/specification#error_object JSON RPC 2.0 Response Error object} should be the reply.
+class CarrotRpc::Error < StandardError
+  autoload :Code, "carrot_rpc/error/code"
+
+  # @return [Integer]A Number that indicates the error type that occurred. Some codes are
+  #   {http://www.jsonrpc.org/specification#error_object predefined}.
+  attr_reader :code
+
+  # @return [Object, nil] A Primitive or Structured value that contains additional information about the error.
+  #   This may be omitted. The value of this member is defined by the Server (e.g. detailed error information,
+  #   nested errors etc.).
+  attr_reader :data
+
+  # @param code [Integer] A Number that indicates the error type that occurred.  Favor using the
+  #   {http://www.jsonrpc.org/specification#error_object predefined codes}.
+  # @param message [String] A String providing a short description of the error. The message SHOULD be limited to a
+  #   concise single sentence.
+  # @param data [Object, nil] A Primitive or Structured value that contains additional information about the error.
+  #   This may be omitted. The value of this member is defined by the Server (e.g. detailed error information,
+  #   nested errors etc.).
+  def initialize(code:, message:, data: nil)
+    @code = code
+    @data = data
+    super(message)
+  end
+
+  # A properly formatted {http://www.jsonrpc.org/specification#error_object JSON RPC Error object}.
+  #
+  # @return [Hash{code: String, message: String}, Hash{code: String, data: Object, message: String}]
+  def serialized_message
+    serialized = {
+      code: code,
+      message: message
+    }
+
+    if data
+      serialized[:data] = data
+    end
+
+    serialized
+  end
+end

data/lib/carrot_rpc/hash_extensions.rb

@@ -0,0 +1,22 @@
+# Refine the Hash class with new methods and functionality.
+module CarrotRpc::HashExtensions
+  refine Hash do
+    # Utility method to rename keys in a hash
+    # @param [String] find the text to look for in a keys
+    # @param [String] replace the text to replace the found text
+    # @return [Hash] a new hash
+    def rename_keys(find, replace, new_hash = {})
+      each do |k, v|
+        new_key = k.to_s.gsub(find, replace)
+
+        new_hash[new_key] = if v.is_a? Hash
+                              v.rename_keys(find, replace)
+                            else
+                              v
+                            end
+      end
+
+      new_hash
+    end
+  end
+end

data/lib/carrot_rpc/rpc_client.rb

@@ -0,0 +1,117 @@
+require "securerandom"
+
+# Generic class for all RPC Consumers. Use as a base class to build other RPC Consumers for related functionality.
+# Let's define a naming convention here for subclasses becuase I don't want to write a Confluence doc.
+# All subclasses should have the following naming convention: <Name>RpcConsumer  ex: PostRpcConsumer
+class CarrotRpc::RpcClient
+  using CarrotRpc::HashExtensions
+
+  attr_reader :channel, :server_queue, :logger
+
+  extend CarrotRpc::ClientServer
+
+  # Use defaults for application level connection to RabbitMQ
+  # All RPC data goes over the same queue. I think that's ok....
+  def initialize(config: nil)
+    config ||= CarrotRpc.configuration
+    @channel = config.bunny.create_channel
+    @logger = config.logger
+    # auto_delete => false keeps the queue around until RabbitMQ restarts or explicitly deleted
+    @server_queue = @channel.queue(self.class.queue_name, auto_delete: false)
+
+    # Setup a direct exchange.
+    @exchange = @channel.default_exchange
+  end
+
+  # Starts the connection to listen for messages.
+  def start
+    # Empty queue name ends up creating a randomly named queue by RabbitMQ
+    # Exclusive => queue will be deleted when connection closes. Allows for automatic "cleanup".
+    @reply_queue = @channel.queue("", exclusive: true)
+
+    # setup a hash for results with a Queue object as a value
+    @results = Hash.new { |h, k| h[k] = Queue.new }
+
+    # setup subscribe block to Service
+    # block => false is a non blocking IO option.
+    @reply_queue.subscribe(block: false) do |_delivery_info, properties, payload|
+      result = JSON.parse(payload).rename_keys("-", "_").with_indifferent_access
+      @results[properties[:correlation_id]].push(result[:result])
+    end
+  end
+
+  # params is an array of method argument values
+  # programmer implementing this class must know about the remote service
+  # the remote service must have documented the methods and arguments in order for this pattern to work.
+  # TODO: change to a hash to account for keyword arguments???
+  #
+  # @param remote_method [String, Symbol] the method to be called on current receiver
+  # @param params [Hash] the arguments for the method being called.
+  # @return [Object] the result of the method call.
+  def remote_call(remote_method, params)
+    correlation_id = SecureRandom.uuid
+    publish(correlation_id: correlation_id, method: remote_method, params: params.rename_keys("_", "-"))
+    wait_for_result(correlation_id)
+  end
+
+  def wait_for_result(correlation_id)
+    # `pop` is `Queue#pop`, so it is blocking on the receiving thread and this must happend before the `Hash.delete` or
+    # the receiving thread won't be able to find the correlation_id in @results
+    result = @results[correlation_id].pop
+    @results.delete correlation_id # remove item from hash. prevents memory leak.
+    result
+  end
+
+  def publish(correlation_id:, method:, params:)
+    message = message(
+      correlation_id: correlation_id,
+      params:         params,
+      method:         method
+    )
+    # Reply To => make sure the service knows where to send it's response.
+    # Correlation ID => identify the results that belong to the unique call made
+    @exchange.publish(message.to_json, routing_key: @server_queue.name, correlation_id: correlation_id,
+                                       reply_to:                                     @reply_queue.name)
+  end
+
+  def message(correlation_id:, method:, params:)
+    {
+      id:      correlation_id,
+      jsonrpc: "2.0",
+      method:  method,
+      params:  params.except(:controller, :action)
+    }
+  end
+
+  # Convience method as a resource alias for index action.
+  # To customize, override the method in your class.
+  #
+  # @param params [Hash] the arguments for the method being called.
+  def index(params)
+    remote_call("index", params)
+  end
+
+  # Convience method as a resource alias for show action.
+  # To customize, override the method in your class.
+  #
+  # @param params [Hash] the arguments for the method being called.
+  def show(params)
+    remote_call("show", params)
+  end
+
+  # Convience method as a resource alias for create action.
+  # To customize, override the method in your class.
+  #
+  # @param params [Hash] the arguments for the method being called.
+  def create(params)
+    remote_call("create", params)
+  end
+
+  # Convience method as a resource alias for update action.
+  # To customize, override the method in your class.
+  #
+  # @param params [Hash] the arguments for the method being called.
+  def update(params)
+    remote_call("update", params)
+  end
+end

data/lib/carrot_rpc/rpc_server/jsonapi_resources/actions.rb

@@ -0,0 +1,108 @@
+# The common CRUD actions for {CarrotRpc::RpcServer::JSONAPIResources}
+module CarrotRpc::RpcServer::JSONAPIResources::Actions
+  #
+  # CONSTANTS
+  #
+
+  # Set of allowed actions for JSONAPI::Resources
+  NAME_SET = Set.new(
+    [
+      # Mimic behaviour of `POST <collection>` routes
+      :create,
+      # Mimic behaviour of `POST <collection>/<id>/relationships/<relation>` routes
+      :create_relationship,
+      # Mimic behavior of `DELETE <collection>/<id>` routes
+      :destroy,
+      # Mimic behavior of `DELETE <collection>/<id>/relationships/<relationship>` routes
+      :destroy_relationship,
+      # Mimics behavior of `GET <collection>/<id>/<relationship>` routes
+      :get_related_resource,
+      # Mimic behavior of `GET <collection>` routes
+      :index,
+      # Mimic behavior of `GET <collection>/<id>` routes
+      :show,
+      # Mimic behavior of `GET <collection>/<id>/relationships/<relationship>` routes
+      :show_relationship,
+      # Mimic behavior of `PATCH|PUT <collection>/<id>` routes
+      :update,
+      # Mimic behavior of `PATCH|PUT <collection>/<id>/relationships/<relationship>` routes
+      :update_relationship
+    ]
+  ).freeze
+
+  #
+  # Module Methods
+  #
+
+  # Defines an action method, `name` on `action_module`.
+  #
+  # @param action_module [Module] Module where action methods are defined so that they can be called with `super` if
+  #   overridden.
+  # @param name [Symbol] an element of `NAME_SET`.
+  # @return [void]
+  def self.define_action_method(action_module, name)
+    action_module.send(:define_method, name) do |params|
+      process_request_params(
+        ActionController::Parameters.new(
+          params.merge(
+            action: name,
+            controller: controller
+          )
+        )
+      )
+    end
+  end
+
+  #
+  # Instance Methods
+  #
+
+  # Adds actions in `names` to the current class.
+  #
+  # The actions are added to a mixin module `self::Actions`, so that the action methods can be overridden and `super`
+  # will work.
+  #
+  # @example Adding only show actions
+  #     extend RpcServer::JSONAPIResources::Actions
+  #     include RpcServer::JSONAPIResources
+  #
+  #     actions :create,
+  #             :destroy,
+  #             :index,
+  #             :show,
+  #             :update
+  #
+  # @param names [Array<Symbol>] a array of a subset of {NAME_SET}.
+  # @return [void]
+  # @raise (see #valid_actions)
+  def actions(*names)
+    valid_actions!(names)
+
+    # an include module so that `super` works if the method is overridden
+    action_module = Module.new
+
+    names.each do |name|
+      CarrotRpc::RpcServer::JSONAPIResources::Actions.define_action_method(action_module, name)
+    end
+
+    const_set(:Actions, action_module)
+
+    include action_module
+  end
+
+  private
+
+  # Checks that all `names` are valid action names.
+  #
+  # @raise [ArgumentError] if any element of `names` is not an element of `NAME_SET`.
+  def valid_actions!(names)
+    given_name_set = Set.new(names)
+    unknown_name_set = given_name_set - NAME_SET
+
+    unless unknown_name_set.empty?
+      fail ArgumentError,
+           "#{unknown_name_set.to_a.sort.to_sentence} are not elements of known actions " \
+           "(#{NAME_SET.to_a.sort.to_sentence})"
+    end
+  end
+end

data/lib/carrot_rpc/rpc_server/jsonapi_resources.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+# Allows a {CarrotRpc::RpcServer} subclass to behave the same as a controller that does
+# `include JSONAPI::ActsAsResourceController`
+module CarrotRpc::RpcServer::JSONAPIResources
+  autoload :Actions, "carrot_rpc/rpc_server/jsonapi_resources/actions"
+
+  # The base "meta" to include in the top-level of all JSON API documents.
+  #
+  # @param request [JSONAPI::Request] the current request.  `JSONAPI::Request#warnings` are merged into the
+  #   {#base_response_meta}.
+  # @return [Hash]
+  def base_meta(request)
+    if request.nil? || request.warnings.empty?
+      base_response_meta
+    else
+      base_response_meta.merge(warnings: request.warnings)
+    end
+  end
+
+  # The base "links" to include the top-level of all JSON API documents before any operation result links are added.
+  #
+  # @return [Hash] Defaults to `{}`.
+  def base_response_links
+    {}
+  end
+
+  # The base "meta" to include in the top-level of all JSON API documents before being merged with any request warnings
+  # in {#base_meta}.
+  #
+  # @return [Hash] Defaults to `{}`.
+  def base_response_meta
+    {}
+  end
+
+  # The operations processor in the configuration or override this to use another operations processor
+  #
+  # @return [JSONAPI::OperationsProcessor]
+  def create_operations_processor
+    JSONAPI.configuration.operations_processor.new
+  end
+
+  # The JSON API Document for the `operation_results` and `request`.
+  #
+  # @param operation_results [JSONAPI::OperationResults] The result of processing the `request`.
+  # @param request [JSONAPI::Request] the request to respond to.
+  # @return [JSONAPI::ResponseDocument]
+  def create_response_document(operation_results:, request:) # rubocop:disable  Metrics/MethodLength
+    JSONAPI::ResponseDocument.new(
+      operation_results,
+      primary_resource_klass: resource_klass,
+      include_directives: request ? request.include_directives : nil,
+      fields: request ? request.fields : nil,
+      base_url: base_url,
+      key_formatter: key_formatter,
+      route_formatter: route_formatter,
+      base_meta: base_meta(request),
+      base_links: base_response_links,
+      resource_serializer_klass: resource_serializer_klass,
+      request: request,
+      serialization_options: serialization_options
+    )
+  end
+
+  # @note Override this to process other exceptions. Be sure to either call `super(exception)` or handle
+  #   `JSONAPI::Exceptions::Error` and `raise` unhandled exceptions.
+  #
+  # @param exception [Exception] the original, exception that was caught
+  # @param request [JSONAPI::Request] the request that triggered the `exception`
+  # @return (see #render_errors)
+  def handle_exceptions(exception, request:)
+    case exception
+    when JSONAPI::Exceptions::Error
+      render_errors(exception.errors, request: request)
+    else
+      internal_server_error = JSONAPI::Exceptions::InternalServerError.new(exception)
+      logger.error { # rubocop:disable Style/BlockDelimiters
+        "Internal Server Error: #{exception.message} #{exception.backtrace.join("\n")}"
+      }
+      render_errors(internal_server_error.errors)
+    end
+  end
+
+  # @note Override if you want to set a per controller key format.
+  #
+  # Control by setting in an initializer:
+  #     JSONAPI.configuration.json_key_format = :camelized_key
+  #
+  # @return [JSONAPI::KeyFormatter]
+  def key_formatter
+    JSONAPI.configuration.key_formatter
+  end
+
+  # Processes the params as a request and renders a response.
+  #
+  # @param params [ActionController::Parameter{action: Symbol, controller: String}] **MUST** set `:action` to the action
+  #   name so that `JSONAPI::Request#setup_action` can dispatch to the correct `setup_*_action` method.  **MUST** set
+  #   `:controller` to a URL name for the controller, such as `"api/v1/partner"`, so that the resource can be looked up
+  #   by the controller name.
+  # @return [Hash] rendered, but not encoded JSON.
+  def process_request_params(params) # rubocop:disable Metrics/MethodLength
+    request = JSONAPI::Request.new(
+      params,
+      context: {},
+      key_formatter: key_formatter,
+      server_error_callbacks: []
+    )
+
+    if !request.errors.empty?
+      render_errors(request.errors, request: request)
+    else
+      operation_results = create_operations_processor.process(request)
+      render_results(
+        operation_results: operation_results,
+        request: request
+      )
+    end
+  rescue => e
+    handle_exceptions(e, request: request)
+  end
+
+  # Renders the `errors` as a JSON API errors Document.
+  #
+  # @param errors [Array<JSONAPI::Error>] errors to use in a JSON API errors Document
+  # @param request [JSONAPI::Request] the request that caused the `errors`.
+  # @return [Hash] rendered, but not encoded JSON
+  def render_errors(errors, request:)
+    operation_results = JSONAPI::OperationResults.new
+    result = JSONAPI::ErrorsOperationResult.new(errors[0].status, errors)
+    operation_results.add_result(result)
+
+    render_results(
+      operation_results: operation_results,
+      request: request
+    )
+  end
+
+  # Renders the `operation_results` as a JSON API Document.
+  #
+  # @param operation_results [JSONAPI::OperationResults] a collection of results from various operations.
+  # @param request [JSONAPI::Request] the original request that generated the `operation_results`.
+  # @return [Hash] rendered, but not encoded JSON
+  def render_results(operation_results:, request:)
+    response_document = create_response_document(
+      operation_results: operation_results,
+      request: request
+    )
+    response_document.contents.as_json
+  end
+
+  # Class to serialize `JSONAPI::Resource`s to JSON API documents.
+  #
+  # @return [Class<JSONAPI::ResourceSerializer>]
+  def resource_serializer_klass
+    @resource_serializer_klass ||= JSONAPI::ResourceSerializer
+  end
+
+  # Control by setting in an initializer:
+  #     JSONAPI.configuration.route = :camelized_route
+  #
+  # @return [JSONAPI::RouteFormatter]
+  def route_formatter
+    JSONAPI.configuration.route_formatter
+  end
+
+  # Options passed to `resource_serializer_klass` instance when serializing the JSON API document.
+  #
+  # @return [Hash] Defaults to `{}`
+  def serialization_options
+    {}
+  end
+end