Added comments to the script

lcmlog-server

@@ -11,19 +11,23 @@ import logging.handlers
 import hashlib
 import contextlib
 
+# We log what happens every time someone connects
 # Preparing the logger
 logger = logging.getLogger(__name__)
 file_formatter = logging.Formatter("%(asctime)s | %(levelname)8s | %(message)s")
 logger.setLevel(logging.INFO)
 
 # Logger handle to log all info
+# We use a TimedRotatingFileHandler to rotate logs once a week
 file_handler = logging.handlers.TimedRotatingFileHandler(filename = DIR + "/logs/logfile", when = "W6", backupCount = 10)
 file_handler.setFormatter(file_formatter)
 logger.addHandler(file_handler)
 
+#------------------------------------------------------------------------------
 
 def main():
 
+	# The user is going to call us through ssh, so to know who he is we can simply get his effective uid
 	user_id = os.geteuid()
 	user_name = pwd.getpwuid(user_id).pw_name
 
@@ -32,25 +36,26 @@ def main():
 	try:
 		method = input() # Can be GET, POST or UPDATE
 		logger.info("Method: " + method)
-		if method == "UPDATE":
-			auth(user_id, "UPDATE", "")
+		if method == "UPDATE":	# We don't need more input lines for the UPDATE method
+			auth(user_id, "UPDATE", "")	# Check if the user can update the database
 			method_update()
 		else:
-			kind = input()   # Can be 150 or Admin
+			kind = input()	# This is the kind of the log, and it can be 150 or Admin
 			logger.info("Kind: " + kind)
-			date = input()
+			# TODO: check if the date format is valid (after deciding which format save the date in
+			date = input()	# The date of the log
 			logger.info("Date: " + date)
-			tags = input()
+			tags = input()	# Tags are comma separated
 			logger.info("Tags: " + tags)
 
-			if kind != "150" and kind != "Admin":
+			if kind != "150" and kind != "Admin":	# We only have this two log types
 				raise KindError
 			if method == "POST":
-				auth(user_id, "POST", kind)
+				auth(user_id, "POST", kind)	# Check if the user can post for the requested kind
 				log = sys.stdin.read() # Read the log content
 				method_post(kind, user_name, date, tags, log)
 			elif method == "GET":
-				auth(user_id, "GET", kind)
+				auth(user_id, "GET", kind)	# Check if the user can get logs for the requested kind
 				user_to_find = input() # Read the user name of the log writer to search
 				logger.info("User to find: " + user_to_find)
 				method_get(kind, user_to_find, date, tags)
@@ -85,9 +90,15 @@ def main():
 	finally:
 		logger.info("End\n")
 
+#------------------------------------------------------------------------------
 
-# Create new log
+# Create new log file and adds it to the database
+# kind, user_name, date and tags is the log metadata
+# log is the log content
+# The log metadata and content is hashed, and the hash is saved in the database and used as the filename for the log
+# The return value of the function is the hash
 def log_create(kind, user_name, date, tags, log):
+	# TODO: utf-8 encoding doesn't allow accented characters. Find a more suitable encoding
 	name = hashlib.sha512((kind + user_name + date + tags + log).encode("utf-8")).hexdigest()
 	with open(DIR + "/data/" + name, "x") as f:
 		f.write(name + "\n" + kind + "\n" + user_name + "\n" + date + "\n" + tags + "\n" + log)	# Write the file
@@ -96,6 +107,9 @@ def log_create(kind, user_name, date, tags, log):
 	return name
 
 # Search for the requested entry
+# The functions returns a list containing the hash (saved in the database) of all the files that meet the specified criteria
+# The kind parameter is mandatory (because different users have different privileges based on it).
+# All the other arguments can be empty. Only the arguments that are not empty are taken into consideration for the search
 def log_find(kind, user_name, date, tags):
 	file_list = list()
 	with open(DIR + "/data/.data", "r") as f:
@@ -116,7 +130,10 @@ def log_find(kind, user_name, date, tags):
 				file_list.append(l[0])
 	return file_list
 
+# TODO: the following functions work with the hash of the log files. The problem is that there are three different places where the hash is: the first line of the file, the database entry for the log and the filename of the log. I have to decide which function operates on which hash, because for example if the hash is changed in the file, it needs to be changed also in the other two locations.
 # Add log file to .data
+# This function reads an existing log file and adds it to the database
+# Tha hash that is saved in the database is not calculated: the first line in the file is considered to be the hash. Use log_check to check if they are the same
 def log_add(name):
 	with open(DIR + "/data/" + name, "r") as f, open(DIR + "/data/.data", "a") as data:
 		data.write(f.readline().rstrip("\n") + ":" +	# Hash
@@ -126,6 +143,8 @@ def log_add(name):
 			   f.readline().rstrip("\n") + "\n") 	# Tags
 
 # Check if the saved hash is correct, and if it is not, ask the user what to do
+# This function calculates the hash of the file with filename name, and returns True if it is the same as the first line of the file, False otherwise
+# If it doesn't correspond, it asks the user if he wants to keep it like it is or change it. Currently, it is pretty messed up: only the hash saved in the file is changed, not the one saved in the database or the file name. Also, the dialog to ask if the hash is to be changed probably should not be in this function.
 def log_check(name):
 	with open(DIR + "/data/" + name, "r") as f:
 		saved_hash = f.readline().rstrip("\n")
@@ -161,6 +180,7 @@ def log_check(name):
 	
 
 # Calculates hash of file
+# The first line of the file is the saved hash, therefore it is not considered in the calculation
 def log_hash(name):
 	with open(DIR + "/data/" + name, "r") as f:
 		f.readline()	# The saved hash doesn'e enter in the calculation
@@ -171,6 +191,8 @@ def log_hash(name):
 		log = f.read()
 		return hashlib.sha512((kind + user_name + date + tags + log).encode("utf-8")).hexdigest()
 
+#------------------------------------------------------------------------------
+
 # Print specified log on stdout
 def method_get(kind, user_to_find, date, tags):
 	file_list = log_find(kind, user_to_find, date, tags)
@@ -202,6 +224,8 @@ def method_update():
 		log_add(newname)
 	logger.info("UPDATE succesful: added " + str(len(file_list)) + " files")
 
+#------------------------------------------------------------------------------
+
 # Checks if the user has the permissions to use the requested method
 def auth(user_id, method, kind):
 	with open(DIR + "/auth/" + kind + "/" + method) as f:
@@ -210,6 +234,8 @@ def auth(user_id, method, kind):
 				return
 	raise AuthError()
 
+#------------------------------------------------------------------------------
+
 # Error definitions
 class AuthError(Exception):
 	pass
@@ -218,6 +244,8 @@ class KindError(Exception):
 class MethodError(Exception):
 	pass
 
+#------------------------------------------------------------------------------
+
 # Starting point
 if __name__ == "__main__":
 	main()