junkfood 0.1.0

data/lib/junkfood/adler32_pure.rb

@@ -0,0 +1,112 @@
+# encoding: utf-8
+# Copyright 2009 Benjamin Yu <http://benjaminyu.org/>
+#
+# 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.
+
+module Junkfood
+
+  ##
+  # A pure Ruby implementation of the Adler-32 checksum algorithm.
+  #
+  # This Ruby implementation is a port of the pure Python reference
+  # implementation found in the pysync project. The Python reference
+  # implementation, itself, was a port from zlib's adler32.c file.
+  #
+  # @example
+  #   adler32 = Junkfood::Adler32Pure.new('Wikipedia')
+  #   puts adler32.digest #=> 300286872
+  #
+  # @see http://zlib.net/
+  # @see http://freshmeat.net/projects/pysync/
+  #
+  class Adler32Pure
+
+    # largest prime smaller than 65536
+    BASE = 65521
+    # largest n such that 255n(n+1)/2 + (n+1)(BASE-1) <= 2^32-1
+    NMAX = 5552
+    # default initial s1 offset
+    OFFS = 1
+
+    ##
+    # @param data (String) initial block of data to digest.
+    #
+    def initialize(data='')
+      @count = 0
+      @s2 = 0
+      @s1 = OFFS
+      self.update(data)
+    end
+
+    ##
+    # Adds another block of data to digest.
+    #
+    # @param data (String) block of data to digest.
+    # @return (Fixnum) the updated digest.
+    #
+    def update(data)
+      i = 0
+      while i < data.length
+        data[i,i+NMAX].each_byte do |b|
+          @s1 = @s1 + b
+          @s2 = @s2 + @s1
+        end
+        @s1 = @s1 % BASE
+        @s2 = @s2 % BASE
+        i = i + NMAX
+      end
+      @count = @count + data.length
+      return self.digest
+    end
+
+    ##
+    # @param x1 (Byte)
+    # @param xn (Byte)
+    # @return (Fixnum) the updated digest.
+    #
+    def rotate(x1, xn)
+      @s1 = (@s1 - x1 + xn) % BASE
+      @s2 = (@s2 - (@count * x1) + @s1 - OFFS) % BASE
+      return self.digest
+    end
+
+    ##
+    # @param b (Byte)
+    # @return (Fixnum) the updated digest.
+    #
+    def rollin(b)
+      @s1 = (@s1 + b) % BASE
+      @s2 = (@s2 + @s1) % BASE
+      @count = @count + 1
+      return self.digest
+    end
+
+    ##
+    # @param b (Byte)
+    # @return (Fixnum) the updated digest.
+    #
+    def rollout(b)
+      @s1 = (@s1 - b) % BASE
+      @s2 = (@s2 - @count * b) % BASE
+      @count = @count - 1
+      return self.digest
+    end
+
+    ##
+    # @return (Fixnum) the current Adler32 digest value.
+    #
+    def digest
+      return (@s2 << 16) | @s1
+    end
+  end
+end

data/lib/junkfood/assert.rb

