dtourolle
19aecee646
Replaces the v1 shape rather than accepting both. `anneal_sec` and the top-level `sample_fps` are deleted, not zeroed; `extraction` and `cut` blocks arrive; `scenes` become objects carrying belief and route, so a window records how far to trust it instead of being a bare float pair. `TruthSchema.IsSupported` is the single gate and is applied on all four read paths — sidecar, managed store load, managed PUT, and converted manifest. Previously only the controller checked, so the version the plugin claimed to require and the one it would actually parse were free to drift. Rejections name the file and the version found, so an item that looks empty is distinguishable from one that was refused. `ManifestConverter` carries belief, route and both provenance blocks through: dropping them would silently downgrade every fetched manifest against a locally extracted one. TRACES: JR-002, JR-003 | SR-003
70 lines
3.0 KiB
C#
70 lines
3.0 KiB
C#
using System.Globalization;
|
|
using Jellyfin.Plugin.JRay.Models;
|
|
|
|
namespace Jellyfin.Plugin.JRay.Services;
|
|
|
|
/// <summary>
|
|
/// The one place that decides whether a truth file speaks a version this plugin
|
|
/// understands.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <b>Flag day, not dual-accept.</b> Only <see cref="SupportedVersion"/> is
|
|
/// accepted; every other value is refused on every path — sidecar read, managed
|
|
/// <c>PUT</c>, managed store load, and converted manifest. There is no
|
|
/// transitional v1 read path.
|
|
/// <para>
|
|
/// All three components are pre-release and move together, and the alternative
|
|
/// carries a cost that outlasts the transition: a v1 read path is the one nobody
|
|
/// exercises, so it is the one that rots, and it would have to be dragged
|
|
/// through every subsequent change to the reader.
|
|
/// </para>
|
|
/// <para>
|
|
/// <b>The consequence is stated rather than discovered:</b> v1 sidecar files
|
|
/// already on disk stop being read at the bump and stay dark until the library
|
|
/// is re-extracted. Callers log the rejection naming the file and the version
|
|
/// found, because an item that looks un-extracted when it is merely stale is the
|
|
/// failure mode that wastes a user's compute.
|
|
/// </para>
|
|
/// <para>
|
|
/// This exists as a shared unit because the check used to live only in the
|
|
/// <c>PUT</c> controller while sidecar reads did not check at all — so the
|
|
/// format the plugin claimed to require and the format it would actually parse
|
|
/// were different things.
|
|
/// </para>
|
|
/// </remarks>
|
|
// TRACES: JR-003 | SR-003
|
|
public static class TruthSchema
|
|
{
|
|
/// <summary>
|
|
/// The only <c>schema_version</c> this plugin reads or writes.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// System-level (SR-003): the same number means the same format in all three
|
|
/// repos, and is incremented once per breaking change across all of them.
|
|
/// </remarks>
|
|
public const int SupportedVersion = 2;
|
|
|
|
/// <summary>
|
|
/// Determines whether a truth file speaks the supported version.
|
|
/// </summary>
|
|
/// <param name="truth">The parsed truth file, which may be <c>null</c>.</param>
|
|
/// <returns><c>true</c> only when the version matches exactly.</returns>
|
|
public static bool IsSupported(TruthFile? truth)
|
|
=> truth is not null && truth.SchemaVersion == SupportedVersion;
|
|
|
|
/// <summary>
|
|
/// Builds the message describing why a truth file was refused.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Names both the version found and the version expected. A rejection that
|
|
/// says only "unsupported" leaves the reader unable to tell a stale file
|
|
/// from a corrupt one.
|
|
/// </remarks>
|
|
/// <param name="found">The version encountered.</param>
|
|
/// <returns>A message naming both versions.</returns>
|
|
public static string DescribeRejection(int found)
|
|
=> string.Create(
|
|
CultureInfo.InvariantCulture,
|
|
$"Unsupported schema_version {found}; expected {SupportedVersion}. Re-extract the item — v1 truth data is no longer read.");
|
|
}
|