card 1.97.0.1 → 1.98.0

data/lib/card/view.rb

@@ -1,31 +1,60 @@
-require_dependency "card/view/visibility"
 require_dependency "card/view/cache"
-require_dependency "card/view/stub"
 require_dependency "card/view/options"
 require_dependency "card/view/classy"
+require_dependency "card/view/permission"
 
 class Card
+  # Card::View manages {Options view options}, {Cache view caching}, and
+  # {Permission view permissions}.
+  #
+  # View objects, which are instantiated whenever a view is rendered, are available as
+  # in views and other format methods.  The view objects can be accessed using `#voo`.
+  # We sometimes feebly pretend VOO is an acronym for "view option object," but really
+  # we just needed a way not to confuse these Card::View options with the countless
+  # references to viewnames that naturally arise when rendering views within views within
+  # views.
+  #
+  # When view A renders view B within the same format object, A's voo is the parent of
+  # B's voo. When card C nests card D, a new (sub)format object is initialized. C is then
+  # the parent _format_ of D, but D has its own root voo.
+  #
+  # So a lineage might look something like this:
+  #
+  # `F1V1 -> F1V2 -> F1V3 -> F2V1 -> F2V2 -> F3V1 ...`
+  #
+  #
   class View
-    # Card::View handles view rendering and caching.
-
-    include Visibility
-    include Cache
-    include Stub
     include Options
-    # include Layout
-    # include Wrapper
+    include Cache
     include Classy
+    include Permission
+
     extend Cache::ClassMethods
 
     attr_reader :format, :parent, :card
 
-    # @return [Symbol]
-    def self.canonicalize view
-      view.present? ? view.to_sym : nil # error for no view?
+    class << self
+      # @return [Symbol] viewname as Symbol
+      def normalize view
+        view.present? ? view.to_sym : nil
+      end
+
+      # @return [Array] list of viewnames as Symbols
+      def normalize_list val
+        case val
+        when NilClass then []
+        when Array    then val
+        when String   then val.split(/[\s,]+/)
+        when Symbol   then [val]
+        else raise Card::Error, "bad show/hide argument: #{val}"
+        end
+      end
     end
 
     # @param format [Card::Format]
-    # @param view [Symbol]
+    # @param view [Symbol] viewname. Note: Card::View is initialized without a view
+    #   when `voo` is called outside of a render,
+    #   eg `subformat(cardname).method_with_voo_reference`.
     # @param raw_options [Hash]
     # @param parent [Card::View] (optional)
     def initialize format, view, raw_options={}, parent=nil
@@ -41,8 +70,7 @@ class Card
     # handle rendering, including optional visibility, permissions, and caching
     # @return [rendered view or a stub]
     def process
-      process_live_options
-      return if optional? && hide?(requested_view)
+      return if process_live_options == :hide
 
       fetch { yield ok_view }
     end
@@ -51,15 +79,14 @@ class Card
     # be overridden, eg for the main view (top view of the main card on a page)
     # @return [Symbol] view name
     def requested_view
-      @requested_view ||= View.canonicalize live_options[:view]
+      @requested_view ||= View.normalize live_options[:view]
     end
 
     # the final view.  can be different from @requested_view when there are
     # issues with permissions, recursions, unknown cards, etc.
     # @return [Symbol] view name
     def ok_view
-      @ok_view ||= format.ok_view requested_view,
-                                  normalized_options[:skip_perms]
+      @ok_view ||= format.monitor_depth { altered_view || requested_view }
     end
 
     # @return [Card::View]
@@ -72,6 +99,7 @@ class Card
       !parent
     end
 
+    # the root voo of the root format
     def deep_root
       format.root.voo
     end
@@ -84,10 +112,11 @@ class Card
 
     # next voo object found tracing ancestry through parent voos and/or parent formats
     # @return [Card::View]
-    def next_ancestor accross_format=true
-      parent || (accross_format && next_format_ancestor) || nil
+    def next_ancestor across_format=true
+      parent || (across_format && next_format_ancestor) || nil
     end
 
+    # voo object of format's parent
     def next_format_ancestor
       format.parent&.voo
     end

data/lib/card/view/cache.rb

