diversion 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e1d9abf9fb297a4097cb0d52b23e802b1df837a2
+  data.tar.gz: 6aaa3057c3e72b0a835a84828375c8a057d9976c
+SHA512:
+  metadata.gz: ad2b860ce09fe117ec736c249fdce3809fec2d3d42ae98c28090a684e84dbda60f3d16f3124292626d7534cde33f116a5fdbc95c721fe0b0fbf8c888d6ad7589
+  data.tar.gz: 5c68a4ce1c9488aab7c2a6a1c1677a9ceabc84287e6764f3c0333a36ff3785b24e5e84a71b0f238819da4bbc8acf8ea6b1ab07175d0b599d0181ac0b56a0a2da

data.tar.gz.sig

@@ -0,0 +1,2 @@
+*�E��u��B���3|�e�!ģ�������'���}�so_gr:'ڻjG�)������AݕRz�ff�]׵��"-�:�ed��x��������N���G�h�?�k��曼�b8�z� ��Z`�O��GTs��
+��hژ��&����4��˜�G�F{ȯ���e�f@�g^YH���N:i�a1��n��T���\U�B�պB������!Լ�Rřyt7D�R�%���Lih6w�R�=j��Xw�)1᳠�W

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Richard Hollis
+
+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,193 @@
+# Diversion Ruby Gem
+
+[![Gem Version](https://badge.fury.io/rb/diversion.png)][gem]
+[![Build Status](https://secure.travis-ci.org/richhollis/diversion.png?branch=master)][travis]
+[![Dependency Status](https://gemnasium.com/richhollis/diversion.png?travis)][gemnasium]
+[![Coverage Status](https://coveralls.io/repos/richhollis/diversion/badge.png?branch=master)][coveralls]
+
+[gem]: https://rubygems.org/gems/diversion
+[travis]: http://travis-ci.org/richhollis/diversion
+[gemnasium]: https://gemnasium.com/richhollis/diversion
+[coveralls]: https://coveralls.io/r/richhollis/diversion
+
+Redirect HTML links through your preferred redirection URL
+
+Diversion aims are simple - to be a framework agnostic way to redirect all URLs via another path whilst leaving the original URL intact, leaving you to perform the actual implementation of the redirection logic. 
+
+Link redirection is particularly desirable for some Rails mailers where you want to track a link click first before redirecting the user to the original link.
+
+Diversion was created specifically with a Rails use case in mind but can be used without Rails/ActionMailer. 
+
+A Rails mailer helper is provided if you are using ActionMailer. 
+
+## Installation
+
+    gem install diversion
+
+To ensure the code you're installing hasn't been tampered with, it's recommended that you verify the signature. To do this, you need to add my public key as a trusted certificate (you only need to do this once):
+
+    gem cert --add <(curl -Ls https://gist.github.com/richhollis/5301656/raw/richhollis.pem)
+
+Then, install the gem with the high security trust policy:
+
+    gem install twitter -P HighSecurity    
+
+Add this line to your application's Gemfile:
+
+    gem 'diversion'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install diversion
+
+## Quick Start Guide & Example
+
+Configure your redirection settings:
+
+```ruby
+Diversion.configure do |config|
+  config.host = 'http://localhost.domain'
+  config.path = '/redirect/'
+end
+```
+
+Example usage:
+
+Encode takes an HTML body and encodes all anchor links to the new redirection location. 
+
+You can specifiy additional parameters for each url by using a "data-" attribute, for example:
+
+```html
+<a data-from="welcome_email" href="http://www.youtube.com/watch?v=feeA-Dr0XGw">Portlandia Intro</a>
+```
+
+The data-from attribute will be added to the encoded parameters and will be available when the URL is decoded.
+
+```ruby
+Diversion::encode('<a data-from="welcome_email" href="http://www.youtube.com/watch?v=feeA-Dr0XGw">Portlandia Intro</a>') 
+# => "<a href=\"http://localhost.domain/redirect/1/?d=from%3Dwelcome_email%26url%3Dhttp%253A%252F%252Fwww.youtube.com%252Fwatch%253Fv%253DfeeA-Dr0XGw\">Portlandia Intro</a>"
+```
+
+Then to get the original data (this might be in say your Redirect controller) we parse the parameters of the URL:
+
+```ruby
+Diversion::decode('d=from%3Dwelcome_email%26url%3Dhttp%253A%252F%252Fwww.youtube.com%252Fwatch%253Fv%253DfeeA-Dr0XGw')
+# => {:key_presented=>"", :parsed=>true, :signed=>false, :key_expected=>"", :key_verified=>false, :from=>"welcome_email", :url=>"http://www.youtube.com/watch?v=feeA-Dr0XGw"} 
+```
+
+## Global data parameters
+
+You can specify parameters that should be present for all encoded URLs. This might typically be an ID or something similar. 
+Specify these parameters in the second parameter to the encode (or diversion mailer) method with a hash of the parameters you wish to add. 
+
+Example:
+
+```ruby
+Diversion::encode('<a data-from="welcome_email" href="http://www.youtube.com/watch?v=feeA-Dr0XGw">Portlandia Intro</a>', {:id => 1} )
+# =>  => "<a href=\"http://localhost.domain/redirect/1/?d=from%3Dwelcome_email%26id%3D1%26url%3Dhttp%253A%252F%252Fwww.youtube.com%252Fwatch%253Fv%253DfeeA-Dr0XGw\">Portlandia Intro</a>"
+```
+
+## Overriding configuration parameters
+
+You can the global configuration by specifying a third parameter to encode (or diversion mailer) with a hash of the parameters you wish to override.
+
+Example:
+
+```ruby
+Diversion::encode('<a data-from="welcome_email" href="http://www.youtube.com/watch?v=feeA-Dr0XGw">Portlandia Intro</a>', {:id => 1}, {:encode_uris => ['https']} )
+# => "<a data-from=\"welcome_email\" href=\"http://www.youtube.com/watch?v=feeA-Dr0XGw\">Portlandia Intro</a>" 
+```
+
+Note: Because we've overridden the encode_uris setting to only encode https urls our URL hasn't been redirected.
+
+## Enabling Url 'Signing'
+
+You can 'sign' the url which works by appending a parameter with a hash of the URL. The hash can be as long as 32 characters. When you enable signing, but setting the sign_length configuration option you can choose between 0-32, where 0 is disabled. The hash is generated using HMAC::MD5.
+
+```ruby
+Diversion.configure do |config|
+  config.sign_length = 2
+  config.sign_key = 'yoursecretkey'
+end
+```
+
+## Changing the Encoding Method
+
+The default encoding method is query string parameters (Encode::Params/Decode::Params). This can be changed for JSON if you wish (Encode::Json/Decode::Json).
+
+```ruby
+Diversion.configure do |config|
+  config.url_encoding = Encode::Json
+  config.url_decoding = Decode::Json
+end
+```
+
+## Rails Mailer Example
+
+app/views/test_mailer/welcome_email.html.erb:
+
+```html
+<p>Hey</p>
+
+<p>Click on the following link to view some great content:</p>
+
+<a data-type="video" href="http://www.youtube.com/watch?v=feeA-Dr0XGw">Portlandia</a>
+```
+
+app/mailers/test_mailer.rb:
+
+```ruby
+class TestMailer < ActionMailer::Base
+  default from: "from@example.com"
+
+  def welcome_email
+    # Note: we're adding a global parameter user_id - this is optional
+    mail(:to => 'somebody@no.where', :subject => "Welcome to My Awesome Site").diversion({:user_id => 1})
+  end
+end
+```
+
+Note: Remember you can also add global parameters and override config options buy passing these to the diversion helper too - e.g.
+
+```ruby
+mail(:to => 'somebody@no.where', :subject => "Welcome to My Awesome Site").diversion({:user_id => 1}, {:encode_uris => ['http']} )
+```
+
+app/controllers/redirect_controller.rb:
+
+```ruby
+class RedirectController < ApplicationController
+
+  respond_to :html
+
+  def show
+    hash = Diversion::decode(request.query_string)
+
+    # do something with parameters hash like save request in database
+
+    # output parameters
+    render :text => hash
+
+    # or redirect
+    # redirect_to(hash[:url])
+  end
+
+end
+```
+
+Sample Redirect Controller output:
+
+{:key_presented=>"", :parsed=>true, :signed=>false, :key_expected=>"", :key_verified=>false, :from=>"welcome_email", :url=>"http://www.youtube.com/watch?v=feeA-Dr0XGw", :user_id => 1}
+
+## 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. Provide tests for the changes
+6. Create new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :test => :spec
+task :default => :spec

data/diversion.gemspec

@@ -0,0 +1,40 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'diversion/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "diversion"
+  gem.version       = Diversion::Version
+  gem.authors       = ["Richard Hollis"]
+  gem.email         = ["richhollis@gmail.com"]
+  gem.description   = %q{Redirect HTML links through your preferred redirection URL}
+  gem.summary       = gem.description
+  gem.homepage      = "https://github.com/richhollis/diversion/"
+
+  gem.cert_chain  = ['certs/richhollis.pem']
+  gem.signing_key = File.expand_path("~/.gem/private_key.pem") if $0 =~ /gem\z/
+
+  gem.files = %w(LICENSE.txt README.md Rakefile diversion.gemspec)
+  gem.files += Dir.glob("lib/**/*.rb")
+  gem.files += Dir.glob("spec/**/*")
+
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+  gem.test_files     = Dir.glob('spec/**/*')
+
+  gem.licenses = ['MIT']
+
+  gem.add_dependency "activesupport", ['>= 3.0', '< 4.1']
+  gem.add_dependency "nokogiri"
+  gem.add_dependency "ruby-hmac"
+  gem.add_dependency 'multi_json', '~> 1.0'
+
+  gem.add_development_dependency "actionmailer", ['>= 3.0', '< 4.1']
+  gem.add_development_dependency "rspec"
+  gem.add_development_dependency "simplecov" if RUBY_VERSION >= '1.9'
+  gem.add_development_dependency "coveralls"
+  
+end
+

data/lib/diversion.rb

@@ -0,0 +1,35 @@
+if defined?(ActionMailer)
+  require 'action_mailer/version'
+  require 'diversion/mailer'
+end
+
+require "diversion/error"
+require "diversion/client"
+require "diversion/version"
+
+module Diversion
+
+  class << self
+    include Diversion::Configurable
+
+    # Delegate to a Diversion::Client
+    #
+    # @return [Diversion::Client]
+    def client
+      @client = Diversion::Client.new(options) unless defined?(@client) && @client.hash == options.hash
+      @client
+    end
+
+    def respond_to_missing?(method_name, include_private=false); client.respond_to?(method_name, include_private); end if RUBY_VERSION >= "1.9"
+    def respond_to?(method_name, include_private=false); client.respond_to?(method_name, include_private) || super; end if RUBY_VERSION < "1.9"
+
+    private
+
+    def method_missing(method_name, *args, &block)
+      return super unless client.respond_to?(method_name)
+      client.send(method_name, *args, &block)
+    end
+  end
+end
+
+Diversion.setup

data/lib/diversion/client.rb

@@ -0,0 +1,21 @@
+require 'diversion/configurable'
+require 'diversion/encode'
+require 'diversion/decode'
+
+module Diversion
+
+  class Client
+
+    include Configurable
+    include Encode
+    include Decode
+
+    def initialize(options={})
+      Diversion::Configurable.keys.each do |key|
+        instance_variable_set(:"@#{key}", options[key] || Diversion.instance_variable_get(:"@#{key}"))
+      end
+    end
+
+  end
+
+end

data/lib/diversion/configurable.rb

@@ -0,0 +1,100 @@
+require 'forwardable'
+require 'diversion/error/configuration_error'
+
+module Diversion
+  module Configurable
+    extend Forwardable
+    attr_accessor :host, :port, :path, :sign_key, :sign_length, :encode_uris
+    attr_accessor :url_encoding, :url_decoding
+    def_delegator :options, :hash
+
+    class << self
+
+      def keys
+        @keys ||= [
+          :host,
+          :port,
+          :path,
+          :sign_key,
+          :sign_length,
+          :encode_uris,
+          :url_encoding,
+          :url_decoding
+        ]
+      end
+
+    end
+
+    def configure
+      yield self
+      validate_configuration!
+      self
+    end
+
+    def reset!
+      @host = 'http://localhost.domain'
+      @port = 80
+      @path = '/redirect/1/'
+      @sign_length = 0
+      @sign_key = nil
+      @encode_uris = ['http','https']
+      @url_encoding = Encode::Params
+      @url_decoding = Decode::Params
+      validate_configuration!
+      self
+    end
+    alias setup reset!
+
+    private
+
+    # @return [Hash]
+    def options
+      Hash[Diversion::Configurable.keys.map{|key| [key, instance_variable_get(:"@#{key}")]}]
+    end
+
+    # Ensures that all configuration parameters are of an expected type. 
+    #
+    # @raise [Diversion::Error::ConfigurationError] Error is raised when
+    #   supplied configuration is not of expected type
+    def validate_configuration!
+      unless @host.is_a?(String) && @host.length > 0
+        raise(Error::ConfigurationError, "Invalid host specified: Host must contain the host to redirect to.")
+      end
+      if @host.end_with?('/')
+        raise(Error::ConfigurationError, "Invalid host specified: #{@host} should not end with a trailing slash.")
+      end
+
+      unless @path.is_a?(String) && @path.length > 0
+        raise(Error::ConfigurationError, "Invalid path specified: Path must contain a path to redirect to.")
+      end
+      unless @path.end_with?('/')
+        raise(Error::ConfigurationError, "Invalid path specified: #{@path} should end with a trailing slash.")
+      end
+
+      unless @port.is_a?(Integer) && @port > 0
+        raise(Error::ConfigurationError, "Invalid port specified: #{@port} must be an integer and non-zero.")
+      end
+
+      if !@sign_key.nil? && !@sign_key.is_a?(String)
+        raise(Error::ConfigurationError, "Invalid sign_key specified: #{@sign_key} must be a String.")
+      end
+
+      unless @sign_length.is_a?(Integer) && @sign_length.between?(0, Signing::MAX_SIGN_LENGTH)
+        raise(Error::ConfigurationError, "Invalid sign_length specified: #{@sign_length} must be an integer between 0-#{Signing::MAX_SIGN_LENGTH}.")
+      end
+
+      unless @encode_uris.is_a?(Array) && @encode_uris.count > 0
+        raise(Error::ConfigurationError, "Invalid encode_uris specified: #{@encode_uris} must be an array with at least one URI scheme.")
+      end
+
+      unless @url_encoding.is_a?(Module) && Encode::ENCODERS.include?(@url_encoding)
+        raise(Error::ConfigurationError, "Invalid url_encoding specified: #{@url_encoding} must be a valid encoder module.")
+      end
+
+      unless @url_decoding.is_a?(Module) && Decode::DECODERS.include?(@url_decoding)
+        raise(Error::ConfigurationError, "Invalid url_decoding specified: #{@url_decoding} must be a valid decoder module.")
+      end
+    end
+
+  end
+end

data/lib/diversion/decode.rb

@@ -0,0 +1,21 @@
+require 'diversion/decode/json'
+require 'diversion/decode/params'
+
+module Diversion
+  module Decode
+    include Base64
+    include Signing
+
+    DECODERS = [ Params, Json ]
+
+    def decode(data, opts = {})
+      raise ArgumentError if data.length == 0
+
+      opts = options.merge(opts)
+
+      # get hash for required type
+      hash = opts[:url_decoding].get_hash(data, opts)
+    end
+
+  end
+end