[MERGE][RFC] Add doc/developers/network-protocol.txt to describe the HPSS protocol; streaming body extension to HPSS protocol.

[Martin Pool]

Martin Pool has voted resubmit.
Status is now: Resubmit
Comment:
+
+:Date: 2007-09-03
+

(comment) I do wonder if anyone will update this, or whether having an 
overall last-modified-date is very useful compared to saying what 
version of Bazaar uses each protocol version.

+ CLIENT   domain logic, accepts domain requests, generated structured
+          data, reads structured data from responses and turns into
+          domain data.  Sends structured data to the protocol.
+          Operates state machines until the request can be delivered
+          (e.g. reading from a bundle generated in bzrlib to deliver a
+          complete request).
+
+          Possibly this should just be RemoteBzrDir, RemoteTransport,
+          ...

Is this in fact now just RemoteBzrDir etc?

Would it be good to show "rest of bzrlib" sitting under the HANDLER and
above the CLIENT respectively?

+  RESPONSE_V2 := "bzr request 2" NEWLINE MESSAGE_V2

really?


+Software versions
+-----------------
+
+Version 1 of the protocol was introduced in Bazaar 0.11.
+
+Version 2 was introduced in Bazaar 0.16.
+

You might put these in the corresponding headings rather than down here.
If I understand correctly, Bazaar 0.90 sends the version identifier but
can't handle the chunked encoding?  That should be documented.

  In other words they'll want to rewrite
+incoming paths to be under that level (and prevent escaping using ../
+tricks.)

Should we say something about ChrootTransport etc?

+URLs that include ~ should probably be passed across to the server
+verbatim and the server can expand them.  This will proably not be
+meaningful when limited to a directory?

You could link the bug for this.

+Requests
+========
+
+The available request methods are registered in `bzrlib.smart.request`.

I'd like if we could document the rpcs in this file, or one linked from 
here, as they're important compatibility points.  For now could you at 
least invite people to document them below?

Aside from that, thanks, very good.



For details, see: 
http://bundlebuggy.aaronbentley.com/request/%3C20070903052237.GA25629%40steerpike.home.puzzling.org%3E