feat: make user limit configurable from admin user management (#18)

Store the per-instance user cap in settings (default 20) and expose
GET/PUT /admin/users/limit endpoints. The user management page now lets
admins view and update the limit without touching system settings.

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: truewhile <truewhile@users.noreply.github.com>

internal/handler/admin.go

@@ -31,7 +31,66 @@ func listUsersHandler(svc *service.Container) gin.HandlerFunc {
 		for i := range users {
 			users[i].PopulateComputedFields()
 		}
-		c.JSON(http.StatusOK, users)
+		maxUsers, err := service.LoadMaxUsers(c.Request.Context(), svc.Repo)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{
+			"users":        users,
+			"max_users":    maxUsers,
+			"current_users": len(users),
+		})
+	}
+}
+
+type updateUserLimitReq struct {
+	MaxUsers int `json:"max_users" binding:"required"`
+}
+
+func getUserLimitHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		maxUsers, err := service.LoadMaxUsers(c.Request.Context(), svc.Repo)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		currentUsers, err := svc.Repo.User.Count(c.Request.Context())
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{
+			"max_users":     maxUsers,
+			"current_users": currentUsers,
+		})
+	}
+}
+
+func updateUserLimitHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		var req updateUserLimitReq
+		if err := c.ShouldBindJSON(&req); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		if err := service.SaveMaxUsers(c.Request.Context(), svc.Repo, req.MaxUsers); err != nil {
+			if errors.Is(err, service.ErrInvalidMaxUsers) {
+				c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+				return
+			}
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		currentUsers, err := svc.Repo.User.Count(c.Request.Context())
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{
+			"max_users":     req.MaxUsers,
+			"current_users": currentUsers,
+		})
 	}
 }
 
@@ -288,7 +347,12 @@ func writeUserMutationError(c *gin.Context, svc *service.Container, err error) {
 	case errors.Is(err, service.ErrUsernameTaken):
 		c.JSON(http.StatusConflict, gin.H{"error": "username already taken"})
 	case errors.Is(err, service.ErrUserLimitReached):
-		c.JSON(http.StatusBadRequest, gin.H{"error": "user limit reached", "max_users": service.UserLimit})
+		maxUsers, loadErr := service.LoadMaxUsers(c.Request.Context(), svc.Repo)
+		if loadErr != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": loadErr.Error()})
+			return
+		}
+		c.JSON(http.StatusBadRequest, gin.H{"error": "user limit reached", "max_users": maxUsers})
 	default:
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 	}

internal/handler/admin_user_limit_test.go

@@ -0,0 +1,55 @@
+package handler
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+func TestUserLimitHandlers(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := db.AutoMigrate(model.AllModels()...); err != nil {
+		t.Fatal(err)
+	}
+	repos := repository.New(db)
+	cfg := &service.Container{Repo: repos, Auth: service.NewAuthService(nil, zap.NewNop(), repos, service.NewTokenService(nil, zap.NewNop(), repos), service.NewPermissionService(zap.NewNop(), repos))}
+	router := gin.New()
+	router.GET("/admin/users/limit", getUserLimitHandler(cfg))
+	router.PUT("/admin/users/limit", updateUserLimitHandler(cfg))
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/users/limit", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("GET limit status = %d body=%s", w.Code, w.Body.String())
+	}
+	if !strings.Contains(w.Body.String(), `"max_users":20`) {
+		t.Fatalf("expected default max_users=20, got %s", w.Body.String())
+	}
+
+	req = httptest.NewRequest(http.MethodPut, "/admin/users/limit", strings.NewReader(`{"max_users":42}`))
+	req.Header.Set("Content-Type", "application/json")
+	w = httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("PUT limit status = %d body=%s", w.Code, w.Body.String())
+	}
+	got, err := service.LoadMaxUsers(t.Context(), repos)
+	if err != nil || got != 42 {
+		t.Fatalf("stored max users = %d err=%v, want 42", got, err)
+	}
+}

