Project 2 Rubric¶

The grading of this project follows a specifications grading approach. If you have not already done so, make sure to read our Grading section of the syllabus for more details.

This project has two submissions: Project 2A and Project 2B. You will receive two SNU scores for each submission:

Completeness score: This score will be determined solely by the result of running the automated tests, as these give a measure of how complete your implementation is (i.e., how much of the assignment you implemented).
Code Quality score: This score is determined by a review of your code done by the course staff, and is based on three aspects of your code:
- Correctness: This encompasses issues with your code that, while not explicitly captured by the tests, could lead to incorrect or inefficient behaviour in your code. This can include small mistakes in your code, as well as larger issues that reveal a lack of mastery in the material.
- Design: This encompasses “qualities, many of which are intangible, that don’t have to do with (and exist to some extent independently of) the correct operation of your code.” (thanks to Adam Shaw for this concise phrasing).
- Style: This encompasses your adherence to our Style Guide.
- Documentation: You will be required to submit certain documentation on your code (the exact documentation is described below)

Submission Timeline¶

The exact timeline of submissions will be the following:

Submission	Requirements	Due Date
Project 2A	Assignment 1 of chiTCP	Thursday, November 7, 8pm
Project 2B	Assignment 2 of chiTCP (Note: Assignment 2 builds on Assignment 1)	Thursday, November 14, 8pm
Resubmission (Optional)	Address feedback received in Project 2	One week after Project 2B is graded

Project 2A will likely not be graded until after Project 2B is due. Once Project 2B is graded, you will have an opportunity to make a resubmission for Project 2A and/or 2B (and, at that point, you will have feedback for both Project 2A and 2B). We will post more details about the resubmission process at a later time.

Completeness¶

The Completeness component will be determined by running the following command:

make grade

(see Automated tests in the chiTCP documentation and, specifically, the “Producing a grade report” section for more details)

Your SNU score will then be determined as follows:

Grade	Project 2A	Project 2B
Grade	chiTCP Assignment 1	chiTCP Assignments 1+2
Satisfactory	at least 90	at least 180
Needs Improvement	at least 60	at least 120
Unsatisfactory	less than 60	less than 120

Code Quality¶

When assessing your code quality, there are a number of things we will be paying close attention to, and which we describe in the sections below (including major issues, labelled “[Major Issue]” that you should be particularly mindful of).

Please note that, since Project 2B builds on Project 2A, all rubric items in Project 2A also apply on Project 2B.

In general, your SNU score will be determined as follows:

Satisfactory: Your submission has a few of the issues described below (but no major issues).
Needs Improvement: Your submission has several of the issues described below, or at least one major issue. In general, major revisions are typically required to get up to an S.
Unsatisfactory: Your submission does not constitute a good-faith effort to complete the work. This includes not submitting any work at all, as well as submitting only placeholder code (e.g., code that includes functions for all the required IRC commands, but where the functions are empty or filled with “TODO”s, etc.)

That said, while the issues listed below are the main things we care about in this project, it is not possible for us to give you an exhaustive list of every single thing that could affect your code quality score. If you get a comment pointing out an issue in your code that we did not list below, take it as an opportunity to improve your work (and remember that you’ll have a chance to revise your work!)

Correctness¶

When assessing the correctness of your code, we will be paying special attention to the following issues:

General¶

Not setting a correct value for SEG.WND
Not updating SND.WND when a packet arrives
Not locking the pending packet mutex before accessing the list of pending packets
Not freeing packets once you’re done with them
Sending a packet that doesn’t conform to the RFC (even if it happens to pass the tests). This can include setting incorrect flags, such as setting the SYN flag after the three-way handshake is done.
Making a state transition inconsistent with the RFC
Incorrect code for checking a condition specified in the RFC. For example, when comparing values, using < even when the RFC says to check for <=. This rubric item also encompasses coding mistakes that result in a condition ultimately being checked incorrectly (e.g., writing something like a < b < c instead of a<b && b<c).
Not locking the pending packets mutex before accessing the pending packets list.

[Project 2A] 3-way Handshake¶

