ballast 1.0.0

data/lib/ballast/concerns/ajax.rb

@@ -0,0 +1,116 @@
+#
+# This file is part of the ballast gem. Copyright (C) 2013 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Ballast
+  # A set of concerns to address common issues.
+  module Concerns
+    # A concern to handle AJAX and HTTP requests.
+    module Ajax
+      extend ActiveSupport::Concern
+
+      # Checks if the current request is AJAX.
+      #
+      # @return [Boolean] `true` if the request is AJAX, `false` otherwise.
+      def is_ajax?
+        (request.respond_to?(:xhr?) && request.xhr?) || params[:xhr].to_boolean
+      end
+
+      # Prepares an AJAX response.
+      #
+      # @param status [Symbol|Fixnum] The HTTP status of the response.
+      # @param data [Object] Additional data to append to the response.
+      # @param error [Object] A error to append to the response.
+      def prepare_ajax(status = :ok, data = nil, error = nil)
+        rv = {status: status}.ensure_access(:indifferent)
+        rv[:error] = error if error.present?
+        rv[:data] = data if data.present?
+        rv
+      end
+
+      # Sends an AJAX response to the client.
+      #
+      # @param data [Hash] The response to send.
+      # @param status [Symbol|Fixnum] The HTTP status of the response, *ignored if already set in data*.
+      # @param format [Symbol] The content type of the response.
+      def send_ajax(data, status: :ok, format: :json)
+        if !performed? then
+          # Prepare data
+          data = prepare_ajax_send(data, status)
+
+          # Setup callback and format
+          format, callback, content_type = format_ajax_send(format)
+          status = data[:status]
+
+          # Prepare data for formatting
+          data = ActiveSupport::JSON.encode(data) if [:json, :jsonp, :pretty_json, :pretty_jsonp, :text].include?(format)
+
+          # Render
+          render(format => data, status: status, callback: callback, content_type: content_type)
+        end
+      end
+
+      # Updates an AJAX response from a operation, taking either the response data or the first error.
+      #
+      # @param data [Hash] The current data.
+      # @param operation [Operation] The operation to gather data from.
+      # @return [Hash] The updated data.
+      def update_ajax(data, operation = nil)
+        operation ||= @operation
+        data.merge!(operation.success? ? {data: operation.response[:data]} : {error: operation.errors.first})
+        data
+      end
+
+      # Prevents HTTP caching.
+      def prevent_caching
+        response.headers.merge!({
+          "Cache-Control" => "no-cache, no-store, max-age=0, must-revalidate",
+          "Pragma" => "no-cache",
+          "Expires" => "Fri, 01 Jan 1990 00:00:00 GMT"
+        })
+      end
+
+      # Allows HTTP Cross-Origin Resource Sharing.
+      def allow_cors
+        headers.merge!({
+          "Access-Control-Allow-Origin" => "*",
+          "Access-Control-Allow-Methods" => "POST, GET, OPTIONS",
+          "Access-Control-Allow-Headers" => "*",
+          "Access-Control-Max-Age" => 1.year.to_i.to_s
+        })
+      end
+
+      # Disallows web robots.
+      def disallow_robots
+        render(text: "User-agent: *\nDisallow: /", content_type: "text/plain")
+      end
+
+      private
+        # Prepares data for sending back to the client.
+        #
+        # @param data [Object] The data to send back. Can be a full response or partial data.
+        # @param status [Symbol|Fixnum] The HTTP status to set if a new response must be created.
+        # @return [Hash] An HTTP response.
+        def prepare_ajax_send(data, status)
+          data = prepare_ajax(status, data) if !data.is_a?(Hash)
+          data[:status] ||= status
+          data[:status] = Rack::Utils.status_code(data[:status].to_s.to_sym) if !data[:status].is_a?(Fixnum)
+          data
+        end
+
+        # Sets up parameters to send a response.
+        #
+        # @param format [Symbol] The format of the data.
+        # @return [Array] An array of format, callback and content_type.
+        def format_ajax_send(format)
+          format ||= params[:format] || request.format || "json"
+          format = format.to_sym
+          callback = format == :jsonp ? (params[:callback] || "jsonp#{Time.now.to_i}") : nil
+          content_type = (format == :text) ? "text/plain" : nil
+
+          [format, callback, content_type]
+        end
+    end
+  end
+end

