From 1b8aad7e91485d6fdb1bdb42ff769124d5ebccad Mon Sep 17 00:00:00 2001
From: Alexander Rosenberg <zanderpkg@pm.me>
Date: Thu, 4 Jun 2026 20:33:45 -0700
Subject: [PATCH] Add design doc

---
 .gitignore |  1 +
 main.c     | 39 ++++++++++++++++++++++++++++++++++++++-
 2 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index d38d173..f18c279 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,4 @@ httpserver
 compile_commands.json
 bin/
 config.json
+.cache/
diff --git a/main.c b/main.c
index 30aad93..d13d56b 100644
--- a/main.c
+++ b/main.c
@@ -1,11 +1,48 @@
 /*
- * Design Doc:
+ * ##############
+ * # Design Doc #
+ * ##############
  * The server is broken into the following files:
  *  - main.c: Argument parsing and high-level control
  *  - http.c: HTTP request parsing and response formatting
  *  - server.c: Abstraction over sockets
  *  - threadpool.c: Thread pool and woker queue implementation
  *  - util.c: Misc. utility functions
+ *
+ * Parallelization:
+ * I use a thread pool (implemented in threadpool.{h,c}) for parallelization. It
+ * uses a job queue that allows threads to push tasks (functions and a datum) to
+ * the queue and then distributes these tasks out to threads. It also makes sure
+ * to take a cleanup function in case the queue is destroyed before a given task
+ * is executed. Also, all the worker threads have a signal mask installed that
+ * prevents them frow receiving any signals (except KILL, CONT, and STOP, of
+ * course), so none of the tasks need to worry about such things.
+ *
+ * Abstraction:
+ * All multithreading stuff is contained in threadpool.{h,c}. Other files don't
+ * need to worry about what thread they are running on, they just need to ensure
+ * their functions are multithread safe.
+ *
+ * All HTTP stuff is handled in http.{h,c}. This includes both parsing requests
+ * and formatting responses. None of the other files do any major parsing, they
+ * just call into http.c and its `HTTPRequest` and `HTTPResponse` objects for
+ * that.
+ *
+ * Socket stuff is handled in server.{h,c}. The `Server` object contained in
+ * this file is a thin wrapper around the POSIX sockets API.
+ *
+ * util.{h,c} has some wrappers around the `malloc` family of functions that
+ * ensure that the application crashes "cleanly" if it is out of memory. As some
+ * functions want to catch these kinds of errors, they aren't used everywhere.
+ *
+ * Argument parsing and the request-to-task flow is handled in main.c. This is
+ * also where signal handling stuff is set up to ensure clean shutdown.
+ *
+ * Testing:
+ * I tested the server using cURL and netcat. I used cURL to create various
+ * kinds of syntactically valid requests. I used netcat (along with a text
+ * editor) to create and send syntactically invalid requests (e.g. `nc
+ * 127.0.0.1:8080 <test`).
  */
 #include "http.h"
 #include "server.h"