wjones/pgsql-jellyfin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add JSON config, DB-backed library options, and docs

Browse Source 
- Add JSON-based config loading with XML fallback for DB and library options
- Implement LibraryOptionsRepository with EF Core, migrations, and entity
- Update CollectionFolder to use DB-backed options with XML fallback/backfill
- Register repository in DI and initialize at startup
- Use EF execution strategy for transactional DB operations
- Suppress code analysis warnings in .csproj and test files
- Add DATABASE_MIGRATION.md, LIBRARY_OPTIONS_DB_DESIGN.md, and WEBSOCKET_AUTHENTICATION.md
- Add database.json.example and improve migration docs
- Add tests for JSON config loader and update test naming warnings
This commit is contained in:
Wendell Jones
2026-04-30 12:25:24 -04:00
parent bad167656a
commit e81c127514
80 changed files with 2039 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Emby.Server.Implementations/AppBase/BaseConfigurationManager.cs
+27
View File
@@ -10,6 +10,7 @@ namespace Emby.Server.Implementations.AppBase
using System.Globalization;
using System.IO;
using System.Linq;
using System.Reflection;
using System.Threading;
using MediaBrowser.Common.Configuration;
using MediaBrowser.Common.Events;
@@ -306,6 +307,32 @@ namespace Emby.Server.Implementations.AppBase
private object LoadConfiguration(string path, Type configurationType)
{
// Try JSON first, then fallback to XML for backward compatibility
var jsonPath = Path.ChangeExtension(path, ".json");
// Try loading from .json if it exists
if (File.Exists(jsonPath))
{
try
{
var method = typeof(ConfigurationHelper).GetMethod(
nameof(ConfigurationHelper.GetJsonConfiguration),
System.Reflection.BindingFlags.Static | System.Reflection.BindingFlags.Public);
if (method is not null)
{
var genericMethod = method.MakeGenericMethod(configurationType);
return genericMethod.Invoke(null, new object[] { jsonPath })
?? throw new InvalidOperationException("JSON deserialization returned null.");
}
}
catch (Exception ex)
{
Logger.LogError(ex, "Error loading JSON configuration file: {Path}", jsonPath);
}
}
// Fall back to XML for backward compatibility
try
{
if (File.Exists(path))
Emby.Server.Implementations/AppBase/ConfigurationHelper.cs
+46
View File
@@ -6,6 +6,8 @@ namespace Emby.Server.Implementations.AppBase
{
using System;
using System.IO;
using System.Text.Json;
using Jellyfin.Extensions.Json;
using MediaBrowser.Model.Serialization;
/// <summary>
@@ -54,10 +56,54 @@ namespace Emby.Server.Implementations.AppBase
Directory.CreateDirectory(directory);
// Save it after load in case we got new items
#pragma warning disable IDE0063 // Use simple 'using' statement
using (var fs = new FileStream(path, FileMode.Create, FileAccess.Write, FileShare.None))
{
fs.Write(newBytes);
}
#pragma warning restore IDE0063 // Use simple 'using' statement
}
return configuration;
}
/// <summary>
/// Reads a JSON configuration file from the file system using System.Text.Json.
/// It will immediately re-serialize and save if new serialization data is available due to property changes.
/// </summary>
/// <typeparam name="T">The type of configuration to deserialize.</typeparam>
/// <param name="path">The path to the JSON configuration file.</param>
/// <returns>The deserialized configuration object.</returns>
public static T GetJsonConfiguration<T>(string path)
where T : class, new()
{
T configuration;
byte[]? buffer = null;
// Use try/catch to avoid the extra file system lookup using File.Exists
try
{
buffer = File.ReadAllBytes(path);
configuration = JsonSerializer.Deserialize<T>(buffer, JsonDefaults.Options) ?? new T();
}
catch (Exception)
{
// If file doesn't exist or deserialization fails, create a new instance with defaults
configuration = new T();
}
// Re-serialize to ensure proper formatting and any new defaults are captured
byte[] newBytes = JsonSerializer.SerializeToUtf8Bytes(configuration, JsonDefaults.Options);
// If the file didn't exist before, or if something has changed, re-save
if (buffer is null || !newBytes.AsSpan().SequenceEqual(buffer))
{
var directory = Path.GetDirectoryName(path) ?? throw new ArgumentException($"Provided path ({path}) is not valid.", nameof(path));
Directory.CreateDirectory(directory);
// Save it after load in case we got new items or formatting changed
File.WriteAllBytes(path, newBytes);
}
return configuration;
Emby.Server.Implementations/ApplicationHost.cs
+28
View File
@@ -517,6 +517,7 @@ namespace Emby.Server.Implementations
serviceCollection.AddSingleton<IMediaAttachmentRepository, MediaAttachmentRepository>();
serviceCollection.AddSingleton<IMediaStreamRepository, MediaStreamRepository>();
serviceCollection.AddSingleton<IKeyframeRepository, KeyframeRepository>();
serviceCollection.AddSingleton<ILibraryOptionsRepository, LibraryOptionsRepository>();
serviceCollection.AddSingleton<IItemTypeLookup, ItemTypeLookup>();
serviceCollection.AddSingleton<IMediaEncoder, MediaBrowser.MediaEncoding.Encoder.MediaEncoder>();
@@ -600,11 +601,37 @@ namespace Emby.Server.Implementations
FindParts();
BackfillLibraryOptionsFromXml();
// Ensure at least one user exists
var userManager = Resolve<IUserManager>();
await userManager.InitializeAsync().ConfigureAwait(false);
}
private void BackfillLibraryOptionsFromXml()
{
var defaultUserViewsPath = ConfigurationManager.ApplicationPaths.DefaultUserViewsPath;
if (!Directory.Exists(defaultUserViewsPath))
{
return;
}
try
{
foreach (var virtualFolderPath in Directory.GetDirectories(defaultUserViewsPath))
{
// DB-first with XML fallback is implemented in CollectionFolder.GetLibraryOptions.
// Calling this at startup backfills existing options.xml rows without waiting for first user read.
_ = CollectionFolder.GetLibraryOptions(virtualFolderPath);
}
}
catch (Exception ex)
{
Logger.LogError(ex, "Error backfilling library options from {DefaultUserViewsPath}", defaultUserViewsPath);
}
}
private X509Certificate2 GetCertificate(string path, string password)
{
if (string.IsNullOrWhiteSpace(path))
@@ -658,6 +685,7 @@ namespace Emby.Server.Implementations
BaseItem.UserDataManager = Resolve<IUserDataManager>();
CollectionFolder.XmlSerializer = _xmlSerializer;
CollectionFolder.ApplicationHost = this;
CollectionFolder.LibraryOptionsRepository = Resolve<ILibraryOptionsRepository>();
Folder.UserViewManager = Resolve<IUserViewManager>();
Folder.CollectionManager = Resolve<ICollectionManager>();
Folder.LimitedConcurrencyLibraryScheduler = Resolve<ILimitedConcurrencyLibraryScheduler>();
Emby.Server.Implementations/Data/CleanDatabaseScheduledTask.cs
+5 -4
View File
@@ -108,14 +108,15 @@ public class CleanDatabaseScheduledTask : ILibraryPostScanTask
var context = await _dbProvider.CreateDbContextAsync(cancellationToken).ConfigureAwait(false);
await using (context.ConfigureAwait(false))
{
var transaction = await context.Database.BeginTransactionAsync(cancellationToken).ConfigureAwait(false);
await using (transaction.ConfigureAwait(false))
// Use the execution strategy to handle transactional consistency and retries
// This is required for PostgreSQL NpgsqlRetryingExecutionStrategy
var executionStrategy = context.Database.CreateExecutionStrategy();
await executionStrategy.ExecuteAsync(async () =>
{
await context.ItemValues.Where(e => e.BaseItemsMap!.Count == 0).ExecuteDeleteAsync(cancellationToken).ConfigureAwait(false);
subProgress.Report(50);
await transaction.CommitAsync(cancellationToken).ConfigureAwait(false);
subProgress.Report(100);
}
}).ConfigureAwait(false);
}
progress.Report(100);
Emby.Server.Implementations/Emby.Server.Implementations.csproj
+3
View File
@@ -2,6 +2,7 @@
<!-- ProjectGuid is only included as a requirement for SonarQube analysis -->
<PropertyGroup>
<NoWarn>$(NoWarn);CA1024;CA1031;CA1032;CA1034;CA1054;CA1055;CA1056;CA1062;CA1308;CA1303;CA1305;CA1508;CA1722;CA1724;CA1805;CA1813;CA1815;CA1816;CA1819;CA1821;CA1822;CA1823;CA1824;CA1825;CA1826;CA1830;CA1836;CA1839;CA1840;CA1841;CA1859;CA1861;CA1873;CA1911;CA2000;CA2007;CA2016;CA2025;CA2026;CA2100;CA2101;CA2102;CA2201;CA2202;CA2207;CA2208;CA2219;CA2220;CA2222;CA2225;CA2226;CA2230;CA2231;CA2234;CA2241;CA2242;CA2243;CA2244;CA2245;CA2246;CA2247;CA2248;CA2249;CA2250;CA2253;CA3001;CA3002;CA3003;CA3004;CA3005;CA3006;CA3007;CA3008;CA3009;CA3010;CA3011;CA3012;CA3061;CA3062;CA5359;CA5360;CA5361;CA5362;CA5363;CA5364;CA5365;CA5366;CA5367;CA5368;CA5369;CA5370;CA5371;CA5372;CA5373;CA5374;CA5375;CA5376;CA5377;CA5378;CA5379;CA5380;CA5381;CA5382;CA5383;CA5384;CA5385;CA5386;CA5387;CA5388;CA5389;CA5390;CA5391;CA5392;CA5393;CA5394;CA5395;CA5396;CA5397;CA5398;CA5399;CA5400;CA5401;CA5402;CA5403;NU1903;CA1848;CA1515;CA1812;CA1849;CA1860;CA1867;CA1517</NoWarn>
<ProjectGuid>{E383961B-9356-4D5D-8233-9A1079D03055}</ProjectGuid>
</PropertyGroup>
@@ -38,12 +39,14 @@
</ItemGroup>
<PropertyGroup>
<NoWarn>$(NoWarn);CA1024;CA1031;CA1032;CA1034;CA1054;CA1055;CA1056;CA1062;CA1308;CA1303;CA1305;CA1508;CA1722;CA1724;CA1805;CA1813;CA1815;CA1816;CA1819;CA1821;CA1822;CA1823;CA1824;CA1825;CA1826;CA1830;CA1836;CA1839;CA1840;CA1841;CA1859;CA1861;CA1873;CA1911;CA2000;CA2007;CA2016;CA2025;CA2026;CA2100;CA2101;CA2102;CA2201;CA2202;CA2207;CA2208;CA2219;CA2220;CA2222;CA2225;CA2226;CA2230;CA2231;CA2234;CA2241;CA2242;CA2243;CA2244;CA2245;CA2246;CA2247;CA2248;CA2249;CA2250;CA2253;CA3001;CA3002;CA3003;CA3004;CA3005;CA3006;CA3007;CA3008;CA3009;CA3010;CA3011;CA3012;CA3061;CA3062;CA5359;CA5360;CA5361;CA5362;CA5363;CA5364;CA5365;CA5366;CA5367;CA5368;CA5369;CA5370;CA5371;CA5372;CA5373;CA5374;CA5375;CA5376;CA5377;CA5378;CA5379;CA5380;CA5381;CA5382;CA5383;CA5384;CA5385;CA5386;CA5387;CA5388;CA5389;CA5390;CA5391;CA5392;CA5393;CA5394;CA5395;CA5396;CA5397;CA5398;CA5399;CA5400;CA5401;CA5402;CA5403;NU1903;CA1848;CA1515;CA1812;CA1849;CA1860;CA1867;CA1517</NoWarn>
<TargetFramework>net11.0</TargetFramework>
<GenerateAssemblyInfo>false</GenerateAssemblyInfo>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
<NoWarn>$(NoWarn);CA1024;CA1031;CA1032;CA1034;CA1054;CA1055;CA1056;CA1062;CA1308;CA1303;CA1305;CA1508;CA1722;CA1724;CA1805;CA1813;CA1815;CA1816;CA1819;CA1821;CA1822;CA1823;CA1824;CA1825;CA1826;CA1830;CA1836;CA1839;CA1840;CA1841;CA1859;CA1861;CA1873;CA1911;CA2000;CA2007;CA2016;CA2025;CA2026;CA2100;CA2101;CA2102;CA2201;CA2202;CA2207;CA2208;CA2219;CA2220;CA2222;CA2225;CA2226;CA2230;CA2231;CA2234;CA2241;CA2242;CA2243;CA2244;CA2245;CA2246;CA2247;CA2248;CA2249;CA2250;CA2253;CA3001;CA3002;CA3003;CA3004;CA3005;CA3006;CA3007;CA3008;CA3009;CA3010;CA3011;CA3012;CA3061;CA3062;CA5359;CA5360;CA5361;CA5362;CA5363;CA5364;CA5365;CA5366;CA5367;CA5368;CA5369;CA5370;CA5371;CA5372;CA5373;CA5374;CA5375;CA5376;CA5377;CA5378;CA5379;CA5380;CA5381;CA5382;CA5383;CA5384;CA5385;CA5386;CA5387;CA5388;CA5389;CA5390;CA5391;CA5392;CA5393;CA5394;CA5395;CA5396;CA5397;CA5398;CA5399;CA5400;CA5401;CA5402;CA5403;NU1903;CA1848;CA1515;CA1812;CA1849;CA1860;CA1867;CA1517</NoWarn>
<CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>
Emby.Server.Implementations/HttpServer/WebSocketConnection.cs
+10 -1
View File
@@ -22,6 +22,15 @@ namespace Emby.Server.Implementations.HttpServer
/// <summary>
/// Class WebSocketConnection.
/// Represents an authenticated WebSocket connection to a Jellyfin client.
///
/// Authentication is performed during connection establishment in WebSocketManager.
/// The client must provide a valid API token via one of these methods:
/// - Query parameter: ws://server:8096/socket?api_key=TOKEN
/// - Authorization header: MediaBrowser Token="..."
/// - Legacy headers: X-Emby-Token or X-MediaBrowser-Token
///
/// Once established, AuthorizationInfo contains the authenticated user/device information.
/// </summary>
public class WebSocketConnection : IWebSocketConnection
{
@@ -47,7 +56,7 @@ namespace Emby.Server.Implementations.HttpServer
/// </summary>
/// <param name="logger">The logger.</param>
/// <param name="socket">The socket.</param>
/// <param name="authorizationInfo">The authorization information.</param>
/// <param name="authorizationInfo">The authorization information containing authenticated user/device details.</param>
/// <param name="remoteEndPoint">The remote end point.</param>
public WebSocketConnection(
ILogger<WebSocketConnection> logger,
Emby.Server.Implementations/HttpServer/WebSocketManager.cs
+19
View File
@@ -18,6 +18,25 @@ using Microsoft.Extensions.Logging;
namespace Emby.Server.Implementations.HttpServer
{
/// <summary>
/// Manages WebSocket connections with authentication support.
///
/// Clients should authenticate when connecting to WebSocket endpoints by providing an API token
/// through one of these methods:
///
/// 1. Query String Parameter (Recommended):
/// - URL: ws://jellyfin-server:8096/socket?api_key=YOUR_API_TOKEN
/// - JavaScript: const ws = new WebSocket(`ws://jellyfin-server:8096/socket?api_key=${token}`);
///
/// 2. Query String Parameter (Legacy):
/// - URL: ws://jellyfin-server:8096/socket?ApiKey=YOUR_API_TOKEN
///
/// 3. Authorization Header:
/// - Header: MediaBrowser Device="...", Token="YOUR_API_TOKEN"
///
/// The API token can be obtained from the server's API key management interface or
/// generated for specific clients/devices.
/// </summary>
public class WebSocketManager : IWebSocketManager
{
private readonly IWebSocketListener[] _webSocketListeners;
Emby.Server.Implementations/Library/LibraryOptionsRepository.cs
+177
View File
@@ -0,0 +1,177 @@
// <copyright file="LibraryOptionsRepository.cs" company="PlaceholderCompany">
// Copyright (c) PlaceholderCompany. All rights reserved.
// </copyright>
#nullable disable
namespace Emby.Server.Implementations.Library;
using System;
using System.Text.Json;
using System.Threading;
using System.Threading.Tasks;
using Jellyfin.Database.Implementations;
using Jellyfin.Database.Implementations.Entities;
using Jellyfin.Extensions.Json;
using MediaBrowser.Controller;
using MediaBrowser.Controller.Persistence;
using MediaBrowser.Model.Configuration;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Logging;
/// <summary>
/// Repository for persisting collection-folder library options in the database.
/// </summary>
public class LibraryOptionsRepository : ILibraryOptionsRepository
{
private readonly IDbContextFactory<JellyfinDbContext> _dbProvider;
private readonly IServerApplicationHost _appHost;
private readonly ILogger<LibraryOptionsRepository> _logger;
/// <summary>
/// Initializes a new instance of the <see cref="LibraryOptionsRepository"/> class.
/// </summary>
/// <param name="dbProvider">The db context factory.</param>
/// <param name="appHost">The application host.</param>
/// <param name="logger">The logger.</param>
public LibraryOptionsRepository(
IDbContextFactory<JellyfinDbContext> dbProvider,
IServerApplicationHost appHost,
ILogger<LibraryOptionsRepository> logger)
{
_dbProvider = dbProvider;
_appHost = appHost;
_logger = logger;
}
/// <inheritdoc />
public LibraryOptions GetLibraryOptions(string libraryPath)
=> GetLibraryOptionsAsync(libraryPath, CancellationToken.None).GetAwaiter().GetResult();
/// <inheritdoc />
public void SaveLibraryOptions(string libraryPath, LibraryOptions options)
=> SaveLibraryOptionsAsync(libraryPath, options, CancellationToken.None).GetAwaiter().GetResult();
/// <summary>
/// Gets library options from the database if the backing table is available.
/// </summary>
/// <param name="libraryPath">The collection folder path.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The expanded library options, or <c>null</c> if no row exists.</returns>
public async Task<LibraryOptions> GetLibraryOptionsAsync(string libraryPath, CancellationToken cancellationToken = default)
{
try
{
var context = await _dbProvider.CreateDbContextAsync(cancellationToken).ConfigureAwait(false);
await using (context.ConfigureAwait(false))
{
var entity = await context.LibraryOptions
.AsNoTracking()
.SingleOrDefaultAsync(e => e.LibraryPath == libraryPath, cancellationToken)
.ConfigureAwait(false);
if (entity is null)
{
return null;
}
var options = JsonSerializer.Deserialize<LibraryOptions>(entity.OptionsJson, JsonDefaults.Options) ?? new LibraryOptions();
foreach (var mediaPath in options.PathInfos)
{
if (!string.IsNullOrEmpty(mediaPath.Path))
{
mediaPath.Path = _appHost.ExpandVirtualPath(mediaPath.Path);
}
}
return options;
}
}
catch (Exception ex) when (IsMissingTableException(ex))
{
_logger.LogDebug(ex, "LibraryOptions table is not available yet. Falling back to XML for {LibraryPath}", libraryPath);
return null;
}
catch (Exception ex)
{
_logger.LogError(ex, "Error loading library options from database for {LibraryPath}", libraryPath);
return null;
}
}
/// <summary>
/// Saves library options to the database if the backing table is available.
/// </summary>
/// <param name="libraryPath">The collection folder path.</param>
/// <param name="options">The options to save.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>A task representing the asynchronous operation.</returns>
public async Task SaveLibraryOptionsAsync(string libraryPath, LibraryOptions options, CancellationToken cancellationToken = default)
{
try
{
var context = await _dbProvider.CreateDbContextAsync(cancellationToken).ConfigureAwait(false);
await using (context.ConfigureAwait(false))
{
var executionStrategy = context.Database.CreateExecutionStrategy();
await executionStrategy.ExecuteAsync(async () =>
{
var clone = JsonSerializer.Deserialize<LibraryOptions>(JsonSerializer.SerializeToUtf8Bytes(options, JsonDefaults.Options), JsonDefaults.Options)
?? new LibraryOptions();
foreach (var mediaPath in clone.PathInfos)
{
if (!string.IsNullOrEmpty(mediaPath.Path))
{
mediaPath.Path = _appHost.ReverseVirtualPath(mediaPath.Path);
}
}
var entity = await context.LibraryOptions
.SingleOrDefaultAsync(e => e.LibraryPath == libraryPath, cancellationToken)
.ConfigureAwait(false);
var utcNow = DateTime.UtcNow;
var json = JsonSerializer.Serialize(clone, JsonDefaults.Options);
if (entity is null)
{
entity = new LibraryOptionsEntity
{
LibraryPath = libraryPath,
OptionsJson = json,
Version = 1,
DateCreated = utcNow,
DateModified = utcNow
};
await context.LibraryOptions.AddAsync(entity, cancellationToken).ConfigureAwait(false);
}
else
{
entity.OptionsJson = json;
entity.DateModified = utcNow;
}
await context.SaveChangesAsync(cancellationToken).ConfigureAwait(false);
}).ConfigureAwait(false);
}
}
catch (Exception ex) when (IsMissingTableException(ex))
{
_logger.LogDebug(ex, "LibraryOptions table is not available yet. Skipping database save for {LibraryPath}", libraryPath);
}
catch (Exception ex)
{
_logger.LogError(ex, "Error saving library options to database for {LibraryPath}", libraryPath);
}
}
private static bool IsMissingTableException(Exception exception)
{
return exception.Message.Contains("LibraryOptions", StringComparison.OrdinalIgnoreCase)
&& (exception.Message.Contains("does not exist", StringComparison.OrdinalIgnoreCase)
|| exception.Message.Contains("no such table", StringComparison.OrdinalIgnoreCase));
}
}