update comments

Author: Oleg Komarov

models/user/spamreport.go

@@ -1,6 +1,8 @@
 // Copyright 2025 The Gitea Authors. All rights reserved.
 // SPDX-License-Identifier: MIT
 
+// BLENDER: spam reporting
+
 package user
 
 import (
@@ -13,10 +15,10 @@ import (
 
 // SpamReportStatusType is used to support a spam report lifecycle:
 //
-// Pending -> Processing
-// Processing -> Processed|Dismissed
+// pending -> locked
+// locked -> processed | dismissed
 //
-// "Processing" status works as a lock for a record that is being processed.
+// "locked" status works as a lock for a record that is being processed.
 type SpamReportStatusType int
 
 const (

routers/web/admin/spamreports.go

@@ -22,7 +22,7 @@ const (
 	tplSpamReports base.TplName = "admin/spamreports/list"
 )
 
-// SpamReports show spam reports
+// SpamReports shows spam reports
 func SpamReports(ctx *context.Context) {
 	ctx.Data["Title"] = ctx.Tr("admin.spamreports")
 	ctx.Data["PageIsSpamReports"] = true
@@ -33,7 +33,7 @@ func SpamReports(ctx *context.Context) {
 		filterStatus user_model.SpamReportStatusType
 	)
 
-	// When no value is specified Pending (status=0) reports are shown,
+	// When no value is specified reports are filtered by status=pending (=0),
 	// which luckily makes sense as a default view.
 	filterStatus = user_model.SpamReportStatusType(ctx.FormInt("status"))
 	ctx.Data["FilterStatus"] = filterStatus
@@ -74,6 +74,8 @@ func SpamReports(ctx *context.Context) {
 	ctx.HTML(http.StatusOK, tplSpamReports)
 }
 
+// SpamReportsPost handles "process" and "dismiss" actions for pending reports.
+// The processing is done synchronously.
 func SpamReportsPost(ctx *context.Context) {
 	action := ctx.FormString("action")
 	// ctx.Req.PostForm is now parsed due to the call to FormString above

routers/web/user/setting/spamreport.go

@@ -14,6 +14,7 @@ import (
 	user_service "code.gitea.io/gitea/services/user"
 )
 
+// SpamReportUserPost creates a spam report for a given user.
 func SpamReportUserPost(ctx *context.Context) {
 	canReportSpam, err := user_service.IsTrustedUser(ctx, ctx.Doer)
 	if err != nil {

routers/web/web.go

@@ -677,6 +677,7 @@ func registerRoutes(m *web.Router) {
 			m.Post("", web.Bind(forms.BlockUserForm{}), user_setting.BlockedUsersPost)
 		})
 
+		// BLENDER: spam reporting
 		m.Post("/spamreport", user_setting.SpamReportUserPost)
 	}, reqSignIn, ctxDataSet("PageIsUserSettings", true, "EnablePackages", setting.Packages.Enabled))
 
@@ -750,6 +751,7 @@ func registerRoutes(m *web.Router) {
 			m.Post("/delete", admin.DeleteEmail)
 		})
 
+		// BLENDER: spam reporting
 		m.Group("/spamreports", func() {
 			m.Get("", admin.SpamReports)
 			m.Post("", admin.SpamReportsPost)

services/cron/tasks_spamreport.go

@@ -19,6 +19,8 @@ func registerProcessSpamReports() {
 		RunAtStart: true,
 		Schedule:   "@every 5m",
 	}, func(ctx context.Context, doer *user_model.User, _ Config) error {
+		// This code assumes that all reports may be processed.
+		// If we start accepting reports from non-trusted users, we need to add a check here.
 		ids, err := user_model.GetPendingSpamReportIDs(ctx)
 		if err != nil {
 			return fmt.Errorf("failed to GetPendingSpamReportIDs: %w", err)

services/user/spamreport.go

@@ -31,8 +31,13 @@ func IsTrustedUser(ctx context.Context, user *user_model.User) (bool, error) {
 }
 
 // CreateSpamReport checks that a reporter can report a user,
-// and inserts a new record in default status=Pending
+// and inserts a new record in default status=pending
 // for further processing, either manual or automatical.
+//
+// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+// !!! If you change this code to accept reports from non-trusted users, !!!
+// !!! make sure to update process_spam_reports cron task.               !!!
+// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 func CreateSpamReport(ctx context.Context, reporter, user *user_model.User) error {
 	reporterIsTrusted, err := IsTrustedUser(ctx, reporter)
 	if err != nil {
@@ -54,7 +59,25 @@ func CreateSpamReport(ctx context.Context, reporter, user *user_model.User) erro
 	})
 }
 
-// ProcessSpamReports updates only reports in status "Pending" to avoid race conditions.
+// ProcessSpamReports performs the cleanup of a reported user account and the content it created.
+// Only the reports in "pending" status are processed to avoid race conditions.
+// A processed user account becomes inactive, restricted, login prohibited, profile fields erased,
+// and the following objects that were created by the user are deleted:
+//   - issues and pulls
+//   - comments
+//   - personal repositories
+//   - personal projects
+//
+// If the processing code fails it leaves the SpamReport record that was being processed in "locked" status.
+// It would need to be handled manually, as the error is assumed to be unrecoverable
+// (which may not always be true, e.g. during transient db downtime).
+//
+// We will have to revisit this approach if it actually causes problems.
+// E.g. we could
+//   - either try to unlock the record on failure (this may not always be possible),
+//	   or unlock after some timeout (according to the record's UpdatedUnix)
+//   - add a new field to keep track of an attempt count per record
+//   - retry on subsequent runs, until the attempt budget is exhausted
 func ProcessSpamReports(ctx context.Context, doer *user_model.User, spamReportIDs []int64) error {
 	var spamReports []user_model.SpamReport
 	err := db.GetEngine(ctx).In("id", spamReportIDs).Find(&spamReports)
@@ -70,7 +93,7 @@ func ProcessSpamReports(ctx context.Context, doer *user_model.User, spamReportID
 			return fmt.Errorf("failed to set SpamReport.Status to locked for id=%d: %w", id, err)
 		}
 		if count < 1 {
-			log.Info("Skipping SpamReport id=%d, status wasn't Pending", id)
+			log.Info("Skipping SpamReport id=%d, status wasn't pending", id)
 			continue
 		}
 
@@ -170,7 +193,7 @@ func ProcessSpamReports(ctx context.Context, doer *user_model.User, spamReportID
 	return nil
 }
 
-// DismissSpamReports updates only reports in status "Pending" to avoid race conditions
+// DismissSpamReports updates only reports in "pending" status to avoid race conditions
 // with the actual processing.
 func DismissSpamReports(ctx context.Context, spamReportIDs []int64) error {
 	_, err := db.GetEngine(ctx).In("id", spamReportIDs).