fix(proxies): ask again for preview-sized proxies and refuse unwanted ones

Earlier versions made the server's proxies of HEIF frames from their embedded
previews. Those carry the frame's capture time, so the proxy pass kept them
and the sequence stayed marked as having all its proxies; renders and
analysis then read thumbnail-sized files and no client or render node was
asked for a real one. The proxy pass now treats a proxy whose long edge falls
short of the policy's for the frame (its own size when smaller, a tenth of
slack, frames of unknown size not judged) as stale, and the server refuses
such a proxy when one is sent (422 proxy_too_small).

PUT /api/v1/frames/{id}/proxy also took a proxy of a frame the server
decodes itself, replacing its own proxy with any JPEG of the right capture
time; it now answers 422 proxy_not_wanted for those and for frames missing or
damaged. Its follow-up jobs are queued even when the sender disconnects once
the proxy is filed.

A render node cleared the server's Undecodable flag on every frame, so a
damaged frame the server's own render skips was downloaded and failed the
node's job. Only a format the server cannot decode and the node can loses the
flag now; other undecodable originals are neither fetched nor rendered unless
read from their proxy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-12 11:06:42 +00:00
1 parent 9588ed7f4b
commit f215b99ca5
9 files changed
+112 -25

No files matched your search

+2
View File
@@ -70,6 +70,8 @@
<data name="Server.Error.PasswordChangeRequired" xml:space="preserve"><value>Change your password first.</value><comment>long</comment></data>
<data name="Server.Error.ProxiesDisabled" xml:space="preserve"><value>This archive makes no proxies.</value><comment>long</comment></data>
<data name="Server.Error.ProxyMismatch" xml:space="preserve"><value>The proxy was made from another photo.</value><comment>long</comment></data>
<data name="Server.Error.ProxyNotWanted" xml:space="preserve"><value>The server does not need a proxy of this photo.</value><comment>long</comment></data>
<data name="Server.Error.ProxyTooSmall" xml:space="preserve"><value>The proxy is smaller than this archive's proxies.</value><comment>long</comment></data>
<data name="Server.Error.QuotaExceeded" xml:space="preserve"><value>This upload would exceed your quota.</value><comment>long</comment></data>
<data name="Server.Error.RateLimited" xml:space="preserve"><value>Too many attempts; wait a minute and try again.</value><comment>long</comment></data>
<data name="Server.Error.SamePassword" xml:space="preserve"><value>Choose a password different from the current one.</value><comment>long</comment></data>
+2
View File
@@ -68,6 +68,8 @@
<data name="Server.Error.PasswordChangeRequired" xml:space="preserve"><value>Cambia prima la password.</value></data>
<data name="Server.Error.ProxiesDisabled" xml:space="preserve"><value>Questo archivio non crea proxy.</value></data>
<data name="Server.Error.ProxyMismatch" xml:space="preserve"><value>Il proxy è stato creato da un'altra foto.</value></data>
<data name="Server.Error.ProxyNotWanted" xml:space="preserve"><value>Al server non serve un proxy di questa foto.</value></data>
<data name="Server.Error.ProxyTooSmall" xml:space="preserve"><value>Il proxy è più piccolo dei proxy di questo archivio.</value></data>
<data name="Server.Error.QuotaExceeded" xml:space="preserve"><value>Questo caricamento supererebbe la tua quota.</value></data>
<data name="Server.Error.RateLimited" xml:space="preserve"><value>Troppi tentativi; attendi un minuto e riprova.</value></data>
<data name="Server.Error.SamePassword" xml:space="preserve"><value>Scegli una password diversa da quella attuale.</value></data>
+35 -4
View File
@@ -2,6 +2,7 @@ using System.Diagnostics;
using Titano.Core.Archiving;
using Titano.Core.Codecs.Jpeg;
using Titano.Core.Imaging;
using Titano.Core.Imaging.Decoders;
using Titano.Core.IO;
using Titano.Core.Metadata;
using Titano.Core.Model;
@@ -24,6 +25,9 @@ public enum ProxyStoreResult
/// <summary>Its Exif capture time is not the frame's: it was made from another photo.</summary>
WrongFrame,
/// <summary>Smaller than the archive's proxies of that frame: made from an embedded preview, not the original.</summary>
TooSmall,
}
/// <summary>
@@ -41,6 +45,7 @@ public sealed class ArchiveImages
private const int CommitFrames = 200;
private const int ProbeLongEdge = 64;
private static readonly TimeSpan CommitInterval = TimeSpan.FromSeconds(10);
private static readonly ImageDecoder ServerDecoders = DecoderFactory.CreateServer();
private readonly TitanoDatabase _db;
private readonly SequenceWriter _writer;
@@ -72,6 +77,12 @@ public sealed class ArchiveImages
/// <summary><see cref="NeedsProxy(ImageDecoder, ImageFileFormat)"/> with this archive engine's decoders.</summary>
public bool NeedsProxy(ImageFileFormat format) => NeedsProxy(_writer.Options.Decoder, format);
/// <summary>
/// <see cref="NeedsProxy(ImageDecoder, ImageFileFormat)"/> on a Titano Server, whose decoders are managed only (BRIEF
/// §4.2): it asks clients and render nodes for the proxies of those originals.
/// </summary>
public static bool ServerNeedsProxy(ImageFileFormat format) => NeedsProxy(ServerDecoders, format);
/// <summary>
/// A proxy of the original at <paramref name="path"/> for a server that cannot decode it (<see cref="StoreProxy"/>):
/// at <paramref name="longEdge"/> (0 = full size) and <paramref name="quality"/>, with <paramref name="frame"/>'s capture
@@ -109,7 +120,8 @@ public sealed class ArchiveImages
/// <summary>
/// Files a proxy made elsewhere (a client or render node whose decoders read the original) as the frame's proxy,
/// replacing the one there: a JPEG of at most <see cref="MaxProxyBytes"/> that decodes, whose Exif capture time is the
/// frame's (proxies carry it, so the proxy counts as current and cannot belong to another photo), written atomically.
/// frame's (proxies carry it, so the proxy counts as current and cannot belong to another photo) and whose size is
/// the policy's (<see cref="TooSmall"/>), written atomically.
/// </summary>
/// <exception cref="ArchiveOfflineException">The archive is offline or read-only.</exception>
public ProxyStoreResult StoreProxy(Archive archive, Sequence sequence, Frame frame, byte[] jpeg)
@@ -117,8 +129,11 @@ public sealed class ArchiveImages
ArgumentNullException.ThrowIfNull(jpeg);
var paths = new ArchivePaths(archive.RootPath);
ArchiveVolume.EnsureWritable(paths);
if (ManifestStore.ReadArchive(paths.ManifestPath).ProxyPolicy.LongEdge == ProxyPolicy.Disabled) return ProxyStoreResult.Disabled;
var policy = ManifestStore.ReadArchive(paths.ManifestPath).ProxyPolicy;
if (policy.LongEdge == ProxyPolicy.Disabled) return ProxyStoreResult.Disabled;
if (jpeg.Length is 0 or > (int)MaxProxyBytes || !Decodes(jpeg)) return ProxyStoreResult.Invalid;
var info = JpegDecoder.ReadInfo(jpeg);
if (TooSmall(System.Math.Max(info.Width, info.Height), frame.Width, frame.Height, policy)) return ProxyStoreResult.TooSmall;
if (frame.CapturedAt is { } captured)
{
using var stream = new MemoryStream(jpeg, writable: false);
@@ -208,8 +223,10 @@ public sealed class ArchiveImages
if (NeedsProxy(frame.Format))
{
// Only a client or render node that decodes the original makes this proxy: a preview would make one the
// size of a thumbnail here. One left from a frame renumbered since goes, so it is asked for again.
var check = ReadProxy(path, frame).Check;
// size of a thumbnail here. One left from a frame renumbered since goes, so it is asked for again, and so
// does one smaller than the policy's (made here from a preview by an earlier version).
var (check, longEdge) = ReadProxy(path, frame);
if (check is ProxyCheck.Current or ProxyCheck.Unverifiable && TooSmall(longEdge, frame.W, frame.H, policy)) check = ProxyCheck.Stale;
if (check is ProxyCheck.Current or ProxyCheck.Unverifiable)
{
reused++;
@@ -272,6 +289,20 @@ public sealed class ArchiveImages
}
}
/// <summary>
/// Whether a proxy whose long edge is <paramref name="longEdge"/> falls short of the policy's for a frame of
/// <paramref name="width"/> × <paramref name="height"/> (the policy's long edge, or the frame's own when smaller or
/// at full size): one made from an embedded preview. A frame of unknown size is never judged (a small original's
/// proxy would be refused again and again); a tenth of slack spares decoders that crop a few pixels.
/// </summary>
private static bool TooSmall(int longEdge, int width, int height, ProxyPolicy policy)
{
var own = System.Math.Max(width, height);
if (own <= 0) return false;
var expected = policy.LongEdge == ProxyPolicy.FullSize ? own : System.Math.Min(own, policy.LongEdge);
return longEdge * 10L < expected * 9L;
}
/// <summary>The frame's proxy as the frame to draw: a JPEG already oriented, under <c>proxies/</c>.</summary>
private static SidecarFrame ProxySource(SidecarFrame frame) => frame with
{
@@ -245,9 +245,13 @@ public sealed class RenderNodeClient : IAsyncDisposable
var project = ProjectStore.Parse(claimed.SettingsJson) with { Export = export };
var sequence = ToSequence(await _client.GetSequenceAsync(claimed.SequenceId, cancellationToken).ConfigureAwait(false));
// This PC's decoders judge what they can read: the server's Undecodable does not keep a frame out of the render here.
// The server's Undecodable stands, as in its own render, except for a format only its decoders lack (HEIF) that
// this PC's read: such a frame renders here from its original. One read from its proxy renders either way.
var decoder = _processing.Archive.Decoder;
var frames = (await ListFramesAsync(claimed.SequenceId, cancellationToken).ConfigureAwait(false))
.ConvertAll(f => f with { Flags = f.Flags & ~FrameFlags.Undecodable });
.ConvertAll(f => ArchiveImages.ServerNeedsProxy(f.Format) && !ArchiveImages.NeedsProxy(decoder, f.Format)
? f with { Flags = f.Flags & ~FrameFlags.Undecodable }
: f);
var files = await DownloadAsync(claimed, frames, work, reporter, cancellationToken).ConfigureAwait(false);
var input = new SequenceFrames(sequence, frames, [.. frames.Select(f => files.GetValueOrDefault(f.Id).Path)])
{
@@ -357,10 +361,12 @@ public sealed class RenderNodeClient : IAsyncDisposable
NodeReporter reporter, CancellationToken cancellationToken)
{
var formats = rows.ToDictionary(f => f.Id, f => f.Format);
var undecodable = rows.Where(f => (f.Flags & FrameFlags.Undecodable) != 0).Select(f => f.Id).ToHashSet();
bool Proxy(ManifestFrame f) =>
f.HasProxy && (claimed.UseProxies || (formats.TryGetValue(f.Id, out var format) && ArchiveImages.NeedsProxy(_processing.Archive.Decoder, format)));
var files = new Dictionary<Guid, (string, bool)>();
var fetched = claimed.Frames.Where(f => ((FrameFlags)f.Flags & NotFetched) == 0).ToList();
// An original that stays undecodable would only be skipped by the render.
var fetched = claimed.Frames.Where(f => ((FrameFlags)f.Flags & NotFetched) == 0 && (Proxy(f) || !undecodable.Contains(f.Id))).ToList();
var done = 0;
var total = fetched.Count;
await reporter.ReportAsync(0, total, Loc.L("Export.Job.Downloading")).ConfigureAwait(false);
+13 -5
View File
@@ -58,10 +58,12 @@ public static class FileEndpoints
}
/// <summary>
/// Files the body (a JPEG made from the original, its Exif capture time the frame's, at most
/// <see cref="ArchiveImages.MaxProxyBytes"/>) as the frame's proxy; the sequence's thumbnails and proxy state follow as
/// background jobs. 204; 413 <c>too_large</c>, 422 <c>invalid_proxy</c> or <c>proxy_mismatch</c>, 409
/// <c>proxies_disabled</c>, 503 <c>archive_offline</c>.
/// Files the body (a JPEG made from the original, its Exif capture time the frame's, as large as the archive's proxies,
/// at most <see cref="ArchiveImages.MaxProxyBytes"/>) as the proxy of a frame the server cannot decode
/// (<see cref="ServerProxies"/>); the sequence's thumbnails and proxy state follow as background jobs. 204; 413
/// <c>too_large</c>; 422 <c>proxy_not_wanted</c> (the server decodes that original itself, or it is missing or
/// damaged), <c>invalid_proxy</c>, <c>proxy_mismatch</c> or <c>proxy_too_small</c>, which concern that proxy only; 409
/// <c>proxies_disabled</c>, which concerns them all; 503 <c>archive_offline</c>.
/// </summary>
private static async Task<IResult> StoreProxyAsync(HttpContext context, Guid id, TitanoDatabase db, ServerArchive archive,
[FromServices] ArchiveService? archives, SequenceJobs follow)
@@ -69,6 +71,9 @@ public static class FileEndpoints
var ct = context.RequestAborted;
if (await db.Frames.GetAsync(id, ct) is not { } frame || await db.Sequences.GetAsync(frame.SequenceId, ct) is not { } sequence)
return ApiErrors.NotFound(context, "frame");
// A proxy replaces the server's own of an original it decodes, which renders and remote views would then show.
if (!ServerProxies.CannotDecode(frame.Format) || (frame.Flags & (FrameFlags.Missing | FrameFlags.Corrupt)) != 0)
return ApiErrors.Result(context, StatusCodes.Status422UnprocessableEntity, "proxy_not_wanted");
if (context.Request.ContentLength is > ArchiveImages.MaxProxyBytes) return ApiErrors.Result(context, StatusCodes.Status413PayloadTooLarge, "too_large");
// Proxies are larger than the JSON bodies Kestrel is limited to; reading past this answers 413.
if (context.Features.Get<IHttpMaxRequestBodySizeFeature>() is { IsReadOnly: false } limit) limit.MaxRequestBodySize = ArchiveImages.MaxProxyBytes;
@@ -93,8 +98,11 @@ public static class FileEndpoints
return ApiErrors.Result(context, StatusCodes.Status422UnprocessableEntity, "invalid_proxy");
case ProxyStoreResult.WrongFrame:
return ApiErrors.Result(context, StatusCodes.Status422UnprocessableEntity, "proxy_mismatch");
case ProxyStoreResult.TooSmall:
return ApiErrors.Result(context, StatusCodes.Status422UnprocessableEntity, "proxy_too_small");
}
await follow.ProxyArrivedAsync(sequence, ct);
// The proxy is filed: its follow-up is queued even when the sender is gone by now.
await follow.ProxyArrivedAsync(sequence, CancellationToken.None);
return Results.NoContent();
}
+2 -6
View File
@@ -1,6 +1,5 @@
using Titano.Core.Archiving;
using Titano.Core.Imaging;
using Titano.Core.Imaging.Decoders;
using Titano.Core.Model;
using Titano.Data;
using Titano.Data.Archiving;
@@ -17,11 +16,8 @@ public static class ServerProxies
{
private const int Page = 1000;
/// <summary>The server's decoders (BRIEF §4.2: managed only).</summary>
private static readonly ImageDecoder Decoder = DecoderFactory.CreateServer();
/// <summary>The server takes this format's pixels from proxies made elsewhere.</summary>
public static bool CannotDecode(ImageFileFormat format) => ArchiveImages.NeedsProxy(Decoder, format);
/// <summary>The server takes this format's pixels from proxies made elsewhere (its decoders are managed only, BRIEF §4.2).</summary>
public static bool CannotDecode(ImageFileFormat format) => ArchiveImages.ServerNeedsProxy(format);
/// <summary>How proxies of the archive are made; null when it makes none (or its manifest cannot be read now).</summary>
public static ProxySpec? Spec(Archive archive)
@@ -78,6 +78,34 @@ public sealed class ProxyTests(TestContext context)
Assert.False((await fx.Db.Sequences.GetAsync(sequence.Id, fx.Ct))!.Status.HasFlag(SequenceStatus.ProxiesBuilt));
}
[Test]
public async Task AProxyMadeFromAPreviewIsAskedForAgain()
{
await using var fx = await CreateAsync(context);
var (sequence, frames) = await HeifSequenceAsync(fx, 4032, 3024);
var folder = fx.Paths.Sequence(sequence.Folder);
var images = fx.Service.Images;
// An earlier version made the frame's proxy here from the original's embedded preview: the frame's capture time,
// a thumbnail's size.
Directory.CreateDirectory(folder.Proxies);
await File.WriteAllBytesAsync(folder.Proxy(0), Proxy(frames[0].CapturedAt!.Value, 5, 160, 120), fx.Ct);
await fx.Db.Sequences.UpdateStatusAsync(sequence.Id, SequenceStatus.ProxiesBuilt, SequenceStatus.None, fx.Ct);
var proxies = await images.BuildProxiesAsync(fx.Archive, sequence, force: false, 0, (_, _) => ValueTask.CompletedTask, fx.Ct);
Assert.Equal((0, 0, 2), (proxies.Built, proxies.Reused, proxies.Undecodable));
Assert.FileMissing(folder.Proxy(0));
Assert.False((await fx.Db.Sequences.GetAsync(sequence.Id, fx.Ct))!.Status.HasFlag(SequenceStatus.ProxiesBuilt), "asked for again");
// A client or render node sending one that small is refused; one of the policy's size (1920 px) is kept.
var frame = frames[0] with { Width = 4032, Height = 3024 };
Assert.Equal(ProxyStoreResult.TooSmall, images.StoreProxy(fx.Archive, sequence, frame, Proxy(frame.CapturedAt!.Value, 6, 160, 120)));
Assert.Equal(ProxyStoreResult.Stored, images.StoreProxy(fx.Archive, sequence, frame, Proxy(frame.CapturedAt!.Value, 7, 1920, 1440)));
var again = await images.BuildProxiesAsync(fx.Archive, sequence, force: false, 0, (_, _) => ValueTask.CompletedTask, fx.Ct);
Assert.Equal((0, 1, 1), (again.Built, again.Reused, again.Undecodable));
Assert.FileExists(folder.Proxy(0));
}
[Test]
public async Task AnArchiveWithoutProxiesRefusesThem()
{
@@ -90,8 +118,11 @@ public sealed class ProxyTests(TestContext context)
Assert.FileMissing(fx.Paths.Sequence(sequence.Folder).Proxy(0));
}
/// <summary>Two ingested frames whose originals the archive engine takes for HEIF (its decoders read none).</summary>
private static async Task<(Sequence Sequence, IReadOnlyList<Frame> Frames)> HeifSequenceAsync(ArchiveFixture fx)
/// <summary>
/// Two ingested frames whose originals the archive engine takes for HEIF (its decoders read none), their size in the
/// sidecar <paramref name="width"/> × <paramref name="height"/> when given.
/// </summary>
private static async Task<(Sequence Sequence, IReadOnlyList<Frame> Frames)> HeifSequenceAsync(ArchiveFixture fx, int? width = null, int? height = null)
{
Guid id = default;
for (var i = 0; i < 2; i++)
@@ -103,14 +134,17 @@ public sealed class ProxyTests(TestContext context)
var sequence = (await fx.Db.Sequences.GetAsync(id, fx.Ct))!;
var folder = fx.Paths.Sequence(sequence.Folder);
var sidecar = ManifestStore.ReadSequence(folder.ManifestPath);
ManifestStore.WriteSequence(folder.ManifestPath, sidecar with { Frames = [.. sidecar.Frames.Select(f => f with { Format = ImageFileFormat.Heif })] });
ManifestStore.WriteSequence(folder.ManifestPath, sidecar with
{
Frames = [.. sidecar.Frames.Select(f => f with { Format = ImageFileFormat.Heif, W = width ?? f.W, H = height ?? f.H })],
});
return (sequence, await fx.Db.Frames.ListBySequenceAsync(id));
}
/// <summary>A 320 × 240 JPEG proxy with <paramref name="captured"/> in its Exif, as a client makes it.</summary>
private static byte[] Proxy(DateTime captured, int seed)
/// <summary>A JPEG proxy (320 × 240 unless sized) with <paramref name="captured"/> in its Exif, as a client makes it.</summary>
private static byte[] Proxy(DateTime captured, int seed, int width = 320, int height = 240)
{
using var image = new ImageBuffer(320, 240);
using var image = new ImageBuffer(width, height);
var level = 0.2f + seed % 5 * 0.1f;
for (var c = 0; c < 3; c++) image.Plane(c).Fill(level + c * 0.05f);
var exif = ExifWriter.BuildJpegApp1(new FrameMetadata { CapturedAt = captured, Software = "Titano" });
@@ -69,9 +69,11 @@ public sealed class RenderNodeClientTests(TestContext context)
var sequenceId = await UploadSequenceAsync(editor, Photos()[..3]);
await Uploads.UploadAsync(editor, [0, 0, 0, 24, .. "ftypheic"u8, 0, 0, 0, 0, .. "mif1heic"u8, .. Uploads.Photo(2000, 9)], "IMG_0004.HEIC", sequenceId);
var frames = await server.Database.Frames.ListBySequenceAsync(sequenceId);
// Frame 1 is gone from the server, frame 2 was adopted and never hashed, frame 4 is a HEIF the server cannot decode.
// Frame 1 is gone from the server, frame 2 was adopted and never hashed, frame 3 is damaged (the server could not
// decode it) and frame 4 is a HEIF the server cannot decode.
File.Delete(Path.Combine(server.Options.ArchivePath, frames[0].RelativePath));
await server.Database.Frames.UpdateFlagsAsync([frames[0].Id], FrameFlags.Missing, FrameFlags.None);
await server.Database.Frames.UpdateFlagsAsync([frames[2].Id, frames[3].Id], FrameFlags.Undecodable, FrameFlags.None);
await using (var session = await server.Database.Database.OpenAsync(context.Cancellation))
{
await session.ExecuteAsync("UPDATE frames SET sha256 = NULL WHERE id = $1", [frames[1].Id], context.Cancellation);
@@ -89,6 +91,9 @@ public sealed class RenderNodeClientTests(TestContext context)
Assert.Equal("done", done.State, done.Error);
Assert.DoesNotContain($"/api/v1/frames/{frames[0].Id}/original", requests.Paths);
Assert.Contains($"/api/v1/frames/{frames[1].Id}/original", requests.Paths);
// The damaged frame stays out, as in the server's own render; the HEIF renders from its original here.
Assert.DoesNotContain($"/api/v1/frames/{frames[2].Id}/original", requests.Paths);
Assert.Contains($"/api/v1/frames/{frames[3].Id}/original", requests.Paths);
var sequence = (await server.Database.Sequences.GetAsync(sequenceId))!;
var proxy = new ArchivePaths(server.Options.ArchivePath).Sequence(sequence.Folder).Proxy(frames[3].Index);
Assert.Equal(frames[3].CapturedAt, MetadataReader.Read(proxy).CapturedAt, "the proxy the server asked for, with the frame's capture time");
@@ -70,6 +70,9 @@ public sealed class ProxyUploadTests(TestContext context)
var upload = await Uploads.UploadAsync(editor, Proxy(new DateTime(2026, 9, 28, 18, 2, 11)), "IMG_0001.JPG", sessionKey: "roof");
Assert.False((await ManifestAsync(editor, upload.SequenceId)).Frames.Single().WantsProxy);
// Nor takes one: renders and remote views keep the proxy the server makes itself.
using var refused = await PutAsync(editor, upload.FrameId, Proxy(new DateTime(2026, 9, 28, 18, 2, 11)));
await refused.ExpectErrorAsync(HttpStatusCode.UnprocessableEntity, "proxy_not_wanted");
}
/// <summary>A HEIF file as far as signature sniffing goes (an <c>ftyp</c> box naming heic), with no pixels the server can read.</summary>