card 1.104.2 → 1.105.1

data/lib/card/director/card_class.rb

@@ -3,16 +3,175 @@ class Card
     # director-related Card class methods
     module CardClass
       def create! opts
-        card = Card.new opts
+        card = new opts
         card.save!
         card
       end
 
       def create opts
-        card = Card.new opts
+        card = new opts
         card.save
         card
       end
+
+      # The ensure methods are use to make sure a card exists and can be used when you're
+      # unsure as to whether it already does. It's arguments are largely the same as
+      # those used by {#create Card#create} and {Director::All#update @card.update} with
+      # the important exception of `conflict`.
+      #
+      # The conflict argument takes one of three values:
+      #
+      #   - **defer**: let existing card stay as it is
+      #   - **default**: update existing card if it is "pristine" (meaning it has not
+      #     been edited by anyone other than Decko Bot)
+      #   - **override**: update existing card
+      #
+      # If the options specify a codename and the name is already in use, things get a
+      # little more involved. (Note: we MUST ensure that a card with the codename exists!)
+      #
+      # If the conflict setting is "**defer**":
+      #
+      #   - if the _codename_ is NOT already in use, we create a new card with an
+      #     altered name
+      #   - otherwise we do nothing.
+      #
+      # If the conflict setting is "**default**":
+      #
+      #    - if the _codename_ is NOT already in use:
+      #      - if the card using the name we want is pristine, we update that card
+      #      - otherwise we create a new card with an altered name
+      #    - if the _codename_ IS already in use
+      #      - if the card with the codename is pristine, we update everything but the
+      #        name (which is used by another card)
+      #      - otherwise we do nothing
+      #
+      # If the conflict setting is "**override**":
+      #
+      #    - if the _codename_ is NOT already in use, we update the existing card with the
+      #      name.
+      #    - otherwise we alter the card withe the conflicting name and update the card
+      #      with the codename.
+      def ensure opts
+        ensuring opts, &:save_if_needed
+      end
+
+      def ensure! opts
+        ensuring opts, &:save_if_needed!
+      end
+
+      private
+
+      def ensuring opts
+        opts.symbolize_keys!
+        with_conflict_mode opts.delete(:conflict) do
+          card, other = fetch_for_ensure opts
+          ensuring_purity(card, other, opts) do |ensured_card, attempt|
+            yield ensured_card if attempt
+            ensured_card
+          end
+        end
+      end
+
+      def with_conflict_mode mode
+        @conflict_mode = mode&.to_sym || :default
+        yield
+      ensure
+        Card::Director.clear
+        @conflict_mode = nil
+      end
+
+      def fetch_for_ensure opts
+        if opts[:codename] && opts[:name]
+          fetch_for_ensure_with_codename_and_name opts
+        elsif (mark = opts[:codename]&.to_sym || opts[:name])
+          [fetch_and_assign(mark, opts), nil]
+        else
+          raise Card::Error::ServerError, "Card.ensure must have name or codename"
+        end
+      end
+
+      def fetch_for_ensure_with_codename_and_name opts
+        codename = opts[:codename].to_sym
+        codename_id = id codename
+        name_id = id opts[:name]
+
+        other_card = name_id && (codename_id != name_id) ? name_id.card : nil
+        [fetch_and_assign(codename, opts), other_card]
+      end
+
+      def fetch_and_assign mark, opts
+        if id(mark) && (card = fetch mark)
+          card.tap { |c| c.assign_attributes opts }
+        else
+          new opts
+        end
+      end
+
+      def ensuring_purity card, other, opts, &block
+        if opts[:codename] && other
+          ensure_purity_advanced card, other, opts, &block
+        else
+          ensure_purity_simple card, &block
+        end
+      end
+
+      def ensure_purity_advanced card, other, opts
+        attempt_card = send "ensure_advanced_#{@conflict_mode}", card, other, opts
+        attempt_card ? yield(attempt_card, true) : yield(card, false)
+      end
+
+      def ensure_purity_simple card
+        attempt_save =
+          case @conflict_mode
+          when :override then true
+          when :default  then card.pristine?
+          when :defer    then card.new?
+          else
+            invalid_conflict_mode!
+          end
+        yield card, attempt_save
+      end
+
+      def ensure_advanced_defer card, other, _opts
+        return unless card.new? # codenamed card doesn't exist yet
+
+        card.name = other.name.alternative
+        card
+      end
+
+      def ensure_advanced_default card, other, opts
+        return unless card.pristine?
+
+        if card.new? && other.pristine?
+          other.assign_attributes opts
+          other
+        else
+          ensure_non_conflicting_name card
+        end
+      end
+
+      def ensure_advanced_override card, other, opts
+        if card.new?
+          other.assign_attributes opts
+          other
+        else
+          other.name = other.name.alternative
+          other.save
+          card.skip_event! :validate_renaming # so that type and content can also change
+          card
+        end
+      end
+
+      def ensure_non_conflicting_name card
+        card.name = card.new? ? card.name.alternative : card.name_before_act
+        card
+      end
+
+      # LOCALIZE
+      def invalid_conflict_mode!
+        raise Card::Error::ServerError, "invalid conflict mode: #{@conflict_mode}. " \
+                                        "Must be defer, default, or override"
+      end
     end
   end
 end

