heroic-sns 1.0.1 → 1.2

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    N2Q1NmY1MjNhNGViOTI4NDk1N2FjZmQzYWZjNTE2ZTM4MzM3OTlkNA==
-  data.tar.gz: !binary |-
-    ZmFkMjY5YzdiMDQ3ODMwZjQyNDNkNzY1ZGM3MzU3OWVmNWYzNDJkYQ==
-!binary "U0hBNTEy":
-  metadata.gz: !binary |-
-    MDZkY2QwOTkwZmRkMzc4ZmMwNTcyYTc5MDRlZjQ1ZTkxN2JmZjMwZWI4MTA4
-    MTRmYzRjMmRjM2M3YTJiOTdlOGZlN2IyMzQyMjAyYWJiZjQ4OTc2Zjg1Yjll
-    MGQ5NjM5ZmM5ZmY5YjdmYjg4Y2ZmZjFiNmUzZDc2Zjk3OWQwMDI=
-  data.tar.gz: !binary |-
-    NDBhNWZmMzY1N2M0YTM5MWY4Njk0ZWQyNTc0NGY0NDk2NTQ4N2U4NDIwODE1
-    NWMwNjhlNzYyNWUzZmE2YjZiMzBkN2Q3ZGM1NjczMDJiOGQ2MGVlNzAyZDQ5
-    MWY4N2RkZDJlOGQ4YWJlM2U0OTUzN2ZmNDNlZWIyODdjYmEwZDU=
+SHA256:
+  metadata.gz: 061bb44887daecae4a05c0a3c75debc2d59c55b7e0a733bc783cc665de9d7a3f
+  data.tar.gz: e0f2aed506a0ebae75e408376a2c102f7825a6a9123f529286be92d6535c7416
+SHA512:
+  metadata.gz: 2007d432d0585597cb35e35cb68af3c82c9d9210b31ec227d432b481228973e25aa8c17410ac9ca6ea487cec698ea56842986c42964f88e6c3cd7c5a22ad6dba
+  data.tar.gz: d6c83fd48d0f59bc5194bca39773c24eae90c34384251dcd5af8ee8656d4f9794d6e08154c40d39327b91d4713ef9370dccd8873d0d274d63ce5943af898ccec

data/.gitignore

@@ -1,4 +1,6 @@
 /capture
+/html
 /pkg
 /tmp
 /Gemfile.lock
