rack-flash3 1.0.0

data/README.md

@@ -0,0 +1,93 @@
+# Rack Flash
+
+    flash[:notice] = "You can stop rolling your own now."
+
+Simple flash hash implementation for Rack apps.
+
+[View the RDoc](http://gitrdoc.com/nakajima/rack-flash/tree/master).
+
+## Usage
+
+Here's how to use it.
+
+### Vanilla Rack apps
+
+You can access flash entries via `env['x-rack.flash']`. You can treat it either
+like a regular flash hash:
+
+    env['x-rack.flash'][:notice] = 'You have logged out.'
+
+Or you can pass the `:accessorize` option to declare your flash types. Each of
+these will have accessors defined on the flash object:
+
+    use Rack::Flash, :accessorize => [:notice, :error]
+    
+    # Set a flash entry
+    env['x-rack.flash'].notice = 'You have logged out.'
+    
+    # Get a flash entry
+    env['x-rack.flash'].notice # => 'You have logged out.'
+    
+    # Set a a flash entry for only the current request
+    env['x-rack.flash'].notice! 'You have logged out.'
+
+Sample rack app:
+
+    get = proc { |env|
+      [200, {},
+        env['x-rack.flash'].notice || 'No flash set. Try going to /set'
+      ]
+    }
+
+    set = proc { |env|
+      env['x-rack.flash'].notice = 'Hey, the flash was set!'
+      [302, {'Location' => '/'},
+        'You are being redirected.'
+      ]
+    }
+
+    builder = Rack::Builder.new do
+      use Rack::Session::Cookie
+      use Rack::Flash, :accessorize => true
+
+      map('/set') { run set }
+      map('/')    { run get }
+    end
+
+    Rack::Handler::Mongrel.run builder, :Port => 9292
+
+### Sinatra
+
+If you're using Sinatra, you can use the flash hash just like in Rails:
+
+    require 'sinatra/base'
+    require 'rack-flash'
+
+    class MyApp < Sinatra::Base
+      enable :sessions
+      use Rack::Flash
+
+      post '/set-flash' do
+        # Set a flash entry
+        flash[:notice] = "Thanks for signing up!"
+        
+        # Get a flash entry
+        flash[:notice] # => "Thanks for signing up!"
+        
+        # Set a flash entry for only the current request
+        flash.now[:notice] = "Thanks for signing up!"
+      end
+    end
+
+If you've got any ideas on how to simplify access to the flash hash for vanilla
+Rack apps, let me know. It still feels a bit off to me.
+
+## Sweeping stale entries
+
+By default Rack::Flash has slightly different behavior than Rails in that it
+doesn't delete entries until they are used. If you want entries to be cleared
+even if they are not ever accessed, you can use the `:sweep` option:
+
+    use Rack::Flash, :sweep => true
+
+This will sweep stale flash entries, whether or not you actually use them.

data/Rakefile

@@ -0,0 +1,28 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler2'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "rack-flash3"
+    gem.summary = "Flash hash implementation for Rack apps."
+    gem.description = "Flash hash implementation for Rack apps."
+    gem.email = "treeder@gmail.com"
+    gem.homepage = "http://www.iron.io"
+    gem.authors = ["Pat Nakajima", "Travis Reeder"]
+    gem.add_dependency 'rack'
+    gem.required_ruby_version = '>= 1.9'
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler2"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test

data/VERSION.yml

@@ -0,0 +1,5 @@
+---
+:major: 1
+:minor: 0
+:patch: 0
+:build: !!null 

data/example/base_app.ru

@@ -0,0 +1,22 @@
+require 'rack/request'
+require 'rack/response'
+require 'rack/showexceptions'
+require 'rack/session/cookie'
+require File.dirname(__FILE__) + '/../lib/rack-flash'
+
+class Base
+  attr_accessor :env
+  
+  def call(env)
+    @env = env
+    flash['err'] = "IT'S ALIVE"
+    res = Rack::Response.new
+    res.write "<title>Flashy</title>"
+    res.write "#{flash['err']}"
+    res.finish
+  end
+end
+use Rack::Session::Cookie
+use Rack::Flash#, :flash_app_class => Base
+use Rack::ShowExceptions
+run Base.new

data/example/sinatra_app.rb

@@ -0,0 +1,36 @@
+require 'rubygems'
+require 'sinatra/base'
+require File.dirname(__FILE__) + '/../lib/rack-flash'
+
+class MyApp < Sinatra::Base
+  use Rack::Flash
+
+  set :root, File.dirname(__FILE__)
+  set :layout, true
+  set :logging, true
+  set :sessions, true
+
+  get '/' do
+    erb :index
+  end
+
+  # View the value of any given flash
+  get '/:name' do
+    erb :show
+  end
+
+  post '/:name' do
+    if params[:message].strip.empty?
+      flash["err"] = "You must enter a message."
+      flash["err_on_#{params[:name]}"] = 1
+      redirect('/')
+    end
+
+    flash[:ok] = "Set flash entry!"
+
+    flash[params[:name]] = params[:message]
+    redirect '/'
+  end
+
+  run!
+end

data/example/views/index.erb

@@ -0,0 +1,28 @@
+<% if flash.has?(:err) %>
+  <h3 class="err"><%= flash[:err] %></h3>
+<% end %>
+
+<% if flash.has?(:ok) %>
+  <h3 class="ok"><%= flash[:ok] %></h3>
+<% end %>
+
+<% [:notice, :error, :success, :whatevz, :bliggety].each do |name| %>
+  <form action="/<%= name %>" method="post" accept-charset="utf-8">
+    <label>
+      <span>
+        <% if flash.has?(name) %>
+          <a href="/<%= name %>">View Current</a>
+        <% end %>
+        
+        Set <code>flash[:<%= name %>]</code>
+        
+        <% if err = flash["err_on_#{name}"] %>
+          <strong class="err_on">Required!</strong>
+        <% end %>
+      </span>
+      <input type="text" name="message" value="" id="message">
+    </label>
+    
+    <input type="submit" value="Set Flash">
+  </form>
+<% end %>

data/example/views/layout.erb

@@ -0,0 +1,131 @@
+<html>
+  <head>
+    <title>Flash Examples</title>
+    <style type="text/css" media="screen">
+      * {
+        margin: 0;
+        padding: 0;
+      }
+    
+      body {
+        font-family: Helvetica;
+        font-size: 18px;
+      }
+      
+      a {
+        color: #f09;
+        text-decoration: none;
+        padding: 0px 3px;
+      }
+      
+      a:hover {
+        background: #f09;
+        color: #fff;
+      }
+      
+      a:active {
+        text-decoration: underline;
+      }
+      
+      h1 {
+        text-align: center;
+      }
+      
+      code {
+        font-family: Bitstream Vera Sans Mono , monospace;
+        background: #D4EBF7;
+      }
+      
+      form {
+        margin: 0.4em auto;
+        display: inline-block;
+      }
+      
+      label {
+        line-height: 1em;
+        height: 1em;
+      }
+      
+      label span {
+        display: block;
+        font-size: 12px;
+        margin-bottom: 1px;
+      }
+      
+      label a {
+        font-weight: bold;
+        float: right;
+        margin-right: 79px;
+        line-height: 1.5em;
+      }
+      
+      input[type="text"] {
+        padding: 2px;
+        font-size: 18px;
+        width: 610px;
+        margin-right: 10px;
+      }
+      
+      input[type="submit"] {
+        cursor: pointer;
+        vertical-align: 20%;
+      }
+      
+      .err, .ok {
+        margin: 0.3em 0;
+        padding: 5px 7px;
+        text-align: center;
+        color: #fff;
+      }
+      
+      .ok {
+        background: #00A8FF;
+      }
+      
+      .err {
+        background: #f10;
+      }
+      
+      .err_on {
+        display: inline-block;
+        padding: 0px 3px;
+        color: #f10;
+        font-weight: bold;
+      }
+      
+      .highlight {
+        background: #ffc;
+        padding: 10px;
+        margin-bottom: 10px;
+      }
+      
+      #content {
+        width: 700px;
+        margin: 1em auto;
+      }
+      
+      #result {
+        font-size: 48px;
+        margin: 10% auto 20%;
+        text-align: center;
+        display: block;
+      }
+      
+      #result cite {
+        font-size: 14px;
+        display: block;
+        text-align: right;
+      }
+      
+      #result cite code {
+        font-style: normal;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="content">
+      <h1><code>Sinatra::Flash</code></h1>
+      <%= yield %>
+    </div>
+  </body>
+</html>