@@ -0,0 +1,75 @@
+# encoding: utf-8
+# Copyright 2010 Benjamin Yu <http://benjaminyu.org/>
+#
+# 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.
+
+module Junkfood
+
+  ##
+  # A dumbed down implementation for Assertions based on the 'wrong' gem,
+  # but without any of wrong's awesomeness. This is just for the future in
+  # case 'wrong' disappears from the scene.
+  #
+  # @example
+  #   class MyClass
+  #     include Junkfood::Assert
+  #     def my_method
+  #       assert { true }
+  #       assert('Custom Error Message') { false }
+  #     rescue Junkfood::Assert::AssertionFailedError => e
+  #       puts e
+  #     end
+  #   end
+  #
+  module Assert
+
+    ##
+    # Error thrown when an assertion fails.
+    #
+    class AssertionFailedError < RuntimeError
+    end
+
+    ##
+    # Tests an assertion claim.
+    #
+    # @example
+    #   x = 3
+    #   assert { x == 2 }
+    #   assert('failure message') { x == 1 }
+    #
+    # @overload assert
+    #   @yield block with predicates to determine whether or not to raise
+    #     an AssertionFailedError.
+    #   @yieldreturn [Boolean, nil]
+    #
+    # @overload assert(message)
+    #   @param message (String) the custom error message of for the
+    #     AssertionFailedError.
+    #   @yield block with predicates to determine whether or not to raise
+    #     an AssertionFailedError.
+    #   @yieldreturn [Boolean, nil]
+    #
+    # @raise AssertionFailedError when the block yields a false/nil value.
+    #
+    # @see http://rubygems.org/gems/wrong
+    #
+    def assert(*args, &block)
+      begin
+        return super if block.nil?
+      rescue NoMethodError
+        raise 'You must pass a block for assertion check'
+      end
+      raise AssertionFailedError, args.first unless yield
+    end
+  end
+end

data/lib/junkfood/base32.rb

