rack_session_manipulation 0.1.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 70ee014ab99f99fa2f2ad204ce13a2bd7962a7ad
-  data.tar.gz: ef49f9684ecaf820f6f8d0d0786d4c2aa0192f7c
+  metadata.gz: a9b92685bdfb1562d5c91f2f43e7d9f011bd7175
+  data.tar.gz: 4039479856583c1db25262e525da2e18ae1846c3
 SHA512:
-  metadata.gz: 069c8f5fe4346c9abf868ef3ba77c770fe34b6cd067e80f281fe8cac52a432de106119ac252fb47de0184a4792a9ed824d2b6ab340ed2da2aeeadf1715263aaf
-  data.tar.gz: aa3860206e132799bad764c79cd029f4f1af5ef4403bccf0c9d3762cba2be65630025f5d8cdce8302d490252d6663f1662bab9bf0ab4905f0b0d639a2b6cb51d
+  metadata.gz: 35eb5e1f919e08e8f0182b7e996e096a811f6f9ca82df0a7013efa43eab50189d36089c7288b0bd5c6c878c82c7bafa26a118aa9054af74d1376eedb7ffda298
+  data.tar.gz: ec6dd5bcfb8be8733b156d77ac76bb873a70bd5c484f272c7fd4f7a80fc8b15ab4824d237d57aed88c4635a91a6a4d51d330198776e92eda2c855f7126fb6f04

data/README.md

@@ -1,9 +1,27 @@
 # RackSessionManipulation
 