data/example/views/show.erb

@@ -0,0 +1,15 @@
+<div id="result">
+  <% if flash.has?(params[:name]) %>
+    <h1 class="highlight"><%= flash[params[:name]] %></h1>
+    <cite>- from <code>flash[:<%= params[:name] %>]</code></cite>
+  <% else %>
+    <p>No flash message for <code>flash[:<%= params[:name] %>]</code></p>
+  <% end %>
+  
+  <br>
+  
+  <small>
+    <a href="/">Go Back Home</a>
+  </small>
+</div>
+

data/lib/rack-flash.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__), *%w[rack flash])

data/lib/rack/flash.rb

@@ -0,0 +1,138 @@
+module Rack
+
+  class Flash
+    # Raised when the session passed to FlashHash initialize is nil. This
+    # is usually an indicator that session middleware is not in use.
+    class SessionUnavailable < StandardError; end
+
+    # Implements bracket accessors for storing and retrieving flash entries.
+    class FlashHash
+      attr_reader :flagged
+
+      def initialize(store, opts={})
+        raise Rack::Flash::SessionUnavailable \
+          .new('Rack::Flash depends on session middleware.') unless store
+
+        @opts = opts
+        @store = store
+
+        if accessors = @opts[:accessorize]
+          accessors.each { |opt| def_accessor(opt) }
+        end
+      end
+
+      # Remove an entry from the session and return its value. Cache result in
+      # the instance cache.
+      def [](key)
+        key = key.to_sym
+        cache[key] ||= values.delete(key)
+      end
+
+      # Store the entry in the session, updating the instance cache as well.
+      def []=(key,val)
+        key = key.to_sym
+        cache[key] = values[key] = val
+      end
+
+      # Store a flash entry for only the current request, swept regardless of
+      # whether or not it was actually accessed. Useful for AJAX requests, where
+      # you want a flash message, even though you're response isn't redirecting.
+      def now
+        cache
+      end
+
+      # Checks for the presence of a flash entry without retrieving or removing
+      # it from the cache or store.
+      def has?(key)
+        [cache, values].any? { |store| store.keys.include?(key.to_sym) }
+      end
+      alias_method :include?, :has?
+
+      # Mark existing entries to allow for sweeping.
+      def flag!
+        @flagged = values.keys
+      end
+
+      # Remove flagged entries from flash session, clear flagged list.
+      def sweep!
+        Array(flagged).each { |key| values.delete(key) }
+        flagged.clear
+      end
+
+      # Hide the underlying :__FLASH__ session key and only expose values stored
+      # in the flash.
+      def inspect
+        '#<FlashHash @values=%s @cache=%s>' % [values.inspect, cache.inspect]
+      end
+
+      # Human readable for logging.
+      def to_s
+        values.inspect
+      end
+
+      private
+
+      # Maintain an instance-level cache of retrieved flash entries. These
+      # entries will have been removed from the session, but are still available
+      # through the cache.
+      def cache
+        @cache ||= {}
+      end
+
+      # Helper to access flash entries from :__FLASH__ session value. This key
+      # is used to prevent collisions with other user-defined session values.
+      def values
+        @store[:__FLASH__] ||= {}
+      end
+
+      # Generate accessor methods for the given entry key if :accessorize is true.
+      def def_accessor(key)
+        raise ArgumentError.new('Invalid entry type: %s' % key) if respond_to?(key)
+
+        class << self; self end.class_eval do
+          define_method(key) { |*args| val = args.first; val ? (self[key]=val) : self[key] }
+          define_method("#{key}=") { |val| self[key] = val }
+          define_method("#{key}!") { |val| cache[key] = val }
+        end
+      end
+    end
+
+    # -------------------------------------------------------------------------
+    # - Rack Middleware implementation
+
+    def initialize(app, opts={})
+      if klass = app_class(app, opts)
+        klass.class_eval do
+          def flash; env['x-rack.flash'] end
+        end
+      end
+
+      @app, @opts = app, opts
+    end
+
+    def call(env)
+      env['x-rack.flash'] ||= Rack::Flash::FlashHash.new(env['rack.session'], @opts)
+
+      if @opts[:sweep]
+        env['x-rack.flash'].flag!
+      end
+
+      res = @app.call(env)
+
+      if @opts[:sweep]
+        env['x-rack.flash'].sweep!
+      end
+
+      res
+    end
+
+    private
+
+    def app_class(app, opts)
+      return nil if opts.has_key?(:helper) and not opts[:helper]
+      opts[:flash_app_class] ||
+        defined?(Sinatra::Base) && Sinatra::Base ||
+        self.class.rack_builder.leaf_app.class
+    end
+  end
+end