+/gemfiles/*.lock

data/.travis.yml

@@ -1,6 +1,22 @@
 language: ruby
 rvm:
-  - ruby-head
-  - "2.0.0"
-  - "1.9.3"
-  - "1.8.7"
+  - "2.7"
+  - "2.6"
+  - "2.5"
+  - "2.4"
+  - "2.3"
+  - "2.2"
+  - "2.1"
+  - "2.0"
+gemfile:
+  - Gemfile
+  - gemfiles/Gemfile.rack-1.x
+before_install:
+  - gem update bundler
+matrix:
+  exclude:
+    - { rvm: "2.1", gemfile: Gemfile }
+    - { rvm: "2.0", gemfile: Gemfile }
+  include:
+    - { rvm: "1.8.7", dist: precise, gemfile: gemfiles/Gemfile.ruby-1.8 }
+    - { rvm: "1.9.3", dist: trusty,  gemfile: gemfiles/Gemfile.rack-1.x }

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+### 1.2
+
+* Add Ruby 2.4, 2.5, 2.6. 2.7 to the Travis CI tests
+* Relax json gem dependency - [@biinari]
+* Stricter signing URL check - [@biinari]
+* Show age when raising 'time is in the future' error - [@mamedov]
+
+### 1.1.3 (July 7, 2016)
+
+* Relax rack version requirement to allow usage with rack 2.x - [@fschwahn]
+
+### 1.1.2 (March 23, 2016)
+
+* Rewind the request body, in case the application wants to read it again - [@cobbr2]
+
+### 1.1.1 (August 9, 2013)
+
+* Ease up json gem dependency - [@speedmanly]
+* Documentation cleaned up and tests improved.
+
+### 1.1.0 (June 20, 2013)
+
+* Rework Cert logic - [@sbeckeriv]
+
+### 1.0.1 (May 17, 2013)
+
+* Gem housekeeping, based on [advice by @dblock](http://code.dblock.org/your-first-ruby-gem)
+
+### 1.0.0 (May 5, 2013)
+
+* Initial public release - [@benzado]
+
+[@benzado]: https://github.com/benzado
+[@biinari]: https://github.com/biinari
+[@cobbr2]: https://github.com/cobbr2
+[@dblock]: https://github.com/dblock
+[@fschwahn]: https://github.com/fschwahn
+[@mamedov]: https://github.com/mamedov
+[@sbeckeriv]: https://github.com/sbeckeriv
+[@speedmanly]: https://github.com/speedmanly

data/Gemfile

@@ -3,3 +3,5 @@ source "http://rubygems.org"
 gemspec
 
 gem "rake"
+gem "rack", "~> 2.0"
+gem "test-unit", "~> 3.3"

data/README.md

@@ -1,23 +1,33 @@
 # Heroic::SNS, Rack middleware for Amazon SNS endpoints
 
+[![Gem Version](https://badge.fury.io/rb/heroic-sns.svg)](http://badge.fury.io/rb/heroic-sns)
+[![Build Status](https://travis-ci.org/benzado/heroic-sns.png?branch=master)](https://travis-ci.org/benzado/heroic-sns)
+
 Heroic::SNS provides secure, lightweight Rack middleware for AWS Simple
 Notification Service (SNS) endpoints.
 
-Any SNS messages POSTed by Amazon to your web application are intercepted,
-parsed, verified, and then passed along via the `sns.message` environment key.
+Any SNS messages POSTed by Amazon to your web application are
+intercepted, parsed, verified, and then passed along via the
+`sns.message` environment key.
+(In case you need it, the original, unparsed message is also available in the
+body of the request.)
 
-If something goes wrong, the error will be passed along via the `sns.error`
-environment key. `Heroic::SNS::Endpoint` does not log any messages itself.
+If something goes wrong, the error will be passed along via the
+`sns.error` environment key. `Heroic::SNS::Endpoint` does not log any
+messages itself.
 
-**Heroic::SNS aims to be secure.** All message signatures are verified (to avoid
-forgeries) and stale messages are rejected (to avoid replay attacks).
+**Heroic::SNS aims to be secure.** All message signatures are verified
+(to avoid forgeries) and stale messages are rejected (to avoid replay
+attacks).
 
-**Heroic::SNS aims to be lightweight.** Beside Ruby standard libraries there are
-no dependencies beside [rack][]. Specifically, Heroic::SNS *does not* depend on [aws-sdk][]. They will be friendly to each other, however, if you include both
-in a project.
+**Heroic::SNS aims to be lightweight.** Beside Ruby standard libraries
+there are no dependencies besides [json][] and [rack][]. Specifically,
+Heroic::SNS *does not* depend on [aws-sdk][]. They will be friendly to
+each other, however, if you include both in a project.
 
-[aws-sdk]: https://github.com/aws/aws-sdk-ruby
+[json]: https://rubygems.org/gems/json
 [rack]: http://rack.github.io/
+[aws-sdk]: https://github.com/aws/aws-sdk-ruby
 
 ## Overview
 
@@ -29,8 +39,8 @@ in a project.
 
 ## How to use it
 
-Once you have installed the gem, simply add the following to your `config.ru`
-file:
+Once you have installed the gem, simply add the following to your
+`config.ru` file:
 
     use Heroic::SNS::Endpoint, :topics => /:aws-ses-bounces$/
 
@@ -38,52 +48,64 @@ On Rails, you could also install it in `/config/initializers/sns_endpoint.rb`:
 
     Rails.application.config.middleware.use Heroic::SNS::Endpoint, :topic => ...
 
-The Endpoint class takes an options hash as an argument, and understands these
-options:
+The Endpoint class takes an options hash as an argument, and understands
+these options:
 
-`:topic` is required, and provides a filter that defines what SNS topics are
-handled by this endpoint. **A message is considered either "on-topic" or
-"off-topic".** You can supply any of the following:
+### :topic
+
+`:topic` is required, and provides a filter that defines what SNS topics
+are handled by this endpoint. **A message is considered either
+"on-topic" or "off-topic".** You can supply any of the following:
 
 - a `String` containing a single topic ARN
+
 - an `Array` of `String` representing a list of topic ARNs
+
 - a `RegExp` which matches on-topic ARNs
-- a `Proc` which accepts an ARN as an argument and returns `true` or `false` for
-  on-topic and off-topic ARNs, respectively.
+
+- a `Proc` which accepts an ARN as an argument and returns `true` or
+  `false` for on-topic and off-topic ARNs, respectively.
 
 The key `:topics` is also supported.
 
+### :auto_confirm
+
 `:auto_confirm` affects how on-topic subscription confirmations are handled.
 
-- If `true`, they are confirmed by retrieving the URL in the `SubscribeURL`
-  field of the SNS message, and your app is not notified.
-- If `false`, they are ignored; your app is also not notified.
-- If `nil`, there is no special handling and the message is passed along to your
-  app.
-  
-The default is `true`.
+- If `true`, they are confirmed by retrieving the URL in the
+  `SubscribeURL` field of the SNS message, and your app is NOT notified.
+  This is the default.
+
+- If `false`, they are ignored; your app is NOT notified.
+
+- If `nil`, there is no special handling and the message is passed along
+  to your app.
+
+### :auto_resubscribe
 
 `:auto_resubscribe` affects how on-topic unsubscribe confirmations are handled.
 
-- If `true`, they topic is automatically re-subscribed by retrieving the URL in
-  the `SubscribeURL` field of the SNS message, and your app is not notified.
-- If `false`, they are ignored and your app is also not notified.
-- If `nil`, there is no special handling and the message is passed along to your
-  app.
+- If `false`, they are ignored and your app is NOT notified. This is the
+  default.
 
-The default is `false`.
+- If `true`, they topic is automatically re-subscribed by retrieving the
+  URL in the `SubscribeURL` field of the SNS message, and your app is
+  NOT notified.
 
-If you are a control-freak and want no special handling whatsoever, use these
-options:
+- If `nil`, there is no special handling and the message is passed along
+  to your app.
+
+If you are a control-freak and want no special handling whatsoever, use
+these options:
 
     use Heroic::SNS::Endpoint, :topics => Proc.new { true }, :auto_confirm => nil, :auto_resubscribe => nil
 
-Then the object will simply parse and verify SNS messages it finds and pass them
-along to your app, taking no action.
+Then the object will simply parse and verify SNS messages it finds and
+pass them along to your app, taking no action.
 
-Once the middleware is set up, any notifications will be made available in your
-Rack environment under the `sns.message` key. If you are using Rails, your
-controller would have a method like this:
+Once the middleware is set up, any notifications will be made available
+in your Rack environment under the `sns.message` key. If you are using
+Rails, your controller would have a method like this:
 
     skip_before_filter :verify_authenticity_token, :only => [:handle_notification]
 
@@ -98,52 +120,52 @@ controller would have a method like this:
       head :ok
     end
 
-You must skip the authenticity token verification to allow Amazon to POST to the
-controller action. Be careful not to disable it for more actions than you need.
-Be sure to disable any authentication checks for that action, too.
+You must skip the authenticity token verification to allow Amazon to
+POST to the controller action. Be careful not to disable it for more
+actions than you need. Be sure to disable any authentication checks for
+that action, too.
 
 ## Multiple endpoint URLs
 
-If you are receiving multiple notifications at multiple endpoint URLs, you
-should only include one instance of the Endpoint in your middleware stack, and
-ensure that its topic filter allows all the notifications you are interested in
-to pass through.
+If you are receiving multiple notifications at multiple endpoint URLs,
+you should only include one instance of the Endpoint in your middleware
+stack, and ensure that its topic filter allows all the notifications you
+are interested in to pass through.
 
 `Endpoint` does not interact with the URL path at all; if you want your
 subscriptions to go to different URLs, simply set them up that way.
 
 ## Off-topic notifications
 
-As a security measure, `Endpoint` requires you to set up a topic filter. Any
-notifications that do not match this filter are not passed along to your
-application.
+As a security measure, `Endpoint` requires you to set up a topic filter.
+Any notifications that do not match this filter are not passed along to
+your application.
 
-All off-topic messages are ignored with one exception: if the message is a
-regular notification (meaning your app has an active subscription) *and* the
-message can be verified as authentic (by checking its signature), `Endpoint`
-will cancel the subscription by visiting the URL in the `UnsubscribeURL` field
-of the message.
+All off-topic messages are ignored with one exception: if the message is
+a regular notification (meaning your app has an active subscription)
+*and* the message can be verified as authentic (by checking its
+signature), `Endpoint` will cancel the subscription by visiting the URL
+in the `UnsubscribeURL` field of the message.
 
-If you would rather make decision about on-topic and off-topic notifications in
-your own code, simply pass `Proc.new { true }` as the topic filter, and all
-messages will be treated as on topic. Be aware that it is dangerous to leave
-`:auto_confirm` enabled with a permissive topic filter, as this will allow
-anyone to subscribe your web app to any SNS notification.
+If you would rather make decision about on-topic and off-topic
+notifications in your own code, simply pass `Proc.new { true }` as the
+topic filter, and all messages will be treated as on topic. Be aware
+that it is dangerous to leave `:auto_confirm` enabled with a permissive
+topic filter, as this will allow anyone to subscribe your web app to any
+SNS notification.
 
 ## Contributing
 
 * Fork the project.
 * Make your feature addition or bug fix and include tests.
-* Update `CHANGELOG`.
+* Update `CHANGELOG.md`.
 * Send a pull request.
 
 ## Copyright and License
 
-Copyright 2013, Heroic Software Inc and Contributors.
+Copyright 2013, 2016, 2020, Benjamin Ragheb and Contributors.
 
 This project [is licensed under the Apache license](LICENSE).
 
 Direct correspondence to Benjamin Ragheb via email at <ben@benzado.com>
 or on Twitter [@benzado](https://twitter.com/benzado).
-
-[![Build Status](https://travis-ci.org/benzado/heroic-sns.png?branch=master)](https://travis-ci.org/benzado/heroic-sns)

data/Rakefile

@@ -1,6 +1,7 @@
 require 'rubygems'
 require 'bundler/gem_tasks'
 require 'rake/testtask'
+require 'rdoc/task'
 
 Bundler.setup(:default, :development)
 
@@ -8,6 +9,11 @@ Rake::TestTask.new do |t|
   t.libs << 'test'
 end
 
+RDoc::Task.new do |rdoc|
+  rdoc.main = "README.md"
+  rdoc.rdoc_files.include("README.md", "CHANGELOG.md", "lib")
+end
+
 task :demo do
   sh 'rackup -Ilib demo/config.ru'
 end

data/gemfiles/Gemfile.rack-1.x

@@ -0,0 +1,7 @@
+source "http://rubygems.org"
+
+gemspec :path => ".."
+
+gem "rake", "~> 10.3"
+gem "rack", "~> 1.0"
+gem "json", "~> 1.7"

data/gemfiles/Gemfile.ruby-1.8

@@ -0,0 +1,8 @@
+source "http://rubygems.org"
+
+gemspec :path => ".."
+
+gem "rake", "~> 10.3"
+gem "rack", "~> 1.0"
+gem "json", "~> 1.7"
+gem "test-unit", "1.2.3"

data/heroic-sns.gemspec

@@ -7,7 +7,15 @@ Gem::Specification.new do |s|
   s.name        = 'heroic-sns'
   s.version     = Heroic::SNS::VERSION
   s.summary     = "Lightweight Rack middleware for AWS SNS endpoints"
-  s.description = File.read('description.txt')
+  s.description = <<-EOD
+Secure, lightweight Rack middleware for Amazon Simple Notification Service (SNS)
+endpoints. SNS messages are intercepted, parsed, verified, and then passed along
+to the web application via the 'sns.message' environment key. Heroic::SNS has no
+dependencies besides Rack (specifically, the aws-sdk gem is not needed).
+SNS message signatures are verified in order to reject forgeries and replay
+attacks.
+EOD
+
   s.license     = 'Apache'
 
   s.author      = "Benjamin Ragheb"
@@ -18,6 +26,8 @@ Gem::Specification.new do |s|
 
   s.platform = Gem::Platform::RUBY
   s.required_ruby_version = '>= 1.8.7'
-  s.add_runtime_dependency 'rack', '~> 1.4'
-  s.add_runtime_dependency 'json', '~> 1.7.7'
+  s.add_development_dependency 'rdoc', '~> 4.0'
+  s.add_development_dependency 'test-unit', '>= 1.2.3'
+  s.add_runtime_dependency 'rack', '>= 1.4'
+  s.add_runtime_dependency 'json', '>= 1.7'
 end

data/lib/heroic/lru_cache.rb

@@ -0,0 +1,165 @@
+module Heroic
+
+  # This LRU Cache is a generic key-value store that is designed to be safe for
+  # concurrent access. It uses a doubly-linked-list to identify which item was
+  # least recently retrieved, and a Hash for fast retrieval by key.
+  #
+  # To support concurrent access, it uses two levels of locks: a cache-level lock
+  # is used to locate or create the desired node and move it to the front of the
+  # LRU list. A node-level lock is used to synchronize access to the node's
+  # value.
+  #
+  # If a thread is busy generating a value to be stored in the cache, other
+  # threads will still be able to read and write to other keys with no conflict.
+  # However, if a second thread tries to read the value that the first thread is
+  # generating, it will block until the first thread has completed its work.
+
+  class LRUCache
+
+    # If you yield a block to the constructor, it will be called on every cache
+    # miss to generate the needed value. This is optional but recommended, as
+    # the block will run while holding a lock on the cache node associated with
+    # the key. Additional attempts to retrieve the same key will wait for your
+    # block to return a result, avoiding duplication of work. However, this also
+    # means you MUST NOT access the cache itself from the block, or you will risk
+    # creating deadlock. (If you need to create cacheable items from other
+    # cacheable items, consider using two separate caches.)
+
+    def initialize(capacity, &block)
+      raise ArgumentError unless capacity > 0
+      @capacity = capacity
+      @block = block || Proc.new { nil }
+      @lock = Mutex.new
+      @store = Hash.new
+      @leftmost = nil
+      @rightmost = nil
+    end
+
+    # Retrieve a value from the cache for a given key. If the value is in the
+    # cache, the method will return immediately. If the value is not in the
+    # cache and a block was provided to the constructor, it will be invoked to
+    # generate the value and insert it into the cache. If another thread is in
+    # the process of generating the same value, the current thread will wait for
+    # it to complete.
+    #
+    # If the cache is full, this method may cause the least recently used item
+    # to be evicted from the cache.
+
+    def get(key)
+      node = node_for_key(key)
+      node.read(&@block)
+    end
+
+    # Inserts a value into the cache, assigning it to the given key. (Instead of
+    # directly inserting values into the cache, it is recommended that you supply
+    # a block to the constructor to generate values on demand.)
+
+    def put(key, value)
+      node = node_for_key(key)
+      node.write(value)
+    end
+
+    # Verify the data structures used to maintain the cache. If a problem is
+    # detected, an exception is raised. This method is intended for testing and
+    # debugging only.
+
+    def verify!
+      @lock.synchronize do
+        left_to_right = Array.new
+        begin
+          node = @leftmost
+          while node
+            left_to_right << node
+            node = node.right
+          end
+        end
+        right_to_left = Array.new
+        begin
+          node = @rightmost
+          while node
+            right_to_left << node
+            node = node.left
+          end
+        end
+        begin
+          raise "leftmost has a left node" if @leftmost && @leftmost.left
+          raise "rightmost has a right node" if @rightmost && @rightmost.right
+          raise "leftmost pointer mismatch" unless @leftmost == left_to_right.first
+          raise "rightmost pointer mismatch" unless @rightmost == right_to_left.first
+          raise "list size mismatch" unless right_to_left.length == left_to_right.length
+          raise "list order mismatch" unless left_to_right.reverse == right_to_left
+          raise "node missing from list" if left_to_right.length < @store.size
+          raise "node missing from store" if left_to_right.length > @store.size
+          raise "store size exceeds capacity" if @store.size > @capacity
+        rescue
+          $stderr.puts "Store: #{@store}"
+          $stderr.puts "L-to-R: #{left_to_right}"
+          $stderr.puts "R-to-L: #{right_to_left}"
+          raise
+        end
+      end
+    end
+
+    private
+
+    class Node # :nodoc:
+      attr_reader :key
+      attr_accessor :left, :right
+      def initialize(key)
+        @key = key
+        @lock = Mutex.new
+      end
+      def read
+        @lock.synchronize { @value ||= yield(@key) }
+      end
+      def write(value)
+        @lock.synchronize { @value = value }
+      end
+      def to_s
+        sprintf '<Node:%x(%s)>', self.object_id, @key.inspect
+      end
+    end
+
+    def node_for_key(key)
+      @lock.synchronize do
+        node = @store[key]
+        if node.nil?
+          # I am a new node, add me to the head of the list!
+          node = @store[key] = Node.new(key)
+          if @leftmost
+            node.right = @leftmost
+            @leftmost.left = node
+          end
+          @leftmost = node
+          @rightmost = @leftmost if @rightmost.nil?
+          if @store.size > @capacity
+            # Uh oh, time to evict the tail node!
+            evicted_node = @store.delete(@rightmost.key)
+            @rightmost = evicted_node.left
+            @rightmost.right = nil
+          end
+        elsif node != @leftmost
+          # Move me to the head of the list!
+          if node == @rightmost
+            # I was the rightmost node, now the node on my left is.
+            @rightmost = node.left
+            node.left.right = nil
+          else
+            # The node on my left should now point to the node on my right.
+            node.left.right = node.right
+            # The node on my right should point to the node on my left.
+            node.right.left = node.left
+          end
+          former_leftmost = @leftmost
+          # I am the new head node!
+          @leftmost = node
+          @leftmost.left = nil
+          @leftmost.right = former_leftmost
+          former_leftmost.left = @leftmost
+        end
+        node
+      end
+    end
+
+  end
+end

data/lib/heroic/sns/endpoint.rb

@@ -1,38 +1,54 @@
 require 'openssl'
 require 'open-uri'
 
-# Heroic::SNS::Endpoint is Rack middleware which intercepts messages from
-# Amazon's Simple Notification Service (SNS). It makes the parsed and verified
-# message available to your application in the Rack environment under the
-# 'sns.message' key. If an error occurred during message handling, the error
-# is available in the Rack environment in the 'sns.error' key.
-
-# Endpoint is to be initialized with a hash of options. It understands three
-# different options:
-# - :topic (or :topics) specifies a filter that defines what SNS topics are
-#   handled by this endpoint ("on-topic"). You can supply any of the following:
-#   - a topic ARN as a String
-#   - a list of topic ARNs as an Array of Strings
-#   - a regular expression matching on-topic ARNs
-#   - a Proc which takes a topic ARN as a String and returns true or false.
-#   You must specify a topic filter. Use Proc.new { true } if you insist on
-#   indiscriminately accepting all notifications.
-# - :auto_confirm determines how SubscriptionConfirmation messages are handled.
-#   If true, the subscription is confirmed and your app is not notified.
-#   If false, the subscription is ignored and your app is not notified.
-#   If nil, the message is passed along to your app.
-
-# You can install this in your config.ru:
-#   use Heroic::SNS::Endpoint, :topics => /whatever/
-
-# For Rails, you can also install it in /config/initializers/sns_endpoint.rb:
-#   Rails.application.config.middleware.use Heroic::SNS::Endpoint, :topic => ...
-
 module Heroic
   module SNS
 
     SUBSCRIPTION_ARN_HTTP_HEADER = 'HTTP_X_AMZ_SNS_SUBSCRIPTION_ARN'
 
+=begin rdoc
+
+  Heroic::SNS::Endpoint is Rack middleware which intercepts messages from
+  Amazon's Simple Notification Service (SNS). It makes the parsed and
+  verified message available to your application in the Rack environment
+  under the 'sns.message' key. If an error occurred during message handling,
+  the error is available in the Rack environment in the 'sns.error' key.
+
+  Endpoint is to be initialized with a hash of options. It understands three
+  different options:
+
+  +:topic+ (or +:topics+) specifies a filter that defines what SNS topics
+  are handled by this endpoint ("on-topic"). You can supply any of the
+  following:
+  - a topic ARN as a String
+  - a list of topic ARNs as an Array of Strings
+  - a regular expression matching on-topic ARNs
+  - a Proc which takes a topic ARN as a String and returns true or false.
+  You *must* specify a topic filter. Use <code>Proc.new{true}</code> if
+  you insist on indiscriminately accepting all notifications.
+
+  +:auto_confirm+ determines how SubscriptionConfirmation messages are handled.
+  - If true, the subscription is confirmed and your app is not notified.
+    This is the default.
+  - If false, the subscription is ignored and your app is not notified.
+  - If nil, the message is passed along to your app.
+
+  +:auto_resubscribe+ affects how on-topic UnsubscribeConfirmation messages are handled.
+  - If false, they are ignored and your app is also not notified.
+    This is the default.
+  - If true, they topic is automatically re-subscribed by retrieving the URL in
+    the `SubscribeURL` field of the SNS message, and your app is not notified.
+  - If nil, there is no special handling and the message is passed along to your
+    app.
+
+  You can install this in your config.ru:
+    use Heroic::SNS::Endpoint, :topics => /whatever/
+
+  For Rails, you can also install it in /config/initializers/sns_endpoint.rb:
+    Rails.application.config.middleware.use Heroic::SNS::Endpoint, :topic => ...
+
+=end
+
     class Endpoint
 
       DEFAULT_OPTIONS = { :auto_confirm => true, :auto_resubscribe => false }
@@ -94,14 +110,15 @@ module Heroic
       def call_on_topic(env)
         begin
           message = Message.new(env['rack.input'].read)
+          env['rack.input'].rewind
           check_headers!(message, env)
           message.verify!
           case message.type
           when 'SubscriptionConfirmation'
-            open(message.subscribe_url) if @auto_confirm
+            URI.parse(message.subscribe_url).open if @auto_confirm
             return OK_RESPONSE unless @auto_confirm.nil?
           when 'UnsubscribeConfirmation'
-            open(message.subscribe_url) if @auto_resubscribe
+            URI.parse(message.subscribe_url).open if @auto_resubscribe
             return OK_RESPONSE unless @auto_resubscribe.nil?
           end
           env['sns.message'] = message
@@ -122,7 +139,7 @@ module Heroic
           begin
             message = Message.new(env['rack.input'].read)
             message.verify!
-            open(message.unsubscribe_url)
+            URI.parse(message.unsubscribe_url).open
           rescue => e
             raise Error.new("error handling off-topic notification: #{e.message}", message)
           end

data/lib/heroic/sns/message.rb

@@ -1,23 +1,31 @@
 require 'json'
 require 'base64'
+require 'open-uri'
+require 'heroic/lru_cache'
 
 module Heroic
   module SNS
 
     MAXIMUM_ALLOWED_AGE = 3600 # reject messages older than one hour
+    MAXIMUM_ALLOWED_CERTIFICATES = 50
 
-    CERTIFICATE_CACHE = Hash.new do |cache, cert_url|
+    CERTIFICATE_CACHE = Heroic::LRUCache.new(MAXIMUM_ALLOWED_CERTIFICATES) do |cert_url|
       begin
-        cert_data = open(cert_url)
-        cache[cert_url] = OpenSSL::X509::Certificate.new(cert_data.read)
-      rescue OpenURI::HTTPError => e
-        raise Error.new("unable to retrieve signing certificate: #{e.message}; URL: #{cert_url}")
+        cert_data = URI.parse(cert_url).open
+        OpenSSL::X509::Certificate.new(cert_data.read)
       rescue OpenSSL::X509::CertificateError => e
-        raise Error.new("unable to parse signing certificate: #{e.message}; URL: #{cert_url}")
+        raise SNS::Error.new("unable to parse signing certificate: #{e.message}; URL: #{cert_url}")
+      rescue => e
+        raise SNS::Error.new("unable to retrieve signing certificate: #{e.message}; URL: #{cert_url}")
       end
     end
 
-    # Encapsulates an SNS message.
+    VALID_AWS_URL_PATTERN = %r{\Ahttps://sns\.[a-z]{2}(?:-gov)?-(?:north|south|east|west|central){1,2}-\d+\.amazonaws\.com(?:\.cn)?/}
+
+    # Encapsulates an SNS message. Since Endpoint takes care of authenticating
+    # the message, most of the time you will simply be interested in retrieving
+    # the +subject+ and +body+ from the message and acting on it.
+    #
     # See: http://docs.aws.amazon.com/sns/latest/gsg/json-formats.html
     class Message
 
@@ -27,6 +35,8 @@ module Heroic
         raise Error.new("failed to parse message as JSON: #{e.message}")
       end
 
+      # The message type will be one of +SubscriptionConfirmation+,
+      # +UnsubscribeConfirmation+, and +Notification+.
       def type
         @msg['Type']
       end
@@ -35,11 +45,14 @@ module Heroic
         @msg['TopicArn']
       end
 
+      # A Universally Unique Identifier, unique for each message published. For
+      # a notification that Amazon SNS resends during a retry, the message ID of
+      # the original message is used.
       def id
         @msg['MessageId']
       end
 
-      # The timestamp as a Time object.
+      # The timestamp when the message was published, as a Time object.
       def timestamp
         Time.xmlschema(@msg['Timestamp'])
       end
@@ -62,6 +75,9 @@ module Heroic
         @msg['Subject']
       end
 
+      # The message payload. As far as Amazon and this class are concerned, the
+      # message payload is just a string of bytes. If you are expecting, for
+      # example, a JSON object, you will need to pass this to a JSON parser.
       def body
         @msg['Message']
       end
@@ -75,13 +91,13 @@ module Heroic
       end
 
       # The token is used to confirm subscriptions via the SNS API. If you visit
-      # the :subscribe_url, you can ignore this field.
+      # the +subscribe_url+, you can ignore this field.
       def token
         @msg['Token']
       end
 
-      def ==(other_message)
-        @msg == other_message.instance_variable_get(:@msg)
+      def ==(other)
+        other.is_a?(Message) && @msg == other.instance_variable_get(:@msg)
       end
 
       def hash
@@ -96,24 +112,27 @@ module Heroic
         string << ">"
       end
 
+      # Returns a JSON serialization of the message. Note that it may not be
+      # identical to the serialization that was retrieved from the network.
       def to_json
         @msg.to_json
       end
 
-      # Verifies the message signature. Raises an exception if it is not valid.
+      # Verifies the message signature. Raises Error if it is not valid.
+      #
       # See: http://docs.aws.amazon.com/sns/latest/gsg/SendMessageToHttp.verify.signature.html
       def verify!
         age = Time.now - timestamp
-        raise Errow.new("timestamp is in the future", self) if age < 0
+        raise Error.new("timestamp is in the future, age: #{age}", self) if age < 0
         raise Error.new("timestamp is too old", self) if age > MAXIMUM_ALLOWED_AGE
         if signature_version != '1'
           raise Error.new("unknown signature version: #{signature_version}", self)
         end
-        if signing_cert_url !~ %r[^https://.*amazonaws\.com/]
+        if signing_cert_url !~ VALID_AWS_URL_PATTERN
           raise Error.new("signing certificate is not from amazonaws.com", self)
         end
         text = string_to_sign # will warn of invalid Type
-        cert = CERTIFICATE_CACHE[signing_cert_url]
+        cert = CERTIFICATE_CACHE.get(signing_cert_url)
         digest = OpenSSL::Digest::SHA1.new
         unless cert.public_key.verify(digest, signature, text)
           raise Error.new("message signature is invalid", self)

data/lib/heroic/sns/version.rb

@@ -1,5 +1,5 @@
 module Heroic
   module SNS
-    VERSION = '1.0.1'
+    VERSION = '1.2'
   end
 end

data/test/fixtures/aws-sns-endpoints.txt

@@ -0,0 +1,27 @@
+sns.af-south-1.amazonaws.com
+sns.ap-east-1.amazonaws.com
+sns.ap-northeast-1.amazonaws.com
+sns.ap-northeast-2.amazonaws.com
+sns.ap-northeast-3.amazonaws.com
+sns.ap-south-1.amazonaws.com
+sns.ap-southeast-1.amazonaws.com
+sns.ap-southeast-2.amazonaws.com
+sns.ca-central-1.amazonaws.com
+sns.cn-north-1.amazonaws.com
+sns.cn-northwest-1.amazonaws.com
+sns.eu-central-1.amazonaws.com
+sns.eu-north-1.amazonaws.com
+sns.eu-south-1.amazonaws.com
+sns.eu-west-1.amazonaws.com
+sns.eu-west-2.amazonaws.com
+sns.eu-west-3.amazonaws.com
+sns.me-south-1.amazonaws.com
+sns.sa-east-1.amazonaws.com
+sns.us-east-1.amazonaws.com
+sns.us-east-2.amazonaws.com
+sns.us-west-1.amazonaws.com
+sns.us-west-2.amazonaws.com
+sns.us-gov-east-1.amazonaws.com
+sns.us-gov-west-1.amazonaws.com
+sns.cn-north-1.amazonaws.com.cn
+sns.cn-northwest-1.amazonaws.com.cn

data/test/helper.rb

@@ -5,30 +5,34 @@
 
 module Heroic
   module SNS
+    # Use a fake certificate cache so tests aren't dependent on
+    # network access, or the fact that the certificate is also fake.
+    CERTIFICATE_CACHE = Class.new do
+      def cert_data
+        File.read('test/fixtures/sns.crt')
+      end
 
-    TEST_CERT_URL = 'https://sns.test.amazonaws.com/self-signed.pem'
-    TEST_CERT_KEY = OpenSSL::PKey::RSA.new(File.read('test/fixtures/sns.key'))
+      def get(_)
+        @cert ||= OpenSSL::X509::Certificate.new(cert_data)
+      end
+    end.new
 
-    CERTIFICATE_CACHE[TEST_CERT_URL] = begin
-      # Insert the certificate in the cache so that these tests aren't dependent
-      # on network access (or the fact that the certificate is fake).
-      cert_data = File.read('test/fixtures/sns.crt')
-      OpenSSL::X509::Certificate.new(cert_data)
-    end
+    TEST_CERT_URL = 'https://sns.xx-east-1.amazonaws.com/self-signed.pem'
+    TEST_CERT_KEY = OpenSSL::PKey::RSA.new(File.read('test/fixtures/sns.key'))
 
     class Message
-
       def update_timestamp!(t = Time.now)
         @msg['Timestamp'] = t.utc.xmlschema(3)
       end
 
+      def update_signing_cert_url!(url = nil)
+        @msg['SigningCertURL'] = url || TEST_CERT_URL
+      end
+
       def sign!
-        @msg['SigningCertURL'] = TEST_CERT_URL
         signature = TEST_CERT_KEY.sign(OpenSSL::Digest::SHA1.new, string_to_sign)
         @msg['Signature'] = Base64::encode64(signature)
       end
-
     end
-
   end
 end

data/test/test_endpoint.rb

@@ -10,6 +10,7 @@ class EndpointTest < Test::Unit::TestCase
     json = File.read("test/fixtures/#{name}.json")
     @msg = Heroic::SNS::Message.new(json)
     @msg.update_timestamp!
+    @msg.update_signing_cert_url!
     @msg.sign!
     @env = {
       'HTTP_X_AMZ_SNS_MESSAGE_TYPE' => @msg.type,
@@ -44,4 +45,16 @@ class EndpointTest < Test::Unit::TestCase
     assert_nothing_raised { app.call(@env) }
   end
 
+  def test_rewind
+    result = [0, {}, []]
+
+    test = Proc.new do |env|
+      msg_json = JSON.parse(env['rack.input'].read)
+      assert_equal(msg_json['Message'],'booyakasha!')
+      result
+    end
+    sns('notification')
+    app = Heroic::SNS::Endpoint.new test, :topic => @msg.topic_arn
+    assert_equal result, app.call(@env)
+  end
 end

data/test/test_lru_cache.rb

@@ -0,0 +1,111 @@
+require 'test/unit'
+require 'heroic/lru_cache'
+
+class LRUCacheTest < Test::Unit::TestCase
+
+  def test_invalid_size
+    assert_raises ArgumentError do
+      Heroic::LRUCache.new(0) { |k| nil }
+    end
+    assert_raises ArgumentError do
+      Heroic::LRUCache.new(-1) { |k| nil }
+    end
+  end
+
+  def test_get_put
+    cache = Heroic::LRUCache.new(1)
+    assert_nil cache.get(:casey)
+    cache.put(:casey, :jones)
+    assert_equal :jones, cache.get(:casey)
+    cache.put(:april, :oneil)
+    assert_equal :oneil, cache.get(:april)
+    assert_nil cache.get(:casey)
+  end
+
+  def test_exceptions
+    @should_throw = true
+    cache = Heroic::LRUCache.new(3) do |k|
+      if @should_throw
+        raise "tried to load a value but failed"
+      else
+        4
+      end
+    end
+    assert_raises RuntimeError do
+      cache.get(:ooze)
+    end
+    @should_throw = false
+    assert_equal 4, cache.get(:ooze)
+  end
+
+  def test_dynamic
+    @counter = 0
+    cache = Heroic::LRUCache.new(3) { |k| @counter += 1; k.to_s.length }
+    assert_equal 0, @counter
+    cache.verify!
+    assert_equal 3, cache.get(:leo); assert_equal 1, @counter
+    cache.verify!
+    assert_equal 3, cache.get(:leo); assert_equal 1, @counter
+    cache.verify!
+    assert_equal 6, cache.get(:donnie); assert_equal 2, @counter
+    cache.verify!
+    assert_equal 6, cache.get(:donnie); assert_equal 2, @counter
+    cache.verify!
+    assert_equal 5, cache.get(:mikey); assert_equal 3, @counter
+    cache.verify!
+    assert_equal 5, cache.get(:mikey); assert_equal 3, @counter
+    cache.verify!
+    # raph will push leo out of cache
+    assert_equal 4, cache.get(:raph); assert_equal 4, @counter
+    cache.verify!
+    assert_equal 4, cache.get(:raph); assert_equal 4, @counter
+    cache.verify!
+    # mikey and donnie remain in cache
+    assert_equal 5, cache.get(:mikey); assert_equal 4, @counter
+    cache.verify!
+    assert_equal 6, cache.get(:donnie); assert_equal 4, @counter
+    cache.verify!
+    # leo will have to be refetched
+    assert_equal 3, cache.get(:leo); assert_equal 5, @counter
+    cache.verify!
+  end
+
+  def test_sync
+    @lock = Mutex.new
+    @counter = 0
+    cache = Heroic::LRUCache.new(100) do |k|
+      sleep 1 # simulate slow generation, such as network I/O
+      @lock.synchronize { @counter += 1 }
+      k.to_s.length
+    end
+    # load the cache with things to read
+    cache.put(:leo, 0)
+    cache.put(:donnie, 0)
+    start_time = Time.now
+    # Start threads to fetch in background. :leo and :donnie should return
+    # immediately, because the values are in the cache; :mikey and :raph should
+    # run concurrently; the second :raph should wait on the first :raph to
+    # complete.
+    threads = [:leo, :donnie, :mikey, :raph, :raph].map do |k|
+      Thread.new { cache.get(k) }
+    end
+    # Fetching values already in the cache should not block.
+    assert_equal 0, cache.get(:leo)
+    assert_equal 0, cache.get(:donnie)
+    assert_equal 0, @lock.synchronize { @counter }
+    # Fetching values being computed now will block until somebody computes them.
+    assert_equal 5, cache.get(:mikey)
+    assert_equal 4, cache.get(:raph)
+    assert_equal 2, @lock.synchronize { @counter }
+    # Fetching those same values should not trigger a recompute.
+    assert_equal 5, cache.get(:mikey)
+    assert_equal 4, cache.get(:raph)
+    assert_equal 2, @lock.synchronize { @counter }
+    # Let's wait for all threads to finish, then check the clock to make sure we
+    # only slept for a second.
+    threads.each { |t| t.join }
+    time_elapsed = (Time.now - start_time)
+    assert_in_delta time_elapsed, 1.0, 0.05
+  end
+
+end

data/test/test_message.rb

@@ -3,11 +3,11 @@ require 'heroic/sns'
 require 'helper'
 
 class MessageTest < Test::Unit::TestCase
-
-  def sns(name, timestamp = Time.now)
+  def sns(name, options = {})
     json = File.read("test/fixtures/#{name}.json")
     msg = Heroic::SNS::Message.new(json)
-    msg.update_timestamp!(timestamp)
+    msg.update_timestamp!(options[:timestamp] || Time.now)
+    msg.update_signing_cert_url!(options[:signing_cert_url])
     msg.sign!
     return msg
   end
@@ -51,13 +51,41 @@ class MessageTest < Test::Unit::TestCase
     end
   end
 
+  def test_untrusted_cert_url_s3
+    cert_url = 'https://sns.s3.amazonaws.com/self-signed.pem'
+    msg = sns("notification", :signing_cert_url => cert_url)
+    assert_equal cert_url, msg.signing_cert_url
+    assert_raises Heroic::SNS::Error do
+      msg.verify!
+    end
+  end
+
+  def test_untrusted_cert_url_other
+    cert_url = 'https://example.com/sns.us-east-1.amazonaws.com/self-signed.pem'
+    msg = sns("subscription", :signing_cert_url => cert_url)
+    assert_equal cert_url, msg.signing_cert_url
+    assert_raises Heroic::SNS::Error do
+      msg.verify!
+    end
+  end
+
+  # Generate tests for every known AWS SNS endpoint.
+  # https://docs.aws.amazon.com/general/latest/gr/sns.html
+  File.read('test/fixtures/aws-sns-endpoints.txt').split(/\n/).each do |domain|
+    define_method("test_trusted_cert_url_#{domain}") do
+      cert_url = "https://#{domain}/certificate.pem"
+      msg = sns("notification", :signing_cert_url => cert_url)
+      assert_equal cert_url, msg.signing_cert_url
+      assert_nothing_raised { msg.verify! }
+    end
+  end
+
   def test_expired
     t = Time.utc(1984, 5)
-    msg = sns("notification", t)
+    msg = sns("notification", :timestamp => t)
     assert_equal t, msg.timestamp
     assert_raises Heroic::SNS::Error do
       msg.verify!
     end
   end
-
 end

metadata

@@ -1,66 +1,86 @@
 --- !ruby/object:Gem::Specification
 name: heroic-sns
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: '1.2'
 platform: ruby
 authors:
 - Benjamin Ragheb
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-17 00:00:00.000000000 Z
+date: 2020-06-15 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.3
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.4'
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.7.7
+        version: '1.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.7.7
-description: ! 'Secure, lightweight Rack middleware for Amazon Simple Notification
-  Service (SNS)
-
+        version: '1.7'
+description: |
+  Secure, lightweight Rack middleware for Amazon Simple Notification Service (SNS)
   endpoints. SNS messages are intercepted, parsed, verified, and then passed along
-
-  to the web application via the ''sns.message'' environment key. Heroic::SNS has
-  no
-
+  to the web application via the 'sns.message' environment key. Heroic::SNS has no
   dependencies besides Rack (specifically, the aws-sdk gem is not needed).
-
   SNS message signatures are verified in order to reject forgeries and replay
-
   attacks.
-
-'
 email: ben@benzado.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .travis.yml
-- CHANGELOG
+- ".gitignore"
+- ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE
 - README.md
@@ -68,12 +88,15 @@ files:
 - bin/fake-sns
 - demo/config.ru
 - demo/demo.erb
-- description.txt
+- gemfiles/Gemfile.rack-1.x
+- gemfiles/Gemfile.ruby-1.8
 - heroic-sns.gemspec
+- lib/heroic/lru_cache.rb
 - lib/heroic/sns.rb
 - lib/heroic/sns/endpoint.rb
 - lib/heroic/sns/message.rb
 - lib/heroic/sns/version.rb
+- test/fixtures/aws-sns-endpoints.txt
 - test/fixtures/notification.json
 - test/fixtures/sns.crt
 - test/fixtures/sns.key
@@ -81,6 +104,7 @@ files:
 - test/fixtures/unsubscribe.json
 - test/helper.rb
 - test/test_endpoint.rb
+- test/test_lru_cache.rb
 - test/test_message.rb
 homepage: https://github.com/benzado/heroic-sns
 licenses:
@@ -92,17 +116,16 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: 1.8.7
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 3.0.8
 signing_key: 
 specification_version: 4
 summary: Lightweight Rack middleware for AWS SNS endpoints

data/CHANGELOG

@@ -1,9 +0,0 @@
-### 1.0.1 (May 17, 2013)
-
-* Gem housekeeping, based on [advice by dblock](http://code.dblock.org/your-first-ruby-gem)
-
-### 1.0.0 (May 5, 2013)
-
-* Initial public release - [@benzado]
-
-[@benzado]: http://github.com/benzado

data/description.txt

@@ -1,6 +0,0 @@
-Secure, lightweight Rack middleware for Amazon Simple Notification Service (SNS)
-endpoints. SNS messages are intercepted, parsed, verified, and then passed along
-to the web application via the 'sns.message' environment key. Heroic::SNS has no
-dependencies besides Rack (specifically, the aws-sdk gem is not needed).
-SNS message signatures are verified in order to reject forgeries and replay
-attacks.