aws-sessionstore-dynamodb 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1395af7cb7211af4f4cb72dcd4037ee046627a64
+  data.tar.gz: 55d5c7eb166a8571b05c883fb05baa53d293152f
+SHA512:
+  metadata.gz: a9f754fabdd1af66c5853249a946b39b76eca01db99ee569ba9f63b11eec8ba2be7f93d94f6e8055af7013371dde889d6af3c3e093967aeaa24dd56c9b4b52f3
+  data.tar.gz: 3d276410f121bdf18acc8217a14c4cc6967a0cd84863e562aa4dd17e1ce38765d4ee42da3472cc3a9ca75d10cbf20ec6cdac15877e2d7d01d84eac39072dca63

data/.gitignore

@@ -0,0 +1,4 @@
+doc
+coverage
+.yardoc
+Gemfile.lock

data/.yardopts

@@ -0,0 +1,3 @@
+--title "Amazon DynamoDB Session Store"
+--exclude /generators/
+--hide-api private

data/Gemfile

@@ -0,0 +1,28 @@
+# Copyright 2013 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake', '~> 10.0'
+
+group :documentation do
+  gem 'yard', '~> 0.0'
+end
+
+group :test do
+  gem 'rspec', '~> 2.0'
+  gem 'simplecov', '~> 0.0', :require => false
+  gem 'rack-test', '~> 0.0'
+end

data/LICENSE.txt

@@ -0,0 +1,12 @@
+Copyright 2013 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License"). You
+may not use this file except in compliance with the License. A copy of
+the License is located at
+
+    http://aws.amazon.com/apache2.0/
+
+or in the "license" file accompanying this file. This file is
+distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+ANY KIND, either express or implied. See the License for the specific
+language governing permissions and limitations under the License.

data/README.md

