hobo 1.1.0 → 1.3.0.RC

data/lib/hobo/model/lifecycles/actions.rb

@@ -0,0 +1,146 @@
+# We need to be able to eval an expression outside of the Hobo module
+# so that, e.g. "User" doesn't eval to "Hobo::Model::User"
+# (Ruby determines this constant lookup scope lexically)
+def __top_level_eval__(obj, expr)
+  obj.instance_eval(expr)
+end
+
+module Hobo
+  module Model
+    module Lifecycles
+      module Actions
+
+        def available_to_acting_user?(record)
+          return true if available_to.nil? # available_to not specified (these steps are not published)
+          acting_user_is?(available_to, record)
+        end
+
+        def publishable_by(user, who, record)
+          case who
+          when :all
+            true
+
+          when :key_holder
+            record.lifecycle.valid_key?
+
+          when :self
+            record == user
+
+          when Array
+            # recursively apply the same test to every item in the array
+            who.detect { |w| publishable_by(user, w, record) }
+
+          else
+            refl = record.class.reflections[who]
+            if refl && refl.macro == :has_many
+              record.send(who).include?(user)
+            elsif refl && refl.macro == :belongs_to
+              record.send("#{who}_is?", user)
+            else
+              value = run_hook(record, who)
+              if value.is_a?(Class)
+                user.is_a?(value)
+              elsif value.respond_to?(:include?)
+                value.include?(user)
+              else
+                value == user
+              end
+            end
+          end
+        end
+
+        def acting_user_is?(who, record)
+          publishable_by(record.acting_user, who, record)
+        end
+
+        def run_hook(record, hook, *args)
+          case hook
+          when Symbol
+            record.send(hook, *args)
+          when String
+            __top_level_eval__(record, hook)
+          when Proc
+            if hook.arity == 1
+              hook.call(record)
+            else
+              record.instance_eval(&hook)
+            end
+          end
+        end
+
+
+        def fire_event(record, event)
+          if event
+            if event.arity == 1
+              event.call(record)
+            else
+              record.instance_eval(&event)
+            end
+          end
+        end
+
+
+        def guard_ok?(record)
+          if options[:if]
+            raise ArgumentError, "do not provide both :if and :unless to lifecycle steps" if options[:unless]
+            run_hook(record, options[:if])
+          elsif options[:unless]
+            !run_hook(record, options[:unless])
+          else
+            true
+          end
+        end
+
+
+        def prepare!(record, attributes)
+          record.attributes = extract_attributes(attributes) if attributes
+          record.lifecycle.generate_key if options[:new_key]
+          apply_user_becomes!(record)
+        end
+
+
+        def can_run?(record)
+          available_to_acting_user?(record) && guard_ok?(record) && record.lifecycle.invariants_satisfied?
+        end
+
+
+        def available_to
+          options[:available_to]
+        end
+
+
+        def publishable?
+          available_to
+        end
+
+
+        def routable_for?(subsite)
+          publishable? && options[:subsite] == subsite
+        end
+
+
+        def apply_user_becomes!(record)
+          if (assoc = options[:user_becomes])
+            record.send("#{assoc}=", record.acting_user)
+          end
+        end
+
+        def get_state(record, state)
+          case state
+          when Proc
+            if state.arity == 1
+              state.call(record)
+            else
+              record.instance_eval(&state)
+            end
+          when String
+            eval(state, record.instance_eval { binding })
+          else
+            state
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/hobo/model/lifecycles/creator.rb

@@ -0,0 +1,74 @@
+module Hobo
+  module Model
+    module Lifecycles
+
+      class Creator < Struct.new(:lifecycle, :name, :on_create, :options)
+
+        def initialize(*args)
+          super
+          self.name = name.to_sym
+          lifecycle.creators[name] = self
+        end
+
+        include Actions
+
+        def allowed?(user)
+          record = lifecycle.model.new
+          record.with_acting_user(user) { can_run?(record) }
+        end
+
+
+        def candidate(user, attributes=nil)
+          record = lifecycle.model.new
+          record.with_acting_user(user) { prepare!(record, attributes) }
+          record.exempt_from_edit_checks = true
+          record
+        end
+
+
+        def extract_attributes(attributes)
+          model = lifecycle.model
+          params = options.fetch(:params, [])
+          allowed = params.dup
+          params.each do |p|
+            if (refl = model.reflections[p]) && refl.macro == :belongs_to
+              allowed << refl.primary_key_name.to_s
+              allowed << refl.options[:foreign_type] if refl.options[:polymorphic]
+            end
+          end
+          attributes & allowed
+        end
+
+
+        def change_state(record)
+          state = get_state(record, options[:become])
+          record.lifecycle.become state if state
+        end
+
+
+        def run!(user, attributes)
+          record = lifecycle.model.new
+          record.lifecycle.active_step = self
+          record.with_acting_user(user) do
+            prepare!(record, attributes)
+            if can_run?(record)
+              if change_state(record)
+                fire_event(record, on_create)
+              end
+              record
+            else
+              raise Hobo::PermissionDeniedError
+            end
+          end
+        end
+
+
+        def parameters
+          options[:params] || []
+        end
+
+      end
+
+    end
+  end
+end

data/lib/hobo/model/lifecycles/lifecycle.rb

