garcun 0.0.2

data/lib/garcon/utility/retry.rb

@@ -0,0 +1,238 @@
+# encoding: UTF-8
+#
+# Author:    Stefano Harding <riddopic@gmail.com>
+# License:   Apache License, Version 2.0
+# Copyright: (C) 2014-2015 Stefano Harding
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require_relative 'timeout'
+require_relative '../exceptions'
+
+module Garcon
+  # Class methods that are added when you include Garcon::Retry
+  #
+  module Retry
+    # Methods are also available as module-level methods as well as a mixin.
+    extend self
+
+    include Garcon::Exceptions
+
+    # Runs a code block, and retries it when an exception occurs. It is
+    # configured using four optional parameters `:tries`, `:on`, `:sleep`,
+    # `:match`, `:ensure` and runs the passed block. Should an exception
+    # occur, it'll retry for (n-1) times. Should the number of retries be
+    # reached without success, the last exception will be raised.
+    #
+    # @example open an URL, retry up to two times when an OpenURI::HTTPError
+    #   occurs.
+    #     retrier(tries: 3, on: OpenURI::HTTPError) do
+    #       xml = open('http://example.com/test.html').read
+    #     end
+    #
+    # @example do _something_, retry up to four times for either ArgumentErro
+    #   or TimeoutError exceptions.
+    #     retrier(tries: 5, on: [ArgumentError, TimeoutError]) do
+    #       # _something_ code
+    #     end
+    #
+    # @example ensure that block of code is executed, regardless of whether an
+    #   exception was raised. It doesn't matter if the block exits normally,
+    #   if it retries to execute block of code, or if it is terminated by an
+    #   uncaught exception -- the ensure block will get run.
+    #     f = File.open('testfile')
+    #     ensure_cb = Proc.new do |retries|
+    #       puts "total retry attempts: #{retries}"
+    #       f.close
+    #     end
+    #     retrier(insure: ensure_cb) do
+    #       # process file
+    #     end
+    #
+    # @example sleeping: by default Retrier waits for one second between
+    #   retries. You can change this and even provide your own exponential
+    #   backoff scheme.
+    #     retrier(sleep:  0) { }              # don't pause between retries
+    #     retrier(sleep: 10) { }              # sleep 10s between retries
+    #     retrier(sleep: ->(n) { 4**n }) { }  # sleep 1, 4, 16, etc. each try
+    #
+    # @example matching error messages: you can also retry based on the
+    #   exception message:
+    #     retrier(matching: /IO timeout/) do |retries, exception|
+    #       raise "yo, IO timeout!" if retries == 0
+    #     end
+    #
+    # @example block parameters: your block is called with two optional
+    #   parameters; the number of tries until now, and the most recent
+    #   exception.
+    #     retrier do |tries, exception|
+    #       puts "try #{tries} failed with error: #{exception}" if retries > 0
+    #       # keep trying...
+    #     end
+    #
+    # @param opts [Hash]
+    #
+    # @option opts [Fixnum] :tries
+    #   Number of attempts to retry before raising the last exception
+    #
+    # @option opts [Fixnum] :sleep
+    #   Number of seconds to wait between retries, use lambda to exponentially
+    #   increasing delay between retries.
+    #
+    # @option opts [Array(Exception)] :on
+    #   The type of exception(s) to catch and retry on
+    #
+    # @option opts [Regex] :matching
+    #   Match based on the exception message
+    #
+    # @option opts [Block] :ensure
+    #   Ensure a block of code is executed, regardless of whether an exception
+    #   is raised
+    #
+    # @yield [Proc]
+    #   A block that will be run, and if it raises an error, re-run until
+    #   success, or timeout is finally reached.
+    #
+    # @raise [Exception]
+    #   Last Exception that caused the loop to retry before giving up.
+    #
+    # @return [Proc]
+    #   The value of the passed block.
+    #
+    # @api public
+    def retrier(opts = {}, &_block)
+      tries  = opts.fetch(:tries,            4)
+      wait   = opts.fetch(:sleep,            1)
+      on     = opts.fetch(:on,   StandardError)
+      match  = opts.fetch(:match,         /.*/)
+      insure = opts.fetch(:ensure, Proc.new {})
+
+      retries         = 0
+      retry_exception = nil
+
+      begin
+        yield retries, retry_exception
+      rescue *[on] => e
+        raise unless e.message =~ match
+        raise if retries + 1 >= tries
+
+        begin
+          sleep wait.respond_to?(:call) ? wait.call(retries) : wait
+        rescue *[on]
+        end
+
+        retries += 1
+        retry_exception = exception
+        retry
+      ensure
+        insure.call(retries)
+      end
+    end
+
+    # `#poll` is a method for knowing when something is ready. When your
+    # block yields true, execution continues. When your block yields false,
+    # poll keeps trying until it gives up and raises an error.
+    #
+    # @example wait up to 30 seconds for the TCP socket to respond.
+    #   def wait_for_server
+    #     poll(30) do
+    #       begin
+    #         TCPSocket.new(SERVER_IP, SERVER_PORT)
+    #         true
+    #       rescue Exception
+    #         false
+    #       end
+    #     end
+    #   end
+    #
+    # @param [Integer] wait
+    #   The number of seconds seconds to poll.
+    #
+    # @param [Integer] delay
+    #   Number of seconds to wait after encountering a failure, default is
+    #   0.1 seconds
+    #
+    # @yield [Proc]
+    #   A block that determines whether polling should continue. Return
+    #   `true` if the polling is complete. Return `false` if polling should
+    #   continue.
+    #
+    # @raise [Garcon::PollingError]
+    #   Raised after too many failed attempts.
+    #
+    # @return [Proc]
+    #   The value of the passed block.
+    #
+    # @api public
+    def poll(wait = 8, delay = 0.1)
+      try_until = Time.now + wait
+
+      while Time.now < try_until do
+        result = yield
+        return result if result
+        sleep delay
+      end
+      raise TimeoutError
+    end
+
+    # Similar to `#poll`, `#patiently` also executes an arbitrary code block.
+    # If the passed block runs without raising an error, execution proceeds
+    # normally. If an error is raised, the block is rerun after a brief
+    # delay, until the block can be run without exceptions. If exceptions
+    # continue to raise, `#patiently` gives up after a bit (default 8
+    # seconds) by re-raising the most recent exception raised by the block.
+    #
+    # @example
+    #   Returns immedialtely if no errors or as soon as error stops.
+    #     patiently { ... }
+    #
+    #   Increase patience to 10 seconds.
+    #     patiently(10)    { ... }
+    #
+    #   Increase patience to 20 seconds, and delay for 3 seconds before retry.
+    #     patiently(20, 3) { ... }
+    #
+    # @param [Integer] seconds
+    #   number of seconds to be patient, default is 8 seconds
+    #
+    # @param [Integer] delay
+    #   seconds to wait after encountering a failure, default is 0.1 seconds
+    #
+    # @yield [Proc]
+    #   A block that will be run, and if it raises an error, re-run until
+    #   success, or patience runs out.
+    #
+    # @raise [Exception] the most recent Exception that caused the loop to
+    #   retry before giving up.
+    #
+    # @return [Proc]
+    #   the value of the passed block.
+    #
+    # @api public
+    def patiently(wait = 8, delay = 0.1)
+      try_until = Time.now + wait
+      failure   = nil
+
+      while Time.now < try_until do
+        begin
+          return yield
+        rescue Exception => e
+          failure = e
+          sleep delay
+        end
+      end
+      failure ? (raise failure) : (raise TimeoutError)
+    end
+  end
+end