data/lib/card/director/{act_direction.rb → class_methods.rb}

@@ -1,6 +1,9 @@
 class Card
   class Director
-    module ActDirection
+    # Card::Director class methods
+    module ClassMethods
+      include EventDelay
+
       attr_accessor :act, :act_card
 
       def act_director
@@ -31,7 +34,6 @@ class Card
         directors.each_pair do |card, _dir|
           card.expire
           card.director = nil
-          card.action = nil
           card.clear_action_specific_attributes
         end
         expire
@@ -92,7 +94,8 @@ class Card
       def delete director
         return unless @directors
 
-        @directors.delete director.card
+        # normal delete was sometimes failing here (eg. when aborting in finalize stage)
+        @directors.delete_if { |k, _v| k == director.card }
         director.delete
       end
 
@@ -110,6 +113,13 @@ class Card
       def to_s
         act_director.to_s
       end
+
+      private
+
+      def delete_card card
+        card_key = @directors.keys.find { |key| key == card }
+        @directors.delete card_key if card_key
+      end
     end
   end
 end

data/lib/card/director/phases.rb

@@ -11,7 +11,7 @@ class Card
       end
 
       def integration_phase_callback?
-        !@only_storage_phase && main?
+        !@abort && !@only_storage_phase && main?
       end
 
       def prepare_for_phases
@@ -32,15 +32,17 @@ class Card
       # Unlike other phases, the storage phase takes a block,
       # because it is called by an "around" callback
       def storage_phase &block
-        catch_up_to_stage :prepare_to_store
-        run_stage :store, &block
-        run_stage :finalize
+        catch_up_to_stage :prepare_to_store # unless @abort
+        # puts "before store #{@card.name}: abort:#{@abort}"
+        run_stage :store, &block # unless @abort
+        run_stage :finalize # unless @abort
         raise ActiveRecord::RecordInvalid, @card if @card.errors.any?
       ensure
         @from_trash = nil
       end
 
       def integration_phase
+        # puts "integration phase: #{@card.name}"
         return if @abort
 
         @card.restore_changes_information
@@ -49,6 +51,7 @@ class Card
         run_stage :integrate_with_delay
       ensure
         @card.clear_changes_information unless @abort
+        @card.expire unless Cardio.delaying? # if delaying, then expired by clear
       end
     end
   end

data/lib/card/director/run.rb

@@ -13,7 +13,7 @@ class Card
       def run_delayed_event act
         @running = true
         @act = act
-        @stage = stage_index :integrate_with_delay
+        @current_stage_index = stage_index :integrate_with_delay
         yield
         run_subcard_stages :integrate_with_delay
       end
