rack-unreloader 1.6.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 63e0754f2064aacba7745d52c60d136019dd5fdf
-  data.tar.gz: 31d3d8223106f59d5fa739b429cbf08d6d47db31
+SHA256:
+  metadata.gz: f60b8ff5b4384a7f55f92c4e851e2589622112228849b63ed7cf520b2e4b4112
+  data.tar.gz: e01e616600037edc3eb954dd9cf7fd6c8667fa43b15590ec4bb5041547c5f4af
 SHA512:
-  metadata.gz: 6645aa444fd1c88c52c09f0de56894f640cf9404624f0e25197071b1498d1aa7745a1bb9a8e9416f3cc7d8aeacf4f993e552adaa06f4b1386be95db43aef4272
-  data.tar.gz: 26811ff5218e1fe20e15f0619dcfb4d4dbabcba2819c82e8c46f428fdfb1714a3348a12a931ba8065d5f6cb182336e989e6d98d93e7a2ac633f4c6c7d783fc43
+  metadata.gz: 5da4eebc546fcc8194667ca1c1176574f6299a2bef8b062f24edf09146fc151f234b8119af9c19120f5245a5b921cb6841bba29c4bfc20abdc5d229ac040305a
+  data.tar.gz: f7fcb791cb9a0d8f585444ba7bddc4f2ffd80759c4544c8a450c8ebeb38b8620bf24cd05c6a368921c395c9de2ddb1a60f6a31a26a30d76df2d458de35355904

data/CHANGELOG

@@ -1,3 +1,25 @@
+= 2.0.0 (2022-06-23)
+
+* Fix TypeError being raised when requiring a file results in an error (jeremyevans)
+
+* Drop Unreloader#strip_path_prefix (jeremyevans)
+
+* Drop Ruby 1.8 support (jeremyevans)
+
+= 1.8.0 (2021-10-15)
+
+* Avoid warnings in verbose warning mode on Ruby 3+ (jeremyevans)
+
+* Check directory timestamps before looking for added or removed files (jeremyevans)
+
+* Add support for a :delete_hook option to Unreloader#require, called when a file is deleted (jeremyevans)
+
+* Handle cases where Module#name raises an exception (jeremyevans) (#9)
+
+= 1.7.0 (2019-03-18)
+
+* Add :handle_reload_errors option, for returning backtrace with error if there is an exception when reloading (jeremyevans)
+
 = 1.6.0 (2017-02-24)
 
 * Add Unreloader#strip_path_prefix, designed to support chrooting (jeremyevans)

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2014-2015 Jeremy Evans
+Copyright (c) 2014-2021 Jeremy Evans
 Copyright (c) 2011 Padrino
 
 Permission is hereby granted, free of charge, to any person obtaining

data/README.rdoc

@@ -1,12 +1,13 @@
 = Rack::Unreloader
 
