zenaton 0.1.0

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install

data/lib/zenaton.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'zenaton/version'
+require 'zenaton/exceptions'
+require 'zenaton/client'
+require 'zenaton/interfaces/event'
+require 'zenaton/tasks/wait'
+require 'zenaton/parallel'
+
+# Top level namespace for the Zenaton ruby library
+module Zenaton
+end

data/lib/zenaton/client.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require 'singleton'
+require 'zenaton/services/http'
+require 'zenaton/services/properties'
+require 'zenaton/services/serializer'
+require 'zenaton/workflows/version'
+
+module Zenaton
+  # Zenaton Client
+  class Client
+    include Singleton
+
+    ZENATON_API_URL = 'https://zenaton.com/api/v1' # Zenaton api url
+    ZENATON_WORKER_URL = 'http://localhost' # Default worker url
+    DEFAULT_WORKER_PORT = 4001 # Default worker port
+    WORKER_API_VERSION = 'v_newton' # Default worker api version
+
+    MAX_ID_SIZE = 256 # Limit on length of custom ids
+
+    APP_ENV = 'app_env' # Parameter name for the application environment
+    APP_ID = 'app_id' # Parameter name for the application ID
+    API_TOKEN = 'api_token' # Parameter name for the API token
+
+    ATTR_ID = 'custom_id' # Parameter name for custom ids
+    ATTR_NAME = 'name' # Parameter name for workflow names
+    ATTR_CANONICAL = 'canonical_name' # Parameter name for version name
+    ATTR_DATA = 'data' # Parameter name for json payload
+    ATTR_PROG = 'programming_language' # Parameter name for the language
+    ATTR_MODE = 'mode' # Parameter name for the worker update mode
+
+    PROG = 'Ruby' # The current programming language
+
+    EVENT_INPUT = 'event_input' # Parameter name for event data
+    EVENT_NAME = 'event_name' # Parameter name for event name
+
+    WORKFLOW_KILL = 'kill' # Worker update mode to stop a worker
+    WORKFLOW_PAUSE = 'pause' # Worker udpate mode to pause a worker
+    WORKFLOW_RUN = 'run' # Worker update mode to resume a worker
+
+    attr_writer :app_id, :api_token, :app_env
+
+    # Class method that sets the three tokens needed to interact with the API
+    # @param app_id [String] the ID of your Zenaton application
+    # @param api_token [String] your Zenaton account API token
+    # @param app_env [String] the environment (dev, staging, prod) to run under
+    # @return [Zenaton::Client] the instance of the client.
+    def self.init(app_id, api_token, app_env)
+      instance.tap do |client|
+        client.app_id = app_id
+        client.api_token = api_token
+        client.app_env = app_env
+      end
+    end
+
+    # @private
+    def initialize
+      @http = Services::Http.new
+      @serializer = Services::Serializer.new
+      @properties = Services::Properties.new
+    end
+
+    # Gets the url for the workers
+    # @param resource [String] the endpoint for the worker
+    # @param params [String] url encoded parameters to include in request
+    # @return [String] the workers url with parameters
+    def worker_url(resource = '', params = '')
+      base_url = ENV['ZENATON_WORKER_URL'] || ZENATON_WORKER_URL
+      port = ENV['ZENATON_WORKER_PORT'] || DEFAULT_WORKER_PORT
+      url = "#{base_url}:#{port}/api/#{WORKER_API_VERSION}/#{resource}?"
+      add_app_env(url, params)
+    end
+
+    # Gets the url for zenaton api
+    # @param resource [String] the endpoint for the api
+    # @param params [String] url encoded parameters to include in request
+    # @return [String] the api url with parameters
+    def website_url(resource = '', params = '')
+      api_url = ENV['ZENATON_API_URL'] || ZENATON_API_URL
+      url = "#{api_url}/#{resource}?#{API_TOKEN}=#{@api_token}&"
+      add_app_env(url, params)
+    end
+
+    # Start the specified workflow
+    # @param flow [Zenaton::Interfaces::Workflow]
+    def start_workflow(flow)
+      @http.post(
+        instance_worker_url,
+        ATTR_PROG => PROG,
+        ATTR_CANONICAL => canonical_name(flow),
+        ATTR_NAME => class_name(flow),
+        ATTR_DATA => @serializer.encode(@properties.from(flow)),
+        ATTR_ID => parse_custom_id_from(flow)
+      )
+    end
+
+    # Stops a workflow
+    # @param workflow_name [String] the class name of the workflow
+    # @param custom_id [String] the custom ID of the workflow (if any)
+    # @return [NilClass]
+    def kill_workflow(workflow_name, custom_id)
+      update_instance(workflow_name, custom_id, WORKFLOW_KILL)
+    end
+
+    # Pauses a workflow
+    # @param workflow_name [String] the class name of the workflow
+    # @param custom_id [String] the custom ID of the workflow (if any)
+    # @return [NilClass]
+    def pause_workflow(workflow_name, custom_id)
+      update_instance(workflow_name, custom_id, WORKFLOW_PAUSE)
+    end
+
+    # Resumes a workflow
+    # @param workflow_name [String] the class name of the workflow
+    # @param custom_id [String] the custom ID of the workflow (if any)
+    # @return [NilClass]
+    def resume_workflow(workflow_name, custom_id)
+      update_instance(workflow_name, custom_id, WORKFLOW_RUN)
+    end
+
+    # Finds a workflow
+    # @param workflow_name [String] the class name of the workflow
+    # @param custom_id [String] the custom ID of the workflow (if any)
+    # @return [Zenaton::Interfaces::Workflow]
+    def find_workflow(workflow_name, custom_id)
+      # rubocop:disable Metrics/LineLength
+      params = "#{ATTR_ID}=#{custom_id}&#{ATTR_NAME}=#{workflow_name}&#{ATTR_PROG}=#{PROG}"
+      # rubocop:enable Metrics/LineLength
+      data = @http.get(instance_website_url(params))['data']
+      data && @properties.object_from(
+        data['name'],
+        @serializer.decode(data['properties'])
+      )
+    end
+
+    # Sends an event to a workflow
+    # @param workflow_name [String] the class name of the workflow
+    # @param custom_id [String] the custom ID of the workflow (if any)
+    # @param event [Zenaton::Interfaces::Event] the event to send
+    # @return [NilClass]
+    def send_event(workflow_name, custom_id, event)
+      body = {
+        ATTR_PROG => PROG,
+        ATTR_NAME => workflow_name,
+        ATTR_ID => custom_id,
+        EVENT_NAME => event.class.name,
+        EVENT_INPUT => @serializer.encode(@properties.from(event))
+      }
+      @http.post(send_event_url, body)
+    end
+
+    private
+
+    def add_app_env(url, params)
+      app_env = @app_env ? "#{APP_ENV}=#{@app_env}&" : ''
+      app_id = @app_id ? "#{APP_ID}=#{@app_id}&" : ''
+
+      "#{url}#{app_env}#{app_id}#{params}"
+    end
+
+    def instance_website_url(params)
+      website_url('instances', params)
+    end
+
+    def instance_worker_url(params = '')
+      worker_url('instances', params)
+    end
+
+    def send_event_url
+      worker_url('events')
+    end
+
+    # rubocop:disable Metrics/MethodLength
+    def parse_custom_id_from(flow)
+      custom_id = flow.id
+      if custom_id
+        unless custom_id.is_a?(String) || custom_id.is_a?(Integer)
+          raise InvalidArgumentError,
+                'Provided ID must be a string or an integer'
+        end
+        custom_id = custom_id.to_s
+        if custom_id.length > MAX_ID_SIZE
+          raise InvalidArgumentError,
+                "Provided Id must not exceed #{MAX_ID_SIZE} bytes"
+        end
+      end
+      custom_id
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    def canonical_name(flow)
+      flow.class.name if flow.is_a? Workflows::Version
+    end
+
+    def class_name(flow)
+      return flow.class.name unless flow.is_a? Workflows::Version
+      flow.current_implementation.class.name
+    end
+
+    def update_instance(workflow_name, custom_id, mode)
+      params = "#{ATTR_ID}=#{custom_id}"
+      url = instance_worker_url(params)
+      options = {
+        ATTR_PROG => PROG,
+        ATTR_NAME => workflow_name,
+        ATTR_MODE => mode
+      }
+      @http.put(url, options)
+    end
+  end
+end

