refactor!: rename Titano to Chronos and move CI and releases to Gitea (#6)
CI / Build and test (push) Successful in 8m14s
CI / Windows tests and installer (push) Skipped
CI / YAML check (push) Successful in 7s
Release / Build, test and publish (push) Successful in 13m19s
CI / PostgreSQL 16 integration (push) Successful in 4m49s
CI / PostgreSQL 17 integration (push) Successful in 5m28s
CI / Docker image (push) Successful in 53s
Release / Server image (push) Failing after 10s

The owner renamed the product and moved the repository to the self-hosted
Gitea (https://gitea.encke-hake.ts.net/BalboSoft/Chronos) for more control,
and asked for Actions and a first automatic release with the server package
and the Windows exe (docs/requests/2026-10-23-chronos-gitea.md).

- Chronos everywhere: a byte-exact rename of contents and paths, then a
  per-language review of the forms the old name's ending had dictated.
- Gitea instead of GitHub: the update check, licence, issue and support
  links read ChronosReleasesUrl; the update check takes the highest stable
  version, offers a pre-release build its final release and reports a
  repository it cannot see as a failed check. EULA, security policy and
  Gitea issue forms live at the repository root.
- Gitea Actions for the Linux act_runner (.gitea/workflows): CI, release,
  nightly image and performance gates in the .NET SDK container with git
  checkout and the system SQLite. The release cross-compiles the Windows
  programs, checks their icon, version and DPI manifest, packs installers
  and zips, publishes the Gitea release and pushes the server image
  (REGISTRY_TOKEN). Windows-only tests run in an opt-in job on a Windows
  runner (WINDOWS_RUNNER).
- New Chronos.Tools commands: zip, gitea-release, postgres-ci (replaces the
  docker-exec script, which Gitea's service containers do not allow; the
  throw-away server runs without durability) and pe-check.
- Timed tests take their budget from TestTiming (CHRONOS_TEST_TIME_FACTOR,
  3 on the shared runner; the weekly performance gates keep theirs).

BREAKING CHANGE: programs, settings, data folders, file types, environment
variables and the Docker image use the new name; nothing is migrated from
Titano, which never had a release.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Alberto Balbo <alberto.balbo.96@gmail.com>
This commit was merged in pull request #6.
This commit is contained in:
Alby96andClaude Opus 5.5 authored and Alby96 committed 2026-10-23 12:45:18 +02:00
1 parent c99842cc86
commit f2b58522b9
1801 files changed
+11804 -10676

No files matched your search

+67
View File
@@ -0,0 +1,67 @@
namespace Chronos.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, chunk size, job history) wait for a restart. <see cref="ProxyWarning"/> is set in
/// responses when TLS mode is proxy and the request did not come through a trusted proxy over HTTPS (ignored when saving).
/// <see cref="Parallelism"/> is how many photos the running job processes at once (jobs run one at a time), and
/// <see cref="PriorityQueue"/> with <see cref="JobPriorities"/> the priority queue (owner review 1); both apply at once.
/// </summary>
public sealed record ServerSettingsDto(
string ServerName,
int HttpPort,
int HttpsPort,
string TlsMode,
string? TlsCert,
string? TlsKey,
string Language,
int Parallelism,
bool PriorityQueue,
IReadOnlyList<JobPriorityDto> JobPriorities,
bool Discovery,
long MaxUploadBytes,
int ChunkSizeBytes,
int JobHistoryDays,
int TokenLifetimeDays,
int UploadRetentionHours,
IReadOnlyList<string> Locked,
bool RestartRequired,
bool ProxyWarning);
/// <summary>A kind of job (<c>render</c>) and its level in the server's priority queue: <c>high</c>, <c>normal</c> or <c>low</c>.</summary>
public sealed record JobPriorityDto(string Kind, string Level);
/// <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).
/// <see cref="ProxyWarning"/>: TLS mode is proxy and this request did not come through a trusted proxy over HTTPS.
/// </summary>
public sealed record DashboardDto(
string ServerName,
string Version,
long UptimeSeconds,
string Database,
string TlsMode,
bool Discovery,
int Users,
ArchiveStatsDto Archive,
JobCountsDto Jobs,
int Parallelism,
bool PriorityQueue,
IReadOnlyList<RenderNodeDto> Nodes,
IReadOnlyList<UploadDayDto> Uploads,
IReadOnlyList<AuditEntryDto> Activity,
IReadOnlyList<JobDto> ActiveJobs,
bool ProxyWarning);
+8
View File
@@ -0,0 +1,8 @@
namespace Chronos.Protocol;
/// <summary>API version negotiated through the <c>X-Chronos-Api</c> header.</summary>
public static class ApiVersion
{
public const int Current = 1;
public const string Header = "X-Chronos-Api";
}
+49
View File
@@ -0,0 +1,49 @@
namespace Chronos.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);
/// <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);
@@ -0,0 +1,6 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<RootNamespace>Chronos.Protocol</RootNamespace>
</PropertyGroup>
</Project>
@@ -0,0 +1,45 @@
using System.Diagnostics;
namespace Chronos.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,48 @@
using System.Net.Security;
using System.Security.Cryptography;
using System.Security.Cryptography.X509Certificates;
namespace Chronos.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 fingerprint rejected by the latest handshake is
/// remembered (and cleared by the next accepted one) 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);
private readonly Lock _gate = new();
private string? _lastRejected;
public string? LastRejectedFingerprint
{
get { lock (_gate) return _lastRejected; }
}
public void Trust(string fingerprint)
{
lock (_gate)
{
_trusted.Add(Normalize(fingerprint));
_lastRejected = null;
}
}
public bool Validate(object sender, X509Certificate? certificate, X509Chain? chain, SslPolicyErrors errors)
{
if (certificate is null) return false;
var fingerprint = errors == SslPolicyErrors.None ? null : Fingerprint(certificate);
lock (_gate)
{
var accepted = fingerprint is null || _trusted.Contains(fingerprint);
_lastRejected = accepted ? null : fingerprint;
return accepted;
}
}
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 Chronos.Protocol.Client;
/// <summary>A non-success API response carrying the server's <see cref="ApiError"/>.</summary>
public sealed class ChronosApiException(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;
}
@@ -0,0 +1,482 @@
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 Chronos.Protocol.Client;
/// <summary>Upload progress for one file.</summary>
public readonly record struct UploadProgress(long BytesSent, long BytesTotal);
/// <summary>
/// Typed client for Chronos 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 ChronosClient : IDisposable
{
private readonly HttpClient _http;
private readonly CertificatePinning _pinning;
private string? _token;
public ChronosClient(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("Chronos", typeof(ChronosClient).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="ChronosApiException"/> 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);
/// <summary>The full deep-analysis report of a sequence (<c>analysis.json</c>); null when it was never deep-analysed.</summary>
public async Task<string?> GetAnalysisReportAsync(Guid sequenceId, CancellationToken ct = default)
{
using var response = await SendRawAsync(new HttpRequestMessage(HttpMethod.Get, $"api/v1/sequences/{sequenceId}/analysis/report"), ct).ConfigureAwait(false);
try
{
await EnsureSuccessAsync(response, ct).ConfigureAwait(false);
}
catch (ChronosApiException ex) when (ex.Status == HttpStatusCode.NotFound && ex.Error.Details == "analysis")
{
return null;
}
return await response.Content.ReadAsStringAsync(ct).ConfigureAwait(false);
}
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);
}
}
/// <summary>
/// Sends the proxy of a frame whose original the server cannot decode (<see cref="ManifestFrame.WantsProxy"/>): a JPEG
/// with the frame's capture time in its Exif, replacing the server's. A transient failure is retried.
/// </summary>
public Task UploadProxyAsync(Guid frameId, byte[] jpeg, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(jpeg);
return RetryAsync(async () =>
{
await Bandwidth.AcquireAsync(jpeg.Length, ct).ConfigureAwait(false);
using var content = new ByteArrayContent(jpeg);
content.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg");
using var response = await SendRawAsync(new HttpRequestMessage(HttpMethod.Put, $"api/v1/frames/{frameId}/proxy") { Content = content }, ct)
.ConfigureAwait(false);
await EnsureSuccessAsync(response, ct).ConfigureAwait(false);
return true;
}, ct);
}
// ---------------- 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>
/// Reports a card import this client streams into the server (started, progress, finished); the server tells every
/// connected client with a <see cref="CardEvent"/> (BRIEF §14.3).
/// </summary>
public Task ReportCardAsync(CardImportReport report, CancellationToken ct = default) =>
SendAsync(HttpMethod.Post, "api/v1/uploads/cards", report, ProtocolJson.Default.CardImportReport, ct);
/// <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 a render of <paramref name="sequenceId"/> made on this PC in resumable chunks; the server verifies the
/// SHA-256 in <paramref name="request"/> and files it under the sequence's exports with the same id. Null when the
/// server already has that render.
/// </summary>
public async Task<RenderDto?> UploadRenderAsync(Guid sequenceId, string path, RenderUploadRequest request, IProgress<UploadProgress>? progress = null,
CancellationToken ct = default)
{
var length = new FileInfo(path).Length;
if (length != request.Size) throw new ArgumentException("The render size does not match the file.", nameof(request));
var start = await RetryAsync(() => SendAsync(HttpMethod.Post, $"api/v1/sequences/{sequenceId}/renders", request,
ProtocolJson.Default.RenderUploadRequest, ProtocolJson.Default.StartUploadResponse, ct), ct).ConfigureAwait(false);
if (start.AlreadyExists) return null;
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/sequences/{sequenceId}/renders/{uploadId}/complete",
ProtocolJson.Default.RenderDto, ct), ct).ConfigureAwait(false);
}
/// <summary>
/// Streams a render's file to <paramref name="destination"/>, resuming with Range from its current length; returns
/// the file name the server gives it.
/// </summary>
public async Task<string?> DownloadRenderAsync(Guid renderId, Stream destination, CancellationToken ct = default)
{
using var request = new HttpRequestMessage(HttpMethod.Get, $"api/v1/renders/{renderId}/file");
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);
await body.CopyToAsync(destination, ct).ConfigureAwait(false);
var disposition = response.Content.Headers.ContentDisposition;
return (disposition?.FileNameStar ?? disposition?.FileName)?.Trim('"');
}
/// <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) =>
ListJobsAsync(state, null, cursor, ct);
/// <summary>A page of jobs, newest first, in <paramref name="state"/> and of <paramref name="kind"/> (wire names; null for any).</summary>
public Task<Page<JobDto>> ListJobsAsync(string? state, string? kind, string? cursor, CancellationToken ct = default) =>
GetAsync($"api/v1/jobs?limit=200{Q("state", state)}{Q("kind", kind)}{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 ChronosApiException(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
{
ChronosApiException 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 Chronos.Protocol;
/// <summary>
/// LAN discovery (CHRONOS_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 = "CHRONOS1 ";
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;
}
}
}
+22
View File
@@ -0,0 +1,22 @@
using System.Text.Json.Serialization;
namespace Chronos.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 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(
string Name,
string Version,
int ApiVersion,
IReadOnlyList<string> Capabilities,
string? TlsFingerprint,
IReadOnlyList<string> Formats,
ServerLimits Limits);
/// <summary><c>GET /health</c>.</summary>
public sealed record HealthStatus(string Status, string Version, IReadOnlyDictionary<string, string> Checks);
+43
View File
@@ -0,0 +1,43 @@
using System.Text.Json.Serialization;
namespace Chronos.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(CardEvent), "cardEvent")]
[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;
/// <summary>
/// A card import that a connected client streams into the server (BRIEF §14.4), as that client reported it
/// (<see cref="CardImportReport"/>): <see cref="State"/> is one of <see cref="CardImportStates"/>, <see cref="Done"/>
/// counts the photos of its plan handled so far (failures included), <see cref="User"/> and <see cref="ClientName"/>
/// say who imports it.
/// </summary>
public sealed record CardEvent(Guid ImportId, string Card, string State, int Done, int Total, int Failed, string User, string? ClientName) : ServerEvent;
/// <summary>States of a card import report and of its <see cref="CardEvent"/>.</summary>
public static class CardImportStates
{
public const string Started = "started";
public const string Progress = "progress";
/// <summary>The import ended: every photo handled, or fewer when it stopped early.</summary>
public const string Finished = "finished";
public static bool IsKnown(string? state) => state is Started or Progress or Finished;
}
public sealed record NodeStateEvent(Guid NodeId, string ClientName, string State) : ServerEvent;
+70
View File
@@ -0,0 +1,70 @@
namespace Chronos.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). <see cref="MaxWidth"/> ×
/// <see cref="MaxHeight"/> is the largest output of any of them, for encoders that announce no limit of their own.
/// </summary>
public sealed record RegisterNodeRequest(string ClientName, IReadOnlyList<NodeEncoder> Encoders, int MaxWidth, int MaxHeight);
/// <summary>
/// One encoder of a render node. <see cref="MaxWidth"/> × <see cref="MaxHeight"/> is its largest output (0 = not announced:
/// the node's own limit applies), so jobs go only to a node with an encoder of their codec that takes their size.
/// </summary>
public sealed record NodeEncoder(string Codec, string Name, bool Hardware, bool TenBit, int MaxWidth = 0, int MaxHeight = 0);
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>
/// <param name="Frames">Every frame of the sequence; a node renders none flagged missing, corrupt or excluded.</param>
/// <param name="Proxies">How to make the proxies the server asks for (<see cref="ManifestFrame.WantsProxy"/>); null when it makes none.</param>
public sealed record ClaimedJob(JobDto Job, Guid SequenceId, string SettingsJson, string PresetJson, bool UseProxies, IReadOnlyList<ManifestFrame> Frames,
ProxySpec? Proxies = null);
/// <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);
+67
View File
@@ -0,0 +1,67 @@
using System.Text.Json.Serialization;
namespace Chronos.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(CardImportReport))]
[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))]
[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(RenderUploadRequest))]
[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;
+153
View File
@@ -0,0 +1,153 @@
namespace Chronos.Protocol;
/// <summary>Sequence summary for lists (BRIEF §12.2 card data).</summary>
/// <param name="PreviewOnlyCount">Frames that decode only through their embedded preview (BRIEF §8.2 tier 2).</param>
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,
int PreviewOnlyCount = 0);
/// <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).
/// <see cref="HeroFrameId"/> names the frame the sequence shows (one of its own; <see cref="Guid.Empty"/> clears it).
/// <see cref="ExpectedFramesVersion"/> is the frames version the settings' frame positions were written against: the
/// edit is refused (409 <c>frames_conflict</c>) when frames were added or removed since.
/// </summary>
public sealed record UpdateSequenceRequest(
string? Title,
IReadOnlyList<string>? Tags,
int? Rating,
string? Notes,
string? SettingsJson,
int? ExpectedSettingsVersion,
Guid? HeroFrameId = null,
int? ExpectedFramesVersion = null);
/// <param name="PreviewWidth">Width of the largest embedded preview before orientation, like <paramref name="Width"/>; 0 when unknown.</param>
/// <param name="PreviewHeight">Height of that preview before orientation; 0 when unknown.</param>
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,
int PreviewWidth = 0,
int PreviewHeight = 0);
/// <summary><c>GET /api/v1/sequences/{id}/manifest</c>: what a client needs to diff a sequence (BRIEF §14.5).</summary>
/// <param name="Proxies">How to make the proxies the server asks for (<see cref="ManifestFrame.WantsProxy"/>); null when it makes none.</param>
public sealed record SequenceManifest(
Guid SequenceId,
int FramesVersion,
int SettingsVersion,
string? SettingsJson,
IReadOnlyList<string> Tags,
IReadOnlyList<ManifestFrame> Frames,
IReadOnlyList<RenderDto> Renders,
ProxySpec? Proxies = null);
/// <summary>One frame of a manifest: its content, whether the server has a proxy and thumbnail of it, and its flags.</summary>
/// <param name="Sha256">Lower-case hex SHA-256; empty while the server has not hashed it (a folder adopted and not verified yet).</param>
/// <param name="Flags">The frame's <c>FrameFlags</c> bits (missing, corrupt, excluded…).</param>
/// <param name="WantsProxy">
/// The server cannot decode this original and has no proxy of it (BRIEF §2.3, §8.1: HEIF): a client or render node that
/// decodes it sends one with <c>PUT /api/v1/frames/{id}/proxy</c>, made as <see cref="SequenceManifest.Proxies"/> says.
/// </param>
public sealed record ManifestFrame(Guid Id, int Index, string FileName, long Size, string Sha256, bool HasProxy, bool HasThumb, long Flags = 0,
bool WantsProxy = false);
/// <summary>How the server's proxies are made (BRIEF §8.5): long edge in pixels (0 = full size) and JPEG quality.</summary>
public sealed record ProxySpec(int LongEdge, int Quality);
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);
/// <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);
+45
View File
@@ -0,0 +1,45 @@
namespace Chronos.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);
/// <summary>
/// <c>POST /api/v1/uploads/cards</c>: a client importing a card into the server through these uploads reports its start,
/// progress and end (BRIEF §14.4); the server tells every connected client with a <see cref="CardEvent"/> (BRIEF §14.3).
/// <see cref="ImportId"/> is the client's import plan, <see cref="Card"/> the card's name as the client shows it.
/// </summary>
public sealed record CardImportReport(Guid ImportId, string Card, string State, int Done, int Total, int Failed);
/// <summary>
/// <c>POST /api/v1/sequences/{id}/renders</c>: a client offers one of its renders of the sequence (BRIEF §14.5,
/// renders are uploaded on request). The render keeps its id on the server, so both sides recognise it; when the
/// server already has that id it answers 200 with <see cref="StartUploadResponse.AlreadyExists"/>. Chunks go to
/// <c>/uploads/{uploadId}/chunks/{n}</c>; <c>POST /sequences/{id}/renders/{uploadId}/complete</c> verifies the SHA-256
/// and files the render under the sequence's exports.
/// </summary>
public sealed record RenderUploadRequest(
Guid RenderId,
string FileName,
long Size,
string Sha256,
string PresetName,
string? Codec,
int Width,
int Height,
double Fps,
double DurationSeconds,
string? ProducedBy);