opt_out 1.0.0

data/.gitignore

@@ -0,0 +1,14 @@
+*.gem
+*.rbc
+*.db
+.bundle
+.config
+.yardoc
+.env
+Gemfile.lock
+_yardoc
+doc/
+pkg
+rdoc
+tmp
+vendor/gems

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in html-pipeline.gemspec
+gemspec
+
+group :development do
+  gem 'bundler'
+  gem 'rake'
+  gem 'dotenv'
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Jerry Cheung
+
+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,71 @@
+# OptOut
+
+OptOut is a rubygem for tracking unsubscriptions to newsletters.
+
+## Usage
+
+```ruby
+OptOut.unsubscribe('newsletters', '5')  # unsubscribe user id '5' from 'newsletters'
+OptOut.subscribed?('newsletters', '5')
+=> false
+
+OptOut.subscribe('newsletters', '5')  # re-subscribe a user to 'newsletters'
+OptOut.subscribed?('newsletters', '5')
+=> true
+
+OptOut.unsubscribed?('newsletters', '5')  # another way to query
+=> false
+
+OptOut.subscribed('newsletters', '8')  # users are subscribed by default unless explicitly unsubscribed
+=> true
+
+['1', '2', '3'].each {|user_id| OptOut.unsubscribe('newsletters', user_id)}
+OptOut.unsubscribers  # returns a list of unsubscribed user ids
+=> ['1', '2', '3']
+```
+
+## Configuration
+
+The persistence backend can be configured to be one of:
+
+* [MemoryAdapter](lib/opt_out/adapters/memory_adapter.rb)
+* [RedisAdapter](lib/opt_out/adapters/redis_adapter.rb)
+* [ActiveRecordAdapter](lib/opt_out/adapters/active_record_adapter.rb)
+
+For example, to configure OptOut to store unsubscriptions in Redis:
+
+```ruby
+OptOut.configure do |c|
+  c.adapter = OptOut::Adapters::RedisAdapter
+  c.options = {
+    :url => 'redis://localhost:6379'
+  }
+end
+```
+
+See individual adapter classes for setup and configuration options. To write a
+custom adapter, take a look at [AbstractAdapter](lib/opt_out/adapters/abstract_adapter.rb)
+
+
+## Development
+
+To run tests, you will need a running redis instance. Add a `.env` file to the
+project root to configure where redis lives:
+
+```
+REDIS_URL=redis://localhost:6379
+```
+
+To run tests:
+
+```sh
+$ rake
+```
+
+## Contributing
+
+1. [Fork it](https://help.github.com/articles/fork-a-repo)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new [Pull Request](https://help.github.com/articles/using-pull-requests)

data/Rakefile

@@ -0,0 +1,11 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+task :default => :test

data/lib/opt_out.rb

@@ -0,0 +1,58 @@
+# Track user unsubscriptions by list.
+#
+# OptOut.unsubscribe('newsletters', '5')  # unsubscribe user id '5' from 'newsletters'
+# OptOut.subscribed?('newsletters', '5')
+# => false
+#
+# OptOut.subscribe('newsletters', '5')  # re-subscribe a user to 'newsletters'
+# OptOut.subscribed?('newsletters', '5')
+# => true
+#
+# OptOut.unsubscribed?('newsletters', '5')  # another way to query
+# => false
+#
+# OptOut.subscribed('newsletters', '8')  # users are subscribed by default unless explicitly unsubscribed
+# => true
+#
+# ['1', '2', '3'].each {|user_id| OptOut.unsubscribe('newsletters', user_id)}
+# OptOut.unsubscribers  # returns a list of unsubscribed user ids
+# => ['1', '2', '3']
+require 'forwardable'
+require 'opt_out/adapters'
+
+module OptOut
+  # Options:
+  #   :adapter - subclass of OptOut::Adapters::AbstractAdapter
+  #   :options - instantiation options to pass to `adapter`
+  class Configuration < Struct.new(:adapter, :options)
+  end
+
+  class << self
+    extend Forwardable
+    delegate [:subscribe, :subscribed?, :unsubscribe, :unsubscribed?, :unsubscribers, :reset] => :adapter
+
+    # Private: returns a memoized instance of adapter to use
+    def adapter
+      @adapter ||= config.adapter.new(config.options)
+    end
+
+    # Public: Configure OptOut. Returns Configuration.
+    #
+    # Example:
+    #
+    #    OptOut.configure do |c|
+    #      c.adapter = OptOut::Adapters::RedisAdapter
+    #      c.options = {:host => 'localhost', :port => '6379', :password => ''}
+    #    end
+    def configure(&blk)
+      blk.call(config)
+      @adapter = nil  # invalidate adapter on reconfiguration
+      config
+    end
+
+    # Public: Returns Configuration
+    def config
+      @config ||= Configuration.new
+    end
+  end
+end

data/lib/opt_out/adapters.rb

@@ -0,0 +1,8 @@
+module OptOut
+  module Adapters
+    autoload :AbstractAdapter,     'opt_out/adapters/abstract_adapter'
+    autoload :MemoryAdapter,       'opt_out/adapters/memory_adapter'
+    autoload :RedisAdapter,        'opt_out/adapters/redis_adapter'
+    autoload :ActiveRecordAdapter, 'opt_out/adapters/active_record_adapter'
+  end
+end

data/lib/opt_out/adapters/abstract_adapter.rb

@@ -0,0 +1,52 @@
+module OptOut
+  module Adapters
+    # An adapter is responsible for tracking (un/re)subscriptions, and
+    # unsubscribers.
+    class AbstractAdapter
+      def initialize(options = nil)
+        @options = options || {}
+      end
+
+      # Public: `user_id` is subscribed? to `list_id` iff it's unsubscribed.
+      #
+      # Returns boolean.
+      def subscribed?(list_id, user_id)
+        !unsubscribed?(list_id, user_id)
+      end
+
+      # Public: Resubscribe `user_id` to `list_id`. Note that adapters should
+      # only keep track of unsubscriptions. Even if subscribe has never been
+      # called before, a user is unsubscribed only if `#unsubscribe` is
+      # called.
+      #
+      # Returns nothing.
+      def subscribe(list_id, user_id)
+        raise NotImplementedError.new
+      end
+
+      # Public: unsubscribe `user_id` from `list_id`
+      #
+      # Returns nothing.
+      def unsubscribe(list_id, user_id)
+        raise NotImplementedError.new
+      end
+
+      # Public: is `user_id` unsubscribed from `list_id`?
+      #
+      # Returns boolean.
+      def unsubscribed?(list_id, user_id)
+        raise NotImplementedError.new
+      end
+
+      # Public: returns an array of unsubscribers for `list_id`
+      def unsubscribers(list_id)
+        raise NotImplementedError.new
+      end
+
+      # Private: reset internal data store for testing
+      def reset
+        raise NotImplementedError.new
+      end
+    end
+  end
+end

data/lib/opt_out/adapters/active_record_adapter.rb

@@ -0,0 +1,56 @@
+require 'active_record'
+
+module OptOut
+  module Adapters
+    # Adapter that stores persists data through ActiveRecord.
+    # It requires the following table:
+    #
+    #    :list_id string
+    #    :user_id string
+    #    composite index on (list_id, user_id)
+    #
+    # Options
+    #   :table_name - name of storage table. Defaults to 'opt_outs'
+    class ActiveRecordAdapter < AbstractAdapter
+
+      def subscribe(list_id, user_id)
+        return if [list_id, user_id].any? {|s| s.nil? || s == ''}
+        store.where(:list_id => list_id.to_s, :user_id => user_id.to_s).delete_all
+        nil
+      end
+
+      # TODO: would prefer opt_outs table to not have a primary key `id`, but
+      # that's not working right now
+      def unsubscribe(list_id, user_id)
+        store.create(:list_id => list_id.to_s, :user_id => user_id.to_s)
+      rescue ActiveRecord::RecordNotUnique
+        # already unsubscribed
+      ensure
+        return nil
+      end
+
+      def unsubscribed?(list_id, user_id)
+        store.exists?(:list_id => list_id.to_s, :user_id => user_id.to_s)
+      end
+
+      def unsubscribers(list_id)
+        store.where(:list_id => list_id.to_s).map(&:user_id).to_a
+      end
+
+      def reset
+        store.delete_all
+      end
+
+      private
+
+      def store
+        return @store if @store
+
+        table_name = @options[:table_name]
+        @store = Class.new(ActiveRecord::Base) do
+          self.table_name = table_name
+        end
+      end
+    end
+  end
+end

data/lib/opt_out/adapters/memory_adapter.rb

@@ -0,0 +1,40 @@
+require 'set'
+
+module OptOut
+  module Adapters
+    # Adapter that stores persists data in memory in a hash.
+    #
+    # Options
+    #   :store - optional Hash instance to store unsubscriptions
+    class MemoryAdapter < AbstractAdapter
+      # Subscribe `user_id` to `list_id`. Returns nothing.
+      def subscribe(list_id, user_id)
+        store[list_id].delete(user_id) and return
+      end
+
+      def unsubscribe(list_id, user_id)
+        store[list_id] ||= Set.new
+        store[list_id] << user_id
+        nil
+      end
+
+      def unsubscribed?(list_id, user_id)
+        (store[list_id] || []).include?(user_id)
+      end
+
+      def unsubscribers(list_id)
+        store[list_id].to_a
+      end
+
+      def reset
+        store.clear
+      end
+
+      private
+
+      def store
+        @store ||= @options[:store] || Hash.new
+      end
+    end
+  end
+end

data/lib/opt_out/adapters/redis_adapter.rb

@@ -0,0 +1,64 @@
+require 'redis'
+require 'uri'
+
+module OptOut
+  module Adapters
+    # Adapter that persists data in a Redis set.
+    #
+    # Options
+    #   :redis - redis connection object OR
+    #   :url   - redis connection url OR
+    #   :host
+    #   :port
+    #   :password
+    #   :key_format - format string for redis key. list_id is interpolated into this option.
+    #                 Default is "opt_out:%s"
+    class RedisAdapter < AbstractAdapter
+      def subscribe(list_id, user_id)
+        redis.srem(key(list_id), user_id) and return
+      end
+
+      def unsubscribe(list_id, user_id)
+        redis.sadd(key(list_id), user_id) and return
+      end
+
+      def unsubscribed?(list_id, user_id)
+        redis.sismember(key(list_id), user_id)
+      end
+
+      def unsubscribers(list_id)
+        redis.smembers(key(list_id))
+      end
+
+      def reset
+        redis.flushdb
+      end
+
+      def key_format
+        @key_format || @options[:key_format] || "opt_out:%s"
+      end
+      attr_writer :key_format
+
+      # Private: returns redis client for this adapter
+      def redis
+        return @redis if @redis
+
+        @redis = if @options[:redis]
+          @options[:redis]
+        elsif @options[:url]
+          uri = URI.parse(@options[:url])
+          Redis.new(:host => uri.host, :port => uri.port, :password => uri.password)
+        else
+          Redis.new(:host => @options[:host], :port => @options[:port], :password => @options[:password])
+        end
+      end
+
+      private
+
+      # Returns key to use for redis set add from `:key_format` option
+      def key(list_id)
+        key_format % list_id
+      end
+    end
+  end
+end

data/lib/opt_out/version.rb

@@ -0,0 +1,3 @@
+module OptOut
+  VERSION = '1.0.0'
+end

data/opt_out.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path("../lib/opt_out/version", __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name          = "opt_out"
+  gem.version       = OptOut::VERSION
+  gem.license       = "MIT"
+  gem.authors       = ["Jerry Cheung"]
+  gem.email         = ["jch@whatcodecraves.com"]
+  gem.description   = %q{Track newsletter unsubscriptions}
+  gem.summary       = %q{Utilities for managing user unsubscribes from lists}
+  gem.homepage      = "https://github.com/jch/opt_out"
+
+  gem.files         = `git ls-files`.split $/
+  gem.test_files    = gem.files.grep(%r{^test})
+  gem.require_paths = ["lib"]
+
+  gem.add_development_dependency "redis"
+  gem.add_development_dependency "activerecord"
+  gem.add_development_dependency "sqlite3"
+end

data/test/active_record_adapter_test.rb

@@ -0,0 +1,20 @@
+require 'adapter_tests'
+require 'sqlite3'
+
+class OptOut::ActiveRecordAdapterTest < Test::Unit::TestCase
+  include AdapterTests
+  test_adapter OptOut::Adapters::ActiveRecordAdapter, :table_name => 'opt_outs' do
+    ActiveRecord::Base.establish_connection({
+      :adapter => 'sqlite3',
+      :database => './test.db'
+    })
+    conn = ActiveRecord::Base.connection
+
+    unless conn.table_exists?(:opt_outs)
+      conn.create_table(:opt_outs) do |t|
+        t.string "list_id"
+        t.string "user_id"
+      end
+    end
+  end
+end

data/test/adapter_tests.rb

@@ -0,0 +1,79 @@
+require 'opt_out'
+require 'test/unit'
+require 'dotenv'
+
+Dotenv.load
+
+# All adapters must pass these tests. To setup a new adapter test:
+#
+# class MyAdapterTest < Test::Unit::TestCase
+#   include AdapterTests
+#   test_adapter(MyAdapter, {:some => 'options'}) do
+#     # optional test setup block
+#   end
+# end
+module AdapterTests
+  def self.included(base)
+    base.extend Macros
+  end
+
+  module Macros
+    attr_accessor :original_config, :test_config
+
+    def test_adapter(adapter, options = {}, &blk)
+      self.original_config = OptOut.config.dup
+      self.test_config = {
+        :adapter => adapter,
+        :options => options,
+        :setup   => blk
+      }
+    end
+  end
+
+  def setup
+    if custom_setup = self.class.test_config[:setup]
+      custom_setup.call
+    end
+    OptOut.configure do |c|
+      c.adapter = self.class.test_config[:adapter]
+      c.options = self.class.test_config[:options]
+    end
+    OptOut.reset
+  end
+
+  def teardown
+    OptOut.config.adapter = self.class.original_config[:adapter]
+    OptOut.config.options = self.class.original_config[:options]
+    OptOut.reset
+  end
+
+  def test_auto_subscribed
+    assert OptOut.subscribed?('newsletters', '5')
+  end
+
+  def test_resubscribe
+    OptOut.unsubscribe('newsletters', '5')
+    OptOut.subscribe('newsletters', '5')
+    assert OptOut.subscribed?('newsletters', '5')
+    assert !OptOut.unsubscribed?('newsletters', '5')
+  end
+
+  def test_unsubscribe
+    OptOut.unsubscribe('newsletters', '5')
+    assert !OptOut.subscribed?('newsletters', '5')
+    assert OptOut.unsubscribed?('newsletters', '5')
+  end
+
+  def test_multi_unsubscribe
+    OptOut.unsubscribe('newsletters', '5')
+    OptOut.unsubscribe('newsletters', '5')
+    assert !OptOut.subscribed?('newsletters', '5')
+    assert OptOut.unsubscribed?('newsletters', '5')
+  end
+
+  def test_unsubscribers
+    OptOut.unsubscribe('newsletters', '5')
+    OptOut.unsubscribe('newsletters', '6')
+    assert_equal ['5', '6'], OptOut.unsubscribers('newsletters').sort
+  end
+end

data/test/memory_adapter_test.rb

@@ -0,0 +1,6 @@
+require 'adapter_tests'
+
+class OptOut::MemoryAdapterTest < Test::Unit::TestCase
+  include AdapterTests
+  test_adapter OptOut::Adapters::MemoryAdapter, :store => {}
+end

data/test/redis_adapter_test.rb

@@ -0,0 +1,17 @@
+require 'adapter_tests'
+
+class OptOut::RedisAdapterTest < Test::Unit::TestCase
+  include AdapterTests
+  test_adapter OptOut::Adapters::RedisAdapter, :url => ENV['REDIS_URL']
+
+  def test_default_key_format
+    OptOut.unsubscribe('releases', '9')
+    assert_equal ['9'], OptOut.adapter.redis.smembers("opt_out:releases")
+  end
+
+  def test_custom_key_format
+    OptOut.adapter.key_format = "notifications:%s:subscribe"
+    OptOut.unsubscribe('releases', '9')
+    assert_equal ['9'], OptOut.adapter.redis.smembers("notifications:releases:subscribe")
+  end
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: opt_out
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Jerry Cheung
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Track newsletter unsubscriptions
+email:
+- jch@whatcodecraves.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/opt_out.rb
+- lib/opt_out/adapters.rb
+- lib/opt_out/adapters/abstract_adapter.rb
+- lib/opt_out/adapters/active_record_adapter.rb
+- lib/opt_out/adapters/memory_adapter.rb
+- lib/opt_out/adapters/redis_adapter.rb
+- lib/opt_out/version.rb
+- opt_out.gemspec
+- test/active_record_adapter_test.rb
+- test/adapter_tests.rb
+- test/memory_adapter_test.rb
+- test/redis_adapter_test.rb
+homepage: https://github.com/jch/opt_out
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Utilities for managing user unsubscribes from lists
+test_files:
+- test/active_record_adapter_test.rb
+- test/adapter_tests.rb
+- test/memory_adapter_test.rb
+- test/redis_adapter_test.rb