Docs: accounts-base / accounts_common.js

docs/accounts-base/README.md

@@ -2,10 +2,21 @@
 
 ## Files documented
 
+* accounts_common.js
+* accounts_rate_limit.js
+* globals_client.js
+* globals_server.js
 * package.js
 * url_client.js
 * url_server.js
 
+## Constants
+
+* `DEFAULT_LOGIN_EXPIRATION_DAYS` = 90. Default login token lifetime. Used by `AccountsCommon_getTokenLifetimeMs()`.
+* `MIN_TOKEN_LIFETIME_CAP_SECS` = 3600. Maximum value of "soon". Used by `AccountsCommon._tokenExpiresSoon(when)`.
+* `EXPIRE_TOKENS_INTERVAL_MS` = 100000. Frequency of token expiration checks. Used by `setExpireTokensInterval(accounts)` in `accounts_server.js`.
+* `CONNECTION_CLOSE_DELAY_MS` = 10000. Logout delay for other clients. Used by `Meteor.logoutOtherClients()`, added from `accounts_server.js`.
+
 ## Classes
 
 ### `AccountsClient`
@@ -24,6 +35,52 @@
         * `defaultSuccessHandler()`
         * `attemptToMatchHash()`
 
+### `AccountsCommon` (`accounts_common.js`)
+
+Base class for `AccountsClient` / `AccountsServer`.
+
+* `constructor(options)`.
+  * initializes `connection`, then `users`.
+  * Options can contain:
+    * `connection`, `ddpUrl` see `initConnection()`
+    * `sendVerificationEmail`, `forbidClientAccountCreation`, `restrictCreationByEmailDomain`, `loginExpirationInDays`, and `oauthSecretKey` (side-effect, not saved). see `config(options)`
+* `addDefaultRateLimit()` : enable per-connection, per-method rate limiter for `login`, `createUser`, `resetPassword` `forgotPassword` to 5 calls every 10 seconds. Added from `accounts_rate_limits.js`.
+* `config(options)`. Set up config for the accounts system. Call this on both the client the server.
+    * Checks and filters options, before saving them to `_options`.
+    * Setting an unknown option throws
+    * Setting an already set option throws
+    * Options can contain:
+        * `sendVerificationEmail` {Boolean}: Send email address verification emails to new users created from client signups.
+        * `forbidClientAccountCreation` {Boolean} Do not allow clients to create accounts directly. [Security issue #828](https://github.com/meteor/meteor/issues/828) exists if this is not called on both client and server
+        * `restrictCreationByEmailDomain` {Function or String} Require created users to have an email matching the function or having the string as domain.
+        * `loginExpirationInDays` {Number} Number of days since login until a user is logged out (login token expires).
+        * `oauthSecretKey` When using the `oauth-encryption` package, the 16 byte key using to encrypt sensitive account credentials in the database, encoded in base64.
+            * Warns if the `oauth-encryption` package is not present
+            * Throws if used on client
+            * Removed from saved config after passing if to the `oauth-encryption` package
+* `ConfigError`: legacy, initialized from `service-configuration` package during `Meteor.startup()`.
+* `connection`: the MongoDB connection. If set to null, the `users` collection will be local (avoid !)
+* `LoginCancelledError`: specific error class to use when a login sequence is cancelled
+* `loginServiceConfiguration`: legacy, initialized from `service-configuration` package during `Meteor.startup()`.
+* `removeDefaultRateLimit()` : disable the rate limiter for the methods below (from `accounts_rate_limits.js`).
+* `user()`: returns the currently logged-in user by finding it from Mongo based on the `userId()` value. Defaults to `null`.
+* `userId()`: `Error("userId method not implemented")` Basically an abstract method to be refined in child classes
+* `users`: the users collection
+* `onLogin(func)`: Register a callback to be called after a login attempt succeeds.
+* `onLoginFailure(func)`: Register a callback to be called after a login attempt fails.
+* `_getTokenLifetimeMs()`: get the remaining login token lifetime in msec. Taken from `loginExpirationInDays` if it exists. Defaults to `DEFAULT_LOGIN_EXPIRATION_DAYS` (= 90) days in msec.
+* `_initConnection(options)` - Options can contain
+    * `connection`: the connection on which to load the `users` collection
+    * `ddpUrl`: if connection is not set, connect to this URL
+    * some non-portable, going-away, mechanism for OAuth
+    * if none if available, `Meteor.connection` will be used as a default
+* `_onLoginHook()`. As per hook.js, Hook system is under development. Use `onLogin(func)` to make use of it.
+* `_onLoginFailureHook()`. As per hook.js, Hook system is under development. Use `onLoginFailure(func)` to make use of it.
+* `_options = {}` - used directly by packages like `accounts-password` and `accounts-ui-unstyled.
+* `_tokenExpiration(when)`: `when` is a token (timestamp, used to be any number in earlier versions). It is converted to Date, and added with `_getTokenLifetimeMs()` to return the expiration date for the `when`.
+* `_tokenExpiresSoon(when)`: `when`  is a token (timestamp). True if it expires in less the smaller of `0.1 * _getTokenLifetimeMs()`and 1 hour.
+* **side-effect** in `accounts_rate_limits.js`  : loading this file initializes the rate-limiter for `addDefaultRateLimit()` and `removeDefaultRateLimit()`. This is why the package has a dependency on `ddp-rate-limiter`.
+
 ### `AccountsServer`
 
 * methods. These 3 methods are public but marked (in 1.2.1) as likely not to remain so
@@ -38,6 +95,11 @@
     * Globals read
        * `Accounts` (see `globals_server.js`)
 
+### Meteor
+
+* `userId`: a copy of the `Accounts.usedId()` method
+* `user()`: a copy of the `Accounts.user()` method
+
 ## Functions
 
 ### `url_client.js`