feat(protocol): API v1 contract and typed client

DTOs for auth, users, sequences, frames, manifests, uploads, jobs,
render nodes, events and LAN discovery; TitanoClient with TOFU
certificate pinning, bearer auth, resumable SHA-256-verified chunked
uploads with retry/backoff, shared bandwidth limiter and the event
WebSocket stream.

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 09:41:20 +00:00
1 parent 2944e6ebb5
commit 83d8cd79bd
12 files changed
+751 -11

No files matched your search

+31
View File
@@ -0,0 +1,31 @@
namespace Titano.Protocol;
/// <summary><c>POST /api/v1/auth/login</c>. <see cref="Cookie"/> = true asks for an HttpOnly session cookie (web admin).</summary>
public sealed record LoginRequest(string Username, string Password, string ClientName, bool Cookie = false);
public sealed record LoginResponse(string? Token, UserDto User, bool MustChangePassword, DateTimeOffset ExpiresAt);
/// <summary><c>POST /api/v1/auth/password</c>.</summary>
public sealed record ChangePasswordRequest(string CurrentPassword, string NewPassword);
public sealed record UserDto(
Guid Id,
string Username,
string? DisplayName,
string Role,
long Permissions,
long QuotaBytes,
long UsedBytes,
bool Disabled,
bool MustChangePassword,
DateTimeOffset Created,
DateTimeOffset? LastLogin);
/// <summary><c>POST /api/v1/users</c> (admin).</summary>
public sealed record CreateUserRequest(string Username, string? DisplayName, string Role, long QuotaBytes, string? Password, bool AllowRenderNode);
/// <summary><c>PATCH /api/v1/users/{id}</c> (admin); null fields stay unchanged.</summary>
public sealed record UpdateUserRequest(string? DisplayName, string? Role, long? QuotaBytes, bool? Disabled, bool? AllowRenderNode);
/// <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);
@@ -0,0 +1,45 @@
using System.Diagnostics;
namespace Titano.Protocol.Client;
/// <summary>Token bucket shared by concurrent uploads (Uploader "Limit … MB/s"). 0 = unlimited.</summary>
public sealed class BandwidthLimiter
{
private readonly Lock _gate = new();
private readonly Stopwatch _clock = Stopwatch.StartNew();
private double _tokens;
private double _last;
private long _bytesPerSecond;
public BandwidthLimiter(long bytesPerSecond = 0) => BytesPerSecond = bytesPerSecond;
public long BytesPerSecond
{
get => Interlocked.Read(ref _bytesPerSecond);
set => Interlocked.Exchange(ref _bytesPerSecond, Math.Max(0, value));
}
/// <summary>Waits until <paramref name="bytes"/> may be sent.</summary>
public async ValueTask AcquireAsync(int bytes, CancellationToken cancellationToken)
{
while (true)
{
var rate = BytesPerSecond;
if (rate == 0) return;
TimeSpan wait;
lock (_gate)
{
var now = _clock.Elapsed.TotalSeconds;
_tokens = Math.Min(rate, _tokens + (now - _last) * rate);
_last = now;
if (_tokens >= bytes || _tokens >= rate)
{
_tokens -= bytes;
return;
}
wait = TimeSpan.FromSeconds(Math.Min(1.0, (bytes - _tokens) / rate));
}
await Task.Delay(wait, cancellationToken).ConfigureAwait(false);
}
}
}
@@ -0,0 +1,34 @@
using System.Net.Security;
using System.Security.Cryptography;
using System.Security.Cryptography.X509Certificates;
namespace Titano.Protocol.Client;
/// <summary>
/// Trust-on-first-use certificate validation: a certificate is accepted when it chains to a trusted root or when
/// its SHA-256 fingerprint is in the caller's trusted set. The last unknown fingerprint is remembered so the UI can
/// ask the user once and add it.
/// </summary>
public sealed class CertificatePinning(IEnumerable<string> trustedFingerprints)
{
private readonly HashSet<string> _trusted = new(trustedFingerprints.Select(Normalize), StringComparer.Ordinal);
public string? LastRejectedFingerprint { get; private set; }
public void Trust(string fingerprint) => _trusted.Add(Normalize(fingerprint));
public bool Validate(object sender, X509Certificate? certificate, X509Chain? chain, SslPolicyErrors errors)
{
if (certificate is null) return false;
if (errors == SslPolicyErrors.None) return true;
var fingerprint = Fingerprint(certificate);
if (_trusted.Contains(fingerprint)) return true;
LastRejectedFingerprint = fingerprint;
return false;
}
public static string Fingerprint(X509Certificate certificate) =>
string.Join(':', certificate.GetCertHash(HashAlgorithmName.SHA256).Select(b => b.ToString("X2", System.Globalization.CultureInfo.InvariantCulture)));
private static string Normalize(string fingerprint) => fingerprint.Replace(" ", string.Empty, StringComparison.Ordinal).ToUpperInvariant();
}
@@ -0,0 +1,23 @@
using System.Net;
namespace Titano.Protocol.Client;
/// <summary>A non-success API response carrying the server's <see cref="ApiError"/>.</summary>
public sealed class TitanoApiException(HttpStatusCode status, ApiError error)
: Exception($"{(int)status} {error.Code}: {error.Message}")
{
public HttpStatusCode Status { get; } = status;
public ApiError Error { get; } = error;
/// <summary>True for errors worth retrying (server busy, gateway, timeout).</summary>
public bool IsTransient => Status is HttpStatusCode.RequestTimeout or HttpStatusCode.TooManyRequests
or HttpStatusCode.BadGateway or HttpStatusCode.ServiceUnavailable or HttpStatusCode.GatewayTimeout;
}
/// <summary>The server presented a certificate whose fingerprint is not trusted yet (trust-on-first-use, BRIEF §12.7).</summary>
public sealed class UntrustedCertificateException(string fingerprint)
: Exception("Server certificate is not trusted: " + fingerprint)
{
/// <summary>SHA-256 fingerprint (XX:XX:…) to show the user before trusting it.</summary>
public string Fingerprint { get; } = fingerprint;
}
+359
View File
@@ -0,0 +1,359 @@
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.");
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));
}
}
return await RetryAsync(() => SendAsync<CompleteUploadResponse>(HttpMethod.Post, $"api/v1/uploads/{uploadId}/complete", ProtocolJson.Default.CompleteUploadResponse, ct), ct).ConfigureAwait(false);
}
/// <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> 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<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);
// ---------------- 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);
}
+31
View File
@@ -0,0 +1,31 @@
using System.Text;
using System.Text.Json;
namespace Titano.Protocol;
/// <summary>
/// LAN discovery (TITANO_DISCOVERY): the server broadcasts a small UDP beacon on port 48300 every few seconds;
/// clients listen and offer "Studio NAS found on this network" on first run.
/// </summary>
public sealed record DiscoveryBeacon(string Name, string Version, int HttpPort, int HttpsPort, string? TlsFingerprint)
{
public const int Port = 48300;
private const string Magic = "TITANO1 ";
public byte[] ToBytes() => Encoding.UTF8.GetBytes(Magic + JsonSerializer.Serialize(this, ProtocolJson.Default.DiscoveryBeacon));
public static DiscoveryBeacon? TryParse(ReadOnlySpan<byte> datagram)
{
if (datagram.Length > 2048) return null;
var text = Encoding.UTF8.GetString(datagram);
if (!text.StartsWith(Magic, StringComparison.Ordinal)) return null;
try
{
return JsonSerializer.Deserialize(text[Magic.Length..], ProtocolJson.Default.DiscoveryBeacon);
}
catch (JsonException)
{
return null;
}
}
}
-11
View File
@@ -20,14 +20,3 @@ public sealed record ServerInfo(
/// <summary><c>GET /health</c>.</summary> /// <summary><c>GET /health</c>.</summary>
public sealed record HealthStatus(string Status, string Version, IReadOnlyDictionary<string, string> Checks); public sealed record HealthStatus(string Status, string Version, IReadOnlyDictionary<string, string> Checks);
/// <summary>Source-generated JSON contracts shared by server and clients (camelCase, enums as strings).</summary>
[JsonSourceGenerationOptions(
PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
UseStringEnumConverter = true)]
[JsonSerializable(typeof(ApiError))]
[JsonSerializable(typeof(ServerInfo))]
[JsonSerializable(typeof(HealthStatus))]
[JsonSerializable(typeof(Dictionary<string, string>))]
public sealed partial class ProtocolJson : JsonSerializerContext;
+22
View File
@@ -0,0 +1,22 @@
using System.Text.Json.Serialization;
namespace Titano.Protocol;
/// <summary>
/// Messages pushed on <c>WS /api/v1/events</c>. Each frame is one JSON object with a <c>type</c> discriminator:
/// jobProgress, jobState, sequenceChanged, cardEvent, nodeState.
/// </summary>
[JsonPolymorphic(TypeDiscriminatorPropertyName = "type")]
[JsonDerivedType(typeof(JobProgressEvent), "jobProgress")]
[JsonDerivedType(typeof(JobStateEvent), "jobState")]
[JsonDerivedType(typeof(SequenceChangedEvent), "sequenceChanged")]
[JsonDerivedType(typeof(NodeStateEvent), "nodeState")]
public abstract record ServerEvent;
public sealed record JobProgressEvent(Guid JobId, long Done, long Total, double? ItemsPerSecond, double? EtaSeconds) : ServerEvent;
public sealed record JobStateEvent(Guid JobId, string State, string? Error) : ServerEvent;
public sealed record SequenceChangedEvent(Guid SequenceId, string Change, int FramesVersion, int SettingsVersion) : ServerEvent;
public sealed record NodeStateEvent(Guid NodeId, string ClientName, string State) : ServerEvent;
+36
View File
@@ -0,0 +1,36 @@
namespace Titano.Protocol;
public sealed record JobDto(
Guid Id,
string Kind,
IReadOnlyList<Guid> TargetIds,
string? TargetLabel,
string State,
string Priority,
long ProgressDone,
long ProgressTotal,
double? ItemsPerSecond,
double? EtaSeconds,
string? LogTail,
string? NodeId,
int Attempts,
string? Error,
DateTimeOffset Created,
DateTimeOffset? Started,
DateTimeOffset? Finished);
/// <summary><c>POST /api/v1/jobs</c>: kind = render, deep-analyse, proxies, thumbs, verify, scan, rebuild, maintenance…</summary>
public sealed record CreateJobRequest(string Kind, IReadOnlyList<Guid> Target, string? ParametersJson);
/// <summary><c>POST /api/v1/nodes/register</c>: a client offers its GPU encoders (BRIEF §14.7).</summary>
public sealed record RegisterNodeRequest(string ClientName, IReadOnlyList<NodeEncoder> Encoders, int MaxWidth, int MaxHeight);
public sealed record NodeEncoder(string Codec, string Name, bool Hardware, bool TenBit);
public sealed record RenderNodeDto(Guid Id, string ClientName, string Username, IReadOnlyList<NodeEncoder> Encoders, DateTimeOffset LastHeartbeat, string State);
/// <summary><c>POST /api/v1/nodes/{id}/claim</c>: the job and everything needed to run it, or 204 when none matches.</summary>
public sealed record ClaimedJob(JobDto Job, Guid SequenceId, string SettingsJson, string PresetJson, bool UseProxies, IReadOnlyList<ManifestFrame> Frames);
/// <summary><c>POST /api/v1/nodes/{id}/jobs/{jobId}/progress</c>.</summary>
public sealed record NodeProgress(long Done, long Total, double? ItemsPerSecond, string? LogLine);
+48
View File
@@ -0,0 +1,48 @@
using System.Text.Json.Serialization;
namespace Titano.Protocol;
/// <summary>Source-generated JSON contracts shared by server and clients (camelCase, enums as strings).</summary>
[JsonSourceGenerationOptions(
PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
PropertyNameCaseInsensitive = true,
UseStringEnumConverter = true)]
[JsonSerializable(typeof(ApiError))]
[JsonSerializable(typeof(ServerInfo))]
[JsonSerializable(typeof(HealthStatus))]
[JsonSerializable(typeof(Dictionary<string, string>))]
[JsonSerializable(typeof(LoginRequest))]
[JsonSerializable(typeof(LoginResponse))]
[JsonSerializable(typeof(ChangePasswordRequest))]
[JsonSerializable(typeof(UserDto))]
[JsonSerializable(typeof(List<UserDto>))]
[JsonSerializable(typeof(CreateUserRequest))]
[JsonSerializable(typeof(UpdateUserRequest))]
[JsonSerializable(typeof(TemporaryPasswordResponse))]
[JsonSerializable(typeof(SequenceDto))]
[JsonSerializable(typeof(Page<SequenceDto>))]
[JsonSerializable(typeof(CreateSequenceRequest))]
[JsonSerializable(typeof(UpdateSequenceRequest))]
[JsonSerializable(typeof(FrameDto))]
[JsonSerializable(typeof(Page<FrameDto>))]
[JsonSerializable(typeof(SequenceManifest))]
[JsonSerializable(typeof(RenderDto))]
[JsonSerializable(typeof(List<RenderDto>))]
[JsonSerializable(typeof(ArchiveStatsDto))]
[JsonSerializable(typeof(StartUploadRequest))]
[JsonSerializable(typeof(StartUploadResponse))]
[JsonSerializable(typeof(ChunkReceived))]
[JsonSerializable(typeof(CompleteUploadResponse))]
[JsonSerializable(typeof(UploadState))]
[JsonSerializable(typeof(JobDto))]
[JsonSerializable(typeof(Page<JobDto>))]
[JsonSerializable(typeof(CreateJobRequest))]
[JsonSerializable(typeof(RegisterNodeRequest))]
[JsonSerializable(typeof(RenderNodeDto))]
[JsonSerializable(typeof(List<RenderNodeDto>))]
[JsonSerializable(typeof(ClaimedJob))]
[JsonSerializable(typeof(NodeProgress))]
[JsonSerializable(typeof(ServerEvent))]
[JsonSerializable(typeof(DiscoveryBeacon))]
public sealed partial class ProtocolJson : JsonSerializerContext;
+104
View File
@@ -0,0 +1,104 @@
namespace Titano.Protocol;
/// <summary>Sequence summary for lists (BRIEF §12.2 card data).</summary>
public sealed record SequenceDto(
Guid Id,
string? Title,
string DisplayTitle,
string Folder,
string? CameraMake,
string? CameraModel,
string? Lens,
DateTime? FirstCapture,
DateTime? LastCapture,
int FrameCount,
double? MedianInterval,
long TotalBytes,
long Status,
int RenderedCount,
Guid? HeroFrameId,
IReadOnlyList<string> Tags,
int Rating,
string? Notes,
int SettingsVersion,
int FramesVersion,
int WarningCount,
Guid? OwnerUserId,
DateTimeOffset UpdatedAt);
/// <summary>A page of results with an opaque keyset cursor; null cursor = last page.</summary>
public sealed record Page<T>(IReadOnlyList<T> Items, string? NextCursor, long? Total);
/// <summary><c>POST /api/v1/sequences</c>.</summary>
public sealed record CreateSequenceRequest(string? Title, string? CameraHint);
/// <summary><c>PATCH /api/v1/sequences/{id}</c>. <see cref="ExpectedSettingsVersion"/> enables conflict detection (409).</summary>
public sealed record UpdateSequenceRequest(
string? Title,
IReadOnlyList<string>? Tags,
int? Rating,
string? Notes,
string? SettingsJson,
int? ExpectedSettingsVersion);
public sealed record FrameDto(
Guid Id,
Guid SequenceId,
int Index,
string FileName,
long Size,
string? Sha256,
DateTime? CapturedAt,
int? UtcOffsetMinutes,
double? ExposureTime,
double? FNumber,
int? Iso,
double? FocalLength,
int Orientation,
int Width,
int Height,
string Format,
long Flags);
/// <summary><c>GET /api/v1/sequences/{id}/manifest</c>: what a client needs to diff a sequence (BRIEF §14.5).</summary>
public sealed record SequenceManifest(
Guid SequenceId,
int FramesVersion,
int SettingsVersion,
string? SettingsJson,
IReadOnlyList<string> Tags,
IReadOnlyList<ManifestFrame> Frames,
IReadOnlyList<RenderDto> Renders);
public sealed record ManifestFrame(Guid Id, int Index, string FileName, long Size, string Sha256, bool HasProxy, bool HasThumb);
public sealed record RenderDto(
Guid Id,
string PresetName,
string? Codec,
int Width,
int Height,
double Fps,
double DurationSeconds,
long Bytes,
DateTimeOffset Created,
string? ProducedBy);
/// <summary>Aggregates for the archive dashboard and the admin panel.</summary>
public sealed record ArchiveStatsDto(
long Sequences,
long Photos,
long Bytes,
long FreeBytes,
long CapacityBytes,
int Cameras,
int? FirstYear,
int? LastYear,
IReadOnlyList<KeyValueCount> ByYear,
IReadOnlyList<KeyValueCount> ByMonth,
IReadOnlyList<KeyValueCount> ByCamera,
IReadOnlyList<KeyValueCount> ByFormat,
int SequencesWithoutProxies,
int UnverifiedSequences);
public sealed record KeyValueCount(string Key, long Count, long Bytes);
+18
View File
@@ -0,0 +1,18 @@
namespace Titano.Protocol;
/// <summary>
/// <c>POST /api/v1/uploads</c> (BRIEF §14.4). The client hashes the file first; when the server already holds that
/// SHA-256 it answers 200 with <see cref="StartUploadResponse.AlreadyExists"/> and no upload is needed.
/// </summary>
public sealed record StartUploadRequest(Guid? SequenceId, string FileName, long Size, string Sha256, DateTime? CapturedAt, string? SessionKey);
public sealed record StartUploadResponse(Guid? UploadId, int ChunkSize, IReadOnlyList<int> Received, bool AlreadyExists, Guid? FrameId);
/// <summary><c>PUT /api/v1/uploads/{id}/chunks/{n}</c> response.</summary>
public sealed record ChunkReceived(int Index, IReadOnlyList<int> Received);
/// <summary><c>POST /api/v1/uploads/{id}/complete</c> response: the committed frame.</summary>
public sealed record CompleteUploadResponse(Guid FrameId, Guid SequenceId, int Index);
/// <summary><c>GET /api/v1/uploads/{id}</c>: resume state.</summary>
public sealed record UploadState(Guid UploadId, string FileName, long Size, string Sha256, int ChunkSize, IReadOnlyList<int> Received, string State);