mirror of https://gitee.com/bigwinds/arangodb
Rmoved old Foxx Bubdled Apps Documentation. Will be displayed elsewhere
This commit is contained in:
Michael Hackstein
parent
9e3d29e722
commit
40ea11ab45
|
|
@ -1,3 +0,0 @@
|
|||
!CHAPTER Bundled Foxx Applications
|
||||
|
||||
ArangoDB ships with a number of Foxx apps that allow you to implement basic authentication and user management with minimal effort.
|
||||
|
|
@ -1,209 +0,0 @@
|
|||
!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.
|
||||
|
|
@ -1,49 +0,0 @@
|
|||
!CHAPTER The Simple Authentication App
|
||||
|
||||
The simple auth app provides hashed password-based authentication with automatically generated salts and constant-time password verification.
|
||||
|
||||
!SECTION Configuration
|
||||
|
||||
This app has the following configuration options:
|
||||
|
||||
* *saltLength* (optional): length of newly generated salts. Default: *16*.
|
||||
* *hashMethod* (optional): hash algorithm to use. Supported values: *sha1*, *sha224*, *sha256*, *md5*. Default: *"sha256"*.
|
||||
|
||||
!SECTION JavaScript API: *auth*
|
||||
|
||||
This app exposes its functionality via a JavaScript API named *auth*.
|
||||
|
||||
@EXAMPLES
|
||||
|
||||
```js
|
||||
var auth = Foxx.requireApp('/_system/simple-auth').auth;
|
||||
```
|
||||
|
||||
!SUBSECTION Generate an authentication object
|
||||
|
||||
Generates an authentication object for a given password.
|
||||
|
||||
`auth.hashPassword(password)`
|
||||
|
||||
Returns an authentication object with the following properties:
|
||||
|
||||
* *hash*: the generated hex-encoded hash.
|
||||
* *salt*: the salt used to generate the hash.
|
||||
* *method*: the algorithm used to generate the hash.
|
||||
|
||||
*Parameter*
|
||||
|
||||
* *password*: the password to hash.
|
||||
|
||||
!SUBSECTION Verify a password
|
||||
|
||||
Verifies a password against a given authentication object.
|
||||
|
||||
`auth.verifyPassword(authData, password)`
|
||||
|
||||
Generates a hash for the given password using the *salt* and *method* stored in the authentication object and performs a constant time string comparison on them. Returns *true* if the password is valid or *false* otherwise.
|
||||
|
||||
*Parameter*
|
||||
|
||||
* *authData*: an authentication object.
|
||||
* *password*: a password to verify.
|
||||
|
|
@ -1,187 +0,0 @@
|
|||
!CHAPTER The Users App
|
||||
|
||||
The users app provides a username-based user storage JavaScript API that can be used in other Foxx apps.
|
||||
|
||||
!SECTION JavaScript API: *userStorage*
|
||||
|
||||
This app exposes a user storage via a JavaScript API named *userStorage*.
|
||||
|
||||
@EXAMPLES
|
||||
|
||||
```js
|
||||
var userStorage = Foxx.requireApp('/_system/users').userStorage;
|
||||
```
|
||||
|
||||
!SUBSECTION Exceptions
|
||||
|
||||
!SUBSUBSECTION User Not Found
|
||||
|
||||
Indicates a user could not be found in the database.
|
||||
|
||||
`new userStorage.errors.UserNotFound(userId)`
|
||||
|
||||
Thrown by the user storage's *delete* and *get* methods if passed a user ID that does not exist in the database.
|
||||
|
||||
@EXAMPLES
|
||||
|
||||
```js
|
||||
try {
|
||||
userStorage.get(invalidUserId);
|
||||
} catch(err) {
|
||||
assertTrue(err instanceof userStorage.errors.UserNotFound);
|
||||
}
|
||||
```
|
||||
|
||||
!SUBSUBSECTION Username Not Available
|
||||
|
||||
Indicates a username is already in use.
|
||||
|
||||
`new userStorage.errors.UsernameNotAvailable(username)`
|
||||
|
||||
Thrown by the user storage's *create* method if passed a *userData* object with a *username* that is already in use.
|
||||
|
||||
@EXAMPLES
|
||||
|
||||
```js
|
||||
try {
|
||||
userStorage.create('alreadyTaken', {some: 'data'});
|
||||
} catch(err) {
|
||||
assertTrue(err instanceof userStorage.errors.UsernameNotAvailable);
|
||||
}
|
||||
```
|
||||
|
||||
!SUBSECTION The user object
|
||||
|
||||
User objects are instances of a Foxx model with the following attributes:
|
||||
|
||||
* *user*: the user's unique *username*.
|
||||
* *userData*: application-specific user data.
|
||||
* *authData*: an arbitrary object used by authentication apps to store sensitive data. For password authentication this could be a hash, for third-party authentication services this could be information about the user's identity. This attribute should never be exposed to the user directly.
|
||||
|
||||
!SUBSECTION Create a user
|
||||
|
||||
Creates and saves a new instance of the user model.
|
||||
|
||||
`userStorage.create(username, [userData,] [authData])`
|
||||
|
||||
Throws *UsernameNotAvailable* if a user with the given username already exists.
|
||||
|
||||
**Note:** When using the system users app (mounted at */\_system/users*), new users will automatically have their *active* flag set to *true* if no value is provided in the *authData* (or if *authData* is omitted entirely).
|
||||
|
||||
*Parameter*
|
||||
|
||||
* *username*: an arbitrary string that will be used as the user's username
|
||||
* *userData* (optional): an arbitrary object that will be stored as the user's *userData* attribute when the model is saved to the database.
|
||||
* *authData* (optional): an arbitrary object that will be stored as the user's *authData* attribute when the model is saved to the database.
|
||||
|
||||
@EXAMPLES
|
||||
|
||||
```js
|
||||
var user = userStorage.create('malaclypse', {hair: 'fuzzy'});
|
||||
assertEqual(user.get('userData').hair, 'fuzzy');
|
||||
```
|
||||
|
||||
!SUBSECTION Fetch an existing user
|
||||
|
||||
There are two ways to fetch a user via the user storage API:
|
||||
|
||||
* resolving a *username* with the user storage's *resolve* method
|
||||
* calling the user storage's *get* method with a user ID directly
|
||||
|
||||
!SUBSUBSECTION Resolve a *username*
|
||||
|
||||
Fetches a user with a given *username*.
|
||||
|
||||
`userStorage.resolve(username)`
|
||||
|
||||
If the username can not be resolved, a *UserNotFound* exception will be thrown instead.
|
||||
|
||||
*Parameter*
|
||||
|
||||
* *username*: an arbitrary string matching the username of the user you are trying to fetch.
|
||||
|
||||
@EXAMPLES
|
||||
|
||||
```js
|
||||
var user = userStorage.resolve('malaclypse');
|
||||
assertEqual(user.user, 'malaclypse');
|
||||
```
|
||||
|
||||
!SUBSUBSECTION Resolve a user ID directly
|
||||
|
||||
Fetches a user with a given ID.
|
||||
|
||||
`userStorage.get(userId)`
|
||||
|
||||
Attempts to fetch the user with the given ID from the database. If the user does not exist, a *UserNotFound* exception will be thrown instead.
|
||||
|
||||
*Parameter*
|
||||
|
||||
* *userId*: a user *_key*.
|
||||
|
||||
@EXAMPLES
|
||||
|
||||
```js
|
||||
var user = userStorage.get(userId);
|
||||
assertEqual(user.get('_key'), userId);
|
||||
```
|
||||
|
||||
!SUBSECTION Delete a user
|
||||
|
||||
There are two ways to delete a user from the database:
|
||||
|
||||
* calling the user storage's *delete* method with a user ID directly
|
||||
* telling a user to delete itself
|
||||
|
||||
!SUBSUBSECTION Delete a user by its ID
|
||||
|
||||
Delete a user with a given ID.
|
||||
|
||||
`userStorage.delete(userId)`
|
||||
|
||||
Attempts to delete the user with the given user ID from the database. If the user does not exist, a *UserNotFound* exception will be thrown. The method always returns *null*.
|
||||
|
||||
*Parameter*
|
||||
|
||||
* *userId*: a user *_key*.
|
||||
|
||||
@EXAMPLES
|
||||
|
||||
```js
|
||||
userStorage.delete(userId);
|
||||
```
|
||||
|
||||
!SUBSUBSECTION Tell a user to delete itself
|
||||
|
||||
Delete a user from the database.
|
||||
|
||||
`user.delete()`
|
||||
|
||||
Attempts to delete the user from the database.
|
||||
|
||||
Returns *true* if the user was deleted successfully.
|
||||
|
||||
Returns *false* if the user already didn't exist.
|
||||
|
||||
@EXAMPLES
|
||||
|
||||
```js
|
||||
var user = userStorage.get(userId);
|
||||
user.delete();
|
||||
```
|
||||
|
||||
!SUBSECTION Save a user
|
||||
|
||||
Save a user to the database.
|
||||
|
||||
`user.save()`
|
||||
|
||||
In order to commit changes made to the user in your code, you need to call this method.
|
||||
|
||||
@EXAMPLES
|
||||
|
||||
```js
|
||||
var userData = user.get('userData');
|
||||
userData.counter++;
|
||||
user.save();
|
||||
```
|
||||
Loading…
Reference in New Issue