added access control headers; more detailed spec comments

telemetry_server/README.md

@@ -1,4 +1,6 @@
 [Design doc](https://docs.google.com/document/d/119mO6KgK3HY6Tx_hRBTXcs0BSQwWCaGpI0whlhqaW74/edit)
+
+
 (server to be temporarily hosted here until the calstar org gets private repos)
 
 The instructions below for installing assume you have some familiarity with nodejs: if you don't, talk to Jonathan and he'll get you up to speed.
@@ -7,37 +9,67 @@ The instructions below for installing assume you have some familiarity with node
 1. Install nodejs and npm (look this up if you don't know how)
 2. Run `npm install`
 3. Install [MariaDB](https://mariadb.org/download/) (this is the SQL server the OCF uses, and is compatible with MySQL libraries)
-4. Run `mysql -uroot < setup.sql`; this initializes the database with a user and stuff.
+4. Run `mysql -uroot < server/setup.sql`; this initializes the database with a user and stuff.
 
 ## Running
 1. <b>Start the SQL server</b> run `mysql.server start`, or whatever the docs tell you to do.
 2. <b>Start the webserver</b> To start the webserver locally, run `npm start`. If you make any changes to server files, you'll need to ctrl-C and restart the server for the changes to take place. Make sure the SQL server is running.
-3. To have client-side files update as you make changes, run `npm run watch`.
+3. To have client-side files update as you make changes, run `npm run watch`. Output files will go in the `dist` folder.
 4. Visit `localhost:<port number>` in your web browser. The port number is 8000 for now.
 
-## Style
+## File Structure
+```
+telemetry_server
+├── dist/ (minified client-side JS)
+├── html/ (client-side HTML files)
+├── node_modules/ (external dependencies for both client and server)
+├── server/ (code for webserver)
+├── src/ (client-side JS files)
+└── test/ (tests, format TBD for now)
+```
+
+## Style and Practice
 ### general
 Make sure that you'll be able to understand what your code does 3 weeks from now, and make sure other people will be able to understand your code. To that end, please comment things as much as possible.
+
 ### js
-Please adhere to the [standardjs](https://standardjs.com/) conventions: (tl;dr 2 space indents, single quoted strings, no semicolons—if you feel really strongly about anything, please inform me as such and we can compromise). This is just for consistency and readability, and because I don't want to configure eslint.
+Please adhere to the [standardjs](https://standardjs.com/) conventions: (tl;dr 2 space indents, single quoted strings, no semicolons—if you feel really strongly about anything, please inform me as such and we can compromise). This is just for consistency and readability, and because Jonathan doesn't want to configure eslint.
+
 Imports (from `require`) should be declared as `const`.
-Feel free to rename the variables I gave in the skeleton code. Just make sure the variable names make sense are at least somewhat descriptive.
+
+Prefer `path.join` to string concatenation when specifying file paths.
+
+Feel free to rename the variables Jonathan gave in the skeleton code. Just make sure the variable names make sense are at least somewhat descriptive.
+
+Also, there's probably important npm packages that Jonathan hasn't imported (like a CSV parser or compression library or whatever). You're welcome to import what you need (remember to do `--save`), but use discretion, i.e. don't import libraries that do trivial tasks. File size probably isn't a huge concern for us, but it's probably a good idea to keep bloat down as much as possible as a matter of good practice.
+
 ### sql
 Capitalize keywords and lowercase names, e.g. `SELECT points FROM data`. For longer statements, try to put clauses like `FROM` and `WHERE` on their own lines for readability.
 
 If the schema of a table exists and you want to change it, remember to change it in `setup.sql` with `ALTER TABLE IF EXISTS`.
 
-USE PREPARED STATEMENTS (as opposed to string concatenating parameters into a query). They help avoid SQL injection attacks, and also undefined behavior.
+USE PREPARED STATEMENTS (as opposed to string concatenating parameters into a query). They help avoid SQL injection attacks and makes code more maintainable.
 
 ### html
-Please 2 space indent. I don't really have much else to say.
+Please 2 space indent. Jonathan doesn't really have much else to say.
+
+### writing tests
+Unit tests are probably good (and JS is a dangerous enough language as is), but Jonathan typically lives dangerously and thus has not chosen a testing framework for this project. If you have any suggestions, talk to Jonathan about it.
+
+That said, please write tests (both unit and integration). This is especially important if your function handles SQL stuff, as we don't want to mess up anybody's databases with bad code.
 
 ## Library docs
 The following documentation pages may be useful:
 - [loggy](https://www.npmjs.com/package/loggy)
 - [express](https://expressjs.com/en/4x/api.html)
 - [mysql2](https://www.npmjs.com/package/mysql2)
-If there's any other libraries I forgot to put down here, Google is your friend.
+- [MariaDB](https://mariadb.com/kb/en/library/documentation/)
+If there's any other libraries not listed here, Google is your friend. If you find anything you think is worth putting here, add it.
 
 ## TODO
-(jonathan will assign these in a bit, stay tuned)
+Tasks are listed as issues in the Github repo. If you wish to work on a task, please assign the issue to yourself.
+
+You're welcome to work on multiple issues at a time, just make sure you're in communication with whoever has it assigned to them.
+
+If Jonathan forgot/messed up something major (e.g. missing API endpoint), make an issue for it if it's not a quick fix and attach it to the project.
+

telemetry_server/server/db-interface.js

@@ -0,0 +1,26 @@
+/**
+ * Access control: CalSTAR MA
+ *
+ * Provides a single unified interface into the SQL server, allowing us to use a
+ * single connection pool to speed up queries.
+ * This file exports a connection pool object from the mysql2 library.
+ * For details on usage, see the package docs:
+ * https://www.npmjs.com/package/mysql2#using-connection-pools
+ *
+ * If you need to change the export of this file, be VERY CAREFUL so as to prevent
+ * changes in the interface of the exported object from affecting other files.
+ */
+
+const sql = require('mysql2') 
+
+// TODO store settings in a json file, or in .env 
+const pool = sql.createPool({ 
+  host: 'localhost', 
+  user: 'telemetry', 
+  database: 'telemetry', 
+  waitForConnections: true, 
+  connectionLimit: 10, 
+  queueLimit: 0 
+}) 
+
+module.exports = pool

telemetry_server/server/export.js

@@ -1,3 +1,15 @@
+/**
+ * Access control: CalSTAR MA
+ *
+ * Handles GET requests to the /export endpoint.
+ * Exports a function (request, response) that returns void, to be used
+ * as express middleware.
+ *
+ * This API endpoint gives the file contents to the querier.
+ *
+ * For further details, refer to the design doc (linked in the README).
+ */
+
 const fs = require('fs')
 const path = require('path')
 

telemetry_server/server/index.js

@@ -1,3 +1,14 @@
+/*
+ * Access control: CalSTAR MA
+ *
+ * The entry point of the server. Responds to requests and stuff.
+ *
+ * To add a new API endpoint, please put the code in a separate file, import
+ * it here, and mount it as appropriate.
+ * Jonathan doesn't really know how routing works, so if you want to do that
+ * to improve readability then feel free to do so.
+ */
+
 // dependencies
 const express = require('express')
 const app = express()
@@ -15,7 +26,9 @@ const postUpload = require('./upload')
 const PORT = 8000
 const BASE_DIR = path.join(__dirname, '..') // parent directory
 
-app.use(express.static(BASE_DIR)) // https://stackoverflow.com/questions/40574159/
+// fixes weird path resolution stuff on localhost
+// https://stackoverflow.com/questions/40574159/
+app.use(express.static(BASE_DIR))
 
 app.get('/', function (req, res) {
   res.sendFile(path.join(BASE_DIR, 'html', 'index.html'))

telemetry_server/server/read-data.js

@@ -1,14 +1,14 @@
-const db = require('mysql2')
-
-// TODO store settings in a json file, or in .env
-const pool = db.createPool({
-  host: 'localhost',
-  user: 'telemetry',
-  database: 'telemetry',
-  waitForConnections: true,
-  connectionLimit: 10,
-  queueLimit: 0
-})
+/*
+ * Access control: CalSTAR MA
+ *
+ * Handles GET requests to the /readData endpoint.
+ * Gets data from a run specified by the parameters of the query and gives the data
+ * to the user as a CSV or something.
+ *
+ * For further details, refer to the design doc (linked in the README).
+ */
+
+const db = require('./db-interface')
 
 // YOUR CODE HERE
 var getReadData = function (req, res) {

telemetry_server/server/runs.js

@@ -1,3 +1,14 @@
+/**
+ * Access control: CalSTAR MA
+ *
+ * Handles GET requests to the /runs and /runs/{id} endpoints.
+ * The former returns a list of all runs stored on the server (probably along
+ * with some information about each, such as date, description, name, and ID).
+ * The latter returns more specific information/metadata for a given run.
+ *
+ * For further details, refer to the design doc (linked in the README).
+ */
+
 const fs = require('fs')
 const path = require('path')
 

telemetry_server/setup.sql → telemetry_server/server/setup.sql

@@ -1,3 +1,10 @@
+/*
+ * Access control: CalSTAR MA
+ *
+ * Contains statements to set up database configuration and schema. Should always be run
+ * before starting the server for the first time.
+ */
+
 CREATE USER IF NOT EXISTS 'telemetry'@'localhost'; -- add password later when in prod
 
 CREATE DATABASE IF NOT EXISTS telemetry;

telemetry_server/server/upload.js

@@ -1,3 +1,19 @@
+/**
+ * Access control: CalSTAR MA
+ *
+ * Handles POST requests to the /upload endpoint.
+ * Exports a function (request, response) that returns void, to be used
+ * as express middleware.
+ *
+ * This API endpoint handles uploads of raw test files; for now, these
+ * files can be .wbpz (ANSYS files used by sims) or .csv; we only need
+ * to worry about parsing .csv files. The .csv files should be parsed,
+ * and their data uploaded into the SQL database as appropriate.
+ *
+ * For further details, refer to the design doc (linked in the README).
+ */
+
+const db = require('./db-interface.js')
 
 // YOUR CODE HERE
 var postUpload = function (req, res) {