feat(app): add service bootstrap package

New app package providing a service lifecycle manager that wires
together config, logger, database, telemetry, and server:

  app.Run(
      app.WithConfig(&cfg, config.WithFile("config.yaml")),
      app.WithLogger(logger.NewSlog()),
      app.WithDB(cfg.DB),
      app.WithTelemetry(cfg.Telemetry),
      app.WithHandler(myHandler),
      app.WithHealthCheck("/ping"),
      app.WithH2C(),
      app.WithAddr(cfg.Addr),
  )

Lifecycle: config → logger → db → telemetry → onStart hooks → server
Shutdown: server → onStop hooks → telemetry flush → db close

Handles SIGINT/SIGTERM for graceful shutdown.

Author: ravisuhag

app/app.go

@@ -0,0 +1,124 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"os/signal"
+	"syscall"
+
+	"github.com/raystack/salt/db"
+	"github.com/raystack/salt/logger"
+	"github.com/raystack/salt/server"
+	"github.com/raystack/salt/telemetry"
+)
+
+// App is a service lifecycle manager that wires together configuration,
+// logging, database, telemetry, and HTTP serving with graceful shutdown.
+type App struct {
+	logger    logger.Logger
+	db        *db.Client
+	dbCfg     *db.Config
+	telCfg    *telemetry.Config
+	telClean  func()
+	serverOps []server.Option
+	onStart   []func(context.Context) error
+	onStop    []func(context.Context) error
+}
+
+// New creates a new App by applying the given options.
+func New(opts ...Option) (*App, error) {
+	a := &App{
+		logger: &logger.Noop{},
+	}
+	for _, opt := range opts {
+		if err := opt(a); err != nil {
+			return nil, fmt.Errorf("app option: %w", err)
+		}
+	}
+	return a, nil
+}
+
+// Run is the simplest entry point: creates an App, starts it with signal
+// handling (SIGINT, SIGTERM), and blocks until shutdown completes.
+func Run(opts ...Option) error {
+	a, err := New(opts...)
+	if err != nil {
+		return err
+	}
+
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+
+	return a.Start(ctx)
+}
+
+// Start initializes all components and starts the server.
+// It blocks until the context is cancelled, then performs graceful shutdown.
+func (a *App) Start(ctx context.Context) error {
+	// Initialize database if configured.
+	if a.dbCfg != nil {
+		client, err := db.New(*a.dbCfg)
+		if err != nil {
+			return fmt.Errorf("app db: %w", err)
+		}
+		a.db = client
+		a.logger.Info("database connected", "host", client.Host())
+	}
+
+	// Initialize telemetry if configured.
+	if a.telCfg != nil {
+		cleanup, err := telemetry.Init(ctx, *a.telCfg, a.logger)
+		if err != nil {
+			return fmt.Errorf("app telemetry: %w", err)
+		}
+		a.telClean = cleanup
+	}
+
+	// Run onStart hooks.
+	for _, fn := range a.onStart {
+		if err := fn(ctx); err != nil {
+			a.cleanup()
+			return fmt.Errorf("app on_start: %w", err)
+		}
+	}
+
+	// Build and start the server.
+	a.serverOps = append(a.serverOps, server.WithLogger(a.logger))
+	srv := server.New(a.serverOps...)
+
+	err := srv.Start(ctx)
+
+	// Shutdown sequence.
+	a.stop(context.Background())
+	return err
+}
+
+// Logger returns the app's logger.
+func (a *App) Logger() logger.Logger {
+	return a.logger
+}
+
+// DB returns the database client, or nil if no database was configured.
+func (a *App) DB() *db.Client {
+	return a.db
+}
+
+func (a *App) stop(ctx context.Context) {
+	for _, fn := range a.onStop {
+		if err := fn(ctx); err != nil {
+			a.logger.Error("app on_stop hook error", "error", err)
+		}
+	}
+	a.cleanup()
+}
+
+func (a *App) cleanup() {
+	if a.telClean != nil {
+		a.telClean()
+	}
+	if a.db != nil {
+		if err := a.db.Close(); err != nil {
+			a.logger.Error("app db close error", "error", err)
+		}
+	}
+}

