caddy 0.0.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 37c9cbaa3ab3273b12d27046c3723417437e1e6d
-  data.tar.gz: 4111cd80d00e965f691e0eb312d397c7c80bb28a
+  metadata.gz: 58eb0f80fe77ef64649d618a10effebcaf5faadb
+  data.tar.gz: 100273def6d0617b57a299124d7ae2306a4ef19e
 SHA512:
-  metadata.gz: bbbcaed1cee1a6d39f4eec77632679360386de76933e3dabf4160e04948891cc2ef71afa13d8f0afda68509d038034df8d3537b75453c3b66c6f5d057f3c19f7
-  data.tar.gz: 8227f5b289ccb13b667ca407a05ad71aa30d36a195677de1063dc0f3bad7b7144dc95795fcfc35d057ead60b08906580b0a3bc0b2d6a76fb8fcb09c58ebbdeea
+  metadata.gz: 1ea464f973e823fca35892ada3d959c3354a1518b5bac24dca2d0a47cbd8162601a931b03bb774a20f2ffa429cce46f860ab3e45828e8325d473597d96d181c6
+  data.tar.gz: d978a63436d6c3b8f7f79ff49909f5282edb33a5786c7b25ae1ce834e7595c9276031e17fe13ba19a5102db5693d9f439721e8cb0e384d5054b86e1953a361e0

data/.codeclimate.yml

@@ -0,0 +1,16 @@
+---
+engines:
+  duplication:
+    enabled: true
+    config:
+      languages:
+      - ruby
+  fixme:
+    enabled: true
+  rubocop:
+    enabled: true
+ratings:
+  paths:
+  - "**.rb"
+exclude_paths:
+- test/

data/README.md

@@ -1,35 +1,70 @@
-# Caddy (WORK IN PROGRESS)
+# Caddy [![Build Status](https://travis-ci.org/nickelser/caddy.svg?branch=master)](https://travis-ci.org/nickelser/caddy) [![Code Climate](https://codeclimate.com/github/nickelser/caddy/badges/gpa.svg)](https://codeclimate.com/github/nickelser/caddy) [![Test Coverage](https://codeclimate.com/github/nickelser/caddy/badges/coverage.svg)](https://codeclimate.com/github/nickelser/caddy) [![Gem Version](https://badge.fury.io/rb/caddy.svg)](http://badge.fury.io/rb/caddy)
 
-Holds your stuff, and keeps it up to date.
+Caddy is an asynchronously updated store that is updated on an interval to store objects that you can access quickly during requests. The cache refresher function can be as slow as you would like and it will not affect your request-time performance.
+
+It's powered by [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby), a battle-tested and comprehensive thread-based (& thread-safe) concurrency library.
 
 ```ruby
 # in your initializers (caddy.rb would be a wonderful name)
-Caddy.refresher = -> { Hash[SomeKeyValueModel.all.map { |skvm| [skvm.key.to_sym, skvm.value } }
+Caddy.refresher = lambda do
+  {
+    flags: SomeFlagService.fetch_flags, # this can take a few seconds; it won't block requests when you use it later
+    cache_keys: SomeCacheKeyService.cache_keys
+  }
+end
+
 Caddy.refresh_interval = 5.minutes # default is 60 seconds
 
-# ... in your unicorn.rb/puma.rb after fork/start
+# ... after your application forks
 Caddy.start
 
 # ... in a controller
 def index
   # the Caddy requests are instant, and are up-to-date (as of 5 minutes ago, as specified above)
   # you could use this for high-level feature flags, cache dumping
-  if Caddy[:use_the_fast_index]
-    Rails.cache.fetch("#{Caddy[:global_cache_version}/#{Caddy[:foo_index_cache_version}/foo/bar") do
+  if Caddy[:flags][:fuzz_bizz] # Caddy provides a convenience method to access the cache by key; you can also access
+                               # it directly with Caddy.cache[:flags][...]
+    Rails.cache.fetch("#{Caddy[:cache_keys][:global_key]}/#{Caddy[:cache_keys][:index_key]}/foo/bar") do
       # wonderful things happen here
     end
   end
 end
 ```
 
-## Using Caddy with Spring (in development)
+## Using Caddy with Unicorn
+
+You need to start Caddy after fork:
+
+```ruby
+# in your unicorn.rb initializer
+after_fork do |server, worker|
+  Caddy.start
+
+  # ... your magic here
+end
+```
+
+## Using Caddy with Puma
+
+Similarly, after work boot:
+
+```ruby
+# in your puma.rb initializer
+on_worker_boot do |server, worker|
+  Caddy.start
+
+  # ... your magic here
+end
+```
+
+## Using Caddy with Spring
 
