Files
Chronos/src/Chronos.Data/Projects/ProjectSidecars.cs
T
Alby96andClaude Opus 5.5 d940fc7c61 fix(projects): sidecars stay the truth when they cannot be read, are missing or newer
A project record that could not be read once, or a missing .chronos/projects, marked
projects deleted for good and made a second Main; an index meeting Main with no mirror
state took its own stale settings column as an outside change and reverted the pushed
head; a newer-format or unreadable head made every project call fail or rewrote the
record's head over the real history. Now:

- Deletion is never inferred from absence or a read failure: an unreadable record holds
  its project back (listed as indexed, nothing written for it, no second Main), a row
  marked deleted is revived when its live record says so, and projects the archive has
  no folder for are written back from the index.
- Appends re-read the record under the lease and refuse when its head is not the
  index's; Main is only made when the sequence has none anywhere.
- An index with no mirror state decides from project.json and the record's new
  mirrored member (older records: the head's ancestry), never from its own column.
- A newer-format Main head is listed and pulled but never mirrored, merged or built on;
  pushes must parse strictly and fit the one 64 MB version limit (TooLarge otherwise).
- Duplicate version numbers and name/Main clashes are contained per project, so a scan
  or rebuild never stops.
- Delete moves the folder first, then writes the deleted record in the trash.
- The home's read-back for workspace pruning and Remove local copy reads the version
  files (IProjectHome.HoldsAsync), not the index.
- A read-only archive is read without writing: its projects open from the sidecars and
  a sequence with no Main gets one in the index only, written back once writable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 10:13:40 +01:00

307 lines
16 KiB
C#

using System.Globalization;
using System.Text;
using System.Text.Json;
using Chronos.Core.Archiving;
using Chronos.Core.IO;
using Chronos.Core.Model;
using Chronos.Core.Project;
namespace Chronos.Data.Projects;
/// <summary>The newest version of a project as its record names it: id and number.</summary>
public sealed record ProjectHead(Guid Id, int Number);
/// <summary>A version's file would be over <see cref="ProjectSidecars.MaxVersionBytes"/>, so it could never be read back: nothing was written.</summary>
public sealed class ProjectVersionTooLargeException(string message) : IOException(message);
/// <summary>
/// The record of a project in its folder (<c>.chronos/projects/&lt;id&gt;/project.json</c>): what the index row is rebuilt
/// from. <see cref="Deleted"/> is set when the project was deleted, once its folder is in the projects' trash.
/// </summary>
/// <param name="Mirrored">Main only: the version whose settings a mirror last wrote into the sequence's <c>project.json</c>
/// (any index of the archive). An index that meets Main for the first time compares <c>project.json</c> with it, never
/// with a copy of the settings it may have read long ago (<see cref="ProjectService"/>). Older records have none.</param>
public sealed record ProjectRecord(Guid Id, Guid SequenceId, string Name, bool IsMain, ProjectHead? Head, DateTimeOffset Created, string? CreatedBy,
DateTimeOffset Updated, DateTimeOffset? Deleted = null, ProjectHead? Mirrored = null)
{
/// <summary>The record of an index row, naming <paramref name="mirrored"/> as the version mirrored last (Main).</summary>
public static ProjectRecord Of(SequenceProject project, ProjectHead? mirrored = null)
{
ArgumentNullException.ThrowIfNull(project);
return new ProjectRecord(project.Id, project.SequenceId, project.Name, project.IsMain,
project.HeadVersionId is { } head ? new ProjectHead(head, project.HeadNumber) : null, project.CreatedAt, project.CreatedBy, project.UpdatedAt,
project.DeletedAt, project.IsMain ? mirrored : null);
}
/// <summary>The index row of this record (nothing mirrored known yet).</summary>
public SequenceProject ToProject() => new()
{
Id = Id,
SequenceId = SequenceId,
Name = Name,
IsMain = IsMain,
HeadVersionId = Head?.Id,
HeadNumber = Head?.Number ?? 0,
CreatedBy = CreatedBy,
CreatedAt = Created,
UpdatedAt = Updated,
DeletedAt = Deleted,
};
}
/// <summary>
/// The files of projects (owner review 2, R8), the same in an archive and in a workspace: the record of a project
/// (<see cref="ProjectRecord"/>) and one file per version, immutable once written:
/// <code>{ "format": "chronos-project-version", "formatVersion": 1, "id", "projectId", "parentId", "number", "kind",
/// "author", "clientName", "note", "settingsFormat", "framesVersion", "contentHash", "restoredFrom", "created",
/// "stored", "settings": "&lt;the portable settings as text&gt;" }</code>
/// The settings are a JSON string, so the bytes the content hash covers come back exactly; a version whose text does not
/// match its hash is refused as damaged. Writes are atomic (temp, flush, rename).
/// </summary>
public static class ProjectSidecars
{
public const string RecordFormat = "chronos-project-record";
public const string VersionFormat = "chronos-project-version";
public const int FormatVersion = 1;
/// <summary>
/// The one size limit of a version file, for writing and reading alike: a version that could not be read back is never
/// written (<see cref="WriteVersion"/>). A version is a few kilobytes; each photo it parks (an exclusion, the hero, a
/// keyframe waiting for its photo) takes about 340 bytes of the file, so this holds the positions of about 190,000
/// photos, well past the largest sequences.
/// </summary>
public const int MaxVersionBytes = 64 << 20;
private static readonly JsonWriterOptions Indented = new() { Indented = true };
/// <summary>Whether <paramref name="version"/> can be stored: its file within <see cref="MaxVersionBytes"/>.</summary>
public static bool Fits(ProjectVersion version) => Encoding.UTF8.GetByteCount(VersionJson(version)) <= MaxVersionBytes;
/// <summary>
/// Writes a version file. A version is immutable: an existing file is left when it holds the same version (same id
/// and content hash) and refused otherwise, unless <paramref name="replace"/> (a workspace's own copy of a version,
/// stored at its home since).
/// </summary>
/// <exception cref="IOException">Another version is at that path.</exception>
/// <exception cref="ProjectVersionTooLargeException">The file would be over <see cref="MaxVersionBytes"/>: nothing was written.</exception>
public static void WriteVersion(string path, ProjectVersion version, bool replace = false)
{
ArgumentNullException.ThrowIfNull(version);
var json = VersionJson(version);
var bytes = Encoding.UTF8.GetByteCount(json);
if (bytes > MaxVersionBytes)
throw new ProjectVersionTooLargeException($"Version {version.Number} of project {version.ProjectId} takes {bytes} bytes, over the {MaxVersionBytes} a version may.");
if (!replace && File.Exists(path))
{
ProjectVersion existing;
try
{
existing = ReadVersion(path);
}
catch (InvalidDataException)
{
// A damaged file is never overwritten: it is moved aside, kept.
File.Move(path, path + ".damaged-" + DateTime.UtcNow.ToString("yyyyMMddHHmmss", CultureInfo.InvariantCulture));
existing = null!;
}
if (existing is not null)
{
if (existing.Id == version.Id && string.Equals(existing.ContentHash, version.ContentHash, StringComparison.OrdinalIgnoreCase)) return;
throw new IOException($"{path} holds another version ({existing.Id}).");
}
}
Directory.CreateDirectory(Path.GetDirectoryName(path)!);
AtomicFile.WriteAllText(path, json);
}
/// <summary>Reads a version file and checks its content hash.</summary>
/// <exception cref="InvalidDataException">Not a version file, damaged, newer, over <see cref="MaxVersionBytes"/>, or its settings do not match their hash.</exception>
/// <exception cref="IOException">The file cannot be read.</exception>
public static ProjectVersion ReadVersion(string path)
{
if (new FileInfo(path).Length > MaxVersionBytes) throw new InvalidDataException($"{path} is too large to be a project version.");
return ParseVersion(AtomicFile.ReadAllText(path), path);
}
/// <summary>The text of a version file.</summary>
public static string VersionJson(ProjectVersion version)
{
ArgumentNullException.ThrowIfNull(version);
using var buffer = new MemoryStream();
using (var w = new Utf8JsonWriter(buffer, Indented))
{
w.WriteStartObject();
w.WriteString("format", VersionFormat);
w.WriteNumber("formatVersion", FormatVersion);
w.WriteString("id", version.Id);
w.WriteString("projectId", version.ProjectId);
if (version.ParentId is { } parent) w.WriteString("parentId", parent);
w.WriteNumber("number", version.Number);
w.WriteString("kind", ProjectVersionKinds.Name(version.Kind));
if (version.Author is { } author) w.WriteString("author", author);
if (version.ClientName is { } client) w.WriteString("clientName", client);
if (version.Note is { } note) w.WriteString("note", note);
w.WriteNumber("settingsFormat", version.SettingsFormat);
w.WriteNumber("framesVersion", version.FramesVersion);
w.WriteString("contentHash", version.ContentHash.ToLowerInvariant());
if (version.RestoredFrom is { } restored) w.WriteString("restoredFrom", restored);
w.WriteString("created", version.CreatedAt);
if (version.StoredAt is { } stored) w.WriteString("stored", stored);
w.WriteString("settings", version.SettingsJson);
w.WriteEndObject();
}
return Encoding.UTF8.GetString(buffer.GetBuffer(), 0, (int)buffer.Length);
}
/// <summary>Reads a version file's text (<paramref name="source"/> names it in errors) and checks its content hash.</summary>
/// <exception cref="InvalidDataException">Not a version file, damaged, newer, or its settings do not match their hash.</exception>
public static ProjectVersion ParseVersion(string json, string source)
{
using var document = Parse(json, source);
var root = document.RootElement;
Check(root, VersionFormat, source);
var settings = Text(root, "settings") ?? throw new InvalidDataException($"{source} holds no settings.");
var hash = Text(root, "contentHash") ?? throw new InvalidDataException($"{source} has no content hash.");
if (!ProjectContent.Verifies(settings, hash)) throw new InvalidDataException($"The settings in {source} do not match their content hash.");
return new ProjectVersion
{
Id = Id(root, "id") ?? throw new InvalidDataException($"{source} has no version id."),
ProjectId = Id(root, "projectId") ?? throw new InvalidDataException($"{source} names no project."),
ParentId = Id(root, "parentId"),
Number = Int(root, "number") is { } number and > 0 ? number : throw new InvalidDataException($"{source} has no version number."),
Kind = ProjectVersionKinds.Parse(Text(root, "kind")),
Author = Text(root, "author"),
ClientName = Text(root, "clientName"),
Note = Text(root, "note"),
SettingsJson = settings,
ContentHash = hash.ToLowerInvariant(),
SettingsFormat = Int(root, "settingsFormat") ?? ProjectContent.FormatOf(settings),
FramesVersion = Int(root, "framesVersion") ?? 0,
RestoredFrom = Id(root, "restoredFrom"),
CreatedAt = Time(root, "created") ?? default,
StoredAt = Time(root, "stored"),
};
}
/// <summary>Writes a project's record atomically.</summary>
public static void WriteRecord(string path, ProjectRecord record)
{
ArgumentNullException.ThrowIfNull(record);
using var buffer = new MemoryStream();
using (var w = new Utf8JsonWriter(buffer, Indented))
{
w.WriteStartObject();
w.WriteString("format", RecordFormat);
w.WriteNumber("formatVersion", FormatVersion);
w.WriteString("id", record.Id);
w.WriteString("sequenceId", record.SequenceId);
w.WriteString("name", record.Name);
w.WriteBoolean("isMain", record.IsMain);
if (record.Head is { } head)
{
w.WriteStartObject("head");
w.WriteString("id", head.Id);
w.WriteNumber("number", head.Number);
w.WriteEndObject();
}
w.WriteString("created", record.Created);
if (record.CreatedBy is { } by) w.WriteString("createdBy", by);
w.WriteString("updated", record.Updated);
if (record.Deleted is { } deleted) w.WriteString("deleted", deleted);
if (record.Mirrored is { } mirrored)
{
w.WriteStartObject("mirrored");
w.WriteString("id", mirrored.Id);
w.WriteNumber("number", mirrored.Number);
w.WriteEndObject();
}
w.WriteEndObject();
}
Directory.CreateDirectory(Path.GetDirectoryName(path)!);
AtomicFile.WriteAllBytes(path, buffer.GetBuffer().AsSpan(0, (int)buffer.Length));
}
/// <summary>Reads a project's record.</summary>
/// <exception cref="InvalidDataException">Not a project record, damaged or newer.</exception>
/// <exception cref="IOException">The file cannot be read.</exception>
public static ProjectRecord ReadRecord(string path)
{
using var document = Parse(AtomicFile.ReadAllText(path), path);
var root = document.RootElement;
Check(root, RecordFormat, path);
var name = Text(root, "name");
return new ProjectRecord(
Id(root, "id") ?? throw new InvalidDataException($"{path} has no project id."),
Id(root, "sequenceId") ?? throw new InvalidDataException($"{path} names no sequence."),
string.IsNullOrWhiteSpace(name) ? throw new InvalidDataException($"{path} has no name.") : name,
root.TryGetProperty("isMain", out var main) && main.ValueKind == JsonValueKind.True,
Head(root, "head"),
Time(root, "created") ?? default,
Text(root, "createdBy"),
Time(root, "updated") ?? Time(root, "created") ?? default,
Time(root, "deleted"),
Head(root, "mirrored"));
}
/// <summary>A version a record names (its head, the version mirrored): <c>{ "id", "number" }</c>; null when it names none.</summary>
private static ProjectHead? Head(JsonElement root, string name) =>
root.TryGetProperty(name, out var h) && h.ValueKind == JsonValueKind.Object && Id(h, "id") is { } id && Int(h, "number") is { } number and > 0
? new ProjectHead(id, number)
: null;
/// <summary>The version files of a folder by number and id (<c>000001-&lt;id&gt;.json</c>), in number order; other files are not listed.</summary>
public static IReadOnlyList<(int Number, Guid Id, string Path)> ListVersions(string directory)
{
if (!Directory.Exists(directory)) return [];
var found = new List<(int, Guid, string)>();
foreach (var path in Directory.EnumerateFiles(directory, "*.json"))
{
if (TryParseName(Path.GetFileName(path), out var number, out var id)) found.Add((number, id, path));
}
return [.. found.OrderBy(f => f.Item1).ThenBy(f => f.Item2)];
}
/// <summary>The number and id a version file name carries (<see cref="ArchiveLayout.ProjectVersionFileName"/>).</summary>
public static bool TryParseName(string fileName, out int number, out Guid id)
{
number = 0;
id = Guid.Empty;
var name = Path.GetFileNameWithoutExtension(fileName);
var dash = name.IndexOf('-', StringComparison.Ordinal);
return dash > 0 && Path.GetExtension(fileName).Equals(".json", StringComparison.OrdinalIgnoreCase)
&& int.TryParse(name.AsSpan(0, dash), NumberStyles.None, CultureInfo.InvariantCulture, out number) && number > 0
&& Guid.TryParseExact(name.AsSpan(dash + 1), "N", out id);
}
private static JsonDocument Parse(string json, string source)
{
try
{
return JsonDocument.Parse(json, new JsonDocumentOptions { MaxDepth = 64 });
}
catch (JsonException ex)
{
throw new InvalidDataException($"{source} is not valid JSON.", ex);
}
}
private static void Check(JsonElement root, string format, string source)
{
if (root.ValueKind != JsonValueKind.Object || Text(root, "format") != format) throw new InvalidDataException($"{source} is not a {format} file.");
if (Int(root, "formatVersion") is not { } version || version < 1) throw new InvalidDataException($"{source} has no valid format version.");
if (version > FormatVersion) throw new InvalidDataException($"{source} uses format {version}, newer than this Chronos ({FormatVersion}).");
}
private static string? Text(JsonElement element, string name) =>
element.TryGetProperty(name, out var value) && value.ValueKind == JsonValueKind.String ? value.GetString() : null;
private static int? Int(JsonElement element, string name) =>
element.TryGetProperty(name, out var value) && value.ValueKind == JsonValueKind.Number && value.TryGetInt32(out var number) ? number : null;
private static Guid? Id(JsonElement element, string name) =>
element.TryGetProperty(name, out var value) && value.ValueKind == JsonValueKind.String && value.TryGetGuid(out var id) && id != Guid.Empty ? id : null;
private static DateTimeOffset? Time(JsonElement element, string name) =>
element.TryGetProperty(name, out var value) && value.ValueKind == JsonValueKind.String && value.TryGetDateTimeOffset(out var time) ? time : null;
}