Files
Chronos/src/Chronos.Protocol/Uploads.cs
T
Alby96andClaude Opus 5.5 283d04d9cd feat: found copies foundation (contracts, migration 0012, store, wire, trash and job hooks, keys)
Owner review 6 asks Chronos to recognise the same time-lapse held under different ids on the
server and on this PC, compare the copies, and keep them apart or integrate and sync them. This
lays the shared foundation the later parcels build on, without any UI or detection yet.

- Migration 0012 adds found_copies (local-server and local-local pairs with evidence, scores,
  answer, policy and the 404 record) and copy_probes; every existing link with a local sequence
  becomes a Linked pair, so a server deletion and the per-link policy have a place.
- FoundCopyStore keeps the pairs: upserts that never touch the answer, a compare-and-set of the
  state with an Integrating backstop (a failed or cancelled job reads as the previous state),
  link promotion and demotion, the once-per-refresh 404 count, the merge's links stage
  (session keys, links reset, pairs moved, refused when both are linked on one server), the
  local overlap queries and the probes. SyncLinkStore.RekeyAsync moves pairs and probes with
  the links in the same transaction.
- Contracts for detection, review, plans, the Integrate and MergeSequences jobs (kinds 25/26,
  High level, new detail steps) and the Upload all rule that keeps suspected, kept-apart,
  deleted, busy and server-born sequences here.
- Wire: POST photos/lookup, uploads into a target (IntoTarget/Copied, trailing and optional),
  frames/delete on the client, capabilities photo-lookup and upload-into, cached per remote.
- The trash plans and deletes accept the job that holds the sequence (its own hold is not
  Busy) and a frames version checked under the lease; a Background job never interrupts a
  running one.
- Settings for linking, the photo policy and projects; the en and it keys of design section 9.

Refs #73

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 19:39:04 +01:00

81 lines
4.9 KiB
C#

namespace Chronos.Protocol;
/// <summary>
/// <c>POST /api/v1/uploads</c> (BRIEF §14.4). The client hashes the file first; when the server already holds that
/// SHA-256 it answers 200 with <see cref="StartUploadResponse.AlreadyExists"/> and no upload is needed. A photo deleted
/// from the target sequence is answered the same way, without a frame (owner review 2, R6), unless <see cref="Restore"/>
/// asks to file it there again: only an explicit user action sends it (the admin panel's "Upload again"), never sync or a
/// watch folder, and the completion repeats it (<c>complete?restore=true</c>). Filing it drops the photo's tombstone.
/// <para>
/// <see cref="IntoTarget"/> (owner review 6, #73; capability <see cref="ServerCapabilities.UploadInto"/>) files the photo into
/// <see cref="SequenceId"/> even when another sequence of the served archive holds it: the server copies its own file into
/// the target, no bytes on the wire, and answers <see cref="StartUploadResponse.Copied"/>. The caller must own the target,
/// be an admin or hold the Edit right; never with <see cref="Restore"/>.
/// </para>
/// </summary>
public sealed record StartUploadRequest(Guid? SequenceId, string FileName, long Size, string Sha256, DateTime? CapturedAt, string? SessionKey,
bool Restore = false, bool IntoTarget = false);
/// <summary>
/// The answer to <c>POST /api/v1/uploads</c>. <see cref="Copied"/>: the server filed the photo into the target from a file it
/// held in another sequence (<see cref="StartUploadRequest.IntoTarget"/>); <see cref="FrameId"/> is the new frame.
/// </summary>
public sealed record StartUploadResponse(Guid? UploadId, int ChunkSize, IReadOnlyList<int> Received, bool AlreadyExists, Guid? FrameId,
bool Copied = false);
/// <summary>Error codes of the frame upload calls that clients act on.</summary>
public static class UploadErrors
{
/// <summary>
/// 409 from <c>POST /api/v1/uploads/{id}/complete</c>: the photo was deleted from the target sequence while it was on its
/// way and the completion did not ask to restore it, so it was not filed and the upload is cancelled (owner review 2, R6).
/// </summary>
public const string PhotoRemoved = "photo_removed";
}
/// <summary><c>PUT /api/v1/uploads/{id}/chunks/{n}</c> response.</summary>
public sealed record ChunkReceived(int Index, IReadOnlyList<int> Received);
/// <summary><c>POST /api/v1/uploads/{id}/complete</c> response: the committed frame.</summary>
public sealed record CompleteUploadResponse(Guid FrameId, Guid SequenceId, int Index);
/// <summary><c>GET /api/v1/uploads/{id}</c>: resume state.</summary>
public sealed record UploadState(Guid UploadId, string FileName, long Size, string Sha256, int ChunkSize, IReadOnlyList<int> Received, string State);
/// <summary>
/// <c>POST /api/v1/uploads/cards</c>: a client importing a card into the server through these uploads reports its start,
/// progress and end (BRIEF §14.4); the server tells every connected client with a <see cref="CardEvent"/> (BRIEF §14.3).
/// <see cref="ImportId"/> is the client's import plan, <see cref="Card"/> the card's name as the client shows it.
/// </summary>
public sealed record CardImportReport(Guid ImportId, string Card, string State, int Done, int Total, int Failed);
/// <summary>
/// <c>POST /api/v1/sequences/{id}/renders</c>: a client offers one of its renders of the sequence (BRIEF §14.5,
/// renders are uploaded on request). The render keeps its id on the server, so both sides recognise it; when the
/// server already has that id it answers 200 with <see cref="StartUploadResponse.AlreadyExists"/>. Chunks go to
/// <c>/uploads/{uploadId}/chunks/{n}</c>; <c>POST /sequences/{id}/renders/{uploadId}/complete</c> verifies the SHA-256
/// and files the render under the sequence's exports. A completion that cannot file it for now answers 503
/// <c>sequence_busy</c>, <c>archive_offline</c> or <c>folder_moved</c> (another index moved the sequence's folder; the
/// server's next scan finds it) and keeps the upload, to be completed again.
/// A render a workspace made on a client (phase 5c) names the project and version it was rendered from
/// (<see cref="ProjectId"/>, <see cref="ProjectVersionId"/>): the server records them with the render once it checked that
/// the project is the sequence's and the version the project's (422 <c>project_mismatch</c> otherwise). Both are optional
/// and appended: a request of an earlier client has neither, and an earlier server ignores them. <see cref="Kind"/> (owner
/// review 1, R9) is the render's kind (<c>still</c>, or null for a video or an image sequence), appended the same way.
/// </summary>
public sealed record RenderUploadRequest(
Guid RenderId,
string FileName,
long Size,
string Sha256,
string PresetName,
string? Codec,
int Width,
int Height,
double Fps,
double DurationSeconds,
string? ProducedBy,
Guid? ProjectId = null,
Guid? ProjectVersionId = null,
string? Kind = null);