-Rack::Unreloader is a rack library that reloads application files when it
-detects changes, unloading constants defined in those files before reloading.
-Like other rack libraries for reloading, this can make application development
-much faster, as you don't need to restart the whole application when you change
-a single file.  Unlike most other rack libraries for reloading, this unloads
-constants before requiring files, avoiding issues when loading a file is not
-idempotent.
+Rack::Unreloader is a code reloader for {Rack}[https://github.com/rack/rack].
+It speeds up application development by automatically reloading stale code
+so that you don't have to restart your dev server every time you change a file.
+
+Unlike most other code loading libraries for Rack,
+this one ensures that reloads are clean and idempotent
+by _unloading_ relevant constants first, and it does so incrementally, only
+reloading the files that are modified.
 
 == Installation
 
@@ -18,49 +19,61 @@ Source code is available on GitHub at https://github.com/jeremyevans/rack-unrelo
 
 == Basic Usage
 
-Assuming a basic web application stored in +app.rb+:
-
-  require 'roda'
+Before:
 
-  class App < Roda
-    route do |r|
-      "Hello world!"
-    end
-  end
+  # config.ru
 
-With a basic +config.ru+ like this:
+  require './app'
 
-  require './app.rb'
   run App
 
-Change +config.ru+ to:
+After:
+
+  # config.ru
 
   require 'rack/unreloader'
   Unreloader = Rack::Unreloader.new{App}
-  require 'roda'
   Unreloader.require './app.rb'
+
   run Unreloader
 
-The block you pass to Rack::Unreloader.new should return the rack application
-to use.  If you make any changes to +app.rb+, <tt>Rack::Unreloader</tt> will remove any
-constants defined by requiring +app.rb+, and rerequire the file.
+Now, +app.rb+ will be monitored for changes on each incoming HTTP request.
 
-Note that this causes problems if +app.rb+ loads any new libraries that define
-constants, as it will unload those constants first.  This is why the example
-code requires the +roda+ library normally before requiring +app.rb+ using
-<tt>Rack::Unreloader</tt>.
+If changes are detected, +Rack::Unreloader+ will
+unload all constants defined inside it and then re-require it
+before proceeding with the request.
 
-However, if +app.rb+ requires more than a single file, it is more
-practical to tell <tt>Rack::Unreloader</tt> to only unload specific subclasses:
+== Handling Subclasses
 
-  require 'rack/unreloader'
-  Unreloader = Rack::Unreloader.new(:subclasses=>%w'Roda'){App}
-  Unreloader.require './app.rb'
-  run Unreloader
+By default, +Rack::Unreloader+ unloads *all* constants defined in +app.rb+.
+That includes third-party libraries, like +Roda+ or +JSON+ in the example below:
 
-When the +:subclasses+ option is given, only subclasses of the given classes
-will be unloaded before reloading the file.  It is recommended that
-you use a +:subclasses+ option when using <tt>Rack::Unreloader</tt>.
+  # app.rb
+
+  require 'roda'
+  require 'json'
+
+  class App < Roda
+    ...
+  end
+
+Unloading these classes/modules isn't just unnecessary, it's dangerous.
+If your own code depends on them, your app will throw a +NameError+ after
+reloading when it tries to access them.
+
+To reload only *subclasses* of +Roda+ (i.e. +App+), use the +:subclasses+
+option:
+
+  Rack::Unreloader.new(:subclasses=>%w'Roda'){App}
+
+== Handling Errors During Reloading
+
+By default, +Rack::Unreloader+ instances do not handle exceptions raised
+during reloading, so that it may be rescued elsewhere (e.g. manually or by middleware).
+You can use the +:handle_reload_errors+ option to send the backtrace directly to the
+client as the HTTP response:
+
+  Rack::Unreloader.new(handle_reload_errors: true){App}
 
 == Dependency Handling
 
@@ -83,7 +96,7 @@ to using:
 
   Unreloader.require './models.rb'
 
-The reason that the <tt>Rack::Unreloader</tt> instance is assigned to a constant in
+The reason that the +Rack::Unreloader+ instance is assigned to a constant in
 +config.ru+ is to make it easy to add reloadable dependencies in this way.
 
 It's even a better idea to require this dependency manually in +config.ru+,
@@ -207,9 +220,20 @@ The advantage for doing this is that new files added to the directory will be
 picked up automatically, and files deleted from the directory will be removed
 automatically. This applies to files in subdirectories of that directory as well.
 
+The +require+ method also supports a +:delete_hook+ option.  This option sets
+a hook that is called when the related file is deleted.  This is useful if adding
+a new file or reloading an existing file will handle things correctly, but
+removing the file will not.  One common case for this is when you have a shared data
+structure that is updated by the files, where adding or reloading the file will
+update the data structure, but deleting will not, and will leave stale entries in
+the data structure.  You can use the +:delete_hook+ option to remove the entries
+related to the file in the data structure:
+
+  Unreloader.require 'models', :delete_hook=>proc{|f| SHARED_HASH.delete(f)}
+
 == Speeding Things Up
 
-By default, <tt>Rack::Unreloader</tt> uses +ObjectSpace+ before and after requiring each
+By default, +Rack::Unreloader+ uses +ObjectSpace+ before and after requiring each
 file that it monitors, to see which classes and modules were defined by the
 require.  This is slow for large numbers of files.  In general use it isn't an
 issue as generally only a single file will be changed at a time, but it can
@@ -218,7 +242,7 @@ time.
 
 If you want to speed things up, you can provide a block to Rack::Unreloader#require,
 which will take the file name, and should return the name of the constants or array
-of constants to unload.  If you do this, <tt>Rack::Unreloader</tt> will no longer need
+of constants to unload.  If you do this, +Rack::Unreloader+ will no longer need
 to use +ObjectSpace+, which substantially speeds up startup.  For example, if all of
 your models just use a capitalized version of the filename:
 
@@ -229,21 +253,9 @@ decide that instead of specifying the constants, ObjectSpace should be used to
 automatically determine the constants loaded. You can specify this by having the
 block return the :ObjectSpace symbol.
 
-== chroot Support
-
-<tt>Rack::Unreloader#strip_path_prefix</tt> exists for supporting reloading in
-chroot environments, where you chroot an application after it has been fully
-loaded, but still want to pick up changes to files inside the chroot. Example:
-
-  Unreloader.strip_path_prefix(Dir.pwd)
-  Dir.chroot(Dir.pwd)
-
-Note that Unreloader.strip_path_prefix also strips the path prefix from
-$LOADED_FEATURES, as that is necessary for correct operation.
-
 == Usage Outside Rack
 
-While <tt>Rack::Unreloader</tt> is usually in the development of rack applications,
+While +Rack::Unreloader+ is usually in the development of rack applications,
 it doesn't depend on rack.  You can just instantiate an instance of Unreloader and
 use it to handle reloading in any ruby application, just by using the +require+ and
 +record_dependency+ to set up the metadata, and calling +reload!+ manually to
@@ -272,11 +284,9 @@ environment anytime there are any changes) are going to be more robust than
 this approach, but probably slower.  Be aware that you are trading robustness
 for speed when using this library.
 
