NAME
6b - wombat's burrow protocol
DESCRIPTION
A wombat server is a program that serves a path. A server responds to requests by clients to get, put or del the file at a path.
The prototypical server is the root, mounted at / by boot; a tree of files kept in the image, where a put stores text and a get returns it. Another possibility is for a server to interpret requests instead of storing them, so that its paths form an interface to something it manages. Bat, which serves /srv/proc/, is an example: putting a record to /srv/proc/new starts a process, deleting a process's directory ends it, and getting its ns file returns its binds, synthesised when asked.
Wombat's burrow protocol, 6b, is used for messages between clients and servers: a client sends a request, and the server answers with a response. A request is stateless and synchronous. A server that needs time answers at once and reports its progress in a file.
MESSAGES
request <verb> <path> [ <length> ] LF
[ <body> ]
response <status> LF
<text>
Each request takes a verb, a path, and optionally a length and a body.
The verb can be: get, put or del.
The path starts with / and contains no spaces or newlines.
The length is the size of the body in bytes and is only present when there is a body.
Each response takes a status and text. The status is a two-digit code: 10 means success and the text is the content; 20 means error and the text is a short reason. Other codes are reserved. The text runs to the end of the response.
Fields on the first line are separated by a single space. LF is a newline; a reader should also accept a carriage return before it, or the end of input in its place.
DIRECTORIES
The parts of a path are separated by /. A directory's path is written with a trailing /.
A get on a directory responds with its listing: one line per entry, each a link.
=> <path> [ <label> ]
A link's path is relative to the directory unless it starts with /.
An entry that is itself a directory ends in /.
A put to a path with a trailing / and no body makes a directory.
A put to a file makes the directories above as needed.
A del on a directory removes it and everything in it.