project-go-backend

Go Backend Patterns

Stack Versions

Always pin to the latest stable Go release. Update Go toolchain (go.mod go directive + CI runner) when a new minor release is GA and has been out for 2+ weeks.

Dependency policy: prefer stdlib. When a library is needed, prefer the canonical pure-Go option:

Need	Library
File watching	github.com/fsnotify/fsnotify
SQLite	modernc.org/sqlite (pure Go, CGO-free, cross-compiles)
Logging	stdlib log/slog
HTTP routing	stdlib net/http + http.ServeMux (Go 1.22+ pattern routing)
UUIDs	github.com/google/uuid
Testing assertions	stdlib testing; resist adding testify
YAML config	gopkg.in/yaml.v3

Adding any new dependency requires a one-line note in the SOW under ## Decisions.

Concurrency Patterns

Goroutine ownership

Every goroutine has a clear owner who is responsible for starting and stopping it. Document in the constructor godoc:

// NewIngester constructs an ingester. The caller MUST call Close to stop
// the internal worker goroutines.
func NewIngester(...) *Ingester { ... }

Context propagation

• Every blocking function takes ctx context.Context as the first parameter.
• Every goroutine respects ctx.Done() for shutdown.
• HTTP handlers use r.Context() and pass it through to store/query calls.
• Registered REST handlers (mux.HandleFunc("/api/...", p.<handler>)) keep their method gate directly visible in the handler body as r.Method != http.Method... comparisons. Do not extract the method guard itself into a helper: scripts/spec-drift.sh intentionally fails closed when it cannot prove the registered verb/path contract from the handler body. Extract the error writer or response/query work instead.

Channels

• Direction: prefer <-chan T / chan<- T in function signatures to make ownership explicit.
• Buffer sizes: documented in code with a comment explaining the choice and the drop policy when full.
• Close: only the sender closes. Document who the sender is.