nits:docs

Author: G8XSU

app/src/main/proto/vss.proto

@@ -2,16 +2,16 @@ syntax = "proto3";
 option java_multiple_files = true;
 package org.vss;
 
-/*
-  StoreId: All APIs operate within a single storeId.
-  StoreId is keyspace identifier.
-  Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store)
-  It is up to clients to use single or multiple store's for their usage.
-  This can be used for client-isolation/ rate-limiting / throttling on server-side.
-  Authorization and billing can also be performed at storeId level.
- */
 message GetObjectRequest {
 
+  /*
+    StoreId: All APIs operate within a single storeId.
+    StoreId is a keyspace identifier.
+    Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store)
+    It is up to clients to use single or multiple stores for their use-case.
+    This can be used for client-isolation/ rate-limiting / throttling on the server-side.
+    Authorization and billing can also be performed at the storeId level.
+ */
   string storeId = 1;
 
   /*
@@ -23,63 +23,74 @@ message GetObjectRequest {
 
     Read Isolation:
     Get/Read operations against a key are ensured to have read-committed isolation.
-    Read-committed is an isolation level that guarantees that any data read was committed at the
-    moment it is read. It will not return with any intermediate, uncommitted or 'dirty' read while
-    another PutObjectRequest was concurrently updating the same keys.
-    Read-committed isolation does not prevent modifications of the key-value immediately after the
-    read.
+    Ref: https://en.wikipedia.org/wiki/Isolation_(database_systems)#Read_committed
    */
   string key = 2;
 }
 
 
 message GetObjectResponse {
   /*
-    Fetched value and version along with corresponding key in request.
+    Fetched value and version along with the corresponding key in the request.
    */
   KeyValue value = 2;
 }
 
 
 message PutObjectRequest {
 
+  /*
+    StoreId: All APIs operate within a single storeId.
+    StoreId is a keyspace identifier.
+    Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store)
+    It is up to clients to use single or multiple stores for their use-case.
+    This can be used for client-isolation/ rate-limiting / throttling on the server-side.
+    Authorization and billing can also be performed at the storeId level.
+ */
   string storeId = 1;
   /*
-    If present, write will only succeed if current DB globalVersion against a storeId is
-    same as in request.
-    Client is expected to store(client-side) global version against storeId.
-    And PutObjectRequest should contain their client-side value of globalVersion.
-
-    For first write of store, global version should be '0'. If write succeeds, clients must increment
-    their global version(client-side) by 1. This updated global version should be used in subsequent
-    PutObjectRequests for the store.
-
-    Requests with conflicting version will fail with [`ConflictException`] as ErrorCode.
+    If present, the write will only succeed if the current server-side globalVersion against
+    a storeId is same as in the request.
+    Clients are expected to store (client-side) the global version against storeId.
+    And the request should contain their client-side value of globalVersion.
+
+    For the first write of the store, global version should be '0'. If the write succeeds, clients
+    must increment their global version (client-side) by 1.
+    The server increments globalVersion (server-side) for every successful write, hence this
+    client-side increment is required to ensure matching versions. This updated global version
+    should be used in subsequent PutObjectRequests for the store.
+
+    Requests with conflicting version will fail with `ConflictException` as ErrorCode.
    */
   optional int64 globalVersion = 2;
 
   /*
-    Each key is supplied with its corresponding value and version.
-    Clients can choose to encrypt keys client-side in order to obfuscate user's usage patterns.
-    If write is successful, previous value of key will be overwritten.
+    Items to be written as a result of this PutObjectRequest.
+
+    In an item, each key is supplied with its corresponding value and version.
+    Clients can choose to encrypt the keys client-side in order to obfuscate user's usage patterns.
+    If write is successful, previous value corresponding to the key will be overwritten.
 
-    Multiple items in transactionItems of single PutObjectRequest are written in
+    Multiple items in transactionItems of a single PutObjectRequest are written in
     a database-transaction in all-or-nothing fashion.
-    Items in single PutObjectRequest should have distinct keys.
+    Items in single PutObjectRequest must have distinct keys.
 
     Write will only succeed if current DB version against key is same as in request.
     Client is expected to store version against every key.
-    When initiating a PutObjectRequest, request should contain their client-side version for that key.
+    When initiating a PutObjectRequest, the request should contain their client-side version for
+    that key-value.
 
-    For first write of key, version should be '0'. If write succeeds, clients must increment
-    their corresponding key versions(client-side) by 1. These updated key versions should be used in
-    subsequent PutObjectRequests for the keys.
+    For first write of key, version should be '0'. If the write succeeds, clients must increment
+    their corresponding key versions (client-side) by 1.
+    The server increments key version (server-side) for every successful write, hence this
+    client-side increment is required to ensure matching versions. These updated key versions should
+    be used in subsequent PutObjectRequests for the keys.
 
-    Requests with conflicting version will fail with [`ConflictException`] as ErrorCode.
+    Requests with conflicting version will fail with `ConflictException` as ErrorCode.
 
     Considerations for transactions:
     Transaction writes of multiple items have a performance overhead, hence it is recommended to use
-    them only if required by client application to ensure logic/code correctness.
+    them only if required by the client application to ensure logic/code correctness.
     That is, transactionItems are not a substitute for batch-write of multiple unrelated items.
     When write of multiple unrelated items is desired, it is recommended to use separate
     PutObjectRequests.
@@ -96,20 +107,20 @@ message PutObjectResponse {
 
 
 /*
-  When HttpStatusCode is not ok(200), response `content` contains serialized ErrorResponse with
-  relevant ErrorCode and errorCode's integer value as HttpStatusCode.
+  When HttpStatusCode is not ok (200), the response `content` contains serialized ErrorResponse with
+  the relevant ErrorCode and ErrorCode's integer value as HttpStatusCode.
  */
 message ErrorResponse {
   /*
-    The error code is a string that uniquely identifies an error condition.
-    It is meant to be read and understood programmatically  by code that detects/handles errors by
+    The error code enum-value uniquely identifies an error condition.
+    It is meant to be read and understood programmatically by code that detects/handles errors by
     type.
    */
   ErrorCode errorCode = 1;
   /*
     The error message contains a generic description of the error condition in English.
     It is intended for a human audience only. And should not be parsed to extract any information
-    programmatically. Client side code may use it for logging only.
+    programmatically. Client-side code may use it for logging only.
    */
   string message = 2;
 }
@@ -121,19 +132,19 @@ message ErrorResponse {
  */
 enum ErrorCode {
   /*
-    Default protobuf Enum value, will not be used as ErrorCode by server.
+    Default protobuf Enum value. Will not be used as ErrorCode by server.
    */
   Unknown = 0;
   /*
-    ConflictException is used when request contains mismatched version (either key or global)
+    ConflictException is used when the request contains mismatched version (either key or global)
     in PutObjectRequest. For more info refer PutObjectRequest.
    */
   ConflictException = 409;
   /*
-    InvalidRequestException is used in following cases:
-      - Request was missing a required argument.
+    InvalidRequestException is used in the following cases:
+      - The request was missing a required argument.
       - The specified argument was invalid, incomplete or in the wrong format.
-      - Request body of api cannot be deserialized into corresponding protobuf object.
+      - The request body of api cannot be deserialized into corresponding protobuf object.
    */
   InvalidRequestException = 400;
   /*
@@ -151,15 +162,17 @@ message KeyValue {
   string key = 1;
 
   /*
-    For first write of key, version should be '0'. If write succeeds, clients must increment
-    their corresponding key version(client-side) by 1. These updated key versions should be used in
-    subsequent PutObjectRequests for the keys.
+    For first write of key, version should be '0'. If the write succeeds, clients must increment
+    their corresponding key version (client-side) by 1.
+    The server increments key version (server-side) for every successful write, hence this
+    client-side increment is required to ensure matching versions. These updated key versions should
+    be used in subsequent PutObjectRequests for the keys.
    */
   int64 version = 2;
 
   /*
-    Object value in bytes which is stored(in put) and fetched (in get).
-    Clients must encrypt this blob client-side before sending it over wire to server in order
+    Object value in bytes which is stored (in put) and fetched (in get).
+    Clients must encrypt this blob client-side before sending it over the wire to server in order
     to preserve privacy and security.
    */
   bytes value = 3;