-== Implementation Support
+== Ruby Version Support
 
-Rack::Unreloader works correctly on Ruby 1.8.7+, JRuby 9.1+, and Rubinius.  It
-also works on older versions of JRuby if you use a proc to specify the constants
-to unload.
+Rack::Unreloader works correctly on Ruby 1.9.2+ and JRuby 9.1+.
 
 == License
 

data/lib/rack/unreloader/reloader.rb

@@ -3,14 +3,11 @@ require 'set'
 module Rack
   class Unreloader
     class Reloader
-      F = ::File
+      File = ::File
 
       # Regexp for valid constant names, to prevent code execution.
       VALID_CONSTANT_NAME_REGEXP = /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/.freeze
 
-      # Options hash to force loading of files even if they haven't changed.
-      FORCE = {:force=>true}.freeze
-
       # Setup the reloader.  Supports :logger and :subclasses options, see
       # Rack::Unloader.new for details.
       def initialize(opts={})
@@ -18,13 +15,15 @@ module Rack
         @classes = opts[:subclasses] ?  Array(opts[:subclasses]).map(&:to_s) : %w'Object'
 
         # Hash of files being monitored for changes, keyed by absolute path of file name,
-        # with values being the last modified time (or nil if the file has not yet been loaded).
+        # with values being an array containing the last modified time (or nil if the file has
+        # not yet been loaded) and the delete hook.
         @monitor_files = {}
 
         # Hash of directories being monitored for changes, keyed by absolute path of directory name,
-        # with values being the an array with the last modified time (or nil if the directory has not
-        # yet been loaded), an array of files in the directory, and a block to pass to
-        # require_dependency for new files.
+        # with values being the an array with a hash of modified times for the directory and
+        # subdirectories (or nil if the directory has not yet been checked), an array of files in
+        # the directory, a block to pass to require_dependency for new files, and the delete_hook
+        # for the files in the directory.
         @monitor_dirs = {}
 
         # Hash of procs returning constants defined in files, keyed by absolute path
