go-server-with-otel/AGENTS.md

AGENTS.md — go-server-with-otel (template)

A ready-to-fork template app for the go-app framework: HTTP + gRPC + grpc-gateway + MCP + OTEL/Prometheus, wired and building. Fork it, rename it, replace the demo domain with your service. See go-app's AGENTS.md for framework internals.

Kick off a new app (do these in order)

1. Rename via the Makefile (rewrites module path, binary/app name, Dockerfile, helm, buf merge_file_name, main.go appName; deletes the old swagger file). GNU sed required (macOS: brew install gnu-sed or coreutils on PATH). The target is interactive, so pipe confirmation:

   echo y | make rename NAME=your.gitremote/pathto/newapp APP=new-app-name
   

   It does not rename the demo domain — that's steps 4–6. Afterward verify git grep go-server-with-otel is empty and update .gitea/workflows/ci.yml.

2. Edit config (pkg/config/custom.go): put app fields on ServiceConfig (keep the embedded *config.AppConfig). Add env:"..." tags for anything env-configurable — and see the env gotcha below. Update config.yaml, env-sample, and helm/values.yaml to match. Then make schema.

3. Define your proto: replace proto/demo/app/v1alpha1/ with proto/<domain>/v1alpha1/, update PROTO_DIRS in the Makefile, and run make proto (buf; managed mode → generates into api/<same path>, so the proto go_package option is overridden — don't fight it). Delete api/demo.

4. Implement service.AppService (Init, GetGRPC, GetHTTP) in a new pkg/<domain>/ package, mirroring pkg/demo:

   • <domain>grpc/ — gRPC impl (embed pb.Unimplemented...Server); GetServices returns *opts.GRPCService; GetDialOpts adds the insecure creds the gateway needs.
   • <domain>mcp/ — mcp.NewServer exposed as HTTPHandler{Prefix:"/api/mcp"}; tools via mcp.AddTool, typically delegating to the gRPC impl.
   • Remove demohttp/ unless you actually need plain HTTP funcs.

5. Register it in main.go: set appServices = []service.AppService{&yoursvc}. This should be the only functional change in main.go.

6. Delete pkg/demo and any remaining demo references.

7. Build/verify: go build ./... && go test ./..., then run and hit /metrics, /api/... (REST), :8081 (grpc + reflection), /api/mcp.

Gotchas the template inherits from go-app

• Custom-field env doesn't auto-apply. MustLoadConfigInto only parses env for the embedded AppConfig. Add a ServiceConfig.LoadEnv() that runs env.Parse over the custom fields (nil the embedded *AppConfig first to keep go-app's precedence) and call it in main.go right after MustLoadConfigInto.
• REST gateway 404s unless grpcGatewayPathStrip: true is set in the grpc config (default is false, so the /api prefix isn't stripped before matching).
• Prometheus double-unit suffix: don't use metric.WithUnit for gauges whose names already carry the unit; the exporter appends another suffix.
• MCP streamable HTTP: clients must POST to /api/mcp/ (trailing slash); the bare path 307-redirects.

What make rename does NOT touch

The demo domain naming: package dirs (pkg/demo*), proto/demo, api/demo, types (DemoService, DemoAppService, DemoTool, …), PROTO_DIRS, and the demo values in config.yaml/helm. Rename those by hand in steps 2–6.