--- AnyEvent-MP/MP/Transport.pm	2009/08/03 22:05:55	1.13
+++ AnyEvent-MP/MP/Transport.pm	2009/08/04 18:33:30	1.18
@@ -282,6 +282,7 @@
    my ($self, $msg) = @_;
 
    if ($self->{node} && $self->{node}{transport} == $self) {
+      $self->{node}->fail (transport_error => $msg);
       $self->{node}->clr_transport;
    }
    $AnyEvent::MP::Base::WARN->("$self->{peerhost}:$self->{peerport}: $msg");
@@ -328,18 +329,26 @@
 
 =head2 GREETING
 
+All the lines until after authentication must not exceed 4kb in length,
+including delimiter. Afterwards there is no limit on the packet size that
+can be received.
+
+=head3 First Greeting Line
+
+Example:
+
+   aemp;0;fec.4a7720fc;127.0.0.1:1235,[::1]:1235;hmac_md6_64_256;json,storable;provider=AE-0.0
+
 The first line contains strings separated (not ended) by C<;>
 characters. The first even ixtrings are fixed by the protocol, the
 remaining strings are C<KEY=VALUE> pairs. None of them may contain C<;>
 characters themselves.
 
-All the lines until after authentication must not exceed 4kb in length, including delimiter.
-
 The fixed strings are:
 
 =over 4
 
-=item C<aemp>
+=item protocol identification
 
 The constant C<aemp> to identify the protocol.
 
@@ -347,7 +356,7 @@
 
 The protocol version supported by this end, currently C<0>. If the
 versions don't match then no communication is possible. Minor extensions
-are supposed to be handled by addign additional key-value pairs.
+are supposed to be handled through additional key-value pairs.
 
 =item a token uniquely identifying the current node instance
 
@@ -399,21 +408,25 @@
 
 =back
 
+=head3 Second Greeting Line
+
 After this greeting line there will be a second line containing a
 cryptographic nonce, i.e. random data of high quality. To keep the
 protocol text-only, these are usually 32 base64-encoded octets, but
 it could be anything that doesn't contain any ASCII CR or ASCII LF
 characters.
 
-Example of the two lines of greeting:
+I<< The two nonces B<must> be different, and an aemp implementation
+B<must> check and fail when they are identical >>.
+
+Example of a nonce line:
 
-   aemp;0;fec.4a7720fc;127.0.0.1:1235,[::1]:1235;hmac_md6_64_256;json,storable;provider=AE-0.0
    p/I122ql7kJR8lumW3lXlXCeBnyDAvz8NQo3x5IFowE4
 
 =head2 TLS handshake
 
-If, after the handshake, both sides indicate interest in TLS, then the
-connection I<must> use TLS, or fail.
+I<< If, after the handshake, both sides indicate interest in TLS, then the
+connection B<must> use TLS, or fail.>>
 
 Both sides compare their nonces, and the side who sent the lower nonce
 value ("string" comparison on the raw octet values) becomes the client,
@@ -482,7 +495,7 @@
 
 =back
 
-Example:
+Example of an authentication reply:
 
    hmac_md6_64_256;363d5175df38bd9eaddd3f6ca18aa1c0c4aa22f0da245ac638d048398c26b8d3;json
 
@@ -491,6 +504,20 @@
 After this, packets get exchanged using the chosen framing protocol. It is
 quite possible that both sides use a different framing protocol.
 
+=head2 FULL EXAMPLE
+
+This is an actual protocol dump of a handshake, followed by a single data
+packet. The greater than/less than lines indicate the direction of the
+transfer only.
+
+   > aemp;0;nndKd+gn;10.0.0.1:4040;hmac_md6_64_256,cleartext;json,storable;provider=AE-0.0;peeraddr=127.0.0.1:1235
+   > sRG8bbc4TDbkpvH8FTP4HBs87OhepH6VuApoZqXXskuG
+   < aemp;0;nmpKd+gh;127.0.0.1:1235,[::1]:1235;hmac_md6_64_256,cleartext;json,storable;provider=AE-0.0;peeraddr=127.0.0.1:58760
+   < dCEUcL/LJVSTJcx8byEsOzrwhzJYOq+L3YcopA5T6EAo
+   > hmac_md6_64_256;9513d4b258975accfcb2ab7532b83690e9c119a502c612203332a591c7237788;json
+   < hmac_md6_64_256;0298d6ba2240faabb2b2e881cf86b97d70a113ca74a87dc006f9f1e9d3010f90;json
+   > ["","lookup","pinger","10.0.0.1:4040#nndKd+gn.a","resolved"]
+
 =head1 SEE ALSO
 
 L<AnyEvent>.