From 7353c17d7b0374337aad7e4e39392651bbd37ed8 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 11:31:07 +0000 Subject: [PATCH] feat(protocol): admin, render-node and sync contracts with client calls Adds DTOs for users summary, audit, sequence stats and delete plan, archive and server settings, dashboard, logs, render job parameters and render results, plus client calls for job pause/resume/priority, node failure and chunked render-result upload (sharing the frame upload chunk loop). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC --- src/Titano.Protocol/Admin.cs | 53 ++++++++++++ src/Titano.Protocol/Auth.cs | 18 +++++ src/Titano.Protocol/Client/TitanoClient.cs | 94 +++++++++++++++------- src/Titano.Protocol/Dtos.cs | 4 +- src/Titano.Protocol/Jobs.cs | 24 ++++++ src/Titano.Protocol/ProtocolJson.cs | 17 ++++ src/Titano.Protocol/Sequences.cs | 23 ++++++ 7 files changed, 203 insertions(+), 30 deletions(-) create mode 100644 src/Titano.Protocol/Admin.cs diff --git a/src/Titano.Protocol/Admin.cs b/src/Titano.Protocol/Admin.cs new file mode 100644 index 00000000..17abbd28 --- /dev/null +++ b/src/Titano.Protocol/Admin.cs @@ -0,0 +1,53 @@ +namespace Titano.Protocol; + +/// +/// GET/PUT /api/v1/server/settings (admin): the editable part of the server configuration. Settings named in +/// come from environment variables and cannot be changed here; says +/// that saved values (ports, TLS, workers, chunk size) wait for a restart. +/// +public sealed record ServerSettingsDto( + string ServerName, + int HttpPort, + int HttpsPort, + string TlsMode, + string? TlsCert, + string? TlsKey, + string Language, + int Workers, + bool Discovery, + long MaxUploadBytes, + int ChunkSizeBytes, + int JobHistoryDays, + int TokenLifetimeDays, + int UploadRetentionHours, + IReadOnlyList Locked, + bool RestartRequired); + +/// A server log file (GET /api/v1/logs/files). +public sealed record LogFileDto(string Name, long Size, DateTimeOffset Modified); + +/// The last lines of the current server log (GET /api/v1/logs). +public sealed record LogTailDto(string File, IReadOnlyList Lines); + +/// Jobs per state; done and failed count today's (UTC) jobs. +public sealed record JobCountsDto(int Queued, int Running, int Paused, int DoneToday, int FailedToday); + +/// Frames committed by uploads on one UTC day. +public sealed record UploadDayDto(DateOnly Day, long Frames, long Bytes); + +/// GET /api/v1/server/dashboard (admin): everything the dashboard page shows in one call (BRIEF §14.8). +public sealed record DashboardDto( + string ServerName, + string Version, + long UptimeSeconds, + string Database, + string TlsMode, + bool Discovery, + int Users, + ArchiveStatsDto Archive, + JobCountsDto Jobs, + int Workers, + IReadOnlyList Nodes, + IReadOnlyList Uploads, + IReadOnlyList Activity, + IReadOnlyList ActiveJobs); diff --git a/src/Titano.Protocol/Auth.cs b/src/Titano.Protocol/Auth.cs index 077009c1..fdf07086 100644 --- a/src/Titano.Protocol/Auth.cs +++ b/src/Titano.Protocol/Auth.cs @@ -29,3 +29,21 @@ public sealed record UpdateUserRequest(string? DisplayName, string? Role, long? /// Response of POST /api/v1/users and /users/{id}/reset-password: a temporary password shown once. public sealed record TemporaryPasswordResponse(UserDto User, string TemporaryPassword); + +/// POST /api/v1/users/{id}/reset-password (admin); without a password the server generates one. +public sealed record ResetPasswordRequest(string? Password); + +/// One row of the admin user list: the account plus when and from which client it was last used. +public sealed record UserSummaryDto(UserDto User, DateTimeOffset? LastSeen, string? LastClient, long UploadsLast30Days); + +/// One audit log entry (who did what to which user, sequence or setting). +public sealed record AuditEntryDto( + Guid Id, + DateTimeOffset At, + Guid? UserId, + string? Username, + string Action, + string? TargetKind, + string? TargetId, + string? Details, + string? RemoteAddress); diff --git a/src/Titano.Protocol/Client/TitanoClient.cs b/src/Titano.Protocol/Client/TitanoClient.cs index d8f57f51..d843ca82 100644 --- a/src/Titano.Protocol/Client/TitanoClient.cs +++ b/src/Titano.Protocol/Client/TitanoClient.cs @@ -154,37 +154,59 @@ public sealed class TitanoClient : IDisposable } var uploadId = start.UploadId ?? throw new InvalidOperationException("Server returned no upload id."); - var chunkSize = start.ChunkSize; - var received = new HashSet(start.Received); - var chunks = (int)((info.Length + chunkSize - 1) / chunkSize); - var buffer = new byte[chunkSize]; - await using (var file = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.ReadWrite, 1 << 16, FileOptions.Asynchronous | FileOptions.SequentialScan)) - { - long sent = received.Count == 0 ? 0 : received.Sum(i => (long)Math.Min(chunkSize, info.Length - (long)i * chunkSize)); - progress?.Report(new UploadProgress(sent, info.Length)); - for (var n = 0; n < chunks; n++) - { - if (received.Contains(n)) continue; - var offset = (long)n * chunkSize; - var length = (int)Math.Min(chunkSize, info.Length - offset); - file.Position = offset; - await file.ReadExactlyAsync(buffer.AsMemory(0, length), ct).ConfigureAwait(false); - await Bandwidth.AcquireAsync(length, ct).ConfigureAwait(false); - await RetryAsync(async () => - { - using var content = new ByteArrayContent(buffer, 0, length); - content.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream"); - using var response = await _http.PutAsync($"api/v1/uploads/{uploadId}/chunks/{n}", content, ct).ConfigureAwait(false); - await EnsureSuccessAsync(response, ct).ConfigureAwait(false); - return true; - }, ct).ConfigureAwait(false); - sent += length; - progress?.Report(new UploadProgress(sent, info.Length)); - } - } + await SendChunksAsync(path, info.Length, uploadId, start.ChunkSize, start.Received, progress, ct).ConfigureAwait(false); return await RetryAsync(() => SendAsync(HttpMethod.Post, $"api/v1/uploads/{uploadId}/complete", ProtocolJson.Default.CompleteUploadResponse, ct), ct).ConfigureAwait(false); } + /// + /// Render node: uploads the output of a claimed job in resumable chunks, then completes the job; the server verifies + /// the SHA-256 in and files the render under the sequence's exports (BRIEF §14.7). + /// + public async Task UploadRenderResultAsync(Guid nodeId, Guid jobId, string path, RenderResultRequest result, + IProgress? progress = null, CancellationToken ct = default) + { + var length = new FileInfo(path).Length; + if (length != result.Size) throw new ArgumentException("The result size does not match the file.", nameof(result)); + var start = await RetryAsync(() => SendAsync(HttpMethod.Post, $"api/v1/nodes/{nodeId}/jobs/{jobId}/result", result, + ProtocolJson.Default.RenderResultRequest, ProtocolJson.Default.StartUploadResponse, ct), ct).ConfigureAwait(false); + var uploadId = start.UploadId ?? throw new InvalidOperationException("Server returned no upload id."); + await SendChunksAsync(path, length, uploadId, start.ChunkSize, start.Received, progress, ct).ConfigureAwait(false); + return await RetryAsync(() => SendAsync(HttpMethod.Post, $"api/v1/nodes/{nodeId}/jobs/{jobId}/result/complete", ProtocolJson.Default.RenderDto, ct), ct) + .ConfigureAwait(false); + } + + /// Sends every chunk the server does not have yet; each PUT is idempotent and retried on transient errors. + private async Task SendChunksAsync(string path, long length, Guid uploadId, int chunkSize, IReadOnlyList alreadyReceived, + IProgress? progress, CancellationToken ct) + { + var received = new HashSet(alreadyReceived); + var chunks = (int)((length + chunkSize - 1) / chunkSize); + var buffer = new byte[chunkSize]; + await using var file = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.ReadWrite, 1 << 16, FileOptions.Asynchronous | FileOptions.SequentialScan); + long sent = received.Sum(i => Math.Min(chunkSize, length - (long)i * chunkSize)); + progress?.Report(new UploadProgress(sent, length)); + for (var n = 0; n < chunks; n++) + { + if (received.Contains(n)) continue; + var offset = (long)n * chunkSize; + var size = (int)Math.Min(chunkSize, length - offset); + file.Position = offset; + await file.ReadExactlyAsync(buffer.AsMemory(0, size), ct).ConfigureAwait(false); + await Bandwidth.AcquireAsync(size, ct).ConfigureAwait(false); + var index = n; + await RetryAsync(async () => + { + using var content = new ByteArrayContent(buffer, 0, size); + content.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream"); + using var response = await _http.PutAsync($"api/v1/uploads/{uploadId}/chunks/{index}", content, ct).ConfigureAwait(false); + await EnsureSuccessAsync(response, ct).ConfigureAwait(false); + return true; + }, ct).ConfigureAwait(false); + sent += size; + progress?.Report(new UploadProgress(sent, length)); + } + } + /// Lower-case hex SHA-256 of a file, streamed. public static async Task HashFileAsync(string path, CancellationToken ct = default) { @@ -201,10 +223,22 @@ public sealed class TitanoClient : IDisposable public Task CreateJobAsync(CreateJobRequest request, CancellationToken ct = default) => SendAsync(HttpMethod.Post, "api/v1/jobs", request, ProtocolJson.Default.CreateJobRequest, ProtocolJson.Default.JobDto, ct); + public Task GetJobAsync(Guid id, CancellationToken ct = default) => GetAsync($"api/v1/jobs/{id}", ProtocolJson.Default.JobDto, ct); + public Task CancelJobAsync(Guid id, CancellationToken ct = default) => SendAsync(HttpMethod.Post, $"api/v1/jobs/{id}/cancel", ProtocolJson.Default.JobDto, ct); public Task RetryJobAsync(Guid id, CancellationToken ct = default) => SendAsync(HttpMethod.Post, $"api/v1/jobs/{id}/retry", ProtocolJson.Default.JobDto, ct); + public Task PauseJobAsync(Guid id, CancellationToken ct = default) => SendAsync(HttpMethod.Post, $"api/v1/jobs/{id}/pause", ProtocolJson.Default.JobDto, ct); + + public Task ResumeJobAsync(Guid id, CancellationToken ct = default) => SendAsync(HttpMethod.Post, $"api/v1/jobs/{id}/resume", ProtocolJson.Default.JobDto, ct); + + /// Moves a waiting job up or down the queue: is background, normal or user. + public Task SetJobPriorityAsync(Guid id, string priority, CancellationToken ct = default) => + SendAsync(HttpMethod.Post, $"api/v1/jobs/{id}/priority", new JobPriorityRequest(priority), ProtocolJson.Default.JobPriorityRequest, ProtocolJson.Default.JobDto, ct); + + public Task> ListNodesAsync(CancellationToken ct = default) => GetAsync("api/v1/nodes", ProtocolJson.Default.ListRenderNodeDto, ct); + public Task RegisterNodeAsync(RegisterNodeRequest request, CancellationToken ct = default) => SendAsync(HttpMethod.Post, "api/v1/nodes/register", request, ProtocolJson.Default.RegisterNodeRequest, ProtocolJson.Default.RenderNodeDto, ct); @@ -222,6 +256,10 @@ public sealed class TitanoClient : IDisposable public Task ReportNodeProgressAsync(Guid nodeId, Guid jobId, NodeProgress progress, CancellationToken ct = default) => SendAsync(HttpMethod.Post, $"api/v1/nodes/{nodeId}/jobs/{jobId}/progress", progress, ProtocolJson.Default.NodeProgress, ct); + /// Gives a claimed job back as failed; a 409 means it was cancelled or reassigned meanwhile. + 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); + // ---------------- Events ---------------- /// Server events over WebSocket until cancelled; reconnect is the caller's policy. diff --git a/src/Titano.Protocol/Dtos.cs b/src/Titano.Protocol/Dtos.cs index d841902d..52934196 100644 --- a/src/Titano.Protocol/Dtos.cs +++ b/src/Titano.Protocol/Dtos.cs @@ -5,8 +5,8 @@ namespace Titano.Protocol; /// Error body of every failed API call: { code, message, details } (BRIEF §14.3). public sealed record ApiError(string Code, string Message, string? Details = null); -/// Upload limits announced by the server. -public sealed record ServerLimits(long MaxUploadBytes, int ChunkSizeBytes); +/// Upload and account limits announced by the server. +public sealed record ServerLimits(long MaxUploadBytes, int ChunkSizeBytes, int PasswordMinLength = 10); /// GET /api/v1/server/info. public sealed record ServerInfo( diff --git a/src/Titano.Protocol/Jobs.cs b/src/Titano.Protocol/Jobs.cs index e5655af4..6a6d8e5c 100644 --- a/src/Titano.Protocol/Jobs.cs +++ b/src/Titano.Protocol/Jobs.cs @@ -34,3 +34,27 @@ public sealed record ClaimedJob(JobDto Job, Guid SequenceId, string SettingsJson /// POST /api/v1/nodes/{id}/jobs/{jobId}/progress. public sealed record NodeProgress(long Done, long Total, double? ItemsPerSecond, string? LogLine); + +/// POST /api/v1/jobs/{id}/priority: background, normal or user. +public sealed record JobPriorityRequest(string Priority); + +/// +/// parametersJson of a render job: what to encode. Render nodes claim the job when they have an encoder for +/// at × (BRIEF §14.7). +/// +public sealed record RenderJobParameters(string PresetName, string PresetJson, string Codec, int Width, int Height, bool UseProxies, string? SettingsJson); + +/// POST /api/v1/nodes/{id}/jobs/{jobId}/result: the finished output a node is about to upload in chunks. +public sealed record RenderResultRequest( + string FileName, + long Size, + string Sha256, + string PresetName, + string? Codec, + int Width, + int Height, + double Fps, + double DurationSeconds); + +/// POST /api/v1/nodes/{id}/jobs/{jobId}/failed: the node could not render the job. +public sealed record NodeJobFailure(string Error); diff --git a/src/Titano.Protocol/ProtocolJson.cs b/src/Titano.Protocol/ProtocolJson.cs index 2f3dad46..2db29cac 100644 --- a/src/Titano.Protocol/ProtocolJson.cs +++ b/src/Titano.Protocol/ProtocolJson.cs @@ -45,4 +45,21 @@ namespace Titano.Protocol; [JsonSerializable(typeof(NodeProgress))] [JsonSerializable(typeof(ServerEvent))] [JsonSerializable(typeof(DiscoveryBeacon))] +[JsonSerializable(typeof(ResetPasswordRequest))] +[JsonSerializable(typeof(UserSummaryDto))] +[JsonSerializable(typeof(List))] +[JsonSerializable(typeof(AuditEntryDto))] +[JsonSerializable(typeof(Page))] +[JsonSerializable(typeof(SequenceStatsDto))] +[JsonSerializable(typeof(SequenceDeletePlan))] +[JsonSerializable(typeof(ArchiveSettingsDto))] +[JsonSerializable(typeof(JobPriorityRequest))] +[JsonSerializable(typeof(RenderJobParameters))] +[JsonSerializable(typeof(RenderResultRequest))] +[JsonSerializable(typeof(NodeJobFailure))] +[JsonSerializable(typeof(ServerSettingsDto))] +[JsonSerializable(typeof(LogFileDto))] +[JsonSerializable(typeof(List))] +[JsonSerializable(typeof(LogTailDto))] +[JsonSerializable(typeof(DashboardDto))] public sealed partial class ProtocolJson : JsonSerializerContext; diff --git a/src/Titano.Protocol/Sequences.cs b/src/Titano.Protocol/Sequences.cs index ab3bb730..eaebcc0d 100644 --- a/src/Titano.Protocol/Sequences.cs +++ b/src/Titano.Protocol/Sequences.cs @@ -102,3 +102,26 @@ public sealed record ArchiveStatsDto( int UnverifiedSequences); public sealed record KeyValueCount(string Key, long Count, long Bytes); + +/// GET /api/v1/sequences/{id}/stats: frame totals by format and flagged frames. +public sealed record SequenceStatsDto( + Guid SequenceId, + int FrameCount, + long TotalBytes, + DateTime? FirstCapture, + DateTime? LastCapture, + double? MedianInterval, + IReadOnlyList ByFormat, + long MissingFrames, + long CorruptFrames, + long DuplicateFrames, + long ExcludedFrames); + +/// +/// DELETE /api/v1/sequences/{id}: what the delete does (with ?dryRun=true) or did. The folder is moved +/// to inside the archive, never erased. +/// +public sealed record SequenceDeletePlan(Guid SequenceId, string? Folder, string? TrashFolder, int FrameCount, long TotalBytes, int RenderCount, bool DryRun); + +/// GET/PUT /api/v1/archive/settings (admin). The root path comes from the server configuration. +public sealed record ArchiveSettingsDto(Guid Id, string Name, string RootPath, string FolderTemplate, string FileTemplate, int ProxyLongEdge);