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 all Rack based frameworks. For Rails applications, use the aws-sdk-rails gem.

Installation

For Rack 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 configuration option that is used for the older version.

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.

For more developer information, see the Full API documentation.

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 directly by Ruby code or through environment variables.

The full set of options along with defaults can be found in the Configuration class documentation.

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'

Garbage Collection

You may want to delete old sessions from your session table. You can use the DynamoDB Time to Live (TTL) feature on the expire_at attribute to automatically delete expired items.

If you want to take other attributes into consideration for deletion, you could instead use the GarbageCollection class. 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.

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.