Blog

1. Change Log
Version 1.0 released on 5th Oct 2020.
Version 1.1 released on 8th Oct 2020: minor update to naming convention
for thread/file names. Version 1.2 released on 19th Oct 2020: fixed some
minor inconsistencies.
Version 1.3 released on 4th Nov 2020: fixed some errors in the sample interaction for 2 clients.
2. Goal and learning objectives
Online discussion forums are widely used as a means for large groups of
people to hold conversations on topics of mutual interest. A good
example is the online forum used for this course. In this assignment,
you will have the opportunity to implement your own version of an online
discussion forum application. Your application is based on a client
server model consisting of one server and multiple clients communicating
either sequentially (i.e., one at a time) or concurrently. The client
and server should communicate using TCP. Your application will support a
range of functions that are typically found on discussion forums
including authentication, creation and deletion of threads and messages,
reading threads, uploading and downloading files. However, unlike
typical online forums that are accessed through HTTP, you will be
designing a custom application protocol.
2.1 Learning Objectives
On completing this assignment, you will gain sufficient expertise in the following skills:
1. Detailed understanding of how online discussion forums work.
2. Expertise in socket programming.
3. Insights into designing an application layer protocol and a fully functioning networked application.
The assignment is worth 20 marks. We will test it in two distinct
configurations. In the first instance, we will test the interaction
between the server and a SINGLE active client. All outlined
functionality will be tested. Multiple clients will connect to the
server but sequentially – one client connects, interacts, exits, the
second client connects, interacts, exits and so on. The first
configuration is worth 14 marks (70% of the total mark). In the second
instance, we will test the interaction of the server with multiple
concurrent clients. All outlined functionality will be tested. The
second configuration is worth 6 marks. Submissions from CSE students
will be tested in both configurations. Submissions from non-CSE students
will only be tested in the first configuration. The marking guidelines
are thus different for the two groups and are indicated in Section 7.
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
Non-CSE Student: The rationale for this option is that students
enrolled in a program that does not include a computer science component
have had very limited exposure to programming and in particular working
on complex programming assignments. A Non-CSE student is a student who
is not enrolled in a CSE program (single or double degree). Examples
would include students enrolled exclusively in a single degree program
such as Mechatronics or Aerospace or Actuarial Studies or Law. Students
enrolled in dual degree programs that include a CSE program as one of
the degrees do not qualify. Any student who meets this criteria and
wishes to avail of this option MUST email cs3331@cse.unsw.edu to seek
approval before 5pm, 16th October (Friday, Week 5). We will assume by
default that all students are attempting the CSE version of the
assignment unless they have sought explicit permission. No exceptions.
3. Assignment Specification
In this programming assignment, you will implement the client and server
programs of a discussion forum application, similar in many ways to the
discussion forum we use for this course. The difference being that your
application is not web-based (i.e. non-HTTP) but uses a custom
application layer protocol which you will design. The client and server
must communicate over TCP. Your application will support a range of
operations including create a new user account, create or delete a new
thread, post a message on a thread, edit or delete messages, upload and
download attachments to/from a thread, read a thread, list all threads
and shutting down the server. You will implement the application
protocol to implement these functions. The server will listen on a port
specified as the command line argument and will wait for a client to
connect. The client program will initiate a TCP connection with the
server. Upon connection establishment, the user will initiate the
authentication process. The client will interact with the user through
the command line interface. Following successful authentication, the
user will initiate one of the available commands. All commands require a
simple request response interaction between the client and server. The
user may execute a series of commands (one after the other) and
eventually quit. Both the client and server MUST print meaningful
messages at the command prompt that capture the specific interactions
taking place. You are free to choose the precise text that is displayed.
Examples of client server interactions are given in Section 8.
The assignment will be tested in two configurations. In the first
configuration, the server will interact with a single client at any
given time. Multiple clients can connect with the server in a serial
fashion, i.e., one client connects, interacts and quits, the second
client connects, interacts and quits, and so on. The server design is
significantly simplified (i.e. you won’t need to use multi-threading) if
you only wish to implement this portion of the assignment. A correct
implementation of this first part is worth 70% of the assignment marks
(14 marks, see Section 7). In the second configuration, the server must
interact with multiple clients concurrently. The client design will only
require minimal changes to meet this requirement. The server design,
however, would require a significant change, in that, the server would
need to send and receive messages to and from multiple clients
concurrently. We strongly recommend using multi- threading to achieve
this. The interaction with a single client, would however be similar as
in the first configuration. Note that, a correctly implemented
multi-threaded server should also be able to interact correctly with a
single client at any given time. So, if you design your client and
server to achieve all functionality expected for the second
configuration, it should work as expected in the first configuration.
3.1 File Names & Execution
The main code for the server and client should be contained in the following files: server.c, 2
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. Submission instructions
are in Section 5.
The server should accept the following 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. It should thus be possible for
multiple TCP connections to use the same server- side port number (in
Part 2).
admin_passwd:thisistheadminpasswordfortheserver.Itisrequiredtoshutdownthe server (see operation SHT later).
The server should be executed before any of the clients. It should be initiated as follows: If you use Java:
java Server server_port admin_passwd
If you use C:
./server server_port admin_passwd
If you use Python:
python server.py server_port admin_passwd OR python3 server.py server_port admin_passwd
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 OR python3 client.py server_IP server_port
Note: When you are testing your assignment, you should run the server
and one or more clients on the same machine in separate terminals. In
this case, use 127.0.0.1 (local host) as the server IP address.
3.2 Authentication
You may assume that a credentials file called credentials.txt will be
available in the current working directory of the server with the
correct access permissions set (read and write). This file will contain
username and passwords of authorised users. They contain uppercase
characters (A-
3
Z), lowercase characters (a-z) and digits (0-9) and special
characters (~!@#$%^&*_- +=`|(){}[]:;”‘<>,. /). An example
credentials.txt file is provided on the assignment page. We may use a
different file for testing so DO NOT hardcode this information in your
program. You may assume that each username and password will be on a
separate line and that there will be one white space between the two.
There will only be one password per username. A sample credentials file
is provided on the assignment page. We may use a different file while
testing.
Upon execution, a client should first attempt to setup a TCP connection
with the server. Assuming the connection is successful, the client
should prompt the user to enter a username. The username should be sent
to the server. The server should check the credentials file
(credentials.txt) for a match. If the username exists, the server sends a
confirmation message to the client. The client prompts the user to
enter a password. The password is sent to the server, which checks for a
match with the stored password for this user. The server sends a
confirmation if the password matches or an error message in the event of
a mismatch. An appropriate message is displayed to the user. In case,
of a mismatch, the client prompts the user to enter a username. If the
username does not exist, the sever sends an appropriate message to the
client. The client prompts the user to enter a new password. The
password is sent to the server. The server creates a new username and
password entry in the credentials file (appending it as the last entry
in the file). A confirmation is sent to the client. The client displays
an appropriate message to the user. You should make sure that write
permissions are enabled for the credentials.txt file (type “chmod +w
credentials.txt” at a terminal in the current working directory of the
server).
When your assignment is tested with multiple concurrent clients, the
server should also check that a new client that is authenticating with
the server does not attempt to login with a username that is already
being used by another active client (i.e. a username cannot be used
concurrently by two clients). The server should keep track of all active
users and check that the username provided by an authenticating client
does not match with those in this list. If a match is found, then a
message to this effect should be sent to the server and displayed at the
prompt for the user and they should be prompted to enter a username.
3.3 Discussion Forum Operations
Following successful login, the client displays a message to the user
informing them of all available commands and prompting to select one
command. The following commands are available:
If an invalid command is selected, an error message should be shown to
the user and they should be prompted to select one of the available
actions.
In the following, the implementation of each command is explained in
detail. The expected usage of each command (i.e. syntax) is included.
Note that, all commands should be upper-case (CRT, MSG, etc.). All
arguments (if any) are separated by a single white space and will be one
word long (except messages which can contain white spaces). You may
assume that all arguments including thread names, file names and the
message text may contain uppercase characters (A-Z), lowercase
characters (a-z) and digits (0-9) and the following limited set of
special characters (!@#$%. ,).
CRT: Create Thread, LST: List Threads, MSG: Post Message, DLT: Delete Message,
RDT: Read Thread, EDT: Edit Message, UPD: Upload File, DWN: Download
File, RMV: Remove Thread, XIT: Exit, SHT: Shutdown Server. All available
commands should be shown to the user in the first instance after
successful login. Subsequent prompts for actions should
include this same message.
4
If the user does not follow the expected usage of any of the
operations listed below, i.e., missing (e.g., not specifying the title
of the thread when creating a thread) or incorrect number of arguments
(e.g., inclusion of additional or fewer arguments than required) , an
error message should be shown to the user and they should be prompted to
select one of the available commands. Section 8 illustrates sample
interactions between the client and server.
There are 11 commands that users can execute. The execution of each individual command is described below.
CRT: Create Thread
CRT threadtitle
The title of the new thread (threadtitle) should be included as an
argument with this command. Thread titles are one word long. The client
should send the command (CRT), the title of the thread and the username
to the server. Each thread is represented as a text file in the current
working directory of the server with the same as the title of the thread
(threadtitle, DO NOT add “.txt” extension to the name). The first line
of the file should contain the username who created the thread. Each
subsequent line should be a message, added in the chronological sequence
in which they were posted. The server should first check if a thread
with this title exists. If so, an error message should be conveyed to
the client and displayed at the prompt to the user. If the thread does
not exist, a new file with the provided title should be created as per
the convention noted above (the first line of this file should be the
username of the creator). You may assume that the server program will
have permission to create a file in the current working directory. A
confirmation message should be sent to the server and displayed at the
prompt to the user. The client should next prompt the user to select one
of the available commands.
MSG: Post Message
MSG threadtitle message
The title of the thread that the message should be posted to and the
message should be included as arguments. Note that, the message may
contain white spaces (e.g. “hello how are you”). The client should send
the command (MSG), the title of the thread, the message and the username
to the server. In our tests, we will only use short messages (a few
words long). The server should first check if a thread with this title
exists. If so, the message and the username should be appended at the
end of the file in the format, along with the number of the message
(messages within each thread are numbered starting at 1):
messagenumber username: message
An example:
1 yoda: do or do not, there is no try
A confirmation message should be sent to the server and displayed to the
user. If the thread with this title does not exist, an error message
should be sent to the client and displayed at the prompt to the user.
The client should next prompt the user to select one of the available
commands.
5
DLT: Delete Message
DLT threadtitle messagenumber
The title of the thread from which the message is to be deleted and the
message number within that thread to be deleted should be included as
arguments. A message can only be deleted by the user who originally
posted that message. The client sends the command (DLT), the title of
the thread, the message number and the username to the server. The
server should check if a thread with this title exists and if the
corresponding message number is valid and finally if this user had
originally posted this message. In the event that any of these checks
are unsuccessful, an appropriate error message should be sent to the
client and displayed at the prompt to the user. If all checks pass, then
the server should delete the message, which entails deleting the line
containing this message in the corresponding thread file (all subsequent
messages in the file should be moved up by one line and their message
numbers should be updated appropriately) and a confirmation should be
sent to the client and displayed at the prompt to the user. The client
should next prompt the user to select one of the available commands.
EDT: Edit Message
EDT threadtitle messagenumber message
The title of the thread from which the message is to be edited, the
message number within that thread to be edited and the new message
should be included as arguments. A message can only be edited by the
user who originally posted that message. The client should send the
command (EDT), the title of the thread, the message number, the new
message and the username to the server. The server should check if a
thread with this title exists and if the corresponding message number is
valid and finally if the username had posted this message. In the event
that any of these checks are unsuccessful, an appropriate error message
should be sent to the client and displayed at the prompt to the user.
If all checks pass, then the server should replace the original message
in the corresponding thread file with the new message (the rest of the
details associated with this message, i.e. message number and username
should remain unchanged) and a confirmation should be sent to the client
and displayed at the prompt to the user. The client should next prompt
the user to select one of the commands.
LST: List Threads
LST
There should be no arguments for this command. The client sends the
command (LST) to the server. The server replies back with a listing of
all the thread titles. Only the thread titles should be listed, not the
messages. The client should print the list on the terminal (one thread
per line). If there are no active threads, then a message to that effect
should be displayed at the prompt to the user. The client should next
prompt the user to select one of the available commands.
RDT: Read Thread
RDT threadtitle
The title of the thread to be read should be included as an argument.
The client should send the command (RDT) and the title of the thread to
be read to the server. The server should check if a thread with this
title exists. If so, the server should send the contents of the file
corresponding to
6
this thread (excluding the first line which contains the username of
the creator of the thread) to the client. The client should display all
contents of the file including messages and information about uploaded
files (see next action) at the terminal to the user. If the thread with
this title does not exist, an error message should be sent to the client
and displayed at the prompt to the user. The client should next prompt
the user to select one of the available commands.
UPD: Upload file
UPD threadtitle filename
The title of the thread to which the file is being uploaded to and the
name of the file should be included as arguments. You may assume that
the file included in the argument will be available in the current
working directory of the client with the correct access permissions set
(read). You should not assume that the file will be in a particular
format, i.e., just assume that it is a binary file. The client should
send the command (UPD) and the title of the thread to the server. The
server should check if a thread with this title exists. If it does not,
then an appropriate error message should be sent to the client and
displayed at the prompt to the user. If the thread exists, then a
confirmation message should be sent to the client. The client should
next send the username and file name to the server. Following this, the
client should transfer the contents of the file to the server. The file
should be stored in the current working directory of the server with the
file name threadtitle-filename (DO NOT add an extension to the name. If
the filename has an extension in the name, retain it, e.g., test.exe
should be stored as threadtitle-test.exe). File names are case sensitive
and one word long. You may assume that the server program will have
permission to create a file in its current working directory. You may
assume that the file name will be unique for each thread (i.e., if a
file with a particular name has been uploaded to a thread, then no other
user will upload a file with that same name to that thread). However, a
file with the same name could be uploaded to a different thread. A
record of the file should be noted on the thread, i.e., an entry should
be added at the end of the file corresponding to the thread title
indicating that this user has uploaded a file with the specified name.
The format should be as follows (note the lack of a message number which
differentiates it from a message):
Username uploaded filename
The entries for file uploads cannot be edited using the EDT command or
deleted using the DLT command. They should however be included when a
thread is read using the RDT command. Finally, the server should send a
confirmation message to the client and a message to this effect should
be displayed at the prompt to the user. The client should next prompt
the user to select one of the available commands.
DWN: Download file
DWN threadtitle filename
The title of the thread from which the file is being downloaded and the
name of the file should be included as arguments. The client should send
the title of the thread and the name of the file to the server. The
server should check if a thread with this title exists and if so whether
the file with this name was previously uploaded to the thread. If
either check does not match, then an appropriate error message should be
sent to the client and displayed at the prompt to the user. If a match
is found, then the server should transfer the contents of the file to
the client. The client should write the contents to a local file in the
current working directory of the client with the same name (filename, DO
NOT include threadtitle in the file name). You may assume that the
7
client program will have permission to create a file in the current
working directory. You may also assume that a file with this same name
does not exist in the current working directory of the client. Once the
file transfer is complete, a confirmation message should be displayed at
the prompt to the user. The client should next prompt the user to
select one of the available commands. Note that, the file should NOT be
deleted at the server end. The client is simply downloading a copy of
the file.
TESTING NOTES: (1) When you test the operation of this command, you will
likely first upload a test file from the client to the server using the
previous command UPD and then try to download the same file from the
server using the DWN command. You should make sure that you remove this
file from the current working directory of the client between these two
commands (to be consistent with the assumption stated in the description
above). You can do this by opening a separate terminal and deleting
this file from the client’s working directory. (2) For similar reasons,
when testing your program under the second configuration, make sure that
the multiple clients are executed in different working directories.
RMV: Remove Thread
RMV threadtitle
The title of the thread to be removed should be included as an argument
with this action. A thread can only be removed by the user who
originally created that thread. The client should send the operation
(RMV), the title of the thread and the username to the server. The
server should first check if a thread with this title exists and if so,
whether the user who created the thread matches with the provided
username. If either check doesn’t match, then an error message should be
sent to the client and displayed at the terminal to the user. Else, the
thread is deleted including the file storing information about the
thread, any files uploaded to the thread and any state maintained about
the thread at the server. A confirmation message should be sent to the
client which is displayed at the prompt to the user. The client should
next prompt the user to select one of the available actions.
XIT: Exit
XIT
There should be no arguments for this command. The client should close
the TCP connection and exit with a goodbye message displayed at the
terminal to the user. The server should update its state information
about currently logged on users. Note that, any messages and files
uploaded by the user must not be deleted.
SHT: Shutdown
SHT admin_password
The admin password should be provided as the argument. The client should
send the command (SHT) and the admin password to the server. Note that,
the admin password is provided to the server as the second command line
argument during execution. It is NOT included in the credentials file.
The server should check the provided password against the admin
password. If the passwords do not match, then an error message should be
sent to the client and displayed at the prompt to the user. The client
should next prompt the user to select one of the available actions. If
the passwords match, then the server should initiate shutdown process.
This includes
8
sending a shutdown message to all active clients (in the case when we
are testing with multiple concurrent clients). Each client will display
an appropriate message at the terminal to the user indicating that the
discussion forum is shutting down and close the socket. The server
should delete all files that were (only) created by the server program
in the current working directory including files for all active threads
and any files uploaded to the threads and the credentials file. The
client need not delete any files in the current working directory. All
sockets should be closed.
3.3 Program Design Considerations
Transport Layer
You MUST use TCP for this assignment. This ensures that your client and
server programs do not have to worry about reliable delivery of messages
to each other. The use of UDP is likely to attract a heavy penalty.
Client Design
The client program should be fairly straightforward. The client needs to
interact with the user through the command line interface and print
meaningful messages. Section 8 provides some examples. You do not have
the use the exact same text as shown in the samples. Upon initiation,
the client should establish a TCP connection with the server and execute
the user authentication process. Following authentication, the user
should be prompted to enter one of the available commands. Almost all
commands require simple request/response interactions between the client
with the server. Note that, the client does not need to maintain any
state about the discussion forum.
Only one minor change would be needed in the client design as you
progress the implementation from the first configuration to the second
configuration. This has to do with the shutdown process. In the first
configuration, only the client currently connected to the server can
initiated the shutdown process. However, in the second configuration,
any one of the concurrently connected clients could initiate the
shutdown process. This would mean a client instance may receive a
message from the server at any time indicating that it is shutting down
(due to the issuance of the SHT command by one of the other clients).
This is the only difference with the first configuration on the client
end. A client program that correctly implements functionality for the
second configuration should be able to correctly accomplish all
interactions expected in the first configuration.
Server Design
The server code will be fairly involved compared to the client as the
server is responsible for maintaining the message forum. However, the
server design to implement functionality for the first configuration of
testing should be relatively straightforward as the server needs to only
interact with one client at a time. When the server starts up, the
forum is empty – i.e., there exist no threads, no messages, no uploaded
files. The server should wait for a client to connect, perform
authentication and service each command issued by the client
sequentially. After the client exits, the server should wait for a new
client to connect. Note that, you will need to define a number of data
structures for managing the current state of the forum (threads, posts,
files). Implementing functionality for the second configuration will
require a significant change as the server must interact with multiple
clients simultaneously. A robust way to achieve this to use
multithreading. In this approach, you will need a main thread to listen
for new connections. This can be done using the socket accept function
within a while loop. This main thread is your
9
main program. For each connected client, you will need to create a
new thread. When interacting with one particular client, the server
should receive a request for a particular operation, take necessary
action and respond accordingly to the client and wait for the next
request. This process is exactly similar to what you would have
implemented to meet the functionality of the first configuration. You
may assume that each interaction with a client is atomic. Consider that
client A initiates an interaction (i.e., a command) with the server.
While the server is processing this interaction, it cannot be
interrupted by a command from another client B. Client B’s command will
be acted upon after the command from client A is processed. Once a
client exits, the corresponding thread should also be terminated. You
should be particularly careful about how multiple threads will interact
with the various data structures. Code snippets for multi-threading in
all supported languages are available on the course webpage. A server
program that correctly implements functionality for the second
configuration should be able to correctly accomplish all interactions
expected in the first configuration.
4. 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. We recommend that you first
implement the functionality for the first configuration, i.e., the
server interacts with a single active client at any time. A good place
to start would be to implement the functionality to allow a single user
to login with the server. Next, add functionality to implement one
command. Ensure you thoroughly test the operation of each command,
including typical error conditions, and then progress to the next. We
recommend that you start with the simpler commands such as CRT, MSG, LST
before progressing to more complex commands such as UPD and DWN. Once
you have thoroughly tested your code for the first configuration,
proceed to the second configuration. It is imperative that you
rigorously test your code to ensure that all possible (and logical)
interactions can be correctly executed. Test, test and test.
Application Layer Protocol: Remember that you are implementing an
application layer protocol for realising a fully functional discussion
forum. You will have to design the format (both syntax and semantics) of
the messages exchanged between the client and server and the actions
taken by each entity on receiving these messages. We do not mandate any
specific requirements with regards the design of your application layer
protocol. We are only considered with the end result, i.e. the
functionality outlined above. You may wish to revisit some of the
application layer protocols that we have studied (HTTP, SMTP, etc.) to
see examples of message format, actions taken, etc.
Transport Layer Protocol: You should use TCP for transferring messages
between each client and server. The TCP connection should be setup by
the client on initiation and should remain active until the user exits
or one of the other concurrently connected users initiates shutdown
(only in the second con