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);