card 1.19.1 → 1.19.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 17c71bfd48263a99742c5d53bf8be447d93eed8b
-  data.tar.gz: 3ee523e8b559f892c45012a03e1ebc9bf3389e01
+  metadata.gz: c530f9f078a90e9de4c239d7f5222e670b10b98a
+  data.tar.gz: 735604a8c31fe1247d23e3bbc5c90d495c83593a
 SHA512:
-  metadata.gz: d14d3a8d117e2b34cd4e830ba5ac3a60dd3f177b0864dc68cc93ef0455b324d43b4d336985415311d55341caf1569fe7e3b8de018f35d0adb5b69bb5ff265abc
-  data.tar.gz: 5d2e6b59ee7acfb5aff106683581ae5331b65a893c5c85af1b60273e0c84fd792805f2c7f6c11e7e2dbca4f0e7c3cbfb4f9336dc4bacf1b1d7c9279b92072baf
+  metadata.gz: 43e1f744865904f81aec258a25a0f823693b2b8b418491e451594a18f345fb4b79e796ece4ca46e4c9ac604c9622646faf137801353348802d7b5c790d14e270
+  data.tar.gz: 6224a80edc261e7b8636dce40fdb1357ee1d94e08c4fc32208587f6470b413c4e3af370156bfb1d9553159a5872245cc10cf1fb304d94d7413d50da90c8a4969

data/.yardopts

@@ -1,6 +1,6 @@
-**/lib/**/*.rb                    \
-**/mod/*/format/*.rb              \
-**/mod/*/chunk/*.rb               \
+lib/**/*.rb                       \
+mod/*/format/*.rb                 \
+mod/*/chunk/*.rb                  \
 tmpsets/set*/**/*.rb -            \
 **/*.rdoc                         \
 GPL                               \

data/VERSION

@@ -1 +1 @@
-1.19.1
+1.19.2

data/db/migrate_core_cards/20160908154210_add_trash_card.rb

@@ -0,0 +1,7 @@
+# -*- encoding : utf-8 -*-
+
+class AddTrashCard < Card::Migration::Core
+  def up
+    create_or_update name: "*trash", codename: "trash"
+  end
+end

data/lib/card.rb

@@ -42,8 +42,8 @@ class Card < ActiveRecord::Base
   require_dependency "card/reference"
   require_dependency "card/subcards"
   require_dependency "card/cache/view_cache"
-  require_dependency "card/stage_director"
-  require_dependency "card/director_register"
+  require_dependency "card/act_manager"
+  require_dependency "card/act_manager/stage_director"
 
   has_many :references_in,  class_name: :Reference, foreign_key: :referee_id
   has_many :references_out, class_name: :Reference, foreign_key: :referer_id

data/lib/card/act_manager.rb

