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;
///
/// 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 ).
///
public sealed class ArchiveService : IJobHandlerProvider
{
/// Lease serialising read-modify-write of archive.json between the processes sharing an archive.
private const string SettingsLease = "archive-settings";
/// Times a title, tags, rating or notes edit is applied at the version it read before it writes regardless.
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; }
/// Commits staged files into sequences (server uploads, client card imports).
public ArchiveIngest Ingest { get; }
public ArchiveVerifier Verifier { get; }
public ArchiveMaintenance Maintenance { get; }
public MassRenamer Renamer { get; }
public ArchiveImages Images { get; }
public ImportService Imports { get; }
/// Deletes sequences into the archive's trash and restores them; lists and empties the trash.
public SequenceTrash Trash { get; }
/// Deletes photos of a sequence into the archive's trash and restores them (owner review 2, R6).
public FrameTrash FrameTrash { get; }
/// Converts sequences to JPEG, TIFF-16 or linear DNG, replacing their frames or into new sequences (owner review 2, R7).
public MassConverter Converter { get; }
/// The projects of the sequences and their versions: this PC's archive as a project's home (owner review 2, R8).
public ProjectService Projects { get; }
/// The decoders of this engine's image passes (thumbnails, proxies).
public Core.Imaging.ImageDecoder Decoder => _writer.Options.Decoder;
/// How the host measures free space under a folder (); null: the folder's drive.
public Func? FreeSpace => _writer.Options.FreeSpace;
///
/// The steps this host's jobs can run: the shared ones (),
/// then the host's (). A schedule host lists their names.
///
public IReadOnlyList CleanupSteps { get; }
/// Where this engine's jobs put their copies (; null: next to the index).
public string? BackupDirectory => _writer.Options.BackupDirectory;
///
/// 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,
/// ) and mass conversion (R7, ); register them on the
/// .
///
public IReadOnlyList 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),
];
/// Makes a new, empty archive and indexes it.
/// The folder already is an archive (open it instead).
public Task 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);
///
/// Makes a new, empty archive with and indexes it. A blank name
/// becomes the folder's name; a longer one than is shortened.
///
/// The folder already is an archive (open it instead).
/// A template or policy is invalid ( names it;
/// for a template that breaks a rule).
public async Task 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);
}
///
/// 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 ); one that
/// cannot be completed yet is logged and waits for the next open. An offline archive is registered as it was last seen.
///
public async Task 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;
}
///
/// Opens a folder of photos as an archive in place (Welcome "adopt folder"): nothing is moved or renamed; enqueue
/// with a full pass to write sidecars and index it.
///
public Task 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);
}
///
/// for a folder that may become a new archive with
/// (templates and policies; the folder's name when its name is blank). An existing
/// archive keeps its own settings.
///
public Task 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);
}
///
/// The settings in the archive's archive.json; those of the index (with the default thumbnail policy, which only
/// the file keeps) while the file cannot be read.
///
public async Task 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());
}
///
/// The settings in the archive's archive.json, 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 's stand-ins are known.
///
public async Task 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;
}
///
/// Changes an archive's settings in its archive.json (the source of truth, BRIEF §7), then in the index.
/// 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 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 ().
///
/// An edited setting is invalid ( names it;
/// for a template that breaks a rule).
/// The archive is offline or read-only.
/// Another process kept the archive's settings busy.
public async Task UpdateSettingsAsync(Guid archiveId, Func 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));
/// Changes title, tags, rating and notes in the sidecar and the index together (settings version + 1).
public Task SetSequenceInfoAsync(Guid sequenceId, string? title, IReadOnlyList tags, int rating, string? notes,
CancellationToken cancellationToken = default) =>
EditSequenceInfoAsync(sequenceId, _ => new SequenceInfo(title, tags, rating, notes), cancellationToken);
///
/// 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
/// 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
/// (): 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
/// ().
/// runs again on top of an edit the API committed meanwhile.
///
/// The sequence is not in the index (or left it before the edit).
public async Task EditSequenceInfoAsync(Guid sequenceId, Func 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;
}
}
}
///
/// Runs under the lease of , 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.
///
/// The sequence's archive is not in the index.
/// The archive is offline or read-only.
/// Another writer held the sequence for longer than the lease wait.
public async Task UnderLeaseAsync(Sequence sequence, Func> 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> FindDuplicatesAsync(Guid archiveId, CancellationToken cancellationToken = default) =>
Maintenance.FindDuplicatesAsync(archiveId, cancellationToken);
public async Task FindOrphansAsync(Guid archiveId, CancellationToken cancellationToken = default) =>
await Maintenance.FindOrphansAsync(await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false), cancellationToken).ConfigureAwait(false);
///
/// 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 (), and what a scan's
/// follow-ups would make again is queued on (null: nothing): the light analysis, a
/// background deep analysis when asks (as
/// does for a scan) and, on a server (), 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.
///
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 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);
}
}
/// Orphans fix: drop index rows whose sidecar is gone.
public async Task RemoveMissingSequencesAsync(Guid archiveId, IReadOnlyList sequenceIds, CancellationToken cancellationToken = default) =>
await Maintenance.RemoveMissingSequencesAsync(await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false), sequenceIds, cancellationToken)
.ConfigureAwait(false);
/// Dry run of a mass rename.
public async Task PlanRenameAsync(Guid archiveId, IReadOnlyList sequenceIds, string? folderTemplate, string? titleTemplate,
CancellationToken cancellationToken = default) =>
await Renamer.PlanAsync(await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false), sequenceIds, folderTemplate, titleTemplate,
cancellationToken).ConfigureAwait(false);
///
/// The dry run of a Reorganize (owner review 2, R7): over , or
/// over every sequence of the archive (by folder) when null. Apply it in a job () or
/// with .
///
/// The archive is unknown, or a sequence is not in it.
/// A new folder would lie inside a sequence's folder.
public async Task PlanReorganizeAsync(Guid archiveId, IReadOnlyList? 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);
}
///
/// The dry run of a mass conversion (owner review 2, R7): , or every sequence of the
/// archive (by folder) when null, converted with in . Apply it in a job
/// ().
///
/// The archive is unknown, the options are invalid, or a sequence is not in the archive.
public async Task PlanConvertAsync(Guid archiveId, IReadOnlyList? 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 ApplyRenameAsync(RenamePlan plan, IProgress? progress = null, CancellationToken cancellationToken = default) =>
await Renamer.ApplyAsync(await LoadArchiveAsync(plan.ArchiveId, cancellationToken).ConfigureAwait(false), plan, progress, cancellationToken)
.ConfigureAwait(false);
/// Dry run of moving sequences to their archive's trash; counts the sequences checked.
public Task PlanDeleteAsync(IReadOnlyList sequenceIds, IProgress? progress = null, CancellationToken cancellationToken = default) =>
Trash.PlanAsync(sequenceIds, progress, cancellationToken);
/// Moves exactly the planned sequences to the trash; returns the trash entries made.
public Task> DeleteAsync(DeletePlan plan, string? deletedBy = null, IProgress? progress = null,
CancellationToken cancellationToken = default) =>
Trash.DeleteAsync(plan, deletedBy, progress, cancellationToken);
/// The entries of an archive's trash, newest first: deleted sequences and photos deleted from sequences ().
public async Task> ListTrashAsync(Guid archiveId, CancellationToken cancellationToken = default) =>
await Trash.ListAsync(await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false), cancellationToken).ConfigureAwait(false);
/// Moves a sequence back from the trash and indexes it again (an entry of deleted photos: see ).
public async Task RestoreAsync(Guid archiveId, string entryName, CancellationToken cancellationToken = default) =>
(await RestoreEntryAsync(archiveId, entryName, null, cancellationToken).ConfigureAwait(false)).Sequence;
///
/// Brings a trash entry back: a sequence into its folder (), or photos into
/// their sequence (, which queues on what the
/// frames need again).
///
/// The entry is not in the trash.
/// A sequence entry whose sequence is in the index already.
/// No file of a photo entry matches its record; nothing moved.
/// 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.
public async Task 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);
}
/// The dry run of emptying an archive's trash: of the entries (null: all), measured, with the plan's fingerprint.
public async Task PlanEmptyTrashAsync(Guid archiveId, IReadOnlyList? names = null, CancellationToken cancellationToken = default) =>
await Trash.PlanEmptyAsync(await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false), names, cancellationToken).ConfigureAwait(false);
/// Plans a card or folder import into an archive (nothing is copied).
public async Task PlanImportAsync(Guid archiveId, string sourceRoot, ImportOptions options, Guid? cardId = null, IProgress? progress = null,
CancellationToken cancellationToken = default) =>
await Imports.PlanAsync(await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false), sourceRoot, options, cardId, progress,
cancellationToken).ConfigureAwait(false);
/// Dry run of "delete imported" for a card; pass the plan to after the user confirms.
public async Task PlanCardEraseAsync(Guid archiveId, Guid cardId, string sourceRoot, IProgress? progress = null,
CancellationToken cancellationToken = default) =>
await Imports.PlanEraseAsync(await LoadArchiveAsync(archiveId, cancellationToken).ConfigureAwait(false), cardId, sourceRoot, progress,
cancellationToken).ConfigureAwait(false);
///
/// 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 is shortened.
///
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 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;
}
///
/// The archive's archive.json; 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.
///
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 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));
}
///
/// 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.
///
public sealed record TrashRestoreResult(TrashKind Kind, Sequence Sequence, int Photos, IReadOnlyList Kept, bool NewSequence);
/// The fields of a sequence the user describes it with (sidecar and index).
public sealed record SequenceInfo(string? Title, IReadOnlyList Tags, int Rating, string? Notes);
///
/// The settings an archive keeps in archive.json (BRIEF §7, §8.5): its name, the naming templates of new imports
/// and the policies of the proxies and thumbnails built from now on.
///
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);
/// Whether the index row holds these settings (all it keeps: not the thumbnail policy).
public bool IsRegisteredIn(Archive archive)
{
ArgumentNullException.ThrowIfNull(archive);
return Name == archive.Name && Templates.Folder == archive.FolderTemplate && Templates.File == archive.FileTemplate
&& Proxies.LongEdge == archive.ProxyLongEdge;
}
///
/// The first invalid field by its API name (name, folderTemplate, fileTemplate,
/// proxyLongEdge, thumbnailLongEdge); null when every field is valid. A template has to be usable
/// (), and one given anew is held to the rules it meets wherever it is typed
/// (): 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.
///
/// 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).
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;
}
///
/// The first template that cannot be used (), with the rule it breaks
/// (); null when both can. A rule broken by a template
/// already holds does not count.
///
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);
}
/// Refuses these settings when a field is invalid ().
/// A template breaks a rule of the archive's templates.
/// Another field is invalid ( names it).
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);
}
}
///
/// An archive setting's template breaks a rule of the archive's templates (): the message says
/// which in one sentence (Errors.Template.<Rule>, in the language of the moment it was refused), and
/// names the template by its API name (folderTemplate, fileTemplate).
///
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;
/// The rule broken ().
public string Rule { get; } = rule;
}
/// Builds the archive jobs; enqueue with .
public static class ArchiveJobs
{
/// Also queue a background deep analysis of the sequences the scan indexes (see ).
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? 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 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 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);
/// : a read-only report of the archive's duplicate photos into the job log.
public static ArchiveJobRequest Duplicates(Archive archive) => new(JobKind.Duplicates, [archive.Id], archive.Name, null, JobPriority.Normal);
/// : a read-only report of where the index and the disk disagree into the job log.
public static ArchiveJobRequest Orphans(Archive archive) => new(JobKind.Orphans, [archive.Id], archive.Name, null, JobPriority.Normal);
/// : a copy of the SQLite index into the backups folder, keeping the newest .
public static ArchiveJobRequest Backup(int keep = DatabaseBackups.Keep) =>
new(JobKind.Backup, [], null, Json(new BackupParameters(keep), ArchiveJobJson.Default.BackupParameters), JobPriority.Normal);
///
/// : the clean-up (by name, in order) with their age limit; the
/// archive, when given, is what archive steps (the trash report) look at.
///
public static ArchiveJobRequest Cleanup(Archive? archive, IReadOnlyList steps, int olderThanDays) =>
new(JobKind.Cleanup, archive is null ? [] : [archive.Id], archive?.Name,
Json(new CleanupParameters(steps, olderThanDays), ArchiveJobJson.Default.CleanupParameters), JobPriority.Normal);
///
/// : erases exactly the entries of a confirmed , refused when the
/// trash no longer matches its fingerprint (owner review 2, R6).
///
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);
}
///
/// : applies the Reorganize (the dry run of ,
/// ) as confirmed, refused when the archive changed since
/// (; owner review 2, R7).
///
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);
}
///
/// : applies the conversion ()
/// 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 (), are the job's targets, so jobs that would touch
/// them wait. The request names the job's id, under which (the way to queue it,
/// which refuses a second conversion of the same sequences) writes which photos those are beside the job's journal
/// (). 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.
///
/// The plan converts nothing.
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());
}
/// Queues , under its own id when it names one ().
public static Task 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 value, System.Text.Json.Serialization.Metadata.JsonTypeInfo typeInfo) => JsonSerializer.Serialize(value, typeInfo);
}