internal/handler/auth.go

@@ -68,6 +68,15 @@ func registerHandler(svc *service.Container) gin.HandlerFunc {
 				c.JSON(http.StatusConflict, gin.H{"error": "username taken"})
 				return
 			}
+			if errors.Is(err, service.ErrUserLimitReached) {
+				maxUsers, loadErr := service.LoadMaxUsers(c.Request.Context(), svc.Repo)
+				if loadErr != nil {
+					c.JSON(http.StatusInternalServerError, gin.H{"error": loadErr.Error()})
+					return
+				}
+				c.JSON(http.StatusBadRequest, gin.H{"error": "user limit reached", "max_users": maxUsers})
+				return
+			}
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
 		}

internal/handler/emby_session_routes_test.go

@@ -213,10 +213,13 @@ func TestEmbyAuthenticatedRequestRefreshesRealtimeUserActivity(t *testing.T) {
 	if w.Code != http.StatusOK {
 		t.Fatalf("admin users status: %d body=%s", w.Code, w.Body.String())
 	}
-	var users []model.User
-	if err := json.Unmarshal(w.Body.Bytes(), &users); err != nil {
+	var payload struct {
+		Users []model.User `json:"users"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &payload); err != nil {
 		t.Fatalf("decode users: %v", err)
 	}
+	users := payload.Users
 	if len(users) != 1 {
 		t.Fatalf("users = %#v", users)
 	}

internal/handler/routes_admin.go

@@ -102,6 +102,8 @@ func registerAdminStrmRoutes(admin *gin.RouterGroup, svc *service.Container) {
 }
 
 func registerAdminUserRoutes(admin *gin.RouterGroup, svc *service.Container) {
+	admin.GET("/users/limit", getUserLimitHandler(svc))
+	admin.PUT("/users/limit", updateUserLimitHandler(svc))
 	admin.GET("/users", listUsersHandler(svc))
 	admin.POST("/users", createUserHandler(svc))
 	admin.PATCH("/users/:id", updateUserHandler(svc))

internal/service/auth.go

@@ -40,14 +40,8 @@ var (
 	ErrUserExpired        = errors.New("user account has expired")
 )
 
-// MaxUsers 是单实例允许的最大用户数（开源版本固定上限）。
-const MaxUsers = OpenSourceUserLimit
-
-// OpenSourceUserLimit 是开源版本的用户数上限。
-const OpenSourceUserLimit = 20
-
-// UserLimit 是注册/邀请码发放时的固定用户数上限（授权管理已移除，固定为开源上限）。
-const UserLimit = OpenSourceUserLimit
+// MaxUsers is kept for tests that seed up to the default cap.
+const MaxUsers = DefaultMaxUsers
 
 // SeedAdmin makes sure at least one admin user exists. It mirrors the
 // legacy default behaviour: if no admin row is found we create
@@ -103,9 +97,13 @@ func (s *AuthService) Register(ctx context.Context, username, password string) (
 	if err := s.repo.User.ReleaseDeletedUsername(ctx, username); err != nil {
 		return nil, nil, err
 	}
+	limit, err := LoadMaxUsers(ctx, s.repo)
+	if err != nil {
+		return nil, nil, err
+	}
 	if n, err := s.repo.User.Count(ctx); err != nil {
 		return nil, nil, err
-	} else if n >= UserLimit {
+	} else if n >= int64(limit) {
 		return nil, nil, ErrUserLimitReached
 	}
 	hash, err := hashPassword(password)

internal/service/user_limits.go

@@ -0,0 +1,71 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+const (
+	// SettingMaxUsers stores the per-instance user cap in the settings table.
+	SettingMaxUsers = "user.max_users"
+
+	// DefaultMaxUsers is used when the setting is missing or invalid.
+	DefaultMaxUsers = 20
+
+	// MaxUsersHardCap prevents absurd values from admin input.
+	MaxUsersHardCap = 10000
+)
+
+var (
+	ErrInvalidMaxUsers = errors.New("invalid max users")
+)
+
+// LoadMaxUsers reads the configured user cap, falling back to DefaultMaxUsers.
+func LoadMaxUsers(ctx context.Context, repo *repository.Container) (int, error) {
+	if repo == nil || repo.Setting == nil {
+		return DefaultMaxUsers, nil
+	}
+	raw, err := repo.Setting.Get(ctx, SettingMaxUsers)
+	if err != nil {
+		return DefaultMaxUsers, err
+	}
+	return parseMaxUsersSetting(raw), nil
+}
+
+func parseMaxUsersSetting(raw string) int {
+	n, err := strconv.Atoi(strings.TrimSpace(raw))
+	if err != nil || n < 1 {
+		return DefaultMaxUsers
+	}
+	if n > MaxUsersHardCap {
+		return MaxUsersHardCap
+	}
+	return n
+}
+
+// ValidateMaxUsers checks an admin-provided cap before persisting it.
+func ValidateMaxUsers(n int) error {
+	if n < 1 {
+		return fmt.Errorf("%w: must be at least 1", ErrInvalidMaxUsers)
+	}
+	if n > MaxUsersHardCap {
+		return fmt.Errorf("%w: must be at most %d", ErrInvalidMaxUsers, MaxUsersHardCap)
+	}
+	return nil
+}
+
+// SaveMaxUsers persists the user cap in settings.
+func SaveMaxUsers(ctx context.Context, repo *repository.Container, n int) error {
+	if err := ValidateMaxUsers(n); err != nil {
+		return err
+	}
+	if repo == nil || repo.Setting == nil {
+		return errors.New("settings repository unavailable")
+	}
+	return repo.Setting.Set(ctx, SettingMaxUsers, strconv.Itoa(n))
+}

internal/service/user_limits_test.go

@@ -0,0 +1,67 @@
+package service
+
+import (
+	"context"
+	"fmt"
+	"testing"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+func TestLoadMaxUsersDefaultsToTwenty(t *testing.T) {
+	ctx := context.Background()
+	repos, _, _, _ := newAuthTestServices(t)
+	got, err := LoadMaxUsers(ctx, repos)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != DefaultMaxUsers {
+		t.Fatalf("max users = %d, want %d", got, DefaultMaxUsers)
+	}
+}
+
+func TestSaveAndLoadMaxUsers(t *testing.T) {
+	ctx := context.Background()
+	repos, _, _, _ := newAuthTestServices(t)
+	if err := SaveMaxUsers(ctx, repos, 50); err != nil {
+		t.Fatal(err)
+	}
+	got, err := LoadMaxUsers(ctx, repos)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != 50 {
+		t.Fatalf("max users = %d, want 50", got)
+	}
+}
+
+func TestValidateMaxUsersRejectsInvalid(t *testing.T) {
+	if err := ValidateMaxUsers(0); err == nil {
+		t.Fatal("expected error for 0")
+	}
+	if err := ValidateMaxUsers(MaxUsersHardCap + 1); err == nil {
+		t.Fatal("expected error above hard cap")
+	}
+}
+
+func TestRegisterRespectsConfiguredUserLimit(t *testing.T) {
+	ctx := context.Background()
+	repos, auth, _, _ := newAuthTestServices(t)
+	if err := SaveMaxUsers(ctx, repos, 3); err != nil {
+		t.Fatal(err)
+	}
+	for i := 0; i < 3; i++ {
+		if err := repos.User.Create(ctx, &model.User{
+			Username:     fmt.Sprintf("user-%02d", i),
+			PasswordHash: "hash",
+			Role:         "user",
+			Tier:         "free",
+		}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	_, _, err := auth.Register(ctx, "overflow", "password")
+	if err == nil {
+		t.Fatal("expected user limit error")
+	}
+}