@nakedev/go-scaffold 0.1.2 → 0.1.4

package/templates/add/rbac/internal/app/role/service_test.go.hbs

@@ -0,0 +1,119 @@
+package role
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"testing"
+
+	"{{goModule}}/internal/app/role/model"
+	"{{goModule}}/internal/shared/apperror"
+)
+
+// fakeRepo = mock of the repository interface, so the service can be tested
+// without a DB — countWithPermission stands in for "how many roles OTHER
+// than the one being edited currently grant PermRoleManage", exactly what
+// CountRolesWithPermission's excludeCode param means.
+type fakeRepo struct {
+	role                *model.Role
+	findErr             error
+	allPermissionCodes  []string
+	countWithPermission int64
+	setPermissionsErr   error
+	deleteErr           error
+}
+
+func (f *fakeRepo) PermissionCodes(context.Context, string) ([]string, error) { return nil, nil }
+func (f *fakeRepo) FindAll(context.Context, int, int) ([]model.Role, error)   { return nil, nil }
+func (f *fakeRepo) FindByCode(context.Context, string) (*model.Role, error) {
+	if f.findErr != nil {
+		return nil, f.findErr
+	}
+	return f.role, nil
+}
+func (f *fakeRepo) Create(context.Context, *model.Role) error { return nil }
+func (f *fakeRepo) SetPermissions(context.Context, string, []string) error {
+	return f.setPermissionsErr
+}
+func (f *fakeRepo) Delete(context.Context, string) error { return f.deleteErr }
+func (f *fakeRepo) FindAllPermissions(context.Context, int, int) ([]model.Permission, error) {
+	return nil, nil
+}
+func (f *fakeRepo) AllPermissionCodes(context.Context) ([]string, error) { return f.allPermissionCodes, nil }
+func (f *fakeRepo) CountRolesWithPermission(context.Context, string, string) (int64, error) {
+	return f.countWithPermission, nil
+}
+
+func status(t *testing.T, err error) int {
+	t.Helper()
+	var appErr *apperror.AppError
+	if !errors.As(err, &appErr) {
+		t.Fatalf("expected *apperror.AppError, got %T: %v", err, err)
+	}
+	return appErr.HTTPStatus
+}
+
+func TestService_SetPermissions_LastRoleManagerLockout(t *testing.T) {
+	repo := &fakeRepo{
+		role:                &model.Role{Code: "ops", Name: "Ops"},
+		allPermissionCodes:  []string{PermRoleManage, "user:read"},
+		countWithPermission: 0, // no OTHER role grants PermRoleManage
+	}
+	svc := NewService(repo)
+	// dropping PermRoleManage from the only role that has it would lock every admin out
+	_, err := svc.SetPermissions(context.Background(), "ops", []string{"user:read"})
+	if got := status(t, err); got != http.StatusConflict {
+		t.Fatalf("want 409 last-role-manager lockout, got %d", got)
+	}
+}
+
+func TestService_SetPermissions_AllowedWhenAnotherRoleStillManages(t *testing.T) {
+	repo := &fakeRepo{
+		role:                &model.Role{Code: "ops", Name: "Ops"},
+		allPermissionCodes:  []string{PermRoleManage, "user:read"},
+		countWithPermission: 1, // another role still grants PermRoleManage
+	}
+	svc := NewService(repo)
+	if _, err := svc.SetPermissions(context.Background(), "ops", []string{"user:read"}); err != nil {
+		t.Fatalf("expected success when another role still manages roles, got %v", err)
+	}
+}
+
+func TestService_SetPermissions_KeepingRoleManageNeverLocksOut(t *testing.T) {
+	repo := &fakeRepo{
+		role:                &model.Role{Code: "ops", Name: "Ops"},
+		allPermissionCodes:  []string{PermRoleManage},
+		countWithPermission: 0,
+	}
+	svc := NewService(repo)
+	// the guard only fires when PermRoleManage is being dropped — keeping it never trips it
+	if _, err := svc.SetPermissions(context.Background(), "ops", []string{PermRoleManage}); err != nil {
+		t.Fatalf("keeping %s in the new set should never trigger the lockout guard, got %v", PermRoleManage, err)
+	}
+}
+
+func TestService_Delete_LastRoleManagerLockout(t *testing.T) {
+	repo := &fakeRepo{role: &model.Role{Code: "ops"}, countWithPermission: 0}
+	svc := NewService(repo)
+	err := svc.Delete(context.Background(), "ops")
+	if got := status(t, err); got != http.StatusConflict {
+		t.Fatalf("want 409 last-role-manager lockout on delete, got %d", got)
+	}
+}
+
+func TestService_Delete_AllowedWhenAnotherRoleStillManages(t *testing.T) {
+	repo := &fakeRepo{role: &model.Role{Code: "ops"}, countWithPermission: 1}
+	svc := NewService(repo)
+	if err := svc.Delete(context.Background(), "ops"); err != nil {
+		t.Fatalf("expected delete to succeed when another role still manages roles, got %v", err)
+	}
+}
+
+func TestService_Delete_SystemRoleRejected(t *testing.T) {
+	repo := &fakeRepo{role: &model.Role{Code: "admin", IsSystem: true}}
+	svc := NewService(repo)
+	err := svc.Delete(context.Background(), "admin")
+	if got := status(t, err); got != http.StatusConflict {
+		t.Fatalf("want 409 for a system role, got %d", got)
+	}
+}