data/lib/ballast/concerns/common.rb

@@ -0,0 +1,97 @@
+#
+# This file is part of the ballast gem. Copyright (C) 2013 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Ballast
+  module Concerns
+    # A concern to handle common tasks in an application.
+    module Common
+      # Checks if the user is sending any data.
+      #
+      # @return [Boolean] `true` if the user is sending data, `false` otherwise.
+      def sending_data?
+        request.post? || request.put?
+      end
+
+      # Performs an operation, using itself as owner by default.
+      #
+      # @param klass [Class] The operation to perform.
+      # @param owner [Object] The owner to use. By default it uses itself.
+      # @param kwargs [Hash] The arguments for performing.
+      # @return [Operation] The performed operation
+      def perform_operation(klass, owner = nil, **kwargs)
+        @operation = klass.perform(owner || self, **kwargs)
+      end
+
+      # Formats a relative date using abbreviation or short formats.
+      #
+      # @param date [DateTime] The date to format.
+      # @param reference [DateTime] The reference date.
+      # @param suffix [String] The suffix to add to the formatted date.
+      # @return [String] The formatted date.
+      def format_short_duration(date, reference = nil, suffix = "")
+        reference ||= Time.now
+        amount = (reference.to_i - date.to_i).to_i
+
+        if amount <= 0 then
+          "now"
+        elsif amount < 1.day then
+          format_short_amount(amount, suffix)
+        elsif amount < 1.year then
+          date.strftime("%b %d")
+        else
+          date.strftime("%b %d %Y")
+        end
+      end
+
+      # Formats a short amount of time (less than one hour).
+      #
+      # @param amount [Fixnum] The amount to format.
+      # @param suffix [String] The suffix to add to the formatted amount.
+      # @return [String] The formatted amount.
+      def format_short_amount(amount, suffix)
+        if amount < 1.minute then
+          "#{amount.floor}s#{suffix}"
+        elsif amount < 1.hour then
+          "#{(amount / 60).floor}m#{suffix}"
+        else
+          "#{(amount / 3600).floor}h#{suffix}"
+        end
+      end
+
+      # Formats a long date.
+      #
+      # @param date [DateTime] The date to format.
+      # @param separator [String] The separator between date and time.
+      # @param format [String] The format of the date, like in strftime. Use `%-` for the separator, `%o` for the ordinalized version of the day of the month
+      #   and `%:Z` for the zone name considering also DST.
+      def format_long_date(date, separator = "•", format = "%I:%M%p %- %b %o, %Y (%:Z)")
+        tz = Time.zone
+        replacements = {"%-" => separator, "%o" => date.day.ordinalize, "%:Z" => tz.send(tz.uses_dst? && date.dst? ? :dst_name : :name)}
+        date.strftime(format).gsub(/%(-|o|(:Z))/) {|r| replacements.fetch(r, r) }
+      end
+
+      # Authenticates a user via HTTP, handling the error if the authentication failed.
+      #
+      # @param area [String] The name of the area.
+      # @param title [String] A title for authentication errors.
+      # @param message [String] A message for authentication errors.
+      # @param authenticator [Proc] A block to verify if authentication is valid.
+      def authenticate_user(area = nil, title = nil, message = nil, &authenticator)
+        area ||= "Private Area"
+        title ||= "Authentication required."
+        message ||= "To view this resource you have to authenticate."
+        authenticated = authenticate_with_http_basic { |username, password| authenticator.call(username, password) }
+
+        if !authenticated then
+          headers["WWW-Authenticate"] = "Basic realm=\"#{area}\""
+          @error_title = title
+          @error_code = 401
+          @error_message = message
+          handle_error
+        end
+      end
+    end
+  end
+end

data/lib/ballast/concerns/errors_handling.rb