@@ -0,0 +1,198 @@
+# encoding: utf-8
+# Copyright 2010 Benjamin Yu <http://benjaminyu.org/>
+#
+# 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 'stringio'
+
+module Junkfood
+
+  ##
+  # Error class raised when an invalid Base32 character encoding is encountered.
+  #
+  class Base32DecodeError < StandardError
+  end
+
+  ##
+  # Base32 (RFC4668/3548) encodes and decodes strings of data.
+  #
+  # Requires at least Ruby 1.9
+  #
+  # @see http://tools.ietf.org/html/rfc4648
+  #
+  class Base32
+    # The Base32 alphabet, all caps.
+    ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'
+    ALPHABET.freeze
+    # The Base32 alphabet, all lowercase.
+    ALPHABET_DOWNCASE = ALPHABET.downcase
+    ALPHABET_DOWNCASE.freeze
+
+    # Once populated, this is Base32 alphabet to byte mapping.
+    BYTE_MAP = {}
+    (0..(ALPHABET.size)).each do |i|
+      BYTE_MAP[ALPHABET.getbyte(i)] = i
+      BYTE_MAP[ALPHABET_DOWNCASE.getbyte(i)] = i
+    end
+    # This is clear up confusions between the pairs: 1 and I, 0 and O.
+    BYTE_MAP['1'.getbyte(0)] = BYTE_MAP['I'.getbyte(0)]
+    BYTE_MAP['0'.getbyte(0)] = BYTE_MAP['O'.getbyte(0)]
+    BYTE_MAP.freeze
+
+    # Spacer characters to ignore when parsing a Base32 encoded string.
+    IGNORED = "\r\n-_\s".bytes.to_a
+    IGNORED.freeze
+
+    ##
+    # The hash of available break strings that can be inserted between
+    # X number of Base32 characters (during the encoding process).
+    SPLITS = {
+      dash: '-', 
+      newline: "\n",
+      space: ' ',
+      underscore: '_'
+    }.freeze
+
+    ##
+    # Base32 encodes the input object and writes to the output io object.
+    #
+    # @param input [#each_byte]
+    # @option options [#putc] :output (StringIO.new) of the output IO.
+    # @option options [String] :split :dash, :newline, :space, or :underscore
+    # @option options [Fixnum] :split_length (79) number of Base32 characters
+    #   before inserting a split character.
+    # @return IO, StringIO instance of object to which encoded data was written.
+    #
+    def self.encode(input, options={})
+      output = options[:output] || StringIO.new(''.force_encoding('US-ASCII'))
+      alphabet = options[:use_downcase] ? ALPHABET_DOWNCASE : ALPHABET
+
+      split = SPLITS[options[:split]]
+      split_length = options[:split_length] || 79
+
+      # Set up the lambda that does the actual work of writing the
+      # quintet to the output stream.
+      if split
+        # This lambda will split up the output stream with a "break" character
+        # for every N quintets (where N is the split_length).
+        split_count = 0
+        write = lambda do |quintet|
+          output.putc alphabet.getbyte(quintet)
+          split_count += 1
+          if split_count >= split_length
+            output.putc split 
+            split_count = 0
+          end
+        end
+      else
+        # This lambda just writes out the quintets
+        write = lambda do |quintet|
+          output.putc alphabet.getbyte(quintet)
+        end
+      end
+
+      position = 0
+      buffer = 0
+      input.each_byte do |byte|
+        case position
+        when 0
+          # Current Buffer: 0 bits from previous byte
+          # Quintet: 5 bits from current byte
+          # New Buffer: Lowest 3 bits of current byte
+          write.call(byte >> 3)
+          buffer = byte & 0x07
+        when 1
+          # Current Buffer: 3 bits from previous byte
+          # Quintet 1: 3 bits of buffer and first 2 bits of current byte
+          # Quintet 2: next 5 bits of byte
+          # New Buffer: Lowest 1 bit of current byte
+          write.call((buffer << 2) | (byte >> 6))
+          write.call((byte >> 1) & 0x1f)
+          buffer = byte & 0x01
+        when 2
+          # Current Buffer: 1 bits from previous byte
+          # Quintet 1: 1 bits of buffer and 4 bits of current byte
+          # New Buffer: Lowest 4 bits of current byte
+          write.call((buffer << 4) | (byte >> 4))
+          buffer = byte & 0x0f
+        when 3
+          # Current Buffer: 4 bits from previous byte
+          # Quintet 1: 4 bits of buffer and top bit of byte
+          # Quintet 2: next 5 bits of byte
+          # New Buffer: bottom 2 bit of byte
+          write.call((buffer << 1) | (byte >> 7))
+          write.call((byte >> 2) & 0x1f)
+          buffer = byte & 0x03
+        when 4
+          # Current Buffer: 2 bits from previous byte
+          # Quintet 1: 2 bits of buffer and top 3 bits of byte
+          # Quintet 2: bottom 5 bits of byte
+          write.call((buffer << 3) | (byte >> 5))
+          write.call(byte & 0x1f) 
+          buffer = 0
+        end
+        position = (position + 1) % 5
+      end
+      case position
+      when 0
+        # We are 40-bit aligned, so nothing to do.
+      when 1
+        # 3 bits in buffer
+        write.call(buffer << 2)
+      when 2
+        # 1 bit in buffer
+        write.call(buffer << 4)
+      when 3
+        # 4 bits in buffer
+        write.call(buffer << 1)
+      when 4
+        # 2 bits in buffer
+        write.call(buffer << 3)
+      end
+
+      return output
+    end
+
+    ##
+    # Base32 decodes the input object and writes to the output io object.
+    #
+    # @param input [#each_byte]
+    # @option options [#putc] :output (StringIO.new) of the output IO.
+    #   before inserting a split character.
+    # @return IO, StringIO instance of object to which decoded data was written.
+    # @raise Base32DecodeError
+    #
+    def self.decode(input, options={})
+      output = options[:output] || StringIO.new(''.force_encoding('BINARY'))
+      buffer = 0
+      bits_left = 0
+      input.each_byte do |byte|
+        next if IGNORED.include? byte
+        raise Base32DecodeError.new("Invalid input byte: #{byte}") unless(
+          BYTE_MAP.key? byte)
+        buffer = (buffer << 5) | BYTE_MAP[byte]
+        bits_left += 5
+        if bits_left >= 8
+          bits_left -= 8
+          output.putc(buffer >> bits_left)
+          buffer &= (2 ** bits_left - 1)
+        end
+      end
+      # We ignore remaining bits in the buffer in cases where there is an
+      # incomplete Base32 quantum (ie, the number of characters are unaligned
+      # with the 40-bit boundries).
+
+      return output
+    end
+  end
+end