-For testing Caddy in development with Spring, you need to have Caddy start after fork:
+In the same vein, with developing with Spring, you need to have Caddy start after fork:
 
 ```ruby
 # in your caddy.rb initializer, perhaps
 
-if Rails.env.development?
+if Rails.env.development? && defined?(Spring)
   Spring.after_fork do
     Caddy.start
   end

data/caddy.gemspec

@@ -8,18 +8,21 @@ Gem::Specification.new do |s|
   s.version       = Caddy::VERSION
   s.authors       = ["Nick Elser"]
   s.email         = ["nick.elser@gmail.com"]
-  s.description   = %q{Caddy gives you a magical auto-updating global cache.}
-  s.summary       = %q{Caddy gives you a magical auto-updating global cache.}
+  s.description   = %q(Caddy gives you a magical auto-updating global cache.)
+  s.summary       = %q(Caddy gives you a magical auto-updating global cache.)
   s.homepage      = "http://github.com/nickelser/caddy"
   s.licenses      = ["MIT"]
 
   s.files         = `git ls-files`.split($/)
-  s.executables   = s.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  s.executables   = s.files.grep(%r{^bin/}).map { |f| File.basename(f) }
   s.test_files    = s.files.grep(%r{^(test|spec|features)/})
   s.require_paths = ["lib"]
 
+  s.required_ruby_version = "~> 2.0"
+
   s.add_dependency "concurrent-ruby"
 
   s.add_development_dependency "rake", "~> 10.5"
   s.add_development_dependency "minitest", "~> 5.0"
+  s.add_development_dependency "codeclimate-test-reporter", "~> 0.4.7"
 end

data/lib/caddy/task_observer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+module Caddy
+  class TaskObserver
+    def update(_, _, boom)
+      return unless boom
+
+      if Caddy.error_handler
+        if Caddy.error_handler.respond_to?(:call)
+          begin
+            Caddy.error_handler.call(boom)
+          rescue => incepted_boom
+            puts_exception("Caddy error handler itself errored", 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}" }`'
+          # rubocop:enable Style/StringLiterals
+
+          puts_exception("Caddy refresher failed with error", boom)
+        end
+      elsif boom.is_a?(Concurrent::TimeoutError)
+        STDERR.puts "Caddy refresher timed out"
+      else
+        puts_exception("Caddy refresher 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")}"
+    end
+  end
+end

data/lib/caddy/version.rb

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

data/lib/caddy.rb

@@ -1,81 +1,67 @@
 # frozen_string_literal: true
 require "caddy/version"
+require "caddy/task_observer"
 require "concurrent/timer_task"
 
 module Caddy
   class << self
-    attr_accessor :refresher, :refresher_error_handler
-    attr_writer :refresh_interval
+    attr_accessor :refresher, :error_handler, :refresh_interval
   end
 
   DEFAULT_REFRESH_INTERVAL = 60
   REFRESH_INTERVAL_JITTER_PCT = 0.15
 
+  @task = nil
+  @refresh_interval = DEFAULT_REFRESH_INTERVAL
+  @_started_pid = nil
+
   def self.[](k)
-    raise "Please run `Caddy.start` before attempting to access values" unless @task
-    raise "Caddy variable access before initial load; allow some more time for your app to start up" unless @task.value
-    @task.value[k]
+    cache[k]
+  end
+
+  def self.cache
+    raise "Please run `Caddy.start` before attempting to access the cache" unless @task
+    raise "Caddy cache access before initial load; allow some more time for your app to start up" unless @task.value
+
+    @task.value
   end
 
   def self.start
-    unless refresher
+    unless refresher && refresher.respond_to?(:call)
       raise "Please set your cache refresher via `Caddy.refresher = -> { <code that returns a value> }`"
     end
 
-    jitter_amount = [1, refresh_interval * REFRESH_INTERVAL_JITTER_PCT].max
+    raise "`Caddy.refresh_interval` must be > 0" unless refresh_interval > 0
+
+    if @_started_pid && $$ != @_started_pid
+      raise "Please run `Caddy.start` *after* forking, as the refresh thread will get killed after fork"
+    end
+
+    jitter_amount = [0.5, refresh_interval * REFRESH_INTERVAL_JITTER_PCT].max
     interval = refresh_interval + rand(-jitter_amount...jitter_amount)
+    timeout_interval = [interval - 1, 0.1].max
 
-    task = Concurrent::TimerTask.new(
+    stop # stop any existing task from running
+
+    @task = Concurrent::TimerTask.new(
       run_now: true,
       execution_interval: interval,
-      timeout_interval: interval - 1) { refresher.call }
+      timeout_interval: timeout_interval
+    ) { refresher.call }
 
-    task.add_observer(InternalCaddyTaskObserver.new)
-    task.execute
+    @task.add_observer(Caddy::TaskObserver.new)
+    @task.execute
 
-    _stop_internal # stop any existing task from running
+    @_started_pid = $$
 
-    @task = task # and transfer over the new task
+    @task.running?
   end
 
   def self.stop