data/lib/rack/flash/test.rb

@@ -0,0 +1,14 @@
+module Rack
+  class Flash
+    def self.fake_session
+      @fake_session ||= {}
+    end
+    
+    alias_method :old_call, :call
+    def new_call(env)
+      env['rack.session'] ||= Rack::Flash.fake_session
+      old_call(env)
+    end
+    alias_method :call, :new_call
+  end
+end

data/test/helper.rb

@@ -0,0 +1,51 @@
+require 'rubygems'
+gem 'sinatra', '<=1.3.2'
+require 'sinatra/base'
+require 'bacon'
+require 'rack/test'
+require File.join(File.dirname(__FILE__), *%w[.. lib rack-flash])
+
+class String
+  [:green, :yellow, :red].each { |c| define_method(c) { self } }
+end if ENV['TM_RUBY']
+
+# bacon swallows errors alive
+def err_explain
+  begin
+    yield
+  rescue => e
+    puts e.inspect
+    puts e.backtrace
+    raise e
+  end
+end
+
+module Rack
+  class FakeFlash < Rack::Flash::FlashHash
+    attr_reader :flagged, :sweeped, :store
+
+    def initialize(*args)
+      @flagged, @sweeped = false, false
+      @store = {}
+      super(@store)
+    end
+
+    def flag!
+      @flagged = true
+      super
+    end
+
+    def sweep!
+      @sweeped = true
+      super
+    end
+
+    def flagged?
+      @flagged
+    end
+
+    def swept?
+      @sweeped
+    end
+  end
+end

