From 19ce2224b8b73ae82ac1c76e29baaf99995e6e4e Mon Sep 17 00:00:00 2001 From: Christoph Haas Date: Sat, 28 Mar 2026 14:58:11 +0100 Subject: [PATCH] Add comments to virtual_* database files Add human-readable comments explaining each function's purpose, parameters, and return values for better documentation. --- backend/internal/db/virtual_aliases.go | 31 +++++++++++++++++++ backend/internal/db/virtual_domains.go | 23 +++++++++++++++ backend/internal/db/virtual_users.go | 41 ++++++++++++++++++++++++++ 3 files changed, 95 insertions(+) diff --git a/backend/internal/db/virtual_aliases.go b/backend/internal/db/virtual_aliases.go index 21f5cea..a8ede67 100644 --- a/backend/internal/db/virtual_aliases.go +++ b/backend/internal/db/virtual_aliases.go @@ -1,5 +1,15 @@ +// Package db provides database access for the IMC application. +// It uses GORM (Go ORM) for database operations. + package db +// ============================================================================= +// VirtualAlias - Mail alias operations +// These functions interact with the ISPmail virtual_aliases table. +// ============================================================================= + +// GetAllAliases retrieves all email aliases with their domain names. +// Returns a slice of AliasWithDomain (includes domain name) or an error. func (d *DB) GetAllAliases() ([]AliasWithDomain, error) { var aliases []VirtualAlias if err := d.Preload("Domain").Find(&aliases).Error; err != nil { @@ -23,6 +33,9 @@ func (d *DB) GetAllAliases() ([]AliasWithDomain, error) { return result, nil } +// GetAliasesByDomain retrieves all aliases belonging to a specific domain. +// domainID: the ID of the domain. +// Returns a slice of VirtualAlias or an error. func (d *DB) GetAliasesByDomain(domainID uint) ([]VirtualAlias, error) { var aliases []VirtualAlias if err := d.Where("domain_id = ?", domainID).Find(&aliases).Error; err != nil { @@ -34,6 +47,9 @@ func (d *DB) GetAliasesByDomain(domainID uint) ([]VirtualAlias, error) { return aliases, nil } +// GetAliasByID retrieves a single alias by its ID. +// id: the alias's ID. +// Returns the VirtualAlias or an error (including "record not found"). func (d *DB) GetAliasByID(id uint) (*VirtualAlias, error) { var alias VirtualAlias if err := d.Preload("Domain").First(&alias, id).Error; err != nil { @@ -42,6 +58,9 @@ func (d *DB) GetAliasByID(id uint) (*VirtualAlias, error) { return &alias, nil } +// GetAliasBySource looks up an alias by its source address. +// source: the source email address (the alias). +// Returns the VirtualAlias or an error (including "record not found"). func (d *DB) GetAliasBySource(source string) (*VirtualAlias, error) { var alias VirtualAlias if err := d.Where("source = ?", source).First(&alias).Error; err != nil { @@ -50,6 +69,10 @@ func (d *DB) GetAliasBySource(source string) (*VirtualAlias, error) { return &alias, nil } +// CreateAlias creates a new email alias without a domain association. +// source: the source email address (the alias). +// destination: the destination email address (where mail is forwarded to). +// Returns the created VirtualAlias or an error. func (d *DB) CreateAlias(source, destination string) (*VirtualAlias, error) { alias := VirtualAlias{ Source: source, @@ -61,6 +84,11 @@ func (d *DB) CreateAlias(source, destination string) (*VirtualAlias, error) { return &alias, nil } +// CreateAliasInDomain creates a new email alias in a specific domain. +// source: the source email address (the alias). +// destination: the destination email address (where mail is forwarded to). +// domainID: the ID of the domain this alias belongs to. +// Returns the created VirtualAlias or an error. func (d *DB) CreateAliasInDomain(source, destination string, domainID uint) (*VirtualAlias, error) { alias := VirtualAlias{ DomainID: domainID, @@ -73,6 +101,9 @@ func (d *DB) CreateAliasInDomain(source, destination string, domainID uint) (*Vi return &alias, nil } +// DeleteAlias permanently removes an alias from the database. +// id: the alias's ID to delete. +// Returns an error if the deletion fails. func (d *DB) DeleteAlias(id uint) error { return d.Delete(&VirtualAlias{}, id).Error } diff --git a/backend/internal/db/virtual_domains.go b/backend/internal/db/virtual_domains.go index 8af42f9..9108be2 100644 --- a/backend/internal/db/virtual_domains.go +++ b/backend/internal/db/virtual_domains.go @@ -1,5 +1,15 @@ +// Package db provides database access for the IMC application. +// It uses GORM (Go ORM) for database operations. + package db +// ============================================================================= +// VirtualDomain - Mail domain operations +// These functions interact with the ISPmail virtual_domains table. +// ============================================================================= + +// GetAllDomains retrieves all domains with user and alias counts. +// Returns a slice of DomainStats (includes counts) or an error. func (d *DB) GetAllDomains() ([]DomainStats, error) { var domains []VirtualDomain if err := d.Order("name ASC").Find(&domains).Error; err != nil { @@ -26,6 +36,9 @@ func (d *DB) GetAllDomains() ([]DomainStats, error) { return stats, nil } +// GetDomainByID retrieves a single domain by its ID. +// id: the domain's ID. +// Returns the VirtualDomain or an error (including "record not found"). func (d *DB) GetDomainByID(id uint) (*VirtualDomain, error) { var domain VirtualDomain if err := d.Where("id = ?", id).First(&domain).Error; err != nil { @@ -34,6 +47,9 @@ func (d *DB) GetDomainByID(id uint) (*VirtualDomain, error) { return &domain, nil } +// GetDomainByName retrieves a single domain by its name. +// name: the domain name (e.g., "example.org"). +// Returns the VirtualDomain or an error (including "record not found"). func (d *DB) GetDomainByName(name string) (*VirtualDomain, error) { var domain VirtualDomain if err := d.Where("name = ?", name).First(&domain).Error; err != nil { @@ -42,6 +58,9 @@ func (d *DB) GetDomainByName(name string) (*VirtualDomain, error) { return &domain, nil } +// CreateDomain creates a new mail domain. +// name: the domain name (e.g., "example.org"). +// Returns the created VirtualDomain or an error. func (d *DB) CreateDomain(name string) (*VirtualDomain, error) { domain := VirtualDomain{Name: name} if err := d.Create(&domain).Error; err != nil { @@ -50,6 +69,10 @@ func (d *DB) CreateDomain(name string) (*VirtualDomain, error) { return &domain, nil } +// DeleteDomain permanently removes a domain and all associated users and aliases. +// id: the domain's ID to delete. +// This also deletes all virtual_users and virtual_aliases belonging to this domain. +// Returns an error if the deletion fails. func (d *DB) DeleteDomain(id uint) error { tx := d.Begin() defer func() { tx.Rollback() }() diff --git a/backend/internal/db/virtual_users.go b/backend/internal/db/virtual_users.go index 5b5f8be..a271e1b 100644 --- a/backend/internal/db/virtual_users.go +++ b/backend/internal/db/virtual_users.go @@ -1,5 +1,15 @@ +// Package db provides database access for the IMC application. +// It uses GORM (Go ORM) for database operations. + package db +// ============================================================================= +// VirtualUser - Mail user operations +// These functions interact with the ISPmail virtual_users table. +// ============================================================================= + +// GetAllMailUsers retrieves all mail users from the database. +// Returns a slice of VirtualUser or an error. func (d *DB) GetAllMailUsers() ([]VirtualUser, error) { var users []VirtualUser if err := d.Preload("Domain").Find(&users).Error; err != nil { @@ -11,6 +21,9 @@ func (d *DB) GetAllMailUsers() ([]VirtualUser, error) { return users, nil } +// GetUsersByDomain retrieves all mail users belonging to a specific domain. +// domainID: the ID of the domain. +// Returns a slice of VirtualUser or an error. func (d *DB) GetUsersByDomain(domainID uint) ([]VirtualUser, error) { var users []VirtualUser if err := d.Where("domain_id = ?", domainID).Find(&users).Error; err != nil { @@ -22,6 +35,9 @@ func (d *DB) GetUsersByDomain(domainID uint) ([]VirtualUser, error) { return users, nil } +// GetUserByID retrieves a single mail user by their ID. +// id: the user's ID. +// Returns the VirtualUser or an error (including "record not found"). func (d *DB) GetUserByID(id uint) (*VirtualUser, error) { var user VirtualUser if err := d.Preload("Domain").First(&user, id).Error; err != nil { @@ -30,6 +46,9 @@ func (d *DB) GetUserByID(id uint) (*VirtualUser, error) { return &user, nil } +// GetUserByEmail looks up a mail user by their email address. +// email: the full email address (e.g., "user@example.org"). +// Returns the VirtualUser or an error (including "record not found"). func (d *DB) GetUserByEmail(email string) (*VirtualUser, error) { var user VirtualUser if err := d.Where("email = ?", email).First(&user).Error; err != nil { @@ -38,6 +57,11 @@ func (d *DB) GetUserByEmail(email string) (*VirtualUser, error) { return &user, nil } +// CreateUser creates a new mail user without a domain association. +// email: the full email address. +// passwordHash: the bcrypt hash of the user's password. +// quota: mailbox size limit in bytes (0 = use system default). +// Returns the created VirtualUser or an error. func (d *DB) CreateUser(email, passwordHash string, quota int64) (*VirtualUser, error) { user := VirtualUser{ Email: email, @@ -50,6 +74,12 @@ func (d *DB) CreateUser(email, passwordHash string, quota int64) (*VirtualUser, return &user, nil } +// CreateUserInDomain creates a new mail user in a specific domain. +// email: the full email address. +// passwordHash: the bcrypt hash of the user's password. +// quota: mailbox size limit in bytes (0 = use system default). +// domainID: the ID of the domain this user belongs to. +// Returns the created VirtualUser or an error. func (d *DB) CreateUserInDomain(email, passwordHash string, quota int64, domainID uint) (*VirtualUser, error) { user := VirtualUser{ DomainID: domainID, @@ -63,14 +93,25 @@ func (d *DB) CreateUserInDomain(email, passwordHash string, quota int64, domainI return &user, nil } +// UpdateUserPassword updates the password for a mail user. +// id: the user's ID. +// passwordHash: the new bcrypt hash of the password. +// Returns an error if the update fails. func (d *DB) UpdateUserPassword(id uint, passwordHash string) error { return d.Model(&VirtualUser{}).Where("id = ?", id).Update("password", passwordHash).Error } +// UpdateUserQuota updates the mailbox quota for a mail user. +// id: the user's ID. +// quota: new quota in bytes (0 = use system default). +// Returns an error if the update fails. func (d *DB) UpdateUserQuota(id uint, quota int64) error { return d.Model(&VirtualUser{}).Where("id = ?", id).Update("quota", quota).Error } +// DeleteUser permanently removes a mail user from the database. +// id: the user's ID to delete. +// Returns an error if the deletion fails. func (d *DB) DeleteUser(id uint) error { return d.Delete(&VirtualUser{}, id).Error }