feat(onstart): implement all reviewer feedback

- Move OnStart logic to a dedicated, testable method.
- Fix all linter issues (deep-exit and cyclomatic complexity).
- Add unit tests for success and error cases.
- Add comprehensive documentation with a realistic example.
- Update the example app to demonstrate a real-world use case.

Author: HeerakKashyap

docs/advanced-guide/startup-hooks.md

@@ -0,0 +1,55 @@
+# Startup Hooks
+
+GoFr provides a way to run synchronous jobs when your application starts, before any servers begin handling requests. This is useful for tasks like seeding a database, warming up a cache, or performing other critical setup procedures.
+
+## `OnStart`
+
+You can register a startup hook using the `a.OnStart()` method on your `app` instance.
+
+### Usage
+
+The method accepts a function with the signature `func(ctx *gofr.Context) error`.
+
+- The `*gofr.Context` passed to the hook is fully initialized and provides access to all dependency-injection-managed services (e.g., `ctx.Container.SQL`, `ctx.Container.Redis`).
+- If any `OnStart` hook returns an error, the application will log the error and refuse to start.
+
+### Example: Warming up a Cache
+
+Here is an example of using `OnStart` to set an initial value in a Redis cache when the application starts.
+
+```go
+package main
+
+import (
+    "gofr.dev/pkg/gofr"
+)
+
+func main() {
+    a := gofr.New()
+
+    // Register an OnStart hook to warm up a cache.
+    a.OnStart(func(ctx *gofr.Context) error {
+        ctx.Container.Logger.Info("Warming up the cache...")
+
+        // In a real app, this might come from a database or another service.
+        cacheKey := "initial-data"
+        cacheValue := "This is some data cached at startup."
+
+        err := ctx.Redis.Set(ctx, cacheKey, cacheValue, 0).Err()
+        if err != nil {
+            ctx.Container.Logger.Errorf("Failed to warm up cache: %v", err)
+            return err // Return the error to halt startup if caching fails.
+        }
+
+        ctx.Container.Logger.Info("Cache warmed up successfully!")
+
+        return nil
+    })
+
+    // ... register your routes
+
+    a.Run()
+}
+```
+
+This ensures that critical startup tasks are completed successfully before the application begins accepting traffic.

examples/http-server/main.go

@@ -28,11 +28,23 @@ func main() {
 	a.GET("/trace", TraceHandler)
 	a.GET("/mysql", MysqlHandler)
 
+	// Register an OnStart hook to warm up a cache.
 	a.OnStart(func(ctx *gofr.Context) error {
+		ctx.Container.Logger.Info("Warming up the cache...")
+
+		// Example: Fetch some data and store it in Redis.
+		// In a real app, this might come from a database or another service.
+		cacheKey := "initial-data"
+		cacheValue := "This is some data cached at startup."
+
+		err := ctx.Redis.Set(ctx, cacheKey, cacheValue, 0).Err()
+		if err != nil {
+			ctx.Container.Logger.Errorf("Failed to warm up cache: %v", err)
+			return err // Return the error to halt startup if caching fails.
+		}
+
+		ctx.Container.Logger.Info("Cache warmed up successfully!")
 
-		fmt.Println("OnStart hook executed!")
-		fmt.Printf("SQL: %#v\n", ctx.Container.SQL)
-		fmt.Printf("Redis: %#v\n", ctx.Container.Redis)
 		return nil
 	})
 

pkg/gofr/gofr.go

@@ -59,14 +59,17 @@ func (a *App) newContextForHooks(ctx context.Context) *Context {
 	}
 }
 
-func (a *App) runOnStartHooks(ctx context.Context) {
+func (a *App) runOnStartHooks(ctx context.Context) error {
 	gofrCtx := a.newContextForHooks(ctx)
 	for _, hook := range a.onStartHooks {
 		if err := hook(gofrCtx); err != nil {
+			// Log the error and return it
 			a.Logger().Errorf("OnStart hook failed: %v", err)
-			os.Exit(1)
+			return err
 		}
 	}
+	// Return nil if all hooks succeed
+	return nil
 }
 
 // Shutdown stops the service(s) and close the application.

pkg/gofr/gofr_test.go

@@ -1,8 +1,10 @@
 package gofr
 
 import (
+	"context"
 	"encoding/base64"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -1162,3 +1164,35 @@ func TestApp_Subscribe(t *testing.T) {
 		assert.False(t, ok)
 	})
 }
+
+func TestApp_OnStart(t *testing.T) {
+	// Test case 1: Hook executes successfully
+	t.Run("success", func(t *testing.T) {
+		var hookCalled bool
+		app := New()
+
+		app.OnStart(func(ctx *Context) error {
+			hookCalled = true
+			return nil
+		})
+
+		err := app.runOnStartHooks(context.Background())
+
+		assert.Nil(t, err, "Expected no error from runOnStartHooks")
+		assert.True(t, hookCalled, "Expected the OnStart hook to be called")
+	})
+
+	// Test case 2: Hook returns an error
+	t.Run("error", func(t *testing.T) {
+		expectedErr := errors.New("hook failed")
+		app := New()
+
+		app.OnStart(func(ctx *Context) error {
+			return expectedErr
+		})
+
+		err := app.runOnStartHooks(context.Background())
+
+		assert.Equal(t, expectedErr, err, "Expected an error from runOnStartHooks")
+	})
+}

pkg/gofr/run.go

@@ -7,7 +7,6 @@ import (
 	"os/signal"
 	"sync"
 	"syscall"
-
 )
 
 // Run starts the application. If it is an HTTP server, it will start the server.
@@ -16,13 +15,14 @@ func (a *App) Run() {
 		a.cmd.Run(a.container)
 	}
 
-	
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGINT, syscall.SIGTERM)
 	defer stop()
 
-	onStartCtx := context.WithoutCancel(ctx)
-    a.runOnStartHooks(onStartCtx)
-	
+	// Running startup hooks and exit if they fail.
+	// Using the main app context to ensure proper lifecycle management.
+	if err := a.runOnStartHooks(ctx); err != nil {
+		os.Exit(1)
+	}
 
 	timeout, err := getShutdownTimeoutFromConfig(a.Config)
 	if err != nil {