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()