Acknowledging the final ACK in the 3-way handshake. Remember that acknowledgements are not acknowledged in TCP.
Not checking that the SYN was acknowledged before sending the ACK and changing state to ESTABLISHED.
3-way Handshake: Setting the ISS to a constant value, instead of using a random number.
[Major issue] Writing a 3-way handshake by rote that doesn’t check the TCP header values, and assumes that the first three messages exchanged must be a SYN, SYN/ACK, and ACK. For example, you could technically pass the three-way handshake tests by making TCP go into an ESTABLISHED state after receiving two packets (without checking whether the first one is a SYN packet, and whether the second one contains a valid ACK).

[Project 2A] Data Transfer¶

Not checking if the value of SEG.ACK and SEG.SEQ is correct. In some cases, no action needs to be taken when a value is incorrect, but we still recommend (but not require) that you chilog() any such cases.
Not setting the ACK flag and including a valid acknowledgement number in every packet after the 3-way handshake. Remember that, even if you haven’t received any new data, you still have to send a valid acknowledgement number in every segment.
Not updating SND.UNA and SND.WND with SEG.ACK and SEG.WND for every incoming packet with a valid SEG.ACK
[Major issue] Unconditionally sending an ACK segment in reply to every segment that is received.
Not updating the value of RCV.WND in the APPLICATION_RECEIVE event
[Major issue] Not taking SND.WND into account when processing the send buffer. You should make sure to never send more bytes than allowed by the effective window (remember this won’t be just SND.WND, but is computed based on SND.WND).
Not segmenting the data in the send buffer into MSS-sized packets (536 bytes), or segmenting it incorrectly

[Project 2A] Connection teardown¶

Not handling the APPLICATION_CLOSE event in both ESTABLISHED and CLOSE_WAIT. In both cases, you should only send a FIN packet if there is no data left in the send buffer, but you should transition to FIN-WAIT-1 / LAST-ACK (respectively) right away.
Not delaying the FIN packet until all outstanding data has been sent and acknowledged.
Not handling the APPLICATION_RECEIVE event in FIN_WAIT_1 and FIN_WAIT_2. TCP can still receive data in those states, which means the application may still call recv.

[Project 2B] Managing the Retransmission Queue¶

Adding pure ACK packets (i.e., not SYN or FIN segments, nor segments with a payload) to the retransmission queue. ACK packets are not retransmitted.
Adding segments with a payload to the retransmission queue, but not adding SYN or FIN segments
Not removing acknowledged packets from the retransmission queue. Take into account that multiple packets could be removed because of a cumulative ack. However, you should not automatically remove all the packets from the retransmission queue whenever you receive an ACK, because you could have packets 1-10 in the queue, and receive an acknowledgement only for 1-5.
Unnecessarily locking the retransmission queue. The retransmission queue is only ever accessed by the socket thread, so there is no possibility of concurrent access by multiple threads. So, it does not need to be protected by a mutex.

[Project 2B] Managing the Timer Thread¶

Unconditionally setting the timer every time a packet is sent. You should set the timer only if you are sending a packet with data (or a SYN or FIN) and the timer is not already active. If the timer is already active, then sending new data doesn’t affect the timer in any way.
Not cancelling the timer when all outstanding data has been acknowledged
Unconditionally restarting the timer when any ACK is received. The timer should only be restarted when the ACK acknowledges outstanding data.
Not restarting the timer at all when an ACK (that acknowledges new data) is received.

[Project 2B] Handling the retransmission timeout¶

Not doing Go-back-N. When a TIMEOUT event happens, you should be doing go-back-N: find the earliest unacknowledged segment in the retransmission queue, and retransmit that segment and all subsequent segments. It is not enough to only retransmit the first segment (without checking whether there are subsequent packets)
Not backing off the RTO each time a timeout happens.

[Project 2B] RTT estimation¶

[Major issue] Not doing any RTT estimation. The RTT estimation tests can’t check whether you implemented RTT estimation correctly (at most, they may alert you to failures that arise as a result of an incorrect RTT estimation), so the graders will be manually checking that you implemented RTT estimation correctly.
Doing RTT estimation, but making a minor mistake in computing the RTT
Doing RTT estimation, but not excluding retransmitted segments from the RTT estimation

[Project 2B] Persist timer¶

Did not actually implement the persist timer. (this rubric item is only applied if you are somehow passing all the persist timer tests, despite not implementing the persist timer)
Not updating SND.NXT when sending a probe segment.

