rack_session_manipulation 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dbcb62e888d972acb2dd24eb5a7a735381d58752
-  data.tar.gz: 9d540498faedaf7581331dd70623a95a617acb92
+  metadata.gz: 61e70f7fa7fadbe40c3e4bf885a1a998fced1c10
+  data.tar.gz: 8c9736d1644eae68a05b9b4655a539bd4235543b
 SHA512:
-  metadata.gz: 30df0e975654195180fd191c52e9fa945f081014c00407e4da3064d979683afad96430b27afd2f74bd34c75ca437cc6428fd9079698fb6460427d8cf82b45089
-  data.tar.gz: 4aec3d4ced2064f6aef2456d805e3473985a60abed1bff6a6add1a60597d7688cfaac2b21c6533e9d4143d3d62f3a6fa9c11b7de93c40d000f764c837e3ddff0
+  metadata.gz: f8377740e66ebb1fb1b921472d91a18ce41640d9178eaef77153ef4c0a9ad46d05b2b792db897bde45caa125ffbb0bf46f366ac28b4dd2e18b4f4fdb11636697
+  data.tar.gz: f7c2522ebd7c448f347b082d11529a49583f2d7a02fbcbb80e323dc0f35dc5e402202be13c6d120d4708a2fda5e758690132586f31b039bf944e3913e7b233aa

data/.rubocop.yml

@@ -1,4 +1,6 @@
 RSpec/FilePath:
   Enabled: false
+Style/RegexpLiteral:
+  AllowInnerSlashes: yes
 require:
 - rubocop-rspec

data/README.md

