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

document new stuff for external special remotes

Browse source 
Got rid of RENAMEEXPORT-UNSUPPORTED, no reason not to use
RENAMEEXPORT-FAILURE for that.

This commit was supported by the NSF-funded DataLad project.
This commit is contained in:
Joey Hess 2017-09-07 12:58:40 -04:00
parent 6ab14710fc
commit 45d30820ac
No known key found for this signature in database
GPG key ID: DB12DB0FF05F8F38
2 changed files with 54 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

5
doc/design/exporting_trees_to_special_remotes.mdwn
View file

@ -114,9 +114,8 @@ Here's the changes to the latter:
* `RENAMEEXPORT Key NewName` * `RENAMEEXPORT Key NewName`
Requests the remote rename a file stored on it from the previously Requests the remote rename a file stored on it from the previously
provided Name to the NewName. provided Name to the NewName.
The remote responds with `RENAMEEXPORT-SUCCESS`, The remote responds with `RENAMEEXPORT-SUCCESS` or with
`RENAMEEXPORT-FAILURE`, or with `RENAMEEXPORT-UNSUPPORTED` if an efficient `RENAMEEXPORT-FAILURE` if an efficient rename cannot be done.
rename cannot be done.
To support old external special remote programs that have not been updated To support old external special remote programs that have not been updated
to support exports, git-annex will need to handle an `ERROR` response to support exports, git-annex will need to handle an `ERROR` response

54
doc/design/external_special_remote_protocol.mdwn
View file

@ -43,7 +43,8 @@ the version of the protocol it is using.
Once it knows the version, git-annex will generally Once it knows the version, git-annex will generally
send a message telling the special remote to start up. send a message telling the special remote to start up.
(Or it might send a INITREMOTE, so don't hardcode this order.) (Or it might send an INITREMOTE or EXPORTSUPPORTED,
so don't hardcode this order.)
PREPARE PREPARE
@ -102,7 +103,7 @@ The following requests *must* all be supported by the special remote.
So any one-time setup tasks should be done idempotently. So any one-time setup tasks should be done idempotently.
* `PREPARE` * `PREPARE`
Tells the remote that it's time to prepare itself to be used. Tells the remote that it's time to prepare itself to be used.
Only INITREMOTE can come before this. Only INITREMOTE or EXPORTSUPPORTED can come before this.
* `TRANSFER STORE|RETRIEVE Key File` * `TRANSFER STORE|RETRIEVE Key File`
Requests the transfer of a key. For STORE, the File is the file to upload; Requests the transfer of a key. For STORE, the File is the file to upload;
for RETRIEVE the File is where to store the download. for RETRIEVE the File is where to store the download.
@ -143,6 +144,46 @@ replying with `UNSUPPORTED-REQUEST` is acceptable.
network access. network access.
This is not needed when `SETURIPRESENT` is used, since such uris are This is not needed when `SETURIPRESENT` is used, since such uris are
automatically displayed by `git annex whereis`. automatically displayed by `git annex whereis`.
* `EXPORTSUPPORTED`
Used to check if a special remote supports exports. The remote
responds with either `EXPORTSUPPORTED-SUCCESS` or
`EXPORTSUPPORTED-FAILURE`. Note that this request may be made before
or after `PREPARE`.
* `EXPORT Name`
Comes immediately before each of the following export-related requests,
specifying the name of the exported file. It will be in the form
of a relative path, and may contain path separators, whitespace,
and other special characters.
* `TRANSFEREXPORT STORE|RETRIEVE Key File`
Requests the transfer of a File on local disk to or from the previously
provided Name on the special remote.
Note that it's important that, while a file is being stored,
CHECKPRESENTEXPORT not indicate it's present until all the data has
been transferred.
The remote responds with either `TRANSFER-SUCCESS` or
`TRANSFER-FAILURE`, and a remote where exports do not make sense
may always fail.
* `CHECKPRESENTEXPORT Key`
Requests the remote to check if the previously provided Name is present
in it.
The remote responds with `CHECKPRESENT-SUCCESS`, `CHECKPRESENT-FAILURE`,
or `CHECKPRESENT-UNKNOWN`.
* `REMOVEEXPORT Key`
Requests the remote to remove content stored by `TRANSFEREXPORT`
with the previously provided Name.
The remote responds with either `REMOVE-SUCCESS` or
`REMOVE-FAILURE`.
If the content was already not present in the remote, it should
respond with `REMOVE-SUCCESS`.
* `RENAMEEXPORT Key NewName`
Requests the remote rename a file stored on it from the previously
provided Name to the NewName.
The remote responds with `RENAMEEXPORT-SUCCESS` or
`RENAMEEXPORT-FAILURE`.
To support old external special remote programs that have not been updated
to support exports, git-annex will need to handle an `ERROR` response
when using any of the above.
More optional requests may be added, without changing the protocol version, More optional requests may be added, without changing the protocol version,
so if an unknown request is seen, reply with `UNSUPPORTED-REQUEST`. so if an unknown request is seen, reply with `UNSUPPORTED-REQUEST`.
@ -210,6 +251,15 @@ while it's handling a request.
stored in the special remote. stored in the special remote.
* `WHEREIS-FAILURE` * `WHEREIS-FAILURE`
Indicates that no location is known for a key. Indicates that no location is known for a key.
* `EXPORTSUPPORTED-SUCCESS`
Indicates that it makes sense to use this special remote as an export.
* `EXPORTSUPPORTED`
Indicates that it does not make sense to use this special remote as an
export.
* `RENAMEEXPORT-SUCCESS`
Indicates that a `RENAMEEXPORT` was done successfully.
* `RENAMEEXPORT-FAILURE`
Indicates that a `RENAMEEXPORT` failed for whatever reason.
* `UNSUPPORTED-REQUEST` * `UNSUPPORTED-REQUEST`
Indicates that the special remote does not know how to handle a request. Indicates that the special remote does not know how to handle a request.