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/handlers/webhook.go

@@ -6,31 +6,36 @@ import (
 	"net/http"
 
 	"github.com/go-chi/chi"
+	"gorm.io/gorm"
 	"sneak.berlin/go/webhooker/internal/database"
 	"sneak.berlin/go/webhooker/internal/delivery"
 )
 
 const (
-	// maxWebhookBodySize is the maximum allowed webhook request body (1 MB).
-	maxWebhookBodySize = 1 << 20
+	// maxWebhookBodySize is the maximum allowed webhook
+	// request body (1 MB).
+	maxWebhookBodySize = 1 << maxBodyShift
 )
 
-// HandleWebhook handles incoming webhook requests at entrypoint URLs.
-// Only POST requests are accepted; all other methods return 405 Method Not Allowed.
-// Events and deliveries are stored in the per-webhook database. The handler
-// builds self-contained DeliveryTask structs with all target and event data
-// so the delivery engine can process them without additional DB reads.
+// HandleWebhook handles incoming webhook requests at entrypoint
+// URLs.
 func (h *Handlers) HandleWebhook() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		if r.Method != http.MethodPost {
 			w.Header().Set("Allow", "POST")
-			http.Error(w, "Method Not Allowed", http.StatusMethodNotAllowed)
+			http.Error(
+				w,
+				"Method Not Allowed",
+				http.StatusMethodNotAllowed,
+			)
+
 			return
 		}
 
 		entrypointUUID := chi.URLParam(r, "uuid")
 		if entrypointUUID == "" {
 			http.NotFound(w, r)
+
 			return
 		}
 
@@ -40,152 +45,302 @@ func (h *Handlers) HandleWebhook() http.HandlerFunc {
 			"remote_addr", r.RemoteAddr,
 		)
 
-		// Look up entrypoint by path (from main application DB)
-		var entrypoint database.Entrypoint
-		result := h.db.DB().Where("path = ?", entrypointUUID).First(&entrypoint)
-		if result.Error != nil {
-			h.log.Debug("entrypoint not found", "path", entrypointUUID)
-			http.NotFound(w, r)
+		entrypoint, ok := h.lookupEntrypoint(
+			w, r, entrypointUUID,
+		)
+		if !ok {
 			return
 		}
 
-		// Check if active
 		if !entrypoint.Active {
 			http.Error(w, "Gone", http.StatusGone)
+
 			return
 		}
 
-		// Read body with size limit
-		body, err := io.ReadAll(io.LimitReader(r.Body, maxWebhookBodySize+1))
-		if err != nil {
-			h.log.Error("failed to read request body", "error", err)
-			http.Error(w, "Bad request", http.StatusBadRequest)
-			return
-		}
-		if len(body) > maxWebhookBodySize {
-			http.Error(w, "Request body too large", http.StatusRequestEntityTooLarge)
-			return
-		}
-
-		// Serialize headers as JSON
-		headersJSON, err := json.Marshal(r.Header)
-		if err != nil {
-			h.log.Error("failed to serialize headers", "error", err)
-			http.Error(w, "Internal server error", http.StatusInternalServerError)
-			return
-		}
-
-		// Find all active targets for this webhook (from main application DB)
-		var targets []database.Target
-		if targetErr := h.db.DB().Where("webhook_id = ? AND active = ?", entrypoint.WebhookID, true).Find(&targets).Error; targetErr != nil {
-			h.log.Error("failed to query targets", "error", targetErr)
-			http.Error(w, "Internal server error", http.StatusInternalServerError)
-			return
-		}
-
-		// Get the per-webhook database for event storage
-		webhookDB, err := h.dbMgr.GetDB(entrypoint.WebhookID)
-		if err != nil {
-			h.log.Error("failed to get webhook database",
-				"webhook_id", entrypoint.WebhookID,
-				"error", err,
-			)
-			http.Error(w, "Internal server error", http.StatusInternalServerError)
-			return
-		}
-
-		// Create the event and deliveries in a transaction on the per-webhook DB
-		tx := webhookDB.Begin()
-		if tx.Error != nil {
-			h.log.Error("failed to begin transaction", "error", tx.Error)
-			http.Error(w, "Internal server error", http.StatusInternalServerError)
-			return
-		}
-
-		event := &database.Event{
-			WebhookID:    entrypoint.WebhookID,
-			EntrypointID: entrypoint.ID,
-			Method:       r.Method,
-			Headers:      string(headersJSON),
-			Body:         string(body),
-			ContentType:  r.Header.Get("Content-Type"),
-		}
-
-		if err := tx.Create(event).Error; err != nil {
-			tx.Rollback()
-			h.log.Error("failed to create event", "error", err)
-			http.Error(w, "Internal server error", http.StatusInternalServerError)
-			return
-		}
-
-		// Prepare body pointer for inline transport (≤16KB bodies are
-		// included in the DeliveryTask so the engine needs no DB read).
-		var bodyPtr *string
-		if len(body) < delivery.MaxInlineBodySize {
-			bodyStr := string(body)
-			bodyPtr = &bodyStr
-		}
-
-		// Create delivery records and build self-contained delivery tasks
-		tasks := make([]delivery.DeliveryTask, 0, len(targets))
-		for i := range targets {
-			dlv := &database.Delivery{
-				EventID:  event.ID,
-				TargetID: targets[i].ID,
-				Status:   database.DeliveryStatusPending,
-			}
-			if err := tx.Create(dlv).Error; err != nil {
-				tx.Rollback()
-				h.log.Error("failed to create delivery",
-					"target_id", targets[i].ID,
-					"error", err,
-				)
-				http.Error(w, "Internal server error", http.StatusInternalServerError)
-				return
-			}
-
-			tasks = append(tasks, delivery.DeliveryTask{
-				DeliveryID:   dlv.ID,
-				EventID:      event.ID,
-				WebhookID:    entrypoint.WebhookID,
-				TargetID:     targets[i].ID,
-				TargetName:   targets[i].Name,
-				TargetType:   targets[i].Type,
-				TargetConfig: targets[i].Config,
-				MaxRetries:   targets[i].MaxRetries,
-				Method:       event.Method,
-				Headers:      event.Headers,
-				ContentType:  event.ContentType,
-				Body:         bodyPtr,
-				AttemptNum:   1,
-			})
-		}
-
-		if err := tx.Commit().Error; err != nil {
-			h.log.Error("failed to commit transaction", "error", err)
-			http.Error(w, "Internal server error", http.StatusInternalServerError)
-			return
-		}
-
-		// Notify the delivery engine with self-contained delivery tasks.
-		// Each task carries all target config and event data inline so
-		// the engine can deliver without touching any database (in the
-		// ≤16KB happy path). The engine only writes to the DB to record
-		// delivery results after each attempt.
-		if len(tasks) > 0 {
-			h.notifier.Notify(tasks)
-		}
-
-		h.log.Info("webhook event created",
-			"event_id", event.ID,
-			"webhook_id", entrypoint.WebhookID,
-			"entrypoint_id", entrypoint.ID,
-			"target_count", len(targets),
-		)
-
-		w.WriteHeader(http.StatusOK)
-		if _, err := w.Write([]byte(`{"status":"ok"}`)); err != nil {
-			h.log.Error("failed to write response", "error", err)
-		}
+		h.processWebhookRequest(w, r, entrypoint)
 	}
 }