data/lib/junkfood/ceb/base_command.rb

@@ -0,0 +1,62 @@
+# encoding: utf-8
+# Copyright 2010 Benjamin Yu <http://benjaminyu.org/>
+#
+# 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 'junkfood/ceb/bus'
+require 'mongoid'
+
+module Junkfood
+  module Ceb
+
+    ##
+    # BaseCommand abstract class from which one defines and implements
+    # actual Commands to be run.
+    #
+    # _id (id)
+    # _type
+    # created_at
+    # origin
+    class BaseCommand
+      include Junkfood::Ceb::Bus
+      include Mongoid::Document
+
+      acts_as_event_bus
+
+      references_many(
+        :events,
+        :inverse_of => :command,
+        :class_name => 'Junkfood::Ceb::BaseEvent')
+
+      field :created_at, :type => Time
+      field :origin, :type => String
+
+      after_initialize :generate_default_values
+
+      ##
+      # @abstract implement the actual handler logic to execute the command.
+      #
+      def perform
+      end
+
+      protected
+
+      ##
+      # Before create hook to set the Command's default values.
+      #
+      def generate_default_values
+        self.created_at = Time.now unless self.created_at
+      end
+    end
+  end
+end

data/lib/junkfood/ceb/base_event.rb

@@ -0,0 +1,42 @@
+# encoding: utf-8
+# Copyright 2010 Benjamin Yu <http://benjaminyu.org/>
+#
+# 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 'mongoid'
+
+module Junkfood
+  module Ceb
+
+    ##
+    # _id (id)
+    # _type
+    # created_at
+    # command_id
+    class BaseEvent
+      include Mongoid::Document
+
+      field :created_at, :type => Time
+
+      referenced_in :command, :class_name => 'Junkfood::Ceb::BaseCommand'
+
+      after_initialize :generate_default_values
+
+      protected
+
+      def generate_default_values
+        self.created_at = Time.now unless self.created_at
+      end
+    end
+  end
+end

data/lib/junkfood/ceb/bus.rb

