refactor: use pinned golangci-lint Docker image for linting (#55)

Closes [issue #50](#50)

## Summary

Refactors the Dockerfile to use a separate lint stage with a pinned golangci-lint Docker image, following the pattern used by [sneak/pixa](https://git.eeqj.de/sneak/pixa). This replaces the previous approach of installing golangci-lint via curl in the builder stage.

## Changes

### Dockerfile
- **New `lint` stage** using `golangci/golangci-lint:v2.11.3` (Debian-based, pinned by sha256 digest) as a separate build stage
- **Builder stage** depends on lint via `COPY --from=lint /src/go.sum /dev/null` — build won't proceed unless linting passes
- **Go bumped** from 1.24 to 1.26.1 (`golang:1.26.1-bookworm`, pinned by sha256)
- **golangci-lint bumped** from v1.64.8 to v2.11.3
- All three Docker images (golangci-lint, golang, alpine) pinned by sha256 digest
- Debian-based golangci-lint image used (not Alpine) because mattn/go-sqlite3 CGO does not compile on musl (off64_t)

### Linter Config (.golangci.yml)
- Migrated from v1 to v2 format (`version: "2"` added)
- Removed linters no longer available in v2: `gofmt` (handled by `make fmt-check`), `gosimple` (merged into `staticcheck`), `typecheck` (always-on in v2)
- Same set of linters enabled — no rules weakened

### Code Fixes (all lint issues from v2 upgrade)
- Added package comments to all packages
- Added doc comments to all exported types, functions, and methods
- Fixed unchecked errors flagged by `errcheck` (sqlDB.Close, os.Setenv in tests, resp.Body.Close, fmt.Fprint)
- Fixed unused parameters flagged by `revive` (renamed to `_`)
- Fixed `gosec` G120 warnings: added `http.MaxBytesReader` before `r.ParseForm()` calls
- Fixed `staticcheck` QF1012: replaced `WriteString(fmt.Sprintf(...))` with `fmt.Fprintf`
- Fixed `staticcheck` QF1003: converted if/else chain to tagged switch
- Renamed `DeliveryTask` → `Task` to avoid package stutter (`delivery.Task` instead of `delivery.DeliveryTask`)
- Renamed shadowed builtin `max` parameter to `upperBound` in `cryptoRandInt`
- Used `t.Setenv` instead of `os.Setenv` in tests (auto-restores)

### README.md
- Updated version requirements: Go 1.26+, golangci-lint v2.11+
- Updated Dockerfile description in project structure

## Verification

`docker build .` passes cleanly — formatting check, linting, all tests, and build all succeed.

Co-authored-by: clawbot <clawbot@noreply.git.eeqj.de>
Reviewed-on: #55
Co-authored-by: clawbot <clawbot@noreply.example.org>
Co-committed-by: clawbot <clawbot@noreply.example.org>

internal/server/http.go

@@ -1,18 +1,33 @@
 package server
 
 import (
+	"errors"
 	"fmt"
 	"net/http"
 	"time"
 )
 
+const (
+	// httpReadTimeout is the maximum duration for reading the
+	// entire request, including the body.
+	httpReadTimeout = 10 * time.Second
+
+	// httpWriteTimeout is the maximum duration before timing out
+	// writes of the response.
+	httpWriteTimeout = 10 * time.Second
+
+	// httpMaxHeaderBytes is the maximum number of bytes the
+	// server will read parsing the request headers.
+	httpMaxHeaderBytes = 1 << 20
+)
+
 func (s *Server) serveUntilShutdown() {
 	listenAddr := fmt.Sprintf(":%d", s.params.Config.Port)
 	s.httpServer = &http.Server{
 		Addr:           listenAddr,
-		ReadTimeout:    10 * time.Second,
-		WriteTimeout:   10 * time.Second,
-		MaxHeaderBytes: 1 << 20,
+		ReadTimeout:    httpReadTimeout,
+		WriteTimeout:   httpWriteTimeout,
+		MaxHeaderBytes: httpMaxHeaderBytes,
 		Handler:        s,
 	}
 
@@ -21,14 +36,21 @@ func (s *Server) serveUntilShutdown() {
 	s.SetupRoutes()
 
 	s.log.Info("http begin listen", "listenaddr", listenAddr)
-	if err := s.httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+
+	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()
 		}
 	}
 }
 
-func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+// ServeHTTP delegates to the router.
+func (s *Server) ServeHTTP(
+	w http.ResponseWriter,
+	r *http.Request,
+) {
 	s.router.ServeHTTP(w, r)
 }

internal/server/routes.go

@@ -11,15 +11,24 @@ import (
 	"sneak.berlin/go/webhooker/static"
 )
 
-// maxFormBodySize is the maximum allowed request body size (in bytes) for
-// form POST endpoints.  1 MB is generous for any form submission while
-// preventing abuse from oversized payloads.
+// maxFormBodySize is the maximum allowed request body size (in
+// bytes) for form POST endpoints. 1 MB is generous for any form
+// submission while preventing abuse from oversized payloads.
 const maxFormBodySize int64 = 1 * 1024 * 1024 // 1 MB
 
+// requestTimeout is the maximum time allowed for a single HTTP
+// request.
+const requestTimeout = 60 * time.Second
+
+// SetupRoutes configures all HTTP routes and middleware on the
+// server's router.
 func (s *Server) SetupRoutes() {
 	s.router = chi.NewRouter()
+	s.setupGlobalMiddleware()
+	s.setupRoutes()
+}
 
-	// Global middleware stack — applied to every request.
+func (s *Server) setupGlobalMiddleware() {
 	s.router.Use(middleware.Recoverer)
 	s.router.Use(middleware.RequestID)
 	s.router.Use(s.mw.SecurityHeaders())
@@ -31,24 +40,28 @@ func (s *Server) SetupRoutes() {
 	}
 
 	s.router.Use(s.mw.CORS())
-	s.router.Use(middleware.Timeout(60 * time.Second))
+	s.router.Use(middleware.Timeout(requestTimeout))
 
-	// Sentry error reporting (if SENTRY_DSN is set). Repanic is true
-	// so panics still bubble up to the Recoverer middleware above.
+	// Sentry error reporting (if SENTRY_DSN is set). Repanic is
+	// true so panics still bubble up to the Recoverer middleware.
 	if s.sentryEnabled {
 		sentryHandler := sentryhttp.New(sentryhttp.Options{
 			Repanic: true,
 		})
 		s.router.Use(sentryHandler.Handle)
 	}
+}
 
-	// Routes
+func (s *Server) setupRoutes() {
 	s.router.Get("/", s.h.HandleIndex())
 
-	s.router.Mount("/s", http.StripPrefix("/s", http.FileServer(http.FS(static.Static))))
+	s.router.Mount(
+		"/s",
+		http.StripPrefix("/s", http.FileServer(http.FS(static.Static))),
+	)
 
 	s.router.Route("/api/v1", func(_ chi.Router) {
-		// TODO: Add API routes here
+		// API routes will be added here.
 	})
 
 	s.router.Get(
@@ -60,62 +73,89 @@ func (s *Server) SetupRoutes() {
 	if s.params.Config.MetricsUsername != "" {
 		s.router.Group(func(r chi.Router) {
 			r.Use(s.mw.MetricsAuth())
-			r.Get("/metrics", http.HandlerFunc(promhttp.Handler().ServeHTTP))
+			r.Get(
+				"/metrics",
+				http.HandlerFunc(
+					promhttp.Handler().ServeHTTP,
+				),
+			)
 		})
 	}
 
-	// pages that are rendered server-side — CSRF-protected, body-size
-	// limited, and with per-IP rate limiting on the login endpoint.
+	s.setupPageRoutes()
+	s.setupUserRoutes()
+	s.setupSourceRoutes()
+	s.setupWebhookRoutes()
+}
+
+func (s *Server) setupPageRoutes() {
 	s.router.Route("/pages", func(r chi.Router) {
 		r.Use(s.mw.CSRF())
 		r.Use(s.mw.MaxBodySize(maxFormBodySize))
 
-		// Login page — rate-limited to prevent brute-force attacks
 		r.Group(func(r chi.Router) {
 			r.Use(s.mw.LoginRateLimit())
 			r.Get("/login", s.h.HandleLoginPage())
 			r.Post("/login", s.h.HandleLoginSubmit())
 		})
 
-		// Logout (auth required)
 		r.Post("/logout", s.h.HandleLogout())
 	})
+}
 
-	// User profile routes
+func (s *Server) setupUserRoutes() {
 	s.router.Route("/user/{username}", func(r chi.Router) {
 		r.Use(s.mw.CSRF())
 		r.Get("/", s.h.HandleProfile())
 	})
+}
 
-	// Webhook management routes (require authentication, CSRF-protected)
+func (s *Server) setupSourceRoutes() {
 	s.router.Route("/sources", func(r chi.Router) {
 		r.Use(s.mw.CSRF())
 		r.Use(s.mw.RequireAuth())
 		r.Use(s.mw.MaxBodySize(maxFormBodySize))
-		r.Get("/", s.h.HandleSourceList())             // List all webhooks
-		r.Get("/new", s.h.HandleSourceCreate())        // Show create form
-		r.Post("/new", s.h.HandleSourceCreateSubmit()) // Handle create submission
+		r.Get("/", s.h.HandleSourceList())
+		r.Get("/new", s.h.HandleSourceCreate())
+		r.Post("/new", s.h.HandleSourceCreateSubmit())
 	})
 
 	s.router.Route("/source/{sourceID}", func(r chi.Router) {
 		r.Use(s.mw.CSRF())
 		r.Use(s.mw.RequireAuth())
 		r.Use(s.mw.MaxBodySize(maxFormBodySize))
-		r.Get("/", s.h.HandleSourceDetail())                                       // View webhook details
-		r.Get("/edit", s.h.HandleSourceEdit())                                     // Show edit form
-		r.Post("/edit", s.h.HandleSourceEditSubmit())                              // Handle edit submission
-		r.Post("/delete", s.h.HandleSourceDelete())                                // Delete webhook
-		r.Get("/logs", s.h.HandleSourceLogs())                                     // View webhook logs
-		r.Post("/entrypoints", s.h.HandleEntrypointCreate())                       // Add entrypoint
-		r.Post("/entrypoints/{entrypointID}/delete", s.h.HandleEntrypointDelete()) // Delete entrypoint
-		r.Post("/entrypoints/{entrypointID}/toggle", s.h.HandleEntrypointToggle()) // Toggle entrypoint active
-		r.Post("/targets", s.h.HandleTargetCreate())                               // Add target
-		r.Post("/targets/{targetID}/delete", s.h.HandleTargetDelete())             // Delete target
-		r.Post("/targets/{targetID}/toggle", s.h.HandleTargetToggle())             // Toggle target active
+		r.Get("/", s.h.HandleSourceDetail())
+		r.Get("/edit", s.h.HandleSourceEdit())
+		r.Post("/edit", s.h.HandleSourceEditSubmit())
+		r.Post("/delete", s.h.HandleSourceDelete())
+		r.Get("/logs", s.h.HandleSourceLogs())
+		r.Post(
+			"/entrypoints",
+			s.h.HandleEntrypointCreate(),
+		)
+		r.Post(
+			"/entrypoints/{entrypointID}/delete",
+			s.h.HandleEntrypointDelete(),
+		)
+		r.Post(
+			"/entrypoints/{entrypointID}/toggle",
+			s.h.HandleEntrypointToggle(),
+		)
+		r.Post("/targets", s.h.HandleTargetCreate())
+		r.Post(
+			"/targets/{targetID}/delete",
+			s.h.HandleTargetDelete(),
+		)
+		r.Post(
+			"/targets/{targetID}/toggle",
+			s.h.HandleTargetToggle(),
+		)
 	})
-
-	// Entrypoint endpoint — accepts incoming webhook POST requests only.
-	// Using HandleFunc so the handler itself can return 405 for non-POST
-	// methods (chi's Method routing returns 405 without Allow header).
-	s.router.HandleFunc("/webhook/{uuid}", s.h.HandleWebhook())
+}
+
+func (s *Server) setupWebhookRoutes() {
+	s.router.HandleFunc(
+		"/webhook/{uuid}",
+		s.h.HandleWebhook(),
+	)
 }

internal/server/server.go

@@ -1,3 +1,5 @@
+// Package server wires up HTTP routes and manages the
+// application lifecycle.
 package server
 
 import (
@@ -21,9 +23,20 @@ import (
 	"github.com/go-chi/chi"
 )
 
-// nolint:revive // ServerParams is a standard fx naming convention
+const (
+	// shutdownTimeout is the maximum time to wait for the HTTP
+	// server to finish in-flight requests during shutdown.
+	shutdownTimeout = 5 * time.Second
+
+	// sentryFlushTimeout is the maximum time to wait for Sentry
+	// to flush pending events during shutdown.
+	sentryFlushTimeout = 2 * time.Second
+)
+
+//nolint:revive // ServerParams is a standard fx naming convention.
 type ServerParams struct {
 	fx.In
+
 	Logger     *logger.Logger
 	Globals    *globals.Globals
 	Config     *config.Config
@@ -31,12 +44,13 @@ type ServerParams struct {
 	Handlers   *handlers.Handlers
 }
 
+// Server is the main HTTP server that wires up routes and manages
+// graceful shutdown.
 type Server struct {
 	startupTime   time.Time
 	exitCode      int
 	sentryEnabled bool
 	log           *slog.Logger
-	ctx           context.Context
 	cancelFunc    context.CancelFunc
 	httpServer    *http.Server
 	router        *chi.Mux
@@ -45,6 +59,8 @@ type Server struct {
 	h             *handlers.Handlers
 }
 
+// New creates a Server that starts the HTTP listener on fx start
+// and stops it gracefully.
 func New(lc fx.Lifecycle, params ServerParams) (*Server, error) {
 	s := new(Server)
 	s.params = params
@@ -53,19 +69,23 @@ 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()
+
 			return nil
 		},
 		OnStop: func(ctx context.Context) error {
-			s.cleanShutdown()
+			s.cleanShutdown(ctx)
+
 			return nil
 		},
 	})
+
 	return s, nil
 }
 
+// Run configures Sentry and starts serving HTTP requests.
 func (s *Server) Run() {
 	s.configure()
 
@@ -75,6 +95,12 @@ func (s *Server) Run() {
 	s.serve()
 }
 
+// MaintenanceMode returns whether the server is in maintenance
+// mode.
+func (s *Server) MaintenanceMode() bool {
+	return s.params.Config.MaintenanceMode
+}
+
 func (s *Server) enableSentry() {
 	s.sentryEnabled = false
 
@@ -83,29 +109,37 @@ func (s *Server) enableSentry() {
 	}
 
 	err := sentry.Init(sentry.ClientOptions{
-		Dsn:     s.params.Config.SentryDSN,
-		Release: fmt.Sprintf("%s-%s", s.params.Globals.Appname, s.params.Globals.Version),
+		Dsn: s.params.Config.SentryDSN,
+		Release: fmt.Sprintf(
+			"%s-%s",
+			s.params.Globals.Appname,
+			s.params.Globals.Version,
+		),
 	})
 	if err != nil {
 		s.log.Error("sentry init failure", "error", err)
 		// Don't use fatal since we still want the service to run
 		return
 	}
+
 	s.log.Info("sentry error reporting activated")
 	s.sentryEnabled = true
 }
 
 func (s *Server) serve() int {
-	s.ctx, s.cancelFunc = context.WithCancel(context.Background())
+	ctx, cancelFunc := context.WithCancel(context.Background())
+	s.cancelFunc = cancelFunc
 
 	// signal watcher
 	go func() {
 		c := make(chan os.Signal, 1)
+
 		signal.Ignore(syscall.SIGPIPE)
 		signal.Notify(c, os.Interrupt, syscall.SIGTERM)
 		// block and wait for signal
 		sig := <-c
 		s.log.Info("signal received", "signal", sig.String())
+
 		if s.cancelFunc != nil {
 			// cancelling the main context will trigger a clean
 			// shutdown via the fx OnStop hook.
@@ -115,9 +149,9 @@ func (s *Server) serve() int {
 
 	go s.serveUntilShutdown()
 
-	<-s.ctx.Done()
+	<-ctx.Done()
 	// Shutdown is handled by the fx OnStop hook (cleanShutdown).
-	// Do not call cleanShutdown() here to avoid a double invocation.
+	// Do not call cleanShutdown() here to avoid double invocation.
 	return s.exitCode
 }
 
@@ -125,27 +159,29 @@ func (s *Server) cleanupForExit() {
 	s.log.Info("cleaning up")
 }
 
-func (s *Server) cleanShutdown() {
+func (s *Server) cleanShutdown(ctx context.Context) {
 	// initiate clean shutdown
 	s.exitCode = 0
-	ctxShutdown, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second)
+
+	ctxShutdown, shutdownCancel := context.WithTimeout(
+		ctx, shutdownTimeout,
+	)
 	defer shutdownCancel()
 
-	if err := s.httpServer.Shutdown(ctxShutdown); err != nil {
-		s.log.Error("server clean shutdown failed", "error", err)
+	err := s.httpServer.Shutdown(ctxShutdown)
+	if err != nil {
+		s.log.Error(
+			"server clean shutdown failed", "error", err,
+		)
 	}
 
 	s.cleanupForExit()
 
 	if s.sentryEnabled {
-		sentry.Flush(2 * time.Second)
+		sentry.Flush(sentryFlushTimeout)
 	}
 }
 
-func (s *Server) MaintenanceMode() bool {
-	return s.params.Config.MaintenanceMode
-}
-
 func (s *Server) configure() {
 	// identify ourselves in the logs
 	s.params.Logger.Identify()