card 1.17.4 → 1.18.0

data/lib/card/stage.rb

@@ -0,0 +1,72 @@
+class Card
+  # The process of writing a card change to the database is divided into
+  # 8 stages that are grouped in 3 phases.
+  #
+  # 'validation phase'
+  #   * initialize stage
+  #   * prepare_to_validate stage
+  #   * validate stage
+  #
+  # 'storage phase'
+  #   * prepare_to_store stage
+  #   * store stage
+  #   * finalize stage
+  #
+  # 'integration phase'
+  #   * integrate stage
+  #   * integrate_with_delay stage
+  #
+  #
+  module Stage
+    STAGES = [:initialize, :prepare_to_validate, :validate, :prepare_to_store,
+              :store, :finalize, :integrate, :integrate_with_delay].freeze
+    STAGE_INDEX = {}
+    STAGES.each_with_index do |stage, i|
+      STAGE_INDEX[stage] = i
+    end
+    STAGE_INDEX.freeze
+
+    def stage_symbol index
+      case index
+      when Symbol
+        return index if STAGE_INDEX[index]
+      when Integer
+        return STAGES[index] if index < STAGES.size
+      end
+      raise Card::Error, "not a valid stage index: #{index}"
+    end
+
+    def stage_index stage
+      case stage
+      when Symbol then
+        return STAGE_INDEX[stage]
+      when Integer then
+        return stage
+      else
+        raise Card::Error, "not a valid stage: #{stage}"
+      end
+    end
+
+    def stage_ok? opts
+      stage && (
+      (opts[:during] && in?(opts[:during])) ||
+        (opts[:before] && before?(opts[:before])) ||
+        (opts[:after] && after?(opts[:after])) ||
+        true # no phase restriction in opts
+      )
+    end
+
+    def before? allowed_phase
+      STAGE_INDEX[allowed_phase] > STAGE_INDEX[stage]
+    end
+
+    def after? allowed_phase
+      STAGE_INDEX[allowed_phase] < STAGE_INDEX[stage]
+    end
+
+    def in? allowed_phase
+      (allowed_phase.is_a?(Array) && allowed_phase.include?(stage)) ||
+        allowed_phase == stage
+    end
+  end
+end

data/lib/card/stage_director.rb

