card 1.92.2 → 1.93.0

data/db/migrate_core_cards/data/cards/*header

@@ -1,4 +1,4 @@
-<div class="navbar navbar-inverse bg-primary navbar-toggleable-md navbar-static-top mb-3">
+<div class="navbar navbar-inverse bg-primary navbar-expand-md navbar-static-top mb-3">
     <button class="navbar-toggler navbar-toggler-right" type="button" data-toggle="collapse" data-target="#navbar-collapse-1" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
       <span class="navbar-toggler-icon"></span>
     </button>

data/lib/card.rb

@@ -2,7 +2,7 @@
 require "carrierwave"
 
 Object.const_remove_if_defined :Card
-#ActiveSupport::Dependencies.loaded.clear
+# ActiveSupport::Dependencies.loaded.clear
 
 # Cards are wiki-inspired building blocks.
 #
@@ -15,24 +15,48 @@ Object.const_remove_if_defined :Card
 #
 # Throughout this document we will refer to @card as an instance of a Card object.
 #
-# ##Names
+# ## Names
 #
 # There are four important card identifiers, sometimes called "marks".  Every card has a unique _name_, _key_, and _id_. Some cards also have a _codename_.
 #
-#       @card.name     # The name, a String, is the most recognizable card mark.
+#       @card.name     # The name, a {Card::Name} object, is the most recognizable card mark.
 #       @card.key      # The key, a String, is a simple lower-case name variant.
 #       @card.id       # The id is an Integer.
 #       @card.codename # The codename, a Symbol, is the name by which a card can be referred to in code.
 #
-# All names with the same key (including the key itself) are considered variants of each other. No two cards can have names with the same key.
+# All names with the same key (including the key itself) are considered variants of each other. No two cards can have names with the same key. Card::Name objects inherit from Strings but add many other methods for common card name patterns, eg `"A+B".to_name.right => "B"`.
 #
-# `@card.cardname` refers to the same name as ``@card.name``, but it is a {Card::Name} object and has many additional methods.
+# Setting a card's name, eg `@card.name = "New Name"`, will automatically update the key.  {Card::Name More on names.}
 #
-# {Card::Codename More about codenames.}
+# {Card::Codename More on codenames.}
 #
-# ## Fetching
+# ## Type
+#
+# Every card has a type, and every type itself has an associated card. For example, _Paula_'s type might be _User_, so there is also a _User_ card.
+#
+# The type may be accessed in several ways:
+#
+#       @card.type_id      # returns id of type card [Integer]
+#       @card.type_name    # returns name of type card [Card::Name]
+#       @card.type_code    # returns codename of type card [Symbol]
+#       @card.type_card    # returns Cardtype card associated with @card's type [Card]
+#
+# {file:mod/core/set/all/type.rb Common type methods}
+#
+# ## Content
+#
+# There are two primary methods for accessing a card's content:
+#
+#       @card.db_content   # the content as it appears in the database
+#       @card.content      # the "official" content, which may be different from db_content when db_content is overridden with a structure rule.
+#
+# {Card::Content Processing card content}
 #
-# The two main ways to retrieve cards are fetching (retrieving cards one at a time) and querying (retrieving lists of cards).
+# {file:mod/core/set/all/content.rb Common content methods}
+#
+# ## Fetch
+#
+# The two main ways to retrieve cards are fetching (retrieving cards one at a time) and querying (retrieving lists of cards). More on querying below.
 #
 # Any of the above marks (name, key, id, codename) can be used to fetch a card, eg:
 #
@@ -42,42 +66,36 @@ Object.const_remove_if_defined :Card
 #
 # The fetch API will first try to find the card in the cache and will only look in the database if necessary.
 #
-# {file:mod/core/set/all/fetch.rb More about fetching}
+# {file:mod/core/set/all/fetch.rb More on fetching.}
 #
-# ## Type
+# ## Query
 #
-# Every card has a type, and every type itself has an associated card. For example, _Paula_'s type might be _User_, so there is also a _User_ card.
+# Card queries find and return lists of cards, eg:
 #
-# The type may be accessed in several ways:
+#       Card.search type_id: 4 # returns an Array of cards with the type_id of 4.
 #
-#       @card.type_card    # returns type card [Card]
-#       @card.type_id      # returns id of type card [Integer]
-#       @card.type_name    # returns name of type card [String]
-#       @card.type_code    # returns codename of type card [Symbol]
+# {Card::Query More on queries}
 #
-# {file:mod/core/set/all/type.rb set module with type methods}
+# ## Views and Events
 #
-# ## Content
-# chunks
+# Views and events are a _Decker's_ primary tools for manipulating cards. Views customize card presentation, while events customize card transactions. Or, if you like, views and events respectively alter cards in _space_ and _time_.
 #
-# ## Query
-# reference, query
+# Both views and events are defined in {Card::Mod mods}, short for modules or modifications.
 #
-# ## Accounts
-# permission
+# {Card::Format More on views}
 #
+# {Card::Set::Act More on events}
 #
-# ## History
-# acts, actions, changes
-# subcards, act_manager
+# ## Accounts and Permissions
 #
-# ## Events
-# mailer
+# Card code is always executed in the context of a given user account. Permissions for that account are automatically checked when running a query, performing an action, or rendering a view.  A typical query, for example, can only return cards that the current user has permission to read.
+#
+# You can see the current user with `Card::Auth.current`. The permissions of a proxy user can be temporarily assumed using `Card::Auth#as`.
+#
+# {Card::Auth More on accounts}
 #
-# ## Caching
-
 class Card < ApplicationRecord
-  require_dependency "active_record/connection_adapters_ext"
+  require_dependency "card/name"
   require_dependency "card/codename"
   require_dependency "card/query"
   require_dependency "card/format"
@@ -92,6 +110,7 @@ class Card < ApplicationRecord
   require_dependency "card/subcards"
   require_dependency "card/view"
   require_dependency "card/act_manager"
+  require_dependency "card/dirty"
 
   has_many :references_in,  class_name: :Reference, foreign_key: :referee_id
   has_many :references_out, class_name: :Reference, foreign_key: :referer_id
@@ -100,7 +119,7 @@ class Card < ApplicationRecord
   has_many :drafts, -> { where(draft: true).order :id }, class_name: :Action
 
   cattr_accessor :set_patterns, :serializable_attributes, :error_codes,
-                 :set_specific_attributes, :current_act
+                 :set_specific_attributes
   self.set_patterns = []
   self.error_codes = {}
 
@@ -112,7 +131,7 @@ class Card < ApplicationRecord
 
   serializable_attr_accessor(
     :action, :supercard, :superleft,
-    :current_act, :current_action,
+    :current_action,
     :comment,                     # obviated soon
     :update_referers,             # wrong mechanism for this
     :update_all_users,            # if the above is wrong then this one too
@@ -153,7 +172,7 @@ class Card < ApplicationRecord
   before_validation :validation_phase, unless: -> { only_storage_phase? }
   around_save :storage_phase
   after_commit :integration_phase, unless: -> { only_storage_phase? }
-  after_rollback :clean_up, unless: -> { only_storage_phase? }
+#  after_rollback :clean_up, unless: -> { only_storage_phase? }
 
   extend CarrierWave::Mount
   ActiveSupport.run_load_hooks(:card, self)

data/lib/card/act_manager.rb

@@ -34,17 +34,17 @@ class Card
   #                                  validation    |    storage    | integration
   #                                 I    P2V  V    |  P2S  S    F  | IG   IGwD
   #-------------------------------------------------------------------------
-  #    attach subcard               yes! yes! yes  | yes  yes  yes |    yes
+  #    attach subcard               yes! yes! yes  | yes  yes  yes | yes  no
   #    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!
+  # 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
+  # 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
+  # 4) within transaction                yes       |      yes      |    no
 
   #    available values:
   #    dirty attributes                  yes       |      yes      |    yes
@@ -66,15 +66,18 @@ class Card
   # 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
+  # 3) In all stages except IGwD:
+  #    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
+  #    executed together with the act card and its subcards.
+  #
+  #    In IGwD all these methods create a new act.
   # 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
+    cattr_accessor :act, :act_card
 
     class << self
       def act_director
@@ -86,8 +89,20 @@ class Card
         @directors ||= {}
       end
 
+      def run_act card
+        self.act_card = card
+        yield
+      ensure
+        clear
+      end
+
+      def need_act
+        self.act ||= Card::Act.create ip_address: Env.ip
+      end
+
       def clear
-        ActManager.act_card = nil
+        self.act_card = nil
+        self.act = nil
         directors.each_pair do |card, _dir|
           card.director = nil
         end
@@ -97,7 +112,7 @@ class Card
       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
+          return dir_card.director if dir_card.name == card.name && dir_card.director
         end
         directors[card] = new_director card, opts
       end
@@ -143,6 +158,45 @@ class Card
         (dir = act_director) && dir.running?
       end
 
+      # If active jobs (and hence the integrate_with_delay events) don't run
+      # in a background process then Card::Env.deserialize! decouples the
+      # controller's params hash and the Card::Env's params hash with the
+      # effect that params changes in the CardController get lost
+      # (a crucial example are success params that are processed in
+      # CardController#update_params_for_success)
+      def contextualize_delayed_event act_id, card, env, auth
+        if delaying?
+          contextualize_for_delay(act_id, card, env, auth) { yield }
+        else
+          yield
+        end
+      end
+
+      def delaying?
+        Delayed::Worker.delay_jobs && Card.config.active_job.queue_adapter == :delayed_job
+      end
+
+      # The whole ActManager setup is gone once we reach a integrate with delay
+      # event processed by ActiveJob.
+      # This is the improvised resetup to get subcards working.
+      def contextualize_for_delay act_id, card, env, auth, &block
+        self.act = Act.find act_id if act_id
+        with_env_and_auth env, auth do
+          return yield unless act
+          run_act(act.card || card) do
+            act_card.director.run_delayed_event act, &block
+          end
+        end
+      end
+
+      def with_env_and_auth env, auth
+        Card::Auth.with auth do
+          Card::Env.with env do
+            yield
+          end
+        end
+      end
+
       def to_s
         act_director.to_s
         #directors.values.map(&:to_s).join "\n"

data/lib/card/act_manager/stage_director.rb

@@ -102,6 +102,14 @@ class Card
         end
       end
 
+      def run_delayed_event act
+        @running = true
+        @act = act
+        @stage = stage_index(:integrate_with_delay)
+        yield
+        run_subdirector_stages :integrate_with_delay
+      end
+
       def reset_stage
         @stage = -1
       end
@@ -119,8 +127,7 @@ class Card
         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
+        @act = act_director.act ||= ActManager.need_act
       end
 
       def main_director
@@ -146,6 +153,10 @@ class Card
         ActManager.card_changed old_card
       end
 
+      def finished_stage? stage
+        @stage > stage_index(stage)
+      end
+
       private
 
       def upto_stage stage

data/lib/card/act_manager/stage_director/phases.rb

@@ -26,13 +26,15 @@ class Card
           run_single_stage :integrate_with_delay
         rescue => e # don't rollback
           Card::Error.current = e
-          warn "exception in integrate stage: #{e.message}"
-          warn e.backtrace.join "\n"
-          @card.notable_exception_raised
+          unless e.class == Card::Error::Abort
+            warn "exception in integrate phase: #{e.message}"
+            warn e.backtrace.join "\n"
+            @card.notable_exception_raised
+          end
           return false
         ensure
           @card.clear_changes_information unless @abort
-          ActManager.clear if main? && !@card.only_storage_phase
+          # ActManager.clear if main? && !@card.only_storage_phase
         end
       end
     end

data/lib/card/auth.rb

@@ -4,7 +4,9 @@ require_dependency "card/auth/proxy"
 require_dependency "card/auth/setup"
 
 class Card
-  # Singleton methods for authentication. Manages current user,
+  # Singleton methods for account authentication and contextualization.
+  #
+  # Manages current user,
   # "as" user, and password verification.
   module Auth
     extend Permissions

data/lib/card/cache.rb

@@ -28,7 +28,7 @@ class Card
     end
   end
 
-  # The {Cache} class manages and integrates {Temporary} and {Persistent
+  # The {Cache} class manages and integrates {Temporary} and {Persistent}
   # caching. The {Temporary} cache is typically process- and request- specific
   # and is often "ahead" of the database; the {Persistent} cache is typically
   # shared across processes and tends to stay true to the database.
@@ -60,7 +60,6 @@ class Card
                                       store: cache_type
       end
 
-      # establish clean context;
       # clear the temporary caches and ensure we're using the latest stamp
       # on the persistent caches.
       def renew
@@ -70,6 +69,12 @@ class Card
         end
       end
 
+      # reset standard cached for all classes
+      def reset
+        reset_hard
+        reset_soft
+      end
+
       # reset all caches for all classes
       def reset_all
         reset_hard
@@ -91,6 +96,7 @@ class Card
 
       # reset the Persistent cache for all classes
       def reset_hard
+        Card::Cache::Persistent.reset
         cache_by_class.each_value do |cache|
           cache.hard.reset if cache.hard
         end

data/lib/card/cache/persistent.rb

@@ -20,12 +20,30 @@ class Card
       class << self
         # name of current database; used here to insure that different databases
         # are cached separately
-        # @todo find better home for this method
+        # TODO: find better home for this method
         def database_name
           @database_name ||= (cfg = Cardio.config) &&
                              (dbcfg = cfg.database_configuration) &&
                              dbcfg[Rails.env]["database"]
         end
+
+        def stamp
+          @stamp ||= Cardio.cache.fetch(stamp_key) { new_stamp }
+        end
+
+        # stamp generator
+        def new_stamp
+          Time.now.to_i.to_s(36) + rand(999).to_s(36)
+        end
+
+        def stamp_key
+          "#{database_name}-stamp"
+        end
+
+        def reset
+          @stamp = new_stamp
+          Cardio.cache.write stamp_key, @stamp
+        end
       end
 
       # @param opts [Hash]
@@ -48,7 +66,7 @@ class Card
 
       # reset effectively clears the cache by setting a new stamp
       def reset
-        @stamp = new_stamp
+        @stamp = self.class.new_stamp
         @prefix = nil
         Cardio.cache.write stamp_key, @stamp
       end
@@ -63,22 +81,17 @@ class Card
       # the cache. Note that Cardio.cache is a simple Rails::Cache, not
       # a Card::Cache object.
       def stamp
-        @stamp ||= Cardio.cache.fetch(stamp_key) { new_stamp }
+        @stamp ||= Cardio.cache.fetch(stamp_key) { self.class.new_stamp }
       end
 
       # key for looking up the current stamp
       def stamp_key
-        "#{@database}/#{@class_key}/stamp"
-      end
-
-      # stamp generator
-      def new_stamp
-        Time.now.to_i.to_s(32) + rand(9999).to_s(32)
+        "#{@database}-#{@class_key}-#{self.class.stamp}-stamp"
       end
 
       # prefix added to cache key to create a system-wide unique key
       def prefix
-        @prefix ||= "#{@database}/#{@class_key}/#{stamp}"
+        @prefix ||= "#{@database}-#{@class_key}-#{stamp}:"
       end
 
       # returns prefix/key