Files
Chronos/src/Chronos.Data/Archiving/ArchiveService.cs
T
Alby96andClaude Opus 5.5 9b24cf74fc
CI / Build and test (push) Successful in 9m43s
CI / Windows tests and installer (push) Skipped
CI / YAML check (push) Successful in 27s
CI / PostgreSQL 16 integration (push) Failing after 8m41s
CI / PostgreSQL 17 integration (push) Successful in 12m37s
CI / Docker image (push) Successful in 56s
Release / Build, test and publish (push) Successful in 14m59s
Release / Server image (push) Successful in 1m51s
feat: owner review 2 phase 5a: workspace and projects with a local home (#14)
Edit opens a sequence as a project of a workspace folder outside the library. Projects have linear version histories kept as sidecars in .chronos/projects/, Main mirrors the sequence's settings, and sync merges setting by setting. Migration 0009, JobKind.WorkspaceCopy = 20, Settings › Workspace, and 241 new strings in 38 languages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Alberto Balbo <alberto.balbo.96@gmail.com>
2026-11-04 09:22:08 +01:00

743 lines
50 KiB
C#

using System.Text.Json;
using Chronos.Core.Archiving;
using Chronos.Core.Conversion;
using Chronos.Core.Diagnostics;
using Chronos.Core.Import;
using Chronos.Core.Localization;
using Chronos.Core.Model;
using Chronos.Core.Naming;
using Chronos.Data.Archiving.Jobs;
using Chronos.Data.Jobs;
using Chronos.Data.Processing;
using Chronos.Data.Projects;
using Chronos.Data.Repositories;
namespace Chronos.Data.Archiving;
/// <summary>
/// What the desktop client and the server call to work with archives (BRIEF §7, §12.4, §12.5, §14.4): open, create
/// or adopt an archive, read and change its settings, plan and apply mass renames, plan mass conversions, plan imports and
/// card erases, delete sequences into the trash and restore them, query duplicates and orphans, and
/// the job handlers for the long operations (enqueue them with <see cref="ArchiveJobs"/>).
/// </summary>
public sealed class ArchiveService : IJobHandlerProvider
{
/// <summary>Lease serialising read-modify-write of <c>archive.json</c> between the processes sharing an archive.</summary>
private const string SettingsLease = "archive-settings";
/// <summary>Times a title, tags, rating or notes edit is applied at the version it read before it writes regardless.</summary>
private const int InfoEditAttempts = 3;
private readonly ChronosDatabase _db;
private readonly SequenceWriter _writer;
public ArchiveService(ChronosDatabase db, ArchiveServiceOptions? options = null)
{
_db = db;
_writer = new SequenceWriter(options ?? new ArchiveServiceOptions());
Indexer = new ArchiveIndexer(db, _writer);
Ingest = new ArchiveIngest(db, _writer, Indexer);
Verifier = new ArchiveVerifier(db, _writer, Indexer);
Maintenance = new ArchiveMaintenance(db, _writer, Indexer);
Renamer = new MassRenamer(db, _writer, Indexer);
Images = new ArchiveImages(db, _writer, Indexer);
Imports = new ImportService(db, Ingest);
Trash = new SequenceTrash(db, _writer, Indexer);
FrameTrash = new FrameTrash(db, _writer, Indexer, Ingest, Trash);
Converter = new MassConverter(db, _writer, Ingest, FrameTrash, Trash, this);
Projects = new ProjectService(db, _writer);
var shared = Housekeeping.CleanupSteps.Shared(Trash);
CleanupSteps = [.. shared, .. _writer.Options.CleanupSteps.Where(s => !shared.Any(o => o.Name == s.Name))];
}
public ArchiveIndexer Indexer { get; }
/// <summary>Commits staged files into sequences (server uploads, client card imports).</summary>
public ArchiveIngest Ingest { get; }
public ArchiveVerifier Verifier { get; }
public ArchiveMaintenance Maintenance { get; }
public MassRenamer Renamer { get; }
public ArchiveImages Images { get; }
public ImportService Imports { get; }
/// <summary>Deletes sequences into the archive's trash and restores them; lists and empties the trash.</summary>
public SequenceTrash Trash { get; }
/// <summary>Deletes photos of a sequence into the archive's trash and restores them (owner review 2, R6).</summary>
public FrameTrash FrameTrash { get; }
/// <summary>Converts sequences to JPEG, TIFF-16 or linear DNG, replacing their frames or into new sequences (owner review 2, R7).</summary>
public MassConverter Converter { get; }
/// <summary>The projects of the sequences and their versions: this PC's archive as a project's home (owner review 2, R8).</summary>
public ProjectService Projects { get; }
/// <summary>The decoders of this engine's image passes (thumbnails, proxies).</summary>
public Core.Imaging.ImageDecoder Decoder => _writer.Options.Decoder;
/// <summary>How the host measures free space under a folder (<see cref="ArchiveServiceOptions.FreeSpace"/>); null: the folder's drive.</summary>
public Func<string, long?>? FreeSpace => _writer.Options.FreeSpace;
/// <summary>
/// The steps this host's <see cref="JobKind.Cleanup"/> jobs can run: the shared ones (<see cref="Housekeeping.CleanupSteps.Shared"/>),
/// then the host's (<see cref="ArchiveServiceOptions.CleanupSteps"/>). A schedule host lists their names.
/// </summary>
public IReadOnlyList<Housekeeping.ICleanupStep> CleanupSteps { get; }
/// <summary>Where this engine's <see cref="JobKind.Backup"/> jobs put their copies (<see cref="ArchiveServiceOptions.BackupDirectory"/>; null: next to the index).</summary>
public string? BackupDirectory => _writer.Options.BackupDirectory;
/// <summary>
/// Handlers for scan, rebuild, verify, import, thumbs, proxies and maintenance jobs, the read-only duplicates and orphans
/// reports, index backups and clean-ups (owner review 2, R10), the emptying of the trash (R6), Reorganize (R7,
/// <see cref="JobKind.Move"/>) and mass conversion (R7, <see cref="JobKind.Convert"/>); register them on the
/// <see cref="JobEngine"/>.
/// </summary>
public IReadOnlyList<IJobHandler> CreateJobHandlers() =>
[
new ScanJobHandler(_db, Indexer, JobKind.Scan, _writer.Options.ImagesAfterScan),
new ScanJobHandler(_db, Indexer, JobKind.Rebuild, _writer.Options.ImagesAfterScan),
new VerifyJobHandler(_db, Verifier),
new ImportJobHandler(_db, Imports),
new ImageJobHandler(_db, Images, JobKind.Thumbs),
new ImageJobHandler(_db, Images, JobKind.Proxies),
new MaintenanceJobHandler(_db, Maintenance),
new DuplicatesJobHandler(_db, Maintenance),
new OrphansJobHandler(_db, Maintenance),
new Housekeeping.BackupJobHandler(_db, _writer.Options.BackupDirectory),
new Housekeeping.CleanupJobHandler(_db, CleanupSteps, TimeProvider.System),
new EmptyTrashJobHandler(_db, Trash),
new MoveJobHandler(_db, Renamer, _writer.Options.SequenceChanged),
new ConvertJobHandler(_db, Converter, _writer.Options.SequenceChanged),
];
/// <summary>Makes <paramref name="root"/> a new, empty archive and indexes it.</summary>
/// <exception cref="InvalidOperationException">The folder already is an archive (open it instead).</exception>
public Task<Archive> CreateAsync(string root, string name, LayoutTemplates? templates = null, ProxyPolicy? proxies = null,
CancellationToken cancellationToken = default) =>
CreateAsync(root, new ArchiveSettings(name, templates ?? new LayoutTemplates(), proxies ?? new ProxyPolicy(), new ThumbnailPolicy()), cancellationToken);
/// <summary>
/// Makes <paramref name="root"/> a new, empty archive with <paramref name="settings"/> and indexes it. A blank name
/// becomes the folder's name; a longer one than <see cref="ArchiveSettings.MaxNameLength"/> is shortened.
/// </summary>
/// <exception cref="InvalidOperationException">The folder already is an archive (open it instead).</exception>
/// <exception cref="ArgumentException">A template or policy is invalid (<see cref="ArgumentException.ParamName"/> names it;
/// <see cref="TemplateRuleException"/> for a template that breaks a rule).</exception>
public async Task<Archive> CreateAsync(string root, ArchiveSettings settings, CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(settings);
var paths = new ArchivePaths(root);
settings = WithUsableName(settings, paths);
settings.Validate();
if (File.Exists(paths.ManifestPath)) throw new InvalidOperationException($"{paths.Root} already is a Chronos archive.");
Directory.CreateDirectory(paths.MetaDirectory);
var manifest = new ArchiveManifest
{
Id = Guid.CreateVersion7(),
Name = settings.Name.Trim(),
Created = DateTimeOffset.UtcNow,
LayoutTemplates = settings.Templates,
ProxyPolicy = settings.Proxies,
ThumbnailPolicy = settings.Thumbnails,
};
ManifestStore.WriteArchive(paths.ManifestPath, manifest);
return await RegisterAsync(paths, manifest, cancellationToken).ConfigureAwait(false);
}
/// <summary>
/// Registers an existing archive (or relinks a moved one: same id, new root) and completes renames a crash
/// interrupted (each sequence they change is told to <see cref="ArchiveServiceOptions.SequenceChanged"/>); one that
/// cannot be completed yet is logged and waits for the next open. An offline archive is registered as it was last seen.
/// </summary>
public async Task<Archive> OpenAsync(string root, CancellationToken cancellationToken = default)
{
var paths = new ArchivePaths(root);
var archive = await RegisterAsync(paths, ManifestStore.ReadArchive(paths.ManifestPath), cancellationToken).ConfigureAwait(false);
if (ArchiveVolume.Probe(paths) != ArchiveAvailability.Online) return archive;
try
{
await Renamer.ResumePendingAsync(archive, cancellationToken).ConfigureAwait(false);
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or InvalidDataException or NewerFormatException)
{
// The journal stays; the next open tries again. The archive itself is usable meanwhile (a server starts all the same).
Log.Warning("archive", $"Resuming an interrupted rename in {paths.Root} failed", ex);
}
return archive;
}
/// <summary>
/// Opens a folder of photos as an archive in place (Welcome "adopt folder"): nothing is moved or renamed; enqueue
/// <see cref="ArchiveJobs.Scan"/> with a full pass to write sidecars and index it.
/// </summary>
public Task<Archive> AdoptAsync(string root, string? name = null, CancellationToken cancellationToken = default)
{
var paths = new ArchivePaths(root);
return File.Exists(paths.ManifestPath)
? OpenAsync(root, cancellationToken)
: CreateAsync(root, name ?? Path.GetFileName(paths.Root), null, null, cancellationToken);
}
/// <summary>
/// <see cref="AdoptAsync(string, string?, CancellationToken)"/> for a folder that may become a new archive with
/// <paramref name="defaults"/> (templates and policies; the folder's name when its name is blank). An existing
/// archive keeps its own settings.
/// </summary>
public Task<Archive> AdoptAsync(string root, ArchiveSettings defaults, CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(defaults);
return File.Exists(new ArchivePaths(root).ManifestPath) ? OpenAsync(root, cancellationToken) : CreateAsync(root, defaults, cancellationToken);
}
/// <summary>
/// The settings in the archive's <c>archive.json</c>; those of the index (with the default thumbnail policy, which only
/// the file keeps) while the file cannot be read.
/// </summary>
public async Task<ArchiveSettings> GetSettingsAsync(Guid archiveId, CancellationToken cancellationToken = default)
{
var archive = await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false);
return TryReadManifest(archive) is { } manifest
? ArchiveSettings.Of(manifest)
: new ArchiveSettings(archive.Name, new LayoutTemplates { Folder = archive.FolderTemplate, File = archive.FileTemplate },
new ProxyPolicy { LongEdge = archive.ProxyLongEdge }, new ThumbnailPolicy());
}
/// <summary>
/// The settings in the archive's <c>archive.json</c>, with its index row brought up to them when another process
/// sharing the archive changed the file (a server's admin panel, another PC's Settings): imports and uploads take their
/// templates and proxy size from that row. Null while the file cannot be read (offline, damaged, newer, of another
/// archive): the row stays as it is, and only <see cref="GetSettingsAsync"/>'s stand-ins are known.
/// </summary>
public async Task<ArchiveSettings?> RefreshSettingsAsync(Guid archiveId, CancellationToken cancellationToken = default)
{
var archive = await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false);
if (TryReadManifest(archive) is not { } manifest) return null;
var settings = ArchiveSettings.Of(manifest);
if (!settings.IsRegisteredIn(archive))
{
// Read without the settings lease, as at open: an edit made meanwhile writes its own row, and the next refresh
// settles a file that changes again.
await RegisterAsync(new ArchivePaths(archive.RootPath), manifest, cancellationToken).ConfigureAwait(false);
Log.Info("archive", $"Settings of {archive.RootPath} changed elsewhere: {manifest.LayoutTemplates.Folder} · {manifest.LayoutTemplates.File}, proxies {manifest.ProxyPolicy.LongEdge}");
}
return settings;
}
/// <summary>
/// Changes an archive's settings in its <c>archive.json</c> (the source of truth, BRIEF §7), then in the index.
/// <paramref name="edit"/> receives the settings read from the file under the archive's settings lease, so a server and
/// a client sharing the archive never undo each other's change; the file is replaced atomically. Folders and files
/// already in the archive keep their names: templates and policies apply to the next imports, proxies and thumbnails.
/// A blank or overlong name in the file (archives made at a drive root, or before names were checked) is made usable
/// as <see cref="CreateAsync(string, ArchiveSettings, CancellationToken)"/> does, instead of failing every edit. Likewise
/// a template the file holds that breaks a rule of the archive's templates (saved before the rules existed) stays as it
/// is through an edit of anything else: only a template the edit gives is held to them (<see cref="ArchiveSettings.Problem"/>).
/// </summary>
/// <exception cref="ArgumentException">An edited setting is invalid (<see cref="ArgumentException.ParamName"/> names it;
/// <see cref="TemplateRuleException"/> for a template that breaks a rule).</exception>
/// <exception cref="ArchiveOfflineException">The archive is offline or read-only.</exception>
/// <exception cref="LeaseUnavailableException">Another process kept the archive's settings busy.</exception>
public async Task<Archive> UpdateSettingsAsync(Guid archiveId, Func<ArchiveSettings, ArchiveSettings> edit, CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(edit);
var archive = await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false);
var paths = new ArchivePaths(archive.RootPath);
ArchiveVolume.EnsureWritable(paths);
// The index row is written under the same lease as the file, so two edits cannot leave them in opposite orders.
using (await LeaseFile.AcquireAsync(paths.LocksDirectory, SettingsLease, _writer.Options.Owner, _writer.Options.LeaseWait, _writer.Options.LeaseDuration,
cancellationToken).ConfigureAwait(false))
{
var current = ManifestStore.ReadArchive(paths.ManifestPath);
if (current.Id != archive.Id) throw new InvalidDataException($"{paths.ManifestPath} belongs to archive {current.Id}, not {archive.Id}.");
// The name read is made usable before the edit sees it; a name the edit sets is checked as given.
var settings = edit(WithUsableName(ArchiveSettings.Of(current), paths));
// A template the file already holds stays as it is, rules or not: only one the edit gives is held to them.
settings.Validate(current.LayoutTemplates);
var manifest = current with
{
Name = settings.Name.Trim(),
LayoutTemplates = settings.Templates,
ProxyPolicy = settings.Proxies,
ThumbnailPolicy = settings.Thumbnails,
};
if (manifest != current) ManifestStore.WriteArchive(paths.ManifestPath, manifest);
Log.Info("archive", $"Settings of {paths.Root}: {manifest.LayoutTemplates.Folder} · {manifest.LayoutTemplates.File}, proxies {manifest.ProxyPolicy.LongEdge}, thumbnails {manifest.ThumbnailPolicy.LongEdge}");
return await RegisterAsync(paths, manifest, cancellationToken).ConfigureAwait(false);
}
}
public static ArchiveAvailability GetAvailability(Archive archive) => ArchiveVolume.Probe(new ArchivePaths(archive.RootPath));
/// <summary>Changes title, tags, rating and notes in the sidecar and the index together (settings version + 1).</summary>
public Task<Sequence> SetSequenceInfoAsync(Guid sequenceId, string? title, IReadOnlyList<string> tags, int rating, string? notes,
CancellationToken cancellationToken = default) =>
EditSequenceInfoAsync(sequenceId, _ => new SequenceInfo(title, tags, rating, notes), cancellationToken);
/// <summary>
/// Changes some of title, tags, rating and notes from their current values — read under the sequence's lease from
/// the sidecar, or from the index when it is ahead (an edit made there only) — so fields <paramref name="edit"/>
/// leaves alone keep any change made since the caller read the sequence. Sidecar and index change together
/// (settings version + 1), the index row in these fields only, at the settings version read under the lease
/// (<see cref="SequenceRepository.EditAsync(Guid, SequenceEdit, int?, CancellationToken)"/>): a settings edit committed
/// since the caller read the sequence (an analysis's Auto values, the server's PATCH, which takes no lease) stays, and
/// so do frames another process listed in the sidecar, which the next scan indexes
/// (<see cref="ArchiveIndexer.InStepAsync(Archive, SequencePaths, SequenceManifest, CancellationToken)"/>).
/// <paramref name="edit"/> runs again on top of an edit the API committed meanwhile.
/// </summary>
/// <exception cref="ArgumentException">The sequence is not in the index (or left it before the edit).</exception>
public async Task<Sequence> EditSequenceInfoAsync(Guid sequenceId, Func<SequenceInfo, SequenceInfo> edit, CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(edit);
var (archive, sequence) = await LoadSequenceAsync(sequenceId, cancellationToken).ConfigureAwait(false);
var paths = new ArchivePaths(archive.RootPath);
ArchiveVolume.EnsureWritable(paths);
await using (await _writer.LockAsync(paths, sequenceId, cancellationToken).ConfigureAwait(false))
{
var folder = await SequenceWriter.FolderAsync(_db, paths, sequence, cancellationToken).ConfigureAwait(false);
var manifest = SequenceWriter.ReadLocked(folder, sequenceId);
var inStep = await Indexer.InStepAsync(archive, folder, manifest, cancellationToken).ConfigureAwait(false);
for (var attempt = 1; ; attempt++)
{
var row = await _db.Sequences.GetAsync(sequenceId, cancellationToken).ConfigureAwait(false) ?? throw Unknown(sequenceId);
var current = row.SettingsVersion > manifest.Versions.Settings
? new SequenceInfo(row.Title, row.Tags, row.Rating, row.Notes)
: new SequenceInfo(manifest.Title, manifest.Tags, manifest.Rating, manifest.Notes);
var info = edit(current);
var title = string.IsNullOrWhiteSpace(info.Title) ? null : info.Title.Trim();
// The last attempt writes over whatever the index holds then rather than fail the user's edit.
var result = await _db.Sequences.EditAsync(sequenceId,
new SequenceEdit { Title = title ?? string.Empty, Tags = info.Tags, Rating = info.Rating, Notes = info.Notes ?? string.Empty },
attempt < InfoEditAttempts ? row.SettingsVersion : null, cancellationToken).ConfigureAwait(false);
// A conflict means the API changed the sequence after the read: the edit applies again on top of that.
if (result.Outcome == SequenceEditOutcome.Conflict) continue;
if (result.Sequence is not { } updated) throw Unknown(sequenceId);
// The sidecar takes the fields as the index stored them (trimmed, tags without duplicates).
ManifestStore.WriteSequence(folder.ManifestPath, manifest with
{
Title = updated.Title,
Tags = updated.Tags,
Rating = updated.Rating,
Notes = updated.Notes,
Versions = manifest.Versions with { Settings = System.Math.Max(manifest.Versions.Settings + 1, updated.SettingsVersion) },
UpdatedAt = DateTimeOffset.UtcNow,
});
if (inStep) await Indexer.RecordStampsAsync(archive, folder, sequenceId, cancellationToken).ConfigureAwait(false);
return updated;
}
}
}
/// <summary>
/// Runs <paramref name="write"/> under the lease of <paramref name="sequence"/>, with its index row read under it (null
/// when the sequence left the index). A Reorganize moves a folder, its row and the paths of the renders inside it under
/// that lease, so a writer that files into the folder and records what it filed (a render a client or render node sends)
/// does both where the sequence is then, never in a folder it left, and what it records follows a later move.
/// </summary>
/// <exception cref="ArgumentException">The sequence's archive is not in the index.</exception>
/// <exception cref="ArchiveOfflineException">The archive is offline or read-only.</exception>
/// <exception cref="LeaseUnavailableException">Another writer held the sequence for longer than the lease wait.</exception>
public async Task<T> UnderLeaseAsync<T>(Sequence sequence, Func<Sequence?, Task<T>> write, CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(sequence);
ArgumentNullException.ThrowIfNull(write);
var paths = new ArchivePaths((await LoadArchiveAsync(sequence.ArchiveId, cancellationToken).ConfigureAwait(false)).RootPath);
ArchiveVolume.EnsureWritable(paths);
await using (await _writer.LockAsync(paths, sequence.Id, cancellationToken).ConfigureAwait(false))
return await write(await _db.Sequences.GetAsync(sequence.Id, cancellationToken).ConfigureAwait(false)).ConfigureAwait(false);
}
public Task<IReadOnlyList<DuplicateGroup>> FindDuplicatesAsync(Guid archiveId, CancellationToken cancellationToken = default) =>
Maintenance.FindDuplicatesAsync(archiveId, cancellationToken);
public async Task<OrphanReport> FindOrphansAsync(Guid archiveId, CancellationToken cancellationToken = default) =>
await Maintenance.FindOrphansAsync(await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false), cancellationToken).ConfigureAwait(false);
/// <summary>
/// Orphans fix: index the unlisted photos of a sequence and flag its missing files. Photos added, gone or back clear
/// what covered the frames, as a scan's reconcile does (<see cref="ArchiveIndexer.ReconcileAsync"/>), and what a scan's
/// follow-ups would make again is queued on <paramref name="followUps"/> (null: nothing): the light analysis, a
/// background deep analysis when <paramref name="deepAnalysis"/> asks (as <see cref="ScanParameters.DeepAnalysis"/>
/// does for a scan) and, on a server (<see cref="ArchiveServiceOptions.ImagesAfterScan"/>), the thumbnails and proxies.
/// A kind the engine does not run, or one a queued job of that kind already covers for the sequence, is left out.
/// </summary>
public async Task ReconcileAsync(Guid sequenceId, JobEngine? followUps, bool deepAnalysis, CancellationToken cancellationToken = default)
{
var (archive, sequence) = await LoadSequenceAsync(sequenceId, cancellationToken).ConfigureAwait(false);
if (!await Indexer.ReconcileAsync(archive, sequence, cancellationToken).ConfigureAwait(false) || followUps is null) return;
List<ArchiveJobRequest> requests = [ProcessingJobs.LightAnalysis([sequenceId], sequence.DisplayTitle)];
// BRIEF §10.2: background, low priority.
if (deepAnalysis) requests.Add(ProcessingJobs.DeepAnalysis([sequenceId], sequence.DisplayTitle) with { Priority = JobPriority.Background });
if (_writer.Options.ImagesAfterScan)
{
requests.Add(ArchiveJobs.Thumbnails([sequenceId], sequence.DisplayTitle));
// An archive whose policy makes no proxies would get a pass that does nothing.
if (archive.ProxyLongEdge != ProxyPolicy.Disabled) requests.Add(ArchiveJobs.Proxies([sequenceId], sequence.DisplayTitle));
}
foreach (var request in requests)
{
if (!followUps.Runs(request.Kind)) continue;
// A queued job runs after the fix, on the frames as they are then, whatever else it targets (a scan's follow-ups).
var queued = await _db.Jobs.ListQueuedAsync(request.Kind, 1000, cancellationToken).ConfigureAwait(false);
if (queued.Any(j => j.TargetIds.Contains(sequenceId))) continue;
await followUps.EnqueueAsync(request, cancellationToken: cancellationToken).ConfigureAwait(false);
}
}
/// <summary>Orphans fix: drop index rows whose sidecar is gone.</summary>
public async Task<int> RemoveMissingSequencesAsync(Guid archiveId, IReadOnlyList<Guid> sequenceIds, CancellationToken cancellationToken = default) =>
await Maintenance.RemoveMissingSequencesAsync(await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false), sequenceIds, cancellationToken)
.ConfigureAwait(false);
/// <summary>Dry run of a mass rename.</summary>
public async Task<RenamePlan> PlanRenameAsync(Guid archiveId, IReadOnlyList<Guid> sequenceIds, string? folderTemplate, string? titleTemplate,
CancellationToken cancellationToken = default) =>
await Renamer.PlanAsync(await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false), sequenceIds, folderTemplate, titleTemplate,
cancellationToken).ConfigureAwait(false);
/// <summary>
/// The dry run of a Reorganize (owner review 2, R7): <paramref name="templates"/> over <paramref name="sequenceIds"/>, or
/// over every sequence of the archive (by folder) when null. Apply it in a job (<see cref="ArchiveJobs.Reorganize"/>) or
/// with <see cref="ApplyRenameAsync"/>.
/// </summary>
/// <exception cref="ArgumentException">The archive is unknown, or a sequence is not in it.</exception>
/// <exception cref="NestedRenameException">A new folder would lie inside a sequence's folder.</exception>
public async Task<RenamePlan> PlanReorganizeAsync(Guid archiveId, IReadOnlyList<Guid>? sequenceIds, RenameTemplates templates,
CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(templates);
var archive = await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false);
var ids = sequenceIds ?? [.. (await _db.Sequences.ListLocationsAsync(archive.Id, cancellationToken).ConfigureAwait(false)).Select(l => l.Id)];
return await Renamer.PlanAsync(archive, ids, templates, cancellationToken).ConfigureAwait(false);
}
/// <summary>
/// The dry run of a mass conversion (owner review 2, R7): <paramref name="sequenceIds"/>, or every sequence of the
/// archive (by folder) when null, converted with <paramref name="options"/> in <paramref name="mode"/>. Apply it in a job
/// (<see cref="ArchiveJobs.Convert"/>).
/// </summary>
/// <exception cref="ArgumentException">The archive is unknown, the options are invalid, or a sequence is not in the archive.</exception>
public async Task<ConvertPlan> PlanConvertAsync(Guid archiveId, IReadOnlyList<Guid>? sequenceIds, ConvertOptions options, ConvertMode mode,
CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(options);
var archive = await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false);
var ids = sequenceIds ?? [.. (await _db.Sequences.ListLocationsAsync(archive.Id, cancellationToken).ConfigureAwait(false)).Select(l => l.Id)];
return await Converter.PlanAsync(archive, ids, options, mode, cancellationToken).ConfigureAwait(false);
}
public async Task<RenameResult> ApplyRenameAsync(RenamePlan plan, IProgress<int>? progress = null, CancellationToken cancellationToken = default) =>
await Renamer.ApplyAsync(await LoadArchiveAsync(plan.ArchiveId, cancellationToken).ConfigureAwait(false), plan, progress, cancellationToken)
.ConfigureAwait(false);
/// <summary>Dry run of moving sequences to their archive's trash; <paramref name="progress"/> counts the sequences checked.</summary>
public Task<DeletePlan> PlanDeleteAsync(IReadOnlyList<Guid> sequenceIds, IProgress<int>? progress = null, CancellationToken cancellationToken = default) =>
Trash.PlanAsync(sequenceIds, progress, cancellationToken);
/// <summary>Moves exactly the planned sequences to the trash; returns the trash entries made.</summary>
public Task<IReadOnlyList<TrashEntry>> DeleteAsync(DeletePlan plan, string? deletedBy = null, IProgress<int>? progress = null,
CancellationToken cancellationToken = default) =>
Trash.DeleteAsync(plan, deletedBy, progress, cancellationToken);
/// <summary>The entries of an archive's trash, newest first: deleted sequences and photos deleted from sequences (<see cref="SequenceTrash.ListAsync"/>).</summary>
public async Task<IReadOnlyList<TrashEntry>> ListTrashAsync(Guid archiveId, CancellationToken cancellationToken = default) =>
await Trash.ListAsync(await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false), cancellationToken).ConfigureAwait(false);
/// <summary>Moves a sequence back from the trash and indexes it again (an entry of deleted photos: see <see cref="RestoreEntryAsync"/>).</summary>
public async Task<Sequence> RestoreAsync(Guid archiveId, string entryName, CancellationToken cancellationToken = default) =>
(await RestoreEntryAsync(archiveId, entryName, null, cancellationToken).ConfigureAwait(false)).Sequence;
/// <summary>
/// Brings a trash entry back: a sequence into its folder (<see cref="SequenceTrash.RestoreAsync"/>), or photos into
/// their sequence (<see cref="Archiving.FrameTrash.RestoreAsync"/>, which queues on <paramref name="followUps"/> what the
/// frames need again).
/// </summary>
/// <exception cref="DirectoryNotFoundException">The entry is not in the trash.</exception>
/// <exception cref="SequenceInLibraryException">A sequence entry whose sequence is in the index already.</exception>
/// <exception cref="TrashMismatchException">No file of a photo entry matches its record; nothing moved.</exception>
/// <exception cref="InvalidDataException">A sidecar is damaged or another sequence's (the trashed folder's own, or that of
/// the sequence the photos go back into); nothing moved.</exception>
public async Task<TrashRestoreResult> RestoreEntryAsync(Guid archiveId, string entryName, JobEngine? followUps = null,
CancellationToken cancellationToken = default)
{
var archive = await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false);
if (!Archiving.FrameTrash.IsPhotoEntry(entryName))
return new TrashRestoreResult(TrashKind.Sequence, await Trash.RestoreAsync(archive, entryName, cancellationToken).ConfigureAwait(false), 0, [], false);
var photos = await FrameTrash.RestoreAsync(archive, entryName, followUps, cancellationToken).ConfigureAwait(false);
return new TrashRestoreResult(photos.Kind, photos.Sequence, photos.Restored, photos.Kept, photos.NewSequence);
}
/// <summary>The dry run of emptying an archive's trash: <paramref name="names"/> of the entries (null: all), measured, with the plan's fingerprint.</summary>
public async Task<TrashEmptyPlan> PlanEmptyTrashAsync(Guid archiveId, IReadOnlyList<string>? names = null, CancellationToken cancellationToken = default) =>
await Trash.PlanEmptyAsync(await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false), names, cancellationToken).ConfigureAwait(false);
/// <summary>Plans a card or folder import into an archive (nothing is copied).</summary>
public async Task<ImportPlan> PlanImportAsync(Guid archiveId, string sourceRoot, ImportOptions options, Guid? cardId = null, IProgress<int>? progress = null,
CancellationToken cancellationToken = default) =>
await Imports.PlanAsync(await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false), sourceRoot, options, cardId, progress,
cancellationToken).ConfigureAwait(false);
/// <summary>Dry run of "delete imported" for a card; pass the plan to <see cref="CardEraser.Execute"/> after the user confirms.</summary>
public async Task<ErasePlan> PlanCardEraseAsync(Guid archiveId, Guid cardId, string sourceRoot, IProgress<int>? progress = null,
CancellationToken cancellationToken = default) =>
await Imports.PlanEraseAsync(await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false), cardId, sourceRoot, progress,
cancellationToken).ConfigureAwait(false);
/// <summary>
/// <paramref name="settings"/> with a name an archive can keep: a blank one becomes the folder's name (the root itself
/// for a drive root), one longer than <see cref="ArchiveSettings.MaxNameLength"/> is shortened.
/// </summary>
private static ArchiveSettings WithUsableName(ArchiveSettings settings, ArchivePaths paths)
{
var name = string.IsNullOrWhiteSpace(settings.Name) ? Path.GetFileName(paths.Root) is { Length: > 0 } folder ? folder : paths.Root : settings.Name.Trim();
return settings with { Name = name.Length > ArchiveSettings.MaxNameLength ? name[..ArchiveSettings.MaxNameLength] : name };
}
private async Task<Archive> RegisterAsync(ArchivePaths paths, ArchiveManifest manifest, CancellationToken cancellationToken)
{
var archive = new Archive
{
Id = manifest.Id,
Name = manifest.Name,
RootPath = paths.Root,
FolderTemplate = manifest.LayoutTemplates.Folder,
FileTemplate = manifest.LayoutTemplates.File,
SchemaVersion = manifest.SchemaVersion,
Created = manifest.Created,
ProxyLongEdge = manifest.ProxyPolicy.LongEdge,
};
await _db.Archives.UpsertAsync(archive, cancellationToken).ConfigureAwait(false);
return archive;
}
/// <summary>
/// The archive's <c>archive.json</c>; null (logged) while it cannot be read, when a newer Chronos wrote it (this one
/// would drop what it does not know) or when it belongs to another archive.
/// </summary>
private static ArchiveManifest? TryReadManifest(Archive archive)
{
var paths = new ArchivePaths(archive.RootPath);
try
{
if (!File.Exists(paths.ManifestPath)) return null;
var manifest = ManifestStore.ReadArchive(paths.ManifestPath);
if (manifest.SchemaVersion > ArchiveManifest.CurrentSchemaVersion)
Log.Warning("archive", $"{paths.ManifestPath} has schema version {manifest.SchemaVersion}, newer than this Chronos's; the index's settings are used");
else if (manifest.Id == archive.Id) return manifest;
else Log.Warning("archive", $"{paths.ManifestPath} belongs to archive {manifest.Id}, not {archive.Id}; the index's settings are used");
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or InvalidDataException)
{
Log.Warning("archive", $"The settings of {paths.Root} cannot be read; the index's are used", ex);
}
return null;
}
private async Task<Archive> LoadArchiveAsync(Guid archiveId, CancellationToken cancellationToken) =>
await _db.Archives.GetAsync(archiveId, cancellationToken).ConfigureAwait(false) ?? throw new ArgumentException($"Unknown archive {archiveId}.", nameof(archiveId));
private async Task<(Archive, Sequence)> LoadSequenceAsync(Guid sequenceId, CancellationToken cancellationToken)
{
var sequence = await _db.Sequences.GetAsync(sequenceId, cancellationToken).ConfigureAwait(false) ?? throw Unknown(sequenceId);
return (await LoadArchiveAsync(sequence.ArchiveId, cancellationToken).ConfigureAwait(false), sequence);
}
private static ArgumentException Unknown(Guid sequenceId) => new($"Unknown sequence {sequenceId}.", nameof(sequenceId));
}
/// <summary>
/// What a restore from the trash did: the kind of entry, the sequence restored (or the one the photos went back into),
/// and for photos how many came back, the photos kept in the trash (each with why) and whether they went into a new sequence.
/// </summary>
public sealed record TrashRestoreResult(TrashKind Kind, Sequence Sequence, int Photos, IReadOnlyList<KeptPhoto> Kept, bool NewSequence);
/// <summary>The fields of a sequence the user describes it with (sidecar and index).</summary>
public sealed record SequenceInfo(string? Title, IReadOnlyList<string> Tags, int Rating, string? Notes);
/// <summary>
/// The settings an archive keeps in <c>archive.json</c> (BRIEF §7, §8.5): its name, the naming templates of new imports
/// and the policies of the proxies and thumbnails built from now on.
/// </summary>
public sealed record ArchiveSettings(string Name, LayoutTemplates Templates, ProxyPolicy Proxies, ThumbnailPolicy Thumbnails)
{
public const int MaxNameLength = 100;
public static ArchiveSettings Of(ArchiveManifest manifest) => new(manifest.Name, manifest.LayoutTemplates, manifest.ProxyPolicy, manifest.ThumbnailPolicy);
/// <summary>Whether the index row <paramref name="archive"/> holds these settings (all it keeps: not the thumbnail policy).</summary>
public bool IsRegisteredIn(Archive archive)
{
ArgumentNullException.ThrowIfNull(archive);
return Name == archive.Name && Templates.Folder == archive.FolderTemplate && Templates.File == archive.FileTemplate
&& Proxies.LongEdge == archive.ProxyLongEdge;
}
/// <summary>
/// The first invalid field by its API name (<c>name</c>, <c>folderTemplate</c>, <c>fileTemplate</c>,
/// <c>proxyLongEdge</c>, <c>thumbnailLongEdge</c>); null when every field is valid. A template has to be usable
/// (<see cref="RenameTemplates.Check"/>), and one given anew is held to the rules it meets wherever it is typed
/// (<see cref="TemplateRules"/>): a folder template may not write a level scans never enter, and a file template must
/// keep the photo's extension, tell a session's photos apart and hold no slash.
/// </summary>
/// <param name="stored">The templates archive.json holds before an edit: one the edit leaves as it is, saved before the
/// rules existed (0.1.0-rc.5 and earlier), never fails an edit of another setting. Null holds both to every rule (a new
/// archive).</param>
public string? Problem(LayoutTemplates? stored = null)
{
if (string.IsNullOrWhiteSpace(Name) || Name.Trim().Length > MaxNameLength) return "name";
if (CheckTemplates(stored) is { } template) return template.Field;
if (!ProxyPolicy.IsValidLongEdge(Proxies.LongEdge) || Proxies.Quality is < 1 or > 100) return "proxyLongEdge";
if (!ThumbnailPolicy.IsValidLongEdge(Thumbnails.LongEdge) || Thumbnails.Quality is < 1 or > 100) return "thumbnailLongEdge";
return null;
}
/// <summary>
/// The first template that cannot be used (<see cref="Problem"/>), with the rule it breaks
/// (<see cref="TemplateProblem.Rule"/>); null when both can. A rule broken by a template <paramref name="stored"/>
/// already holds does not count.
/// </summary>
public TemplateProblem? CheckTemplates(LayoutTemplates? stored = null)
{
if (string.IsNullOrWhiteSpace(Templates.Folder)) return new TemplateProblem("folderTemplate", null);
if (string.IsNullOrWhiteSpace(Templates.File)) return new TemplateProblem("fileTemplate", null);
static TemplateProblem? Given(RenameTemplates template, bool kept) => template.Check() is { } problem && (problem.Rule is null || !kept) ? problem : null;
return Given(new RenameTemplates(Folder: Templates.Folder), Templates.Folder == stored?.Folder)
?? Given(new RenameTemplates(File: Templates.File), Templates.File == stored?.File);
}
/// <summary>Refuses these settings when a field is invalid (<see cref="Problem"/>).</summary>
/// <exception cref="TemplateRuleException">A template breaks a rule of the archive's templates.</exception>
/// <exception cref="ArgumentException">Another field is invalid (<see cref="ArgumentException.ParamName"/> names it).</exception>
internal void Validate(LayoutTemplates? stored = null)
{
if (Problem(stored) is not { } field) return;
if (CheckTemplates(stored) is { Rule: { } rule } template && template.Field == field) throw new TemplateRuleException(field, rule);
throw new ArgumentException($"The archive setting {field} is invalid.", field);
}
}
/// <summary>
/// An archive setting's template breaks a rule of the archive's templates (<see cref="TemplateRules"/>): the message says
/// which in one sentence (<c>Errors.Template.&lt;Rule&gt;</c>, in the language of the moment it was refused), and
/// <see cref="ParamName"/> names the template by its API name (<c>folderTemplate</c>, <c>fileTemplate</c>).
/// </summary>
public sealed class TemplateRuleException(string field, string rule) : ArgumentException(Loc.L("Errors.Template." + rule))
{
// Not the base's: its message would end in "(Parameter '…')".
public override string? ParamName { get; } = field;
/// <summary>The rule broken (<see cref="TemplateProblem.Rule"/>).</summary>
public string Rule { get; } = rule;
}
/// <summary>Builds the archive jobs; enqueue with <see cref="EnqueueAsync"/>.</summary>
public static class ArchiveJobs
{
/// <param name="deepAnalysis">Also queue a background deep analysis of the sequences the scan indexes (see <see cref="ScanParameters"/>).</param>
public static ArchiveJobRequest Scan(Archive archive, bool full = false, bool deepAnalysis = false) =>
new(JobKind.Scan, [archive.Id], archive.Name, Json(new ScanParameters(full, deepAnalysis), ArchiveJobJson.Default.ScanParameters), JobPriority.User);
public static ArchiveJobRequest Rebuild(Archive archive) => new(JobKind.Rebuild, [archive.Id], archive.Name, null, JobPriority.User);
public static ArchiveJobRequest Verify(Archive archive, IReadOnlyList<Guid>? sequenceIds = null) =>
new(JobKind.Verify, [archive.Id], archive.Name, Json(new VerifyParameters(sequenceIds), ArchiveJobJson.Default.VerifyParameters), JobPriority.User);
public static ArchiveJobRequest Import(Archive archive, ImportPlan plan, Guid? cardId, bool verify = true, Guid? userId = null) =>
new(JobKind.Import, [archive.Id], archive.Name,
Json(new ImportJobParameters(archive.Id, plan, cardId, verify, userId), ArchiveJobJson.Default.ImportJobParameters), JobPriority.User);
public static ArchiveJobRequest Thumbnails(IReadOnlyList<Guid> sequenceIds, string? label = null, bool force = false) =>
new(JobKind.Thumbs, sequenceIds, label, Json(new ImageJobParameters(force), ArchiveJobJson.Default.ImageJobParameters), JobPriority.Background);
public static ArchiveJobRequest Proxies(IReadOnlyList<Guid> sequenceIds, string? label = null, bool force = false) =>
new(JobKind.Proxies, sequenceIds, label, Json(new ImageJobParameters(force), ArchiveJobJson.Default.ImageJobParameters), JobPriority.Background);
public static ArchiveJobRequest Maintenance(Archive archive, bool dryRun = false) =>
new(JobKind.Maintenance, [archive.Id], archive.Name, Json(new MaintenanceParameters(dryRun), ArchiveJobJson.Default.MaintenanceParameters),
JobPriority.Normal);
/// <summary><see cref="JobKind.Duplicates"/>: a read-only report of the archive's duplicate photos into the job log.</summary>
public static ArchiveJobRequest Duplicates(Archive archive) => new(JobKind.Duplicates, [archive.Id], archive.Name, null, JobPriority.Normal);
/// <summary><see cref="JobKind.Orphans"/>: a read-only report of where the index and the disk disagree into the job log.</summary>
public static ArchiveJobRequest Orphans(Archive archive) => new(JobKind.Orphans, [archive.Id], archive.Name, null, JobPriority.Normal);
/// <summary><see cref="JobKind.Backup"/>: a copy of the SQLite index into the backups folder, keeping the newest <paramref name="keep"/>.</summary>
public static ArchiveJobRequest Backup(int keep = DatabaseBackups.Keep) =>
new(JobKind.Backup, [], null, Json(new BackupParameters(keep), ArchiveJobJson.Default.BackupParameters), JobPriority.Normal);
/// <summary>
/// <see cref="JobKind.Cleanup"/>: the clean-up <paramref name="steps"/> (by name, in order) with their age limit; the
/// archive, when given, is what archive steps (the trash report) look at.
/// </summary>
public static ArchiveJobRequest Cleanup(Archive? archive, IReadOnlyList<string> steps, int olderThanDays) =>
new(JobKind.Cleanup, archive is null ? [] : [archive.Id], archive?.Name,
Json(new CleanupParameters(steps, olderThanDays), ArchiveJobJson.Default.CleanupParameters), JobPriority.Normal);
/// <summary>
/// <see cref="JobKind.EmptyTrash"/>: erases exactly the entries of a confirmed <paramref name="plan"/>, refused when the
/// trash no longer matches its fingerprint (owner review 2, R6).
/// </summary>
public static ArchiveJobRequest EmptyTrash(Archive archive, TrashEmptyPlan plan)
{
ArgumentNullException.ThrowIfNull(archive);
ArgumentNullException.ThrowIfNull(plan);
var items = plan.Entries.OrderBy(e => e.Name, StringComparer.Ordinal).Select(e => new EmptyTrashItem(e.Name, SequenceTrash.EntryFingerprint(e))).ToList();
return new(JobKind.EmptyTrash, [archive.Id], archive.Name, Json(new EmptyTrashParameters(items, plan.Fingerprint), ArchiveJobJson.Default.EmptyTrashParameters),
JobPriority.User);
}
/// <summary>
/// <see cref="JobKind.Move"/>: applies the Reorganize <paramref name="plan"/> (the dry run of <paramref name="templates"/>,
/// <see cref="ArchiveService.PlanReorganizeAsync"/>) as confirmed, refused when the archive changed since
/// (<see cref="MoveJobParameters"/>; owner review 2, R7).
/// </summary>
public static ArchiveJobRequest Reorganize(Archive archive, RenamePlan plan, RenameTemplates templates)
{
ArgumentNullException.ThrowIfNull(archive);
ArgumentNullException.ThrowIfNull(plan);
ArgumentNullException.ThrowIfNull(templates);
// The sequences that have a step, in the order the plan was made for: the others change nothing, now or when planned again.
var steps = plan.Steps.Select(s => s.SequenceId).ToHashSet();
var sequences = plan.Subjects.Where(steps.Contains).Select(id => new MoveSequence(id)).ToList();
return new(JobKind.Move, [archive.Id], archive.Name,
Json(new MoveJobParameters(templates.Folder, templates.File, templates.Title, sequences, plan.Fingerprint()), ArchiveJobJson.Default.MoveJobParameters),
JobPriority.User);
}
/// <summary>
/// <see cref="JobKind.Convert"/>: applies the conversion <paramref name="plan"/> (<see cref="ArchiveService.PlanConvertAsync"/>)
/// as confirmed (owner review 2, R7): the sequences it converts, in its order with their frames versions and the digest
/// of the photos each converts (<see cref="ConvertSequencePlan.Digest"/>), are the job's targets, so jobs that would touch
/// them wait. The request names the job's id, under which <see cref="MassConverter.QueueAsync"/> (the way to queue it,
/// which refuses a second conversion of the same sequences) writes which photos those are beside the job's journal
/// (<see cref="ConfirmedPhotos"/>). The job converts those photos alone, and leaves as it is and reports a sequence where
/// one of them no longer holds the content confirmed when the job comes to it.
/// </summary>
/// <exception cref="ArgumentException">The plan converts nothing.</exception>
public static ArchiveJobRequest Convert(Archive archive, ConvertPlan plan)
{
ArgumentNullException.ThrowIfNull(archive);
ArgumentNullException.ThrowIfNull(plan);
var sequences = plan.Converted.Select(s => new ConvertSequence(s.SequenceId, s.FramesVersion, s.Digest())).ToList();
if (sequences.Count == 0) throw new ArgumentException("The plan converts nothing.", nameof(plan));
var label = sequences.Count == 1 ? plan.Converted.First().Title : archive.Name;
return new(JobKind.Convert, [.. sequences.Select(s => s.Id)], label,
Json(new ConvertJobParameters(archive.Id, plan.Options.Target, plan.Options.Quality, plan.Mode, sequences, plan.Fingerprint()),
ArchiveJobJson.Default.ConvertJobParameters), JobPriority.User, Guid.CreateVersion7());
}
/// <summary>Queues <paramref name="request"/>, under its own id when it names one (<see cref="ArchiveJobRequest.Id"/>).</summary>
public static Task<Job> EnqueueAsync(this JobEngine engine, ArchiveJobRequest request, Guid? createdBy = null, CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(engine);
ArgumentNullException.ThrowIfNull(request);
return request.Id is { } id
? engine.EnqueueAsync(id, request.Kind, request.Targets, request.Label, request.ParametersJson, request.Priority, createdBy, cancellationToken)
: engine.EnqueueAsync(request.Kind, request.Targets, request.Label, request.ParametersJson, request.Priority, createdBy, cancellationToken);
}
private static string Json<T>(T value, System.Text.Json.Serialization.Metadata.JsonTypeInfo<T> typeInfo) => JsonSerializer.Serialize(value, typeInfo);
}