Session Storage

Session storage is a limited, server-side, semi-permanent store for keeping state information across web requests. The HTTP protocol by design, encourages stateless implementations and so session state storage provides an essential context for a series of requests by a specific client.

ESP provides a high performance, in-process session state store. The store is managed in that ESP imposes a session timeout on information and will automatically prune stale information. It uses the memory limit configured by the http.limits directive to restrict the amount of memory that is devoted to session state.

Sample Code

if (!(id = getSessionVar("user-id")) != 0) {
    redirect("/login");
}

You can also use the abbreviated API form: session()

if (!(id = session("user-id")) != 0) {
    redirect("/login");
}

This example (above) tests if a "user-id" is defined in the session store. If not, the user must login and is redirect to the login page.

destroySession();
createSession();

This forces the creation of a new session.

setSessionVar("Name", "John");

This defines the "Name" variable to the value "John".

ESP APIs

The ESP session state API is comprised of four key APIs:

• createSession
• destroySession
• getSessionVar
• setSessionVar

Client Feedback

Controllers often need to provide out-of-band feedback to the client. This may be a simple notification that a record has been updated or deleted. Or it may be details of an error condition. ESP provides a simple feedback API to send such messages to the client.

Feedback Types

Feedback messages are divided into different types:

• Errors — An error occurred and the operation failed.
• Warnings — A warning has been issued, but the operation succeeded.
• Informational — The operation succeeded and this is just for feedback.
• Other — Any other kind of message.

When ESP generates feedback messages in a web page, it emits a CSS style corresponding to the message type. This permits all errors to be flagged to the user using an "error" style. Similarly, for warnings and informational errors.

Defining Feedback Messages

To issue a flash message for the next web page, use the feedback API.

feedback("inform", Document saved");
feedback("warn", "Session is about to expire in %d seconds", seconds);
feedback("error", "Could not save document");
feedback("custom", "Error code %d", code);

To read a feedback message, use getFlash:

char *msg = getFeedback("inform");

If you need to pass a message from the controller into the next controller, use the flash message facility below.

Displaying Feedback Messages

To display feedback messages in a web page, use the renderFeedback API.

<% renderFeedback("all"); %>

This will display all feedback messages.

Configuring Session

Session data has a lifespan defined by the http.timeouts configuration directive. When this timeout expires, ESP will prune the data from the session store.

If there is a low memory condition, ESP may prune session data prematurely to free up memory. The maximum memory limit may be configured by the http.limits configuration directive.

Performance Considerations

Minimize Session Data Size

To maximize the performance of your application, try to minimize the size of data stored in the session state store. Session data is copied to and from the store. Unnecessary copies will slow your application.

Minimize Session Data Reads and Writes

It is important not to read from the session store repeatedly. During one request, try to read session data once and keep a reference to the data for the duration of that request.

Session Expiry Callbacks

Because session data may be stored remotely, ESP does not offer a callback when session state expires. Rather, you can test if session state has expired by calling espGetSessionID.

The best design is to run a client-side session expiry inactivity timer which warns the user when the session is about to expire.