Description
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/ HTTP/1.1 where 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/ HTTP/1.1 Content-Length: where and are replaced with the required key and value strings respectively, and is replaced 80 by the number of bytes in . 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: ” must be provided, where is replaced 239 by the correct authentication string. Note that leading and trailing spaces will be removed from the 240 (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 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 1. 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 2. Write a small program to explore the basic HTTP request/response patterns, and associated API functions 309 in libcsse2310a4.so. 310 3. 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 4. The read_line() function from libcsse2310a3 may be useful for reading the authentication key. 313 5. The multithreaded network server example from the lectures can form the basis of dbserver. 314 6. Use the provided library functions (see above). 315 7. 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 10 Version 1.2 If any errors result from the make command (e.g. an executable can not be created) then you will receive 342 0 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/svn/csse2310-sem1-sXXXXXXX/trunk/a4 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. 11 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 1. libstringstore – correctly create and free memory associated with a StringStore object (4 marks) 394 2. libstringstore – correctly add and retrieve key/value pairs (4 marks) 395 3. libstringstore – correctly delete key/value pairs (2 marks) 396 397 4. dbclient correctly handles invalid command lines (including invalid keys) (2 marks) 398 5. dbclient connects to server and also handles inability to connect to server (2 marks) 399 6. dbclient correctly requests key values from the server (2 marks) 400 7. dbclient correctly sets key/value pairs on the server (2 marks) 401 8. dbclient correctly handles communication failure (including bad server responses) (2 marks) 402 403 9. dbserver correctly handles invalid command lines (3 marks) 404 10. dbserver correctly listens for connections and reports the port 405 (including inability to listen for connections) (3 marks) 406 11. dbserver correctly handles invalid and badly formed HTTP requests (3 marks) 407 12. dbserver correctly handles public key/value pair set/get (6 marks) 408 13. dbserver correctly handles public key/value pair delete (3 marks) 409 14. dbserver correctly handles inability to read authentication string (2 marks) 410 15. dbserver correctly handles authenticated/private key/value pair set/get (4 3 marks) 411 16. dbserver correctly handles authenticated/private key/value pair delete (3 2 marks) 412 17. dbserver correctly handles multiple simultaneous client connections using threads 413 (including protecting data structures with mutexes) (4 marks) 414 18. dbserver correctly handles disconnecting clients and communication failure (3 marks) 415 19. dbserver correctly implements client connection limiting (4 marks) 416 20. 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 12 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 0 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. 13 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 14 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 15 Version 1.2