@@ -0,0 +1,49 @@
+#
+# This file is part of the ballast gem. Copyright (C) 2013 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Ballast
+  module Concerns
+    # A concern to handle errors.
+    module ErrorsHandling
+      extend ActiveSupport::Concern
+
+      # Handles an error in the application.
+      #
+      # @param exception [Hash|Exception] The exception to handle.
+      # @param layout [String] The layout to use to render the error.
+      # @param title [String] The title to set in case of custom errors.
+      def handle_error(exception = nil, layout = "error", title = "Error - Application")
+        @error ||= exception
+
+        if @error.is_a?(Lazier::Exceptions::Debug) then
+          @error_title = "Debug"
+          @error_code = 503
+        elsif @error.is_a?(Hash) then
+          @error_title = title
+          @error_code = @error[:status]
+          @error_message = @error[:error]
+        else
+          @error_title = "Error - #{@error.class.to_s}"
+          @error_code = 500
+        end
+
+        send_or_render_error(layout)
+      end
+
+      private
+        # Send an AJAX error o renders it.
+        #
+        # @param layout [String] The layout to use to render the error.
+        def send_or_render_error(layout)
+          if is_ajax? then
+            data = prepare_ajax(@error_code, {type: @error_title, backtrace: @error.backtrace.join("\n")}, @error_message || @error.message)
+            send_ajax(data)
+          else
+            render(nothing: true, status: @error_code, layout: layout, formats: [:html])
+          end
+        end
+    end
+  end
+end

data/lib/ballast/concerns/view.rb

@@ -0,0 +1,63 @@
+#
+# This file is part of the ballast gem. Copyright (C) 2013 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Ballast
+  module Concerns
+    # A concern to help view handling.
+    module View
+      # Scopes the CSS of the current page using the controller and action name.
+      #
+      # @return [String] The scoped string.
+      def scope_css
+        "%s %s" % [controller_path.gsub("/", "-"), action_name]
+      end
+
+      # Returns an instance of the browser.
+      #
+      # @return [Browser] A browser object.
+      def browser
+        @browser ||= Brauser::Browser.new(request.user_agent)
+      end
+
+      # Checks if the current browser is supported according to a definition YAML file.
+      #
+      # @param conf_file [String] The configuration file which holds the definitions.
+      # @return [Boolean] `true` if the browser is supported, `false` otherwise.
+      def browser_supported?(conf_file = nil)
+        conf_file ||= (Rails.root + "config/supported-browsers.yml").to_s if defined?(Rails)
+        browser.supported?(conf_file)
+      end
+
+      # Outputs the Javascript parameters.
+      #
+      # @param as_html [Boolean] Whether to return the parameters as HTML rather than hash.
+      # @param tag [Symbol] The tag to use for HTML.
+      # @param id [String] The id for the tag.
+      # @return [String|Hash] Javascript parameters as HTML or the hash.
+      def javascript_params(as_html = true, tag = :details, id = nil)
+        as_html ? content_tag(tag, @javascript_params.to_json.html_safe, "data-jid" => id): @javascript_params
+      end
+
+      # Appends new Javascript parameters.
+      #
+      # @param key [String|Symbol] The key of the new parameters. If `nil`, the root will be merged/replaced.
+      # @param data [Hash] The data to add.
+      # @param replace [Boolean] Whether to replace existing data rather than merge.
+      def add_javascript_params(key, data, replace = false)
+        @javascript_params ||= HashWithIndifferentAccess.new
+
+        if key
+          @javascript_params[key] = nil if replace
+          @javascript_params[key] ||= {}
+          @javascript_params[key].merge!(data)
+        elsif replace
+          @javascript_params = data.with_indifferent_access
+        else
+          @javascript_params.merge!(data)
+        end
+      end
+    end
+  end
+end

data/lib/ballast/context.rb

@@ -0,0 +1,38 @@
+#
+# This file is part of the ballast gem. Copyright (C) 2013 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Ballast
+  # A context for an operation. It is basically a Hash with few enhancements, like owner, errors and output support.
+  class Context < Interactor::Context
+    # Builds a new context.
+    #
+    # @param owner [Object] The owner of this context.
+    # @param additional [Hash] Additional parameters to include into the context.
+    def self.build(owner, additional = {})
+      super({
+        owner: owner,
+        errors: [],
+        output: nil,
+        response: HashWithIndifferentAccess.new
+      }.merge(additional).ensure_access(:indifferent))
+    end
+
+    # Lookups missing methods in the delegatee hash.
+    #
+    # @param method [Symbol] The method to lookup.
+    # @param args [Array] The arguments passed to the method. *This is ignored.*
+    # @param block [Proc] The block passed to the method. *This is ignored.*
+    # @return [Object] The value for the method, if present.
+    def method_missing(method, *args, &block)
+      object = __getobj__
+
+      if object[method] then
+        object[method]
+      else
+        super(method, *args, &block)
+      end
+    end
+  end
+end

