Rotate a database target's archive monthly, daily or hourly (closes #379)

A database target's rotation (none, monthly, daily or hourly) puts the
UTC period of each event's receive time in its archive file name, so
each file holds exactly its period's events. It is on the new webhook
page, the add target form and the target edit form, and shown in the
target list.

Renames move every one of a target's files and move them back if one
fails. The sweep prunes every file, one at a time under the target's
lock, and deletes a rotated file it leaves empty. Download lists the
files, then opens one at a time, oldest first, finding each again under
the target's current names, and gives each row its period. The target
list names the current file and totals the size of all of them.

Model: opus-5-5

internal/delivery/target_database_export_test.go

@@ -12,6 +12,8 @@ import (
 	"os"
 	"path/filepath"
 	"runtime"
+	"strings"
+	"sync"
 	"testing"
 	"time"
 
@@ -29,14 +31,8 @@ const (
 	exportTargetName  = "Long-term archive"
 )
 
-const (
-	// binaryBody is a body that is not valid UTF-8.
-	binaryBody = "\xff\xfe\x00\x01binary\x80"
-
-	// openedEventID is the event the snapshot tests archive before
-	// they open the export.
-	openedEventID = "opened"
-)
+// binaryBody is a body that is not valid UTF-8.
+const binaryBody = "\xff\xfe\x00\x01binary\x80"
 
 // writeExportTo writes export to w as the archive of the export tests'
 // webhook and target, exported at 2026-10-02T12:03:04Z.
@@ -59,19 +55,41 @@ func writeExportTo(
 	)
 }
 
+// listExport lists the archive at path for export, as the archive of a
+// target whose names do not change.
+func listExport(t *testing.T, path string) *delivery.ArchiveExport {
+	t.Helper()
+
+	return newExport(t, path, &sync.Mutex{}, func() (string, error) {
+		return path, nil
+	})
+}
+
+// newExport lists the archive at path for export, to find each file
+// again under the path currentPath gives, holding lock while it does.
+// Nothing else takes lock while it lists, so it does not hold lock.
+func newExport(
+	t *testing.T,
+	path string,
+	lock sync.Locker,
+	currentPath func() (string, error),
+) *delivery.ArchiveExport {
+	t.Helper()
+
+	export, err := delivery.NewArchiveExport(
+		path, lock, currentPath, archiveTestLogger(),
+	)
+	require.NoError(t, err)
+
+	return export
+}
+
 // exportArchive runs a whole export of the archive at path and returns
 // its JSON, decompressed and parsed.
 func exportArchive(t *testing.T, path string) map[string]any {
 	t.Helper()
 
-	export, err := delivery.OpenArchiveExport(
-		t.Context(), path, archiveTestLogger(),
-	)
-	require.NoError(t, err)
-
-	defer func() { require.NoError(t, export.Close()) }()
-
-	return writeExport(t, export)
+	return writeExport(t, listExport(t, path))
 }
 
 // writeExport writes an opened export and returns its JSON,
@@ -241,66 +259,199 @@ func TestArchiveExport_Empty(t *testing.T) {
 	}
 }
 
