virginia 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 07e0d2abf4237b76b1f56162e819f4fd997d811b
-  data.tar.gz: ebd38ebbd3ffb59194c3d5c89ba60be8f66b5241
+  metadata.gz: ecea8b6d003b01938bc430ec0dff8dd07d43f84e
+  data.tar.gz: ffa4a6fe704ae8de52f36aad3a01f168ebaacb22
 SHA512:
-  metadata.gz: 2edaea0ae04deae86d67912d3169c3d502b6dc9c1cb85b436065c39eb6d06d9ae105d18b6d5eecd1ee0b9c2236d5a262cec16e171dcf0a33b80259396611e0b9
-  data.tar.gz: b2f943bda56a7a176448eb6c9e64e66ef2d027bcc97a8baf80736629a96e49eb37bd17cc1d62e66274d5951c38b8479103e426cac1506838e6186b2fc34c0b89
+  metadata.gz: e76fcf59abbe5d17776ada161021491489ad9c81667f1f5baba592463a8873eb023c69fbc0927316fb46ed051ea07ccb15dc04977c0dd8e1833504259b1b648e
+  data.tar.gz: 7f793657d6ee01f31246fff65fdaf4a79cdf2a3bec287df951df0a10f7b3528dc227a9db252a600a098374cfa4b5cde4d469b8b190a01c3da9329c7762712224

data/.rspec

@@ -0,0 +1 @@
+--format documentation

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+# develop
+
+# Version 0.4.0
+  * BREAKING CHANGES! See the updated example in the README and the changes described below:
+  * Support for storing document content-types associated with each cached document. You must now specify the content type (or use the default of text/plain) when caching a document. This way Virginia knows how to serve it when it is requested.
+  * Wrap cached documents and store them as Virginia::DocumentCache::Document. The wrapped document is what will be returned from the cache.
+  * DocumentCache#fetch no longer accepts a `lifetime` argument. Instead, return an array of arguments suitable for passing to `#store` from the block, or return a complete DocumentCache::Document
+  * Switch DocumentCache to an Actor for better performance
+  * Load & start DocumentCache's actor by default
+  * Allow registering a document ID with a callback to populate it on demand
+
 # Version 0.4.0
   * Add document cache
 

data/Guardfile

@@ -1,4 +1,4 @@
-guard 'rspec', :version => 2, :cli => '--format documentation' do
+guard 'rspec', cmd: 'bundle exec rspec' do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
   watch('spec/spec_helper.rb')  { "spec/" }

data/README.md

@@ -57,16 +57,15 @@ Assuming you are using Sinatra like in the above examples, put this in your `lib
 
 ```Ruby
 require 'sinatra'
-require 'virginia/document_cache'
 
 get '/documents/:id' do
   begin
-    grammar = Virginia::DocumentCache.fetch params[:id]
+    document = Virginia::DocumentCache.fetch params[:id]
+    headers['Content-Type'] = document.content_type
+    document.body
   rescue Virginia::DocumentCache::NotFound
     raise Sinatra::NotFound
   end
