@johnnyboy11234/esg-idea-contest 0.2.4 → 0.3.1

package/backend/internal/idea/service.go

@@ -0,0 +1,53 @@
+// Package idea owns the idea table and is the only way to read an Idea
+// (Backend.md 8): every read goes through the visibility query.
+package idea
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+
+	"github.com/google/uuid"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/audit"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/deadline"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/idea/internal/store"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/security"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+// Idea is the module's read model of one Idea.
+type Idea = store.Idea
+
+// Service reads and creates Ideas.
+type Service struct {
+	DB    *sql.DB
+	Audit *audit.Service
+	// Gate, Slides, Objects and Aborter are needed by Create only.
+	Gate    deadline.SubmissionGate
+	Slides  SlideRules
+	Objects ObjectStore
+	Aborter UploadAborter
+}
+
+// Get returns the Idea if the caller may see it. A missing Idea and a hidden
+// one both return the same NOT_FOUND error; the handler audits it as DENIED.
+func (s *Service) Get(ctx context.Context, id uuid.UUID, caller security.Principal) (Idea, error) {
+	got, err := store.GetVisible(ctx, s.DB, id, caller.UserID, caller.IsAdmin())
+	if errors.Is(err, store.ErrNotFound) {
+		return Idea{}, web.NewError(web.CodeNotFound, "")
+	}
+	return got, err
+}
+
+// Summary is the module's read model of one list row.
+type Summary = store.Summary
+
+// ListFilter is the validated filter set of the list.
+type ListFilter = store.ListFilter
+
+// List returns one page of the Ideas the caller may see and the total match
+// count. limit and offset are already validated by the handler.
+func (s *Service) List(ctx context.Context, caller security.Principal, f ListFilter, limit, offset int) ([]Summary, int, error) {
+	return store.ListVisible(ctx, s.DB, caller.UserID, caller.IsAdmin(), f, limit, offset)
+}

package/backend/internal/server/api.go

@@ -7,6 +7,7 @@ import (
 	"github.com/brian-huanggg/AwardRegistration/backend/internal/api"
 	"github.com/brian-huanggg/AwardRegistration/backend/internal/auth"
 	"github.com/brian-huanggg/AwardRegistration/backend/internal/deadline"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/idea"
 )
 
 // API composes the module handlers into api.ServerInterface. Operations whose
@@ -19,6 +20,7 @@ type API struct {
 	Me       auth.MeHandler
 	Account  account.Handler
 	Deadline deadline.Handler
+	Ideas    idea.Handler
 }
 
 // GetDeadline serves GET /deadline.
@@ -42,3 +44,18 @@ func (a API) Logout(w http.ResponseWriter, r *http.Request, _ api.LogoutParams)
 
 // GetMe serves GET /auth/me.
 func (a API) GetMe(w http.ResponseWriter, r *http.Request) { a.Me.GetMe(w, r) }
+
+// GetIdea serves GET /ideas/{id}.
+func (a API) GetIdea(w http.ResponseWriter, r *http.Request, id api.IdeaId) {
+	a.Ideas.GetIdea(w, r, id)
+}
+
+// CreateIdea serves POST /ideas.
+func (a API) CreateIdea(w http.ResponseWriter, r *http.Request, _ api.CreateIdeaParams) {
+	a.Ideas.CreateIdea(w, r)
+}
+
+// ListIdeas serves GET /ideas.
+func (a API) ListIdeas(w http.ResponseWriter, r *http.Request, params api.ListIdeasParams) {
+	a.Ideas.ListIdeas(w, r, params)
+}

package/backend/internal/server/public.go

@@ -31,6 +31,7 @@ var WriteActions = map[string]string{
 	http.MethodPost + " /api/v1/auth/login":    "AUTH_LOGIN",
 	http.MethodPost + " /api/v1/auth/register": "AUTH_REGISTER",
 	http.MethodPost + " /api/v1/auth/logout":   "AUTH_LOGOUT",
+	http.MethodPost + " /api/v1/ideas":         "IDEA_CREATE",
 }
 
 // ActionFor returns the audit action of r, or "" when unknown.

