nucleus-core 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b2545a3c813f8b6c7fc829e527ed77dc5105b10857af9ea2621bcb8ac81264de
+  data.tar.gz: 2b1724c47837c91d2039625f3efdea8fbc550d3513f0a9a253b0cb5104dd7c8c
+SHA512:
+  metadata.gz: 84e7a40ba56b63f86dedf43cf139386cb73e128e30986ba3fb169ac39e46dea24625658f466183302a5706edb9aca5b1414b8392663f753abf417807a2b32dae
+  data.tar.gz: 5f7237b583e69352ebd3a805cd3bd4bbbe73951a9e06b128f8bbac7950631a110fd1abcd246c284fc30c6a958574d6bb804fbf4077f31606fd0b0ecab4f63f01

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 dodgerogers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,192 @@
+# NucleusCore
+
+[![Gem Version](https://badge.fury.io/rb/nucleus-core.svg)](https://rubygems.org/gems/nucleus-core)
+[![Circle](https://circleci.com/gh/dodgerogers/nucleus-core/tree/main.svg?style=shield)](https://app.circleci.com/pipelines/github/dodgerogers/nucleus-core?branch=main)
+[![Code Climate](https://codeclimate.com/github/dodgerogers/nucleus-core/badges/gpa.svg)](https://codeclimate.com/github/dodgerogers/nucleus-core)
+
+NucleusCore Core is a framework to express and orchestrate business logic in a way that is agnostic to the framework.
+
+## This gem is still very much in development. A `nucleus-rails` gem will handle the adaptation of NucleusCore::View objects to the rails rendering methods.
+
+Here are the classes NucleusCore exposes, they have preordained responsibilities, can be composed together, and tested simply in isolation from the framework.
+
+- Policy (Authorization) - Can this user perform this process?
+- Operation (Services) - Executes a single unit of business logic, or side effect (ScheduleAppointment, CancelOrder, UpdateAddress).
+- Workflow (Service Orchestration) - Excecutes multiple units of work, and side effects (ApproveLoan, TakePayment, CancelFulfillments).
+- View (Presentation) - A presentation object which can render to multiple formats.
+- Repository (Data access) - Interacts with data sources to hide the implementation details to callers, and return Aggregates. Data sources could be an API, ActiveRecord, SQL, a local file, etc.
+- Aggregate (Domain/business Object) - Maps data from the data source to an object the aplication defines, known as an anti corruption layer.
+
+Below is an example using NucleusCore Core with Rails:
+
+```ruby
+# controllers/payments_controller.rb
+class PaymentsController < ApplicationController
+  def create
+    NucleusCore::Responder.handle_response do
+      policy.enforce!(:can_write?)
+
+      context, _process = HandleCheckoutWorkflow.call(invoice_params)
+
+      return context if !context.success?
+
+      return PaymentView.new(cart: context.cart, paid: context.paid)
+    end
+  end
+
+  private
+
+  def policy
+    Policy.new(current_user)
+  end
+
+  def invoice_params
+    params.slice(:cart_id)
+  end
+end
+
+# workflows/handle_checkout_workflow.rb
+class HandleCheckoutWorkflow < NucleusCore::Workflow
+  def define
+    start_node(continue: :calculate_amount)
+    register_node(
+      state: :calculate_amount,
+      operation: FetchShoppingCart,
+      determine_signal: ->(context) { context.cart.total > 10 ? :discount : :pay },
+      signals: { discount: :apply_discount, pay: :take_payment }
+    )
+    register_node(
+      state: :apply_discount,
+      operation: ApplyDiscountToShoppingCart,
+      signals: { continue: :take_payment }
+    )
+    register_node(
+      state: :take_payment,
+      operation: ->(context) { context.paid = context.cart.paid },
+      determine_signal: ->(_) { :completed }
+    )
+    register_node(
+      state: :completed,
+      determine_signal: ->(_) { :wait }
+    )
+  end
+end
+
+# app/operations/fetch_shopping_cart.rb
+class FetchShoppingCart < NucleusCore::Operation
+  def call
+    cart = ShoppingCartRepository.find(context.cart_id)
+
+    context.cart = cart
+  rescue NucleusCore::NotFound => e
+    context.fail!(e.message, exception: e)
+  end
+end
+
+# app/repositories/shopping_cart_repository.rb
+class ShoppingCartRepository < NucleusCore::Repository
+  def self.find(cart_id)
+    cart = ShoppingCart.find(cart_id)
+
+    return ShoppingCart::Aggregate.new(cart)
+  rescue ActiveRecord::RecordNotFound => e
+    raise NucleusCore::NotFound, e.message
+  end
+
+  def self.discount(cart_id, percentage)
+    cart = find(cart_id, percentage=0.5)
+
+    cart.update!(total: cart.total * percentage, paid: true)
+
+    return ShoppingCart::Aggregate.new(cart)
+  rescue NucleusCore::NotFound => e
+    raise e
+  end
+end
+
+class ShoppingCart < ActiveRecord::Base
+  # ...
+end
+
+# app/aggregates/shopping_cart.rb
+class ShoppingCart::Aggregate < NucleusCore::Aggregate
+  def initialize(cart)
+    super(id: cart.id, total: cart.total, paid: cart.paid, created_at: cart.created_at)
+  end
+end
+
+# app/operations/apply_discount_to_shopping_cart.rb
+class ApplyDiscountToShoppingCart < NucleusCore::Operation
+  def call
+    cart = ShoppingCartRepository.discount(context.cart_id, 0.75)
+
+    context.cart
+  rescue NucleusCore::NotFound => e
+    context.fail!(e.message, exception: e)
+  end
+end
+
+# app/views/payments_view.rb
+class NucleusCore::PaymentView < NucleusCore::View
+  def initialize(cart)
+    super(total: "$#{cart.total}", paid: cart.paid, created_at: cart.created_at)
+  end
+
+  def json_response
+    content = {
+      payment: {
+        price: price,
+        paid: paid,
+        created_at: created_at,
+        signature: SecureRandom.hex
+      }
+    }
+
+    NucleusCore::JsonResponse.new(content: content)
+  end
+
+  def pdf_response
+    pdf_string = generate_pdf_string(price, paid)
+
+    NucleusCore::PdfResponse.new(content: pdf_string)
+  end
+
+  private def generate_pdf_string(price, paid)
+    # pdf string genration...
+  end
+end
+```
+
+---
+
+- [Quick start](#quick-start)
+- [Support](#support)
+- [License](#license)
+- [Code of conduct](#code-of-conduct)
+- [Contribution guide](#contribution-guide)
+
+## Quick start
+
+```
+$ gem install nucleus-core
+```
+
+```ruby
+require "nucleus-core"
+```
+
+## Support
+
+If you want to report a bug, or have ideas, feedback or questions about the gem, [let me know via GitHub issues](https://github.com/dodgerogers/nucleus_core/issues/new) and I will do my best to provide a helpful answer. Happy hacking!
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+
+## Code of conduct
+
+Everyone interacting in this project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).
+
+## Contribution guide
+
+Pull requests are welcome!

data/exe/nucleus

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require "nucleus"
+NucleusCore::CLI.new.call(ARGV)

data/lib/nucleus_core/aggregate.rb

@@ -0,0 +1 @@
+class NucleusCore::Aggregate < NucleusCore::BasicObject; end

data/lib/nucleus_core/basic_object.rb

@@ -0,0 +1,24 @@
+module NucleusCore
+  class BasicObject
+    def initialize(attrs={})
+      attrs.each_pair do |key, value|
+        define_singleton_method(key.to_s) do
+          instance_variable_get("@#{key}")
+        end
+
+        define_singleton_method("#{key}=") do |val|
+          instance_variable_set("@#{key}", val)
+        end
+
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
+    def to_h
+      instance_variables
+        .reduce({}) do |acc, var|
+        acc.merge(var.to_s.delete("@") => instance_variable_get(var))
+      end
+    end
+  end
+end

data/lib/nucleus_core/cli.rb

@@ -0,0 +1,6 @@
+module NucleusCore
+  class CLI
+    def call(_argv)
+    end
+  end
+end

data/lib/nucleus_core/exceptions.rb

@@ -0,0 +1,5 @@
+class NucleusCore::BaseException < StandardError; end
+class NucleusCore::NotAuthorized < NucleusCore::BaseException; end
+class NucleusCore::NotFound < NucleusCore::BaseException; end
+class NucleusCore::Unprocessable < NucleusCore::BaseException; end
+class NucleusCore::BadRequest < NucleusCore::BaseException; end

data/lib/nucleus_core/extensions/array.rb

@@ -0,0 +1,11 @@
+class Array
+  def self.wrap(object)
+    if object.nil?
+      []
+    elsif object.respond_to?(:to_ary)
+      object.to_ary || [object]
+    else
+      [object]
+    end
+  end
+end

data/lib/nucleus_core/extensions/rack.rb

@@ -0,0 +1,86 @@
+# Rack::Utils patch for status code
+module NucleusCore
+  module Rack
+    class Utils
+      HTTP_STATUS_CODES = {
+        100 => "Continue",
+        101 => "Switching Protocols",
+        102 => "Processing",
+        103 => "Early Hints",
+        200 => "OK",
+        201 => "Created",
+        202 => "Accepted",
+        203 => "Non-Authoritative Information",
+        204 => "No Content",
+        205 => "Reset Content",
+        206 => "Partial Content",
+        207 => "Multi-Status",
+        208 => "Already Reported",
+        226 => "IM Used",
+        300 => "Multiple Choices",
+        301 => "Moved Permanently",
+        302 => "Found",
+        303 => "See Other",
+        304 => "Not Modified",
+        305 => "Use Proxy",
+        306 => "(Unused)",
+        307 => "Temporary Redirect",
+        308 => "Permanent Redirect",
+        400 => "Bad Request",
+        401 => "Unauthorized",
+        402 => "Payment Required",
+        403 => "Forbidden",
+        404 => "Not Found",
+        405 => "Method Not Allowed",
+        406 => "Not Acceptable",
+        407 => "Proxy Authentication Required",
+        408 => "Request Timeout",
+        409 => "Conflict",
+        410 => "Gone",
+        411 => "Length Required",
+        412 => "Precondition Failed",
+        413 => "Payload Too Large",
+        414 => "URI Too Long",
+        415 => "Unsupported Media Type",
+        416 => "Range Not Satisfiable",
+        417 => "Expectation Failed",
+        421 => "Misdirected Request",
+        422 => "Unprocessable Entity",
+        423 => "Locked",
+        424 => "Failed Dependency",
+        425 => "Too Early",
+        426 => "Upgrade Required",
+        428 => "Precondition Required",
+        429 => "Too Many Requests",
+        431 => "Request Header Fields Too Large",
+        451 => "Unavailable for Legal Reasons",
+        500 => "Internal Server Error",
+        501 => "Not Implemented",
+        502 => "Bad Gateway",
+        503 => "Service Unavailable",
+        504 => "Gateway Timeout",
+        505 => "HTTP Version Not Supported",
+        506 => "Variant Also Negotiates",
+        507 => "Insufficient Storage",
+        508 => "Loop Detected",
+        509 => "Bandwidth Limit Exceeded",
+        510 => "Not Extended",
+        511 => "Network Authentication Required"
+      }.freeze
+
+      SYMBOL_TO_STATUS_CODE = Hash[*HTTP_STATUS_CODES.map do |code, message|
+        [message.downcase.gsub(/\s|-|'/, "_").to_sym, code]
+      end.flatten]
+
+      def self.status_code(status)
+        if status.is_a?(Symbol)
+          return SYMBOL_TO_STATUS_CODE.fetch(status) do
+            raise ArgumentError, "Unrecognized status code #{status.inspect}"
+          end
+        end
+
+        status.to_i
+      end
+    end
+  end
+end

data/lib/nucleus_core/operation.rb

@@ -0,0 +1,68 @@
+require "ostruct"
+
+module NucleusCore
+  class Operation
+    class Context < OpenStruct
+      class Error < StandardError
+        attr_reader :exception
+
+        def initialize(message, opts={})
+          @exception = opts[:exception]
+
+          super(message)
+        end
+      end
+
+      attr_reader :failure
+
+      def initialize(attrs={})
+        @failure = false
+
+        super(attrs)
+      end
+
+      def success?
+        !@failure
+      end
+
+      def fail!(message, attrs={})
+        @failure = true
+
+        self.message = message
+        self.exception = attrs.delete(:exception)
+
+        raise Context::Error, message
+      end
+    end
+
+    attr_reader :context
+
+    def initialize(args={})
+      @context = args.is_a?(Context) ? args : Context.new(args)
+    end
+
+    def self.call(args={})
+      operation = new(args)
+
+      operation.call
+
+      operation.context
+    rescue Context::Error
+      operation.context
+    end
+
+    def self.rollback(context)
+      operation = new(context)
+
+      operation.rollback
+
+      operation.context
+    end
+
+    def call
+    end
+
+    def rollback
+    end
+  end
+end

data/lib/nucleus_core/policy.rb

@@ -0,0 +1,23 @@
+require "nucleus_core/exceptions"
+
+module NucleusCore
+  class Policy
+    attr_reader :user, :record
+
+    def initialize(user, record=nil)
+      @user = user
+      @record = record
+    end
+
+    def enforce!(*policy_methods)
+      policy_methods.each do |policy_method_and_args|
+        next if send(*policy_method_and_args)
+
+        name = Array.wrap(policy_method_and_args).first
+        message = "You do not have access to: #{name}"
+
+        raise NucleusCore::NotAuthorized, message
+      end
+    end
+  end
+end

data/lib/nucleus_core/repository.rb

@@ -0,0 +1,6 @@
+module NucleusCore
+  class Repository
+    def self.execute
+    end
+  end
+end

data/lib/nucleus_core/responder.rb

@@ -0,0 +1,130 @@
+require "set"
+
+module NucleusCore
+  module Responder
+    def set_request_format(request=nil)
+      @request_format = request&.format&.to_sym || :json
+    end
+
+    def request_format
+      @request_format ||= set_request_format
+    end
+
+    # rubocop:disable Lint/RescueException:
+    def handle_response(&block)
+      entity = proc_to_lambda(&block)
+
+      render_entity(entity)
+    rescue Exception => e
+      handle_exception(e)
+    end
+    # rubocop:enable Lint/RescueException:
+
+    def handle_exception(exception)
+      logger(exception)
+
+      status = exception_to_status(exception)
+      attrs = { message: exception.message, status: status }
+      error = NucleusCore::ErrorView.new(attrs)
+
+      render_entity(error)
+    end
+
+    # Calling `return` in a block/proc returns from the outer calling scope as well.
+    # Lambdas do not have this limitation. So we convert the proc returned
+    # from a block method into a lambda to avoid 'return' exiting the method early.
+    # https://stackoverflow.com/questions/2946603/ruby-convert-proc-to-lambda
+    def proc_to_lambda(&block)
+      define_singleton_method(:_proc_to_lambda_, &block)
+
+      method(:_proc_to_lambda_).to_proc.call
+    end
+
+    def render_entity(entity)
+      return handle_context(entity) if entity.is_a?(NucleusCore::Operation::Context)
+      return render_response(entity) if subclass_of(entity, NucleusCore::ResponseAdapter)
+      return render_view(entity) if subclass_of(entity, NucleusCore::View)
+    end
+
+    def handle_context(context)
+      return render_nothing(context) if context.success?
+      return handle_exception(context.exception) if context.exception
+
+      message = context.message
+      attrs = { message: message, status: :unprocessable_entity }
+      error_view = NucleusCore::ErrorView.new(attrs)
+
+      render_view(error_view)
+    end
+
+    def render_view(view)
+      format_rendering = "#{request_format}_response".to_sym
+      renders_format = view.respond_to?(format_rendering)
+      format_response = view.send(format_rendering) if renders_format
+
+      raise NucleusCore::BadRequest, "#{request_format} is not supported" if format_response.nil?
+
+      render_response(format_response)
+    end
+
+    def render_response(entity)
+      render_headers(entity.headers)
+
+      render_method = {
+        NucleusCore::JsonResponse => :render_json,
+        NucleusCore::XmlResponse => :render_xml,
+        NucleusCore::PdfResponse => :render_pdf,
+        NucleusCore::CsvResponse => :render_csv,
+        NucleusCore::TextResponse => :render_text,
+        NucleusCore::NoResponse => :render_nothing
+      }.fetch(entity.class, nil)
+
+      response_adapter&.send(render_method, entity)
+    end
+
+    def render_headers(headers={})
+      (headers || {}).each do |k, v|
+        formatted_key = k.titleize.gsub(/\s *|_/, "-")
+
+        response_adapter&.set_header(formatted_key, v)
+      end
+    end
+
+    # rubocop:disable Lint/DuplicateBranch
+    def exception_to_status(exception)
+      config = exception_map
+
+      case exception
+      when NucleusCore::NotFound, *config.not_found
+        :not_found
+      when NucleusCore::BadRequest, *config.bad_request
+        :bad_request
+      when NucleusCore::NotAuthorized, *config.forbidden
+        :forbidden
+      when NucleusCore::Unprocessable, *config.unprocessable
+        :unprocessable_entity
+      when NucleusCore::BaseException, *config.server_error
+        :internal_server_error
+      else
+        :internal_server_error
+      end
+    end
+    # rubocop:enable Lint/DuplicateBranch
+
+    def subclass_of(entity, *classes)
+      Set[*entity.class.ancestors].intersect?(classes.to_set)
+    end
+
+    def logger(object, log_level=:info)
+      NucleusCore.configuration.logger&.send(log_level, object)
+    end
+
+    def exception_map
+      NucleusCore.configuration.exceptions_map
+    end
+
+    def response_adapter
+      NucleusCore.configuration.response_adapter
+    end
+  end
+end

data/lib/nucleus_core/response_adapter.rb

@@ -0,0 +1,81 @@
+class NucleusCore::ResponseAdapter < NucleusCore::BasicObject
+  def initialize(attrs={})
+    attributes = defaults
+      .merge(attrs)
+      .slice(*defaults.keys)
+      .tap do |hash|
+        hash[:status] = status_code(hash[:status])
+      end
+
+    super(attributes)
+  end
+
+  private
+
+  def defaults
+    { content: "", headers: {}, status: 200, location: nil }
+  end
+
+  def status_code(status=nil)
+    status = NucleusCore::Rack::Utils.status_code(status)
+    default_status = 200
+
+    status.zero? ? default_status : status
+  end
+end
+
+class NucleusCore::NoResponse < NucleusCore::ResponseAdapter
+  def initialize(attrs={})
+    attrs = attrs.merge(content: nil, type: "text/html; charset=utf-8")
+
+    super(attrs)
+  end
+end
+
+class NucleusCore::TextResponse < NucleusCore::ResponseAdapter
+  def initialize(attrs={})
+    attrs = attrs.merge(type: "application/text")
+
+    super(attrs)
+  end
+end
+
+class NucleusCore::JsonResponse < NucleusCore::ResponseAdapter
+  def initialize(attrs={})
+    attrs = attrs.merge(type: "application/json")
+
+    super(attrs)
+  end
+end
+
+class NucleusCore::XmlResponse < NucleusCore::ResponseAdapter
+  def initialize(attrs={})
+    attrs = attrs.merge(type: "application/xml")
+
+    super(attrs)
+  end
+end
+
+class NucleusCore::CsvResponse < NucleusCore::ResponseAdapter
+  def initialize(attrs={})
+    attrs = attrs.merge(
+      disposition: "attachment",
+      filename: attrs.fetch(:filename) { "response.csv" },
+      type: "text/csv; charset=UTF-8;"
+    )
+
+    super(attrs)
+  end
+end
+
+class NucleusCore::PdfResponse < NucleusCore::ResponseAdapter
+  def initialize(attrs={})
+    attrs = attrs.merge(
+      disposition: "inline",
+      filename: attrs.fetch(:filename) { "response.pdf" },
+      type: "application/pdf"
+    )
+
+    super(attrs)
+  end
+end

data/lib/nucleus_core/version.rb

@@ -0,0 +1,3 @@
+module NucleusCore
+  VERSION = "0.1.0".freeze
+end

data/lib/nucleus_core/views/error_view.rb

@@ -0,0 +1,17 @@
+require "nucleus_core/response_adapter"
+
+class NucleusCore::ErrorView < NucleusCore::View
+  def initialize(attrs={})
+    super(
+      {}.tap do |a|
+        a[:status] = attrs.fetch(:status, :unprocessable_entity)
+        a[:message] = attrs.fetch(:message, nil)
+        a[:errors] = attrs.fetch(:errors, [])
+      end
+    )
+  end
+
+  def json_response
+    NucleusCore::JsonResponse.new(content: to_h, status: status)
+  end
+end

data/lib/nucleus_core/views/view.rb

@@ -0,0 +1,5 @@
+class NucleusCore::View < NucleusCore::BasicObject
+  def json_response
+    NucleusCore::JsonResponse.new(content: to_h, status: :ok)
+  end
+end

data/lib/nucleus_core/workflow.rb

@@ -0,0 +1,180 @@
+# rubocop:disable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/ClassLength, Metrics/AbcSize:
+module NucleusCore
+  class Workflow
+    class Node
+      attr_reader :state, :operation, :rollback, :signals, :prepare_context, :determine_signal
+
+      def initialize(attrs={})
+        @state = attrs[:state]
+        @operation = attrs[:operation]
+        @rollback = attrs[:rollback]
+        @signals = attrs[:signals]
+        @prepare_context = attrs[:prepare_context]
+        @determine_signal = attrs[:determine_signal]
+      end
+    end
+
+    class Process
+      attr_accessor :state, :visited
+
+      def initialize(state)
+        @state = state
+        @visited = []
+      end
+
+      def visit(state)
+        @state = state
+        @visited.push(state)
+      end
+    end
+
+    # States
+    ###########################################################################
+    INITIAL_STATE = :initial
+
+    # Signals
+    ###########################################################################
+    CONTINUE = :continue
+    WAIT = :wait
+
+    # Node statuses
+    ###########################################################################
+    OK = :ok
+    FAILED = :failed
+
+    attr_accessor :process, :nodes, :context
+
+    def initialize(process: nil, context: {})
+      @nodes = {}
+      @process = process || Process.new(INITIAL_STATE)
+      @context = build_context(context)
+
+      init_nodes
+    end
+
+    def register_node(attrs={})
+      node = Node.new(attrs)
+
+      @nodes[node.state] = node
+    end
+
+    def start_node(signals={})
+      raise ArgumentError, "#{self.class}##{__method__}: missing signals" if signals.empty?
+
+      register_node(state: INITIAL_STATE, signals: signals)
+    end
+
+    def init_nodes
+      define
+    end
+
+    # Override this method to draw the workflow graph
+    def define
+    end
+
+    def self.call(signal: nil, process: nil, context: {})
+      workflow = new(process: process, context: context)
+
+      workflow.validate_nodes!
+      workflow.execute(signal)
+
+      [workflow.context, workflow.process]
+    end
+
+    def self.rollback(process:, context:)
+      workflow = new(process: process, context: context)
+      visited = workflow.process.visited.clone
+
+      visited.reverse_each do |state|
+        node = workflow.nodes[state]
+
+        next node.operation.rollback(context) if node.operation.is_a?(NucleusCore::Operation)
+        next node.rollback.call(context) if node.rollback.is_a?(Proc)
+      end
+    end
+
+    def validate_nodes!
+      start_nodes = nodes.values.count do |node|
+        node.state == INITIAL_STATE
+      end
+
+      raise ArgumentError, "#{self.class}: missing `:initial` start node" if start_nodes.zero?
+      raise ArgumentError, "#{self.class}: more than one start node detected" if start_nodes > 1
+    end
+
+    def execute(signal=nil)
+      signal ||= CONTINUE
+      current_state = process.state
+      next_signal = (fetch_node(current_state)&.signals || {})[signal]
+      current_node = fetch_node(next_signal)
+
+      context.fail!("invalid signal: #{signal}") if current_node.nil?
+
+      while next_signal
+        status, next_signal, @context = execute_node(current_node, context)
+
+        break if status == FAILED
+
+        process.visit(current_node.state)
+        current_node = fetch_node(next_signal)
+
+        break if next_signal == WAIT
+      end
+
+      context
+    rescue NucleusCore::Operation::Context::Error
+      context
+    rescue StandardError => e
+      fail_context(@context, e)
+    end
+
+    private
+
+    def build_context(context={})
+      return context if context.is_a?(NucleusCore::Operation::Context)
+
+      NucleusCore::Operation::Context.new(context)
+    end
+
+    def execute_node(node, context)
+      context = prepare_context(node, context)
+      operation = node.operation
+
+      operation&.call(context)
+
+      status = context.success? ? OK : FAILED
+      next_signal = determine_signal(node, context)
+
+      [status, next_signal, context]
+    end
+
+    def prepare_context(node, context)
+      return node.prepare_context.call(context) if node.prepare_context.is_a?(Proc)
+      return send(node.prepare_context, context) if node.prepare_context.is_a?(Symbol)
+
+      context
+    end
+
+    def determine_signal(node, context)
+      signal = CONTINUE
+      signal = node.determine_signal.call(context) if node.determine_signal.is_a?(Proc)
+      signal = send(node.determine_signal, context) if node.determine_signal.is_a?(Symbol)
+      node_signals = node.signals || {}
+
+      node_signals[signal]
+    end
+
+    def fetch_node(state)
+      nodes[state]
+    end
+
+    def fail_context(context, exception)
+      message = "Unhandled exception #{self.class}: #{exception.message}"
+
+      context.fail!(message, exception: exception)
+    rescue NucleusCore::Operation::Context::Error
+      context
+    end
+  end
+end
+# rubocop:enable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/ClassLength, Metrics/AbcSize:

data/lib/nucleus_core.rb

@@ -0,0 +1,94 @@
+require "ostruct"
+require "nucleus_core/exceptions"
+require "json"
+require "set"
+
+Dir[File.join(__dir__, "nucleus_core", "extensions", "*.rb")].sort.each { |file| require file }
+
+module NucleusCore
+  autoload :CLI, "nucleus_core/cli"
+  autoload :VERSION, "nucleus_core/version"
+  autoload :BasicObject, "nucleus_core/basic_object"
+  autoload :View, "nucleus_core/views/view"
+  autoload :ErrorView, "nucleus_core/views/error_view"
+  autoload :ResponseAdapter, "nucleus_core/response_adapter"
+  autoload :Aggregate, "nucleus_core/aggregate"
+  autoload :Policy, "nucleus_core/policy"
+  autoload :Operation, "nucleus_core/operation"
+  autoload :Workflow, "nucleus_core/workflow"
+  autoload :Responder, "nucleus_core/responder"
+
+  class Configuration
+    attr_reader :exceptions_map, :response_adapter
+    attr_accessor :logger
+
+    def initialize
+      @logger = nil
+      @response_adapter = nil
+      @exceptions_map = nil
+    end
+
+    def exceptions_map=(args={})
+      @exceptions_map = format_exceptions(args)
+    end
+
+    def response_adapter=(adapter)
+      @response_adapter = format_adapter(adapter)
+    end
+
+    private
+
+    def objectify(hash)
+      OpenStruct.new(hash)
+    end
+
+    ERROR_STATUSES = %i[not_found bad_request unauthorized unprocessable server_error].freeze
+
+    def format_exceptions(exceptions={})
+      exception_defaults = ERROR_STATUSES.reduce({}) { |acc, ex| acc.merge(ex => nil) }
+
+      objectify(
+        (exceptions || exception_defaults)
+            .slice(*exception_defaults.keys)
+            .reduce({}) do |acc, (key, value)|
+              acc.merge(key => Array.wrap(value))
+            end
+      )
+    end
+
+    def format_adapter(adapter={})
+      adapter.tap do |a|
+        verify_adapter!(a)
+      end
+    end
+
+    ADAPTER_METHODS = %i[
+      render_json render_xml render_text render_pdf render_csv render_nothing set_header
+    ].freeze
+
+    def verify_adapter!(adapter)
+      current_adapter_methods = Set[*(adapter.methods - Object.methods)]
+      required_adapter_methods = ADAPTER_METHODS.to_set
+
+      return if current_adapter_methods == required_adapter_methods
+
+      missing = current_adapter_methods.subtract(required_adapter_methods)
+
+      raise ArgumentError, "responder.adapter must implement: #{missing}"
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset
+      @configuration = Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end

metadata

@@ -0,0 +1,194 @@
+--- !ruby/object:Gem::Specification
+name: nucleus-core
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- dodgerogers
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-02-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.11'
+- !ruby/object:Gem::Dependency
+  name: minitest-ci
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.43.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.43.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.26.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.26.1
+- !ruby/object:Gem::Dependency
+  name: rubocop-packaging
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.5.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.5.2
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.15.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.15.2
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+description:
+email:
+- dodgerogers@hotmail.com
+executables:
+- nucleus
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/nucleus
+- lib/nucleus_core.rb
+- lib/nucleus_core/aggregate.rb
+- lib/nucleus_core/basic_object.rb
+- lib/nucleus_core/cli.rb
+- lib/nucleus_core/exceptions.rb
+- lib/nucleus_core/extensions/array.rb
+- lib/nucleus_core/extensions/rack.rb
+- lib/nucleus_core/operation.rb
+- lib/nucleus_core/policy.rb
+- lib/nucleus_core/repository.rb
+- lib/nucleus_core/responder.rb
+- lib/nucleus_core/response_adapter.rb
+- lib/nucleus_core/version.rb
+- lib/nucleus_core/views/error_view.rb
+- lib/nucleus_core/views/view.rb
+- lib/nucleus_core/workflow.rb
+homepage: https://github.com/dodgerogers/nucleus-core
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/dodgerogers/nucleus-core/issues
+  changelog_uri: https://github.com/dodgerogers/nucleus-core/releases
+  source_code_uri: https://github.com/dodgerogers/nucleus-core
+  homepage_uri: https://github.com/dodgerogers/nucleus-core
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.5
+signing_key:
+specification_version: 4
+summary: A Ruby business logic framework
+test_files: []