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

simplify

Browse source
This commit is contained in:
Joey Hess 2013-12-16 11:36:19 -04:00
parent 641159ff6a
commit 81d051cad5
1 changed files with 30 additions and 30 deletions
Download patch file Download diff file Expand all files Collapse all files

60
doc/design/external_special_remote_protocol.mdwn
View file

@ -22,6 +22,10 @@ progress to stdout. (Such stuff can be sent to stderr instead.)
The protocol is line based. Messages are sent in either direction, from The protocol is line based. Messages are sent in either direction, from
git-annex to the special remote, and from the special remote to git-annex. git-annex to the special remote, and from the special remote to git-annex.
In order to avoid confusing interactions, one or the other has control
at any given time, and is responsible for sending requests, while the other
only sends replies to the requests.
## example session ## example session
The special remote is responsible for sending the first message, indicating The special remote is responsible for sending the first message, indicating
@ -104,10 +108,9 @@ send one of the corresponding replies listed in the next section.
## special remote replies ## special remote replies
These should be sent only in response to the git-annex request messages. These should be sent only in response to the git-annex request messages.
(Any sent unexpectedly will be ignored.)
They do not have to be sent immediately after the request; the special They do not have to be sent immediately after the request; the special
remote can send other messages and queries (listed in sections below) remote can send its own requests (listed in the next section below)
as it's performing the request. while it's handling a request.
* `PREPARE-SUCCESS` * `PREPARE-SUCCESS`
Sent as a response to PREPARE once the special remote is ready for use. Sent as a response to PREPARE once the special remote is ready for use.
@ -143,53 +146,50 @@ as it's performing the request.
## special remote messages ## special remote messages
These are messages the special remote program can send to These messages may be sent by the special remote at any time that it's
git-annex at any time. It should not expect any response from git-annex. in control.
* `VERSION Int` * `VERSION Int`
Supported protocol version. Current version is 0. Must be sent first Supported protocol version. Current version is 0. Must be sent first
thing at startup, as until it sees this git-annex does not know how to thing at startup, as until it sees this git-annex does not know how to
talk with the special remote program! talk with the special remote program!
* `ERROR ErrorMsg`
Generic error. Can be sent at any time if things get messed up.
When possible, use a more specific reply from the list above.
It would be a good idea to send this if git-annex sends a command
you do not support. The program should exit after sending this, as
git-annex will not talk to it any further.
* `PROGRESS STORE|RETRIEVE Key Int` * `PROGRESS STORE|RETRIEVE Key Int`
Indicates the current progress of the transfer. May be repeated any Indicates the current progress of the transfer. May be repeated any
number of times during the transfer process. This is highly recommended number of times during the transfer process. This is highly recommended
for STORE. (It is optional but good for RETRIEVE.) for STORE. (It is optional but good for RETRIEVE.)
(git-annex does not send a reply to this message.)
## special remote queries
After git-annex has sent the special remote a request, and before the
special remote sends back a reply, git-annex enters quiet mode. It will
avoid sending additional messages. While git-annex is in quiet mode,
the special remote can send queries to it. Queries can not be sent at any
other time.
* `DIRHASH Key` * `DIRHASH Key`
Gets a two level hash associated with a Key. Something like "abc/def". Gets a two level hash associated with a Key. Something like "abc/def".
This is always the same for any given Key, so can be used for eg, This is always the same for any given Key, so can be used for eg,
creating hash directory structures to store Keys in. creating hash directory structures to store Keys in.
(git-annex replies with VALUE followed by the value.)
* `GETCONFIG Setting` * `GETCONFIG Setting`
Gets one of the special remote's configuration settings. Gets one of the special remote's configuration settings.
(git-annex replies with VALUE followed by the value.)
* `SETSTATE Key Value` * `SETSTATE Key Value`
git-annex can store state in the git-annex branch on a git-annex can store state in the git-annex branch on a
per-special-remote, per-key basis. This sets that state. per-special-remote, per-key basis. This sets that state.
(git-annex replies with VALUE followed by the value stored.)
* `GETSTATE Key` * `GETSTATE Key`
Gets any state previously stored for the key from the git-annex branch. Gets any state previously stored for the key from the git-annex branch.
Note that some special remotes may be accessed from multiple Note that some special remotes may be accessed from multiple
repositories, and the state is only eventually consistently synced repositories, and the state is only eventually consistently synced
between them. If two repositories set different values in the state between them. If two repositories set different values in the state
for a key, the one that sets it last wins. for a key, the one that sets it last wins.
(git-annex replies with VALUE followed by the value.)
When it sees a query, git-annex will respond a VALUE message. ## general messages
The rest of the line contains the requested data.
git-annex may also respond with an ERROR message if it did not These messages can be sent at any time by either git-annex or the special
understand the query. In this case, it will continue processing remote.
further messages.
* `ERROR ErrorMsg`
Generic error. Can be sent at any time if things get messed up.
When possible, use a more specific reply from the list above.
It would be a good idea to send this if git-annex sends a command
you do not support. The program should exit after sending this, as
git-annex will not talk to it any further. If the program receives
an ERROR, it can try to recover, or exit with its own ERROR.
## Simple shell example ## Simple shell example