rack-session-xfile 0.10.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 64d96bd5bb35fd04da4c0c2b7cd7f697f367617f
+  data.tar.gz: 81f1f785803a8447c899da0441fff97dc4d81766
+SHA512:
+  metadata.gz: 2ea0309035a48c736404d70b5669056b18735a8c578da6badb5296d058a53aa54279721ff74d485d492f9f0fd07481db6a2cb584bc159c78c53183f6c4fa76a6
+  data.tar.gz: ee252d4880ff8e137c9718395d391b1a639d89ba24c1c314c3cc8b3bb51f592bf64c76dd7239451f9c584b1fb138370a3ab9957e6325e46a5a18da661b4ffe0b

data/README.rdoc

@@ -0,0 +1,164 @@
+= Rack::Session::XFile --- Atomic File-Based Session Management
+
+== Design and implementation
+
+XFile leverages mutex and file locking to guarantee atomic updates to session
+data. Exclusive create locks are also used to allocate the resource file when
+generating a new session id (SID). This eliminates race conditions and ensures
+data consistency for multi-threaded and multi-process applications.
+
+File-based sessions are the fastest and simplest persistent-storage option. To
+maximize performance, store session files on an SSD, an in-memory filesystem, or
+a disk-based filesystem with performant caching, such as ZFS. Session files are
+distributed across 62 directories to minimize access time on some filesystems.
+
+=== Goals
+
+1. *Simple*:     We already have a working filesystem; no configuration.
+2. *Reliable*:   We are using a time-tested filesystem and file lock mechanism.
+3. *Secure*:     Session data is always stored on the server under our control.
+4. *Performant*: Session access is very responsive with memory cache or SSDs.
+5. *Persistent*: Sessions persist regardless of application crashes or restarts.
+
+
+== How session data is stored and referenced
+
+Session data is marshaled and written to the persistent file on the server
+associated with the SID. The client cookie (set by the +key+ option) is then
+assigned the SID.
+
+== Request filtering
+
+The request filter uses Rack's +skip+ option to completely bypass session
+processing for matching requests. When a request matches the filter, a
+temporary, in-memory session hash is created instead. The filesystem is never
+accessed.
+
+User agents can be filtered by setting the +user_agent_filter+ option with a
+regular expression.
+
+This feature was originally implemented to avoid processing sessions for robots.
+Many sources state that one-third to two-thirds of all web traffic is from bots.
+However, most robots don't store or forward cookies. Consequently, processing
+sessions for robots wastes resources and pollutes the session store with
+needless "one-time" sessions.
+
+By default, SIDs are validated by the request filtering system to detect SID
+tampering, which could lead to directory traversal exploits. Requests with
+invalid SIDs are skipped.
+
+== Purging expired session files
+
+The XFile session manager does not concern itself with purging expired sessions.
+This task is much better suited for an out-of-band process, such as cron.
+
+For example, run an hourly cron job that executes +find+ and deletes expired
+session files. For instance, if the +expire_after+ option is set to 30 days,
+then delete session files with last-modification times greater than 30 days.
+
+Additionally, files with modification times past an _X_ amount of time but less
+than expiration could be truncated to free up disk space. This effectively
+returns an empty session, but will preserve session IDs previously issued to
+clients. SID preservation may be critical if these session IDs are referenced by
+another backend system or service, such as an analytics system.
+
+=== Example cron job to purge sessions older than 30 days
+
+  0  *  *  *  *  find /tmp/xfile-sessions -type f -mtime +30 -exec rm -- {} +
+
+=== Example cron job to clear sessions older than 15 days while maintaining SIDs
+
+  0  0  *  *  *  find /tmp/xfile-sessions -type f -mtime +15 -exec cp /dev/null {} \;
+
+*Caveat*: There is potential for a race condition anytime a process modifies
+XFile sessions without utilizing file locks. However, in this case with cron,
+the potential is very small considering the session files to be deleted haven't
+been accessed in a relatively long time and probably won't be any time soon.
+
+
+== Usage Examples
+
+=== Basic usage with sessions stored under the application directory
+
+  require 'rack-session-xfile'
+
+  use Rack::Session::XFile,
+    session_dir: File.join(settings.root, 'tmp/sessions'),
+    expire_after: 60*60*24*30,
+    secure: true,
+    key: 'sid'
+
+By default, sessions are stored in the directory named _xfile-sessions_ under
+the operating system's temporary file path.
+
+=== Bypass session processing for robots
+
+  require 'rack-session-xfile'
+
+  use Rack::Session::XFile,
+    user_agent_filter: /(bot|crawler|spider)/i
+
+A more extensive filter could include: wget|archive|search|seo|libwww|index.
+
+== Install, test & contribute
+
+* Install as a system-wide gem.
+
+     $ sudo gem install rack-session-xfile
+
+* Install as a user-local gem.
+
+     $ gem install rack-session-xfile --user-install
+
+* Clone the Mercurial repository.
+
+     $ hg clone https://bitbucket.org/pachl/rack-session-xfile
+
+XFile is tested with Christian Neukirchen's awesome test framework,
+{Bacon}[https://github.com/chneukirchen/bacon]. First, get bacon. Then crank up
+the heat on the entire test suite. Let's get cooking!
+
+  $ sudo gem install bacon
+  $ cd rack-session-xfile
+  $ bacon -a
+
+If you find or fix a bug, please send reports and patches to pachl@ecentryx.com
+or open an issue on the bug tracker.
+
+
+== Links
+
+Homepage      :: http://ecentryx.com/gems/rack-session-xfile
+Ruby Gem      :: https://rubygems.org/gems/rack-session-xfile
+Source Code   :: https://bitbucket.org/pachl/rack-session-xfile/src
+Bug Tracker   :: https://bitbucket.org/pachl/rack-session-xfile/issues
+
+== Compatibility
+
+Rack::Session::XFile was developed and tested on
+OpenBSD[http://www.openbsd.org] 5.6
+using Ruby[https://www.ruby-lang.org] 2.1.2
+and Rack[https://github.com/rack/rack] 1.6.0.
+
+== History
+
+1. 2015-01-29, v0.10.0: First public release
+   * XFile ran in production for more than a year before public release.
+
+== License
+
+({ISC License}[http://opensource.org/licenses/ISC])
+
+Copyright (c) 2015, Clint Pachl <pachl@ecentryx.com>
+
+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/Rakefile

@@ -0,0 +1,22 @@
+verbose false
+
+require 'rubygems/package_task'
+Gem::PackageTask.new(eval File.read('xfile.gemspec')) {}
+
+require 'rdoc/task'
+RDoc::Task.new do |rdoc|
+  rdoc.main = 'README.rdoc'
+  rdoc.rdoc_files.include('README.rdoc', 'lib/**/*.rb')
+end
+
+desc 'Upload RDoc files to public server'
+task :uprdoc => :rdoc do
+  dir = '/var/www/sites/ecentryx.com/public/gems/rack-session-xfile/'
+  host = 'hercules'
+  sh "cd ./html && pax -w . | ssh #{host} 'cd #{dir} && rm -rf * && pax -r'"
+end
+
+desc 'Run all specs'
+task :spec do
+  sh 'bacon -aq'
+end

data/lib/rack/session/xfile.rb

@@ -0,0 +1,193 @@
+require 'rack/session/abstract/id'
+require 'tmpdir'
+
+module Rack
+  module Session
+
+    class XFile < Abstract::ID
+
+      VERSION = '0.10.1'
+
+      File = ::File # override Rack::File
+
+      SIDCharacters = [*(0..9), *(:a..:z), *(:A..:Z)].map!(&:to_s)
+
+      Abstract::ID::DEFAULT_OPTIONS.merge! \
+        session_dir: File.join(Dir.tmpdir, 'xfile-sessions'),
+        user_agent_filter: nil,
+        key: 'xid'
+
+      def initialize(app, options = {})
+        super
+        @mutex       = Mutex.new
+        @session_dir = @default_options[:session_dir]
+        @ua_filter   = @default_options[:user_agent_filter]
+        @sid_nbytes  = @default_options[:sidbits] / 8
+        setup_directories
+        check_permissions
+      end
+
+      def set_session(env, sid, session, options)
+        critical_section(env) do
+          write_session(sid, session)
+        end
+      end
+
+      def get_session(env, sid)
+        critical_section(env) do
+          return [nil, {}] if filter_request(env, sid)
+
+          unless sid and session = read_session(sid)
+            sid, session = generate_sid, {}
+          end
+          [sid, session]
+        end
+      end
+  
+      def destroy_session(env, sid, options)
+        critical_section(env) do
+          File.unlink(session_file(sid)) rescue nil
+          generate_sid unless options[:drop]
+        end
+      end
+
+      def session_count
+        Dir[File.join(@session_dir, '?', '*')].count
+      end
+
+      private
+
+      #
+      # Provide thread-safety for critical sections.
+      #--
+      # Some systems do not implement, or implement correctly, advisory file
+      # locking for threads; therefore a mutex lock must encompass file locks.
+      #
+      def critical_section(env)
+        @mutex.lock if env['rack.multithread']
+        yield
+      ensure
+        @mutex.unlock if @mutex.locked?
+      end
+ 
+      #
+      # Atomically generate a unique session ID and allocate the resource file.
+      # Returns the session ID.
+      # --
+      # NOTE
+      # The sid is also a filename. Only SIDCharacters are allowed in the sid.
+      # If +super+ is called it returns a HEX sid, which is a subset.
+      #
+      def generate_sid
+        sid = SecureRandom.urlsafe_base64(@sid_nbytes) rescue super
+        sid.tr!('_-', SIDCharacters.sample(2).join)
+        File.open(session_file(sid), File::WRONLY|File::CREAT|File::EXCL).close
+        sid
+      rescue Errno::EEXIST
+        retry
+      end
+
+      #
+      # Read session from file using a shared lock.
+      #
+      def read_session(sid)
+        File.open(session_file(sid)) do |f|
+          f.flock(File::LOCK_SH)
+          begin
+            f.size == 0 ? {} : Marshal.load(f)
+          rescue ArgumentError, TypeError => e
+            warn "#{self.class} PATH=#{session_file(sid)}: #{e.message}"
+            {}
+          end
+        end
+      rescue Errno::ENOENT
+      end
+
+      #
+      # Write session to file using an exclusive lock.
+      #
+      def write_session(sid, session)
+        File.open(session_file(sid), 'r+') do |f|
+          f.flock(File::LOCK_EX)
+          f.write(Marshal.dump(session))
+          f.flush
+          f.truncate(f.pos)
+        end
+        sid
+      rescue => e
+        warn "#{self.class} cannot set session: #{e.message}"
+        false
+      end
+
+      #
+      # Skip session processing if the request matches a filter.
+      #
+      # == User agent filter
+      # User agents that do not utilize sessions, such as bots, may be filtered.
+      #
+      # == SID filter
+      # The +sid+ is provided by untrusted clients. A tampered sid could result
+      # in directory traversal, pathname, or guessing exploits. Do not waste
+      # resources on a client that sends an invalid sid.
+      #
+      # NOTE: Whitelist all valid sid characters. It's probably not sufficient
+      # to blacklist only potentially dangerous chars such as '..', '/' or '\'.
+      #
+      # sid bit range: 62^10-62^50 (approx. 2^60-2^297)
+      #
+      def filter_request(env, sid)
+        request = nil
+
+        if @ua_filter
+          request = Request.new(env)
+          if request.user_agent =~ @ua_filter
+            return request.session.options[:skip] = true
+          end
+        end
+
+        if sid and sid !~ /^[a-zA-Z0-9]{10,50}$/
+          warn "#{self.class} SID=#{sid}: tampered sid detected."
+          request ||= Request.new(env)
+          request.session.options[:skip] = true
+        end
+      end
+
+      def session_file(sid)
+        File.join @session_dir, sid[0], sid
+      end
+
+      #
+      # Create directory structure for session file distribution.
+      #
+      def setup_directories
+        Dir.mkdir(@session_dir, 0700) unless Dir.exist? @session_dir
+
+        SIDCharacters.each do |char|
+          dir = File.join @session_dir, char
+          Dir.mkdir(dir, 0700) unless Dir.exist? dir
+        end
+      end
+
+      #
+      # Ensure session directory has secure permissions, else raise exception.
+      #
+      def check_permissions
+        perms = File.stat(@session_dir).mode
+        msg   = "#{self.class}: #{@session_dir} sessions directory is "
+
+        raise Errno::EACCES, msg + 'not owned' unless File.owned? @session_dir
+        raise Errno::EACCES, msg + 'not accessible'   if perms & 0700 != 0700
+        raise SecurityError, msg + 'world accessible' if perms & 0007 != 0
+
+        if perms & 070 != 0
+          if File.grpowned? @session_dir
+            warn msg + 'group owned/accessible'
+          else
+            raise SecurityError, msg + 'group accessible'
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/rack-session-xfile.rb

@@ -0,0 +1 @@
+require_relative 'rack/session/xfile'

data/spec/spec_xfile.rb

@@ -0,0 +1,461 @@
+require 'rack/session/xfile'
+require 'rack/mock'
+require 'fileutils'
+require 'tmpdir'
+
+
+describe Rack::Session::XFile do
+
+  def counter number
+   %[{"counter"=>#{number}}]
+  end
+
+  def empty_session
+    '{}'
+  end
+
+  def set_sid id
+    if id =~ TheSession
+      {'HTTP_COOKIE' => id}
+    else
+      {'HTTP_COOKIE' => "#{@session_key}=#{id}"}
+    end
+  end
+
+  # Create an xfile out-of-band in the current session directory.
+  def create_session data = nil
+    app = Rack::Session::XFile.new(nil)
+    sid = app.send(:generate_sid)
+    app.set_session({}, sid, (data || {sid: sid}), {})
+    sid
+  end
+
+  spec_tmp_dir  = Dir.mktmpdir 'xfile-specs-'
+  @session_dir  = Rack::Session::XFile::DEFAULT_OPTIONS[:session_dir].
+                  replace(File.join(spec_tmp_dir, 'xfile-sessions'))
+  @session_key  = Rack::Session::XFile::DEFAULT_OPTIONS[:key]
+  session_bits  = Rack::Session::XFile::DEFAULT_OPTIONS[:sidbits]
+  session_chars = (session_bits / 8 / 3.0 * 4).ceil   # urlsafe_base64 length
+  TheSession    = /^#{@session_key}=[0-9a-zA-Z]{#{session_chars}};/
+
+  # Apps
+
+  incrementor = lambda do |env|
+    env['rack.session']['counter'] ||= 0
+    env['rack.session']['counter'] += 1
+    Rack::Response.new(env['rack.session'].inspect).to_a
+  end
+
+  noop = lambda do |env|
+    Rack::Response.new('noop').to_a
+  end
+
+  read_session_id = lambda do |env|
+    Rack::Response.new(env['rack.session'].id).to_a
+  end
+
+  read_session = lambda do |env|
+    env['rack.session'].send(:load_for_read!)
+    Rack::Response.new(env['rack.session'].inspect).to_a
+  end
+
+  defer_session = lambda do |env|
+    env['rack.session.options'][:defer] = true
+    incrementor.call(env)
+  end
+
+  drop_session = lambda do |env|
+    env['rack.session.options'][:drop] = true
+    incrementor.call(env)
+  end
+
+  renew_session = lambda do |env|
+    env['rack.session.options'][:renew] = true
+    incrementor.call(env)
+  end
+
+
+  before do
+    @warnings = warnings = []
+    Rack::Session::XFile.class_eval do
+      define_method(:warn) { |m| warnings << m }
+    end
+  end
+
+  after do
+    FileUtils.rm_rf(@session_dir)
+    Rack::Session::XFile.class_eval { remove_method :warn }
+  end
+
+  it 'sets default options' do
+    key    = 'secret'
+    dir    = File.join(spec_tmp_dir, 'secret-sessions')
+    filter = /useragent/
+    expire = 3600
+    app    = Rack::Session::XFile.new(incrementor,
+                                      key: key,
+                                      session_dir: dir,
+                                      user_agent_filter: filter,
+                                      expire_after: expire)
+    app.key.should.equal key
+    app.default_options[:key].should.be.nil # deleted in superclass
+    app.default_options[:session_dir].should.equal dir
+    app.default_options[:user_agent_filter].should.equal filter
+    app.default_options[:expire_after].should.equal expire
+    cookie = Rack::MockRequest.new(app).get('/')['Set-Cookie']
+    cookie.should.match /^#{key}=/
+    FileUtils.rm_rf(dir)
+  end
+
+  it 'initializes session directory structure' do
+    app = Rack::Session::XFile.new(noop)
+    dir = app.default_options[:session_dir]
+    Dir[File.join(dir, '**', '*')].count.should == # greedy match
+      Rack::Session::XFile::SIDCharacters.count
+    app.session_count.should.be.zero
+  end
+
+  it 'sets secure permissions when creating session directory' do
+    # NOTE unable to test when no user/group ownership
+    Rack::Session::XFile.new(noop)
+    (File.stat(@session_dir).mode & 077).should.be.zero
+    File.owned?(@session_dir).should.be.true
+  end
+
+  it 'raises exception if session directory is world accessible' do
+    Dir.mkdir(@session_dir, 0707)
+    should.raise(SecurityError) { Rack::Session::XFile.new(noop) }.
+      message.should.include 'world accessible'
+  end
+
+  it 'raises exception if session directory is not user accessible' do
+    Dir.mkdir @session_dir
+    File.chmod 0000, @session_dir
+    should.raise(Errno::EACCES) { Rack::Session::XFile.new(noop) }
+    File.chmod 0100, @session_dir
+    should.raise(Errno::EACCES) { Rack::Session::XFile.new(noop) }
+    File.chmod 0200, @session_dir
+    should.raise(Errno::EACCES) { Rack::Session::XFile.new(noop) }
+    File.chmod 0400, @session_dir
+    should.raise(Errno::EACCES) { Rack::Session::XFile.new(noop) }
+    File.chmod 0700, @session_dir
+    should.not.raise(Errno::EACCES) { Rack::Session::XFile.new(noop) }
+  end
+
+  it 'warns if session directory is group accessible but group owned' do
+    Dir.mkdir(@session_dir, 0770)
+    should.not.raise { Rack::Session::XFile.new(noop) }
+    @warnings.count.should.equal 1
+    @warnings.first.should.include 'group owned/accessible'
+  end
+
+  it 'returns false when setting session if cannot serialize data' do
+    obj = Object.new
+    def obj.singleton() nil end
+    nonserializable_session = { data: obj }
+
+    sid = create_session
+    app = Rack::Session::XFile.new(noop)
+    app.set_session({}, sid, nonserializable_session, {}).should.be.false
+    @warnings.count.should.equal 1
+    @warnings.first.should.match /cannot set session.*singleton can't be dumped/
+  end
+
+  it 'returns false when setting session if sid is nonexistent' do
+    sid = 'nonexistent'
+    app = Rack::Session::XFile.new(noop)
+    app.set_session({}, sid, {}, {}).should.be.false
+    @warnings.count.should.equal 1
+    @warnings.first.should.match /cannot set session.*No such file/
+  end
+
+  it 'creates new xfile session' do
+    app = Rack::Session::XFile.new(incrementor)
+    res = Rack::MockRequest.new(app).get('/')
+    res['Set-Cookie'].should.match TheSession
+    res.body.should.equal counter(1)
+  end
+
+  it 'creates one xfile with six stateful requests' do
+    app = Rack::Session::XFile.new(incrementor)
+    req = Rack::MockRequest.new(app)
+
+    app.session_count.should.be.zero
+    cookie = req.get('/')['Set-Cookie']
+    app.session_count.should.equal 1
+    6.times { req.get('/', set_sid(cookie)) }
+    app.session_count.should.equal 1
+  end
+
+  it 'creates six xfiles with six stateless requests' do
+    app = Rack::Session::XFile.new(incrementor)
+    req = Rack::MockRequest.new(app)
+
+    app.session_count.should.be.zero
+    6.times { req.get('/') }
+    app.session_count.should.equal 6
+  end
+
+  it 'loads session data from existing xfile' do
+    app = Rack::Session::XFile.new(read_session)
+    sid = create_session(data = {'preloaded' => true})  # rack stringifies keys
+    res = Rack::MockRequest.new(app).get('/', set_sid(sid))
+    res.body.should.equal data.inspect
+    app.session_count.should.equal 1
+  end
+
+  it 'merges session data from middleware in front' do
+    app = Rack::Session::XFile.new(incrementor)
+    res = Rack::MockRequest.new(app).get('/', 'rack.session' => {foo: 'bar'})
+    res.body.should.match /counter/
+    res.body.should.match /foo/
+  end
+
+  it 'creates new session when xfile is nonexistent' do
+    app = Rack::Session::XFile.new(read_session)
+    res = Rack::MockRequest.new(app).get('/', set_sid('nonexistent'))
+    res.body.should.equal empty_session
+    res['Set-Cookie'].should.match TheSession
+  end
+
+  it 'creates new session when xfile is empty' do
+    app = Rack::Session::XFile.new(read_session)
+    sid = create_session
+    xfile = app.send(:session_file, sid)
+    File.truncate(xfile, 0)
+    File.size(xfile).should.be.zero
+
+    res = Rack::MockRequest.new(app).get('/', set_sid(sid))
+    res.body.should.equal empty_session
+    res['Set-Cookie'].should.be.nil # because sid already exists
+    app.session_count.should.equal 1
+    File.size(xfile).should.not.be.zero
+  end
+
+  it 'creates new session when xfile is corrupt' do
+    app = Rack::Session::XFile.new(read_session)
+    sid = create_session
+    session_file = app.send(:session_file, sid)
+    session_data = {'key' => 0}
+
+    # return an empty session if marshaled session data is corrupt in any way
+    critical_indices = [0, 3, 6]  # positions in marhaled +session_data+
+    critical_indices.each do |i|  # that are suceptible to corruption
+      corrupt_data = Marshal.dump(session_data).insert(i, 'FUBAR')
+      File.write(session_file, corrupt_data)
+      res = Rack::MockRequest.new(app).get('/', set_sid(sid))
+      res.body.should.equal empty_session
+      res['Set-Cookie'].should.be.nil
+    end
+
+    @warnings.count.should.equal critical_indices.count
+    @warnings[0].should.include 'incompatible marshal file format' 
+    @warnings[1].should.include 'dump format error for symbol' 
+    @warnings[2].should.include 'marshal data too short' 
+  end
+
+  it 'protects against sid encoding and path traversal exploits' do
+    app = Rack::Session::XFile.new(read_session)
+
+    res1 = Rack::MockRequest.new(app).get('/', set_sid('%2e%2e%2f%2e%2e%2f%00'))
+    res1.body.should.equal empty_session
+    res1['Set-Cookie'].should.be.nil
+    app.session_count.should.be.zero
+
+    res2 = Rack::MockRequest.new(app).get('/', set_sid('../../../../etc/passwd'))
+    res2.body.should.equal empty_session
+    res2['Set-Cookie'].should.be.nil
+    app.session_count.should.be.zero
+
+    @warnings.size.should.equal 2
+    @warnings[0].should.include 'tampered sid detected'
+    @warnings[1].should.include 'tampered sid detected'
+  end
+
+  it 'returns new sid cookie with :renew option set' do
+    inc_cntr  = Rack::Session::XFile.new(incrementor)
+    read_sid  = Rack::Session::XFile.new(read_session_id) # doesn't inc counter
+    renew_sid = Rack::Session::XFile.new(renew_session)   # increments counter
+
+    res = Rack::MockRequest.new(inc_cntr).get('/')
+    cookie = res['Set-Cookie']
+    res.body.should.equal counter(1)
+
+    res = Rack::MockRequest.new(read_sid).get('/', set_sid(cookie))
+    cookie = res['Set-Cookie'] if res['Set-Cookie']
+    res.body.length.should.equal session_chars
+    old_sid = res.body
+
+    res = Rack::MockRequest.new(renew_sid).get('/', set_sid(cookie))
+    cookie = res['Set-Cookie'] if res['Set-Cookie']
+    res.body.should.equal counter(2)
+
+    res = Rack::MockRequest.new(read_sid).get('/', set_sid(cookie))
+    cookie = res['Set-Cookie'] if res['Set-Cookie']
+    res.body.length.should.equal session_chars
+    new_sid = res.body
+
+    # the session id should have changed, ...
+    new_sid.should.not.equal old_sid
+
+    # but the session data should persist
+    res = Rack::MockRequest.new(inc_cntr).get('/', set_sid(cookie))
+    res.body.should.equal counter(3)
+
+    # and there should only be one xfile session
+    inc_cntr.session_count.should.equal 1
+  end
+
+  it 'returns no cookie and deletes xfile with :drop option set' do
+    app = Rack::Session::XFile.new(incrementor)
+    req = Rack::MockRequest.new(app)
+    drop = Rack::Utils::Context.new(app, drop_session)
+    dreq = Rack::MockRequest.new(drop)
+
+    res = req.get('/')
+    original_session = res['Set-Cookie'][TheSession]
+    res.body.should.equal counter(1)
+    app.session_count.should.equal 1
+
+    res = req.get('/', set_sid(original_session))
+    res.body.should.equal counter(2)
+    app.session_count.should.equal 1
+
+    res = dreq.get('/', set_sid(original_session))
+    res['Set-Cookie'].should.be.nil
+    res.body.should.equal counter(3)
+    app.session_count.should.be.zero
+
+    res = req.get('/', set_sid(original_session))
+    res['Set-Cookie'][TheSession].should.not.equal original_session
+    res.body.should.equal counter(1)
+    app.session_count.should.equal 1
+  end
+
+  it 'returns no cookie and updates xfile with :defer option set' do
+    app   = Rack::Session::XFile.new(incrementor)
+    exp   = Rack::Session::XFile.new(incrementor, expire_after:3600)
+    exdfr = Rack::Session::XFile.new(incrementor, expire_after:3600, defer:true)
+    defer = Rack::Session::XFile.new(defer_session)
+
+    res = Rack::MockRequest.new(defer).get('/')
+    res['Set-Cookie'].should.be.nil     # normally, new sessions set cookies
+    res.body.should.equal counter(1)    # this xfile is updated on the server,
+    app.session_count.should.equal 1    # but is not referenced by any client
+
+    res = Rack::MockRequest.new(app).get('/')
+    cookie = res['Set-Cookie']
+    cookie.should.not.be.nil            # because new session created
+    res.body.should.equal counter(1)
+    app.session_count.should.equal 2
+
+    res = Rack::MockRequest.new(app).get('/', set_sid(cookie))
+    res['Set-Cookie'].should.be.nil     # because sid did not change
+    res.body.should.equal counter(2)
+    app.session_count.should.equal 2
+
+    res = Rack::MockRequest.new(exp).get('/', set_sid(cookie))
+    cookie = res['Set-Cookie']
+    cookie.should.not.be.nil            # because :expire_after forced update
+    res.body.should.equal counter(3)
+    app.session_count.should.equal 2
+
+    res = Rack::MockRequest.new(exdfr).get('/', set_sid(cookie))
+    res['Set-Cookie'].should.be.nil     # because :defer overrides :expire_after
+    res.body.should.equal counter(4)
+    app.session_count.should.equal 2
+
+    res = Rack::MockRequest.new(app).get('/', set_sid(cookie))
+    res['Set-Cookie'].should.be.nil     # because sid did not change,
+    res.body.should.equal counter(5)    # but keeps state even after :defer
+    app.session_count.should.equal 2
+  end
+
+  it 'returns no cookie and updates xfile with :defer option set in context' do
+    app   = Rack::Session::XFile.new(incrementor)
+    defer = Rack::Utils::Context.new(app, defer_session)
+
+    res = Rack::MockRequest.new(defer).get('/')
+    res['Set-Cookie'].should.be.nil
+    res.body.should.equal counter(1)
+    app.session_count.should.equal 1
+  end
+
+  it 'returns no cookie and skips session processing for filtered requests' do
+    human_user_agent = 'Mozilla/5.0 CoolSurf/100.50'
+    robot_user_agent = 'BigSpider v1.0'
+    robot_filter = /(bot|spider|crawler)/i
+    app = Rack::Session::XFile.new(incrementor, user_agent_filter: robot_filter)
+    req = Rack::MockRequest.new(app)
+
+    res = req.get('/', 'HTTP_USER_AGENT' => robot_user_agent)
+    res['Set-Cookie'].should.be.nil
+    app.session_count.should.be.zero
+
+    res = req.get('/', 'HTTP_USER_AGENT' => human_user_agent)
+    res['Set-Cookie'].should.not.be.nil
+    app.session_count.should.equal 1
+  end
+
+  it 'returns no cookie if sid is unchanged' do
+    app = Rack::Session::XFile.new(incrementor)
+    req = Rack::MockRequest.new(app)
+
+    cookie = req.get('/')['Set-Cookie']
+    cookie.should.match TheSession
+
+    res = req.get('/', set_sid(cookie))
+    res.body.should.equal counter(2)
+    res['Set-Cookie'].should.be.nil
+
+    res = req.get('/', set_sid(cookie))
+    res.body.should.equal counter(3)
+    res['Set-Cookie'].should.be.nil
+  end
+
+  it 'returns no cookie if session is not read or written' do
+    app = Rack::Session::XFile.new(noop)
+    res = Rack::MockRequest.new(app).get('/')
+    res['Set-Cookie'].should.be.nil
+    app.session_count.should.be.zero
+  end
+
+  it 'returns no cookie if previous session is not read or written' do
+    app = Rack::Session::XFile.new(noop)
+    res = Rack::MockRequest.new(app).get('/', set_sid(create_session))
+    res['Set-Cookie'].should.be.nil
+    app.session_count.should.equal 1
+  end
+
+  it 'returns no cookie if session is read but not written' do
+    app = Rack::Session::XFile.new(read_session)
+    res = Rack::MockRequest.new(app).get('/')
+    res['Set-Cookie'].should.be.nil
+    app.session_count.should.be.zero
+  end
+
+  it 'returns no cookie if previous session is read but not written' do
+    app = Rack::Session::XFile.new(read_session)
+    res = Rack::MockRequest.new(app).get('/', set_sid(create_session))
+    res['Set-Cookie'].should.be.nil
+    app.session_count.should.equal 1
+  end
+
+  it 'returns no cookie if session is not written and was not '\
+     'previously created, regardless of the :expire_after option' do
+    app = Rack::Session::XFile.new(read_session, expire_after: 3600)
+    res = Rack::MockRequest.new(app).get('/')
+    res['Set-Cookie'].should.be.nil
+    app.session_count.should.be.zero
+  end
+
+  it 'returns cookie if previous session is not read or written '\
+     'but :expire_after option is set' do
+    app = Rack::Session::XFile.new(noop, expire_after: 3600)
+    res = Rack::MockRequest.new(app).get('/', set_sid(create_session))
+    res['Set-Cookie'].should.not.be.nil
+    app.session_count.should.equal 1
+  end
+
+  FileUtils.rm_rf(spec_tmp_dir)
+end

data/xfile.gemspec

@@ -0,0 +1,19 @@
+Gem::Specification.new do |s|
+  s.name        = 'rack-session-xfile'
+  s.version     = File.read('lib/rack/session/xfile.rb')[/VERSION = '(.*)'/, 1]
+  s.author      = 'Clint Pachl'
+  s.email       = 'pachl@ecentryx.com'
+  s.homepage    = 'http://ecentryx.com/gems/rack-session-xfile'
+  s.license     = 'ISC'
+  s.summary     = 'File-based session management with eXclusive R/W locking.'
+  s.description = <<-EOS
+A simple and reliable file-based session manager with eXclusive R/W locking.
+Session data is updated atomically using mutex and file locks, making it
+suitable for multi-threaded and multi-process applications.
+  EOS
+  s.files = Dir['Rakefile', 'README*', '*.gemspec', 'lib/**/*.rb', 'spec/*']
+  s.test_files = Dir['spec/spec_*.rb']
+  s.required_ruby_version = '>= 1.9.2'
+  s.add_runtime_dependency 'rack', '~> 1.5'
+  s.add_development_dependency 'bacon', '~> 1.2'
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: rack-session-xfile
+version: !ruby/object:Gem::Version
+  version: 0.10.1
+platform: ruby
+authors:
+- Clint Pachl
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-01-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: bacon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: |
+  A simple and reliable file-based session manager with eXclusive R/W locking.
+  Session data is updated atomically using mutex and file locks, making it
+  suitable for multi-threaded and multi-process applications.
+email: pachl@ecentryx.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.rdoc
+- Rakefile
+- lib/rack-session-xfile.rb
+- lib/rack/session/xfile.rb
+- spec/spec_xfile.rb
+- xfile.gemspec
+homepage: http://ecentryx.com/gems/rack-session-xfile
+licenses:
+- ISC
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: File-based session management with eXclusive R/W locking.
+test_files:
+- spec/spec_xfile.rb