fragmentary 0.1.0 → 0.3

data/fragmentary.gemspec

@@ -22,9 +22,11 @@ Gem::Specification.new do |spec|
   spec.bindir        = "exe"
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "rails", ">= 4.0.0", "< 5"
+  spec.add_runtime_dependency "rails", "~> 5.0"
   spec.add_runtime_dependency "delayed_job_active_record", "~> 4.1"
   spec.add_runtime_dependency "wisper-activerecord", "~> 1.0"
+  spec.add_runtime_dependency "http", "~> 3.0.0"
+  spec.add_runtime_dependency "nokogiri"
   spec.add_development_dependency "bundler", "~> 1.17"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"

data/lib/fragmentary/config.rb

@@ -0,0 +1,65 @@
+module Fragmentary
+
+  class Config
+    include Singleton
+    attr_accessor :current_user_method, :get_sign_in_path, :post_sign_in_path, :sign_out_path,
+                  :users, :default_user_type_mapping, :session_users, :application_root_url_column, :remote_urls
+
+    def initialize
+      # default
+      @current_user_method = :current_user
+      @application_root_url_column = :application_root_url
+      @remote_urls = []
+    end
+
+    def session_users=(session_users)
+      raise "config.session_users must be a Hash" unless session_users.is_a?(Hash)
+      Fragmentary.parse_session_users(session_users)
+      @session_users = session_users
+    end
+
+    def application_root_url_column=(column_name)
+      @application_root_url_column = column_name.to_sym
+    end
+  end
+
+  def self.current_user_method
+    self.config.current_user_method
+  end
+
+  # Parse a set of session_user options, creating session_users where needed, and return a set of user_type keys.
+  # session_users may take several forms:
+  #   (1) a hash whose keys are user_type strings and whose values have the form {:credentials => credentials},
+  #       where 'credentials' is either a hash of parameters to be submitted when logging in or a proc that
+  #       returns those parameters.
+  #   (2) an array of hashes as described in (1) above.
+  #   (3) an array of user_type strings corresponding to SessionUser objects already defined.
+  #   (4) an array containing a mixture of user_type strings and hashes as described in (1) above.
+  # Non-hash elements that don't represent existing SessionUser objects should raise an exception. Array
+  # elements that are hashes should be parsed to create new SessionUser objects. Raise an exception on
+  # any attempt to redefine an existing user_type.
+  def self.parse_session_users(session_users = nil)
+    return nil unless session_users
+    if session_users.is_a?(Array)
+      # Fun fact: can't use 'each_with_object' here because 'acc += parse_session_users(v)' would assign
+      # a different object to 'acc' on each iteration, while 'each_with_object' passes the *same* object
+      # to the block on each iteration.
+      session_users.inject([]) do |acc, v|
+        if v.is_a?(Hash)
+          acc + parse_session_users(v)
+        else
+          # v is a user_type, e.g. :admin
+          raise "No SessionUser exists for user_type '#{v}'" unless SessionUser.fetch(v)
+          acc << v
+        end
+      end
+    elsif session_users.is_a?(Hash)
+      session_users.each_with_object([]) do |(k,v), acc|
+        # k is the user_type, v is an options hash that typically looks like  {:credentials => login_credentials} where
+        # login_credentials is either a hash of parameters to be submitted at login or a proc that returns those parameters.
+        # In the latter case, the proc is executed when we actually log in to create a new session for the specified user.
+        acc << k if user = SessionUser.new(k,v)
+      end
+    end
+  end
+end

data/lib/fragmentary/fragment.rb

@@ -24,13 +24,12 @@ module Fragmentary
         # redundant duplicate request.
         after_commit :touch_parent, :on => [:update, :destroy]
 
-        attr_accessible :parent_id, :root_id, :record_id, :user_id, :user_type, :key
-
         attr_accessor :indexed_children
 
-        validate :root_id, :presence => true
-
-        cache_timestamp_format = :usec  # Not be needed for Rails 5, which uses :usec by default.
+        # Set cache timestamp format to :usec instead of :nsec because the latter is greater precision than Postgres supports,
+        # resulting in mismatches between timestamps on a newly created fragment and one retrieved from the database.
+        # Probably not needed for Rails 5, which uses :usec by default.
+        self.cache_timestamp_format = :usec
 
       end
 
@@ -49,14 +48,14 @@ module Fragmentary
     module ClassMethods
 
       def root(options)
