| 1 | Introduction |
| 2 | Connections, Commands, and Frames |
| 3 | Initialization |
| 4 | Frames |
| 4.1 | Frame Syntax |
| 4.2 | Frame Header |
| 5 | Command Numbers |
| 6 | Aborts and Kills |
| 7 | References |
| A | Copyright Notice |
This memo describes the Asynchronous Notification Transport Protocol Version 2.0 (ANTP/2.0), a generic framing protocol for connection-oriented, asynchronous interactions. ANTP permits simultaneous and independent exchanges of data between peers. Data exchanges may take the form of one directional messaging, or request/reply pairs in which data flows in both directions. The protocol is asynchronous in the sense that replies are transmitted as soon as their data is ready--they need not be transmitted in the order in which their corresponding requests were issued.
ANTP assumes it will be used on top of a reliable, connection-oriented protocol such as TCP/IP. ANTP can be used to exchange data when only one direction of a connection is available for use as long as the application limits itself to messaging.
ANTP does little else other than to provide a framing mechanism. For example, it defines no mechanism for authentication. Exchanges relating to security are expected to be carried by the standard framing mechanism provided by ANTP and implemented by a protocol layered on top of ANTP.
ANTP defines a framing protocol that is similar to the one defined by The Blocks Extensible Exchange Protocol [BEEP]. It is distinguished by the fact that all data transfers are asynchronous, and frames of a data transfer may be interleaved with the frames that make up any other transfer.
In BEEP, data is transferred on channels. "When a message is segmented and sent as several frames, those frames must be sent sequentially, without any intervening frames from other messages on the same channel." [BEEP, p. 9] To implement ANTP on top of BEEP, one would have to create and destroy a channel for each message sent.
ANTP is also distinguished from BEEP by its support for one directional messaging and lack of support for requests that expect more than reply.
ANTP provides data framing on a connection between two peers. To link the two peers, one peer listens for connections, while the other initiates the connection. After a connection is established, the roles of both peers are indistinguishable as long as both directions of the connection remain open.
In the common case, a connection provides two streams on which bytes flow in opposite directions. Such a connection is called full duplex. A connection with one stream is called half duplex.
On a full duplex connection, both peers may initiate data exchange. For
the purposes of exposition, the peer initiating a data exchange will be
called the sender, and other peer will be called the
receiver. In the examples that follow, they are referred to as
S:
and R:
, respectively.
ANTP supports two styles of data exchange, one way messaging, in which data flows only from the sender to the receiver, and request/response pairs in which data flows in both directions. The sender produces the request and the receiver produces the reply. Request/response pairs can be carried only on a full duplex connection.
The unit in which data is transported is called a command. Each message, request, and reply constitutes one command. An error report associated with a command is considered to be part of the command.
Every command is transported in one or more frames. Large commands should be transported in multiple frames so that other commands can be interleaved on the same connection. In this way, a short command sent after the first frame of a large command can arrive before the last frame of the large command is received. A frame that transports all or part of a command is called a chunk of the command.
A framing session is initialized by the sending of an ANTP greeting on each open stream. The greeting states the maximum size in bytes of every command sent on the stream during the session. The size of a command is the sum of the size of the payload of each chunk of a command. The maximum command size must be at least 1024 bytes, and may be as large as 2147483647 bytes. Every peer must support all maximum command sizes up to 8192 bytes. The format of a greeting follows.
ANTP/2.0 size
Note that the two streams of a full duplex connection may specify a different maximum command size.
Each frame consists of a header, and a payload. The header is represented using printable ASCII characters and is terminated with a CRLF pair. The payload follows, consisting of zero or more octets.
For example, the following display contains a one way message in a single frame that has a payload of 35 octets spread over 2 lines, where each line is terminated with the LF character:
S: MSG 0 . 35 S: This is one line. S: This is another.
The ABNF [ABNF] for an ANTP stream is:
stream = greeting *frame greeting = "ANTP/2.0" SP size CR LF frame = msg / abt / req / rpy / kil msg = "MSG" SP parameters CR LF payload abt = "ABT" SP parameters CR LF payload req = "REQ" SP parameters CR LF payload rpy = "RPY" SP parameters CR LF payload kil = "KIL" SP parameters CR LF payload parameters = cmdno SP more SP size cmdno = 0..2147483647 more = "." / "*" size = 0..2147483647 payload = *OCTET
The frame header consists of a three-character keyword, followed by three parameters. A single space character separates each component. The header is terminated with a CRLF pair.
The keyword must be one of: "MSG", "ABT", "REQ"", "RPY", or "KIL". A one way message is identified by the keyword "MSG", a request by "REQ", and a reply by "RPY". An aborted command is identified by the keyword "ABT", and a killed command by "KIL".
The command number ("cmdno") must be a non-negative integer in the range 0..2147483647. It is used to identify the frames that make up one command.
The continuation indicator ("more") specifies whether this is the final frame of the command. It must be one of: "*", or ".". Asterisk signifies that at least one other frame follows for the command. Period signifies that this frame completes the command.
The payload size ("size") must be a non-negative integer in the range 0..2147483647. It specifies the exact number of octets in the payload.
A command number is used to identify the frames that make up one command on a connection. The sending peer assigns a command number to all messages and requests. The sending peer must ensure that no two commands initiated by the peer on a connection share the same command number. A reply uses the command number of its associated request.
A sending peer may reuse the command number of a message after the last chunk of the message has been written to the connection. A sending peer may reuse the command number of a request after the last chunk of the reply has been received from the connection. For example, following data exchanges require the use of only one command number.
S: REQ 0 . 11 S: A request. R: RPY 0 . 0 S: MSG 0 . 11 S: A message. S: REQ 0 . 17 S: Another request. R: RPY 0 . 0
An essential feature of this protocol is that it allows asynchronous interactions. In particular, several requests can be made without waiting for a reply and replies need not arrive in the order in which the corresponding requests were issued. The receiving peer of a request must see the end of a request before it sends the first chunk of the reply. The use of more than one command number allows the following data exchanges.
S: REQ 0 * 11 S: A request. S: REQ 1 * 17 S: Another request. R: RPY 0 * 22 R: First chunk of reply. S: REQ 1 . 29 S: Another part of the request. S: MSG 2 . 11 S: A message. R: RPY 1 . 0 R: RPY 0 . 6 R: Done.
The final frame of most commands is simply an ordinary frame with a period for the continuation indicator. The final frame of a command can also be an abort or a kill. Aborts and kills indicate exceptional conditions associated with a command. An abort is used by the sending peer to indicate an exceptional condition to the receiver, and a kill is used by the receiving peer to indicate an exceptional condition to the sender. Thus, only messages and requests can be aborted while only replies can be killed.
Aborts and Kills must fit into one frame; that is, their continuation indicator must be a period. The payload of every abort or kill is one of a fixed set of one line error reports defined below.
400 Bad Request- The request was ill formed.
401 Request Too Large- The request was too large.
402 Request Time Out- The peer timed-out waiting for the complete request.
500 Bad Reply- The peer received an erroneous response from another peer.
501 Reply Too Large- The reply was too large.
502 Reply Time Out- The peer timed-out after waiting for a response from another peer.
503 Internal Error- The command was terminated because of an error internal to the peer.
504 Early Reply- A reply was received before the complete request was sent.
The payload of an abort or a kill must not include the CR character or the LF character.
When the receiver of a message gets an abort, the receiver can assume that the sender is unable or unwilling to transmit the complete message and the sender will transmit no more chunks of the command. A message that is sent in one frame can never be aborted. The sender can reuse the command number of an aborted message.
When the receiver of a request gets an abort, the receiver can assume that the sender is unable or unwilling to transmit the complete request and the sender will transmit no more chunks of the command. If the receiver has not yet killed the reply, it must respond by sending a kill to the sender. The payload of the kill must be the same as the payload of the abort.
When the sender of a request gets a kill, the sender can assume that the receiver will not transmit any more chunks of the reply. If the sender has not completed sending the request, it should immediately abort the request. The payload of the abort must be the same as the payload of the kill. The sender can reuse the command number of a killed reply.
If a sender receives the first chunk of a reply, and the sender has not completed sending the matching request, it should immediately abort the request. The abort payload must contain the early reply report number 504. This condition should only occur when the receiving peer incorrectly implements the protocol.
Each endpoint of a connection must be able to handle up to a total of 1024 incomplete messages and requests. An endpoint may simply close its input if asked to handle too many incomplete commands.
Copyright © 2002 The MITRE Corporation. All Rights Reserved.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to The MITRE Corporation.
This document and the information contained herein is provided on an "AS IS" basis and THE MITRE CORPORATION DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.