new server/client protocol, draft 0.01

[Tapani T. <tt...@it...>]

OK, here goes. Comments welcome, positive or otherwise:


amavis server/client (milter) protocol - draft 0.01
===================================================
<Tapani Tarvainen 2003-05-02 16:13:20>

Note: the message lists below are intended as neither
comprehensive nor minimum required. 

This assumes the client initiates the connection and
sends its greeting message first; I am of two minds
about this, it might be better for it to wait for a
reply after connecting before sending anything (cf. smtp). 


*** Messages from client to server ***
--------------------------------------

General format:
NNN KEYWORD data\r\n

NNN is 3-digit numeric code, generally interpreted as follows:

digit 1: callback class
	0 = greeting (no real callback)
	1 = connection-oriented except close or abort
	2 = recipient-oriented
	3 = message-oriented except eom
	4 = eom, message-modifying commands accepted
	5 = eom, expecting multi-line body data
	9 = end of discussion (close, abort)
digit 2: specific callback within class (see below)
digit 3: message type
	0 = OK (no message)
	1 = default message for this callback
        2 = multi-line message (body format, "."-terminated)
	3-6 = reserved
	7 = SYMBOL symbol=value
	8 = warning message 
	9 = error message

Greeting: only 0x response allowed
   011 AMILTER-CLIENT version feature-code comment\r\n
Connection-oriented: 1x and 7x responses allowed
   111 CONNECT a.b.c.d hostname\r\n
   121 HELO string\r\n
Recipient-oriented callbacks: 1x, 2x, 3x and 7x responses allowed
   211 ENVRCPT user@host\r\n
Message-oriented callbacks: 1x, 2x, 3x and 7x responses allowed
   311 ENVFROM user@host\r\n
   321 HEADER string\r\n
   331 EOH\r\n
   342 BODY\r\n
   [after receiving 51 response]
   lines of text, terminated with period by itself,
   on other lines leading periods doubled
Ready for message modification: 1x-4x and 7x responses allowed
   411 EOM\r\n
Ready for body-type data: expects "."-terminated sequence of lines
   511 READY FOR "."-TERMINATED DATA\r\n
Termination: no further communication accepted
   911 CLOSE\r\n
   921 ABORT\r\n
   991 PANIC\r\n
Information only (xx may be from any of the above): 
   xx0 OK\r\n
   xx7 SYMBOL symbol=value\r\n
   xx8 WARNING message\r\n
   xx9 ERROR message\r\n

*** Messages from server to client ***
--------------------------------------

General format:
NN KEYWORD data\r\n

Greeting, required as response to greeting (0xx), could specify
which callbacks we're interested in, or which version we want, &c:
   01 AMILTER-SERVER version feature-code comment\r\n
Responses valid to all callbacks (1xx-4xx):
   11 CONTINUE\r\n
   12 REJECT\r\n
   13 ACCEPT\r\n
   19 TEMPFAIL\r\n
Responses valid to recipient- and message-oriented callbacks only (2xx-4xx):
   21 DISCARD\r\n
Message modifying commands, valid in 41x callback only:
   41 ADDHEADER string\r\n
   42 CHGHEADER string\r\n
   43 ADDRCPT string\r\n
   44 DELRCPT string\r\n
   45 REPLACEBODY\r\n
   [after receiving 511 response]
   lines of text, terminated with a period by itself,
   on other lines leading periods double
Message indicating readiness to body-type data, valid after xx2 only
   51 READY FOR "."-TERMINATED DATA\r\n
Data access and library control, valid almost everywhere:
   71 GETSYMVAL string\r\n
   72 SETREPLY code\r\n


*** Minimum requirements ***
----------------------------

The client must start with the 011 greeting and
terminate with an 9xx message; normally it should
provide at least one 1xx-4xx class message, 
but in an error situation it may give
9xx at any point, even immediately after greeting.
Upon receiving 12-19 or 21 it should take appropriate 
action and terminate the connection immediately with 911.
Unknown 1x and 2x messages should be treated as 19 (??).
The "feature-code" in greeting message could provide
a code of features supported or action wanted
[unspecified as yet].
(E.g., any or all 7x and some or even all of 4x might
be unsupported by some clients.) 
Unknown messages should be replied with xx8.

The server is required to reply properly to 011
and know that 9xx messages mean end of communication;
it should respond to all 1xx-4xx messages it doesn't
understand or care about with "11 CONTINUE".
It must know how to receive all lines of xx2 messages 
(even if it then ignores them).
The "feature-code" in greeting message could request
an alternate behaviour from the client (after it has
advertized such capability).

=====================================================


-- 
Tapani Tarvainen