!CHAPTER The Sessions App

The sessions app provides a session storage JavaScript API that can be used in other Foxx apps.

!SECTION Configuration

This app has the following configuration options:

* *timeToLive* (optional): number of milliseconds until the session expires or *0* to disable session expiry. Default: *604800000* (one week).
* *ttlType* (optional): attribute against which the *timeToLive* is enforced. Valid options: *lastAccess*, *lastUpdate*, *created*. Default: *"created"*.
* *sidTimestamp* (optional): whether to append a timestamp to the random part of generated session IDs. Default: *false*.
* *sidLength* (optional): number of random characters to use for new session IDs. Default *20*.

!SECTION JavaScript API: *sessionStorage*

This app exposes a session storage via a JavaScript API named *sessionStorage*.

@EXAMPLES

```js
var sessionStorage = Foxx.requireApp('/_system/sessions').sessionStorage;
```

!SUBSECTION Exceptions

!SUBSUBSECTION Session Not Found

Indicates a session could not be found in the database.

`new sessionStorage.errors.SessionNotFound(sessionId)`

Thrown by the session storage's *delete* and *get* methods if passed a session ID that does not exist in the database.

@EXAMPLES

```js
try {
    sessionStorage.get(invalidSessionId);
} catch(err) {
    assertTrue(err instanceof sessionStorage.errors.SessionNotFound);
}
```

!SUBSUBSECTION Session Expired

Indicates the session exists in the database but has expired.

`new sessionStorage.errors.SessionExpired(sessionId)`

Thrown by the session storage's *get* method if passed a session ID for a session that has expired. See also this app's configuration options.

@EXAMPLES

```js
try {
    sessionStorage.get(expiredSessionId);
} catch(err) {
    assertTrue(err instanceof sessionStorage.errors.SessionExpired);
    assertTrue(err instanceof sessionStorage.errors.SessionNotFound);
}
```

!SUBSECTION The session object

Session objects are instances of a Foxx model with the following attributes:

* *sessionData*: volatile session data. This can be an arbitrary object that will be stored with the session in the database. If you want to store session-specific (rather than user-specific) data in the database, this is the right place for that.
* *uid*: the session's active user's *_key* or *undefined* (no active user).
* *userData*: the session's active user's *userData* attribute or an empty object.
* *created*: timestamp the session was created at.
* *lastAccess*: timestamp of the last time the session was fetched from the database.
* *lastUpdate*: timestamp of the last time the session was written to the database.

!SUBSECTION Create a session

Creates and saves a new instance of the session model.

`sessionStorage.create(sessionData)`

*Parameter*

* *sessionData* (optional): an arbitrary object that will be stored as the session's *sessionData* attribute when the model is saved to the database.

@EXAMPLES

```js
var session = sessionStorage.create(sessionData);
assertEqual(session.get('sessionData'), sessionData);
```

!SUBSECTION Fetch an existing session

Fetch a session from the database for a given ID.

`sessionStorage.get(sessionId)`

Attempts to load the session with the given session ID from the database. If the session does not exist, a *SessionNotFound* exception will be thrown. If the session does exist, but has already expired, a *SessionExpired* exception will be thrown instead.

*Parameter*

* *sessionId*: a session *_key*.

@EXAMPLES

```js
var session = sessionStorage.get(sessionId);
```

!SUBSECTION Delete a session

There are two ways to delete a session from the database:

* calling the session storage's *delete* method with a session ID directly
* telling a session to delete itself

!SUBSUBSECTION Delete a session by its ID

Delete a session with a given ID.

`sessionStorage.delete(sessionId)`

Attempts to delete the session with the given session ID from the database. If the session does not exist, a *SessionNotFound* exception will be thrown. The method always returns *null*.

*Parameter*

* *sessionId*: a session *_key*.

@EXAMPLES

```js
sessionStorage.delete(sessionId);
```

!SUBSUBSECTION Tell a session to delete itself

Delete a session from the database.

`session.delete()`

Attempts to delete the session from the database.

Returns *true* if the session was deleted successfully.

Returns *false* if the session already didn't exist.

@EXAMPLES

```js
session.delete();
```

!SUBSECTION Save a session

Save a session to the database.

`session.save()`

If you made any changes to the session and are not using the sessions app via Foxx Authentication, you must call this method to commit the changes to the database.

@EXAMPLES

```js
session.setUser(user);
session.save();
```

!SUBSECTION Set a session's active user

Set the active user of a session.

`session.setUser(user)`

Expects a Foxx model with a *userData* attribute and sets the session's *uid* attribute to the model's *_key* and the session's *userData* attribute to the model's *userData* attribute.

*Parameter*

* *user*: instance of a Foxx model with a *`userData* attribute.

@EXAMPLES

```js
session.setUser(user);
assertEqual(session.get('uid'), user.get('_key'));
assertEqual(session.get('userData'), user.get('userData'));
```

!SUBSECTION Determine whether a session has expired

Get a session's expiry state.

`session.hasExpired()`

Returns *true* if the session's expiry time lies in the past, *false* otherwise.

!SUBSECTION Determine when a session will expire

Get a session's expiry time.

`session.getExpiry()`

Returns an integer representing the UTC timestamp in milliseconds at which the session will expire, or *Infinity* (indicating the session will never expire) if session expiry is disabled.

!SUBSECTION Determine the TTL of a session

Get a session's time to live.

`session.getTTL()`

Returns an integer representing number of milliseconds until the session will expire, or *Infinity* (indicating the session will never expire) if session expiry is disabled.