@@ -53,47 +52,6 @@ module Rack
         @skip_reload = []
       end
 
-      # Strip the given path prefix from the internal data structures.
-      def strip_path_prefix(path_prefix)
-        empty = ''.freeze
-
-        # Strip the path prefix from $LOADED_FEATURES, otherwise the reloading won't work.
-        # Hopefully a future version of ruby will do this automatically when chrooting.
-        $LOADED_FEATURES.map!{|s| s.sub(path_prefix, empty)}
-
-        fix_path = lambda do |s|
-          s.sub(path_prefix, empty)
-        end
-
-        [@dependency_order, @skip_reload].each do |a|
-          a.map!(&fix_path)
-        end
-
-        [@files, @old_entries].each do |hash|
-          hash.each do |k,h|
-            h[:features].map!(&fix_path)
-          end
-        end
-        
-        @monitor_dirs.each_value do |a|
-          a[1].map!(&fix_path)
-        end
-
-        @dependencies.each_value do |a|
-          a.map!(&fix_path)
-        end
-
-        [@files, @old_entries, @monitor_files, @monitor_dirs, @constants_defined, @dependencies].each do |hash|
-          hash.keys.each do |k|
-            if k.start_with?(path_prefix)
-              hash[fix_path.call(k)] = hash.delete(k)
-            end
-          end
-        end
-
-        nil
-      end
-
       # Unload all reloadable constants and features, and clear the list
       # of files to monitor.
       def clear!
@@ -117,7 +75,7 @@ module Rack
         order.concat(files)
         order.uniq!
 
-        if F.directory?(path)
+        if File.directory?(path)
           (@monitor_files.keys & Unreloader.ruby_files(path)).each do |file|
             record_dependency(file, files)
           end
@@ -136,27 +94,26 @@ module Rack
         end
 
         removed_files = []
+        delete_hooks = []
 
-        @monitor_files.to_a.each do |file, time|
-          if F.file?(file)
+        @monitor_files.to_a.each do |file, (time, delete_hook)|
+          if File.file?(file)
             if file_changed?(file, time)
               changed_files << file
             end
           else
+            delete_hooks << [delete_hook, file] if delete_hook
             removed_files << file
           end
         end
 
         remove_files(removed_files)
+        delete_hooks.each{|hook, file| hook.call(file)}
 
         return if changed_files.empty?
 
         unless @dependencies.empty?
-          changed_files = reload_files(changed_files)
-          changed_files.flatten!
-          changed_files.map!{|f| F.directory?(f) ? Unreloader.ruby_files(f) : f}
-          changed_files.flatten!
-          changed_files.uniq!
+          changed_files = Unreloader.expand_directory_paths(reload_files(changed_files))
           
           order = @dependency_order
           order &= changed_files
@@ -164,44 +121,45 @@ module Rack
         end
 
         unless @skip_reload.empty?
-          skip_reload = @skip_reload.map{|f| F.directory?(f) ? Unreloader.ruby_files(f) : f}
-          skip_reload.flatten!
-          skip_reload.uniq!
-          changed_files -= skip_reload
+          changed_files -= Unreloader.expand_directory_paths(@skip_reload)
         end
 
+        changed_files.select! do |file|
+          @monitor_files.has_key?(file)
+        end
         changed_files.each do |file|
-          safe_load(file, FORCE)
+          safe_load(file)
         end
       end
 
       # Require the given dependencies, monitoring them for changes.
       # Paths should be a file glob or an array of file globs.
-      def require_dependencies(paths, &block)
+      def require_dependencies(paths, opts={}, &block)
         options = {:cyclic => true}
+        delete_hook = opts[:delete_hook]
         error = nil 
 
         Unreloader.expand_paths(paths).each do |file|
