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:

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:

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.

Flash Storage

ESP also provides a layer over session storage called "flash" storage that is useful for passing information into the next controller and request action. Thereafter, the flash information is automatically removed. Using bare session state for this is problematic as the message can easily propagate to subsequent requests other than the immediate next request. Flash messages will be automatically removed message after the next request. Flash messages can thus be used to pass feedback messages into the next request, even the current request issues a redirection response to the current request.

Defining Flash Messages

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

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

To read a flash message, use getFlash:

char *msg = getFlash("inform");

If you only need to pass a message from the controller into the view page, then feedback messages above are a better choice.

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.

© Embedthis Software, 2003-2015. All rights reserved.