package/templates/add/rbac/internal/shared/middleware/authz.go.hbs

@@ -0,0 +1,88 @@
+package middleware
+
+import (
+	"context"
+	"net/http"
+	"sync"
+	"time"
+
+	"{{goModule}}/internal/shared/apperror"
+
+	"github.com/gin-gonic/gin"
+)
+
+// Authz answers "does this role have this permission?". shared/ can't import
+// a domain package (see RequireAuth's comment), so the role->permission
+// lookup is injected as a func value from main.go instead of calling the
+// role domain directly.
+type Authz struct {
+	resolve func(ctx context.Context, roleCode string) (map[string]struct{}, error)
+	ttl     time.Duration
+
+	mu    sync.RWMutex
+	cache map[string]cachedPerms
+}
+
+type cachedPerms struct {
+	perms   map[string]struct{}
+	expires time.Time
+}
+
+// NewAuthz builds an Authz that calls resolve on a cache miss. The cache key
+// is the role code, not the user or the request — a handful of roles means
+// a handful of DB round trips per TTL window, independent of traffic.
+func NewAuthz(resolve func(context.Context, string) (map[string]struct{}, error), ttl time.Duration) *Authz {
+	return &Authz{resolve: resolve, ttl: ttl, cache: map[string]cachedPerms{}}
+}
+
+// Require 403s unless the caller's role (set by RequireAuth) grants perm.
+// Must run after RequireAuth.
+func (a *Authz) Require(perm string) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		perms, err := a.permsOf(c.Request.Context(), c.GetString(RoleKey))
+		if err != nil {
+			c.Error(err)
+			c.Abort()
+			return
+		}
+		if _, ok := perms[perm]; !ok {
+			c.Error(apperror.New(http.StatusForbidden, "FORBIDDEN", "insufficient permissions"))
+			c.Abort()
+			return
+		}
+		c.Next()
+	}
+}
+
+// ponytail: process-local cache, a handful of roles x AUTHZ_CACHE_TTL_MIN —
+// a role's permission grants take effect within the TTL, no pub/sub needed.
+// Move to Redis only if instant cross-pod invalidation turns out to matter.
+//
+// Double-checked locking: the common case (cache hit) only needs RLock, so
+// concurrent requests for different roles never block each other. Only a
+// miss takes the exclusive Lock, and only for the one role being resolved —
+// ceiling is that a miss still blocks other roles' misses (not their hits)
+// for the duration of one resolve() call; move to a per-role singleflight
+// if that contention ever actually shows up under load.
+func (a *Authz) permsOf(ctx context.Context, role string) (map[string]struct{}, error) {
+	a.mu.RLock()
+	e, ok := a.cache[role]
+	a.mu.RUnlock()
+	if ok && time.Now().Before(e.expires) {
+		return e.perms, nil
+	}
+
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	// re-check: another goroutine may have refreshed this role while we
+	// were waiting for the write lock.
+	if e, ok := a.cache[role]; ok && time.Now().Before(e.expires) {
+		return e.perms, nil
+	}
+	perms, err := a.resolve(ctx, role)
+	if err != nil {
+		return nil, err
+	}
+	a.cache[role] = cachedPerms{perms: perms, expires: time.Now().Add(a.ttl)}
+	return perms, nil
+}

