simple-feed 2.0.2 → 2.1.0

data/.rubocop_todo.yml

@@ -0,0 +1,134 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2020-05-23 01:49:13 -0700 using RuboCop version 0.83.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyleAlignWith, AutoCorrect, Severity.
+# SupportedStylesAlignWith: keyword, variable, start_of_line
+Layout/EndAlignment:
+  Exclude:
+    - 'lib/simplefeed/dsl/formatter.rb'
+
+# Offense count: 2
+Lint/ShadowingOuterLocalVariable:
+  Exclude:
+    - 'lib/simplefeed/providers/redis/provider.rb'
+
+# Offense count: 1
+# Configuration parameters: AllowComments.
+Lint/SuppressedException:
+  Exclude:
+    - 'lib/simplefeed/providers/hash/provider.rb'
+
+# Offense count: 3
+# Configuration parameters: AllowKeywordBlockArguments.
+Lint/UnderscorePrefixedVariableName:
+  Exclude:
+    - 'lib/simplefeed/dsl/formatter.rb'
+    - 'lib/simplefeed/providers/redis/provider.rb'
+
+# Offense count: 1
+# Configuration parameters: CheckForMethodsWithNoSideEffects.
+Lint/Void:
+  Exclude:
+    - 'lib/simplefeed/feed.rb'
+
+# Offense count: 25
+# Configuration parameters: CountComments, ExcludedMethods.
+# ExcludedMethods: refine
+Metrics/BlockLength:
+  Max: 185
+
+# Offense count: 1
+# Configuration parameters: ExpectMatchingDefinition, Regex, IgnoreExecutableScripts, AllowedAcronyms.
+# AllowedAcronyms: CLI, DSL, ACL, API, ASCII, CPU, CSS, DNS, EOF, GUID, HTML, HTTP, HTTPS, ID, IP, JSON, LHS, QPS, RAM, RHS, RPC, SLA, SMTP, SQL, SSH, TCP, TLS, TTL, UDP, UI, UID, UUID, URI, URL, UTF8, VM, XML, XMPP, XSRF, XSS
+Naming/FileName:
+  Exclude:
+    - 'lib/simple-feed.rb'
+
+# Offense count: 1
+# Configuration parameters: EnforcedStyleForLeadingUnderscores.
+# SupportedStylesForLeadingUnderscores: disallowed, required, optional
+Naming/MemoizedInstanceVariableName:
+  Exclude:
+    - 'lib/simplefeed/providers/redis/stats.rb'
+
+# Offense count: 5
+# Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
+# AllowedNames: io, id, to, by, on, in, at, ip, db, os, pp
+Naming/MethodParameterName:
+  Exclude:
+    - 'lib/simplefeed/dsl/formatter.rb'
+    - 'lib/simplefeed/providers/redis/driver.rb'
+    - 'spec/support/mock_feed.rb'
+    - 'spec/support/shared_examples_for_providers.rb'
+
+# Offense count: 1
+# Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros.
+# NamePrefix: is_, has_, have_
+# ForbiddenPrefixes: is_, has_, have_
+# AllowedMethods: is_a?
+# MethodDefinitionMacros: define_method, define_singleton_method
+Naming/PredicateName:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/simplefeed/response.rb'
+
+# Offense count: 9
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: annotated, template, unannotated
+Style/FormatStringToken:
+  Exclude:
+    - 'lib/simplefeed/dsl/formatter.rb'
+    - 'lib/simplefeed/providers/redis/driver.rb'
+
+# Offense count: 3
+# Configuration parameters: MinBodyLength.
+Style/GuardClause:
+  Exclude:
+    - 'lib/simplefeed/event.rb'
+    - 'lib/simplefeed/providers/base/provider.rb'
+    - 'lib/simplefeed/providers/hash/provider.rb'
+
+# Offense count: 1
+# Configuration parameters: AllowIfModifier.
+Style/IfInsideElse:
+  Exclude:
+    - 'lib/simplefeed/response.rb'
+
+# Offense count: 2
+Style/MethodMissingSuper:
+  Exclude:
+    - 'lib/simplefeed/providers/proxy.rb'
+    - 'lib/simplefeed/providers/redis/driver.rb'
+
+# Offense count: 4
+Style/MissingRespondToMissing:
+  Exclude:
+    - 'lib/simplefeed.rb'
+    - 'lib/simplefeed/providers/proxy.rb'
+    - 'lib/simplefeed/providers/redis/driver.rb'
+
+# Offense count: 3
+Style/MultilineTernaryOperator:
+  Exclude:
+    - 'lib/simplefeed/feed.rb'
+    - 'lib/simplefeed/providers/redis/provider.rb'
+    - 'lib/simplefeed/response.rb'
+
+# Offense count: 1
+Style/OptionalArguments:
+  Exclude:
+    - 'lib/simplefeed/providers/redis/provider.rb'
+
+# Offense count: 3
+Style/StructInheritance:
+  Exclude:
+    - 'lib/simplefeed/key/template.rb'
+    - 'lib/simplefeed/key/type.rb'
+    - 'lib/simplefeed/providers/redis/driver.rb'

