123456789_123456789_123456789_123456789_123456789_

Class: Rack::Events

Relationships & Source Files
Namespace Children
Modules:
Abstract
Classes:
BufferedResponse, EventedBodyProxy
Inherits: Object
Defined in: lib/rack/events.rb

Overview

This middleware provides hooks to certain places in the request / response lifecycle. This is so that middleware that don’t need to filter the response data can safely leave it alone and not have to send messages down the traditional “rack stack”.

The events are:

  • on_start(request, response)

    This event is sent at the start of the request, before the next middleware in the chain is called. This method is called with a request object, and a response object. Right now, the response object is always nil, but in the future it may actually be a real response object.

  • on_commit(request, response)

    The response has been committed. The application has returned, but the response has not been sent to the webserver yet. This method is always called with a request object and the response object. The response object is constructed from the rack triple that the application returned. Changes may still be made to the response object at this point.

  • on_send(request, response)

    The webserver has started iterating over the response body, or has called the streaming body, and presumably has started sending data over the wire. This method is always called with a request object and the response object. The response object is constructed from the rack triple that the application returned. Changes SHOULD NOT be made to the response object as the webserver has already started sending data. Any mutations will likely result in an exception.

  • on_finish(request, response)

    The webserver has closed the response, and all data has been written to the response socket. The request and response object should both be read-only at this point. The body MAY NOT be available on the response object as it may have been flushed to the socket.

  • on_error(request, response, error)

    An exception has occurred in the application or an #on_commit event. This method will get the request, the response (if available) and the exception that was raised.

Order

#on_start is called on the handlers in the order that they were passed to the constructor. #on_commit, on_send`, #on_finish, and #on_error are called in the reverse order. #on_finish handlers are called inside an ensure block, so they are guaranteed to be called even if something raises an exception. If something raises an exception in a #on_finish method, then nothing is guaranteed.

Class Method Summary

Instance Method Summary

Constructor Details

.new(app, handlers) ⇒ Events

[ GitHub ] 

  


# File 'lib/rack/events.rb', line 121



def initialize(app, handlers)
  @app      = app
  @handlers = handlers
end


  







Instance Method Details



  

    #call(env)  
  

  [ GitHub ]


  

  


# File 'lib/rack/events.rb', line 126



def call(env)
  request = make_request env
  on_start request, nil

  begin
    status, headers, body = @app.call request.env
    response = make_response status, headers, body
    on_commit request, response
  rescue StandardError => e
    on_error request, response, e
    on_finish request, response
    raise
  end

  body = EventedBodyProxy.new(body, request, response, @handlers) do
    on_finish request, response
  end
  [response.status, response.headers, body]
end


  








  

    #make_request(env)   (private)
  

  [ GitHub ]


  

  


# File 'lib/rack/events.rb', line 164



def make_request(env)
  Rack::Request.new env
end


  








  

    #make_response(status, headers, body)   (private)
  

  [ GitHub ]


  

  


# File 'lib/rack/events.rb', line 168



def make_response(status, headers, body)
  BufferedResponse.new status, headers, body
end


  








  

    #on_commit(request, response)   (private)
  

  [ GitHub ]


  

  


# File 'lib/rack/events.rb', line 152



def on_commit(request, response)
  @handlers.reverse_each { |handler| handler.on_commit request, response }
end


  








  

    #on_error(request, response, e)   (private)
  

  [ GitHub ]


  

  


# File 'lib/rack/events.rb', line 148



def on_error(request, response, e)
  @handlers.reverse_each { |handler| handler.on_error request, response, e }
end


  








  

    #on_finish(request, response)   (private)
  

  [ GitHub ]


  

  


# File 'lib/rack/events.rb', line 160



def on_finish(request, response)
  @handlers.reverse_each { |handler| handler.on_finish request, response }
end


  








  

    #on_start(request, response)   (private)
  

  [ GitHub ]


  

  


# File 'lib/rack/events.rb', line 156



def on_start(request, response)
  @handlers.each { |handler| handler.on_start request, nil }
end