From 11ab1630be46dc22ce7ea003ca6c112bc6d09fe2 Mon Sep 17 00:00:00 2001 From: vx-clutch Date: Sun, 28 Dec 2025 16:39:33 -0500 Subject: [PATCH] maint: annotate source code --- modules/doc/doc.go | 1 + modules/server/server.go | 38 +++++++++++++++++++++++++++++++++----- modules/ui/ui.go | 7 +++++++ 3 files changed, 41 insertions(+), 5 deletions(-) diff --git a/modules/doc/doc.go b/modules/doc/doc.go index e00bcda..0740931 100644 --- a/modules/doc/doc.go +++ b/modules/doc/doc.go @@ -9,6 +9,7 @@ import ( "github.com/pkg/browser" ) +/* open documentation in browser */ func Open() error { fmt.Println("Opening documentation in browser") diff --git a/modules/server/server.go b/modules/server/server.go index 1448fae..10c329b 100644 --- a/modules/server/server.go +++ b/modules/server/server.go @@ -17,11 +17,21 @@ import ( "time" ) +/* this is the request data we pass over the bus to the application, via the fes.bus interface */ type reqData struct { path string params map[string]string } +/* performs relavent handling based on the directory passaed + * + * Special directories + * - www/ <= contains lua routes. + * - static/ <= static content accessable at /static/path or /static/dir/path. + * - include/ <= globally accessable lua functions, cannot directly access "fes" right now. + * - archive/ <= contains user facing files such as archives or dists. + * + */ func handleDir(entries []os.DirEntry, dir string, routes map[string]string, base string, isStatic bool) error { for _, entry := range entries { path := filepath.Join(dir, entry.Name()) @@ -59,6 +69,7 @@ func handleDir(entries []os.DirEntry, dir string, routes map[string]string, base return nil } +// TODO(vx-clutch): this should not be a function func loadIncludeModules(L *lua.LState, includeDir string) *lua.LTable { app := L.NewTable() ents, err := os.ReadDir(includeDir) @@ -94,7 +105,8 @@ func loadIncludeModules(L *lua.LState, includeDir string) *lua.LTable { return app } -func loadLua(entry string, cfg *config.AppConfig, requestData reqData) ([]byte, error) { +/* renders the given lua route */ +func renderRoute(entry string, cfg *config.AppConfig, requestData reqData) ([]byte, error) { L := lua.NewState() defer L.Close() @@ -219,6 +231,7 @@ func loadLua(entry string, cfg *config.AppConfig, requestData reqData) ([]byte, return []byte(""), nil } +/* this indexes and generate the page for viewing the archive directory */ func generateArchiveIndex(fsPath string, urlPath string) (string, error) { info, err := os.Stat(fsPath) if err != nil { @@ -309,6 +322,9 @@ func generateArchiveIndex(fsPath string, urlPath string) (string, error) { return b.String(), nil } +/* generates the data for the not found page. Checks for user-defined source in this order + * 404.lua => 404.md => 404.html => default. + */ func generateNotFoundData(cfg *config.AppConfig) []byte { notFoundData := []byte(` @@ -320,9 +336,13 @@ func generateNotFoundData(cfg *config.AppConfig) []byte { `) if _, err := os.Stat(filepath.Join("www", "404.lua")); err == nil { - if nf, err := loadLua("www/404.lua", cfg, reqData{}); err == nil { + if nf, err := renderRoute("www/404.lua", cfg, reqData{}); err == nil { notFoundData = nf } + } else if _, err := os.Stat("www/404.md"); err == nil { + if buf, err := os.ReadFile("www/404.html"); err == nil { + notFoundData = []byte(markdownToHTML(string(buf))) + } } else if _, err := os.Stat("www/404.html"); err == nil { if buf, err := os.ReadFile("www/404.html"); err == nil { notFoundData = buf @@ -331,6 +351,7 @@ func generateNotFoundData(cfg *config.AppConfig) []byte { return notFoundData } +/* helper to load all special directories */ func loadDirs() map[string]string { routes := make(map[string]string) @@ -355,6 +376,7 @@ func loadDirs() map[string]string { return routes } +/* helper to parse the Fes.toml and generate config */ func parseConfig() config.AppConfig { tomlDocument, err := os.ReadFile("Fes.toml") if err != nil { @@ -372,15 +394,21 @@ func parseConfig() config.AppConfig { return cfg } -func readArchive(w http.ResponseWriter, route string) { +/* helper to read the archive files */ +func readArchive(w http.ResponseWriter, route string) error { fsPath := "." + route if info, err := os.Stat(fsPath); err == nil && info.IsDir() { if page, err := generateArchiveIndex(fsPath, route); err == nil { w.Write([]byte(page)) + return nil + } else { + return err } } + return nil } +/* start the Fes server */ func Start(dir string) error { if err := os.Chdir(dir); err != nil { return ui.Error(fmt.Sprintf("failed to change directory to %s", dir), err) @@ -405,7 +433,7 @@ func Start(dir string) error { route = r.URL.Path if strings.HasPrefix(route, "/archive") { - readArchive(w, route) + err = readArchive(w, route) } else { w.WriteHeader(http.StatusNotFound) w.Write([]byte(notFoundData)) @@ -422,7 +450,7 @@ func Start(dir string) error { var data []byte if strings.HasSuffix(route, ".lua") { - data, err = loadLua(route, &cfg, reqData{path: r.URL.Path, params: params}) + data, err = renderRoute(route, &cfg, reqData{path: r.URL.Path, params: params}) } else if strings.HasSuffix(route, ".md") { data, err = os.ReadFile(route) data = []byte(markdownToHTML(string(data))) diff --git a/modules/ui/ui.go b/modules/ui/ui.go index 71e14d9..b5d00a5 100644 --- a/modules/ui/ui.go +++ b/modules/ui/ui.go @@ -11,6 +11,7 @@ import ( "github.com/fatih/color" ) +/* print out the current path (route) and relevant error */ func Path(path string, err error) { path = strings.TrimPrefix(path, "/") @@ -29,29 +30,35 @@ func Path(path string, err error) { } } +/* print general system warning */ func Warning(msg string, err error) error { fmt.Printf("%s: %s: %v\n", version.PROGRAM_NAME, color.MagentaString("warning"), err) return err } +/* print general system error */ func Error(msg string, err error) error { fmt.Printf("%s: %s: %v\n", version.PROGRAM_NAME, color.RedString("error"), err) return err } +/* print fatality and panic */ func Fatal(msg string, err error) error { fmt.Printf("%s: %s: %v\n", version.PROGRAM_NAME, color.RedString("fatal"), err) panic(err) } +/* print message using the ok status color */ func OK(msg string) { color.Green(msg) } +/* print message using the warning status color */ func WARN(msg string) { color.Magenta(msg) } +/* print message using the error status color */ func ERROR(msg string) { color.Red(msg) }