app/app_test.go

@@ -0,0 +1,150 @@
+package app_test
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/raystack/salt/app"
+	"github.com/raystack/salt/logger"
+	"github.com/raystack/salt/server"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNew(t *testing.T) {
+	t.Run("creates app with defaults", func(t *testing.T) {
+		a, err := app.New()
+		require.NoError(t, err)
+		assert.NotNil(t, a)
+		assert.NotNil(t, a.Logger())
+		assert.Nil(t, a.DB())
+	})
+
+	t.Run("sets logger", func(t *testing.T) {
+		l := logger.NewNoop()
+		a, err := app.New(app.WithLogger(l))
+		require.NoError(t, err)
+		assert.Equal(t, l, a.Logger())
+	})
+
+	t.Run("returns error from option", func(t *testing.T) {
+		badOpt := func(a *app.App) error {
+			return fmt.Errorf("bad option")
+		}
+		_, err := app.New(badOpt)
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "bad option")
+	})
+}
+
+func TestAppStartAndShutdown(t *testing.T) {
+	t.Run("starts and stops cleanly", func(t *testing.T) {
+		ctx, cancel := context.WithCancel(context.Background())
+
+		a, err := app.New(
+			app.WithLogger(logger.NewNoop()),
+			app.WithAddr("127.0.0.1:18950"),
+			app.WithHealthCheck("/ping"),
+		)
+		require.NoError(t, err)
+
+		errCh := make(chan error, 1)
+		go func() { errCh <- a.Start(ctx) }()
+
+		time.Sleep(100 * time.Millisecond)
+
+		// Verify health check works
+		resp, err := http.Get("http://127.0.0.1:18950/ping")
+		require.NoError(t, err)
+		defer resp.Body.Close()
+		assert.Equal(t, http.StatusOK, resp.StatusCode)
+
+		cancel()
+
+		select {
+		case err := <-errCh:
+			assert.NoError(t, err)
+		case <-time.After(5 * time.Second):
+			t.Fatal("shutdown timed out")
+		}
+	})
+
+	t.Run("runs onStart hooks", func(t *testing.T) {
+		ctx, cancel := context.WithCancel(context.Background())
+
+		var hookRan bool
+		a, err := app.New(
+			app.WithAddr("127.0.0.1:18951"),
+			app.WithOnStart(func(ctx context.Context) error {
+				hookRan = true
+				return nil
+			}),
+		)
+		require.NoError(t, err)
+
+		go func() {
+			time.Sleep(100 * time.Millisecond)
+			cancel()
+		}()
+
+		a.Start(ctx)
+		assert.True(t, hookRan)
+	})
+
+	t.Run("runs onStop hooks", func(t *testing.T) {
+		ctx, cancel := context.WithCancel(context.Background())
+
+		var hookRan bool
+		a, err := app.New(
+			app.WithAddr("127.0.0.1:18952"),
+			app.WithOnStop(func(ctx context.Context) error {
+				hookRan = true
+				return nil
+			}),
+		)
+		require.NoError(t, err)
+
+		go func() {
+			time.Sleep(100 * time.Millisecond)
+			cancel()
+		}()
+
+		a.Start(ctx)
+		assert.True(t, hookRan)
+	})
+
+	t.Run("serves custom handler", func(t *testing.T) {
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+
+		a, err := app.New(
+			app.WithLogger(logger.NewNoop()),
+			app.WithAddr("127.0.0.1:18953"),
+			app.WithHandler("/hello", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				fmt.Fprint(w, "world")
+			})),
+			app.WithHealthCheck("/ping"),
+			app.WithH2C(),
+		)
+		require.NoError(t, err)
+
+		go a.Start(ctx)
+		time.Sleep(100 * time.Millisecond)
+
+		resp, err := http.Get("http://127.0.0.1:18953/hello")
+		require.NoError(t, err)
+		defer resp.Body.Close()
+
+		body, _ := io.ReadAll(resp.Body)
+		assert.Equal(t, "world", string(body))
+
+		cancel()
+	})
+}
+
+// Verify Option type is compatible (compile-time check).
+var _ server.Option = server.WithAddr("")