@@ -8,9 +8,10 @@
 [![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.
+information to be read and modified from within tests (primarily for use within
+Capybara). 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
@@ -37,6 +38,18 @@ gem solved the updating of state using multiple requests, and marshalled
 objects as well as unecessary use of builder. The approach seemed more
 complicated, slower and more dangerous than necessary.
 
+If you are looking to test a specific session state from a pure rack/test unit
+perspective, you don't need this gem. The native rack/test HTTP methods provide
+the mechanism to directly set and test state like so:
+
+```
+session_data = { 'user_id' => 5 }
+get '/test_path', {}, { 'rack.session' => session_data }
+```
+
+The above will make a get request to '/test_path' with the session state
+contained within the `session_data` variable.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -55,6 +68,64 @@ Or install it yourself as:
 
 ## Usage
 
+The middleware is useful on it's own, but this gem's primary power comes from
+it's integration with Capybara. On it's own or with capybara, the first step is
+to inject the middleware. This varies from framework to framework, the most
+common examples I've provided below.
+
+### Rack
+
+The following is a super simple rack app that at a minimum can be used as a
+fallback definition for any Ruby web application by replacing the `YourApp`
+constant with your application (generally this is what is passed to `run` in
+your 'config.ru' file. At the same time you'll want to replace the value in
+your 'config.ru' file with the constant `YourAwesomeRackStack` (though you can
+change that as you'd like).
+
+```ruby
+YourAwesomeRackStack = Rack::Builder.new do
+  # To access sessions they must first exist. Configure the appropriate Rack
+  # session mechanism prior to using this middleware.
+  use Rack::Session::Cookie, secret: 'some secret string'
+
+  # Add this middleware to the stack
+  use RackSessionManipulation::Middleware
+
+  # Finally, running your own App at the top of the stack
+  run YourApp
+end.to_app
+```
+
+### Sinatra
+
+TODO
+
+### Rails
+
+TODO
+
+### Capybara Usage
+
+After setting up the middleware and Capybara as you would normally, the only
+additional setup is requiring the Capybara helpers (you generally want to add
+this line after the 'capybara' require):
+
+```ruby
+require 'rack_session_access/capybara'
+```
+
+After that anywhere you are using Capybara you will have three additional
+methods available to you:
+
+* reset_session: Clear the entire contents of the existing session.
+* session: Get a hash representing the current session state.
+* session=: additional data into the current session.
+
+When setting the session, you'll want to provide a hash. The values at the top
+level keys of the hash will replace the equivalent keys in the current session.
+Any keys that existed before but aren't getting set will continue to exist. It
+works like a simple Hash merge. The other methods are fairly self explanatory.
+
 ## Contributing
 
 I welcome new ideas, bug fixes and comments from anyone and strive to take no
@@ -72,10 +143,15 @@ contribution guide:
 
 1. Review the [Contributor Code of Conduct][2]
 2. Fork it ( https://github.com/sstelfox/rack_session_manipulation/fork )
-3. Create your feature branch (`git checkout -b my-new-feature`)
+3. Create your feature branch (`git checkout -b my-new-feature develop`)
 4. Commit your changes (`git commit -am 'Add some feature'`)
 5. Push to the branch (`git push origin my-new-feature`)
 6. Create a new Pull Request against this repo's develop branch
 
+Code in the master branch is the latest released version. All code that has
+made it into the develop branch is staged for the next release. All tests must
+be passing before the code will get merged into develop. Along those lines,
+please write tests to cover bugs found or features added!
+
 [1]: https://github.com/railsware/rack_session_access
 [2]: CODE_OF_CONDUCT.md

data/lib/rack_session_manipulation/capybara.rb

@@ -1,4 +1,3 @@
-# Parent namespace for the Rack Session Manipulation middleware.
 module RackSessionManipulation
   # This module exposes the session state helpers to Capybara, allowing feature
   # tests to quickly access the session mechanisms.
@@ -34,6 +33,10 @@ module RackSessionManipulation
       driver_method_fallback(:put, session_manipulation_config.path, data)
     end
 
+    # Expose an instance of the middleware's configuration object to Capybara
+    # to allow configuration alongside the DSL.
+    #
+    # @return [RackSessionManipulation::Config]
     def session_manipulation_config
       @rsm_config ||= Config.new
     end

data/lib/rack_session_manipulation/middleware.rb

@@ -1,10 +1,60 @@
-# Parent namespace for the Rack Session Manipulation middleware.
 module RackSessionManipulation
   # Rack middleware that handles the accessing and modification of session
   # state.
+  #
+  # @attr_reader [Object] app The core Rack application running on top of this
+  #   middleware.
+  # @attr_reader [RackSessionManipulation::Config] config An instance of the
+  #   configuration provided to this middleware.
+  # @attr_reader [Hash<String=>Symbol>] routes Mapping of HTTP methods to
+  #   local method handler.
   class Middleware
     attr_reader :app, :config, :routes
 
+    # @!group Action Handlers
+
+    # 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 = config.encoder.encode(session_hash)
+
+      [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']
+      config.encoder.decode(session_data).each do |k, v|
+        request.env['rack.session'][k] = v
+      end
+
+      loc_hdr = { 'Location' => config.path }
+      [303, headers(0).merge(loc_hdr), '']
+    rescue JSON::ParserError
+      [400, headers(0), '']
+    end
+
+    # @!endgroup
+    # @!group Standard Middleware Methods
+
     # 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
@@ -18,7 +68,7 @@ module RackSessionManipulation
       request = Rack::Request.new(env)
 
       action = get_action(request)
-      action.nil? ? app.call(env) : send(action, request)
+      action.nil? ? app.call(env) : safe_handle(action, request)
     end
 
     # Setup the middleware with the primary application passed in, anything we
@@ -38,6 +88,9 @@ module RackSessionManipulation
       }
     end
 
+    # @!endgroup
+    # @!group Request Handling Helpers
+
     # 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.
@@ -82,43 +135,17 @@ module RackSessionManipulation
       }
     end
 
-    # Handle requests to entirely reset the session state.
+    # Safely handle the middleware requests so we can properly handle errors in
+    # the middleware by returning the correct HTTP status code and message.
     #
-    # @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 = config.encoder.encode(session_hash)
-
-      [200, headers(content.length), content]
+    # @param [Symbol] action The local method that will handle the request.
+    # @param [Rack::Request] request The request that needs to be processed.
+    def safe_handle(action, request)
+      send(action, request)
+    rescue => e
+      [500, headers(e.message.length), e.message]
     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']
-      config.encoder.decode(session_data).each do |k, v|
-        request.env['rack.session'][k] = v
-      end
-
-      loc_hdr = { 'Location' => config.path }
-      [303, headers(0).merge(loc_hdr), '']
-    rescue JSON::ParserError
-      [400, headers(0), '']
-    end
+    # @!endgroup
   end
 end

data/lib/rack_session_manipulation/version.rb

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

metadata

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