package/templates/add/rbac/internal/shared/middleware/authz_test.go.hbs

@@ -0,0 +1,88 @@
+package middleware
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestAuthz_CachesWithinTTL(t *testing.T) {
+	var calls int32
+	a := NewAuthz(func(context.Context, string) (map[string]struct{}, error) {
+		atomic.AddInt32(&calls, 1)
+		return map[string]struct{}{"x": {}}, nil
+	}, time.Minute)
+
+	if _, err := a.permsOf(context.Background(), "staff"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if _, err := a.permsOf(context.Background(), "staff"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := atomic.LoadInt32(&calls); got != 1 {
+		t.Fatalf("want resolve called once for two calls within TTL (cache hit), got %d", got)
+	}
+}
+
+func TestAuthz_ReResolvesAfterTTLExpires(t *testing.T) {
+	var calls int32
+	a := NewAuthz(func(context.Context, string) (map[string]struct{}, error) {
+		atomic.AddInt32(&calls, 1)
+		return map[string]struct{}{"x": {}}, nil
+	}, 10*time.Millisecond)
+
+	if _, err := a.permsOf(context.Background(), "staff"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	time.Sleep(20 * time.Millisecond)
+	if _, err := a.permsOf(context.Background(), "staff"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := atomic.LoadInt32(&calls); got != 2 {
+		t.Fatalf("want resolve called again once the TTL expires, got %d calls", got)
+	}
+}
+
+func TestAuthz_Require_ForbidsMissingPermission(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	a := NewAuthz(func(context.Context, string) (map[string]struct{}, error) {
+		return map[string]struct{}{"other:perm": {}}, nil
+	}, time.Minute)
+
+	r := gin.New()
+	// Require only records a *apperror.AppError via c.Error — Error(true) is
+	// what actually translates that into the response status code, same as
+	// the real router (see cmd/api/main.go).
+	r.Use(Error(true))
+	r.GET("/x", func(c *gin.Context) { c.Set(RoleKey, "staff") }, a.Require("role:manage"), func(c *gin.Context) {
+		c.Status(http.StatusOK)
+	})
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/x", nil))
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("want 403 without the required permission, got %d", w.Code)
+	}
+}
+
+func TestAuthz_Require_AllowsGrantedPermission(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	a := NewAuthz(func(context.Context, string) (map[string]struct{}, error) {
+		return map[string]struct{}{"role:manage": {}}, nil
+	}, time.Minute)
+
+	r := gin.New()
+	r.Use(Error(true))
+	r.GET("/x", func(c *gin.Context) { c.Set(RoleKey, "admin") }, a.Require("role:manage"), func(c *gin.Context) {
+		c.Status(http.StatusOK)
+	})
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/x", nil))
+	if w.Code != http.StatusOK {
+		t.Fatalf("want 200 with the required permission granted, got %d", w.Code)
+	}
+}

package/templates/add/rbac/migrations/add_roles.down.sql.hbs

@@ -0,0 +1,15 @@
+-- if an admin created a custom role after this migration and it's still
+-- assigned to any user, dropping the roles table would orphan that value —
+-- raise a clear, actionable error instead of a raw FK-violation.
+DO $$
+BEGIN
+    IF EXISTS (SELECT 1 FROM users WHERE role NOT IN ('staff', 'admin')) THEN
+        RAISE EXCEPTION 'cannot roll back add_roles: users still have a role other than staff/admin — reassign them to staff/admin first';
+    END IF;
+END $$;
+
+ALTER TABLE users DROP COLUMN role;
+
+DROP TABLE role_permissions;
+DROP TABLE permissions;
+DROP TABLE roles;

package/templates/add/rbac/migrations/add_roles.up.sql.hbs

@@ -0,0 +1,35 @@
+CREATE TABLE roles (
+    code       VARCHAR(20) PRIMARY KEY,
+    name       TEXT NOT NULL,
+    is_system  BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE permissions (
+    code        VARCHAR(50) PRIMARY KEY,
+    description TEXT NOT NULL
+);
+
+CREATE TABLE role_permissions (
+    role_code       VARCHAR(20) NOT NULL REFERENCES roles(code) ON DELETE CASCADE,
+    permission_code VARCHAR(50) NOT NULL REFERENCES permissions(code) ON DELETE CASCADE,
+    PRIMARY KEY (role_code, permission_code)
+);
+
+INSERT INTO roles (code, name, is_system) VALUES
+    ('staff', 'Staff', TRUE),
+    ('admin', 'Admin', TRUE);
+
+INSERT INTO permissions (code, description) VALUES
+    ('role:manage',       'Create roles and change their permissions'),
+    ('user:manage-role',  'Change a user''s assigned role'),
+    ('user:read',         'List and view other users');
+
+-- admin gets every permission that exists, staff gets none — no behavior
+-- change for existing users until an admin explicitly grants something.
+INSERT INTO role_permissions (role_code, permission_code)
+SELECT 'admin', code FROM permissions;
+
+ALTER TABLE users
+    ADD COLUMN role VARCHAR(20) NOT NULL DEFAULT 'staff' REFERENCES roles(code);

package/templates/add/worker/cmd/worker/main.go.hbs

@@ -0,0 +1,77 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"{{goModule}}/internal/platform/mail"
+	"{{goModule}}/internal/platform/queue"
+	"{{goModule}}/internal/shared/config"
+	// go-scaffold:imports
+)
+
+func main() {
+	cfg := config.Load()
+
+	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: parseLevel(cfg.LogLevel)}))
+	slog.SetDefault(logger)
+
+	srv, err := queue.NewServer(cfg.RedisURL)
+	if err != nil {
+		logger.Error("new queue server", "error", err)
+		os.Exit(1)
+	}
+
+	srv.Handle(mail.TypeSendEmail, mail.HandleSendEmail(mail.Open(cfg)))
+	// go-scaffold:queue-handlers
+
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+
+	go func() {
+		logger.Info("worker started")
+		if err := srv.Start(); err != nil && !errors.Is(err, context.Canceled) {
+			logger.Error("worker server", "error", err)
+			os.Exit(1)
+		}
+	}()
+
+	<-ctx.Done()
+	logger.Info("shutting down worker")
+
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	// asynq's Shutdown() blocks until in-flight tasks finish (or the process
+	// is killed) with no context/timeout parameter of its own — run it in a
+	// goroutine and race it against shutdownCtx so a stuck task can't hang
+	// the process forever.
+	done := make(chan struct{}, 1)
+	go func() {
+		srv.Shutdown()
+		close(done)
+	}()
+	select {
+	case <-done:
+	case <-shutdownCtx.Done():
+		logger.Warn("worker shutdown timed out")
+	}
+	logger.Info("worker stopped")
+}
+
+func parseLevel(s string) slog.Level {
+	switch s {
+	case "debug":
+		return slog.LevelDebug
+	case "warn":
+		return slog.LevelWarn
+	case "error":
+		return slog.LevelError
+	default:
+		return slog.LevelInfo
+	}
+}

