changed design for p2p generic socket

Having the git-annex-p2p-<netname> command output the socket filename
left git-annex scrambling to listen to it in order to not miss incoming
connections. And if the command uses something like socat UNIX-CONNECT,
that expects the socket to be accepting connections and errors out when
it's not, that would be a problem.

Rather than complicating the protocol with git-annex needing to send
back a message when it's listening to the socket, simplified it by
having git-annex provide the socket path to the command.

This does mean that, if a P2P network has its own place it expects to
find a socket file, the git-annex-p2p-<netname> command would need to
somehow arrange for it to use the git-annex socket path. A symlink would
be one way to handle that situation.

diff --git a/doc/design/generic_p2p_transport.mdwn b/doc/design/generic_p2p_transport.mdwn
index 094cfc0bc0361953788e171f2c9af3d9657d9800..18e966bff84c53aee26e6ff59d8e62f576d3bc68 100644 (file)
--- a/doc/design/generic_p2p_transport.mdwn
+++ b/doc/design/generic_p2p_transport.mdwn
@@ -1,4 +1,6 @@
 This is a generic interface that allows git-annex to use a P2P network.
+The [[P2P_protocol]] is used, to allow accessing a peer's git-annex
+repository as a git remote.
 
 Examples of such networks are tor, yggstack or fowl. (git-annex has a
 built-in integration with tor which does not use this interface.)
@@ -17,19 +19,6 @@ the peer, and data received from the peer should be output to stdout. If it
 is unable to connect, the command can exit nonzero. When the peer closes
 connection, the command can exit zero.
 
-To handle incoming connections from peers, `git-annex remotedaemon`
-runs `git-annex-p2p-<netname>` with the parameter "socket", followed 
-by the P2P address of the local repository. The command
-should output a single line, the path of a unix socket file. 
-(Any subsequent output is ignored.)
-When it does, `git-annex remotedaemon` will use that socket file to listen for connections from
-peers, and service them. (The [[P2P_protocol]] is spoken over these
-connections.)
-
-Note that, if the P2P network does not natively use a unix socket file,
-a command like `socat` can be run by `git-annex-p2p-<netname> socket` 
-to convert the P2P network's own equivilant into a unix socket file.
-
 To configure `git-annex remotedaemon` to listen on a given P2P network,
 the user runs `git-annex p2p --enable <netname>`. That also
 runs `git-annex-p2p-<netname>`, this time with the parameter "address".
@@ -37,6 +26,17 @@ That should output one or more lines, the P2P network address (or addresses)
 that can be used by peers to connect to the repository. It can first do
 whatever it needs to do to set up the P2P network.
 
+To handle incoming connections from peers, `git-annex remotedaemon` runs
+`git-annex-p2p-<netname>`, with two parameters. The first parameter is the
+P2P address of the local repository, obtained earlier as described above.
+The second parameter is the path to a unix socket file, which git-annex
+will have already created. git-annex listens for connections from peers
+that are made to the socket, and services them.
+
+Note that, if the P2P network does not natively use a unix socket file,
+a command like `socat` can be run by `git-annex-p2p-<netname> socket` 
+to convert the P2P network's own equivilant into a unix socket file.
+
 The program [[git-remote-p2p-annex]] is included in git-annex as a git
 remote helper program. git will use that program to handle `pull` and
 `push` with git remotes that use the `p2p-annex::` url scheme.