mirror of https://gitee.com/bigwinds/arangodb
210 lines
5.9 KiB
Plaintext
210 lines
5.9 KiB
Plaintext
!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.
|