-        if options[:type].constantize.requestable?
+        if fragment = options[:fragment]
+          raise ArgumentError, "You passed Fragment #{fragment.id} to Fragment.root, but it's a child of Fragment #{fragment.parent_id}" if fragment.parent_id
+        else
           klass, search_attributes, options = base_class.attributes(options)
           fragment = klass.where(search_attributes).includes(:children).first_or_initialize(options); fragment.save if fragment.new_record?
           fragment.set_indexed_children if fragment.child_search_key
-          fragment
-        else
-          raise RangeError, "#{options[:type]} is not a root fragment class"
         end
+        fragment
       end
 
       # Each fragment record is unique by type and parent_id (which is nil for a root_fragment) and for some types also by
@@ -72,8 +71,14 @@ module Fragmentary
         # Collect the attributes to be used when searching for an existing fragment. Fragments are unique by these values.
         search_attributes = {}
 
-        parent_id = options.delete(:parent_id)
-        search_attributes.merge!(:parent_id => parent_id) if parent_id
+        if (parent_id = options.delete(:parent_id))
+          search_attributes.merge!(:parent_id => parent_id)
+        else
+          application_root_url_column = Fragmentary.config.application_root_url_column
+          if (application_root_url = options.delete(application_root_url_column)) && column_names.include?(application_root_url_column.to_s)
+            search_attributes.merge!(application_root_url_column => application_root_url)
+          end
+        end
 
         [:record_id, :user_id, :user_type, :key].each do |attribute_name|
           if klass.needs?(attribute_name)
@@ -94,16 +99,21 @@ module Fragmentary
         @@cache_store ||= Rails.application.config.action_controller.cache_store
       end
 
+      # ToDo: combine this with Fragment.root
       def existing(options)
-        options.merge!(:type => name) unless self == base_class
-        raise ArgumentError, "A 'type' attribute is needed in order to retrieve a fragment" unless options[:type]
-        klass, search_attributes, options = base_class.attributes(options)
-        # We merge options because it may include :record_id, which may be needed for uniqueness even
-        # for classes that don't 'need_record_id' if the parent_id isn't available.
-        fragment = klass.where(search_attributes.merge(options)).includes(:children).first
-        # Unlike Fragment.root and Fragment#child we don't instantiate a record if none is found,
-        # so fragment may be nil.
-        fragment.try :set_indexed_children if fragment.try :child_search_key
+        if fragment = options[:fragment]
+          raise ArgumentError, "You passed Fragment #{fragment.id} to Fragment.existing, but it's a child of Fragment #{fragment.parent_id}" if fragment.parent_id
+        else
+          options.merge!(:type => name) unless self == base_class
+          raise ArgumentError, "A 'type' attribute is needed in order to retrieve a fragment" unless options[:type]
+          klass, search_attributes, options = base_class.attributes(options)
+          # We merge options because it may include :record_id, which may be needed for uniqueness even
+          # for classes that don't 'need_record_id' if the parent_id isn't available.
+          fragment = klass.where(search_attributes.merge(options)).includes(:children).first
+          # Unlike Fragment.root and Fragment#child we don't instantiate a record if none is found,
+          # so fragment may be nil.
+          fragment.try :set_indexed_children if fragment.try :child_search_key
+        end
         fragment
       end
 
@@ -111,20 +121,53 @@ module Fragmentary
         self
       end
 
+      # There is one queue per user_type per application instance (the current app and any external instances). The queues
+      # for all fragments are held in common by the Fragment base class here in @@request_queues but are also indexed on a
+      # subclass basis by an individual subclass's user_types (see the inherited hook below). As well as being accessible
+      # here as Fragment.request_queues, the queues are also available without indexation as RequestQueue.all.
       def request_queues
-        @@request_queues ||= Hash.new do |hash, user_type|
-          hash[user_type] = RequestQueue.new(user_type)
+        @@request_queues ||= Hash.new do |hsh, host_url|
+          # As well as acting as a hash key to index the set of request queues for a given target application instance
+          # (for which its uniqueness is the only requirement), host_url is also passed to the RequestQueue constructor,
+          # from which it is used:
+          #   (i) by the RequestQueue::Sender to derive the name of the delayed_job queue that will be used to process the
+          #       queued requests if the sender is invoked in asynchronous mode - see RequestQueue::Sender#schedulerequests.
+          #   (ii) by the Fragmentary::InternalUserSession instantiated by the Sender to configure the session_host.
+          hsh[host_url] = Hash.new do |hsh2, user_type|
+            hsh2[user_type] = RequestQueue.new(user_type, host_url)
+          end
         end