data/lib/garcon/utility/timeout.rb

@@ -0,0 +1,58 @@
+# encoding: UTF-8
+#
+# Author:    Stefano Harding <riddopic@gmail.com>
+# License:   Apache License, Version 2.0
+# Copyright: (C) 2014-2015 Stefano Harding
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require 'thread'
+require_relative '../exceptions'
+
+module Garcon
+  # Class methods that are added when you include Garcon::Timeout
+  #
+  module Timeout
+    # Methods are also available as module-level methods as well as a mixin.
+    extend self
+
+    include Garcon::Exceptions
+
+    # Wait the given number of seconds for the block operation to complete.
+    # Intended to be a simpler and more reliable replacement to the Ruby
+    # standard library `Timeout::timeout` method.
+    #
+    # @param [Integer] seconds
+    #   Number of seconds to wait for the block to terminate. Any number may
+    #   be used, including Floats to specify fractional seconds. A value of 0
+    #   or nil will execute the block without any timeout.
+    #
+    # @return [Object]
+    #   Result of the block if the block completed before the timeout,
+    #   otherwise raises a TimeoutError exception.
+    #
+    # @raise [Garcon::TimeoutError]
+    #   When the block operation does not complete in the alloted time.
+    #
+    # @see Ruby Timeout::timeout
+    #
+    # @api public
+    def timeout(seconds)
+      thread = Thread.new  { Thread.current[:result] = yield }
+      thread.join(seconds) ? (return thread[:result]) : (raise TimeoutError)
+    ensure
+      Thread.kill(thread) unless thread.nil?
+    end
+  end
+end

