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.)
Such a P2P network has some form of address, which can be used to connect to a given peer by address across the network.
A git remote using the P2P network has an url of the form
p2p-annex::<netname>:<address>
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.
program interface
To connect to a P2P remote, git-annex runs the command
git-annex-p2p-<netname>, giving it the P2P network address as its only
parameter. The command is responsible for connecting to that peer, and
relaying data to it. Data fed into the command on stdin should be sent to
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 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".
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.
example
Here's a simple shell script example. While this avoids using any real P2P network and dummys it up by symlinking unix socket files together, its skeleton should be a good starting point.
security
This is only as secure as the underlying P2P network. It is really designed with P2P networks in mind that are fully encrypted, and that use cryptography to validate the identities of peers.
See the security discussion on p2p.