From b86be4c749888383be03219ecde66c92c2ecf943 Mon Sep 17 00:00:00 2001
From: Arthur Lu <root@tronnet.net>
Date: Tue, 18 Nov 2025 19:36:05 +0000
Subject: [PATCH] add a bunch of comments to important code

---
 app/app.go            |  4 ++++
 app/common/types.go   | 18 ++++++++++++++++--
 app/common/utils.go   | 13 +++----------
 app/routes/account.go |  3 +++
 app/routes/index.go   | 34 +++++++++++++++++++++-------------
 app/routes/login.go   |  1 -
 6 files changed, 47 insertions(+), 26 deletions(-)

diff --git a/app/app.go b/app/app.go
index 312bce9..81d97b7 100644
--- a/app/app.go
+++ b/app/app.go
@@ -14,6 +14,7 @@ import (
 func Run(configPath *string) {
 	common.Global = common.GetConfig(*configPath)
 
+	// setup static resources
 	gin.SetMode(gin.ReleaseMode)
 	router := gin.Default()
 	m := common.InitMinify()
@@ -21,6 +22,7 @@ func Run(configPath *string) {
 	html := common.MinifyStatic(m, web.Templates)
 	common.TMPL = common.LoadHTMLToGin(router, html)
 
+	// dynamic routes for pages and page fragments
 	router.GET("/", routes.HandleGETIndex)
 	router.GET("/index", routes.HandleGETIndex)
 	router.GET("/index/instances", routes.HandleGETInstancesFragment)
@@ -35,9 +37,11 @@ func Run(configPath *string) {
 	router.GET("/login", routes.HandleGETLogin)
 	router.GET("/settings", routes.HandleGETSettings)
 
+	// run on all interfaces with port
 	log.Fatal(router.Run(fmt.Sprintf("0.0.0.0:%d", common.Global.Port)))
 }
 
+// setup static resources under web (css, images, modules, scripts)
 func ServeStatic(router *gin.Engine, m *minify.M) {
 	css := common.MinifyStatic(m, web.CSS_fs)
 	router.GET("/css/*css", func(c *gin.Context) {
diff --git a/app/common/types.go b/app/common/types.go
index aeaa9c6..f38ad5c 100644
--- a/app/common/types.go
+++ b/app/common/types.go
@@ -1,5 +1,9 @@
 package common
 
+import "html/template"
+
+var Global Config
+
 type Config struct {
 	Port         int    `json:"listenPort"`
 	Organization string `json:"organization"`
@@ -8,11 +12,23 @@ type Config struct {
 	API          string `json:"apiurl"`
 }
 
+// variable for html template root
+// generated from LoadHTMLToGin
+var TMPL *template.Template
+
+// static served file type containing data and mimetype
 type StaticFile struct {
 	Data     string
 	MimeType MimeType
 }
 
+// parsed vmpath data (ie node/type/vmid)
+type VMPath struct {
+	Node string
+	Type string
+	VMID string
+}
+
 // type used for templated <select>
 type Select struct {
 	ID       string
@@ -27,8 +43,6 @@ type Option struct {
 	Display  string
 }
 
-type RequestType int
-
 type RequestContext struct {
 	Cookies map[string]string
 }
diff --git a/app/common/utils.go b/app/common/utils.go
index 020780c..1561b3f 100644
--- a/app/common/utils.go
+++ b/app/common/utils.go
@@ -20,15 +20,7 @@ import (
 	"github.com/tdewolff/minify/v2"
 )
 
-var TMPL *template.Template
-var Global Config
-
-type VMPath struct {
-	Node string
-	Type string
-	VMID string
-}
-
+// get config file from configPath
 func GetConfig(configPath string) Config {
 	content, err := os.ReadFile(configPath)
 	if err != nil {
@@ -42,6 +34,7 @@ func GetConfig(configPath string) Config {
 	return config
 }
 
+// initialize minifier using the meta types specified
 func InitMinify() *minify.M {
 	m := minify.New()
 	for _, v := range MimeTypes {
@@ -125,7 +118,7 @@ func LoadHTMLToGin(engine *gin.Engine, html map[string]StaticFile) *template.Tem
 		},
 	}
 	tmpl := template.Must(root, LoadAndAddToRoot(engine.FuncMap, root, html))
-	engine.SetHTMLTemplate(tmpl)
+	engine.SetHTMLTemplate(root)
 	return tmpl
 }
 
diff --git a/app/routes/account.go b/app/routes/account.go
index 73bd7a2..499d125 100644
--- a/app/routes/account.go
+++ b/app/routes/account.go
@@ -21,12 +21,14 @@ type Account struct {
 	Resources map[string]map[string]any
 }
 
+// numerical constraint
 type Constraint struct {
 	Max   int64
 	Used  int64
 	Avail int64
 }
 
+// match constraint
 type Match struct {
 	Name  string
 	Match string
@@ -107,6 +109,7 @@ func HandleGETAccount(c *gin.Context) {
 			return
 		}
 
+		// for each resource category, create a resource chart
 		for category, resources := range account.Resources {
 			for resource, v := range resources {
 				switch t := v.(type) {
diff --git a/app/routes/index.go b/app/routes/index.go
index baf480a..f651e5e 100644
--- a/app/routes/index.go
+++ b/app/routes/index.go
@@ -10,13 +10,7 @@ import (
 	"github.com/go-viper/mapstructure/v2"
 )
 
-// used in constructing instance cards in index
-type Node struct {
-	Node   string `json:"node"`
-	Status string `json:"status"`
-}
-
-// used in constructing instance cards in index
+// primary type used in constructing instance cards in index
 type InstanceCard struct {
 	VMID        uint
 	Name        string
@@ -29,6 +23,12 @@ type InstanceCard struct {
 	BackupsPath string
 }
 
+// used in constructing instance cards in index
+type Node struct {
+	Node   string `json:"node"`
+	Status string `json:"status"`
+}
+
 // used in retriving cluster tasks
 type Task struct {
 	Type    string
@@ -92,24 +92,24 @@ func GetClusterResources(auth common.Auth) (map[uint]InstanceCard, map[string]No
 	if err != nil {
 		return nil, nil, err
 	}
-	if code != 200 { // if we did not successfully retrieve resources, then return 500 because auth was 1 but was invalid somehow
+	if code != 200 { // if we did not successfully retrieve resources, then return the error because auth was 1 but was invalid somehow
 		return nil, nil, fmt.Errorf("request to /cluster/resources resulted in %+v", res)
 	}
 
 	instances := map[uint]InstanceCard{}
 	nodes := map[string]Node{}
 
-	// if we successfully retrieved the resources, then process it and return index
+	// parse /proxmox/cluster/resources to separate instances and nodes
 	for _, v := range body["data"].([]any) {
 		m := v.(map[string]any)
-		if m["type"] == "node" {
+		if m["type"] == "node" { // if type is node -> parse as Node object
 			node := Node{}
 			err := mapstructure.Decode(v, &node)
 			if err != nil {
 				return nil, nil, err
 			}
 			nodes[node.Node] = node
-		} else if m["type"] == "lxc" || m["type"] == "qemu" {
+		} else if m["type"] == "lxc" || m["type"] == "qemu" { // if type is lxc or qemu -> parse as InstanceCard object
 			instance := InstanceCard{}
 			err := mapstructure.Decode(v, &instance)
 			if err != nil {
@@ -118,16 +118,21 @@ func GetClusterResources(auth common.Auth) (map[uint]InstanceCard, map[string]No
 			instances[instance.VMID] = instance
 		}
 	}
+	// once all basic instance and node stuff is parsed, go back and fill in cross referenced data
 	for vmid, instance := range instances {
-		nodestatus := nodes[instance.Node].Status
-		instance.NodeStatus = nodestatus
+		// set instance's node status
+		instance.NodeStatus = nodes[instance.Node].Status
+		// set instance's config link path
 		instance.ConfigPath = fmt.Sprintf("config?node=%s&type=%s&vmid=%d", instance.Node, instance.Type, instance.VMID)
+		// set the instance's console link path
 		if instance.Type == "qemu" {
 			instance.ConsolePath = fmt.Sprintf("%s/?console=kvm&vmid=%d&vmname=%s&node=%s&resize=off&cmd=&novnc=1", common.Global.PVE, instance.VMID, instance.Name, instance.Node)
 		} else if instance.Type == "lxc" {
 			instance.ConsolePath = fmt.Sprintf("%s/?console=lxc&vmid=%d&vmname=%s&node=%s&resize=off&cmd=&xtermjs=1", common.Global.PVE, instance.VMID, instance.Name, instance.Node)
 		}
+		// set the instance's backups link path
 		instance.BackupsPath = fmt.Sprintf("backups?node=%s&type=%s&vmid=%d", instance.Node, instance.Type, instance.VMID)
+		// save back to instances map
 		instances[vmid] = instance
 	}
 
@@ -143,7 +148,9 @@ func GetClusterResources(auth common.Auth) (map[uint]InstanceCard, map[string]No
 	most_recent_task := map[uint]uint{}
 	expected_state := map[uint]string{}
 
+	// iterate through recent user accessible tasks to find the task most recently made on an instance
 	for _, v := range body["data"].([]any) {
+		// parse task as Task object
 		task := Task{}
 		err := mapstructure.Decode(v, &task)
 		if err != nil {
@@ -177,6 +184,7 @@ func GetClusterResources(auth common.Auth) (map[uint]InstanceCard, map[string]No
 		}
 	}
 
+	// iterate through the instances with recent tasks, refetch their state from a more reliable source
 	for vmid, expected_state := range expected_state { // for the expected states from recent tasks
 		if instances[vmid].Status != expected_state { // if the current node's state from /cluster/resources differs from expected state
 			// get /status/current which is updated faster than /cluster/resources
diff --git a/app/routes/login.go b/app/routes/login.go
index cae154f..f7a3c3a 100644
--- a/app/routes/login.go
+++ b/app/routes/login.go
@@ -26,7 +26,6 @@ func GetLoginRealms() ([]Realm, error) {
 
 	ctx := common.RequestContext{
 		Cookies: nil,
-		//Body:    map[string]any{},
 	}
 	body := map[string]any{}
 	res, code, err := common.RequestGetAPI("/proxmox/access/domains", ctx, &body)