CS 168 Spring 2025

Project 3: Transport

In this project, you will implement a subset of the TCP protocol. Your implementation will provide reliability, though it wonʼt include congestion control.

Lectures needed for this project: Lecture 11 (Reliability), 12 (TCP Implementation).

You can work on this project alone, or with one partner. You can keep the same partner from an earlire project, or choose a different partner. Reminder: Our course policies page has a collaboration policy that you must follow.

Setup

Operating System Installation

This project has been tested to work on Linux and Mac.

If youʼre on Windows, we recommend using WSL.

Python Installation

This project has been tested to work on Python 3.7. (It probably works on newer versions of Python as well, but use at your own risk.)

If you run python3 --version or python --version in your terminal and you see output of the form. Python 3.7.*, youʼre all set.

Starter Code

Download a copy of the starter code here.

In your terminal, use cd to navigate to the cs168-sp25-proj3-transport/ext/cs168p2 directory. All of the Python commands should be run from this directory.

To check that your setup works, in your terminal, run:

python ../../pox.py config=tests/sanity_test.cfg

If you see this message, everything should be set up correctly:

[test] [00:00:02] All checks passed, test PASSED

You should only edit ext/cs168p2/student_socket.py. There are comments clearly indicating the places where you should fill in code.

Guidelines:

Donʼt modify any other files.

Donʼt add any new files.

Donʼt add any imports.

Donʼt edit any code outside the sections indicated by the comments.

Donʼt add any hard-coded global variables.

Adding helper methods is fine.

In general, if we havenʼt told you to use something, you probably donʼt need it. Our goal is not to trick you!

New Spec

Note: This spec has been rewritten for Fall 2024 to be clearer and provide a few extra hints. It may contain bugs.

If you would like to work off the previous version of the spec, you can find it here.

Project Overview

This project is split into 9 stages.

In Project 3A, youʼll need to complete Stages 1–5.

In Project 3B, youʼll need to complete Stages 6–9.

Each stage has its own unit tests, provided to you locally. Your grade will be determined only by these unit tests (no hidden tests).

To run a unit test, navigate to cs168-sp25-proj3-transport/ext/cs168p2, and run one of these commands, replacing 5 with the number of the stage you want to test:

python autograder.py s5 # Runs unit tests for Stage 5.

python autograder.py all # Runs all unit tests.

python autograder.py all 5 # Runs all unit tests up to and including Stage 5.

If a test fails, youʼll see some output like this:

test_s1_t1 (__main__.test_s1_t1.test_s1_t1) ...

Running test: ./tests/s1_t1.cfg

Tracefile: ./trace/s1_t1/2024-08-22T16:09:52.593234

../../pox.py config=./tests/s1_t1.cfg tcpip.pcap --node=r1 --no-tx --filename=./trace/s1_t1/20

FAIL

To see nicely-formatted output for that specific test, take the last line, just before the “FAIL,” drop the --filename argument, and run that command in your terminal:

../../pox.py config=./tests/s1_t1.cfg tcpip.pcap --node=r1 --no-tx

Code Overview

You will be implementing the StudentUSocket class in student_socket.py, which represents a TCP socket.

student_socket.py also contains other useful methods, which weʼll describe below.

Modular Arithmetic

Sequence numbers are 32 bits long, and they can wrap around (e.g. 0xFFFFFFFF + 1 = 0x00000000).

Whenever you perform. arithmetic operations on sequence numbers, use these operators:

State

The instance variable self.state records the state of the current TCP connection.

self.state is always assigned to one of the values in this list:

[CLOSED, LISTEN, SYN_RECEIVED, ESTABLISHED, SYN_SENT, FIN_WAIT_1, FIN_WAIT_2, CLOSING, TIME_WA

Weʼll describe more details about each state as they come up in the spec.

Send Sequence Space: TXControlBlock

The instance variable self.tx_data is a byte array representing what youʼre sending. The user will append bytes to the back of this array, and you will remove bytes from the front of this array as you send them out.

The instance variable self.snd is a TXControlBlock object, which has information about the outgoing bytestream that you are sending.

The TXControlBlock object has the following relevant instance variables:

self.snd.iss: Your initial sequence number.

self.snd.una: The oldest unacknowledged sequence number that you sent.

self.snd.nxt: The next sequence number you should send.

self.snd.wnd: The current size of your send window, determined by how much buffer space the other side (recipient) has left.

This diagram shows the bytestream that you are sending and what the instance variables represent:

Receive Sequence Space: RXControlBlock

The instance variable self.rx_data is a byte array representing what youʼre receiving. As you receive packets, you should append their payloads (in the correct order) to this byte array so that the user can read them.

The instance variable self.rcv is a RXControlBlock object, which has information about the incoming bytestream that you are receiving.

The RXControlBlock object has the following relevant instance variables:

self.rcv.nxt: The next sequence number you expect to receive.

self.rcv.wnd: The current size of your receive window, determined by how much buffer space you have left.

This diagram shows the bytestream that you are sending and what the instance variables represent:

Receiving Incoming Segments

The packets you send and receive are TCP/IP packets.

If you receive an IP packet p, you can extract the TCP header and payload like this:

seg = p.tcp

If you receive a TCP segment seg, you can extract these fields from its header:

seg.seq: The sequence number.

seg.ack: The ack number.

seg.win: The advertised window (how much buffer space left on the other side).

seg.ACK: Whether this segment has the ACK flag set (Boolean value).

seg.SYN: Whether this segment has the SYN flag set (Boolean value).

seg.FIN: Whether this segment has the FIN flag set (Boolean value).

If you receive a TCP segment seg, you can extract the payload like this:

seg.payload # The payload.

len(seg.payload) # Length of the payload.

Sending Outgoing Segments

To create a new packet, you can use the function self.new_packet(ack=True, data=None, syn=False), which takes in the following arguments:

ack: Whether to set the ACK flag. True by default.

data: The TCP payload to send. None by default.

syn: Whether to set the SYN flag. False by default.