982013-04-23 15:34:37teratornRevert to revision 96.972013-04-20 20:44:49JoelZOWA962013-03-22 15:53:26teratornRevert to revision 94.952013-03-21 22:02:21NiamhKins942013-03-21 20:03:57teratornRevert to revision 92.932013-03-18 20:53:11JoelZOWA922012-09-02 21:25:37teratornnote912012-09-02 19:30:29teratornwhitespace902012-08-31 20:51:38rrcs-50-84-155-27.sw.biz.rr.comy it iz so gud892012-08-31 18:05:55rrcs-50-84-155-27.sw.biz.rr.comimpl note882012-08-31 18:05:01rrcs-50-84-155-27.sw.biz.rr.comreword872012-03-14 07:56:5112.191.60.106TLS link862011-08-26 14:15:54teratornRevert to revision 84.852011-08-26 10:49:11204-242-webenlet.hu842011-07-31 10:12:39rrcs-71-42-153-210.sw.biz.rr.comminor tweaks832011-07-30 04:18:51rrcs-71-42-153-210.sw.biz.rr.com822011-07-12 21:13:17rrcs-71-42-153-210.sw.biz.rr.comformat tweaks812011-07-01 22:04:16rrcs-71-42-153-210.sw.biz.rr.com802011-06-13 00:09:39teratorn792011-06-06 18:48:24teratorn782011-06-06 06:27:22teratorn772011-06-06 06:03:49teratorn762011-06-06 06:03:28teratorn752011-06-06 05:52:18202-7-189-118.static.tpgi.com.auMention size limits.742011-06-01 16:52:45teratorn732011-05-30 21:39:07teratorni laff722011-05-30 21:36:06teratornclarify desired behavior for error codes712011-05-30 21:24:06teratorn702011-05-24 16:25:55teratornanchor test692011-05-21 06:04:44109.64.184.254682011-01-13 10:58:46teratorn672010-12-15 14:16:47teratornadd line break662010-12-15 14:13:02teratorn0x02 instead of 0x03652010-11-17 03:43:51teratorn642010-11-17 00:28:43teratorn632010-11-17 00:26:38teratorn622010-11-11 20:17:20teratorn612010-11-11 20:15:11teratorn602010-11-11 20:14:15teratorn592010-11-11 17:25:30teratorn582010-11-11 17:23:52teratorn572010-11-10 23:46:33teratorn562010-11-10 23:44:28teratorn552010-11-10 23:44:05teratornrevert screwup542010-11-10 23:41:56teratorn532010-11-10 17:21:01teratorn522010-11-10 17:03:08teratornadd section on error handling512010-11-10 10:42:59teratorn502010-11-10 09:33:00121.90.108.75492010-11-10 08:22:23teratorn482010-11-09 23:13:13teratorn472010-11-09 22:56:51teratorn462010-11-09 22:51:36teratorn452010-11-09 22:49:15teratorn442010-11-09 19:40:42teratorn432010-11-09 19:40:21teratorn422010-11-09 19:37:31teratorn412010-11-09 19:33:08teratorn402010-11-09 19:31:33teratorn392010-11-09 19:28:50teratorn382010-11-09 18:32:38teratorn372010-11-09 18:04:17rrcs-71-42-153-210.sw.biz.rr.com362010-11-09 18:01:53rrcs-71-42-153-210.sw.biz.rr.com352010-11-09 17:33:23teratorn342010-11-09 17:25:18teratorn332010-11-09 17:21:24teratorn322010-11-09 17:19:58teratorn312010-11-09 17:15:09teratorn302010-11-09 17:09:03teratorn292010-11-09 17:06:39teratorn282010-11-09 17:03:12teratorn272010-11-09 15:14:00teratorn262010-11-09 13:09:55teratorn252010-11-09 13:04:41teratorn242010-11-09 13:04:07teratorn232010-11-09 03:24:01teratorn222010-11-09 03:20:51teratorn212010-11-09 03:19:49teratorn202010-11-09 03:17:01teratorn192010-11-09 03:15:44teratorn182010-11-09 03:09:00teratorn172010-11-08 15:45:47rrcs-71-42-153-210.sw.biz.rr.com162010-11-08 15:42:25rrcs-71-42-153-210.sw.biz.rr.com152010-11-08 15:40:24rrcs-71-42-153-210.sw.biz.rr.com142010-11-08 15:34:47rrcs-71-42-153-210.sw.biz.rr.com132010-11-08 15:33:47rrcs-71-42-153-210.sw.biz.rr.com122010-11-08 15:32:59rrcs-71-42-153-210.sw.biz.rr.com112010-11-08 15:24:40rrcs-71-42-153-210.sw.biz.rr.com102010-11-08 15:18:04rrcs-71-42-153-210.sw.biz.rr.com92010-11-08 15:15:59rrcs-71-42-153-210.sw.biz.rr.com82010-11-08 15:15:22rrcs-71-42-153-210.sw.biz.rr.com72010-11-08 15:11:03teratorn62010-11-08 14:30:25teratorn52010-11-08 14:18:20teratorn42010-11-08 14:12:28teratornstart of first example32010-11-08 09:11:40rrcs-71-42-153-210.sw.biz.rr.com22010-11-08 08:20:19rrcs-71-42-153-210.sw.biz.rr.comtweak12010-11-08 08:12:00teratorninitial version

