Route GORM's logger through slog and bound it (closes #178)

internal/gormlog/export_test.go

@@ -0,0 +1,17 @@
+package gormlog
+
+import (
+	"log/slog"
+	"time"
+)
+
+// ExportNewWithSlowThreshold builds a Logger whose slow-statement
+// threshold is d rather than DefaultSlowThreshold, so a test can pin
+// which arm of Trace it is exercising instead of racing the clock on a
+// loaded machine. The threshold is set at construction, like every
+// other field, so the type's concurrency guarantee still holds.
+func ExportNewWithSlowThreshold(
+	log *slog.Logger, d time.Duration,
+) *Logger {
+	return &Logger{log: log, slowThreshold: d}
+}

internal/gormlog/gormlog.go

@@ -0,0 +1,168 @@
+// Package gormlog adapts GORM's logger onto the service's slog
+// logger.
+//
+// GORM's own default logger is not usable here. It is built at package
+// init with log.New(os.Stdout, ...) at LogLevel Warn with
+// IgnoreRecordNotFoundError false, so it writes the fully interpolated
+// SQL — parameters and all — for every statement that returns an
+// error, including gorm.ErrRecordNotFound. Two of this service's
+// lookups miss by design on unauthenticated routes: the entrypoint
+// lookup on /webhook/{uuid}, whose path segment the client picks
+// outright, and the user lookup behind the login form, whose username
+// the client picks outright. Under the default logger each of those
+// misses printed an unbounded, attacker-chosen string, at no level the
+// operator can turn down, past every handler internal/logger installs.
+//
+// This adapter fixes all three properties at once: the lines get a
+// level the operator controls, they are shaped by whichever handler
+// internal/logger selected, and every value a client can influence is
+// spent through logfield.Truncate.
+package gormlog
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"time"
+
+	gormlogger "gorm.io/gorm/logger"
+	"sneak.berlin/go/webhooker/internal/logfield"
+)
+
+// DefaultSlowThreshold is the duration at or above which a statement
+// is logged as slow. It is GORM's own default, kept deliberately: slow
+// SQL is the one thing GORM's logger reports that nothing else in this
+// service does, so silencing the logger outright would have cost real
+// observability to fix a log-volume defect.
+const DefaultSlowThreshold = 200 * time.Millisecond
+
+// Logger implements gormlogger.Interface on top of an *slog.Logger.
+//
+// It is safe for concurrent use: every field is set at construction
+// and never written again.
+type Logger struct {
+	log           *slog.Logger
+	slowThreshold time.Duration
+}
+
+// Interface compliance is asserted here rather than discovered at the
+// gorm.Open call sites.
+var _ gormlogger.Interface = (*Logger)(nil)
+
+// New returns a GORM logger that writes through log.
+func New(log *slog.Logger) *Logger {
+	return &Logger{
+		log:           log,
+		slowThreshold: DefaultSlowThreshold,
+	}
+}
+
+// LogMode returns the logger unchanged.
+//
+// GORM's LogLevel is deliberately not honoured. Level is the operator's
+// decision and it is expressed once, through LOG_LEVEL and the
+// slog.LevelVar internal/logger holds; a second level knob inside the
+// database layer could only disagree with it. The mapping from GORM's
+// four categories onto slog levels is fixed in Trace below.
+//
+//nolint:ireturn // The interface return is GORM's signature, not a choice.
+func (l *Logger) LogMode(gormlogger.LogLevel) gormlogger.Interface {
+	return l
+}
+
+// Info logs one of GORM's own informational messages.
+func (l *Logger) Info(
+	ctx context.Context, msg string, data ...any,
+) {
+	l.log.InfoContext(ctx, "gorm", "message", format(msg, data...))
+}
+
+// Warn logs one of GORM's own warnings.
+func (l *Logger) Warn(
+	ctx context.Context, msg string, data ...any,
+) {
+	l.log.WarnContext(ctx, "gorm", "message", format(msg, data...))
+}
+
+// Error logs one of GORM's own errors.
+func (l *Logger) Error(
+	ctx context.Context, msg string, data ...any,
+) {
+	l.log.ErrorContext(ctx, "gorm", "message", format(msg, data...))
+}
+
+// Trace reports the outcome of a single statement. GORM calls it for
+// every statement it runs, so the cheap paths stay cheap: fc()
+// renders the interpolated SQL and is called only on a branch that
+// will actually emit.
+//
+// The arms are ordered exactly as GORM's own Trace orders them —
+// non-record-not-found error, then slow, then the routine case — so
+// that a statement which both misses and runs slow is still reported
+// as slow. A miss is the likeliest statement to be slow, since it is
+// the one that scans without finding a row, and ordering the drop
+// ahead of the slow arm would have made this adapter less observant
+// than the IgnoreRecordNotFoundError option it was chosen over.
+func (l *Logger) Trace(
+	ctx context.Context,
+	begin time.Time,
+	fc func() (string, int64),
+	err error,
+) {
+	elapsed := time.Since(begin)
+
+	switch {
+	case err != nil && !errors.Is(err, gormlogger.ErrRecordNotFound):
+		sql, rows := fc()
+		l.log.ErrorContext(ctx, "sql statement failed",
+			"error", logfield.Truncate(err.Error(), logfield.MaxBytes),
+			"sql", logfield.Truncate(sql, logfield.MaxBytes),
+			"rows", rows,
+			"elapsed_ms", elapsed.Milliseconds(),
+		)
+
+	case l.slowThreshold > 0 && elapsed >= l.slowThreshold:
+		sql, rows := fc()
+		l.log.WarnContext(ctx, "slow sql statement",
+			"sql", logfield.Truncate(sql, logfield.MaxBytes),
+			"rows", rows,
+			"elapsed_ms", elapsed.Milliseconds(),
+			"threshold_ms", l.slowThreshold.Milliseconds(),
+		)
+
+	case err != nil:
+		// gorm.ErrRecordNotFound is not an error on the paths that
+		// produce it here: an invented entrypoint UUID and an unknown
+		// username are the expected outcome of an unauthenticated
+		// request, not a fault. This is the IgnoreRecordNotFoundError
+		// behaviour, and it is unconditional rather than configurable
+		// because no caller in this service wants the other one — the
+		// two handlers that care already record the miss themselves,
+		// at DEBUG, without the SQL. A miss that ran slow has already
+		// been reported by the arm above.
+		return
+
+	case l.log.Enabled(ctx, slog.LevelDebug):
+		sql, rows := fc()
+		l.log.DebugContext(ctx, "sql statement",
+			"sql", logfield.Truncate(sql, logfield.MaxBytes),
+			"rows", rows,
+			"elapsed_ms", elapsed.Milliseconds(),
+		)
+	}
+}
+
+// format renders one of GORM's printf-style internal messages and
+// bounds it. GORM builds these itself, but they can quote a value the
+// statement carried, so they are spent through the same budget as
+// everything else rather than trusted.
+func format(msg string, data ...any) string {
+	if len(data) == 0 {
+		return logfield.Truncate(msg, logfield.MaxBytes)
+	}
+
+	return logfield.Truncate(
+		fmt.Sprintf(msg, data...), logfield.MaxBytes,
+	)
+}

