Files
Chronos/src/Titano.Protocol/Client/TitanoClient.cs
T
Claude 7353c17d7b 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
2026-10-02 11:31:07 +00:00

398 lines
22 KiB
C#

using System.Net;
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Net.WebSockets;
using System.Runtime.CompilerServices;
using System.Security.Cryptography;
using System.Text.Json;
using System.Text.Json.Serialization.Metadata;
namespace Titano.Protocol.Client;
/// <summary>Upload progress for one file.</summary>
public readonly record struct UploadProgress(long BytesSent, long BytesTotal);
/// <summary>
/// Typed client for Titano Server API v1 (BRIEF §14.3), used by the desktop client and the uploader.
/// Thread-safe; one instance per server connection.
/// </summary>
public sealed class TitanoClient : IDisposable
{
private readonly HttpClient _http;
private readonly CertificatePinning _pinning;
private string? _token;
public TitanoClient(Uri baseAddress, CertificatePinning pinning, string clientName, HttpMessageHandler? handler = null)
{
_pinning = pinning;
ClientName = clientName;
BaseAddress = baseAddress;
var socketsHandler = handler ?? new SocketsHttpHandler
{
SslOptions = { RemoteCertificateValidationCallback = pinning.Validate },
PooledConnectionLifetime = TimeSpan.FromMinutes(5),
ConnectTimeout = TimeSpan.FromSeconds(10),
AutomaticDecompression = DecompressionMethods.None,
};
_http = new HttpClient(socketsHandler) { BaseAddress = baseAddress, Timeout = Timeout.InfiniteTimeSpan };
_http.DefaultRequestHeaders.Add(ApiVersion.Header, ApiVersion.Current.ToString(System.Globalization.CultureInfo.InvariantCulture));
_http.DefaultRequestHeaders.UserAgent.Add(new ProductInfoHeaderValue("Titano", typeof(TitanoClient).Assembly.GetName().Version?.ToString(3) ?? "0"));
}
public Uri BaseAddress { get; }
public string ClientName { get; }
public CertificatePinning Pinning => _pinning;
/// <summary>Bearer token; set after <see cref="LoginAsync"/> or restored from secure storage.</summary>
public string? Token
{
get => _token;
set
{
_token = value;
_http.DefaultRequestHeaders.Authorization = value is null ? null : new AuthenticationHeaderValue("Bearer", value);
}
}
/// <summary>Shared upload rate limit.</summary>
public BandwidthLimiter Bandwidth { get; } = new();
// ---------------- Server ----------------
/// <summary>Reads server info; throws <see cref="UntrustedCertificateException"/> when the TLS certificate needs confirmation.</summary>
public Task<ServerInfo> GetInfoAsync(CancellationToken ct = default) => GetAsync("api/v1/server/info", ProtocolJson.Default.ServerInfo, ct);
// ---------------- Auth ----------------
public async Task<LoginResponse> LoginAsync(string username, string password, CancellationToken ct = default)
{
var response = await SendAsync(HttpMethod.Post, "api/v1/auth/login", new LoginRequest(username, password, ClientName), ProtocolJson.Default.LoginRequest, ProtocolJson.Default.LoginResponse, ct).ConfigureAwait(false);
Token = response.Token;
return response;
}
public async Task LogoutAsync(CancellationToken ct = default)
{
await SendNoContentAsync(HttpMethod.Post, "api/v1/auth/logout", ct).ConfigureAwait(false);
Token = null;
}
public Task<UserDto> MeAsync(CancellationToken ct = default) => GetAsync("api/v1/auth/me", ProtocolJson.Default.UserDto, ct);
public Task ChangePasswordAsync(string current, string next, CancellationToken ct = default) =>
SendAsync(HttpMethod.Post, "api/v1/auth/password", new ChangePasswordRequest(current, next), ProtocolJson.Default.ChangePasswordRequest, ct);
// ---------------- Sequences ----------------
public Task<Page<SequenceDto>> ListSequencesAsync(string? query = null, string? cursor = null, int limit = 200, CancellationToken ct = default) =>
GetAsync($"api/v1/sequences?limit={limit}{Q("q", query)}{Q("cursor", cursor)}", ProtocolJson.Default.PageSequenceDto, ct);
public Task<SequenceDto> GetSequenceAsync(Guid id, CancellationToken ct = default) => GetAsync($"api/v1/sequences/{id}", ProtocolJson.Default.SequenceDto, ct);
public Task<SequenceDto> CreateSequenceAsync(CreateSequenceRequest request, CancellationToken ct = default) =>
SendAsync(HttpMethod.Post, "api/v1/sequences", request, ProtocolJson.Default.CreateSequenceRequest, ProtocolJson.Default.SequenceDto, ct);
/// <summary>Updates metadata/settings; a 409 <see cref="TitanoApiException"/> means the settings changed on the server.</summary>
public Task<SequenceDto> UpdateSequenceAsync(Guid id, UpdateSequenceRequest request, CancellationToken ct = default) =>
SendAsync(HttpMethod.Patch, $"api/v1/sequences/{id}", request, ProtocolJson.Default.UpdateSequenceRequest, ProtocolJson.Default.SequenceDto, ct);
public Task<SequenceManifest> GetManifestAsync(Guid id, CancellationToken ct = default) =>
GetAsync($"api/v1/sequences/{id}/manifest", ProtocolJson.Default.SequenceManifest, ct);
public Task<Page<FrameDto>> ListFramesAsync(Guid sequenceId, string? cursor = null, int limit = 1000, CancellationToken ct = default) =>
GetAsync($"api/v1/sequences/{sequenceId}/frames?limit={limit}{Q("cursor", cursor)}", ProtocolJson.Default.PageFrameDto, ct);
/// <summary>Streams a frame resource (original, proxy or thumb) to <paramref name="destination"/>, resuming with Range from its current length.</summary>
public async Task DownloadFrameAsync(Guid frameId, string kind, Stream destination, IProgress<long>? progress = null, CancellationToken ct = default)
{
if (kind is not ("original" or "proxy" or "thumb")) throw new ArgumentOutOfRangeException(nameof(kind));
using var request = new HttpRequestMessage(HttpMethod.Get, $"api/v1/frames/{frameId}/{kind}");
if (destination.CanSeek && destination.Length > 0)
{
destination.Seek(0, SeekOrigin.End);
request.Headers.Range = new RangeHeaderValue(destination.Length, null);
}
using var response = await _http.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, ct).ConfigureAwait(false);
await EnsureSuccessAsync(response, ct).ConfigureAwait(false);
if (response.StatusCode == HttpStatusCode.OK && destination.CanSeek) destination.SetLength(0);
await using var body = await response.Content.ReadAsStreamAsync(ct).ConfigureAwait(false);
var buffer = new byte[1 << 16];
long total = 0;
int read;
while ((read = await body.ReadAsync(buffer, ct).ConfigureAwait(false)) > 0)
{
await destination.WriteAsync(buffer.AsMemory(0, read), ct).ConfigureAwait(false);
total += read;
progress?.Report(total);
}
}
// ---------------- Uploads ----------------
/// <summary>
/// Uploads one file with resumable, idempotent chunks; the server verifies the SHA-256 before committing it
/// (BRIEF §14.4). Returns the committed frame id. Transient failures retry with exponential backoff.
/// </summary>
public async Task<CompleteUploadResponse?> UploadFileAsync(
string path,
Guid? sequenceId,
DateTime? capturedAt,
string? sessionKey = null,
string? knownSha256 = null,
IProgress<UploadProgress>? progress = null,
CancellationToken ct = default)
{
var info = new FileInfo(path);
var sha = knownSha256 ?? await HashFileAsync(path, ct).ConfigureAwait(false);
var start = await RetryAsync(() => SendAsync(HttpMethod.Post, "api/v1/uploads",
new StartUploadRequest(sequenceId, info.Name, info.Length, sha, capturedAt, sessionKey),
ProtocolJson.Default.StartUploadRequest, ProtocolJson.Default.StartUploadResponse, ct), ct).ConfigureAwait(false);
if (start.AlreadyExists)
{
progress?.Report(new UploadProgress(info.Length, info.Length));
return start.FrameId is { } existing ? new CompleteUploadResponse(existing, sequenceId ?? Guid.Empty, -1) : null;
}
var uploadId = start.UploadId ?? throw new InvalidOperationException("Server returned no upload id.");
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)
{
await using var file = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.ReadWrite, 1 << 20, FileOptions.Asynchronous | FileOptions.SequentialScan);
var hash = await SHA256.HashDataAsync(file, ct).ConfigureAwait(false);
return Convert.ToHexStringLower(hash);
}
// ---------------- Jobs and render nodes ----------------
public Task<Page<JobDto>> ListJobsAsync(string? state = null, string? cursor = null, CancellationToken ct = default) =>
GetAsync($"api/v1/jobs?limit=200{Q("state", state)}{Q("cursor", cursor)}", ProtocolJson.Default.PageJobDto, ct);
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);
public Task HeartbeatAsync(Guid nodeId, CancellationToken ct = default) => SendNoContentAsync(HttpMethod.Post, $"api/v1/nodes/{nodeId}/heartbeat", ct);
/// <summary>Claims the next render job matching this node; null when there is none.</summary>
public async Task<ClaimedJob?> ClaimAsync(Guid nodeId, CancellationToken ct = default)
{
using var response = await _http.PostAsync($"api/v1/nodes/{nodeId}/claim", null, ct).ConfigureAwait(false);
if (response.StatusCode == HttpStatusCode.NoContent) return null;
await EnsureSuccessAsync(response, ct).ConfigureAwait(false);
return await response.Content.ReadFromJsonAsync(ProtocolJson.Default.ClaimedJob, ct).ConfigureAwait(false);
}
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>
public async IAsyncEnumerable<ServerEvent> EventsAsync([EnumeratorCancellation] CancellationToken ct = default)
{
using var socket = new ClientWebSocket();
socket.Options.RemoteCertificateValidationCallback = _pinning.Validate;
if (_token is not null) socket.Options.SetRequestHeader("Authorization", "Bearer " + _token);
var ws = new UriBuilder(new Uri(BaseAddress, "api/v1/events")) { Scheme = BaseAddress.Scheme == "https" ? "wss" : "ws" }.Uri;
await socket.ConnectAsync(ws, ct).ConfigureAwait(false);
var buffer = new byte[64 * 1024];
using var message = new MemoryStream();
while (socket.State == WebSocketState.Open && !ct.IsCancellationRequested)
{
var result = await socket.ReceiveAsync(buffer, ct).ConfigureAwait(false);
if (result.MessageType == WebSocketMessageType.Close) yield break;
message.Write(buffer, 0, result.Count);
if (!result.EndOfMessage) continue;
ServerEvent? e = null;
try
{
e = JsonSerializer.Deserialize(message.GetBuffer().AsSpan(0, (int)message.Length), ProtocolJson.Default.ServerEvent);
}
catch (JsonException)
{
// Unknown event types from a newer server are ignored.
}
message.SetLength(0);
if (e is not null) yield return e;
}
}
public void Dispose() => _http.Dispose();
// ---------------- Plumbing ----------------
private async Task<T> GetAsync<T>(string url, JsonTypeInfo<T> type, CancellationToken ct)
{
using var response = await SendRawAsync(new HttpRequestMessage(HttpMethod.Get, url), ct).ConfigureAwait(false);
await EnsureSuccessAsync(response, ct).ConfigureAwait(false);
return (await response.Content.ReadFromJsonAsync(type, ct).ConfigureAwait(false))!;
}
private async Task<TResponse> SendAsync<TRequest, TResponse>(HttpMethod method, string url, TRequest body, JsonTypeInfo<TRequest> requestType, JsonTypeInfo<TResponse> responseType, CancellationToken ct)
{
using var request = new HttpRequestMessage(method, url) { Content = JsonContent.Create(body, requestType) };
using var response = await SendRawAsync(request, ct).ConfigureAwait(false);
await EnsureSuccessAsync(response, ct).ConfigureAwait(false);
return (await response.Content.ReadFromJsonAsync(responseType, ct).ConfigureAwait(false))!;
}
private async Task SendAsync<TRequest>(HttpMethod method, string url, TRequest body, JsonTypeInfo<TRequest> requestType, CancellationToken ct)
{
using var request = new HttpRequestMessage(method, url) { Content = JsonContent.Create(body, requestType) };
using var response = await SendRawAsync(request, ct).ConfigureAwait(false);
await EnsureSuccessAsync(response, ct).ConfigureAwait(false);
}
private async Task<TResponse> SendAsync<TResponse>(HttpMethod method, string url, JsonTypeInfo<TResponse> responseType, CancellationToken ct)
{
using var response = await SendRawAsync(new HttpRequestMessage(method, url), ct).ConfigureAwait(false);
await EnsureSuccessAsync(response, ct).ConfigureAwait(false);
return (await response.Content.ReadFromJsonAsync(responseType, ct).ConfigureAwait(false))!;
}
private async Task SendNoContentAsync(HttpMethod method, string url, CancellationToken ct)
{
using var response = await SendRawAsync(new HttpRequestMessage(method, url), ct).ConfigureAwait(false);
await EnsureSuccessAsync(response, ct).ConfigureAwait(false);
}
private async Task<HttpResponseMessage> SendRawAsync(HttpRequestMessage request, CancellationToken ct)
{
using (request)
{
try
{
using var timeout = CancellationTokenSource.CreateLinkedTokenSource(ct);
timeout.CancelAfter(TimeSpan.FromSeconds(100));
return await _http.SendAsync(request, timeout.Token).ConfigureAwait(false);
}
catch (HttpRequestException) when (_pinning.LastRejectedFingerprint is { } fingerprint)
{
throw new UntrustedCertificateException(fingerprint);
}
}
}
private static async Task EnsureSuccessAsync(HttpResponseMessage response, CancellationToken ct)
{
if (response.IsSuccessStatusCode) return;
ApiError error;
try
{
error = await response.Content.ReadFromJsonAsync(ProtocolJson.Default.ApiError, ct).ConfigureAwait(false)
?? new ApiError("http_" + (int)response.StatusCode, response.ReasonPhrase ?? "error");
}
catch (JsonException)
{
error = new ApiError("http_" + (int)response.StatusCode, response.ReasonPhrase ?? "error");
}
catch (NotSupportedException)
{
error = new ApiError("http_" + (int)response.StatusCode, response.ReasonPhrase ?? "error");
}
throw new TitanoApiException(response.StatusCode, error);
}
/// <summary>Retries transient failures 5 times with exponential backoff (1, 2, 4, 8, 16 s).</summary>
private static async Task<T> RetryAsync<T>(Func<Task<T>> action, CancellationToken ct)
{
for (var attempt = 0; ; attempt++)
{
try
{
return await action().ConfigureAwait(false);
}
catch (Exception ex) when (attempt < 5 && !ct.IsCancellationRequested && IsTransient(ex))
{
await Task.Delay(TimeSpan.FromSeconds(1 << attempt), ct).ConfigureAwait(false);
}
}
}
private static bool IsTransient(Exception ex) => ex switch
{
TitanoApiException api => api.IsTransient,
HttpRequestException => true,
TaskCanceledException => true,
IOException => true,
_ => false,
};
private static string Q(string name, string? value) => string.IsNullOrEmpty(value) ? string.Empty : "&" + name + "=" + Uri.EscapeDataString(value);
}