Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time


While IP-SFS makes it possible to transmit Internet protocols over semaphore signalling systems such as Clacks, the reverse is not always the case. Information sent in the Overhead may be lost when Clacks messages are sent using HTTP.

This document specifies HTTP headers for transmitting Overhead messages that originate or are intended for Clacks towers.

Syntax Notation

This specification uses the Augmented Backus-Naur Form (ABNF) notation of and includes, by reference, the "token", "word", "OWS", and "BWS" rules and the #rule extension as defined within Sections 3.2.1 and 3.2.4 of .

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .

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. 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 Demon and further interpretation of the message body is not required. For this reason Clacks Towers, 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. Clacks messages that arrive at the Tower are read by a Demon (alternately a Dwarf, Troll, or the occasional quick-fingered Human) then forwarded to an Internet connected computer with appropriate HTTP headers applied. The Demon will activate the Clacks shutters when data is received from the Internet.

A Gateway MUST send one HTTP request for each regular Clacks message. Because Overhead messages are transmitted more frequently on a Clacks network, sending a request for each message is inefficient. A Gateway MUST buffer incoming Overhead messages. One or more buffered messages are forwarded when one of the following events occurs:

  • A regular Clacks message is forwarded.
  • The Demon has exhausted available memory for saving messages.
  • The Demon is about to go down the ladder.

If Overhead messages are being sent without a Clacks message as the body of the HTTP request then the Gateway MUST send a "HEAD" request. The Gateway SHOULD send as many Overhead messages as possible when sending a request.

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 header field is used to transmit Overhead messages in an HTTP response or request. The Accept-Clacks header field is sent in an HTTP request to indicate to a server that a client is able to process Overhead messages. In the absence of an Accept-Clacks header a server MAY respond with a Clacks message in the hope that the client can do something with it and merely forgot to send the Accept-Clacks header.

An Overhead message consists of a Clacks Code, an optional Tower Address, and a possibly encoded message body. Servers SHOULD limit the length and number of Clacks so as not to overwhelm the receiving Gateway Demon.

Clacks          = 1#clacks-overhead
clacks-overhead = clacks-code [ RWS tower-address ] RWS value
tower-address   = token
clacks-code     = 1*codechar
codechar        = ALPHA
value           = value-string / quoted-string / ext-value
ext-value       = "=" charset "'" [ language ] "'" value-chars
                ; like [RFC5987]

The 'codechar' above may refer to any uppercase letter; codes in common use throughout the Clacks network are defined in the .

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 valid Accept-Clacks header is received by a server then it MUST NOT send Overhead message codes that are not indicated by the Accept-Clacks header.

A client can refuse all Clacks responses with the Accept-Clacks header value of "no". A server MUST NOT send a Clacks header if the request refuses.

Accept-Clacks  = "no" / accept-clacks-encoding
accept-clacks-encoding = clacks-code RWS clacks-encodings
clacks-encodings = "*" / ( token *( "/" token ) )

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 that is only used by the Clacks tower at Unseen University.


HTTP/1.1 200 OK
Clacks: GNU John Dearheart

IANA Considerations

The 'Clacks' header field has been added to the "Permanent Message Header Field Names" registry defined in . FIXME: not submitted yet

Header field name: Clacks

Applicable Protocol: HTTP

Status: Standard

Author: Sir Terry Pratchett (posthumously)

Change controller: IETF

Specification document: this specification

Environmental Considerations

As noted in , a Clacks message sent via the traditional semaphore network represents a significant expenditure of energy, not only in the operation of the signalling panels, but in manual verification and message passing. It is self-evident that this specification provides for a high level of efficiency, utilizing existing infrastructure to provide the seamless interaction that users of the Clacks network have come to expect.

Security Considerations

This document represents an extension to and all security considerations therein, or in documents updating or replacing that document, also apply to this one.

Proxy considerations

Since all Clacks messages are effectively point-to-point transmissions there is very limited scope for multiple User-Agents to require the same message. Due to this any message with the Clacks header MUST be considered equivalent to the no-cache header defined in Section this allows for the cache to store the object as long as it is revalidated prior to sending.

User-Agent considerations

A user-agent should follow the Grand Trunk Clacks standards for Overhead definition.

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.