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); }