-// TestArchiveExport_ReadsOneSnapshot proves an export writes the
-// archive as it was when it was opened, and holds up no archive
-// write: a row written while the export is open is stored, and is not
-// in the export. A write held up for the whole busy timeout would
-// fail.
+// unlockHook is a sync.Locker that runs fn each time it is unlocked. An
+// export unlocks its lock right after it opens a file.
+type unlockHook struct {
+	sync.Mutex
+
+	fn func()
+}
+
+func (u *unlockHook) Unlock() {
+	u.Mutex.Unlock()
+	u.fn()
+}
+
+// TestArchiveExport_ReadsOneSnapshot proves an export writes a file
+// out as it was when the export opened it, and holds up no archive
+// write: a row written after the export was listed but before the file
+// was opened is in the export, and one written while the file is open
+// is stored, and is not. A write held up for the whole busy timeout
+// would fail.
 func TestArchiveExport_ReadsOneSnapshot(t *testing.T) {
 	t.Parallel()
 
 	path := filepath.Join(t.TempDir(), "archive.db")
 	w := delivery.NewExportArchiveWriter(path, archiveTestLogger(), 0)
 
-	require.NoError(t, w.Write(delivery.ExportArchivedEvent{EventID: openedEventID}, 0))
+	require.NoError(t, w.Write(delivery.ExportArchivedEvent{EventID: "listed"}, 0))
 
-	export, err := delivery.OpenArchiveExport(
-		t.Context(), path, archiveTestLogger(),
-	)
-	require.NoError(t, err)
+	opened := &unlockHook{fn: func() {
+		require.NoError(t, w.Write(delivery.ExportArchivedEvent{EventID: "during"}, 0))
+	}}
+	export := newExport(t, path, opened, func() (string, error) {
+		return path, nil
+	})
 
-	defer func() { require.NoError(t, export.Close()) }()
-
-	require.NoError(t, w.Write(delivery.ExportArchivedEvent{EventID: "during"}, 0))
+	require.NoError(t, w.Write(delivery.ExportArchivedEvent{EventID: "before-open"}, 0))
 
 	assert.Equal(t,
-		[]string{openedEventID}, exportedEventIDs(t, writeExport(t, export)),
+		[]string{"listed", "before-open"},
+		exportedEventIDs(t, writeExport(t, export)),
 	)
 
 	var stored int64
 
 	require.NoError(t, openArchiveDBForRead(t, path).
 		Model(&delivery.ExportArchivedEvent{}).Count(&stored).Error)
-	assert.Equal(t, int64(2), stored)
+	assert.Equal(t, int64(3), stored)
 }
 
