Description

Assignment for Session 1, 2017

Version 1.0

Mandatory Demo: Your regular lab slot (Week 9)
Updates to the assignment, including any corrections and clarifications, will be posted on the subject website. Please make sure that you check the subject website regularly for updates.

1. Change Log

2. Goal and learning objectives

Instant messaging applications such as WhatsApp, WeChat, Facebook Messenger, etc. are widely used with millions of subscribers participating in them globally. In this assignment, you will have the opportunity to implement your own version of an instant messaging application. In addition to basic messaging functionality, you will also implement many additional services that are available in many of the aforementioned applications. Your application is based on a client server model consisting of one server and multiple messaging clients. The clients communicate with the server using TPC. The server is mainly used to authenticate the clients and direct the messages (online or offline) between clients. Besides, the server also has to support certain additional functions (presence notification, blacklisting, timeout, etc.). The extended version asks you to implement peer-to-peer messaging that bypasses the server.

2.1 Learning Objectives

On completing this assignment, you will gain sufficient expertise in the following skills:

1. Detailed understanding of how instant messaging services work.

2. Expertise in socket programming.

3. Insights into designing an application layer protocol.

3. Assignment Specification

The assignment includes 2 major modules, the server program and the client program. The server program will be run first followed by multiple instances of the client program (Each instance supports one client). They will be run from the terminals on the same and/or different hosts.
For the standard version, all messages between clients MUST be sent via the server. The extended version asks you implement additional functionality whereby two users can exchange messages with each other directly (i.e. bypassing the server) in a peer-to-peer fashion.
4.1. Server
The server has the following responsibilities –
On entering invalid credentials, the user is prompted to retry. After 3 consecutive failed attempts, the user is blocked for a duration of block_duration seconds (block_duration is a command line argument supplied to the server), and cannot login during this duration (even from another IP address). While a user is online, if someone uses the same username/password to log in (even from another IP address), then this new login attempt is denied. If the username is invalid then block access from that IP address for block_duration.
Timeout – The server should keep track of all online users. If the server does not receive any commands from a user for a period of timeout seconds (timeout is a command line argument supplied to the server), then the server should automatically log this user out. Note that, to be considered active, a user must actively issue a command. The receipt of a message does not count.
Presence Broadcasts – The server should notify the presence/absence of other users logged into the server, i.e. send a broadcast notification to all online users when a user logs in and logs out.
List of online users – The server should provide a list of users that are currently online in response to such a query from a user.
Online history – The sever should provide a list of users that logged in for a user specified time in the past (e.g. users who logged in within the past 15 minutes).
Message Forwarding – The server should forward each instant message to the correct recipient assuming they are online.
Offline Messaging – When the recipient of a message is not logged in (i.e. is offline), the message will be saved by the server. When the recipient logs in next, the server will send all the unread messages stored for that user (timestamps are not required).
Message Broadcast – The server should allow a user to broadcast a message to all online users.
Offline messaging is not required for broadcast messages.
Blacklisting – The server should allow a user to block / unblock any other user. For example, if user A has blocked user B, B can no longer send messages to A i.e. the server should intercept such messages and inform B that the message cannot be forwarded. Blocked users also do not get presence notifications i.e. B will not be informed each time A logs in or logs out. 
 4.2. Client
The client has the following responsibilities –
Authentication – The client should provide a login prompt to enable the user to authenticate with the server.
Message – The client should allow the user to send a message to any other user and display messages sent by other users. The client should also allow the user to send a broadcast message to all online users.
Notifications – The client should display presence notifications sent by the server about users logging in and out from the server.
Find users online – The client should provide a way for the user to obtain a list of all the users currently online from the server.
Find online history – The client should provide a way for the user to obtain a list of all users who had logged in within a user specified time period.
Blacklist – The client should allow a user to block a user from sending any further messages. The client should also allow a user to unblock a user that was earlier blocked.
4.3 Commands supported by the client
After a user is logged in, the client should support all the commands shown in the table below. For the following, assume that commands were run by user A.
Command Description
message <user> <message> Send <message> to <user> through the server. If the user is online then deliver the message immediately, else store the message for offline delivery. If <user> has blocked A, then a message to that effect should be displayed for A. If the <user> is not present in the credentials file (i.e. invalid user) or is self (A) then an appropriate error message should be displayed. The <message> used in our tests will be a few words at most.
broadcast <message> Send <message> to all online users except A and those users who have blocked A. Inform A that message could not be sent to some recipients.
whoelse This should display the names of all users that are currently online excluding A. Users can be displayed in any order.
whoelsesince <time> This should display the names of all users who were logged in at any time within the past <time> seconds excluding A. Note that
block <user> blocks the <user> from sending messages to A. A message should be displayed to A confirming the blocking action. If <user> is self (i.e., A) or is invalid, then an appropriate error message should be displayed. <user> must not be informed that A has blocked them.
unblock <user> unblocks the <user> who has been previously blocked by A. A message should be displayed to A confirming the unblocking action. If <user> is self (i.e., A) or is invalid or was not already blocked, then an appropriate error message should be displayed.
logout log out user A.

