ohm 1.3.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: fb164eaa5fbec17afbcceb9a4c7f8ded8ace93b5
-  data.tar.gz: 4ab08c00e7edf980f16e3d854012b3a5e9503b1a
-SHA512:
-  metadata.gz: 5f3c9c4a0457fd31a0b14eb783840c23e8996e69205fffaacea18ae22efb1c5aa643188d2ddcaf1c2fe584efe2fa5231b58d5997627e7f9f7249b6e52c5b446e
-  data.tar.gz: 6d0e08cd9092c0fce4c41a326163c1cf13a37f2a781020be389bd83d46fa650b8af05785873fb57343cdeb3b7721d341c4c063b1dca38163f835f7e7b8975ee7
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZDVlZWJhMjlkNWUzM2Y2NzY3ODVmN2E3YmIxYjQ3ZmU3OGQ3N2JiOA==
+  data.tar.gz: !binary |-
+    ZGMyODFlYTAwYzU0MzE4MTQ0Y2FhZTNlZTdhODU0YzgwYTgyZjA4Mw==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    NGY2YmU4YTE0NWQ3N2E4Y2QyYWViZDBiOWUwM2NmMTFhNjY5YjNmMTIxNmE3
+    OTRhNmJiMjQ2ZjcwNDQwMjU4YTQ3ZWRjZmJjMmZlOTIxMTY3OTA5ZGJkNDYy
+    Yjg0ZDllODdkNjM4NGFmNWM4YzY5MTQ0ODBlYTNkYjhkODhmOGE=
+  data.tar.gz: !binary |-
+    ZTJiYWNjNGUxZTk1ZTUxNTQ5Nzk2NTZmOGQ1YTAzY2QzY2Y2NDk4MGE5MDU3
+    Zjk1ODY3MThlYTdmOGZhZWFiY2QyNzg1MTg2YjA5NjFlODE4NDNjNmE4N2Mx
+    MmJlNjg3ZjViYzc4NmU5ZGNlNmU1MmEwMmNkMDBhOTg1ZDUyZjk=

data/.gems

@@ -0,0 +1,4 @@
+nest -v 1.1.1
+scrivener -v 0.0.3
+redis -v 3.0.1
+cutest -v 1.2.0.rc2

data/.gitignore

@@ -0,0 +1,4 @@
+/pkg
+/.yardoc
+/doc
+.rbenv-gemsets

data/CHANGELOG

