refcode 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e758644ad3263ebb08c54c505b606c310ba5a88a
-  data.tar.gz: 5eef6a2ba89fa9dc55922ee1ea6fe54488155c72
+  metadata.gz: 420403fbddbdbbfe612045ab19119651a54f8740
+  data.tar.gz: 41307cc055dfbea7997fc7e66f20dffbcf94ff9a
 SHA512:
-  metadata.gz: aa418e724d2bc68c26e7fb06ce6758d8ab2aa04d96aa5b3aaadaf5981750ab8e428706016d15d0c543ddd0f88b38807f8f91ab2fcd209839ee60263c853b36c5
-  data.tar.gz: d098a3bd746a7f4afe3fb4db4240c7ec645b795f8e99e7296d91bd8677bd013203536cb79437a35e6a843947882727caa35c4be16f8b44a469e7c49197915d00
+  metadata.gz: b3fd63ca01f994071ac81ab8545f1880433a661806d73aa81797aeb83fa4763ea7f636777926f823b2df1115df90a3ab463c0c6a74424cceef958274d2095284
+  data.tar.gz: 172f2f19bc9a3d6f02c75adc665bda99f4a12f5c6edbf825e4c4845cfd42de3fc88e9da06f215fbcfa862b54daa58a640bddf6eb4d50b291988e4a11dc2c270f

data/README.md

@@ -5,7 +5,9 @@ URL-safe strings. The strings can be simply decrypted later to be used by your
 application.
 
 Refcode was conceived as a way to attach referral data to tracking links. Encryption
-makes it unlikely that the links can be tampered with.
+makes it unlikely that the links will be tampered with. Still, it is not recommended
+for critically sensitive applications! It was designed to power a simple referral
+link tracking system.
 
 ## Implementation
 
@@ -31,6 +33,8 @@ Or install it yourself as:
 
 ## Usage
 
+Refcode can be used in two ways. Most simply, you can use the `Refcode::Encoder` class directly.
+
     encoder = Refcode::Encoder.new do |e|
       e.secret = "a long crunchy secret"
       e.salt = "some salt"
@@ -39,11 +43,32 @@ Or install it yourself as:
     something = OpenStruct.new(channel: 'facebook', action: 'message', user_id: 43765)
     encoded_param = encoder.encode something
 
-    # in some future request...
+    # in some future request:
 
     something = encoder.decode params[:encoded_param]
     puts something.channel # 'facebook'
 
+For added convenience when using Refcode with an ORM such as ActiveRecord, a module called `Refcode::Encodable` is also provided.
+
+    class Job < ActiveRecord::Base
+      include Refcode::Encodable
+      has_refcode secret: 'a long crunchy secret', salt: :id
+    end
+
+    # the salt option of the has_refcode method can accept a proc/lambda, string
+    # or a symbol representing an existing method on the class (id in this case)
+
+    # in some controller code:
+
+    @job = Job.find params[:id]
+    referral_code = @job.generate_refcode channel: 'facebook', action: 'message', user_id: 43765
+
+    # and in another action:
+
+    @job = Job.find params[:id]
+    referral_data = @job.parse_refcode params[:encoded_param]
+
+
 ## Contributing
 
 1. Fork it

data/lib/refcode.rb

@@ -3,39 +3,5 @@ require 'yaml'
 require 'base64url'
 require 'encryptor'
 require 'refcode/version'
-
-module Refcode
-
-  class Encoder
-
-    attr_accessor :secret, :salt
-
-    def initialize
-      yield self if block_given?
-    end
-
-    def encode val
-      Base64URL.encode(encrypt(YAML.dump(val)))
-    end
-
-    def decode val
-      YAML.load(decrypt(Base64URL.decode(val)))
-    end
-
-    def encrypt val
-      Encryptor.encrypt(:value => val, :key => @secret, :salt => @salt, :iv => iv)
-    end
-
-    def decrypt val
-      Encryptor.decrypt(:value => val, :key => @secret, :salt => @salt, :iv => iv)
-    end
-
-    private
-
-    def iv
-      [@secret, @salt].join
-    end
-
-  end
-
-end
+require 'refcode/encoder'
+require 'refcode/encodable'

data/lib/refcode/encodable.rb