data/lib/garcon/utility/uber/builder.rb

@@ -0,0 +1,91 @@
+module Uber
+  # When included, allows to add builder on the class level.
+  #
+  #   class Operation
+  #     include Uber::Builder
+  #
+  #     builds do |params|
+  #       SignedIn if params[:current_user]
+  #     end
+  #
+  #     class SignedIn
+  #     end
+  #
+  # The class then has to call the builder to compute a class name using the build blocks you defined.
+  #
+  #     def self.build(params)
+  #       class_builder.call(params).
+  #       new(params)
+  #     end
+  module Builder
+    def self.included(base)
+      base.class_eval do
+        def self.builders
+          @builders ||= []
+        end
+
+        extend ClassMethods
+      end
+    end
+
+    class Constant
+      def initialize(constant) # TODO: evaluate usage of builders and implement using Uber::Options::Value.
+        @constant     = constant
+        @builders     = @constant.builders # only dependency, must be a Cell::Base subclass.
+      end
+
+      def call(*args)
+        build_class_for(*args)
+      end
+
+    private
+      def build_class_for(*args)
+        @builders.each do |blk|
+          klass = run_builder_block(blk, *args) and return klass
+        end
+        @constant
+      end
+
+      def run_builder_block(block, *args)
+        block.call(*args)
+      end
+    end
+
+    module ClassMethods
+      # Adds a builder to the cell class. Builders are used in #cell to find out the concrete
+      # class for rendering. This is helpful if you frequently want to render subclasses according
+      # to different circumstances (e.g. login situations) and you don't want to place these deciders in
+      # your view code.
+      #
+      # Passes the model and options from #cell into the block.
+      #
+      # Multiple build blocks are ORed, if no builder matches the building cell is used.
+      #
+      # Example:
+      #
+      # Consider two different user box cells in your app.
+      #
+      #   class AuthorizedUserBox < UserInfoBox
+      #   end
+      #
+      #   class AdminUserBox < UserInfoBox
+      #   end
+      #
+      # Now you don't want to have deciders all over your views - use a declarative builder.
+      #
+      #   UserInfoBox.build do |model, options|
+      #     AuthorizedUserBox if options[:is_signed_in]
+      #     AdminUserBox if model.admin?
+      #   end
+      #
+      # In your view #cell will instantiate the right cell for you now.
+      def builds(proc=nil, &block)
+        builders << (proc.kind_of?(Proc) ? proc : block)
+      end
+
+      def class_builder
+        @class_builder ||= Constant.new(self)
+      end
+    end # ClassMethods
+  end
+end

data/lib/garcon/utility/uber/callable.rb

@@ -0,0 +1,7 @@
+module Uber
+  # Include this module into a class or extend an object to mark it as callable.
+  # E.g., in a dynamic option in Options::Value it will be treated like a Proc object
+  # and invoked with +#call+.
+  module Callable
+  end
+end

data/lib/garcon/utility/uber/delegates.rb

@@ -0,0 +1,13 @@
+require 'forwardable'
+
+module Uber
+  module Delegates
+    def delegates(model, *names)
+      mod = Module.new do
+        extend Forwardable
+        def_delegators model, *names
+      end
+      include mod
+    end
+  end
+end

data/lib/garcon/utility/uber/inheritable_attr.rb

@@ -0,0 +1,37 @@
+module Uber
+  module InheritableAttr
+    def inheritable_attr(name)
+      instance_eval %Q{
+        def #{name}=(v)
+          @#{name} = v
+        end
+
+        def #{name}
+          return @#{name} if instance_variable_defined?(:@#{name})
+          @#{name} = InheritableAttribute.inherit_for(self, :#{name})
+        end
+      }
+    end
+
+    def self.inherit_for(klass, name)
+      return unless klass.superclass.respond_to?(name)
+
+      value = klass.superclass.send(name) # could be nil.
+      Clone.(value) # this could be dynamic, allowing other inheritance strategies.
+    end
+
+    class Clone
+      # The second argument allows injecting more types.
+      def self.call(value, uncloneable=uncloneable())
+        uncloneable.each { |klass| return value if value.kind_of?(klass) }
+        value.clone
+      end
+
+      def self.uncloneable
+        [Symbol, TrueClass, FalseClass, NilClass]
+      end
+    end
+  end
+
+  InheritableAttribute = InheritableAttr
+end