In-progress checkpoint of gateway description.

middle.mkd

@@ -27,19 +27,51 @@ interpreted as described in [](#RFC2119).
 
 # The Clacks Protocol
 
-Clacks is a semaphore signalling system invented by Robert Dearheart. It is the primary means of communication between city-states along The Grand Trunk. Like most protocols Clacks has a Header (called the Overhead) and Payload. The Overhead contains information about (among other things) source, destination, message detail, logging, and mechanism control. This document doesn't define the Clacks protocol, only it's delivery over HTTP. The Clacks protocol definition is owned by The Grand Trunk Semaphore Company, Ankh Morpork.
-
-All Overhead messages begin with a Clacks Code. A Code is a sequence of upper-case letters. Each letter determines how the message and the order of letters is significant. Some instructions require a Tower Address which is sent immediately after the Code. The Code and Tower Address are always sent in the Plain.
-
-The Overhead body may be encoded to shorten the message or conceal it from eavesdropping. A message that is not encoded is sent "in the Plain" or just "Plain" In many cases the Code alone is sufficient instruction to the Clacks operator and further interpretation of the message body is not required. For this reason Clacks operators, and thus HTTP clients and servers, MUST be able to accept messages with an unknown encoding.
-
-# Clacks over HTTP Protocol Additions
-
-The Clacks over HTTP extension specifies one header field which MAY be included
+Clacks is a semaphore signalling system invented by Robert Dearheart. It is the
+primary means of communication between city-states along The Grand Trunk. In a
+Clacks network a Tower transmits message packets to peers selected by either a
+minimum-cost or nearest-neighbor algorithm depending on the packet class. The
+packet payload is either a regular Clacks as input directly by a user or a user
+agent, or an Overhead packet for transmitting side channel data between Towers.
+
+    +------------------------+
+    |          Code          |
+    +------------------------+
+    |Tower Address (optional)|
+    +------------------------+
+    |                        |
+    //    Overhead Body      //
+    |                        |
+    +------------------------+
+^[fig:packet::An Overhead packet.]
+
+An Overhead message begins with a Clacks Code. A Code is a sequence of upper-case
+letters with the order of letters being significant. Some Codes require a Tower
+Address which is sent immediately after the Code. The Code and Tower Address are
+always sent in the Plain. A registry of Clacks Codes is maintained by the Grand
+Trunk Semaphore Company, Ankh Morpork.
+
+The Overhead body may be encoded to shorten the message or conceal it from
+eavesdropping. A message that is not encoded is sent "in the Plain" or just
+"Plain" In many cases the Code alone is sufficient instruction to the Clacks
+operator and further interpretation of the message body is not required. For
+this reason Clacks operators, and thus HTTP clients and servers, MUST be able
+to accept messages with an unknown encoding.
+
+# Clacks-over-HTTP Gateways
+
+The Clacks networks of Discworld interface with the Internet of Roundworld at
+gateway Towers.
+
+TODO: draw a diagram, packet flow through gateways, gateways must flush overhead before the operator forgets what the message is (require HEAD requests for overhead sans message body?)
+
+## Protocol Additions
+
+The Clacks-over-HTTP extension specifies one header field which MAY be included
 in a HTTP response or request, and one header field which MAY by included in
 a HTTP request.
 
-## The Clacks response field
+### The Clacks response field
 
 The Clacks header field is used to transmit Overhead messages in an 
 HTTP response or request. The Accept-Clacks header field is sent in
@@ -49,6 +81,8 @@ a server MAY respond with a Clacks message in the hope [](#HOPE)
 that the client can do something with it and merely forgot to send the
 Accept-Clacks header.
 
+TODO: maximum length?
+
 An Overhead message consists of a Clacks Code, an optional Tower Address, and a possibly encoded message body.
 
     Clacks          = 1#clacks-overhead
@@ -63,7 +97,7 @@ An Overhead message consists of a Clacks Code, an optional Tower Address, and a
 The 'codechar' above may refer to any uppercase letter; codes in common use
 throughout the Clacks network are defined in the [GTSC-CLACKS](Grand Trunk Semaphore Company, "Clacks Operator's Book").
 
-## The Accept-Clacks header field
+### The Accept-Clacks header field
 
 A Clacks-capable client SHOULD include in HTTP requests an Accept-Clacks
 header indicating the Clacks codes and encodings it recognises. If a
@@ -76,7 +110,7 @@ header.
 
 A Clacks-capable client MUST support "Plain" encoding. Other commonly used encodings are "RKN" Reverse-Klatchian Notation, and "Ook" also known as Simian Computer System for Information Interchange [](#SCSII) that is only used by the Clacks tower at Unseen University. 
 
-## Examples
+### Examples
 
     HTTP/1.1 200 OK
     Clacks: GNU John Dearheart
@@ -118,7 +152,7 @@ Since all Clacks messages are effectively point-to-point transmissions there is
 # User-Agent considerations
 A user-agent should follow the Grand Trunk Clacks standards [](#GTSC-CLACKS) for Overhead definition. 
 
-Since the Clacks to HTTP gateway is expected to be a human (or Dwarf, Troll, etc.) operated process User-Agents need to cope with long session availability to provide the necessary time window to allow the message to be input.
+Since the Clacks-over-HTTP gateway is expected to be a human (or Dwarf, Troll, etc.) operated process User-Agents need to cope with long session availability to provide the necessary time window to allow the message to be input.
 
 # IP-SFS Tunnelling 
 The Clacks-over-HTTP protocol makes available the option of tunnelling proprietary Clacks messages over an IP-SFS based network to allow for interconnection of different operator networks.