@@ -1,14 +1,178 @@
-require_dependency "card/view/cache_action"
-
 class Card
   class View
-    include CacheAction
-
+    # View::Cache supports smart card view caching.
+    #
+    # The basic idea is that when view caching is turned on (via `config.view_cache`),
+    # we try to cache a view whenever it's "safe" to do so. We will include everything
+    # inside that view (including other views) until we find something that isn't safe.
+    # When something isn't safe, we render a {Stub stub}: a placeholder
+    # with all the info we need to come back and replace it with the correct content
+    # later. In this way it is possible to have many levels of cached views within
+    # cached views.
+    #
+    # Here are some things that we never consider safe to cache:
+    #
+    # 1. a view explicitly configured _never_ to be cached
+    # 2. a view of a card with view-relevant permission restrictions
+    # 3. a view other than the requested view (eg a denial view)
+    # 4. a card with unsaved content changes
+    #
+    # We also consider it unsafe to cache a view of one card within a view of a different
+    # card, so nests are always handled with a stub.
+    #
+    # ## Cache configuration
+    #
+    # Cache settings (#5) can be configured in the
+    # {Set::Format::AbstractFormat#view view definition}
+    # and (less commonly) as a {Card::View::Options view option}.
+    #
+    # By far, the most common explicit caching configuration is `:never`. This setting
+    # is used to prevent over-caching, which becomes problematic when data changes
+    # do not clear the cache.
+    #
+    # Generally speaking, a card is smart about clearing its own view caches when
+    # anything about the card itself. So when I update the card "Johnny", all the cached
+    # views of "Johnny" are cleared. Similarly, changes to structure rules and other
+    # basic patterns are typically well managed by the caching system.
+    #
+    # However, there are many other potential changes that views cannot detect. Views that
+    # are susceptible to these "cache hazards" should be configured with `cache: :never`.
+    #
+    # ## Cache hazards
+    #
+    # If a view contains any of the following cache hazards, it would be wise to consider
+    # a `cache: :never` configuration:
+    #
+    # - dynamic searches (eg `Card.search`) whose results may change
+    # - live timestamps (eg `Time.now`)
+    # - environmental variables (eg `Env.params`)
+    # - any variables altered in one view and used in another (eg `@myvar`)
+    # - other cards' properties (eg `Card["random"].content`)
+    #
+    # What all of the above have in common is that they involve changes about which the
+    # view caching system is unaware. This means that whether the cache hazard is
+    # rendered directly in a view or just used in its logic, it can change in a way
+    # that _should_ change the view but _won't_ change the view if it's cached.
+    #
+    # ## Altering cached views
+    #
+    # Whereas ignoring cache hazards may cause over-caching, altering cached views
+    # may cause outright errors. If a view directly alters a rendered view,
+    # it may be dangerous to cache.
+    #
+    #        # obviously safe to cache
+    #        view(:x) { "ABC" }
+    #
+    #        # also safe, because x is NOT altered
+    #        view(:y) { render_x + "DEF" }
+    #
+    #        # unsafe and thus never cached, because x is altered
+    #        view(:z, cache: :never) { render_x.reverse }
+    #
+    # Specifically, the danger is that the inner view will be rendered as a stub,
+    # and the out view will end up altering the stub and not the view.
+    #
+    # Although alterations should be considered dangerous, they are actually only
+    # problematic in situations where the inner view might sometimes render a stub.
+    # If the outer view is rendering a view of the _same card_ with all the _same view
+    # settings_ (perms, unknown, etc), there will be no stub and thus no error.
+    # Remember, however, that a view on a narrow set may inherit view settings
+    # from a general set. To be confident that a view alteration is safe, all inherited
+    # settings must be taken into account.
+    #
+    # ## Caching Best Practices
+    #
+    # Here are some good rules of thumb to make good use of view caching:
+    #
+    # 1. *Use nests.* If you can show the content of a different card with a nest rather
+    #    than by showing the content directly, the caching system will be much
+    #    happier with you.
+    #
+    #        view :bad_idea, cache: :never do
+    #          Card["random"].content
+    #        end
+    #
+    #        view :good_idea do
+    #          nest :random, view: :core
+    #        end
+    #
+    # 2. *Isolate the cache hazards.*  Consider the following variants:
+    #
+    #        view :bad_idea, cache: :never do
+    #          if morning_for_user?
+    #            expensive_good_morning
+    #          else
+    #            expensive_good_afternoon
+    #          end
+    #        end
+    #
+    #        view :good_idea, cache: :never do
+    #          morning_for_user? ? render_good_morning : render_good_afternoon
+    #        end
+    #
+    #     In the first example, we have to generate expensive greetings every time we
+    #     render the view.  In the second, only the test is not cached.
+    #
+    # 3. If you must alter view results, consider *generating the view content
+    #    in a separate method.*
+    #
+    #        # First Attempt
+    #
+    #        view :hash_it_in do
+    #          { cool: false }
+    #        end
+    #
+    #        view :bad_idea, cache: :never do
+    #          render_badhash.merge sucks: true
+    #        end
+    #
+    #
+    #        #Second Attempt
+    #
+    #        view :hash_it_out do
+    #          hash_it_out
+    #        end
+    #
+    #        def hash_it_out
+    #          { cool: true }
+    #        end
+    #
+    #        view :good_idea do
+    #          hash_it_out.merge rocks: true
+    #        end
+    #
+    #     The first attempt will work fine with caching off but is risky with caching on.
+    #     The second is safe with caching on.
+    #
+    # ## Optimizing with `:always`
+    #
+    # It is never strictly necessary to use `cache: :always`, but this setting can help
+    # optimize your use of the caching system in some cases.
+    #
+    # Consider the following views:
+    #
+    #        view(:hat) { "hat" } # ...but imagine this is computationally expensive
+    #
+    #        view(:old_hat)  { "old #{render_hat}"  }
+    #        view(:new_hat)  { "new #{render_hat}"  }
+    #        view(:red_hat)  { "red #{render_hat}"  }
+    #        view(:blue_hat) { "blue #{render_hat}" }
+    #
+    # Whether "hat" uses `:standard` or `:always`, the hat varieties (old, new, etc...)
+    # will fully contain the rendered hat view in their cache. However, with `:standard`,
+    # the other views will each re-render hat without attempting to cache it separately
+    # or to find it in the cache.  This could lead to man expensive renderings of the
+    # "hat" view.  By contrast, if the cache setting is `:always`, then hat will be
+    # cached and retrieved even when it's rendered inside another cached view.
+    #
     module Cache