-          if F.directory?(file)
-            @monitor_dirs[file] = [nil, [], block]
+          if File.directory?(file)
+            @monitor_dirs[file] = [nil, [], block, delete_hook]
             check_monitor_dir(file)
             next
           else
             @constants_defined[file] = block
-            @monitor_files[file] = nil
+            @monitor_files[file] = [nil, delete_hook]
           end
 
           begin
             safe_load(file, options)
           rescue NameError, LoadError => error
-            log "Cyclic dependency reload for #{error}"
+            log "Cyclic dependency reload for #{error.class}: #{error.message}"
           rescue Exception => error
+            log "Error: #{error.class}: #{error.message}"
             break
           end
         end
 
         if error
-          log error
           raise error
         end
       end
@@ -234,10 +192,21 @@ module Rack
         @logger.info(s) if @logger
       end
 
+      # A hash of modify times for all subdirectories of the given directory.
+      def subdir_times(dir)
+        h = {}
+        Find.find(dir) do |f|
+          h[f] = modified_at(f) if File.directory?(f)
+        end
+        h
+      end
+
       # Check a monitored directory for changes, adding new files and removing
       # deleted files.
       def check_monitor_dir(dir, changed_files=nil)
-        time, files, block = @monitor_dirs[dir]
+        subdir_times, files, block, delete_hook = md = @monitor_dirs[dir]
+        return if subdir_times && subdir_times.all?{|subdir, time| File.directory?(subdir) && modified_at(subdir) == time}
+        md[0] = subdir_times(dir)
 
         cur_files = Unreloader.ruby_files(dir)
         return if files == cur_files
@@ -250,8 +219,11 @@ module Rack
         end
 
         remove_files(removed_files)
+        if delete_hook
+          removed_files.each{|f| delete_hook.call(f)}
+        end
 
-        require_dependencies(new_files, &block)
+        require_dependencies(new_files, :delete_hook=>delete_hook, &block)
 
         new_files.each do |file|
           if deps = @dependencies[dir]
@@ -281,9 +253,6 @@ module Rack
       # by the require, and rolling back the constants and features if there
       # are any errors.
       def safe_load(file, options={})
-        return unless @monitor_files.has_key?(file)
-        return unless options[:force] || file_changed?(file)
-
         prepare(file) # might call #safe_load recursively
         log "Loading #{file}"
         begin
@@ -344,7 +313,7 @@ module Rack
       # Store the currently loaded classes and features, so in case of an error
       # this state can be rolled back to.
       def prepare(name)
-        file = remove(name)
+        remove(name)
         @old_entries[name] = {:features => monitored_features}
         if constants = constants_for(name)
           defs = constants.select{|c| constant_defined?(c)}
@@ -383,7 +352,7 @@ module Rack
 
         @files[name] = entry
         @old_entries.delete(name)
-        @monitor_files[name] = modified_at(name)
+        @monitor_files[name][0] = modified_at(name)
 
         defs, not_defs = entry[:constants].partition{|c| constant_defined?(c)}
         unless not_defs.empty?
@@ -413,7 +382,7 @@ module Rack
         rs = Set.new
 
         ::ObjectSpace.each_object(Module).each do |mod|
-          if !mod.name.to_s.empty? && monitored_module?(mod)
+          if !(mod.name rescue next).to_s.empty? && monitored_module?(mod)
             rs << mod
           end
         end
@@ -466,7 +435,7 @@ module Rack
       end
 
       # Returns true if the file is new or it's modification time changed.
-      def file_changed?(file, time = @monitor_files[file])
+      def file_changed?(file, time = @monitor_files[file][0])
         !time || modified_at(file) > time
       end
 
@@ -474,7 +443,7 @@ module Rack
       # to base the reloading on something other than the file's modification
       # time.
       def modified_at(file)
-        F.mtime(file)
+        File.mtime(file)
       end
     end
   end

data/lib/rack/unreloader.rb

@@ -9,26 +9,27 @@ module Rack
     MUTEX = Monitor.new
 
     # Reference to ::File as File would return Rack::File by default.