data/.travis.yml

@@ -1,14 +1,21 @@
 cache: bundler
 rvm:
-- 2.3.3
-- 2.4.0
+- 2.3.8
+- 2.4.10
+- 2.5.3
+- 2.6.2
+- 2.7.1
 services:
 - redis-server
 before_script:
-script: bundle exec rspec
-after_success:
-  - bundle exec codeclimate-test-reporter
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+script: bundle exec rspec --format=documentation
+after_script:
+  - bash <(curl -s https://codecov.io/bash)
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT
 env:
-notifications:
-  slack:
-    secure: QaaD9WpCYoGFITVd8ku3cjkw1ADJ/rqsPgFGsbRxjPOj1HDzkkUVs20IK0AysxeI6CPY31rfWqbBcE4I4dUE49uIhpOoBXZ8GDYunUONeEmqGwrqZtV/8NqMLNc0Ouu5Jp/KVlnMO93Pcg97BBW81t1koxqyvgSU5oEmJdTmQZIsRNprhczeCj7T6jbb12LEA8uKi2qnp+FAhL5NJczHxqWCd2pWThtbA+hiRmH/mU0480n1eRForN51jDYUrgxb4PamhfUUG1xkzMPzGsvJTMCQDOG4eyHaq71vlZ3z9BbQG6vbcjfEQHVwfrPRz1k0luIlxMXJxszCFnnLVqeRYs85y4FOQSrLsDfsyLCU+1NgLqtseN6jNKOtY624Ok7YvYzsVYez/CPWUG1d2NIRMYQ+BoL2VQ3SDfvr4bYQ02QmqlhM1bKqmBoM+WmiH1FQk6CKOFcmlSkgkFilLi6YSB/EisQ5V5jo7DnzD38VVACo6J6SgVk2D6soONE3zev34Qa6PIOuwTTlXl6JKH0cpiG058lI+Oza+0xi0jg58sZG3jxeGM7m4wg66htgyN1oRQjIukSR+IJ3PZlFKTLvx2rCUcYz+8fRpPCMTSIVLeju5oPqOm0VRUni2dG5JGyNACV8EhI4ZMcfl7+uFTIagCnllRftBx8lY6AxWN3WpDE=
+  global:
+    CODECOV_TOKEN="2085c087-f833-49c7-a105-703bce882653"
+    secure: cdUlrz0XNCu0HB5lNLYZBF6yaukIkDZRlVsAbeeaNhPKCVj7MOvuGEUZ9TzQP0yXRaGXHy3xXem0MdDbnli5WYvHxj2MTrRVEDBiRm4jaZFHe3Rewr2mWmLqK1c4g9gvOTgjPNPTesdft87+wQuPedQLpfMGuedA86tkKzA2Tkc4J69DI93C02h6H89iiQFHL9ISNk5DzZh3FJo+fyi0JQlD6CAzWrVplCqf088qGdAk3Hy77Q2GKkVEdOb/P0cdmDLnFjekdh4b0TPI/uaqgu4cZeoebWQgg61K/enGLqxY2Lp0f4DsXQev+06d14KxIJMYHLuDgvlVwYMDInxQU7kXgTRgAnaxRdm0S7NbP89uBVkfIQiNGan7Qkvw2ayGhYCcu7Vgvjo6C2btZWLpxT0XvpQGfpvHrRrPnzFbFLLtG4rhJd3iiTbSa5LPDEi4Qx9uwGNy4iR6IB69R6dPwAR8P45XZE4JnJVUvrM/X9v9Yv2hAxnuCb48whalIozGqpwavLdYrgCf2pQecls74uw4mCxvDAg0EoskrDYuk4DYeZ507ajor4zX1avLUVfYk/0igpp6KeLENY5ozl1zsEvRcOldfdV8R9tKEGxliIgffe67Hc5/ZP+C/53lcK0nIxXYrB1I7Q+CVlEDNutNQNZRDfrNBYJVe/+RvmmdD+w=

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in activity-feed.gemspec

data/Guardfile

@@ -1,4 +1,6 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
+
 require 'guard/rspec'
 
 guard :rspec,
@@ -8,11 +10,9 @@ guard :rspec,
       all_after_pass: false,
       all_on_start:   false,
       keep_failed:    false do
-
-  watch(%r{.*\.gemspec}) { 'spec' }
+  watch(/.*\.gemspec/) { 'spec' }
   watch(%r{^lib/(.+)\.rb$}) { 'spec' }
   watch(%r{^spec/.+_spec\.rb$})
   watch('spec/spec_helper.rb') { 'spec' }
   watch(%r{spec/support/.*}) { 'spec' }
 end
-

data/{README.md → README.adoc}

@@ -1,83 +1,137 @@
-# SimpleFeed — Scalable, easy to use activity feed implementation.
+= SimpleFeed
+:doctype: book
+:toc:
+:toclevels: 5
+:sectnums:
 
+== Scalable, Easy to Use Activity Feed Implementation.
 
-[![Gem Version](https://img.shields.io/gem/v/simple-feed.svg)](https://rubygems.org/gems/simple-feed)
-[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/kigster/simple-feed/master/LICENSE.txt)
+image:https://img.shields.io/gem/v/simple-feed.svg[Gem Version,link=https://rubygems.org/gems/simple-feed]
+image:https://img.shields.io/badge/license-MIT-blue.svg[MIT licensed,link=https://github.com/kigster/simple-feed/master/LICENSE.txt]
 
-[![Build Status](https://travis-ci.org/kigster/simple-feed.svg?branch=master)](https://travis-ci.org/kigster/simple-feed)
-[![Code Climate](https://codeclimate.com/repos/58339a5b3d9faa74ac006b36/badges/8b899f6df4fc1ed93759/gpa.svg)](https://codeclimate.com/repos/58339a5b3d9faa74ac006b36/feed)
-[![Test Coverage](https://codeclimate.com/repos/58339a5b3d9faa74ac006b36/badges/8b899f6df4fc1ed93759/coverage.svg)](https://codeclimate.com/repos/58339a5b3d9faa74ac006b36/coverage)
-[![Issue Count](https://codeclimate.com/repos/58339a5b3d9faa74ac006b36/badges/8b899f6df4fc1ed93759/issue_count.svg)](https://codeclimate.com/repos/58339a5b3d9faa74ac006b36/feed)
-[![Inline docs](http://inch-ci.org/github/kigster/simple-feed.svg?branch=master)](http://inch-ci.org/github/kigster/simple-feed)
-[![Talk on Gitter](https://img.shields.io/gitter/room/gitterHQ/gitter.svg)](https://gitter.im/kigster/simple-feed)
+image:https://github.com/kigster/simple-feed/workflows/Ruby/badge.svg?branch=master[Ruby,link=https://github.com/kigster/simple-feed/actions?query=workflow%3ARuby]
+image:https://github.com/kigster/simple-feed/workflows/Rubocop/badge.svg?branch=master[Ruby,link=https://github.com/kigster/simple-feed/actions?query=workflow%3ARubocop]
 
----
+image:https://travis-ci.org/kigster/simple-feed.svg?branch=master[Build Status,link=https://travis-ci.org/kigster/simple-feed]
+image:https://api.codeclimate.com/v1/badges/a11061820895fcde635e/maintainability[Maintainability,link=https://codeclimate.com/github/kigster/simple-feed/maintainability]
+image:https://api.codeclimate.com/v1/badges/a11061820895fcde635e/test_coverage[Test Coverage,link=https://codeclimate.com/github/kigster/simple-feed/test_coverage]
 
-**February 20th, 2017**: Please read the blog post [Feeding Frenzy with SimpleFeed](http://kig.re/2017/02/19/feeding-frenzy-with-simple-feed-activity-feed-ruby-gem.html) launching this library. Please leave comments or questions in the discussion thread at the bottom of that post. Thanks! 
+image:http://inch-ci.org/github/kigster/simple-feed.svg?branch=master[Inline docs,link=http://inch-ci.org/github/kigster/simple-feed]
+image:https://img.shields.io/gitter/room/gitterHQ/gitter.svg[Talk on Gitter,link=https://gitter.im/kigster/simple-feed]
 
----
+IMPORTANT: Please read the (somewhat outdated) blog post http://kig.re/2017/02/19/feeding-frenzy-with-simple-feed-activity-feed-ruby-gem.html[Feeding Frenzy with SimpleFeed] launching this library. Please leave comments or questions in the discussion thread at the bottom of that post. Thanks!
 
 If you like to see this project grow, your donation of any amount is much appreciated.
 
-[![Donate](https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=FSFYYNEQ8RKWU)
+image::https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif[Donate,link=https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=FSFYYNEQ8RKWU]
+'''
 
----
+This is a fast, pure-ruby implementation of an activity feed concept commonly used in social networking applications. The implementation is optimized for *read-time performance* and high concurrency (lots of users), and can be extended with custom backend providers. Two providers come bundled: the production-ready Redis provider, and a naive Ruby Hash-based provider.
 
-This is a fast, pure-ruby implementation of an activity feed concept commonly used in social networking applications. The implementation is optimized for **read-time performance** and high concurrency (lots of users), and can be extended with custom backend providers. Two providers come bundled: the production-ready Redis provider, and a naive Ruby Hash-based provider.
+*Important Notes and Acknowledgements:*
 
-__Important Notes and Acknowledgements:__
+* SimpleFeed _does not depend on Ruby on Rails_ and is a *pure-ruby* implementation
+* SimpleFeed requires ruby 2.3 or later
+* SimpleFeed is currently live in production
+* SimpleFeed is open source thanks to the generosity of *http://simbi.com[Simbi, Inc]*.
 
- * SimpleFeed *does not depend on Ruby on Rails* and is a __pure-ruby__ implementation
- * SimpleFeed requires ruby 2.3 or later
- * SimpleFeed is currently live in production
- * SimpleFeed is open source thanks to the generosity of __[Simbi, Inc](http://simbi.com)__.
+== Features
 
-## Background, Examples, Serialization, etc
+SimpleFeed offers the following features:
 
-Please read the additional documentation, including the examples, on the [project's Github Wiki](https://github.com/kigster/simple-feed/wiki).
+ * Highly performant Redis-based activity feed
 
-## Usage
+ * Scales to millions of users (may need to use Twemproxy to shard across several Redis instances)
+
+ * Stores a fixed number of events per unique activity ID (eg, a user) — the default is 2000. When the full list is used, the oldest events are bumped off the feed (and are effectively trashed).
+
+ * Store user_id as either a string or an integer (the latter is base62 encoded when serialized, so very large users_ids are OK)
+
+ * Updating feeds of N users is roughly a O(N * log(N)) operation
+
+ * Reading feed for one user (or one type of user) is a O(1) operation
+
+ * For each activity (user) read the number of total and new items in the feed, computed since the user last saw their feed.
+
+ * Delete items from user's feed selectively (for instance, if a user unfollows someone they shouldn't see their events anymore).
+
+ * Automatically reset the timestamp when the user last read their feed when reading from the feed (or not, it's an argument). As soon as the user reads their feed (you call the `paginate` method), the "unread counter" is reset to 0.
+
+ * You can create as many different types of feeds per application as you like. No Singletons are used.
+
+ * Thread-safe implementation.
+
+ * Zero assumptions about what you are storing: the "data" is just a string. Serialize it with JSON, Marshall, YAML, or whatever.
+
+== Background, Examples, Serialization, etc
+
+Please read the additional documentation, including the examples, on the https://github.com/kigster/simple-feed/wiki[project's Github Wiki].
+
+Below is a screen shot of an actual activity feed powered by this library.
+
+image::https://raw.githubusercontent.com/kigster/simple-feed/master/man/activity-feed-action.png[usage]
+
+== Usage
 
 A key concept to understanding SimpleFeed gem, is that of a _provider_, which is effectively a persistence implementation for the events belonging to each user.
 
 Two providers are supplied with this gem:
 
- * The production-ready `:redis` provider, which uses the [sorted set Redis data type](https://redislabs.com/ebook/redis-in-action/part-2-core-concepts-2/chapter-3-commands-in-redis/3-5-sorted-sets) to store and fetch the events, scored by time (but not necessarily). 
-
- * The naïve `:hash` provider based on the ruby `Hash` class, that can be useful in unit tests, or in simple simulations. 
+* The production-ready `:redis` provider, which uses the https://redislabs.com/ebook/redis-in-action/part-2-core-concepts-2/chapter-3-commands-in-redis/3-5-sorted-sets[sorted set Redis data type] to store and fetch the events, scored by time (but not necessarily).
+* The naïve `:hash` provider based on the ruby `Hash` class, that can be useful in unit tests, or in simple simulations.
 
 You initialize a provider by using the `SimpleFeed.provider([Symbol])` method.
 
-### Configuration
+=== Configuration
 
-Below we configure a feed called `:newsfeed`, which in this example will be populated with the various events coming from the followers. 
+Below we configure a feed called `:newsfeed`, which in this example will be populated with the various events coming from the followers.
 
-```ruby
+[source,ruby]
+----
 require 'simplefeed'
 
-# Let's define a Redis-based feed, and wrap Redis in a in a ConnectionPool. 
+# Let's define a Redis-based feed, and wrap Redis in a in a ConnectionPool.
 SimpleFeed.define(:newsfeed) do |f|
-  f.provider   = SimpleFeed.provider(:redis, 
+  f.provider   = SimpleFeed.provider(:redis,
                                       redis: -> { ::Redis.new },
                                       pool_size: 10)
   f.per_page   = 50     # default page size
   f.batch_size = 10     # default batch size
   f.namespace  = 'nf'   # only needed if you use the same redis for more than one feed
 end
-```
+----
 
 After the feed is defined, the gem creates a similarly named method under the `SimpleFeed` namespace to access the feed. For example, given a name such as `:newsfeed` the following are all valid ways of accessing the feed:
 
- * `SimpleFeed.newsfeed`
- * `SimpleFeed.get(:newsfeed)`
+* `SimpleFeed.newsfeed`
+* `SimpleFeed.get(:newsfeed)`
 
 You can also get a full list of currently defined feeds with `SimpleFeed.feed_names` method.
 
-### Reading from and writing to the feed
+=== User IDs
+
+In the following section you will see the examples of reading and writing activity for users based on their ID.
+
+SimpleFeed supports user IDs that are either numeric (integer) or string-based (eg, UUID).
+
+If your User IDs are numeric, they generate redis keys using Base62 encoding (which makes them shorter, and more compact).
+
+For string User IDs, the only transformation performed is the basic link:https://en.wikipedia.org/wiki/ROT13[`rot13`] in case user ids are semi-sensitive.
 
-For the impatient here is a quick way to get started with the `SimpleFeed`.
+==== Partitioning Schema
 
-```ruby
+You can take advantage of string user IDs for situations where your feed requires a composite keys for instance. Just remember that SimpleFeed does not care about what's in your user ID, and even what you call "a user". It's convenient to think of the activities in terms of users, because typically each user has a unique feed that only they see.
+
+But you can just as easily use zip code as the unique activity ID, and create one feed of events per geographical location, that all folks living in that zip code share. But what about other countries?
+
+Now you use partioning scheme: make "user_id" a combination `iso_country_code.postal_code`, eg for San Francisco, you'd use `us.94107`, but for Australia you could use, eg `au.3148`.
+
+=== Reading from and writing to the feed
+
+For the impatient, here is a quick way to get started with the `SimpleFeed`.
+
+[source,ruby]
+----
 # This assumes we have previously defined a feed named :newsfeed (see above)
 activity = SimpleFeed.newsfeed.activity(@current_user.id)
 # Store directly the value and the optional time stamp
@@ -88,7 +142,7 @@ activity.store(value: 'hello')
 @event = SimpleFeed::Event.new('hello', Time.now)
 activity.store(event: @event)
 # => false # false indicates that the same event is already in the feed.
-```
+----
 
 As we've added events for this user, we can request them back, sorted by
 the time and paginated. If you are using a distributed provider, such as
@@ -96,34 +150,37 @@ the time and paginated. If you are using a distributed provider, such as
 application, not just the one that published the event (which is the
 case for the "toy" `Hash::Provider`.
 
-```ruby
+[source,ruby]
+----
 activity.paginate(page: 1, reset_last_read: true)
 # => [ <SimpleFeed::Event#0x2134afa value='hello' at='2016-11-20 23:32:56 -0800'> ]
-```
+----
 
-### The Two Forms of the API
+=== The Two Forms of the API
 
 The feed API is offered in two forms:
 
- 1. single-user form, and 
- 2. a batch (multi-user) form.
+. single-user form, and
+. a batch (multi-user) form.
 
 The method names and signatures are the same. The only difference is in what the methods return:
 
- 1. In the single user case, the return of, say, `#total_count` is an `Integer` value representing the total count for this user.
- 2. In the multi-user case, the return is a `SimpleFeed::Response` instance, that can be thought of as a `Hash`, that has the user IDs as the keys, and return results for each user as a value. 
+. In the single user case, the return of, say, `#total_count` is an `Integer` value representing the total count for this user.
+. In the multi-user case, the return is a `SimpleFeed::Response` instance, that can be thought of as a `Hash`, that has the user IDs as the keys, and return results for each user as a value.
 
-Please see further below the details about the [Batch API](#batch-api).
+Please see further below the details about the <<batch-api,Batch API>>.
 
-<a name="single-user-api"/>
++++<a name="single-user-api">++++++</a>+++
 
-##### Single-User API 
+[discrete]
+===== Single-User API
 
 In the examples below we show responses based on a single-user usage. As previously mentioned, the multi-user usage is the same, except what the response values are, and is discussed further down below.
 
 Let's take a look at a ruby session, which demonstrates return values of the feed operations for a single user:
 
-```ruby
+[source,ruby]
+----
 require 'simplefeed'
 
 # Define the feed using an in-memory Hash provider, which uses
@@ -134,17 +191,21 @@ SimpleFeed.define(:followers) do |f|
   f.per_page = 2
 end
 
-# Let's get the Activity instance that wraps this user_id
-activity = SimpleFeed.followers.activity(user_id)   # => [... complex object removed for brevity ]
+# Let's get the Activity instance that wraps this
+activity = SimpleFeed.followers.activity(user_id)         # => [... complex object removed for brevity ]
+
 # let's clear out this feed to ensure it's empty
 activity.wipe                                             # => true
+
 # Let's verify that the counts for this feed are at zero
 activity.total_count                                      # => 0
 activity.unread_count                                     # => 0
+
 # Store some events
 activity.store(value: 'hello')                            # => true
 activity.store(value: 'goodbye', at: Time.now - 20)       # => true
 activity.unread_count                                     # => 2
+
 # Now we can paginate the events, while resetting this user's last-read timestamp:
 activity.paginate(page: 1, reset_last_read: true)
 # [
@@ -159,49 +220,54 @@ activity.delete(value: 'hello')                           # => true
 # array of all events that have been deleted for this user.
 activity.delete_if do |event, user_id|
   event.value =~ /good/
-end                                                       
+end
 # => [
 #     [0] #<SimpleFeed::Event: value=good bye, at=1480475294.0579991>
-# ]   
+# ]
 activity.total_count                                      # => 0
-```
+----
 
-You can fetch all items (optionally filtered by time) in the feed using `#fetch`, 
+You can fetch all items (optionally filtered by time) in the feed using `#fetch`,
 `#paginate` and reset the `last_read` timestamp by passing the `reset_last_read: true` as a parameter.
 
-<a name="batch-api"/>
++++<a name="batch-api">++++++</a>+++
 
-#####  Batch (Multi-User) API 
+[discrete]
+===== Batch (Multi-User) API
 
 This API should be used when dealing with an array of users (or, in the
-future, a Proc or an ActiveRecord relation). 
+future, a Proc or an ActiveRecord relation).
+
+____
+There are several reasons why this API should be preferred for
+operations that perform a similar action across a range of users:
+_various provider implementations can be heavily optimized for
+concurrency, and performance_.
 
-> There are several reasons why this API should be preferred for
-> operations that perform a similar action across a range of users:
-> _various provider implementations can be heavily optimized for
-> concurrency, and performance_.
-> 
-> The Redis Provider, for example, uses a notion of `pipelining` to send
-> updates for different users asynchronously and concurrently.
+The Redis Provider, for example, uses a notion of `pipelining` to send
+updates for different users asynchronously and concurrently.
+____
 
 Multi-user operations return a `SimpleFeed::Response` object, which can
 be used as a hash (keyed on user_id) to fetch the result of a given
 user.
 
-```ruby
+[source,ruby]
+----
 # Using the Feed API with, eg #find_in_batches
 @event_producer.followers.find_in_batches do |group|
- 
+
   # Convert a group to the array of IDs and get ready to store
   activity = SimpleFeed.get(:followers).activity(group.map(&:id))
   activity.store(value: "#{@event_producer.name} liked an article")
-  
-  # => [Response] { user_id1 => [Boolean], user_id2 => [Boolean]... } 
+
+  # => [Response] { user_id1 => [Boolean], user_id2 => [Boolean]... }
   # true if the value was stored, false if it wasn't.
 end
-```
+----
 
-##### Activity Feed DSL (Domain-Specific Language) 
+[discrete]
+===== Activity Feed DSL (Domain-Specific Language)
 
 The library offers a convenient DSL for adding feed functionality into
 your current scope.
@@ -211,7 +277,8 @@ exports just one primary method `#with_activity`. You call this method
 and pass an activity object created for a set of users (or a single
 user), like so:
 
-```ruby
+[source,ruby]
+----
 require 'simplefeed/dsl'
 include SimpleFeed::DSL
 
@@ -226,43 +293,46 @@ end
 with_activity(activity, countries: data_to_store) do
   # we can use countries as a variable because it was passed above in **opts
   countries.each do |country|
-    # we can call #store without a receiver because the block is passed to 
+    # we can call #store without a receiver because the block is passed to
     # instance_eval
     store(value: country) { |result| report(result ? 'success' : 'failure') }
-    # we can call #report inside the proc because it is evaluated in the 
+    # we can call #report inside the proc because it is evaluated in the
     # outside context of the #with_activity
-    
-    # now let's print a color ASCII dump of the entire feed for this user: 
-    color_dump 
-  end  
+
+    # now let's print a color ASCII dump of the entire feed for this user:
+    color_dump
+  end
   printf "Activity counts are: %d unread of %d total\n", unread_count, total_count
 end
-```
+----
 
-The DSL context has access to two additional methods: 
+The DSL context has access to two additional methods:
 
- * `#event(value, at)` returns a fully constructed `SimpleFeed::Event` instance
- * `#color_dump` prints to STDOUT the ASCII text dump of the current user's activities (events), as well as the counts and the `last_read` shown visually on the time line.
- 
-##### `#color_dump`
+* `#event(value, at)` returns a fully constructed `SimpleFeed::Event` instance
+* `#color_dump` prints to STDOUT the ASCII text dump of the current user's activities (events), as well as the counts and the `last_read` shown visually on the time line.
+
+[discrete]
+===== `#color_dump`
 
 Below is an example output of `color_dump` method, which is intended for the debugging purposes.
 
-[<img src="https://raw.githubusercontent.com/kigster/simple-feed/master/man/sf-color-dump.png" width="450" alt="color_dump output" style="width: 300px; max-width:100%;">](https://raw.githubusercontent.com/kigster/simple-feed/master/man/sf-color-dump.png)
+[image:https://raw.githubusercontent.com/kigster/simple-feed/master/man/sf-color-dump.png[color_dump output,450]](https://raw.githubusercontent.com/kigster/simple-feed/master/man/sf-color-dump.png)
 
-<a name="api"/>
++++<a name="api">++++++</a>+++
 
-## Complete API
+== Complete API
 
-For completeness sake we'll show the multi-user API responses only. For a single-user use-case the response is typically a scalar, and the input is a singular `user_id`, not an array of ids. 
+For completeness sake we'll show the multi-user API responses only. For a single-user use-case the response is typically a scalar, and the input is a singular `user_id`, not an array of ids.
 
-#### Multi-User (Batch) API
+[discrete]
+==== Multi-User (Batch) API
 
 Each API call at this level expects an array of user IDs, therefore the
 return value is an object, `SimpleFeed::Response`, containing individual
 responses for each user, accessible via `response[user_id]` method.
 
-```ruby
+[source,ruby]
+----
 @multi = SimpleFeed.get(:feed_name).activity(User.active.map(&:id))
 
 @multi.store(value:, at:)
@@ -274,7 +344,7 @@ responses for each user, accessible via `response[user_id]` method.
 # => [Response] { user_id => [Boolean], ... } true if the value was removed, false if it didn't exist
 
 @multi.delete_if do |event, user_id|
-  # if the block returns true, the event is deleted and returned 
+  # if the block returns true, the event is deleted and returned
 end
 # => [Response] { user_id => [deleted_event1, deleted_event2, ...], ... }
 
@@ -283,15 +353,15 @@ end
 # => [Response] { user_id => [Boolean], ... } true if user activity was found and deleted, false otherwise
 
 # Return a paginated list of all items, optionally with the total count of items
-@multi.paginate(page: 1, 
-                per_page: @multi.feed.per_page, 
-                with_total: false, 
+@multi.paginate(page: 1,
+                per_page: @multi.feed.per_page,
+                with_total: false,
                 reset_last_read: false)
 # => [Response] { user_id => [Array]<Event>, ... }
 # Options:
 #   reset_last_read: false — reset last read to Time.now (true), or the provided timestamp
 #   with_total: true — returns a hash for each user_id:
-#        => [Response] { user_id => { events: Array<Event>, total_count: 3 }, ... } 
+#        => [Response] { user_id => { events: Array<Event>, total_count: 3 }, ... }
 
 # Return un-paginated list of all items, optionally filtered
 @multi.fetch(since: nil, reset_last_read: false)
@@ -305,111 +375,106 @@ end
 # => [Response] { user_id => [Time] last_read, ... }
 
 @multi.total_count
-# => [Response] { user_id => [Integer] total_count, ... }
+# => [Response] { user_id => [Integer, String] total_count, ... }
 
 @multi.unread_count
-# => [Response] { user_id => [Integer] unread_count, ... }
+# => [Response] { user_id => [Integer, String] unread_count, ... }
 
 @multi.last_read
 # => [Response] { user_id => [Time] last_read, ... }
+----
 
-```
-
-## Providers in Depth 
+== Providers
 
-As we've discussed above, a provider is an underlying persistence mechanism implementation. 
+As we've discussed above, a provider is an underlying persistence mechanism implementation.
 
 It is the intention of this gem that:
 
- * it should be easy to write new providers 
- * it should be easy to swap out providers
+* it should be easy to write new providers
+* it should be easy to swap out providers
 
 To create a new provider please use `SimpleFeed::Providers::Hash::Provider` class as a starting point.
 
 Two providers are available with this gem:
 
-### `SimpleFeed::Providers::Redis::Provider` 
+=== `SimpleFeed::Providers::Redis::Provider`
 
-Redis Provider is a production-ready persistence adapter that uses the [sorted set Redis data type](https://redislabs.com/ebook/redis-in-action/part-2-core-concepts-2/chapter-3-commands-in-redis/3-5-sorted-sets). 
+Redis Provider is a production-ready persistence adapter that uses the https://redislabs.com/ebook/redis-in-action/part-2-core-concepts-2/chapter-3-commands-in-redis/3-5-sorted-sets[sorted set Redis data type].
 
-This provider is optimized for large writes and can use either a single Redis instance for all users of your application, or any number of Redis [shards](https://en.wikipedia.org/wiki/Shard_(database_architecture)) by using a [_Twemproxy_](https://github.com/twitter/twemproxy) in front of the Redis shards. 
+This provider is optimized for large writes and can use either a single Redis instance for all users of your application, or any number of Redis https://en.wikipedia.org/wiki/Shard_(database_architecture)[shards] by using a https://github.com/twitter/twemproxy[_Twemproxy_] in front of the Redis shards.
 
-While future 
+=== `SimpleFeed::Providers::HashProvider`
 
- * `SimpleFeed::Providers::HashProvider` is a pure Hash-like implementation of a provider that can be useful in unit tests of a host application. This provider could be used to write and read events within a single ruby process, can be serialized to and from a YAML file, and is therefore intended primarily for Feed emulations in automated tests.
-  
+This is a pure Hash-like implementation of a provider that can be useful in unit tests of a host application. This provider could be used to write and read events within a single ruby process, can be serialized to and from a YAML file, and is therefore intended primarily for Feed emulations in automated tests.
 
-### Redis Provider
+== Redis Provider
 
 If you set environment variable `REDIS_DEBUG` to `true` and run the example (see below) you will see every operation redis performs. This could be useful in debugging an issue or submitting a bug report.
-  
-## Running the Examples
+
+== Running the Examples
 
 Source code for the gem contains the `examples` folder with an example file that can be used to test out the providers, and see what they do under the hood.
 
 To run it, checkout the source of the library, and then:
 
-```bash
+[source,bash]
+----
 git clone https://github.com/kigster/simple-feed.git
 cd simple-feed
 bundle
 be rspec  # make sure tests are passing
-ruby examples/redis_provider_example.rb 
-```
+ruby examples/redis_provider_example.rb
+----
 
-The above command will help you download, setup all dependencies, and run the examples for a single user: 
+The above command will help you download, setup all dependencies, and run the examples for a single user:
 
-[![Example](https://raw.githubusercontent.com/kigster/simple-feed/master/man/running-example.png)](https://raw.githubusercontent.com/kigster/simple-feed/master/man/running-example.png)
+image::https://raw.githubusercontent.com/kigster/simple-feed/master/man/running-example.png[Example,link=https://raw.githubusercontent.com/kigster/simple-feed/master/man/running-example.png]
 
 If you set `REDIS_DEBUG` variable prior to running the example, you will be able to see every single Redis command executed as the example works its way through. Below is a sample output:
 
-[![Example with Debugging](https://raw.githubusercontent.com/kigster/simple-feed/master/man/running-example-redis-debug.png)](https://raw.githubusercontent.com/kigster/simple-feed/master/man/running-example-redis-debug.png)
+image::https://raw.githubusercontent.com/kigster/simple-feed/master/man/running-example-redis-debug.png[Example with Debugging,link=https://raw.githubusercontent.com/kigster/simple-feed/master/man/running-example-redis-debug.png]
 
-### Generating Ruby API Documentation
+=== Generating Ruby API Documentation
 
-```bash
+[source,bash]
+----
 rake doc
-```
+----
 
 This should use Yard to generate the documentation, and open your browser once it's finished.
 
-### Installation
+=== Installation
 
 Add this line to your application's Gemfile:
 
-```ruby
+[source,ruby]
+----
 gem 'simple-feed'
-```
+----
 
 And then execute:
 
-```
-$ bundle
-```
+ $ bundle
 
 Or install it yourself as:
 
-```
-$ gem install simple-feed
-```
+ $ gem install simple-feed
 
-### Development
+=== Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to https://rubygems.org[rubygems.org].
 
-### Contributing
+=== Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/kigster/simple-feed
 
-### License
-
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-
-### Acknowledgements
+=== License
 
- * This project is conceived and sponsored by [Simbi, Inc.](https://simbi.com).
- * Author's personal experience at [Wanelo, Inc.](https://wanelo.com) has served as an inspiration.
+The gem is available as open source under the terms of the http://opensource.org/licenses/MIT[MIT License].
 
+=== Acknowledgements
 
+* This project is conceived and sponsored by https://simbi.com[Simbi, Inc.].
+* Author's personal experience at https://wanelo.com[Wanelo, Inc.] has served as an inspiration.