jRay/Jellyfin.Plugin.JRay/Services/TruthDataService.cs

using System;
using System.Collections.Concurrent;
using System.IO;
using System.Text.Json;
using System.Threading;
using System.Threading.Tasks;
using Jellyfin.Plugin.JRay.Models;
using Jellyfin.Plugin.JRay.Services.Interfaces;
using MediaBrowser.Controller.Library;
using Microsoft.Extensions.Logging;

namespace Jellyfin.Plugin.JRay.Services;

/// <summary>
/// Loads scene-actor-extraction truth files from disk, alongside each media
/// item's source file, and caches the parsed result for a configurable
/// duration.
/// </summary>
/// <remarks>
/// Managed truth — pushed by a worker, or fetched from a manifest server —
/// takes precedence over a sidecar file. Storing fetched manifests through the
/// managed store is what keeps this a two-way rule rather than a three-way one,
/// so the read path never learns that the exchange exists.
/// </remarks>
// TRACES: JR-008, JR-010, JR-011 | PR-001
public sealed class TruthDataService : ITruthDataService
{
    private static readonly JsonSerializerOptions JsonOptions = new(JsonSerializerDefaults.Web);

    private readonly ILibraryManager _libraryManager;
    private readonly IManagedTruthStore _managedTruthStore;
    private readonly ILogger<TruthDataService> _logger;
    private readonly ConcurrentDictionary<Guid, CacheEntry> _cache = new();

    /// <summary>
    /// Initializes a new instance of the <see cref="TruthDataService"/> class.
    /// </summary>
    /// <param name="libraryManager">The Jellyfin library manager.</param>
    /// <param name="managedTruthStore">The managed truth store.</param>
    /// <param name="logger">The logger.</param>
    public TruthDataService(ILibraryManager libraryManager, IManagedTruthStore managedTruthStore, ILogger<TruthDataService> logger)
    {
        _libraryManager = libraryManager;
        _managedTruthStore = managedTruthStore;
        _logger = logger;
    }

    /// <inheritdoc />
    public async Task<TruthFile?> GetTruthAsync(Guid itemId, CancellationToken cancellationToken)
    {
        var cacheDuration = TimeSpan.FromMinutes(Math.Max(0, Plugin.Instance?.Configuration.CacheDurationMinutes ?? 0));

        if (_cache.TryGetValue(itemId, out var cached) && DateTime.UtcNow - cached.LoadedAt < cacheDuration)
        {
            return cached.Truth;
        }

        var managed = await _managedTruthStore.LoadAsync(itemId, cancellationToken).ConfigureAwait(false);
        if (managed is not null)
        {
            _cache[itemId] = new CacheEntry(managed, DateTime.UtcNow);
            return managed;
        }

        var item = _libraryManager.GetItemById(itemId);
        if (item is null || string.IsNullOrEmpty(item.Path))
        {
            _logger.LogDebug("JRay: item {ItemId} not found or has no path", itemId);
            return null;
        }

        var truthPath = GetSidecarPath(item.Path);

        if (!File.Exists(truthPath))
        {
            _logger.LogDebug("JRay: no truth file at {TruthPath}", truthPath);
            _cache[itemId] = new CacheEntry(null, DateTime.UtcNow);
            return null;
        }

        try
        {
            using var stream = File.OpenRead(truthPath);
            var truth = await JsonSerializer.DeserializeAsync<TruthFile>(stream, JsonOptions, cancellationToken)
                .ConfigureAwait(false);

            if (!TruthSchema.IsSupported(truth))
            {
                // Named, not silent. A stale v1 sidecar makes an item look
                // un-extracted, and re-extracting a library that has already
                // been processed is the most expensive mistake this plugin can
                // cause a user to make. The log line is what distinguishes the
                // two states.
                _logger.LogWarning(
                    "JRay: ignoring truth file {TruthPath} — schema_version {Found}, expected {Expected}. Re-extract this item.",
                    truthPath,
                    truth?.SchemaVersion ?? 0,
                    TruthSchema.SupportedVersion);
                _cache[itemId] = new CacheEntry(null, DateTime.UtcNow);
                return null;
            }

            _cache[itemId] = new CacheEntry(truth, DateTime.UtcNow);
            return truth;
        }
        catch (Exception ex) when (ex is IOException or JsonException)
        {
            // A v1 file also lands here rather than above: `scenes` was a float
            // pair in v1 and is an object in v2, so it fails to deserialise
            // before the version can be inspected. Both routes must therefore
            // name the file, which is why the message below says the same thing.
            _logger.LogWarning(
                ex,
                "JRay: failed to read truth file {TruthPath}. If this is a v1 file, re-extract the item — v1 is no longer read.",
                truthPath);
            return null;
        }
    }

    /// <inheritdoc />
    public TruthProvenance? GetProvenance(Guid itemId)
    {
        // Managed truth wins, exactly as in GetTruthAsync -- resolving
        // precedence twice by different rules is how the two would drift.
        var managed = _managedTruthStore.LoadProvenance(itemId);
        if (managed is not null)
        {
            return managed;
        }

        var item = _libraryManager.GetItemById(itemId);
        if (item is null || string.IsNullOrEmpty(item.Path))
        {
            return null;
        }

        var sidecarPath = GetSidecarPath(item.Path);
        if (!File.Exists(sidecarPath))
        {
            return null;
        }

        // A sidecar records nothing about itself, so its provenance is derived:
        // it is local, and its timestamp is the file's own.
        return TruthProvenance.Local(TruthSource.Sidecar, File.GetLastWriteTimeUtc(sidecarPath));
    }

    /// <inheritdoc />
    public void Invalidate(Guid itemId)
    {
        _cache.TryRemove(itemId, out _);
    }

    /// <inheritdoc />
    public bool HasTruth(Guid itemId, string itemPath)
    {
        return _managedTruthStore.Exists(itemId) || File.Exists(GetSidecarPath(itemPath));
    }

    private static string GetSidecarPath(string itemPath)
    {
        var suffix = Plugin.Instance?.Configuration.TruthFileSuffix ?? ".jray.json";
        return Path.Combine(
            Path.GetDirectoryName(itemPath) ?? string.Empty,
            Path.GetFileNameWithoutExtension(itemPath) + suffix);
    }

    private sealed record CacheEntry(TruthFile? Truth, DateTime LoadedAt);
}