arq 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a4e1c4a65e159a4c635f1a1bee0bc1b0797dbe99a01d16b9a515bc6f1a2060bd
+  data.tar.gz: 4dca5b5179826aa0161b8ae619407533ded39112db29bec87c8c7c744ca41e99
+SHA512:
+  metadata.gz: 253883d41ea384035d6e9ebadc41e9c9a94f752b16eb28d0aad0f368406a7ca413ae14bb6f5c4f973f6806ca58531c70de82e20c9208a5ae951e2c7142efcef8
+  data.tar.gz: 741d201875b5fdeded240b28961a8b4367c224048f0e3cfcf1d90085d0269d847ccaef0e4aecde774cc4c648054a82f8b28be1b088c440b14869ce8f14e9d8c1

data/lib/arq/action.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Arq
+  # Module to extend to create an action. Exposes confing functions #call, #params, and #returns.
+  module Action
+    def call(ctx)
+      ctx = transform_input_context(ctx)
+
+      generate_runnable(ctx).call
+
+      ctx
+    end
+
+    def params(*keys)
+      params_list.concat(keys).compact
+    end
+
+    def returns(*keys)
+      returns_list.concat(keys).compact
+    end
+
+    def run(&block)
+      @run_block = block
+    end
+
+    private
+
+    def transform_input_context(ctx)
+      case ctx
+      when Arq::Context
+        ctx
+      when Hash
+        Arq::Context.new(ctx)
+      else
+        raise Arq::InvalidContextParameterError
+      end
+    end
+
+    def generate_runnable(ctx)
+      Arq::Runnable.new(ctx, params_list, returns_list, &run_block)
+    end
+
+    def params_list
+      @params_list ||= []
+    end
+
+    def returns_list
+      @returns_list ||= []
+    end
+
+    def run_block
+      @run_block ||= nil
+    end
+  end
+end

data/lib/arq/context.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Arq
+  # Light wrapper around Hash with additional properties for action results.
+  class Context < Hash
+    def initialize(params = {})
+      super(nil)
+      merge!(params)
+    end
+
+    def fail!(message = nil)
+      @failure = true
+      @message = message
+    end
+
+    def fail_now!(message = nil)
+      fail!(message)
+      raise Arq::FailureError
+    end
+
+    def failure?
+      @failure ||= false
+    end
+
+    def success?
+      !failure?
+    end
+
+    def message
+      @message ||= ""
+    end
+  end
+end

data/lib/arq/errors.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Arq
+  # Raised when the context for an action is not a Arq::Context or a Hash.
+  class InvalidContextParameterError < StandardError
+    def initialize
+      super("Must be a Arq::Context or Hash")
+    end
+  end
+
+  # Raised when action parameters do not exist within the passed context.
+  class ParametersNotInContextError < StandardError
+    def initialize(params)
+      super(params.join(", "))
+    end
+  end
+
+  # Raised when action return keys do not exist within the passed context.
+  class ReturnValuesNotInContextError < StandardError
+    def initialize(returns)
+      super(returns.join(", "))
+    end
+  end
+
+  # Raised internally in [Arq::Runnable#hard_fail!] to escape the current action.
+  class FailureError < StandardError
+  end
+end

data/lib/arq/runnable.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Arq
+  # Represents a process to run with a given context, parameters, and returns.
+  # A Runnable is generated from an Action.
+  class Runnable
+    def initialize(ctx, params = [], returns = [], &block)
+      @ctx     = ctx
+      @params  = params
+      @returns = returns
+      @block   = block
+    end
+
+    def call
+      return if @ctx.failure?
+
+      validate_required_params
+
+      import_context
+      val = run_block
+      export_context
+
+      # If the block returned an array, attempt to run
+      run_sequence(val) if val.is_a?(Array)
+
+      # Only validate returns if context is successful
+      validate_required_returns if @ctx.success?
+
+      val
+    end
+
+    def run(&block)
+      Arq::Runnable.new(@ctx, [], [], &block)
+    end
+
+    def fail!(message)
+      @ctx.fail!(message)
+    end
+
+    def fail_now!(message)
+      @ctx.fail_now!(message)
+    end
+
+    private
+
+    def run_block
+      instance_eval(&@block)
+    rescue Arq::FailureError
+      nil
+    end
+
+    def run_sequence(sequence)
+      sequence.each do |e|
+        case e
+        when Arq::Action
+          e.call(@ctx)
+        when Arq::Runnable
+          e.call
+        end
+      end
+    end
+
+    def import_context
+      @ctx.each do |key, val|
+        instance_variable_set(:"@#{key}", val)
+      end
+    end
+
+    def export_context
+      keys = [*@ctx.keys, *@returns]
+
+      keys.each do |key|
+        instance_key = :"@#{key}"
+        # Must check for existence since getting non-existent
+        # instance variables will return nil.
+        @ctx[key] = instance_variable_get(instance_key) if instance_variables.include?(instance_key)
+      end
+    end
+
+    def validate_required_params
+      missing_params = (@params - @ctx.keys)
+      raise Arq::ParametersNotInContextError, missing_params unless missing_params.empty?
+    end
+
+    def validate_required_returns
+      missing_returns = (@returns - @ctx.keys)
+      raise Arq::ReturnValuesNotInContextError, missing_returns unless missing_returns.empty?
+    end
+  end
+end

data/lib/arq/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Arq
+  VERSION = "0.1.0"
+end

data/lib/arq.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "arq/version"
+require "arq/errors"
+require "arq/context"
+require "arq/runnable"
+require "arq/action"

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: arq
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kavin Phan
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-09-05 00:00:00.000000000 Z
+dependencies: []
+description: A service skeleton framework heavily inspired by LightService with the
+  primary goal of being less verbose.
+email:
+- kavin@kphan.tech
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/arq.rb
+- lib/arq/action.rb
+- lib/arq/context.rb
+- lib/arq/errors.rb
+- lib/arq/runnable.rb
+- lib/arq/version.rb
+homepage: https://github.com/kphan32/arq
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kphan32/arq
+  source_code_uri: https://github.com/kphan32/arq
+  changelog_uri: https://github.com/kphan32/arq/blob/main/CODE_OF_CONDUCT.md
+  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: 3.0.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.32
+signing_key:
+specification_version: 4
+summary: A simple service skeleton framework
+test_files: []