Add comments to improve code readability

Author: dottorblaster

src/conversion.c

@@ -1,5 +1,6 @@
 #include "conversion.h"
 
+// Shall I need to convert that image? This function gives us a clue.
 int is_image(char *tok) {
     if (!strncmp(&tok[0], "image/jpeg", strlen("image/jpeg"))) {
         return 1;
@@ -22,21 +23,26 @@ int is_image(char *tok) {
     return 0;
 }
 
+// Checker for headers: does this header have quality inside?
 int has_quality(char *tok) {
     if (strstr(tok, ";q=") != NULL) {
         return 1;
     }
     return 0;
 }
 
+// Here we take an header and give back the conversion quality as an int.
 int conversion_quality(char *header) {
     char *tok, *str, *dbuf;
     double quality;
     int retval;
 
     dbuf = str = strdup(header);
+    // Iteration upon tokens returned by strsep
     while ((tok = strsep(&str, ",")) != NULL) {
         if (is_image(tok) && has_quality(tok)) {
+            // strsep again upon a different token
+            // to get our quality
             strsep(&tok, ";q=");
             tok += 2;
             quality = atof(tok)*100;
@@ -49,6 +55,7 @@ int conversion_quality(char *header) {
 	return 0;
 }
 
+// Compute a cached filename from a basic filename buffer
 char * cached_filename(char *buf, int quality) {
     char *str;
     char *retval = malloc(sizeof(buf)+4);
@@ -64,11 +71,14 @@ char * cached_filename(char *buf, int quality) {
     return retval;
 }
 
+// Cache hit helper function.
 int cachehit(char *buf, hcontainer *headers) {
 	char *cachedfn, *toaccess;
 	int q;
 	if (!strcmp(headers[0].val, "")) { return 0; }
 
+    // Checking if we have a conversion quality > 0
+    // Then computing the correct filename
     if ((q = conversion_quality(headers[0].val)) == 0) { return 0; }
     cachedfn = cached_filename(buf, q);
 
@@ -78,17 +88,25 @@ int cachehit(char *buf, hcontainer *headers) {
 
     printf("%s\n", toaccess);
 
+    // If the cached copy doesn't exist, we convert
+    // the file on-the-fly with an helper
     if (access(toaccess, F_OK | R_OK) == 0) {
         logger(LOG, "Cache hit!", "serving the cached file");
 	} else {
         logger(LOG, "Cache didn't hit", "still need to convert the file");
         convert_img(buf, cachedfn, q);
     }
 
+    // Here we violate the single responsibility principle
+    // editing the buffer and pointing it to another file.
+    // The cached one.
     strcpy(buf, cachedfn);
 	return 1;
 }
 
+// We use an sprintf-powered builder to build up a string
+// then we issue a system command. We use this function as
+// an abstraction layer upon `convert`.
 int convert_img(char *source, char *dest, int quality) {
     char cmd[sizeof(source)+sizeof(dest)+211];
 

src/error_handler.c

@@ -1,5 +1,8 @@
 #include "error_handler.h"
 
+// Error handler shorthand function.
+// We have a switch case and various writes to the buffer,
+// each one with a static response.
 void handle_error(int type, int socket_fd) {
 	switch(type) {
 		case ERROR:

src/grocery.c

@@ -1,9 +1,13 @@
 #include "grocery.h"
 
+// Prints an help string if needed.
 void print_help() {
 	printf("Usage: ./grocery 8080");
 }
 
+// Preliminary checks for execution.
+// We create the cache directory, and we check for proper arguments.
+// In case we don't meet the requirements, we exit(0).
 void preliminary_checks(int argc, char **argv) {
 	if (argc != 2 || !strcmp(argv[1], "-h")) {
 		print_help();
@@ -23,14 +27,15 @@ void preliminary_checks(int argc, char **argv) {
 	}
 }
 
+// Spawning the server
 void spawn_server(char **argv) {
 	int pid, lfd, sock_fd, optv;
 	static struct sockaddr_in cli;
 	static struct sockaddr_in server;
 
 	socklen_t l;
 
-	/* Just ignore SIGCHLD and SIGHUP, we don't care. */
+	// Just ignore SIGCHLD and SIGHUP, we don't care.
 	signal(SIGHUP, SIG_IGN);
 	signal(SIGCHLD, SIG_IGN);
 
@@ -47,16 +52,23 @@ void spawn_server(char **argv) {
 
 	printf("grocery listening on port %s\n", argv[1]);
 
+	// Endless loop to accept requests and
+	// dispatch new child processes
 	for (;;) {
 		l = sizeof(cli);
 
+		// Accept incoming connections, fork and handle requests
 		if ((sock_fd = accept(lfd, (struct sockaddr *)&cli, &l)) < 0) { logger(ERROR, "Error during a syscall", "accept"); }
 
 		if ((pid = fork()) < 0) {
 			logger(ERROR, "Error during a syscall", "fork()");
 		}
 		else {
 			if (pid == 0) {
+				// Properly handle requests passing the socket file descriptor
+				// as an argument. The second argument is the keepalive one.
+				// Basing a logic upon this lets us discriminate about requests
+				// coming from keepalive connections or not.
 				request_handler(sock_fd, 0);
 			} else {
 				close(sock_fd);
@@ -65,6 +77,9 @@ void spawn_server(char **argv) {
 	}
 }
 
+// Main function.
+// We run our preliminary checks, then we spawn the server
+// passing the argv arguments array to bind properly
 int main(int argc, char **argv) {
 	preliminary_checks(argc, argv);
 	spawn_server(argv);

src/headers.c

@@ -1,5 +1,7 @@
 #include "headers.h"
 
+// Determine an header's length
+// iterating on the buffer.
 int headers_l(char *buf) {
 	int i, res = 0;
 	for (i = 0; i < BUFSIZE; i++) {
@@ -11,6 +13,9 @@ int headers_l(char *buf) {
 	return res;
 }
 
+// Look for a particular header in the buffer.
+// Takin' a label, the buffer, and iterate on the
+// buffer until we find the Ring.
 char * hlook(char *label, char *buf) {
 	char *tk, *str, *dbuf;
 	dbuf = str = strdup(buf);

src/logger.c

@@ -1,5 +1,8 @@
 #include "logger.h"
 
+// Constants-powered logger shorthand function.
+// We print all of our informations to the STDOUT,
+// then to a `grocery.log` plain text file.
 void logger(int type, char *s1, char *s2) {
 	int fd;
 	char logbuffer[BUFSIZE*2];

src/request_handler.c

@@ -1,11 +1,13 @@
 #include "request_handler.h"
 
+// Request identifier.
 char * whichreq(char *buf) {
 	if (!strncmp(&buf[0],"GET", 3) || !strncmp(&buf[0],"get", 3)) { return "get"; }
 	if (!strncmp(&buf[0],"HEAD", 4) || !strncmp(&buf[0],"head", 4)) { return "head"; }
 	return "other";
 }
 
+// Unsupported method handler. Here we print out to the response buffer a 405 Unsupported Method.
 void handle_unsupported_method(int sock_fd, char *buf) {
 	sprintf(
 		buf,
@@ -17,18 +19,24 @@ void handle_unsupported_method(int sock_fd, char *buf) {
 	exit(0);
 }
 
+// Handler for GETs.
 void handle_get(int sock_fd, char *buf, char *ext, hcontainer *headers) {
 	int fle;
 	long ln, rt;
 	char fn[sizeof(buf) + 11];
 
+	// Here we check for cache-hit and set an eventual cache directory prefix
+	// otherwise we use `./www`
 	if (is_image(ext) && cachehit(&buf[5], headers)) {
 		strcpy(fn, "./cache/");
 		strcat(fn, &buf[5]);
 	} else {
 		strcpy(fn, "./www/");
 		strcat(fn, &buf[5]);
 	}
+
+	// ... then we try to open the file.
+	// If we can't open it, we fire a 404 Not Found.
 	if ((fle = open(fn, O_RDONLY)) == -1) {
 		logger(NOTFOUND, "not found", &buf[5]);
 		handle_error(NOTFOUND, sock_fd);
@@ -37,6 +45,8 @@ void handle_get(int sock_fd, char *buf, char *ext, hcontainer *headers) {
 	logger(LOG, "GET", &buf[5]);
 	ln = (long)lseek(fle, (off_t)0, SEEK_END);
 	lseek(fle, (off_t)0, SEEK_SET);
+
+	// Print the response' header to the response buffer
 	sprintf(
 		buf,
 		"HTTP/1.1 200 OK\nServer: grocery/%d.0\nContent-Length: %ld\nConnection: %s\nContent-Type: %s\n\n",
@@ -47,13 +57,15 @@ void handle_get(int sock_fd, char *buf, char *ext, hcontainer *headers) {
 	);
 	write(sock_fd, buf, strlen(buf));
 
+	// Then write the actual file to the buffer.
 	while ((rt = read(fle, buf, BUFSIZE)) > 0) {
 		write(sock_fd, buf, rt);
 	}
 
 	close(fle);
 	sleep(1);
 
+	// Check for a keepalive header, then dispatch another handler or close everything and die
 	if (strlen(headers[1].val) != 0 && !strncmp(&headers[1].val[1], "close", 5)) {
 		close(sock_fd);
 		free(headers);
@@ -66,6 +78,8 @@ void handle_get(int sock_fd, char *buf, char *ext, hcontainer *headers) {
 	}
 }
 
+// HEAD handler.
+// Very similar to the one above, but without the file body.
 void handle_head(int sock_fd, char *buf, char *ext) {
 	int fle;
 	long ln;
@@ -93,13 +107,15 @@ void handle_head(int sock_fd, char *buf, char *ext) {
 	exit(0);
 }
 
+// Generic request handler.
 void request_handler(int sock_fd, int keepalive) {
 	long rt, ln, i;
 	static char buf[BUFSIZE+1];
 	char *method, *ext;
 
 	hcontainer headers[3];
 
+	// We declare a struct of supported extensions/filetypes
 	struct {
 		char *ext;
 		char *filetype;
@@ -118,6 +134,7 @@ void request_handler(int sock_fd, int keepalive) {
 		{0, 0}
 	};
 
+	// Read the request then check for errors
 	rt = read(sock_fd, buf, BUFSIZE);
 	if (rt == -1) {
 		logger(ERROR, "Error reading request", "read()");
@@ -129,6 +146,8 @@ void request_handler(int sock_fd, int keepalive) {
 
 	(rt > 0 && rt < BUFSIZE) ? (buf[rt] = 0) : (buf[0] = 0);
 
+	// Check for headers through `hlook`, then
+	// populate the `headers` struct
 	if (keepalive == 0) {
 		headers[0].key = "Accept";
 		headers[0].val = hlook("Accept: ", buf);
@@ -151,13 +170,16 @@ void request_handler(int sock_fd, int keepalive) {
 			break;
 		}
 	}
+	// index.html standard support!
 	if (!strncmp(&buf[0],"GET /\0", 6) || !strncmp(&buf[0],"get /\0", 6)) {
 		strcpy(buf, "GET /index.html");
 	}
 	if (!strncmp(&buf[0],"HEAD /\0", 7) || !strncmp(&buf[0],"head /\0", 7)) {
 		strcpy(buf, "HEAD /index.html");
 	}
 
+	// Check if the file extension is supported, then
+	// fire a 403 Forbidden if this is not the case
 	ext = "";
 	for (i = 0; extensions[i].ext != 0; i++) {
 		ln = strlen(extensions[i].ext);
@@ -170,6 +192,9 @@ void request_handler(int sock_fd, int keepalive) {
 		handle_error(FORBIDDEN, sock_fd);
 	}
 
+	// Discriminate incoming requests.
+	// Should I use GET' handler? HEAD's one?
+	// Should I stay or should I go?
 	method = whichreq(buf);
 	if (!strncmp(&method[0], "get", 3)) {
 		handle_get(sock_fd, buf, ext, headers);