Assert the VSS protocol version matches

We assert that the VSS protocol version matches on all responses
returned from the server, including errors.

Author: tankyleo

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vss-client-ng"
-version = "0.5.0"
+version = "0.6.0"
 authors = ["Leo Nash <hello@leonash.net>", "Elias Rohrer <dev@tnull.de>"]
 rust-version = "1.75.0"
 license = "MIT OR Apache-2.0"

src/client.rs

@@ -20,6 +20,8 @@ const CONTENT_TYPE: &str = "content-type";
 const DEFAULT_TIMEOUT_SECS: u64 = 10;
 const MAX_RESPONSE_BODY_SIZE: usize = 1024 * 1024 * 1024; // 1GB
 const DEFAULT_CLIENT_CAPACITY: usize = 10;
+const PROTOCOL_VERSION_HEADER: &str = "vss-protocol-version";
+const PROTOCOL_VERSION: &str = "0";
 
 /// Thin-client to access a hosted instance of Versioned Storage Service (VSS).
 /// The provided [`VssClient`] API is minimalistic and is congruent to the VSS server-side API.
@@ -212,6 +214,16 @@ impl<R: RetryPolicy<E = VssError>> VssClient<R> {
 		}
 
 		let response = self.client.send_async(http_request).await?;
+		// Return early in case of version mismatch, this issue must be solved first.
+		if response.headers.get(PROTOCOL_VERSION_HEADER).map(String::as_str)
+			!= Some(PROTOCOL_VERSION)
+		{
+			let mut response = response;
+			return Err(VssError::VSSVersionMismatchError {
+				version_served: response.headers.remove(PROTOCOL_VERSION_HEADER),
+				version_expected: String::from(PROTOCOL_VERSION),
+			});
+		}
 
 		let status_code = response.status_code;
 		let payload = response.into_bytes();

src/error.rs

