From 04f1cbca48f7c95aacc96e565e424b31760af598 Mon Sep 17 00:00:00 2001
From: Leonard Lyubich <leonard@nspcc.ru>
Date: Wed, 20 Nov 2019 19:46:30 +0300
Subject: [PATCH] docs: add session proto documentation

---
 session/service.proto | 20 ++++++++++++++++++++
 session/types.proto   | 10 ++++++++++
 2 files changed, 30 insertions(+)

diff --git a/session/service.proto b/session/service.proto
index ee56a22..484425b 100644
--- a/session/service.proto
+++ b/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;
     }
 }
diff --git a/session/types.proto b/session/types.proto
index 8989040..bf804bf 100644
--- a/session/types.proto
+++ b/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];
 }