package/templates/add/worker/internal/platform/cache/redis.go.hbs

@@ -0,0 +1,18 @@
+package cache
+
+import (
+	"{{goModule}}/internal/shared/config"
+
+	"github.com/redis/go-redis/v9"
+)
+
+// Open connects to Redis — it talks to a real external system, so it lives
+// in platform/, not shared/. Used for ephemeral, TTL-bound data and as the
+// backing store for the async task queue (platform/queue).
+func Open(cfg config.Config) (*redis.Client, error) {
+	opts, err := redis.ParseURL(cfg.RedisURL)
+	if err != nil {
+		return nil, err
+	}
+	return redis.NewClient(opts), nil
+}

package/templates/add/worker/internal/platform/mail/mail.go.hbs

@@ -0,0 +1,48 @@
+package mail
+
+import (
+	"fmt"
+	"log/slog"
+	"net/smtp"
+
+	"{{goModule}}/internal/shared/config"
+)
+
+// Client sends plain-text email over SMTP (net/smtp already handles STARTTLS
+// when the server offers it, which covers Gmail/SendGrid/Mailgun/SES/Resend
+// SMTP relays on port 587) — talks to a real external system, so it lives in
+// platform/, not shared/.
+type Client struct {
+	host, port, username, password, from string
+}
+
+func Open(cfg config.Config) *Client {
+	return &Client{
+		host:     cfg.SMTPHost,
+		port:     cfg.SMTPPort,
+		username: cfg.SMTPUsername,
+		password: cfg.SMTPPassword,
+		from:     cfg.SMTPFrom,
+	}
+}
+
+// Send delivers a plain-text email. If SMTP isn't configured (dev default —
+// SMTP_HOST unset), it logs the message instead of failing, so flows that
+// send email stay testable without a real mail server.
+func (c *Client) Send(to, subject, body string) error {
+	if c.host == "" {
+		// ponytail: no SMTP configured — log instead of failing. Upgrade path:
+		// set SMTP_HOST (+ USERNAME/PASSWORD/FROM) once a real environment needs it.
+		slog.Info("email not sent (SMTP not configured)", "to", to, "subject", subject, "body", body)
+		return nil
+	}
+	msg := fmt.Sprintf("To: %s\r\nFrom: %s\r\nSubject: %s\r\n\r\n%s\r\n", to, c.from, subject, body)
+	// nil Auth when no username is set — a relay/local catcher that doesn't
+	// require auth (or doesn't advertise AUTH at all) rejects a non-nil Auth
+	// outright, even with empty credentials.
+	var auth smtp.Auth
+	if c.username != "" {
+		auth = smtp.PlainAuth("", c.username, c.password, c.host)
+	}
+	return smtp.SendMail(c.host+":"+c.port, auth, c.from, []string{to}, []byte(msg))
+}