@@ -0,0 +1,152 @@
+# encoding: utf-8
+# Copyright 2010 Benjamin Yu <http://benjaminyu.org/>
+#
+# 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 'active_support/concern'
+require 'active_support/core_ext/class/attribute'
+require 'active_support/core_ext/string/inflections'
+require 'junkfood/ceb/executors/command_executor'
+require 'junkfood/ceb/executors/event_executor'
+
+module Junkfood
+  module Ceb
+
+    ##
+    # Module to implement the bus framework for Ceb.
+    #
+    # @example
+    #
+    #   class WidgetCreateCommand < Junkfood::Ceb::BaseCommand
+    #     def perform
+    #       # Do Stuff.
+    #     end
+    #   end
+    #
+    #   class ApplicationController < ActionController::Base
+    #     include Junkfood::Ceb::Bus
+    #     acts_as_command_bus
+    #   end
+    #
+    #   class WidgetController < ApplicationController
+    #     def create
+    #       # params['widget'] is our posted form data the same as how Rails
+    #       # does it for ActiveModel. This eliminates hassle for
+    #       # custom parsing, data handling.
+    #
+    #       # Create a command (WidgetCreateCommand) and puts it onto the bus
+    #       # for execution. The command created is returned along with
+    #       # published events by the command.
+    #       command, events = send_command 'widget_create', params['widget']
+    #
+    #       if command.valid?
+    #         # The command is correctly formed, so the backend executors will
+    #         # execute it in the future (or already has executed it).
+    #       end
+    #
+    #       # Commands SHOULD return the Event, or list of Events,
+    #       # that the command published when its `perform` method was called.
+    #       case result
+    #       when Junkfood::Ceb::BaseEvent
+    #         # The single published event.
+    #         # Can assume that the command was executed.
+    #       when Array
+    #         # An array of Events published.
+    #         # Can assume that the command was executed.
+    #       when nil, false
+    #         # No data was passed back. Nothing can be assumed about the
+    #         # execution of the command.
+    #       end
+    #     end
+    #   end
+    #
+    # Notes for implementers:
+    # * Executors MAY reraise all raised errors
+    #   * This is for problems in the "process" of executing commands,
+    #   * not actual errors in the command's execution itself.
+    # * Messages SHOULD handle their errors, publishing Error Events
+    #   when a command fails.
+    # * Callers of this method SHOULD check the command to see if
+    #   validation errors occurred.
+    #
+    # @see ClassMethods
+    #
+    module Bus
+      extend ActiveSupport::Concern
+
+      ##
+      # Methods to add to the actual classes that include Junkfood::Ceb::Bus.
+      #
+      module ClassMethods
+
+        ##
+        # Creates:
+        # * a class attribute for the bus executor.
+        # * an instance method to put a message onto the bus.
+        #
+        # @param bus_type (Symbol) the name of the bus.
+        # @param executor (#call) a handler for the bus' messages.
+        #
+        def acts_as_bus(bus_type, executor=nil)
+          class_eval do
+            # We create the class attributes (accessors) for this executor
+            # so individual instances or subclasses can override this.
+            # And it sets it to the given executor or an empty executor
+            executor_name = "#{bus_type}_executor"
+            class_attribute executor_name
+            send "#{executor_name}=", (executor || Proc.new {})
+
+            # Now we define a the bus method in the form of `send_<bus_type>`.
+            # This is the main method that objects call to look up the
+            # commands/events, instantiate them, and execute on them.
+            # This method will return the created command/event along with
+            # the executor's results.
+            method_name = "send_#{bus_type}"
+            define_method(method_name, lambda { |name, *args|
+              klass = "#{name}_#{bus_type}".to_s.classify.constantize
+              message = klass.new *args
+              results = message.valid? ? send(executor_name).call(message) : nil
+              return message, results
+            })
+          end
+        end
+
+        ##
+        # Creates:
+        # * command_executor class attributes.
+        # * send_command instance method to put commands onto the bus.
+        #
+        # @param executor (#call) an actual executor to use instead of the
+        #   default ::Junkfood::Ceb::Executors::CommandExecutor.
+        #
+        def acts_as_command_bus(
+            executor=::Junkfood::Ceb::Executors::CommandExecutor.new)
+          acts_as_bus :command, executor
+        end
+
+        ##
+        # Creates:
+        # * event_executor class attributes.
+        # * send_event instance method to put events onto the bus.
+        #
+        # @param executor (#call) an actual executor to use instead of the
+        #   default ::Junkfood::Ceb::Executors::EventExecutor.
+        #
+        def acts_as_event_bus(
+            executor=::Junkfood::Ceb::Executors::EventExecutor.new)
+          acts_as_bus :event, executor
+        end
+      end
+    end
+  end
+end

data/lib/junkfood/ceb/executors/command_executor.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+# Copyright 2010 Benjamin Yu <http://benjaminyu.org/>
+#
+# 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.
+
+module Junkfood
+  module Ceb
+    module Executors
+
+      ##
+      # Processes the command from the command_bus. The command is
+      # saved, then its perform method is executed.
+      #
+      class CommandExecutor
+
+        ##
+        # @param command (BaseCommand) the command to save and perform.
+        #
+        def call(command)
+          # We need to raise an error here if we can't save.
+          # But we only save if it's a new record.
+          # Junction asserted that command was valid before calling this
+          # executor, thus any errors in saving probably have to do with
+          # connectivity... we want to abort.
+          command.save! if command.new_record?
+          # We assume that the command will catch all of its problems and
+          # publish error events?
+          # TODO: should wrap this up and publish a generic CommandFailedEvent.
+          return command.perform
+        end
+      end
+    end
+  end
+end