-        if self == base_class
-          @@request_queues
-        else
-          return nil unless new.requestable?
-          user_types.each_with_object({}){|user_type, queues| queues[user_type] = @@request_queues[user_type]}
+      end
+
+      # Subclass-specific request_queues
+      def inherited(subclass)
+        subclass.instance_eval do
+
+          def request_queues
+            super  # ensure that @@request_queues has been defined
+            @request_queues ||= begin
+              app_root_url = Rails.application.routes.url_helpers.root_url
+              remote_urls = Fragmentary.config.remote_urls
+              user_types.each_with_object( Hash.new {|hsh0, url| hsh0[url] = {}} ) do |user_type, hsh|
+                # Internal request queues
+                hsh[app_root_url][user_type] = @@request_queues[app_root_url][user_type]
+                # External request queues
+                if remote_urls.any?
+                  unless Rails.application.routes.default_url_options[:host]
+                    raise "Can't create external request queues without setting Rails.application.routes.default_url_options[:host]"
+                  end
+                  remote_urls.each {|remote_url| hsh[remote_url][user_type] = @@request_queues[remote_url][user_type]}
+                end
+              end
+            end
+          end
+
         end
+        super
       end
 
-      def remove_queued_request(user:, record_id:)
-        request_queues[user_type(user)].remove_path(request_path(record_id))
+      def remove_queued_request(user:, request_path:)
+        request_queues.each{|key, hsh| hsh[user_type(user)].remove_path(request_path)}
       end
 
       def subscriber
@@ -141,7 +184,7 @@ module Fragmentary
       # create or retrieve a Fragment of that class. A user_id is needed for example when caching user-specific content
       # such as a user profile. When the fragment is instantiated using FragmentsHelper methods 'cache_fragment' or
       # 'CacheBuilder.cache_child', a :user option is added to the options hash automatically from the value of 'current_user'.
-      # The user_id is extracted from this option in Fragment.find_or_create.
+      # The user_id is extracted from this option in Fragment.attributes.
       def needs_user_id
         self.extend NeedsUserId
       end
@@ -151,9 +194,24 @@ module Fragmentary
       # differently depending on the type of user, e.g. to distinguish between content seen by signed in users and those not
       # signed in. When the fragment is instantiated using FragmentsHelper methods 'cache_fragment' or 'CacheBuilder.cache_child',
       # a :user option is added to the options hash automatically from the value of 'current_user'. The user_type is extracted
-      # from this option in Fragment.find_or_create.
-      def needs_user_type
+      # from this option in Fragment.attributes.
+      #
+      # For each class that declares 'needs_user_type', a set of user_types is defined that determines the set of request_queues
+      # that will be used to send requests to the application when a fragment is touched. By default these user_types are defined
+      # globally using 'Fragmentary.setup' but they can alternatively be set on a class-specific basis by passing a :session_users
+      # option to 'needs_user_type'. See 'Fragmentary.parse_session_users' for details.
+      def needs_user_type(options = {})
         self.extend NeedsUserType
+        instance_eval do
+          @user_type_mapping = options[:user_type_mapping]
+          def self.user_type(user)
+            (@user_type_mapping || Fragmentary.config.default_user_type_mapping).try(:call, user)
+          end
+          @user_types = Fragmentary.parse_session_users(options[:session_users] || options[:types] || options[:user_types])
+          def self.user_types
+            @user_types || Fragmentary.config.session_users.keys
+          end
+        end
       end
 
       def needs_key(options = {})
@@ -202,17 +260,25 @@ module Fragmentary
             # by the fragment.
             class << record_type_subscription
               set_callback :after_destroy, :after, ->{subscriber.client.remove_fragments_for_record(record.id)}
+              set_callback :after_create, :after, ->{subscriber.client.try_request_for_record(record.id)}
             end
           end
 
-          def record
-            record_type.constantize.find(record_id)
-          end
+          self.extend RecordClassMethods
+          define_method(:record){record_type.constantize.find(record_id)}
         end
       end
 
-      def remove_fragments_for_record(record_id)
-        where(:record_id => record_id).each(&:destroy)
+      module RecordClassMethods
+        def remove_fragments_for_record(record_id)
+          where(:record_id => record_id).each(&:destroy)
+        end
+
+        def try_request_for_record(record_id)
+          if requestable?
+            queue_request(request(record_id))
+          end
+        end
       end
 
       def needs_record_id?
