dtourolleandClaude Opus 5
5152f6f129
Three routes now deliver truth data -- a sidecar, a worker push, and a fetched
manifest -- and once stored they were indistinguishable. The truth file records
nothing about how it arrived, so a locally computed sidecar and a loose-tier
manifest from a third-party server looked identical to every reader, despite
making claims of very different strength about the same item.
TruthProvenance records source, server, match tier, applied offset and caveat.
GET /Items/{itemId}/Provenance serves it, and JR-036's loose-tier caveat now
has somewhere to come from.
Two decisions carried in the code rather than assumed:
Provenance is stored BESIDE the truth file, never inside it. Injecting fields
would mean the bytes served back are not the bytes the producer wrote, which is
the property JR-004 turns on. UT-026 pins it by asserting the stored truth JSON
contains no provenance keys.
The applied offset is recorded because it is otherwise unrecoverable. Once
JR-030 shifts every window the timings look native, and nothing else would say
they had been shifted -- which matters when diagnosing an overlay that is
consistently a few seconds out.
A sidecar's provenance is derived rather than stored: it is local, and its
timestamp is the file's own. Precedence resolves through the same rule as
GetTruthAsync, because resolving it twice by different rules is how the two
would drift.
Fourth mutation check: stopping Delete from removing provenance fails UT-027
alone -- a stale record would otherwise outlive its claim and describe data the
next fetch had already replaced.
TRACES: UT-024, UT-025, UT-026, UT-027, UT-028 | JR-010
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
58 lines
2.5 KiB
C#
58 lines
2.5 KiB
C#
using System;
|
|
using System.Threading;
|
|
using System.Threading.Tasks;
|
|
using Jellyfin.Plugin.JRay.Models;
|
|
|
|
namespace Jellyfin.Plugin.JRay.Services.Interfaces;
|
|
|
|
/// <summary>
|
|
/// Stores and retrieves truth files that were pushed to JRay directly
|
|
/// (e.g. by a remote extraction worker), independent of any sidecar file
|
|
/// on the media filesystem.
|
|
/// </summary>
|
|
public interface IManagedTruthStore
|
|
{
|
|
/// <summary>
|
|
/// Loads the managed truth file for the given item, if one was uploaded.
|
|
/// </summary>
|
|
/// <param name="itemId">The Jellyfin library item id.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>The parsed truth file, or null if none has been uploaded for this item.</returns>
|
|
Task<TruthFile?> LoadAsync(Guid itemId, CancellationToken cancellationToken);
|
|
|
|
/// <summary>
|
|
/// Saves (creates or replaces) the managed truth file for the given item.
|
|
/// </summary>
|
|
/// <param name="itemId">The Jellyfin library item id.</param>
|
|
/// <param name="truth">The truth file contents to persist.</param>
|
|
/// <param name="provenance">How this truth data was obtained.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>A task that completes when the file has been written.</returns>
|
|
/// <remarks>
|
|
/// Provenance is written beside the truth file, never into it: the bytes
|
|
/// served back must be the bytes the producer wrote (JR-004).
|
|
/// </remarks>
|
|
Task SaveAsync(Guid itemId, TruthFile truth, TruthProvenance provenance, CancellationToken cancellationToken);
|
|
|
|
/// <summary>
|
|
/// Loads the provenance recorded alongside an item's managed truth data.
|
|
/// </summary>
|
|
/// <param name="itemId">The Jellyfin library item id.</param>
|
|
/// <returns>The provenance, or null if this item has no managed truth data.</returns>
|
|
TruthProvenance? LoadProvenance(Guid itemId);
|
|
|
|
/// <summary>
|
|
/// Deletes the managed truth file for the given item, if one exists.
|
|
/// </summary>
|
|
/// <param name="itemId">The Jellyfin library item id.</param>
|
|
/// <returns><c>true</c> if a file was deleted; <c>false</c> if none existed.</returns>
|
|
bool Delete(Guid itemId);
|
|
|
|
/// <summary>
|
|
/// Checks whether a managed truth file has been uploaded for the given item.
|
|
/// </summary>
|
|
/// <param name="itemId">The Jellyfin library item id.</param>
|
|
/// <returns><c>true</c> if a managed truth file exists.</returns>
|
|
bool Exists(Guid itemId);
|
|
}
|