Project 1 - DaB Server and Client

Client-Server Interfaces, Spring 2002

Due Date
Background
The Project
Messages
Client-Server Interaction
Implementation Details

Due Date

This assignment is due on Tuesday, 5 March, no later than 2:00 p.m.

See the assignment turn-in page (last modified on 4 March 2002) for instructions on turning in your assignment.

Dots and Boxes (DaB) is a simple, two-player paper and pencil game played on a grid with R rows and C columns, where R and C are usually between 3 and 8. Turns alternate between the two players. At each turn, a player connects two adjacent dots either horizontally or vertically. If the connection forms a 1-by-1 box, the player puts their initial in the box and moves again; the player continues to add lines until they fail to form a box, at which point it's the other player's turn. Play ends when all R*C boxes have been filled in; the player with the most initialed boxes is the winner.

Here is an example game between Amy and Brian (the traditional Dots and Boxes players) on a 2-by-2 board:

The lower-left dot has coordinate (0, 0); x coordinates grow moving to the right and y coordinates grow moving up.

The Project

This project involves creating a DaB server and a DaB client. The DaB client plays Dots and Boxes; the DaB server coordinates DaB clients so they play a game together.

Messages

Each message starts with a one-byte value giving the message tag; the recognized message tags are defined in /export/home/class/cs-537/dab.h. The structure of the rest of the message depends on the message tag.

The play message - A client in search of a partner with which to play Dots and Boxes sends a play message to the server. A play message has the format

where
1. play - The play message tag.
The game message - When a server pairs two clients wanting to play Dots and Boxes, it sends a game message to each of the clients. A game message has the format

where
1. game - The game message tag.
2. C - The board contains C columns.
3. R - The board contains R rows.
Both C and R must be greater than 1.
The turn message - The server sends a turn message to a client playing Dots and Boxes to indicate that it's the client's turn to make a move. The turn message also indicates all the changes made to the board since the last turn message received by the client, or since the beginning of the game. The turn-message format is

where
1. turn - The turn message tag.
2. n - The number of lines drawn in the opponent's most recent turn. n will be zero for the first turn of the game; otherwise, it is invalid for n to be less than 1 or larger than the number of available lines on the board.
3. X1_i, Y1_i - The x and y coordinates of the endpoint of the i-th line drawn on the board in the opponent's most recent turn, 1 <= i <= n.
4. X2_i, Y2_i - The x and y coordinates of the other endpoint of the i-th line drawn on the board in the opponent's most recent turn, 1 <= i <= n.
The x coordinates must be in the range 0 to C inclusive; The Y coordinates must be in the range 0 to R inclusive. Coordinates outside their respective ranges are invalid.
The move message - A client makes its moves (draws lines) in a game of Dots and Boxes by sending a move message to the server. A move message has the format

where
1. move - The move message tag.
2. n - The number of new lines drawn on the board by this move. It is invalid for n to be larger than the number of open lines on the board.
3. X1_i, Y1_i - The x and y coordinates of the endpoint of the i-th line added to the board by this move, 1 <= i <= n.
4. X2_i, Y2_i - The x and y coordinates of the other endpoint of the i-th line added to the board by this move, 1 <= i <= n.
The win message - The client that wins a game of Dots and Boxes receives a win message from the server. If there's a draw, both clients receive a win message. The win message has the format

where
1. win - The win message tag.
2. A - The number of squares initialed by player A.
3. B - The number of squares initialed by player B.
The sum A + B must be equal to the product R*C; A and B are invalid if they don't sum to R*C. In case of a tie, A and B will be equal.
The lose message - The client losing a game of Dots and Boxes receives a lose message from the server. A lose message has the format

where
1. lose - The lose message tag.
2. A - The number of squares initialed by player A.
3. B - The number of squares initialed by player B.
The sum A + B must be equal to the product R*C, and A must not equal B; A and B are invalid if they don't sum to R*C or if they are equal.
The exit message - The sender of an exit message indicates to the receiver of the message that the sender is no longer taking part in the communication and the sender's connection endpoint should be considered closed. An exit message has the format