@@ -0,0 +1,52 @@
+1.3.1
+
+- Improve memory consumption when indexing persisted attributes.
+
+  No migration is needed and old indices will be cleaned up as you save
+  instances.
+
+1.3.0
+
+- Add Model.attributes.
+
+1.2.0
+
+- Enumerable fix.
+- Merge Ohm::PipelinedFetch into Ohm::Collection.
+- Fix Set, MultiSet, and List enumerable behavior.
+- Change dependencies to use latest cutest.
+
+1.1.0
+
+- Compatible with redis-rb 3.
+
+1.0.0
+
+- Fetching a batch of objects is now done through one pipeline, effectively
+  reducing the IO to just 2 operations (one for SMEMBERS / LRANGE, one for
+  the actual HGET of all the individual HASHes.)
+- write_remote / read_remote have been replaced with set / get respectively.
+- Ohm::Model.unique has been added.
+- Ohm::Model::Set has been renamed to Ohm::Set
+- Ohm::Model::List has been renamed to Ohm::List
+- Ohm::Model::Collection is gone.
+- Ohm::Validations is gone. Ohm now uses Scrivener::Validations.
+- Ohm::Key is gone. Ohm now uses Nest directly.
+- No more concept of volatile keys.
+- Ohm::Model::Wrapper is gone.
+- Use Symbols for constants instead of relying on Ohm::Model.const_missing.
+- #sort / #sort_by now uses `limit` as it's used in redis-rb, e.g. you
+  have to pass in an array like so: sort(limit: [0, 1]).
+- Set / List have been trimmed to contain only the minimum number
+  of necessary methods.
+- You can no longer mutate a collection / set as before, e.g. doing
+  User.find(...).add(User[1]) will throw an error.
+- The #union operation has been added. You can now chain it with your filters.
+- Temporary keys when doing finds are now automatically cleaned up.
+- Counters are now stored in their own key instead, i.e. in
+  User:<id>:counters.
+- JSON support has to be explicitly required by doing `require
+  "ohm/json"`.
+- All save / delete / update operations are now done using
+  transactions (see http://redis.io/topics/transactions).
+- All indices are now stored without converting the values to base64.

data/benchmarks/common.rb

@@ -0,0 +1,33 @@
+require "bench"
+require_relative "../lib/ohm"
+
+Ohm.connect(:port => 6379, :db => 15)
+Ohm.flush
+
+class Event < Ohm::Model
+  attribute :name
+  attribute :location
+
+  index :name
+  index :location
+
+  def validate
+    assert_present :name
+    assert_present :location
+  end
+end
+
+class Sequence
+  def initialize
+    @value = 0
+  end
+
+  def succ!
+    Thread.exclusive { @value += 1 }
+  end
+
+  def self.[](name)
+    @@sequences ||= Hash.new { |hash, key| hash[key] = Sequence.new }
+    @@sequences[name]
+  end
+end

data/benchmarks/create.rb

@@ -0,0 +1,21 @@
+require_relative "common"
+
+benchmark "Create Events" do
+  i = Sequence[:events].succ!
+
+  Event.create(:name => "Redis Meetup #{i}", :location => "London #{i}")
+end
+
+benchmark "Find by indexed attribute" do
+  Event.find(:name => "Redis Meetup 1").first
+end
+
+benchmark "Mass update" do
+  Event[1].update(:name => "Redis Meetup II")
+end
+
+benchmark "Load events" do
+  Event[1].name
+end
+
+run 5000

data/benchmarks/delete.rb

@@ -0,0 +1,13 @@
+require_relative "common"
+
+1000.times do |i|
+  Event.create(:name => "Redis Meetup #{i}", :location => "At my place")
+end
+
+benchmark "Delete event" do
+  Event.all.each do |event|
+    event.delete
+  end
+end
+
+run 1

data/examples/activity-feed.rb

@@ -0,0 +1,162 @@
+### Building an activity feed
+
+#### Common solutions using a relational design
+
+# When faced with this application requirement, the most common approach by
+# far have been to create an *activities* table, and rows in this table would
+# reference a *user*. Activities would typically be generated for each
+# follower (or friend) when a certain user performs an action, like posting a
+# new status update.
+
+#### Problems
+
+# The biggest issue with this design, is that the *activities* table will
+# quickly get very huge, at which point you would need to shard it on
+# *user_id*. Also, inserting thousands of entries per second would quickly
+# bring your database to its knees.
+
+#### Ohm Solution
+
+# As always we need to require `Ohm`.
+require "ohm"
+
+# We create a `User` class, with a `set` for all the other users he
+# would be `following`, and another `set` for all his `followers`.
+class User < Ohm::Model
+  set :followers, User
+  set :following, User
+
+  # Because a `User` literally has a `list` of activities, using a Redis
+  # `list` to model the activities would be a good choice. We default to
+  # getting the first 100 activities, and use
+  # [lrange](http://code.google.com/p/redis/wiki/LrangeCommand) directly.
+  def activities(start = 0, limit = 100)
+    key[:activities].lrange(start, start + limit)
+  end
+
+  # Broadcasting a message to all the `followers` of a user would simply
+  # be prepending the message for each if his `followers`. We also use
+  # the Redis command
+  # [lpush](http://code.google.com/p/redis/wiki/RpushCommand) directly.
+  def broadcast(str)
+    followers.each do |user|
+      user.key[:activities].lpush(str)
+    end
+  end
+
+  # Given that *Jane* wants to follow *John*, we simply do the following
+  # steps:
+  #
+  # 1. *John* is added to *Jane*'s `following` list.
+  # 2. *Jane* is added to *John*'s `followers` list.
+  def follow(other)
+    following << other
+    other.followers << self
+  end
+end
+
+
+#### Testing
+
+# We'll use cutest for our testing framework.
+require "cutest"
+
+# The database is flushed before each test.
+prepare { Ohm.flush }
+
+# We define two users, `john` and `jane`, and yield them so all
+# other tests are given access to these 2 users.
+setup do
+  john = User.create
+  jane = User.create
+
+  [john, jane]
+end
+
+# Let's verify our model for `follow`. When `jane` follows `john`,
+# the following conditions should hold:
+#
+# 1. The followers list of `john` is comprised *only* of `jane`.
+# 2. The list of users `jane` is following is comprised *only* of `john`.
+test "jane following john" do |john, jane|
+  jane.follow(john)
+
+  assert [john] == jane.following.to_a
+  assert [jane] == john.followers.to_a
+end
+
+# Broadcasting a message should simply notify all the followers of the
+# `broadcaster`.
+test "john broadcasting a message" do |john, jane|
+  jane.follow(john)
+  john.broadcast("Learning about Redis and Ohm")
+
+  assert jane.activities.include?("Learning about Redis and Ohm")
+end
+
+#### Total Denormalization: Adding HTML
+
+# This may be a real edge case design decision, but for some scenarios this
+# may work. The beauty of this solution is that you only have to generate the
+# output once, and successive refreshes of the end user will help you save
+# some CPU cycles.
+#
+# This example of course assumes that the code that generates this does all
+# the conditional checks (possibly changing the point of view like *Me:*
+# instead of *John says:*).
+test "broadcasting the html directly" do |john, jane|
+  jane.follow(john)
+
+  snippet = '<a href="/1">John</a> says: How\'s it going ' +
+            '<a href="/user/2">jane</a>?'
+
+  john.broadcast(snippet)
+
+  assert jane.activities.include?(snippet)
+end
+
+#### Saving Space
+
+# In most cases, users don't really care about keeping their entire activity
+# history. This application requirement would be fairly trivial to implement.
+
+# Let's reopen our `User` class and define a new broadcast method.
+class User
+  # We define a constant where we set the maximum number of activity entries.
+  MAX = 10
+
+  # Using `MAX` as the reference, we check if the number of activities exceeds
+  # `MAX`, and use
+  # [ltrim](http://code.google.com/p/redis/wiki/LtrimCommand) to truncate
+  # the activities.
+  def broadcast(str)
+    followers.each do |user|
+      user.key[:activities].lpush(str)
+
+      if user.key[:activities].llen > MAX
+        user.key[:activities].ltrim(0, MAX - 1)
+      end
+    end
+  end
+end
+
+# Now let's verify that this new behavior is enforced.
+test "pushing 11 activities maintains the list to 10" do |john, jane|
+  jane.follow(john)
+
+  11.times { john.broadcast("Flooding your feed!") }
+
+  assert 10 == jane.activities.size
+end
+
+
+#### Conclusion
+
+# As you can see, choosing a more straightforward approach (in this case,
+# actually having a list per user, instead of maintaining a separate
+# `activities` table) will greatly simplify the design of your system.
+#
+# As a final note, keep in mind that the Ohm solution would still need
+# sharding for large datasets, but that would be again trivial to implement
+# using [redis-rb](http://github.com/ezmobius/redis-rb)'s distributed support
+# and sharding it against the *user_id*.

data/examples/chaining.rb

@@ -0,0 +1,203 @@
+### Chaining Ohm Sets
+
+#### Doing the straight forward approach
+
+# Let's design our example around the following requirements:
+#
+# 1. a `User` has many orders.
+# 2. an  `Order` can be pending, authorized or captured.
+# 3. a `Product` is referenced by an `Order`.
+
+#### Doing it the normal way
+
+# Let's first require `Ohm`.
+require "ohm"
+
+# A `User` has a `collection` of *orders*. Note that a collection
+# is actually just a convenience, which implemented simply will look like:
+#
+#     def orders
+#       Order.find(:user_id => self.id)
+#     end
+#
+class User < Ohm::Model
+  collection :orders, Order
+end
+
+# The product for our purposes will only contain a name.
+class Product < Ohm::Model
+  attribute :name
+end
+
+# We define an `Order` with just a single `attribute` called state, and
+# also add an `index` so we can search an order given its state.
+#
+# The `reference` to the `User` is actually required for the `collection`
+# of *orders* in the `User` declared above, because the `reference` defines
+# an index called `:user_id`.
+#
+# We also define a `reference` to a `Product`.
+class Order < Ohm::Model
+  attribute :state
+  index :state
+
+  reference :user, User
+  reference :product, Product
+end
+
+##### Testing what we have so far.
+
+# For the purposes of this tutorial, we'll use cutest for our test framework.
+require "cutest"
+
+# Make sure that every run of our test suite has a clean Redis instance.
+prepare { Ohm.flush }
+
+# Let's create a *user*, a *pending*, *authorized* and a captured order.
+# We also create two products named *iPod* and *iPad*.
+setup do
+  @user = User.create
+
+  @ipod = Product.create(:name => "iPod")
+  @ipad = Product.create(:name => "iPad")
+
+  @pending =    Order.create(:user => @user, :state => "pending",
+                             :product => @ipod)
+  @authorized = Order.create(:user => @user, :state => "authorized",
+                             :product => @ipad)
+  @captured =   Order.create(:user => @user, :state => "captured",
+                             :product => @ipad)
+end
+
+# Now let's try and grab all pending orders, and also pending
+# *iPad* and *iPod* ones.
+test "finding pending orders" do
+  assert @user.orders.find(state: "pending").include?(@pending)
+
+  assert @user.orders.find(:state => "pending",
+                           :product_id => @ipod.id).include?(@pending)
+
+  assert @user.orders.find(:state => "pending",
+                           :product_id => @ipad.id).empty?
+end
+
+# Now we try and find captured and authorized orders. The tricky part
+# is trying to find an order that is either *captured* or *authorized*,
+# since `Ohm` as of this writing doesn't support unions in its
+# finder syntax.
+test "finding authorized and/or captured orders" do
+  assert @user.orders.find(:state => "authorized").include?(@authorized)
+  assert @user.orders.find(:state => "captured").include?(@captured)
+
+  assert @user.orders.find(:state => ["authorized", "captured"]).empty?
+
+  auth_or_capt = @user.orders.key.volatile[:auth_or_capt]
+  auth_or_capt.sunionstore(
+    @user.orders.find(:state => "authorized").key,
+    @user.orders.find(:state => "captured").key
+  )
+
+  assert auth_or_capt.smembers.include?(@authorized.id)
+  assert auth_or_capt.smembers.include?(@captured.id)
+end
+
+#### Creating shortcuts
+
+# You can of course define methods to make that code more readable.
+class User < Ohm::Model
+  def authorized_orders
+    orders.find(:state => "authorized")
+  end
+
+  def captured_orders
+    orders.find(:state => "captured")
+  end
+end
+
+# And we can now test these new methods.
+test "finding authorized and/or captured orders" do
+  assert @user.authorized_orders.include?(@authorized)
+  assert @user.captured_orders.include?(@captured)
+end
+
+# In most cases this is fine, but if you want to have a little fun,
+# then we can play around with some chainability.
+
+#### Chaining Kung-Fu
+
+# The `Ohm::Model::Set` takes a *Redis* key and a *class monad*
+# for its arguments.
+#
+# We can simply subclass it and define the monad to always be an
+# `Order` so we don't have to manually set it everytime.
+class UserOrders < Ohm::Model::Set
+  def initialize(key)
+    super key, Ohm::Model::Wrapper.wrap(Order)
+  end
+
+  # Here is the crux of the chaining pattern. Instead of
+  # just doing a straight up `find(:state => "pending")`, we return
+  # `UserOrders` again.
+  def pending
+    self.class.new(model.index_key_for(:state, "pending"))
+  end
+
+  def authorized
+    self.class.new(model.index_key_for(:state, "authorized"))
+  end
+
+  def captured
+    self.class.new(model.index_key_for(:state, "captured"))
+  end
+
+  # Now we wrap the implementation of doing an `SUNIONSTORE` and also
+  # make it return a `UserOrders` object.
+  #
+  # NOTE: `volatile` just returns the key prepended with a `~:`, so in
+  # this case it would be `~:Order:accepted`.
+  def accepted
+    model.key.volatile[:accepted].sunionstore(
+      authorized.key, captured.key
+    )
+
+    self.class.new(model.key.volatile[:accepted])
+  end
+end
+
+# Now let's re-open the `User` class and add a customized `orders` method.
+class User < Ohm::Model
+  def orders
+    UserOrders.new(Order.index_key_for(:user_id, id))
+  end
+end
+
+# Ok! Let's put all of that chaining code to good use.
+test "finding pending orders using a chainable style" do
+  assert @user.orders.pending.include?(@pending)
+  assert @user.orders.pending.find(:product_id => @ipod.id).include?(@pending)
+
+  assert @user.orders.pending.find(:product_id => @ipad.id).empty?
+end
+
+test "finding authorized and/or captured orders using a chainable style" do
+  assert @user.orders.authorized.include?(@authorized)
+  assert @user.orders.captured.include?(@captured)
+
+  assert @user.orders.accepted.include?(@authorized)
+  assert @user.orders.accepted.include?(@captured)
+
+  accepted = @user.orders.accepted
+
+  assert accepted.find(:product_id => @ipad.id).include?(@authorized)
+  assert accepted.find(:product_id => @ipad.id).include?(@captured)
+end
+
+#### Conclusion
+
+# This design pattern is something that really depends upon the situation. In
+# the example above, you can add more complicated querying on the `UserOrders`
+# class.
+#
+# The most important takeaway here is the ease of which we can weild the
+# different components of Ohm, and mold it accordingly to our preferences,
+# without having to monkey-patch anything.