feat(server): the server keeps its sequences' projects, pushed and pulled like a PC's archive

Owner review 2, phase 5b (R8): a server is a project home. A workspace can
list a sequence's projects, make, rename and delete them, read their
versions and push new ones through /api/v1/sequences/{sid}/projects. The
endpoints run on the archive's ProjectService exactly as a desktop's archive
does (sidecars first, then the index, under the sequence's lease), so no
version is stored apart and a desktop sharing the archive sees the same
projects.

- Protocol: project, version, create, rename, version page, push answer
  (outcome, stored version, head, plus code and message on 409/422) and
  home frames DTOs, the projectChanged event, the "projects" capability and
  the ChronosClient calls; a push returns its outcome without throwing on
  409 or 422. ProjectWire maps them to and from the model for both sides.
- Server: Read lists and reads, Edit makes, renames and pushes, Delete (the
  sequence's owner, the project's maker or an admin) deletes; refusals with
  stable codes, 503 while the sequence is busy, offline or moved; the
  pushing account becomes the version's author; creations, renames and
  deletions audited, pushes logged.
- ProjectService tells the host what each call changed, compared under the
  lease, so projectChanged also follows Main's external versions; a Main
  version mirrored into the settings sends sequenceChanged too, for older
  clients. ProjectCatchUp takes settings a PATCH, an analysis or a
  conversion wrote into Main at once, for sequences that have a Main.
- Renders of a project version: POST /jobs checks the project and version
  against the sequence and pins a project alone to its head; render nodes
  get the version's settings placed on the frames they claim; the render
  records the project and version.
- Admin panel: the sequence page lists its projects (Main marked, head,
  last change, versions on demand) with Rename and Delete for the others,
  live on projectChanged. It edits no settings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Alby96andClaude Opus 5.5 committed 2026-11-04 11:15:19 +01:00
1 parent 917cddde41
commit e2ecc409a3
30 files changed
+2261 -35

No files matched your search

@@ -472,6 +472,98 @@ public sealed class ChronosClient : IDisposable
public Task ReportNodeFailureAsync(Guid nodeId, Guid jobId, string error, CancellationToken ct = default) =>
SendAsync(HttpMethod.Post, $"api/v1/nodes/{nodeId}/jobs/{jobId}/failed", new NodeJobFailure(error), ProtocolJson.Default.NodeJobFailure, ct);
// ---------------- Projects (owner review 2, R8; servers with the "projects" capability) ----------------
/// <summary>The live projects of a server sequence, Main first (made from the sequence's settings the first time they are read).</summary>
public Task<List<ProjectDto>> ListProjectsAsync(Guid sequenceId, CancellationToken ct = default) =>
GetAsync($"api/v1/sequences/{sequenceId}/projects", ProtocolJson.Default.ListProjectDto, ct);
public Task<ProjectDto> GetProjectAsync(Guid sequenceId, Guid projectId, CancellationToken ct = default) =>
GetAsync($"api/v1/sequences/{sequenceId}/projects/{projectId}", ProtocolJson.Default.ProjectDto, ct);
/// <summary>
/// A new project of the sequence, its first version copied from <see cref="CreateProjectRequest.FromVersionId"/> or from
/// Main's head; a name refused is a 400 <c>invalid_name</c> or 409 <c>name_taken</c> <see cref="ChronosApiException"/>.
/// </summary>
public Task<ProjectDto> CreateProjectAsync(Guid sequenceId, CreateProjectRequest request, CancellationToken ct = default) =>
SendAsync(HttpMethod.Post, $"api/v1/sequences/{sequenceId}/projects", request, ProtocolJson.Default.CreateProjectRequest, ProtocolJson.Default.ProjectDto, ct);
/// <summary>Gives a project another name; a name refused is a 400 <c>invalid_name</c> or 409 <c>name_taken</c> <see cref="ChronosApiException"/>.</summary>
public Task<ProjectDto> RenameProjectAsync(Guid sequenceId, Guid projectId, string name, CancellationToken ct = default) =>
SendAsync(HttpMethod.Patch, $"api/v1/sequences/{sequenceId}/projects/{projectId}", new RenameProjectRequest(name), ProtocolJson.Default.RenameProjectRequest,
ProtocolJson.Default.ProjectDto, ct);
/// <summary>
/// Deletes a project and its versions into the sequence's projects' trash (never erased); Main is refused (409
/// <c>main_cannot_be_deleted</c>).
/// </summary>
public Task DeleteProjectAsync(Guid sequenceId, Guid projectId, CancellationToken ct = default) =>
SendNoContentAsync(HttpMethod.Delete, $"api/v1/sequences/{sequenceId}/projects/{projectId}", ct);
/// <summary>The project's newest version.</summary>
public Task<ProjectVersionDto> GetProjectHeadAsync(Guid sequenceId, Guid projectId, CancellationToken ct = default) =>
GetAsync($"api/v1/sequences/{sequenceId}/projects/{projectId}/head", ProtocolJson.Default.ProjectVersionDto, ct);
/// <summary>
/// One page of a project's versions: newest first, numbered below <paramref name="before"/> (from the head when null),
/// or, with <paramref name="after"/>, oldest first numbered above it (what a workspace pulls). <paramref name="limit"/>:
/// 1–200 (the server's default, 50 newest first and 100 oldest first, when null).
/// </summary>
public Task<ProjectVersionPageDto> ListProjectVersionsAsync(Guid sequenceId, Guid projectId, int? before = null, int? after = null, int? limit = null,
CancellationToken ct = default) =>
GetAsync($"api/v1/sequences/{sequenceId}/projects/{projectId}/versions?{N("before", before)}{N("after", after)}{N("limit", limit)}".TrimEnd('&', '?'),
ProtocolJson.Default.ProjectVersionPageDto, ct);
/// <summary>A version of the project by id; null when the server has no such version of it.</summary>
public async Task<ProjectVersionDto?> GetProjectVersionAsync(Guid sequenceId, Guid projectId, Guid versionId, CancellationToken ct = default)
{
try
{
return await GetAsync($"api/v1/sequences/{sequenceId}/projects/{projectId}/versions/{versionId}", ProtocolJson.Default.ProjectVersionDto, ct)
.ConfigureAwait(false);
}
catch (ChronosApiException ex) when (ex.Status == HttpStatusCode.NotFound && ex.Error.Details == "version")
{
return null;
}
}
/// <summary>
/// Pushes <paramref name="version"/>, made in a workspace from the project's head (<see cref="ProjectVersionDto.ParentId"/>):
/// the server stores it as the new head, numbered head + 1 (201, <c>stored</c>), or answers it again for a repeated push
/// (200, <c>already_stored</c>), or refuses it, storing nothing: 409 <c>diverged</c> with the head, 422
/// <c>hash_mismatch</c>, <c>newer_format</c> or <c>invalid</c>. These come back as <see cref="ProjectPushResultDto"/>
/// without throwing; any other failure (the sequence or project gone, no permission, the archive offline or the sequence
/// busy: 503) throws <see cref="ChronosApiException"/>. Safe to repeat: the version's id makes a second push a no-op.
/// </summary>
public async Task<ProjectPushResultDto> PushProjectVersionAsync(Guid sequenceId, Guid projectId, ProjectVersionDto version, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(version);
using var request = new HttpRequestMessage(HttpMethod.Post, $"api/v1/sequences/{sequenceId}/projects/{projectId}/versions")
{
Content = JsonContent.Create(version, ProtocolJson.Default.ProjectVersionDto),
};
using var response = await SendRawAsync(request, ct).ConfigureAwait(false);
if (response.StatusCode is HttpStatusCode.OK or HttpStatusCode.Created or HttpStatusCode.Conflict or HttpStatusCode.UnprocessableEntity)
{
var body = await response.Content.ReadAsStringAsync(ct).ConfigureAwait(false);
try
{
if (JsonSerializer.Deserialize(body, ProtocolJson.Default.ProjectPushResultDto) is { Outcome.Length: > 0 } result) return result;
}
catch (JsonException)
{
// Not a push answer (a proxy's page): the status says what failed.
}
}
await EnsureSuccessAsync(response, ct).ConfigureAwait(false);
throw new ChronosApiException(response.StatusCode, new ApiError("http_" + (int)response.StatusCode, response.ReasonPhrase ?? "error"));
}
/// <summary>The sequence's frames and photo aliases as of one frames version: what its projects' positions are placed on.</summary>
public Task<ProjectFramesDto> GetProjectFramesAsync(Guid sequenceId, CancellationToken ct = default) =>
GetAsync($"api/v1/sequences/{sequenceId}/projects/frames", ProtocolJson.Default.ProjectFramesDto, ct);
// ---------------- Events ----------------
/// <summary>Server events over WebSocket until cancelled; reconnect is the caller's policy.</summary>
@@ -606,4 +698,8 @@ public sealed class ChronosClient : IDisposable
};
private static string Q(string name, string? value) => string.IsNullOrEmpty(value) ? string.Empty : "&" + name + "=" + Uri.EscapeDataString(value);
/// <summary>A number of the query (<c>name=value&amp;</c>); empty when null.</summary>
private static string N(string name, int? value) =>
value is { } n ? name + "=" + n.ToString(System.Globalization.CultureInfo.InvariantCulture) + "&" : string.Empty;
}
+10
View File
@@ -23,5 +23,15 @@ public sealed record ServerInfo(
ServerLimits Limits,
IReadOnlyList<string>? Extensions = null);
/// <summary>Names of <see cref="ServerInfo.Capabilities"/> that clients act on.</summary>
public static class ServerCapabilities
{
/// <summary>
/// The server keeps its sequences' projects (owner review 2, R8): <c>/api/v1/sequences/{sid}/projects</c>, the
/// <c>projectChanged</c> event, renders of a project version. A server without it knows only the sequence's settings.
/// </summary>
public const string Projects = "projects";
}
/// <summary><c>GET /health</c>.</summary>
public sealed record HealthStatus(string Status, string Version, IReadOnlyDictionary<string, string> Checks);
+12 -1
View File
@@ -4,7 +4,8 @@ namespace Chronos.Protocol;
/// <summary>
/// Messages pushed on <c>WS /api/v1/events</c>. Each frame is one JSON object with a <c>type</c> discriminator:
/// jobProgress, jobState, sequenceChanged, cardEvent, nodeState, scheduleChanged.
/// jobProgress, jobState, sequenceChanged, cardEvent, nodeState, scheduleChanged, projectChanged. A client ignores the types it
/// does not know (an older client those of a newer server).
/// </summary>
[JsonPolymorphic(TypeDiscriminatorPropertyName = "type")]
[JsonDerivedType(typeof(JobProgressEvent), "jobProgress")]
@@ -13,6 +14,7 @@ namespace Chronos.Protocol;
[JsonDerivedType(typeof(CardEvent), "cardEvent")]
[JsonDerivedType(typeof(NodeStateEvent), "nodeState")]
[JsonDerivedType(typeof(ScheduleChangedEvent), "scheduleChanged")]
[JsonDerivedType(typeof(ProjectChangedEvent), "projectChanged")]
public abstract record ServerEvent;
public sealed record JobProgressEvent(Guid JobId, long Done, long Total, double? ItemsPerSecond, double? EtaSeconds) : ServerEvent;
@@ -48,3 +50,12 @@ public sealed record NodeStateEvent(Guid NodeId, string ClientName, string State
/// included, or its next run moved (owner review 2, R10): the admin panel's Scheduled tab reads the list again.
/// </summary>
public sealed record ScheduleChangedEvent(Guid ScheduleId, bool Deleted) : ServerEvent;
/// <summary>
/// A project of a sequence changed (owner review 2, R8): <see cref="Change"/> is one of <see cref="ProjectChanges"/>
/// (<c>created</c>, <c>renamed</c>, <c>deleted</c>, <c>pushed</c>), <see cref="HeadNumber"/> and <see cref="HeadVersionId"/>
/// its head after the change. Sent for the API's own changes and when Main takes settings another path wrote (a
/// <c>PATCH</c> of the sequence's settings, an analysis, the sync of a desktop's copy, a conversion); a workspace with that
/// project checked out knows its home moved, and the admin panel reads the projects again.
/// </summary>
public sealed record ProjectChangedEvent(Guid SequenceId, Guid ProjectId, string Change, int HeadNumber, Guid? HeadVersionId) : ServerEvent;
+157
View File
@@ -0,0 +1,157 @@
namespace Chronos.Protocol;
/// <summary>
/// A project of a server sequence (owner review 2, R8; <c>/api/v1/sequences/{sid}/projects</c>): a named set of render
/// settings ("4K landscape", "Vertical social") with a linear history of versions. Every sequence has one Main project
/// (<see cref="IsMain"/>, listed first), whose head is the sequence's own settings: an old client's <c>PATCH
/// /sequences/{id}</c> of the settings becomes a version of it. <see cref="HeadKind"/>, <see cref="HeadAuthor"/>,
/// <see cref="HeadClientName"/> and <see cref="HeadStoredAt"/> describe the head version: who changed the project last,
/// and when. <see cref="CreatedBy"/> is the account that made the project (null for Main, made from the settings).
/// </summary>
public sealed record ProjectDto(
Guid Id,
Guid SequenceId,
string Name,
bool IsMain,
Guid? HeadVersionId,
int HeadNumber,
string? CreatedBy,
DateTimeOffset CreatedAt,
DateTimeOffset UpdatedAt,
string? HeadKind = null,
string? HeadAuthor = null,
string? HeadClientName = null,
DateTimeOffset? HeadStoredAt = null);
/// <summary>
/// One version of a project, immutable once stored (owner review 2, R8). <see cref="SettingsJson"/> is the portable form of
/// the settings (every frame position parked by photo, canonical text) and <see cref="ContentHash"/> the lower-case hex
/// SHA-256 of its UTF-8 bytes, which every side checks. <see cref="Kind"/> is <c>commit</c>, <c>merge</c>, <c>restore</c>,
/// <c>imported</c> or <c>external</c> (Main only: settings written outside the projects). <see cref="SettingsFormat"/> is the
/// settings' format (a newer one opens read-only), <see cref="FramesVersion"/> the frames version they were made against,
/// <see cref="RestoredFrom"/> the version a restore brought back. <see cref="StoredAt"/> is null for a version a workspace
/// has not pushed. A push (<c>POST …/versions</c>) sends the version as the workspace made it, its parent the head it knew:
/// the server numbers it (head + 1), records the account that pushed it as its <see cref="Author"/> and stores it.
/// </summary>
public sealed record ProjectVersionDto(
Guid Id,
Guid ProjectId,
Guid? ParentId,
int Number,
string Kind,
string? Author,
string? ClientName,
string? Note,
string SettingsJson,
string ContentHash,
int SettingsFormat,
int FramesVersion,
Guid? RestoredFrom,
DateTimeOffset CreatedAt,
DateTimeOffset? StoredAt);
/// <summary>
/// <c>POST /api/v1/sequences/{sid}/projects</c>: a new project named <see cref="Name"/> (1–60 characters, unique among the
/// sequence's projects whatever the case), whose first version (kind <c>imported</c>) holds the settings of
/// <see cref="FromVersionId"/> (a version of any project of the sequence), or of Main's head.
/// </summary>
public sealed record CreateProjectRequest(string Name, Guid? FromVersionId = null);
/// <summary><c>PATCH /api/v1/sequences/{sid}/projects/{pid}</c>: the project's new name (1–60 characters, unique among the sequence's projects).</summary>
public sealed record RenameProjectRequest(string Name);
/// <summary>
/// <c>GET /api/v1/sequences/{sid}/projects/{pid}/versions</c>: one page of a project's versions, newest first (below
/// <c>before</c>, from the head when absent) or oldest first with <c>after</c> (what a workspace pulls). <see cref="More"/>:
/// versions follow this page in its order. <see cref="HeadNumber"/> is the project's head as the page was read.
/// </summary>
public sealed record ProjectVersionPageDto(IReadOnlyList<ProjectVersionDto> Items, int HeadNumber, bool More);
/// <summary>
/// The answer to a push (<c>POST /api/v1/sequences/{sid}/projects/{pid}/versions</c>): <see cref="Outcome"/> (one of
/// <see cref="ProjectPushOutcomes"/>), the version as stored (<c>stored</c>: 201, <c>already_stored</c>: 200, a push repeated
/// after its answer was lost) and the project's head. A refusal stores nothing and carries the error's <see cref="Code"/>
/// and its sentence in the request's language (<see cref="Message"/>), so the body also reads as an <see cref="ApiError"/>:
/// 409 <c>project_diverged</c> (<c>diverged</c>: the head moved past the version's parent; pull the head, replay the version
/// on it and push again), 422 <c>hash_mismatch</c> (the settings do not match the content hash), <c>newer_format</c>
/// (settings of a newer format than the server reads), <c>invalid_version</c> (<c>invalid</c>: positions not parked by
/// photo, or the id is another project's version).
/// </summary>
public sealed record ProjectPushResultDto(string Outcome, ProjectVersionDto? Version, ProjectVersionDto? Head, string? Code = null, string? Message = null);
/// <summary>
/// <c>GET /api/v1/sequences/{sid}/projects/frames</c>: what a workspace places a server sequence's project positions on, as
/// of one frames version: every frame in index order (as <c>GET /sequences/{id}/frames</c> gives them) and the links between
/// encodings of one photo, the sequence's tombstones of reason <c>replaced</c> (a conversion's original and its replacement;
/// a position parked on either finds the frame that holds the other). <see cref="Aliases"/> is null when there are none.
/// </summary>
public sealed record ProjectFramesDto(Guid SequenceId, int FramesVersion, IReadOnlyList<FrameDto> Frames, IReadOnlyList<RemovedPhotoDto>? Aliases = null);
/// <summary>What became of a pushed version (<see cref="ProjectPushResultDto.Outcome"/>).</summary>
public static class ProjectPushOutcomes
{
/// <summary>Stored as the new head: its parent was the head (a fast-forward). 201.</summary>
public const string Stored = "stored";
/// <summary>A version with that id and content is stored already (a repeated push): nothing changed. 200.</summary>
public const string AlreadyStored = "already_stored";
/// <summary>The head moved past the version's parent. 409 <c>project_diverged</c>.</summary>
public const string Diverged = "diverged";
/// <summary>The settings do not match the content hash. 422 <c>hash_mismatch</c>.</summary>
public const string HashMismatch = "hash_mismatch";
/// <summary>Settings of a newer format than the server reads. 422 <c>newer_format</c>.</summary>
public const string NewerFormat = "newer_format";
/// <summary>Not a version of this project (positions not parked by photo, or another project's id). 422 <c>invalid_version</c>.</summary>
public const string Invalid = "invalid";
/// <summary>The version's file would be larger than a version may be (64 MiB). 422 <c>too_large</c>.</summary>
public const string TooLarge = "too_large";
}
/// <summary>Changes of a project a <see cref="ProjectChangedEvent"/> tells.</summary>
public static class ProjectChanges
{
/// <summary>A project was made (Main too, the first time the sequence's projects are read).</summary>
public const string Created = "created";
public const string Renamed = "renamed";
/// <summary>A project left the sequence (into its projects' trash).</summary>
public const string Deleted = "deleted";
/// <summary>
/// The project has a new head: a version pushed, settings written outside the projects taken as Main's external version
/// (an older client, an analysis, the sync of a desktop's copy), a merge, or versions another program sharing the archive
/// wrote.
/// </summary>
public const string Pushed = "pushed";
}
/// <summary>Error codes of the project calls that clients act on (owner review 2, R8).</summary>
public static class ProjectErrors
{
/// <summary>409 from a push: the head moved past the version's parent (the answer carries the head).</summary>
public const string Diverged = "project_diverged";
/// <summary>422 from a push: the settings do not match their content hash.</summary>
public const string HashMismatch = "hash_mismatch";
/// <summary>422 from a push: settings of a newer format than the server reads.</summary>
public const string NewerFormat = "newer_format";
/// <summary>422 from a push: not a version of this project.</summary>
public const string InvalidVersion = "invalid_version";
/// <summary>400: a project name is blank, longer than 60 characters or holds a control character.</summary>
public const string InvalidName = "invalid_name";
/// <summary>409: another project of the sequence has that name (case does not count).</summary>
public const string NameTaken = "name_taken";
/// <summary>409: the Main project holds the sequence's own settings and is never deleted.</summary>
public const string MainCannotBeDeleted = "main_cannot_be_deleted";
}
+8
View File
@@ -91,4 +91,12 @@ namespace Chronos.Protocol;
[JsonSerializable(typeof(ReorganizePlanDto))]
[JsonSerializable(typeof(ConvertRequest))]
[JsonSerializable(typeof(ConvertPlanDto))]
[JsonSerializable(typeof(ProjectDto))]
[JsonSerializable(typeof(List<ProjectDto>))]
[JsonSerializable(typeof(ProjectVersionDto))]
[JsonSerializable(typeof(CreateProjectRequest))]
[JsonSerializable(typeof(RenameProjectRequest))]
[JsonSerializable(typeof(ProjectVersionPageDto))]
[JsonSerializable(typeof(ProjectPushResultDto))]
[JsonSerializable(typeof(ProjectFramesDto))]
public sealed partial class ProtocolJson : JsonSerializerContext;