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; }