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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 11:31:07 +00:00
1 parent 9a38057169
commit 7353c17d7b
7 files changed
+203 -30

No files matched your search

+53
View File
@@ -0,0 +1,53 @@
namespace Titano.Protocol;
/// <summary>
/// <c>GET/PUT /api/v1/server/settings</c> (admin): the editable part of the server configuration. Settings named in
/// <see cref="Locked"/> come from environment variables and cannot be changed here; <see cref="RestartRequired"/> says
/// that saved values (ports, TLS, workers, chunk size) wait for a restart.
/// </summary>
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<string> Locked,
bool RestartRequired);
/// <summary>A server log file (<c>GET /api/v1/logs/files</c>).</summary>
public sealed record LogFileDto(string Name, long Size, DateTimeOffset Modified);
/// <summary>The last lines of the current server log (<c>GET /api/v1/logs</c>).</summary>
public sealed record LogTailDto(string File, IReadOnlyList<string> Lines);
/// <summary>Jobs per state; done and failed count today's (UTC) jobs.</summary>
public sealed record JobCountsDto(int Queued, int Running, int Paused, int DoneToday, int FailedToday);
/// <summary>Frames committed by uploads on one UTC day.</summary>
public sealed record UploadDayDto(DateOnly Day, long Frames, long Bytes);
/// <summary><c>GET /api/v1/server/dashboard</c> (admin): everything the dashboard page shows in one call (BRIEF §14.8).</summary>
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<RenderNodeDto> Nodes,
IReadOnlyList<UploadDayDto> Uploads,
IReadOnlyList<AuditEntryDto> Activity,
IReadOnlyList<JobDto> ActiveJobs);
+18
View File
@@ -29,3 +29,21 @@ public sealed record UpdateUserRequest(string? DisplayName, string? Role, long?
/// <summary>Response of <c>POST /api/v1/users</c> and <c>/users/{id}/reset-password</c>: a temporary password shown once.</summary>
public sealed record TemporaryPasswordResponse(UserDto User, string TemporaryPassword);
/// <summary><c>POST /api/v1/users/{id}/reset-password</c> (admin); without a password the server generates one.</summary>
public sealed record ResetPasswordRequest(string? Password);
/// <summary>One row of the admin user list: the account plus when and from which client it was last used.</summary>
public sealed record UserSummaryDto(UserDto User, DateTimeOffset? LastSeen, string? LastClient, long UploadsLast30Days);
/// <summary>One audit log entry (who did what to which user, sequence or setting).</summary>
public sealed record AuditEntryDto(
Guid Id,
DateTimeOffset At,
Guid? UserId,
string? Username,
string Action,
string? TargetKind,
string? TargetId,
string? Details,
string? RemoteAddress);
+66 -28
View File
@@ -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<int>(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<CompleteUploadResponse>(HttpMethod.Post, $"api/v1/uploads/{uploadId}/complete", ProtocolJson.Default.CompleteUploadResponse, ct), ct).ConfigureAwait(false);
}
/// <summary>
/// Render node: uploads the output of a claimed job in resumable chunks, then completes the job; the server verifies
/// the SHA-256 in <paramref name="result"/> and files the render under the sequence's exports (BRIEF §14.7).
/// </summary>
public async Task<RenderDto> UploadRenderResultAsync(Guid nodeId, Guid jobId, string path, RenderResultRequest result,
IProgress<UploadProgress>? 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<RenderDto>(HttpMethod.Post, $"api/v1/nodes/{nodeId}/jobs/{jobId}/result/complete", ProtocolJson.Default.RenderDto, ct), ct)
.ConfigureAwait(false);
}
/// <summary>Sends every chunk the server does not have yet; each PUT is idempotent and retried on transient errors.</summary>
private async Task SendChunksAsync(string path, long length, Guid uploadId, int chunkSize, IReadOnlyList<int> alreadyReceived,
IProgress<UploadProgress>? progress, CancellationToken ct)
{
var received = new HashSet<int>(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));
}
}
/// <summary>Lower-case hex SHA-256 of a file, streamed.</summary>
public static async Task<string> HashFileAsync(string path, CancellationToken ct = default)
{
@@ -201,10 +223,22 @@ public sealed class TitanoClient : IDisposable
public Task<JobDto> CreateJobAsync(CreateJobRequest request, CancellationToken ct = default) =>
SendAsync(HttpMethod.Post, "api/v1/jobs", request, ProtocolJson.Default.CreateJobRequest, ProtocolJson.Default.JobDto, ct);
public Task<JobDto> GetJobAsync(Guid id, CancellationToken ct = default) => GetAsync($"api/v1/jobs/{id}", ProtocolJson.Default.JobDto, ct);
public Task<JobDto> CancelJobAsync(Guid id, CancellationToken ct = default) => SendAsync<JobDto>(HttpMethod.Post, $"api/v1/jobs/{id}/cancel", ProtocolJson.Default.JobDto, ct);
public Task<JobDto> RetryJobAsync(Guid id, CancellationToken ct = default) => SendAsync<JobDto>(HttpMethod.Post, $"api/v1/jobs/{id}/retry", ProtocolJson.Default.JobDto, ct);
public Task<JobDto> PauseJobAsync(Guid id, CancellationToken ct = default) => SendAsync<JobDto>(HttpMethod.Post, $"api/v1/jobs/{id}/pause", ProtocolJson.Default.JobDto, ct);
public Task<JobDto> ResumeJobAsync(Guid id, CancellationToken ct = default) => SendAsync<JobDto>(HttpMethod.Post, $"api/v1/jobs/{id}/resume", ProtocolJson.Default.JobDto, ct);
/// <summary>Moves a waiting job up or down the queue: <paramref name="priority"/> is background, normal or user.</summary>
public Task<JobDto> 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<List<RenderNodeDto>> ListNodesAsync(CancellationToken ct = default) => GetAsync("api/v1/nodes", ProtocolJson.Default.ListRenderNodeDto, ct);
public Task<RenderNodeDto> 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);
/// <summary>Gives a claimed job back as failed; a 409 means it was cancelled or reassigned meanwhile.</summary>
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 ----------------
/// <summary>Server events over WebSocket until cancelled; reconnect is the caller's policy.</summary>
+2 -2
View File
@@ -5,8 +5,8 @@ namespace Titano.Protocol;
/// <summary>Error body of every failed API call: <c>{ code, message, details }</c> (BRIEF §14.3).</summary>
public sealed record ApiError(string Code, string Message, string? Details = null);
/// <summary>Upload limits announced by the server.</summary>
public sealed record ServerLimits(long MaxUploadBytes, int ChunkSizeBytes);
/// <summary>Upload and account limits announced by the server.</summary>
public sealed record ServerLimits(long MaxUploadBytes, int ChunkSizeBytes, int PasswordMinLength = 10);
/// <summary><c>GET /api/v1/server/info</c>.</summary>
public sealed record ServerInfo(
+24
View File
@@ -34,3 +34,27 @@ public sealed record ClaimedJob(JobDto Job, Guid SequenceId, string SettingsJson
/// <summary><c>POST /api/v1/nodes/{id}/jobs/{jobId}/progress</c>.</summary>
public sealed record NodeProgress(long Done, long Total, double? ItemsPerSecond, string? LogLine);
/// <summary><c>POST /api/v1/jobs/{id}/priority</c>: background, normal or user.</summary>
public sealed record JobPriorityRequest(string Priority);
/// <summary>
/// <c>parametersJson</c> of a render job: what to encode. Render nodes claim the job when they have an encoder for
/// <see cref="Codec"/> at <see cref="Width"/> × <see cref="Height"/> (BRIEF §14.7).
/// </summary>
public sealed record RenderJobParameters(string PresetName, string PresetJson, string Codec, int Width, int Height, bool UseProxies, string? SettingsJson);
/// <summary><c>POST /api/v1/nodes/{id}/jobs/{jobId}/result</c>: the finished output a node is about to upload in chunks.</summary>
public sealed record RenderResultRequest(
string FileName,
long Size,
string Sha256,
string PresetName,
string? Codec,
int Width,
int Height,
double Fps,
double DurationSeconds);
/// <summary><c>POST /api/v1/nodes/{id}/jobs/{jobId}/failed</c>: the node could not render the job.</summary>
public sealed record NodeJobFailure(string Error);
+17
View File
@@ -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<UserSummaryDto>))]
[JsonSerializable(typeof(AuditEntryDto))]
[JsonSerializable(typeof(Page<AuditEntryDto>))]
[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<LogFileDto>))]
[JsonSerializable(typeof(LogTailDto))]
[JsonSerializable(typeof(DashboardDto))]
public sealed partial class ProtocolJson : JsonSerializerContext;
+23
View File
@@ -102,3 +102,26 @@ public sealed record ArchiveStatsDto(
int UnverifiedSequences);
public sealed record KeyValueCount(string Key, long Count, long Bytes);
/// <summary><c>GET /api/v1/sequences/{id}/stats</c>: frame totals by format and flagged frames.</summary>
public sealed record SequenceStatsDto(
Guid SequenceId,
int FrameCount,
long TotalBytes,
DateTime? FirstCapture,
DateTime? LastCapture,
double? MedianInterval,
IReadOnlyList<KeyValueCount> ByFormat,
long MissingFrames,
long CorruptFrames,
long DuplicateFrames,
long ExcludedFrames);
/// <summary>
/// <c>DELETE /api/v1/sequences/{id}</c>: what the delete does (with <c>?dryRun=true</c>) or did. The folder is moved
/// to <see cref="TrashFolder"/> inside the archive, never erased.
/// </summary>
public sealed record SequenceDeletePlan(Guid SequenceId, string? Folder, string? TrashFolder, int FrameCount, long TotalBytes, int RenderCount, bool DryRun);
/// <summary><c>GET/PUT /api/v1/archive/settings</c> (admin). The root path comes from the server configuration.</summary>
public sealed record ArchiveSettingsDto(Guid Id, string Name, string RootPath, string FolderTemplate, string FileTemplate, int ProxyLongEdge);