Any command that is not listed above should result in an error message being displayed to the user. The interaction with the user should be via the terminal (i.e. console). All messages must be displayed in the same terminal. There is no need to create separate terminals for messaging with different users.
We do not mandate the exact text that should be displayed by the client to the user for the various messages. However, you must make sure that the displayed text is easy to comprehend. Please make sure that you DO NOT print any debugging information on the client terminal.
We also prefer that you do not print anything at the terminal running the server. We suggest that you use an optional debug flag (e.g. –d) for the server. When this flag is turned on, your server can print debugging information to the terminal.
Some examples illustrating client server interaction using the above commands are provided in Section 10.
4.4 File Names & Execution

The main code for the server and client should be contained in the following files: server.c, or Server.java or server.py, and client.c or Client.java or client.py. You are free to create additional files such as header files or other class files and name them as you wish.
The server should accept the following three arguments:
• server_port: this is the port number which the server will use to communicate with the clients. Recall that a TCP socket is NOT uniquely identified by the server port number. So it is possible for multiple TCP connections to use the same server-side port number.
• block_duration: this is the duration in seconds for which a user should be blocked after three unsuccessful authentication attempts.
• timeout: this is the duration in seconds of inactivity after which a user is logged off by the server.
The server should be executed before any of the clients. It should be initiated as follows:
If you use Java:
java Server server_port block_duration timeout
If you use C:
./server server_port block_duration timeout
If you use Python: python server.py server_port block_duration timeout

The client should accept the following two arguments:
• server_IP: this is the IP address of the machine on which the server is running.
• server_port: this is the port number being used by the server. This argument should be the same as the first argument of the server.
Note that, you do not have to specify the port to be used by the client. You should allow the OS to pick a random available port. Each client should be initiated in a separate terminal as follows:
If you use Java:
java Client server_IP server_port
If you use C:
./client server_IP server_port
If you use Python: python client.py server_IP server_port
Note: When you are testing your assignment, you can run the server and multiple clients on the same machine on separate terminals. In this case, use 127.0.0.1 (local host) as the server IP address.
5. Extended Version

The client for the extended version should support the following commands (in addition to those listed in Section 4.3)

Command Description
startprivate <user> This command indicates that user A wishes to commence p2p messaging with <user>. The client should obtain the IP address and port number being used by the <user> from the server. The client should establish a TCP connection to this IP address and port number combination. A confirmation message should be displayed to A. If <user> has blocked A, then server should not provide the IP address and port number and an appropriate error message should be displayed. If <user> is offline, invalid or self then appropriate error messages should be displayed.
private <user> <message> Send <message> to <user> directly without routing through the server. If the user is no longer online at the address obtained via

6. Additional Notes
• This is NOT group assignment. You are expected to work on this individually.
• Tips on getting started: The best way to tackle a complex implementation task is to do it in stages. A good place to start would be to implement the functionality to allow a single user to login with the server. Next, add the blocking functionality for 3 unsuccessful attempts. You could then proceed to the timeout functionality (i.e. automatically logout a user after inactivity) . Then extend this to handle multiple clients. Once your server can support multiple clients, implement the functions for presence notification, whoelse and whoelsesince. Your next milestone should be to implement messaging between users. Start with broadcast, then move to online messaging and finally offline messaging. Once you have ensured that all of the above are working perfectly, add the blacklist functionality. Note that, this will require changing the implementation of some of the functionality that you have already implemented. It is imperative that you rigourously test your code to ensure that all possible (and logical) interactions can be correctly executed. Test, test and test.
• There is no requirement that you must use the same text for the various messages displayed to the user on the terminal as illustrated in the examples in Section 10. However, please make sure that the text is clear and unambiguous.
• You are encouraged to use the website (i.e. OpenLearning) to ask questions and to discuss different approaches to solve the problem. However, you should not post your solution or any code fragments on the website.
• We will arrange for additional consultations in Week 7 and Week 8 to assist you with assignment related questions. Information about the consults will be announced via the website.

7. Submission

You are required to submit your source code and report.pdf. You can submit your assignment using the give command in a terminal from any CSE machine (or connecting via SSH to the CSE login servers). Make sure you are in the same directory as your code and report, and then do the following:

1. Type tar -cvf assign.tar filenames
e.g. tar -cvf assign.tar *.java report.pdf

2. When you are ready to submit, at the bash prompt type 3331

3. Next, type: give cs3331 assign1 assign.tar (You should receive a message stating the result of your submission).

DO NOT SUBMIT ANYTHING ON OPENLEARNING.

Important notes
• The system will only accept assign.tar submission name. All other names will be rejected.

Late Submission Penalty: Late penalty will be applied as follows:
• 5 or more days late: NOT accepted

NOTE: The above penalty is applied to your final total. For example, if you submit your assignment 1 day late and your score on the assignment is 10, then your final mark will be 10 – 1 (10% penalty) = 9.

9. Marking Policy

You should test your program rigorously before submitting your code. Your code will be marked using the following criteria:

The following table outlines the marking rubric:

