Node.js/Javascript Collaborative App

The purpose of this assignment is to give you practice building a collaborative app and writing your own javascript modules. Also to take advantage of the fact that we can host servers on the Open Stack virtual machines that can be reached by other machines.

In this assignment you are going build a second javascript client-server app based primarily on native capabilties of Node.js, however this time you are required to implemement at least one "helper" javascript module. You are also free to import (or more correctly "require") npm modules from the npm (node package manager) registry. However, the use of Express.js and similar "high level" frameworks is still not allowed for this assignment. This is still primarily a javascript programming exercise and we still want you to build an app based primarily on node.js built in capabilities with a few helper modules. This assignment will give you a chance to build something interesting of your own design using what you learned doing assignment #1.

In this assignment we are not going to specify what the app should do. Instead we will have some basic requirements that must be met. This is your chance to come up with something creative.

The components are:

Server build with just Node.js and its build in modules (e.g. http, path, fs, url), at least one module of your own creation and perhaps other npm modules like "connect" or "websockets" but still not using express.js. If you have any doubts about whether you can require a certain npm module please check with me ahead of time.

Client: browser which is provided with a web page from the server consisting of html, css, javascript and jquery. (You can use which ever of these your want.)

The intention of this assigment is to build an app that will be access from multiple actual machines. The easiest way to do that is to host your server on the open stack virtual image for the course than clients on other machines can access it based on the IP address you provide.

Assignment restrictions:

Because each layer of node.js/javascipt based technologies like npm modules or the express.js framework solves many problem for you, in this assignment we will not allow the use of express.js yet. After this assignment express.js will be free game for the remainder of the course.

Note: this, and other assignments, can be done in pairs if you want to work with a partner. Please submit one copy to culearn with both your names on it.

Marking: This assignment is based on 17 specific numbered design requirements numbered R1.1... R4.4. Two marks each for a total of 34 marks. We will award 2 marks for those requirements that are met and well implemented, 1 mark for those only partly met or met but poorly implmented, and 0 marks for any requirement not met.

In addition there are some general programming and good practice requirements that you must satisfy. These requirements are numbered R0.1, R0.2 .... Be prepared to lose marks if these requirements are not satisfied. If requirement R0.0 or R0.1 is not met the assignment grade will be 0.

Good Programming and Good Practice Requirements

The following requirements will pertain to all your assignments regardless of what your application is supposed to do (i.e. regardless of the design requirements). These requirements are to ensure that your code is readable and maintainable by other programmers (or readable by TA's in our case), and that your program adopts good practices. You will lose 5 marks from your total assignment mark for each of the following requirements that is not satisfied. If, however, you do not satisfy requirement R0.0 or R0.1 you will get 0 for the assignment.

R0.0) IMPORTANT Uniqueness Requirement. The solution and code you submit MUST be unique. That is, it cannot be a copy of, or be too similar to, someone else's code, or other code found elsewhere. A mark of 0 will be assigned to any assignment that is judged by the instructors or the TA's not to be unique. (You are free to use any code posted on our course web site as part of our assignment solution.)

R0.1) CODE SUBMISSION ORGANIZATION AND COMPILATION: You should submit an app.js file and whatever directories and data is required. The TA's will then execute your app with node app.js. You must also provide a ReadMe.txt file telling the TA how to setup and run your app. Your ReadMe.txt must tell the TA what OS your developed under and what browser you tested your code with. If you compress your code when submitting to culearn you must use only .zip format (not .rar or .tar or whatever). Though you are permitted to write code on Windows 8, Linux, or Mac OS the code should be generic enough to be OS agnostic. Nevertheless, your ReadMe.txt file must says which OS you developed. Your code must work with at least a current Chrome or Firefox browser.

R0.2) All of your variables and functions should have meaningful names that reflect their purpose. Do not follow the convention common in math courses where they say things like: "let x be the number of customers and let y be the number of products...". Instead call your variables numberOfCustomers or numberOfProducts. Your program should not have any variables called "x" unless there is a good reason for them to be called "x". (One exception: It's OK to call simple for-loop counters i,j and k etc. when the context is clear and VERY localized.) Remember javascript does not have typed variables or functions so choosing good names is even more important. Many functions in javascript are annonymous (have no name) and so the name of the variable that refers to them is even more important.

R0.3) Code Comment Requirements: Comments in your code must coincide with what the code actually does. It is a very common bug in industry for people to modify code and forget to modify the comments and so you end up with comments that say one thing and code that actually does another. By the way, try not to over-comment your code but instead choose good variable names and function names that make the code more "self commenting".

R0.4) Citation Requirements: If you use code from other sources you should cite the source in comments that appear with the code. If the source is an internet website then put the URL in the comments. You may draw on code from outside sources but this may not form the complete solution you are handing in.

VERY IMPORTANT: Any sample code fragments provided may have bugs (although none have been put there intentionally). It is part of your task to identify errors in the requirements and sample code. Please report errors so they can be fixed and an assignment revision noted.

Application Requirements

