fixup! Add Vss KVStore api.

Author: G8XSU

rust/api/src/error.rs

@@ -1,25 +1,36 @@
 use std::error::Error;
 use std::fmt::{Display, Formatter};
 use std::io;
-
 /// When there is an error while writing to VSS storage, the response contains a relevant error code.
-/// A mapping from a VSS server error codes. Refer to [`ErrorResponse`] docs for more
+/// A mapping for VSS server error codes. Refer to [`ErrorResponse`] docs for more
 /// information regarding each error code and corresponding use-cases.
+///
+/// [`ErrorResponse`]: crate::types::ErrorResponse
 #[derive(Debug)]
 pub enum VssError {
 	/// Please refer to [`ErrorCode::NoSuchKeyException`].
+	///
+	/// [`ErrorCode::NoSuchKeyException`]: crate::types::ErrorCode::NoSuchKeyException
 	NoSuchKeyError(String),
 
 	/// Please refer to [`ErrorCode::InvalidRequestException`].
+	///
+	/// [`ErrorCode::InvalidRequestException`]: crate::types::ErrorCode::InvalidRequestException
 	InvalidRequestError(String),
 
 	/// Please refer to [`ErrorCode::ConflictException`].
+	///
+	/// [`ErrorCode::ConflictException`]: crate::types::ErrorCode::ConflictException
 	ConflictError(String),
 
 	/// Please refer to [`ErrorCode::AuthException`].
+	///
+	/// [`ErrorCode::AuthException`]: crate::types::ErrorCode::AuthException
 	AuthError(String),
 
 	/// Please refer to [`ErrorCode::InternalServerException`].
+	///
+	/// [`ErrorCode::InternalServerException`]: crate::types::ErrorCode::InternalServerException
 	InternalServerError(String),
 }
 
@@ -30,10 +41,10 @@ impl Display for VssError {
 				write!(f, "Requested key does not exist: {}", message)
 			},
 			VssError::InvalidRequestError(message) => {
-				write!(f, "Request sent to VSS Storage was invalid: {}", message)
+				write!(f, "Request sent to VSS was invalid: {}", message)
 			},
 			VssError::ConflictError(message) => {
-				write!(f, "Potential version conflict in write operation: {}", message)
+				write!(f, "Version conflict in write operation: {}", message)
 			},
 			VssError::AuthError(message) => {
 				write!(f, "Authentication or Authorization failure: {}", message)

rust/api/src/kv_store.rs

@@ -1,34 +1,47 @@
 use crate::error::VssError;
 use crate::types::{
-	DeleteObjectRequest, DeleteObjectResponse, GetObjectRequest, GetObjectResponse, KeyValue,
+	DeleteObjectRequest, DeleteObjectResponse, GetObjectRequest, GetObjectResponse,
 	ListKeyVersionsRequest, ListKeyVersionsResponse, PutObjectRequest, PutObjectResponse,
 };
 use async_trait::async_trait;
+
+#[cfg(test)]
+use crate::types::KeyValue;
 #[cfg(test)]
 use bytes::Bytes;
 #[cfg(test)]
 use rand::distributions::Alphanumeric;
 #[cfg(test)]
 use rand::{thread_rng, Rng};
 
-pub const GLOBAL_VERSION_KEY: &str = "global_version";
-pub const INITIAL_RECORD_VERSION: i32 = 1;
+pub(crate) const GLOBAL_VERSION_KEY: &str = "global_version";
+pub(crate) const INITIAL_RECORD_VERSION: i32 = 1;
+
+/// An interface that must be implemented by every backend implementation of VSS.
 #[async_trait]
 pub trait KvStore: Send + Sync {
+	/// Retrieves an object based on the provided request and user token.
 	async fn get(
 		&self, user_token: String, request: GetObjectRequest,
 	) -> Result<GetObjectResponse, VssError>;
+
+	/// Stores an object with the provided request and user token.
 	async fn put(
 		&self, user_token: String, request: PutObjectRequest,
 	) -> Result<PutObjectResponse, VssError>;
+
+	/// Deletes an object based on the provided request and user token.
 	async fn delete(
 		&self, user_token: String, request: DeleteObjectRequest,
 	) -> Result<DeleteObjectResponse, VssError>;
+
+	/// Lists the versions of keys based on the provided request and user token.
 	async fn list_key_versions(
 		&self, user_token: String, request: ListKeyVersionsRequest,
 	) -> Result<ListKeyVersionsResponse, VssError>;
 }
 
+/// Defines KvStoreTestSuite which is required for an implementation to be VSS protocol compliant.
 #[macro_export]
 macro_rules! define_kv_store_tests {
 	($test_suite_name:ident, $store_type:path, $create_store_expr: expr) => {

rust/api/src/lib.rs

@@ -1,4 +1,21 @@
-pub mod auth;
+//! Hosts API contract for VSS.
+//!
+//! VSS is an open-source project designed to offer a server-side cloud storage solution specifically
+//! tailored for noncustodial Lightning supporting mobile wallets. Its primary objective is to
+//! simplify the development process for Lightning wallets by providing a secure means to store
+//! and manage the essential state required for Lightning Network (LN) operations.
+
+#![deny(rustdoc::broken_intra_doc_links)]
+#![deny(rustdoc::private_intra_doc_links)]
+#![deny(missing_docs)]
+
+/// Implements the error type ([`error::VssError`]) which is eventually converted to [`ErrorResponse`] and returned to client.
+///
+/// [`ErrorResponse`]: crate::types::ErrorResponse
 pub mod error;
+
+/// Contains [`kv_store::KvStore`] interface which needs to be implemented by every backend implementation of VSS.
 pub mod kv_store;
+
+/// Contains request/response types generated from the API definition of VSS.
 pub mod types;