Introduction

The goal of this assignment is to further develop your C programming skills, and to demonstrate your under-

standing of networking and multithreaded programming.   You are to create two programs.   One – dbserver

– is a networked database server that takes requests from clients, allowing them to store, retrieve and delete

string-based key/value pairs.  The other – dbclient – is a simple network client that can query the database

managed by dbserver.  Communication between the dbclient and dbserver is done using HTTP requests and

responses,  using a  simple  RESTful API. Advanced  functionality  such as authentication,  connection  limiting,

signal handling and statistics reporting are also required for full marks.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  〈this  happens）?”   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.

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

they 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.

//www.itee.uq.edu.au/itee-student-misconduct-including-plagiarism

Specification – dbclient

The dbclient program provides a commandline interface to allow access to a subset of the dbserver’s capabil-

ities, in particular it permits only the setting and retrieving of key/value pairs.  It does not support dbserver

authentication, or deletion of key/value pairs. Note that you will need to read the dbserver specification

below also to fully understand how the programs communicate.

dbclient does not need to be multithreaded.

Command Line Arguments

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

./dbclient  portnum  key  [value]

● The portnum argument indicates which localhost port dbserver is listening on – either numerical or the

name of a service.

●  The key argument specifies the key to be read or written.

● The value argument, if provided, specifies the value to be written to the database for the corresponding

key. If value is not provided, then dbclient will read the value from the database.

● Any additional arguments are to be silently ignored.

dbclient Behaviour

If insufficient command line arguments are provided then dbclient should emit the following message (termi-

nated by a newline) to stderr and exit with status 1:

Usage: dbclient portnum key [value]

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

Restrictions on the key value

The key value must not contain any spaces or newlines. If it does then dbclient should emit the following

message (terminated by a newline) to stderr and exit with status 1:

dbclient: key must not contain spaces or newlines

The key (and associated value) may be empty strings. The value associated with a key may contain any character

other than a null character.

Connection error

If dbclient is unable to connect to the server on the specified port of localhost, it shall emit the following

message (terminated by a newline) to stderr and exit with status 2:

dbclient: unable to connect to port N

where N should be replaced by the argument given on the command line.

GETting key/value pairs

If no value argument is specified, then dbclient shall send a GET HTTP request to the dbserver for the

specified key in the public database. The HTTP request will look like this:

GET /public/<key> HTTP/1.1

where  is replaced by the requested database key. Note that the request (first) line must be terminated by

a carriage-return line-feed  (CRLF) sequence  (CRLF = \r\n) and be followed by a similarly-terminated blank

line. There is no body part necessary in the request.

If the server returns a  200  (OK) response, then  dbclient shall emit the returned value string to  stdout

(with a terminating newline), and exit with status 0.

If the server returns any other response (e.g. 404 Not Found) or the connection with the server is lost, then

dbclient shall emit no output, and exit with status 3.

PUT /public/<key> HTTP/1.1 Content-Length: <N> <value>

where  and  are replaced with the required key and value strings respectively, and  is replaced

by  the  number  of bytes  in  .  As  always,  lines  in  a  HTTP  request  should  be  terminated  by  a  CRLF

sequence. The body part of the request must be the unmodified value part of the key-value pair – no newlines

are present unless they are part of the value.

If the server returns a 200 (OK) response, then dbclient shall exit with status 0. If the server returns any

other response  (e.g. 404 Not Found or 503 Service Unavailable) or the connection with the server is lost, then

dbclient shall exit with status 4.

dbclient example usage

Setting and reading values from the database (assuming the dbserver is listening on port 49152):

Using shell quoting for values containing spaces and/or newlines:

$ ./dbclient 49152 key "my long value spread over two lines" $ ./dbclient 49152 key my long value spread over two lines

Attempting to read a missing key:

$ ./dbclient 49152 badkey $ echo $? 3

Failed attempt to write a key/value pair:

Specification – dbserver

