From 1dc93932ccb1f43f37ddf971497444bda8a5045b Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 12 Oct 2026 15:51:22 +0000 Subject: [PATCH] fix(server): report Windows service start and stop failures to the event log A service has no console, and a refused data folder or server.json throws before the server's log file exists, so the SCM recorded only error 1064 and the entry to check was lost. ServiceMain and the stop path now also write the reason to the Application event log (source TitanoServer, advapi32 ReportEventW, no message file registered). The Windows README says where to look and that a data folder created by an unelevated console run must be deleted or given to Administrators first. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC --- deploy/releases-repo/README.md | 9 ++- docs/ARCHITECTURE.md | 2 +- .../Hosting/Windows/ServiceEventLog.cs | 58 +++++++++++++++++++ .../Hosting/Windows/ServiceNative.cs | 16 ++++- .../Hosting/Windows/WindowsServiceHost.cs | 6 +- .../Hosting/WindowsServiceTests.cs | 49 ++++++++++++++++ 6 files changed, 134 insertions(+), 6 deletions(-) create mode 100644 src/Titano.Server/Hosting/Windows/ServiceEventLog.cs diff --git a/deploy/releases-repo/README.md b/deploy/releases-repo/README.md index f6df9bf8..4f420809 100644 --- a/deploy/releases-repo/README.md +++ b/deploy/releases-repo/README.md @@ -116,13 +116,16 @@ Choose the *Server* component in the setup, or unpack `Titano-Server-win-x64- +/// Errors of the Windows service in the Application event log (source TitanoServer). A service has no console, +/// and a start-up failure comes before the server's log file exists (the data folder that holds it may be the very +/// thing refused), so Event Viewer is where an operator finds why the service stopped. The source is not registered +/// with a message file: Event Viewer says it found no description for the event, then shows the text whole. +/// +internal static unsafe class ServiceEventLog +{ + public const uint StartFailed = 1; + public const uint StopFailed = 2; + + /// ReportEvent takes at most 31,839 characters per string. + public const int MaxLength = 31_839; + + /// + /// The event text: and the reason the server gave (the entry to check, for a refused data + /// folder), then the exception for a bug report; cut to . + /// + public static string Describe(string what, Exception exception) + { + var text = $"{what} {exception.Message}{Environment.NewLine}{Environment.NewLine}{exception}"; + if (text.Length <= MaxLength) return text; + var cut = MaxLength - 1; + // Never half a surrogate pair. + if (char.IsHighSurrogate(text[cut - 1])) cut--; + return string.Concat(text.AsSpan(0, cut), "…"); + } + + /// Writes an error event; false when the event log could not be written (the console still gets it). + [SupportedOSPlatform("windows")] + public static bool Error(uint eventId, string text) => Error(WindowsServiceHost.ServiceName, eventId, text); + + /// as (tests write as their own source). + [SupportedOSPlatform("windows")] + internal static bool Error(string sourceName, uint eventId, string text) + { + var source = RegisterEventSourceW(null, sourceName); + if (source == 0) return false; + try + { + fixed (char* chars = text.Length <= MaxLength ? text : text[..MaxLength]) + { + var strings = stackalloc char*[1]; + strings[0] = chars; + return ReportEventW(source, EventLogErrorType, 0, eventId, 0, 1, 0, strings, null); + } + } + finally + { + DeregisterEventSource(source); + } + } +} diff --git a/src/Titano.Server/Hosting/Windows/ServiceNative.cs b/src/Titano.Server/Hosting/Windows/ServiceNative.cs index 1b89fd1e..c4e642d3 100644 --- a/src/Titano.Server/Hosting/Windows/ServiceNative.cs +++ b/src/Titano.Server/Hosting/Windows/ServiceNative.cs @@ -3,7 +3,7 @@ using System.Runtime.Versioning; namespace Titano.Server.Hosting.Windows; -/// Service Control Manager functions of advapi32 (no Windows-only package needed). +/// Service Control Manager and event log functions of advapi32 (no Windows-only package needed). [SupportedOSPlatform("windows")] internal static unsafe partial class ServiceNative { @@ -29,6 +29,8 @@ internal static unsafe partial class ServiceNative public const uint ErrorCallNotImplemented = 120; public const uint ErrorExceptionInService = 1064; + public const ushort EventLogErrorType = 0x1; + [StructLayout(LayoutKind.Sequential)] public struct ServiceStatus { @@ -90,4 +92,16 @@ internal static unsafe partial class ServiceNative [LibraryImport("advapi32.dll", SetLastError = true)] [return: MarshalAs(UnmanagedType.Bool)] public static partial bool CloseServiceHandle(nint handle); + + [LibraryImport("advapi32.dll", SetLastError = true, StringMarshalling = StringMarshalling.Utf16)] + public static partial nint RegisterEventSourceW(string? uncServerName, string sourceName); + + [LibraryImport("advapi32.dll", SetLastError = true)] + [return: MarshalAs(UnmanagedType.Bool)] + public static partial bool ReportEventW(nint eventLog, ushort type, ushort category, uint eventId, nint userSid, ushort stringCount, uint dataSize, + char** strings, void* rawData); + + [LibraryImport("advapi32.dll", SetLastError = true)] + [return: MarshalAs(UnmanagedType.Bool)] + public static partial bool DeregisterEventSource(nint eventLog); } diff --git a/src/Titano.Server/Hosting/Windows/WindowsServiceHost.cs b/src/Titano.Server/Hosting/Windows/WindowsServiceHost.cs index d08a87e7..b0824520 100644 --- a/src/Titano.Server/Hosting/Windows/WindowsServiceHost.cs +++ b/src/Titano.Server/Hosting/Windows/WindowsServiceHost.cs @@ -9,7 +9,8 @@ namespace Titano.Server.Hosting.Windows; /// /// Runs the server as a Windows service with the SCM API directly (StartServiceCtrlDispatcherW, /// RegisterServiceCtrlHandlerExW, SetServiceStatus). Stop and shutdown requests stop the web host gracefully: running -/// jobs keep their checkpoints and resume at the next start. +/// jobs keep their checkpoints and resume at the next start. A failure to start or stop goes to the Application event +/// log (), since a service has no console. /// [SupportedOSPlatform("windows")] public static class WindowsServiceHost @@ -56,7 +57,9 @@ public static class WindowsServiceHost } catch (Exception ex) { + // A refused data folder or server.json says which entry to check; the SCM itself records only error 1064. Console.Error.WriteLine(ex); + ServiceEventLog.Error(ServiceEventLog.StartFailed, ServiceEventLog.Describe("Titano Server did not start:", ex)); Report(Status.Stopped(ErrorExceptionInService)); } } @@ -96,6 +99,7 @@ public static class WindowsServiceHost catch (Exception ex) { Console.Error.WriteLine(ex); + ServiceEventLog.Error(ServiceEventLog.StopFailed, ServiceEventLog.Describe("Titano Server did not stop cleanly:", ex)); exitCode = ErrorExceptionInService; } Report(Status.Stopped(exitCode)); diff --git a/tests/Titano.Server.Tests/Hosting/WindowsServiceTests.cs b/tests/Titano.Server.Tests/Hosting/WindowsServiceTests.cs index 2d624ec0..70317aeb 100644 --- a/tests/Titano.Server.Tests/Hosting/WindowsServiceTests.cs +++ b/tests/Titano.Server.Tests/Hosting/WindowsServiceTests.cs @@ -1,3 +1,4 @@ +using System.Diagnostics.Eventing.Reader; using System.Security.AccessControl; using System.Security.Principal; using Titano.Server.Hosting; @@ -41,6 +42,54 @@ public sealed class WindowsServiceTests(TestContext context) Assert.Equal(1064u, new ServiceStatusTracker().Stopped(1064).ExitCode); } + [Test] + public void AServiceFailureLeadsWithTheReasonTheServerGave() + { + var refused = new InvalidOperationException(@"C:\ProgramData\Titano Server belongs to PC\ada, not to SYSTEM, Administrators or the account Titano Server runs as."); + var text = ServiceEventLog.Describe("Titano Server did not start:", refused); + Assert.True(text.StartsWith(@"Titano Server did not start: C:\ProgramData\Titano Server belongs to PC\ada", StringComparison.Ordinal), text); + Assert.Contains("System.InvalidOperationException", text); + + // ReportEvent refuses a longer string: the text is cut, never between the halves of a surrogate pair. + var cut = ServiceEventLog.Describe("x", new InvalidOperationException(new string('a', ServiceEventLog.MaxLength))); + Assert.Equal(ServiceEventLog.MaxLength, cut.Length); + Assert.True(cut.EndsWith("a\u2026", StringComparison.Ordinal), cut[^5..]); + var pair = ServiceEventLog.Describe("x", new InvalidOperationException(new string('a', ServiceEventLog.MaxLength - 4) + "\uD83D\uDE00" + new string('b', 99))); + Assert.Equal(ServiceEventLog.MaxLength - 1, pair.Length); + Assert.True(pair.EndsWith("a\u2026", StringComparison.Ordinal), pair[^5..]); + } + + [Test] + [WindowsOnly] + public void AServiceFailureReachesTheApplicationEventLog() + { + if (!OperatingSystem.IsWindows()) return; + // Written as a source of its own, so a test run never looks like a failed service in Event Viewer. + const string source = "Titano.Server.Tests"; + var marker = source + " " + Guid.NewGuid().ToString("N"); + Assert.True(ServiceEventLog.Error(source, ServiceEventLog.StartFailed, marker), "the Application log takes the event"); + var filter = $"*[System[Provider[@Name='{source}'] and EventID={ServiceEventLog.StartFailed}]]"; + var query = new EventLogQuery("Application", PathType.LogName, filter) { ReverseDirection = true }; + for (var attempt = 0; attempt < 50; attempt++) + { + using (var reader = new EventLogReader(query)) + { + for (var read = 0; read < 100 && reader.ReadEvent() is { } record; read++) + { + using (record) + { + // The event's one string, which Event Viewer shows whole. + if (record.Properties.Count != 1 || record.Properties[0].Value as string != marker) continue; + Assert.Equal((byte?)2, record.Level, "an error"); + return; + } + } + } + Thread.Sleep(100); + } + Assert.Fail($"No {source} event carries '{marker}'."); + } + [Test] [WindowsOnly] public void TheServiceIsRegisteredOnlyFromInsideProgramFiles()