longstanding project to slowly put some comments into my source code...

Author: cstryker

api_server/README.pubnub

@@ -3,8 +3,8 @@ We currently have a demo subscription
 https://admin.pubnub.com
 
 username: [email protected]
-password: pkt4Rocks
+password: CS!R0cks
 
 publish key: pub-c-b65a2340-6854-4bf2-9ab4-ed971aea9dd4
 subscribe key: sub-c-12519fba-c8a0-11e6-8164-0619f8945a4f
-secret: sec-c-NmFkMzAyM2YtMGI2MC00ZDU2LWFmZDgtMTE1Y2FmODQ5YTEy
+secret: sec-c-NmFkMzAyM2YtMGI2MC00ZDU2LWFmZDgtMTE1Y2FmODQ5YTEy

api_server/README.quick_test

@@ -1,7 +1,14 @@
 #!/usr/bin/env node
+
+// Main executable for running the CodeStream API Server
+//
+// We'll load a bunch of configurations and then use a "generic" API server to do most of the work
+
 'use strict';
 
-var APICluster = require(process.env.CS_API_TOP + '/lib/api_server/api_cluster.js');
+var APICluster = require(process.env.CS_API_TOP + '/lib/api_server/api_cluster.js'); // this is the real meat of the API server
+
+// load configurations
 const ConfigDirectory = process.env.CS_API_TOP + '/config';
 const ModuleDirectory = process.env.CS_API_TOP + '/services/api/modules';
 const ApiConfig = require(ConfigDirectory + '/api.js');
@@ -15,12 +22,15 @@ const Limits = require(ConfigDirectory + '/limits.js');
 const Version = require(ConfigDirectory + '/version.js');
 const SimpleFileLogger = require(process.env.CS_API_TOP + '/lib/util/simple_file_logger');
 
+// establish our logger
 var Logger = new SimpleFileLogger(LoggerConfig);
 
 if (MongoConfig.queryLogging) {
+	// we maintain a separate log file for mongo queries
 	Object.assign(MongoConfig.queryLogging, LoggerConfig, MongoConfig.queryLogging);
 }
 
+// establish our data collections
 const DataCollections = {
 	users: require(ModuleDirectory + '/users/user'),
 	companies: require(ModuleDirectory + '/companies/company'),
@@ -33,6 +43,7 @@ const DataCollections = {
 };
 const MongoCollections = Object.keys(DataCollections);
 
+// invoke a node cluster master with our configurations provided
 var MyAPICluster = new APICluster({
 	moduleDirectory: ModuleDirectory,
 	api: ApiConfig,
@@ -51,6 +62,7 @@ var MyAPICluster = new APICluster({
 	dataCollections: DataCollections
 }, Logger);
 
+// start up the master, this will launch workers to really get down to work
 MyAPICluster.start((error) => {
 	if (error) {
 		console.error('Failed to start: ' + error);

api_server/bin/api_server.js

@@ -1,5 +1,7 @@
+// general api server configuration
+
 'use strict';
 
 module.exports = {
-	confirmationNotRequired: process.env.CS_API_CONFIRMATION_NOT_REQUIRED
+	confirmationNotRequired: process.env.CS_API_CONFIRMATION_NOT_REQUIRED	 // avoid the email configuration by setting this env var
 };

api_server/config/api.js

@@ -1,11 +1,13 @@
+// configuration for running api server unit tests
+
 'use strict';
 
 module.exports = {
-	api: {
+	api: {	// where is the api server running?
 		host: process.env.CS_API_HOST,
 		port: process.env.CS_API_PORT
 	},
-	mongo: {
+	mongo: { // where is mongo running?
 		host: process.env.CS_API_MONGO_HOST,
 		port: process.env.CS_API_MONGO_PORT,
 		database: process.env.CS_API_MONGO_DATABASE

api_server/config/api_test.js

@@ -1,11 +1,13 @@
+// email configuration
+
 'use strict';
 
 module.exports = {
-	sendgrid: {
+	sendgrid: {	// sendgrid credentials
 		url: '/v3/mail/send',
 		apiKey: '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',
-		emailTo: process.env.CS_API_EMAIL_TO
+		emailTo: process.env.CS_API_EMAIL_TO // redirect emails to this address, for safe testing
 	},
-	senderEmail: '[email protected]',	 
-	confirmationEmailTemplateId: '300934c5-3a9c-46f8-a905-b801c23439ab',
+	senderEmail: '[email protected]', // we'll send emails from this address
+	confirmationEmailTemplateId: '300934c5-3a9c-46f8-a905-b801c23439ab', // template to use for confirmation emails
 };

api_server/config/email.js

@@ -1,12 +1,14 @@
+// express js configuration
+
 'use strict';
 
 module.exports = {
 	host: process.env.CS_API_HOST,
 	port: process.env.CS_API_PORT,
-	https: {
+	https: { // https key/cert
 		keyfile: process.env.CS_API_SSL_KEYFILE,
 		certfile: process.env.CS_API_SSL_CERTFILE,
 		cafile: process.env.CS_API_SSL_CAFILE
 	},
-	ignoreHttps: process.env.CS_API_IGNORE_HTTPS
+	ignoreHttps: process.env.CS_API_IGNORE_HTTPS // run on http instead of https, for testing only
 };

api_server/config/express.js

@@ -1,7 +1,9 @@
+// defines various limits
+
 'use strict';
 
 module.exports = {
-	maxPostsPerRequest: 100,
-	maxStreamsPerRequest: 100,
-	maxMarkersPerRequest: 100
+	maxPostsPerRequest: 100, 	// never serve more than this many posts in a page
+	maxStreamsPerRequest: 100,	// never serve more than this many streams in a page
+	maxMarkersPerRequest: 100	// never serve more than this many markers in a page (not currently used)
 };

api_server/config/limits.js

@@ -1,9 +1,11 @@
+// logger configuration
+
 'use strict';
 
 module.exports = {
-	directory: process.env.CS_API_LOG_DIRECTORY,
-	basename: 'api',
-	retentionPeriod: 30 * 24 * 60 * 60 * 1000,
-	consoleOk: process.env.CS_API_LOG_CONSOLE_OK,
-	debugOk: process.env.CS_API_LOG_DEBUG
+	directory: process.env.CS_API_LOG_DIRECTORY,	// put log files in this directory
+	basename: 'api',								// use this for the basename of the log file
+	retentionPeriod: 30 * 24 * 60 * 60 * 1000,		// retain log files for this many milliseconds
+	consoleOk: process.env.CS_API_LOG_CONSOLE_OK,	// also output to the console
+	debugOk: process.env.CS_API_LOG_DEBUG			// output debug messages, for special debugging
 };

api_server/config/logger.js

@@ -1,14 +1,16 @@
+// mongo configuration
+
 'use strict';
 
 module.exports = {
 	host: process.env.CS_API_MONGO_HOST,
 	port: process.env.CS_API_MONGO_PORT,
 	database: process.env.CS_API_MONGO_DATABASE,
-	queryLogging: {
+	queryLogging: { // we write a separate log file for mongo queries, and for slow and "really slow" queries so we can look for problems
 		basename: 'mongo-query',
 		slowBasename: 'slow-mongo-query',
-		slowThreshold: 100,
+		slowThreshold: 100, // queries that take longer than this go to the slow query log
 		reallySlowBasename: 'really-slow-mongo-query',
-		reallySlowThreshold: 1000
+		reallySlowThreshold: 1000 // queries that take longer than this go to the "really slow" query log
 	}
 };