From 356c5be2c6bd33792d5ebcbc69b2af42bd3c5023 Mon Sep 17 00:00:00 2001
From: LordMathis <matus@namesny.com>
Date: Sun, 26 Oct 2025 10:34:36 +0100
Subject: [PATCH] Improve comments

---
 pkg/server/handlers.go          | 9 +++++++++
 pkg/server/handlers_backends.go | 4 +++-
 pkg/server/handlers_nodes.go    | 2 +-
 pkg/server/handlers_openai.go   | 4 ++--
 4 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/pkg/server/handlers.go b/pkg/server/handlers.go
index 3a33a8f..f341270 100644
--- a/pkg/server/handlers.go
+++ b/pkg/server/handlers.go
@@ -12,11 +12,13 @@ import (
 	"time"
 )
 
+// errorResponse represents an error response returned by the API
 type errorResponse struct {
 	Error   string `json:"error"`
 	Details string `json:"details,omitempty"`
 }
 
+// writeError writes a JSON error response with the specified HTTP status code
 func writeError(w http.ResponseWriter, status int, code, details string) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)
@@ -25,6 +27,7 @@ func writeError(w http.ResponseWriter, status int, code, details string) {
 	}
 }
 
+// writeJSON writes a JSON response with the specified HTTP status code
 func writeJSON(w http.ResponseWriter, status int, data any) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)
@@ -33,6 +36,7 @@ func writeJSON(w http.ResponseWriter, status int, data any) {
 	}
 }
 
+// writeText writes a plain text response with the specified HTTP status code
 func writeText(w http.ResponseWriter, status int, data string) {
 	w.Header().Set("Content-Type", "text/plain")
 	w.WriteHeader(status)
@@ -41,12 +45,14 @@ func writeText(w http.ResponseWriter, status int, data string) {
 	}
 }
 
+// Handler provides HTTP handlers for the llamactl server API
 type Handler struct {
 	InstanceManager manager.InstanceManager
 	cfg             config.AppConfig
 	httpClient      *http.Client
 }
 
+// NewHandler creates a new Handler instance with the provided instance manager and configuration
 func NewHandler(im manager.InstanceManager, cfg config.AppConfig) *Handler {
 	return &Handler{
 		InstanceManager: im,
@@ -57,6 +63,7 @@ func NewHandler(im manager.InstanceManager, cfg config.AppConfig) *Handler {
 	}
 }
 
+// getInstance retrieves an instance by name from the request query parameters
 func (h *Handler) getInstance(r *http.Request) (*instance.Instance, error) {
 	name := r.URL.Query().Get("name")
 	validatedName, err := validation.ValidateInstanceName(name)
@@ -72,6 +79,8 @@ func (h *Handler) getInstance(r *http.Request) (*instance.Instance, error) {
 	return inst, nil
 }
 
+// ensureInstanceRunning ensures the instance is running by starting it if on-demand start is enabled
+// It handles LRU eviction when the maximum number of running instances is reached
 func (h *Handler) ensureInstanceRunning(inst *instance.Instance) error {
 	options := inst.GetOptions()
 	allowOnDemand := options != nil && options.OnDemandStart != nil && *options.OnDemandStart
diff --git a/pkg/server/handlers_backends.go b/pkg/server/handlers_backends.go
index 84c15b5..e6a2aa5 100644
--- a/pkg/server/handlers_backends.go
+++ b/pkg/server/handlers_backends.go
@@ -10,11 +10,12 @@ import (
 	"strings"
 )
 
-// ParseCommandRequest represents the request body for command parsing
+// ParseCommandRequest represents the request body for backend command parsing
 type ParseCommandRequest struct {
 	Command string `json:"command"`
 }
 
+// validateLlamaCppInstance validates that the instance specified in the request is a llama.cpp instance
 func (h *Handler) validateLlamaCppInstance(r *http.Request) (*instance.Instance, error) {
 	inst, err := h.getInstance(r)
 	if err != nil {
@@ -33,6 +34,7 @@ func (h *Handler) validateLlamaCppInstance(r *http.Request) (*instance.Instance,
 	return inst, nil
 }
 
+// stripLlamaCppPrefix removes the llama.cpp proxy prefix from the request URL path
 func (h *Handler) stripLlamaCppPrefix(r *http.Request, instName string) {
 	// Strip the "/llama-cpp/<name>" prefix from the request URL
 	prefix := fmt.Sprintf("/llama-cpp/%s", instName)
diff --git a/pkg/server/handlers_nodes.go b/pkg/server/handlers_nodes.go
index ed6c827..7c84b0a 100644
--- a/pkg/server/handlers_nodes.go
+++ b/pkg/server/handlers_nodes.go
@@ -6,7 +6,7 @@ import (
 	"github.com/go-chi/chi/v5"
 )
 
-// NodeResponse represents a sanitized node configuration for API responses
+// NodeResponse represents a node configuration in API responses
 type NodeResponse struct {
 	Address string `json:"address"`
 }
diff --git a/pkg/server/handlers_openai.go b/pkg/server/handlers_openai.go
index da2ebc3..35ac746 100644
--- a/pkg/server/handlers_openai.go
+++ b/pkg/server/handlers_openai.go
@@ -8,13 +8,13 @@ import (
 	"net/http"
 )
 
-// OpenAIListInstancesResponse represents the response structure for listing instances (models) in OpenAI format
+// OpenAIListInstancesResponse represents the response structure for listing instances (models) in OpenAI-compatible format
 type OpenAIListInstancesResponse struct {
 	Object string           `json:"object"`
 	Data   []OpenAIInstance `json:"data"`
 }
 
-// OpenAIInstance represents a single instance (model) in OpenAI format
+// OpenAIInstance represents a single instance (model) in OpenAI-compatible format
 type OpenAIInstance struct {
 	ID      string `json:"id"`
 	Object  string `json:"object"`