[Project 2B] Out-of-order¶

Did not actually implement out-of-order delivery. (this rubric item is only applied if you are somehow passing all out-of-order tests, despite not implementing out-of-order delivery)
Not placing out-of-order segments in the out-of-order list
Inserting duplicate segments in the out-of-order list

Design¶

When assessing the design of your code, we will be paying special attention to the following:

[Major issue] Not writing a packet arrival handler. You should structure your code so that you have a single packet arrival handler that gets called from any state where a packet arrives.
[Major issue] Writing a packet arrival handler that does not follow the exact SEGMENT ARRIVES logic in the RFC. Most notably, you should not try to reverse-engineer the logic in SEGMENT ARRIVES to figure our the steps to follow based on the current TCP state (the RFC does indicate a number of steps that will depend on the TCP state, but you should check for the value of the TCP state when the RFC tells you to, instead of combing through the logic and trying to extract the steps that only apply to a given state).
Writing a packet arrival handler, but still having some of the packet arrival handler logic in the state handling functions. That said, we will allow some of the packet arrival handling logic to appear in the CLOSED, LISTEN, and SYN-SENT states (and the rest in a packer arrival handler), given that the RFC specifies a specific treatment for those three states, whereas the rest of the states are lumped together.
Not writing a function to process the send buffer. Based on the TCP variables, this function should decide whether to send any packets or not. This function should be called when handling APPLICATION_SEND, and whenever SND.UNA or SND.WND changes (since that may open up the window, allowing more data to be sent).
Destroying the multitimer thread each time a single timer expires. Your multitimer should have a single thread that should not be stopped/re-recreated at any point (it should just be stopped when calling mt_free, once we’re completely done using the multitimer). Most notably, you should not destroy the thread when a single timer expires (to then create a thread when setting the next timer)
Inefficient access to the next expiring timer. It should be possible to determine the next expiring timer in O(1) time. It is ok to have a data structure that requires more than O(1) time to add/remove an active timer.
Inefficient access to a timer by ID. It should be possible to access a timer by ID in O(1) time.
[Major issue] Implementing the multitimer with busy waiting instead of using condition variables
Complicated callback functions for the retransmission timer or the persist timer. These callback functions should be little more than a call to chitcpd_timeout, and should include little (if any) retransmission/persist logic.
Repeating retransmission logic in multiple places. Your code should be structured in such a way that you only need to add segments to the retransmission queue in a single point in your code (e.g., by having a “send packet” function that also takes care of adding the packet to the retransmission queue if necessary).

Style¶

We will be checking your general adherence to our Style Guide and, while we will not be checking that you follow every minute aspect of our style guide, we do expect you to follow a consistent style that asymptotically approaches the one specified in our style guide. That said, there are certain aspects we will be paying more attention to:

Documenting functions: Every function written by you must have a function comment with a brief description of what the function does, and a description of the parameters and the return value. Please note that not documenting your functions at all (as opposed to doing so inconsistently or not following the style guide) is considered a major issue.
Consistent indentation: Your code must follow one of the allowed indentation styles consistently.
Clarity: Your code must be easy to read and understand. This is a fairly subjective aspect, but remember that things like using variable names without descriptive names or using magic numbers will usually make your code harder to read.
[Major Issue] Using global variables, except when defining compile-time constants.
[Major Issue] Using goto statements, except in the very limited cases described in the style guide.

Documentation¶

Your submission must include a DOCUMENTATION.md file in the root of your repository with some specific documentation about the code you have written. If you do not include this file, Gradescope will reject your submission entirely. If you do include it, but the file does not provide the information we request below, this will be treated as a major issue in your submission.

The DOCUMENTATION.md file must follow the template below (the exact sections are explained further below):

Project 2
=========

Team members:
- TEAM MEMBER 1 (CNETID1)
- TEAM MEMBER 2 (CNETID2)

Test score: XXX / YYY

Additional functions
--------------------
- function1() in tcp.c
- function2() in multitimer.c

Other code details / requests for feedback
------------------------------------------
<COMPLETE THIS SECTION>

Known omissions
---------------
<COMPLETE THIS SECTION>

Citations
---------
<COMPLETE THIS SECTION>