@@ -0,0 +1,143 @@
+class Card
+  # Manages the whole process of creating an {act Card::Act} ie. changing
+  # a card and attached subcards.
+  #
+  # For every card that is part of the act the ActManager creates a
+  # {StageDirector} that leads the card through all the stages.
+  # Because cards sometimes get expired and reloaded during an act we need
+  # this global object to ensure that the stage information doesn't get lost
+  # until the act is finished.
+  #
+  # The process of creating an act/writing a card change to the database
+  # is divided into 8 stages that are grouped in 3 phases.
+  #
+  # 'validation phase'
+  #   * initialize stage (I)
+  #   * prepare_to_validate stage (P2V)
+  #   * validate stage (V)
+  #
+  # 'storage phase'
+  #   * prepare_to_store stage (P2S)
+  #   * store stage (S)
+  #   * finalize stage (F)
+  #
+  # 'integration phase'
+  #   * integrate stage (IG)
+  #   * integrate_with_delay stage (IGwD)
+  #
+  #
+  # The table below gives you an overview what you can do in which stage:
+  #
+  #                                  validation    |    storage    | integration
+  #                                 I    P2V  V    |  P2S  S    F  | IG   IGwD
+  #-------------------------------------------------------------------------
+  #    attach subcard               yes! yes! yes  | yes  yes  yes |    yes
+  #    detach subcard               yes! yes! yes  | yes  no   no! |    no!
+  #    validate                     yes  yes  yes! |      no       |    no
+  # 1  insecure change              yes  yes! no   |      no!      |    no!
+  # 2  secure change                     yes       | yes! no!  no! |    no!
+  #    abort                             yes!      |      yes      |    yes?
+  #    add errors                        yes!      |      no!      |    no!
+  # 3  create other cards                yes       |      yes      |    yes
+  #    has id                            no        | no   no?  yes |    yes
+  #    within web request                yes       |      yes      | yes  no
+  # 4  within transaction                yes       |      yes      |    no
+
+  #    available values:
+  #    dirty attributes                  yes       |      yes      |    yes
+  #    params                            yes       |      yes      |    yes
+  #    success                           yes       |      yes      | yes  no
+  #    session                           yes       |      yes      | yes  no
+  #
+  #
+  # Explanation:
+  #  yes!  the recommended stage to do that
+  #  yes   ok to do it here
+  #  no    not recommended; chance to mess things up
+  #        but if something forces you to do it here you can try
+  #  no!   never do it here. it won't work or will break things
+  #
+  # if there is only a single entry in a phase column it counts for all stages
+  # of that phase
+  #
+  # 1) 'insecure' means a change of a card attribute that can possibly make
+  #    the card invalid to save
+  # 2) 'secure' means you are sure that the change doesn't affect the validation
+  # 3) If you call 'create', 'update_attributes' or 'save' the card will become
+  #    part of the same act and all stage of the validation and storage phase
+  #    will be executed immediately for that card. The integration phase will be
+  #    executed together with the act card and its subcards
+  # 4) This means if an exception is raised in the validation or storage phase
+  #    everything will rollback. If the integration phase fails the db changes
+  #    of the other two phases will remain persistent.
+  class ActManager
+    cattr_accessor :act_card
+
+    class << self
+      def act_director
+        return unless act_card
+        act_card.director
+      end
+
+      def directors
+        @directors ||= {}
+      end
+
+      def clear
+        ActManager.act_card = nil
+        directors.each_pair do |card, _dir|
+          card.director = nil
+        end
+        @directors = nil
+      end
+
+      def fetch card, opts={}
+        return directors[card] if directors[card]
+        directors.each_key do |dir_card|
+          return dir_card.director if dir_card.name == card.name
+        end
+        directors[card] = new_director card, opts
+      end
+
+      def new_director card, opts={}
+        if opts[:parent]
+          StageSubdirector.new card, opts
+        elsif act_card && act_card != card && running_act?
+          act_card.director.subdirectors.add card
+        else
+          StageDirector.new card
+        end
+      end
+
+      def add director
+        directors[director.card] = director
+      end
+
+      def card_changed old_card
+        return unless (director = @directors.delete old_card)
+        add director
+      end
+
+      def delete director
+        return unless @directors
+        @directors.delete director.card
+        director.delete
+      end
+
+      def deep_delete director
+        director.subdirectors.each do |subdir|
+          deep_delete subdir
+        end
+        delete director
+      end
+
+      def running_act?
+        (dir = act_director) && dir.running?
+      end
+
+      def to_s
+        directors.values.map(&:to_s).join "\n"
+      end
+    end
+  end
+end

data/lib/card/act_manager/stage.rb

@@ -0,0 +1,56 @@
+class Card
+  class ActManager
+    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 = 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
+end

data/lib/card/act_manager/stage_director.rb

