Passenger: Passenger::Session Class Reference

# Passenger::Session Class Reference

Represents a single request/response pair of an application process. More...

`#include <Session.h>`

Inheritance diagram for Passenger::Session:
[legend]

List of all members.

## Public Member Functions
virtual | ~Session ()
| Concrete classes might throw arbitrary exceptions.
virtual void | initiate ()=0
| Initiate the session by connecting to the associated process.
virtual bool | initiated () const =0
| Returns whether this session has been initiated (that is, whether initiate() had been called in the past).
virtual string | getSocketType () const =0
| Returns the type of the socket that this session is served from, e.g.
virtual string | getSocketName () const =0
| Returns the address of the socket that this session is served from.
virtual void | sendHeaders (const char *headers, unsigned int size)
| Send HTTP request headers to the application.
virtual void | sendHeaders (const StaticString &headers)
| Convenience shortcut for sendHeaders(const char *, unsigned int).
virtual void | sendBodyBlock (const char *block, unsigned int size)
| Send a chunk of HTTP request body data to the application.
virtual int | getStream () const =0
| Returns this session's channel's file descriptor.
virtual void | setReaderTimeout (unsigned int msec)=0
| Set the timeout value for reading data from the I/O channel.
virtual void | setWriterTimeout (unsigned int msec)=0
| Set the timeout value for writing data from the I/O channel.
virtual void | shutdownReader ()=0
| Indicate that we don't want to read data anymore from the I/O channel.
virtual void | shutdownWriter ()=0
| Indicate that we don't want to write data anymore to the I/O channel.
virtual void | closeStream ()=0
| Close the I/O stream.
virtual void | discardStream ()=0
| Discard the I/O channel's file descriptor, so that the destructor won't automatically close it.
virtual pid_t | getPid () const =0
| Get the process ID of the application process that this session belongs to.
const string | getConnectPassword () const
| Returns this session's process's connect password.

## Detailed Description

Represents a single request/response pair of an application process.

Session is used to forward a single HTTP request to an application process, and to read back the HTTP response. A Session object is to be used in the following manner:

1. Serialize the HTTP request headers into a format as expected by sendHeaders(), then send that string by calling sendHeaders().
2. In case of a POST of PUT request, send the HTTP request body by calling sendBodyBlock(), possibly multiple times.
3. Shutdown the writer end of the session channel (shutdownWriter()) since you're now done sending data.
4. The HTTP response can now be read through the session channel (getStream()).
5. When the HTTP response has been read, the session must be closed. This is done by destroying the Session object.

A usage example is shown in Process::newSession().

Session is an abstract base class. Concrete implementations can be found in StandardSession and ApplicationPool::Client::RemoteSession.

Session is not guaranteed to be thread-safe.

## Member Function Documentation

virtual void Passenger::Session::closeStream | ( |  | ) | `[pure virtual]`

Close the I/O stream.

Exceptions:

  | SystemException | Something went wrong.
  | boost::thread_interrupted |

Precondition:
  initiated()

Postcondition:
  getStream() == -1

Implemented in Passenger::StandardSession.

virtual void Passenger::Session::discardStream | ( |  | ) | `[pure virtual]`

Discard the I/O channel's file descriptor, so that the destructor won't automatically close it.

Precondition:
  initiated()

Postcondition:
  getStream() == -1

Implemented in Passenger::StandardSession.

const string Passenger::Session::getConnectPassword | ( |  | ) | const`[inline]`

Returns this session's process's connect password.

This password is guaranteed to be valid ASCII.

virtual string Passenger::Session::getSocketName | ( |  | ) | const`[pure virtual]`

Returns the address of the socket that this session is served from.

This can be a Unix socket filename or a TCP host:port string like "127.0.0.1:1234".

Postcondition:
  !result.empty()

Implemented in Passenger::StandardSession.

virtual string Passenger::Session::getSocketType | ( |  | ) | const`[pure virtual]`

Returns the type of the socket that this session is served from, e.g.

"unix" indicating a Unix socket.

Postcondition:
  !result.empty()

Implemented in Passenger::StandardSession.

virtual int Passenger::Session::getStream | ( |  | ) | const`[pure virtual]`

Returns this session's channel's file descriptor.

This stream is full-duplex, and will be automatically closed upon Session's destruction, unless discardStream() is called.

Precondition:
  initiated()

Returns:
  The file descriptor, or -1 if the I/O channel has already been closed or discarded.