package/backend/internal/server/slides.go

@@ -0,0 +1,21 @@
+package server
+
+import (
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/idea"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/storage"
+)
+
+// IdeaSlideRules adapts the storage slide rules to idea.SlideRules. It lives
+// here because idea must not import storage (D29) and storage must not know
+// idea's types.
+func IdeaSlideRules() idea.SlideRules {
+	return idea.SlideRules{
+		ExpectedBase: storage.ExpectedFilenameBase,
+		CheckLength:  storage.CheckFilenameLength,
+		Validate: func(f idea.SlideFile, expectedBase string) (string, error) {
+			// ReadMultipart guarantees exactly one part (step 1, 400).
+			kind, err := storage.Validate([]storage.Part{{Filename: f.Filename, Size: f.Size, Data: f.Data}}, expectedBase)
+			return string(kind), err
+		},
+	}
+}

package/backend/internal/shared/config/config.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"log/slog"
 	"os"
+	"strconv"
 	"strings"
 	"time"
 )
@@ -20,13 +21,32 @@ type Config struct {
 	ReadyDrainDelay time.Duration // time readiness stays false before Shutdown starts
 	CSRFKey         string        // HMAC key that signs CSRF tokens (>= 32 bytes)
 	CSRFKeyPrevious string        // optional: still verifies for 8 h after a rotation
+	ProxyHops       int           // X-Forwarded-For proxies to trust for the client IP; 0 = TCP peer (PRD §6.5)
+	MinIO           MinIO
 }
 
+// MinIO configures the slide store. The bucket must exist; the application
+// never creates it.
+type MinIO struct {
+	Endpoint  string // host:port
+	AccessKey string
+	SecretKey string
+	Bucket    string
+	Secure    bool // TLS to MinIO
+}
+
+// DefaultMinIOKey is the access and secret key of docker-compose.yml, used by
+// the local profile only; every other profile must set both keys.
+const DefaultMinIOKey = "minioadmin"
+
 // DefaultCSRFKey is the throwaway key of the local profile only; every other
 // profile must set ESG_CSRF_KEY.
 const DefaultCSRFKey = "local-dev-csrf-key-not-a-secret-0000"
 
-const minCSRFKeyBytes = 32
+const (
+	minCSRFKeyBytes = 32
+	maxProxyHops    = 10
+)
 
 // DefaultDSN matches docker-compose.yml (throwaway local credentials). The query
 // pins UTC and matched-row counts (Backend.md §2.3).
