Go service rules

# AGENTS.md: Go service

Go module. Check the `go` directive in `go.mod` before using newer language or standard library features.

## Commands
- Build: `go build ./...`. Tests: `go test -race ./...`. Vet: `go vet ./...`.
- Format: `gofmt -l .` must print nothing (or `goimports` if the project uses it).
- Lint, if `.golangci.yml` exists: `golangci-lint run`.
- Done means: gofmt clean, vet clean, tests green with `-race`.

## Errors
- Return errors; never `panic` on input. Wrap with context: `fmt.Errorf("load user %d: %w", id, err)`.
- Compare with `errors.Is` and `errors.As`, never by string. Define sentinel errors (`var ErrNotFound = errors.New(...)`)
  for conditions callers handle.
- Handle every error once: either return it or log it, not both.

## Concurrency
- `context.Context` is the first parameter of anything that does I/O or may block. Respect cancellation.
- Every goroutine has an owner and a way to stop (context, closed channel or `errgroup`). No fire-and-forget goroutines.
- Shared state behind a mutex or owned by one goroutine. `go test -race` must stay clean.

## HTTP
- Go 1.22+ routing: `mux.HandleFunc("GET /items/{id}", h)` and `r.PathValue("id")`. Do not add a router library for that.
- Servers set timeouts (`ReadHeaderTimeout` at least). Clients use a `http.Client` with `Timeout`, never the default client
  for external calls.
- Write JSON with the right `Content-Type` and status; decode with a size limit (`http.MaxBytesReader`).

## Dependencies and style
- Standard library first. Ask before adding a module; then `go get <module>@<version>` and `go mod tidy`.
- Logging with `log/slog`, structured key-value pairs. No secrets in logs.
- Table-driven tests with `t.Run`; `net/http/httptest` for handlers. New handlers: use the `go-http-handler` skill.
- Small interfaces, defined where they are used. Accept interfaces, return structs.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `go-http-handler`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Go service rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/go-service/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `go-http-handler`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Go service rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/go-service/ -->

---
name: go-http-handler
description: Add a Go net/http handler with 1.22+ routing, a size-limited JSON body, wrapped errors mapped to status codes and table-driven httptest tests. Use when adding or changing an HTTP endpoint.
---

# Go HTTP handler

1. Read how the service builds its `http.ServeMux` and stores dependencies (usually a struct with methods).
2. Follow `references/handler.go`: a method on the server struct, `r.PathValue` for path parameters,
   `http.MaxBytesReader` plus `json.Decoder` with `DisallowUnknownFields` for bodies.
3. Map errors to status codes in one place: `errors.Is(err, ErrNotFound)` gives 404, validation 400, everything else 500
   with the detail logged through `slog`, not sent to the client.
4. Register the route with method and pattern: `mux.HandleFunc("POST /items", s.createItem)`.
5. Tests like `references/handler_test.go`: table-driven, `httptest.NewRecorder`, one row per status code.
6. Run `gofmt -l .`, `go vet ./...` and `go test -race ./...`. Report the results.

// Package items is an example of a net/http handler set: Go 1.22+ routing, limited JSON bodies, errors mapped to status.
package items

import (
	"encoding/json"
	"errors"
	"fmt"
	"log/slog"
	"net/http"
	"strconv"
	"sync"
)

// ErrNotFound is returned when an item does not exist.
var ErrNotFound = errors.New("item not found")

// Item is the public representation of an item.
type Item struct {
	ID         int    `json:"id"`
	Name       string `json:"name"`
	PricePence int    `json:"price_pence"`
}

// Server holds dependencies for the handlers.
type Server struct {
	mu    sync.Mutex
	items map[int]Item
	log   *slog.Logger
}

// NewServer returns a Server with an empty store.
func NewServer(log *slog.Logger) *Server {
	return &Server{items: map[int]Item{}, log: log}
}

// Routes registers the handlers on a new mux.
func (s *Server) Routes() *http.ServeMux {
	mux := http.NewServeMux()
	mux.HandleFunc("POST /items", s.createItem)
	mux.HandleFunc("GET /items/{id}", s.getItem)
	return mux
}

func (s *Server) find(id int) (Item, error) {
	s.mu.Lock()
	defer s.mu.Unlock()
	it, ok := s.items[id]
	if !ok {
		return Item{}, fmt.Errorf("find %d: %w", id, ErrNotFound)
	}
	return it, nil
}

func (s *Server) getItem(w http.ResponseWriter, r *http.Request) {
	id, err := strconv.Atoi(r.PathValue("id"))
	if err != nil {
		http.Error(w, "id must be a number", http.StatusBadRequest)
		return
	}
	it, err := s.find(id)
	if err != nil {
		s.fail(w, err)
		return
	}
	writeJSON(w, http.StatusOK, it)
}

func (s *Server) createItem(w http.ResponseWriter, r *http.Request) {
	r.Body = http.MaxBytesReader(w, r.Body, 1<<20)
	dec := json.NewDecoder(r.Body)
	dec.DisallowUnknownFields()
	var in struct {
		Name       string `json:"name"`
		PricePence int    `json:"price_pence"`
	}
	if err := dec.Decode(&in); err != nil {
		http.Error(w, "invalid JSON body", http.StatusBadRequest)
		return
	}
	if in.Name == "" || in.PricePence < 0 {
		http.Error(w, "name is required and price_pence must be 0 or more", http.StatusBadRequest)
		return
	}
	s.mu.Lock()
	it := Item{ID: len(s.items) + 1, Name: in.Name, PricePence: in.PricePence}
	s.items[it.ID] = it
	s.mu.Unlock()
	writeJSON(w, http.StatusCreated, it)
}

// fail maps errors to status codes in one place. Internal detail is logged, not sent.
func (s *Server) fail(w http.ResponseWriter, err error) {
	switch {
	case errors.Is(err, ErrNotFound):
		http.Error(w, "not found", http.StatusNotFound)
	default:
		s.log.Error("request failed", "err", err)
		http.Error(w, "internal error", http.StatusInternalServerError)
	}
}

func writeJSON(w http.ResponseWriter, status int, v any) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	_ = json.NewEncoder(w).Encode(v)
}

package items

import (
	"io"
	"log/slog"
	"net/http"
	"net/http/httptest"
	"strings"
	"testing"
)

func TestHandlers(t *testing.T) {
	srv := NewServer(slog.New(slog.NewTextHandler(io.Discard, nil)))
	h := srv.Routes()

	tests := []struct {
		name, method, path, body string
		want                     int
	}{
		{"create", "POST", "/items", `{"name":"Tea","price_pence":250}`, http.StatusCreated},
		{"read created", "GET", "/items/1", "", http.StatusOK},
		{"missing", "GET", "/items/99", "", http.StatusNotFound},
		{"bad id", "GET", "/items/abc", "", http.StatusBadRequest},
		{"unknown field", "POST", "/items", `{"name":"Tea","colour":"red"}`, http.StatusBadRequest},
		{"negative price", "POST", "/items", `{"name":"Tea","price_pence":-1}`, http.StatusBadRequest},
		{"wrong method", "DELETE", "/items/1", "", http.StatusMethodNotAllowed},
	}
	for _, tc := range tests {
		t.Run(tc.name, func(t *testing.T) {
			req := httptest.NewRequest(tc.method, tc.path, strings.NewReader(tc.body))
			rec := httptest.NewRecorder()
			h.ServeHTTP(rec, req)
			if rec.Code != tc.want {
				t.Fatalf("%s %s: got %d, want %d (%s)", tc.method, tc.path, rec.Code, tc.want, rec.Body.String())
			}
		})
	}
}