@@ -0,0 +1,243 @@
+module Hobo
+  module Model
+    module Lifecycles
+
+      class Lifecycle
+
+        def self.init(model, options)
+          @model   = model
+          @options = options
+          reset
+        end
+
+        def self.reset
+          @states        = {}
+          @creators      = {}
+          @transitions   = []
+          @invariants    = []
+        end
+
+        class << self
+          attr_accessor :model, :options, :states, :default_state,
+                        :creators, :transitions, :invariants
+        end
+
+        def self.def_state(name, on_enter)
+          name = name.to_sym
+          class_eval "def #{name}_state?; state_name == :#{name} end"
+          states[name] = Lifecycles::State.new(name, on_enter)
+        end
+
+
+        def self.def_creator(name, on_create, options)
+          class_eval %{
+                       def self.#{name}(user, attributes=nil)
+                         create(:#{name}, user, attributes)
+                       end
+                       def self.can_#{name}?(user, attributes=nil)
+                         can_create?(:#{name}, user)
+                       end
+                      }
+          Creator.new(self, name.to_s, on_create, options)
+        end
+
+        def self.def_transition(name, start_state, end_states, on_transition, options)
+          class_eval %{
+                       def #{name}!(user, attributes=nil)
+                         transition(:#{name}, user, attributes)
+                       end
+                       def can_#{name}?(user, attributes=nil)
+                         can_transition?(:#{name}, user)
+                       end
+                      }
+          Transition.new(self, name.to_s, start_state, end_states, on_transition, options)
+        end
+
+        def self.state_names
+          states.keys
+        end
+
+        def self.publishable_creators
+          creators.values.where.publishable?
+        end
+
+        def self.publishable_transitions
+          transitions.where.publishable?
+        end
+
+        def self.step_names
+          (creators.keys | transitions.*.name).uniq
+        end
+
+
+        def self.creator(name)
+          creators[name.to_sym] or raise ArgumentError, "No such creator in lifecycle: #{name}"
+        end
+
+
+        def self.can_create?(name, user)
+          creators[name.to_sym].allowed?(user)
+        end
+
+
+        def self.create(name, user, attributes=nil)
+          creator = creators[name.to_sym] or raise LifecycleError, "No creator #{name} available"
+          creator.run!(user, attributes)
+        end
+
+
+        def self.state_field
+          options[:state_field]
+        end
+
+        def self.key_timeout
+          options[:key_timeout]
+        end
+
+
+        # --- Instance Features --- #
+
+        attr_reader :record
+
+        attr_accessor :provided_key, :active_step
+
+
+        def initialize(record)
+          @record = record
+        end
+
+
+        def can_transition?(name, user)
+          available_transitions_for(user, name).any?
+        end
+
+
+        def transition(name, user, attributes)
+          transition = find_transition(name, user) or raise LifecycleError, "No transition #{name} available"
+          transition.run!(record, user, attributes)
+        end
+
+
+        def find_transition(name, user)
+          available_transitions_for(user, name).first
+        end
+
+
+        def state_name
+          name = record.read_attribute(self.class.state_field)
+          name.to_sym if name
+        end
+
+
+        def state
+          self.class.states[state_name]
+        end
+
+
+        def available_transitions
+          state ? state.transitions_out : []
+        end
+
+        # see also publishable_transitions_for
+        def available_transitions_for(user, name=nil)
+          name = name.to_sym if name
+          matches = available_transitions
+          matches = matches.select { |t| t.name == name } if name
+          record.with_acting_user(user) do
+            matches.select { |t| t.can_run?(record) }
+          end
+        end
+
+        def publishable_transitions_for(user)
+          record.with_acting_user(user) do
+            available_transitions_for(user).select do |t|
+              t.publishable_by(user, t.available_to, record)
+            end
+          end
+        end
+
+
+        def become(state_name, validate=true)
+          state_name = state_name.to_sym
+          record.send :write_attribute, self.class.state_field, state_name.to_s
+
+          if state_name == :destroy
+            record.destroy
+            true
+          else
+            s = self.class.states[state_name]
+            raise ArgumentError, "No such state '#{state_name}' for #{record.class.name}" unless s
+
+            if record.save(:validate => validate)
+              s.activate! record
+              self.active_step = nil # That's the end of this step
+              true
+            else
+              false
+            end
+          end
+        end
+
+
+        def key_timestamp_field
+          record.class::Lifecycle.options[:key_timestamp_field]
+        end
+
+        def key_timeout
+          record.class::Lifecycle.options[:key_timeout]
+        end
+
+        def generate_key
+          if Time.zone.nil?
+            raise RuntimeError, "Cannot generate lifecycle key timestamp if the time-zone is not configured. Please add, e.g. config.time_zone = 'UTC' to environment.rb"
+          end
+          key_timestamp = Time.now.utc
+          record.send :write_attribute, key_timestamp_field, key_timestamp
+          key
+        end
+
+
+        def key
+          require 'digest/sha1'
+          timestamp = record.read_attribute(key_timestamp_field)
+          if timestamp
+            timestamp = timestamp.getutc
+            Digest::SHA1.hexdigest("#{record.id}-#{state_name}-#{timestamp}-#{Rails.application.config.secret_token}")
+          end
+        end
+
+        def key_expired?
+          timestamp = record.read_attribute(key_timestamp_field)
+          timestamp.nil? || (timestamp.getutc + key_timeout < Time.now.utc)
+        end
+
+        def valid_key?
+          provided_key && provided_key == key && !key_expired?
+        end
+
+        def clear_key
+          record.send :write_attribute, key_timestamp_field, nil
+        end
+
+        def invariants_satisfied?
+          self.class.invariants.all? { |i| record.instance_eval(&i) }
+        end
+
+
+        def active_step_is?(name)
+          active_step && active_step.name == name.to_sym
+        end
+
+        def method_missing(name, *args)
+          if name.to_s =~ /^(.*)_in_progress\?$/
+            active_step_is?($1)
+          else
+            super
+          end
+        end
+
+      end
+
+    end
+  end
+end