@@ -0,0 +1,171 @@
+# Amazon DynamoDB Session Store
+
+The **Amazon DynamoDB Session Store** handles sessions for Ruby web applications
+using a DynamoDB backend. The session store is compatible with Rails and other
+Rack based frameworks.
+
+## Installation
+
+#### Rails Installation
+
+Install the session store gem by placing the following command into your
+Gemfile:
+
+    gem 'aws-sessionstore-dynamodb'
+
+You will need to have an existing Amazon DynamoDB session table in order for the
+application to work. You can generate a migration file for the session table
+with the following command:
+
+    rails generate sessionstore:dynamodb
+
+To create the table, run migrations as normal with:
+
+    rake db:migrate
+
+Change the session store to `:dynamodb_store` by editing
+`config/initializers/session_store.rb` to contain the following:
+
+    YourAppName::Application.config.session_store :dynamodb_store
+
+You can now start your Rails application with session support.
+
+#### Basic Rack Application Installation
+
+For non-Rails applications, you can create the Amazon DynamoDB table in a
+Ruby file using the following method:
+
+    require 'aws-sessionstore-dynamodb'
+
+    AWS::SessionStore::DynamoDB::Table.create_table
+
+Run the session store as a Rack middleware in the following way:
+
+    require 'aws-sessionstore-dynamodb'
+    require 'some_rack_app'
+
+    options = { :secret_key => 'SECRET_KEY' }
+
+    use AWS::SessionStore::DynamoDB::RackMiddleware.new(options)
+    run SomeRackApp
+
+Note that `:secret_key` is a mandatory configuration option that must be set.
+
+## Detailed Usage
+
+The session store is a Rack Middleware, meaning that it will implement the Rack
+interface for dealing with HTTP request/responses.
+
+This session store uses a DynamoDB backend in order to provide scaling and
+centralized data benefits for session storage with more ease than other
+containers, like local servers or cookies. Once an application scales beyond
+a single web server, session data will need to be shared across the servers.
+DynamoDB takes care of this burden for you by scaling with your application.
+Cookie storage places all session data on the client side,
+discouraging sensitive data storage. It also forces strict data size
+limitations. DynamoDB takes care of these concerns by allowing for a safe and
+scalable storage container with a much larger data size limit for session data.
+
+Full API documentation of the library can be found on [RubyDoc.info][1].
+
+### Configuration Options
+
+A number of options are available to be set in
+`AWS::SessionStore::DynamoDB::Configuration`, which is used by the
+`RackMiddleware` class. These options can be set in the YAML configuration
+file in a Rails application (located in `config/sessionstore/dynamodb.yml`),
+directly by Ruby code, or through environment variables.
+
+The full set of options along with defaults can be found in the
+[Configuration class documentation][2].
+
+#### Environment Options
+
+Certain configuration options can be loaded from the environment. These
+options must be specified in the following format:
+
+    DYNAMO_DB_SESSION_NAME-OF-CONFIGURATION-OPTION
+
+The example below would be a valid way to set the session table name:
+
+    export DYNAMO_DB_SESSION_TABLE_NAME='sessions'
+
+### Rails Generator Details
+
+The generator command specified in the installation section will generate two
+files: a migration file, `db/migration/VERSION_migration_name.rb`, and a
+configuration YAML file, `config/sessionstore/dynamodb.yml`.
+
+You can run the command with an argument that will define the name of the
+migration file. Once the YAML file is created, you can uncomment any of the
+lines to set configuration options to your liking. The session store will pull
+options from `config/sessionstore/dynamodb.yml` by default if the file exists.
+If you do not wish to place the configuration YAML file in that location,
+you can also pass in a different file path to pull options from.
+
+### Garbage Collection
+
+You may want to delete old sessions from your session table. The
+following examples show how to clear old sessions from your table.
+
+#### Rails
+
+A Rake task for garbage collection is provided for Rails applications.
+By default sessions do not expire. See `config/sessionstore/dynamodb.yml` to
+configure the max age or stale period of a session. Once you have configured
+those values you can clear the old sessions with:
+
+    rake dynamo_db:collect_garbage
+
+#### Outside of Rails
+
+You can create your own Rake task for garbage collection similar to below:
+
+    require "aws-sessionstore-dynamodb"
+
+    desc 'Perform Garbage Collection'
+    task :garbage_collect do |t|
+     options = {:max_age => 3600*24, max_stale => 5*3600 }
+     AWS::SessionStore::DynamoDB::GarbageCollection.collect_garbage(options)
+    end
+
+The above example will clear sessions older than one day or that have been
+stale for longer than an hour.
+
+### Locking Strategy
+
+You may want the Session Store to implement the provided pessimistic locking
+strategy if you are concerned about concurrency issues with session accesses.
+By default, locking is not implemented for the session store. You must trigger
+the locking strategy through the configuration of the session store. Pessimistic
+locking, in this case, means that only one read can be made on a session at
+once. While the session is being read by the process with the lock, other
+processes may try to obtain a lock on the same session but will be blocked.
+
+Locking is expensive and will drive up costs depending on how it is used.
+Without locking, one read and one write are performed per request for session
+data manipulation. If a locking strategy is implemented, as many as the total
+maximum wait time divided by the lock retry delay writes to the database.
+Keep these considerations in mind if you plan to enable locking.
+
+#### Configuration for Locking
+
+The following configuration options will allow you to configure the pessimistic
+locking strategy according to your needs:
+
+    options = {
+      :enable_locking => true,
+      :lock_expiry_time => 500,
+      :lock_retry_delay => 500,
+      :lock_max_wait_time => 1
+    }
+
+### Error Handling
+
+You can pass in your own error handler for raised exceptions or you can allow
+the default error handler to them for you. See the API documentation
+on the {AWS::SessionStore::DynamoDB::Errors::BaseHandler} class for more
+details.
+
+[1]: http://rubydoc.org/gems/aws-sessionstore-dynamodb/frames
+[2]: http://rubydoc.org/gems/aws-sessionstore-dynamodb/AWS/SessionStore/DynamoDB/Configuration#initialize-instance_method

data/Rakefile

@@ -0,0 +1,15 @@
+# Copyright 2013 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+Dir.glob(File.dirname(__FILE__) + '/tasks/*.rake').each {|file| load file }
+task :default => 'test:unit'

data/aws-sessionstore-dynamodb.gemspec

@@ -0,0 +1,18 @@
+require File.dirname(__FILE__) + '/lib/aws/session_store/dynamo_db/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "aws-sessionstore-dynamodb"
+  spec.version       = AWS::SessionStore::DynamoDB::VERSION
+  spec.authors       = ["Ruby Robinson"]
+  spec.summary       = "The Amazon DynamoDB Session Store handles sessions " +
+                       "for Ruby web applications using a DynamoDB backend."
+  spec.homepage      = "http://github.com/aws/aws-sessionstore-dynamodb-ruby"
+  spec.license       = "Apache License 2.0"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'aws-sdk', '~> 1.0'
+  spec.add_dependency 'rack', '~> 1.0'
+end