package/templates/add/worker/internal/platform/mail/task.go.hbs

@@ -0,0 +1,52 @@
+package mail
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/hibiken/asynq"
+)
+
+const TypeSendEmail = "email:send"
+
+type sendEmailPayload struct {
+	To      string
+	Subject string
+	Body    string
+}
+
+func NewSendEmailTask(p sendEmailPayload) *asynq.Task {
+	payload, _ := json.Marshal(p)
+	return asynq.NewTask(TypeSendEmail, payload)
+}
+
+func HandleSendEmail(client *Client) asynq.Handler {
+	return asynq.HandlerFunc(func(ctx context.Context, task *asynq.Task) error {
+		var p sendEmailPayload
+		if err := json.Unmarshal(task.Payload(), &p); err != nil {
+			return err
+		}
+		return client.Send(p.To, p.Subject, p.Body)
+	})
+}
+
+type AsyncClient struct {
+	q interface {
+		Enqueue(task *asynq.Task, opts ...asynq.Option) (string, error)
+	}
+}
+
+func NewAsyncClient(q interface {
+	Enqueue(task *asynq.Task, opts ...asynq.Option) (string, error)
+}) *AsyncClient {
+	return &AsyncClient{q: q}
+}
+
+// Send enqueues the email instead of sending it inline, so the caller (an
+// HTTP handler) returns in ~µs instead of blocking on SMTP. cmd/worker picks
+// it up and calls Client.Send.
+func (c *AsyncClient) Send(to, subject, body string) error {
+	task := NewSendEmailTask(sendEmailPayload{To: to, Subject: subject, Body: body})
+	_, err := c.q.Enqueue(task, asynq.MaxRetry(5))
+	return err
+}

package/templates/add/worker/internal/platform/queue/client.go.hbs

@@ -0,0 +1,31 @@
+package queue
+
+import (
+	"github.com/hibiken/asynq"
+)
+
+// Client enqueues tasks to Redis. Created by cmd/api; each domain or platform
+// package defines its own task types and calls Client.Enqueue.
+type Client struct {
+	inner *asynq.Client
+}
+
+func NewClient(redisURL string) (*Client, error) {
+	opt, err := asynq.ParseRedisURI(redisURL)
+	if err != nil {
+		return nil, err
+	}
+	return &Client{inner: asynq.NewClient(opt)}, nil
+}
+
+func (c *Client) Enqueue(task *asynq.Task, opts ...asynq.Option) (string, error) {
+	info, err := c.inner.Enqueue(task, opts...)
+	if err != nil {
+		return "", err
+	}
+	return info.ID, nil
+}
+
+func (c *Client) Close() error {
+	return c.inner.Close()
+}