Implemented in Passenger::StandardSession.

virtual void Passenger::Session::initiate | ( |  | ) | `[pure virtual]`

Initiate the session by connecting to the associated process.

A Session is not usable until it's initiated.

Exceptions:

  | SystemException | Something went wrong.
  | IOException | Something went wrong.
  | boost::thread_interrupted |

Implemented in Passenger::StandardSession.

virtual void Passenger::Session::sendBodyBlock | ( | const char * | block,
|  | unsigned int | size |
| ) |  |  | `[inline, virtual]`

Send a chunk of HTTP request body data to the application.

You can call this method as many times as is required to transfer the entire HTTP request body.

This method must only be called after a sendHeaders(), otherwise strange things may happen.

Parameters:

  | block | A block of HTTP request body data to send.
  | size | The size, in bytes, of `block`.

Precondition:
  initiated()

Exceptions:

  | IOException | The I/O channel has already been closed or discarded.
  | SystemException | Something went wrong during writing.
  | boost::thread_interrupted |

virtual void Passenger::Session::sendHeaders | ( | const StaticString & | headers | ) | `[inline, virtual]`

Convenience shortcut for sendHeaders(const char *, unsigned int).

Parameters:

  | headers | The headers

Precondition:
  initiated()

Exceptions:

  | IOException | The I/O channel has already been closed or discarded.
  | SystemException | Something went wrong during writing.
  | boost::thread_interrupted |

virtual void Passenger::Session::sendHeaders | ( | const char * | headers,
|  | unsigned int | size |
| ) |  |  | `[inline, virtual]`

Send HTTP request headers to the application.

The HTTP headers must be converted into CGI headers, and then encoded into a string that matches this grammar:

    	   headers ::= header*
    	   header ::= name NUL value NUL
    	   name ::= notnull+
    	   value ::= notnull+
    	   notnull ::= "\x01" | "\x02" | "\x02" | ... | "\xFF"
    	   NUL = "\x00"

There must be a header with the name "PASSWORD_CONNECT_PASSWORD", and it must have the same value as the string returned by getConnectPassword().

This method should be the first one to be called during the lifetime of a Session object, otherwise strange things may happen.

Parameters:

  | headers | The HTTP request headers, converted into CGI headers and encoded as a string, according to the description.
  | size | The size, in bytes, of `headers`.

Precondition:
  headers != NULL
  initiated()

Exceptions:

  | IOException | The I/O channel has already been closed or discarded.
  | SystemException | Something went wrong during writing.
  | boost::thread_interrupted |

virtual void Passenger::Session::setReaderTimeout | ( | unsigned int | msec | ) | `[pure virtual]`

Set the timeout value for reading data from the I/O channel.

If no data can be read within the timeout period, then the read call will fail with error EAGAIN or EWOULDBLOCK.

Precondition:
  The I/O channel hasn't been closed or discarded.
  initiated()

Parameters:

  | msec | The timeout, in milliseconds. If 0 is given, there will be no timeout.

Exceptions:

  | SystemException | Cannot set the timeout.

Implemented in Passenger::StandardSession.

virtual void Passenger::Session::setWriterTimeout | ( | unsigned int | msec | ) | `[pure virtual]`

Set the timeout value for writing data from the I/O channel.

If no data can be written within the timeout period, then the write call will fail with error EAGAIN or EWOULDBLOCK.

Precondition:
  The I/O channel hasn't been closed or discarded.
  initiated()

Parameters:

  | msec | The timeout, in milliseconds. If 0 is given, there will be no timeout.

Exceptions:

  | SystemException | Cannot set the timeout.

Implemented in Passenger::StandardSession.

virtual void Passenger::Session::shutdownReader | ( |  | ) | `[pure virtual]`

Indicate that we don't want to read data anymore from the I/O channel.

Calling this method after closeStream()/discardStream() is called will have no effect.

Precondition:
  initiated()

Exceptions:

  | SystemException | Something went wrong.
  | boost::thread_interrupted |

Implemented in Passenger::StandardSession.

virtual void Passenger::Session::shutdownWriter | ( |  | ) | `[pure virtual]`

Indicate that we don't want to write data anymore to the I/O channel.

Calling this method after closeStream()/discardStream() is called will have no effect.

Precondition:
  initiated()

Exceptions:

  | SystemException | Something went wrong.
  | boost::thread_interrupted |

Implemented in Passenger::StandardSession.

The documentation for this class was generated from the following file:

- Session.h