@@ -24,65 +24,33 @@ class Card
 
       def restart
         @running = false
-        @stage = nil
+        @current_stage_index = nil
       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? next_stage
-        @stage ||= -1
-        return false if in_or_after?(next_stage) || ahead_of_parent?(next_stage)
-        return false unless valid_card? next_stage
-
-        check_skipped_stage next_stage
-        true
-      end
-
-      def valid_card? next_stage
-        @card.errors.empty? || in_or_before?(:validate, next_stage)
-      end
-
-      def check_skipped_stage stage
-        return unless before? previous_stage_index(stage)
-
-        raise Card::Error, "stage #{previous_stage_symbol stage} was " \
-                           "skipped for card #{@card}"
-      end
-
-      def ahead_of_parent? next_stage
-        return false if head?
-
-        after? parent.stage, next_stage
-      end
-
       def run_stage stage, &block
         return true unless valid_next_stage? stage
 
         # puts "#{@card.name}: #{stage} stage".yellow
-        prepare_stage_run stage
-        execute_stage_run stage, &block
-      end
-
-      def prepare_stage_run stage
-        @stage = stage_index stage
-        prepare_for_phases if stage == :initialize
+        @current_stage_index = stage_index stage
+        handle_stage stage, block do
+          run_stage_callbacks stage
+          run_subcard_stages stage
+          run_final_stage_callbacks stage
+        end
       end
 
-      def execute_stage_run stage, &block
-        # in the store stage it can be necessary that
-        # other subcards must be saved before we save this card
-        return store(&block) if stage == :store
-
-        run_stage_callbacks stage
-        run_subcard_stages stage
-        run_final_stage_callbacks stage
+      def handle_stage stage, block
+        case stage
+        when :initialize
+          prepare_for_phases
+        when :store
+          # in the store stage it can be necessary that
+          # other subcards must be saved before we save this card
+          return store(&block)
+        end
+        yield
       end
 
       def run_stage_callbacks stage, callback_postfix=""
@@ -115,6 +83,39 @@ class Card
       def run_final_stage_callbacks stage
         run_stage_callbacks stage, "_final"
       end
+
+      def upto_stage stage
+        @current_stage_index ||= -1
+        (@current_stage_index + 1).upto(stage_index(stage)) do |i|
+          yield stage_symbol(i)
+        end
+      end
+
+      def valid_next_stage? next_stage
+        @current_stage_index ||= -1
+        return false if @abort ||
+                        in_or_after?(next_stage) ||
+                        ahead_of_parent?(next_stage) ||
+                        !valid_card?(next_stage)
+
+        check_skipped_stage next_stage
+        true
+      end
+
+      def valid_card? next_stage
+        @card.errors.empty? || in_or_before?(:validate, next_stage)
+      end
+
+      def check_skipped_stage stage
+        return unless before? previous_stage_index(stage)
+
+        raise Card::Error, "stage #{previous_stage_symbol stage} was " \
+                           "skipped for card #{@card}"
+      end
+
+      def ahead_of_parent? next_stage
+        head? ? false : after?(parent.current_stage_index, next_stage)
+      end
     end
   end
 end

data/lib/card/director/stages.rb

@@ -1,29 +1,31 @@
 class Card
   class Director
-    # Methods for intepreting stages of an action
+    # Methods for interpreting stages of an action
     module Stages
-      STAGES = %i[initialize prepare_to_validate validate
-                  prepare_to_store store finalize integrate
-                  after_integrate integrate_with_delay].freeze
-      STAGE_INDEX = STAGES.each_with_index.with_object({}) do |(stage, index), hash|
+      SYMBOLS = %i[initialize prepare_to_validate validate] +      # Validation phase
+                %i[prepare_to_store store finalize] +              # Storage phase
+                %i[integrate after_integrate integrate_with_delay] # Integration phase
+                .freeze
+
+      INDECES = SYMBOLS.each_with_index.with_object({}) do |(stage, index), hash|
         Card.define_callbacks "#{stage}_stage", "#{stage}_final_stage"
         hash[stage] = index
       end.freeze
 
       def stage_symbol index
