Compare commits
2
Commits
next
..
d6fe2c32f2
| Author | SHA1 | Date | |
|---|---|---|---|
 sneak
|
d6fe2c32f2 | ||
|
sneak
|
5c855f3eb8 |
+1
-13
@@ -17,17 +17,7 @@
|
||||
# stage that compiles runs `git describe --tags --always` on .git, which
|
||||
# does not need .git/config; that file can hold a credential, such as a
|
||||
# password in a remote URL or the token the CI checkout step stores there.
|
||||
# Each submodule keeps a config with the same exposure in its git directory
|
||||
# under .git/modules/, nested again for a submodule's own submodules, or in
|
||||
# its own .git directory when it keeps one.
|
||||
# KNOWN GAP: a submodule whose name has a `config` segment (`config`,
|
||||
# `deploy/config`, `config/lib`) loses its whole git directory, because
|
||||
# `**/.git/modules/**/config` also matches that segment's directory
|
||||
# under .git/modules/. Go's version stamping then fails the build;
|
||||
# nothing leaks. Name such a submodule without that segment:
|
||||
# `git submodule add --name`.
|
||||
**/.git/config
|
||||
**/.git/modules/**/config
|
||||
.git/config
|
||||
|
||||
# Agent scratch: one full checkout of the repo per in-flight agent.
|
||||
# Anchored because it occurs once where agents run at the repo root.
|
||||
@@ -51,9 +41,7 @@
|
||||
**/[iI][dD]_[rR][sS][aA]
|
||||
**/[iI][dD]_[dD][sS][aA]
|
||||
**/[iI][dD]_[eE][cC][dD][sS][aA]
|
||||
**/[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
|
||||
**/[iI][dD]_[eE][dD]25519
|
||||
**/[iI][dD]_[eE][dD]25519_[sS][kK]
|
||||
|
||||
# Dependencies: restored inside the image, never copied in.
|
||||
**/node_modules
|
||||
|
||||
@@ -1,4 +0,0 @@
|
||||
# Every PR adds an entry at the top of TODO.md's Completed Steps; union keeps
|
||||
# both sides instead of conflicting. Git never reports a conflict here: read
|
||||
# the merged entries after every merge or rebase.
|
||||
TODO.md merge=union
|
||||
+5
-25
@@ -20,28 +20,8 @@ Thumbs.db
|
||||
# Node
|
||||
node_modules/
|
||||
|
||||
# Secrets. Unanchored like every entry above, so each matches at every
|
||||
# depth. Matching is case-sensitive on Linux, so names use character
|
||||
# ranges rather than a lowercase form that misses `Server.Key`.
|
||||
|
||||
# Environment files. `*.env` covers bare `.env` and the `prod.env`
|
||||
# convention. Only the templates `example.env` and `sample.env` are
|
||||
# re-included below. A repository that commits any other template adds
|
||||
# its own negation after these lines, for example `!.env.example`.
|
||||
*.[eE][nN][vV]
|
||||
.[eE][nN][vV].*
|
||||
.[eE][nN][vV][rR][cC]
|
||||
!example.env
|
||||
!sample.env
|
||||
|
||||
# Private keys and the bundles carrying them.
|
||||
*.[pP][eE][mM]
|
||||
*.[kK][eE][yY]
|
||||
*.[pP]12
|
||||
*.[pP][fF][xX]
|
||||
[iI][dD]_[rR][sS][aA]
|
||||
[iI][dD]_[dD][sS][aA]
|
||||
[iI][dD]_[eE][cC][dD][sS][aA]
|
||||
[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
|
||||
[iI][dD]_[eE][dD]25519
|
||||
[iI][dD]_[eE][dD]25519_[sS][kK]
|
||||
# Environment / secrets
|
||||
.env
|
||||
.env.*
|
||||
*.pem
|
||||
*.key
|
||||
|
||||
@@ -21,86 +21,6 @@ fmt-check, and commit.
|
||||
|
||||
# Completed Steps
|
||||
|
||||
- 2026-10-04: `REPO_POLICIES.md` now says which `Dockerfile` stages run
|
||||
`script/bootstrap` (issue 90). The gate phases and the build stage start from
|
||||
their pinned base images and install what those images lack either inline, as
|
||||
the canonical Go `Dockerfile` does for `git`, or by running
|
||||
`script/bootstrap`, as this repo's own `Dockerfile` does for its yarn
|
||||
packages. The development environment stage, the final stage of a non-server
|
||||
repo, runs `script/bootstrap`. The new repo checklist says the same.
|
||||
- 2026-10-04: Added a root `.gitattributes` that merges `TODO.md` with git's
|
||||
union merge (issue 98), so two branches that each add an entry at the top of
|
||||
Completed Steps merge without a conflict. Git now never reports a conflict in
|
||||
`TODO.md`: a real conflict elsewhere keeps both versions of the line, and when
|
||||
two new entries share an identical line, one is inserted into the middle of
|
||||
the other, which a rebase can do to an entry already on `next`. Read the
|
||||
merged entries after every merge or rebase. This applies to this repository
|
||||
only; no canonical file changed.
|
||||
- 2026-10-04: The canonical `.dockerignore` now also keeps out the git `config`
|
||||
of a submodule that keeps its own `.git` directory, which still reached the
|
||||
image (issue 88): both git patterns now carry the `**/` prefix. A submodule
|
||||
whose name has a `config` segment (`config`, `deploy/config`, `config/lib`)
|
||||
still loses its whole git directory, so Go's version stamping fails the build;
|
||||
the file records this as a `KNOWN GAP:` with the remedy,
|
||||
`git submodule add --name`. Closing it would take a wildcard re-include, which
|
||||
makes BuildKit walk every excluded directory, such as `node_modules`, on every
|
||||
build. `REPO_POLICIES.md` and both checklists say so in the same words.
|
||||
- 2026-10-04: The note under the canonical Go `Dockerfile` example in
|
||||
`REPO_POLICIES.md` now installs lint-phase system libraries with `apt-get`
|
||||
under their Debian package names (issue 83). The `golangci/golangci-lint`
|
||||
image is Debian-based and has no `apk`, so the old `apk add` instruction
|
||||
failed as written. Nothing is pinned or unpinned; that is still open on
|
||||
issue 72.
|
||||
- 2026-10-04: Fixed the server lifecycle example in
|
||||
`prompts/GO_HTTP_SERVER_CONVENTIONS.md` (issue 86). Only fx handles SIGINT and
|
||||
SIGTERM, and `Run()` in `main` exits with the shutdown's exit code. A listen
|
||||
error asks fx to shut down with exit code 1 through `fx.Shutdowner`; a Sentry
|
||||
start failure is returned from the server's start hook instead of calling
|
||||
`os.Exit` from a goroutine, so the stop hooks of what had started still run.
|
||||
The server's stop hook shuts the HTTP server down within 5 seconds and fails
|
||||
when requests are still running. A new paragraph says who owns signals and the
|
||||
exit code.
|
||||
- 2026-10-04: `REPO_POLICIES.md` now says how a Go tool a repo needs on the host
|
||||
is pinned (issue 37): installed with `go install` pinned to a commit hash,
|
||||
never tracked as a `go.mod` tool dependency or through a `tools.go` file.
|
||||
golangci-lint is unaffected, since no repo installs it on the host.
|
||||
- 2026-10-04: The canonical `.gitignore` and `.dockerignore` now also keep out
|
||||
`id_ecdsa_sk` and `id_ed25519_sk`, the private key files `ssh-keygen` writes
|
||||
for keys backed by a hardware security key (issue 81). Their `.pub` halves
|
||||
stay trackable.
|
||||
- 2026-10-04: `package.json` now has `"license": "MIT"`, matching `LICENSE`, so
|
||||
yarn no longer prints "No license field" when `script/bootstrap` runs it
|
||||
inside the Docker phases (issue 76). That was the only yarn warning there.
|
||||
- 2026-10-04: `REPO_POLICIES.md` now states that guidance for coding agents
|
||||
lives in one `AGENTS.md` at the repository root, never under a file or
|
||||
directory named after one agent tool and never in separate memory files (issue
|
||||
31). This retires the rule, still present in older vendored copies, that kept
|
||||
agent memory as committed files under `.claude/memory/`. `AGENTS.md` joins the
|
||||
list of files allowed in the root, and both checklists say so.
|
||||
- 2026-10-04: Rewrote the note under the canonical Go `make test` example in
|
||||
`REPO_POLICIES.md` (issue 77), which still named the cache-busting build
|
||||
argument that `--no-cache` replaced. It now says where Go's test result cache
|
||||
can replay a pass: on a developer's machine, where the Makefile target runs,
|
||||
and not in the `test` phase of the `Dockerfile`, whose base image and earlier
|
||||
steps hold no result for the repo's tests.
|
||||
- 2026-10-04: The Makefile examples in the Go styleguide and the HTTP server
|
||||
conventions now fall back to `dev` when `git describe` prints nothing (outside
|
||||
a git checkout, or where git is missing or refuses the checkout), instead of
|
||||
stamping an empty version (issue 74). The canonical `Dockerfile` already fails
|
||||
on a `dev` version when `.git` is in the build context.
|
||||
- 2026-10-04: The canonical `.dockerignore` now also keeps out each submodule's
|
||||
`config` (issue 75). A submodule's git directory lives under `.git/modules/`,
|
||||
nested again for its own submodules, and its `config` can hold a credential
|
||||
just like `.git/config`. The pattern `.git/modules/**/config` covers every
|
||||
depth and leaves the top-level `.git` that `git describe` reads untouched.
|
||||
`REPO_POLICIES.md` and both checklists say so in the same words.
|
||||
- 2026-10-03: Fixed two defects in the canonical Go `Dockerfile` example (issue
|
||||
73). The test phase now uses the Debian Go image, since `-race` needs cgo and
|
||||
the alpine image has no C compiler, so the phase failed before running a test.
|
||||
The stage that compiles runs `git config --system --add safe.directory /src`,
|
||||
because a context sent as a tar stream keeps the sender's file owners and git
|
||||
refuses that checkout, leaving the version empty. Both checklists state that
|
||||
step in the same words.
|
||||
- 2026-10-03: Moved the canonical golangci-lint to v2.14.0, built with go1.27,
|
||||
because v2.12.2 refuses to lint a module whose `go` directive is 1.27 (issue
|
||||
65). Releases from v2.13.0 deprecate `exhaustruct` in favour of
|
||||
@@ -108,11 +28,6 @@ fmt-check, and commit.
|
||||
`.golangci.yml` now disables `exhaustruct_v5` beside `exhaustruct`. v2.12.2
|
||||
rejects that file, so `REPO_POLICIES.md` and both repo checklists now say a
|
||||
repo sets the lint phase digest and re-vendors `.golangci.yml` in one commit.
|
||||
- 2026-10-03: Brought the canonical `.gitignore` level with `.dockerignore` on
|
||||
secrets (issue 38): it now also ignores `prod.env`-style `*.env` files,
|
||||
`.envrc`, `*.p12`, `*.pfx` and the extensionless SSH private keys, written to
|
||||
`.gitignore`'s own rules (no `**/` prefix) and case-folded with character
|
||||
ranges. `example.env` and `sample.env` stay trackable through negations.
|
||||
- 2026-10-02: The image version now comes from git inside the build (issues 69
|
||||
and 71), superseding the 2026-09-08 entry that excluded `.git`. The canonical
|
||||
`.dockerignore` sends `.git` but keeps out `.git/config`, which can hold a
|
||||
|
||||
@@ -1,5 +1,4 @@
|
||||
{
|
||||
"license": "MIT",
|
||||
"devDependencies": {
|
||||
"prettier": "3.8.1"
|
||||
}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Code Styleguide — Go
|
||||
last_modified: 2026-10-04
|
||||
last_modified: 2026-10-02
|
||||
---
|
||||
|
||||
1. Try to hard wrap long lines at 77 characters or less.
|
||||
@@ -51,10 +51,8 @@ last_modified: 2026-10-04
|
||||
# ?= rather than := so that a `VERSION` build argument takes precedence:
|
||||
# where a build stage invokes make, `ARG VERSION` puts it in the
|
||||
# environment and `?=` defers to it. Otherwise `git describe` runs, in a
|
||||
# build stage on the `.git` the build context carries. When it prints
|
||||
# nothing (outside a git checkout, or where git is missing or refuses the
|
||||
# checkout), the version falls back to `dev`.
|
||||
VERSION ?= $(or $(shell git describe --tags --always 2>/dev/null),dev)
|
||||
# build stage on the `.git` the build context carries.
|
||||
VERSION ?= $(shell git describe --tags --always)
|
||||
|
||||
GOLDFLAGS += -X main.Version=$(VERSION)
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Existing Repo Checklist
|
||||
last_modified: 2026-10-04
|
||||
last_modified: 2026-10-03
|
||||
---
|
||||
|
||||
Use this checklist when beginning work in a repo that may not yet conform to our
|
||||
@@ -24,10 +24,6 @@ with your task.
|
||||
- [ ] `LICENSE` file exists and matches the README
|
||||
- [ ] `REPO_POLICIES.md` exists and version date is current — fetch from
|
||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`
|
||||
- [ ] Guidance for coding agents, if the repo has any, is one `AGENTS.md` at the
|
||||
root — never a file or directory named after one agent tool, such as
|
||||
`CLAUDE.md` or `.claude/`, and never separate memory files. Move what any
|
||||
such committed file says into `AGENTS.md` and delete it.
|
||||
- [ ] `.gitignore` is comprehensive (OS, editor, agent scratch, language
|
||||
artifacts, secrets) — fetch from
|
||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` if missing.
|
||||
@@ -63,33 +59,22 @@ with your task.
|
||||
here run anywhere other than the repo root, the anchored entry misses
|
||||
`services/api/.claude/`: add anchored entries for those directories.
|
||||
- [ ] If the repo embeds a version in a binary: `.dockerignore` lets `.git` into
|
||||
the build context. It keeps out every git `config` at any depth
|
||||
(`**/.git/config`, `**/.git/modules/**/config`): the repository's own,
|
||||
each submodule's under `.git/modules/`, and that of a submodule keeping
|
||||
its own `.git` directory. `git describe` does not need them, and each can
|
||||
hold a credential: a password in a remote URL, or the token the CI
|
||||
checkout step stores there. A submodule whose name has a `config` segment
|
||||
(`config`, `deploy/config`, `config/lib`) loses its whole git directory to
|
||||
`**/.git/modules/**/config`, and Go's version stamping then fails the
|
||||
build: give it a name without that segment (`git submodule add --name`).
|
||||
The stage that compiles has `git` (the Debian Go image has it; an alpine
|
||||
one needs `apk add --no-cache git`) and takes the version from the
|
||||
`VERSION` build argument when one is given, otherwise from
|
||||
`git describe --tags --always`. That gives the tag on a tagged commit; on
|
||||
a later commit, the tag, the number of commits since it and the short
|
||||
commit (`v1.2.3-4-gabc1234`); and the short commit when no tag is
|
||||
reachable. The stage that compiles also marks its working directory safe
|
||||
for git (`git config --system --add safe.directory /src`): a context sent
|
||||
as a tar stream keeps the sender's file owners, and git refuses a checkout
|
||||
owned by another user, so the version would come out empty. `ARG VERSION`
|
||||
has no default, and the build fails if the context carries `.git` and the
|
||||
version still comes out empty, `dev` or `unknown`. A plain
|
||||
`docker build .` with no build arguments must succeed; a Dockerfile that
|
||||
refuses an empty build argument drops that refusal and keeps the argument.
|
||||
`script/docker` and `script/cibuild` pass the version they compute on the
|
||||
host; it takes precedence. A tag-derived version additionally needs
|
||||
`fetch-depth: 0` on the CI checkout step, which clones shallow and fetches
|
||||
no tags by default.
|
||||
the build context. It keeps out `.git/config`, which `git describe` does
|
||||
not need and which can hold a credential: a password in a remote URL, or
|
||||
the token the CI checkout step stores there. The stage that compiles has
|
||||
`git` (the Debian Go image has it; an alpine one needs
|
||||
`apk add --no-cache git`) and takes the version from the `VERSION` build
|
||||
argument when one is given, otherwise from `git describe --tags --always`.
|
||||
That gives the tag on a tagged commit; on a later commit, the tag, the
|
||||
number of commits since it and the short commit (`v1.2.3-4-gabc1234`); and
|
||||
the short commit when no tag is reachable. `ARG VERSION` has no default,
|
||||
and the build fails if the context carries `.git` and the version still
|
||||
comes out empty, `dev` or `unknown`. A plain `docker build .` with no
|
||||
build arguments must succeed; a Dockerfile that refuses an empty build
|
||||
argument drops that refusal and keeps the argument. `script/docker` and
|
||||
`script/cibuild` pass the version they compute on the host; it takes
|
||||
precedence. A tag-derived version additionally needs `fetch-depth: 0` on
|
||||
the CI checkout step, which clones shallow and fetches no tags by default.
|
||||
- [ ] Gitea Actions workflow in `.gitea/workflows/` runs `script/cibuild` on
|
||||
push — reference
|
||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitea/workflows/check.yml`
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Go HTTP Server Conventions
|
||||
last_modified: 2026-10-04
|
||||
last_modified: 2026-10-02
|
||||
---
|
||||
|
||||
This document defines the architectural patterns, design decisions, and
|
||||
@@ -106,9 +106,6 @@ project-root/
|
||||
package main
|
||||
|
||||
import (
|
||||
"os/signal"
|
||||
"syscall"
|
||||
|
||||
"yourproject/internal/config"
|
||||
"yourproject/internal/database"
|
||||
"yourproject/internal/globals"
|
||||
@@ -129,9 +126,6 @@ func main() {
|
||||
globals.Appname = Appname
|
||||
globals.Version = Version
|
||||
|
||||
// A write to a closed stdout or stderr must not end the process.
|
||||
signal.Ignore(syscall.SIGPIPE)
|
||||
|
||||
fx.New(
|
||||
fx.Provide(
|
||||
config.New,
|
||||
@@ -204,8 +198,7 @@ Providers are resolved automatically by fx, but conceptually follow this order:
|
||||
Database)
|
||||
6. `middleware.New` - Middleware (depends on Logger, Globals, Config)
|
||||
7. `handlers.New` - Handlers (depends on Logger, Globals, Database, Healthcheck)
|
||||
8. `server.New` - Server (depends on all above, and on `fx.Shutdowner`, which fx
|
||||
provides itself)
|
||||
8. `server.New` - Server (depends on all above)
|
||||
|
||||
---
|
||||
|
||||
@@ -224,14 +217,16 @@ type ServerParams struct {
|
||||
Config *config.Config
|
||||
Middleware *middleware.Middleware
|
||||
Handlers *handlers.Handlers
|
||||
Shutdowner fx.Shutdowner
|
||||
}
|
||||
|
||||
type Server struct {
|
||||
startupTime time.Time
|
||||
port int
|
||||
exitCode int
|
||||
sentryEnabled bool
|
||||
log *slog.Logger
|
||||
ctx context.Context
|
||||
cancelFunc context.CancelFunc
|
||||
httpServer *http.Server
|
||||
router *chi.Mux
|
||||
params ServerParams
|
||||
@@ -253,15 +248,13 @@ func New(lc fx.Lifecycle, params ServerParams) (*Server, error) {
|
||||
lc.Append(fx.Hook{
|
||||
OnStart: func(ctx context.Context) error {
|
||||
s.startupTime = time.Now()
|
||||
if err := s.enableSentry(); err != nil {
|
||||
return err
|
||||
}
|
||||
s.SetupRoutes()
|
||||
s.httpServer = s.newHTTPServer()
|
||||
go s.serveUntilShutdown()
|
||||
go s.Run()
|
||||
return nil
|
||||
},
|
||||
OnStop: func(ctx context.Context) error {
|
||||
// Server shutdown logic
|
||||
return nil
|
||||
},
|
||||
OnStop: s.cleanShutdown,
|
||||
})
|
||||
return s, nil
|
||||
}
|
||||
@@ -271,25 +264,23 @@ func New(lc fx.Lifecycle, params ServerParams) (*Server, error) {
|
||||
|
||||
```go
|
||||
// internal/server/http.go
|
||||
func (s *Server) newHTTPServer() *http.Server {
|
||||
return &http.Server{
|
||||
Addr: fmt.Sprintf(":%d", s.params.Config.Port),
|
||||
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,
|
||||
Handler: s,
|
||||
}
|
||||
}
|
||||
|
||||
// serveUntilShutdown returns when the stop hook shuts the HTTP server down.
|
||||
// If it stops for any other reason, such as its port being taken, it asks fx
|
||||
// to shut down with exit code 1.
|
||||
func (s *Server) serveUntilShutdown() {
|
||||
s.log.Info("http begin listen", "listenaddr", s.httpServer.Addr)
|
||||
s.SetupRoutes()
|
||||
|
||||
s.log.Info("http begin listen", "listenaddr", listenAddr)
|
||||
if err := s.httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {
|
||||
s.log.Error("listen error", "error", err)
|
||||
if err := s.params.Shutdowner.Shutdown(fx.ExitCode(1)); err != nil {
|
||||
s.log.Error("shutdown request failed", "error", err)
|
||||
if s.cancelFunc != nil {
|
||||
s.cancelFunc()
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -301,30 +292,43 @@ func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
|
||||
|
||||
## Signal Handling and Graceful Shutdown
|
||||
|
||||
fx owns SIGINT, SIGTERM and the exit code. `Run()` in `main` waits for one of
|
||||
those signals or for a call to `Shutdown()` on `fx.Shutdowner`, runs the stop
|
||||
hooks, and exits 0 after a signal, or with the code the call gave in
|
||||
`fx.ExitCode`. It exits 1 instead when a start hook or a stop hook returns an
|
||||
error; when a start hook fails, fx first runs the stop hooks of everything
|
||||
already started. No other code calls `signal.Notify` or `os.Exit`: the listen
|
||||
error above asks fx to shut down with `fx.ExitCode(1)`, and a Sentry start
|
||||
failure is returned from the start hook. Each component releases its own
|
||||
resources in its own stop hook, which fx runs in the reverse order of start.
|
||||
|
||||
```go
|
||||
// cleanShutdown is the server's stop hook. It fails when requests are still
|
||||
// running after 5 seconds.
|
||||
func (s *Server) cleanShutdown(ctx context.Context) error {
|
||||
ctxShutdown, shutdownCancel := context.WithTimeout(ctx, 5*time.Second)
|
||||
defer shutdownCancel()
|
||||
err := s.httpServer.Shutdown(ctxShutdown)
|
||||
func (s *Server) serve() int {
|
||||
s.ctx, s.cancelFunc = context.WithCancel(context.Background())
|
||||
|
||||
// Signal watcher
|
||||
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()
|
||||
}
|
||||
}()
|
||||
|
||||
go s.serveUntilShutdown()
|
||||
|
||||
for range s.ctx.Done() {
|
||||
}
|
||||
s.cleanShutdown()
|
||||
return s.exitCode
|
||||
}
|
||||
|
||||
func (s *Server) cleanShutdown() {
|
||||
s.exitCode = 0
|
||||
ctxShutdown, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second)
|
||||
if err := s.httpServer.Shutdown(ctxShutdown); err != nil {
|
||||
s.log.Error("server clean shutdown failed", "error", err)
|
||||
}
|
||||
if shutdownCancel != nil {
|
||||
shutdownCancel()
|
||||
}
|
||||
s.cleanupForExit()
|
||||
if s.sentryEnabled {
|
||||
sentry.Flush(2 * time.Second)
|
||||
}
|
||||
if err != nil {
|
||||
return fmt.Errorf("http server shutdown: %w", err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
@@ -983,10 +987,8 @@ Use ldflags to inject version information at build time:
|
||||
# ?= rather than := so that a `VERSION` build argument takes precedence:
|
||||
# where a build stage invokes make, `ARG VERSION` puts it in the
|
||||
# environment and `?=` defers to it. Otherwise `git describe` runs, in a
|
||||
# build stage on the `.git` the build context carries. When it prints
|
||||
# nothing (outside a git checkout, or where git is missing or refuses the
|
||||
# checkout), the version falls back to `dev`.
|
||||
VERSION ?= $(or $(shell git describe --tags --always 2>/dev/null),dev)
|
||||
# build stage on the `.git` the build context carries.
|
||||
VERSION ?= $(shell git describe --tags --always)
|
||||
|
||||
build:
|
||||
go build -ldflags "-X main.Version=$(VERSION)" ./cmd/httpd
|
||||
@@ -1156,11 +1158,11 @@ s.router.Get("/.well-known/healthcheck", s.h.HandleHealthCheck())
|
||||
Sentry is conditionally enabled based on `SENTRY_DSN` environment variable:
|
||||
|
||||
```go
|
||||
func (s *Server) enableSentry() error {
|
||||
func (s *Server) enableSentry() {
|
||||
s.sentryEnabled = false
|
||||
|
||||
if s.params.Config.SentryDSN == "" {
|
||||
return nil
|
||||
return
|
||||
}
|
||||
|
||||
err := sentry.Init(sentry.ClientOptions{
|
||||
@@ -1168,17 +1170,15 @@ func (s *Server) enableSentry() error {
|
||||
Release: fmt.Sprintf("%s-%s", s.params.Globals.Appname, s.params.Globals.Version),
|
||||
})
|
||||
if err != nil {
|
||||
return fmt.Errorf("sentry init failure: %w", err)
|
||||
s.log.Error("sentry init failure", "error", err)
|
||||
os.Exit(1)
|
||||
return
|
||||
}
|
||||
s.log.Info("sentry error reporting activated")
|
||||
s.sentryEnabled = true
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
The server's start hook calls `enableSentry()` and returns its error, so a DSN
|
||||
Sentry rejects stops startup and fx exits 1.
|
||||
|
||||
Sentry middleware with repanic (bubbles panics to chi's Recoverer):
|
||||
|
||||
```go
|
||||
@@ -1190,7 +1190,7 @@ if s.sentryEnabled {
|
||||
}
|
||||
```
|
||||
|
||||
Flush Sentry in the server's stop hook, `cleanShutdown()`:
|
||||
Flush Sentry on shutdown:
|
||||
|
||||
```go
|
||||
if s.sentryEnabled {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: New Repo Checklist
|
||||
last_modified: 2026-10-04
|
||||
last_modified: 2026-10-03
|
||||
---
|
||||
|
||||
Use this checklist when creating a new repository from scratch. Follow the steps
|
||||
@@ -54,9 +54,6 @@ Template files can be fetched from:
|
||||
- [ ] `LICENSE` file matching the chosen license
|
||||
- [ ] `REPO_POLICIES.md` — fetch from
|
||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`
|
||||
- [ ] Guidance for coding agents, if the repo has any, is one `AGENTS.md` at the
|
||||
root — never a file or directory named after one agent tool, such as
|
||||
`CLAUDE.md` or `.claude/`, and never separate memory files
|
||||
- [ ] `Dockerfile` and `.dockerignore` — fetch `.dockerignore` from
|
||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore`
|
||||
- Extend `.dockerignore` with the repo's own host-built artifacts, giving
|
||||
@@ -71,29 +68,19 @@ Template files can be fetched from:
|
||||
will run them in subdirectories, `services/api/.claude/` needs its own
|
||||
anchored entry.
|
||||
- If the image embeds a version in a binary: `.dockerignore` lets `.git`
|
||||
into the build context. It keeps out every git `config` at any depth
|
||||
(`**/.git/config`, `**/.git/modules/**/config`): the repository's own,
|
||||
each submodule's under `.git/modules/`, and that of a submodule keeping
|
||||
its own `.git` directory. `git describe` does not need them, and each can
|
||||
hold a credential: a password in a remote URL, or the token the CI
|
||||
checkout step stores there. A submodule whose name has a `config` segment
|
||||
(`config`, `deploy/config`, `config/lib`) loses its whole git directory to
|
||||
`**/.git/modules/**/config`, and Go's version stamping then fails the
|
||||
build: give it a name without that segment (`git submodule add --name`).
|
||||
The stage that compiles has `git` (the Debian Go image has it; an alpine
|
||||
one needs `apk add --no-cache git`) and takes the version from the
|
||||
`VERSION` build argument when one is given, otherwise from
|
||||
`git describe --tags --always`. That gives the tag on a tagged commit; on
|
||||
a later commit, the tag, the number of commits since it and the short
|
||||
commit (`v1.2.3-4-gabc1234`); and the short commit when no tag is
|
||||
reachable. The stage that compiles also marks its working directory safe
|
||||
for git (`git config --system --add safe.directory /src`): a context sent
|
||||
as a tar stream keeps the sender's file owners, and git refuses a checkout
|
||||
owned by another user, so the version would come out empty. `ARG VERSION`
|
||||
has no default, and the build fails if the context carries `.git` and the
|
||||
version still comes out empty, `dev` or `unknown`. A plain
|
||||
`docker build .` with no build arguments must succeed; a Dockerfile that
|
||||
refuses an empty build argument drops that refusal and keeps the argument.
|
||||
into the build context. It keeps out `.git/config`, which `git describe`
|
||||
does not need and which can hold a credential: a password in a remote URL,
|
||||
or the token the CI checkout step stores there. The stage that compiles
|
||||
has `git` (the Debian Go image has it; an alpine one needs
|
||||
`apk add --no-cache git`) and takes the version from the `VERSION` build
|
||||
argument when one is given, otherwise from `git describe --tags --always`.
|
||||
That gives the tag on a tagged commit; on a later commit, the tag, the
|
||||
number of commits since it and the short commit (`v1.2.3-4-gabc1234`); and
|
||||
the short commit when no tag is reachable. `ARG VERSION` has no default,
|
||||
and the build fails if the context carries `.git` and the version still
|
||||
comes out empty, `dev` or `unknown`. A plain `docker build .` with no
|
||||
build arguments must succeed; a Dockerfile that refuses an empty build
|
||||
argument drops that refusal and keeps the argument.
|
||||
- The Dockerfile carries a `lint` phase and a `test` phase, each invoking
|
||||
its tool directly rather than through `make` or `script/`, and the final
|
||||
stage carries a `COPY --from=` of a harmless file from each so the image
|
||||
@@ -124,10 +111,8 @@ are thin shims calling them. Model scripts:
|
||||
- [ ] `script/bootstrap` / `make bootstrap` — installs all dependencies,
|
||||
idempotently, assuming nothing (pkg manager detection nix/apt/brew/apk;
|
||||
node used if present, else pinned version via nvm from a hash-verified
|
||||
archive; pinned yarn via corepack); a non-server repo's development
|
||||
environment stage runs it instead of inline installs; a gate phase or the
|
||||
build stage installs what its base image lacks either inline or by running
|
||||
it
|
||||
archive; pinned yarn via corepack); Dockerfile runs it instead of inline
|
||||
installs
|
||||
- [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`,
|
||||
then `install-precommit`, plus repo-specific init
|
||||
- [ ] `script/test` / `make test` — `docker build --no-cache --target test .`,
|
||||
|
||||
+38
-75
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Repository Policies
|
||||
last_modified: 2026-10-04
|
||||
last_modified: 2026-10-03
|
||||
---
|
||||
|
||||
This document covers repository structure, tooling, and workflow standards. Code
|
||||
@@ -104,14 +104,10 @@ style conventions are in separate documents:
|
||||
`lint` phase and a `test` phase, with the final stage depending on both so the
|
||||
image cannot be built unless they pass. For non-server repos the final stage
|
||||
brings up a development environment; for server repos it is the runtime image.
|
||||
The gate phases and the build stage start from their pinned base images and
|
||||
install what those images lack either inline, as the canonical Go `Dockerfile`
|
||||
below does for `git`, or by running `script/bootstrap`, as the `prompts`
|
||||
repo's own `Dockerfile` does for its yarn packages. The development
|
||||
environment stage installs development prerequisites by running
|
||||
`script/bootstrap` rather than duplicating its installs inline. A stage that
|
||||
runs `script/bootstrap` COPYs `script/` and the dependency manifests
|
||||
(`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it.
|
||||
Dockerfiles install development prerequisites by running `script/bootstrap`
|
||||
rather than duplicating installs inline; COPY `script/` and the dependency
|
||||
manifests (`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before
|
||||
running it.
|
||||
|
||||
- **Linting and testing run in Docker, as phases of the `Dockerfile`.** There is
|
||||
no separate lint file. `script/lint` and `script/test` each build one phase
|
||||
@@ -164,7 +160,7 @@ style conventions are in separate documents:
|
||||
- **The gate phases are separate stages, and the build stage depends on both.**
|
||||
The lint phase is based on the `golangci/golangci-lint` image (pinned by
|
||||
hash), so lint failures surface in seconds rather than after a full compile,
|
||||
and the test phase is based on the Debian Go image. The canonical Go repo
|
||||
and the test phase is based on the Go image. The canonical Go repo
|
||||
`Dockerfile`:
|
||||
|
||||
```dockerfile
|
||||
@@ -177,9 +173,8 @@ style conventions are in separate documents:
|
||||
COPY . .
|
||||
RUN golangci-lint run --config .golangci.yml ./...
|
||||
|
||||
# Test phase. -race needs cgo and so a C compiler, which the Debian Go
|
||||
# image ships and the alpine one does not.
|
||||
# golang:1.x, YYYY-MM-DD
|
||||
# Test phase
|
||||
# golang:1.x-alpine, YYYY-MM-DD
|
||||
FROM golang@sha256:... AS test
|
||||
WORKDIR /src
|
||||
COPY go.mod go.sum ./
|
||||
@@ -197,8 +192,6 @@ style conventions are in separate documents:
|
||||
COPY --from=lint /src/go.sum /dev/null
|
||||
COPY --from=test /src/go.sum /dev/null
|
||||
RUN apk add --no-cache git
|
||||
# A tar-stream context keeps the sender's file owners, which git refuses.
|
||||
RUN git config --system --add safe.directory /src
|
||||
WORKDIR /src
|
||||
COPY go.mod go.sum ./
|
||||
RUN go mod download
|
||||
@@ -240,41 +233,22 @@ style conventions are in separate documents:
|
||||
(e.g. a web frontend compiled in a separate stage), the lint phase must
|
||||
create placeholder files so the embed directives resolve. Example:
|
||||
`RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css`.
|
||||
- If the project requires CGO or system libraries for linting, install them
|
||||
in the lint phase. The `golangci/golangci-lint` image is Debian-based and
|
||||
has no `apk`, so install with `apt-get` under the Debian package name
|
||||
(`libvips-dev`, where alpine says `vips-dev`), and delete the package
|
||||
lists in the same `RUN`, so the layer does not keep them:
|
||||
|
||||
```dockerfile
|
||||
RUN apt-get update \
|
||||
&& apt-get install -y --no-install-recommends libvips-dev \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
```
|
||||
|
||||
- `.dockerignore` lets `.git` into the build context. It keeps out every git
|
||||
`config` at any depth (`**/.git/config`, `**/.git/modules/**/config`): the
|
||||
repository's own, each submodule's under `.git/modules/`, and that of a
|
||||
submodule keeping its own `.git` directory. `git describe` does not need
|
||||
them, and each can hold a credential: a password in a remote URL, or the
|
||||
token the CI checkout step stores there. A submodule whose name has a
|
||||
`config` segment (`config`, `deploy/config`, `config/lib`) loses its whole
|
||||
git directory to `**/.git/modules/**/config`, and Go's version stamping
|
||||
then fails the build: give it a name without that segment
|
||||
(`git submodule add --name`). The stage that compiles has `git` (the
|
||||
Debian Go image has it; an alpine one needs `apk add --no-cache git`) and
|
||||
takes the version from the `VERSION` build argument when one is given,
|
||||
otherwise from `git describe --tags --always`. That gives the tag on a
|
||||
tagged commit; on a later commit, the tag, the number of commits since it
|
||||
and the short commit (`v1.2.3-4-gabc1234`); and the short commit when no
|
||||
tag is reachable. The stage that compiles also marks its working directory
|
||||
safe for git (`git config --system --add safe.directory /src`): a context
|
||||
sent as a tar stream keeps the sender's file owners, and git refuses a
|
||||
checkout owned by another user, so the version would come out empty.
|
||||
`ARG VERSION` has no default, and the build fails if the context carries
|
||||
`.git` and the version still comes out empty, `dev` or `unknown`. A plain
|
||||
`docker build .` with no build arguments must succeed; a Dockerfile that
|
||||
refuses an empty build argument drops that refusal and keeps the argument.
|
||||
- If the project requires CGO or system libraries for linting (e.g.
|
||||
`vips-dev`), install them in the lint phase with `apk add`.
|
||||
- `.dockerignore` lets `.git` into the build context. It keeps out
|
||||
`.git/config`, which `git describe` does not need and which can hold a
|
||||
credential: a password in a remote URL, or the token the CI checkout step
|
||||
stores there. The stage that compiles has `git` (the Debian Go image has
|
||||
it; an alpine one needs `apk add --no-cache git`) and takes the version
|
||||
from the `VERSION` build argument when one is given, otherwise from
|
||||
`git describe --tags --always`. That gives the tag on a tagged commit; on
|
||||
a later commit, the tag, the number of commits since it and the short
|
||||
commit (`v1.2.3-4-gabc1234`); and the short commit when no tag is
|
||||
reachable. `ARG VERSION` has no default, and the build fails if the
|
||||
context carries `.git` and the version still comes out empty, `dev` or
|
||||
`unknown`. A plain `docker build .` with no build arguments must succeed;
|
||||
a Dockerfile that refuses an empty build argument drops that refusal and
|
||||
keeps the argument.
|
||||
|
||||
- Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
|
||||
runs `script/cibuild` on push, and checks out the repo as its only other step.
|
||||
@@ -336,19 +310,17 @@ style conventions are in separate documents:
|
||||
```
|
||||
|
||||
`-count=1` is required on both invocations: it defeats Go's test _result_
|
||||
cache, so neither run can report a stored pass in place of running the
|
||||
tests. It leaves the build cache alone, so it costs the runtime of the suite
|
||||
and no recompilation.
|
||||
cache, so the target cannot report a pass it did not earn, and the rerun
|
||||
reproduces a failure instead of replaying it. It leaves the build cache
|
||||
alone, so it costs the runtime of the suite and no recompilation.
|
||||
|
||||
That cache is Go's own, separate from Docker's layer cache. Go stores a
|
||||
passing result in its cache directory (`GOCACHE`), and when the same tests
|
||||
run again on unchanged code it prints that result, marked `(cached)`,
|
||||
without running them. That matters on a developer's machine, where this
|
||||
target runs and the directory lasts from one run to the next. The `test`
|
||||
phase of the `Dockerfile` needs no `-count=1`: its base image holds no
|
||||
result for this repo's tests and nothing before its `go test` step runs a
|
||||
test, so there is nothing to replay. `--no-cache` (above) is what makes that
|
||||
step run on an unchanged tree.
|
||||
Note that this is a second, independent cache, stacked below the Docker
|
||||
layer cache that [issue #26](https://git.eeqj.de/sneak/prompts/issues/26)
|
||||
addresses. `CHECK_EPOCH` guarantees the `RUN make test` _step_ re-executes;
|
||||
it does not guarantee `go test` inside that step does any work, because the
|
||||
`GOCACHE` baked into earlier image layers survives into the re-executed
|
||||
step. They are two separate defects requiring two separate fixes, and a fix
|
||||
for one must not be recorded as covering the other.
|
||||
|
||||
Python example:
|
||||
|
||||
@@ -514,11 +486,6 @@ style conventions are in separate documents:
|
||||
|
||||
Keep it POSIX sh: no arrays, no `[[`, no `grep -P`.
|
||||
|
||||
A Go tool a repo needs on the host is installed with `go install` pinned to
|
||||
a commit hash (`go install <package>@<commit hash>`). It is never tracked as
|
||||
a `go.mod` tool dependency or through a `tools.go` file, either of which
|
||||
pulls the tool's own dependencies into the repo's `go.mod` and `go.sum`.
|
||||
|
||||
- When pinning images or packages by hash, add a comment above the reference
|
||||
with the version and date (YYYY-MM-DD).
|
||||
|
||||
@@ -631,10 +598,10 @@ style conventions are in separate documents:
|
||||
settings.
|
||||
|
||||
- Avoid putting files in the repo root unless necessary. Root should contain
|
||||
only project-level config files (`README.md`, `AGENTS.md`, `Makefile`,
|
||||
`Dockerfile`, `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`,
|
||||
and language-specific config). Everything else goes in a subdirectory.
|
||||
Canonical subdirectory names:
|
||||
only project-level config files (`README.md`, `Makefile`, `Dockerfile`,
|
||||
`LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and
|
||||
language-specific config). Everything else goes in a subdirectory. Canonical
|
||||
subdirectory names:
|
||||
- `bin/` — executable scripts and tools
|
||||
- `cmd/` — Go command entrypoints; thin only: one `main.go` per binary whose
|
||||
body is a single call into `internal/` or `pkg/`, no project logic in
|
||||
@@ -665,7 +632,3 @@ style conventions are in separate documents:
|
||||
- Go: `go.mod`, `go.sum`, `.golangci.yml`
|
||||
- JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
|
||||
- Python: `pyproject.toml`
|
||||
|
||||
- Guidance for coding agents lives in one `AGENTS.md` at the repository root. It
|
||||
is never committed under a file or directory named after one agent tool, such
|
||||
as `CLAUDE.md` or `.claude/`, and never split into separate memory files.
|
||||
|
||||
Reference in New Issue
Block a user