make some requests optional, simplify and future-proof protocol more

Remote/External.hs

@@ -152,7 +152,8 @@ safely a = go =<< tryAnnex a
 		return False
 
 {- Sends a Request to the external remote, and waits for it to generate
- - a Response that the responsehandler accepts.
+ - a Response. That is fed into the responsehandler, which should return
+ - the action to run for it (or Nothing if there's a protocol error).
  -
  - While the external remote is processing the Request, it may send
  - any number of RemoteRequests, that are handled here.
@@ -291,7 +292,7 @@ getCost external r gc = go =<< remoteCost' gc
 	go Nothing = do
 		c <- handleRequest external GETCOST Nothing $ \req -> case req of
 			COST c -> Just $ return c
-			COST_UNKNOWN -> Just $ return expensiveRemoteCost
+			UNSUPPORTED_REQUEST -> Just $ return expensiveRemoteCost
 			_ -> Nothing
 		setRemoteCost r c
 		return c

Remote/External/Types.hs

@@ -118,10 +118,9 @@ data Response
 	| REMOVE_SUCCESS Key
 	| REMOVE_FAILURE Key ErrorMsg
 	| COST Cost
-	| COST_UNKNOWN
 	| INITREMOTE_SUCCESS
 	| INITREMOTE_FAILURE ErrorMsg
-	| UNKNOWN_REQUEST
+	| UNSUPPORTED_REQUEST
 	deriving (Show)
 
 instance Receivable Response where
@@ -134,10 +133,9 @@ instance Receivable Response where
 	parseCommand "REMOVE-SUCCESS" = parse1 REMOVE_SUCCESS
 	parseCommand "REMOVE-FAILURE" = parse2 REMOVE_FAILURE
 	parseCommand "COST" = parse1 COST
-	parseCommand "COST_UNKNOWN" = parse0 COST_UNKNOWN
 	parseCommand "INITREMOTE-SUCCESS" = parse0 INITREMOTE_SUCCESS
 	parseCommand "INITREMOTE-FAILURE" = parse1 INITREMOTE_FAILURE
-	parseCommand "UNKNOWN-REQUEST" = parse0 UNKNOWN_REQUEST
+	parseCommand "UNSUPPORTED-REQUEST" = parse0 UNSUPPORTED_REQUEST
 	parseCommand _ = parseFail
 
 -- Requests that the external remote can send at any time it's in control.

doc/design/external_special_remote_protocol.mdwn

@@ -75,16 +75,14 @@ The special remote program can then exit.
 
 ## git-annex request messages
 
-These are the request messages git-annex may send to the special remote
+These are messages git-annex sends to the special remote program.
-program. None of these messages require an immediate reply. The special
+None of these messages require an immediate reply. The special
 remote can send any messages it likes while handling the requests.
 
 Once the special remote has finished performing the request, it should
 send one of the corresponding replies listed in the next section.
 
-More requests may be added over time, so if the special remote sees a
+The following requests *must* all be supported by the special remote.
-request it does not understand, it should respond with UNKNOWN-REQUEST
-and continue running.
 
 * `PREPARE`  
   Tells the special remote it's time to prepare itself to be used.
@@ -97,9 +95,6 @@ and continue running.
   Note: This may be run repeatedly, as a remote is initialized in
   different repositories, or as the configuration of a remote is changed.
   So any one-time setup tasks should be done idempotently.
-* `GETCOST`  
-  Requests the remote return a use cost. Higher costs are more expensive.
-  (See Config/Cost.hs for some standard costs.)
 * `TRANSFER STORE|RETRIEVE Key File`  
   Requests the transfer of a key. For Send, the File is the file to upload;
   for Receive the File is where to store the download.  
@@ -113,6 +108,16 @@ and continue running.
 * `REMOVE Key`  
   Requests the remote remove a key's contents.
 
+The following requests can optionally be supported. If not handled,
+replying with `UNSUPPORTED-REQUEST` is acceptable.
+
+* `GETCOST`  
+  Requests the remote return a use cost. Higher costs are more expensive.
+  (See Config/Cost.hs for some standard costs.)
+
+More optional requests may be added, without changing the protocol version,
+so if an unknown request is seen, reply with `UNSUPPORTED-REQUEST`.
+
 ## special remote replies
 
 These should be sent only in response to the git-annex request messages.
@@ -142,13 +147,11 @@ while it's handling a request.
   Indicates that the key was unable to be removed from the remote.
 * `COST Int`  
   Indicates the cost of the remote.
-* `COST-UNKNOWN`  
-  Indicates the remote has no opinion of its cost.
 * `INITREMOTE-SUCCESS`  
   Indicates the INITREMOTE succeeded and the remote is ready to use.
 * `INITREMOTE-FAILURE ErrorMsg`  
   Indicates that INITREMOTE failed.
-* `UNKNOWN-REQUEST`  
+* `UNSUPPORTED-REQUEST`  
   Indicates that the special remote does not know how to handle a request.
 
 ## special remote messages

doc/special_remotes/external/example.sh

@@ -66,9 +66,6 @@ while read line; do
 				echo INITREMOTE-SUCCESS
 			fi
 		;;
-		GETCOST)
-			echo COST-UNKNOWN
-		;;
 		PREPARE)
 			# XXX Use GETCONFIG to get configuration settings,
 			# and do anything needed to get ready for using the
@@ -123,7 +120,10 @@ while read line; do
 			echo REMOVE-SUCCESS "$key"
 		;;
 		*)
-			echo UNKNOWN-REQUEST
+			# The requests listed above are all the ones
+			# that are required to be supported, so it's fine
+			# to say that any other request is unsupported.
+			echo UNSUPPORTED-REQUEST
 		;;
 	esac	
 done