mixed_gauge 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5cb22b7adaa5a1e4b9ef9b995f5bd5fe1793d366
-  data.tar.gz: 334e18351f5e92c0a931aceff4fb8f294afee30b
+  metadata.gz: af67019109e77025f6dcc080900efb12622b9f7e
+  data.tar.gz: be1c25c01c401d06286e26e1075bbd29f5df5d6c
 SHA512:
-  metadata.gz: a11c1dd6b9df580f0671d9cff99ce4d69d5c6aef2b26cfd378803bd8fa025875b988b549f9b866f230454e5b53cf09bdad246af0da61ddf337e22f1c04c4c1f4
-  data.tar.gz: eb0683ff2d6d3df290edaa26a9e7391a169a7dc0e4b9f617d45f58f5d5d1e22a63df4655592d76c90bed54af2de14fc93ae4fb1f15ac4aa01fece1260f51fd46
+  metadata.gz: 70a434108a0fecee84f08f63d79a74a751c91396352dac7682be3031fbd80249a7dac288cdd2a137993411ff40b375697889d4c01a0409686bc4486421e88bf7
+  data.tar.gz: 0b415db64f93f88422fab59c290d504a65e546a2e4d49cb33bf75178f5f825a4e1fb4590ff199c25c6342407622412b700bfc01448c1d3f06400b8127d210028

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.1.2
+- Enable to register before hook on `.put!`.
+- Enable to define arbitrary methods to model class.
+- Arbitrary hash function registeration.
+- `.get!` to raise error when record not found.
+
 ## 0.1.1
 - Fix NoMethodError bug on MixedGauge::Model.
 - Improve tests, measure coverage.

data/README.md

@@ -3,22 +3,6 @@
 
 An ActiveRecord extension for database sharding.
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'mixed_gauge'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install mixed_gauge
-
 ## Usage
 
 Add additional database connection config to `database.yml`.
@@ -81,9 +65,88 @@ alice = User.get('alice@example.com')
 alice.age = 1
 alice.save!
 
-User.all_shards.flat_map {|m| m.where(name: 'alice') }.compact
+User.all_shards.flat_map {|m| m.find_by(name: 'alice') }.compact
 ```
 
+When you want find by non-distkey, not recomended though, you can define finder
+methods to model class.
+
+```ruby
+class User < ActiveRecord::Base
+  include MixedGauge::Model
+  use_cluster :user
+  def_distkey :email
+
+  parent_methods do
+    def find_from_all_by_name(name)
+      all_shards.map {|m| m.find_by(name: name) }.compact.first
+    end
+  end
+end
+
+alice = User.find_from_all_by_name('Alice')
+alice.age = 0
+alice.save!
+```
+
+Sometimes you want to generates distkey value before validation. Since mixed_gauge
+generates sub class of your models, AR's callback is not usesless for this usecase,
+so mixed_gauge offers its own callback method.
+
+```ruby
+class AccessToken < ActiveRecord::Base
+  include MixedGauge::Model
+  use_cluster :access_token
+  def_distkey :token
+
+  validates :token, presence: true
+
+  def self.generate_token
+    SecureRandom.uuid
+  end
+
+  before_put do |attributes|
+    unless attributes[:token] || attributes['token']
+      attributes[:token] = generate_token
+    end
+  end
+end
+
+access_token = AccessToken.put!
+access_token.token #=> a generated token
+```
+
+## Advanced configuration
+### Hash fucntion
+Register arbitrary hash function. Hash function must be a proc and
+must return integer.
+
+```ruby
+# gem install fnv
+require "fnv"
+Mixedgauge.configure do |config|
+  config.register_hash_function do |key|
+    FNV.new.fnv1a_64(key)
+  end
+end
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mixed_gauge'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install mixed_gauge
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/mixed_gauge/config.rb

@@ -1,14 +1,22 @@
 module MixedGauge
   class Config
+    DEFAULT_HASH_FUNCTION = -> (key) { Digest::MD5.hexdigest(key).to_i(16) }
+
+    attr_reader :hash_proc
+
     def initialize
       @cluster_configs = {}
+      @hash_proc = DEFAULT_HASH_FUNCTION
     end
 
+    # Define config for specific cluster.
     # @param [Symbol] cluster_name
     # @return [nil]
     # @example
-    #   config.define_cluster(:user) do |c|
-    #     c.define_slots(1..1024)
+    #   config.define_cluster(:user) do |cluster|
+    #     cluster.define_slots(1..1048576)
+    #     cluster.register(1..524288, :production_user_001)
+    #     cluster.register(524289..1048576, :production_user_002)
     #   end
     def define_cluster(cluster_name, &block)
       cluster_config = ClusterConfig.new(cluster_name)
@@ -22,5 +30,21 @@ module MixedGauge
     def fetch_cluster_config(cluster_name)
       @cluster_configs.fetch(cluster_name)
     end
+
+    # Register arbitrary hash function. Hash function must be a proc and
+    # must return integer.
+    # @example
+    #   # gem install fnv
+    #   require "fnv"
+    #   Mixedgauge.configure do |config|
+    #     config.register_hash_function do |key|
+    #       FNV.new.fnv1a_64(key)
+    #     end
+    #   end
+    def register_hash_function(&block)
+      raise ArgumentError if block.arity != 1
+      raise ArgumentError unless block.call('test value').is_a? Integer
+      @hash_proc = block
+    end
   end
 end

