Add periodic package (#34)

Author: firecow

periodic/periodic.go

@@ -0,0 +1,35 @@
+package periodic
+
+import (
+	"context"
+	"time"
+)
+
+// Run spawns a goroutine that executes fn immediately after the jitter delay,
+// then repeats it at the given interval until ctx is cancelled.
+func Run(ctx context.Context, interval time.Duration, jitter time.Duration, fn func()) {
+	go func() {
+		if jitter > 0 {
+			jitterTimer := time.NewTimer(jitter)
+			defer jitterTimer.Stop()
+			select {
+			case <-ctx.Done():
+				return
+			case <-jitterTimer.C:
+			}
+		}
+
+		ticker := time.NewTicker(interval)
+		defer ticker.Stop()
+
+		fn()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-ticker.C:
+				fn()
+			}
+		}
+	}()
+}

periodic/periodic_test.go

@@ -0,0 +1,86 @@
+package periodic_test
+
+import (
+	"context"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/cego/go-lib/v2/periodic"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestRunExecutesImmediately(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	var count atomic.Int32
+	periodic.Run(ctx, time.Hour, 0, func() {
+		count.Add(1)
+	})
+
+	time.Sleep(50 * time.Millisecond)
+	assert.Equal(t, int32(1), count.Load())
+}
+
+func TestRunExecutesPeriodically(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	var count atomic.Int32
+	periodic.Run(ctx, 50*time.Millisecond, 0, func() {
+		count.Add(1)
+	})
+
+	time.Sleep(200 * time.Millisecond)
+	assert.GreaterOrEqual(t, count.Load(), int32(3))
+}
+
+func TestRunStopsOnContextCancel(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+
+	var count atomic.Int32
+	periodic.Run(ctx, 50*time.Millisecond, 0, func() {
+		count.Add(1)
+	})
+
+	time.Sleep(100 * time.Millisecond)
+	cancel()
+	countAtCancel := count.Load()
+
+	time.Sleep(200 * time.Millisecond)
+	assert.Equal(t, countAtCancel, count.Load())
+}
+
+func TestRunAppliesJitter(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	var count atomic.Int32
+	periodic.Run(ctx, time.Hour, 200*time.Millisecond, func() {
+		count.Add(1)
+	})
+
+	time.Sleep(50 * time.Millisecond)
+	assert.Equal(t, int32(0), count.Load())
+
+	time.Sleep(200 * time.Millisecond)
+	assert.Equal(t, int32(1), count.Load())
+}
+
+func TestRunDoesNotBlock(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	returned := make(chan struct{})
+	go func() {
+		periodic.Run(ctx, time.Hour, time.Hour, func() { /* no-op: testing that Run returns immediately */ })
+		close(returned)
+	}()
+
+	select {
+	case <-returned:
+	case <-time.After(50 * time.Millisecond):
+		t.Fatal("Run blocked the caller")
+	}
+}

readme.md

@@ -19,6 +19,7 @@ import (
     "github.com/cego/go-lib/v2/forwardauth"
     "github.com/cego/go-lib/v2/headers"
     "github.com/cego/go-lib/v2/serve"
+    "github.com/cego/go-lib/v2/periodic"
 )
 ```
 
@@ -40,6 +41,10 @@ l := logger.NewWithLevel(slog.LevelInfo)
 
 // Set as global slog default
 slog.SetDefault(l)
+
+// Testing with mock logger
+l := logger.NewMock()
+r := renderer.New(l)
 ```
 
 ## Using Renderer with builtin logging
@@ -77,12 +82,6 @@ mux.Handle("/data", fa.HandlerFunc(func (w http.ResponseWriter, req *http.Reques
 }))
 ```
 
-## Testing with Mock Logger
-```go
-l := logger.NewMock()
-r := renderer.New(l)
-```
-
 ## Headers
 ```go
 req.Header.Get(headers.Authorization)
@@ -91,6 +90,19 @@ req.Header.Get(headers.XForwardedFor)
 
 Available constants: `XForwardedProto`, `XForwardedMethod`, `XForwardedHost`, `XForwardedUri`, `XForwardedFor`, `Accept`, `UserAgent`, `Cookie`, `Authorization`, `RemoteUser`, `ContentType`
 
+## Using Periodic
+
+Context-aware periodic task execution with jitter support.
+
+```go
+ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+defer stop()
+
+periodic.Run(ctx, 2*time.Second, time.Duration(rand.Intn(1000))*time.Millisecond, func() {
+    fmt.Println("runs every 2 seconds until ctx is cancelled")
+})
+```
+
 ## Using Serve (Graceful Shutdown)
 
 Graceful HTTP server shutdown with a configurable delay for load balancer deregistration.