data/test/test_flash.rb

@@ -0,0 +1,157 @@
+require File.dirname(__FILE__) + '/helper'
+
+describe 'Rack::Flash' do
+  include Rack::Test::Methods
+
+  def app(&block)
+    return Sinatra.new &block
+  end
+
+  before do
+    @fake_session = {}
+  end
+
+  def new_flash(entries={})
+    flash = Rack::Flash::FlashHash.new(@fake_session)
+    entries.each { |key,val| flash[key] = val }
+    flash
+  end
+
+  it 'stores entries' do
+    new_flash[:foo] = 'bar'
+    new_flash[:foo].should.equal('bar')
+  end
+
+  it 'accepts strings or hashes' do
+    new_flash[:foo] = 'bar'
+    new_flash['foo'].should.equal('bar')
+  end
+
+  it 'deletes entries from session after retrieval' do
+    new_flash[:foo] = 'bar'
+    new_flash[:foo]
+    new_flash[:foo].should.be.nil
+  end
+
+  it 'caches retrieved entries in instance' do
+    flash = new_flash(:foo => 'bar')
+    flash[:foo].should.equal('bar')
+    flash[:foo].should.equal('bar')
+  end
+
+  it 'does not step on session keys' do
+    @fake_session[:foo] = true
+    new_flash[:foo] = false
+    @fake_session[:foo].should.be.true
+  end
+
+  it 'can flag existing entries' do
+    flash = new_flash(:foo => 'bar', :fizz => 'buzz')
+    flash.flag!
+    flash.flagged.should.include(:foo)
+    flash.flagged.should.include(:fizz)
+  end
+
+  it 'can sweep flagged entries' do
+    err_explain do
+      flash = new_flash(:foo => 'bar', :fizz => 'buzz')
+      flash.flag!
+      flash.sweep!
+      flash.flagged.should.be.empty
+      new_flash[:foo].should.be.nil
+      new_flash[:fizz].should.be.nil
+    end
+  end
+
+  it 'allows setters with Flash.now semantics' do
+    flash = new_flash
+    flash.now[:foo] = 'bar'
+    flash[:foo].should.equal('bar')
+    new_flash[:foo].should.be.nil
+  end
+
+  it 'does not raise an error when session is cleared' do
+    flash = new_flash
+    flash[:foo] = 'bar'
+    @fake_session.clear
+    flash['foo'].should.equal(nil)
+  end
+
+  describe 'accessorize option' do
+    def new_flash(entries={})
+      flash = Rack::Flash::FlashHash.new(@fake_session, :accessorize => [:foo, :fizz])
+      entries.each { |key,val| flash[key] = val }
+      flash
+    end
+
+    it 'allows getters' do
+      flash = new_flash(:foo => 'bar')
+      flash.foo.should.equal('bar')
+    end
+
+    it 'allows setters' do
+      flash = new_flash
+      flash.fizz = 'buzz'
+      flash.fizz.should.equal('buzz')
+    end
+
+    it 'allows declarative setters' do
+      flash = new_flash
+      flash.fizz 'buzz'
+      flash.fizz.should.equal('buzz')
+    end
+
+    it 'allows setters with Flash.now semantics' do
+      flash = new_flash
+      flash.foo! 'bar'
+      flash.foo.should.equal('bar')
+      new_flash[:foo].should.be.nil
+    end
+
+    it 'only defines accessors for passed entry types' do
+      err_explain do
+        flash = new_flash
+        proc {
+          flash.bliggety = 'blam'
+        }.should.raise(NoMethodError)
+      end
+    end
+  end
+
+  it 'does not provide getters by default' do
+    proc {
+      new_flash(:foo => 'bar').foo
+    }.should.raise(NoMethodError)
+  end
+
+  it 'does not provide setters by default' do
+    proc {
+      flash = new_flash
+      flash.fizz = 'buzz'
+    }.should.raise(NoMethodError)
+  end
+
+  describe 'integration' do
+    it 'provides :sweep option to clear unused entries' do
+      app {
+        use Rack::Flash, :sweep => true
+
+        set :sessions, true
+
+        get '/' do
+          'ok'
+        end
+      }
+
+      fake_flash = Rack::FakeFlash.new(:foo => 'bar')
+
+      get '/', :env=>{ 'x-rack.flash' => fake_flash }
+
+      fake_flash.should.be.flagged
+      fake_flash.should.be.swept
+      fake_flash.store[:foo].should.be.nil
+    end
+  end
+
+  # Testing sessions is a royal pain in the ass.
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: rack-flash3
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Pat Nakajima
+- Travis Reeder
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-03-19 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: &11215120 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *11215120
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: &11214480 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *11214480
+description: Flash hash implementation for Rack apps.
+email: treeder@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- Rakefile
+- VERSION.yml
+- example/base_app.ru
+- example/sinatra_app.rb
+- example/views/index.erb
+- example/views/layout.erb
+- example/views/show.erb
+- lib/rack-flash.rb
+- lib/rack/flash.rb
+- lib/rack/flash/test.rb
+- test/helper.rb
+- test/test_flash.rb
+homepage: http://www.iron.io
+licenses: []
+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'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: Flash hash implementation for Rack apps.
+test_files: []