caddy 1.5.5 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1fcc04e3d12bf33c0268a418a46e4d255d8f9e38
-  data.tar.gz: bae67e7130cb5ce2dfd39086c5757e72acf53217
+  metadata.gz: ed9c2bf138fdfa093e81a888f423ade1a55890af
+  data.tar.gz: 0cb897a71cb7bb5345059a80c56c9f93cb25e29d
 SHA512:
-  metadata.gz: e4fbdcfbf10f665d85497e149f35b418e1f90c79db76e32d78221abdea6a4c66415e5117c64d65fc3c4be5dc6d956ab3b3102f2f39823958d5b415b67978057b
-  data.tar.gz: 5cc6776a9d1060785c3d58f306a53157f9994706799905ab445503e23c6a96bc60fde75c56f6d4f9e7f0d102a35a113c3adf0282a72182208bfcb591c116fb49
+  metadata.gz: 6ebff58f7afbfcaa321a3f69158c92636cd545946df87d11eb660911f54ae938256fcb3c7b77b94793296dc40db66aad3a654dc0ee3563e82ad335970f9bf824
+  data.tar.gz: b6f5786869e114c14d3374f086c7b439c6312b637ee45079d7fd7f8d99dcb012804a64fb000df9409b29220db793ffa1fb2f336fe247fa57e3aa7db6f1baf700

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "caddy"
+require "irb"
+
+IRB.start

data/bin/setup

@@ -0,0 +1,5 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install

data/lib/caddy.rb

@@ -5,23 +5,31 @@ require "caddy/version"
 require "caddy/task_observer"
 require "caddy/cache"
 
+# Caddy gives you a auto-updating global cache to speed up requests
 module Caddy
   class << self
+    # @!attribute error_handler
+    #   @return [Proc] called when any cache refresher throws an exception (or times out)
     attr_accessor :error_handler
+
+    # see {#logger}
+    attr_writer :logger
   end
 
   @started_pid = nil
   @caches = Hash.new { |h, k| h[k] = Caddy::Cache.new(k) }
+  @needs_fork_check = !Concurrent::TimerSet.private_method_defined?(:ns_reset_if_forked)
 
-  ##
-  # Returns the cache object for key +k+.
+  # Returns the cache object at a key.
   #
   # If the cache at +k+ does not exist yet, Caddy will initialize an empty one.
+  #
+  # @param k [Symbol] the cache key.
+  # @return [Caddy::Cache] the cache object at key +k+.
   def self.[](k)
     @caches[k]
   end
 
-  ##
   # Starts the Caddy refresh processes for all caches.
   #
   # If the refresh process was started pre-fork, Caddy will error out, as this means
@@ -30,27 +38,47 @@ module Caddy
   # Caddy freezes the hash of caches at this point, so no more further caches can be
   # added after start.
   def self.start
-    if !@started_pid
-      @started_pid = $$
-    elsif @started_pid && $$ != @started_pid
-      raise "Please run `Caddy.start` *after* forking, as the refresh thread will get killed after fork"
-    end
-
-    @caches.freeze
+    raise_if_forked if @needs_fork_check
+    logger.info "Starting Caddy with refreshers: #{@caches.keys.join(', ')}"
 
     @caches.values.each(&:start).all?
   end
 
-  ##
   # Cleanly shut down all currently running refreshers.
   def self.stop
+    logger.info "Stopping Caddy refreshers"
+
     @caches.values.each(&:stop).all?
   end
 
-  ##
-  # Start and then stop again all refreshers. Useful for triggering an immediate refresh of all caches.
+  # Start and then stop all refreshers. Useful for triggering an immediate refresh of all caches.
   def self.restart
     stop
     start
   end
+
+  # @!attribute logger
+  #   @return [Logger] logger used for all non-fatals; defaults to the Rails logger if it exists
+  def self.logger
+    @logger ||= begin
+      if defined?(Rails.logger)
+        Rails.logger
+      else
+        @logger ||= Logger.new(STDOUT).tap do |logger|
+          logger.formatter = -> (_, datetime, _, msg) { "#{datetime}: #{msg}\n" }
+        end
+      end
+    end
+  end
+
+  # TODO: when https://github.com/ruby-concurrency/concurrent-ruby/pull/573 is merged, remove this whole block
+  # or add a warning
+  # @private
+  def self.raise_if_forked
+    if !@started_pid
+      @started_pid = $$
+    elsif @started_pid && $$ != @started_pid
+      raise "Please run `Caddy.start` *after* forking, as the refresh thread will get killed after fork"
+    end
+  end
 end

data/lib/caddy/cache.rb

@@ -1,13 +1,27 @@
 # frozen_string_literal: true
 module Caddy
   class Cache
+    # Default refresh interval, in seconds
     DEFAULT_REFRESH_INTERVAL = 60
+
+    # Percentage to randomly smooth the refresh interval to avoid stampeding herd on expiration
     REFRESH_INTERVAL_JITTER_PCT = 0.15
 
