summaryrefslogtreecommitdiff
path: root/doc/design/external_special_remote_protocol.mdwn
diff options
context:
space:
mode:
authorGravatar Joey Hess <joey@kitenet.net>2013-12-26 18:14:52 -0400
committerGravatar Joey Hess <joey@kitenet.net>2013-12-26 18:15:18 -0400
commit310c39a6ad6027d37f6f0da437960566f5fd499a (patch)
tree4f25e7227792bbb57767889156c9799d56dc1362 /doc/design/external_special_remote_protocol.mdwn
parent3bd2cadd24615cc6b3208ec1ee71bbbc6ab9a55c (diff)
external special remote documentation and example script
Diffstat (limited to 'doc/design/external_special_remote_protocol.mdwn')
-rw-r--r--doc/design/external_special_remote_protocol.mdwn77
1 files changed, 9 insertions, 68 deletions
diff --git a/doc/design/external_special_remote_protocol.mdwn b/doc/design/external_special_remote_protocol.mdwn
index 8c5c245b0..7dc8182fa 100644
--- a/doc/design/external_special_remote_protocol.mdwn
+++ b/doc/design/external_special_remote_protocol.mdwn
@@ -1,10 +1,13 @@
-See [[todo/support_for_writing_external_special_remotes]] for motivation.
+Communication between git-annex and a program implementing an external
+special remote uses this protocol.
-This is a design for a protocol to be used to communicate between git-annex
-and a program implementing an external special remote.
+[[!toc]]
+
+## starting the program
The external special remote program has a name like
-`git-annex-remote-$bar`. When `git annex initremote foo type=$bar` is run,
+`git-annex-remote-$bar`. When
+`git annex initremote foo type=external externaltype=$bar` is run,
git-annex finds the appropriate program in PATH.
The program is started by git-annex when it needs to access the special
@@ -31,7 +34,7 @@ only sends replies to the requests.
The special remote is responsible for sending the first message, indicating
the version of the protocol it is using.
- VERSION 0
+ VERSION 1
Once it knows the version, git-annex will send a message telling the
special remote to start up.
@@ -154,7 +157,7 @@ These messages may be sent by the special remote at any time that it's
in control.
* `VERSION Int`
- Supported protocol version. Current version is 0. Must be sent first
+ Supported protocol version. Current version is 1. Must be sent first
thing at startup, as until it sees this git-annex does not know how to
talk with the special remote program!
* `PROGRESS Int`
@@ -200,68 +203,6 @@ remote.
git-annex will not talk to it any further. If the program receives
an ERROR from git-annex, it can exit with its own ERROR.
-## Simple shell example
-
-[[!format sh """
-#!/bin/sh
-set -e
-
-echo VERSION 0
-
-while read line; do
- set -- $line
- case "$1" in
- INITREMOTE)
- # XXX do anything necessary to create resources
- # used by the remote. Try to be idempotent.
- # Use GETCONFIG to get any needed configuration
- # settings, and SETCONFIG to set any persistent
- # configuration settings.
- echo INITREMOTE-SUCCESS
- ;;
- GETCOST)
- echo COST-UNKNOWN
- ;;
- PREPARE)
- # XXX Use GETCONFIG to get configuration settings,
- # and do anything needed to start using the
- # special remote here.
- echo PREPARE-SUCCESS
- ;;
- TRANSFER)
- key="$3"
- file="$4"
- case "$2" in
- STORE)
- # XXX upload file here
- # XXX when possible, send PROGRESS
- echo TRANSFER-SUCCESS STORE "$key"
- ;;
- RETRIEVE)
- # XXX download file here
- echo TRANSFER-SUCCESS RETRIEVE "$key"
- ;;
-
- esac
- ;;
- CHECKPRESENT)
- key="$2"
- echo CHECKPRESENT-UNKNOWN "$key" "not implemented"
- ;;
- REMOVE)
- key="$2"
- # XXX remove key here
- echo REMOVE-SUCCESS "$key"
- ;;
- *)
- echo UNKNOWN-REQUEST
- ;;
- esac
-done
-
-# XXX anything that needs to be done at shutdown can be done here
-"""]]
-
## TODO
* Communicate when the network connection may have changed, so long-running