Project 1 - Accordion Server and Client

Client-Server Interfaces, Spring 2003

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

Due Date

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

See the assignment turn-in page (last modified on 25 February 2003) for instructions on turning in your assignment.

Background

Accordion is a solitaire card game played with a standard 52-card deck. Play starts with a single card dealt face up. Play continues by repeatedly making any of the following moves:

Move the top card in a pile to the pile to its immediate left if the top cards on both piles match. Two cards match if both have the same suit (clubs, diamonds, hearts, spades) or the same rank (ace through king). If the two adjacent cards don't match, this move can't be made.
Move a card pile to the card pile to its immediate left if the top cards on both piles match. If the two adjacent cards don't match, this move can't be made. The gap left by the moved pile is ignored.
Move the top card in a card pile to the card pile two to its immediate left if the top cards on both card piles match. If the two adjacent cards don't match, this move can't be made. This move is similar to move 1, except the card jumps the in between pile.
Move a card pile to the card pile two to its immediate left if the top cards on both piles match. If the two cards don't match, this move can't be made. This move is similar to move 2, except the card pile jumps the in between card pile.
Deal a new right-most card face up from the deck.

You are not required to make any of the moves 1 through 4 as soon as they are possible.

Play ends when all the cards have been dealt. You win if there's a single pile of cards left.

This project involves creating an Accordion server and an Accordion client. The Accordion client plays a game of Accordion solitaire; the Accordion server deals the cards for the client and also plays the same game as the client.

At the end of the game, the client sends its final card configuration to the server. The server checks the client's configuration for mistakes, and then compares the client's configuration to its own for the game. If the client's configuration is correct and contains no more piles than does the server's configuration, then the client has won, even if the client doesn't have a single pile at the end of the game. Otherwise the client has lost.

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/p1/accordion.h. The structure of the rest of the message depends on the message tag.

The play message - A client wanting to play a game Accordion solitaire sends a play message to the server. The server responds with another play message. A play message has the format

where
1. play - The play message tag.
2. gid - The game id. This value is undefined in the message sent from the client to the server. If gid is zero in the message sent from the server to the client, the server has rejected the client's request to start a new game. Otherwise, the server has accepted the client's request, and the gid is the identifier for the new game.
The deal message - When a client wants a new card, it sends a deal message to the server. The server responds with another deal message.
A deal message has the format

where
1. deal - The deal message tag.
2. gid - The game id. This should be the game id returned in the server's play message.
3. C - The card dealt. C is undefined when the message is from the client; C contains the card dealt when the message is from the server.
The ping message - When the client sends a ping message to the server, the server responds in kind. A ping message resets the server's last-message timer, but has no effect on the game. A ping message has the format

where
1. ping - The ping message tag.
2. gid - The game id. This should be the game id returned in the server's play message.
3. data - An arbitrary 4-byte value. This value is set by the client and returned by the server; the server places no interpretation on the value of data.
The tableau message - When the client has finished its game, it sends its tableau to the server using a tableau message.

where
1. tableau - The tableau message tag.
2. gid - The game id.
3. P - The number of piles in the final tableau, 1 <= P <= 52.
4. C_i - The ith card in the final tableau, 1 <= i <= 52 + P - 1. The cards are listed in the left to right order of the piles and, within each pile, in the top-to-bottom order of the pile. One pile is separated from the next by the card value C_i = 0.
The result message - The server responds to a client's tableau message with a result message. A result message has the format

where
1. result - The result message tag.
2. gid - The game id.
3. D - A single signed byte giving the difference between the number of piles left by the server and the number of piles left by the client. If D is positive, the client had D more piles than did the server, and the client loses. If D is negative, the server had D more piles than did the client, and the client wins. If D is zero, the client and server had the same number of piles, and the game's a draw, unless there was only one pile, in which case the client wins.
The error message - Whenever the client or server detect problems on the other end, it should send an error message to the other end.

where
1. error - The error message tag.
2. S - The size of the error string in characters, S >= 0.
3. C_i - The ith character in the error string, 0 <= i < S.

Cards are represented by two-byte values using the formula s*100 + r, where s is the card's suit and r is the card's rank. The suit and rank values are

Suit	Value
club	0
diamond	1
heart	2
spade	3

Rank	Value
ace	1
i	i
ten	10
jack	11
queen	12
king	13

For example, the jack of hearts has the value 2*100 + 11 = 211.

All values are unsigned and in network-byte order unless otherwise noted..

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 Accordion until it sends a play message. If the server fails to receive a play message within 5 seconds, it should send an error message to the client and close the connection.

Upon receiving a play message from the connecting client, the server responds with a play message containing the client's game id.

Play

Once the server sends a play message to a client, the client's game is underway. Under normal circumstances, the client sends a sequence of deal messages and ends with a tableau message. The client may also terminate the game at any time by sending an error message with an empty error string to the sever.

The longest allowable interval between two successive message from the same client is around one minute; if the server does not receive the next message from a client within one minute of receiving the previous message, the server assumes the client is gone and ends the game with an error message.

Similarly, if the client fails to receive the server's response to a message within one minute, the client should consider the server gone and end the game with an error message.

A playing client can keep its game alive without using a deal message by sending a ping message to the server. The server responds by sending a ping message back, and the client has approximately one more minute to send another message. A client can send at most 10 consecutive ping messages during its turn. If the client fails to send a non-ping message after 10 consecutive ping messages, the server ends the game with an error message.

Shut-Down

After the last card is dealt, the client should send a taleau message to the server. The server responds with a results message and ends the game. If the client wants to play another game, it must start over again at the beginning by sending another play 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 error message with a helpful error string to the faulty side of the connection before closing the connection. However, this is optional; the working side need not send an error message, or, if it does, it need not send an error string.

The receiver of an error message should assume the connection over which the message arrived has been closed (this means the receiver should not try to send an error message back when it receives a faulty error message). The receiver should print the error string (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.

Error 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 error 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 your choice of TCP or UDP. 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 Accordion; just have the client make random moves. After you get everything working, you can go back and soup up your game-playing algorithm.

This page last modified on 12 March 2003.