@@ -0,0 +1,47 @@
+module Refcode
+
+  module Encodable
+
+    def self.included base
+      base.extend ClassMethods
+    end
+
+    def generate_refcode val
+      raise 'You must call the has_refcode method in your class definition' unless self.class.refcode_options
+      encoder.encode val
+    end
+
+    def parse_refcode code
+      encoder.decode code
+    end
+
+    module ClassMethods
+      def has_refcode options
+        raise ArgumentError unless options[:secret] && options[:salt]
+        @refcode_options = options
+      end
+      def refcode_options
+        @refcode_options
+      end
+    end
+
+    private
+
+    def encoder
+      Refcode::Encoder.new do |r|
+        r.secret = self.class.refcode_options[:secret]
+        salt_option = self.class.refcode_options[:salt]
+        if salt_option.respond_to? :call
+          r.salt = salt_option.call
+        elsif salt_option.is_a? Symbol
+          r.salt = self.send salt_option
+        else
+          r.salt = salt_option
+        end
+        raise "Value for salt is nil (#{salt_option} given)" if r.salt.nil?
+      end
+    end
+
+  end
+
+end

data/lib/refcode/encoder.rb

@@ -0,0 +1,31 @@
+module Refcode
+
+  class Encoder
+
+    attr_accessor :secret, :salt
+
+    def initialize
+      yield self if block_given?
+    end
+    def encode val
+      Base64URL.encode(encrypt(YAML.dump(val)))
+    end
+    def decode val
+      YAML.load(decrypt(Base64URL.decode(val)))
+    end
+
+    private
+
+    def encrypt val
+      Encryptor.encrypt(:value => val, :key => @secret, :salt => @salt, :iv => iv)
+    end
+    def decrypt val
+      Encryptor.decrypt(:value => val, :key => @secret, :salt => @salt, :iv => iv)
+    end
+    def iv
+      [@secret, @salt].join
+    end
+
+  end
+
+end

data/lib/refcode/version.rb

@@ -1,3 +1,3 @@
 module Refcode
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/test/refcode_test.rb

@@ -7,6 +7,13 @@ class RefcodeTest < Test::Unit::TestCase
   SECRET = "686cb0461769ebed556f56bc88c956bfdf786646ab1920f58201723c557ccbaeb57112fd53302c06475e6e19a176ba617ee284b091d375858cb259e8578c620f"
   SALT = "dcc74de5efdab0d80b5d763f8a63bef3d37c7453ee45446fbbccd26648af8ca6a112576dafbf5475f3cd7b968703cc9e0682ee45b8b622045cec287908f536e8"
 
+  class BareEncodableObject < OpenStruct
+    include Refcode::Encodable
+  end
+  class EncodableObject < BareEncodableObject
+    has_refcode :secret => SECRET, :salt => :record_id
+  end
+
   def test_encoder_against_hash
     test_hash = { :channel => 'email', :record_id => 49203, :action => 'forward' }
     assert_equal test_hash, encode_and_decode(test_hash)
@@ -26,8 +33,40 @@ class RefcodeTest < Test::Unit::TestCase
     assert_equal test_struct, encode_and_decode(test_struct)
   end
 
+  def test_should_raise_argument_error_if_generate_refcode_called_without_val
+    assert_raise ArgumentError do
+      encodable_object.generate_refcode
+    end
+  end
+
+  def test_should_raise_error_if_generate_refcode_called_before_has_refcode
+    assert_raise ArgumentError do
+      obj = BareEncodableObject.new :some => 'value'
+      obj.generate_refcode
+    end
+  end
+
+  def test_should_raise_an_error_if_salt_is_empty
+    encodable_object.record_id = nil
+    assert_raise RuntimeError do
+      referral_code_content = { :channel => 'email', :action => 'forward', :user_id => 14325 }
+      code = encodable_object.generate_refcode referral_code_content
+      assert_equal referral_code_content, encodable_object.parse_refcode(code)
+    end
+  end
+
+  def test_encodable_against_hash
+    referral_code_content = { :channel => 'email', :action => 'forward', :user_id => 14325 }
+    code = encodable_object.generate_refcode referral_code_content
+    assert_equal referral_code_content, encodable_object.parse_refcode(code)
+  end
+
   private
 
+  def encodable_object
+    @encodable_object ||= EncodableObject.new :name => 'Unimportant Value', :record_id => 381598
+  end
+
   def encoder
     @encoder ||= Refcode::Encoder.new do |e|
       e.secret = SECRET

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: refcode
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Jordan Sitkin
@@ -79,6 +79,8 @@ files:
 - README.md
 - Rakefile
 - lib/refcode.rb
+- lib/refcode/encodable.rb
+- lib/refcode/encoder.rb
 - lib/refcode/version.rb
 - refcode.gemspec
 - test/refcode_test.rb