@@ -0,0 +1,231 @@
+
+class Card
+  # A 'StageDirector' executes the stages of a card when the card gets created,
+  # updated or deleted.
+  # For subcards, i.e. other cards that are changed in the same act, a
+  # StageDirector has StageSubdirectors that take care of the stages for
+  # those cards
+  #
+  # In general a stage is executed for all involved cards before the
+  # StageDirector proceeds with the next stage.
+  # Only exception is the finalize stage.
+  # The finalize stage of a subcard is executed immediately after its store
+  # stage. When all subcards are finalized the supercard's finalize stage is
+  # executed.
+  #
+  # If a subcard is added in a stage then it catches up at the end of the stage
+  # to the current stage.
+  # For example if you add a subcard in a card's :prepare_to_store stage then
+  # after that stage the stages :initialize, :prepare_to_validate,
+  # :validate and :prepare_to_store are executed for the subcard.
+  #
+  # Stages are executed with pre-order depth-first search.
+  # That means if A has subcards AA and AB; AAA is subcard of AA and ABA
+  # subcard of AB then the order of execution is
+  # A -> AA -> AAA -> AB -> ABA
+  #
+  # A special case can happen in the store phase.
+  # If the id of a subcard is needed for a supercard
+  # (for example as left_id or as type_id) and the subcard doesn't
+  # have an id yet (because it gets created in the same act)
+  # then the subcard's store stage is executed before the supercard's store
+  # stage
+  class StageDirector
+    include Stage
+
+    attr_accessor :prior_store, :act, :card, :stage, :parent, :main,
+                  :subdirectors
+    attr_reader :running
+    alias running? running
+    alias main? main
+
+    def initialize card, opts={}, main=true
+      @card = card
+      @card.director = self
+      @card.prepare_for_phases
+      @stage = nil
+      @running = false
+      @parent = opts[:parent]
+      # has card to be stored before the supercard?
+      @prior_store = opts[:priority]
+      @main = main
+      @subdirectors = SubdirectorArray.initialize_with_subcards(self)
+      register
+    end
+
+    def register
+      Card::DirectorRegister.add self
+    end
+
+    def unregister
+      @card.director = nil
+      @subdirectors = nil
+      @stage = nil
+      @action = nil
+      Card::DirectorRegister.delete self
+    end
+
+    def validation_phase
+      @running = true
+      run_single_stage :initialize
+      run_single_stage :prepare_to_validate
+      run_single_stage :validate
+      @card.expire_pieces if @card.errors.any?
+      @card.errors.empty?
+    end
+
+    # everything in here can use dirty marks
+    def storage_phase &block
+      # for a subcard :prepare_to_store was already executed
+      # don't execute it twice
+      catch_up_to_stage :prepare_to_store
+      run_single_stage :store, &block
+      run_single_stage :finalize
+    ensure
+      @from_trash = nil
+    end
+
+    # dirty marks are gone in this phase
+    def integration_phase
+      run_single_stage :integrate
+      run_single_stage :integrate_with_delay
+    rescue => e  # don't rollback
+      Card::Error.current = e
+      @card.notable_exception_raised
+      return false
+    end
+
+    def catch_up_to_stage next_stage
+      @stage ||= -1
+      (@stage + 1).upto(stage_index(next_stage)) do |i|
+        run_single_stage stage_symbol(i)
+      end
+    end
+
+    def call_after_store &block
+      @call_after_store ||= []
+      @call_after_store << block
+    end
+
+    def need_act
+      act_director = main_director
+      unless act_director
+        raise Card::Error, 'act requested without a main stage director'
+      end
+      act_director.act ||= Card::Act.create(ip_address: Env.ip)
+      @card.current_act = @act = act_director.act
+    end
+
+    def main_director
+      if main?
+        self
+      else
+        DirectorRegister.act_director || (@parent && @parent.main_director)
+      end
+    end
+
+    private
+
+    def run_single_stage stage, &block
+      # puts "#{@card.name}: #{stage} stage".red
+      @stage = stage_index stage
+      return if @card.errors.any? && @stage <= stage_index(:validate)
+
+      # in the store stage it can be necessary that
+      # other subcards must be saved before we save this card
+      if stage == :store
+        store(&block)
+      else
+        run_stage_callbacks stage
+        run_subdirector_stages stage unless stage == :finalize
+      end
+    rescue => e
+      @card.rescue_event e
+    end
+
+    def run_stage_callbacks stage
+      # we use abort :success in the :store stage for :save_draft
+      if stage_index(stage) <= stage_index(:store) && !main?
+        @card.abortable do
+          @card.run_callbacks :"#{stage}_stage"
+        end
+      else
+        @card.run_callbacks :"#{stage}_stage"
+      end
+    end
+
+    def run_subdirector_stages stage
+      @subdirectors.each do |subdir|
+        subdir.catch_up_to_stage stage
+      end
+    ensure
+      @card.handle_subcard_errors
+    end
+
+    # handle the store stage
+    # The tricky part here is to preserve the dirty marks on the subcards'
+    # attributes for the finalize stage.
+    # To achieve this we can't just call the :store and :finlaize callbacks on
+    # the subcards as  we do in the other phases.
+    # Instead we have to call `save` on the subcards
+    # and use the ActiveRecord :around_save callback to run the :store and
+    # :finalize stages
+    def store &save_block
+      if main? && !block_given?
+        raise Card::Error, 'need block to store main card'
+      end
+      # the block is the ActiveRecord block from the around save callback that
+      # saves the card
+      if block_given?
+        run_stage_callbacks :store
+        store_with_subcards(&save_block)
+      else
+        store_and_finalize_as_subcard
+      end
+    end
+
+    def store_with_subcards
+      store_prior_subcards
+      yield
+      if @call_after_store
+        @call_after_store.each do |handle_id|
+          handle_id.call(@card.id)
+        end
+      end
+      store_subcards
+      @virtual = false # TODO: find a better place for this
+    ensure
+      @card.handle_subcard_errors
+    end
+
+    # store subcards whose ids we need for this card
+    def store_prior_subcards
+      @subdirectors.each do |subdir|
+        next unless subdir.prior_store
+        subdir.catch_up_to_stage :store
+      end
+    end
+
+    def store_subcards
+      @subdirectors.each do |subdir|
+        next if subdir.prior_store
+        subdir.catch_up_to_stage :store
+      end
+    end
+
+    # trigger the storage_phase, skip the other phases
+    # At this point the :prepare_to_store stage was already executed
+    # by the parent director. So the storage phase will only run
+    # the :store stage and the :finalize stage
+    def store_and_finalize_as_subcard
+      @card.skip_phases = true
+      @card.save! validate: false
+    end
+  end
+
+  class StageSubdirector < StageDirector
+    def initialize card, opts={}
+      super card, opts, false
+    end
+  end
+end

