caddy 1.5.4 → 1.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2c6eada3f463107c0237acb6a9df95d25c923658
-  data.tar.gz: d0a85901f32e68fa48e91792896ac0faaea5747e
+  metadata.gz: 1fcc04e3d12bf33c0268a418a46e4d255d8f9e38
+  data.tar.gz: bae67e7130cb5ce2dfd39086c5757e72acf53217
 SHA512:
-  metadata.gz: 42f536651f9799b6edacb11176f1644e1ec9e58911e739ed908922e062d91fafa887c6a48fd5d7fed7dc1a6717f29c94af4d91dc88ba02cc033847e9090b39d1
-  data.tar.gz: 4c10ee82e94ee1d0f5d0002b86d5e567433d1eb9afbfd220818cde2bbacc442629673b2c192d1112d1cf36a0577acc41ca1f8a655c6301375de624ad3be38434
+  metadata.gz: e4fbdcfbf10f665d85497e149f35b418e1f90c79db76e32d78221abdea6a4c66415e5117c64d65fc3c4be5dc6d956ab3b3102f2f39823958d5b415b67978057b
+  data.tar.gz: 5cc6776a9d1060785c3d58f306a53157f9994706799905ab445503e23c6a96bc60fde75c56f6d4f9e7f0d102a35a113c3adf0282a72182208bfcb591c116fb49

data/.rubocop.yml

@@ -1,8 +1,6 @@
 AllCops:
   Exclude:
     - .git/**/*
-    - tmp/**/*
-    - suo.gemspec
 
 Lint/DuplicateMethods:
   Enabled: true

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.5.5
+
+- Add more detailed documentation/comments.
+
 ## 1.5.4
 
 - Some minor wording updates.

data/lib/caddy.rb

@@ -13,14 +13,22 @@ module Caddy
   @started_pid = nil
   @caches = Hash.new { |h, k| h[k] = Caddy::Cache.new(k) }
 
+  ##
+  # Returns the cache object for key +k+.
+  #
+  # If the cache at +k+ does not exist yet, Caddy will initialize an empty one.
   def self.[](k)
     @caches[k]
   end
 
-  def self.caches
-    @caches
-  end
-
+  ##
+  # Starts the Caddy refresh processes for all caches.
+  #
+  # If the refresh process was started pre-fork, Caddy will error out, as this means
+  # the refresh process would have been killed by the fork.
+  #
+  # 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 = $$
@@ -33,10 +41,14 @@ module Caddy
     @caches.values.each(&:start).all?
   end
 
+  ##
+  # Cleanly shut down all currently running refreshers.
   def self.stop
     @caches.values.each(&:stop).all?
   end
 
+  ##
+  # Start and then stop again all refreshers. Useful for triggering an immediate refresh of all caches.
   def self.restart
     stop
     start

data/lib/caddy/cache.rb

@@ -6,6 +6,8 @@ module Caddy
 
     attr_accessor :refresher, :refresh_interval, :error_handler
 
+    ##
+    # Create a new cache with key +key+.
     def initialize(key)
       @task = nil
       @refresh_interval = DEFAULT_REFRESH_INTERVAL
@@ -13,10 +15,17 @@ 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.
     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
@@ -24,6 +33,13 @@ module Caddy
       @cache
     end
 
+    ##
+    # Starts the period refresh cycle.
+    #
+    # Every +refresh_interval+ seconds -- smoothed by a jitter amount (a random amount +/- +REFRESH_INTERVAL_JITTER_PCT+) --
+    # the refresher lambda is called and the results stored in +cache+.
+    #
+    # Note that the result of the refresh is frozen to avoid multithreading mutations.
     def start
       unless refresher && refresher.respond_to?(:call)
         raise "Please set your cache refresher via `Caddy[:#{@key}].refresher = -> { <code that returns a value> }`"
@@ -52,6 +68,10 @@ module Caddy
       @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

data/lib/caddy/task_observer.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 module Caddy
-  class TaskObserver
+  class TaskObserver #:nodoc:
     def initialize(error_handler, cache_name)
       @error_handler = error_handler || Caddy.error_handler
       @cache_name = cache_name

data/lib/caddy/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Caddy
-  VERSION = "1.5.4".freeze
+  VERSION = "1.5.5".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: caddy
 version: !ruby/object:Gem::Version
-  version: 1.5.4
+  version: 1.5.5
 platform: ruby
 authors:
 - Nick Elser