data/lib/ballast/errors.rb

@@ -0,0 +1,34 @@
+#
+# This file is part of the ballast gem. Copyright (C) 2013 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Ballast
+  # Common errors raised by a Rails application.
+  module Errors
+    # The base error raised from an application.
+    #
+    # @attribute [r] response
+    #   @return [String|Hash] The response which contains either a message or an hash with status code and a error message.
+    class BaseError < RuntimeError
+      attr_reader :response
+
+      def initialize(msg = nil)
+        super(msg)
+        @response = msg
+      end
+    end
+
+    # This is raised when an invalid domain is requested.
+    class InvalidDomain < BaseError
+    end
+
+    # This is raised when something went wrong during the processing of a operation.
+    class PerformError < BaseError
+    end
+
+    # This is raised when some invalid parameters are passed to a operation.
+    class ValidationError < BaseError
+    end
+  end
+end

data/lib/ballast/operation.rb

@@ -0,0 +1,136 @@
+#
+# This file is part of the ballast gem. Copyright (C) 2013 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Ballast
+  # A operation represents a single responsibility class. Subclasses should only expose and override the #perform method.
+  class Operation
+    extend ::Forwardable
+    include Interactor
+    def_delegators :context, :owner, :errors, :response, :output
+
+    # Performs the operation.
+    #
+    # @param owner_or_context [Object|Context] If is a context, then it will be the context of the operation, otherwise a blank a context with the object
+    #   as owner will be created.
+    # @param context [NilClass] The context for the operation. *Ignored if `owner_or_context` is a context.*
+    # @param params [Hash] The additional parameters for the new context. *Ignored if `owner_or_context` is a context.*
+    # @return [Operation] The performed operation.
+    def self.perform(owner_or_context, context: nil, params: {})
+      arg = owner_or_context
+      arg = (context || ::Ballast::Context.build(owner_or_context, params)) if !arg.is_a?(::Ballast::Context)
+      super(arg)
+    end
+
+    # Creates a new operation.
+    #
+    # @param context [Context] The context for the operation.
+    def initialize(context)
+      @context = context
+      setup
+    end
+
+    # Sets up the response hash from instance variables.
+    #
+    # @param force [Boolean] Whether to setup the response even if the operation failed.
+    # @return [Hash] The response hash.
+    def setup_response(force = false)
+      if success? || force then
+        vars = instance_variables
+        vars.delete(:@context)
+
+        context.response.merge!(vars.reduce({}){ |rv, var|
+          rv[var.to_s.gsub(/[:@]/, "")] = instance_variable_get(var)
+          rv
+        })
+      end
+
+      context.response
+    end
+
+    # Imports the response hash into the target instance variables.
+    #
+    # @param target [Object] The target of the import.
+    # @param fields [Array] The keys to import.
+    # @param overwrite [Boolean] Whether to overwrite existing variables into the target. If set to `false`, any overwrite will raise an `ArgumentError`.
+    def import_response(target, *fields, overwrite: true)
+      fields.each do |field|
+        raise ArgumentError.new(field) if target.instance_variable_get("@#{field}") && !overwrite
+        target.instance_variable_set("@#{field}", response[field])
+      end
+    end
+
+    # Performs the operation handling base errors.
+    #
+    # @param setup_response_after [Boolean] Whether to setup the response after processing.
+    def perform_with_handling(setup_response_after = true)
+      begin
+        yield
+      rescue Lazier::Exceptions::Debug => de
+        raise de
+      rescue => e
+        e.is_a?(::Ballast::Errors::BaseError) ? fail!(e.response) : raise(e)
+      end
+
+      setup_response if setup_response_after
+    end
+
+    # Marks failure of the operation appending the error to the context.
+    #
+    # @param error [Object|NilClass] The error to store.
+    def fail!(error = nil)
+      errors << error if error
+      super()
+    end
+
+    # Imports the current operation errors into the target's `@error` instance variable or in the flash hash.
+    #
+    # @param target [Object] The target of the import.
+    # @param to_flash [Boolean] If to import the error in the target's flash object rather than the instance variable.
+    # @param first_only [Boolean] If to only import the first error.
+    def import_error(target, to_flash = true, first_only = true)
+      values = errors
+      values = values.map {|v| v[:error] } if to_flash
+      values = values.first if first_only
+
+      if to_flash then
+        target.flash[:error] = values
+      else
+        target.instance_variable_set(:@error, values)
+      end
+    end
+
+    # Resolves a numeric error to a human readable message.
+    #
+    # @param error [BaseError|Fixnum] The error to resolve.
+    # @param supported_messages [Hash] The list of supported error codes.
+    # @param only_message [Boolean] If to only return the message string rather than a full error hash.
+    # @return [String|Hash] The error with a human readable message or the message alone.
+    def resolve_error(error, supported_messages = {}, only_message = false)
+      code = (error.respond_to?(:response) ? error.response : 500).to_integer(500)
+      rv = {status: code, error: supported_messages.fetch(code, "Oops! We're having some issue. Please try again later.")}
+      only_message ? rv[:error] : rv
+    end
+
+    # If running under eventmachine, run the block in a thread of its threadpool using EM::Synchrony, otherwise run the block normally.
+    #
+    # @param block [Proc] The block to run.
+    def in_em_thread(&block)
+      EM.reactor_running? ? EM::Synchrony.defer(&block) : block.call
+    end
+
+    # Forwards any missing method to the owner.
+    #
+    # @param method [Symbol] The method to forward.
+    # @param args [Array] The arguments to pass to the method.
+    # @param block [Proc] The block to pass to the method.
+    def method_missing(method, *args, &block)
+      if owner.respond_to?(method)
+        owner.send(method, *args, &block)
+      else
+        super(method, *args, &block)
+      end
+    end
+  end
+end

