using System.Collections.Concurrent;
using Chronos.Core.Archiving;
using Chronos.Core.Imaging;
using Chronos.Core.Model;
namespace Chronos.Data.Archiving;
/// Settings shared by the archive services.
public sealed record ArchiveServiceOptions
{
/// Decoders for thumbnails and proxies beyond embedded previews and JPEG (WIC on Windows).
public ImageDecoder Decoder { get; init; } = new([]);
/// Name written into lease files so a waiting writer can say who holds a sequence.
public string Owner { get; init; } = "chronos@" + Environment.MachineName;
/// How long a writer waits for a sequence held by another process before giving up.
public TimeSpan LeaseWait { get; init; } = TimeSpan.FromMinutes(2);
public TimeSpan LeaseDuration { get; init; } = LeaseFile.DefaultDuration;
///
/// Scans queue thumbnails and proxies of the sequences they index without them, as an upload does (the server, whose
/// clients load both from it: BRIEF §4.3, §14.4). The desktop decodes its thumbnails on demand and makes proxies when
/// asked.
///
public bool ImagesAfterScan { get; init; }
///
/// Photos a pass works on at once, asked at the start of each sequence (owner review 1, R2: one job runs at a time and
/// the host's parallelism decides how many photos it processes at once; Settings › Rendering › Parallelism on the
/// desktop, CHRONOS_PARALLELISM on the server). Default: half the logical cores.
///
public Func Parallelism { get; init; } = () => DefaultParallelism;
///
/// Memory the photos a proxy pass decodes at once may take, in bytes, asked with : fewer at once
/// for large originals. Default: a quarter of the memory available, at least 1 GiB.
///
public Func MemoryBudget { get; init; } = () => DefaultMemoryBudget;
///
/// The host's own clean-up steps (the server's uploads sweep, the desktop's cache trim), run by
/// jobs after the shared ones of when a
/// schedule names them (owner review 2, R10). A name the shared steps use already is ignored.
///
public IReadOnlyList CleanupSteps { get; init; } = [];
///
/// Folder of the copies jobs make; null: the backups folder next to the
/// SQLite index (), where the desktop and the server keep them.
///
public string? BackupDirectory { get; init; }
///
/// Told after a Reorganize changed a sequence's folder, title or file names (change reorganized), once its step is
/// journaled, or once its folder moved and its index row followed when the step then failed: by its job, or by an archive
/// open that completed a plan an interruption left (). Told too after a conversion
/// replaced a sequence's frames (converted) or made a new sequence of them (created).
/// A server tells its connected clients (BRIEF §14.3); the service it opens its archive with at start sets none, as no
/// client is connected yet. The desktop reloads an editor open on the sequence. A failure is logged and never fails the job.
///
public Func? SequenceChanged { get; init; }
///
/// Told after a call of changed a sequence's projects (owner review 2, R8): a project
/// made, renamed or deleted, a new head (a push, settings another path wrote taken as Main's external version, a merge, the
/// versions another program sharing the archive wrote found in the sidecars), and whether the call wrote Main's head into
/// the sequence's settings. Told once per call, after the sequence's lease is let go. A server tells its connected clients
/// (BRIEF §14.3); a failure is logged and never fails the call.
///
public Func? ProjectsChanged { get; init; }
///
/// The free bytes a write under a folder of an archive (its root, its staging folder) may count on, as the host counts
/// them: a server takes the tighter of its space volume (owner review 2, R2) and the folder's own volume, the desktop asks
/// Windows, which measures a network share too; null: the folder's drive (). A conversion checks its
/// estimate against it before it starts, before each sequence and before each photo (R7). The function returns null when
/// the space cannot be measured.
///
public Func? FreeSpace { get; init; }
/// Half the logical cores, at least one: the parallelism when the host sets none.
public static int DefaultParallelism => Math.Max(1, Environment.ProcessorCount / 2);
/// A quarter of the memory available to this process, at least 1 GiB.
public static long DefaultMemoryBudget => Math.Max(1L << 30, GC.GetGCMemoryInfo().TotalAvailableMemoryBytes / 4);
}
///
/// Read-modify-write of sidecars, serialised per sequence: an in-process gate for this process's writers plus a lease
/// file for writers in other processes on the same share (server and client). Every edit sees the latest sidecar,
/// with an interrupted ingest batch completed first.
///
internal sealed class SequenceWriter(ArchiveServiceOptions options)
{
private readonly ConcurrentDictionary _gates = new();
public ArchiveServiceOptions Options => options;
/// Holds the sequence exclusively until disposed.
public Task LockAsync(ArchivePaths archive, Guid sequenceId, CancellationToken cancellationToken) =>
LockAsync(archive, sequenceId, null, cancellationToken);
///
/// Holds the sequence exclusively until disposed, waiting at most for this process's other writers
/// and for the lease (the options' lease wait when null).
///
/// Another writer kept the sequence for longer than the wait.
public async Task LockAsync(ArchivePaths archive, Guid sequenceId, TimeSpan? wait, CancellationToken cancellationToken)
{
var name = $"seq-{sequenceId:N}";
var gate = _gates.GetOrAdd(sequenceId, _ => new SemaphoreSlim(1, 1));
if (wait is { } limit)
{
if (!await gate.WaitAsync(limit, cancellationToken).ConfigureAwait(false)) throw new LeaseUnavailableException(name, null);
}
else
{
await gate.WaitAsync(cancellationToken).ConfigureAwait(false);
}
try
{
var lease = await LeaseFile.AcquireAsync(archive.LocksDirectory, name, options.Owner, wait ?? options.LeaseWait, options.LeaseDuration,
cancellationToken).ConfigureAwait(false);
return new Held(gate, lease);
}
catch
{
gate.Release();
throw;
}
}
///
/// Reads the sidecar of a locked sequence, completing an interrupted Reorganize of its files (),
/// undoing an interrupted photo deletion (), undoing or completing an interrupted frame
/// replacement (, a conversion or its undo), settling an interrupted restore from the
/// trash (; left for later while its trash entry is busy) and completing an interrupted
/// ingest batch first. A sidecar a rename recovery rewrites leaves the index behind it until the rename resumes or the
/// next scan reads it.
///
/// The trash entry lease the caller holds already (a restore of that entry), if any.
/// The sidecar in the folder belongs to another sequence.
public static SequenceManifest ReadLocked(SequencePaths sequence, Guid sequenceId, string? heldEntryLease = null)
{
var manifest = ManifestStore.ReadSequence(sequence.ManifestPath);
if (manifest.Id != sequenceId)
throw new InvalidDataException($"{sequence.ManifestPath} belongs to sequence {manifest.Id}, not {sequenceId}.");
if (File.Exists(sequence.FileRenameJournalPath))
{
if (FileRenameJournal.Recover(sequence, manifest) is { } renamed)
{
ManifestStore.WriteSequence(sequence.ManifestPath, renamed);
manifest = renamed;
}
FileRenameJournal.Delete(sequence);
}
FrameRemovalJournal.Recover(sequence, manifest);
FrameTrash.RecoverReplace(sequence, manifest, heldEntryLease);
FrameTrash.RecoverRestore(sequence, manifest, heldEntryLease);
if (IngestJournal.Recover(sequence, manifest) is { } recovered)
{
ManifestStore.WriteSequence(sequence.ManifestPath, recovered);
manifest = recovered;
}
IngestJournal.Delete(sequence);
return manifest;
}
///
/// The folder of a sequence whose lock the caller holds, as the index has it now. A Reorganize moves a folder and
/// updates its row under the sequence's lease (and its thumbnail lease), so a writer that read the row before taking
/// the lease writes where the sequence is, never into the folder it left, which the write would create again. The
/// folder of when the row is gone (reading its sidecar then fails as it did).
///
public static async Task FolderAsync(ChronosDatabase db, ArchivePaths archive, Sequence sequence, CancellationToken cancellationToken) =>
archive.Sequence((await db.Sequences.GetAsync(sequence.Id, cancellationToken).ConfigureAwait(false))?.Folder ?? sequence.Folder);
/// Applies to the sidecar under the lock; a null result writes nothing.
public async Task UpdateAsync(ArchivePaths archive, Guid sequenceId, string folder,
Func edit, CancellationToken cancellationToken)
{
var sequence = archive.Sequence(folder);
await using (await LockAsync(archive, sequenceId, cancellationToken).ConfigureAwait(false))
{
var manifest = ReadLocked(sequence, sequenceId);
if (edit(manifest) is not { } updated) return manifest;
ManifestStore.WriteSequence(sequence.ManifestPath, updated);
return updated;
}
}
private sealed class Held(SemaphoreSlim gate, LeaseFile lease) : IAsyncDisposable
{
public ValueTask DisposeAsync()
{
lease.Dispose();
gate.Release();
return ValueTask.CompletedTask;
}
}
}