-    attr_accessor :refresher, :refresh_interval, :error_handler
+    # @!attribute refresher
+    #   @return [Proc] called on interval {#refresh_interval} with the returned object used as the cache
+    attr_accessor :refresher
+
+    # @!attribute refresh_interval
+    #   @return [Numeric] number of seconds between calls to {#refresher}; timeout is set to <tt>{#refresher} - 0.1</tt>
+    attr_accessor :refresh_interval
 
-    ##
-    # Create a new cache with key +key+.
+    # @!attribute error_handler
+    #   @return [Proc] if unset, defaults to the global error handler (see #{Caddy.error_handler});
+    #   called when exceptions or timeouts happen within the refresher
+    attr_accessor :error_handler
+
+    # Create a new periodically updated cache.
+    # @param key [Symbol] the name of this cache
     def initialize(key)
       @task = nil
       @refresh_interval = DEFAULT_REFRESH_INTERVAL
@@ -15,25 +29,28 @@ module Caddy
       @key = key
     end
 
-    ##
     # Convenience method for getting the value of the refresher-returned object at path +k+,
     # assuming the refresher-returned value responds to <tt>[]</tt>.
     #
-    # If not, #cache can be used instead to access the refresher-returned object.
+    # If not, {#cache} can be used instead to access the refresher-returned object.
+    # @param k key to access from the refresher-returned cache.
     def [](k)
       cache[k]
     end
 
-    ##
     # Returns the refresher-produced value that is used as the cache.
     def cache
       raise "Please run `Caddy.start` before attempting to access the cache" unless @task && @task.running?
-      raise "Caddy cache access of :#{@key} before initial load; allow some more time for your app to start up" unless @cache
+
+      unless @cache
+        logger.warn "Caddy cache access of :#{@key} before initial load; doing synchronous load."\
+                    "Please allow some more time for your app to start up."
+        refresh
+      end
 
       @cache
     end
 
-    ##
     # Starts the period refresh cycle.
     #
     # Every +refresh_interval+ seconds -- smoothed by a jitter amount (a random amount +/- +REFRESH_INTERVAL_JITTER_PCT+) --
@@ -58,22 +75,38 @@ module Caddy
         execution_interval: interval,
         timeout_interval: timeout_interval
       ) do
-        @cache = refresher.call.freeze
-        nil # no need to save the value internally to TimerTask
+        refresh
+        nil # no need for the {#Concurrent::TimerTask} to keep a reference to the value
       end
 
       @task.add_observer(Caddy::TaskObserver.new(error_handler, @key))
+
+      logger.debug "Starting Caddy refresher for :#{@key}, updating every #{interval.round(1)}s."
+
       @task.execute
 
       @task.running?
     end
 
-    ##
     # Stops the current executing refresher.
     #
     # The current cache value is persisted even if the task is stopped.
     def stop
       @task.shutdown if @task && @task.running?
     end
+
+    # Updates the internal cache object.
+    #
+    # Freezes the result to avoid mutation errors.
+    def refresh
+      @cache = refresher.call.freeze
+    end
+
+    private
+
+    # Delegates logging to the module logger
+    def logger
+      Caddy.logger
+    end
   end
 end

data/lib/caddy/task_observer.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 module Caddy
-  class TaskObserver #:nodoc:
+  # {TaskObserver} is used internally to monitor the status of the running refreshers
+  # @private
+  class TaskObserver
     def initialize(error_handler, cache_name)
       @error_handler = error_handler || Caddy.error_handler
       @cache_name = cache_name
@@ -14,28 +16,32 @@ module Caddy
           begin
             @error_handler.call(boom)
           rescue => incepted_boom
-            puts_exception("Caddy error handler itself errored handling refresh for :#{@cache_name}", incepted_boom)
+            log_exception("Caddy error handler itself errored handling refresh for :#{@cache_name}", incepted_boom)
           end
         else
           # rubocop:disable Style/StringLiterals
-          STDERR.puts 'Caddy error handler not callable. Please set the error handler like:'\
-                      ' `Caddy.error_handler = -> (e) { puts "#{e}" }`'
+          logger.error 'Caddy error handler not callable. Please set the error handler like:'\
+                       ' `Caddy.error_handler = -> (e) { puts "#{e}" }`'
           # rubocop:enable Style/StringLiterals
 
-          puts_exception("Caddy refresher for :#{@cache_name} failed with error", boom)
+          log_exception("Caddy refresher for :#{@cache_name} failed with error", boom)
         end
       elsif boom.is_a?(Concurrent::TimeoutError)
-        STDERR.puts "Caddy refresher for :#{@cache_name} timed out"
+        logger.error "Caddy refresher for :#{@cache_name} timed out"
       else
-        puts_exception("Caddy refresher for :#{@cache_name} failed with error", boom)
+        log_exception("Caddy refresher for :#{@cache_name} failed with error", boom)
       end
     end
 
     private
 
