共计 40477 个字符，预计需要花费 102 分钟才能阅读完成。
The University of Queensland
School of Information Technology and Electrical Engineering
CSSE2310/CSSE7231 — Semester 1, 2022
Assignment 4 (version 1.2 – 26 May 2022)
Marks: 75 (for CSSE2310), 85 (for CSSE7231)
Weighting: 15%
Due: 4:00pm Friday 3 June, 2022
Specification changes since version 1.1 are shown in blue and are summarised at the end of the document.
Introduction 1
The goal of this assignment is to further develop your C programming skills, and to demonstrate your under- 2
standing of networking and multithreaded programming. You are to create two programs. One – dbserver 3
– is a networked database server that takes requests from clients, allowing them to store, retrieve and delete 4
string-based key/value pairs. The other – dbclient – is a simple network client that can query the database 5
managed by dbserver. Communication between the dbclient and dbserver is done using HTTP requests and 6
responses, using a simple RESTful API. Advanced functionality such as authentication, connection limiting, 7
signal handling and statistics reporting are also required for full marks. 8
The assignment will also test your ability to code to a particular programming style guide, to write a library 9
to a provided API, and to use a revision control system appropriately. 10
Student Conduct 11
This is an individual assignment. You should feel free to discuss general aspects of C programming and 12
the assignment specification with fellow students, including on the discussion forum. In general, questions like 13
“How should the program behave if hthis happensi?”would be safe, if they are seeking clarification on the 14
specification. 15
You must not actively help (or seek help from) other students or other people with the actual design, structure 16
and/or coding of your assignment solution. It is cheating to look at another student’s assignment code 17
and it is cheating to allow your code to be seen or shared in printed or electronic form by others. 18
All submitted code will be subject to automated checks for plagiarism and collusion. If we detect plagiarism or 19
collusion, formal misconduct actions will be initiated against you, and those you cheated with. That’s right, if 20
you share your code with a friend, even inadvertently, then both of you are in trouble. Do not post your 21
code to a public place such as the course discussion forum or a public code repository, and do not allow others 22
to access your computer – you must keep your code secure. 23
You must follow the following code referencing rules for all code committed to your SVN repository (not 24
just the version that you submit): 25
Code Origin Usage/Referencing
Code provided to you in writing this semester by
CSSE2310/7231 teaching staff (e.g. code hosted on Blackboard,
posted on the discussion forum, or shown in class).
May be used freely without reference. (You must be able
to point to the source if queried about it.)
Code you have personally written this semester for
CSSE2310/7231 (e.g. code written for A1 reused in A3)
May be used freely without reference. (This assumes
that no reference was required for the original use.)
Code examples found in man pages on moss.
May be used provided the source of the code is
referenced in a comment adjacent to that code.
Code you have personally written in a previous enrolment
in this course or in another ITEE course and where that
code has not been shared or published.
Code (in any programming language) that you have taken
inspiration from but have not copied.
Other code – includes: code provided by teaching staff only
in a previous offering of this course (e.g. previous A1 solution);
code from websites; code from textbooks; any code
written by someone else; and any code you have written
that is available to other students.
May not be used. If the source of the code is referenced
adjacent to the code then this will be considered code
without academic merit (not misconduct) and will be
removed from your assignment prior to marking (which
may cause compilation to fail). Copied code without
adjacent referencing will be considered misconduct and
action will be taken.
26
1 Version 1.2
Uploading or otherwise providing the assignment specification or part of it to a third party including online 27
tutorial and contract cheating websites is considered misconduct. The university is aware of these sites and 28
they cooperate with us in misconduct investigations. 29
The course coordinator reserves the right to conduct interviews with students about their submissions, for 30
the purposes of establishing genuine authorship. If you write your own code, you have nothing to fear from this 31
process. If you are not able to adequately explain your code or the design of your solution and/or be able to 32
make simple modifications to it as requested at the interview, then your assignment mark will be scaled down 33
based on the level of understanding you are able to demonstrate. 34
In short – Don’t risk it! If you’re having trouble, seek help early from a member of the teaching staff. 35
Don’t be tempted to copy another student’s code or to use an online cheating service. You should read and 36
understand the statements on student misconduct in the course profile and on the school web-site: https: 37
//www.itee.uq.edu.au/itee-student-misconduct-including-plagiarism 38
Specification – dbclient 39
The dbclient program provides a commandline interface to allow access to a subset of the dbserver’s capabil- 40
ities, in particular it permits only the setting and retrieving of key/value pairs. It does not support dbserver 41
authentication, or deletion of key/value pairs. Note that you will need to read the dbserver specification 42
below also to fully understand how the programs communicate. 43
dbclient does not need to be multithreaded. 44
Command Line Arguments 45
Your dbclient program is to accept command line arguments as follows: 46
./dbclient portnum key [value] 47
• The portnum argument indicates which localhost port dbserver is listening on – either numerical or the 48
name of a service. 49
• The key argument specifies the key to be read or written. 50
• The value argument, if provided, specifies the value to be written to the database for the corresponding 51
key. If value is not provided, then dbclient will read the value from the database. 52
• Any additional arguments are to be silently ignored. 53
dbclient Behaviour 54
If insufficient command line arguments are provided then dbclient should emit the following message (termi- 55
nated by a newline) to stderr and exit with status 1: 56
Usage: dbclient portnum key [value]
If the correct number of arguments is provided, then further errors are checked for in the order below. 57
Restrictions on the key value 58
The key value must not contain any spaces or newlines. If it does then dbclient should emit the following 59
message (terminated by a newline) to stderr and exit with status 1: 60
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 61
other than a null character. 62
Connection error 63
If dbclient is unable to connect to the server on the specified port of localhost, it shall emit the following 64
message (terminated by a newline) to stderr and exit with status 2: 65
dbclient: unable to connect to port N
where N should be replaced by the argument given on the command line. 66
2 Version 1.2
GETting key/value pairs 67
If no value argument is specified, then dbclient shall send a GET HTTP request to the dbserver for the 68
specified key in the public database. The HTTP request will look like this: 69
GET /public/<key> HTTP/1.1
where <key> is replaced by the requested database key. Note that the request (first) line must be terminated by 70
a carriage-return line-feed (CRLF) sequence (CRLF = \r\n) and be followed by a similarly-terminated blank 71
line. There is no body part necessary in the request. 72
If the server returns a 200 (OK) response, then dbclient shall emit the returned value string to stdout 73
(with a terminating newline), and exit with status 0. 74
If the server returns any other response (e.g. 404 Not Found) or the connection with the server is lost, then 75
dbclient shall emit no output, and exit with status 3. 76
PUTting key/value pairs 77
If value is specified, then dbclient shall attempt to set the corresponding key/value pair, using a PUT HTTP 78
request as follows (see the Communication protocol section below for details): 79
PUT /public/<key> HTTP/1.1
Content-Length: <N>
<value>
where <key> and <value> are replaced with the required key and value strings respectively, and <N> is replaced 80
by the number of bytes in <value>. As always, lines in a HTTP request should be terminated by a CRLF 81
sequence. The body part of the request must be the unmodified value part of the key-value pair – no newlines 82
are present unless they are part of the value. 83
If the server returns a 200 (OK) response, then dbclient shall exit with status 0. If the server returns any 84
other response (e.g. 404 Not Found or 503 Service Unavailable) or the connection with the server is lost, then 85
dbclient shall exit with status 4. 86
dbclient example usage 87
Setting and reading values from the database (assuming the dbserver is listening on port 49152): 88
$ ./dbclient 49152 mykey myvalue
$ echo $?
0
$ ./dbclient 49152 mykey
myvalue
$ echo $?
0
Using shell quoting for values containing spaces and/or newlines: 89
$ ./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: 90
$ ./dbclient 49152 badkey
$ echo $?
3
3 Version 1.2
Failed attempt to write a key/value pair: 91
$ ./dbclient 49152 somekey somevalue
$ echo $?
4
$ ./dbclient 49152 somekey
$ echo $?
3
Specification – dbserver 92
dbserver is a networked database server, capable of storing and returning text-based key/value pairs. Client 93
requests and server responses are communicated over HTTP. 94
The GET operation permits a client to query the database for the provided key. If present, the server returns 95
the corresponding stored value. 96
The PUT operation permits a client to store a key/value pair. If a value is already stored for the provided 97
key, then it is replaced by the new value. 98
The DELETE operation permits a client to delete a stored key/value pair. 99
dbserver must implement at least one database instance, known as public, which can be accessed by any 100
connecting client without authentication. 101
For advanced functionality and additional marks, dbserver must manage a second database instance, called 102
private, access to which is only permitted if the client provides the correct authentication string in the HTTP 103
request headers. This functionality will be described in detail below. 104
Command Line Arguments 105
Your dbserver program is to accept command line arguments as follows: 106
./dbserver authfile connections [portnum] 107
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. 109
The authfile argument is the name of a text file, the first line of which is to be used as an authentication 110
string (see below for details). 111
The connections argument indicates the maximum number of simultaneous client connections to be per- 112
mitted. If this is zero, then there is no limit to how many clients may connect (other than operating system 113
limits which we will not test). 114
The portnum argument, if specified, indicates which localhost port dbserver is to listen on. If the port 115
number is absent, then dbserver is to use an ephemeral port. 116
Important: Even if you do not implement the authentication or connection limiting functionality, your 117
program must still correctly handle command lines which include those arguments (after which it can ignore 118
any provided values – you will simply not receive any marks for those features). 119
Program Operation 120
The dbserver program is to operate as follows: 121
• If the program receives an invalid command line then it must print the message: 122
Usage: dbserver authfile connections [portnum]
to stderr, and exit with an exit status of 1. 123
Invalid command lines include (but may not be limited to) any of the following: 124
– no authfile or connections number specified 125
– the connections argument is not a non-negative integer 126
– the port number argument (if present) is not an integer value, or is an integer value and is not either 127
zero, or in the range of 1024 to 65535 inclusive 128
– too many arguments are supplied 129
4 Version 1.2
• If portnum is missing or zero, then dbserver shall attempt to open an ephemeral localhost port for 130
listening. Otherwise, it shall attempt to open the specific port number. 131
• If authfile cannot be opened for reading, or the first line is empty then dbserver shall emit the following 132
message to stderr and terminate with exit status 2: 133
dbserver: unable to read authentication string
• If portnum is missing or zero, then dbserver shall attempt to open an ephemeral localhost port for 134
listening. Otherwise, it shall attempt to open the specific port number. If the authentication string can be 135
read but dbserver is unable to listen on either the ephemeral or specific port, it shall emit the following 136
message to stderr and terminate with exit status 3: 137
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 138
single newline character, and then flush the output. In the case of an ephemeral port, the actual 139
port number obtained shall be printed, not zero. 140
• Upon receiving an incoming client connection on the port, dbserver shall spawn a new thread to handle 141
that client (see below for client thread handling). 142
• If specified (and implemented), dbserver must keep track of how many client connections have been 143
made, and must not let that number exceed the connections parameter. See below on client handling 144
threads for more details on how this limit is to be implemented. 145
• Note that all error messages must be terminated by a single newline character. 146
• The dbserver program should not terminate under normal circumstances, nor should it block or otherwise 147
attempt to handle SIGINT. 148
• Note that your dbserver must be able to deal with any clients using the correct communication protocol, 149
not just dbclient. In particular, note that dbclient will only send one request per connection but other 150
clients may send multiple requests per connection. 151
Client handling threads 152
A client handler thread is spawned for each incoming connection. This client thread must then wait for HTTP 153
requests, one at a time, over the socket. The exact format of the requests is described in the Communication 154
protocol section below. 155
To deal with multiple simultaneous client requests, your dbserver will need some sort of mutual exclusion 156
structure around access to your key-value store. 157
Once the client disconnects or there is a communication error on the socket or a badly formed request is 158
received then the client handler thread is to close the connection, clean up and terminate. (A properly formed 159
request for an unavailable service shall be rejected with a Bad Request response – it will not result in termination 160
of the client thread.) 161
SIGHUP handling (Advanced) 162
Upon receiving SIGHUP, dbserver is to emit (and flush) to stderr statistics reflecting the program’s operation 163
to-date, specifically 164
• Total number of clients connected (at this instant) 165
• The total number of clients that have connected and disconnected since program start 166
• The total number of authentication failures (since program start) 167
• The total number of successful GET requests processed (since program start) 168
• The total number of successful PUT requests received (since program start) 169
• The total number of successful DELETE requests received (since program start) 170
5 Version 1.2
The required format is illustrated below. 171
Listing 1: dbserver SIGHUP stderr output sample
Connected clients:4
Completed clients:20
Auth failures:4
GET operations:4
PUT operations:15
DELETE operations:0
Note that to accurately account these statistics and avoid race conditions, you will need some sort of mutual 172
exclusion structure protecting the variables holding these statistics. 173
Client connection limiting (Advanced) 174
If the connections feature is implemented and a non-zero command line argument is provided, then dbserver 175
must not permit more than that number of simultaneous client connections to the database. dbserver shall 176
maintain a connected client count, and if a client beyond that limit attempts to connect, dbserver shall send 177
a 503 (Service Unavailable) HTTP response to that client and immediately terminate the connection. A client 178
that connects and is immediately disconnected in this way is not counted in the number of clients for statistics 179
purposes. 180
Program output 181
Other than error messages, the listening port number, and SIGHUP-initiated statistics output, dbserver is not 182
to emit any output to stdout or stderr. 183
Communication protocol 184
The communication protocol uses HTTP. The client (dbclient, or other program such as netcat) shall send 185
HTTP requests to the server, as described below, and the server (dbserver) shall send HTTP responses as 186
described below. The connection between client and server is kept alive between requests. Supported request 187
types are GET, PUT and DELETE requests. 188
Additional HTTP header lines beyond those specified may be present in requests or responses and must be 189
ignored by the respective server/client. Note that interaction between dbclient and dbserver is synchronous – a 190
single client can only have a single request underway at any one time. This greatly simplifies the implementation 191
of dbclient and the dbserver client-handling threads. 192
• Request: GET /public/key HTTP/1.1 193
– Description: the client is requesting the value associated with the provided key, from the public 194
database instance. 195
– Request 196
∗ Request Headers: none expected, any headers present will be ignored by dbserver. 197
∗ Request Body: none, any request body will be ignored 198
– Response 199
∗ Response Status: either 200 (OK) or 404 (Not Found). 200 will be returned if the provided key 200
exists in the database, otherwise 404 will be returned. 201
∗ Response Headers: the Content-Length header with correct value is required (number of bytes 202
in the response body), other headers are optional. 203
∗ Response Body: the corresponding value from the public database (or empty if the key is not 204
found). 205
• Request: PUT /public/key HTTP/1.1 206
– Description: the client is requesting the server to write a key/value pair to the public database. 207
– Request 208
6 Version 1.2
∗ Request Headers: the Content-Length header is expected (the value will be the number of bytes 209
in the request body). This header may be omitted if the body length is zero, i.e. the value is the 210
empty string. Other headers shall be ignored. 211
∗ Request Body: the value to be set for the corresponding key/value pair. 212
– Response 213
∗ Response Status: either 200 (OK) or 500 (Internal Server Error). 200 will be returned if the 214
database update operation succeeds, otherwise 500 will be returned. 215
∗ Response Headers: the Content-Length: 0 header is expected (the zero value is the number of 216
bytes in the response body), other headers are optional. 217
∗ Response Body: None. 218
• Request: DELETE /public/key HTTP/1.1 219
– Description: the client is requesting the server to delete a key/value pair from the public database. 220
– Request 221
∗ Request Headers: none expected, any headers present will be ignored by dbserver. 222
∗ Request Body: None. 223
– Response 224
∗ Response Status: either 200 (OK) or 404 (Not Found). 200 will be returned if the database delete 225
operation succeeds, otherwise 404 will be returned. 226
∗ Response Headers: the Content-Length: 0 header is expected, other headers are optional. 227
∗ Response Body: None. 228
• Any other (well-formed) requests should result in dbserver sending a 400 (Bad Request) HTTP response. 229
Badly formed requests (i.e. the data received can not be parsed as a HTTP request) will result in the 230
server disconnecting the client (as described earlier). Note that any attempt to use a space in the key will 231
be interpreted as a bad request because the HTTP request line will have too many spaces. Note that it is 232
permissible for the key (and the associated value) to be an empty string. 233
Advanced communication protocol – authentication 234
If implemented, the HTTP request Authorization: header may be used (note American spelling with a‘z’), 235
along with an authentication string, to access the private database instance. This access is identical to the 236
standard protocol above, with the following extensions 237
• All URL addresses become /private/key 238
• The request header “Authorization: <authstring>” must be provided, where <authstring> is replaced 239
by the correct authentication string. Note that leading and trailing spaces will be removed from the 240
<authstring> (as per the HTTP protocol) so authentication strings with leading and/or trailing spaces 241
are not supported – and will not be tested. 242
• If the authentication header is not provided, or is incorrect, dbserver is to respond with the HTTP 243
response“401 (Unauthorized)”244
Note that library functions are provided to you to do most of the work of parsing/constructing HTTP request- 245
s/responses. See below. 246
The stringstore database library and API 247
An API (Application Programming Interface) for the database implementation, known as‘StringStore’, is pro- 248
vided to you in the form of a header file, found on moss in /local/courses/csse2310/include/stringstore.h. 249
An implementation of stringstore is also available to you on moss, in the form of a shared library file 250
(/local/courses/csse2310/lib/libstringstore.so). 251
However, to receive full marks you must implement your own version of StringStore according 252
to the API specified by stringstore.h. You must submit your stringstore.c and your Makefile must build 253
this to your own libstringstore.so. 254
This will allow you to start writing dbserver without first implementing the underlying database. 255
7 Version 1.2
Your dbserver must use this API and link against libstringstore.so. Note that we will use our 256
libstringstore.so when testing your dbserver so that you are not penalised in the marking of dbserver for 257
any bugs in your StringStore implementation. You are free to use your own libstringstore.so when testing 258
yourself – see below. 259
stringstore.h defines the following functions: 260
Listing 2: stringstore.h contents
/// Opaque type for StringStore – you’ll need to define ‘struct StringStore’
// in your stringstore.c file
typedef struct StringStore StringStore;
// Create a new StringStore instance, and return a pointer to it
StringStore *stringstore_init(void);
// Delete all memory associated with the given StringStore, and return NULL
StringStore stringstore_free(StringStore store);
// Add the given ‘key’/’value’ pair to the StringStore ‘store’.
// The ‘key’ and ‘value’ strings are copied with strdup() before being
// added to the database. Returns 1 on success, 0 on failure (e.g. if
// strdup() fails).
int stringstore_add(StringStore store, const char key, const char *value);
// Attempt to retrieve the value associated with a particular ‘key’ in the
// StringStore ‘store’.
// If the key exists in the database, return a const pointer to corresponding
// value string.
// If the key does not exist, return NULL
const char stringstore_retrieve(StringStore store, const char *key);
// Attempt to delete the key/value pair associated with a particular ‘key’ in
// the StringStore ‘store’.
// If the key exists and deletion succeeds, return 1.
// Otherwise, return 0
int stringstore_delete(StringStore store, const char key);
Note that it is not expected that your StringStore library be thread safe – the provided libstringstore.so 261
is not. 262
Creating shared libraries – libstringstore.so 263
This section is only relevant if you are creating your own implementation of libstringstore.o. 264
Special compiler and linker flags are required to build shared libraries. Here is a Makefile fragment you can 265
use to turn stringstore.c into a shared library, libstringstore.so: 266
Listing 3: Makefile fragment to compile and build a shared library
CC=gcc
LIBCFLAGS=-fPIC -Wall -pedantic -std=gnu99
Turn stringstore.c into stringstore.o
stringstore.o: stringstore.c stringstore.h
$(CC) $(LIBCFLAGS) -c $<
Turn stringstore.o into shared library libstringstore.so
libstringstore.so: stringstore.o
$(CC) -shared -o $@ stringstore.o
stringstore.h should only be listed as a dependency in your Makefile if you have a local copy in your repository. 267
This is not required, but if you do include a copy of stringstore.h in your submission then it must be styled 268
correctly. 269
8 Version 1.2
Running dbserver with your libstringstore.so library 270
The shell environment variable LD_LIBRARY_PATH specifies the path (set of directories) searched for shared li- 271
braries. On moss, by default this includes /local/courses/csse2310/lib, which is where the provided libraries 272
libcsse2310a4.so and our implementation of libstringstore.so live. 273
If you are building your own version and wish to use it when you run dbserver, then you’ll need to make 274
sure that your version of libstringstore.so is used. To do this you can use the following: 275
LD_LIBRARY_PATH=.:${LD_LIBRARY_PATH} ./dbserver 276
This commandline sets the LD_LIBRARY_PATH just for this specific run of dbserver, causing it to 277
dynamically link against your version of libstringstore.so in the current directory instead of the one we 278
have provided. 279
Note that we will use our libstringstore.so when testing your dbserver. Your libstringstore.so will 280
be tested independently. 281
Provided Libraries 282
libstringstore 283
See above. This must be linked with -L/local/courses/csse2310/lib -lstringstore. Do not statically link 284
your own stringstore.o into your dbserver or hardwire the path to libstringstore.so. If you wish to test 285
your own libstringstore.so then you can use the approach described above. 286
libcsse2310a4 287
Several library functions have been provided to you to aid parsing/construction of HTTP requests/responses. 288
These are: 289
char* split_by_char(char str, char split, unsigned int maxFields);
int get_HTTP_request(FILE *f, char method, char address,
HttpHeader *headers, char body);
char construct_HTTP_response(int status, char statusExplanation,
HttpHeader* headers, char body);
int get_HTTP_response(FILE f, int httpStatus, char** statusExplain,
HttpHeader* headers, char body);
void free_header(HttpHeader* header);
void free_array_of_headers(HttpHeader** headers);
These functions and the HttpHeader type are declared in /local/courses/csse2310/include/csse2310a4.h 290
on moss and their behaviour is described in man pages on moss – see split_by_char(3), get_HTTP_request(3), 291
and free_header(3). 292
To use these library functions, you will need to add #include <csse2310a4.h> to your code and use the 293
compiler flag -I/local/courses/csse2310/include when compiling your code so that the compiler can find 294
the include file. You will also need to link with the library containing these functions. To do this, use the 295
compiler arguments -L/local/courses/csse2310/lib -lcsse2310a4 296
(You only need to specify the -I and -L flags once if you are using multiple libraries from those locations, 297
e.g. both libstringstore and libcsse2310a4.) 298
libcsse2310a3 299
You are also welcome to use the “libcsse2310a3” library from Assignment 3 if you wish. This can be linked 300
with -L/local/courses/csse2310/lib -lcsse2310a3. 301
9 Version 1.2
Style 302
Your program must follow version 2.2 of the CSSE2310/CSSE7231 C programming style guide available on the 303
course Blackboard site. Note that, in accordance with the style guide, function comments are not expected in 304
your stringstore.c for functions that are declared and commented in stringstore.h. 305
Hints 306
- Review the lectures related to network clients, HTTP, threads and synchronisation and multi-threaded 307
network servers. This assignment builds on all of these concepts. 308 - Write a small program to explore the basic HTTP request/response patterns, and associated API functions 309
in libcsse2310a4.so. 310 - You can test dbclient and dbserver independently using netcat as demonstrated in the lectures. You 311
can also use the provided demo programs demo-dbclient and demo-dbserver. 312 - The read_line() function from libcsse2310a3 may be useful for reading the authentication key. 313
- The multithreaded network server example from the lectures can form the basis of dbserver. 314
- Use the provided library functions (see above). 315
- Consider a dedicated signal handling thread for SIGHUP. pthread_sigmask() can be used to mask signal 316
delivery to threads, and sigwait() can be used in a thread to block until a signal is received. You will 317
need to do some research and experimentation to get this working. 318
Forbidden Functions 319
You must not use any of the following C functions/statements. If you do so, you will get zero (0) marks for the 320
assignment. 321
• goto 322
• longjmp() and equivalent functions 323
• system() 324
• mkfifo() or mkfifoat() 325
• POSIX regex functions 326
• fork(), pipe(), popen(), execl(), execvp() and other exec family members. 327
Submission 328
Your submission must include all source and any other required files (in particular you must submit a Makefile). 329
Do not submit compiled files (eg .o, compiled programs) or test files. You are not expected to submit 330
stringstore.h. If you do so, it will be marked for style. 331
Your programs (named dbclient and dbserver) and your stringstore library (named libstringstore.so 332
if you implement it) must build on moss.labs.eait.uq.edu.au with: 333
make 334
If you only implement one or two of the programs/library then it is acceptable for make to just build those 335
programs/library – and we will only test those programs/library. 336
Your programs must be compiled with gcc with at least the following switches (plus applicable -I options 337
etc. – see Provided Libraries above): 338
-pedantic -Wall -std=gnu99 339
You are not permitted to disable warnings or use pragmas to hide them. You may not use source files other 340
than .c and .h files as part of the build process – such files will be removed before building your program. 341 - Version 1.2
If any errors result from the make command (e.g. an executable can not be created) then you will receive 342 - marks for functionality (see below). Any code without academic merit will be removed from your program 343
before compilation is attempted (and if compilation fails, you will receive 0 marks for functionality). 344
Your program must not invoke other programs or use non-standard headers/libraries (besides those we have 345
provided for you to use). 346
Your assignment submission must be committed to your subversion repository under 347
https://source.eait.uq.edu.au… 348
where sXXXXXXX is your moss/UQ login ID. Only files at this top level will be marked so do not put source 349
files in subdirectories. You may create subdirectories for other purposes (e.g. your own test files) but these 350
will not be considered in marking – they will not be checked out of your repository. 351
You must ensure that all files needed to compile and use your assignment (including a Makefile) are commit- 352
ted and within the trunk/a4 directory in your repository (and not within a subdirectory) and not just sitting 353
in your working directory. Do not commit compiled files or binaries. You are strongly encouraged to check out 354
a clean copy for testing purposes – the reptesta4.sh script will do this for you. 355
To submit your assignment, you must run the command 356
2310createzip a4 357
on moss and then submit the resulting zip file on Blackboard (a GradeScope submission link will be made 358
available in the Assessment area on the CSSE2310/7231 Blackboard site)1
. The zip file will be named 359
sXXXXXXX_csse2310_a4_timestamp.zip 360
where sXXXXXXX is replaced by your moss/UQ login ID and timestamp is replaced by a timestamp indicating 361
the time that the zip file was created. 362
The 2310createzip tool will check out the latest version of your assignment from the Subversion repository, 363
ensure it builds with the command‘make’, and if so, will create a zip file that contains those files and your 364
Subversion commit history and a checksum of the zip file contents. You may be asked for your password as part 365
of this process in order to check out your submission from your repository. 366
You must not create the zip file using some other mechanism and you must not modify the zip file prior 367
to submission. If you do so, you will receive zero marks. Your submission time will be the time that the file 368
is submitted via GradeScope on Blackboard, and not the time of your last repository commit nor the time of 369
creation of your submission zip file. 370
We will mark your last submission, even if that is after the deadline and you made submissions before the 371
deadline. Any submissions after the deadline2 will incur a late penalty – see the CSSE2310/7231 course profile 372
for details. 373
Marks 374
Marks will be awarded for functionality and style and documentation. Marks may be reduced if you are asked 375
to attend an interview about your assignment and you are unable to adequately respond to questions – see the 376
Student conduct section above. 377
Functionality (60 marks) 378
Provided your code compiles (see above) and does not use any prohibited statements/functions (see above), 379
and your zip file has not been modified prior to submission, then you will earn functionality marks based on 380
the number of features your program correctly implements, as outlined below. Partial marks will be awarded 381
for partially meeting the functionality requirements. Not all features are of equal difficulty. If your program 382
does not allow a feature to be tested then you will receive 0 marks for that feature, even if you 383
claim to have implemented it. Reasonable time limits will be applied to all tests. If your program takes longer 384
than this limit, then it will be terminated and you will earn no marks for the functionality associated with that 385
test. If your dbserver does not link against libstringstore.so then you can earn no marks for tests that 386
interact with the key-value pair database (i.e. all tests in categories 12 to 15 13, 15 to 16, and most tests in 387
categories 17 to 20 16 to 19). 388
1You may need to use scp or a graphical equivalent such as WinSCP, Filezilla or Cyberduck in order to download the zip file to
your local computer and then upload it to the submission site.
2or your extended deadline if you are granted an extension. - Version 1.2
Exact text matching of files and output (stdout and stderr) is used for functionality marking. 389
Strict adherence to the output format in this specification is critical to earn functionality marks. 390
The markers will make no alterations to your code (other than to remove code without academic merit). 391
Marks will be assigned in the following categories. There are 10 marks for libstringstore.o, 10 marks for 392
dbclient and 40 marks for dbserver. 393 - libstringstore – correctly create and free memory associated with a StringStore object (4 marks) 394
- libstringstore – correctly add and retrieve key/value pairs (4 marks) 395
- libstringstore – correctly delete key/value pairs (2 marks) 396
397 - dbclient correctly handles invalid command lines (including invalid keys) (2 marks) 398
- dbclient connects to server and also handles inability to connect to server (2 marks) 399
- dbclient correctly requests key values from the server (2 marks) 400
- dbclient correctly sets key/value pairs on the server (2 marks) 401
- dbclient correctly handles communication failure (including bad server responses) (2 marks) 402
403 - dbserver correctly handles invalid command lines (3 marks) 404
- dbserver correctly listens for connections and reports the port 405
(including inability to listen for connections) (3 marks) 406 - dbserver correctly handles invalid and badly formed HTTP requests (3 marks) 407
- dbserver correctly handles public key/value pair set/get (6 marks) 408
- dbserver correctly handles public key/value pair delete (3 marks) 409
- dbserver correctly handles inability to read authentication string (2 marks) 410
- dbserver correctly handles authenticated/private key/value pair set/get (4 3 marks) 411
- dbserver correctly handles authenticated/private key/value pair delete (3 2 marks) 412
- dbserver correctly handles multiple simultaneous client connections using threads 413
(including protecting data structures with mutexes) (4 marks) 414 - dbserver correctly handles disconnecting clients and communication failure (3 marks) 415
- dbserver correctly implements client connection limiting (4 marks) 416
- dbserver correctly implements SIGHUP statistics reporting (4 marks) 417
Some functionality may be assessed in multiple categories, e.g. it is not possible test the deletion of keys without 418
being able to add keys first. 419
Style Marking 420
Style marking is based on the number of style guide violations, i.e. the number of violations of version 2.2 of 421
the CSSE2310/CSSE7231 C Programming Style Guide (found on Blackboard). Style marks will be made up of 422
two components – automated style marks and human style marks. These are detailed below. 423
You should pay particular attention to commenting so that others can understand your code. The marker’s 424
decision with respect to commenting violations is final – it is the marker who has to understand your code. To 425
satisfy layout related guidelines, you may wish to consider the indent(1) tool. Your style marks can never be 426
more than your functionality mark – this prevents the submission of well styled programs which don’t meet at 427
least a minimum level of required functionality. 428
You are encouraged to use the style.sh tool installed on moss to style check your code before submission. 429
This does not check all style requirements, but it will determine your automated style mark (see below). Other 430
elements of the style guide are checked by humans. 431 - Version 1.2
All .c and .h files in your submission will be subject to style marking. This applies whether they are 432
compiled/linked into your executable or not3
. 433
Automated Style Marking (5 marks) 434
Automated style marks will be calculated over all of your .c and .h files as follows. If any of your submitted 435
.c and/or .h files are unable to be compiled by themselves then your automated style mark will be zero (0). 436
(Automated style marking can only be undertaken on code that compiles. The provided style.sh script checks 437
this for you.) 438
If your code does compile then your automated style mark will be determined as follows: Let 439
• W be the total number of distinct compilation warnings recorded when your .c files are individually built 440
(using the correct compiler arguments) 441
• A be the total number of style violations detected by style.sh when it is run over each of your .c and 442
.h files individually4
. 443
Your automated style mark S will be 444
S = 5 − (W + A) 445
If W +A ≥ 5 then S will be zero (0) – no negative marks will be awarded. Note that in some cases style.sh 446
may erroneously report style violations when correct style has been followed. If you believe that you have been 447
penalised incorrectly then please bring this to the attention of the course coordinator and your mark can be 448
updated if this is the case. Note also that when style.sh is run for marking purposes it may detect style 449
errors not picked up when you run style.sh on moss. This will not be considered a marking error – it is your 450
responsibility to ensure that all of your code follows the style guide, even if styling errors are not detected in 451
some runs of style.sh. 452
Human Style Marking (5 marks) 453
The human style mark (out of 5 marks) will be based on the criteria/standards below for“comments”,“naming”454
and“other”. The meanings of words like appropriate and required are determined by the requirements in the 455
style guide. Note that functions longer than 50 lines will be penalised in the automated style marking. Functions 456
that are also longer than 100 lines will be further penalised here. 457
Comments (2.5 marks) 458
Mark Description
0
The majority (50%+) of comments present are inappropriate OR there are many required comments
missing
0.5 The majority of comments present are appropriate AND the majority of required comments are
present
1.0 The vast majority (80%+) of comments present are appropriate AND there are at most a few missing
comments
1.5 All or almost all comments present are appropriate AND there are at most a few missing comments
2.0 Almost all comments present are appropriate AND there are no missing comments
2.5 All comments present are appropriate AND there are no missing comments
459
Naming (1 mark) 460
Mark Description - At least a few names used are inappropriate
0.5 Almost all names used are appropriate
1.0 All names used are appropriate
461
3Make sure you remove any unneeded files from your repository, or they will be subject to style marking.
4Every .h file in your submission must make sense without reference to any other files, e.g., it must #include any .h files that
contain declarations or definitions used in that .h file. - Version 1.2
Other (1.5 marks) 462
Mark Description
0
One or more functions is longer than 100 lines of code OR there is more than one global/static
variable present inappropriately OR there is a global struct variable present inappropriately OR
there are more than a few instances of poor modularity (e.g. repeated code)
0.5 All functions are 100 lines or shorter AND there is at most one inappropriate non-struct global/static
variable AND there are at most a few instances of poor modularity
1.0
All functions are 100 lines or shorter AND there are no instances of inappropriate global/static
variables AND there is no or very limited use of magic numbers AND there is at most one instance
or poor modularity
1.5 All functions are 100 lines or shorter AND there are no instances of inappropriate global/static
variables AND there is no use of magic numbers AND there are no instances of poor modularity
463
SVN commit history assessment (5 marks) 464
Markers will review your SVN commit history for your assignment up to your submission time. This element 465
will be graded according to the following principles: 466
• Appropriate use and frequency of commits (e.g. a single monolithic commit of your entire assignment will 467
yield a score of zero for this section) 468
• Appropriate use of log messages to capture the changes represented by each commit. (Meaningful messages 469
explain briefly what has changed in the commit (e.g. in terms of functionality) and/or why the change 470
has been made and will be usually be more detailed for significant changes.) 471
The standards expected are outlined in the following rubric: 472
Mark
(out of 5) Description
0
Minimal commit history – single commit OR
all commit messages are meaningless.
1
Some progressive development evident (more than one commit) OR
at least one commit message is meaningful.
2
Some progressive development evident (more than one commit) AND
at least one commit message is meaningful.
3
Progressive development is evident (multiple commits) AND
at least half the commit messages are meaningful.
4
Multiple commits that show progressive development of all functionality AND
meaningful messages for most commits.
5
Multiple commits that show progressive development of all functionality AND
meaningful messages for ALL commits.
473
Design Documentation (10 marks) – for CSSE7231 students only 474
CSSE7231 students must submit a PDF document containing a written overview of the architecture and design 475
of your program. This must be submitted via the Turnitin submission link on Blackboard. 476
Please refer to the grading criteria available on BlackBoard under“Assessment”for a detailed breakdown 477
of how these submissions will be marked. Note that your submission time for the whole assignment will be 478
considered to be the later of your submission times for your zip file and your PDF design document. Any late 479
penalty will be based on this submission time and apply to your whole assignment mark. 480
This document should describe, at a general level, the functional decomposition of the program, the key design 481
decisions you made and why you made them. It must meet the following formatting requirements: 482
• Maximum two A4 pages in 12 point font 483
• Diagrams are permitted up to 25% of the page area. The diagram(s) must be discussed in the text, it is 484
not ok to just include a figure without explanatory discussion. 485
Don’t overthink this! The purpose is to demonstrate that you can communicate important design decisions, 486
and write in a meaningful way about your code. To be clear, this document is not a restatement of the program 487
specification – it is a discussion of your design and your code. 488 - Version 1.2
If your documentation obviously does not match your code, you will get zero for this compo- 489
nent, and will be asked to explain why. 490
Total Mark 491
Let 492
• F be the functionality mark for your assignment (out of 60). 493
• S be the automated style mark for your assignment (out of 5). 494
• H be the human style mark for your assignment (out of 5). 495
• C be the SVN commit history mark (out of 5). 496
• D be the documentation mark for your assignment (out of 10 for CSSE7231 students) – or 0 for CSSE2310 497
students. 498
Your total mark for the assignment will be: 499
M = F + min{F, S + H} + min{F, C} + min{F, D} 500
out of 75 (for CSSE2310 students) or 85 (for CSSE7231 students). 501
In other words, you can’t get more marks for style or SVN commit history or documentation than you do 502
for functionality. Pretty code that doesn’t work will not be rewarded! 503
Late Penalties 504
Late penalties will apply as outlined in the course profile. 505
Specification Updates 506
Any errors or omissions discovered in the assignment specification will be added here, and new versions released 507
with adequate time for students to respond prior to due date. Potential specification errors or omissions can be 508
discussed on the discussion forum or emailed to csse2310@uq.edu.au. 509
510
Version 1.1 511
• Added clarification that PUT request may omit the Content-Length: header if the body part of the 512
request is empty. 513
• Added clarification on valid keys and values. 514
• Clarified that dbclient communication failure criteria includes bad server responses. 515
• Clarified that dbserver listening criteria includes the inability to listen. 516
• Added separate dbserver marking criteria for inability to read authentication string and redistributed 517
marks relating to authenticated/private key/value access. 518
• Clarified language around invalid port number arguments to dbserver. 519
• Made it clear that too many arguments to dbserver is an invalid command line. 520
• Clarified order of dbserver error checking on startup. 521
522
Version 1.2 523
• Clarified limitations on authentication strings. 524
• Added advice on Makefile for libstringstore.so and listed linking flags to use libstringstore and 525
libcsse2310a3. 526
• Clarified counting of clients disconnected due to connection limiting. 527 - Version 1.2
