Files
Chronos/src/Titano.Data/Sync/SyncRemote.cs
T
Claude ea6e1a69e0 fix(sync): keep project positions on their photos when settings cross copies
Settings synced between a PC and its server sequence were stored as they
came, in the other copy's frame order. When the inserted photos arrived
later (a download, an upload), the index moved those already-correct
positions a second time, so exclusions, the hero and camera keyframes
landed on other photos (V-21, CD-2).

- Settings are translated by photo (SHA-256, else size and capture time)
  to the frames of the copy they go to: the server's before they are
  compared or applied here, this PC's to the server's frames as its
  manifest lists them before a push (SyncPositions).
- A position on a photo the receiving copy lacks waits in project.json as
  a pending frame and takes its place when the photo arrives, on an
  insertion or an append in step with the index; the Library's hero
  frame follows. A hero chosen meanwhile wins, and advice does not fill
  a hero while one waits. Old projects without the member are unchanged.
- Pushes send expectedFramesVersion; PATCH /api/v1/sequences/{id} answers
  409 frames_conflict when the frames changed since, and the next
  comparison translates again.
- A pulled payload equal to the local copy is settled without the
  archive: an offline or read-only archive no longer fails the
  comparison (V-10).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
2026-10-12 16:20:11 +00:00

144 lines
7.8 KiB
C#