-    def puts_exception(msg, boom)
-      STDERR.puts "\n#{msg}: #{boom}"
-      STDERR.puts "\t#{boom.backtrace.join("\n\t")}"
+    def log_exception(msg, boom)
+      logger.error "\n#{msg}: #{boom}"
+      logger.error "\t#{boom.backtrace.join("\n\t")}"
+    end
+
+    def logger
+      Caddy.logger
     end
   end
 end

data/lib/caddy/version.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
 module Caddy
-  VERSION = "1.5.5".freeze
+  # Current version
+  VERSION = "1.6.0".freeze
 end

data/test/caddy_test.rb

@@ -14,6 +14,14 @@ class CaddyTest < Minitest::Test
     sleep(0.05)
   end
 
+  def with_test_logger
+    sio = StringIO.new
+    Caddy.logger = Logger.new(sio)
+    yield
+    Caddy.logger = $test_logger
+    sio.string
+  end
+
   def test_basic_lookup
     Caddy[:test].refresher = -> { {foo: "bar"} }
     Caddy.start
@@ -122,15 +130,23 @@ class CaddyTest < Minitest::Test
   def test_incepted_error_handling
     Caddy[:test].refresher = -> { raise "boom" }
     Caddy.error_handler = -> (_) { raise "boomboom" }
-    Caddy.start
-    sleep(0.1)
+    log_output = with_test_logger do
+      Caddy.start
+      sleep(0.1)
+    end
+
+    assert_match(/Caddy error handler itself errored/, log_output)
   end
 
   def test_bad_error_handler
     Caddy[:test].refresher = -> { raise "boom" }
     Caddy.error_handler = "no"
-    Caddy.start
-    sleep(0.1)
+    log_output = with_test_logger do
+      Caddy.start
+      sleep(0.1)
+    end
+
+    assert_match(/Caddy error handler not callable/, log_output)
   end
 
   def test_timeout
@@ -149,16 +165,27 @@ class CaddyTest < Minitest::Test
   def test_no_handler_timeout
     Caddy[:test].refresher = -> { sleep 1 }
     Caddy[:test].refresh_interval = 0.5
-    Caddy.start
-    sleep(2)
-    Caddy.stop
-    sleep(2)
+
+    log_output = with_test_logger do
+      Caddy.start
+      sleep(2)
+      Caddy.stop
+      sleep(2)
+    end
+
+    assert_match(/timed out/, log_output)
   end
 
   def test_no_handler
     Caddy[:test].refresher = -> { raise "boom" }
     Caddy.start
     sleep(0.1)
+    log_output = with_test_logger do
+      Caddy.start
+      sleep(0.1)
+    end
+
+    assert_match(/failed with error/, log_output)
   end
 
   def test_requires_refesher
@@ -173,6 +200,19 @@ class CaddyTest < Minitest::Test
     assert_raises { Caddy[:nope][:not_there] }
   end
 
+  def test_does_synchronous_load
+    Caddy[:sync].refresher = -> { sleep 1; "sync" }
+
+    assert_raises { Caddy[:sync].cache }
+
+    log_output = with_test_logger do
+      Caddy.start
+      assert_equal "sync", Caddy[:sync].cache
+    end
+
+    assert_match(/doing synchronous load./, log_output)
+  end
+
   def test_requires_positive_interval
     Caddy[:test].refresh_interval = -2
 

data/test/test_helper.rb

@@ -7,3 +7,13 @@ end
 
 require "minitest/autorun"
 require "caddy"
+
+ENV["RACK_ENV"] = ENV["RAILS_ENV"] = "test"
+
+$test_logger = begin
+  l = Logger.new(STDOUT)
+  l.level = Logger::ERROR
+  l
+end
+
+Caddy.logger = $test_logger

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: caddy
 version: !ruby/object:Gem::Version
-  version: 1.5.5
+  version: 1.6.0
 platform: ruby
 authors:
 - Nick Elser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-09-10 00:00:00.000000000 Z
+date: 2016-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -72,7 +72,9 @@ description: |2
       Caddy is great for storing information like feature flags -- accessed extremely frequently during many requests, updated relatively rarely and usually safe to be stale by some small duration.
 email:
 - nick.elser@gmail.com
-executables: []
+executables:
+- console
+- setup
 extensions: []
 extra_rdoc_files: []
 files:
@@ -80,11 +82,14 @@ files:
 - ".gitignore"
 - ".rubocop.yml"
 - ".travis.yml"
+- ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- bin/console
+- bin/setup
 - caddy.gemspec
 - docs/architecture.dot
 - docs/architecture.svg
@@ -121,4 +126,3 @@ summary: Caddy gives you a auto-updating global cache to speed up requests.
 test_files:
 - test/caddy_test.rb
 - test/test_helper.rb
-has_rdoc: