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
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:
1 parent
c99842cc86
commit
f2b58522b9
1801 files changed
+11804
-10676
No files matched your search
@@ -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);
|
||||
@@ -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";
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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);
|
||||
@@ -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;
|
||||
@@ -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);
|
||||
@@ -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;
|
||||
@@ -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);
|
||||
@@ -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);
|
||||
Reference in new issue
Block a user