internal/gormlog/gormlog_test.go

@@ -0,0 +1,436 @@
+package gormlog_test
+
+import (
+	"bytes"
+	"context"
+	"database/sql"
+	"fmt"
+	"log/slog"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+	_ "modernc.org/sqlite" // Pure Go SQLite driver.
+	"sneak.berlin/go/webhooker/internal/gormlog"
+	"sneak.berlin/go/webhooker/internal/middleware"
+)
+
+// fillBytes is how much client-chosen text each case drives into the
+// statement. It is well past every budget in play, so a value that
+// arrives short arrived short because something cut it.
+const fillBytes = 8 << 10
+
+// tailMarker sits at the far end of every generated value. A line that
+// contains it carried the whole value, which means nothing cut it — so
+// a value that merely happened to be short cannot pass for a truncated
+// one.
+const tailMarker = "ENDOFCLIENTVALUE"
+
+// fills are the characters a client can drive into a SQL parameter,
+// chosen for what the log handlers charge for them rather than for
+// looking dangerous.
+//
+// The C0 control is the one that matters. Both handlers spell U+0001
+// as a six-byte escape for the single byte it costs a client to send,
+// which is the widest multiplier available in the basic multilingual
+// plane and the case a raw-byte budget breaks on first. The astral
+// non-printable costs ten under the text handler, four more than the
+// JSON handler ever spends.
+func fills() []struct {
+	name string
+	fill string
+} {
+	return []struct {
+		name string
+		fill string
+	}{
+		{"plain", "x"},
+		{"quote", `"`},
+		{"backslash", `\`},
+		{"tab", "\t"},
+		{"newline", "\n"},
+		{"c0_control", "\x01"},
+		{"astral_nonprintable", "\U0001000C"},
+	}
+}
+
+// clientValue builds a value of at least fillBytes raw bytes out of
+// fill, ending in tailMarker.
+func clientValue(fill string) string {
+	var b strings.Builder
+
+	for b.Len() < fillBytes {
+		b.WriteString(fill)
+	}
+
+	b.WriteString(tailMarker)
+
+	return b.String()
+}
+
+// handlers are the two slog handlers internal/logger can install. The
+// ceiling is quoted to operators unqualified, so every case is
+// asserted under both.
+func handlers() []struct {
+	name string
+	make func(*bytes.Buffer) slog.Handler
+} {
+	opts := &slog.HandlerOptions{Level: slog.LevelDebug}
+
+	return []struct {
+		name string
+		make func(*bytes.Buffer) slog.Handler
+	}{
+		{"json", func(b *bytes.Buffer) slog.Handler {
+			return slog.NewJSONHandler(b, opts)
+		}},
+		{"text", func(b *bytes.Buffer) slog.Handler {
+			return slog.NewTextHandler(b, opts)
+		}},
+	}
+}
+
+type thing struct {
+	ID   string `gorm:"primaryKey"`
+	Name string
+}
+
+// neverSlow is a slow-statement threshold no statement in this file
+// can reach. Cases that are about a non-slow arm of Trace set it, so
+// that a machine under load cannot turn a miss into a slow report and
+// decide the outcome for them.
+const neverSlow = time.Hour
+
+// alwaysSlow makes every statement count as slow, so the slow arm is
+// reached without the test waiting for it.
+const alwaysSlow = time.Nanosecond
+
+// openDB opens a real SQLite database behind the adapter under test,
+// so every assertion below is made against SQL that GORM actually
+// rendered rather than against a string a test wrote by hand. slow is
+// the adapter's slow-statement threshold.
+func openDB(
+	t *testing.T, buf *bytes.Buffer, h slog.Handler, slow time.Duration,
+) *gorm.DB {
+	t.Helper()
+
+	sqlDB, err := sql.Open("sqlite", fmt.Sprintf(
+		"file:%s?mode=rwc",
+		filepath.Join(t.TempDir(), "gormlog.db"),
+	))
+	require.NoError(t, err)
+
+	t.Cleanup(func() { _ = sqlDB.Close() })
+
+	gl := gormlog.ExportNewWithSlowThreshold(slog.New(h), slow)
+
+	gdb, err := gorm.Open(
+		sqlite.Dialector{Conn: sqlDB},
+		&gorm.Config{Logger: gl},
+	)
+	require.NoError(t, err)
+
+	require.NoError(t, gdb.AutoMigrate(&thing{}))
+
+	// Migration chatter is not what any of these cases is about.
+	buf.Reset()
+
+	return gdb
+}
+
+// assertBounded holds every line the adapter wrote to the stated
+// ceiling and proves each was cut rather than merely short.
+func assertBounded(t *testing.T, out string) {
+	t.Helper()
+
+	assert.NotContains(
+		t, out, tailMarker,
+		"the far end of the client value reached the log, so "+
+			"nothing truncated it",
+	)
+
+	for line := range strings.SplitSeq(
+		strings.TrimRight(out, "\n"), "\n",
+	) {
+		if line == "" {
+			continue
+		}
+
+		assert.LessOrEqual(
+			t, len(line), middleware.MaxAccessLogLineBytes,
+			"log line exceeded its bound: %s",
+			line[:min(len(line), 300)],
+		)
+	}
+}
+
+// TestRecordNotFound_WritesNothing is the defect itself. GORM's own
+// default logger prints the fully interpolated SELECT on every
+// ErrRecordNotFound, and on this service's two unauthenticated
+// lookups the interpolated parameter is whatever the client sent.
+func TestRecordNotFound_WritesNothing(t *testing.T) {
+	t.Parallel()
+
+	for _, h := range handlers() {
+		for _, f := range fills() {
+			t.Run(h.name+"/"+f.name, func(t *testing.T) {
+				t.Parallel()
+
+				var buf bytes.Buffer
+
+				gdb := openDB(t, &buf, h.make(&buf), neverSlow)
+
+				var got thing
+
+				err := gdb.Where(
+					"id = ?", clientValue(f.fill),
+				).First(&got).Error
+				require.ErrorIs(t, err, gorm.ErrRecordNotFound)
+
+				assert.Empty(
+					t, buf.String(),
+					"a miss on a client-chosen key must not "+
+						"write a log line",
+				)
+			})
+		}
+	}
+}
+
+// TestSlowRecordNotFound_IsStillReportedSlow pins the arm ordering in
+// Trace against the drop above.
+//
+// GORM's own Trace orders its cases error-that-is-not-a-miss, then
+// slow, then routine, so IgnoreRecordNotFoundError: true — the cheap
+// option this adapter was chosen over — still reports a miss that ran
+// slow. An adapter that dropped the miss first would be strictly less
+// observant than the option it replaced, on exactly the two lookups
+// this package exists for. A miss is also the statement most likely to
+// be slow, since it is the one that scans without finding a row.
+func TestSlowRecordNotFound_IsStillReportedSlow(t *testing.T) {
+	t.Parallel()
+
+	for _, h := range handlers() {
+		for _, f := range fills() {
+			t.Run(h.name+"/"+f.name, func(t *testing.T) {
+				t.Parallel()
+
+				var buf bytes.Buffer
+
+				gdb := openDB(t, &buf, h.make(&buf), alwaysSlow)
+
+				var got thing
+
+				err := gdb.Where(
+					"id = ?", clientValue(f.fill),
+				).First(&got).Error
+				require.ErrorIs(t, err, gorm.ErrRecordNotFound)
+
+				assert.Contains(
+					t, buf.String(), "slow sql statement",
+					"a slow statement that missed was not "+
+						"reported as slow",
+				)
+				assertBounded(t, buf.String())
+			})
+		}
+	}
+}
+
+// TestRecordNotFoundFlood_DoesNotGrowWithInput states the definition
+// of done directly: a flood of misses at two input sizes 64 times
+// apart must cost the same number of bytes of log.
+func TestRecordNotFoundFlood_DoesNotGrowWithInput(t *testing.T) {
+	t.Parallel()
+
+	const requests = 50
+
+	flood := func(t *testing.T, size int) int {
+		t.Helper()
+
+		var buf bytes.Buffer
+
+		gdb := openDB(
+			t, &buf,
+			slog.NewJSONHandler(&buf, &slog.HandlerOptions{
+				Level: slog.LevelDebug,
+			}),
+			neverSlow,
+		)
+
+		value := strings.Repeat("\x01", size)
+
+		for range requests {
+			var got thing
+
+			_ = gdb.Where("id = ?", value).First(&got).Error
+		}
+
+		return buf.Len()
+	}
+
+	small := flood(t, 128)
+	big := flood(t, 128*64)
+
+	assert.Equal(
+		t, small, big,
+		"log volume tracked the size of the client's input",
+	)
+}
+
+// TestStatementError_LineIsBounded covers the branch that does log.
+// A driver error is not ErrRecordNotFound, so the interpolated
+// statement is written — and on an insert the interpolated value is
+// still whatever the client supplied.
+func TestStatementError_LineIsBounded(t *testing.T) {
+	t.Parallel()
+
+	for _, h := range handlers() {
+		for _, f := range fills() {
+			t.Run(h.name+"/"+f.name, func(t *testing.T) {
+				t.Parallel()
+
+				var buf bytes.Buffer
+
+				gdb := openDB(t, &buf, h.make(&buf), neverSlow)
+
+				row := thing{ID: clientValue(f.fill), Name: "a"}
+
+				require.NoError(t, gdb.Create(&row).Error)
+
+				buf.Reset()
+
+				// The same primary key a second time: a UNIQUE
+				// constraint failure, which is an error GORM logs.
+				err := gdb.Create(&thing{
+					ID: row.ID, Name: "b",
+				}).Error
+				require.Error(t, err)
+
+				assert.Contains(
+					t, buf.String(), "sql statement failed",
+				)
+				assertBounded(t, buf.String())
+			})
+		}
+	}
+}
+
+// TestSucceedingStatement_LineIsBoundedOnEitherArm covers the two
+// arms a statement that returns no error can take, over the same
+// query, so neither can be bounded by accident of the other.
+//
+//   - slow. Silencing GORM outright would have been the cheaper fix
+//     and would have cost this report, which is the one thing GORM's
+//     logger gave an operator that nothing else in this service does.
+//   - routine. The branch an operator reaches by turning the level
+//     down to DEBUG: every statement is reported, so every
+//     statement's interpolated parameters have to be bounded too.
+func TestSucceedingStatement_LineIsBoundedOnEitherArm(t *testing.T) {
+	t.Parallel()
+
+	// "sql statement" is a substring of "slow sql statement", so the
+	// routine arm carries notWant as well: Contains alone cannot tell
+	// the two arms apart in that direction.
+	arms := []struct {
+		name    string
+		slow    time.Duration
+		want    string
+		notWant string
+	}{
+		{"slow", alwaysSlow, "slow sql statement", ""},
+		{"routine", neverSlow, "sql statement", "slow sql statement"},
+	}
+
+	for _, a := range arms {
+		for _, h := range handlers() {
+			for _, f := range fills() {
+				name := a.name + "/" + h.name + "/" + f.name
+
+				t.Run(name, func(t *testing.T) {
+					t.Parallel()
+
+					var buf bytes.Buffer
+
+					gdb := openDB(t, &buf, h.make(&buf), a.slow)
+
+					var got []thing
+
+					require.NoError(t, gdb.Where(
+						"name = ?", clientValue(f.fill),
+					).Find(&got).Error)
+
+					assert.Contains(t, buf.String(), a.want)
+
+					if a.notWant != "" {
+						assert.NotContains(
+							t, buf.String(), a.notWant,
+						)
+					}
+
+					assertBounded(t, buf.String())
+				})
+			}
+		}
+	}
+}
+
+// TestGORMOwnMessages_AreBounded covers the three printf-style
+// entry points. GORM builds these itself, but nothing stops one of
+// them quoting a value the statement carried.
+func TestGORMOwnMessages_AreBounded(t *testing.T) {
+	t.Parallel()
+
+	for _, h := range handlers() {
+		for _, f := range fills() {
+			t.Run(h.name+"/"+f.name, func(t *testing.T) {
+				t.Parallel()
+
+				var buf bytes.Buffer
+
+				gl := gormlog.New(slog.New(h.make(&buf)))
+				ctx := context.Background()
+				value := clientValue(f.fill)
+
+				gl.Info(ctx, "%s", value)
+				gl.Warn(ctx, "%s", value)
+				gl.Error(ctx, "%s", value)
+
+				// The no-argument form, which is how GORM reports
+				// most of its own conditions. Reached through a
+				// function value so the vet printf check does not
+				// read the message as a format string — which is
+				// also why the adapter does not.
+				noArgs := func(
+					f func(context.Context, string, ...any),
+					msg string,
+				) {
+					f(ctx, msg)
+				}
+				noArgs(gl.Info, value)
+
+				assertBounded(t, buf.String())
+			})
+		}
+	}
+}
+
+// TestLogMode_KeepsTheOperatorsLevel records that GORM's own level
+// knob is deliberately inert: level belongs to LOG_LEVEL, and a
+// second one inside the database layer could only disagree with it.
+func TestLogMode_KeepsTheOperatorsLevel(t *testing.T) {
+	t.Parallel()
+
+	var buf bytes.Buffer
+
+	gl := gormlog.New(slog.New(slog.NewJSONHandler(
+		&buf, &slog.HandlerOptions{Level: slog.LevelDebug},
+	)))
+
+	assert.Same(t, gl, gl.LogMode(0))
+}