dbserver is a networked database server, capable of storing and returning text-based key/value pairs. Client

requests and server responses are communicated over HTTP.

The GET operation permits a client to query the database for the provided key. If present, the server returns

the corresponding stored value.

The PUT operation permits a client to store a key/value pair. If a value is already stored for the provided

key, then it is replaced by the new value.

The DELETE operation permits a client to delete a stored key/value pair.

dbserver must implement at least one database instance, known as public, which can be accessed by any   connecting client without authentication.                                   advanced functionality and additional marks, dbserver must manage a second database instance, called  private, access to which is only permitted if the client provides the correct authentication string in the HTTP

request headers. This functionality will be described in detail below.

Command Line Arguments

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

./dbserver  authfile  connections  [portnum]   In other words, your program should accept two mandatory arguments (authfile and connections), and    108 one optional argument which is the port number to listen on.                                                       The authfile argument is the name of a text file, the first line of which is to be used as an authentication  string (see below for details).                                                                                                                                       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 dbserver is to listen on. If the port   

number is absent, then dbserver is to use an ephemeral port.  

Important: Even  if you  do  not  implement  the  authentication  or  connection  limiting  functionality,  your 

program must still correctly handle command lines which include those arguments (after which it can ignore   any provided values – you will simply not receive any marks for those features).

Program Operation

The dbserver program is to operate as follows:

● If the program receives an invalid command line then it must print the message:

Usage: dbserver authfile connections [portnum]

to stderr, and exit with an exit status of 1.

Invalid command lines include (but may not be limited to) any of the following:

– no authfile or connections number specified

– the connections argument is not a non-negative integer

– the port number argument (if present) is not an integer value, or is an integer value and is not either  zero, or in the range of 1024 to 65535 inclusive

– too many arguments are supplied

● If authfile cannot be opened for reading, or the first line is empty then dbserver shall emit the following  message to stderr and terminate with exit status 2:

dbserver: unable to read authentication string

● If portnum is missing or zero, then dbserver shall attempt to open an ephemeral localhost port for   listening. Otherwise, it shall attempt to open the specific port number. If the authentication string can be  read but dbserver is unable to listen on either the ephemeral or specific port, it shall emit the following  message to stderr and terminate with exit status 3:

dbserver: unable to open socket for listening

●  Once the port is opened for listening, dbserver shall print the port number to stderr, followed by a  single newline character, and then flush the output. In the case of an ephemeral port, the actual  port number obtained shall be printed, not zero.

●  Upon receiving an incoming client connection on the port, dbserver shall spawn a new thread to handle  that client (see below for client thread handling).

● If specified  (and implemented), dbserver must keep track of how many client connections have been   made, and must not let that number exceed the connections parameter. See below on client handling  threads for more details on how this limit is to be implemented.

● Note that all error messages must be terminated by a single newline character.

●  The dbserver program should not terminate under normal circumstances, nor should it block or otherwise attempt to handle SIGINT.

●  Note that your dbserver must be able to deal with any clients using the correct communication protocol,  not just dbclient. In particular, note that dbclient will only send one request per connection but other  clients may send multiple requests per connection.

Client handling threads

protocol section below.

To deal with multiple simultaneous client requests, your dbserver will need some sort of mutual exclusion  structure around access to your key-value store.

Once the client disconnects or there is a communication error on the socket or a badly formed request is

received then the client handler thread is to close the connection, clean up and terminate. (A properly formed

request for an unavailable service shall be rejected with a Bad Request response – it will not result in termination

of the client thread.)

SIGHUP handling (Advanced)

Upon receiving SIGHUP, dbserver is to emit (and flush) to stderr statistics reflecting the program’s operation to-date, specifically

● Total number of clients connected (at this instant)

● The total number of clients that have connected and disconnected since program start

● The total number of authentication failures (since program start)

●  The total number of successful GET requests processed (since program start)

●  The total number of successful PUT requests received (since program start)

●  The total number of successful DELETE requests received (since program start)