-      # Support context-aware card view caching.
-      #
+      include CacheAction
+      include Stub
+
+      private
+
       # render or retrieve view (or stub) with current options
-      # @params &block [Block] render block
+      # @param block [Block] code block to render
       # @return [rendered view or stub]
       def fetch &block
         case cache_action
@@ -64,10 +228,14 @@ class Card
 
       def cache_key
         @cache_key ||= [
-          card.key, format.class, format.nest_mode, options_for_cache_key
+          card_cache_key, format.class, format.nest_mode, options_for_cache_key
         ].map(&:to_s).join "-"
       end
 
+      def card_cache_key
+        card.real? ? card.id : "#{card.key}-#{card.type_id}"
+      end
+
       # Registers the cached view for later clearing in the event of related card changes
       def register_cache_key
         card.register_view_cache_key cache_key

data/lib/card/view/cache/cache_action.rb

@@ -0,0 +1,124 @@
+class Card
+  class View
+    module Cache
+      # determine action to be used in #fetch
+      module CacheAction
+        private
+
+        # course of action based on config/status/options
+        # @return [Symbol] :yield, :cache_yield, or
+        def cache_action
+          log_cache_action do
+            send "#{cache_status}_cache_action"
+          end
+        end
+
+        def log_cache_action
+          action = yield
+          # TODO: make configurable
+          # ...or better yet, integrate into performance logger...
+          # Rails.logger.warn "VIEW CACHE #{cache_active? ? '-->' : ''}[#{action}] "\
+          #                   "(#{card.name}##{requested_view})"
+          action
+        end
+
+        # @return [Symbol] :off, :active, or :free
+        def cache_status
+          case
+          when !cache_on?
+            :off      # view caching is turned off, format- or system-wide
+          when cache_active?
+            :active   # another view cache is in progress (current view is inside it)
+          else
+            :free     # no other cache in progress
+          end
+        end
+
+        # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+        # CACHE STATUS: OFF
+        # view caching is turned off, format- or system-wide
+
+        # @return [True/False]
+        def cache_on?
+          Card.config.view_cache && format.class.view_caching?
+        end
+
+        # always skip all the magic
+        def off_cache_action
+          :yield
+        end
+
+        # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+        # CACHE STATUS: FREE
+        # caching is on; no other cache in progress
+
+        # @return [Symbol]
+        def free_cache_action
+          free_cache_ok? ? :cache_yield : :yield
+        end
+
+        # @return [True/False]
+        def free_cache_ok?
+          cache_setting != :never && clean_enough_to_cache?
+        end
+
+        # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+        # CACHE STATUS: ACTIVE
+        # another view cache is in progress; this view is inside it
+
+        # @return [Symbol]
+        def active_cache_action
+          active_cache_ok? ? active_cache_action_from_setting : :stub
+        end
+
+        # @return [True/False]
+        def active_cache_ok?
+          return false unless parent && clean_enough_to_cache?
+          return true if normalized_options[:skip_perms]
+
+          active_cache_permissible?
+        end
+
+        # apply any permission checks required by view.
+        # (do not cache views with nuanced permissions)
+        def active_cache_permissible?
+          case view_perms
+          when :none             then true
+          when parent.view_perms then true
+          when Symbol            then format.anyone_can?(view_perms)
+          else                        false
+          end
+        end
+
+        # determine the cache action from the cache setting
+        # (assuming cache status is "active")
+        # @return [Symbol] cache action
+        def active_cache_action_from_setting
+          level = ACTIVE_CACHE_LEVEL[cache_setting]
+          level || raise("unknown cache setting: #{cache_setting}")
+        end
+
+        ACTIVE_CACHE_LEVEL =
+          { always: :cache_yield, standard: :yield, never: :stub }.freeze
+
+        # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+        # SHARED METHODS
+
+        # @return [Symbol] :standard, :always, or :never
+        def cache_setting
+          format.view_cache_setting requested_view
+        end
+
+        # altered view requests and altered cards are not cacheable
+        # @return [True/False]
+        def clean_enough_to_cache?
+          requested_view == ok_view && !card.unknown? && !card.db_content_changed?
+          # unknown views may be safe if we add type_id to the cache key for unknown
+          # (or all new?) cards.
+          #
+          #
+        end
+      end
+    end
+  end
+end