@@ -245,7 +311,7 @@ module Fragmentary
       # hasn't yet been requested, e.g. an assumption created on an article page won't necessarily have been rendered on the
       # opinion analysis page.
       def touch_fragments_for_record(record_id)
-        fragments_for_record(record_id).each(&:touch)
+        fragments_for_record(record_id).includes({:parent => :parent}).each(&:touch)
       end
 
       def fragments_for_record(record_id)
@@ -260,24 +326,12 @@ module Fragmentary
         nil
       end
 
-      def queue_request(*args)
-        puts "  queue request for #{self.name}: #{args.inspect}"
-        if r = request(*args)
-          request_queues.each{|key, queue| queue << r}
-        end
+      def queue_request(request=nil)
+        request_queues.each{|key, hsh| hsh.each{|key2, queue| queue << request}} if request
       end
 
       def requestable?
-        respond_to? :request_path
-      end
-
-      # Subclasses that define a class method self.request_path also need to override this method
-      def request(*args)
-        if respond_to? :request_path
-          raise "You can't call Fragment.request for a subclass that defines 'request_path'. #{name} needs its own request implementation."
-       else
-          raise "There is no 'request' class method defined for the #{name} class."
-        end
+        respond_to?(:request_path)
       end
 
       # The instance method 'request_method' is defined in terms of this.
@@ -291,7 +345,11 @@ module Fragmentary
 
       # The instance method 'request_options' is defined in terms of this.
       def request_options
-        nil
+        {}
+      end
+
+      def request
+        raise NotImplementedError
       end
 
       # This method defines the handler for the creation of new list items. The method takes:
@@ -382,7 +440,10 @@ module Fragmentary
     # rendered on its own, e.g. inserted by ajax into a parent that is already on the page. In this case the
     # children won't have already been loaded or indexed.
     def child(options)
-      begin
+      if child = options[:child]
+        raise ArgumentError, "You passed a child fragment to a parent it's not a child of." unless child.parent_id == self.id
+        child
+      else
         existing = options.delete(:existing)
         # root_id and parent_id are passed from parent to child. For all except root fragments, root_id is stored explicitly.
         derived_options = {:root_id => root_id || id}
@@ -412,10 +473,7 @@ module Fragmentary
           fragment_children = fragment.children
           fragment.set_indexed_children if fragment.child_search_key
         end
-
         fragment
-      rescue => e
-        Rails.logger.error e.message + "\n " + e.backtrace.join("\n ")
       end
     end
 
@@ -436,7 +494,7 @@ module Fragmentary
     end
 
     def touch(*args, no_request: false)
-      request_queues.each{|key, queue| queue << request} if request && !no_request
+      request_queues.each{|key, hsh| hsh.each{|key2, queue| queue << request}} if request && !no_request
       super(*args)
     end
 
@@ -459,10 +517,13 @@ module Fragmentary
       touch(:no_request => no_request) unless children.any?
     end
 
+    # Touch this fragment and all descendants that have entries in the cache. Destroy any that
+    # don't have cache entries.
     def touch_or_destroy
       puts "  touch_or_destroy #{self.class.name} #{id}"
       if cache_exist?
         children.each(&:touch_or_destroy)
+        # if there are children, this will be touched automatically once they are.
         touch(:no_request => true) unless children.any?
       else
         destroy  # will also destroy all children because of :dependent => :destroy
@@ -529,14 +590,6 @@ module Fragmentary
       def needs_user_type?
         true
       end
-
-      def user_types
-        ['admin', 'signed_in']
-      end
-
-      def user_type(user)
-        user ? (user.is_an_admin? ? "admin" : "signed_in") : "signed_out"
-      end
     end
 
     module NeedsKey

data/lib/fragmentary/fragments_helper.rb

@@ -2,61 +2,76 @@ module Fragmentary
 
   module FragmentsHelper
 
