Files
Chronos/tests/Titano.Data.Tests/Sqlite/DatabaseBackupsTests.cs
T
Claude 56aa4da674 fix(settings): restore before the index opens; archive rows edit only their archive; parallelism follows the brief
Index restore (ENG-06, UI-09):
- A staged restore now runs on the files before the index is opened, so it also
  recovers an index that no longer opens; Settings > Advanced > Restore works
  without an open index (the current one is shown as unreadable).
- The staged copy passes PRAGMA quick_check (before migration, in a scratch copy)
  ahead of any backup: a damaged copy is set aside as .failed and never renews the
  daily copies. The index it replaces is kept as a VACUUM INTO copy, or, when it
  cannot be read, copied whole with its WAL as titano-replaced-<stamp>.db outside the
  rotation. The staged file is renamed over the index, so it is never applied twice.
- Archive > Maintenance gains Restore database..., which opens Settings > Advanced.

Archive settings (UI-03, ENG-03):
- An archive.json with an empty or overlong name (drive roots) can be edited again:
  the name read is made usable as at creation.
- Proxy and thumbnail sizes outside the presets (an admin's 3840) are listed and
  shown with their number.
- Changing the archive folder retargets the rows: an archive there is registered
  and rescanned; with none, the rows edit only the defaults of new archives. The
  rows never fall back to another archive of the index.
- Reset all and Import settings no longer rewrite the shared archive.json; Archive >
  Reset section asks first, naming the archive.
- PUT /api/v1/archive/settings: 409 archive_busy on a lease conflict, 409
  archive_manifest for a damaged, newer or foreign archive.json (was 500).

Parallelism (UI-02):
- Auto is the job engine's default, half the logical cores (BRIEF 14.6), with each
  job's own decode and analysis threads; a value the user sets is the number of
  workers and caps those threads. The memory budget is shared: each job's frame
  window gets budget / workers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
2026-10-12 11:06:27 +00:00

253 lines
14 KiB
C#
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
using Titano.Core.Model;
using Titano.Data.Repositories;
using Titano.Testing;
namespace Titano.Data.Tests.Sqlite;
/// <summary>
/// BRIEF §6.2: a VACUUM INTO copy of the SQLite index once a day, the newest three kept, and a restore from Settings ›
/// Advanced that waits for the next start, runs before the index opens (so it recovers one that no longer opens), checks
/// the copy first (quick_check included) and never replaces a working index with a broken one.
/// </summary>
[Category("sqlite")]
public sealed class DatabaseBackupsTests(TestContext context)
{
/// <summary>A clock the test moves; timers created on it never fire by themselves.</summary>
private sealed class ManualClock(DateTimeOffset now) : TimeProvider
{
public DateTimeOffset Now { get; set; } = now;
public override DateTimeOffset GetUtcNow() => Now;
}
private async Task<(TitanoDatabase Db, string Path)> OpenAsync(string name = "titano.db")
{
var path = System.IO.Path.Combine(context.CreateTempDirectory("db"), name);
return (await TitanoDatabase.OpenAsync(DatabaseOptions.Sqlite(path), context.Cancellation), path);
}
private static Task AddArchiveAsync(TitanoDatabase db, string name) =>
db.Archives.UpsertAsync(new Archive { Id = Guid.CreateVersion7(), Name = name, RootPath = "/archives/" + name, Created = DateTimeOffset.UtcNow });
[Test]
public async Task ListsTheCopiesOfThisIndexNewestFirst()
{
var directory = context.CreateTempDirectory("backups");
File.WriteAllText(Path.Combine(directory, "titano-20261010-030000-000.db"), "a");
File.WriteAllText(Path.Combine(directory, "titano-20261012-030000-000.db"), "bb");
File.WriteAllText(Path.Combine(directory, "titano-20261011-030000-000.db"), "ccc");
File.WriteAllText(Path.Combine(directory, "other-20261013-030000-000.db"), "x");
File.WriteAllText(Path.Combine(directory, "titano-notes.db"), "x");
var backups = DatabaseBackups.List(directory, "/data/titano.db");
Assert.SequenceEqual(["titano-20261012-030000-000.db", "titano-20261011-030000-000.db", "titano-20261010-030000-000.db"],
backups.Select(b => Path.GetFileName(b.Path)));
Assert.Equal(new DateTimeOffset(2026, 10, 12, 3, 0, 0, TimeSpan.Zero), backups[0].Created);
Assert.Equal(2L, backups[0].Bytes);
Assert.Empty(DatabaseBackups.List(Path.Combine(directory, "missing"), "/data/titano.db"));
}
[Test]
public void ACopyIsDueWhenTheNewestIsADayOld()
{
var now = new DateTimeOffset(2026, 10, 12, 9, 0, 0, TimeSpan.Zero);
Assert.True(DatabaseBackups.IsDue([], now));
Assert.False(DatabaseBackups.IsDue([new DatabaseBackup("b", now.AddHours(-23), 1)], now));
Assert.True(DatabaseBackups.IsDue([new DatabaseBackup("b", now.AddHours(-24), 1)], now));
}
[Test]
public async Task TheDailyCopyIsMadeAtStartOnlyWhenDue()
{
var (db, _) = await OpenAsync();
await using var _ = db;
var directory = context.CreateTempDirectory("backups");
var clock = new ManualClock(DateTimeOffset.UtcNow);
// No copy yet: one is made at once, then the loop waits for its hourly check until stopped.
using (var stop = new CancellationTokenSource())
{
var loop = DatabaseBackups.RunDailyAsync(db, directory, clock, stop.Token);
var until = DateTime.UtcNow.AddSeconds(20);
while (Directory.GetFiles(directory, "*.db").Length == 0 && DateTime.UtcNow < until) await Task.Delay(20);
await stop.CancelAsync();
await loop.WaitAsync(TimeSpan.FromSeconds(20));
}
Assert.Count(1, Directory.GetFiles(directory, "*.db"));
// A fresh copy exists: starting again makes none.
using (var stop = new CancellationTokenSource())
{
var loop = DatabaseBackups.RunDailyAsync(db, directory, clock, stop.Token);
await Task.Delay(300);
await stop.CancelAsync();
await loop.WaitAsync(TimeSpan.FromSeconds(20));
}
Assert.Count(1, Directory.GetFiles(directory, "*.db"));
}
[Test]
public async Task AStagedRestoreReplacesTheIndexAtTheNextOpen()
{
var (db, path) = await OpenAsync();
var directory = context.CreateTempDirectory("backups");
await AddArchiveAsync(db, "kept");
var backup = await db.BackupAsync(directory, DatabaseBackups.Keep, context.Cancellation);
await AddArchiveAsync(db, "added later");
Assert.Equal(new DatabaseSummary(db.SchemaVersion, 2, 0, 0), await DatabaseBackups.SummarizeAsync(db, context.Cancellation));
// The dry run reads the copy without touching it.
var bytes = await File.ReadAllBytesAsync(backup, context.Cancellation);
var summary = await DatabaseBackups.SummarizeBackupAsync(backup, context.CreateTempDirectory("scratch"), context.Cancellation);
Assert.Equal(1, summary.Archives);
Assert.SequenceEqual(bytes, await File.ReadAllBytesAsync(backup, context.Cancellation));
await DatabaseBackups.StageRestoreAsync(backup, path, context.Cancellation);
Assert.True(DatabaseBackups.HasStagedRestore(path));
await db.DisposeAsync();
// The next start, before the index opens: the index as it was is copied first, then it is the chosen copy and
// the staged file is gone (consumed by the swap, so it can never be applied twice).
Assert.True(await DatabaseBackups.RestoreStagedAsync(path, directory, context.Cancellation));
await using var reopened = await TitanoDatabase.OpenAsync(DatabaseOptions.Sqlite(path), context.Cancellation);
Assert.SequenceEqual(["kept"], (await reopened.Archives.ListAsync(context.Cancellation)).Select(a => a.Name));
Assert.False(DatabaseBackups.HasStagedRestore(path));
var copies = DatabaseBackups.List(directory, path);
Assert.Count(2, copies);
var replaced = await DatabaseBackups.SummarizeBackupAsync(copies[0].Path, context.CreateTempDirectory("scratch"), context.Cancellation);
Assert.Equal(2, replaced.Archives);
Assert.False(await DatabaseBackups.RestoreStagedAsync(path, directory, context.Cancellation), "nothing staged any more");
}
[Test]
public async Task AStagedRestoreRecoversAnIndexThatNoLongerOpens()
{
var (db, path) = await OpenAsync();
var directory = context.CreateTempDirectory("backups");
await AddArchiveAsync(db, "kept");
await db.BackupAsync(directory, DatabaseBackups.Keep, context.Cancellation);
var newest = await db.BackupAsync(directory, DatabaseBackups.Keep, context.Cancellation);
var daily = DatabaseBackups.List(directory, path).Select(b => b.Path).ToList();
await DatabaseBackups.StageRestoreAsync(newest, path, context.Cancellation);
await db.DisposeAsync();
// The index is damaged beyond opening ("file is not a database").
File.Delete(path + "-wal");
File.Delete(path + "-shm");
var garbage = new byte[16384];
new Random(7).NextBytes(garbage);
await File.WriteAllBytesAsync(path, garbage, context.Cancellation);
await Assert.ThrowsAsync<DatabaseException>(async () => await (await TitanoDatabase.OpenAsync(DatabaseOptions.Sqlite(path), context.Cancellation)).DisposeAsync());
Assert.True(await DatabaseBackups.RestoreStagedAsync(path, directory, context.Cancellation));
await using var reopened = await TitanoDatabase.OpenAsync(DatabaseOptions.Sqlite(path), context.Cancellation);
Assert.SequenceEqual(["kept"], (await reopened.Archives.ListAsync(context.Cancellation)).Select(a => a.Name));
Assert.False(DatabaseBackups.HasStagedRestore(path));
// The damaged index is kept whole beside the daily copies, outside their rotation: none of them was pushed out.
Assert.SequenceEqual(daily, DatabaseBackups.List(directory, path).Select(b => b.Path));
var aside = Assert.Contains(Directory.GetFiles(directory), f => Path.GetFileName(f).StartsWith("titano-replaced-", StringComparison.Ordinal));
Assert.SequenceEqual(garbage, await File.ReadAllBytesAsync(aside, context.Cancellation));
}
[Test]
public async Task ABrokenStagedCopyIsSetAsideAndTheIndexKept()
{
var (db, path) = await OpenAsync();
await AddArchiveAsync(db, "current");
await db.DisposeAsync();
await File.WriteAllTextAsync(DatabaseBackups.StagedPath(path), "this is not a database", context.Cancellation);
var backups = context.CreateTempDirectory("backups");
await Assert.ThrowsAsync<InvalidDataException>(() => DatabaseBackups.RestoreStagedAsync(path, backups, context.Cancellation));
Assert.False(DatabaseBackups.HasStagedRestore(path));
Assert.FileExists(DatabaseBackups.StagedPath(path) + ".failed");
Assert.Empty(Directory.GetFiles(backups));
await using var reopened = await TitanoDatabase.OpenAsync(DatabaseOptions.Sqlite(path), context.Cancellation);
Assert.SequenceEqual(["current"], (await reopened.Archives.ListAsync(context.Cancellation)).Select(a => a.Name));
await Assert.ThrowsAsync<InvalidDataException>(() =>
DatabaseBackups.SummarizeBackupAsync(DatabaseBackups.StagedPath(path) + ".failed", context.CreateTempDirectory("scratch"), context.Cancellation));
}
[Test]
public async Task AStagedCopyThatFailsItsIntegrityCheckIsSetAsideBeforeAnyCopyIsMade()
{
var (db, path) = await OpenAsync();
var directory = context.CreateTempDirectory("backups");
await AddArchiveAsync(db, "current");
// A table the summary never reads, filled so its pages come last in a VACUUM INTO copy.
await using (var session = await db.Database.OpenAsync(context.Cancellation))
{
await session.ExecuteScriptAsync("""
CREATE TABLE filler (id INTEGER PRIMARY KEY, data BLOB);
WITH RECURSIVE n(i) AS (SELECT 1 UNION ALL SELECT i + 1 FROM n WHERE i < 200) INSERT INTO filler (data) SELECT randomblob(1000) FROM n;
""", context.Cancellation);
}
for (var i = 0; i < DatabaseBackups.Keep; i++) await db.BackupAsync(directory, DatabaseBackups.Keep, context.Cancellation);
var daily = DatabaseBackups.List(directory, path).Select(b => b.Path).ToList();
await db.DisposeAsync();
// One damaged page in the filler table of the copy: the header, the schema and every counted table are intact.
var damaged = Path.Combine(context.CreateTempDirectory("damaged"), "copy.db");
File.Copy(daily[0], damaged);
var bytes = await File.ReadAllBytesAsync(damaged, context.Cancellation);
var pageSize = (bytes[16] << 8) | bytes[17];
if (pageSize == 1) pageSize = 65536;
bytes[bytes.Length - pageSize] = 0xFF;
await File.WriteAllBytesAsync(damaged, bytes, context.Cancellation);
// Opening, migrating and counting do not notice it: only quick_check does.
var probe = Path.Combine(context.CreateTempDirectory("probe"), "titano.db");
File.Copy(damaged, probe);
await using (var opened = await TitanoDatabase.OpenAsync(DatabaseOptions.Sqlite(probe), context.Cancellation))
Assert.Equal(1, (await DatabaseBackups.SummarizeAsync(opened, context.Cancellation)).Archives);
await Assert.ThrowsAsync<InvalidDataException>(() => DatabaseBackups.SummarizeBackupAsync(damaged, context.CreateTempDirectory("scratch"), context.Cancellation));
await DatabaseBackups.StageRestoreAsync(damaged, path, context.Cancellation);
await Assert.ThrowsAsync<InvalidDataException>(() => DatabaseBackups.RestoreStagedAsync(path, directory, context.Cancellation));
Assert.False(DatabaseBackups.HasStagedRestore(path), "set aside: the next start neither retries it nor makes another copy");
Assert.FileExists(DatabaseBackups.StagedPath(path) + ".failed");
Assert.SequenceEqual(daily, DatabaseBackups.List(directory, path).Select(b => b.Path));
Assert.False(await DatabaseBackups.RestoreStagedAsync(path, directory, context.Cancellation));
await using var reopened = await TitanoDatabase.OpenAsync(DatabaseOptions.Sqlite(path), context.Cancellation);
Assert.SequenceEqual(["current"], (await reopened.Archives.ListAsync(context.Cancellation)).Select(a => a.Name));
}
[Test]
public async Task CancellingAStagedRestoreKeepsTheIndex()
{
var (db, path) = await OpenAsync();
var directory = context.CreateTempDirectory("backups");
var backup = await db.BackupAsync(directory, DatabaseBackups.Keep, context.Cancellation);
await DatabaseBackups.StageRestoreAsync(backup, path, context.Cancellation);
await db.DisposeAsync();
DatabaseBackups.CancelStagedRestore(path);
Assert.False(DatabaseBackups.HasStagedRestore(path));
Assert.False(await DatabaseBackups.RestoreStagedAsync(path, directory, context.Cancellation));
Assert.FileExists(backup);
}
[Test]
public async Task ARestoreWaitsWhenTheIndexCannotBeBackedUpFirst()
{
var (db, path) = await OpenAsync();
var backup = await db.BackupAsync(context.CreateTempDirectory("backups"), DatabaseBackups.Keep, context.Cancellation);
await AddArchiveAsync(db, "since the backup");
await DatabaseBackups.StageRestoreAsync(backup, path, context.Cancellation);
await db.DisposeAsync();
// The backups folder cannot be created: a file is in its way.
var blocked = Path.Combine(context.CreateTempDirectory("blocked"), "backups");
await File.WriteAllTextAsync(blocked, "not a folder", context.Cancellation);
await Assert.ThrowsAsync<IOException>(() => DatabaseBackups.RestoreStagedAsync(path, blocked, context.Cancellation));
Assert.True(DatabaseBackups.HasStagedRestore(path), "the restore stays staged for the next start");
await using var reopened = await TitanoDatabase.OpenAsync(DatabaseOptions.Sqlite(path), context.Cancellation);
Assert.SequenceEqual(["since the backup"], (await reopened.Archives.ListAsync(context.Cancellation)).Select(a => a.Name));
}
}