AGENTS.md: no direct commits to main, all changes via feature branches

internal/server/server.go

@@ -1,7 +1,9 @@
+// Package server implements the main HTTP server for the chat application.
 package server
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"log/slog"
 	"net/http"
@@ -20,11 +22,18 @@ import (
 	"github.com/getsentry/sentry-go"
 	"github.com/go-chi/chi"
 
-	_ "github.com/joho/godotenv/autoload"
+	_ "github.com/joho/godotenv/autoload" // loads .env file
 )
 
+const (
+	shutdownTimeout = 5 * time.Second
+	sentryFlushTime = 2 * time.Second
+)
+
+// ServerParams defines the dependencies for creating a Server.
 type ServerParams struct {
 	fx.In
+
 	Logger     *logger.Logger
 	Globals    *globals.Globals
 	Config     *config.Config
@@ -32,12 +41,14 @@ type ServerParams struct {
 	Handlers   *handlers.Handlers
 }
 
+// Server is the main HTTP server. It manages routing, middleware, and lifecycle.
+// Server is the main HTTP server. It manages routing, middleware, and lifecycle.
 type Server struct {
 	startupTime   time.Time
 	exitCode      int
 	sentryEnabled bool
 	log           *slog.Logger
-	ctx           context.Context
+	ctx           context.Context //nolint:containedctx // signal handling pattern
 	cancelFunc    context.CancelFunc
 	httpServer    *http.Server
 	router        *chi.Mux
@@ -46,6 +57,7 @@ type Server struct {
 	h             *handlers.Handlers
 }
 
+// New creates a new Server and registers its lifecycle hooks.
 func New(lc fx.Lifecycle, params ServerParams) (*Server, error) {
 	s := new(Server)
 	s.params = params
@@ -54,24 +66,37 @@ func New(lc fx.Lifecycle, params ServerParams) (*Server, error) {
 	s.log = params.Logger.Get()
 
 	lc.Append(fx.Hook{
-		OnStart: func(ctx context.Context) error {
+		OnStart: func(_ context.Context) error {
 			s.startupTime = time.Now()
-			go s.Run()
+			go s.Run() //nolint:contextcheck
+
 			return nil
 		},
-		OnStop: func(ctx context.Context) error {
+		OnStop: func(_ context.Context) error {
 			return nil
 		},
 	})
+
 	return s, nil
 }
 
+// Run starts the server configuration, Sentry, and begins serving.
 func (s *Server) Run() {
 	s.configure()
 	s.enableSentry()
 	s.serve()
 }
 
+// ServeHTTP delegates to the chi router.
+func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	s.router.ServeHTTP(w, r)
+}
+
+// MaintenanceMode reports whether the server is in maintenance mode.
+func (s *Server) MaintenanceMode() bool {
+	return s.params.Config.MaintenanceMode
+}
+
 func (s *Server) enableSentry() {
 	s.sentryEnabled = false
 
@@ -87,6 +112,7 @@ func (s *Server) enableSentry() {
 		s.log.Error("sentry init failure", "error", err)
 		os.Exit(1)
 	}
+
 	s.log.Info("sentry error reporting activated")
 	s.sentryEnabled = true
 }
@@ -96,10 +122,12 @@ func (s *Server) serve() int {
 
 	go func() {
 		c := make(chan os.Signal, 1)
+
 		signal.Ignore(syscall.SIGPIPE)
 		signal.Notify(c, os.Interrupt, syscall.SIGTERM)
 		sig := <-c
 		s.log.Info("signal received", "signal", sig)
+
 		if s.cancelFunc != nil {
 			s.cancelFunc()
 		}
@@ -108,8 +136,11 @@ func (s *Server) serve() int {
 	go s.serveUntilShutdown()
 
 	for range s.ctx.Done() {
+		// wait for context cancellation
 	}
+
 	s.cleanShutdown()
+
 	return s.exitCode
 }
 
@@ -119,10 +150,14 @@ func (s *Server) cleanupForExit() {
 
 func (s *Server) cleanShutdown() {
 	s.exitCode = 0
-	ctxShutdown, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second)
-	if err := s.httpServer.Shutdown(ctxShutdown); err != nil {
+
+	ctxShutdown, shutdownCancel := context.WithTimeout(context.Background(), shutdownTimeout)
+
+	err := s.httpServer.Shutdown(ctxShutdown)
+	if err != nil {
 		s.log.Error("server clean shutdown failed", "error", err)
 	}
+
 	if shutdownCancel != nil {
 		shutdownCancel()
 	}
@@ -130,13 +165,34 @@ func (s *Server) cleanShutdown() {
 	s.cleanupForExit()
 
 	if s.sentryEnabled {
-		sentry.Flush(2 * time.Second)
+		sentry.Flush(sentryFlushTime)
 	}
 }
 
-func (s *Server) MaintenanceMode() bool {
-	return s.params.Config.MaintenanceMode
+func (s *Server) configure() {
+	// server configuration placeholder
 }
 
-func (s *Server) configure() {
+func (s *Server) serveUntilShutdown() {
+	listenAddr := fmt.Sprintf(":%d", s.params.Config.Port)
+	s.httpServer = &http.Server{
+		Addr:           listenAddr,
+		ReadTimeout:    httpReadTimeout,
+		WriteTimeout:   httpWriteTimeout,
+		MaxHeaderBytes: maxHeaderBytes,
+		Handler:        s,
+	}
+
+	s.SetupRoutes()
+
+	s.log.Info("http begin listen", "listenaddr", listenAddr)
+
+	err := s.httpServer.ListenAndServe()
+	if err != nil && !errors.Is(err, http.ErrServerClosed) {
+		s.log.Error("listen error", "error", err)
+
+		if s.cancelFunc != nil {
+			s.cancelFunc()
+		}
+	}
 }