@@ -47,6 +67,12 @@ func Load(getenv func(string) string) (Config, error) {
 		DBDSN:           get("ESG_DB_DSN", DefaultDSN),
 		CSRFKey:         getenv("ESG_CSRF_KEY"),
 		CSRFKeyPrevious: getenv("ESG_CSRF_KEY_PREVIOUS"),
+		MinIO: MinIO{
+			Endpoint:  get("ESG_MINIO_ENDPOINT", "localhost:9000"),
+			AccessKey: getenv("ESG_MINIO_ACCESS_KEY"),
+			SecretKey: getenv("ESG_MINIO_SECRET_KEY"),
+			Bucket:    get("ESG_MINIO_BUCKET", "esg-slides"),
+		},
 	}
 	switch c.Profile {
 	case "local", "k3s", "dev":
@@ -56,6 +82,17 @@ func Load(getenv func(string) string) (Config, error) {
 	if c.CSRFKey == "" && c.Profile == "local" {
 		c.CSRFKey = DefaultCSRFKey
 	}
+	if c.Profile == "local" {
+		if c.MinIO.AccessKey == "" {
+			c.MinIO.AccessKey = DefaultMinIOKey
+		}
+		if c.MinIO.SecretKey == "" {
+			c.MinIO.SecretKey = DefaultMinIOKey
+		}
+	}
+	if c.MinIO.AccessKey == "" || c.MinIO.SecretKey == "" {
+		return Config{}, fmt.Errorf("ESG_MINIO_ACCESS_KEY and ESG_MINIO_SECRET_KEY are required outside the local profile")
+	}
 	if len(c.CSRFKey) < minCSRFKeyBytes {
 		return Config{}, fmt.Errorf("ESG_CSRF_KEY: need at least %d bytes", minCSRFKeyBytes)
 	}
@@ -66,6 +103,12 @@ func Load(getenv func(string) string) (Config, error) {
 		return Config{}, fmt.Errorf("ESG_LOG_LEVEL: %w", err)
 	}
 	var err error
+	if c.ProxyHops, err = strconv.Atoi(get("ESG_TRUSTED_PROXY_HOPS", "1")); err != nil || c.ProxyHops < 0 || c.ProxyHops > maxProxyHops {
+		return Config{}, fmt.Errorf("ESG_TRUSTED_PROXY_HOPS: want an integer 0..%d", maxProxyHops)
+	}
+	if c.MinIO.Secure, err = strconv.ParseBool(get("ESG_MINIO_SECURE", "false")); err != nil {
+		return Config{}, fmt.Errorf("ESG_MINIO_SECURE: %w", err)
+	}
 	if c.ShutdownTimeout, err = time.ParseDuration(get("ESG_SHUTDOWN_TIMEOUT", "20s")); err != nil {
 		return Config{}, fmt.Errorf("ESG_SHUTDOWN_TIMEOUT: %w", err)
 	}

package/backend/internal/shared/config/config_test.go

@@ -18,32 +18,40 @@ func TestDefaults(t *testing.T) {
 		t.Fatal(err)
 	}
 	if c.Profile != "local" || c.PublicAddr != ":8080" || c.ManagementAddr != ":8081" ||
-		c.LogLevel != slog.LevelInfo || c.ShutdownTimeout != 20*time.Second || c.CSRFKey != config.DefaultCSRFKey {
+		c.LogLevel != slog.LevelInfo || c.ShutdownTimeout != 20*time.Second || c.CSRFKey != config.DefaultCSRFKey || c.ProxyHops != 1 ||
+		c.MinIO != (config.MinIO{Endpoint: "localhost:9000", AccessKey: "minioadmin", SecretKey: "minioadmin", Bucket: "esg-slides"}) {
 		t.Fatalf("%+v", c)
 	}
 }
 
 func TestOverrides(t *testing.T) {
 	c, err := config.Load(env(map[string]string{
-		"ESG_PROFILE": "dev", "ESG_CSRF_KEY": key, "ESG_CSRF_KEY_PREVIOUS": key + "2", "ESG_LOG_LEVEL": "debug", "ESG_SHUTDOWN_TIMEOUT": "5s", "ESG_READY_DRAIN_DELAY": "1s",
+		"ESG_PROFILE": "dev", "ESG_CSRF_KEY": key, "ESG_CSRF_KEY_PREVIOUS": key + "2", "ESG_LOG_LEVEL": "debug", "ESG_SHUTDOWN_TIMEOUT": "5s", "ESG_READY_DRAIN_DELAY": "1s", "ESG_TRUSTED_PROXY_HOPS": "2",
+		"ESG_MINIO_ENDPOINT": "minio:9000", "ESG_MINIO_ACCESS_KEY": "a", "ESG_MINIO_SECRET_KEY": "s", "ESG_MINIO_BUCKET": "b", "ESG_MINIO_SECURE": "true",
 	}))
-	if err != nil || c.Profile != "dev" || c.LogLevel != slog.LevelDebug || c.ReadyDrainDelay != time.Second {
+	if err != nil || c.Profile != "dev" || c.LogLevel != slog.LevelDebug || c.ReadyDrainDelay != time.Second || c.ProxyHops != 2 ||
+		c.MinIO != (config.MinIO{Endpoint: "minio:9000", AccessKey: "a", SecretKey: "s", Bucket: "b", Secure: true}) {
 		t.Fatalf("%+v %v", c, err)
 	}
 }
 
 func TestInvalid(t *testing.T) {
 	for name, m := range map[string]map[string]string{
-		"profile":            {"ESG_PROFILE": "prod"},
-		"log level":          {"ESG_LOG_LEVEL": "loud"},
-		"timeout":            {"ESG_SHUTDOWN_TIMEOUT": "soon"},
-		"zero timeout":       {"ESG_SHUTDOWN_TIMEOUT": "0s"},
-		"drain":              {"ESG_READY_DRAIN_DELAY": "x"},
-		"short csrf key":     {"ESG_CSRF_KEY": "short"},
-		"short previous key": {"ESG_CSRF_KEY": key, "ESG_CSRF_KEY_PREVIOUS": "short"},
-		"dev needs csrf key": {"ESG_PROFILE": "dev"},
-		"k3s needs csrf key": {"ESG_PROFILE": "k3s"},
-		"same address":       {"ESG_PUBLIC_ADDR": ":9", "ESG_MANAGEMENT_ADDR": ":9"},
+		"profile":              {"ESG_PROFILE": "prod"},
+		"log level":            {"ESG_LOG_LEVEL": "loud"},
+		"timeout":              {"ESG_SHUTDOWN_TIMEOUT": "soon"},
+		"zero timeout":         {"ESG_SHUTDOWN_TIMEOUT": "0s"},
+		"drain":                {"ESG_READY_DRAIN_DELAY": "x"},
+		"short csrf key":       {"ESG_CSRF_KEY": "short"},
+		"short previous key":   {"ESG_CSRF_KEY": key, "ESG_CSRF_KEY_PREVIOUS": "short"},
+		"dev needs csrf key":   {"ESG_PROFILE": "dev"},
+		"k3s needs csrf key":   {"ESG_PROFILE": "k3s"},
+		"hops text":            {"ESG_TRUSTED_PROXY_HOPS": "one"},
+		"negative hops":        {"ESG_TRUSTED_PROXY_HOPS": "-1"},
+		"too many hops":        {"ESG_TRUSTED_PROXY_HOPS": "11"},
+		"same address":         {"ESG_PUBLIC_ADDR": ":9", "ESG_MANAGEMENT_ADDR": ":9"},
+		"dev needs minio keys": {"ESG_PROFILE": "dev", "ESG_CSRF_KEY": key},
+		"minio secure":         {"ESG_MINIO_SECURE": "maybe"},
 	} {
 		if _, err := config.Load(env(m)); err == nil {
 			t.Errorf("%s: want error", name)

package/backend/internal/shared/db/intx_integration_test.go

@@ -0,0 +1,179 @@
+//go:build integration
+
+package db_test
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"net"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/testcontainers/testcontainers-go"
+	"github.com/testcontainers/testcontainers-go/modules/toxiproxy"
+	"github.com/testcontainers/testcontainers-go/network"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/db"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/dbtest"
+)
+
+const toxiproxyImage = "ghcr.io/shopify/toxiproxy:2.12.0"
+
+// insertLock writes one login_lock row (PK lock_key): a table with a primary
+// key, so a second writer blocks while the first transaction is still open.
+func insertLock(ctx context.Context, tx *sql.Tx, key string) error {
+	_, err := tx.ExecContext(ctx,
+		`INSERT INTO login_lock (lock_key, fail_count, last_fail_at) VALUES (?, 1, NOW(6))`, key)
+	return err
+}
+
+func lockRows(t *testing.T, d *sql.DB, key string) int {
+	t.Helper()
+	var n int
+	if err := d.QueryRow(`SELECT COUNT(*) FROM login_lock WHERE lock_key = ?`, key).Scan(&n); err != nil {
+		t.Fatal(err)
+	}
+	return n
+}
+
+// Backend.md §4.4 / §11: the classification against a real server, through the
+// connector that commits-then-fails or fails-without-committing.
+func TestInTxLostCommitAgainstMariaDB(t *testing.T) {
+	dsn := dbtest.Start(t)
+	direct := dbtest.Open(t, dsn)
+	faulty, faults := dbtest.OpenFaulty(t, dsn)
+	ctx := context.Background()
+
+	for _, tc := range []struct {
+		name    string
+		fault   *dbtest.CommitFault
+		want    db.Outcome
+		applied bool
+	}{
+		{"no fault", nil, db.Committed, true},
+		{"commit applied, ack lost", &dbtest.LostAckCommitted, db.Unknown, true},
+		{"connection lost before commit", &dbtest.LostAckNotCommitted, db.Unknown, false},
+		{"deadlock at commit (SQLState 40)", &dbtest.DeadlockAtCommit, db.RolledBack, false},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			key := "lost-" + strings.ReplaceAll(tc.name, " ", "-")
+			if len(key) > 32 {
+				key = key[:32]
+			}
+			if tc.fault != nil {
+				faults.FailNextCommit(*tc.fault)
+			}
+			out, err := db.InTx(ctx, faulty, func(ctx context.Context, tx *sql.Tx) error {
+				return insertLock(ctx, tx, key)
+			})
+			if out != tc.want {
+				t.Errorf("outcome = %v, want %v (err %v)", out, tc.want, err)
+			}
+			if (err != nil) != (tc.fault != nil) {
+				t.Errorf("err = %v", err)
+			}
+			if got := lockRows(t, direct, key) == 1; got != tc.applied {
+				t.Errorf("row applied = %v, want %v", got, tc.applied)
+			}
+		})
+	}
+
+	t.Run("fn error rolls back on the real server", func(t *testing.T) {
+		out, err := db.InTx(ctx, faulty, func(ctx context.Context, tx *sql.Tx) error {
+			if err := insertLock(ctx, tx, "lost-fn-error"); err != nil {
+				return err
+			}
+			return errors.New("audit insert failed")
+		})
+		if out != db.RolledBack || err == nil || lockRows(t, direct, "lost-fn-error") != 0 {
+			t.Errorf("got %v, %v", out, err)
+		}
+	})
+}
+
+// One real-network sanity check (Sequence.md §7): Toxiproxy cuts the
+// connection between the last statement and COMMIT. The driver sees a dead
+// connection, InTx must say Unknown (never RolledBack: it cannot know), and the
+// server must have rolled the transaction back.
+func TestInTxConnectionCutBeforeCommit(t *testing.T) {
+	ctx := context.Background()
+	nw, err := network.New(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = nw.Remove(context.WithoutCancel(ctx)) })
+
+	direct := dbtest.Open(t, dbtest.Start(t, network.WithNetwork([]string{"mariadb"}, nw)))
+
+	tp, err := toxiproxy.Run(ctx, toxiproxyImage,
+		toxiproxy.WithProxy("mariadb", "mariadb:3306"),
+		network.WithNetwork([]string{"toxiproxy"}, nw))
+	testcontainers.CleanupContainer(t, tp)
+	if err != nil {
+		t.Fatalf("start toxiproxy: %v", err)
+	}
+	host, port, err := tp.ProxiedEndpoint(8666)
+	if err != nil {
+		t.Fatal(err)
+	}
+	api, err := tp.URI(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	proxied := dbtest.Open(t, dbtest.DSN(net.JoinHostPort(host, port)))
+	if err := proxied.PingContext(ctx); err != nil {
+		t.Fatalf("ping through toxiproxy: %v", err)
+	}
+
+	const key = "toxiproxy-cut"
+	out, err := db.InTx(ctx, proxied, func(ctx context.Context, tx *sql.Tx) error {
+		if err := insertLock(ctx, tx, key); err != nil {
+			return err
+		}
+		disableProxy(t, api) // the next bytes (COMMIT) go nowhere
+		return nil
+	})
+	if out != db.Unknown || err == nil {
+		t.Fatalf("InTx = %v, %v; want Unknown with an error", out, err)
+	}
+
+	// COMMIT never reached the server: once it notices the closed socket it
+	// rolls back and releases the row lock, so this insert stops blocking.
+	deadline := time.Now().Add(15 * time.Second)
+	for {
+		_, err := direct.ExecContext(ctx,
+			`SET STATEMENT innodb_lock_wait_timeout = 1 FOR
+			 INSERT INTO login_lock (lock_key, fail_count, last_fail_at) VALUES (?, 1, NOW(6))`, key)
+		if err == nil {
+			break
+		}
+		if !db.IsContention(err) || time.Now().After(deadline) {
+			t.Fatalf("server did not roll the cut transaction back: %v", err)
+		}
+	}
+}
+
+// disableProxy disables the proxy over the Toxiproxy HTTP API, which closes
+// every connection through it.
+func disableProxy(t *testing.T, api string) {
+	t.Helper()
+	body := `{"enabled":false}`
+	req, err := http.NewRequestWithContext(context.Background(), http.MethodPost,
+		api+"/proxies/mariadb", strings.NewReader(body))
+	if err != nil {
+		t.Fatal(err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("User-Agent", "toxiproxy-cli")
+	resp, err := (&http.Client{Timeout: 10 * time.Second}).Do(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("toxiproxy update: HTTP %d", resp.StatusCode)
+	}
+}

package/backend/internal/shared/dbtest/dbtest.go

@@ -13,6 +13,7 @@ import (
 	"testing"
 
 	_ "github.com/go-sql-driver/mysql"
+	"github.com/testcontainers/testcontainers-go"
 	"github.com/testcontainers/testcontainers-go/modules/mariadb"
 
 	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/config"
@@ -41,15 +42,26 @@ func MigrationFiles() ([]string, error) {
 // New starts MariaDB, applies every migration and returns a pool that uses
 // the production DSN. The container is terminated when the test ends.
 func New(t testing.TB) *sql.DB {
+	t.Helper()
+	return Open(t, Start(t))
+}
+
+// Start starts MariaDB with every migration applied and returns the production
+// DSN for it. opts customise the container (for example a Docker network, so a
+// Toxiproxy container can reach it). The container is terminated when the test
+// ends.
+func Start(t testing.TB, opts ...testcontainers.ContainerCustomizer) string {
 	t.Helper()
 	ctx := context.Background()
 	scripts, err := MigrationFiles()
 	if err != nil || len(scripts) == 0 {
 		t.Fatalf("no migrations found: %v", err)
 	}
-	ctr, err := mariadb.Run(ctx, Image,
+	opts = append([]testcontainers.ContainerCustomizer{
 		mariadb.WithDatabase("esg"), mariadb.WithUsername("esg"), mariadb.WithPassword("esg"),
-		mariadb.WithScripts(scripts...))
+		mariadb.WithScripts(scripts...),
+	}, opts...)
+	ctr, err := mariadb.Run(ctx, Image, opts...)
 	if err != nil {
 		t.Fatalf("start mariadb: %v", err)
 	}
@@ -63,7 +75,13 @@ func New(t testing.TB) *sql.DB {
 	if u == nil {
 		t.Fatalf("unexpected connection string %q", cs)
 	}
-	db, err := sql.Open("mysql", DSN(u[1]))
+	return DSN(u[1])
+}
+
+// Open opens a pool on dsn, closed when the test ends.
+func Open(t testing.TB, dsn string) *sql.DB {
+	t.Helper()
+	db, err := sql.Open("mysql", dsn)
 	if err != nil {
 		t.Fatal(err)
 	}

package/backend/internal/shared/dbtest/faults.go

@@ -0,0 +1,162 @@
+package dbtest
+
+import (
+	"context"
+	"database/sql"
+	"database/sql/driver"
+	"errors"
+	"fmt"
+	"sync"
+	"testing"
+
+	"github.com/go-sql-driver/mysql"
+)
+
+// CommitFault is what the next COMMIT on a FaultyDB does (Backend.md §11,
+// Sequence.md §7: lost-commit tests).
+type CommitFault struct {
+	// Apply commits the transaction on the server before Err is returned; when
+	// false the transaction is rolled back instead and nothing is applied.
+	Apply bool
+	// Err is what Commit returns to database/sql.
+	Err error
+}
+
+var (
+	// LostAckCommitted: the server committed, the acknowledgement was lost.
+	LostAckCommitted = CommitFault{Apply: true, Err: mysql.ErrInvalidConn}
+	// LostAckNotCommitted: the connection died before the COMMIT was applied.
+	LostAckNotCommitted = CommitFault{Apply: false, Err: mysql.ErrInvalidConn}
+	// DeadlockAtCommit: the server rejected the COMMIT with SQLState 40001.
+	DeadlockAtCommit = CommitFault{Apply: false, Err: &mysql.MySQLError{
+		Number: 1213, SQLState: [5]byte{'4', '0', '0', '0', '1'}, Message: "Deadlock found (injected)"}}
+)
+
+// Faults arms commit faults on a pool opened by OpenFaulty. A fault applies to
+// the next COMMIT on any connection of that pool, then disarms itself.
+type Faults struct {
+	mu    sync.Mutex
+	next  *CommitFault
+	fired int
+}
+
+// FailNextCommit arms f for the next COMMIT.
+func (f *Faults) FailNextCommit(cf CommitFault) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.next = &cf
+}
+
+// Fired reports how many armed faults have been triggered.
+func (f *Faults) Fired() int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return f.fired
+}
+
+func (f *Faults) take() *CommitFault {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	cf := f.next
+	if cf != nil {
+		f.next = nil
+		f.fired++
+	}
+	return cf
+}
+
+// OpenFaulty opens a pool on dsn whose driver.Connector wraps the MySQL one, so
+// a COMMIT can be made to "commit then fail" or "fail without committing". The
+// pool is closed when the test ends.
+func OpenFaulty(t testing.TB, dsn string) (*sql.DB, *Faults) {
+	t.Helper()
+	cfg, err := mysql.ParseDSN(dsn)
+	if err != nil {
+		t.Fatal(err)
+	}
+	inner, err := mysql.NewConnector(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	f := &Faults{}
+	db := sql.OpenDB(faultConnector{inner: inner, f: f})
+	t.Cleanup(func() { _ = db.Close() })
+	return db, f
+}
+
+type faultConnector struct {
+	inner driver.Connector
+	f     *Faults
+}
+
+func (c faultConnector) Driver() driver.Driver { return c.inner.Driver() }
+
+func (c faultConnector) Connect(ctx context.Context) (driver.Conn, error) {
+	conn, err := c.inner.Connect(ctx)
+	if err != nil {
+		return nil, err
+	}
+	fc, ok := conn.(fullConn)
+	if !ok {
+		_ = conn.Close()
+		return nil, fmt.Errorf("dbtest: %T lacks a driver interface the wrapper forwards", conn)
+	}
+	return faultConn{fullConn: fc, f: c.f}, nil
+}
+
+// fullConn is every optional interface the MySQL connection implements;
+// embedding it forwards them all, so database/sql takes the same code paths as
+// with the plain driver.
+type fullConn interface {
+	driver.Conn
+	driver.ConnBeginTx
+	driver.ConnPrepareContext
+	driver.ExecerContext
+	driver.QueryerContext
+	driver.Pinger
+	driver.SessionResetter
+	driver.Validator
+	driver.NamedValueChecker
+}
+
+type faultConn struct {
+	fullConn
+	f *Faults
+}
+
+func (c faultConn) Begin() (driver.Tx, error) {
+	return c.BeginTx(context.Background(), driver.TxOptions{})
+}
+
+func (c faultConn) BeginTx(ctx context.Context, opts driver.TxOptions) (driver.Tx, error) {
+	tx, err := c.fullConn.BeginTx(ctx, opts)
+	if err != nil {
+		return nil, err
+	}
+	return faultTx{inner: tx, f: c.f}, nil
+}
+
+type faultTx struct {
+	inner driver.Tx
+	f     *Faults
+}
+
+func (t faultTx) Rollback() error { return t.inner.Rollback() }
+
+func (t faultTx) Commit() error {
+	cf := t.f.take()
+	if cf == nil {
+		return t.inner.Commit()
+	}
+	if cf.Apply {
+		if err := t.inner.Commit(); err != nil {
+			return fmt.Errorf("dbtest: real commit failed before the injected fault: %w", err)
+		}
+		return cf.Err
+	}
+	// Roll back so the locks are released; the server never applies it.
+	if err := t.inner.Rollback(); err != nil {
+		return errors.Join(cf.Err, err)
+	}
+	return cf.Err
+}