-// TestArchiveExport_SurvivesRename proves that renaming the archive
-// while an export of it is open, as renaming its webhook or target
-// does, leaves the export reading the same file.
-func TestArchiveExport_SurvivesRename(t *testing.T) {
+// TestArchiveExport_FindsFilesAfterRename proves that renaming the
+// archive after an export has listed it, as renaming its webhook or
+// target does, loses no file: the export finds each file again by its
+// period under the new name. A file moved away by then is skipped.
+func TestArchiveExport_FindsFilesAfterRename(t *testing.T) {
 	t.Parallel()
 
-	path := filepath.Join(t.TempDir(), "archive-old.db")
+	dir := t.TempDir()
+	path := filepath.Join(dir, "archive-old.db")
 	w := delivery.NewExportArchiveWriter(path, archiveTestLogger(), 0)
 
-	require.NoError(t, w.Write(delivery.ExportArchivedEvent{EventID: openedEventID}, 0))
+	for _, period := range []string{"", dayPeriod, hourPeriod} {
+		require.NoError(t, w.WritePeriod(
+			delivery.ExportArchivedEvent{EventID: "in-" + period}, 0, period,
+		))
+	}
 
-	export, err := delivery.OpenArchiveExport(
-		t.Context(), path, archiveTestLogger(),
-	)
-	require.NoError(t, err)
-
-	defer func() { require.NoError(t, export.Close()) }()
+	current := path
+	export := newExport(t, path, &sync.Mutex{}, func() (string, error) {
+		return current, nil
+	})
 
 	require.NoError(t, w.Rename("archive-new.db"))
-	require.NoError(t, w.Write(delivery.ExportArchivedEvent{EventID: "after"}, 0))
-	require.NoFileExists(t, path)
+
+	current = filepath.Join(dir, "archive-new.db")
+
+	removeArchiveFiles(t, periodPath(current, dayPeriod))
 
 	assert.Equal(t,
-		[]string{openedEventID}, exportedEventIDs(t, writeExport(t, export)),
+		[]string{"in-", "in-" + hourPeriod},
+		exportedEventIDs(t, writeExport(t, export)),
 	)
 }
 
+// TestArchiveExport_EveryFileOldestFirst writes a row to a target's
+// file without a period and to its files for a month, an hour and a
+// day, and proves the export holds every row: the file without a
+// period first, then the others oldest period first, each row from a
+// file named for a period carrying that period. A file made after the
+// export was listed is not in it.
+func TestArchiveExport_EveryFileOldestFirst(t *testing.T) {
+	t.Parallel()
+
+	path := filepath.Join(t.TempDir(), "archive-wh.db")
+	w := delivery.NewExportArchiveWriter(path, archiveTestLogger(), 0)
+
+	// Written in an order that is not the export's.
+	for _, period := range []string{nextDayPeriod, "", hourPeriod, "2026-03"} {
+		require.NoError(t, w.WritePeriod(
+			delivery.ExportArchivedEvent{EventID: "in-" + period}, 0, period,
+		))
+	}
+
+	export := listExport(t, path)
+
+	require.NoError(t, w.WritePeriod(
+		delivery.ExportArchivedEvent{EventID: "later"}, 0, "2026-03-06",
+	))
+
+	events := exportedEvents(t, writeExport(t, export))
+	ids := make([]string, 0, len(events))
+	periods := make([]any, 0, len(events))
+
+	for _, ev := range events {
+		ids = append(ids, fmt.Sprint(ev["event_id"]))
+		periods = append(periods, ev["period"])
+	}
+
+	assert.Equal(t,
+		[]string{"in-", "in-2026-03", "in-" + hourPeriod, "in-" + nextDayPeriod},
+		ids,
+	)
+	assert.Equal(t,
+		[]any{nil, "2026-03", hourPeriod, nextDayPeriod}, periods,
+	)
+	assert.NotContains(t, events[0], "period",
+		"a row from the file without a period has no period")
+}
+
+// openFilesPeak is an io.Writer that discards what it is given and
+// records the most archive files in dir the process had open at any
+// write, as /proc/self/fd lists the files a process has open.
+type openFilesPeak struct {
+	dir string
+	max int
+}
+
+func (p *openFilesPeak) Write(b []byte) (int, error) {
+	fds, err := os.ReadDir("/proc/self/fd")
+	if err != nil {
+		return 0, err
+	}
+
+	open := map[string]bool{}
+
+	for _, fd := range fds {
+		file, err := os.Readlink(filepath.Join("/proc/self/fd", fd.Name()))
+		if err == nil && filepath.Dir(file) == p.dir &&
+			strings.HasSuffix(file, ".db") {
+			open[file] = true
+		}
+	}
+
+	p.max = max(p.max, len(open))
+
+	return len(b), nil
+}
+
+// TestArchiveExport_OneFileOpenAtATime exports a target with a file for
+// each of 24 hours and proves the export never had more than one of
+// them open, and had one open while it wrote. Each file holds a row of
+// 48 KiB of random base64, which gzip shrinks little, so the export
+// writes output while it reads each file.
+func TestArchiveExport_OneFileOpenAtATime(t *testing.T) {
+	t.Parallel()
+
+	if runtime.GOOS != "linux" {
+		t.Skip("only Linux lists a process's open files in /proc/self/fd")
+	}
+
+	// Readlink gives each open file's path with no symbolic link in it.
+	dir, err := filepath.EvalSymlinks(t.TempDir())
+	require.NoError(t, err)
+
+	path := filepath.Join(dir, "archive-wh.db")
+	w := delivery.NewExportArchiveWriter(path, archiveTestLogger(), 0)
+	random := make([]byte, 36<<10)
+
+	for hour := range 24 {
+		_, _ = rand.Read(random)
+
+		require.NoError(t, w.WritePeriod(delivery.ExportArchivedEvent{
+			Body: base64.StdEncoding.EncodeToString(random),
+		}, 0, fmt.Sprintf("2026-10-01-%02d", hour)))
+	}
+
+	// The writer's own handle on the last file is not the export's.
+	w.Evict()
+
+	peak := &openFilesPeak{dir: dir}
+
+	require.NoError(t, writeExportTo(t, listExport(t, path), peak))
+	assert.Equal(t, 1, peak.max)
+}
+
 // heapPeak is an io.Writer that discards what it is given and records
 // the largest heap it saw at a write. It collects garbage before each
 // reading, so the heap it reads is what is still held.
@@ -338,12 +489,7 @@ func exportHeapGrowth(t *testing.T, rows, bodySize int) uint64 {
 		}, 0))
 	}
 
-	export, err := delivery.OpenArchiveExport(
-		t.Context(), path, archiveTestLogger(),
-	)
-	require.NoError(t, err)
-
-	defer func() { require.NoError(t, export.Close()) }()
+	export := listExport(t, path)
 
 	runtime.GC()