From fa59ca6064ce9400adb1765deeb960bfe51c2f6f Mon Sep 17 00:00:00 2001
From: yum <yum.food.vr@gmail.com>
Date: Sat, 25 Feb 2023 12:09:53 -0800
Subject: Begin work on custom webserver

oatpp was a crashy mess. Begin making a simple web server from scratch.

* Add Designs/ folder to document nontrivial things like the webserver
  design
---
 Designs/webserver_design.md | 76 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 Designs/webserver_design.md

(limited to 'Designs')

diff --git a/Designs/webserver_design.md b/Designs/webserver_design.md
new file mode 100644
index 0000000..c6b61ef
--- /dev/null
+++ b/Designs/webserver_design.md
@@ -0,0 +1,76 @@
+This is the API design of the webserver supporting the browser source.
+
+I tried oatpp but it had a nasty habit of randomly crashing. I looked at
+crowCPP but it depends on boost, which I have a personal grudge against.
+So I'm making Yet Another Web Framework.
+
+This one supports only the minimum feature set required to implement the
+browser source.
+
+The browser source requires two APIs:
+1. GET /: return index.html (html)
+2. GET /api/transcript: return transcript (json)
+
+```
+enum ContentType {
+  HTTP,
+  JSON,
+};
+
+class WebServer:
+public:
+  WebServer(u16 port)
+
+  // method and path are in-params
+  // payload and type are out-params
+  typedef handler_t std::function<void(const string method, const string path,
+      string& payload, ContentType& type);
+
+  void RegisterPathHandler(string method, string path, handler_t handler);
+
+  Run(volatile bool* run)
+```
+
+We need a way to generate HTML from responses:
+```
+class HTTPMapper:
+  HTTPMapper()
+
+  void Map(const string method, const string path, const string payload, const
+      ContentType type) = 0;
+
+class HTTPMapperHTML : public HTTPMapper:
+  HTTPMapperHTML()
+
+  ...
+
+class HTTPMapperJSON : public HTTPMapper:
+  HTTPMapperJSON()
+
+  ...
+```
+
+We also need a way to parse client-sent HTML:
+```
+class HTTPParser:
+  HTTPParser()
+
+  bool Parse(const string payload)
+
+  string GetMethod();
+  string GetPath();
+  bool GetHeader(const string header, string value)
+
+  bool GetPayload()
+```
+
+WebServer hides HTTPMapper.
+WebServer and HTTPMapper share ContentType.
+
+So we have
+
+  WebCommon.h: shared types
+  HTTPParser.h: supporting API for WebServer
+  HTTPMapper.h: supporting API for WebServer
+  WebServer.h: user-visible API
+
-- 
cgit v1.2.3