4 — From interfaces to protocols

Due Sunday, 7 February, midnight

The assignment consists of two related tasks and one development task. The first task concern the implementation of a player as a server program. The second one requests a small test suite for the player implementation. The development task is your first look at the Evolution game.

                   player 1

    main             |

     |               |             player 2  ....

     |               |                |

     |               |                |  NOTE we ignore

     |               |                |  how the server

     |               |                |  finds the players

     |               |                |

     |               |                |

     |  start-round  |                |

     | ------------> |                |

     |               |                |  NOTE start-round is

     |               |                |  called once per round,

     |        start-round             |  at the beginning; this

     | -----------------------------> |  may happen in

     | <============================= |  interleaving order

     | <============ |                |

     |               |                |

     |               |                |

     |   take-turn   |                |

     | ------------> |                |

     | <============ |                |

     |               |                |  NOTE take-turn is

     |               |                |  called once per turn

     |              take-turn         |

     | -----------------------------> |

     | <============================= |

     |               |                |

     |              choose            |

     | -----------------------------> |  NOTE choose is

     | <============================= |  optional, once per

     |               |                |  turn after take-turn

     |               |                |

     .               .                .

     .               .                .  NOTE there are

     .               .                .  exactly 10 turns

     |               |                |

Figure 10: A remote access protocol for the "Take 5" player

Task 1 Implement a player in your chosen language that implements the remote-access protocol specified in figure 10. The interaction diagram explains how a main program interacts with several, independently running players. In the end, these components will run on distinct computers employing TCP/IP; for your development process, you may utilize distinct processes and communicate via the "localhost" interface. Use port 45678.

The interaction diagram presents interactions concerning one round of our "take 6" game. It ignores how the main program and the players connect with each other and how a complete game is set up and run.

The system will use JSON as the data exchange language:

A Name is a JSON string.

A Integer is a JSON number interpretable as a positive integer.

A Card is [Integer, Integer].
constraint: the first Integer is between 1 and 105 face value, as described by the requirements analysis for 6 Nimmt!
constraint: the second Integer are between 2 and 7 bull points, as described by the requirements analysis for 6 Nimmt!

A LCard is [Card, ..., Card].

A Stack is an LCard that contains at least one Card.

A Deck is [Stack, ..., Stack].

The per-round communication consists of three kinds of exchanges:
  • At the beginning of each round, each player component receives a start-round message with a hand of cards and responds with an acknowledgment.

    format ["start-round", LCard], where LCard has exactly enough cards to fill a hand

    return true, which acknowledges the receipt of the message.

  • Following this opening message, main sends a take-turn message with a deck of stacks for each turn and expects a card in return.

    format ["take-turn", Deck], where the Deck consists of as many LCards as required by the game

    return Card, which is the card the player wishes to play.

  • Every single take-turn message might be followed by an optional choose message, also containing a deck of stacks. On receipt of a choose message a remote player sends a stack in response.

    format ["choose", Deck], where the Deck consists of as many LCards as required by the game

    return Stack, which is the stack the player wishes to take.

For this assignment, you may assume that the remote player receives only valid JSON. The remote player must ignore all messages that do not satisfy one of the three message formats. In contrast, it sends a return message of false when a message violates the timing protocol.

Your remote player component must re-use the player from 3 — Development includes maintenance without modification. If, in the course of completing this task, you discover bugs in your previous player implementation, create patches and add them to your directory commit and push appropriate changes. Use the commit message to indicate that the difference is a bug fix. If the bug fix affects the user-facing side of your software---e.g., the API or UI---explain it in README.txt. We will inspect them and may apply them to create running systems. We may use git log -p to inspect the bug fixes and we may ask you to do so during a code walk.

Delivery Create a sub-directory remote and place all necessary files into this folder. Name the primary file remote and make sure it can be run from the command line. That is,


will start a player process that is waiting for TCP messages at the specified port.

Notes on JSON The notation [a,b,c] denotes a JSON array. With [a,..., a], the specification refers to arrays of arbitrary length with elements of kind a. This notation is a mere convenience, and it is not meant to signal that the length changes during the execution.

Task 2 Develop up to five pairs of JSON files that represent unit tests for your remote player. The input file contains a sequence of JSON expressions, separated by some white space, that play the role of messages sent from main to the player component; the output file contains the exact sequence of expected JSON return messages, again separated by white space. The tests cannot do not need to represent a complete game, a complete round, or a complete turn.

The unit tests may test (1) the input-output behavior of the player and the (2) protocol, that is, the timing behavior. They do not need to represent complete rounds of the game. Since the remote player reuses the existing player code, it does not---and is not supposed to---check anything concerning the player's task; it merely acts as an intermediary between the player and the TCP/IP ports.

Extra We will use all tests on all submissions. You will get a bonus point for Every mistake that your test suite discovers in another submission and that is confirmed as a mistake by our test suite.

Delivery Create a sub-directory test and place all test files into this folder. Each input file must have the format


for some natural number n between 1 and 5. The corresponding output file is named


Task 3 Your company has just decided to build a competition framework for the Evolution game. The first goal is to develop a monolithic framework in which you can test player strategies. The eventual goal is to support a server to which others can connect remote players.

Note You may assume that for this first stage of the project the player components live up to the rules of the game. It is still best to assign the dealer all tasks that can be completed automatically as soon as the dealer has acquired the necessary knowledge from the players.

The software architect of your company has studied the board game and has written up a requirements analysis. It is now your task to review this analysis. Your immediate goal is to eliminate discover and highlight any ambiguities in this description. Drawing a diagram on a white board and taking a picture is acceptable. You may also use ASCII art if you are comfortable editing such files. In support of this goal, study the document with the goal of and identify the essential software components (data representations, what do they represent? what do they refer to?) and how/why they are related to each other. You may deliver either a structured document (in English) or (inclusive) an annotated UML/Doodle class diagram. The document specifies a data design and lists ambiguities.

Also send all questions concerning ambiguities that arise to the software architect. He will edit the document in response if necessary.

Delivery Create a sub-directory evolution and place all document files into this directory.