data/lib/ballast/operations_chain.rb

@@ -0,0 +1,38 @@
+#
+# This file is part of the ballast gem. Copyright (C) 2013 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Ballast
+  # A operation made of several operation run sequentially passing the common context. The chain will stop on the first failure.
+  #
+  # @attribute [r] operations
+  #   @return [Array] The list of operations performed.
+  class OperationsChain < Operation
+    include ::Interactor::Organizer
+    attr_reader :operations
+
+    # Performs the chain.
+    #
+    # @param argument [Object|Context] If is a context, then it will be the context of the operation, unless a blank a context with the object
+    #   as owner will be created.
+    # @param operations [Array] The list of operations to perform.
+    # @param context [NilClass] The context for the operation. *Ignored if `owner_or_context` is a context.*
+    # @param params [Hash] The additional parameters for the new context. *Ignored if `owner_or_context` is a context.*
+    # @return [Operation] The performed chain.
+    def self.perform(argument, operations, context: nil, params: {})
+      argument = (context || ::Ballast::Context.build(argument, params)) if !argument.is_a?(::Ballast::Context)
+      new(operations, argument).tap(&:perform)
+    end
+
+    # Creates a new chain.
+    #
+    # @param operations [Array] The list of operations to perform.
+    # @param context [Context] The context for the chain.
+    def initialize(operations, context)
+      @context = context
+      @operations = operations.ensure_array
+      setup
+    end
+  end
+end

data/lib/ballast/version.rb

@@ -0,0 +1,24 @@
+#
+# This file is part of the ballast gem. Copyright (C) 2013 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+# A collection of base utilities for Ruby on Rails.
+module Ballast
+  # The current version of ballast, according to semantic versioning.
+  #
+  # @see http://semver.org
+  module Version
+    # The major version.
+    MAJOR = 1
+
+    # The minor version.
+    MINOR = 0
+
+    # The patch version.
+    PATCH = 0
+
+    # The current version of ballast.
+    STRING = [MAJOR, MINOR, PATCH].compact.join(".")
+  end
+end

data/lib/ballast.rb

@@ -0,0 +1,24 @@
+#
+# This file is part of the ballast gem. Copyright (C) 2013 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+require "lazier"
+require "brauser"
+require "interactor"
+require "addressable/uri"
+require "rack/utils"
+require "rack/fiber_pool"
+require "em-synchrony"
+
+Lazier.load!
+
+require "ballast/version" if !defined?(Ballast::Version)
+require "ballast/errors"
+require "ballast/context"
+require "ballast/operation"
+require "ballast/operations_chain"
+require "ballast/concerns/ajax"
+require "ballast/concerns/common"
+require "ballast/concerns/view"
+require "ballast/concerns/errors_handling"