data/lib/mixed_gauge/errors.rb

@@ -5,4 +5,8 @@ module MixedGauge
   # Raised when try to put new record without distkey attribute.
   class MissingDistkeyAttribute < Error
   end
+
+  # Inherit from AR::RecordNotFound to enable to handle as AR's one.
+  class RecordNotFound < ActiveRecord::RecordNotFound
+  end
 end

data/lib/mixed_gauge/model.rb

@@ -25,6 +25,7 @@ module MixedGauge
     end
 
     module ClassMethods
+      # The cluster config must be defined before `use_cluster`.
       # @param [Symbol] A cluster name which is set by MixedGauge.configure
       def use_cluster(name)
         config = MixedGauge.config.fetch_cluster_config(name)
@@ -33,20 +34,22 @@ module MixedGauge
         self.abstract_class = true
       end
 
+      # Distkey is a column. mixed_gauge hashes that value and determine which
+      # shard to store.
       # @param [Symbol] column
       def def_distkey(column)
         self.distkey = column.to_sym
       end
 
-      # @param [Object] key 
-      # @return [ActiveRecord::Base] A auto-generated sub model of included model
-      def get(key)
-        shard_for(key.to_s).find_by(distkey => key)
-      end
-
+      # Create new record with given attributes in proper shard for given key.
+      # When distkey value is empty, raises MixedGauge::MissingDistkeyAttribute
+      # error.
       # @param [Hash] attributes
       # @return [ActiveRecord::Base] A sub class instance of included model
+      # @raise [MixedGauge::MissingDistkeyAttribute]
       def put!(attributes)
+        @before_put_callback.call(attributes) if @before_put_callback
+
         if key = attributes[distkey] || attributes[distkey.to_s]
           shard_for(key).create!(attributes)
         else
@@ -54,17 +57,84 @@ module MixedGauge
         end
       end
 
-      # @param [Object] key A value of distkey
+      # Returns nil when not found. Except that, is same as `.get!`.
+      # @param [String] key
+      # @return [ActiveRecord::Base, nil] A sub model instance of included model
+      def get(key)
+        raise 'key must be a String' unless key.is_a?(String)
+        shard_for(key.to_s).find_by(distkey => key)
+      end
+
+      # `.get!` raises MixedGauge::RecordNotFound which is child class of
+      # `ActiveRecord::RecordNotFound` so you can rescue that exception as same
+      # as AR's RecordNotFound.
+      # @param [String] key
+      # @return [ActiveRecord::Base] A sub model instance of included model
+      # @raise [MixedGauge::RecordNotFound]
+      def get!(key)
+        get(key) or raise MixedGauge::RecordNotFound
+      end
+
+      # Register hook to assign auto-generated distkey or something.
+      # Sometimes you want to generates distkey value before validation. Since
+      # mixed_gauge generates sub class of your models, AR's callback is not
+      # usesless for this usecase, so mixed_gauge offers its own callback method.
+      # @example
+      #   class User
+      #     include MixedGauge::Model
+      #     use_cluster :user
+      #     def_distkey :name
+      #     before_put do |attributes|
+      #       attributes[:name] = generate_name unless attributes[:name]
+      #     end
+      #   end
+      def before_put(&block)
+        @before_put_callback = block
+      end
+
+      # Returns a generated sub class of this model which is connected proper
+      # shard for given key.
+      # @param [String] key A value of distkey
       # @return [Class] A sub model for this distkey value
       def shard_for(key)
         connection_name = cluster_routing.route(key.to_s)
         sub_model_repository.fetch(connection_name)
       end
 
+      # Returns all generated sub class of this model. Useful to query to
+      # all shards.
       # @return [Array<Class>] An array of sub models
+      # @example
+      #   User.all_shards.flat_map {|m| m.find_by(name: 'alice') }.compact
       def all_shards
         sub_model_repository.all
       end
+
+      # Define utility methods which uses all shards or specific shard.
+      # These methods can be called from included model class.
+      # @example
+      #   class User
+      #     include MixedGauge::Model
+      #     use_cluster :user
+      #     def_distkey :name
+      #     parent_methods do
+      #       def all_count
+      #         all_shards.map {|m| m.count }.reduce(&:+)
+      #       end
+      #
+      #       def find_from_all_by(condition)
+      #         all_shards.flat_map {|m m.find_by(condition) }.compact.first
+      #       end
+      #     end
+      #   end
+      #
+      #   User.put!(email: 'a@m.com', name: 'a')
+      #   User.put!(email: 'b@m.com', name: 'b')
+      #   User.all_count #=> 2
+      #   User.find_from_all_by(name: 'b') #=> User b
+      def parent_methods(&block)
+        instance_eval(&block)
+      end
     end
   end
 end

data/lib/mixed_gauge/routing.rb

@@ -17,7 +17,7 @@ module MixedGauge
     # @param [String] key
     # @return [Integer]
     def hash_f(key)
-      Digest::MD5.hexdigest(key).to_i(16)
+      MixedGauge.config.hash_proc.call(key)
     end
   end
 end

data/lib/mixed_gauge/version.rb

@@ -1,3 +1,3 @@
 module MixedGauge
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mixed_gauge
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Taiki Ono