+[![Gem Version](https://badge.fury.io/rb/rack_session_manipulation.svg)](https://rubygems.org/gems/rack_session_manipulation)
 [![Build Status](https://travis-ci.org/sstelfox/rack_session_manipulation.svg)](https://travis-ci.org/sstelfox/rack_session_manipulation)
 [![Coverage Status](https://coveralls.io/repos/sstelfox/rack_session_manipulation/badge.svg?branch=develop)](https://coveralls.io/r/sstelfox/rack_session_manipulation?branch=develop)
 [![Dependency Status](https://gemnasium.com/sstelfox/rack_session_manipulation.svg)](https://gemnasium.com/sstelfox/rack_session_manipulation)
 [![Code Climate](https://codeclimate.com/github/sstelfox/rack_session_manipulation/badges/gpa.svg)](https://codeclimate.com/github/sstelfox/rack_session_manipulation)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-green.svg)](http://www.rubydoc.info/gems/rack_session_manipulation)
+
+RackSessionManipulation is rack middleware designed to expose internal session
+information to be read and modified from within tests. This is intended to
+assist in treating routes as modular units of work that can be tested in
+isolation without the dependency of the rest of your application.
+
+This is not intended to replace full set of 'behavior' tests, but can be used
+to speed up getting to a 'Given' state in place of helpers that previously
+would be forced to walk through your entire application stack to establish the
+target state. That walkthrough is valuable but can be redundant and unecessary.
+
+This middleware should never be used in production as it allows arbitrary
+tampering of encrypted server-side session information without any form of
+authentication. Use in production can lead to abuses such as user
+impersonation, privilege escalation, and private information exposure depending
+on what the application stores in the session.
 
 ## Installation
 

data/lib/rack_session_manipulation/capybara.rb

@@ -1,18 +1,65 @@
-# Parent module for the Rack Session Manipulation middleware.
+# Parent namespace for the Rack Session Manipulation middleware.
 module RackSessionManipulation
-  # Capybara helpers for accessing and setting session values
+  # This module exposes the session state helpers to Capybara, allowing feature
+  # tests to quickly access the session mechanisms.
   module Capybara
-    def session=(hash)
-      data = { 'session_data' => RackSessionManipulation.encode(hash) }
-      driver.put(RackSessionManipulation.config.path, data)
+    # Provides a mechanism to completely reset the server's session to a fresh
+    # blank slate.
+    def reset_session
+      driver_method_fallback(:delete, RackSessionManipulation.config.path, data)
     end
 
+    # Retrieve a hash containing the entire state of the current session.
+    #
+    # @return [Hash] Hash of the session
     def session
       driver.get(RackSessionManipulation.config.path)
       RackSessionManipulation.decode(driver.response.body)
     end
+
+    # Updates the state of the current session. An important thing to note
+    # about this mechanism is that it does not set the session to perfectly
+    # match the state of the provided hash. The provided hash is effectively
+    # merged with the current state of the session.
+    #
+    # This also does not support marshalling objects into the session state.
+    # This limitation is intentional as objects stored in sessions tend to be
+    # a detriment to both performance and security.
+    #
+    # @param [Hash] hash Data to be set / updated within the current session.
+    def session=(hash)
+      data = { 'session_data' => RackSessionManipulation.encode(hash) }
+      driver_method_fallback(:put, RackSessionManipulation.config.path, data)
+    end
+
+    protected
+
+    # Capybara drivers are only required to implement the #get method. Where
+    # appropriate we'll use the correct HTTP method, but when unavailable we'll
+    # use the fallback mechanism.
+    #
+    # There may be a subtle bug in this fallback mechanism when the driver
+    # doesn't support 'POST' requests. If large data payloads are used. Normal
+    # HTTP request parameters within the URL itself are limited to 1024
+    # characters.
+    #
+    # @param [Symbol] method A valid HTTP method name (all lowercase).
+    # @param [String] path The path to request in the driver's rack app.
+    # @param [Hash] dat An optional hash of data that will be sent along as
+    #   part of the query parameters.
+    def driver_method_fallback(method, path, dat = {})
+      if driver.respond_to?(method)
+        driver.send(method, path, dat)
+        return
+      end
+
+      data.merge!('_method' => method.to_s.upcase)
+      driver.respond_to?(:post) ? driver.post(path, dat) : driver.get(path, dat)
+    end
   end
 end
 
+# When this file is required automatically expose it through the Capybara
+# session helpers.
 require 'capybara/session'
 Capybara::Session.send(:include, RackSessionManipulation::Capybara)

data/lib/rack_session_manipulation/config.rb

@@ -1,4 +1,5 @@
-# Parent module for the Rack Session Manipulation middleware.
+# Parent namespace for the Rack Session Manipulation middleware.
 module RackSessionManipulation
+  # A data storage structure for holding configuration related information.
   Config = Struct.new(:path)
 end

data/lib/rack_session_manipulation/middleware.rb

@@ -1,8 +1,17 @@
-# Parent module for the Rack Session Manipulation middleware.
+# Parent namespace for the Rack Session Manipulation middleware.
 module RackSessionManipulation
   # Rack middleware that handles the accessing and modification of session
   # state.
   class Middleware
+    # Primary entry point of this middleware. Every request that makes it this
+    # far into the stack will be parsed and when it matches something this
+    # middleware is designed to handle it will stop the chain and process it
+    # appropriately.
+    #
+    # @param [Hash] env An environment hash containing everything about the
+    #   client's request.
+    # @return [Array<Fixnum, Hash, String>] A generated response to the
+    #   client's request.
     def call(env)
       request = Rack::Request.new(env)
 
@@ -10,34 +19,80 @@ module RackSessionManipulation
       action.nil? ? @app.call(env) : send(action, request)
     end
 
-    def initialize(app, _options = {})
+    # Setup the middleware with the primary application passed in, anything we
+    # can't handle will be passed to this application.
+    #
+    # @param [Object#call] app A rack application that implements the #call
+    #   method.
+    def initialize(app)
       @app = app
       @routes = {
-        'GET' => :retrieve,
-        'PUT' => :update
+        'DELETE'  => :reset,
+        'GET'     => :retrieve,
+        'PUT'     => :update
       }
     end
 
     protected
 
+    # Look up what HTTP method was used for this request. In the event the
+    # client doesn't support all HTTP methods, the standard '_method' parameter
+    # fall back is made available to override the method actually used.
+    #
+    # Normally the '_method' fall back is only accepted over the POST method,
+    # however, Capybara drivers are only required to implement GET method and
+    # so this does not require any particular method to support the override.
+    #
+    # When a GET method was used to provide data, a subtle issue can crop up.
+    # URLs can't exceed 1024 characters. Generally this results in them being
+    # truncated which in turn will cause a JSON parse error and no changes
+    # being made to the session.
+    #
+    # @param [Rack::Request] request The request to analyze
+    # @return [String] The decided on HTTP method
     def extract_method(request)
-      return request.request_method unless request.request_method == 'POST'
       return request.params['_method'].upcase if request.params['_method']
       request.request_method
     end
 
+    # Considers the request and if it matches something this middleware handles
+    # return the symbol matching the name of the method that should handle the
+    # request.
+    #
+    # @param [Rack::Request] request The request to assess
+    # @return [Symbol,Nil] Name of method to use or nil if this middleware
+    #   should pass the request on to the app.
     def get_action(request)
       return unless request.path == RackSessionManipulation.config.path
       @routes[extract_method(request)]
     end
 
+    # A helper mechanism to consistently generate common headers client will
+    # expect.
+    #
+    # @param [Fixnum] length Byte size of the message body.
+    # @return [Hash] The common headers
     def headers(length)
       {
-        'Content-Type'   => 'application/json',
-        'Content-Length' => length
+        'Content-Length'  => length,
+        'Content-Type'    => 'application/json; charset=utf-8'
       }
     end
 
+    # Handle requests to entirely reset the session state.
+    #
+    # @param [Rack::Request] request
+    # @return [Array<Fixnum, Hash, String>]
+    def reset(request)
+      request.env['rack.session'].clear
+      [204, headers(0), '']
+    end
+
+    # Retrieve the entire contents of the session and properly encode it
+    # before returning.
+    #
+    # @param [Rack::Request] request
+    # @return [Array<Fixnum, Hash, String>]
     def retrieve(request)
       session_hash = request.env['rack.session'].to_hash
       content = RackSessionManipulation.encode(session_hash)
@@ -45,13 +100,20 @@ module RackSessionManipulation
       [200, headers(content.length), content]
     end
 
+    # Update the current state of the session with the provided data. This
+    # works effectively like a hash merge on the current session only setting
+    # and overriding keys in the session data provided.
+    #
+    # @param [Rack::Request] request
+    # @return [Array<Fixnum, Hash, String>]
     def update(request)
       session_data = request.params['session_data']
       RackSessionManipulation.decode(session_data).each do |k, v|
         request.env['rack.session'][k] = v
       end
 
-      [204, headers(0), '']
+      loc_hdr = { 'Location' => RackSessionManipulation.config.path }
+      [303, headers(0).merge(loc_hdr), '']
     rescue JSON::ParserError
       [400, headers(0), '']
     end

data/lib/rack_session_manipulation/utilities.rb

@@ -1,12 +1,24 @@
-# Parent module for the Rack Session Manipulation middleware.
+# Parent namespace for the Rack Session Manipulation middleware.
 module RackSessionManipulation
   # Various utility methods that will be module level functions for the parent
   # namespace module.
   module Utilities
+    # Helper method for decoding the session state into a standard Ruby hash.
+    # This data is exposed as JSON, and is parsed as such.
+    #
+    # @param [String] encoded_data JSON encoded session data
+    # @return [Hash] Hash version of the session data
     def decode(encoded_data)
       JSON.parse(encoded_data)
     end
 
+    # Helper method for encoding modified session state for the middleware. The
+    # middleware expects JSON so this is just a thin wrapper for encoding to
+    # JSON.
+    #
+    # @param [Hash] obj An object that can be serialized using JSON, generally
+    #   this is a hash.
+    # @return [String] The encoded data.
     def encode(obj)
       JSON.generate(obj)
     end
@@ -19,11 +31,11 @@ module RackSessionManipulation
     def random_path_prefix
       num = begin
         require 'securerandom'
-        SecureRandom.random_number(2**64 - 1)
+        SecureRandom.random_number(2**128 - 1)
       rescue LoadError, NotImplementedError
-        Kernel.rand(2**64 - 1)
+        Kernel.rand(2**128 - 1)
       end
-      format('/%016x', num)
+      format('/%032x', num)
     end
   end
 end

data/lib/rack_session_manipulation/version.rb

@@ -1,5 +1,5 @@
-# Parent module for the Rack Session Manipulation middleware.
+# Parent namespace for the Rack Session Manipulation middleware.
 module RackSessionManipulation
   # The current version of this module
-  VERSION = '0.1.0'
+  VERSION = '0.7.0'
 end

data/lib/rack_session_manipulation.rb

@@ -5,14 +5,23 @@ require 'rack_session_manipulation/middleware'
 require 'rack_session_manipulation/utilities'
 require 'rack_session_manipulation/version'
 
-# Parent module for the Rack Session Manipulation middleware.
+# RackSessionManipulation is rack middleware designed to expose internal
+# session information to be read and modified from within tests.
 module RackSessionManipulation
   extend RackSessionManipulation::Utilities
 
+  # Keeps a globally accessible instance of a configuration object. This will
+  # initialize a new Config object the first time this is called (using a
+  # random path for the session access path).
+  #
+  # @return [RackSessionManipulation::Config]
   def self.config
     @config ||= RackSessionManipulation::Config.new(random_path_prefix)
   end
 
+  # Allows block DSL style configuration of the global configuration instance.
+  #
+  # @yield [RackSessionManipulation::Config]
   def self.configure
     yield(config)
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rack_session_manipulation
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Sam Stelfox
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-28 00:00:00.000000000 Z
+date: 2015-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -222,7 +222,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.3
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: A rack middleware for exposing session state to tests.