-    F = ::File
+    File = ::File
 
     # Given the list of paths, find all matching files, or matching ruby files
     # in subdirecories if given a directory, and return an array of expanded
     # paths.
     def self.expand_directory_paths(paths)
-      expand_paths(paths).
-        map{|f| F.directory?(f) ? ruby_files(f) : f}.
-        flatten
+      paths = expand_paths(paths)
+      paths.map!{|f| File.directory?(f) ? ruby_files(f) : f}
+      paths.flatten!
+      paths
     end
 
     # Given the path glob or array of path globs, find all matching files
     # or directories, and return an array of expanded paths.
     def self.expand_paths(paths)
-      Array(paths).
-        flatten.
-        map{|path| Dir.glob(path).sort_by{|filename| filename.count('/')}}.
-        flatten.
-        map{|path| F.expand_path(path)}.
-        uniq
+      paths = Array(paths).flatten
+      paths.map!{|path| Dir.glob(path).sort_by!{|filename| filename.count('/')}}
+      paths.flatten!
+      paths.map!{|path| File.expand_path(path)}
+      paths.uniq!
+      paths
     end
 
     # The .rb files in the given directory or any subdirectory.
@@ -47,6 +48,8 @@ module Rack
     # 
     # :cooldown :: The number of seconds to wait between checks for changed files.
     #              Defaults to 1.  Set to nil/false to not check for changed files.
+    # :handle_reload_errors :: Whether reload to handle reload errors by returning
+    #                          a 500 plain text response with the backtrace.
     # :reload :: Set to false to not setup a reloader, and just have require work
     #            directly.  Should be set to false in production mode.
     # :logger :: A Logger instance which will log information related to reloading.
@@ -58,12 +61,13 @@ module Rack
       @app_block = block
       if opts.fetch(:reload, true)
         @cooldown = opts.fetch(:cooldown, 1)
+        @handle_reload_errors = opts[:handle_reload_errors]
         @last = Time.at(0)
-        Kernel.require 'rack/unreloader/reloader'
+        require_relative 'unreloader/reloader'
         @reloader = Reloader.new(opts)
         reload!
       else
-        @reloader = @cooldown = false
+        @reloader = @cooldown = @handle_reload_errors = false
       end
     end
 
@@ -71,16 +75,25 @@ module Rack
     # Call the app with the environment.
     def call(env)
       if @cooldown && Time.now > @last + @cooldown
-        MUTEX.synchronize{reload!}
+        begin
+          MUTEX.synchronize{reload!}
+        rescue StandardError, ScriptError => e
+          raise unless @handle_reload_errors
+          content = "#{e.class}: #{e}\n#{e.backtrace.join("\n")}"
+          return [500, {'Content-Type' => 'text/plain', 'Content-Length' => content.bytesize.to_s}, [content]]
+        end
         @last = Time.now
       end
       @app_block.call.call(env)
     end
 
     # Add a file glob or array of file globs to monitor for changes.
-    def require(paths, &block)
+    # Options:
+    # :delete_hook :: When a file being monitored is deleted, call
+    #                 this hook with the path of the deleted file.
+    def require(paths, opts={}, &block)
       if @reloader
-        @reloader.require_dependencies(paths, &block)
+        @reloader.require_dependencies(paths, opts, &block)
       else
         Unreloader.expand_directory_paths(paths).each{|f| super(f)}
       end
@@ -116,17 +129,5 @@ module Rack
     def reload!
       @reloader.reload! if @reloader
     end
-
-    # Strip the given path prefix from all absolute paths used by the
-    # reloader.  This is designed when chrooting an application.
-    #
-    # Options:
-    # :strip_core :: Also strips the path prefix from $LOADED_FEATURES and
-    #              $LOAD_PATH.
-    def strip_path_prefix(path_prefix, opts={})
-      if @reloader
-        @reloader.strip_path_prefix(path_prefix)
-      end
-    end
   end
 end