data/lib/zenaton/engine.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'singleton'
+require 'zenaton/exceptions'
+require 'zenaton/interfaces/task'
+require 'zenaton/interfaces/workflow'
+require 'zenaton/client'
+require 'zenaton/processor'
+
+module Zenaton
+  # Zenaton Engine is a singleton class that stores a reference to the current
+  # client and processor. It then handles job processing either locally or
+  # through the processor with Zenaton workers
+  # To access the instance, call `Zenaton::Engine.instance`
+  class Engine
+    include Singleton
+
+    # @param value [Zenaton::Processor]
+    attr_writer :processor
+
+    # @private
+    def initialize
+      @client = Zenaton::Client.instance
+      @processor = nil
+    end
+
+    # Executes jobs synchronously
+    # @param jobs [Array<Zenaton::Interfaces::Job>]
+    # @return [Array<String>, nil] the results if executed locally, or nil
+    def execute(jobs)
+      jobs.map(&method(:check_argument))
+      return jobs.map(&:handle) if process_locally?(jobs)
+      @processor.process(jobs, true)
+    end
+
+    # Executes jobs asynchronously
+    # @param jobs [Array<Zenaton::Interfaces::Job>]
+    # @return nil
+    def dispatch(jobs)
+      jobs.map(&method(:check_argument))
+      jobs.map(&method(:local_dispatch)) if process_locally?(jobs)
+      @processor&.process(jobs, false) unless jobs.length.zero?
+      nil
+    end
+
+    private
+
+    def process_locally?(jobs)
+      jobs.length.zero? || @processor.nil?
+    end
+
+    def local_dispatch(job)
+      if job.is_a? Interfaces::Workflow
+        @client.start_workflow(job)
+      else
+        job.handle
+      end
+    end
+
+    def check_argument(job)
+      raise InvalidArgumentError, error_message unless valid_job?(job)
+    end
+
+    def error_message
+      'You can only execute or dispatch Zenaton Task or Worflow'
+    end
+
+    def valid_job?(job)
+      job.is_a?(Interfaces::Task) || job.is_a?(Interfaces::Workflow)
+    end
+  end
+end

