From f08efa840e9c91ddcaa702f66f37e73325f754ad Mon Sep 17 00:00:00 2001 From: Ben Date: Thu, 22 Oct 2026 12:40:09 -0400 Subject: [PATCH 1/5] Added Moonfin/Time: the server's clock and time zone, for access schedules judged in server-local time Co-Authored-By: Claude Sonnet 5.5 --- Jellyfin/backend/Api/MoonfinController.cs | 8 +++ Jellyfin/backend/Api/ServerTimeController.cs | 67 +++++++++++++++++++ .../Moonfin.Server.Tests/ServerTimeTests.cs | 67 +++++++++++++++++++ 3 files changed, 142 insertions(+) create mode 100644 Jellyfin/backend/Api/ServerTimeController.cs create mode 100644 Jellyfin/tests/Moonfin.Server.Tests/ServerTimeTests.cs diff --git a/Jellyfin/backend/Api/MoonfinController.cs b/Jellyfin/backend/Api/MoonfinController.cs index bf1333a9..a52cc414 100644 --- a/Jellyfin/backend/Api/MoonfinController.cs +++ b/Jellyfin/backend/Api/MoonfinController.cs @@ -143,6 +143,7 @@ public ActionResult Ping() PinSupported = true, IncompleteRecordingsSupported = config?.LiveTvDetectIncompleteRecordings ?? true, ExtendedCompleteShowingsSupported = config?.LiveTvDetectIncompleteRecordings ?? true, + TimeSupported = true, RecommendationsSupported = config?.RecommendationsProviderEnabled ?? true, DefaultSettings = config?.DefaultUserSettings }); @@ -1605,6 +1606,13 @@ public class MoonfinPingResponse [JsonPropertyName("extendedCompleteShowingsSupported")] public bool? ExtendedCompleteShowingsSupported { get; set; } + /// + /// True when this plugin reports the server's clock and time zone at Moonfin/Time. Older + /// plugins leave it out, so the app falls back to the device clock. + /// + [JsonPropertyName("timeSupported")] + public bool? TimeSupported { get; set; } + /// /// True when this plugin supports server-side recommendations scoring. /// diff --git a/Jellyfin/backend/Api/ServerTimeController.cs b/Jellyfin/backend/Api/ServerTimeController.cs new file mode 100644 index 00000000..da9d6dd1 --- /dev/null +++ b/Jellyfin/backend/Api/ServerTimeController.cs @@ -0,0 +1,67 @@ +using System.Globalization; +using System.Net.Mime; +using System.Text.Json.Serialization; +using Microsoft.AspNetCore.Authorization; +using Microsoft.AspNetCore.Http; +using Microsoft.AspNetCore.Mvc; + +namespace Moonfin.Server.Api; + +/// +/// The server's clock and time zone. Jellyfin judges a user's access schedule against the server's +/// local time, which no stock endpoint reports, so a client in another zone can't work out when +/// the account is open or next opens without it. +/// +[ApiController] +[Route("Moonfin")] +[Produces(MediaTypeNames.Application.Json)] +public class ServerTimeController : ControllerBase +{ + /// The server's current time, its UTC offset and its time zone. + [HttpGet("Time")] + [Authorize] + [ProducesResponseType(StatusCodes.Status200OK)] + [ProducesResponseType(StatusCodes.Status401Unauthorized)] + public ActionResult GetTime() + { + return Ok(Describe(DateTimeOffset.UtcNow, TimeZoneInfo.Local)); + } + + /// Builds the response for an instant and zone, so it can be checked without a clock. + internal static ServerTimeResponse Describe(DateTimeOffset now, TimeZoneInfo zone) + { + var utc = now.ToUniversalTime(); + var local = TimeZoneInfo.ConvertTime(utc, zone); + + return new ServerTimeResponse + { + UtcTime = utc.ToString("yyyy-MM-dd'T'HH:mm:ss'Z'", CultureInfo.InvariantCulture), + LocalTime = local.ToString("yyyy-MM-dd'T'HH:mm:ss", CultureInfo.InvariantCulture), + UtcOffsetSeconds = (int)zone.GetUtcOffset(utc).TotalSeconds, + TimeZoneId = zone.Id, + IsDaylightSavingTime = zone.IsDaylightSavingTime(utc), + }; + } +} + +public class ServerTimeResponse +{ + /// The instant, as ISO 8601 UTC with a trailing Z. + [JsonPropertyName("utcTime")] + public string UtcTime { get; set; } = string.Empty; + + /// The same instant on the server's wall clock, with no offset. This is what an access schedule is judged against. + [JsonPropertyName("localTime")] + public string LocalTime { get; set; } = string.Empty; + + /// The server's offset from UTC right now, in seconds, east positive. + [JsonPropertyName("utcOffsetSeconds")] + public int UtcOffsetSeconds { get; set; } + + /// The server's time zone id as the host names it. + [JsonPropertyName("timeZoneId")] + public string TimeZoneId { get; set; } = string.Empty; + + [JsonPropertyName("isDaylightSavingTime")] + public bool IsDaylightSavingTime { get; set; } +} diff --git a/Jellyfin/tests/Moonfin.Server.Tests/ServerTimeTests.cs b/Jellyfin/tests/Moonfin.Server.Tests/ServerTimeTests.cs new file mode 100644 index 00000000..c876b61f --- /dev/null +++ b/Jellyfin/tests/Moonfin.Server.Tests/ServerTimeTests.cs @@ -0,0 +1,67 @@ +using System.Text.Json; +using Moonfin.Server.Api; +using Xunit; + +namespace Moonfin.Server.Tests; + +public sealed class ServerTimeTests +{ + private static TimeZoneInfo Zone(string offset) => + TimeZoneInfo.CreateCustomTimeZone("Test/Zone", TimeSpan.Parse(offset), "Test", "Test"); + + [Fact] + public void Describe_ReportsUtcAndTheServerWallClock() + { + var time = ServerTimeController.Describe(new DateTimeOffset(2026, 3, 1, 23, 30, 0, TimeSpan.Zero), Zone("05:30")); + + Assert.Equal("2026-03-01T23:30:00Z", time.UtcTime); + Assert.Equal("2026-03-02T05:00:00", time.LocalTime); + Assert.Equal(19800, time.UtcOffsetSeconds); + Assert.Equal("Test/Zone", time.TimeZoneId); + } + + [Fact] + public void Describe_NegativeOffsetRollsTheDayBack() + { + var time = ServerTimeController.Describe(new DateTimeOffset(2026, 3, 1, 2, 0, 0, TimeSpan.FromHours(3)), Zone("-08:00")); + + Assert.Equal("2026-02-28T23:00:00Z", time.UtcTime); + Assert.Equal("2026-02-28T15:00:00", time.LocalTime); + Assert.Equal(-28800, time.UtcOffsetSeconds); + } + + // Skipped quietly on a host with no tz database, where the zone can't be looked up. + [Fact] + public void Describe_FollowsDaylightSavingTransitions() + { + TimeZoneInfo zone; + try + { + zone = TimeZoneInfo.FindSystemTimeZoneById("America/New_York"); + } + catch (TimeZoneNotFoundException) + { + return; + } + + var winter = ServerTimeController.Describe(new DateTimeOffset(2026, 1, 15, 12, 0, 0, TimeSpan.Zero), zone); + var summer = ServerTimeController.Describe(new DateTimeOffset(2026, 7, 15, 12, 0, 0, TimeSpan.Zero), zone); + + Assert.Equal(-18000, winter.UtcOffsetSeconds); + Assert.False(winter.IsDaylightSavingTime); + Assert.Equal(-14400, summer.UtcOffsetSeconds); + Assert.True(summer.IsDaylightSavingTime); + } + + // Clients read these exact keys, so a rename would leave them on the device clock unnoticed. + [Fact] + public void Response_UsesTheKeysClientsRead() + { + var json = JsonSerializer.Serialize(ServerTimeController.Describe(DateTimeOffset.UtcNow, TimeZoneInfo.Utc)); + + foreach (var key in new[] { "utcTime", "localTime", "utcOffsetSeconds", "timeZoneId", "isDaylightSavingTime" }) + { + Assert.Contains($"\"{key}\"", json); + } + } +} From 52aab6d84ec14af82440b1f36854750dd674a4b6 Mon Sep 17 00:00:00 2001 From: Ben Date: Sun, 1 Nov 2026 01:55:04 -0400 Subject: [PATCH 2/5] Added the server's next offset change to Moonfin/Time, so a client can turn a future time on the server's clock into an instant across daylight saving. A client that names the next opening of an access schedule in its own time zone has to turn a time on the server's wall clock into an instant, and the server's offset right now is wrong for that once daylight saving changes in between. Moonfin/Time now also answers nextOffsetChangeUtc, the first instant the server's offset differs from now (ISO 8601 UTC, to the second), and nextUtcOffsetSeconds, the offset after it. Both are null for a zone without changes within about 400 days. Changes come months apart, so one is enough for a week's look-ahead. It's found by stepping a day at a time and halving the day it falls in, so it relies only on TimeZoneInfo.GetUtcOffset and not on how the zone's adjustment rules are written. Older clients ignore the new keys. Co-Authored-By: Claude Opus 5.5 --- Jellyfin/backend/Api/ServerTimeController.cs | 74 +++++++++++++++++- .../Moonfin.Server.Tests/ServerTimeTests.cs | 78 ++++++++++++++++++- 2 files changed, 150 insertions(+), 2 deletions(-) diff --git a/Jellyfin/backend/Api/ServerTimeController.cs b/Jellyfin/backend/Api/ServerTimeController.cs index da9d6dd1..6017cfcd 100644 --- a/Jellyfin/backend/Api/ServerTimeController.cs +++ b/Jellyfin/backend/Api/ServerTimeController.cs @@ -33,7 +33,7 @@ internal static ServerTimeResponse Describe(DateTimeOffset now, TimeZoneInfo zon var utc = now.ToUniversalTime(); var local = TimeZoneInfo.ConvertTime(utc, zone); - return new ServerTimeResponse + var time = new ServerTimeResponse { UtcTime = utc.ToString("yyyy-MM-dd'T'HH:mm:ss'Z'", CultureInfo.InvariantCulture), LocalTime = local.ToString("yyyy-MM-dd'T'HH:mm:ss", CultureInfo.InvariantCulture), @@ -41,6 +41,66 @@ internal static ServerTimeResponse Describe(DateTimeOffset now, TimeZoneInfo zon TimeZoneId = zone.Id, IsDaylightSavingTime = zone.IsDaylightSavingTime(utc), }; + + var change = NextOffsetChange(utc, zone); + if (change is { } next) + { + time.NextOffsetChangeUtc = next.ToString("yyyy-MM-dd'T'HH:mm:ss'Z'", CultureInfo.InvariantCulture); + time.NextUtcOffsetSeconds = (int)zone.GetUtcOffset(next).TotalSeconds; + } + + return time; + } + + // Far enough to find the next change in any zone that has them, which come at most a year apart + private const int LookAheadDays = 400; + + /// + /// The first instant after at which the zone's offset differs from its + /// offset now, to the second, or null when it doesn't change within the look-ahead. Found by + /// stepping a day at a time and then halving the day, so it relies only on GetUtcOffset and + /// not on how the zone's adjustment rules are written. + /// + internal static DateTimeOffset? NextOffsetChange(DateTimeOffset utc, TimeZoneInfo zone) + { + var start = utc.ToUniversalTime(); + var offset = zone.GetUtcOffset(start); + var before = start; + DateTimeOffset? after = null; + + for (var day = 1; day <= LookAheadDays; day++) + { + var probe = start.AddDays(day); + if (zone.GetUtcOffset(probe) != offset) + { + after = probe; + break; + } + + before = probe; + } + + if (after is not { } high) + { + return null; + } + + // The offset is the old one at before and the new one at high; close in to the second + var low = before; + while ((high - low).TotalSeconds > 1) + { + var middle = low.AddTicks((high - low).Ticks / 2); + if (zone.GetUtcOffset(middle) == offset) + { + low = middle; + } + else + { + high = middle; + } + } + + return new DateTimeOffset(high.UtcTicks - (high.UtcTicks % TimeSpan.TicksPerSecond), TimeSpan.Zero); } } @@ -64,4 +124,16 @@ public class ServerTimeResponse [JsonPropertyName("isDaylightSavingTime")] public bool IsDaylightSavingTime { get; set; } + + /// + /// When the server's offset next changes, as ISO 8601 UTC with a trailing Z, or null when it + /// doesn't within about a year. A client turning a future time on the server's wall clock into + /// an instant uses from here on. + /// + [JsonPropertyName("nextOffsetChangeUtc")] + public string? NextOffsetChangeUtc { get; set; } + + /// The server's offset from UTC after that change, in seconds, east positive, or null with it. + [JsonPropertyName("nextUtcOffsetSeconds")] + public int? NextUtcOffsetSeconds { get; set; } } diff --git a/Jellyfin/tests/Moonfin.Server.Tests/ServerTimeTests.cs b/Jellyfin/tests/Moonfin.Server.Tests/ServerTimeTests.cs index c876b61f..a4f8cb55 100644 --- a/Jellyfin/tests/Moonfin.Server.Tests/ServerTimeTests.cs +++ b/Jellyfin/tests/Moonfin.Server.Tests/ServerTimeTests.cs @@ -59,9 +59,85 @@ public void Response_UsesTheKeysClientsRead() { var json = JsonSerializer.Serialize(ServerTimeController.Describe(DateTimeOffset.UtcNow, TimeZoneInfo.Utc)); - foreach (var key in new[] { "utcTime", "localTime", "utcOffsetSeconds", "timeZoneId", "isDaylightSavingTime" }) + foreach (var key in new[] { "utcTime", "localTime", "utcOffsetSeconds", "timeZoneId", "isDaylightSavingTime", "nextOffsetChangeUtc", "nextUtcOffsetSeconds" }) { Assert.Contains($"\"{key}\"", json); } } + + private static TimeZoneInfo? Named(string id) + { + try + { + return TimeZoneInfo.FindSystemTimeZoneById(id); + } + catch (TimeZoneNotFoundException) + { + return null; + } + } + + [Fact] + public void Describe_AFixedOffsetHasNoNextChange() + { + var time = ServerTimeController.Describe(new DateTimeOffset(2026, 3, 1, 12, 0, 0, TimeSpan.Zero), Zone("05:30")); + + Assert.Null(time.NextOffsetChangeUtc); + Assert.Null(time.NextUtcOffsetSeconds); + } + + // The night US daylight saving ended in 2026: 02:00 EDT became 01:00 EST at 06:00 UTC + [Fact] + public void Describe_NamesTheNextChangeToTheSecond() + { + if (Named("America/New_York") is not { } zone) + { + return; + } + + var time = ServerTimeController.Describe(new DateTimeOffset(2026, 11, 1, 5, 16, 4, TimeSpan.Zero), zone); + + Assert.Equal(-14400, time.UtcOffsetSeconds); + Assert.Equal("2026-11-01T06:00:00Z", time.NextOffsetChangeUtc); + Assert.Equal(-18000, time.NextUtcOffsetSeconds); + } + + [Fact] + public void Describe_LooksMonthsAhead() + { + if (Named("America/New_York") is not { } zone) + { + return; + } + + var summer = ServerTimeController.Describe(new DateTimeOffset(2026, 7, 15, 12, 0, 0, TimeSpan.Zero), zone); + var winter = ServerTimeController.Describe(new DateTimeOffset(2026, 12, 15, 12, 0, 0, TimeSpan.Zero), zone); + + Assert.Equal("2026-11-01T06:00:00Z", summer.NextOffsetChangeUtc); + Assert.Equal(-18000, summer.NextUtcOffsetSeconds); + Assert.Equal("2027-03-14T07:00:00Z", winter.NextOffsetChangeUtc); + Assert.Equal(-14400, winter.NextUtcOffsetSeconds); + } + + // Southern hemisphere: Sydney leaves daylight saving in April, 03:00 AEDT back to 02:00 AEST + [Fact] + public void Describe_FollowsASouthernZone() + { + if (Named("Australia/Sydney") is not { } zone) + { + return; + } + + var time = ServerTimeController.Describe(new DateTimeOffset(2027, 1, 10, 0, 0, 0, TimeSpan.Zero), zone); + + Assert.Equal(39600, time.UtcOffsetSeconds); + Assert.Equal("2027-04-03T16:00:00Z", time.NextOffsetChangeUtc); + Assert.Equal(36000, time.NextUtcOffsetSeconds); + } + + [Fact] + public void NextOffsetChange_IsNullWithoutChanges() + { + Assert.Null(ServerTimeController.NextOffsetChange(DateTimeOffset.UtcNow, TimeZoneInfo.Utc)); + } } From 57c125c62e93373666ff3d9e3cd2d4d2f582ffbb Mon Sep 17 00:00:00 2001 From: Ben Date: Sun, 1 Nov 2026 01:17:22 -0400 Subject: [PATCH 3/5] Let Moonfin/Time and Ping skip the access-schedule check Jellyfin's default policy refuses a user outside their access schedule, which is when the client needs the server clock to say when the account next opens, and Ping to learn it can ask. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeUxUhUKfFgRTh1Hj7YmzQ --- Jellyfin/backend/Api/MoonfinController.cs | 6 +++++- Jellyfin/backend/Api/ServerTimeController.cs | 6 +++++- .../tests/Moonfin.Server.Tests/ServerTimeTests.cs | 15 +++++++++++++++ 3 files changed, 25 insertions(+), 2 deletions(-) diff --git a/Jellyfin/backend/Api/MoonfinController.cs b/Jellyfin/backend/Api/MoonfinController.cs index a52cc414..d63b9125 100644 --- a/Jellyfin/backend/Api/MoonfinController.cs +++ b/Jellyfin/backend/Api/MoonfinController.cs @@ -116,8 +116,12 @@ public ActionResult RestoreConfigFromBackup() /// Ping endpoint to check if Moonfin plugin is installed. /// /// Plugin status information including admin defaults. + /// + /// Skips the access-schedule check so a client outside its user's hours can still find out + /// the plugin is there and whether it can ask for the server time. + /// [HttpGet("Ping")] - [Authorize] + [Authorize(Policy = "IgnoreParentalControl")] [ProducesResponseType(StatusCodes.Status200OK)] public ActionResult Ping() { diff --git a/Jellyfin/backend/Api/ServerTimeController.cs b/Jellyfin/backend/Api/ServerTimeController.cs index 6017cfcd..3a9fa6ec 100644 --- a/Jellyfin/backend/Api/ServerTimeController.cs +++ b/Jellyfin/backend/Api/ServerTimeController.cs @@ -18,8 +18,12 @@ namespace Moonfin.Server.Api; public class ServerTimeController : ControllerBase { /// The server's current time, its UTC offset and its time zone. + /// + /// Skips the access-schedule check: a user outside their hours is exactly the one whose client + /// needs the server clock to say when the account next opens. + /// [HttpGet("Time")] - [Authorize] + [Authorize(Policy = "IgnoreParentalControl")] [ProducesResponseType(StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status401Unauthorized)] public ActionResult GetTime() diff --git a/Jellyfin/tests/Moonfin.Server.Tests/ServerTimeTests.cs b/Jellyfin/tests/Moonfin.Server.Tests/ServerTimeTests.cs index a4f8cb55..889e701f 100644 --- a/Jellyfin/tests/Moonfin.Server.Tests/ServerTimeTests.cs +++ b/Jellyfin/tests/Moonfin.Server.Tests/ServerTimeTests.cs @@ -1,4 +1,6 @@ +using System.Reflection; using System.Text.Json; +using Microsoft.AspNetCore.Authorization; using Moonfin.Server.Api; using Xunit; @@ -140,4 +142,17 @@ public void NextOffsetChange_IsNullWithoutChanges() { Assert.Null(ServerTimeController.NextOffsetChange(DateTimeOffset.UtcNow, TimeZoneInfo.Utc)); } + + // Jellyfin's default policy refuses a user outside their access schedule, which is when the + // client most needs the server clock and the Ping flag that says it can ask for it. + [Theory] + [InlineData(typeof(ServerTimeController), nameof(ServerTimeController.GetTime))] + [InlineData(typeof(MoonfinController), nameof(MoonfinController.Ping))] + public void Endpoint_IsReachableOutsideTheAccessSchedule(Type controller, string action) + { + var authorize = controller.GetMethod(action)!.GetCustomAttribute(); + + Assert.NotNull(authorize); + Assert.Equal("IgnoreParentalControl", authorize!.Policy); + } } From 804c132419696e1ec2c6a814a23f4280a5fc5478 Mon Sep 17 00:00:00 2001 From: Ben Date: Sun, 1 Nov 2026 10:53:56 -0500 Subject: [PATCH 4/5] Said the next offset change is left out of Moonfin/Time when there is none, not null Jellyfin drops null properties from its responses, so a server with no change coming leaves both keys out, the same as a plugin that predates them. Clients already treat a missing key as no change. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeUxUhUKfFgRTh1Hj7YmzQ --- Jellyfin/backend/Api/ServerTimeController.cs | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Jellyfin/backend/Api/ServerTimeController.cs b/Jellyfin/backend/Api/ServerTimeController.cs index 3a9fa6ec..7bbddc0c 100644 --- a/Jellyfin/backend/Api/ServerTimeController.cs +++ b/Jellyfin/backend/Api/ServerTimeController.cs @@ -130,14 +130,15 @@ public class ServerTimeResponse public bool IsDaylightSavingTime { get; set; } /// - /// When the server's offset next changes, as ISO 8601 UTC with a trailing Z, or null when it - /// doesn't within about a year. A client turning a future time on the server's wall clock into - /// an instant uses from here on. + /// When the server's offset next changes, as ISO 8601 UTC with a trailing Z. Left out of the + /// response when it doesn't change within about a year, as it is by plugins that predate it, so + /// clients treat a missing key as no change. A client turning a future time on the server's + /// wall clock into an instant uses from here on. /// [JsonPropertyName("nextOffsetChangeUtc")] public string? NextOffsetChangeUtc { get; set; } - /// The server's offset from UTC after that change, in seconds, east positive, or null with it. + /// The server's offset from UTC after that change, in seconds, east positive. Left out along with it. [JsonPropertyName("nextUtcOffsetSeconds")] public int? NextUtcOffsetSeconds { get; set; } } From f115146dd7595fb6f8b8aa8ecbfbbc83b2129f96 Mon Sep 17 00:00:00 2001 From: Ben Date: Sun, 1 Nov 2026 10:59:59 -0500 Subject: [PATCH 5/5] Said the next offset from Moonfin/Time holds only until the change after it The response names one change, so a time past the one after it needs a fresh answer, not the same offset. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeUxUhUKfFgRTh1Hj7YmzQ --- Jellyfin/backend/Api/ServerTimeController.cs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Jellyfin/backend/Api/ServerTimeController.cs b/Jellyfin/backend/Api/ServerTimeController.cs index 7bbddc0c..79d730d1 100644 --- a/Jellyfin/backend/Api/ServerTimeController.cs +++ b/Jellyfin/backend/Api/ServerTimeController.cs @@ -133,12 +133,14 @@ public class ServerTimeResponse /// When the server's offset next changes, as ISO 8601 UTC with a trailing Z. Left out of the /// response when it doesn't change within about a year, as it is by plugins that predate it, so /// clients treat a missing key as no change. A client turning a future time on the server's - /// wall clock into an instant uses from here on. + /// wall clock into an instant uses from this change until + /// the one after it, which this response doesn't describe: for times past that, ask again + /// after this change. /// [JsonPropertyName("nextOffsetChangeUtc")] public string? NextOffsetChangeUtc { get; set; } - /// The server's offset from UTC after that change, in seconds, east positive. Left out along with it. + /// The server's offset from UTC after that change, in seconds, east positive, until the change after it. Left out along with it. [JsonPropertyName("nextUtcOffsetSeconds")] public int? NextUtcOffsetSeconds { get; set; } }