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;
/// Upload progress for one file.
public readonly record struct UploadProgress(long BytesSent, long BytesTotal);
///
/// 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.
///
public sealed class ChronosClient : IDisposable
{
private readonly HttpClient _http;
private readonly CertificatePinning _pinning;
/// The client made its own handler, so TLS goes through (tests pass theirs).
private readonly bool _ownsHandler;
private string? _token;
public ChronosClient(Uri baseAddress, CertificatePinning pinning, string clientName, HttpMessageHandler? handler = null)
{
_pinning = pinning;
_ownsHandler = handler is null;
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;
/// Bearer token; set after or restored from secure storage.
public string? Token
{
get => _token;
set
{
_token = value;
_http.DefaultRequestHeaders.Authorization = value is null ? null : new AuthenticationHeaderValue("Bearer", value);
}
}
/// Shared upload rate limit.
public BandwidthLimiter Bandwidth { get; } = new();
// ---------------- Server ----------------
///
/// Reads server info; throws when the TLS certificate of a Chronos Server
/// needs confirmation, and when the address answers as something else (owner
/// review 3): a redirect, a page that is not JSON, JSON of another shape, or an error Chronos did not write. Behind a
/// certificate that is not trusted yet, the info is first read once more without checking the certificate and without
/// credentials: only an answer that is Chronos's leads to the fingerprint question, so the certificate of another
/// service on the host is never offered for trust. An HTTPS address whose port answers plain HTTP (the HTTP port typed
/// without a scheme) is not Chronos either. Nothing is trusted here.
///
public async Task GetInfoAsync(CancellationToken ct = default)
{
HttpResponseMessage response;
try
{
response = await SendRawAsync(new HttpRequestMessage(HttpMethod.Get, InfoPath), ct).ConfigureAwait(false);
}
catch (UntrustedCertificateException) when (_ownsHandler)
{
if (await ProbeAsync(BaseAddress, ct).ConfigureAwait(false) is { Chronos: false }) throw new NotChronosServerException(BaseAddress);
throw;
}
catch (HttpRequestException tls) when (_ownsHandler && tls.HttpRequestError == HttpRequestError.SecureConnectionError
&& BaseAddress.Scheme == Uri.UriSchemeHttps)
{
// The same authority over plain HTTP: any answer means the port is not Chronos's HTTPS port.
var plain = new UriBuilder(BaseAddress) { Scheme = Uri.UriSchemeHttp, Port = BaseAddress.Port }.Uri;
if (await ProbeAsync(plain, ct).ConfigureAwait(false) is { Answered: true }) throw new NotChronosServerException(BaseAddress, tls);
throw;
}
using (response)
{
var answer = await IdentifyAsync(response, ct).ConfigureAwait(false);
if (answer.Info is { } info) return info;
if (answer.Chronos == false) throw new NotChronosServerException(BaseAddress);
// Chronos's own error, already read (the body cannot be read twice), or busy: as any other request reports it.
if (answer.Error is { } error) throw new ChronosApiException(response.StatusCode, error);
await EnsureSuccessAsync(response, ct).ConfigureAwait(false);
throw new NotChronosServerException(BaseAddress);
}
}
private const string InfoPath = "api/v1/server/info";
/// More than a server info ever holds: a larger answer is something else.
private const int MaxInfoBytes = 1 << 20;
/// What every Chronos Server's info holds; JSON of another shape reads as nulls and zeros.
private static bool IsChronos(ServerInfo? info) =>
info is { Name.Length: > 0, Version.Length: > 0, ApiVersion: > 0, Capabilities: not null, Formats: not null, Limits: not null };
///
/// What a server/info answer is: Chronos's (with its info when it succeeded, or its error when it failed),
/// something else, or unknown (busy).
///
private readonly record struct Identity(bool? Chronos, ServerInfo? Info = null, bool Answered = true, ApiError? Error = null);
///
/// Tells a server/info answer of Chronos from any other. Chronos answers it anonymously with its JSON and never
/// redirects; every response of its carries , so an error is Chronos's only with that
/// header and an error body of its own. A busy answer (408, 429, 502-504) with JSON or no body cannot tell; any answer
/// that is not JSON, or is larger than , is something else.
///
private static async Task IdentifyAsync(HttpResponseMessage response, CancellationToken ct)
{
if ((int)response.StatusCode is >= 300 and < 400) return new(false);
var type = response.Content.Headers.ContentType?.MediaType;
var json = type is not null && (type.Equals("application/json", StringComparison.OrdinalIgnoreCase) || type.EndsWith("+json", StringComparison.OrdinalIgnoreCase));
if (ChronosApiException.IsTransientStatus(response.StatusCode)) return new(json || type is null ? null : false);
if (!json || response.Content.Headers.ContentLength > MaxInfoBytes) return new(false);
try
{
await response.Content.LoadIntoBufferAsync(MaxInfoBytes, ct).ConfigureAwait(false);
if (response.IsSuccessStatusCode)
{
var info = await response.Content.ReadFromJsonAsync(ProtocolJson.Default.ServerInfo, ct).ConfigureAwait(false);
return IsChronos(info) ? new(true, info) : new(false);
}
if (!response.Headers.Contains(ApiVersion.Header)) return new(false);
var error = await response.Content.ReadFromJsonAsync(ProtocolJson.Default.ApiError, ct).ConfigureAwait(false);
return error is { Code.Length: > 0 } && !error.Code.StartsWith("http_", StringComparison.Ordinal) ? new(true, Error: error) : new(false);
}
catch (Exception ex) when (ex is JsonException or NotSupportedException or HttpRequestException)
{
// Not JSON after all, or more than a server info.
return new(false);
}
}
///
/// The info at read without checking the certificate, by a client of its own that holds no
/// token and follows no redirect; is false when nothing answered (no connection, TLS
/// refused, timeout).
///
private static async Task ProbeAsync(Uri address, CancellationToken ct)
{
using var handler = new SocketsHttpHandler
{
SslOptions = { RemoteCertificateValidationCallback = static (_, _, _, _) => true },
ConnectTimeout = TimeSpan.FromSeconds(10),
AutomaticDecompression = DecompressionMethods.None,
AllowAutoRedirect = false,
UseCookies = false,
};
using var http = new HttpClient(handler) { BaseAddress = address, Timeout = TimeSpan.FromSeconds(20) };
http.DefaultRequestHeaders.Add(ApiVersion.Header, ApiVersion.Current.ToString(System.Globalization.CultureInfo.InvariantCulture));
try
{
using var response = await http.GetAsync(InfoPath, HttpCompletionOption.ResponseHeadersRead, ct).ConfigureAwait(false);
return await IdentifyAsync(response, ct).ConfigureAwait(false);
}
catch (Exception ex) when (ex is HttpRequestException or IOException || (ex is OperationCanceledException && !ct.IsCancellationRequested))
{
return new(null, Answered: false);
}
}
// ---------------- Auth ----------------
public async Task 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 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> 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 GetSequenceAsync(Guid id, CancellationToken ct = default) => GetAsync($"api/v1/sequences/{id}", ProtocolJson.Default.SequenceDto, ct);
public Task CreateSequenceAsync(CreateSequenceRequest request, CancellationToken ct = default) =>
SendAsync(HttpMethod.Post, "api/v1/sequences", request, ProtocolJson.Default.CreateSequenceRequest, ProtocolJson.Default.SequenceDto, ct);
/// Updates metadata/settings; a 409 means the settings changed on the server.
public Task 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 GetManifestAsync(Guid id, CancellationToken ct = default) =>
GetAsync($"api/v1/sequences/{id}/manifest", ProtocolJson.Default.SequenceManifest, ct);
/// The full deep-analysis report of a sequence (analysis.json); null when it was never deep-analysed.
public async Task 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> 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);
/// Streams a frame resource (original, proxy or thumb) to , resuming with Range from its current length.
public async Task DownloadFrameAsync(Guid frameId, string kind, Stream destination, IProgress? 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);
}
}
///
/// Sends the proxy of a frame whose original the server cannot decode (): a JPEG
/// with the frame's capture time in its Exif, replacing the server's. A transient failure is retried.
///
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 ----------------
///
/// Uploads one file with resumable, idempotent chunks; the server verifies the SHA-256 before committing it
/// (BRIEF §14.4). Returns the committed frame id; null when the server holds the photo without a frame to name: it was
/// deleted from the target sequence, before the upload or while it was on its way (owner review 2, R6). Transient
/// failures retry with exponential backoff.
///
public async Task UploadFileAsync(
string path,
Guid? sequenceId,
DateTime? capturedAt,
string? sessionKey = null,
string? knownSha256 = null,
IProgress? 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);
try
{
return await RetryAsync(() => SendAsync(HttpMethod.Post, $"api/v1/uploads/{uploadId}/complete", ProtocolJson.Default.CompleteUploadResponse, ct), ct)
.ConfigureAwait(false);
}
catch (ChronosApiException ex) when (ex is { Status: HttpStatusCode.Conflict, Error.Code: UploadErrors.PhotoRemoved })
{
return null;
}
}
///
/// Reports a card import this client streams into the server (started, progress, finished); the server tells every
/// connected client with a (BRIEF §14.3).
///
public Task ReportCardAsync(CardImportReport report, CancellationToken ct = default) =>
SendAsync(HttpMethod.Post, "api/v1/uploads/cards", report, ProtocolJson.Default.CardImportReport, ct);
///
/// Render node: uploads the output of a claimed job in resumable chunks, then completes the job; the server verifies
/// the SHA-256 in and files the render under the sequence's exports (BRIEF §14.7).
///
public async Task UploadRenderResultAsync(Guid nodeId, Guid jobId, string path, RenderResultRequest result,
IProgress? progress = null, CancellationToken ct = default)
{
var length = new FileInfo(path).Length;
if (length != result.Size) throw new ArgumentException("The result size does not match the file.", nameof(result));
var start = await RetryAsync(() => SendAsync(HttpMethod.Post, $"api/v1/nodes/{nodeId}/jobs/{jobId}/result", result,
ProtocolJson.Default.RenderResultRequest, ProtocolJson.Default.StartUploadResponse, ct), ct).ConfigureAwait(false);
var uploadId = start.UploadId ?? throw new InvalidOperationException("Server returned no upload id.");
await SendChunksAsync(path, length, uploadId, start.ChunkSize, start.Received, progress, ct).ConfigureAwait(false);
return await RetryAsync(() => SendAsync(HttpMethod.Post, $"api/v1/nodes/{nodeId}/jobs/{jobId}/result/complete", ProtocolJson.Default.RenderDto, ct), ct)
.ConfigureAwait(false);
}
///
/// Sends a render of made on this PC in resumable chunks; the server verifies the
/// SHA-256 in and files it under the sequence's exports with the same id. Null when the
/// server already has that render.
///
public async Task UploadRenderAsync(Guid sequenceId, string path, RenderUploadRequest request, IProgress? 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(HttpMethod.Post, $"api/v1/sequences/{sequenceId}/renders/{uploadId}/complete",
ProtocolJson.Default.RenderDto, ct), ct).ConfigureAwait(false);
}
///
/// Streams a render's file to , resuming with Range from its current length; returns
/// the file name the server gives it.
///
public async Task 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('"');
}
/// Sends every chunk the server does not have yet; each PUT is idempotent and retried on transient errors.
private async Task SendChunksAsync(string path, long length, Guid uploadId, int chunkSize, IReadOnlyList alreadyReceived,
IProgress? progress, CancellationToken ct)
{
var received = new HashSet(alreadyReceived);
var chunks = (int)((length + chunkSize - 1) / chunkSize);
var buffer = new byte[chunkSize];
await using var file = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.ReadWrite, 1 << 16, FileOptions.Asynchronous | FileOptions.SequentialScan);
long sent = received.Sum(i => Math.Min(chunkSize, length - (long)i * chunkSize));
progress?.Report(new UploadProgress(sent, length));
for (var n = 0; n < chunks; n++)
{
if (received.Contains(n)) continue;
var offset = (long)n * chunkSize;
var size = (int)Math.Min(chunkSize, length - offset);
file.Position = offset;
await file.ReadExactlyAsync(buffer.AsMemory(0, size), ct).ConfigureAwait(false);
await Bandwidth.AcquireAsync(size, ct).ConfigureAwait(false);
var index = n;
await RetryAsync(async () =>
{
using var content = new ByteArrayContent(buffer, 0, size);
content.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
using var response = await _http.PutAsync($"api/v1/uploads/{uploadId}/chunks/{index}", content, ct).ConfigureAwait(false);
await EnsureSuccessAsync(response, ct).ConfigureAwait(false);
return true;
}, ct).ConfigureAwait(false);
sent += size;
progress?.Report(new UploadProgress(sent, length));
}
}
/// Lower-case hex SHA-256 of a file, streamed.
public static async Task HashFileAsync(string path, CancellationToken ct = default)
{
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> ListJobsAsync(string? state = null, string? cursor = null, CancellationToken ct = default) =>
ListJobsAsync(state, null, cursor, ct);
/// A page of jobs, newest first, in and of (wire names; null for any).
public Task> 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 CreateJobAsync(CreateJobRequest request, CancellationToken ct = default) =>
SendAsync(HttpMethod.Post, "api/v1/jobs", request, ProtocolJson.Default.CreateJobRequest, ProtocolJson.Default.JobDto, ct);
public Task GetJobAsync(Guid id, CancellationToken ct = default) => GetAsync($"api/v1/jobs/{id}", ProtocolJson.Default.JobDto, ct);
public Task CancelJobAsync(Guid id, CancellationToken ct = default) => SendAsync(HttpMethod.Post, $"api/v1/jobs/{id}/cancel", ProtocolJson.Default.JobDto, ct);
public Task RetryJobAsync(Guid id, CancellationToken ct = default) => SendAsync(HttpMethod.Post, $"api/v1/jobs/{id}/retry", ProtocolJson.Default.JobDto, ct);
public Task PauseJobAsync(Guid id, CancellationToken ct = default) => SendAsync(HttpMethod.Post, $"api/v1/jobs/{id}/pause", ProtocolJson.Default.JobDto, ct);
public Task ResumeJobAsync(Guid id, CancellationToken ct = default) => SendAsync(HttpMethod.Post, $"api/v1/jobs/{id}/resume", ProtocolJson.Default.JobDto, ct);
/// Moves a waiting job up or down the queue: is background, normal or user.
public Task SetJobPriorityAsync(Guid id, string priority, CancellationToken ct = default) =>
SendAsync(HttpMethod.Post, $"api/v1/jobs/{id}/priority", new JobPriorityRequest(priority), ProtocolJson.Default.JobPriorityRequest, ProtocolJson.Default.JobDto, ct);
public Task> ListNodesAsync(CancellationToken ct = default) => GetAsync("api/v1/nodes", ProtocolJson.Default.ListRenderNodeDto, ct);
public Task RegisterNodeAsync(RegisterNodeRequest request, CancellationToken ct = default) =>
SendAsync(HttpMethod.Post, "api/v1/nodes/register", request, ProtocolJson.Default.RegisterNodeRequest, ProtocolJson.Default.RenderNodeDto, ct);
public Task HeartbeatAsync(Guid nodeId, CancellationToken ct = default) => SendNoContentAsync(HttpMethod.Post, $"api/v1/nodes/{nodeId}/heartbeat", ct);
/// Claims the next render job matching this node; null when there is none.
public async Task 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);
/// Gives a claimed job back as failed; a 409 means it was cancelled or reassigned meanwhile.
public Task ReportNodeFailureAsync(Guid nodeId, Guid jobId, string error, CancellationToken ct = default) =>
SendAsync(HttpMethod.Post, $"api/v1/nodes/{nodeId}/jobs/{jobId}/failed", new NodeJobFailure(error), ProtocolJson.Default.NodeJobFailure, ct);
// ---------------- Projects (owner review 2, R8; servers with the "projects" capability) ----------------
/// The live projects of a server sequence, Main first (made from the sequence's settings the first time they are read).
public Task> ListProjectsAsync(Guid sequenceId, CancellationToken ct = default) =>
GetAsync($"api/v1/sequences/{sequenceId}/projects", ProtocolJson.Default.ListProjectDto, ct);
public Task GetProjectAsync(Guid sequenceId, Guid projectId, CancellationToken ct = default) =>
GetAsync($"api/v1/sequences/{sequenceId}/projects/{projectId}", ProtocolJson.Default.ProjectDto, ct);
///
/// A new project of the sequence, its first version copied from or from
/// Main's head; a name refused is a 400 invalid_name or 409 name_taken .
///
public Task CreateProjectAsync(Guid sequenceId, CreateProjectRequest request, CancellationToken ct = default) =>
SendAsync(HttpMethod.Post, $"api/v1/sequences/{sequenceId}/projects", request, ProtocolJson.Default.CreateProjectRequest, ProtocolJson.Default.ProjectDto, ct);
/// Gives a project another name; a name refused is a 400 invalid_name or 409 name_taken .
public Task RenameProjectAsync(Guid sequenceId, Guid projectId, string name, CancellationToken ct = default) =>
SendAsync(HttpMethod.Patch, $"api/v1/sequences/{sequenceId}/projects/{projectId}", new RenameProjectRequest(name), ProtocolJson.Default.RenameProjectRequest,
ProtocolJson.Default.ProjectDto, ct);
///
/// Deletes a project and its versions into the sequence's projects' trash (never erased); Main is refused (409
/// main_cannot_be_deleted).
///
public Task DeleteProjectAsync(Guid sequenceId, Guid projectId, CancellationToken ct = default) =>
SendNoContentAsync(HttpMethod.Delete, $"api/v1/sequences/{sequenceId}/projects/{projectId}", ct);
/// The project's newest version.
public Task GetProjectHeadAsync(Guid sequenceId, Guid projectId, CancellationToken ct = default) =>
GetAsync($"api/v1/sequences/{sequenceId}/projects/{projectId}/head", ProtocolJson.Default.ProjectVersionDto, ct);
///
/// One page of a project's versions: newest first, numbered below (from the head when null),
/// or, with , oldest first numbered above it (what a workspace pulls). :
/// 1–200 (the server's default, 50 newest first and 100 oldest first, when null).
///
public Task ListProjectVersionsAsync(Guid sequenceId, Guid projectId, int? before = null, int? after = null, int? limit = null,
CancellationToken ct = default) =>
GetAsync($"api/v1/sequences/{sequenceId}/projects/{projectId}/versions?{N("before", before)}{N("after", after)}{N("limit", limit)}".TrimEnd('&', '?'),
ProtocolJson.Default.ProjectVersionPageDto, ct);
/// A version of the project by id; null when the server has no such version of it.
public async Task GetProjectVersionAsync(Guid sequenceId, Guid projectId, Guid versionId, CancellationToken ct = default)
{
try
{
return await GetAsync($"api/v1/sequences/{sequenceId}/projects/{projectId}/versions/{versionId}", ProtocolJson.Default.ProjectVersionDto, ct)
.ConfigureAwait(false);
}
catch (ChronosApiException ex) when (ex.Status == HttpStatusCode.NotFound && ex.Error.Details == "version")
{
return null;
}
}
///
/// Pushes , made in a workspace from the project's head ():
/// the server stores it as the new head, numbered head + 1 (201, stored), or answers it again for a repeated push
/// (200, already_stored), or refuses it, storing nothing: 409 diverged with the head, 422
/// hash_mismatch, newer_format or invalid. These come back as
/// without throwing; any other failure (the sequence or project gone, no permission, the archive offline or the sequence
/// busy: 503) throws . Safe to repeat: the version's id makes a second push a no-op.
///
public async Task PushProjectVersionAsync(Guid sequenceId, Guid projectId, ProjectVersionDto version, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(version);
using var request = new HttpRequestMessage(HttpMethod.Post, $"api/v1/sequences/{sequenceId}/projects/{projectId}/versions")
{
Content = JsonContent.Create(version, ProtocolJson.Default.ProjectVersionDto),
};
using var response = await SendRawAsync(request, ct).ConfigureAwait(false);
if (response.StatusCode is HttpStatusCode.OK or HttpStatusCode.Created or HttpStatusCode.Conflict or HttpStatusCode.UnprocessableEntity)
{
var body = await response.Content.ReadAsStringAsync(ct).ConfigureAwait(false);
try
{
if (JsonSerializer.Deserialize(body, ProtocolJson.Default.ProjectPushResultDto) is { Outcome.Length: > 0 } result) return result;
}
catch (JsonException)
{
// Not a push answer (a proxy's page): the status says what failed.
}
}
await EnsureSuccessAsync(response, ct).ConfigureAwait(false);
throw new ChronosApiException(response.StatusCode, new ApiError("http_" + (int)response.StatusCode, response.ReasonPhrase ?? "error"));
}
/// The sequence's frames and photo aliases as of one frames version: what its projects' positions are placed on.
public Task GetProjectFramesAsync(Guid sequenceId, CancellationToken ct = default) =>
GetAsync($"api/v1/sequences/{sequenceId}/projects/frames", ProtocolJson.Default.ProjectFramesDto, ct);
// ---------------- Events ----------------
/// Server events over WebSocket until cancelled; reconnect is the caller's policy.
public async IAsyncEnumerable 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 GetAsync(string url, JsonTypeInfo 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 SendAsync(HttpMethod method, string url, TRequest body, JsonTypeInfo requestType, JsonTypeInfo 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(HttpMethod method, string url, TRequest body, JsonTypeInfo 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 SendAsync(HttpMethod method, string url, JsonTypeInfo 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 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);
}
/// Retries transient failures 5 times with exponential backoff (1, 2, 4, 8, 16 s).
private static async Task RetryAsync(Func> 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);
/// A number of the query (name=value&); empty when null.
private static string N(string name, int? value) =>
value is { } n ? name + "=" + n.ToString(System.Globalization.CultureInfo.InvariantCulture) + "&" : string.Empty;
}