data/lib/zenaton/exceptions.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Zenaton
+  # Zenaton base error class
+  class Error < StandardError; end
+
+  # Exception raised when communication with workers failed
+  class InternalError < Error; end
+
+  # Exception raise when clien code is invalid
+  class ExternalError < Error; end
+
+  # Exception raised when wrong argument type is provided
+  class InvalidArgumentError < ExternalError; end
+
+  # :nodoc:
+  class UnknownWorkflowError < ExternalError; end
+
+  # Exception raised when network connectivity is lost
+  class ConnectionError < Error; end
+
+  # Exception raised when interfaces are not fulfilled by client code
+  class NotImplemented < Error; end
+end

data/lib/zenaton/interfaces/event.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Zenaton
+  module Interfaces
+    # @abstract Subclass this to define your custom events
+    class Event
+    end
+  end
+end

data/lib/zenaton/interfaces/job.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'zenaton/exceptions'
+
+module Zenaton
+  # Abstract classes used as interfaces
+  module Interfaces
+    # @abstract Do not subclass job directly, use either Tasks or Workflows
+    class Job
+      # Child classes should implement the handle method
+      def handle
+        raise NotImplemented, "Your job does not implement the `handle' method"
+      end
+    end
+  end
+end

data/lib/zenaton/interfaces/task.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'zenaton/interfaces/job'
+
+module Zenaton
+  module Interfaces
+    # @abstract Subclass and override {#handle} to define your custom tasks
+    class Task < Job
+      # Child classes should implement the handle method
+      def handle
+        raise NotImplemented,
+              "Your workflow does not implement the `handle' method"
+      end
+    end
+  end
+end