-    raise "Please run `Caddy.start` before running `Caddy.stop`" unless @task
-
-    _stop_internal
-  end
-
-  def self.refresh_interval
-    @refresh_interval || DEFAULT_REFRESH_INTERVAL
-  end
-
-  private_class_method def self._stop_internal
     @task.shutdown if @task && @task.running?
   end
 
-  class InternalCaddyTaskObserver
-    def update(time, _, boom)
-      return unless boom
-
-      if Caddy.refresher_error_handler
-        if Caddy.refresher_error_handler.respond_to?(:call)
-          begin
-            Caddy.refresher_error_handler.call(boom)
-          rescue => incepted_boom
-            STDERR.puts "(#{time}) Caddy error handler itself errored: #{incepted_boom}"
-          end
-        else
-          # rubocop:disable Style/StringLiterals
-          STDERR.puts 'Caddy error handler not callable. Please set the error handler like:'\
-                      ' `Caddy.refresher_error_handler = -> (e) { puts "#{e}" }`'
-          # rubocop:enable Style/StringLiterals
-
-          STDERR.puts "(#{time}) Caddy refresher failed with error #{boom}"
-        end
-      elsif boom.is_a?(Concurrent::TimeoutError)
-        STDERR.puts "(#{time}) Caddy refresher timed out"
-      else
-        STDERR.puts "(#{time}) Caddy refresher failed with error #{boom}"
-      end
-    end
+  def self.restart
+    stop || start
   end
 end

data/test/caddy_test.rb

@@ -1,5 +1,86 @@
-require "minitest/autorun"
-require "caddy"
+require "test_helper"
 
 class CaddyTest < Minitest::Test
+  def setup
+    Caddy.stop
+    Caddy.refresher = -> {}
+    Caddy.refresh_interval = 30
+    Caddy.error_handler = nil
+  end
+
+  def test_basic_lookup
+    Caddy.refresher = -> { {foo: "bar"} }
+    Caddy.start
+    sleep(0.1)
+
+    assert_equal "bar", Caddy[:foo]
+  end
+
+  def test_basic_interval_updating
+    x = 0
+    Caddy.refresher = lambda do
+      x += 1
+      {baz: x}
+    end
+    Caddy.refresh_interval = 2
+    Caddy.start
+    sleep(3)
+
+    assert_operator Caddy[:baz], :>=, 2
+  end
+
+  def test_restart
+    Caddy.refresher = -> { {foo: "baz"} }
+    Caddy.start
+    sleep(0.1)
+    Caddy.stop
+    Caddy.restart
+
+    assert_equal "baz", Caddy[:foo]
+  end
+
+  def test_error_handling
+    reported = nil
+    Caddy.refresher = -> { raise "boom" }
+    Caddy.error_handler = -> (ex) { reported = ex }
+    Caddy.start
+    sleep(0.1)
+
+    assert_equal "boom", reported.message
+  end
+
+  def test_incepted_error_handling
+    Caddy.refresher = -> { raise "boom" }
+    Caddy.error_handler = -> (_) { raise "boomboom" }
+    Caddy.start
+  end
+
+  def test_bad_error_handler
+    Caddy.refresher = -> { raise "boom" }
+    Caddy.error_handler = "no"
+    Caddy.start
+  end
+
+  def test_timeout
+    Caddy.refresher = -> { sleep 5 }
+    Caddy.refresh_interval = 1
+    Caddy.start
+  end
+
+  def test_no_handler
+    Caddy.refresher = -> { raise "boom" }
+    Caddy.start
+  end
+
+  def test_requires_refesher
+    Caddy.refresher = nil
+
+    assert_raises { Caddy.start }
+  end
+
+  def test_requires_positive_interval
+    Caddy.refresh_interval = -2
+
+    assert_raises { Caddy.start }
+  end
 end

data/test/test_helper.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
+
+if ENV["CODECLIMATE_REPO_TOKEN"]
+  require "codeclimate-test-reporter"
+  CodeClimate::TestReporter.start
+end
+
+require "minitest/autorun"
+require "caddy"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: caddy
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Nick Elser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-09-02 00:00:00.000000000 Z
+date: 2016-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: codeclimate-test-reporter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.7
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.7
 description: Caddy gives you a magical auto-updating global cache.
 email:
 - nick.elser@gmail.com
@@ -59,6 +73,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".codeclimate.yml"
 - ".gitignore"
 - ".rubocop.yml"
 - ".travis.yml"
@@ -68,8 +83,10 @@ files:
 - Rakefile
 - caddy.gemspec
 - lib/caddy.rb
+- lib/caddy/task_observer.rb
 - lib/caddy/version.rb
 - test/caddy_test.rb
+- test/test_helper.rb
 homepage: http://github.com/nickelser/caddy
 licenses:
 - MIT
@@ -80,9 +97,9 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -96,4 +113,5 @@ specification_version: 4
 summary: Caddy gives you a magical auto-updating global cache.
 test_files:
 - test/caddy_test.rb
+- test/test_helper.rb
 has_rdoc: