notably 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bd247eba7aa38faf56a73e9eb6bb8734d22e4358
+  data.tar.gz: 739b8d7bb0d16402b478e2c79d3c30e1d3822813
+SHA512:
+  metadata.gz: cc524ed6ef36a6fe5f56ded1cc91b58011603426af5e9876ec6dc0fd33d35dcea1945d4d86bf6321b3a7cc61a6c8b55c03857823b892913209513b57fd8e8a4e
+  data.tar.gz: fcb35392ccaf761b3a6a666a1752668e5114621539fc578c7dfe64ea34b40e0ea8a684c8b1248d8c5809d66eae2ce1dd6efa8c8fb418cc280a17f9d8c5c9e8d4

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in notably.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 UpTrending LLC
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,251 @@
+# Notably
+
+Notably is a redis-backed notification system.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'notably'
+```
+
+And then execute:
+
+```
+$ bundle
+```
+
+Or install it yourself as:
+
+```
+$ gem install notably
+```
+
+## Concepts
+
+Before we dive right in to usage, let me quickly go over a few of the basic concepts of Notably.
+
+### Notification
+
+Most simply, we have a Notification module which you can include in your own classes. It expects a few methods to be overridden, and provides a few helper methods.
+
+Notifications have required attributes, which you set. For instance a CommentNotification might have required attributes of `:comment_id` and `:author_id`. Those attributes become accessor methods that you can use inside your class. Then you must define two methods: `to_html` and `receivers`.
+
+`to_html` should return an html string, which is what you will use in the view to display the notification to the user. (If you're using Rails, you'll have access to all the standard view helpers)
+
+`receivers` should return an array of models to be notified by this notification. All the models returned should be of a class that includes the `Notably::Notifiable` module.  Speaking of...
+
+### Notifiable
+
+The Notifiable module is what you include in the classes that should be notified of things. The only demand placed on the class that includes it is that it responds to and returns a unique value for `id`. So if you're including it in an `ActiveRecord::Base` subclass, you should be good to go.
+
+Notifiable adds these public methods to your class:
+
+* `notifications` Return an array of all notifications
+* `notifications_since(time)` Return an array of all notifications that happened after the time parameter
+* `unread_notifications` Return an array of all unread notifications
+* `unread_notifications!` Return an array of all unread notifications, and update the last_notification_read_at time atomically
+* `read_notifications` Return an array of all read notifications
+* `read_notifications!` Update the last_notification_read_at time
+* `last_notification_read_at` Return an integer representing the time the last notification was read
+* `notification_key` The key in redis where the notifications will get stored
+* `last_notification_read_at_key` The key in redis where the last_notification_read_at will get stored
+
+For most setups, you should probably only really need access to three or so of those methods.
+
+## Usage
+
+Lets try implementing a comment notification in a sample Rails app with a User model and a Comment model.  We'll start from here:
+
+```ruby
+# app/models/user.rb
+class User < ActiveRecord::Base
+  has_many :comments, foreign_key: :author_id
+end
+
+# app/models/comment.rb
+class Comment < ActiveRecord::Base
+  belongs_to :author, class_name: User
+  belongs_to :commentable, polymorphic: true, touch: true
+end
+
+# app/controllers/comments_controller.rb
+class CommentsController < ApplicationController
+  before_filter :require_login
+  respond_to :json
+  def create
+    @comment = current_user.comments.create(comment_params)
+    respond_with @comment
+  end
+
+  private
+
+  def comment_params
+    params.require(:comment).permit(:body, :commentable_type, :commentable_id)
+  end
+end
+```
+
+So to begin we know we want our Users to be the one getting the notifications, so lets go ahead and include the necessary module
+
+```ruby
+# app/models/user.rb
+class User < ActiveRecord::Base
+  include Notably::Notifiable
+  # ...
+end
+```
+
+Now we need to create our `CommentNotification` class. I like to do that in an app/notifications directory.  I'll show the finished product here, and then walk through it line by line.
+
+```ruby
+# app/notifications/comment_notification.rb
+class CommentNotification
+  include Notably::Notification
+  required_attributes :commentable_type, :commentable_id, :author_id
+
+  def to_html
+    "#{author.short_name} commented on #{link_to commentable.name, polymorphic_path(commentable)}"
+  end
+
+  def receivers
+    commentable.comments.pluck(:author_id).uniq - [author_id]
+  end
+
+  def commentable
+    @commentable ||= commentable_type.constantize.find(commentable_id)
+  end
+
+  def author
+    @author ||= User.where(id: author_id)
+  end
+end
+```
+
+So first we include our Notification module, then define the required attributes. The next thing I did was set up the `commentable` and `author` methods for convenience sake, which uses the required attributes to look up the models they point to.  Then I wrote the `to_html` method which would return something that looks like:
+
+> Michael B. commented on [Save Our Bluths](#)
+
+Then I define the `receivers` method which will return a list of users that have also commented on whatever it is I'm commenting on, minus the author of the comment we're currently notifying people about.
+
+Ok, so far so good. Now we just need to hook up the notification creation. I'm sure there's some debate to be had about where the best place to put Notification creation would be, but to me it makes the most sense to have it in the controller. So...
+
+```ruby
+# app/controllers/comments_controller.rb
+class CommentsController < ApplicationController
+  # ...
+  def create
+    @comment = current_user.comments.create(comment_params)
+    CommentNotification.create(@comment)
+    respond_with @comment
+  end
+  # ...
+end
+```
+
+And... we're done. Let me explain a bit about how that create method is working. You can pass it an object, or a hash. The object must respond to all the required attributes. And if it's a hash, it must have a key-value for each required attribute. So I could have just as easily have done
+
+```ruby
+CommentNotification.create(
+  commentable_type: @comment.commentable_type,
+  commentable_id: @comment.commentable_id,
+  author_id: current_user.id})
+```
+
+But where's the fun in that?
+
+## Grouping
+
+Ok so things are looking pretty good, except the Save Our Bluths post is getting kind of popular, and my notification feed looks like this:
+
+> Michael B. commented on [Save Our Bluths](#)
+
+> Lucille B. commented on [Save Our Bluths](#)
+
+> Buster B. commented on [Save Our Bluths](#)
+
+> Tobius F. commented on [Save Our Bluths](#)
+
+It would be nicer if it looked like
+
+> Buster B., Lucille B., Michael B., and Tobius F. commented on [Save Our Bluths](#)
+
+And what a wonderful time to show you Notably's grouping feature! It works by defining a subset of the required attributes that you group by. So if we wanted to group our `CommentNotification` like I did above, we would write this:
+
+```ruby
+# app/notifications/comment_notification.rb
+class CommentNotification
+  include Notably::Notification
+  required_attributes :commentable_type, :commentable_id, :author_id
+  group_by :commentable_type, :commentable_id
+
+  # ...
+end
+```
+
+So let me explain how it's doing this. When a new notification is being saved, it's going to look at the receiver's current notification list, and see if any of them match the `group_by` attributes of the one that is currently saving. If there are any, than it adds the attributes of those that are not being grouped by (in our case, just `:author_id`) to an array that is accessible to you through the `groups` method. As soon as you add the `group_by` line, you have access to all non-grouped-by attributes through the `groups` method. So lets see how that would affect our `CommentNotification` class.
+
+```ruby
+# app/notifications/comment_notification.rb
+class CommentNotification
+  include Notably::Notification
+  required_attributes :commentable_type, :commentable_id, :author_id
+  group_by :commentable_type, :commentable_id
+
+  def to_html
+    "#{authors.collect(&:short_name).to_sentence} commented on #{link_to commentable.name, polymorphic_path([commentable.project, commentable])}"
+  end
+
+  def receivers
+    commentable.comments.pluck(:author_id).uniq - [author_id]
+  end
+
+  def commentable
+    @commentable ||= commentable_type.constantize.find(commentable_id)
+  end
+
+  def authors
+    @authors ||= User.where(id: groups.collect(&:author_id)).order(:first_name)
+  end
+end
+```
+
+And that's really it. `groups` returns an array of OpenStructs that have all the non-grouped-by attributes of all the notifications that are being grouped, including the current notification. But notice that (as I use in the `receivers` method) you can still access `author_id` directly, which will just give you the author_id of the current notification that's being saved.
+
+There's one part of Grouping that I haven't mention yet, and that is `group_within`, which lets you specify the time range that the notification has to fall into in order to be eligable to be grouped. You probably don't want a notification from last week to be grouped with one that just happened. Or maybe you do, and you can set that. By default, it groups within the last_notification_read_at
+time. Which I think is a good sensible default, if you're using last_notification_read_at. Otherwise it might be best to set it to a generic `4.hours.ago`. You set it by passing it a lambda or Proc. The lambda or Proc should have one argument, which will be the receiver who's notification list it's grouping from. So this might look like:
+
+```ruby
+# app/notifications/comment_notification.rb
+class CommentNotification
+  include Notably::Notification
+  required_attributes :commentable_type, :commentable_id, :author_id
+  group_by :commentable_type, :commentable_id
+  group_within ->(receiver) { 4.hours.ago }
+  # ...
+end
+```
+
+Or
+
+```ruby
+  group_within ->(receiver) { receiver.updated_at }
+```
+
+Or
+
+```ruby
+  group_within ->(receiver) { receiver.last_notification_read_at } # default
+```
+
+(Just a warning, even if you're setting it to something that doesn't need the receiver passed in to calculate it, you need to specify it as an argument if you're going to use lambdas. They don't like it when arguments get ignored.)
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/notably.rb

@@ -0,0 +1,14 @@
+require "notably/configuration"
+require "notably/notification"
+require "notably/notifiable"
+require "notably/version"
+
+module Notably
+  module_function
+
+  def config
+    @config ||= Configuration.new
+    yield @config if block_given?
+    @config
+  end
+end

data/lib/notably/configuration.rb

@@ -0,0 +1,12 @@
+module Notably
+  class Configuration
+    attr_writer :redis
+
+    def initialize
+    end
+
+    def redis
+      @redis ||= Redis.current
+    end
+  end
+end

data/lib/notably/notifiable.rb

@@ -0,0 +1,46 @@
+module Notably
+  module Notifiable
+
+    def notifications
+      parse_notifications(Notably.config.redis.zrevrangebyscore(notification_key, Time.now.to_i, 0))
+    end
+
+    def notifications_since(time)
+      parse_notifications(Notably.config.redis.zrevrangebyscore(notification_key, Time.now.to_i, time.to_i))
+    end
+
+    def unread_notifications
+      notifications_since(last_notification_read_at)
+    end
+
+    def unread_notifications!
+      notifications_since(Notably.config.redis.getset(last_notification_read_at_key, Time.now.to_i))
+    end
+
+    def read_notifications
+      parse_notifications(Notably.config.redis.zrevrangebyscore(notification_key, last_notification_read_at, 0))
+    end
+
+    def read_notifications!
+      parse_notifications(Notably.config.redis.set(last_notification_read_at_key, Time.now.to_i))
+    end
+
+    def last_notification_read_at
+      Notably.config.redis.get(last_notification_read_at_key).to_i
+    end
+
+    def notification_key
+      "notably:notifications:#{self.class}:#{self.id}"
+    end
+
+    def last_notification_read_at_key
+      "notably:last_read_at:#{self.class}:#{self.id}"
+    end
+
+    private
+
+    def parse_notifications(notifications)
+      notifications.collect { |n| Marshal.load(n) }
+    end
+  end
+end

data/lib/notably/notification.rb

@@ -0,0 +1,136 @@
+module Notably
+  module Notification
+    attr_accessor :data, :created_at, :groups
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      if defined?(Rails) && defined?(ActionView)
+        base.send(:include, ActionView::Helpers)
+        base.send(:include, Rails.application.routes.url_helpers)
+      end
+    end
+
+    def to_s
+      ActionView::Base.full_sanitizer.sanitize(to_html) if defined?(ActionView)
+    end
+
+    def to_html
+      ""
+    end
+
+    def receivers
+      []
+    end
+
+    def initialize(*attributes_hashes)
+      @data = {}
+      @groups = []
+      attributes_hashes.each do |attributes|
+        case attributes
+        when Hash
+          raise ArgumentError, "Hash does not have all required attributes" unless self.class.required_attributes.all? { |k| attributes.key? k }
+          if @data.any?
+            raise ArgumentError, "Group by fields do not have shared values" unless @data == attributes.slice(*self.class.group_by)
+          else
+            @data = attributes
+          end
+          @groups << OpenStruct.new(attributes.except(*self.class.group_by))
+        else
+          raise ArgumentError, "Object #{attributes} does not respond to all required attributes" unless self.class.required_attributes.all? { |k| attributes.respond_to? k }
+          if @data.any?
+            raise ArgumentError, "Group by fields do not have shared values" unless @data == Hash[self.class.group_by.collect { |k| [k, attributes.send(k)] }]
+          else
+            @data = Hash[self.class.required_attributes.collect { |k| [k, attributes.send(k)] }]
+          end
+          @groups << OpenStruct.new(Hash[(self.class.required_attributes - self.class.group_by).collect { |k| [k, attributes.send(k)] }])
+        end
+      end
+    end
+
+    def save
+      receivers.each do |receiver|
+        # look for groupable messages within group_within
+        # group_within = self.class.group_within.arity == 1 ? self.class.group_within.call(user) : self.class.group_within.call
+        group_within = self.class.group_within.call(receiver)
+        groupable_notifications = receiver.notifications_since(group_within)
+        groupable_notifications.select! { |notification| notification[:data].slice(*self.class.group_by) == data.slice(*self.class.group_by) }
+        groupable_notifications.each do |notification|
+          @groups += notification[:groups]
+        end
+        Notably.config.redis.pipelined do
+          Notably.config.redis.zadd(receiver.send(:notification_key), created_at.to_i, marshal)
+          groupable_notifications.each do |notification|
+            Notably.config.redis.zrem(receiver.send(:notification_key), Marshal.dump(notification))
+            @groups -= notification[:groups]
+          end
+        end
+      end
+    end
+
+    def to_h
+      {
+        created_at: created_at,
+        data: data,
+        groups: groups,
+        message: to_s,
+        html: to_html
+      }
+    end
+
+    def marshal
+      Marshal.dump(to_h)
+    end
+
+    def created_at
+      @created_at ||= Time.now
+    end
+
+    def method_missing(method, *args, &block)
+      if method.to_s =~ /=/
+        method = method.to_s.gsub!('=', '')
+        if @data.key? method
+          @data[method.to_sym] = *args
+        end
+      else
+        if @data.key? method
+          @data[method]
+        else
+          super
+        end
+      end
+    end
+
+    module ClassMethods
+      def create(attributes={})
+        new(attributes).save
+      end
+
+      def required_attributes(*args)
+        if args.any?
+          @required_attributes ||= []
+          @required_attributes += args
+        else
+          @required_attributes ||= []
+        end
+      end
+
+      def group_by(*args)
+        if args.any?
+          @group_by ||= []
+          @group_by += args
+        else
+          @group_by ||= []
+        end
+      end
+
+      def group_within(block=nil)
+        if block
+          @group_within = block
+        else
+          @group_within ||= ->(receiver) { receiver.last_notification_read_at }
+        end
+      end
+    end
+
+  end
+end

data/lib/notably/version.rb

@@ -0,0 +1,3 @@
+module Notably
+  VERSION = "0.0.1"
+end

data/notably.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'notably/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "notably"
+  spec.version       = Notably::VERSION
+  spec.authors       = ["Will Cosgrove"]
+  spec.email         = ["will@willcosgrove.com"]
+  spec.description   = %q{A redis backed notification system}
+  spec.summary       = %q{A redis backed notification system}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: notably
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Will Cosgrove
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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'
+description: A redis backed notification system
+email:
+- will@willcosgrove.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/notably.rb
+- lib/notably/configuration.rb
+- lib/notably/notifiable.rb
+- lib/notably/notification.rb
+- lib/notably/version.rb
+- notably.gemspec
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: A redis backed notification system
+test_files: []