rack-state 0.0.1

data/README.rdoc

@@ -0,0 +1,187 @@
+= Rack::State -- Secure & Modular State Management
+
+Rack::State is middleware that securely stores and manages object state.
+
+Applications use the Manager API to _set_, _get_, and _delete_ state of
+any object that requires persistence in a stateless environment.
+
+== The Core Components
+
+* Rack::State
+* Rack::State::Manager
+* Rack::State::Store
+
+== Diagram of All the Players
+
+  State (middleware)
+  |
+  +--> Manager (env[rack.state.KEY]) <-- API (get/set/delete object)
+       |
+       +--> client-side: cookie (KEY = token)
+       |
+       +--> server-side: Store (token, object)
+                         |
+                         +--> Memory
+                         +--> File
+                         +--> Postgres
+                         +--> PreparedPostgres
+
+The *KEY* and Store *adapter* may be set for each instance of middleware.
+
+== Design & Motivation
+
+=== Primary goal
+
+State management for multiple objects with independent control of the
+visibility, security, and storage of each object's state.
+
+=== But we have Rack::Session
+
+Rack::Session provides state management, but does so using only a single
+SessionHash, which is statically located in Rack's environment. The drawback is
+the lack of fine-grained control, efficiency, and multiple instances. This
+single hash-like object is always available to the entire application whether it
+is needed or not.
+
+I attempted to modify and bend Rack::Session to meet my design goal, but there
+seemed to be no clean and easy solution. Rack::State was born...
+
+=== Use Case
+
+An application has the following areas that require data persistence:
+
+1. site-wide personalization -- <i>real name, theme, etc.</i>
+2. blog activity tracking -- <i>articles read, favorites, shares</i>
+3. secure store -- <i>TLS for entire store, shopping cart, and checkout</i>
+
+Three instances of Rack::State can be used. The domain, path, expiration, token
+security (i.e., HttpOnly & Secure cookie flags) and storage backend can be set
+appropriately for each area.
+
+For example, site-wide personalization may set path to "/" with a long
+expiration, but the secure store could use "/store" with expiration at end of
+session and set the HttpOnly and Secure flags as well. Additionally, site-wide
+personalization and blog activity tracking states could be stored in the
+database while the secure store state could be saved in files.
+
+== Usage Examples
+
+=== Manage a single state in memory
+
+Here's a simple rackup (config.ru) file that uses the Rack::State middleware
+with default options.
+
+  require 'rack'
+  require 'rack/state'
+
+  use Rack::State
+
+  run MyApp
+
+The application can access the State::Manager via the environment. The following
+code sets up Rack::State to function similarly to Rack::Session.
+
+  def session
+    env['rack.state.token'].get or env['rack.state.token'].set Hash.new
+  end
+
+  session['username']
+
+
+=== Multiple state management with different storage adapters
+
+Below, the _store_ state will use the default Memory store and _blog_ will store
+state in files under "tmp/sessions" in the project's root.  Additionally, if
+"/store" requires encryption it is wise to secure the token.
+
+  use Rack::State, key: 'store', path: '/store', secure: true
+  use Rack::State, key: 'blog',  path: '/blog', max_age: 60*60*24*30,
+    store: Rack::State::Store::File.new('tmp/sessions')
+
+Then on the application side you may have some helper methods like this:
+
+  def store
+    env['rack.state.store']
+  end
+
+  store.set SecureStore.new # start shopping session
+  store.get.cart.add :item7 # buy some stuff
+  store.delete              # remove from client and server after checkout
+
+  def blog
+    env['rack.state.blog'].get or env['rack.state.blog'].set BlogTracker.new
+  end
+
+  blog.viewed << :article9
+  blog.shared << :article5
+
+
+=== Choose a specific storage adapter depending on the environment
+
+Here we use the Postgres store for production, otherwise use the default Memory
+store for development and testing.
+
+  if ENV['RACK_ENV'] == 'production'
+    DB = PG::Connection.new
+    use Rack::State, store: Rack::State::Store::Postgres.new(DB)
+  else
+    use Rack::State
+  end
+
+
+== Install, Test & Contribute
+
+Install the gem:
+
+  $ sudo gem install rack-state
+
+Or clone the project:
+
+  TODO
+
+State is tested with Christian Neukirchen's awesome test framework,
+{Bacon}[https://github.com/chneukirchen/bacon].
+Get some bacon and start cooking:
+
+  $ sudo gem install bacon
+
+Run the entire test suite from the project's root:
+
+  $ bacon -a
+
+To test a specific component, such as a new storage adapter, run:
+
+  $ bacon -Ilib spec/spec_COMPONENT.rb
+
+After you fix a bug or develop a storage adapter, submit your code and tests.
+
+  TODO
+
+== Compatibility
+
+Rack::State was developed and tested on
+OpenBSD[http://www.openbsd.org] 5.3
+using Ruby[https://www.ruby-lang.org] 1.9.3
+and Rack[https://github.com/rack/rack] 1.5.
+
+== History
+
+* September 5, 2013: Initial design, development and testing.
+
+* September 22, 2013: First public release 0.0.1.
+
+== Copyright
+
+Copyright (c) 2013, Clint Pachl <http://clint.pachl.us>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

data/lib/rack/state.rb

@@ -0,0 +1,392 @@
+# :title: Rack::State -- Secure & Modular State Management
+# :main:  README.rdoc
+
+require 'securerandom'
+
+module Rack
+
+  #
+  # == The Middleware Interface
+  #
+  # Stores and manages the state of a single object on the server and sets the
+  # state token in a client cookie. Multiple State instances may be utilized to
+  # manage multiple states, each with different storage adapters and options.
+  #
+  # State initializes Manager, which contains the API.
+  #
+  class State
+
+    VERSION = '0.0.1'
+
+    #
+    # == Middleware Options
+    #
+    # [store]
+    #   Instance of the storage adapter. See Rack::State::Store for available
+    #   adapters. The default is Store::Memory.
+    # [key]
+    #   Client cookie name and Rack environment key suffix. For example, the key
+    #   "token" sets a cookie named "token" and the environment key to
+    #   "rack.state.token". Therefore, the application can access the
+    #   State::Manager instance at <tt>env["rack.state.token"]</tt>.
+    #   The default is "token".
+    # [domain, path, max_age, expires, secure, httponly]
+    #   Standard cookie options supported by Rack. None are set by default;
+    #   therefore, the state will be valid for the session only on the domain
+    #   and path in which it was set and available over unsecured connections.
+    #
+    def initialize(app, options = {})
+      @app = app
+      @options = options
+      @store = options.delete(:store) || Store::Memory.new
+      @key = options.delete(:key) || 'token'
+      @skey = "rack.state.#{@key}"
+    end
+
+    def call(env)
+      token = Request.new(env).cookies.fetch(@key, nil)
+      state = env[@skey] = Manager.new(@store, token, @key, @options)
+      status, headers, body = @app.call(env)
+      resp = Response.new(body, status, headers)
+      state.finish(resp)
+      resp.finish
+    end
+
+    #
+    # == The Application Interface
+    #
+    # Orchestrates the state management of an object. The API is very simple:
+    # you can #get, #set, and #delete an object.
+    #
+    # The application can access Manager via the Rack environment.
+    # See the *key* middleware option in State.new.
+    #
+    class Manager
+
+      #
+      # Instantiated in middleware-land.
+      #
+      # [store]
+      #   Storage instance that implements CRUD methods for storing state.
+      # [token]
+      #   Used to reference the state object in store. The token is stored as 
+      #   the cookie value on the client. If nil, token not set on client.
+      # [key]
+      #   Cookie name.
+      # [options]
+      #   Cookie options.
+      #
+      def initialize(store, token, key, options) #:nodoc:
+        @object = nil
+        @key = key
+        @store = store
+        @token = token
+        @options = options
+      end
+
+      # Return object if it exists in store, otherwise nil.
+      def get
+        object
+      end
+
+      # Save object in store and set associated token on client.
+      def set(object)
+        @object = object
+      end
+
+      # Remove object from store and delete associated token on client.
+      def delete
+        set false
+      end
+
+      #
+      # Create, update, or delete the state in the store and set or delete the 
+      # client's cookie accordingly.
+      #
+      # Note: middleware method not intended for application use.
+      #
+      # [resp] Rack::Response used to set and delete the client cookie.
+      #
+      def finish(resp) #:nodoc:
+        if token? && object?
+          update_state(resp)
+        elsif object?
+          create_state(resp)
+        elsif token? && deleted?
+          delete_state(resp)
+        end
+      end
+
+      private
+
+      attr_reader :store, :key, :options
+
+      def token(generate = false)
+        @token = generate ? SecureRandom.urlsafe_base64 : @token
+      end
+
+      def token?
+        ! @token.nil?
+      end
+
+      # Load object from store on initial access only.
+      def object
+        @object ||= token? ? store.read(token) : nil
+      end
+
+      # Returns true if object has been set directly or loaded from store.
+      def object?
+        !!@object
+      end
+
+      # The object has been marked for deletion.
+      def deleted?
+        @object == false
+      end
+
+      def create_state(resp)
+        store.create(token(true), object)
+        resp.set_cookie(key, options.merge(value: token))
+      rescue KeyError # token exists
+        retry
+      end
+
+      def update_state(resp)
+        store.update(token, object)
+        resp.set_cookie(key, options.merge(value: token)) # update timestamp
+      rescue KeyError # token nonexistent
+        create_state(resp)
+      end
+
+      def delete_state(resp)
+        store.delete(token)
+        resp.delete_cookie(key, options)
+      end
+    end
+
+    #
+    # Storage adapters are used by Manager for storing object state.
+    #
+    # == Available Adapters
+    #
+    # * File
+    # * Memory
+    # * Postgres
+    # * PreparedPostgres
+    #
+    # == Adapters Must Implement CRUD Methods
+    #
+    # [create(token, object)]
+    #   Create +object+ at +token+. Raise KeyError if token exists.
+    #
+    # [read(token)]
+    #   Read +object+ at +token+. Return nil if token is nonexistent.
+    #
+    # [update(token, object)]
+    #   Update +object+ at +token+. Raise KeyError if token is nonexistent.
+    #
+    # [delete(token)]
+    #   Delete +object+ at +token+. Return nil if token is nonexistent.
+    #
+    # == Adapters Must Conform to Specification
+    #
+    # All adapters must pass the specifications in spec/state_store.rb to
+    # guarantee compatibility with Manager.
+    #
+    module Store
+
+      #
+      # The default state storage adapter: a slight subclassing of Hash.
+      # Memory is only suitable for development and single process apps.
+      #
+      class Memory < Hash
+        def create(token, object)
+          raise KeyError if has_key? token
+          store(token, object)
+        end
+
+        def read(token)
+          fetch(token, nil)
+        end
+
+        def update(token, object)
+          raise KeyError unless has_key? token
+          store(token, object)
+        end
+      end
+
+      #
+      # File-based state storage adapter. The state token is the file name 
+      # and the state object is Marshaled and stored in the file.
+      #
+      class File
+
+        require 'tmpdir'
+
+        #
+        # [directory]
+        #   Storage directory for state files. It must exist and have proper
+        #   permissions.
+        #
+        def initialize(directory = Dir.tmpdir)
+          @directory = directory
+        end
+
+        def create(token, object)
+          flags = ::File::WRONLY|::File::CREAT|::File::EXCL
+
+          ::File.open(state_file(token), flags, 0600) do |f|
+            f.flock ::File::LOCK_EX
+            f.write ::Marshal.dump(object)
+          end
+        rescue Errno::EEXIST
+          raise KeyError
+        end
+
+        def read(token)
+          ::File.open(state_file(token)) do |f|
+            f.flock ::File::LOCK_SH
+            ::Marshal.load(f) if f.size > 0
+          end rescue nil
+        end
+
+        def update(token, object)
+          flags = ::File::WRONLY|::File::TRUNC
+
+          ::File.open(state_file(token), flags) do |f|
+            f.flock ::File::LOCK_EX
+            f.write ::Marshal.dump(object)
+          end
+        rescue Errno::ENOENT
+          raise KeyError
+        end
+
+        def delete(token)
+          ::File.unlink state_file(token) rescue nil
+        end
+
+        private
+
+        def state_file(token)
+          ::File.join(@directory, token)
+        end
+      end
+
+      #
+      # Postgres table-based state storage adapter.
+      #
+      # The following statement will create the required database table:
+      #
+      #   CREATE UNLOGGED TABLE state (
+      #     token   varchar PRIMARY KEY,
+      #     object  bytea NOT NULL,
+      #     mtime   timestamp DEFAULT current_timestamp
+      #   )
+      #
+      # The _mtime_ timestamp column may be used for implementing state expiry
+      # external to this class. For example, the following statement could be 
+      # piped to psql(1) daily via cron(8):
+      #
+      #   DELETE FROM state WHERE (mtime + interval '30d') < current_timestamp
+      #
+      class Postgres
+
+        # Indicate binary data; the object is stored in binary format.
+        BINARY = 1
+
+        #
+        # [connection]
+        #   Instance of the database connection, e.g., PG::Connection.new
+        # [table]
+        #   Table name where state is stored.
+        #
+        def initialize(connection, table = 'state')
+          @db = connection
+          @table = table
+        end
+
+        def create(token, object)
+          sql = "INSERT INTO #{@table} (token,object) VALUES ($1,$2)"
+          params = [token, {value: ::Marshal.dump(object), format: BINARY}]
+          @db.exec_params(sql, params).clear
+        rescue PG::UniqueViolation
+          raise KeyError
+        end
+
+        def read(token)
+          sql = "SELECT object FROM #{@table} WHERE token = $1"
+          @db.exec_params(sql, [token], BINARY) do |result|
+            ::Marshal.load result.getvalue(0,0)
+          end rescue nil
+        end
+
+        def update(token, object)
+          sql = "UPDATE #{@table} SET object = $2 WHERE token = $1"
+          params = [token, {value: ::Marshal.dump(object), format: BINARY}]
+          @db.exec_params(sql, params) do |result|
+            raise KeyError if result.cmd_tuples == 0
+          end
+        end
+
+        def delete(token)
+          sql = "DELETE FROM #{@table} WHERE token = $1"
+          @db.exec_params(sql, [token]).clear
+        end
+      end
+
+      #
+      # Postgres table-based state storage adapter using prepared statements.
+      # Because accessing state is a highly repetitive activity, prepared
+      # statements may offer some optimization.
+      #
+      # See Postgres for details.
+      #
+      class PreparedPostgres
+        BINARY = 1
+
+        def initialize(connection, table = 'state')
+          @db = connection
+          begin
+            @db.prepare 'create_state',
+              "INSERT INTO #{table} (token,object) VALUES ($1,$2)"
+            @db.prepare 'read_state',
+              "SELECT object FROM #{table} WHERE token=$1"
+            @db.prepare 'update_state',
+              "UPDATE #{table} SET object=$2, mtime=NOW() WHERE token=$1"
+            @db.prepare 'delete_state',
+              "DELETE FROM #{table} WHERE token=$1"
+          rescue PG::DuplicatePstatement
+          end
+        end
+
+        def create(token, object)
+          @db.exec_prepared('create_state', params(token, object)).clear
+        rescue PG::UniqueViolation
+          raise KeyError
+        end
+
+        def read(token)
+          @db.exec_prepared('read_state', params(token), BINARY) do |result|
+            ::Marshal.load result.getvalue(0,0)
+          end rescue nil
+        end
+
+        def update(token, object)
+          @db.exec_prepared('update_state', params(token, object)) do |result|
+            raise KeyError if result.cmd_tuples == 0
+          end
+        end
+
+        def delete(token)
+          @db.exec_prepared('delete_state', params(token)).clear
+        end
+
+        private
+
+        def params(token, obj = nil)
+          obj ? [token, {value: ::Marshal.dump(obj), format:BINARY}] : [token]
+        end
+      end
+    end
+  end
+end

data/spec/spec_state.rb

@@ -0,0 +1,174 @@
+require 'rack/state'
+require 'rack/mock'
+
+module StateMiddlewareHelpers #:nodoc:
+  def valid_token
+    lambda { |obj|
+      name = obj.split('=')[0]
+      obj.match /^#{name}=[^;]{22,}$/
+    }
+  end
+
+  def expired_token
+    lambda { |obj|
+      name = obj.split('=')[0]
+      obj.match /^#{name}=; max-age=0; expires=Thu, 01 Jan 1970/
+    }
+  end
+
+  def get_state(key, token)
+    @req.get("/get_state?key=#{key}", {'HTTP_COOKIE' => token})['Set-Cookie']
+  end
+
+  def set_state(key, token = nil)
+    cookie = token ? {'HTTP_COOKIE' => token} : {}
+    @req.get("/set_state?key=#{key}", cookie)['Set-Cookie']
+  end
+
+  def del_state(key, token)
+    @req.get("/del_state?key=#{key}", {'HTTP_COOKIE' => token})['Set-Cookie']
+  end
+
+  def mock_app
+    Proc.new do |env|
+      req = Rack::Request.new(env)
+      key = req.params['key'] || 'token'
+      skey = 'rack.state.' + key
+      data = nil
+
+      case req.path
+      when '/get_state'
+        data = env[skey].get
+      when '/set_state'
+        data = env[skey].set(key + 'data')
+      when '/del_state'
+        env[skey].delete
+      end
+
+      Rack::Response.new(data.to_s).to_a
+    end
+  end
+end
+
+describe Rack::State do
+
+  describe 'Default Options' do
+    extend StateMiddlewareHelpers
+
+    before do
+      @key = 'token' # default key name
+      @req = Rack::MockRequest.new(Rack::State.new(mock_app))
+    end
+
+    should 'not return token if state object not accessed' do
+      @req.get('/')['Set-Cookie'].should.be.nil
+    end
+
+    should 'return token when setting state' do
+      set_state(@key).should.be.a valid_token
+    end
+
+    should 'return previous token' do
+      token1 = set_state(@key)
+      token2 = get_state(@key, token1)
+      token1.should.equal token2
+    end
+
+    should 'not return token after deleting state' do
+      token1 = set_state(@key)
+      token2 = del_state(@key, token1)
+      token3 = get_state(@key, token1)
+      token1.should.be.a valid_token
+      token2.should.be.an expired_token
+      token3.should.be.nil
+    end
+
+    should 'return no token when getting state with nonexistent token' do
+      get_state(@key, "#{@key}=nonexistent").should.be.nil
+    end
+
+    should 'return new token when setting state with nonexistent token' do
+      token = set_state(@key, "#{@key}=nonexistent")
+      token.should.not.equal "#{@key}=nonexistent"
+      token.should.be.a valid_token
+    end
+
+    should 'expire token when deleting state with nonexistent token' do
+      token = del_state(@key, "#{@key}=nonexistent")
+      token.should.not.equal "#{@key}=nonexistent"
+      token.should.be.an expired_token
+    end
+  end
+
+  describe 'Two Instances Each With Different Stores' do
+    require 'tmpdir'
+    extend StateMiddlewareHelpers
+
+    before do
+      fstore = Rack::State::Store::File.new(@dir = Dir.mktmpdir)
+      mstore = Rack::State::Store::Memory.new
+      app = Rack::State.new(mock_app, key:'f', store:fstore)
+      app = Rack::State.new(app,      key:'m', store:mstore)
+      @req = Rack::MockRequest.new(app)
+    end
+
+    after do
+      FileUtils.remove_dir @dir
+    end
+
+    should 'return persistent data via response body on subsequent requests' do
+      fres = @req.get('/set_state?key=f')
+      mres = @req.get('/set_state?key=m')
+      fres.body.should.equal 'fdata'
+      mres.body.should.equal 'mdata'
+      fres = @req.get('/get_state?key=f', 'HTTP_COOKIE' => fres['Set-Cookie'])
+      mres = @req.get('/get_state?key=m', 'HTTP_COOKIE' => mres['Set-Cookie'])
+      fres.body.should.equal 'fdata'
+      mres.body.should.equal 'mdata'
+      fres = @req.get('/del_state?key=f', 'HTTP_COOKIE' => fres['Set-Cookie'])
+      mres = @req.get('/del_state?key=m', 'HTTP_COOKIE' => mres['Set-Cookie'])
+      fres.body.should.be.empty
+      mres.body.should.be.empty
+    end
+
+    should 'return tokens when setting state for two different keys' do
+      ftoken = set_state('f')
+      mtoken = set_state('m')
+      ftoken.should.be.a valid_token
+      mtoken.should.be.a valid_token
+      ftoken.should.not.equal mtoken
+    end
+
+    should 'set states and delete one at a time verifing no token returned' do
+      ftoken = set_state('f')
+      mtoken = set_state('m')
+      del_state('f', ftoken).should.be.an expired_token
+      get_state('f', ftoken).should.be.nil
+      get_state('m', mtoken).should.be.a valid_token
+      del_state('m', mtoken).should.be.an expired_token
+      get_state('m', mtoken).should.be.nil
+    end
+
+    should 'return previous token for each state' do
+      ft1 = set_state('f')
+      mt1 = set_state('m')
+      ft2 = get_state('f', ft1)
+      mt2 = get_state('m', mt1)
+      ft1.should.equal ft2
+      mt1.should.equal mt2
+      ft2.should.not.equal mt2
+    end
+
+    should 'return new tokens when setting states with nonexistent tokens' do
+      ftoken= 'f=nonexistent'
+      mtoken= 'm=nonexistent'
+      ft = set_state('f', ftoken)
+      mt = set_state('m', mtoken)
+      ft.should.not.equal ftoken
+      ft.should.be.a valid_token
+      mt.should.not.equal mtoken
+      mt.should.be.a valid_token
+      mt.should.not.equal ft
+    end
+  end
+end

data/spec/spec_state_store_file.rb

@@ -0,0 +1,23 @@
+require_relative 'state_store'
+require 'tmpdir'
+
+describe Rack::State::Store::File do
+
+  before do
+    @dir = Dir.mktmpdir
+    @store = Rack::State::Store::File.new(@dir)
+  end
+
+  after do
+    FileUtils.remove_dir @dir
+  end
+
+  behaves_like Rack::State::Store
+
+  it 'creates and deletes token file when creating and deleting state' do
+    @store.create(@token, @data)
+    File.should.exist File.join(@dir, @token)
+    @store.delete(@token)
+    File.should.not.exist File.join(@dir, @token)
+  end
+end

data/spec/spec_state_store_memory.rb

@@ -0,0 +1,10 @@
+require_relative 'state_store'
+
+describe Rack::State::Store::Memory do
+
+  before do
+    @store = Rack::State::Store::Memory.new
+  end
+
+  behaves_like Rack::State::Store
+end

data/spec/spec_state_store_postgres.rb

@@ -0,0 +1,43 @@
+#
+# This is more of an integration test that requires a proper environment to run.
+# Therefore, these specs are encapsulated by exception handling to contain a
+# potential explosion!
+#
+# To run these specs, simply:
+# 1. Set appropriate environment variables: PGDATABASE, PGHOST, PGPORT, PGUSER
+# 2. Specify your database password in ~/.pgpass
+#
+
+begin
+  require 'pg'
+  require_relative 'state_store'
+
+  PGTable = 'state'
+  PGDB = PG::Connection.new
+  PGDB.exec 'SET client_min_messages TO WARNING'
+  PGDB.exec <<-SQL
+    CREATE TEMPORARY TABLE #{PGTable} (
+      token   varchar PRIMARY KEY,
+      object  bytea NOT NULL,
+      mtime   timestamp DEFAULT current_timestamp
+    )
+  SQL
+
+  describe Rack::State::Store::Postgres do
+    before { @store = Rack::State::Store::Postgres.new(PGDB, PGTable) }
+    after { PGDB.exec "TRUNCATE TABLE #{PGTable}" }
+    behaves_like Rack::State::Store
+  end
+
+  describe Rack::State::Store::PreparedPostgres do
+    before { @store = Rack::State::Store::PreparedPostgres.new(PGDB, PGTable) }
+    after { PGDB.exec "TRUNCATE TABLE #{PGTable}" }
+    behaves_like Rack::State::Store
+  end
+
+  PGDB.close
+rescue LoadError
+  $stderr.puts 'Not running Postgres specs: cannot load the "pg" library.'
+rescue PG::ConnectionBad
+  $stderr.puts 'Not running Postgres specs: cannot connect to the database.'
+end

data/spec/state_store.rb

@@ -0,0 +1,36 @@
+require 'rack/state'
+
+#
+# All Rack::State::Store adapters must include these specifications.
+# Passing these specs guarantees compatibility with StateObject.
+#
+shared Rack::State::Store do
+  @token = 'a-valid-token-name'
+  @data  = 'example state data'
+
+  it 'returns nil when reading state for a nonexistent token' do
+    @store.read(@token).should.be.nil
+  end
+
+  it 'returns nil when deleting state for a nonexistent token' do
+    @store.delete(@token).should.be.nil
+  end
+
+  it 'raises KeyError when updating state for nonexistent token' do
+    should.raise(KeyError) { @store.update(@token, @data) }
+  end
+
+  it 'raises KeyError when creating state for existing token' do
+    should.not.raise(KeyError) { @store.create(@token, @data) }
+    should.    raise(KeyError) { @store.create(@token, @data) }
+  end
+
+  it 'executes the standard CRUD process as expected' do
+    should.not.raise(KeyError) { @store.create(@token, @data) }
+    @store.read(@token).should.equal @data
+    should.not.raise(KeyError) { @store.update(@token, @data+'more') }
+    @store.read(@token).should.equal @data+'more'
+    @store.delete(@token)
+    @store.read(@token).should.be.nil
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: rack-state
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Clint Pachl
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-09-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: bacon
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: ! 'Rack::State is middleware that securely stores and manages object
+  state.
+
+
+  It is similar to Rack::Session, but provides state management for multiple
+
+  objects with independent control of the visibility, security, and storage of
+
+  each object''s state.
+
+
+  Applications use the Manager API to _set_, _get_, and _delete_ state of
+
+  any object that requires persistence in a stateless environment.
+
+'
+email: pachl@ecentryx.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.rdoc
+- lib/rack/state.rb
+- spec/state_store.rb
+- spec/spec_state.rb
+- spec/spec_state_store_file.rb
+- spec/spec_state_store_memory.rb
+- spec/spec_state_store_postgres.rb
+homepage: https://rubygems.org/gems/rack-state
+licenses:
+- ISC
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Secure & Modular State Management
+test_files:
+- spec/spec_state.rb
+- spec/spec_state_store_file.rb
+- spec/spec_state_store_memory.rb
+- spec/spec_state_store_postgres.rb