-        case index
-        when Symbol
-          return index if STAGE_INDEX[index]
-        when Integer
-          return STAGES[index] if index < STAGES.size
+        if index.is_a?(Symbol) && INDECES[index]
+          index
+        elsif index.is_a?(Integer) && index < SYMBOLS.size
+          SYMBOLS[index]
+        else
+          raise Card::Error, "not a valid stage index: #{index}"
         end
-        raise Card::Error, "not a valid stage index: #{index}"
       end
 
       def stage_index stage
         case stage
         when Symbol
-          STAGE_INDEX[stage]
+          INDECES[stage]
         when Integer
           stage
         when nil
@@ -41,17 +43,17 @@ class Card
       end
 
       def finished_stage? stage
-        @stage > stage_index(stage)
+        @current_stage_index > stage_index(stage)
       end
 
       def reset_stage
-        @stage = -1
+        @current_stage_index = -1
       end
 
       private
 
       def previous_stage_index from_stage=nil
-        from_stage ||= @stage
+        from_stage ||= @current_stage_index
         stage_index(from_stage) - 1
       end
 
@@ -80,7 +82,7 @@ class Card
       end
 
       def stage_test reference_stage, test_stage=nil
-        test_stage ||= @stage
+        test_stage ||= @current_stage_index
         yield stage_index(reference_stage), stage_index(test_stage)
       end
     end

data/lib/card/director/store.rb

@@ -63,7 +63,7 @@ class Card
       # 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
+        @current_stage_index = stage_index :prepare_to_store
         @only_storage_phase = true
         @card.save! validate: false, as_subcard: true
       end

data/lib/card/director.rb

@@ -100,7 +100,7 @@ class Card
   # self/bar.rb
   #
   #     event :met_a_foo_at_the_bar, :prepare_to_store, on: :update do
-  #       add_subcard "foo"
+  #       subcard "foo"
   #     end
   #
   # And then you run `Card[:bar].update!({})`.
@@ -133,15 +133,14 @@ class Card
   #
   # ---
   class Director
-    extend EventDelay
-    extend ActDirection
+    extend ClassMethods
 
     include Stages
     include Phases
     include Run
     include Store
 
-    attr_accessor :act, :card, :stage, :parent, :subdirectors, :head
+    attr_accessor :act, :card, :current_stage_index, :parent, :subdirectors, :head
     attr_reader :running
     alias_method :running?, :running
 
@@ -150,7 +149,7 @@ class Card
       @card.director = self
       # for read actions there is no validation phase
       # so we have to set the action here
-      @stage = nil
+      @current_stage_index = nil
       @running = false
       @prepared = false
       @parent = parent
@@ -178,7 +177,7 @@ class Card
       @parent&.subdirectors&.delete self
       @card.director = nil
       @subdirectors.clear
-      @stage = nil
+      @current_stage_index = nil
       @action = nil
       @running = false
     end
@@ -220,7 +219,7 @@ class Card
       card.director = self
       @card = card
       reset_stage
-      catch_up_to_stage @stage if @stage
+      catch_up_to_stage @current_stage_index if @current_stage_index
     end
 
     def update_card card

data/lib/card/env/location.rb

@@ -34,7 +34,7 @@ class Card
       private
 
       def cardname_from_url_regexp
