Improve comments & documentation

Author: Ben Stahl

lib/Server.js

@@ -2,25 +2,28 @@
 
 /**
  * @fileOverview
- * TUS Protocol 1.0.0 Server Implementation.
+ * TUS Protocol Server Implementation.
  *
  * @author Ben Stahl <[email protected]>
  */
-
 const http = require('http');
-const DataStore = require('./stores/DataStore');
 
-const OptionsHandler = require('./handlers/OptionsHandler');
-const PostHandler = require('./handlers/PostHandler');
+const DataStore = require('./stores/DataStore');
 const HeadHandler = require('./handlers/HeadHandler');
+const OptionsHandler = require('./handlers/OptionsHandler');
 const PatchHandler = require('./handlers/PatchHandler');
-const TUS_RESUMABLE = require('./constants').TUS_RESUMABLE;
+const PostHandler = require('./handlers/PostHandler');
 const RequestValidator = require('./validators/RequestValidator');
+
 const EXPOSED_HEADERS = require('./constants').EXPOSED_HEADERS;
+const TUS_RESUMABLE = require('./constants').TUS_RESUMABLE;
 
 class TusServer {
 
     constructor() {
+        // Any handlers assigned to this object with the method as the key
+        // will be used to repond to those requests. They get set/re-set
+        // when a datastore is assigned to the server.
         this.handlers = {};
     }
 
@@ -33,7 +36,8 @@ class TusServer {
     }
 
     /**
-     * Ensure store is a DataStore and add file create API handler
+     * Assign a datastore to this server, and re-set the handlers to use that
+     * data store when doing file operations.
      *
      * @param  {DataStore} store Store for uploaded files
      */
@@ -45,7 +49,13 @@ class TusServer {
         this._datastore = store;
 
         this.handlers = {
-            GET: {}, // Alow implemenation to have full handler control
+            // GET handlers should be written in the implementations
+            // eg.
+            //      const server = new tus.Server();
+            //      server.get('/', (req, res) => { ... });
+            GET: {},
+
+            // These methods are handled under the tus protocol
             HEAD: new HeadHandler(store),
             OPTIONS: new OptionsHandler(store),
             PATCH: new PatchHandler(store),
@@ -62,32 +72,40 @@ class TusServer {
      * @param  {Function} callback Request listener
      */
     get(path, callback) {
+
+        // Add this handler callback to the GET method handler list.
         this.handlers.GET[path] = callback;
     }
 
     /**
-     * Main server requestListener, the function which is
-     * automatically added to the 'request' event.
+     * Main server requestListener, invoked on every 'request' event.
      *
      * @param  {object} req http.incomingMessage
      * @param  {object} res http.ServerResponse
      * @return {ServerResponse}
      */
     handle(req, res) {
         console.info(`[TusServer] handle: ${req.method} ${req.url}`);
+
         // Allow overriding the HTTP method. The reason for this is
         // that some libraries/environments to not support PATCH and
         // DELETE requests, e.g. Flash in a browser and parts of Java
         if (req.headers['x-http-method-override']) {
             req.method = req.headers['x-http-method-override'].toUpperCase();
         }
 
+
         if (req.method === 'GET') {
+
+            // Check if this url has been added to allow GET requests, with an
+            // appropriate callback to handle the request
             if (!(req.url in this.handlers.GET)) {
                 res.writeHead(404, {});
                 res.write('Not found\n');
                 return res.end();
             }
+
+            // invoke the callback
             return this.handlers.GET[req.url](req, res);
         }
 
@@ -100,7 +118,7 @@ class TusServer {
             return res.end('Tus-Resumable Required\n');
         }
 
-        // Validate all other headers
+        // Validate all required headers to adhere to the tus protocol
         const invalid_headers = [];
         for (const header_name in req.headers) {
             if (req.method === 'OPTIONS') {
@@ -114,17 +132,18 @@ class TusServer {
         }
 
         if (invalid_headers.length > 0) {
+            // The request was not configured to the tus protocol
             res.writeHead(412, {}, 'Precondition Failed');
             return res.end(`Invalid ${invalid_headers.join(' ')}\n`);
         }
 
+        // Enable CORS
+        res.setHeader('Access-Control-Expose-Headers', EXPOSED_HEADERS);
         if (req.headers.origin) {
             res.setHeader('Access-Control-Allow-Origin', req.headers.origin);
         }
 
-        res.setHeader('Access-Control-Expose-Headers', EXPOSED_HEADERS);
-
-        // Handle POST, HEAD, PATCH, OPTIONS requests
+        // Invoke the handler for the method requested
         if (this.handlers[req.method]) {
             return this.handlers[req.method].send(req, res);
         }