Updated wiki

Auth.js.md

@@ -0,0 +1,20 @@
+##### Auth.js
+
+---
+
+Auth object, created to hold config/master/user information for requests
+
+Also has helper methods for getting a public or master Auth object, or from a session token
+
+See [[Config.js|Config.js]]
+
+---
+
+```
+var auth = new Auth(config, isMaster, userObject);
+
+var nobody = Auth.nobody(config);
+var master = Auth.master(config);
+
+var sessionAuth = Auth.getAuthForSessionToken(config, sessionToken);
+```

Config.js.md

@@ -0,0 +1,9 @@
+##### Config.js
+
+---
+
+Config object, storage for the application configuration and some router information
+
+Given an applicationId and a mount point (https://myserver.com/parse) this will assemble other information from the cache and database
+
+---

DatabaseAdapter.js.md

@@ -0,0 +1,21 @@
+##### DatabaseAdapter.js
+
+---
+
+Interface for allowing the underlying database to be changed
+
+Adapter classes must implement the following methods:
+* a constructor with signature (connectionString, optionsObject)
+* connect()
+* loadSchema()
+* create(className, object)
+* find(className, query, options)
+* update(className, query, update, options)
+* destroy(className, query, options)
+* This list is incomplete and the database process is not fully modularized.
+
+---
+
+See [[ExportAdapter.js|ExportAdapter.js]] for the default adapter implementation using MongoDB.
+
+See [[transform.js|transform.js]] for additional database specific transformation logic.

ExportAdapter.js.md

@@ -0,0 +1,64 @@
+##### ExportAdapter.js
+
+---
+
+DatabaseAdapter for MongoDB (default)
+
+See [[DatabaseAdapter.js|DatabaseAdapter.js]]
+
+---
+
+```
+// Connects automatically
+var db = new ExportAdapter('mongodb://...', { collectionPrefix: '' });
+
+// Get the mongo collection object
+db.collection('TestObject').then((collection) => { ... });
+
+// Load a copy of the schema
+db.loadSchema().then((schema) => { ... });
+
+// Validate a REST API formatted object against the schema (can update the stored schema)
+db.validateObject('TestObject', myObject).then(() => { ... });
+
+// Transform a database object to REST API format
+var obj = db.untransformObject(schema, isMaster, aclGroup, className, mongoObject);
+
+// Update the database
+db.update(className, query, update, options).then( ... );
+
+// Handle relation operations, mutates the update
+db.handleRelationUpdates(className, objectId, update).then( ... );
+
+// Adds a relation
+db.addRelation(key, fromClassName, fromId, toId).then( ... );
+
+// Removes a relation
+db.removeRelation(key, fromClassName, fromId, toId).then( ... );
+
+// Delete objects matching the query
+db.destroy(className, query, options).then( ... );
+
+// Create an object
+db.create(className, object, options).then( ... );
+
+// Get related Ids given an owning Id
+db.relatedIds(className, key, owningId).then( ... );
+
+// Get owning Ids given a list of related Ids
+db.owningIds(className, key, relatedIds).then( ... );
+
+// Processes any $in constraints, mutates the query
+db.reduceInRelation(className, query, schema).then( ... );
+
+// Processes any $relatedTo constraints, mutates the query
+db.reduceRelationKeys(className, query).then( ... );
+
+// Does a find with "smart indexing"
+// Currently just adds indexes for geo-point fields if not already set.
+db.smartFind(collection, where, options).then( ... );
+
+// Runs a find on the database
+db.find(className, query, options).then( ... );
+
+```

FilesAdapter.js.md

@@ -0,0 +1,13 @@
+##### FilesAdapter.js
+
+---
+
+Interface for allowing the underlying file storage to be changed
+
+Adapter classes must implement the following functions:
+* create(config, filename, data)
+* get(config, filename)
+
+See [[GridStoreAdapter.js|GridStoreAdapter.js]] for the default implementation
+
+---

GridStoreAdapter.js.md

@@ -0,0 +1,15 @@
+##### GridStoreAdapter.js
+
+---
+
+FilesAdapter for storing uploaded files in GridStore/MongoDB (default)
+
+See [[FilesAdapter.js|FilesAdapter.js]]
+
+---
+
+```
+gridstore.create(config, filename, data).then( ... );
+
+gridstore.get(config, filename).then( ... );
+```

Home.md

@@ -6,13 +6,7 @@ Parse Server is a new project, separate from the hosted Parse API service.  Our
 
 ---
 
-Discussion:
-
-To ask a question, please submit an issue against the repository.  Answers to questions may be placed in the wiki.
-
-* [[About|About]] - 
-
-Files:
+Table of contents:
 
 * [[index.js|index.js]] - exposes the ParseServer constructor and mutates Parse.Cloud
 * [[analytics.js|analytics.js]] - handle the /events routes

PromiseRouter.js.md

@@ -0,0 +1,11 @@
+##### PromiseRouter.js
+
+---
+
+A router that is based on promises rather than req/res/next.
+
+This is intended to replace the use of express.Router to handle subsections of the API surface.
+
+This will make it easier to have methods like 'batch' that themselves use our routing information, without disturbing express components that external developers may be modifying.
+
+---

RestQuery.js.md

@@ -0,0 +1,17 @@
+##### RestQuery.js
+
+---
+
+An object that encapsulates everything we need to run a 'find' operation, encoded in the REST API format.
+
+---
+
+```
+var query = new RestQuery(config, auth, className, restWhere, restOptions);
+
+// A convenient method to perform all the steps of processing a query
+// in order.
+// Returns a promise for the response - an object with optional keys
+// 'results' and 'count'.
+query.execute().then( ... );
+```

RestWrite.js.md

@@ -0,0 +1,26 @@
+##### RestWrite.js
+
+---
+
+A RestWrite encapsulates everything we need to run an operation that writes to the database. This could be either a "create" or an "update".
+
+---
+
+```
+// query and data are both provided in REST API format. So data
+// types are encoded by plain old objects.
+// If query is null, this is a "create" and the data in data should be
+// created.
+// Otherwise this is an "update" - the object matching the query
+// should get updated with data.
+// RestWrite will handle objectId, createdAt, and updatedAt for
+// everything. It also knows to use triggers and special modifications
+// for the _User class.
+var write = new RestWrite(config, auth, className, query, data, originalData);
+
+// A convenient method to perform all the steps of processing the
+// write, in order.
+// Returns a promise for a {response, status, location} object.
+// status and location are optional.
+write.execute().then( ... );
+```

Schema.js.md

@@ -0,0 +1,22 @@
+##### Schema.js
+
+---
+
+This class handles schema validation, persistence, and modification.
+
+Each individual Schema object should be immutable. The helpers to
+do things with the Schema just return a new schema when the schema
+is changed.
+
+The canonical place to store this Schema is in the database itself,
+in a _SCHEMA collection. This is not the right way to do it for an
+open source framework, but it's backward compatible, so we're
+keeping it this way for now.
+
+In API-handling code, you should only use the Schema class via the
+ExportAdapter. This will let us replace the schema logic for
+different databases.
+
+**TODO:** hide all schema logic inside the database adapter.
+
+---

analytics.js.md

@@ -0,0 +1,14 @@
+##### analytics.js
+
+---
+
+Handle the /events/ routes
+
+Currently these just swallow/ignore the input and return a successful response to the client.
+
+---
+
+```
+POST - /events/AppOpened
+POST - /events/:eventName
+```

batch.js.md

@@ -0,0 +1,9 @@
+##### batch.js
+
+---
+
+Batch handling implemented for PromiseRouter
+
+This is used in [[index.js|index.js]] during initialization.
+
+---

cache.js.md

@@ -0,0 +1,22 @@
+##### cache.js
+
+---
+
+Simple caching for the app and user sessions
+
+---
+
+```
+// during a request
+var user = cache.getUser(sessionToken);
+if (!user) { ... }
+
+// during login/signup
+cache.setUser(sessionToken, userObject);
+
+// during logout
+cache.clearUser(sessionToken);
+
+```
+
+Also has an unused statistics object which could be used to implement in-memory analytics storage.

classes.js.md

@@ -0,0 +1,17 @@
+##### classes.js
+
+---
+
+Handle the /classes/ routes
+
+Mostly just passes through to [[rest.js|rest.js]] with some minor modifications
+
+---
+
+```
+GET - /classes/:className
+POST - /classes/:className
+GET - /classes/:className/:objectId
+DELETE - /classes/:className/:objectId
+PUT - /classes/:className/:objectId
+```

crypto.js.md

@@ -0,0 +1,13 @@
+##### crypto.js
+
+---
+
+Uses bcrypt for password hashing and comparison
+
+---
+
+```
+crypto.hash('hunter2').then( ... ).catch( ... );
+
+crypto.compare('hunter2', 'previously-hashed-password-hash').then( ... ).catch( ... );
+```

facebook.js.md

@@ -0,0 +1,15 @@
+##### facebook.js
+
+---
+
+Helper functions for accessing the Graph API
+
+---
+
+```
+// Make sure the provided access token matches the provided user
+facebook.validateUserId(userId, accessToken).then( ... );
+
+// Make sure the provided access token matches the app
+facebook.validateAppId(appId, accessToken).then( ... );
+```

files.js.md

@@ -0,0 +1,14 @@
+##### files.js
+
+---
+
+Handle the /files/ routes
+
+See [[FilesAdapter.js|FilesAdapter.js]]
+
+---
+
+```
+GET - /files/:fileName
+POST - /files/:fileName
+```

functions.js.md

@@ -0,0 +1,11 @@
+##### functions.js
+
+---
+
+Handle the /functions/ routes
+
+---
+
+```
+POST - /functions/:functionName
+```

index.js.md

@@ -0,0 +1,38 @@
+##### index.js
+
+---
+
+Exposes the ParseServer constructor and mutates the Parse.Cloud namespace to support Cloud Code
+
+---
+
+```
+// ParseServer works like a constructor of an express app.
+// The args that we understand are:
+// "databaseAdapter": a class like ExportAdapter providing create, find,
+//                    update, and delete
+// "filesAdapter": a class like GridStoreAdapter providing create, get,
+//                 and delete
+// "databaseURI": a uri like mongodb://localhost:27017/dbname to tell us
+//          what database this Parse API connects to.
+// "cloud": relative location to cloud code to require
+// "appId": the application id to host
+// "masterKey": the master key for requests to this app
+// "collectionPrefix": optional prefix for database collection names
+// "fileKey": optional key from Parse dashboard for supporting older files
+//            hosted by Parse
+// "clientKey": optional key from Parse dashboard
+// "dotNetKey": optional key from Parse dashboard
+// "restAPIKey": optional key from Parse dashboard
+// "javascriptKey": optional key from Parse dashboard
+
+var ParseServer = require('parse-server').ParseServer;
+
+var api = new ParseServer({
+	appId: 'my-app-id',
+	masterKey: 'secret',
+	cloud: './cloud/main.js'
+});
+
+myExpressApp.use('/parse', api);
+```

installations.js.md

@@ -0,0 +1,15 @@
+##### installations.js
+
+---
+
+Handle the /installations/ routes
+
+---
+
+```
+POST - /installations/
+GET - /installations/
+GET - /installations/:objectId
+PUT - /installations/:objectId
+DELETE - /installations/:objectId
+```

middlewares.js.md

@@ -0,0 +1,12 @@
+##### middlewares.js
+
+---
+
+Express middleware used during request processing
+
+---
+
+* handleParseHeaders - runs after body-parser, checks the request has a valid appId, checks user auth, mutates the request
+* allowCrossDomain - sets Access-Control-Allow-* headers and catches OPTIONS requests
+* allowMethodOverride - handles method overrides sent from javascript (i.e. a PUT sent as a POST)
+* handleParseErrors - runs late in the chain, catches any propogated errors

push.js.md

@@ -0,0 +1,11 @@
+##### push.js
+
+---
+
+Handle the /push/ route.  Not yet implemented.  Developers can continue to use Parse.com for Push if they set up a Hosted Parse app using their Mongo connection string.
+
+---
+
+```
+POST - /push/
+```

rest.js.md

@@ -0,0 +1,24 @@
+##### rest.js
+
+---
+
+This file contains helpers for running operations in REST format.  The goal is that handlers that explicitly handle an express route should just be shallow wrappers around things in this file, but these functions should not explicitly depend on the request object.
+
+This means that one of these handlers can support multiple routes. That's useful for the routes that do really similar things.
+
+---
+
+```
+// Returns a promise for an object with optional keys 'results' and 'count'.
+rest.find(config, auth, className, restWhere, restOptions).then( ... );
+
+// Returns a promise that doesn't resolve to any useful value.
+rest.del(config, auth, className, objectId).then( ... );
+
+// Returns a promise for a {response, status, location} object.
+rest.create(config, auth, className, restObject).then( ... );
+
+// Returns a promise that contains the fields of the update that the
+// REST API is supposed to return.  Usually, this is just updatedAt.
+rest.update(config, auth, className, objectId, restObject).then( ... );
+```

roles.js.md

@@ -0,0 +1,14 @@
+##### roles.js
+
+---
+
+Handle the /roles/ routes
+
+---
+
+```
+POST - /roles/
+GET - /roles/:objectId
+PUT - /roles/:objectId
+DELETE - /roles/:objectId
+```

sessions.js.md

@@ -0,0 +1,17 @@
+##### sessions.js
+
+---
+
+Handle the /sessions and /logout routes
+
+---
+
+```
+POST - /logout
+POST - /sessions
+GET - /sessions
+GET - /sessions/me
+GET - /sessions/:objectId
+PUT - /sessions/:objectId
+DELETE - /sessions/:objectId
+```

testing-routes.js.md

@@ -0,0 +1,7 @@
+##### testing-routes.js
+
+---
+
+Used by internal Parse integration tests.  Enabled by environment variable TESTING=1, this allows us to create and clear many apps during parallel testing.
+
+---

transform.js.md

@@ -0,0 +1,32 @@
+##### transform.js
+
+---
+
+Transforms keys/values between Mongo and REST API formats.
+
+**TODO:** Turn this into a helper library for [[DatabaseAdapter.js|DatabaseAdapter.js]]
+
+---
+
+```
+// Transforms a key used in the REST API format to its mongo format.
+function transformKey(schema, className, key) {
+
+// Main exposed method to help run queries.
+// restWhere is the "where" clause in REST API form.
+// Returns the mongo form of the query.
+// Throws a Parse.Error if the input query is invalid.
+function transformWhere(schema, className, restWhere) { ... }
+
+// Main exposed method to create new objects.
+// restCreate is the "create" clause in REST API form.
+// Returns the mongo form of the object.
+function transformCreate(schema, className, restCreate) { ... }
+
+// Main exposed method to help update old objects.
+function transformUpdate(schema, className, restUpdate) { ... }
+
+// Converts from a mongo-format object to a REST-format object.
+// Does not strip out anything based on a lack of authentication.
+function untransformObject(schema, className, mongoObject) { ... }
+```

triggers.js.md

@@ -0,0 +1,8 @@
+##### triggers.js
+
+---
+
+Cloud code methods for handling database trigger events
+
+---
+

users.js.md

@@ -0,0 +1,19 @@
+##### users.js
+
+---
+
+Handle the /users and /login routes
+
+---
+
+```
+POST - /users
+GET - /users
+GET - /login
+GET - /users/me
+GET - /users/:objectId
+PUT - /users/:objectId
+DELETE - /users/:objectId
+
+POST - /requestPasswordReset (not implemented)
+```