-        return unless Env.origin
+        return unless Env.origin.present?
 
         %r{#{Regexp.escape Env.origin}/(?<mark>[^?]+)}
       end

data/lib/card/env/serializable.rb

@@ -3,6 +3,8 @@ class Card
     # These methods are all handled in serialization and are thus preserved for the
     # integrate_with_delay phase
     module Serializable
+      attr_reader :main_name, :params
+
       def ip
         request&.remote_ip
       end

data/lib/card/env/serialization.rb

@@ -11,11 +11,10 @@ class Card
       # @param serialized_env [Hash]
       def with serialized_env
         tmp_env = serialize
-        @env ||= {}
-        @env.update serialized_env
+        @serialized.update serialized_env
         yield
       ensure
-        @env.update tmp_env if tmp_env
+        @serialized.update tmp_env if tmp_env
       end
 
       # supercede serializable methods when serialized values are available

data/lib/card/env.rb

@@ -11,8 +11,8 @@ class Card
     extend Serialization
 
     class << self
-      attr_accessor :controller, :main_name, :params
-      attr_writer :session
+      attr_accessor :controller
+      attr_writer :session, :main_name, :params
 
       def request
         controller&.request

data/lib/card/error.rb

@@ -1,5 +1,14 @@
 # -*- encoding : utf-8 -*-
 
+class StandardError
+  MAX_BACKTRACE_LINES = 20
+
+  def report
+    Rails.logger.info "exception = #{self.class}: #{message}"
+    Rails.logger.debug backtrace[0..MAX_BACKTRACE_LINES].join("\n")
+  end
+end
+
 class Card
   # exceptions and errors.
   # (arguably most of these should be Card::Exception)
@@ -29,11 +38,6 @@ class Card
       @backtrace || super
     end
 
-    def report
-      Rails.logger.info "exception = #{self.class}: #{message}"
-      Rails.logger.debug backtrace.join("\n")
-    end
-
     def card_message_text
       card.errors.first&.message
     end

data/lib/card/fetch/card_class.rb

@@ -1,29 +1,32 @@
 class Card
   class Fetch
-    # = Card#fetch
-    #
-    # A multipurpose retrieval operator that integrates caching, database lookups,
+    # A multipurpose retrieval system that integrates caching, database lookups,
     # and "virtual" card construction
     module CardClass
       # Look for cards in
-      # * cache
-      # * database
-      # * virtual cards
+      #   * cache
+      #   * database
+      #   * virtual cards
       #
       # @param args [Integer, String, Card::Name, Symbol, Array]
       #    Initials args must be one or more "marks," which uniquely idenfify cards:
+      #
+      #
       #      1. a name/key. (String or Card::Name)
       #      2. a numeric id. Can be (a) an Integer or (b) a String with an integer
       #         prefixed with a tilde, eg "~1234"
       #      3. a codename. Can be (a) a Symbol or (b) a String with a colon prefix,
       #         eg :mycodename
+      #
       #    If you pass more then one mark or an array of marks they get joined with a '+'.
       #    The final argument can be a Hash to set the following options
-      #      :skip_virtual               Real cards only
-      #      :skip_modules               Don't load Set modules
-      #      :look_in_trash              Return trashed card objects
-      #      :local_only                 Use only local cache for lookup and storing
-      #      new: { opts for Card#new }  Return a new card when not found
+      #
+      #        :skip_virtual               Real cards only
+      #        :skip_modules               Don't load Set modules
+      #        :look_in_trash              Return trashed card objects
+      #        :local_only                 Use only local cache for lookup and storing
+      #        new: { opts for Card#new }  Return a new card when not found
+      #
       # @return [Card]
       def fetch *args
         f = Fetch.new(*args)
@@ -32,9 +35,9 @@ class Card
         Card.new name: "card id out of range: #{f.mark}"
       end
 
-      # fetch only real (no virtual) cards
+      # a shortcut for fetch that returns only real cards (no virtuals)
       #
-      # @param mark - see #fetch
+      # @param mark [various] - see {#fetch}
       # @return [Card]
       def [] *mark
         fetch(*mark, skip_virtual: true)
@@ -62,6 +65,9 @@ class Card
       # ATTRIBUTE FETCHING
       # The following methods optimize fetching of specific attributes
 
+      # numerical card id
+      # @params cardish [various] interprets integers as id, symbols as codename, etc
+      # @return [Integer]
       def id cardish
         case cardish
         when Integer then cardish