add documentation

cookies.go

@@ -21,19 +21,24 @@ import (
 	"strings"
 )
 
+// ErrValueTooLong indicates that the cookie value exceeds the allowed length limit.
+// ErrInvalidValue signifies that the cookie value is in an invalid format.
 var (
 	ErrValueTooLong = errors.New("cookie value too long")
 	ErrInvalidValue = errors.New("invalid cookie value")
 )
 
-// Declare the User type.
+// UserCookie represents a structure to hold user-specific data stored in a cookie, including Email and Token fields.
 type UserCookie struct {
 	Email string
 	Token string
 }
 
+// secretcookie is a global variable used to store the decoded secret key for encrypting and decrypting cookies.
 var secretcookie []byte
 
+// GetCookie retrieves and decrypts the user cookie from the provided HTTP request and returns it as a UserCookie.
+// Returns an error if the cookie retrieval, decryption, or decoding process fails.
 func GetCookie(r *http.Request) (UserCookie, error) {
 
 	var err error
@@ -78,6 +83,7 @@ func GetCookie(r *http.Request) (UserCookie, error) {
 
 }
 
+// SetCookie sets an encrypted cookie with a user's email and token, using gob encoding for data serialization.
 func SetCookie(w http.ResponseWriter, email string, token string) error {
 	// Initialize a User struct containing the data that we want to store in the
 	// cookie.
@@ -138,6 +144,8 @@ func SetCookie(w http.ResponseWriter, email string, token string) error {
 	return nil
 }
 
+// CookieWrite writes a secure HTTP cookie to the response writer after base64 encoding its value.
+// Returns ErrValueTooLong if the cookie string exceeds the 4096-byte size limit.
 func CookieWrite(w http.ResponseWriter, cookie http.Cookie) error {
 	// Encode the cookie value using base64.
 	cookie.Value = base64.URLEncoding.EncodeToString([]byte(cookie.Value))
@@ -154,6 +162,8 @@ func CookieWrite(w http.ResponseWriter, cookie http.Cookie) error {
 	return nil
 }
 
+// CookieRead retrieves a base64-encoded cookie value by name from the HTTP request and decodes it.
+// Returns the decoded value as a string or an error if the cookie is not found or the value is invalid.
 func CookieRead(r *http.Request, name string) (string, error) {
 	// Read the cookie as normal.
 	cookie, err := r.Cookie(name)
@@ -173,6 +183,9 @@ func CookieRead(r *http.Request, name string) (string, error) {
 	return string(value), nil
 }
 
+// CookieWriteEncrypted encrypts the cookie's value using AES-GCM and writes it to the HTTP response writer.
+// The cookie name is authenticated along with its value.
+// It returns an error if encryption fails or the cookie exceeds the maximum allowed length.
 func CookieWriteEncrypted(w http.ResponseWriter, cookie http.Cookie, secretKey []byte) error {
 	// Create a new AES cipher block from the secret key.
 	block, err := aes.NewCipher(secretKey)
@@ -213,6 +226,8 @@ func CookieWriteEncrypted(w http.ResponseWriter, cookie http.Cookie, secretKey [
 	return CookieWrite(w, cookie)
 }
 
+// CookieReadEncrypted reads an encrypted cookie, decrypts its value using AES-GCM, and validates its name before returning.
+// Returns the plaintext cookie value or an error if decryption or validation fails.
 func CookieReadEncrypted(r *http.Request, name string, secretKey []byte) (string, error) {
 	// Read the encrypted value from the cookie as normal.
 	encryptedValue, err := CookieRead(r, name)