data/lib/zenaton/interfaces/workflow.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'zenaton/interfaces/job'
+
+module Zenaton
+  module Interfaces
+    # @abstract Subclass and override {#handle} to implement a custom Workflow
+    class Workflow < Job
+      # Method called to run the workflow
+      def handle
+        raise NotImplemented,
+              "Your workflow does not implement the `handle' method"
+      end
+
+      # (Optional) Implement this method if you want to use custom IDs for your
+      # workflows.
+      # @return [String, Integer, NilClass] the custom id. Must be <= 256 bytes.
+      def id
+        nil
+      end
+    end
+  end
+end

data/lib/zenaton/parallel.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'zenaton/engine'
+
+module Zenaton
+  # Convenience class to execute jobs in parallel
+  class Parallel
+    # Build a collection of jobs to be executed in parallel
+    # @param items [Zenaton::Interfaces::Job]
+    def initialize(*items)
+      @items = items
+    end
+
+    # Execute synchronous jobs
+    def execute
+      Engine.instance.execute(@items)
+    end
+
+    # Dispatches asynchronous jobs
+    def dispatch
+      Engine.instance.dispatch(@items)
+    end
+  end
+end

data/lib/zenaton/processor.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Zenaton
+  # Zenaton Processor
+  class Processor
+    # processes the jobs
+    # @param jobs [Array<Zenaton::Interfaces::Job>]
+    # @param bool [Boolean]
+    def process(jobs, bool); end
+  end
+end

data/lib/zenaton/query/builder.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'zenaton/exceptions'
+require 'zenaton/client'
+require 'zenaton/interfaces/workflow'
+
+module Zenaton
+  # Wrapper module for interacting with jobs
+  module Query
+    # Wrapper class around the client to interact with workflows by id
+    class Builder
+      def initialize(klass)
+        check_klass(klass)
+        @klass = klass
+        @client = Client.instance
+      end
+
+      # Sets the id of the workflow we want to find
+      # @param id [String, NilClass] the id
+      # @return [Zenaton::Query::Builder] the current builder
+      def where_id(id)
+        @id = id
+        self
+      end
+
+      # Finds a workflow
+      # @return [Zenaton::Interfaces::Workflow]
+      def find
+        @client.find_workflow(@klass, @id)
+      end
+
+      # Sends an event to a workflow
+      # @param event [Zenaton::Interfaces::Event] the event to send
+      # @return [Zenaton::Query::Builder] the current builder
+      def send_event(event)
+        @client.send_event(@klass, @id, event)
+        self
+      end
+
+      # Stops a workflow
+      # @return [Zenaton::Query::Builder] the current builder
+      def kill
+        @client.kill_workflow(@klass, @id)
+        self
+      end
+
+      # Pauses a workflow
+      # @return [Zenaton::Query::Builder] the current builder
+      def pause
+        @client.pause_workflow(@klass, @id)
+        self
+      end
+
+      # Resumes a workflow
+      # @return [Zenaton::Query::Builder] the current builder
+      def resume
+        @client.resume_workflow(@klass, @id)
+        self
+      end
+
+      private
+
+      def check_klass(klass)
+        msg = "#{klass} should be a subclass of Zenaton::Interfaces::Workflow"
+        raise ExternalError, msg unless klass < Interfaces::Workflow
+      end
+    end
+  end
+end