From 40955a378a4bb7c38beb48c267cdc8c81da7200b Mon Sep 17 00:00:00 2001
From: terrill <314156936@qq.com>
Date: Tue, 3 Jul 2018 10:38:18 +0800
Subject: [PATCH] add blurbs and comment for nested code and each important
 function

---
 .../dendrite/encryptoapi/encryptoapi.go       |  4 ++++
 .../dendrite/encryptoapi/routing/keys.go      | 19 ++++++++++++++++++-
 .../encryptoapi/storage/encrypt_algorithm.go  |  2 ++
 .../encryptoapi/storage/encrypt_keys_table.go |  5 +++++
 .../dendrite/encryptoapi/storage/storage.go   |  6 ++++++
 5 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/src/github.com/matrix-org/dendrite/encryptoapi/encryptoapi.go b/src/github.com/matrix-org/dendrite/encryptoapi/encryptoapi.go
index b103dc827..dfb746d85 100644
--- a/src/github.com/matrix-org/dendrite/encryptoapi/encryptoapi.go
+++ b/src/github.com/matrix-org/dendrite/encryptoapi/encryptoapi.go
@@ -23,6 +23,10 @@ import (
 	"fmt"
 )
 
+// in order to gain key management capability
+// , CMD should involve this invoke into main function
+// , a setup need an assemble of i.e configs as base and
+// accountDB and deviceDB
 func SetupEcryptoapi(
 	base *basecomponent.BaseDendrite,
 	accountsDB *accounts.Database,
diff --git a/src/github.com/matrix-org/dendrite/encryptoapi/routing/keys.go b/src/github.com/matrix-org/dendrite/encryptoapi/routing/keys.go
index 11ab6acdf..6a1889219 100644
--- a/src/github.com/matrix-org/dendrite/encryptoapi/routing/keys.go
+++ b/src/github.com/matrix-org/dendrite/encryptoapi/routing/keys.go
@@ -49,6 +49,8 @@ type KeyNotifier struct {
 
 var keyProducer = &KeyNotifier{}
 
+// this function is for user upload his device key, and one-time-key
+// to a limit at 50 set as default
 func UploadPKeys(
 	req *http.Request,
 	encryptionDB *storage.Database,
@@ -60,11 +62,13 @@ func UploadPKeys(
 		return *reqErr
 	}
 	keySpecific := turnSpecific(keybody)
+	// persist keys into encryptionDB
 	err := persistKeys(
 		encryptionDB,
 		req.Context(),
 		&keySpecific,
 		userID, deviceID)
+	// numMap is algorithm-num map
 	numMap := (QueryOneTimeKeys(
 		TYPESUM,
 		userID,
@@ -87,6 +91,7 @@ func UploadPKeys(
 	}
 }
 
+// this function is for user query other's device key
 func QueryPKeys(
 	req *http.Request,
 	encryptionDB *storage.Database,
@@ -127,15 +132,19 @@ func QueryPKeys(
 		}
 	}
 
+	// query one's device key from user corresponding to uid
 	for uid, arr := range queryRq.DeviceKeys {
 		queryRp.DeviceKeys[uid] = make(map[string]types.DeviceKeysQuery)
 		deviceKeysQueryMap := queryRp.DeviceKeys[uid]
 		// backward compatible to old interface
 		midArr := []string{}
+		// figure out device list from devices described as device which is actually deviceID
 		for device, _ := range arr.(map[string]interface{}) {
 			midArr = append(midArr, device)
 		}
+		// all device keys
 		dkeys, _ := encryptionDB.QueryInRange(req.Context(), uid, midArr)
+		// build response for them
 		for _, key := range dkeys {
 			// preset for complicated nested map struct
 			if _, ok := deviceKeysQueryMap[key.Device_id]; !ok {
@@ -182,6 +191,7 @@ func QueryPKeys(
 	}
 }
 
+// claim for one time key that may be used in session exchange in olm encryption
 func ClaimOneTimeKeys(
 	req *http.Request,
 	encryptionDB *storage.Database,
@@ -258,7 +268,8 @@ func LookUpChangedPKeys() util.JSONResponse {
 	}
 }
 
-// todo: check through interface for duplicate
+// todo: check through interface for duplicate and what type of request should it be
+// whether device or one time or both of them
 func checkUpload(req *types.UploadEncryptSpecific, typ int) bool {
 	if typ == BODYDEVICEKEY {
 		devicekey := req.DeviceKeys
@@ -292,6 +303,7 @@ func QueryOneTimeKeys(
 // when web client sign out, a clean should be processed, cause all keys would never been used from then on.
 func ClearUnused() {}
 
+// persist both device keys and one time keys
 func persistKeys(
 	database *storage.Database,
 	ctx context.Context,
@@ -300,6 +312,10 @@ func persistKeys(
 	deviceID string,
 ) (err error) {
 	// in order to persist keys , a check filtering duplicate should be processed
+	// true stands for counterparts are in request
+	// situation 1: only device keys
+	// situation 2: both device keys and one time keys
+	// situation 3: only one time keys
 	if checkUpload(body, BODYDEVICEKEY) {
 		deviceKeys := body.DeviceKeys
 		al := deviceKeys.Algorithm
@@ -375,6 +391,7 @@ func persistKeys(
 	return err
 }
 
+// make keys instantiated to specific struct from keybody interface{}
 func turnSpecific(
 	cont types.UploadEncrypt,
 ) (spec types.UploadEncryptSpecific) {
diff --git a/src/github.com/matrix-org/dendrite/encryptoapi/storage/encrypt_algorithm.go b/src/github.com/matrix-org/dendrite/encryptoapi/storage/encrypt_algorithm.go
index 18657e859..d243028c6 100644
--- a/src/github.com/matrix-org/dendrite/encryptoapi/storage/encrypt_algorithm.go
+++ b/src/github.com/matrix-org/dendrite/encryptoapi/storage/encrypt_algorithm.go
@@ -58,6 +58,7 @@ func (s *alStatements) prepare(db *sql.DB) (err error) {
 	return
 }
 
+// persist algorithms
 func (ks *alStatements) insertAl(
 	ctx context.Context, txn *sql.Tx,
 	userID, deviceID, algorithms string,
@@ -67,6 +68,7 @@ func (ks *alStatements) insertAl(
 	return err
 }
 
+// select algorithms
 func (ks *alStatements) selectAl(
 	ctx context.Context,
 	txn *sql.Tx,
diff --git a/src/github.com/matrix-org/dendrite/encryptoapi/storage/encrypt_keys_table.go b/src/github.com/matrix-org/dendrite/encryptoapi/storage/encrypt_keys_table.go
index fdce52d9e..c314770af 100644
--- a/src/github.com/matrix-org/dendrite/encryptoapi/storage/encrypt_keys_table.go
+++ b/src/github.com/matrix-org/dendrite/encryptoapi/storage/encrypt_keys_table.go
@@ -95,6 +95,7 @@ func (s *keyStatements) prepare(db *sql.DB) (err error) {
 	return
 }
 
+// insert keys
 func (ks *keyStatements) insertKey(
 	ctx context.Context, txn *sql.Tx,
 	deviceID, userID, keyID, keyTyp, keyInfo, algorithm, signature string,
@@ -104,6 +105,7 @@ func (ks *keyStatements) insertKey(
 	return err
 }
 
+// select by user and device
 func (ks *keyStatements) selectKey(
 	ctx context.Context,
 	txn *sql.Tx,
@@ -131,6 +133,8 @@ func (ks *keyStatements) selectKey(
 	}
 	return holders, err
 }
+
+// select single one for claim usage
 func (ks *keyStatements) selectSingleKey(
 	ctx context.Context,
 	userID, deviceID, algorithm string,
@@ -156,6 +160,7 @@ func (ks *keyStatements) selectSingleKey(
 	return holder, err
 }
 
+// select details by given an array of devices
 func (ks *keyStatements) selectInKeys(
 	ctx context.Context,
 	userID string,
diff --git a/src/github.com/matrix-org/dendrite/encryptoapi/storage/storage.go b/src/github.com/matrix-org/dendrite/encryptoapi/storage/storage.go
index bb14bb2ab..a08f4ad87 100644
--- a/src/github.com/matrix-org/dendrite/encryptoapi/storage/storage.go
+++ b/src/github.com/matrix-org/dendrite/encryptoapi/storage/storage.go
@@ -47,6 +47,7 @@ func NewDatabase(dataSourceName string) (*Database, error) {
 	return &Database{db: db, keyStatements: keyStatement, alStatements: alStatement}, nil
 }
 
+// insert device key
 func (d *Database) InsertKey(
 	ctx context.Context,
 	deviceID, userID, keyID, keyTyp, keyInfo, al, sig string,
@@ -57,6 +58,7 @@ func (d *Database) InsertKey(
 	return
 }
 
+// for key upload response usage a map from key algorithm to sum to counterpart
 func (d *Database) SelectOneTimeKeyCount(
 	ctx context.Context,
 	deviceID, userID string,
@@ -77,6 +79,7 @@ func (d *Database) SelectOneTimeKeyCount(
 	return
 }
 
+// query keys in a range of devices
 func (d *Database) QueryInRange(
 	ctx context.Context,
 	userID string,
@@ -86,6 +89,7 @@ func (d *Database) QueryInRange(
 	return
 }
 
+// persist algorithms
 func (d *Database) InsertAl(
 	ctx context.Context, uid, device string, al []string,
 ) (err error) {
@@ -96,6 +100,7 @@ func (d *Database) InsertAl(
 	return
 }
 
+// select algorithms
 func (d *Database) SelectAl(
 	ctx context.Context, uid, device string,
 ) (res []string, err error) {
@@ -107,6 +112,7 @@ func (d *Database) SelectAl(
 	return
 }
 
+// claim for one time key one for once
 func (d *Database) SelectOneTimeKeySingle(
 	ctx context.Context,
 	userID, deviceID, algorithm string,