-    def cache_fragment(options)
-      no_cache = options.delete(:no_cache)
-      options.reverse_merge!(:user => current_user) if respond_to?(:current_user)
-      fragment = options.delete(:fragment) || Fragmentary::Fragment.base_class.root(options)
-      builder = CacheBuilder.new(fragment, template = self)
-      unless no_cache
-        cache fragment, :skip_digest => true do
-          yield(builder)
-        end
-      else
-        yield(builder)
-      end
-      self.output_buffer = WidgetParser.new(self).parse_buffer
+    def cache_fragment(options, &block)
+      options.reverse_merge!(Fragmentary.config.application_root_url_column => self.root_url.gsub(%r{https?://}, ''))
+      CacheBuilder.new(self).cache_fragment(options, &block)
     end
 
     def fragment_builder(options)
-      template = options.delete(:template)
-      options.reverse_merge!(:user => current_user) if respond_to?(:current_user)
-      CacheBuilder.new(Fragmentary::Fragment.base_class.existing(options), template)
+      # the template option is deprecated but avoids breaking prior usage
+      template = options.delete(:template) || self
+      options.reverse_merge!(:user => Template.new(template).current_user)
+      options.reverse_merge!(Fragmentary.config.application_root_url_column => self.root_url.gsub(%r{https?://}, ''))
+      CacheBuilder.new(template, Fragmentary::Fragment.base_class.existing(options))
     end
 
-
     class CacheBuilder
       include ::ActionView::Helpers::CacheHelper
       include ::ActionView::Helpers::TextHelper
 
-      attr_accessor :fragment, :template
+      attr_reader :fragment
 
-      def initialize(fragment, template)
+      def initialize(template, fragment = nil)
         @fragment = fragment
         @template = template
       end
 
-      def cache_child(options)
+      def cache_fragment(options, &block)
         no_cache = options.delete(:no_cache)
         insert_widgets = options.delete(:insert_widgets)
-        options.reverse_merge!(:user => template.current_user) if template.respond_to?(:current_user)
-        child = options.delete(:child) || fragment.child(options)
-        builder = CacheBuilder.new(child, template)
+        options.reverse_merge!(:user => Template.new(@template).current_user)
+        # If the CacheBuilder was instantiated with an existing fragment, next_fragment is its child;
+        # otherwise it is the root fragment specified by the options provided.
+        next_fragment = @fragment.try(:child, options) || Fragmentary::Fragment.base_class.root(options)
+        builder = CacheBuilder.new(@template, next_fragment)
         unless no_cache
-          template.cache child, :skip_digest => true do
+          @template.cache next_fragment, :skip_digest => true do
             yield(builder)
           end
         else
           yield(builder)
         end
-        template.output_buffer = WidgetParser.new(template).parse_buffer if insert_widgets
+        @template.output_buffer = WidgetParser.new(@template).parse_buffer if (!@fragment || insert_widgets)
       end
 
+      alias cache_child cache_fragment
+
+      private
+
       def method_missing(method, *args)
-        fragment.send(method, *args)
+        @fragment.send(method, *args)
       end
 
     end
 
   end
 
+
+  # Just a wrapper to allow us to call a configurable current_user_method on the template
+  class Template
+
+    def initialize(template)
+      @template = template
+    end
+
+    def current_user
+      return nil unless methd = Fragmentary.current_user_method
+      if @template.respond_to? methd
+        @template.send methd
+      else
+        raise NoMethodError, "The current_user_method '#{methd.to_s}' specified doesn't exist"
+      end
+    end
+  end
+
 end

data/lib/fragmentary/publisher.rb

@@ -33,7 +33,9 @@ module Fragmentary
       end
 
       def after_update_broadcast
-        broadcast(:after_update, self)
+        Rails.logger.info "\n***** #{start = Time.now} broadcasting :after_update from #{self.class.name} #{self.id}\n"
+        broadcast(:after_update, self) if self.previous_changes.any?
+        Rails.logger.info "\n***** #{Time.now} broadcast :after_update from #{self.class.name} #{self.id} took #{(Time.now - start) * 1000} ms\n"
       end
 
       def after_destroy_broadcast

data/lib/fragmentary/request.rb

@@ -3,28 +3,13 @@ module Fragmentary
   class Request
     attr_reader :method, :path, :options, :parameters
 
-    def initialize(method, path, parameters=nil, options=nil)
+    def initialize(method, path, parameters=nil, options={})
       @method, @path, @parameters, @options = method, path, parameters, options
     end
 
     def ==(other)
       method == other.method and path == other.path and parameters == other.parameters and options == other.options
     end
-
-    def to_proc
-      method = @method; path = @path; parameters = @parameters; options = @options.try :dup
-      if @options.try(:[], :xhr)
-        Proc.new do
-          puts "      * Sending xhr request '#{method.to_s} #{path}'" + (!parameters.nil? ? " with #{parameters.inspect}" : "")
-          send(:xhr, method, path, parameters, options)
-        end
-      else
-        Proc.new do
-          puts "      * Sending request '#{method.to_s} #{path}'" + (!parameters.nil? ? " with #{parameters.inspect}" : "")
-          send(method, path, parameters, options)
-        end
-      end
-    end
   end
 
 end