where
1. exit - The exit message tag.
2. n - The number of bytes in the message; n may be zero if there's no message.
3. C₁ through C_n - The characters in the message. Each character C_i must be in the range '' '' (ASCII value 32 decimal) to '~' value 126 decimal) inclusive. Characters outside this range are invalid.

All values are unsigned and in network-byte order.

Client-Server Interaction

The event diagram

gives a general idea of the way in which clients and servers interact. More specifically, the interaction between client and server can be broken up into three phases: set-up, play, and shut-down.

Set-Up

Once a client connects to a server, the server waits for the client to send a play message. The server should receive a play message from the connecting client within 5 seconds of connection establishment. A client cannot be considered for a game of Dots and Boxes until it sends a play message. If the server fails to receive a play message within 5 seconds, it should send an exit message to the client and close the connection.

Upon receiving a play message from the connecting client, the server pairs the playing client with a waiting client and starts a game of Dots and Boxes between the two clients. If there is no waiting client, the playing client becomes the waiting client. A waiting client may wait an arbitrarily long time.

Note that the server can have at most one waiting client, but can have an arbitrary number of clients that are connected but are still missing their play messages.

Play

Once the server pairs two clients for a game of Dots and Boxes, it generates a random board size and sends each client a game message. It then randomly sends one of the playing clients a turn message to start the game.

The playing client receiving a turn message from the server has somewhere around 30 seconds to respond with a move message. The playing client can reset the 30 second clock by sending a move message with n equal to zero back to the server; the client then has another 30 seconds or so to send another move message.

When the server receives a non-empty move message from the client, it adjusts the board according to the moves given in the move message. If the game is over, the server shuts the game down; otherwise, it sends a turn message to the other client in the game.

When the server receives an empty move message, it resets its move-response time-out clock for that game. A client can send at most 10 consecutive empty move messages during its turn. If the client fails to send any moves after 10 consecutive empty move messages, the server should disconnect the client and declare the other playing client the winner.

Shut-Down

When the game ends, the server sends win and lose messages to the appropriate clients. After sending the lose message, the server closes the connection to the losing client (this does not require an exit message). The winner remains connected to the server to face the next client. The winning client need not send another play message to the server to start the next game, but it will receive another game message from the server to indicate when the new game starts.

If a game ends in a tie, both clients receive a win message and both remain connected to the server; whether they play each other again depends on the server and whether or not there's a client waiting to play. If there is, then the server may pick one of the winners to play the waiter, while the other winner becomes the new waiter. If there's no waiting client, then the two winners must play each other again.

A client may withdraw from the server at any time by sending an exit message, possibly with an explanatory message. If a game is in progress, the server declares the other client the winner, sending it a win message (this means a client may receive a win message before the game is over). If a client disconnects from the server without sending an exit message, the servers should behave as if it had sent an exit message with no error message.

Error Interaction

When one side of a connection detects an error from the other side of the connection, it should close its half of the connection and act accordingly (a client should probably halt, a server should continue to handle other connections). If the error permits it, the working side of the connection may send an exit message with a helpful error message to the faulty side of the connection before closing the connection. However, this is optional; the working side need not send an exit message, or, if it does, it need not send a message.

The receiver of an exit message should assume the connection over which the message arrived has been closed (this means the receiver should not try to send an exit message back when it receives a faulty exit message). The receiver should print the error message (if any) to std-err and close the connection. What happens next depends on the receiver; a client should probably halt, a server should clean-up the connection and continue.

Exit messages can be sent at any time, even at times when no error has been detected by the sender. The receiver's response to an exit message, however, should always be as described in the previous paragraph.

Erroneous behavior includes receiving undefined messages, receiving incorrectly formatted messages, receiving messages with bad values, receiving messages out of expected order, failure to interact within a reasonable amount of time, and unexpected connection terminations.

Implementation Details

Clients and a server communicate using TCP (If you're really into it, you might try UDP, but I don't recommend it). The client should support the -h and -p command-line options to specify the server's host IP address and listening-port number, respectively. The server should support the -p command-line option to pick specific listening-port number.

Your client should play the game itself; it should not prompt the user for moves. And remember, you're supposed to be learning about clients and servers, not about Dots and Boxes; just have the client generate random moves. After you get everything working, you can go back and soup up your game-playing algorithm.

This page last modified on 2 March 2002.