using Titano.Protocol;
using Titano.Protocol.Client;
namespace Titano.Data.Sync;
/// <summary>
/// The server calls the sync engine makes (BRIEF §14.3). <see cref="TitanoSyncRemote"/> sends them with
/// <see cref="TitanoClient"/>; screenshots and tests substitute fakes. Failures are <see cref="TitanoApiException"/>s
/// (404 gone, 409 settings conflict) or network exceptions. Dispose a remote handed out by an <see cref="ISyncConnector"/>.
/// </summary>
public interface ISyncRemote : IDisposable
{
/// <summary>Normalised server address the links are stored under (<see cref="SyncService.ServerKey"/>).</summary>
string Server { get; }
/// <summary>Every sequence on the server.</summary>
Task<IReadOnlyList<SequenceDto>> ListSequencesAsync(CancellationToken cancellationToken);
Task<SequenceDto> GetSequenceAsync(Guid id, CancellationToken cancellationToken);
Task<SequenceManifest> GetManifestAsync(Guid id, CancellationToken cancellationToken);
/// <summary>Every frame row of a sequence, in index order.</summary>
Task<IReadOnlyList<FrameDto>> ListFramesAsync(Guid sequenceId, CancellationToken cancellationToken);
/// <summary>The first frame row of a sequence (its thumbnail stands for a sequence without a hero frame); null when it has none yet.</summary>
async Task<FrameDto?> FirstFrameAsync(Guid sequenceId, CancellationToken cancellationToken) =>
(await ListFramesAsync(sequenceId, cancellationToken).ConfigureAwait(false)).FirstOrDefault();
/// <summary>
/// A 409 <see cref="TitanoApiException"/> means the settings version moved on the server, or its frames did since
/// <see cref="UpdateSequenceRequest.ExpectedFramesVersion"/>.
/// </summary>
Task<SequenceDto> UpdateSequenceAsync(Guid id, UpdateSequenceRequest request, CancellationToken cancellationToken);
/// <summary>
/// Chunked, resumable upload of one original into <paramref name="sequenceId"/>, or into the sequence the server
/// files <paramref name="sessionKey"/> under (created by the first one); the server verifies <paramref name="sha256"/>
/// before committing it (BRIEF §14.4). An original the server already holds is not sent again: the response then
/// names <paramref name="sequenceId"/> (<see cref="Guid.Empty"/> without one). See <see cref="TitanoClient.UploadFileAsync"/>.
/// </summary>
Task<CompleteUploadResponse?> UploadFileAsync(string path, Guid? sequenceId, string? sessionKey, string sha256, DateTime? capturedAt,
CancellationToken cancellationToken);
/// <summary>Streams a frame's original, proxy or thumb, resuming with Range from the destination's length.</summary>
Task DownloadFrameAsync(Guid frameId, string kind, Stream destination, CancellationToken cancellationToken);
/// <summary>
/// Sends the proxy of a frame the server cannot decode (<see cref="ManifestFrame.WantsProxy"/>); a 422
/// <see cref="TitanoApiException"/> means it was refused (not a JPEG of that frame), 409 that the server makes no
/// proxies. A remote without the call (the screenshots' sample server) throws <see cref="NotSupportedException"/>.
/// </summary>
Task UploadProxyAsync(Guid frameId, byte[] jpeg, CancellationToken cancellationToken) => throw new NotSupportedException();
/// <summary>Streams a render's file, resuming with Range from the destination's length; returns the file name the server gives it.</summary>
Task<string?> DownloadRenderAsync(Guid renderId, Stream destination, CancellationToken cancellationToken);
/// <summary>
/// Chunked, resumable upload of a render of <paramref name="sequenceId"/> made on this PC; the server verifies the
/// SHA-256 and keeps the render's id. Null when the server already has it. See <see cref="TitanoClient.UploadRenderAsync"/>.
/// </summary>
Task<RenderDto?> UploadRenderAsync(Guid sequenceId, string path, RenderUploadRequest request, CancellationToken cancellationToken);
/// <summary>Server events until cancelled or the socket closes.</summary>
IAsyncEnumerable<ServerEvent> EventsAsync(CancellationToken cancellationToken);
}
/// <summary>Where sync jobs find their server connection.</summary>
public interface ISyncConnector
{
/// <summary>A signed-in remote of <paramref name="server"/> owned by the caller; null when this PC is not connected to that server.</summary>
ValueTask<ISyncRemote?> ConnectAsync(string server, CancellationToken cancellationToken);
}
/// <summary><see cref="ISyncRemote"/> over a signed-in <see cref="TitanoClient"/>, which it disposes when it owns it.</summary>
public sealed class TitanoSyncRemote(TitanoClient client, bool ownsClient) : ISyncRemote
{
private const int SequencePage = 500;
private const int FramePage = 1000;
public string Server { get; } = SyncService.ServerKey(client.BaseAddress);
public async Task<IReadOnlyList<SequenceDto>> ListSequencesAsync(CancellationToken cancellationToken)
{
var all = new List<SequenceDto>();
string? cursor = null;
do
{
var page = await client.ListSequencesAsync(null, cursor, SequencePage, cancellationToken).ConfigureAwait(false);
all.AddRange(page.Items);
cursor = page.NextCursor;
}
while (cursor is not null);
return all;
}
public Task<SequenceDto> GetSequenceAsync(Guid id, CancellationToken cancellationToken) => client.GetSequenceAsync(id, cancellationToken);
public Task<SequenceManifest> GetManifestAsync(Guid id, CancellationToken cancellationToken) => client.GetManifestAsync(id, cancellationToken);
public async Task<IReadOnlyList<FrameDto>> ListFramesAsync(Guid sequenceId, CancellationToken cancellationToken)
{
var all = new List<FrameDto>();
string? cursor = null;
do
{
var page = await client.ListFramesAsync(sequenceId, cursor, FramePage, cancellationToken).ConfigureAwait(false);
all.AddRange(page.Items);
cursor = page.NextCursor;
}
while (cursor is not null);
return all;
}
/// <summary>One row of the first frames page instead of the whole list.</summary>
public async Task<FrameDto?> FirstFrameAsync(Guid sequenceId, CancellationToken cancellationToken) =>
(await client.ListFramesAsync(sequenceId, null, 1, cancellationToken).ConfigureAwait(false)).Items.FirstOrDefault();
public Task<SequenceDto> UpdateSequenceAsync(Guid id, UpdateSequenceRequest request, CancellationToken cancellationToken) =>
client.UpdateSequenceAsync(id, request, cancellationToken);
public Task<CompleteUploadResponse?> UploadFileAsync(string path, Guid? sequenceId, string? sessionKey, string sha256, DateTime? capturedAt,
CancellationToken cancellationToken) =>
client.UploadFileAsync(path, sequenceId, capturedAt, sessionKey, sha256, null, cancellationToken);
public Task DownloadFrameAsync(Guid frameId, string kind, Stream destination, CancellationToken cancellationToken) =>
client.DownloadFrameAsync(frameId, kind, destination, null, cancellationToken);
public Task UploadProxyAsync(Guid frameId, byte[] jpeg, CancellationToken cancellationToken) => client.UploadProxyAsync(frameId, jpeg, cancellationToken);
public Task<string?> DownloadRenderAsync(Guid renderId, Stream destination, CancellationToken cancellationToken) =>
client.DownloadRenderAsync(renderId, destination, cancellationToken);
public Task<RenderDto?> UploadRenderAsync(Guid sequenceId, string path, RenderUploadRequest request, CancellationToken cancellationToken) =>
client.UploadRenderAsync(sequenceId, path, request, null, cancellationToken);
public IAsyncEnumerable<ServerEvent> EventsAsync(CancellationToken cancellationToken) => client.EventsAsync(cancellationToken);
public void Dispose()
{
if (ownsClient) client.Dispose();
}
}