@@ -0,0 +1,313 @@
+
+class Card
+  def restore_changes_information
+    return unless @previously_changed
+    @changed_attributes = ActiveSupport::HashWithIndifferentAccess.new
+    @previously_changed.each do |k, (old, _new)|
+      @changed_attributes[k] = old
+    end
+  end
+
+  def clean_after_stage_fail
+    @action = nil
+    expire_pieces
+    subcards.each(&:expire_pieces)
+  end
+
+  class ActManager
+    # 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, :transact_in_stage
+      attr_reader :running
+      alias_method :running?, :running
+      alias_method :main?, :main
+
+      def initialize card, opts={}, main=true
+        @card = card
+        @card.director = self
+        # for read actions there is no validation phase
+        # so we have to set the action here
+        @card.identify_action
+
+        @stage = nil
+        @running = false
+        @prepared = false
+        @parent = opts[:parent]
+        # has card to be stored before the supercard?
+        @prior_store = opts[:priority]
+        @call_after_store = []
+        @main = main
+        @subdirectors = SubdirectorArray.initialize_with_subcards(self)
+        register
+      end
+
+      def register
+        ActManager.add self
+      end
+
+      def unregister
+        ActManager.delete self
+      end
+
+      def delete
+        @card.director = nil
+        @subdirectors.clear
+        @stage = nil
+        @action = nil
+      end
+
+      def prepare_for_phases
+        @card.prepare_for_phases unless @prepared
+        @prepared = true
+        @subdirectors.each(&:prepare_for_phases)
+      end
+
+      def validation_phase
+        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
+
+      def storage_phase &block
+        catch_up_to_stage :prepare_to_store
+        run_single_stage :store, &block
+        run_single_stage :finalize
+      ensure
+        @from_trash = nil
+      end
+
+      def integration_phase
+        return if @abort
+        @card.restore_changes_information
+        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
+      ensure
+        @card.changes_applied unless @abort
+        ActManager.clear if main? && !@card.only_storage_phase
+      end
+
+      def catch_up_to_stage next_stage
+        if @transact_in_stage
+          return if @transact_in_stage != next_stage
+          next_stage = :integrate_with_delay
+        end
+        upto_stage(next_stage) do |stage|
+          run_single_stage stage
+        end
+      end
+
+      def reset_stage
+        @stage = -1
+      end
+
+      def abort
+        @abort = true
+      end
+
+      def call_after_store &block
+        @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
+          ActManager.act_director || (@parent && @parent.main_director)
+        end
+      end
+
+      def to_s
+        str = @card.name.to_s.clone
+        if @subdirectors
+          subs = subdirectors.map(&:card)
+                             .map { |card| "  #{card.name}" }.join "\n"
+          str << "\n#{subs}"
+        end
+        str
+      end
+
+      def update_card card
+        old_card = @card
+        @card = card
+        ActManager.card_changed old_card
+      end
+
+      private
+
+      def upto_stage stage
+        @stage ||= -1
+        (@stage + 1).upto(stage_index(stage)) do |i|
+          yield stage_symbol(i)
+        end
+      end
+
+      def valid_next_stage? stage
+        new_stage = stage_index(stage)
+        @stage ||= -1
+        return if @stage >= new_stage
+        if @stage < new_stage - 1
+          raise Card::Error, "stage #{stage_symbol(new_stage - 1)} was " \
+                             "skipped for card #{@card}"
+        end
+        @card.errors.empty? || new_stage > stage_index(:validate)
+      end
+
+      def run_single_stage stage, &block
+        return true unless valid_next_stage? stage
+        # puts "#{@card.name}: #{stage} stage".red
+
+        @stage = stage_index stage
+        if stage == :initialize
+          @running ||= true
+          prepare_for_phases
+        end
+        # 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
+        end
+      rescue => e
+        @card.clean_after_stage_fail
+        raise e
+      end
+
+      def run_stage_callbacks stage
+        Rails.logger.debug "#{stage}: #{@card.name}"
+        # 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 :finalize 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
+          trigger_storage_phase_callback
+        end
+      end
+
+      def store_with_subcards
+        store_pre_subcards
+        yield
+        @call_after_store.each { |handle_id| handle_id.call(@card.id) }
+        store_post_subcards
+        true.tap { @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_pre_subcards
+        @subdirectors.each do |subdir|
+          next unless subdir.prior_store
+          subdir.catch_up_to_stage :store
+        end
+      end
+
+      def store_post_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 trigger_storage_phase_callback
+        @stage = stage_index :prepare_to_store
+        @card.only_storage_phase = true
+        @card.save! validate: false
+      end
+    end
+
+    class StageSubdirector < StageDirector
+      def initialize card, opts={}
+        super card, opts, false
+      end
+
+      def delete
+        @parent.subdirectors.delete self if @parent
+        super
+      end
+    end
+  end
+end