data/lib/card/view/cache/stub.rb

@@ -0,0 +1,55 @@
+class Card
+  class View
+    module Cache
+      # A "stub" is a placeholder for a card view.
+      #
+      # Cached views use stubs so that _nesting_ content can remained cached
+      # even while _nested_ content changes. The nested content's place is held
+      # by a stub.
+      #
+      # A stub must contain all the information necessary to produce the view as intended.
+      module Stub
+        class << self
+          def escape stub_json
+            stub_json.gsub "(", "_OParEN_"
+          end
+
+          def unescape stub_json
+            stub_json.gsub "_OParEN_", "("
+          end
+
+          # FIXME: escaping and unescaping stubs should not be necessary
+          # It's used to avoid problems with altered views, but altering views is
+          # unsafe and should be eliminated.  See {Card::View::Cache}.
+        end
+
+        private
+
+        # @return [String]
+        def stub
+          "(stub)#{Stub.escape stub_json}(/stub)".html_safe
+        end
+
+        # @return [String] the stub_hash as JSON
+        def stub_json
+          JSON.generate stub_hash
+        end
+
+        # @return [Hash]
+        def stub_hash
+          { cast: card.cast,
+            view_opts: normalized_options.merge(normalized_visibility_options),
+            format_opts: { nest_mode: format.nest_mode,
+                           override: root?,
+                           context_names: format.context_names } }
+          # nest mode handling:
+          #
+          # Typically modes override views on nests, but stubs create non-standard nests.
+          # Mode-based view overrides should NOT apply to standard render calls that have
+          # been replaced with stubs - only to standard nest calls. The override value
+          # is used to retain this distinction.
+        end
+      end
+    end
+  end
+end