Matthieu Herrb » dinner

h1. THE DINING HACKERS PROTOCOL

April 14th 2001

Felipe Bergo @<bergo@seul.org>@

_"You may have read April 1st RFCs, but no text ever came so close to a February-30th-RFC as this"_

h2. ABSTRACT

This document describes a protocol meant to provide a centralized service for clients ('dining hackers') who are fighting (more literally than in previous similar protocols) for a finite set of resources.

h2. INTRODUCTION

The Dining Hacker protocol implements a situation similar to that shown in Dijkstra's Dining Philosophers paper.

A finite set of clients with different personalities are competing for a set of resources (chopsticks).

The situation is a round table with at N hackers, N <= 256.

There are always N chopsticks and N chinese food boxes on the table.

Hackers wish to eat, but one must first acquire the two chopsticks adjacent to his own position to start eating.

How much time and how frequently a hacker will eat depends on the client.

But conflict resolution is arbitrated by the server, using RPG-like character sheets.

The protocol itself is divided into 2 sub-protocols, each running on a TCP connection.

h2. CLIENT SUB-PROTOCOL

The Client Sub-Protocol is used to connect a client (hacker)     to the dinner table (server). The client connects to     TCP 8081 of the server, which will send a greeting message     and wait for requests.

The greeting message is terminated by a newline (0x0a) and     the only requirement is that it contains the "DINNERD"     string (in uppercase characters). Usually it will contain     also a version number.

The following operations can be triggered by the client:

h3. GROUP 1 : SET PROPERTIES

Each client has an associated "character sheet", with 5

properties: name (up to 16 octets), ST (Strength, 1 octet),

DX (Dexterity, 1 octet), Aggr (Aggressivity, 1 octet) and

HT (Health, 1 octet). All properties are read/write,

except HT which starts at 100 and is read only.

*Operations*

# SET NAME

           Client sends 0x30 (up to 16 octets) 0x0a.

           The command always succeeds.

# SET ST

           Client sends 0x31 ST-octet

           The command always succeeds.

# SET DX

           Client sends 0x32 ST-octet

           The command always succeeds.

# SET Aggr

           Client sends 0x33 Aggr-octet

           The command always succeeds.

h3. GROUP 2: GET PROPERTIES

*Operations*

# GET NAME

           Client sends  0x3f 0x30     ("?0")

           Server replies with 16 octets. The name is

           a zero-terminated string.

           The command always succeeds.

# GET ST

           Client sends  0x3f 0x31     ("?1")

           Server replies with the ST octet.

           The command always succeeds.

# GET DX

           Client sends  0x3f 0x32     ("?2")

           Server replies with the DX octet.

           The command always succeeds.

# GET Aggr

           Client sends  0x3f 0x33     ("?3")

           Server replies with the Aggr octet.

           The command always succeeds.

# GET HT

           Client sends  0x3f 0x34     ("?4")

           Server replies with the HT octet.

           The command always succeeds.

h3. GROUP 3: RESOURCE USAGE

# REQUEST LEFT CHOPSTICK

           Client sends 0x4c           ("L")

           Server replies 0x30 on failure, 0x31 on success.

# REQUEST RIGHT CHOPSTICK

           Client sends 0x52           ("R")

           Server replies 0x30 on failure, 0x31 on success.

# DROP LEFT CHOPSTICK

           Client sends 0x6c           ("l")

           The command always succeds.

# DROP RIGHT CHOPSTICK

           Client sends 0x72           ("r")

           The command always succeds.

h3. GROUP 4: OTHER

# SUICIDE

           Client sends 0x51           ("Q")

           The command always suceeds. The hacker and his

           chopstick are removed from the table.

           Disconnecting has the same effect.

h2. INITIALIZATION

The character sheet is generated from random bits upon

connection. Until the client supplies data with SET

requests, he'll have a random 3-character name, HT 100,

ST in [5,15], DX in [5,15] and Aggr in [5,15].

h2. RESOURCE MANAGEMENT

The great difference from the Dining Philosophers

situation is that hackers have an attitude. They won't

starve while the neighbour is eating happily. They'll

attack their neighbours phisically with punches.

The ST, Aggr and DX stats shape the behavior. A

situation when a hacker may hit a neighbour is

called a hit roll, and is performed by the server.

Clients only find out they've been hit by checking the

HT with GET requests.

A hit roll is performed when a hacker already has 

acquired a chopstick, tries to acquire the second

and fails. The hacker is anger at the neighbour who

caused the request to fail, and the server performs

a hit roll.

First the server rolls 3D6 (3 6-faced dice) against

the hacker's Aggr parameter. If the roll is greater

than Aggr, the hacker wasn't upset enough, and won't

proceed with the hit.

If the hacker proceeds with the hit, the server

rolls a dexterity dispute between the attacker

and the defender, with a +2 innitiative bonus for the

attacker. The roll is :

* Attacker:  Attacker.DX + 1D6 + 2

* Defender:  Defender.DX + 1D6

If the defender's result is greater or equal than the

attacker's result, he successfully dodged the punch, and

the hit roll is over.

Else, the punch hit, and the server will roll the

damage, which is

 (Attacker.ST x 1D6) / 3

The damage is subtracted from the defender's HT.

A character is knocked out if his HT reaches 0 or

less. Knocked out characters are disconnected from

the server, and both the character and his associated

chopstick are removed from the table.

h2. STARVATION

The starvation timeout is ST x 3 seconds. The server

knocks off starved hackers.

h2. OBSERVATION SUB-PROTOCOL

The server also provides a secondary protocol for

processes willing to observe the global table

situation. The watcher makes a TCP connection

to port 8082. There's no greeting message, the

server starts listening for requests immediatelly.

To request a global overview the client sends

any octet to the server.

The server replies with a table snapshot made of

  1 octet   - H# : NUMBER OF ACTIVE HACKERS

and H# hacker state messages. Adjacent messages

represent adjacent hackers. Each message is 21

octets long:

        16 octets    - hacker name, zero-terminated

         1 octet     - ST

         1 octet     - HT

         1 octet     - DX

         1 octet     - Aggr

         1 octet     - eating flag, non-zero if the hacker

                       currently has two chopsticks in his

                       possession, zero otherwise.