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

add LISTCONFIGS to external special remote protocol

Browse source 
Special remote programs that use GETCONFIG/SETCONFIG are recommended
to implement it.

The description is not yet used, but will be useful later when adding a way
to make initremote list all accepted configs.

configParser now takes a RemoteConfig parameter. Normally, that's not
needed, because configParser returns a parter, it does not parse it
itself. But, it's needed to look at externaltype and work out what
external remote program to run for LISTCONFIGS.

Note that, while externalUUID is changed to a Maybe UUID, checkExportSupported
used to use NoUUID. The code that now checks for Nothing used to behave
in some undefined way if the external program made requests that
triggered it.

Also, note that in externalSetup, once it generates external,
it parses the RemoteConfig strictly. That generates a
ParsedRemoteConfig, which is thrown away. The reason it's ok to throw
that away, is that, if the strict parse succeeded, the result must be
the same as the earlier, lenient parse.

initremote of an external special remote now runs the program three
times. First for LISTCONFIGS, then EXPORTSUPPORTED, and again
LISTCONFIGS+INITREMOTE. It would not be hard to eliminate at least
one of those, and it should be possible to only run the program once.
This commit is contained in:
Joey Hess 2020-01-17 15:30:14 -04:00
parent 1ce722d86f
commit 99cb3e75f1
No known key found for this signature in database
GPG key ID: DB12DB0FF05F8F38
20 changed files with 158 additions and 76 deletions
Download patch file Download diff file Expand all files Collapse all files

26
doc/design/external_special_remote_protocol.mdwn
View file

@ -54,8 +54,9 @@ could have its own protocol extension details, but none are currently used.
EXTENSIONS
Next, git-annex will generally send a message telling the special
remote to start up. (Or it might send an INITREMOTE or EXPORTSUPPORTED,
or perhaps other things in the future, so don't hardcode this order.)
remote to start up. (Or it might send an INITREMOTE or EXPORTSUPPORTED or
LISTCONFIGS, or perhaps other things in the future, so don't hardcode this
order.)
PREPARE
@ -116,9 +117,9 @@ The following requests *must* all be supported by the special remote.
Indicates that INITREMOTE failed.
* `PREPARE`
Tells the remote that it's time to prepare itself to be used.
Only a few requests for details about the remote can come before this.
Those include EXTENSIONS, INITREMOTE, and EXPORTSUPPORTED, but others
may be added later.
Only a few requests for details about the remote can come before this
(EXTENSIONS, INITREMOTE, EXPORTSUPPORTED, and LISTCONFIGS,
but others may be added later).
* `PREPARE-SUCCESS`
Sent as a response to PREPARE once the special remote is ready for use.
* `PREPARE-FAILURE ErrorMsg`
@ -173,6 +174,19 @@ the special remote can reply with `UNSUPPORTED-REQUEST`.
Sent in response to a EXTENSIONS request, the List could be used to indicate
protocol extensions that the special remote uses, but there are currently
no such extensions.
* `LISTCONFIGS`
Requests the remote to return a list of settings it uses (with
`GETCONFIG` and `SETCONFIG`). Providing a list makes `git annex initremote`
work better, because it can check the user's input, and can also display
a list of settings with descriptions. Note that the user is not required
to provided all the settings listed here. A block of responses
can be made to this, which must always end with `CONFIGSEND`.
* `CONFIG Name Description`
Indicates the name and description of a config setting. The description
should be reasonably short. Example:
"CONFIG directory store data here"
* `CONFIGEND`
Indicates the end of the response block.
* `GETCOST`
Requests the remote to return a use cost. Higher costs are more expensive.
(See Config/Cost.hs for some standard costs.)
@ -283,6 +297,8 @@ handling a request.
Gets one of the special remote's configuration settings, which can have
been passed by the user when running `git annex initremote`, or
can have been set by a previous SETCONFIG. Can be run at any time.
It's recommended that special remotes that use this implement
LISTCONFIGS.
(git-annex replies with VALUE followed by the value. If the setting is
not set, the value will be empty.)
* `SETCREDS Setting User Password`