From dc53ee66cbc1d0e2ff025b0155f75c1e5de6c0de Mon Sep 17 00:00:00 2001
From: Antonio De Lucreziis <antonio.delucreziis@gmail.com>
Date: Tue, 14 Jun 2022 01:34:27 +0200
Subject: [PATCH] Added some comments

---
 auth/auth.go | 14 ++++++++++++++
 auth/ldap.go |  5 +++++
 main.go      |  4 +++-
 3 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/auth/auth.go b/auth/auth.go
index 5c39517..9de21d1 100644
--- a/auth/auth.go
+++ b/auth/auth.go
@@ -2,8 +2,10 @@ package auth
 
 import "fmt"
 
+// ErrInvalidSession is thrown when an AuthenticatorService is given a missing or invalid session token
 var ErrInvalidSession = fmt.Errorf(`invalid session token`)
 
+// User represents a user returned from AuthenticatorService
 type User struct {
 	Username string `json:"username"`
 	Name     string `json:"name"`
@@ -12,6 +14,7 @@ type User struct {
 	Email    string `json:"email"`
 }
 
+// WithDefaultFullName is a utility that returns a copy of the given user with the full name set to the concatenation of the name and surname of the user.
 func (u User) WithDefaultFullName() User {
 	return User{
 		Username: u.Username,
@@ -23,18 +26,28 @@ func (u User) WithDefaultFullName() User {
 	}
 }
 
+// Session represents a session returned from AuthenticatorService
 type Session struct {
 	Username string `json:"username"`
 	Token    string `json:"token"`
 }
 
+// AuthenticatorService can login users using a separate http service or a temporary in memory store. When a user logs in the auth service returns a session token that can be used to read and modify user properties without having to re-send the user password. (TODO: Not yet implemented: this token has to be renewed every so often otherwise it lasts just a couple of days)
 type AuthenticatorService interface {
+	// GetUser retrieves the user info given the username
 	GetUser(username string) (*User, error)
+
+	// GetUsers retrieves the full user list from the authentication service
 	GetUsers() ([]*User, error)
+
+	// GetSession retrieves the user session associated to a session token
 	GetSession(token string) (*Session, error)
+
+	// Login tries to log in a user given username and password and if successful returns a new user session
 	Login(username, password string) (*Session, error)
 }
 
+// UserForSession returns the user (object) linked to a session token, this is just a shortcut for calling [AuthenticatorService.GetSession] and then [AuthenticatorService.GetUser]
 func UserForSession(as AuthenticatorService, token string) (*User, error) {
 	session, err := as.GetSession(token)
 	if err != nil {
@@ -49,6 +62,7 @@ func UserForSession(as AuthenticatorService, token string) (*User, error) {
 	return user, nil
 }
 
+// New create an AuthenticatorService given an "host" string, if ":memory:" then this just returns an example AuthenticatorService using the [auth.Memory] implementation, otherwise for now this defaults to [auth.LDAPAuthService]
 func New(host string) AuthenticatorService {
 	if host == ":memory:" {
 		return exampleMemoryUsers
diff --git a/auth/ldap.go b/auth/ldap.go
index 16f092e..1fc14c0 100644
--- a/auth/ldap.go
+++ b/auth/ldap.go
@@ -9,6 +9,7 @@ import (
 	"path"
 )
 
+// ldapUser represents an LDAP User, most fields are inherited from [auth.User]
 type ldapUser struct {
 	User
 	NumericId int    `json:"id"`
@@ -16,6 +17,7 @@ type ldapUser struct {
 	Gecos     string `json:"gecos"`
 }
 
+// AsUser converts an [ldapUser] to an instance of [auth.User]
 func (u ldapUser) AsUser() *User {
 	return &User{
 		Username: u.Username,
@@ -27,10 +29,12 @@ func (u ldapUser) AsUser() *User {
 	}
 }
 
+// LDAPAuthService just holds the remote host of the HTTP LDAP service to make requests to
 type LDAPAuthService struct {
 	Host string
 }
 
+// doGetRequest is a utility to make HTTP GET requests
 func (a *LDAPAuthService) doGetRequest(url string, response interface{}) error {
 	req, err := http.NewRequest(
 		"GET", path.Join(a.Host, "ldap", url), bytes.NewBuffer([]byte("")),
@@ -55,6 +59,7 @@ func (a *LDAPAuthService) doGetRequest(url string, response interface{}) error {
 	return nil
 }
 
+// doPostRequest is a utility to make HTTP POST requests
 func (a *LDAPAuthService) doPostRequest(url string, request interface{}, response interface{}) error {
 	jsonStr, err := json.Marshal(request)
 	if err != nil {
diff --git a/main.go b/main.go
index 84f6328..adb9c2f 100644
--- a/main.go
+++ b/main.go
@@ -32,13 +32,15 @@ func main() {
 
 	app.Use(logger.New())
 	app.Use(recover.New())
+
+	// Remove trailing slash from URLs
 	app.Use(redirect.New(redirect.Config{
 		Rules: map[string]string{
 			"/*/": "/$1",
 		},
 	}))
 
-	// Static content
+	// Serve content statically from "./public", mounted on the "/public/" route
 	app.Static("/public/", "./public")
 
 	authService := auth.New(config.AuthServiceHost)