-
-  grammar.to_s
 end
 ```
 

data/lib/virginia.rb

@@ -1,11 +1,10 @@
 require "adhearsion"
-require "active_support/dependencies/autoload"
-require "virginia/version"
-require "virginia/plugin"
+%w(
+  version
+  plugin
+  service
+  document_cache
+).each { |file| require "virginia/#{file}" }
 
 module Virginia
-  extend ActiveSupport::Autoload
-  autoload :Plugin
-  autoload :Service
-  autoload :LoggingHandler
 end

data/lib/virginia/document_cache.rb

@@ -1,29 +1,31 @@
 # encoding: utf-8
 require 'singleton'
+require 'virginia/document_cache/document'
 
 module Virginia
   class DocumentCache
-    include Singleton
+    include Celluloid
 
     NotFound = Class.new StandardError
 
-    attr_reader :mutex
+    DEFAULT_CONTENT_TYPE = 'text/plain'
+    DEFAULT_LIFETIME = 10
+
+    execute_block_on_receiver :register, :send
 
     class << self
       def method_missing(m, *args, &block)
-        instance.mutex.synchronize do
-          instance.send m, *args, &block
-        end
+        Celluloid::Actor[:virginia_document_cache].send m, *args, &block
       end
     end
 
     def initialize
-      @mutex = Mutex.new
       @documents = {}
+      @document_creators = {}
 
-      supervisor = Housekeeping.supervise_as :document_cache_housekeeping
-      Adhearsion::Events.register_callback :shutdown do
-        supervisor.terminate
+      every(60) do
+        logger.debug "Reaping expired cached document"
+        reap_expired!
       end
     end
 
@@ -31,56 +33,82 @@ module Virginia
     # @param [Object] document The document to be stored in the cache
     # @param [Fixnum, Nil] lifetime The amount of time in seconds the document should be kept. If nil, document will be kept indefinitely.
     # @param [String, Nil] id The ID to use to store the document. If nil, one will be generated.
-    # @return [String] ID of the stored document
-    def store(document, lifetime = 10, id = nil)
+    # @return [String] Cache ID of the stored document
+    def store(document, content_type = DEFAULT_CONTENT_TYPE, lifetime = DEFAULT_LIFETIME, id = nil)
+      return if document.nil? || document.to_s.empty?
+
       id ||= generate_id
-      @documents[id] = {
-        document: document,
-        expires: lifetime ? Time.now + lifetime : nil
-      }
-      id
+      doc = Virginia::DocumentCache::Document.new id, document, content_type, lifetime
+      store_document doc
+    end
+
+    # Registers a new Virginia::DocumentCache::Document with the cache
+    # @param [Virginia::DocumentCache::Document] document The document to be stored in the cache
+    # @return [String] Cache ID of the stored document
+    def store_document(document)
+      @documents[document.id] =  document
+      document.id
     end
 
     # Deletes a document from the cache
     # @param [Object] id ID of the document to be removed from the cache
     # @return [Object, Nil] document Returns the document if found in the cache, nil otherwise
     def delete(id)
-      data = @documents.delete id
-      data[:document]
+      @documents.delete id
     end
 
     # Retrieves a document from the cache
     # @param [String] id ID of the document to be retrieved from the cache
-    # @param [Fixnum, Nil] lifetime The amount of time in seconds the document should be kept. If nil, document will be kept indefinitely.
     # @yield If given, will be used to generate the document, store it, and then return.
-    # @return [Object] document Returns the document if found in the cache
-    # @raises [NotFound] If the document is not found in the cache
-    def fetch(id, lifetime = 10)
+    # @return [Virginia::DocumentCache::Document] Returns the document if found in the cache
+    # @raises [Virginia::DocumentCache::NotFound] If the document is not found in the cache
+    def fetch(id)
+      # Check for a registered creator first
+      check_and_run_creator id unless @documents.has_key? id
+
+      # If we still don't have a document, check for a supplied block
       unless @documents.has_key? id
+
         if block_given?
-          store yield, lifetime, id
+          result = yield
+          if result.is_a? Document
+            store_document result
+          else
+            args = *yield
+            doc = Virginia::DocumentCache::Document.new id, args[0], args[1] || DEFAULT_CONTENT_TYPE, args[2] || DEFAULT_LIFETIME
+            store_document doc
+          end
         else
-          raise NotFound
+          abort NotFound.new
         end
       end
-      
-      @documents[id][:document]
+
+      @documents[id]
     end
 
-    def reap_expired!
-      @documents.each_pair do |id, data|
-        @documents.delete(id) if data[:expires] < Time.now
-      end
+    # Registers a creation callback to populate a given document when requested
+    # @param [String] id ID of the document for which the creator should be registered
+    # @param [String] content_type Content-Type of the document
+    # @param [Fixnum, Nil] lifetime The amount of time in seconds the document should be kept. If nil, document will be kept indefinitely.
+    # @return [Nil, Object] nil if the ID was not found among the creators; otherwise the creator is returned
+    def register(id, content_type, lifetime = DEFAULT_LIFETIME, &callback)
+      @document_creators[id] = {
+        content_type: content_type,
+        lifetime: lifetime,
+        callback: callback,
+      }
     end
 
-    class Housekeeping
-      include Celluloid
+    # Removes a document creator registration by ID
+    # @param [String] id ID of the document for which the creator should be deleted
+    # @return [Nil, Object] nil if the ID was not found among the creators; otherwise the creator is returned
+    def unregister(id)
+      @document_creators.delete id
+    end
 
-      def initialize
-        every(1.minute) do
-          logger.debug "Reaping expired cached document"
-          DocumentCache.reap_expired!
-        end
+    def reap_expired!
+      @documents.each_pair do |id, doc|
+        @documents.delete(id) if doc.expires_at && doc.expires_at < Time.now
       end
     end
 
@@ -89,5 +117,15 @@ module Virginia
     def generate_id
       SecureRandom.hex(16)
     end
+
+    def check_and_run_creator(id)
+      if creator = @document_creators[id]
+        begin
+          store_document Document.new id, creator[:callback].call, creator[:content_type], creator[:lifetime]
+        rescue => e
+          abort e
+        end
+      end
+    end
   end
 end

data/lib/virginia/document_cache/document.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+module Virginia
+  class DocumentCache
+    class Document < Struct.new(:id, :body, :content_type, :lifetime, :created_at, :expires_at)
+      def initialize(id, body, content_type = 'text/plain', lifetime = nil)
+        self.id, self.body, self.content_type, self.lifetime = id, body, content_type, lifetime
+        self.created_at = Time.now
+        if self.lifetime
+          self.expires_at = self.created_at + self.lifetime
+        end
+      end
+    end
+  end
+end

data/lib/virginia/plugin.rb

@@ -6,6 +6,12 @@ module Virginia
     run :virginia do
       logger.info "Virginia has been loaded"
       Service.start
+
+      # Document Cache
+      supervisor = Virginia::DocumentCache.supervise_as(:virginia_document_cache)
+      Adhearsion::Events.register_callback :shutdown do
+        supervisor.terminate
+      end
     end
 
     config :virginia do

data/lib/virginia/version.rb

@@ -1,3 +1,3 @@
 module Virginia
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/spec/spec_helper.rb

@@ -1,13 +1,18 @@
 require 'adhearsion'
 require 'virginia'
+require 'timecop'
 
 ENV['AHN_ENV'] = 'test'
 
 RSpec.configure do |config|
-  config.color_enabled = true
+  config.color = true
   config.tty = true
 
   config.filter_run :focus => true
   config.run_all_when_everything_filtered = true
+
+  config.after :each do
+    Timecop.return
+  end
 end
 

data/spec/virginia/document_cache/document_spec.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+require 'spec_helper'
+
+describe Virginia::DocumentCache::Document do
+  let(:subject) { Virginia::DocumentCache::Document }
+
+  before :each do
+    Timecop.freeze
+    @document = subject.new 'fake_id', 'fake_content'
+  end
+
+  it 'should accurately represent my content' do
+    expect(@document.body).to eq 'fake_content'
+  end
+
+  it 'should automatically set the created_at time' do
+    expect(@document.created_at).to eq Time.now
+  end
+
+  it 'should default to an empty expiration time' do
+    expect(@document.expires_at).to be_nil
+  end
+
+  it 'should automatically determine the expiration time' do
+    # TODO: Use Timecop to make this test more precise
+    doc = subject.new '1', 'foo', 'text/plain', 30
+    expect(doc.expires_at).to eq Time.now + 30
+  end
+end

data/spec/virginia/document_cache_spec.rb

@@ -0,0 +1,144 @@
+# encoding: utf-8
+require 'spec_helper'
+require 'virginia/document_cache'
+
+describe Virginia::DocumentCache do
+  let(:subject) { Virginia::DocumentCache.new }
+
+  it 'should store the document and return the ID' do
+    expect(subject.store('foo')).to be_a String
+  end
+
+  it 'should not store a nil document' do
+    expect(subject.store(nil)).to be_nil
+  end
+
+  it 'should not store an empty string document' do
+    expect(subject.store("")).to be_nil
+  end
+
+  it 'should allow me to retrieve the document by ID' do
+    doc = 'foobar'
+    id = subject.store doc
+    expect(subject.fetch(id).body).to eq doc
+  end
+
+  it 'should allow me to store and retrieve a document with a specified ID' do
+    subject.store 'foobar', 'text/plain', nil, 'abc123'
+    expect(subject.fetch('abc123').body).to eq 'foobar'
+  end
+
+  it 'should store the document content type' do
+    id = subject.store '{foo: "bar"}', 'application/json'
+    expect(subject.fetch(id).content_type).to eq 'application/json'
+  end
+
+  it 'should allow me to specify a lifetime' do
+    Timecop.freeze
+    id = subject.store 'foobar', 'text/plain', 30
+    doc = subject.fetch id
+    expect(doc.expires_at).to eq Time.now + 30
+  end
+
+  it 'should allow documents that do not expire' do
+    Timecop.freeze
+    id = subject.store 'foobar', 'text/plain', nil
+    doc = subject.fetch id
+    expect(doc.expires_at).to be nil
+    Timecop.travel Time.now + (20 * 365 * 24 * 60 * 60) # 20 years
+    subject.reap_expired!
+    doc = subject.fetch id
+    expect(doc.body).to eq 'foobar'
+  end
+
+  it 'should remove (only) expired documents from the cache' do
+    Timecop.freeze
+    id1 = subject.store 'foobar', 'text/plain', 30
+    id2 = subject.store 'bazqux', 'text/plain', 90
+    Timecop.travel Time.now + 60
+    subject.reap_expired!
+
+    expect { subject.fetch(id1) }.to raise_error Virginia::DocumentCache::NotFound
+    expect(subject.fetch(id2).body).to eq 'bazqux'
+  end
+
+  context 'auto-creation on #fetch' do
+    let(:doc_id) { 'boo' }
+    let(:body) { 'abcd' }
+    let(:ctype) { 'text/plain' }
+    let(:lifetime) { 93 }
+
+    before :each do
+      Timecop.freeze
+      expect { subject.fetch(doc_id) }.to raise_error Virginia::DocumentCache::NotFound
+    end
+
+    after :each do
+      doc = subject.fetch doc_id
+      expect(doc.body).to eq body
+      expect(doc.content_type).to eq ctype
+      expect(doc.expires_at).to eq Time.now + lifetime
+    end
+
+    it 'should allow me to supply a block to #store and create a document if one is not already cached' do
+      subject.fetch(doc_id) do
+        [body, 'text/plain', lifetime]
+      end
+    end
+
+    it 'should allow me to supply a block to #store that returns a document and cache it, if one is not already cached' do
+      subject.fetch(doc_id) do
+        Virginia::DocumentCache::Document.new doc_id, body, ctype, lifetime
+      end
+    end
+  end
+
+  context 'registering document content at an id' do
+    let(:doc_id) { 'abcd1234' }
+    let(:body) { 'once upon a time there was a muppet' }
+    let(:ctype) { 'application/x-powa' }
+    let(:lifetime) { 193 }
+
+    before :each do
+      expect { subject.fetch(doc_id) }.to raise_error Virginia::DocumentCache::NotFound
+      Timecop.freeze
+    end
+
+    context 'auto-creating documents' do
+      after :each do
+        doc = subject.fetch doc_id
+        expect(doc.body).to eq body
+        expect(doc.content_type).to eq ctype
+        expect(doc.expires_at).to eq Time.now + lifetime
+      end
+
+      it 'should auto-populate the document if not found in the cache' do
+        subject.register(doc_id, ctype, lifetime) do
+          body
+        end
+      end
+
+      it 'should not invoke the block if the document is already in the cache' do
+        subject.store body, ctype, lifetime, doc_id
+        subject.register(doc_id, ctype, lifetime) do
+          raise "Should not get here!"
+        end
+      end
+    end
+
+    it 'should allow removing a document creator' do
+      Timecop.freeze
+      subject.register(doc_id, ctype, lifetime) do
+        body
+      end
+      doc = subject.fetch(doc_id)
+
+      # Move past expiration and clean up the cached document
+      Timecop.travel Time.now + (lifetime + 1)
+      subject.reap_expired!
+
+      subject.unregister(doc_id)
+      expect { subject.fetch(doc_id) }.to raise_error Virginia::DocumentCache::NotFound
+    end
+  end
+end

data/spec/virginia/service_spec.rb

@@ -18,7 +18,7 @@ describe Virginia::Service do
   end
 
   it "should instantiate the handler" do
-    rack_logger = mock 'Rack::CommonLogger'
+    rack_logger = double 'Rack::CommonLogger'
     ::Rack::CommonLogger.should_receive(:new).once.with(TestApp, Adhearsion.logger).and_return rack_logger
     ::Reel::Rack::Server.should_receive(:supervise_as).once.with(:reel_rack_server, rack_logger, options)
     Virginia::Service.start

data/virginia.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.require_paths = ["lib"]
 
-  s.add_runtime_dependency %q<adhearsion>, ["~> 2.4"]
+  s.add_runtime_dependency %q<adhearsion>, ["~> 2.6"]
   s.add_runtime_dependency %q<activesupport>, [">= 3.0"]
   s.add_runtime_dependency %q<reel>, ["~> 0.5.0"]
   s.add_runtime_dependency %q<reel-rack>
@@ -25,5 +25,6 @@ Gem::Specification.new do |s|
   s.add_development_dependency %q<bundler>, ["~> 1.0"]
   s.add_development_dependency %q<rspec>, ["~> 2.5"]
   s.add_development_dependency %q<rake>, [">= 0"]
+  s.add_development_dependency %q<timecop>
   s.add_development_dependency %q<guard-rspec>
  end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: virginia
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Luca Pradovera
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-27 00:00:00.000000000 Z
+date: 2015-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: adhearsion
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '2.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '2.6'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +108,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: guard-rspec
   requirement: !ruby/object:Gem::Requirement
@@ -131,6 +145,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rspec"
 - ".travis.yml"
 - CHANGELOG.md
 - Gemfile
@@ -140,11 +155,14 @@ files:
 - Rakefile
 - lib/virginia.rb
 - lib/virginia/document_cache.rb
+- lib/virginia/document_cache/document.rb
 - lib/virginia/plugin.rb
 - lib/virginia/service.rb
 - lib/virginia/version.rb
 - spec/fixtures/config.ru
 - spec/spec_helper.rb
+- spec/virginia/document_cache/document_spec.rb
+- spec/virginia/document_cache_spec.rb
 - spec/virginia/service_spec.rb
 - tmp/dsl.rb
 - tmp/example.rb
@@ -168,11 +186,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: virginia
-rubygems_version: 2.4.6
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: A Reel interface to Adhearsion
 test_files:
 - spec/fixtures/config.ru
 - spec/spec_helper.rb
+- spec/virginia/document_cache/document_spec.rb
+- spec/virginia/document_cache_spec.rb
 - spec/virginia/service_spec.rb