@@ -26,6 +26,14 @@ pub enum VssError {
 	/// There is an unknown error, it could be a client-side bug, unrecognized error-code, network error
 	/// or something else.
 	InternalError(String),
+
+	/// The VSS server and client speak different versions of the VSS protocol
+	VSSVersionMismatchError {
+		/// The VSS protocol version served
+		version_served: Option<String>,
+		/// The VSS protocol version expected
+		version_expected: String,
+	},
 }
 
 impl VssError {
@@ -62,6 +70,21 @@ impl Display for VssError {
 			VssError::InternalServerError(message) => {
 				write!(f, "InternalServerError: {}", message)
 			},
+			VssError::VSSVersionMismatchError {
+				version_served: Some(served),
+				version_expected,
+			} => {
+				write!(
+					f,
+					"The VSS server and client speak different versions of the \
+					VSS protocol, the server serves version {}, client expects \
+					{}",
+					served, version_expected,
+				)
+			},
+			VssError::VSSVersionMismatchError { version_served: None, version_expected: _ } => {
+				write!(f, "The server did not set the `vss-protocol-version` header")
+			},
 			VssError::InternalError(message) => {
 				write!(f, "InternalError: {}", message)
 			},

tests/tests.rs

@@ -21,6 +21,8 @@ mod tests {
 
 	const APPLICATION_OCTET_STREAM: &str = "application/octet-stream";
 	const CONTENT_TYPE: &str = "content-type";
+	const PROTOCOL_VERSION_HEADER: &str = "vss-protocol-version";
+	const PROTOCOL_VERSION: &str = "0";
 
 	const GET_OBJECT_ENDPOINT: &'static str = "/getObject";
 	const PUT_OBJECT_ENDPOINT: &'static str = "/putObjects";
@@ -44,6 +46,7 @@ mod tests {
 			.match_header(CONTENT_TYPE, APPLICATION_OCTET_STREAM)
 			.match_body(get_request.encode_to_vec())
 			.with_status(200)
+			.with_header(PROTOCOL_VERSION_HEADER, PROTOCOL_VERSION)
 			.with_body(mock_response.encode_to_vec())
 			.create();
 
@@ -77,6 +80,7 @@ mod tests {
 			.match_header("headerkey", "headervalue")
 			.match_body(get_request.encode_to_vec())
 			.with_status(200)
+			.with_header(PROTOCOL_VERSION_HEADER, PROTOCOL_VERSION)
 			.with_body(mock_response.encode_to_vec())
 			.create();
 
@@ -119,6 +123,7 @@ mod tests {
 			.match_header(CONTENT_TYPE, APPLICATION_OCTET_STREAM)
 			.match_body(request.encode_to_vec())
 			.with_status(200)
+			.with_header(PROTOCOL_VERSION_HEADER, PROTOCOL_VERSION)
 			.with_body(mock_response.encode_to_vec())
 			.create();
 
@@ -154,6 +159,7 @@ mod tests {
 			.match_header(CONTENT_TYPE, APPLICATION_OCTET_STREAM)
 			.match_body(request.encode_to_vec())
 			.with_status(200)
+			.with_header(PROTOCOL_VERSION_HEADER, PROTOCOL_VERSION)
 			.with_body(mock_response.encode_to_vec())
 			.create();
 
@@ -195,6 +201,7 @@ mod tests {
 			.match_header(CONTENT_TYPE, APPLICATION_OCTET_STREAM)
 			.match_body(request.encode_to_vec())
 			.with_status(200)
+			.with_header(PROTOCOL_VERSION_HEADER, PROTOCOL_VERSION)
 			.with_body(mock_response.encode_to_vec())
 			.create();
 
@@ -222,6 +229,7 @@ mod tests {
 		};
 		let mock_server = mockito::mock("POST", GET_OBJECT_ENDPOINT)
 			.with_status(404)
+			.with_header(PROTOCOL_VERSION_HEADER, PROTOCOL_VERSION)
 			.with_body(&error_response.encode_to_vec())
 			.create();
 
@@ -246,6 +254,7 @@ mod tests {
 		let mock_response = GetObjectResponse { value: None, ..Default::default() };
 		let mock_server = mockito::mock("POST", GET_OBJECT_ENDPOINT)
 			.with_status(200)
+			.with_header(PROTOCOL_VERSION_HEADER, PROTOCOL_VERSION)
 			.with_body(&mock_response.encode_to_vec())
 			.create();
 
@@ -270,6 +279,7 @@ mod tests {
 		};
 		let mock_server = mockito::mock("POST", Matcher::Any)
 			.with_status(400)
+			.with_header(PROTOCOL_VERSION_HEADER, PROTOCOL_VERSION)
 			.with_body(&error_response.encode_to_vec())
 			.create();
 
@@ -330,6 +340,7 @@ mod tests {
 		};
 		let mock_server = mockito::mock("POST", Matcher::Any)
 			.with_status(401)
+			.with_header(PROTOCOL_VERSION_HEADER, PROTOCOL_VERSION)
 			.with_body(&error_response.encode_to_vec())
 			.create();
 
@@ -412,6 +423,7 @@ mod tests {
 		};
 		let mock_server = mockito::mock("POST", Matcher::Any)
 			.with_status(409)
+			.with_header(PROTOCOL_VERSION_HEADER, PROTOCOL_VERSION)
 			.with_body(&error_response.encode_to_vec())
 			.create();
 
@@ -445,6 +457,7 @@ mod tests {
 		};
 		let mock_server = mockito::mock("POST", Matcher::Any)
 			.with_status(500)
+			.with_header(PROTOCOL_VERSION_HEADER, PROTOCOL_VERSION)
 			.with_body(&error_response.encode_to_vec())
 			.create();
 
@@ -502,6 +515,7 @@ mod tests {
 			ErrorResponse { error_code: 999, message: "UnknownException".to_string() };
 		let mut _mock_server = mockito::mock("POST", Matcher::Any)
 			.with_status(999)
+			.with_header(PROTOCOL_VERSION_HEADER, PROTOCOL_VERSION)
 			.with_body(&error_response.encode_to_vec())
 			.create();
 
@@ -534,6 +548,7 @@ mod tests {
 		let malformed_error_response = b"malformed";
 		_mock_server = mockito::mock("POST", Matcher::Any)
 			.with_status(409)
+			.with_header(PROTOCOL_VERSION_HEADER, PROTOCOL_VERSION)
 			.with_body(&malformed_error_response)
 			.create();
 
@@ -546,17 +561,36 @@ mod tests {
 		let list_malformed_err_response = vss_client.list_key_versions(&list_request).await;
 		assert!(matches!(list_malformed_err_response.unwrap_err(), VssError::InternalError { .. }));
 
-		// Requests to endpoints are no longer mocked and will result in network error.
+		// Requests to endpoints are no longer mocked and will result in version mismatch
+		// errors.
 		drop(_mock_server);
 
-		let get_network_err = vss_client.get_object(&get_request).await;
-		assert!(matches!(get_network_err.unwrap_err(), VssError::InternalError { .. }));
-
-		let put_network_err = vss_client.put_object(&put_request).await;
-		assert!(matches!(put_network_err.unwrap_err(), VssError::InternalError { .. }));
-
-		let list_network_err = vss_client.list_key_versions(&list_request).await;
-		assert!(matches!(list_network_err.unwrap_err(), VssError::InternalError { .. }));
+		let get_version_err = vss_client.get_object(&get_request).await;
+		assert!(matches!(
+			get_version_err.unwrap_err(),
+			VssError::VSSVersionMismatchError {
+				version_served: None,
+				version_expected: version
+			} if version == PROTOCOL_VERSION
+		));
+
+		let put_version_err = vss_client.put_object(&put_request).await;
+		assert!(matches!(
+			put_version_err.unwrap_err(),
+			VssError::VSSVersionMismatchError {
+				version_served: None,
+				version_expected: version
+			} if version == PROTOCOL_VERSION
+		));
+
+		let list_version_err = vss_client.list_key_versions(&list_request).await;
+		assert!(matches!(
+			list_version_err.unwrap_err(),
+			VssError::VSSVersionMismatchError {
+				version_served: None,
+				version_expected: version
+			} if version == PROTOCOL_VERSION
+		));
 	}
 
 	fn retry_policy() -> impl RetryPolicy<E = VssError> {