CSSE2310/CSSE7231 — Semester 2, 2022

Assignment 4 (version 1.1)

Marks: 75 (for CSSE2310), 85 (for CSSE7231)

Weighting: 15%

Due: 6:00pm Friday 28 October, 2022

Specification changes since version 1.0 are shown in red and are summarised at the end of the document.

Introduction

The goal of this assignment is to further develop your C programming skills, and to demonstrate your un-derstanding of networking and multithreaded programming. You are to create two programs which together implement a distributed communication architecture known as publish/subscribe. One program – psserver – is a network server which accepts connections from clients (including psclient, which you will implement). Clients connect, and tell the server that they wish to subscribe to notifications on certain topics. Clients can also publish values (strings) on certain topics. The server will relay a message to all subscribers of a particular topic. Communication between the psclient and psserver is over TCP using a newline-terminated text command protocol. Advanced functionality such as connection limiting, signal handling and statistics reporting are also required for full marks. CSSE7231 students shall also implement a simple HTTP interface to psserver.

The assignment will also test your ability to code to a particular programming style. guide, to write a library to a provided API, and to use a revision control system appropriately.

Student Conduct

This is an individual assignment. You should feel free to discuss general aspects of C programming and the assignment specification with fellow students, including on the discussion forum. In general, questions like “How should the program behave if h this happensi ?” would be safe, if they are seeking clarification on the specification.

You must not actively help (or seek help from) other students or other people with the actual design, structure and/or coding of your assignment solution. It is cheating to look at another student’s assignment code and it is cheating to allow your code to be seen or shared in printed or electronic form. by others. All submitted code will be subject to automated checks for plagiarism and collusion. If we detect plagiarism or collusion, formal misconduct actions will be initiated against you, and those you cheated with. That’s right, if you share your code with a friend, even inadvertently, then both of you are in trouble. Do not post your code to a public place such as the course discussion forum or a public code repository, and do not allow others to access your computer – you must keep your code secure.

You must follow the following code referencing rules for all code committed to your SVN repository (not just the version that you submit):

Uploading or otherwise providing the assignment specification or part of it to a third party including online tutorial and contract cheating websites is considered misconduct. The university is aware of these sites and many cooperate with us in misconduct investigations.

The course coordinator reserves the right to conduct interviews with students about their submissions, for the purposes of establishing genuine authorship. If you write your own code, you have nothing to fear from this process. If you are not able to adequately explain your code or the design of your solution and/or be able to make simple modifications to it as requested at the interview, then your assignment mark will be scaled down based on the level of understanding you are able to demonstrate.

In short - Don’t risk it! If you’re having trouble, seek help early from a member of the teaching staff. Don’t be tempted to copy another student’s code or to use an online cheating service. You should read and understand the statements on student misconduct in the course profile and on the school web-site: https://www.itee.uq.edu.au/itee-student-misconduct-including-plagiarism

The publish/subscribe communication model

From wikipedia:

“In software architecture, publish-subscribe is a messaging pattern where senders of messages, called publishers, do not program the messages to be sent directly to receivers, called subscribers. Instead, senders categorise published messages into classes without knowledge of which subscribers, if any, there may be. Similarly, subscribers express interest in one or more classes and only receive messages that are of interest, without knowledge of which publishers, if any, there are.”

In this way, the participants in the communication are very loosely coupled - when publishing a message on a given topic there is no knowledge or requirement that other participant be listening for that topic. When correctly implemented, publish/subscribe can be very efficient for scaling to large numbers of participants - take a look at the wikipedia page for more details if you are interested, but this is not required to complete this assignment.

Specification – psclient

The psclient program provides a commandline interface that allows you to participate in the publish/subscribe system as a client, connecting to the server, naming the client, subscribing to and publishing topics. psclient will also output notifications when topics to which that client is subscribed, get published.

To fully implement this functionality, psclient will either require two threads (easiest), or if you wish you may use select(). Choose whichever you prefer, as long as you achieve the required functionality.

Command Line Arguments

Your psclient program is to accept command line arguments as follows:

./psclient portnum name [topic] ...

• The mandatory portnum argument indicates which localhost port psserver is listening on – either nu-merical or the name of a service.

• The mandatory name argument specifies the name to be associated with this client, e.g. barney

• Any topic arguments, if provided, are to be treated as strings which are topics to which psclient should immediately subscribe after connecting to the server, e.g. news, weather

• If no topic arguments are provided then psclient will connect to the server without subscribing to any topics.

psclient behaviour

If insufficient command line arguments are provided then psclient should emit the following message (termi- nated by a newline) to stderr and exit with status 1:

Usage: psclient portnum name [topic] ...

If the correct number of arguments is provided, then further errors are checked for in the order below.

Restrictions on the name

The name argument must not contain any spaces, colons, or newlines. The name argument must not be an empty string. If either of these conditions is not met then psclient shall emit the following message (terminated by a newline) to stderr and exit with status 2:

