Added WHEREIS to external special remote protocol.

2 files changed, 41 insertions, 4 deletions

diff --git a/doc/bugs/External_special_remote_SETURLPRESENT_doesn__39__t_seem_to_work/comment_3_6e856db0eb3bb3e7674649857d53cc11._comment b/doc/bugs/External_special_remote_SETURLPRESENT_doesn__39__t_seem_to_work/comment_3_6e856db0eb3bb3e7674649857d53cc11._comment
new file mode 100644
index 000000000..35108ee82
--- /dev/null
+++ b/doc/bugs/External_special_remote_SETURLPRESENT_doesn__39__t_seem_to_work/comment_3_6e856db0eb3bb3e7674649857d53cc11._comment
@@ -0,0 +1,24 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 3"""
+ date="2015-08-13T20:47:28Z"
+ content="""
+Needing enableremote is a trifle annoying, but I don't see a way to avoid
+it and it's symmetric with needing to add a git remote to a repo before
+accessing it. And of course, the user has to install your external special
+remote's implementation too. Which is perhaps more annoying in this use case
+where the file is only being retrieved with a dumb http call in the end.
+
+Instead of the current approach, I could have had special remotes
+use SETURLPRESENT to record the public urls for keys. Then git-annex
+would have something that notices if a special remote is not enabled, but
+supports public urls, and perhaps auto-enables the special remote in
+readonly mode, not using the normal implementation of the special remote,
+but a standin implementation that just uses the public urls. That seems a
+little complicated, especially with the auto-enabling, and it bloats the
+git-annex branch with public urls. IIRC those are the reasons I decided not
+to go that route.
+
+I've added WHEREIS to the protocol. It is only used for `whereis`
+display.
+"""]]
diff --git a/doc/design/external_special_remote_protocol.mdwn b/doc/design/external_special_remote_protocol.mdwn
index d6aa9904a..524271d10 100644
--- a/doc/design/external_special_remote_protocol.mdwn
+++ b/doc/design/external_special_remote_protocol.mdwn
@@ -133,6 +133,15 @@ replying with `UNSUPPORTED-REQUEST` is acceptable.
   Asks the remote to check if the url's content can currently be downloaded
   (without downloading it). The remote replies with one of `CHECKURL-FAILURE`,
   `CHECKURL-CONTENTS`, or `CHECKURL-MULTI`.
+* `WHEREIS Key`
+  Asks the remote to provide any information it can about ways to access
+  the content of a key stored in it, such as eg, public urls.
+  This will be displayed to the user by eg, `git annex whereis`. The remote
+  replies with `WHEREIS-SUCCESS` or `WHEREIS-FAILURE`.  
+  Note that users expect `git annex whereis` to run fast, without eg,
+  network access.  
+  This is not needed when `SETURIPRESENT` is used, since such uris are
+  automatically displayed by `git annex whereis`.  
 
 More optional requests may be added, without changing the protocol version,
 so if an unknown request is seen, reply with `UNSUPPORTED-REQUEST`.
@@ -193,6 +202,12 @@ while it's handling a request.
   can contain spaces.
 * `CHECKURL-FAILURE`  
   Indicates that the requested url could not be accessed.
+* `WHEREIS-SUCCESS String`  
+  Indicates a location of a key. Typically an url, the string can
+  be anything that it makes sense to display to the user about content
+  stored in the special remote.
+* `WHEREIS-FAILURE`  
+  Indicates that no location is known for a key.
 * `UNSUPPORTED-REQUEST`  
   Indicates that the special remote does not know how to handle a request.
 
@@ -281,11 +296,9 @@ in control.
   Records that the key can no longer be downloaded from the specified
   URL.
 * `SETURIPRESENT Key Uri`  
-  Records a special URI where the Key can be downloaded from.  
+  Records an URI where the Key can be downloaded from.  
   For example, "ipfs:ADDRESS" is used for the ipfs special remote;
-  its CLAIMURL handler checks for such URIS and claims them. Setting
-  it present as an URI makes `git annex whereis` display the URI
-  as belonging to the special remote.
+  its CLAIMURL handler checks for such URIS and claims them.
 * `SETURIMISSING Key Uri`  
   Records that the key can no longer be downloaded from the specified
   URI.