From 0893e1ac80f3707fdc67d6099829502f7c3d343a Mon Sep 17 00:00:00 2001 From: Michael Mayer Date: Thu, 2 Oct 2025 16:15:18 +0200 Subject: [PATCH] Docs: Improve code comments in internal/entity/auth*.go Signed-off-by: Michael Mayer --- internal/entity/auth_client.go | 6 +++--- internal/entity/auth_session.go | 4 ++-- internal/entity/auth_session_delete.go | 8 ++++---- internal/entity/auth_session_login.go | 6 +++--- internal/entity/auth_tokens.go | 3 ++- internal/entity/auth_user.go | 4 ++-- internal/entity/auth_user_cli.go | 4 ++-- internal/entity/auth_user_default.go | 2 +- internal/entity/auth_user_details.go | 6 +++--- internal/entity/auth_user_settings.go | 6 +++--- internal/entity/auth_user_share.go | 6 +++--- 11 files changed, 28 insertions(+), 27 deletions(-) diff --git a/internal/entity/auth_client.go b/internal/entity/auth_client.go index ca5fe29ff..d36439cae 100644 --- a/internal/entity/auth_client.go +++ b/internal/entity/auth_client.go @@ -25,10 +25,10 @@ const ( ClientUID = byte('c') ) -// Clients represents a list of client applications. +// Clients is a convenience alias for slices of Client. type Clients []Client -// Client represents a client application. +// Client represents an OAuth/OpenID client registered with PhotoPrism. type Client struct { ClientUID string `gorm:"type:VARBINARY(42);primary_key;auto_increment:false;" json:"-" yaml:"ClientUID"` NodeUUID string `gorm:"type:VARBINARY(64);index;default:'';" json:"NodeUUID,omitempty" yaml:"NodeUUID,omitempty"` @@ -60,7 +60,7 @@ func (Client) TableName() string { return "auth_clients" } -// NewClient returns a new client application instance. +// NewClient returns a new client application instance with default ACL role and authentication settings. func NewClient() *Client { return &Client{ UserUID: "", diff --git a/internal/entity/auth_session.go b/internal/entity/auth_session.go index fad1993e5..624797a38 100644 --- a/internal/entity/auth_session.go +++ b/internal/entity/auth_session.go @@ -30,10 +30,10 @@ const ( UnknownIP = limiter.DefaultIP ) -// Sessions represents a list of sessions. +// Sessions is a convenience alias for slices of Session. type Sessions []Session -// Session represents a User session. +// Session represents an authenticated user or client session persisted in the database. type Session struct { ID string `gorm:"type:VARBINARY(2048);primary_key;auto_increment:false;" json:"-" yaml:"ID"` authToken string `gorm:"-" yaml:"-"` diff --git a/internal/entity/auth_session_delete.go b/internal/entity/auth_session_delete.go index 61e37759a..980ec5642 100644 --- a/internal/entity/auth_session_delete.go +++ b/internal/entity/auth_session_delete.go @@ -11,7 +11,7 @@ import ( "github.com/photoprism/photoprism/pkg/time/unix" ) -// DeleteSession permanently deletes a session. +// DeleteSession permanently deletes the session and any sessions that were derived from it. func DeleteSession(s *Session) error { if s == nil { return nil @@ -38,7 +38,7 @@ func DeleteSession(s *Session) error { return UnscopedDb().Delete(s).Error } -// DeleteChildSessions deletes any other sessions that were authenticated with the specified session. +// DeleteChildSessions deletes sessions that authenticated via the provided parent session ID. func DeleteChildSessions(s *Session) (deleted int) { if s == nil { return 0 @@ -64,7 +64,7 @@ func DeleteChildSessions(s *Session) (deleted int) { return deleted } -// DeleteClientSessions deletes client sessions above the specified limit. +// DeleteClientSessions deletes sessions for the client beyond the configured retention limit. func DeleteClientSessions(client *Client, authMethod authn.MethodType, limit int64) (deleted int) { if limit < 0 { return 0 @@ -110,7 +110,7 @@ func DeleteClientSessions(client *Client, authMethod authn.MethodType, limit int return deleted } -// DeleteExpiredSessions deletes all expired sessions. +// DeleteExpiredSessions removes sessions whose expiration timestamp has passed. func DeleteExpiredSessions() (deleted int) { found := Sessions{} diff --git a/internal/entity/auth_session_login.go b/internal/entity/auth_session_login.go index 91a75eb00..37c8ec2a0 100644 --- a/internal/entity/auth_session_login.go +++ b/internal/entity/auth_session_login.go @@ -18,7 +18,7 @@ import ( "github.com/photoprism/photoprism/pkg/txt" ) -// Auth checks if the credentials are valid and returns the user and authentication provider. +// Auth validates login credentials and returns the authenticated user plus provider/method metadata. var Auth = func(frm form.Login, s *Session, c *gin.Context) (user *User, provider authn.ProviderType, method authn.MethodType, err error) { // Get sanitized username from login form. nameName := frm.CleanUsername() @@ -39,7 +39,7 @@ var Auth = func(frm form.Login, s *Session, c *gin.Context) (user *User, provide return user, provider, method, err } -// AuthSession returns the client session that belongs to the auth token provided, or returns nil if it was not found. +// AuthSession resolves an existing session from an app password token embedded in the login form. func AuthSession(frm form.Login, c *gin.Context) (sess *Session, user *User, err error) { if frm.Password == "" { // Abort authentication if no token was provided. @@ -68,7 +68,7 @@ func AuthSession(frm form.Login, c *gin.Context) (sess *Session, user *User, err return sess, sess.GetUser(), nil } -// AuthLocal authenticates against the local user database with the specified username and password. +// AuthLocal authenticates against the local user database, handling OTP and app-password flows. func AuthLocal(user *User, frm form.Login, s *Session, c *gin.Context) (provider authn.ProviderType, method authn.MethodType, err error) { // Set defaults. provider = authn.ProviderNone diff --git a/internal/entity/auth_tokens.go b/internal/entity/auth_tokens.go index e46cab0dc..1935f6bd2 100644 --- a/internal/entity/auth_tokens.go +++ b/internal/entity/auth_tokens.go @@ -4,6 +4,7 @@ import ( "github.com/photoprism/photoprism/pkg/rnd" ) +// Reserved token names used for configuration and public access. const TokenConfig = "__config__" const TokenPublic = "public" @@ -11,7 +12,7 @@ var PreviewToken = NewStringMap(Strings{}) var DownloadToken = NewStringMap(Strings{}) var ValidateTokens = true -// GenerateToken returns a random string token. +// GenerateToken returns a short random token for previews or downloads. func GenerateToken() string { return rnd.Base36(8) } diff --git a/internal/entity/auth_user.go b/internal/entity/auth_user.go index 9da0acdc4..ec3e39816 100644 --- a/internal/entity/auth_user.go +++ b/internal/entity/auth_user.go @@ -40,10 +40,10 @@ var PasswordLength = PasswordLengthDefault // UsersPath is the relative path for user assets. var UsersPath = "users" -// Users represents a list of users. +// Users is a convenience alias for slices of User. type Users []User -// User represents a person that may optionally log in as user. +// User represents an account that can authenticate with PhotoPrism. type User struct { ID int `gorm:"primary_key" json:"ID" yaml:"-"` UUID string `gorm:"type:VARBINARY(64);column:user_uuid;index;" json:"UUID,omitempty" yaml:"UUID,omitempty"` diff --git a/internal/entity/auth_user_cli.go b/internal/entity/auth_user_cli.go index 1f4deab41..44766f235 100644 --- a/internal/entity/auth_user_cli.go +++ b/internal/entity/auth_user_cli.go @@ -8,7 +8,7 @@ import ( "github.com/photoprism/photoprism/pkg/clean" ) -// SetValuesFromCli updates the entity values from a CLI context and validates them. +// SetValuesFromCli updates user fields based on CLI flags and invalidates sessions after privilege changes. func (m *User) SetValuesFromCli(ctx *cli.Context) error { frm := form.NewUserFromCli(ctx) @@ -102,7 +102,7 @@ func (m *User) SetValuesFromCli(ctx *cli.Context) error { return nil } -// RestoreFromCli restored the account from a CLI context. +// RestoreFromCli restores a deleted account from CLI input and optionally sets a new password. func (m *User) RestoreFromCli(ctx *cli.Context, newPassword string) (err error) { m.DeletedAt = nil diff --git a/internal/entity/auth_user_default.go b/internal/entity/auth_user_default.go index 59aa2e0e8..76f29ec0c 100644 --- a/internal/entity/auth_user_default.go +++ b/internal/entity/auth_user_default.go @@ -6,7 +6,7 @@ import ( "github.com/photoprism/photoprism/pkg/authn" ) -// Role defaults. +// Role defaults referenced when creating built-in users. const ( AdminUserName = "admin" AdminDisplayName = "Admin" diff --git a/internal/entity/auth_user_details.go b/internal/entity/auth_user_details.go index 2a3f6d51f..0033bcd44 100644 --- a/internal/entity/auth_user_details.go +++ b/internal/entity/auth_user_details.go @@ -15,7 +15,7 @@ const ( GenderOther = "other" ) -// UserDetails represents user profile information. +// UserDetails stores extended profile information for a user account. type UserDetails struct { UserUID string `gorm:"type:VARBINARY(42);primary_key;auto_increment:false;" json:"-" yaml:"-"` SubjUID string `gorm:"type:VARBINARY(42);index;" json:"SubjUID,omitempty" yaml:"SubjUID,omitempty"` @@ -58,12 +58,12 @@ func (UserDetails) TableName() string { return "auth_users_details" } -// NewUserDetails creates new user details. +// NewUserDetails allocates an empty profile record for the user UID. func NewUserDetails(uid string) *UserDetails { return &UserDetails{UserUID: uid} } -// CreateUserDetails creates new user details or returns nil on error. +// CreateUserDetails ensures a profile record exists for the user, creating one when absent. func CreateUserDetails(user *User) error { if user == nil { return fmt.Errorf("user is nil") diff --git a/internal/entity/auth_user_settings.go b/internal/entity/auth_user_settings.go index 1fb535710..f6d0c8222 100644 --- a/internal/entity/auth_user_settings.go +++ b/internal/entity/auth_user_settings.go @@ -9,7 +9,7 @@ import ( "github.com/photoprism/photoprism/pkg/rnd" ) -// UserSettings represents user preferences. +// UserSettings stores per-user UI, indexing, and workflow preferences. type UserSettings struct { UserUID string `gorm:"type:VARBINARY(42);primary_key;auto_increment:false;" json:"-" yaml:"UserUID"` UITheme string `gorm:"type:VARBINARY(32);column:ui_theme;" json:"UITheme,omitempty" yaml:"UITheme,omitempty"` @@ -38,12 +38,12 @@ func (UserSettings) TableName() string { return "auth_users_settings" } -// NewUserSettings creates new user preferences. +// NewUserSettings allocates a settings record bound to the provided user UID. func NewUserSettings(uid string) *UserSettings { return &UserSettings{UserUID: uid} } -// CreateUserSettings creates new user settings or returns nil on error. +// CreateUserSettings ensures settings exist for the given user, creating them if missing. func CreateUserSettings(user *User) error { if user == nil { return fmt.Errorf("user is nil") diff --git a/internal/entity/auth_user_share.go b/internal/entity/auth_user_share.go index 7b92668ff..4dd06f44d 100644 --- a/internal/entity/auth_user_share.go +++ b/internal/entity/auth_user_share.go @@ -27,7 +27,7 @@ const ( SharePrefix = "share" ) -// UserShares represents shared content. +// UserShares groups share relationships granted to a user. type UserShares []UserShare // UIDs returns shared UIDs. @@ -61,7 +61,7 @@ func (m UserShares) Contains(uid string) bool { return false } -// UserShare represents content shared with a user. +// UserShare represents a share relationship granting a user access to another entity. type UserShare struct { UserUID string `gorm:"type:VARBINARY(42);primary_key;auto_increment:false;" json:"-" yaml:"UserUID"` ShareUID string `gorm:"type:VARBINARY(42);primary_key;index;" json:"ShareUID" yaml:"ShareUID"` @@ -79,7 +79,7 @@ func (UserShare) TableName() string { return "auth_users_shares" } -// NewUserShare creates a new entity model. +// NewUserShare constructs a share relationship with optional expiration. func NewUserShare(userUID, shareUid string, perm uint, expires *time.Time) *UserShare { result := &UserShare{ UserUID: userUID,