psclient: invalid name

Topic argument(s)

The topic arguments are optional.

All topic arguments must not contain any spaces, colons, or newlines. All topic arguments must also not be empty strings. If either of these conditions is not met for any of the topics specified on the command line then psclient shall emit the following message (terminated by a newline) to stderr and exit with status 2:

psclient: invalid topic

Duplicated topic strings are permitted – your program does not need to check for these but should instead just attempt to subscribe multiple times. (A correctly implemented server will ignore requests to subscribe to a topic that is already subscribed to.)

Connection error

If psclient is unable to connect to the server on the specified port (or service name) of localhost, it shall emit the following message (terminated by a newline) to stderr and exit with status 3:

psclient: unable to connect to port N

where N should be replaced by the argument given on the command line. (This may be a non-numerical string.)

psclient runtime behaviour

Assuming that the commandline arguments are without errors, psclient is to perform. the following actions, in this order, immediately upon starting:

• Connect to the server on the specified port number (or service name) – see above for how to handle a connection error.

• Provide the client’s name to the server using the ‘name’ command (see the Communication protocol section for details of the name command).

• Send subscription requests to the server for any topics listed on the command line, in the order that they were specified (see the Communication protocol section for details of the subscribe command).

From this point, psclient shall simply output to its stdout, any lines received over the network connection from the server, without any error checking or processing. A correctly implemented psserver will only ever send publication notices, however your psclient does not need to check for this.

Specifically – psclient is not responsible for any logic processing or error checking on messages received from the server – for example if a faulty server keeps sending psclient publication messages on a topic to which psclient never subscribed, or from which it has unsubscribed, psclient does not have to detect this. It shall simply and blindly output those messages to stdout.

If the network connection to the server is closed (e.g. psclient detects EOF on the socket), then psclient shall emit the following message to stderr and terminate with exit status 4:

psclient: server connection terminated

Simultaneously and asynchronously, psclient shall be reading newline-terminated lines from stdin, and sending those lines unmodified to the server (effectively, this interface requires the user to type in command strings that are sent to the server – this simplifies the implementation of psclient dramatically). The three valid message types are:

• pub <topic> <value> – publish <value> under topic <topic>. Note that <value>s may contain spaces and colons.

• sub <topic> – subscribe this client to topic <topic>.

• unsub <topic> – unsubscribe this client from future publication of <topic>.

Note that psclient is not required to perform. any error checking on the input lines – simply send them unmodified to the server. In this sense, psclient is a lot like netcat.

If psclient detects EOF on stdin or some other communication error, it shall terminate with exit status 0.

Your psclient program is not to register any signal handers nor attempt to mask or block any signals.

psclient example usage

Subscribing to a topic from the commandline, then sending an invalid publish (missing value) and then imme-diately publishing on that same topic and receiving the publication notice back from the server (assuming the psserver is listening on port 49152). Lines in bold face are typed interactively on the console, they are not part of the output of the program:

$./psclient 49152 fred topic1

pub topic1

:invalid

pub topic1 value 1

fred:topic1:value 1

Subscribing to a topic interactively, publishing on it (and receiving the publication notice back from the server), unsubscribing, then publishing again:

$./psclient 49152 fred

sub topic1

pub topic1 value1

fred:topic1:value1

unsub topic1

pub topic1 value1

Here you can see that the publishing of ‘topic1’ after subscribing, causes the client to receive the publica- tion notice as expected. Then the client unsubscribes, and no notification is subsequently received despite the republication of the same topic.

Subscribing to several topics on the command line, and having these published by other clients at some point after connecting:

$./psclient 49152 fred topic1 topic2

...

barney:topic1:value 1

...

wilma:topic2:value:2

barney:topic2:some Value

...

unsub topic1

wilma:topic2:a String Here

...

Note that after sending the ‘unsub’ command, and assuming a correctly functioning server, we do not expect this client to receive any further publication messages regarding ‘topic1’. Messages on other subscribed topics will still be received.

Specification – psserver

psserver is a networked publish/subscribe server, allowing clients to connect, name themselves, subscribe to and unsubscribe from topics, and publish messages setting values for topics. All communication between clients and the server is over TCP using a simple command protocol that will be described in a later section.

Command Line Arguments

Your psserver program is to accept command line arguments as follows:

./psserver connections [portnum]

In other words, your program should accept one mandatory argument (connections), and one optional argument which is the port number to listen on for connections from clients.

The connections argument indicates the maximum number of simultaneous client connections to be per- mitted. If this is zero, then there is no limit to how many clients may connect (other than operating system limits which we will not test).

The portnum argument, if specified, indicates which localhost port psserver is to listen on. If the port number is absent or zero, then psserver is to use an ephemeral port.

Important: Even if you do not implement the connection limiting functionality, your program must correctly handle command lines which include that argument (after which it can ignore any provided value – you will simply not receive any marks for that feature).