Definition of the Arch revision control protocol Status This document is a very rough draft, and is subject to change. Abstract The Arch protocol allows an implementation of the arch revision control system to communicate with a server. It provides the ability to both read archives and to commit to them. Several forms of authentication are standardized, and the protocol is flexible enough to allow more to be added later. This protocol has the potential to allow much more efficient communication than between a client and a "dumb filesystem". Table of Contents [to be added later] Arch Protocol specification 1. How to Read This Document 1.1. Organization of This Document This document is written for people interested in writing either an arch client or an arch server. 1.2. Conventions Used [insert all the typical RFC stuff about MUST, SHOULD, etc. here] 2. Protocol Overview 2.1 Link Layer The Arch protocol assumes a reliable underlying transport, such as TCP. The port intended to be reserved for the Arch protocol is 2420. 2.2. Commands and Responses An Arch protocol connection consists of the initial link layer connection, then a greeting from the server, and followed by a sequence of client commands and the server response. As with many other Internet protocols, the lines sent between the server and client are strings that are terminated by CRLF. A server or client may also send a sequence of octects with a predeclared length. The structure of a command or response consists of a single line, followed by a (possibly empty) sequence of headers, then a single empty line (which denotes the end of the headers), and possibly followed by a "payload". More details follow. 2.2.1. Command/Response line This is the first line in a message sent between a client or a server. 2.2.1.1. Client command line A client command line consists of a single command word, followed by an archive name, and then by a (possibly empty) sequence of arguments. Each argument is separated by a single space character. Example: statrev address@hidden cat--main--0--patch-3 2.2.1.2. Server response line A server response line consists of a numeric status code, followed by an informational message which SHOULD NOT be used programmatically by the client. It is intended primarily for debugging purposes. Example: 404 No such category 2.2.2. Headers A header is a single line, which consists of a key and a value. Both the key and the value may only contain printable ASCII characters. The key is separated from the value by a colon and a space character. Both the client and the server can send a group of these headers along with a command or response line. Some headers have general meaning independent of the command or response, and some may have to be treated differently depending on the particular command or reponse code. The headers form a sequence, and are terminated by a single empty line. 2.2.2.1. Command/Response line independent headers The single header which all clients MUST read if present is "Content-Length". This header implies that there is a "payload" to be read along with this command. More on this will be explained below. 2.2.2.2. Command/Response line dependent headers These headers will be defined along with their associated commands, below. 2.2.3. Payload This third part of a message is optional; it is only present if Content-Length: is present in the headers. The value of the Content-Length field contains an integer that describes the number of octets to follow after the end of the headers. 3. State and Flow There are three states: UNAUTH, AUTH1, and AUTH. More on this will come later. 4. Data Formats More on this later. 5. Client Commands 5.1 AUTH Command Still to be documented. 5.2. CATEGORIES Command Arguments: archive, category Specific Headers: none Payload: yes This command returns a serialized relational table with one field, consisting of the categories in the specified archive. 5.3. BRANCHES Command (see above) 5.4. VERSIONS Command (see above) 5.5. REVISIONS Command (see above) 5.6. ARCHVERSION Command Arguments: archive Specific Headers: none Payload: yes This command returns a string representing the version of the data formats in use in this archive. 5.7. CATLOG Command Arguments: archive, revision Specific Headers: none Payload: yes This command returns the contents of the log associated with the specified revision. 5.8. STATREV Command Arguments: archive, revision Specific Headers: Mode, Continuation, Cacherev Payload: no Result: This command returns no payload; the interesting data is contained in the headers. They'll be documented later.