data/lib/card/subcards.rb

@@ -11,29 +11,13 @@
 class Card
   def subcards
     @subcards ||= Subcards.new(self)
-  end
-
-  def preserve_subcards
-    return unless subcards.present?
-    Card.cache.soft.write subcards_cache_key, @subcards
-  end
-
-  def restore_subcards
-    cached_subcards = Card.cache.soft.read(subcards_cache_key)
-    return unless cached_subcards
-    @subcards = cached_subcards
-    @subcards.context_card = self
+    # @subcards ||= (director && director.subcards)
   end
 
   def expire_subcards
-    Card.cache.soft.delete subcards_cache_key
     subcards.clear
   end
 
-  def subcards_cache_key
-    "#{key}#SUBCARDS#"
-  end
-
   class Subcards
     attr_accessor :context_card, :keys
     def initialize context_card
@@ -48,6 +32,15 @@ class Card
       @keys = ::Set.new
     end
 
+    def deep_clear cleared=::Set.new
+      each_card do |card|
+        next if cleared.include? card.id
+        cleared << card.id
+        card.subcards.deep_clear cleared
+      end
+      clear
+    end
+
     def remove name_or_card
       key = case name_or_card
             when Card
@@ -96,8 +89,15 @@ class Card
       end
     end
 
-    def rename old_name, new_name
+    def catch_up_to_stage stage_index
+      each_card do |subcard|
+        subcard.catch_up_to_stage stage_index
+      end
+    end
+
+    def rename old_name, _new_name
       return unless @keys.include? old_name.to_name.key
+      # FIXME: something should happen here
     end
 
     def << value
@@ -122,7 +122,7 @@ class Card
       end
     end
 
-    alias_method :each, :each_card
+    alias each each_card
 
     def each_with_key
       @keys.each do |key|
@@ -146,9 +146,7 @@ class Card
 
     def field name
       key = field_name_to_key name
-      if @keys.include? key
-        fetch_subcard key
-      end
+      fetch_subcard key if @keys.include? key
     end
 
     def card name
@@ -173,8 +171,8 @@ class Card
       end
     end
 
-    alias_method :add_field, :add_child
-    alias_method :remove_field, :remove_child
+    alias add_field add_child
+    alias remove_field remove_child
 
     def present?
       @keys.present?
@@ -240,7 +238,41 @@ class Card
       end
       @keys << card.key
       Card.write_to_soft_cache card
+      card.director = @context_card.director.subdirectors.add(card)
       card
     end
   end
+
+  def right_id= card_or_id
+    write_card_or_id :right_id, card_or_id
+  end
+
+  def left_id= card_or_id
+    write_card_or_id :left_id, card_or_id
+  end
+
+  def type_id= card_or_id
+    write_card_or_id :type_id, card_or_id
+  end
+
+  def write_card_or_id attribute, card_or_id
+    if card_or_id.is_a? Card
+      card = card_or_id
+      if card.id
+        write_attribute attribute, card.id
+      else
+        add_subcard card
+        card.director.prior_store = true
+        with_id_when_exists(card) do |id|
+          write_attribute attribute, id
+        end
+      end
+    else
+      write_attribute attribute, card_or_id
+    end
+  end
+
+  def with_id_when_exists card, &block
+    card.director.call_after_store(&block)
+  end
 end

data/lib/card/subdirector_array.rb

@@ -0,0 +1,31 @@
+class Card
+  class SubdirectorArray < Array
+    def self.initialize_with_subcards parent
+      dir_array = new(parent)
+      parent.card.subcards.each_card do |subcard|
+        dir_array.add subcard
+      end
+      dir_array
+    end
+
+    def initialize parent
+      @parent = parent
+      super()
+    end
+
+    def add card
+      each do |dir|
+        return dir if dir.card == card
+      end
+      dir = Card::DirectorRegister.fetch card, parent: @parent
+      dir.main = false
+      dir.parent = @parent
+      self << dir
+      dir
+    end
+
+    def delete card
+      delete_if { |dir| dir.card == card }
+    end
+  end
+end