home: imp docs

internal/home/auth.go

@@ -57,6 +57,12 @@ type Auth struct {
 	sessionTTL  uint32
 }
 
+// webUser represents a user of the Web UI.
+type webUser struct {
+	Name         string `yaml:"name"`
+	PasswordHash string `yaml:"password"`
+}
+
 // InitAuth - create a global object
 func InitAuth(dbFilename string, users []webUser, sessionTTL uint32, rateLimiter *authRateLimiter) *Auth {
 	log.Info("Initializing auth module: %s", dbFilename)

internal/home/authhttp.go

@@ -26,12 +26,7 @@ const cookieTTL = 365 * timeutil.Day
 // sessionCookieName is the name of the session cookie.
 const sessionCookieName = "agh_session"
 
-// webUser represents a user of the Web UI.
-type webUser struct {
-	Name         string `yaml:"name"`
-	PasswordHash string `yaml:"password"`
-}
-
+// loginJSON is the JSON structure for authentication.
 type loginJSON struct {
 	Name     string `json:"name"`
 	Password string `json:"password"`
@@ -134,6 +129,7 @@ func writeErrorWithIP(
 	http.Error(w, text, code)
 }
 
+// handleLogin is the handler for the POST /control/login HTTP API.
 func handleLogin(w http.ResponseWriter, r *http.Request) {
 	req := loginJSON{}
 	err := json.NewDecoder(r.Body).Decode(&req)
@@ -204,6 +200,7 @@ func handleLogin(w http.ResponseWriter, r *http.Request) {
 	aghhttp.OK(w)
 }
 
+// handleLogout is the handler for the GET /control/logout HTTP API.
 func handleLogout(w http.ResponseWriter, r *http.Request) {
 	respHdr := w.Header()
 	c, err := r.Cookie(sessionCookieName)
@@ -239,20 +236,9 @@ func RegisterAuthHandlers() {
 	httpRegister(http.MethodGet, "/control/logout", handleLogout)
 }
 
-// authLogPrefix prepares a prefix with IP address for logging and logs the IP
-// parsing error if any.
-func authLogPrefix(addr string) (pref string) {
-	ip, err := netutil.SplitHost(addr)
-	if err != nil {
-		log.Error("auth: getting remote address: %s", err)
-	}
-
-	return fmt.Sprintf("auth: raddr %s", ip)
-}
-
-// optionalAuthThird return true if user should authenticate first.
+// optionalAuthThird returns true if a user should authenticate first.
 func optionalAuthThird(w http.ResponseWriter, r *http.Request) (mustAuth bool) {
-	pref := authLogPrefix(r.RemoteAddr)
+	pref := fmt.Sprintf("auth: raddr %s", r.RemoteAddr)
 
 	if glProcessCookie(r) {
 		log.Debug("%s: authentication is handled by gl-inet submodule", pref)
@@ -287,7 +273,7 @@ func optionalAuthThird(w http.ResponseWriter, r *http.Request) (mustAuth bool) {
 
 	if p := r.URL.Path; p == "/" || p == "/index.html" {
 		if glProcessRedirect(w, r) {
-			log.Debug("%s: redirected to login page by GL-Inet submodule", pref)
+			log.Debug("%s: redirected to login page by gl-inet submodule", pref)
 		} else {
 			log.Debug("%s: redirected to login page", pref)
 			http.Redirect(w, r, "login.html", http.StatusFound)
@@ -320,8 +306,7 @@ func optionalAuth(
 					return
 				}
 
-				pref := authLogPrefix(r.RemoteAddr)
-				log.Debug("%s: invalid cookie value: %q", pref, cookie)
+				log.Debug("auth: raddr %s: invalid cookie value: %q", r.RemoteAddr, cookie)
 			}
 		} else if isPublicResource(p) {
 			// Process as usual, no additional auth requirements.
@@ -353,14 +338,17 @@ func isPublicResource(p string) (ok bool) {
 	return isAsset || isLogin
 }
 
+// authHandler is a helper structure that implements [http.Handler].
 type authHandler struct {
 	handler http.Handler
 }
 
+// ServeHTTP implements the [http.Handler] interface for *authHandler.
 func (a *authHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	optionalAuth(a.handler.ServeHTTP)(w, r)
 }
 
+// optionalAuthHandler returns a authentication handler.
 func optionalAuthHandler(handler http.Handler) http.Handler {
 	return &authHandler{handler}
 }
@@ -436,22 +424,25 @@ func (a *Auth) getCurrentUser(r *http.Request) (u webUser) {
 	return webUser{}
 }
 
-// GetUsers - get users
-func (a *Auth) GetUsers() []webUser {
+// Users returns a list of users.
+func (a *Auth) Users() (users []webUser) {
 	a.lock.Lock()
-	users := a.users
-	a.lock.Unlock()
+	defer a.lock.Unlock()
+
+	users = make([]webUser, len(a.users))
+	copy(users, a.users)
+
 	return users
 }
 
-// AuthRequired - if authentication is required
+// AuthRequired returns true if a authentication is required.
 func (a *Auth) AuthRequired() bool {
 	if GLMode {
 		return true
 	}
 
 	a.lock.Lock()
-	r := (len(a.users) != 0)
-	a.lock.Unlock()
-	return r
+	defer a.lock.Unlock()
+
+	return len(a.users) != 0
 }

internal/home/config.go

@@ -587,7 +587,7 @@ func (c *configuration) write() (err error) {
 	defer c.Unlock()
 
 	if Context.auth != nil {
-		config.Users = Context.auth.GetUsers()
+		config.Users = Context.auth.Users()
 	}
 
 	if Context.tls != nil {