Lays down every contract the later parcels of owner review 1 phase 5 build on, so they compile against shared types without touching each other's files. - Settings format 3: export.playback (direction, loops, fades, hold), omitted at its default and member by member; RequiredFormat is 3 only while used. - OutputProgram public API with a forward-only body; still-frame job parameters (StillFrame, StillPhoto) routed to format-3 nodes only. - Render.Sha256/Kind, RenderCopy, RenderKind; JobKind.VideoCopy = 24. - Migration 0010 (sqlite, postgres): renders.sha256/kind, ix_renders_created, render_copies without a foreign key. - Videos protocol DTOs, client calls, ServerCapabilities.Videos (declared, not announced yet), ServerSettingsDto.VideosPath. - IVideoLibrary with a NotImplemented stub registered on the server; TrashKind.Videos, VideoTrashNames, VideoErrors. - en and it strings for the whole phase, five icons, decisions 1-22 and the open-question defaults; tests that used format 3 as "newer" now use 4. Refs #21 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
290 lines
15 KiB
C#
290 lines
15 KiB
C#
using System.Text.Json;
|
|
using System.Text.Json.Serialization;
|
|
using Chronos.Core.Model;
|
|
using Chronos.Data.Archiving.Jobs;
|
|
using Chronos.Protocol;
|
|
|
|
namespace Chronos.Data.Videos;
|
|
|
|
/// <summary>
|
|
/// What the videos library lists (owner review 1, R9): every member optional, combined with "and". The values are those of
|
|
/// <c>GET /api/v1/videos</c> (<see cref="VideoQueryDto"/>).
|
|
/// </summary>
|
|
public sealed record VideoQuery
|
|
{
|
|
/// <summary>The most videos a page holds.</summary>
|
|
public const int MaxLimit = 500;
|
|
|
|
/// <summary>Text in the sequence title, the preset name or the file name (any case).</summary>
|
|
public string? Text { get; init; }
|
|
|
|
/// <summary><see cref="RenderKind.Video"/>, <see cref="RenderKind.Still"/> or <see cref="RenderKind.Sequence"/>; null for every kind.</summary>
|
|
public string? Kind { get; init; }
|
|
|
|
/// <summary>A codec name as recorded (<c>h264</c>, <c>hevc</c>, <c>pngsequence</c>…); null for every codec.</summary>
|
|
public string? Codec { get; init; }
|
|
|
|
/// <summary>The year the render was made (UTC).</summary>
|
|
public int? Year { get; init; }
|
|
|
|
/// <summary>The renders of one sequence.</summary>
|
|
public Guid? SequenceId { get; init; }
|
|
|
|
/// <summary>One of <see cref="VideoSorts"/>; null for newest first.</summary>
|
|
public string? Sort { get; init; }
|
|
|
|
/// <summary>The <see cref="VideoPage.Next"/> of the previous page; null for the first.</summary>
|
|
public string? Cursor { get; init; }
|
|
|
|
/// <summary>Videos per page, 1..<see cref="MaxLimit"/>.</summary>
|
|
public int Limit { get; init; } = 100;
|
|
|
|
/// <summary>The query of an API request (its limit clamped, the default when none is given).</summary>
|
|
public static VideoQuery From(VideoQueryDto dto)
|
|
{
|
|
ArgumentNullException.ThrowIfNull(dto);
|
|
return new VideoQuery
|
|
{
|
|
Text = dto.Q,
|
|
Kind = dto.Kind,
|
|
Codec = dto.Codec,
|
|
Year = dto.Year,
|
|
SequenceId = dto.Sequence,
|
|
Sort = dto.Sort,
|
|
Cursor = dto.Cursor,
|
|
Limit = dto.Limit is { } limit ? Math.Clamp(limit, 1, MaxLimit) : 100,
|
|
};
|
|
}
|
|
}
|
|
|
|
/// <summary>A render as the videos library shows it: the render, its sequence and project, where its file is, and its copies.</summary>
|
|
public sealed record VideoItem
|
|
{
|
|
public required Render Render { get; init; }
|
|
|
|
/// <summary>The display title of the render's sequence.</summary>
|
|
public required string SequenceTitle { get; init; }
|
|
|
|
/// <summary>When the sequence's first photo was taken; null when unknown.</summary>
|
|
public DateTime? SequenceFirstCapture { get; init; }
|
|
|
|
/// <summary>The project rendered (owner review 2, R8); null for a render of the sequence's settings.</summary>
|
|
public string? ProjectName { get; init; }
|
|
|
|
/// <summary>The number of the project version rendered; null with <see cref="ProjectName"/>.</summary>
|
|
public int? ProjectVersionNumber { get; init; }
|
|
|
|
/// <summary>Absolute path of the render's file (or folder, for an image sequence) on this host.</summary>
|
|
public required string FullPath { get; init; }
|
|
|
|
/// <summary>The file is not at <see cref="FullPath"/>: shown as Missing, and a delete removes only its row.</summary>
|
|
public bool Missing { get; init; }
|
|
|
|
/// <summary>Its verified copies in videos folders, oldest first.</summary>
|
|
public IReadOnlyList<RenderCopy> Copies { get; init; } = [];
|
|
|
|
/// <summary>The library kind (<see cref="RenderKind.Of(Render)"/>).</summary>
|
|
public string Kind => RenderKind.Of(Render);
|
|
|
|
/// <summary><see cref="VideoStates.Ok"/> or <see cref="VideoStates.Missing"/>.</summary>
|
|
public string State => Missing ? VideoStates.Missing : VideoStates.Ok;
|
|
|
|
/// <summary>The file (or folder) name.</summary>
|
|
public string FileName => Path.GetFileName(FullPath.TrimEnd('/', '\\'));
|
|
}
|
|
|
|
/// <summary>One page of the videos library; <see cref="Next"/> is the cursor of the next page, null on the last one.</summary>
|
|
/// <param name="Total">Videos matching the query on every page; null when not counted.</param>
|
|
public sealed record VideoPage(IReadOnlyList<VideoItem> Items, string? Next, long? Total = null)
|
|
{
|
|
public static VideoPage Empty { get; } = new([], null, 0);
|
|
}
|
|
|
|
/// <summary>A render a delete leaves where it is: <see cref="Reason"/> is one of <see cref="VideoBlockReasons"/>.</summary>
|
|
/// <param name="Video">The render, when it exists.</param>
|
|
public sealed record VideoBlocked(Guid RenderId, string Reason, VideoItem? Video = null);
|
|
|
|
/// <summary>
|
|
/// The dry run of deleting renders into the trash (decision 17): the renders that go (a missing one only loses its row), the
|
|
/// renders left where they are, and the plan's fingerprint, which the delete itself must give back. Copies in videos
|
|
/// folders are never touched.
|
|
/// </summary>
|
|
public sealed record VideoDeletePlan(IReadOnlyList<VideoItem> Items, IReadOnlyList<VideoBlocked> Blocked, string Fingerprint)
|
|
{
|
|
/// <summary>The bytes that move into the trash (missing files count nothing).</summary>
|
|
public long Bytes => Items.Where(i => !i.Missing).Sum(i => i.Render.Bytes);
|
|
}
|
|
|
|
/// <summary>What a delete did: the renders moved into the trash (or, missing, whose rows went), those left, and the trash entries made.</summary>
|
|
/// <param name="TrashEntries">The names of the entries made (<see cref="VideoTrashNames"/>), each restorable.</param>
|
|
public sealed record VideoDeleteResult(IReadOnlyList<VideoItem> Deleted, IReadOnlyList<VideoBlocked> Blocked, IReadOnlyList<string> TrashEntries);
|
|
|
|
/// <summary>
|
|
/// The parameters of a <see cref="JobKind.VideoCopy"/> job (decision 16): the renders to copy into <see cref="Folder"/>,
|
|
/// each hash-verified before it takes its name (a free one, " (2)" on a collision), the render never touched.
|
|
/// </summary>
|
|
/// <param name="RenderIds">The renders, in the order they are copied.</param>
|
|
/// <param name="Folder">The videos folder (absolute), checked again when the job runs.</param>
|
|
/// <param name="FromServer">On the desktop: the renders are the signed-in server's, downloaded into the folder.</param>
|
|
/// <param name="RequestedBy">The user (server) or PC (desktop) recorded as <see cref="RenderCopy.CopiedBy"/>.</param>
|
|
public sealed record VideoCopyParameters(IReadOnlyList<Guid> RenderIds, string Folder, bool FromServer = false, string? RequestedBy = null)
|
|
{
|
|
public string ToJson() => JsonSerializer.Serialize(this, VideoJson.Default.VideoCopyParameters);
|
|
|
|
/// <summary>The parameters of a job; null when it has none that read.</summary>
|
|
public static VideoCopyParameters? Read(string? json)
|
|
{
|
|
if (string.IsNullOrWhiteSpace(json)) return null;
|
|
try
|
|
{
|
|
return JsonSerializer.Deserialize(json, VideoJson.Default.VideoCopyParameters) is { RenderIds: not null, Folder.Length: > 0 } parameters ? parameters : null;
|
|
}
|
|
catch (JsonException)
|
|
{
|
|
return null;
|
|
}
|
|
}
|
|
}
|
|
|
|
/// <summary>
|
|
/// The error codes of the videos library (<see cref="VideoLibraryException.Code"/>), the same as the server's API errors:
|
|
/// each has a server message <c>Server.Error.<Code></c> and a desktop message <c>Errors.Videos.*</c>.
|
|
/// </summary>
|
|
public static class VideoErrors
|
|
{
|
|
/// <summary>No videos folder is set (409).</summary>
|
|
public const string FolderUnset = "videos_folder_unset";
|
|
|
|
/// <summary>The videos folder lies inside an archive root or the workspace (422).</summary>
|
|
public const string FolderInvalid = "videos_folder_invalid";
|
|
|
|
/// <summary>The plan of a delete changed since it was made (409; nothing moved).</summary>
|
|
public const string PlanChanged = "plan_changed";
|
|
|
|
/// <summary>A copy, or a trashed video being restored, does not match its render's SHA-256.</summary>
|
|
public const string HashMismatch = "trash_hash_mismatch";
|
|
|
|
/// <summary>Not enough free space in the videos folder (507).</summary>
|
|
public const string NoSpace = "videos_no_space";
|
|
|
|
/// <summary>A trashed video's sequence is not in the library: restore the sequence first (409).</summary>
|
|
public const string SequenceGone = "sequence_gone";
|
|
|
|
/// <summary>A send, an upload or a copy of the render is running (409).</summary>
|
|
public const string Busy = "video_busy";
|
|
}
|
|
|
|
/// <summary>A videos library operation refused with one of <see cref="VideoErrors"/>; nothing was changed.</summary>
|
|
public sealed class VideoLibraryException(string code, string message) : InvalidOperationException(message)
|
|
{
|
|
public string Code { get; } = code;
|
|
}
|
|
|
|
/// <summary>The names of the videos trash entries (decision 17): <c>videos-<render id>-<UTC ticks></c>, listed as kind "videos".</summary>
|
|
public static class VideoTrashNames
|
|
{
|
|
/// <summary>The prefix of every videos entry name.</summary>
|
|
public const string Prefix = "videos-";
|
|
|
|
/// <summary>The folder of the videos area inside an archive's trash, which holds the entries and their records.</summary>
|
|
public const string FolderName = "videos";
|
|
|
|
/// <summary>The entry name of render <paramref name="renderId"/> deleted at <paramref name="deletedAt"/>.</summary>
|
|
public static string EntryName(Guid renderId, DateTimeOffset deletedAt) =>
|
|
Prefix + renderId.ToString("D") + "-" + deletedAt.UtcTicks.ToString(System.Globalization.CultureInfo.InvariantCulture);
|
|
|
|
/// <summary>Whether <paramref name="name"/> is a videos entry name (and nothing else: no path, no other entry's name).</summary>
|
|
public static bool IsEntryName(string? name) => TryParse(name, out _, out _);
|
|
|
|
/// <summary>The render id and the UTC ticks of a videos entry name; false for any other name.</summary>
|
|
public static bool TryParse(string? name, out Guid renderId, out long ticks)
|
|
{
|
|
renderId = Guid.Empty;
|
|
ticks = 0;
|
|
if (name is null || !name.StartsWith(Prefix, StringComparison.Ordinal)) return false;
|
|
var rest = name.AsSpan(Prefix.Length);
|
|
// A "D" guid is 36 characters; then "-" and the ticks.
|
|
return rest.Length > 37 && rest[36] == '-' && Guid.TryParseExact(rest[..36], "D", out renderId)
|
|
&& long.TryParse(rest[37..], System.Globalization.NumberStyles.None, System.Globalization.CultureInfo.InvariantCulture, out ticks);
|
|
}
|
|
}
|
|
|
|
/// <summary>
|
|
/// The videos library of one index (owner review 1, R9): every render of its archives in one list, deleted into the trash
|
|
/// and restored by id, and copied hash-verified into a videos folder. The desktop's Videos section and the server's
|
|
/// <c>/api/v1/videos</c> endpoints use it; <see cref="Archiving.ArchiveService.Videos"/> is the instance of an archive engine.
|
|
/// </summary>
|
|
public interface IVideoLibrary
|
|
{
|
|
/// <summary>False for the groundwork stub (<see cref="NotImplementedVideoLibrary"/>): callers show no library then.</summary>
|
|
bool IsAvailable { get; }
|
|
|
|
/// <summary>One page of the renders matching <paramref name="query"/>, each with its copies and whether its file is there.</summary>
|
|
Task<VideoPage> ListAsync(VideoQuery query, CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>One render; null when the index has no such render.</summary>
|
|
Task<VideoItem?> GetAsync(Guid renderId, CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>The dry run of deleting <paramref name="renderIds"/> into the trash; nothing moves.</summary>
|
|
Task<VideoDeletePlan> PlanDeleteAsync(IReadOnlyList<Guid> renderIds, CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Deletes <paramref name="renderIds"/> as planned: each file into <c>.chronos/trash/videos/</c> of its archive with a
|
|
/// record, its row removed and its sequence's render count recounted; a missing file loses only its row.
|
|
/// </summary>
|
|
/// <exception cref="VideoLibraryException"><see cref="VideoErrors.PlanChanged"/>: <paramref name="fingerprint"/> is not the plan's now; nothing moved.</exception>
|
|
Task<VideoDeleteResult> DeleteAsync(IReadOnlyList<Guid> renderIds, string fingerprint, string? deletedBy, CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Brings a videos trash entry of archive <paramref name="archiveId"/> back: the file re-hashed against its record, moved
|
|
/// back (to a free name when its own is taken) and its row inserted again with the same render id.
|
|
/// </summary>
|
|
/// <exception cref="DirectoryNotFoundException">The entry is not in the trash.</exception>
|
|
/// <exception cref="VideoLibraryException"><see cref="VideoErrors.HashMismatch"/> or <see cref="VideoErrors.SequenceGone"/>; nothing moved.</exception>
|
|
Task<Render> RestoreAsync(Guid archiveId, string entryName, CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Why <paramref name="folder"/> cannot be the videos folder (<see cref="VideoErrors.FolderUnset"/> or
|
|
/// <see cref="VideoErrors.FolderInvalid"/>); null when it can.
|
|
/// </summary>
|
|
string? FolderProblem(string? folder);
|
|
|
|
/// <summary>The <see cref="JobKind.VideoCopy"/> job copying <paramref name="parameters"/>' renders; enqueue it on the host's engine.</summary>
|
|
/// <exception cref="VideoLibraryException">The folder cannot be the videos folder (<see cref="FolderProblem"/>).</exception>
|
|
ArchiveJobRequest CopyJob(VideoCopyParameters parameters);
|
|
}
|
|
|
|
/// <summary>
|
|
/// The videos library until its parcel lands (phase 5 groundwork): lists nothing, finds nothing, and refuses every change
|
|
/// with <see cref="NotImplementedException"/>; registered so the server and the desktop compile against
|
|
/// <see cref="IVideoLibrary"/>.
|
|
/// </summary>
|
|
public sealed class NotImplementedVideoLibrary : IVideoLibrary
|
|
{
|
|
public static NotImplementedVideoLibrary Instance { get; } = new();
|
|
|
|
public bool IsAvailable => false;
|
|
|
|
public Task<VideoPage> ListAsync(VideoQuery query, CancellationToken cancellationToken = default) => Task.FromResult(VideoPage.Empty);
|
|
|
|
public Task<VideoItem?> GetAsync(Guid renderId, CancellationToken cancellationToken = default) => Task.FromResult<VideoItem?>(null);
|
|
|
|
public Task<VideoDeletePlan> PlanDeleteAsync(IReadOnlyList<Guid> renderIds, CancellationToken cancellationToken = default) =>
|
|
throw new NotImplementedException("The videos library is not implemented yet.");
|
|
|
|
public Task<VideoDeleteResult> DeleteAsync(IReadOnlyList<Guid> renderIds, string fingerprint, string? deletedBy, CancellationToken cancellationToken = default) =>
|
|
throw new NotImplementedException("The videos library is not implemented yet.");
|
|
|
|
public Task<Render> RestoreAsync(Guid archiveId, string entryName, CancellationToken cancellationToken = default) =>
|
|
throw new NotImplementedException("The videos library is not implemented yet.");
|
|
|
|
public string? FolderProblem(string? folder) => string.IsNullOrWhiteSpace(folder) ? VideoErrors.FolderUnset : null;
|
|
|
|
public ArchiveJobRequest CopyJob(VideoCopyParameters parameters) => throw new NotImplementedException("The videos library is not implemented yet.");
|
|
}
|
|
|
|
[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase, DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
|
|
PropertyNameCaseInsensitive = true)]
|
|
[JsonSerializable(typeof(VideoCopyParameters))]
|
|
internal sealed partial class VideoJson : JsonSerializerContext;
|