docs: add session proto documentation

session/service.proto

@@ -7,21 +7,41 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
 
 option (gogoproto.stable_marshaler_all) = true;
 
+
 service Session {
+    // Open a trusted session to manipulate an object. In order to put or
+    // delete object client have to obtain session token with trusted node.
+    // Trusted node will modify client's object (add missing headers, checksums,
+    // homomorphic hash) and sign id with session key. Session is established
+    // during 4-step handshake in one gRPC stream
+
+    // - First client stream message SHOULD BE type of `CreateRequest_Init`.
+    // - First server stream message SHOULD BE type of `CreateResponse_Unsigned`.
+    // - Second client stream message SHOULD BE type of `CreateRequest_Signed`.
+    // - Second server stream message SHOULD BE type of `CreateResponse_Result`.
+
     rpc Create (stream CreateRequest) returns (stream CreateResponse);
 }
 
 
 message CreateRequest {
+    // Message should be one of
     oneof Message {
+        // Message to init session opening. Carry:
+        // owner of manipulation object;
+        // ID of manipulation object;
+        // token lifetime bounds.
         session.Token Init = 1;
+        // Signed Init message response (Unsigned) from server with user private key
         session.Token Signed = 2;
     }
 }
 
 message CreateResponse {
     oneof Message {
+        // Unsigned token with token ID and session public key generated on server side
         session.Token Unsigned = 1;
+        // Resulting token which can be used for object placing through an trusted intermediary
         session.Token Result = 2;
     }
 }

session/types.proto

@@ -7,16 +7,26 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
 option (gogoproto.stable_marshaler_all) = true;
 
 message VerificationHeader {
+    // Session public key
     bytes PublicKey = 1;
+    // Session public key signature. Signed by trusted side
     bytes KeySignature = 2;
 }
 
+// User token granting rights for object manipulation
 message Token {
+    // Header carries verification data of session key
     VerificationHeader Header = 1 [(gogoproto.nullable) = false];
+    // Owner of manipulation object
     bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
+    // Initial epoch of token lifetime
     uint64 FirstEpoch = 3;
+    // Last epoch of token lifetime
     uint64 LastEpoch = 4;
+    // ID of manipulation object
     repeated bytes ObjectID = 5 [(gogoproto.customtype) = "ObjectID", (gogoproto.nullable) = false];
+    // Token signature. Signed by owner of manipulation object
     bytes Signature = 6;
+    // Token ID (UUID)
     bytes ID = 7 [(gogoproto.customtype) = "TokenID", (gogoproto.nullable) = false];
 }