package/templates/add/worker/internal/platform/queue/server.go.hbs

@@ -0,0 +1,68 @@
+package queue
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+
+	"github.com/hibiken/asynq"
+)
+
+// Server runs the background worker. Created by cmd/worker; handlers register
+// their task types on the mux before Start is called.
+type Server struct {
+	inner *asynq.Server
+	mux   *asynq.ServeMux
+}
+
+// slogAdapter wraps *slog.Logger to implement asynq.Logger. Asynq calls these
+// like the stdlib `log` package (a plain message, sometimes several args
+// meant to be concatenated) — fmt.Sprint joins them into one message string
+// rather than passing them as slog key-value pairs, which would otherwise
+// misinterpret a lone message argument as a key with no value.
+type slogAdapter struct {
+	inner *slog.Logger
+}
+
+func (a *slogAdapter) Debug(args ...interface{}) { a.inner.Debug(fmt.Sprint(args...)) }
+func (a *slogAdapter) Info(args ...interface{})  { a.inner.Info(fmt.Sprint(args...)) }
+func (a *slogAdapter) Warn(args ...interface{})  { a.inner.Warn(fmt.Sprint(args...)) }
+func (a *slogAdapter) Error(args ...interface{}) { a.inner.Error(fmt.Sprint(args...)) }
+func (a *slogAdapter) Fatal(args ...interface{}) { a.inner.Error(fmt.Sprint(args...)) }
+
+func NewServer(redisURL string) (*Server, error) {
+	opt, err := asynq.ParseRedisURI(redisURL)
+	if err != nil {
+		return nil, err
+	}
+	srv := &Server{
+		inner: asynq.NewServer(opt, asynq.Config{
+			Concurrency: 10,
+			Logger:      &slogAdapter{inner: slog.Default()},
+		}),
+		mux: asynq.NewServeMux(),
+	}
+	// Global error handler for tasks that panic or return a non-Retryable error.
+	srv.mux.Use(func(next asynq.Handler) asynq.Handler {
+		return asynq.HandlerFunc(func(ctx context.Context, task *asynq.Task) error {
+			err := next.ProcessTask(ctx, task)
+			if err != nil {
+				slog.Error("task failed", "type", task.Type(), "error", err)
+			}
+			return err
+		})
+	})
+	return srv, nil
+}
+
+func (s *Server) Handle(pattern string, handler asynq.Handler) {
+	s.mux.Handle(pattern, handler)
+}
+
+func (s *Server) Start() error {
+	return s.inner.Start(s.mux)
+}
+
+func (s *Server) Shutdown() {
+	s.inner.Shutdown()
+}

package/templates/create/base/.env.example.hbs

@@ -1,3 +1,8 @@
+# development | production — the one gate for prod behavior (config.IsProd):
+# hides error `details` from responses. Any other value makes the app refuse
+# to boot (so a typo can't silently downgrade prod).
+APP_ENV=development                 # prod: production
+
 PORT=8080
 DB_DSN=postgres://postgres:postgres@localhost:5432/{{dbName}}?sslmode=disable
 LOG_LEVEL=info
@@ -5,3 +10,18 @@ AUTO_MIGRATE=true
 DB_MAX_OPEN_CONNS=10
 DB_MAX_IDLE_CONNS=10
 DB_CONN_MAX_LIFETIME_MIN=5
+
+# read only by `go test`, never by cmd/api — a separate database on purpose: the
+# integration-test harness does DropTable+AutoMigrate on every run, which would
+# otherwise wipe the schema `make migrate-up` built in DB_DSN above.
+# Create it once: make db-create DB_NAME={{dbName}}_test
+TEST_DB_DSN=postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=disable
+
+# comma-separated frontend origins allowed to call this API with credentials (cookies)
+CORS_ALLOWED_ORIGINS=http://localhost:3000
+{{#if observability}}
+
+# OTLP/HTTP endpoint for trace export (e.g. localhost:4318) — empty disables
+# tracing entirely: no exporter is created, no network calls are made
+OTEL_EXPORTER_OTLP_ENDPOINT=
+{{/if}}