data/lib/aws-sessionstore-dynamodb.rb

@@ -0,0 +1,34 @@
+# Copyright 2013 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+
+module AWS
+  module SessionStore
+    module DynamoDB; end
+  end
+end
+
+require 'aws/session_store/dynamo_db/configuration'
+require 'aws/session_store/dynamo_db/invalid_id_error'
+require 'aws/session_store/dynamo_db/missing_secret_key_error'
+require 'aws/session_store/dynamo_db/lock_wait_timeout_error'
+require 'aws/session_store/dynamo_db/errors/base_handler'
+require 'aws/session_store/dynamo_db/errors/default_handler'
+require 'aws/session_store/dynamo_db/garbage_collection'
+require 'aws/session_store/dynamo_db/locking/base'
+require 'aws/session_store/dynamo_db/locking/null'
+require 'aws/session_store/dynamo_db/locking/pessimistic'
+require 'aws/session_store/dynamo_db/rack_middleware'
+require 'aws/session_store/dynamo_db/table'
+require 'aws/session_store/dynamo_db/version'
+require 'aws/session_store/dynamo_db/railtie' if defined?(Rails)

data/lib/aws/session_store/dynamo_db/configuration.rb

@@ -0,0 +1,298 @@
+# Copyright 2013 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'yaml'
+require 'aws-sdk'
+
+module AWS::SessionStore::DynamoDB
+  # This class provides a Configuration object for all DynamoDB transactions
+  # by pulling configuration options from Runtime, a YAML file, the ENV and
+  # default settings.
+  #
+  # == Environment Variables
+  # The Configuration object can load default values from your environment. An example
+  # of setting and environment variable is below:
+  #
+  #   export DYNAMO_DB_SESSION_TABLE_NAME='Sessions'
+  #
+  # == Handling Errors
+  # There are two configurable options for error handling: :raise_errors and :error_handler.
+  #
+  # If you would like to use the Default Error Handler, you can decide to set :raise_errors
+  # to true or false depending on whether you want all errors, regadless of class, to be raised
+  # up the stack and essentially throw a 500.
+  #
+  # If you decide to use your own Error Handler. You may pass it in for the value of the key
+  # :error_handler as a cofniguration object. You must implement the BaseErrorHandler class.
+  # @see BaseHandler Interface for Error Handling for DynamoDB Session Store.
+  #
+  # == Locking Strategy
+  # By default, locking is not implemented for the session store. You must trigger the
+  # locking strategy through the configuration of the session store. Pessimistic locking,
+  # in this case, means that only one read can be made on a session at once. While the session
+  # is being read by the process with the lock, other processes may try to obtain a lock on
+  # the same session but will be blocked. See the accessors with lock in their name for
+  # how to configure the pessimistic locking strategy to your needs.
+  #
+  # == DynamoDB Specific Options
+  # You may configure the table name and table hash key value of your session table with
+  # the :table_name and :table_key options. You may also configure performance options for
+  # your table with the :consistent_read, :read_capacity, write_capacity. For more information
+  # about these configurations see CreateTable method for Amazon DynamoDB.
+  #
+  class Configuration
+
+    # Default configuration options
+    DEFAULTS = {
+      :table_name => "sessions",
+      :table_key => "session_id",
+      :consistent_read => true,
+      :read_capacity => 10,
+      :write_capacity => 5,
+      :raise_errors => false,
+      # :max_age => 7*3600*24,
+      # :max_stale => 3600*5,
+      :enable_locking => false,
+      :lock_expiry_time => 500,
+      :lock_retry_delay => 500,
+      :lock_max_wait_time => 1,
+      :secret_key => nil,
+      :api_version => '2012-08-10'
+    }
+
+    # @return [String] Session table name.
+    attr_reader :table_name
+
+    # @return [String] Session table hash key name.
+    attr_reader :table_key
+
+    # @return [true] If a strongly consistent read is used
+    # @return [false] If an eventually consistent read is used.
+    # See AWS DynamoDB documentation for table consistent_read for more
+    # information on this setting.
+    attr_reader :consistent_read
+
+    # @return [Integer] Maximum number of reads consumed per second before
+    #   DynamoDB returns a ThrottlingException. See AWS DynamoDB documentation
+    #   for table read_capacity for more information on this setting.
+    attr_reader :read_capacity
+
+    # @return [Integer] Maximum number of writes consumed per second before
+    #   DynamoDB returns a ThrottlingException. See AWS DynamoDB documentation
+    #   for table write_capacity for more information on this setting.
+    attr_reader :write_capacity
+
+    # @return [true] All errors are raised up the stack when default ErrorHandler
+    #   is used.
+    # @return [false] Only specified errors are raised up the stack when default
+    #   ErrorHandler is used.
+    attr_reader :raise_errors
+
+    # @return [DynamoDB Client] DynamoDB client.
+    attr_reader :dynamo_db_client
+
+    # @return [Error Handler] An error handling object that handles all exceptions
+    #   thrown during execution of the AWS DynamoDB Session Store Rack Middleware.
+    #   For more information see the Handling Errors Section.
+    attr_reader :error_handler
+
+    # @return [Integer] Maximum number of seconds earlier
+    #   from the current time that a session was created.
+    attr_reader :max_age
+
+    # @return [Integer] Maximum number of seconds
+    #   before the current time that the session was last accessed.
+    attr_reader :max_stale
+
+    # @return [String] The secret key for HMAC encryption.
+    attr_reader :secret_key
+
+    # @return [true] Pessimistic locking strategy will be implemented for
+    #   all session accesses.
+    # @return [false] No locking strategy will be implemented for
+    #   all session accesses.
+    attr_reader :enable_locking
+
+    # @return [Integer] Time in milleseconds after which lock will expire.
+    attr_reader :lock_expiry_time
+
+    # @return [Integer] Time in milleseconds to wait before retrying to obtain
+    #   lock once an attempt to obtain lock has been made and has failed.
+    attr_reader :lock_retry_delay
+
+    # @return [Integer] Maximum time in seconds to wait to acquire lock
+    #   before giving up.
+    attr_reader :lock_max_wait_time
+
+
+    # Provides configuration object that allows access to options defined
+    # during Runtime, in a YAML file, in the ENV and by default.
+    #
+    # @option options [String] :table_name ("Sessions") Name of the session
+    #   table.
+    # @option options [String] :table_key ("id") The hash key of the sesison
+    #   table.
+    # @option options [Boolean] :consistent_read (true) If true, a strongly
+    #   consistent read is used. If false, an eventually consistent read is
+    #   used.
+    # @option options [Integer] :read_capacity (10) The maximum number of
+    #   strongly consistent reads consumed per second before
+    #   DynamoDB raises a ThrottlingException. See AWS DynamoDB documentation
+    #   for table read_capacity for more information on this setting.
+    # @option options [Integer] :write_capacity (5) The maximum number of writes
+    #   consumed per second before DynamoDB returns a ThrottlingException.
+    #   See AWS DynamoDB documentation for table write_capacity for more
+    #   information on this setting.
+    # @option options [DynamoDB Client] :dynamo_db_client
+    #   (AWS::DynamoDB::ClientV2) DynamoDB client used to perform database
+    #   operations inside of middleware application.
+    # @option options [Boolean] :raise_errors (false) If true, all errors are
+    #   raised up the stack when default ErrorHandler. If false, Only specified
+    #   errors are raised up the stack when default ErrorHandler is used.
+    # @option options [Error Handler] :error_handler (DefaultErrorHandler)
+    #   An error handling object that handles all exceptions thrown during
+    #   execution of the AWS DynamoDB Session Store Rack Middleware.
+    #   For more information see the Handling Errors Section.
+    # @option options [Integer] :max_age (nil) Maximum number of seconds earlier
+    #   from the current time that a session was created.
+    # @option options [Integer] :max_stale (nil) Maximum number of seconds
+    #   before current time that session was last accessed.
+    # @option options [String] :secret_key (nil) Secret key for HMAC encription.
+    # @option options [Integer] :enable_locking (false) If true, a pessimistic
+    #   locking strategy will be implemented for all session accesses.
+    #   If false, no locking strategy will be implemented for all session
+    #   accesses.
+    # @option options [Integer] :lock_expiry_time (500) Time in milliseconds
+    #   after which lock expires on session.
+    # @option options [Integer] :lock_retry_delay (500) Time in milleseconds to
+    #   wait before retrying to obtain lock once an attempt to obtain lock
+    #   has been made and has failed.
+    # @option options [Integer] :lock_max_wait_time (500) Maximum time in seconds
+    #   to wait to acquire lock before giving up.
+    # @option options [String] :secret_key (SecureRandom.hex(64))
+    #   Secret key for HMAC encription.
+    def initialize(options = {})
+      @options = default_options.merge(
+      env_options.merge(
+          file_options(options).merge(
+            symbolize_keys(options)
+           )
+         )
+       )
+      @options = client_error.merge(@options)
+      set_attributes(@options)
+    end
+
+    # @return [Hash] The merged configuration hash.
+    def to_hash
+      @options.dup
+    end
+
+    private
+
+    # @return [Hash] DDB client.
+    def gen_dynamo_db_client
+      client_opts = client_subset(@options)
+      client = AWS::DynamoDB::Client
+      dynamo_db_client = @options[:dynamo_db_client] || client.new(client_opts)
+      {:dynamo_db_client => dynamo_db_client}
+    end
+
+    # @return [Hash] Default Error Handler
+    def gen_error_handler
+      default_handler = AWS::SessionStore::DynamoDB::Errors::DefaultHandler
+      error_handler = @options[:error_handler] ||
+                            default_handler.new(@options[:raise_errors])
+      {:error_handler => error_handler}
+    end
+
+    # @return [Hash] Client and error objects in hash.
+    def client_error
+      gen_error_handler.merge(gen_dynamo_db_client)
+    end
+
+    # @return [Hash] Default Session table options.
+    def default_options
+      DEFAULTS
+    end
+
+    # @return [Hash] Environment options that are useful for Session Handler.
+    def env_options
+      default_options.keys.inject({}) do |opts, opt_name|
+        env_var = "DYNAMO_DB_SESSION_#{opt_name.to_s.upcase}"
+        opts[opt_name] = ENV[env_var] if ENV.key?(env_var)
+        opts
+      end
+    end
+
+    # @return [Hash] File options.
+    def file_options(options = {})
+      file_path = config_file_path(options)
+      if file_path
+        load_from_file(file_path)
+      elsif rails_defined && File.exists?(rails_config_file_path)
+        load_from_file(rails_config_file_path)
+      else
+        {}
+      end
+    end
+
+    # @return [Boolean] Necessary Rails variables defined.
+    def rails_defined
+      defined?(Rails) && defined?(Rails.root) && defined?(Rails.env)
+    end
+
+    # Load options from YAML file depending on existence of Rails
+    # and possible development stage defined.
+    def load_from_file(file_path)
+      require "erb"
+      opts = YAML.load(ERB.new(File.read(file_path)).result) || {}
+      opts = opts[Rails.env] if rails_defined && opts.key?(Rails.env)
+      symbolize_keys(opts)
+    end
+
+    # @return [String] Configuration path found in environment or YAML file.
+    def config_file_path(options)
+      options[:config_file] || ENV["DYNAMO_DB_SESSION_CONFIG_FILE"]
+    end
+
+    # @return [String] Rails configuraton path to YAML file default.
+    def rails_config_file_path
+      File.join(Rails.root, "config", "sessionstore/dynamodb.yml")
+    end
+
+    # Set accessible attributes after merged options.
+    def set_attributes(options)
+      @options.keys.each do |opt_name|
+        instance_variable_set("@#{opt_name}", options[opt_name])
+      end
+    end
+
+    # @return [Hash] Hash with all symbolized keys.
+    def symbolize_keys(options)
+      options.inject({}) do |opts, (opt_name, opt_value)|
+        opts[opt_name.to_sym] = opt_value
+        opts
+      end
+    end
+
+    # @return [Hash] Client subset options hash.
+    def client_subset(options = {})
+      client_keys = [:aws_secret_key, :aws_region, :aws_access_key, :api_version]
+      options.inject({}) do |opts, (opt_name, opt_value)|
+        opts[opt_name.to_sym] = opt_value if client_keys.include?(opt_name.to_sym)
+        opts
+      end
+    end
+  end
+end