Below you can find more details on each of the sections. If you are not providing any information in a given section, please do not remove the section. Instead, just write N/A below it.

Team members: Include the names and CNetIDs of both team members.
Test score: Please include the test score you are seeing when running the tests on your computer. This will allow us to look into situations where the Gradescope autograder reports a different score (in these cases, we will run the tests manually to verify we can get the same score you are getting)
Additional functions: If you added new functions to tcp.c or multitimer.c, please list them here.
Other code details / requests for feedback: Use this section to provide any other information that may be relevant to the graders as they read through your code. If you would like us to provide feedback on any specific aspect of your work, you can also let us know in this section.
Known omissions: If you intentionally skipped any part of the project, or intentionally did not address any rubric items, please list them here. If we can provide any feedback that would help you address these rubric items, please let us know here as well.
Citations: Citations for use of Generative AI or external resources should be included, when possible, as code comments above any code where you relied on external sources. However, if you consulted a source that had a more broad impact on your work (and not on specific pieces of code), you can include the citation here. Additionally, if you had any high-level discussions about the project with other students in the class, please list their names here.

Note: If the Generative AI platform you’re using does not allow you to easily generate a shareable link, please include a copy of the conversation(s) at the bottom of the DOCUMENTATION.md file.

Other Code Quality Issues¶

There are a couple of other issues that we care about across all projects:

Reinventing wheels that don’t need to be reinvented: In this class, we expect you to know how to use data structures like linked lists, hash tables, etc. (and how to choose the right data structure for a given task). However, this is a Networks class, not a Data Structures class, and you should not be spending any time implementing such data structures. The projects largely use the following data structure implementations:
- utlist: A linked list library
- uthash: A hash table for C structures
- SDS: Simple Dynamic Strings
Implementing your own linked list, hash table, etc. from scratch is considered a major issue. While you may think that implementing your own data structure is a worthwhile exercise, it invariably results in more work for the TAs and graders (as you will likely run into all sorts of issues and segfaults that could have been avoided by using a well-known and well-tested data structures library). Plus, it will be a much more worthwhile experience for you to understand how to incorporate an existing library into your own code.
Submitting code that doesn’t build: If you submit code that does not build on Gradescope’s autograder, but the graders can get it to build with some minor fixes (missing semicolons, parenthesis, etc.), this will just be treated as a major issue. However, if your code requires substantial work to get it to build, you will receive a U score.

So, make sure you verify that the version of the code you submitted builds correctly on a supported software environment (see the Projects - Getting Started page for more details on this) Additionally, it is your responsibility to check that the code you submitted to Gradescope builds correctly. If it doesn’t, but it builds correctly on your end, please let us know so we can look into it.
Using printf instead of chilog: All the projects in this class use a simple logging library called chilog that is documented in each of the project specifications. You must use the chilog functions exclusively for printing logging or debug messages. Do not use printf() directly in your code. Please note that the chilog functions provide essentially the same functionality as printf, so there is no situation where printf would be necessary instead of chilog (using chilog consistently also means you will not have to scrub printf’s from your code before submitting it).

Furthermore, all the messages at the INFO, WARNING, ERROR, and CRITICAL levels must be used only for their intended purposes (e.g., only use ERROR to print out actual errors in the execution of your program). You must use the DEBUG level only to print informative debug messages that would be understood by any developer trying to debug your code. You may use the TRACE level to print any debug message (including those that would only be understood by you). However, if your code is riddled with TRACE logging statements (including commented out ones) to the point where it is hard to read the code itself, we may penalize you for this. So, once a TRACE logging statement has served its purpose, we suggest you remove it (not just comment it out).

You should assume that graders will run your code with logging at the INFO level, and will only use the DEBUG level if they need to debug an issue with your code. We will never run your code with logging at the TRACE level.

Please note that, in assignments where you are responsible for writing the main function, you may use fprintf to print to standard error if there is an error that prevents the program from starting (e.g., if a command-line parameter has not been provided, etc.)
Grossly incorrect memory management: You should make sure to free any memory you malloc, but we will usually not penalize you unless you’ve been grossly negligent in your malloc’ing/freeing. You should also make sure to not “save” pointers to stack-allocated memory that is going to be deallocated. This can happen if you store a pointer to a functions’ local variable in a struct that is heap-allocated.