mirrors/git-annex
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

design for p2p socket transport

Browse source
This commit is contained in:
Joey Hess 2025-07-29 14:00:21 -04:00
commit 05c016084d
No known key found for this signature in database
GPG key ID: DB12DB0FF05F8F38
2 changed files with 62 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

40
doc/design/p2p_socket_transport.mdwn Normal file
View file

@ -0,0 +1,40 @@
This is a generic interface that allows git-annex to use a P2P network.
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>`
To connect to that 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 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 the path of a unix socket file. 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".
That should output the P2P network address that can be used by peers
to connect to the repository.
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.

22
doc/todo/generic_p2p_socket_transport/comment_12_c106b0a8011cc5f66e35894e9899c2ab._comment Normal file
View file

@ -0,0 +1,22 @@
[[!comment format=mdwn
username="joey"
subject="""comment 12"""
date="2025-07-29T16:41:07Z"
content="""
I have started a design document at [[design/p2p_socket_transport]],
to collect all the scattered decisions here into a coherent document that
can be used by someone implementing support for one of these networks.
In the process, I realized that rather than defining a path where git-annex
expects the socket file to be, it could run the same `git-annex-p2p-foo`
command in a mode where the command outputs the path to the socket file.
That also lets the command run socat to connect up the socket, for example.
I also put in there that `git-annex p2p --enable <netname>` will run
`git-annex-p2p-<netname> address`, which will output the P2P address that
peers will use to connect the the repository. That seemed nicer than
requiring the user to somehow come up with the P2P address on their own.
I have started writing the user-level documentation too, on the
`genericp2p` branch.
"""]]