+
+// processWebhookRequest reads the body, serializes headers,
+// loads targets, and delivers the event.
+func (h *Handlers) processWebhookRequest(
+	w http.ResponseWriter,
+	r *http.Request,
+	entrypoint database.Entrypoint,
+) {
+	body, ok := h.readWebhookBody(w, r)
+	if !ok {
+		return
+	}
+
+	headersJSON, err := json.Marshal(r.Header)
+	if err != nil {
+		h.serverError(w, "failed to serialize headers", err)
+
+		return
+	}
+
+	targets, err := h.loadActiveTargets(entrypoint.WebhookID)
+	if err != nil {
+		h.serverError(w, "failed to query targets", err)
+
+		return
+	}
+
+	h.createAndDeliverEvent(
+		w, r, entrypoint, body, headersJSON, targets,
+	)
+}
+
+// loadActiveTargets returns all active targets for a webhook.
+func (h *Handlers) loadActiveTargets(
+	webhookID string,
+) ([]database.Target, error) {
+	var targets []database.Target
+
+	err := h.db.DB().Where(
+		"webhook_id = ? AND active = ?",
+		webhookID, true,
+	).Find(&targets).Error
+
+	return targets, err
+}
+
+// lookupEntrypoint finds an entrypoint by UUID path.
+func (h *Handlers) lookupEntrypoint(
+	w http.ResponseWriter,
+	r *http.Request,
+	entrypointUUID string,
+) (database.Entrypoint, bool) {
+	var entrypoint database.Entrypoint
+
+	result := h.db.DB().Where(
+		"path = ?", entrypointUUID,
+	).First(&entrypoint)
+	if result.Error != nil {
+		h.log.Debug(
+			"entrypoint not found",
+			"path", entrypointUUID,
+		)
+		http.NotFound(w, r)
+
+		return entrypoint, false
+	}
+
+	return entrypoint, true
+}
+
+// readWebhookBody reads and validates the request body size.
+func (h *Handlers) readWebhookBody(
+	w http.ResponseWriter,
+	r *http.Request,
+) ([]byte, bool) {
+	body, err := io.ReadAll(
+		io.LimitReader(r.Body, maxWebhookBodySize+1),
+	)
+	if err != nil {
+		h.log.Error(
+			"failed to read request body", "error", err,
+		)
+		http.Error(
+			w, "Bad request", http.StatusBadRequest,
+		)
+
+		return nil, false
+	}
+
+	if len(body) > maxWebhookBodySize {
+		http.Error(
+			w,
+			"Request body too large",
+			http.StatusRequestEntityTooLarge,
+		)
+
+		return nil, false
+	}
+
+	return body, true
+}
+
+// createAndDeliverEvent creates the event and delivery records
+// then notifies the delivery engine.
+func (h *Handlers) createAndDeliverEvent(
+	w http.ResponseWriter,
+	r *http.Request,
+	entrypoint database.Entrypoint,
+	body, headersJSON []byte,
+	targets []database.Target,
+) {
+	tx, err := h.beginWebhookTx(w, entrypoint.WebhookID)
+	if err != nil {
+		return
+	}
+
+	event := h.buildEvent(r, entrypoint, headersJSON, body)
+
+	err = tx.Create(event).Error
+	if err != nil {
+		tx.Rollback()
+		h.serverError(w, "failed to create event", err)
+
+		return
+	}
+
+	bodyPtr := inlineBody(body)
+
+	tasks := h.buildDeliveryTasks(
+		w, tx, event, entrypoint, targets, bodyPtr,
+	)
+	if tasks == nil {
+		return
+	}
+
+	err = tx.Commit().Error
+	if err != nil {
+		h.serverError(w, "failed to commit transaction", err)
+
+		return
+	}
+
+	h.finishWebhookResponse(w, event, entrypoint, tasks)
+}
+
+// beginWebhookTx opens a transaction on the per-webhook DB.
+func (h *Handlers) beginWebhookTx(
+	w http.ResponseWriter,
+	webhookID string,
+) (*gorm.DB, error) {
+	webhookDB, err := h.dbMgr.GetDB(webhookID)
+	if err != nil {
+		h.serverError(
+			w, "failed to get webhook database", err,
+		)
+
+		return nil, err
+	}
+
+	tx := webhookDB.Begin()
+	if tx.Error != nil {
+		h.serverError(
+			w, "failed to begin transaction", tx.Error,
+		)
+
+		return nil, tx.Error
+	}
+
+	return tx, nil
+}
+
+// inlineBody returns a pointer to body as a string if it fits
+// within the inline size limit, or nil otherwise.
+func inlineBody(body []byte) *string {
+	if len(body) < delivery.MaxInlineBodySize {
+		s := string(body)
+
+		return &s
+	}
+
+	return nil
+}
+
+// finishWebhookResponse notifies the delivery engine, logs the
+// event, and writes the HTTP response.
+func (h *Handlers) finishWebhookResponse(
+	w http.ResponseWriter,
+	event *database.Event,
+	entrypoint database.Entrypoint,
+	tasks []delivery.Task,
+) {
+	if len(tasks) > 0 {
+		h.notifier.Notify(tasks)
+	}
+
+	h.log.Info("webhook event created",
+		"event_id", event.ID,
+		"webhook_id", entrypoint.WebhookID,
+		"entrypoint_id", entrypoint.ID,
+		"target_count", len(tasks),
+	)
+
+	w.WriteHeader(http.StatusOK)
+
+	_, err := w.Write([]byte(`{"status":"ok"}`))
+	if err != nil {
+		h.log.Error(
+			"failed to write response", "error", err,
+		)
+	}
+}
+
+// buildEvent creates a new Event struct from request data.
+func (h *Handlers) buildEvent(
+	r *http.Request,
+	entrypoint database.Entrypoint,
+	headersJSON, body []byte,
+) *database.Event {
+	return &database.Event{
+		WebhookID:    entrypoint.WebhookID,
+		EntrypointID: entrypoint.ID,
+		Method:       r.Method,
+		Headers:      string(headersJSON),
+		Body:         string(body),
+		ContentType:  r.Header.Get("Content-Type"),
+	}
+}
+
+// buildDeliveryTasks creates delivery records in the
+// transaction and returns tasks for the delivery engine.
+// Returns nil if an error occurred.
+func (h *Handlers) buildDeliveryTasks(
+	w http.ResponseWriter,
+	tx *gorm.DB,
+	event *database.Event,
+	entrypoint database.Entrypoint,
+	targets []database.Target,
+	bodyPtr *string,
+) []delivery.Task {
+	tasks := make([]delivery.Task, 0, len(targets))
+
+	for i := range targets {
+		dlv := &database.Delivery{
+			EventID:  event.ID,
+			TargetID: targets[i].ID,
+			Status:   database.DeliveryStatusPending,
+		}
+
+		err := tx.Create(dlv).Error
+		if err != nil {
+			tx.Rollback()
+			h.log.Error(
+				"failed to create delivery",
+				"target_id", targets[i].ID,
+				"error", err,
+			)
+			http.Error(
+				w, "Internal server error",
+				http.StatusInternalServerError,
+			)
+
+			return nil
+		}
+
+		tasks = append(tasks, delivery.Task{
+			DeliveryID:   dlv.ID,
+			EventID:      event.ID,
+			WebhookID:    entrypoint.WebhookID,
+			TargetID:     targets[i].ID,
+			TargetName:   targets[i].Name,
+			TargetType:   targets[i].Type,
+			TargetConfig: targets[i].Config,
+			MaxRetries:   targets[i].MaxRetries,
+			Method:       event.Method,
+			Headers:      event.Headers,
+			ContentType:  event.ContentType,
+			Body:         bodyPtr,
+			AttemptNum:   1,
+		})
+	}
+
+	return tasks
+}