AMP is an RPC protocol for sending multiple asynchronous request/response pairs over the same connection. Requests and responses are both collections of key/value pairs. Keys are limited to 255 bytes in length, and values to 65,535 bytes (Why?). Any number of key/value pairs may be encoded in a single AMP packet. AMP enables a rich set of Internet applications, from Client-Server "traditional" web-service operations, to highly custom and efficient RPC protocols, to distributed peer-to-peer messaging configurations. Once connected, the AMP protocol is symmetric, allowing either client or server to initiate an asynchronous request, provided the other side implements a handler for it. For values, AMP defines a number of Standard Data Types, while keys are always strings. AMP originally appeared in Twisted, a Python networking framework, however AMP is not Python-specific. Implementation are available for a variety of languages including Python, C, C#, Java, PHP and Erlang. See the implementations page for details.

AMP uses a very simple and logical wire-level format, making it easy to implement in your language of choice. Lets take a hypothetical Sum command which accepts two arguments, a and b, and returns a+b as the argument named total. Sample key/values of a request to the Sum command:_ask 23 _command Sum a 13 b 81 Key/values of the response:_answer 23 total 94 That's all there is to it for a successful invocation of the Sum command! (We'll talk about error handling later.) The special _ask key is a unique-per-connection identifier, which identifies individual requests on a particular connection (e.g. a TCP socket). Its value is used with the special _answer key to indicate the original request that is being answered. And obviously the special _command key indicates which command-handler should be invoked to process the request. AMP is asynchronous, meaning that requests and responses may be interleaved on the wire at will. You can happily fire off several requests before receiving any responses... and responses may be returned in any order. AMP is full-duplex (or symmetric), meaning that requests may be initiated from either side of the connection.

Client and server for a "Sum" command is here. You will need Python (2.x) and Twisted. Or check out a C# example.

Keys and values in AMP are length-prefixed. Keys and values both use a 16-bit (2 byte) prefix value, however, key length is restricted to 8 bits (1 byte). This means keys have a maximum length of 255 bytes, and values a maximum length of 65,535 bytes. Prefix values are in Network Byte Order (big-endian). So, the request above (a "packet", in AMP terms) looks like this on the wire:0x00 0x04 A key name of length 4 follows... 0x5F 0x61 0x73 0x6B "_ask" 0x00 0x02 A value of length 2 follows... 0x32 0x33 "23" 0x00 0x08 A key name of length 8 follows... 0x5F 0x63 0x6F 0x6D 0x6D 0x61 0x6E 0x64 "_command" 0x00 0x03 A value of length 3 follows... 0x53 0x75 0x6D "Sum" 0x00 0x01 A key name of length 1 follows... 0x61 "a" 0x00 0x02 A value of length 2 follows...0x31 0x33 "13" 0x00 0x01 A key name of length 1 follows... 0x62 "b" 0x00 0x02 A value of length 2 follows...0x38 0x31 "81" 0x00 0x00 A key of length 0. THIS MARKS THE END OF THE PACKET. Pretty simple, eh? Key names are UTF-8 encoded strings. The integer arguments, a and b, are also UTF-8 strings. The response is encoded like so:0x00 0x07 A key name of length 7 follows... 0x5F 0x61 0x6E 0x73 0x77 0x65 0x72 "_answer" 0x00 0x02 A value of length 2 follows... 0x32 0x33 "23" 0x00 0x05 A key name of length 5 follows... 0x74 0x6F 0x74 0x61 0x6C "total" 0x00 0x02 A value of length 2 follows... 0x39 0x34 "94" 0x00 0x00 A key of length 0. THIS MARKS THE END OF THE PACKET.

With AMP it is possible to fire off a request for which no result is generated, or for which you simply don't care what the result will be. You do this by omitting the _ask key. The only request key that is absolutely required by the wire-protocol is _command.

When something goes wrong making an AMP call the response we get back will be quite different than the response we saw above. Instead of the _answer key, there is an _error key instead. For example, the first thing you can do wrong is to make a request for an AMP command which doesn't exist:_ask 1 _command GetSecretFile path /etc/shadow Presumably the other side won't know anything about a GetSecretFile command, so you get this:_error 1 _error_code UNHANDLED _error_description Unhandled Command: 'GetSecretFile' The string "UNHANDLED" is a special code that all compliant AMP implementations use.

Let's imagine a Divide command which takes two integers, numerator and denominator, and returns a floating-point value result (the result of numerator/denominator). Clearly, division can fail if you divide by zero, so we need to define what the _error_code will be in that case. Using the Twisted implementation we would do it something like this:Then, if the responder for the Divide command raises a ZeroDivisionError exception, the response will look something like this:_error 1 _error_code ZERO_DIVISION _error_description float division AMP implementations should then raise this same exception on the client (calling) side. In languages without exceptions the raw error code should be made available so that special handling may be implemented.

So what if something happens that wasn't planned for? AMP doesn't just encode information about arbitrary exceptions because this could represent a potentially harmful information leak. And because it's just better design to make things explicit rather than implicit. Lets say the responder for a given command raises a WorldExplodedException for which you have not defined an _error_code. (What would be the point, after all?) You will get something like this:_error 1 _error_code UNKNOWN _error_description Unknown Error The string "UNKNOWN" is a special code that all compliant AMP implementations use. Well, that's all there is to error handling!

As you've seen, AMP is simple, efficient and flexible. You can build virtually any kind of high-level protocol on top of it. Security features are achieved by layering AMP on top of TLS. A standard set of rich data types are shipped with the reference implementation. Other implementations may or may not provide the full set of types out of the box. However, adding custom data types with your own serialization format is fairly simple. -- Happy AMP'ing!