Overhaul of Parse Server Guide

_includes/common/performance.md

@@ -35,8 +35,8 @@ Take a look at the following query to retrieve GameScore objects:
 
 {% if page.language == "js" %}
 ```javascript
-var GameScore = Parse.Object.extend("GameScore");
-var query = new Parse.Query(GameScore);
+const GameScore = Parse.Object.extend("GameScore");
+const query = new Parse.Query(GameScore);
 query.equalTo("score", 50);
 query.containedIn("playerName",
     ["Jonathan Walsh", "Dario Wunsch", "Shawn Simon"]);
@@ -181,8 +181,8 @@ For example, let's say you're tracking high scores for a game in a GameScore cla
 
 {% if page.language == "js" %}
 ```javascript
-var GameScore = Parse.Object.extend("GameScore");
-var query = new Parse.Query(GameScore);
+const GameScore = Parse.Object.extend("GameScore");
+const query = new Parse.Query(GameScore);
 query.notEqualTo("playerName", "Michael Yabuti");
 query.find().then(function(results) {
   // Retrieved scores successfully
@@ -269,7 +269,7 @@ For example if the User class has a column called state which has values “Sign
 
 {% if page.language == "js" %}
 ```javascript
-var query = new Parse.Query(Parse.User);
+const query = new Parse.Query(Parse.User);
 query.notEqualTo("state", "Invited");
 ```
 {% endif %}

_includes/common/security.md

@@ -547,10 +547,13 @@ The master key should be used carefully. setting `useMasterKey` to `true` only i
 
 ```js
 Parse.Cloud.define("like", async request => {
-  var post = new Parse.Object("Post");
+  const post = new Parse.Object("Post");
   post.id = request.params.postId;
   post.increment("likes");
   await post.save(null, { useMasterKey: true })
+}, {
+  fields: ['postId'],
+  requireUser: true
 });
 ```
 

_includes/parse-server/adapters.md

@@ -0,0 +1,7 @@
+# Adapters
+
+All official adapters are distributed as scoped pacakges on [npm (@parse)](https://www.npmjs.com/search?q=scope%3Aparse).
+
+Some adapters are also available on the [Parse Server Modules](https://github.com/parse-server-modules) organization.
+
+You can also find more adapters maintained by the community by searching on [npm](https://www.npmjs.com/search?q=parse-server%20adapter&page=1&ranking=optimal).

_includes/parse-server/bleeding-edge.md

@@ -0,0 +1,9 @@
+# Want to ride the bleeding edge?
+
+It is recommend to use builds deployed to npm for many reasons, but if you want to use
+the latest not-yet-released version of parse-server, you can do so by depending
+directly on this branch:
+
+```
+npm install parse-community/parse-server.git#master
+```

_includes/parse-server/configuration.md

@@ -0,0 +1,209 @@
+# Configuration
+
+Parse Server can be configured using the following options. You may pass these as parameters when running a standalone `parse-server`, or by loading a configuration file in JSON format using `parse-server path/to/configuration.json`. If you're using Parse Server on Express, you may also pass these to the `ParseServer` object as options.
+
+For the full list of available options, run `parse-server --help` or take a look at [Parse Server Configurations](http://parseplatform.org/parse-server/api/master/ParseServerOptions.html).
+
+## Basic Options
+
+* `appId`: A unique identifier for your app.
+* `databaseURI`: Connection string URI for your MongoDB.
+* `cloud`: Path to your app’s Cloud Code.
+* `masterKey`: A key that overrides all permissions. Keep this secret.
+* `serverURL`: URL to your Parse Server (don't forget to specify http:// or https://). This URL will be used when making requests to Parse Server from Cloud Code.
+* `port`: The default port is 1337, specify this parameter to use a different port.
+* `push`: An object containing push configuration. See [Push](#push-notifications)
+* `auth`: Configure support for [3rd party authentication](#oauth-and-3rd-party-authentication).
+
+For the full list of available options, run `parse-server --help` or refer to [Parse Server Options](https://parseplatform.org/parse-server/api/master/ParseServerOptions.html) for a complete list of configuration options.
+
+The Parse Server object was built to be passed directly into `app.use`, which will mount the Parse API at a specified path in your Express app:
+
+```js
+const express = require('express');
+const ParseServer = require('parse-server').ParseServer;
+
+const app = express();
+const api = new ParseServer({ ... });
+
+// Serve the Parse API at /parse URL prefix
+app.use('/parse', api);
+
+var port = 1337;
+app.listen(port, function() {
+  console.log('parse-server-example running on port ' + port + '.');
+});
+```
+
+And with that, you will have a Parse Server running on port 1337, serving the Parse API at `/parse`.
+
+## Additional Options
+
+### Email verification and password reset
+
+Verifying user email addresses and enabling password reset via email requires an email adapter.
+
+You can also use email adapters contributed by the community such as:
+- [parse-server-mailgun-adapter-template](https://www.npmjs.com/package/parse-server-mailgun-adapter-template)
+- [parse-smtp-template (Multi Language and Multi Template)](https://www.npmjs.com/package/parse-smtp-template)
+- [parse-server-postmark-adapter](https://www.npmjs.com/package/parse-server-postmark-adapter)
+- [parse-server-sendgrid-adapter](https://www.npmjs.com/package/parse-server-sendgrid-adapter)
+- [parse-server-mandrill-adapter](https://www.npmjs.com/package/parse-server-mandrill-adapter)
+- [parse-server-simple-ses-adapter](https://www.npmjs.com/package/parse-server-simple-ses-adapter)
+- [parse-server-sendinblue-adapter](https://www.npmjs.com/package/parse-server-sendinblue-adapter)
+- [parse-server-mailjet-adapter](https://www.npmjs.com/package/parse-server-mailjet-adapter)
+- [simple-parse-smtp-adapter](https://www.npmjs.com/package/simple-parse-smtp-adapter)
+- [parse-server-generic-email-adapter](https://www.npmjs.com/package/parse-server-generic-email-adapter)
+
+The Parse Server Configuration Options relating to email verifcation are:
+
+* `verifyUserEmails`: whether the Parse Server should send mail on user signup
+* `emailVerifyTokenValidityDuration`: how long the email verify tokens should be valid for
+* `emailVerifyTokenReuseIfValid`: whether an existing token should be resent if the token is still valid
+* `preventLoginWithUnverifiedEmail`: whether the Parse Server should prevent login until the user verifies their email
+* `publicServerURL`: The public URL of your app. This will appear in the link that is used to verify email addresses and reset passwords.
+* `appName`: Your apps name. This will appear in the subject and body of the emails that are sent.
+* `emailAdapter`: The email adapter.
+
+```js
+const api = ParseServer({
+  ...otherOptions,
+  verifyUserEmails: true,
+  emailVerifyTokenValidityDuration: 2 * 60 * 60, // in seconds (2 hours = 7200 seconds)
+  preventLoginWithUnverifiedEmail: false, // defaults to false
+  publicServerURL: 'https://example.com/parse',
+  appName: 'Parse App',
+  emailAdapter: {
+    module: '@parse/simple-mailgun-adapter',
+    options: {
+      fromAddress: 'parse@example.com',
+      domain: 'example.com',
+      apiKey: 'key-mykey',
+    }
+  },
+});
+```
+Note:
+
+* If `verifyUserEmails` is `true` and if `emailVerifyTokenValidityDuration` is `undefined` then email verify token never expires. Else, email verify token expires after `emailVerifyTokenValidityDuration`.
+
+### Account Lockout
+
+Account lockouts prevent login requests after a defined number of failed password attempts. The account lock prevents logging in for a period of time even if the correct password is entered.
+
+If the account lockout policy is set and there are more than `threshold` number of failed login attempts then the `login` api call returns error code `Parse.Error.OBJECT_NOT_FOUND` with error message `Your account is locked due to multiple failed login attempts. Please try again after <duration> minute(s)`.
+
+After `duration` minutes of no login attempts, the application will allow the user to try login again.
+
+*`accountLockout`: Object that contains account lockout rules
+*`accountLockout.duration`: Determines the number of minutes that a locked-out account remains locked out before automatically becoming unlocked. Set it to a value greater than 0 and less than 100000.
+*`accountLockout.threshold`: Determines the number of failed sign-in attempts that will cause a user account to be locked. Set it to an integer value greater than 0 and less than 1000.
+
+```js
+const api = ParseServer({
+  ...otherOptions,
+  accountLockout: {
+    duration: 5,
+    threshold: 3
+  }
+});
+```
+
+### Password Policy
+
+Password policy is a good way to enforce that users' passwords are secure.
+
+Two optional settings can be used to enforce strong passwords. Either one or both can be specified.
+
+If both are specified, both checks must pass to accept the password
+
+1. `passwordPolicy.validatorPattern`: a RegExp object or a regex string representing the pattern to enforce
+2. `passwordPolicy.validatorCallback`: a callback function to be invoked to validate the password
+
+The full range of options for Password Policy are:
+
+*`passwordPolicy` is an object that contains the following rules:
+*`passwordPolicy.validationError`: optional error message to be sent instead of the default "Password does not meet the Password Policy requirements." message.
+*`passwordPolicy.doNotAllowUsername`: optional setting to disallow username in passwords
+*`passwordPolicy.maxPasswordAge`: optional setting in days for password expiry. Login fails if user does not reset the password within this period after signup/last reset.
+*`passwordPolicy.maxPasswordHistory`: optional setting to prevent reuse of previous n passwords. Maximum value that can be specified is 20. Not specifying it or specifying 0 will not enforce history.
+*`passwordPolicy.resetTokenValidityDuration`: optional setting to set a validity duration for password reset links (in seconds)
+*`passwordPolicy.resetTokenReuseIfValid`: optional setting to resend current token if it's still valid
+
+```js
+const validatePassword = password => {
+  if (!password) {
+    return false;
+  }
+  if (password.includes('pass')) {
+    return false;
+  }
+  return true;
+}
+const api = ParseServer({
+  ...otherOptions,
+  passwordPolicy: {
+    validatorPattern: /^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])(?=.{8,})/, // enforce password with at least 8 char with at least 1 lower case, 1 upper case and 1 digit
+    validatorCallback: (password) => { return validatePassword(password) },
+    validationError: 'Password must contain at least 1 digit.',
+    doNotAllowUsername: true,
+    maxPasswordAge: 90,
+    maxPasswordHistory: 5,
+    resetTokenValidityDuration: 24*60*60,
+    resetTokenReuseIfValid: true
+  }
+});
+```
+
+### Custom Pages
+
+It’s possible to change the default pages of the app and redirect the user to another path or domain.
+
+```js
+const api = ParseServer({
+  ...otherOptions,
+  customPages: {
+    passwordResetSuccess: "http://yourapp.com/passwordResetSuccess",
+    verifyEmailSuccess: "http://yourapp.com/verifyEmailSuccess",
+    parseFrameURL: "http://yourapp.com/parseFrameURL",
+    linkSendSuccess: "http://yourapp.com/linkSendSuccess",
+    linkSendFail: "http://yourapp.com/linkSendFail",
+    invalidLink: "http://yourapp.com/invalidLink",
+    invalidVerificationLink: "http://yourapp.com/invalidVerificationLink",
+    choosePassword: "http://yourapp.com/choosePassword"
+  }
+})
+```
+
+## Insecure Options
+
+When deploying to be production, make sure:
+
+* `allowClientClassCreation` is set to `false`
+* `mountPlayground` is not set to `true`
+* `masterKey` is set to a long and complex string
+* `readOnlyMasterKey` if set, is set to a long and complex string
+* That you have authentication required on your database, and, if you are using mongo, disable unauthenticated access to port 27017
+* You have restricted `count` and `addField` operations via [Class Level Permissions](#class-level-permissions)
+* You enforce ACL and data validation using [cloud code]({{site.baseURL}}/cloudcode/guide/)
+
+## Using environment variables to configure Parse Server
+
+You may configure the Parse Server using environment variables:
+
+```bash
+PORT
+PARSE_SERVER_APPLICATION_ID
+PARSE_SERVER_MASTER_KEY
+PARSE_SERVER_DATABASE_URI
+PARSE_SERVER_URL
+PARSE_SERVER_CLOUD
+```
+
+The default port is 1337, to use a different port set the PORT environment variable:
+
+```bash
+$ PORT=8080 parse-server --appId APPLICATION_ID --masterKey MASTER_KEY
+```
+
+For the full list of configurable environment variables, run `parse-server --help` or take a look at [Parse Server Configuration](https://github.com/parse-community/parse-server/blob/master/src/Options/Definitions.js).

_includes/parse-server/development.md

@@ -1,5 +1,7 @@
 # Development Guide
 
+We really want Parse to be yours, to see it grow and thrive in the open source community. Please see the [Contributing to Parse Server notes](https://github.com/parse-community/parse-server/blob/master/CONTRIBUTING.md).
+
 ## Running Parse Server for development
 
 Normally, when you run a standalone Parse Server, the [latest release that has been pushed to npm](https://www.npmjs.com/package/parse-server) will be used. This is great if you are interested in just running Parse Server, but if you are developing a new feature or fixing a bug you will want to use the latest code on your development environment.
@@ -59,6 +61,3 @@ The following is a breakdown of the various files you will find in the Parse Ser
 * [triggers.js](https://github.com/parse-community/parse-server/wiki/triggers.js) - cloud code methods for handling database trigger events
 * [users.js](https://github.com/parse-community/parse-server/wiki/users.js) - handle the /users and /login routes
 
-## Contributing
-
-We really want Parse to be yours, to see it grow and thrive in the open source community. Please see the [Contributing to Parse Server notes](https://github.com/parse-community/parse-server/blob/master/CONTRIBUTING.md).

_includes/parse-server/experimental.md

@@ -0,0 +1,59 @@
+# Experimental
+
+Experimental Features are items that we are experimenting with that will eventually become full features, or items that will be removed from the system if they are proven to not work well.
+
+These features may not be approprate for production, so use at your own risk.
+
+## Direct Access
+
+`directAccess` replaces the HTTP Interface when using the JS SDK in the current node runtime. This may improve performance, along with `enableSingleSchemaCache` set to `true`.
+
+Configuration:
+```js
+const api = new ParseServer({
+    //...other configuration
+    directAccess: true
+});
+```
+
+## Idempotency
+
+This feature deduplicates identical requests that are received by Parse Server mutliple times, typically due to network issues or network adapter access restrictions on mobile operating systems.
+
+Identical requests are identified by their request header `X-Parse-Request-Id`. Therefore a client request has to include this header for deduplication to be applied. Requests that do not contain this header cannot be deduplicated and are processed normally by Parse Server. This means rolling out this feature to clients is seamless as Parse Server still processes request without this header when this feature is enbabled.
+
+This feature needs to be enabled on the client side to send the header and on the server to process the header. Refer to the specific Parse SDK docs to see whether the feature is supported yet.
+
+Deduplication is only done for object creation and update (`POST` and `PUT` requests). Deduplication is not done for object finding and deletion (`GET` and `DELETE` requests), as these operations are already idempotent by definition.
+
+Configutation:
+```js
+const api = new ParseServer({
+  //...other configuration
+    idempotencyOptions: {
+        paths: [".*"],       // enforce for all requests
+        ttl: 120             // keep request IDs for 120s
+    }
+});
+```
+Parameters:
+
+* `idempotencyOptions` (`Object`): Setting this enables idempotency enforcement for the specified paths.
+* `idempotencyOptions.paths`(`Array<String>`): An array of path patterns that have to match the request path for request deduplication to be enabled. 
+* The mount path must not be included, for example to match the request path `/parse/functions/myFunction` specify the path pattern `functions/myFunction`. A trailing slash of the request path is ignored, for example the path pattern `functions/myFunction` matches both `/parse/functions/myFunction` and `/parse/functions/myFunction/`.
+
+  Examples:
+
+  * `.*`: all paths, includes the examples below
+  * `functions/.*`: all functions
+  * `jobs/.*`: all jobs
+  * `classes/.*`: all classes
+  * `functions/.*`: all functions
+  * `users`: user creation / update
+  * `installations`: installation creation / update
+
+* `idempotencyOptions.ttl`: The duration in seconds after which a request record is discarded from the database. Duplicate requests due to network issues can be expected to arrive within milliseconds up to several seconds. This value must be greater than `0`.
+
+#### Notes
+
+- This feature is currently only available for MongoDB and not for Postgres.