Functionality Marks
Successful log in and log out for single client 0.5
Blocking user for specified interval after 3 unsuccessful attempts (even from different IP) 1
Successful log in for multiple clients (from multiple machines) 1
Correct Implementation of presence notification 1
Correct Implementation of whoelse 1
Correct Implementation of whoelsesince 1
Correct Implementation of automatic logout functionality after inactivity (timeout) 1
Correct Implementation of broadcast 1
Correct Implementation of messaging between two online clients 1.5
Correct Implementation of offline messaging 1.5
Correct Implementation of user blocking and unblocking and its effects 1.5
Properly documented report 0.5
Code quality and documentation 0.5
Peer to peer Messaging (EXTENDED VERSION ONLY) 2

NOTE: While marking, we will be testing for typical usage scenarios for the above functionality and some straightforward error conditions. A typical demo will last for about 10-15 minutes during which we will initiate at most 5 clients. However, please do not hard code any specific limits in your programs. We won’t be testing your code under very complex scenarios and extreme edge cases.
10. Sample Interaction

Note that the following list is not exhaustive but should be useful to get a sense of what is expected.

Case 1: Successful Login
Terminal 1
>java Server 4000 60 120 Terminal 2
>java Client 10.11.0.3 120 (assume that server is executing on 10.11.0.3)
>Username: yoda
>Password: wise
>Welcome to the greatest messaging application ever!
>
Case 2: Unsuccessful Login (assume server is running on Terminal 1 as in Case 1)
Terminal 2
>java Client 10.11.0.3 120 (assume that server is executing on 10.11.0.3)
>Username: yoda
>Password: weird
>Invalid Password. Please try again >Password: green
>Invalid Password. Please try again
>Password: password
>Invalid Password. Your account has been blocked. Please try again later
The user should now be blocked for 60 seconds (since block_time is 60). The terminal should shut down at this point.
Terminal 2 (reopened before 60 seconds are over)
>java Client 10.11.0.3 120 (assume that server is executing on 10.11.0.3)
>Username: yoda
>Password: wise
Terminal 2 (reopened after 60 seconds are over)
>java Client 10.11.0.3 120 (assume that server is executing on 10.11.0.3)
>Username: yoda
>Password: wise
>Welcome to the greatest messaging application ever!
>

Example Interactions
Consider a scenario where three users Hans, Yoda and Luke are currently logged in. No one has yet blocked anyone else. In the following we will illustrate the text displayed at the terminals for all three users as they execute various commands. Some other examples with different users are also provided.

1. Hans executes whoelse followed by a command that is not supported
hans’s Terminal yoda’s Terminal luke’s Terminal
>whoelse
>yoda
>luke > >
>whatsthetime
>Error. Invalid command
2. Hans messages Yoda and then messages an invalid user
hans’s Terminal yoda’s Terminal luke’s Terminal
>message yoda Hey Dude
>hans: Hey Dude
>message bob party time
>Error. Invalid user
3. Hans broadcasts a message
hans’s Terminal yoda’s Terminal luke’s Terminal
>broadcast vader sucks
>hans: vader sucks >hans: vader sucks
4. Luke blocks Hans followed by a few interactions that illustrate the effect of blocking and unblocking.
hans’s Terminal yoda’s Terminal luke’s Terminal
>block hans
>hans is blocked
>broadcast I rock
>Your message could not be delivered to some
recipients
>hans: I rock
>message luke You angry?
>Your message could not be delivered as the
recipient has blocked you
>block hans
>Error. Cannot block self
>unblock yoda
>Error. yoda was not
blocked
>unblock hans
>hans is unblocked
>broadcast stormtroopers
>hans: stormtroppers >hans: stormtroppers
5. Assume that Vader was logged in 5 minutes ago but logged out 2 minutes ago and that R2D2 was logged in 10 minutes ago but logged out 5 minutes ago.
hans’s Terminal yoda’s Terminal luke’s Terminal
>whoelsesince 200
>hans
>yoda
>vader
>whoelsesince 500
>hans
>luke
>vader
>r2d2
6. Now assume that Hans and Yoda are logged in but that Luke is currently offline. Luke joins in later and receives a stored message from Hans. It also shows presence notification. Later, Yoda logs out and the corresponding notification is shown to others.
hans’s Terminal yoda’s Terminal luke’s Terminal
>message luke Let’s rock (Assume that luke logs in after this message)

>luke logged in >luke logged in
>hans: Let’s rock
>logout
>yoda logged out >yoda logged out

7. Assume that Hans, Yoda and Luke are currently logged in. Hans first tries to send a private message to Yoda without first executing startprivate. This is followed by the correct sequence of commands for private messaging. Observe that a non-private message (i.e. through the server) can also be sent by a user engaged in a private conversation.
hans’s Terminal yoda’s Terminal luke’s Terminal
>private luke hey dude
>Error. Private messaging to luke not enabled
>startprivate luke
>Start private messaging
with luke
>private luke hey dude
>hans(private): hey dude
>private hans hello
>luke(private): hello
>message yoda force is strong
>hans: force is strong
>logout
>hans logged out >hans logged out