protocol.md - mainline in sup

Redwood Protocol
================

The server begins by sending a line of the form `Redwood <ver> <encodings>
<extensions>`, where `ver` is the major protocol version (1), encodings is a
comma-separated list of supported message encodings (e.g. `json,bert,marshal`),
and `extensions` is a comma-separated list of protocol extensions. The server
must advertise at least one encoding. A zero-length list of extensions is
represented by `none`. The client replies in the same format, with the
restrictions that the protocol version must match, `encodings` and `extensions`
must be subsets of what the server advertised, and there must be exactly 1
encoding specified.

Requests and responses are represented as `[type, params]`, where `type`
is a lowercase string corresponding to one of the message types specified
below and `params` is a dictionary with string keys.

Requests
--------

There may be zero or more replies to a request. Multiple requests may be
issued concurrently. There is an implicit, optional, opaque `tag` parameter to
every request which will be returned in all replies to the request to
aid clients in keeping multiple requests in flight. `tag` may be an
arbitrary datastructure and for the purposes of Cancel defaults to nil.

### Query
Send a Message response for each hit on `query` starting at `offset`
and sending a maximum of `limit` Messages responses. `raw` controls
whether the raw message text is included in the response.

#### Parameters
*   `query`: Query
*   `offset`: int
*   `limit`: int
*   `raw`: boolean

#### Responses
*   multiple Message
*   one Done after all Messages


### Count
Send a count reply with the number of hits for `query`.

#### Parameters
*   `query`: Query

#### Responses
*   one Count


### Label
Modify the labels on all messages matching `query`. First removes the
labels in `remove` then adds those in `add`.

#### Parameters
*   `query`: Query
*   `add`: string list
*   `remove`: string list

#### Responses
*   one Done


### Add
Add a message to the database. `raw` is the normal RFC 2822 message text.

#### Parameters
*   `raw`: string
*   `labels`: string list

#### Responses
*   one Done


### Stream
Sends a Message response whenever a new message that matches `query` is
added with the Add request. This request will not terminate until a
corresponding Cancel request is sent.

#### Parameters
*   `query`: Query

#### Responses
multiple Message


### Cancel
Cancels all active requests with tag `target`. This is only required to
be implemented for the Stream request.

#### Parameters
*   `target`: string

#### Responses
one Done



Responses
---------

### Done
Signifies that a request has completed successfully.


### Message
Represents a query result. If `raw` is present it is the raw message
text that was previously a parameter to the Add request.

#### Parameters
*   `summary`: Summary
*   `raw`: optional string


### Count
`count` is the number of messages matched.

#### Parameters
*   `count`: int


### Error

#### Parameters
*   `type`: string
*   `message`: string



Datatypes
---------

### Query
Recursive prefix-notation datastructure describing a boolean condition.
Where `a` and `b` are Queries and `field` and `value` are strings, a
Query can be any of the following:

*   `[:and, a, b, ...]`
*   `[:or, a, b, ...]`
*   `[:not, a, b]`
*   `[:term, field, value]`


### Summary
*   `message_id`: string
*   `date`: time
*   `from`: Person
*   `to`, `cc`, `bcc`: Person list
*   `subject`: string
*   `refs`: string list
*   `replytos`: string list
*   `labels`: string list


### Person
*   `name`: string
*   `email`: string


TODO
----

*   Protocol negotiation
   -   Version
   -   Compression (none, gzip, ...)
*   Specify string encodings

1	Redwood Protocol
2	================
3
4	The server begins by sending a line of the form `Redwood <ver> <encodings>
5	<extensions>`, where `ver` is the major protocol version (1), encodings is a
6	comma-separated list of supported message encodings (e.g. `json,bert,marshal`),
7	and `extensions` is a comma-separated list of protocol extensions. The server
8	must advertise at least one encoding. A zero-length list of extensions is
9	represented by `none`. The client replies in the same format, with the
10	restrictions that the protocol version must match, `encodings` and `extensions`
11	must be subsets of what the server advertised, and there must be exactly 1
12	encoding specified.
13
14	Requests and responses are represented as `[type, params]`, where `type`
15	is a lowercase string corresponding to one of the message types specified
16	below and `params` is a dictionary with string keys.
17
18	Requests
19	--------
20
21	There may be zero or more replies to a request. Multiple requests may be
22	issued concurrently. There is an implicit, optional, opaque `tag` parameter to
23	every request which will be returned in all replies to the request to
24	aid clients in keeping multiple requests in flight. `tag` may be an
25	arbitrary datastructure and for the purposes of Cancel defaults to nil.
26
27	### Query
28	Send a Message response for each hit on `query` starting at `offset`
29	and sending a maximum of `limit` Messages responses. `raw` controls
30	whether the raw message text is included in the response.
31
32	#### Parameters
33	* `query`: Query
34	* `offset`: int
35	* `limit`: int
36	* `raw`: boolean
37
38	#### Responses
39	* multiple Message
40	* one Done after all Messages
41
42
43	### Count
44	Send a count reply with the number of hits for `query`.
45
46	#### Parameters
47	* `query`: Query
48
49	#### Responses
50	* one Count
51
52
53	### Label
54	Modify the labels on all messages matching `query`. First removes the
55	labels in `remove` then adds those in `add`.
56
57	#### Parameters
58	* `query`: Query
59	* `add`: string list
60	* `remove`: string list
61
62	#### Responses
63	* one Done
64
65
66	### Add
67	Add a message to the database. `raw` is the normal RFC 2822 message text.
68
69	#### Parameters
70	* `raw`: string
71	* `labels`: string list
72
73	#### Responses
74	* one Done
75
76
77	### Stream
78	Sends a Message response whenever a new message that matches `query` is
79	added with the Add request. This request will not terminate until a
80	corresponding Cancel request is sent.
81
82	#### Parameters
83	* `query`: Query
84
85	#### Responses
86	multiple Message
87
88
89	### Cancel
90	Cancels all active requests with tag `target`. This is only required to
91	be implemented for the Stream request.
92
93	#### Parameters
94	* `target`: string
95
96	#### Responses
97	one Done
98
99
100
101	Responses
102	---------
103
104	### Done
105	Signifies that a request has completed successfully.
106
107
108	### Message
109	Represents a query result. If `raw` is present it is the raw message
110	text that was previously a parameter to the Add request.
111
112	#### Parameters
113	* `summary`: Summary
114	* `raw`: optional string
115
116
117	### Count
118	`count` is the number of messages matched.
119
120	#### Parameters
121	* `count`: int
122
123
124	### Error
125
126	#### Parameters
127	* `type`: string
128	* `message`: string
129
130
131
132	Datatypes
133	---------
134
135	### Query
136	Recursive prefix-notation datastructure describing a boolean condition.
137	Where `a` and `b` are Queries and `field` and `value` are strings, a
138	Query can be any of the following:
139
140	* `[:and, a, b, ...]`
141	* `[:or, a, b, ...]`
142	* `[:not, a, b]`
143	* `[:term, field, value]`
144
145
146	### Summary
147	* `message_id`: string
148	* `date`: time
149	* `from`: Person
150	* `to`, `cc`, `bcc`: Person list
151	* `subject`: string
152	* `refs`: string list
153	* `replytos`: string list
154	* `labels`: string list
155
156
157	### Person
158	* `name`: string
159	* `email`: string
160
161
162	TODO
163	----
164
165	* Protocol negotiation
166	- Version
167	- Compression (none, gzip, ...)
168	* Specify string encodings

Gitorious