Background

For this assignment we want you to come up with a small app that allows collaboration between, or among, more than one browser client at the same time running on different machines. You can decide what is does but it needs to satisfy the stated requirements.

We will, for the sake of discussion, refer to an imaginary air hockey game to help explain certain requirements but your app does not have to resemble it, or even be a game. It will however need to have some motion in the window.

For this assignment we want you to build a client server single page app that will allow several browser clients to collaborate on some task. This could be playing a game, or working on a "white board" or whatever. By collaborative we mean that what one person does on their web browser others will see on theirs in real-time.

For example, imagine an air hockey game in which one person -with their browser and mouse or keyboard controls one paddle while the other person on their browser controls the opposing one. The air hockey puck would presumably bounce off the walls and the players would be trying to knock the puck with their paddle to score points.

As another example imagine a group of people collaborating, or brainstorming, on a white board moving images or words around. When one person moves things in their browser others should see the same thing happening in real-time on theirs. Users however should not be able to control the same item at once. This would cause confusion and your app will have to prevent this.

Finally another classic collaborative app would be a chat session but this assignment requires that there be some motion involved.

Demo Code: We will be posting an example of a polling-based collaborative app (Asynchronous Collaboration based on Polling) and an example based on web sockets (Basic Chat Collaboration with WebSockets) in the course notes. These might be helpful as a starting point.

1) Server-Side Requirements

R1.1) The server code should use only javascript and node.js and may use npm modules but not express.js or other high level framework. Intended npm modules include "connect" or "websocket" Note this assignment is doable without any additional modules beyond assignment #1, and the one you are required to write.

R1.2) Your server should make use of at a least one module of your own creation. That is, a module that you write in javascript and then "require" in the main app code. This module will be hosted locally and not via the npm registry.

R1.3) The server-side and client-side javascript should keep track of who has permission to move what items in the client view. For example the server should know what can be moved and who is assigned to control it. The server should enforce that items not get moved by users who have not been assigned control of the items. The idea here is to not allow a "free for all" with users tugging at the same item. (Note this app can be done entirely in the main memory of the server. This assignment does not require that your read and write any files or use a database.)

R1.4) Server should be hosted on port 3000 and reachable from a browser on the same machine or other machines. The initial launch of the web app should be the result of the client making a request to http://localhost:3000/assignment2.html.

R1.5) More than one web browser should be able to connect to the server at the same time. Access should be possible from multiple computers.

2) Client-Server Data Exchange

R2.1) The exchange data between client and server should be in the form of JSON object strings. (The initial launch of the client web page will just be the result of a GET request for a static file.)

3) Client Requirements

R3.1) When the app first launches the client should see the environment of the app. In the case of an air hockey game it would be the playing surface, the paddles, perhaps the puck. The player should not initially be able to move anything in the app environment.

R3.2) To be allowed to control items a user must register, or sign in, or request control of a certain item. This could be done by the user typing their name and some indication of what they want to control as appropriate for your app.

R3.3) The app should have certain things that a user can move either with the mouse or keyboard strokes. To move an item, however, the user must first be given control of that item or set of items. For example, two air hocket paddles may initially be unclaimed but if a user requests that they "be" one of the paddles the server should allow them to control that paddle, but not the paddle of the opposing player. This might be done as follows. A player might type "red" into a text field and then click "assign" which will assign them to control the red paddle. This could be as simple as the server letting the client javascript know what items that client can move.

R3.4) The app should make it clear visually what items are currently being controlled by users and what items are available for users to request. For example, once a user is assigned to control of an air hockey paddle the appearance of that paddle might change -maybe have their name on it or have a certain colour or look.

R3.5) The client should only be allowed to move the items that the server has assigned them control over. If the client requests other items to control the server might add them, or instead drop control permissions of the previous item. It depends on your situation.

R3.6) If a client, with control premissions, moves an item that motion should appear in real-time accross all browser windows connected to the app. Note we are expecting you will co-ordinate the different clients through the server. This can be based on the clients simply using a timer and polling the server for updated status and locations or it could be based on the server having websocket connections with various clients. The choice is yours. Polling is easier to build but has more message traffic.

R3.7) The app should involve and show motion. That is, items moving around under user control and perhaps some moving around by themselves. If you are building a collaborative "fridge poetry" app the only motion might come from users dragging words around. If it is an air hockey game then the puck is traveling by itself with the players each moving their paddle. Games face a challenge because collisions should appear the same in all browser windows and the motion might create a lot of message traffic. Don' t worry if you motion is more "choppy" than you might have hoped for. We are looking for proof of concept here. If real-time is very important to your app the a web socket solution would likely be better than a polling solution.

4) Documentation Requirements

R4.1) Your app should be accompanied by a short .pdf document containing the items specfied below. (Your document must be in .pdf format).

R4.2) Your document should explain what the app is intended to do or what service it provides the users.

R4.3) Your document should tell the marker how to launch and run it.

R4.4) Your document should have some screen captures so the marker will have an idea what to expect before they launch your app.