From: Joey Hess Date: Tue, 29 Jul 2025 18:24:05 +0000 (-0400) Subject: rename design page X-Git-Tag: archive/raspbian/10.20251029-1+rpi1~1^2~3^2~247 X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=d70a8de5c58e0414f9cd5a7f94b1413854b06dfe;p=git-annex.git rename design page --- diff --git a/doc/design/generic_p2p_transport.mdwn b/doc/design/generic_p2p_transport.mdwn new file mode 100644 index 0000000000..0302607cc7 --- /dev/null +++ b/doc/design/generic_p2p_transport.mdwn @@ -0,0 +1,41 @@ +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::+
` + +To connect to that remote, git-annex runs the command +`git-annex-p2p-`, 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-` 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- 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 `. That also +runs `git-annex-p2p-`, this time with the parameter "address". +That should output the P2P network address 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 networl. + +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. diff --git a/doc/design/p2p_socket_transport.mdwn b/doc/design/p2p_socket_transport.mdwn deleted file mode 100644 index 0302607cc7..0000000000 --- a/doc/design/p2p_socket_transport.mdwn +++ /dev/null @@ -1,41 +0,0 @@ -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::+
` - -To connect to that remote, git-annex runs the command -`git-annex-p2p-`, 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-` 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- 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 `. That also -runs `git-annex-p2p-`, this time with the parameter "address". -That should output the P2P network address 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 networl. - -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. diff --git a/doc/git-annex-p2p.mdwn b/doc/git-annex-p2p.mdwn index 7d96c0dbf8..7d4c6ee80a 100644 --- a/doc/git-annex-p2p.mdwn +++ b/doc/git-annex-p2p.mdwn @@ -17,7 +17,7 @@ network. (This needs Tor to be installed.) git-annex can also support other P2P networks, using a helper program that you can install. These programs have names of the form `git-annex-p2p-`. See - + for documentation about how to create such a program. # OPTIONS diff --git a/doc/git-remote-p2p-annex.mdwn b/doc/git-remote-p2p-annex.mdwn index 175ae3bc29..5021312cae 100644 --- a/doc/git-remote-p2p-annex.mdwn +++ b/doc/git-remote-p2p-annex.mdwn @@ -28,7 +28,7 @@ gitremote-helpers(1) [[git-remote-tor-annex]](1) - + # AUTHOR diff --git a/doc/todo/generic_p2p_socket_transport/comment_12_c106b0a8011cc5f66e35894e9899c2ab._comment b/doc/todo/generic_p2p_socket_transport/comment_12_c106b0a8011cc5f66e35894e9899c2ab._comment index b6b2203482..941ebe62c1 100644 --- a/doc/todo/generic_p2p_socket_transport/comment_12_c106b0a8011cc5f66e35894e9899c2ab._comment +++ b/doc/todo/generic_p2p_socket_transport/comment_12_c106b0a8011cc5f66e35894e9899c2ab._comment @@ -3,7 +3,7 @@ subject="""comment 12""" date="2025-07-29T16:41:07Z" content=""" -I have started a design document at [[design/p2p_socket_transport]], +I have started a design document at [[design/generic_p2p_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.