moneta 1.4.0 → 1.5.0

data/README.md

@@ -1,7 +1,7 @@
 # Moneta: A unified interface for key/value stores
 
 [![Gem Version](https://badge.fury.io/rb/moneta.svg)](http://rubygems.org/gems/moneta)
-[![Build Status](https://secure.travis-ci.org/moneta-rb/moneta.svg?branch=master)](http://travis-ci.org/moneta-rb/moneta)
+[![Build Status](https://github.com/moneta-rb/moneta/actions/workflows/ruby.yml/badge.svg)](https://github.com/moneta-rb/moneta/actions/workflows/ruby.yml)
 [![Code Climate](https://codeclimate.com/github/moneta-rb/moneta.svg)](https://codeclimate.com/github/moneta-rb/moneta)
 [![Flattr this git repo](http://api.flattr.com/button/flattr-badge-large.png)](https://flattr.com/submit/auto?user_id=min4d&url=https://github.com/moneta-rb/moneta&title=Moneta&language=&tags=github&category=software)
 
@@ -32,7 +32,7 @@ same for template languages.
 * Give people a starting point or example code to start working with their favourite key/value store. Feel free to copy code, please mention Moneta then :)
 * Create a reusable piece of code, since similar things are solved over and over again ([Rails](http://rubyonrails.org/) brings its own cache stores, and many frameworks do the same...)
 
-Moneta is tested thoroughly using [Travis-CI](http://travis-ci.org/moneta-rb/moneta).
+Moneta is tested thoroughly using [GitHub Actions](https://github.com/moneta-rb/moneta/actions).
 
 ------
 
@@ -74,11 +74,11 @@ store.close
 
 * Source: <http://github.com/moneta-rb/moneta>
 * Bugs:   <http://github.com/moneta-rb/moneta/issues>
-* Tests and benchmarks: <http://travis-ci.org/moneta-rb/moneta>
+* Tests and benchmarks: <https://github.com/moneta-rb/moneta/actions>
 * API documentation:
     * Latest Gem: <http://rubydoc.info/gems/moneta/frames>
-    * GitHub master: <http://rubydoc.info/github/moneta-rb/moneta/master/frames>
-* Changelog: <https://github.com/moneta-rb/moneta/blob/master/CHANGES>
+    * GitHub main: <http://rubydoc.info/github/moneta-rb/moneta/main/frames>
+* Changelog: <https://github.com/moneta-rb/moneta/blob/main/CHANGES>
 
 In case you are wondering, Moneta uses [Semantic Versioning](https://semver.org/) since v1.0.0.
 
@@ -135,7 +135,7 @@ to upgrade to a real key/value store.
 
 ### Backend feature matrix
 
-__NOTE:__ <a name="backend-matrix"></a>The backend matrix is much more readable on rubydoc.info than on github. [Go there!](http://rubydoc.info/github/moneta-rb/moneta/master/file/README.md#backend-matrix)
+__NOTE:__ <a name="backend-matrix"></a>The backend matrix is much more readable on rubydoc.info than on github. [Go there!](http://rubydoc.info/github/moneta-rb/moneta/main/file/README.md#backend-matrix)
 
 <table>
 <tr><th>Adapter</th><th>Required gems</th><th style="writing-mode:tb">MRI support<sup>1</sup></th><th style="writing-mode:tb">JRuby support<sup>1</sup></th><th style="writing-mode:tb">Multi-thread safe<sup>2</sup></th><th style="writing-mode:tb">Multi-process safe<sup>3</sup></th><th style="writing-mode:tb">Atomic increment<sup>4</sup></th><th style="writing-mode:tb">Atomic create<sup>5</sup></th><th style="writing-mode:tb">Native expires<sup>6</sup></th><th style="writing-mode:tb">Persistent</th><th style="writing-mode:tb">Key Traversal</th><th style="writing-mode:tb">Bulk read<sup>7</sup></th><th style="writing-mode:tb">Bulk write<sup>8</sup></th><th>Description</th></tr>
@@ -221,7 +221,9 @@ __NOTE:__ <a name="backend-matrix"></a>The backend matrix is much more readable
 3. Share a Moneta store between multiple processes using `Moneta::Shared` (See below).
 4. If a store provides atomic increment it can be used with `Moneta::Semaphore`. You can add weak `#increment` support using the `Moneta::WeakIncrement` proxy.
 5. If a store provides atomic creation it can be used with `Moneta::Mutex`. You can add weak `#create` support using the `Moneta::WeakCreate` proxy.
-6. Add expiration support by using `Moneta::Expires` or by passing the option `expires: true` to `Moneta#new`.
+6. Add expiration support by using `Moneta::Expires` or by passing the option
+   `expires: true` (or `expires: <seconds>` if you want all values to expire by
+   default) to `Moneta#new`.
 7. This indicates that there is some performance gain when fetching multiple values at once using `#values_at`/`#fetch_values` or `#slice`. For instance, the `MGET` instruction in Redis, or the ability to retrieve several rows in one query in SQL.
 8. This indicates that there is some performance gain when storing multiple key/value pairs at once using `#merge!`/`#update`.
 9. Sqlite/YAML/PStore are multiprocess safe, but the performance suffers badly since the whole database file must be locked for writing. Use a key/value server if you want multiprocess concurrency!
@@ -909,15 +911,17 @@ Person.adapter :memory, Moneta.new(:Redis)
 
 ## Testing and Benchmarks
 
-Testing is done using [Travis-CI](http://travis-ci.org/moneta-rb/moneta).
-Currently we support MRI Ruby >= 2.3.0 and the JRuby >= 9.2.9.0.
+Testing is done using [GitHub Actions](https://github.com/moneta-rb/moneta/actions).
+Currently we support MRI Ruby >= 2.4.0 (but not yet 3.x) and the JRuby >=
+9.2.9.0. MRI 2.3.0 should mostly still work, but is no longer tested in CI.
 
-Benchmarks for each store are done on
-[Travis-CI](http://travis-ci.org/moneta-rb/moneta) for each build. Take a look
-there to compare the speed of the different key value stores for different
-key/value sizes and size distributions.  Feel free to add your own
-configurations! The impact of Moneta should be minimal since it is only a thin
-layer on top of the different stores.
+~~Benchmarks for each store are done on
+[Travis-CI](http://travis-ci.org/moneta-rb/moneta) for each build.~~  At the
+time of writing, benchmarks still need to be migrated from Travis to GitHub
+Actions.  Take a look there to compare the speed of the different key value
+stores for different key/value sizes and size distributions.  Feel free to add
+your own configurations! The impact of Moneta should be minimal since it is
+only a thin layer on top of the different stores.
 
 
 ------
@@ -937,8 +941,8 @@ If you want support for another adapter you can at first at it to the list of
 missing adapters at https://github.com/moneta-rb/moneta/issues/16
 
 If you choose to implement an adapter please also add tests.  Please check also
-if travis.yml needs changes, for example if you need to start additional
-services.
+if anything in `.github/workflows` needs changes, for example if you need to
+start additional services.
 
 Check if the default settings in Moneta#new are appropriate for your adapter. If
 not specify a better one.

data/lib/moneta/adapter.rb

@@ -0,0 +1,52 @@
+module Moneta
+  # Adapter base class
+  # @api public
+  class Adapter
+    include Defaults
+    include Config
+
+    attr_reader :backend
+
+    class << self
+      # Define a block used to build this adapter's backend.  The block will
+      # receive as keyword arguments any options passed to the adapter during
+      # initialization that are not config settings.
+      #
+      # If the adapter is initialized with a `:backend` option, this will be used
+      # instead, and the block won't be called.
+      #
+      # @param [Boolean] required
+      # @yield [**options] options passed to the adapter's initialize method
+      # @yieldreturn [Object] The backend to use
+      def backend(required: true, &block)
+        raise "backend block already set" if class_variables(false).include?(:@@backend_block)
+        class_variable_set(:@@backend_block, block)
+        class_variable_set(:@@backend_required, true) if required
+      end
+
+      def backend_block
+        class_variable_get(:@@backend_block) if class_variable_defined?(:@@backend_block)
+      end
+
+      def backend_required?
+        class_variable_defined?(:@@backend_required)
+      end
+    end
+
+    # @param [Hash] options
+    def initialize(options = {})
+      set_backend(**configure(**options))
+    end
+
+    private
+
+    def set_backend(backend: nil, **options)
+      @backend = backend ||
+        if backend_block = self.class.backend_block
+          instance_exec(**options, &backend_block)
+        end
+
+      raise ArgumentError, 'backend needs to be set - refer to adapter documentation' if !@backend && self.class.backend_required?
+    end
+  end
+end

data/lib/moneta/adapters/activerecord.rb

@@ -5,12 +5,10 @@ module Moneta
   module Adapters
     # ActiveRecord as key/value stores
     # @api public
-    class ActiveRecord
-      include Defaults
-
+    class ActiveRecord < Adapter
       supports :create, :increment, :each_key
 
-      attr_reader :table, :key_column, :value_column
+      attr_reader :table
       delegate :with_connection, to: :connection_pool
 
       @connection_lock = ::Mutex.new
@@ -37,9 +35,30 @@ module Moneta
         end
       end
 
+      config :key_column, default: :k
+      config :value_column, default: :v
+
+      backend required: false do |table: :moneta, connection: nil, create_table: nil|
+        @spec = spec_for_connection(connection)
+
+        # Ensure the table name is a symbol.
+        table_name = table.to_sym
+
+        if create_table == nil
+          default_create_table(table_name)
+        elsif create_table
+          with_connection(&create_table)
+        end
+
+        @table = ::Arel::Table.new(table_name)
+
+        # backend is only used if there's an existing ActiveRecord model
+        nil
+      end
+
       # @param [Hash] options
       # @option options [Object]               :backend A class object inheriting from ActiveRecord::Base to use as a table
-      # @option options [String]               :table ('moneta') Table name
+      # @option options [String,Symbol]        :table (:moneta) Table name
       # @option options [Hash/String/Symbol]   :connection ActiveRecord connection configuration (`Hash` or `String`), or
       #   symbol giving the name of a Rails connection (e.g. :production)
       # @option options [Proc, Boolean]        :create_table Proc called with a connection if table
@@ -47,54 +66,12 @@ module Moneta
       # @option options [Symbol]               :key_column (:k) The name of the column to use for keys
       # @option options [Symbol]               :value_column (:v) The name of the column to use for values
       def initialize(options = {})
-        @key_column = options.delete(:key_column) || :k
-        @value_column = options.delete(:value_column) || :v
+        super
 
-        if backend = options.delete(:backend)
+        # If a :backend was provided, use it to set the spec and table
+        if backend
           @spec = backend.connection_pool.spec
-          @table = ::Arel::Table.new(backend.table_name.to_sym)
-        else
-          # Feed the connection info into ActiveRecord and get back a name to use for getting the
-          # connection pool
-          connection = options.delete(:connection)
-          @spec =
-            case connection
-            when Symbol
-              connection
-            when Hash, String
-              # Normalize the connection specification to a hash
-              resolver = ::ActiveRecord::ConnectionAdapters::ConnectionSpecification::Resolver.new \
-                'dummy' => connection
-
-              # Turn the config into a standardised hash, sans a couple of bits
-              hash = resolver.resolve(:dummy)
-              hash.delete('name')
-              hash.delete(:password) # For security
-              # Make a name unique to this config
-              name = 'moneta?' + URI.encode_www_form(hash.to_a.sort)
-              # Add into configurations unless its already there (initially done without locking for
-              # speed)
-              unless self.class.configurations.key? name
-                self.class.connection_lock.synchronize do
-                  self.class.configurations[name] = connection \
-                    unless self.class.configurations.key? name
-                end
-              end
-
-              name.to_sym
-            else
-              ::ActiveRecord::Base.connection_pool.spec.name.to_s
-            end
-
-          table_name = (options.delete(:table) || :moneta).to_sym
-          create_table_proc = options.delete(:create_table)
-          if create_table_proc == nil
-            create_table(table_name)
-          elsif create_table_proc
-            with_connection(&create_table_proc)
-          end
-
-          @table = ::Arel::Table.new(table_name)
+          @table = ::Arel::Table.new(backend.table_name)
         end
       end
 
@@ -110,8 +87,8 @@ module Moneta
       # (see Proxy#each_key)
       def each_key(&block)
         with_connection do |conn|
-          return enum_for(:each_key) { conn.select_value(arel_sel.project(table[key_column].count)) } unless block_given?
-          conn.select_values(arel_sel.project(table[key_column])).each { |k| yield(k) }
+          return enum_for(:each_key) { conn.select_value(arel_sel.project(table[config.key_column].count)) } unless block_given?
+          conn.select_values(arel_sel.project(table[config.key_column])).each { |k| yield(k) }
         end
         self
       end
@@ -136,10 +113,10 @@ module Moneta
       def delete(key, options = {})
         with_connection do |conn|
           conn.transaction do
-            sel = arel_sel_key(key).project(table[value_column]).lock
+            sel = arel_sel_key(key).project(table[config.value_column]).lock
             value = decode(conn, conn.select_value(sel))
 
-            del = arel_del.where(table[key_column].eq(key))
+            del = arel_del.where(table[config.key_column].eq(key))
             conn.delete(del)
 
             value
@@ -155,7 +132,7 @@ module Moneta
             amount
           rescue ::ActiveRecord::RecordNotUnique
             conn.transaction do
-              sel = arel_sel_key(key).project(table[value_column]).lock
+              sel = arel_sel_key(key).project(table[config.value_column]).lock
               value = decode(conn, conn.select_value(sel))
               value = (value ? Integer(value) : 0) + amount
               # Re-raise if the upate affects no rows (i.e. row deleted after attempted insert,
@@ -213,13 +190,13 @@ module Moneta
 
             sel = arel_sel
               .join(temp_table)
-              .on(table[key_column].eq(temp_table[:key]))
-              .project(table[key_column], table[value_column])
+              .on(table[config.key_column].eq(temp_table[:key]))
+              .project(table[config.key_column], table[config.value_column])
             sel = sel.lock if lock
             result = conn.select_all(sel)
 
-            k = key_column.to_s
-            v = value_column.to_s
+            k = config.key_column.to_s
+            v = config.value_column.to_s
             result.map do |row|
               [row[k], decode(conn, row[v])]
             end
@@ -275,7 +252,7 @@ module Moneta
         self.class.retrieve_or_establish_connection_pool(@spec)
       end
 
-      def create_table(table_name)
+      def default_create_table(table_name)
         with_connection do |conn|
           return if conn.table_exists?(table_name)
 
@@ -283,10 +260,10 @@ module Moneta
           self.class.connection_lock.synchronize do
             conn.create_table(table_name, id: false) do |t|
               # Do not use binary key (Issue #17)
-              t.string key_column, null: false
-              t.binary value_column
+              t.string config.key_column, null: false
+              t.binary config.value_column
             end
-            conn.add_index(table_name, key_column, unique: true)
+            conn.add_index(table_name, config.key_column, unique: true)
           end
         end
       end
@@ -304,21 +281,21 @@ module Moneta
       end
 
       def arel_sel_key(key)
-        arel_sel.where(table[key_column].eq(key))
+        arel_sel.where(table[config.key_column].eq(key))
       end
 
       def conn_ins(conn, key, value)
         ins = ::Arel::InsertManager.new.into(table)
-        ins.insert([[table[key_column], key], [table[value_column], value]])
+        ins.insert([[table[config.key_column], key], [table[config.value_column], value]])
         conn.insert ins
       end
 
       def conn_upd(conn, key, value)
-        conn.update arel_upd.where(table[key_column].eq(key)).set([[table[value_column], value]])
+        conn.update arel_upd.where(table[config.key_column].eq(key)).set([[table[config.value_column], value]])
       end
 
       def conn_sel_value(conn, key)
-        decode(conn, conn.select_value(arel_sel_key(key).project(table[value_column])))
+        decode(conn, conn.select_value(arel_sel_key(key).project(table[config.value_column])))
       end
 
       def encode(conn, value)
@@ -346,6 +323,38 @@ module Moneta
           value
         end
       end
+
+      # Feed the connection info into ActiveRecord and get back a name to use
+      # for getting the connection pool
+      def spec_for_connection(connection)
+        case connection
+        when Symbol
+          connection
+        when Hash, String
+          # Normalize the connection specification to a hash
+          resolver = ::ActiveRecord::ConnectionAdapters::ConnectionSpecification::Resolver.new \
+            'dummy' => connection
+
+          # Turn the config into a standardised hash, sans a couple of bits
+          hash = resolver.resolve(:dummy)
+          hash.delete('name')
+          hash.delete(:password) # For security
+          # Make a name unique to this config
+          name = 'moneta?' + URI.encode_www_form(hash.to_a.sort)
+          # Add into configurations unless its already there (initially done without locking for
+          # speed)
+          unless self.class.configurations.key? name
+            self.class.connection_lock.synchronize do
+              self.class.configurations[name] = connection \
+                unless self.class.configurations.key? name
+            end
+          end
+
+          name.to_sym
+        else
+          ::ActiveRecord::Base.connection_pool.spec.name.to_s
+        end
+      end
     end
   end
 end

data/lib/moneta/adapters/activesupportcache.rb

@@ -2,32 +2,23 @@ module Moneta
   module Adapters
     # ActiveSupport::Cache::Store adapter
     # @api public
-    class ActiveSupportCache
-      include Defaults
+    class ActiveSupportCache < Adapter
       include ExpiresSupport
 
       supports :increment
 
-      # @param [Hash] options
-      # @option options [Numeric] :expires default expiration in seconds
-      def initialize(options = {})
-        self.default_expires = options.delete(:expires)
-        @backend =
-          if options[:backend]
-            options[:backend]
-          elsif defined?(Rails)
-            Rails.cache
-          else
-            raise ArgumentError, 'Option :backend is required'
-          end
-      end
+      # @!method initialize(options = {})
+      #   @param [Hash] options
+      #   @option options [ActiveSupport::Cache::Store] :backend (Rails.cache) Cache store to use
+      #   @option options [Numeric] :expires default expiration in seconds
+      backend { Rails.cache if defined?(Rails) }
 
       # (see Proxy#key?)
       def key?(key, options = {})
-        @backend.exist?(key).tap do |exists|
+        backend.exist?(key).tap do |exists|
           if exists && (expires = expires_value(options, nil)) != nil
-            value = @backend.read(key, options)
-            @backend.write(key, value, options.merge(expires_in: expires ? expires.seconds : nil))
+            value = backend.read(key, options)
+            backend.write(key, value, options.merge(expires_in: expires ? expires.seconds : nil))
           end
         end
       end
@@ -35,9 +26,9 @@ module Moneta
       # (see Proxy#load)
       def load(key, options = {})
         expires = expires_value(options, nil)
-        value = @backend.read(key, options)
+        value = backend.read(key, options)
         if value and expires != nil
-          @backend.write(key, value, options.merge(expires_in: expires ? expires.seconds : nil))
+          backend.write(key, value, options.merge(expires_in: expires ? expires.seconds : nil))
         end
         value
       end
@@ -45,7 +36,7 @@ module Moneta
       # (see Proxy#store)
       def store(key, value, options = {})
         expires = expires_value(options)
-        @backend.write(key, value, options.merge(expires_in: expires ? expires.seconds : nil))
+        backend.write(key, value, options.merge(expires_in: expires ? expires.seconds : nil))
         value
       end
 
@@ -53,11 +44,11 @@ module Moneta
       def increment(key, amount = 1, options = {})
         expires = expires_value(options)
         options.delete(:raw)
-        existing = Integer(@backend.fetch(key, options.merge(raw: true)) { 0 })
+        existing = Integer(backend.fetch(key, options.merge(raw: true)) { 0 })
         if amount > 0
-          @backend.increment(key, amount, options.merge(expires_in: expires ? expires.seconds : nil))
+          backend.increment(key, amount, options.merge(expires_in: expires ? expires.seconds : nil))
         elsif amount < 0
-          @backend.decrement(key, -amount, options.merge(expires_in: expires ? expires.seconds : nil))
+          backend.decrement(key, -amount, options.merge(expires_in: expires ? expires.seconds : nil))
         else
           existing
         end
@@ -65,25 +56,25 @@ module Moneta
 
       # (see Proxy#delete)
       def delete(key, options = {})
-        value = @backend.read(key, options)
+        value = backend.read(key, options)
         if value != nil
-          @backend.delete(key, options)
+          backend.delete(key, options)
           options[:raw] ? value.to_s : value
         end
       end
 
       # (see Proxy#clear)
       def clear(options = {})
-        @backend.clear
+        backend.clear
         self
       end
 
       # (see Proxy#slice)
       def slice(*keys, **options)
-        hash = @backend.read_multi(*keys)
+        hash = backend.read_multi(*keys)
         if (expires = expires_value(options, nil)) != nil
           hash.each do |key, value|
-            @backend.write(key, value, options.merge(expires_in: expires ? expires.seconds : nil))
+            backend.write(key, value, options.merge(expires_in: expires ? expires.seconds : nil))
           end
         end
         if options[:raw]
@@ -115,13 +106,13 @@ module Moneta
 
         hash = Hash === pairs ? pairs : Hash[pairs.to_a]
         expires = expires_value(options)
-        @backend.write_multi(hash, options.merge(expires_in: expires ? expires.seconds : nil))
+        backend.write_multi(hash, options.merge(expires_in: expires ? expires.seconds : nil))
         self
       end
 
       private
 
-      def expires_value(options, default = @default_expires)
+      def expires_value(options, default = config.expires)
         super.tap { options.delete(:expires) unless options.frozen? }
       end
     end