Improve Garbage Collector (#162)

* Implement [TOTP] Cleanup Configuration

- [+] feat(otpverifier): add cleanup interval constants and configuration
- [+] Introduce cleanup interval constants (FastCleanup, MediumCleanup, SlowCleanup) to represent different cleanup frequencies for removing expired tokens in the TOTP verifier.
- [+] Add a CleanupIntervals map to associate cleanup interval constants with their corresponding percentage of the TOTP period.
- [+] Include the CleanupInterval field in the Config struct to allow configuring the cleanup interval when creating a new TOTPVerifier.
- [+] Modify the startPeriodicCleanup method to use the configured cleanup interval percentage to determine the cleanup period.

- [+] test(otpverifier): update TestTOTPVerifier_PeriodicCleanup test case
- [+] Set the CleanupInterval to FastCleanup in the test configuration.
- [+] Adjust the sleep duration to match the FastCleanup interval (100% of the token validity period) to ensure the cleanup process has occurred before verifying the token.

* Docs [pkg.go.dev] Update Documentation

- [+] docs(otpverifier): document CleanupIntervals options for TOTP verifier cleanup process
- [+] refactor(otpverifier): update default cleanup interval comment to use consistent formatting

Author: H0llyW00dzZ

internal/otpverifier/docs.go

@@ -116,6 +116,10 @@
 //   - [BLAKE3256]
 //   - [BLAKE3384]
 //   - [BLAKE3512]
+//   - [CleanupIntervals]: The interval at which the cleanup process runs to remove expired tokens in the TOTP verifier. Available options are:
+//   - [FastCleanup]
+//   - [MediumCleanup]
+//   - [SlowCleanup]
 //
 // # QR Code Configuration
 //

internal/otpverifier/otpverifier.go

@@ -160,6 +160,39 @@ var SyncWindowRanges = map[int][]int{
 	LowStrict:    {5, 10},
 }
 
+const (
+	// FastCleanup represents the fastest cleanup interval for removing expired tokens in the TOTP verifier.
+	// It is assigned a value of iota + 1, which evaluates to 1.
+	// When FastCleanup is selected, the cleanup process runs every 25% of the TOTP period, providing the most frequent cleanup.
+	FastCleanup = iota + 1
+
+	// MediumCleanup represents a medium cleanup interval for removing expired tokens in the TOTP verifier.
+	// It is assigned the next sequential value of iota, which evaluates to 2.
+	// When MediumCleanup is selected, the cleanup process runs every 50% of the TOTP period, providing a balanced cleanup frequency.
+	MediumCleanup
+
+	// SlowCleanup represents the slowest cleanup interval for removing expired tokens in the TOTP verifier.
+	// It is assigned the next sequential value of iota, which evaluates to 3.
+	// When SlowCleanup is selected, the cleanup process runs every 75% of the TOTP period, providing the least frequent cleanup.
+	SlowCleanup
+)
+
+// CleanupIntervals is a map that associates cleanup interval constants with their corresponding percentage of the TOTP period.
+// The cleanup interval determines how frequently the cleanup process runs to remove expired tokens.
+//
+// The available cleanup intervals are:
+//   - [FastCleanup]: The cleanup process runs every 25% of the TOTP period.
+//   - [MediumCleanup]: The cleanup process runs every 50% of the TOTP period.
+//   - [SlowCleanup]: The cleanup process runs every 75% of the TOTP period.
+//
+// Note: Choosing an appropriate cleanup interval is important to balance the need for timely removal of expired tokens
+// and the overhead of running the cleanup process too frequently. The default cleanup interval is [MediumCleanup].
+var CleanupIntervals = map[int]float64{
+	FastCleanup:   0.25, // 25% of the TOTP period
+	MediumCleanup: 0.50, // 50% of the TOTP period
+	SlowCleanup:   0.75, // 75% of the TOTP period
+}
+
 // TimeSource is a function type that returns the current time.
 type TimeSource func() time.Time
 
@@ -189,6 +222,7 @@ type Config struct {
 	CustomURITemplateParams map[string]string
 	Hash                    string
 	Crypto                  Crypto
+	CleanupInterval         int
 }
 
 // QRCodeConfig represents the configuration for generating QR codes.

internal/otpverifier/otpverifier_test.go

@@ -181,11 +181,12 @@ func TestTOTPVerifier_PeriodicCleanup(t *testing.T) {
 	secret := gotp.RandomSecret(16)
 	period := 10 // Set the token validity period to 10 seconds
 	config := otpverifier.Config{
-		Secret:     secret,
-		Period:     period,
-		Digits:     6,
-		Hash:       otpverifier.SHA256,
-		TimeSource: time.Now,
+		Secret:          secret,
+		Period:          period,
+		Digits:          6,
+		Hash:            otpverifier.SHA256,
+		TimeSource:      otpverifier.DefaultConfig.TOTPTime,
+		CleanupInterval: otpverifier.FastCleanup,
 	}
 
 	verifier := otpverifier.NewTOTPVerifier(config)
@@ -195,7 +196,7 @@ func TestTOTPVerifier_PeriodicCleanup(t *testing.T) {
 	verifier.Verify(token1)
 
 	// Wait Assistant garbage collector for periodic cleanup to occur (less than the token validity period)
-	time.Sleep(time.Duration(period*3/4) * time.Second)
+	time.Sleep(time.Duration(period*4/4) * time.Second)
 
 	// Simulate used tokens
 	token2 := verifier.GenerateToken()

internal/otpverifier/totp.go

@@ -17,9 +17,10 @@ import (
 
 // TOTPVerifier is a TOTP verifier that implements the OTPVerifier interface.
 type TOTPVerifier struct {
-	config     Config
-	totp       *gotp.TOTP
-	UsedTokens *sync.Map
+	config          Config
+	totp            *gotp.TOTP
+	UsedTokens      *sync.Map
+	CleanupInterval int
 }
 
 // NewTOTPVerifier creates a new TOTPVerifier with the given configuration.
@@ -68,7 +69,8 @@ func NewTOTPVerifier(config ...Config) *TOTPVerifier {
 		totp:   totp,
 		// Allocates 11 to 15 allocs/op without signature (depends on the hash function), which is relatively inexpensive for this TOTP synchronization window.
 		// Without implementing a synchronization window similar to HOTP, it can lead to high vulnerability.
-		UsedTokens: &sync.Map{},
+		UsedTokens:      &sync.Map{},
+		CleanupInterval: c.CleanupInterval,
 	}
 
 	// Start the periodic cleanup goroutine
@@ -209,7 +211,12 @@ func (v *TOTPVerifier) GenerateOTPURL(issuer, accountName string) string {
 
 // startPeriodicCleanup starts a goroutine that periodically cleans up expired tokens.
 func (v *TOTPVerifier) startPeriodicCleanup() {
-	cleanupPeriod := time.Duration(v.config.Period/2) * time.Second
+	cleanupPeriodPercentage, ok := CleanupIntervals[v.CleanupInterval]
+	if !ok {
+		cleanupPeriodPercentage = CleanupIntervals[MediumCleanup] // Default to medium if invalid value is provided
+	}
+
+	cleanupPeriod := time.Duration(float64(v.config.Period)*cleanupPeriodPercentage) * time.Second
 	cleanupTicker := time.NewTicker(cleanupPeriod)
 	defer cleanupTicker.Stop()