More...

Inheritance diagram for Tgstation.Server.Host.Server:

[legend]

Collaboration diagram for Tgstation.Server.Host.Server:

[legend]

Public Member Functions

Server (IHostBuilder hostBuilder, string? updatePath)

Initializes a new instance of the Server class.

async ValueTask Run (CancellationToken cancellationToken)

Runs the IServer.

Parameters

cancellationToken The CancellationToken for the operation.

Returns: A ValueTask representing the running operation.

bool TryStartUpdate (IServerUpdateExecutor updateExecutor, Version newVersion)

Attempt to update with a given updateExecutor .

Parameters

updateExecutor	The IServerUpdateExecutor to use for the update.
newVersion	The Version the IServerControl is updating to.

Returns: true if the update started successfully, false if there was another update in progress.

IRestartRegistration RegisterForRestart (IRestartHandler handler)

Register a given handler to run before stopping the server for a restart.

Parameters

handler The IRestartHandler to register.

Returns: A new IRestartRegistration representing the scope of the registration.

ValueTask Restart ()

Restarts the Host.

Returns: A ValueTask representing the running operation.

ValueTask GracefulShutdown (bool detach)

Gracefully shutsdown the Host.

Parameters

detach If the graceful shutdown should detach any running watchdog. If false the server will wait for the next TgsReboot() or world exit before shutting down.

Returns: A ValueTask representing the running operation.

ValueTask Die (Exception? exception)

Kill the server with a fatal exception.

Parameters

exception The Exception to propagate to the watchdog if any.

Returns: A Task representing the running operation.

Properties
bool	RestartRequested `[get, private set]`
	If the IServer should restart.

bool	UpdateInProgress `[get, private set]`
	Whether or not the server is currently updating.

bool	WatchdogPresent `[get]`
	`true` if live updates are supported, `false`. TryStartUpdate(IServerUpdateExecutor, Version) and Restart will fail if this is `false`.

Properties inherited from Tgstation.Server.Host.IServer
Properties inherited from Tgstation.Server.Host.Core.IServerControl

Private Member Functions
async ValueTask< bool >	DumpGraphQLSchemaIfRequested (IServiceProvider services, CancellationToken cancellationToken)
	Checks if InternalConfiguration.DumpGraphQLApiPath is set and dumps the GraphQL API Schema to it if so.

void	CheckSanity (bool checkWatchdog)
	Throws an InvalidOperationException if the IServerControl cannot be used.

void	CheckExceptionPropagation (Exception? otherException)
	Re-throw propagatedException if it exists.

async ValueTask	RestartImpl (Version? newVersion, Exception? exception, bool requireWatchdog, bool completeAsap)
	Implements Restart().

void	WatchForShutdownFileCreation (object sender, FileSystemEventArgs eventArgs)
	Event handler for the updatePath's FileSystemWatcher. Triggers shutdown if requested by host watchdog.

void	StopServerImmediate ()
	Fires off the cancellationTokenSource without any checks, shutting down everything.

Private Attributes
readonly IHostBuilder	hostBuilder
	The IHostBuilder for the Server.

readonly List< IRestartHandler >	restartHandlers
	The IRestartHandlers to run when the Server restarts.

readonly? string	updatePath
	The absolute path to install updates to.

readonly object	restartLock
	`lock` object for certain restart related operations.

ILogger< Server >?	logger
	The ILogger for the Server.

GeneralConfiguration?	generalConfiguration
	The GeneralConfiguration for the Server.

CancellationTokenSource?	cancellationTokenSource
	The cancellationTokenSource for the Server.

Exception?	propagatedException
	The Exception to propagate when the server terminates.

Task?	updateTask
	The Task that is used for asynchronously updating the server.

bool	shutdownInProgress
	If the server is being shut down or restarted.

bool	terminateIfUpdateFails
	If there is an update in progress and this flag is set, it should stop the server immediately if it fails.

Detailed Description

Definition at line 25 of file Server.cs.

Constructor & Destructor Documentation

◆ Server()

Tgstation.Server.Host.Server.Server	(	IHostBuilder	hostBuilder,
		string?	updatePath
	)

Initializes a new instance of the Server class.

Parameters

hostBuilder	The value of hostBuilder.
updatePath	The value of updatePath.

Definition at line 106 of file Server.cs.

        {
            this.hostBuilder = hostBuilder ?? throw new ArgumentNullException(nameof(hostBuilder));
            this.updatePath = updatePath;
 
            hostBuilder.ConfigureServices(serviceCollection => serviceCollection.AddSingleton<IServerControl>(this));
 
            restartHandlers = new List<IRestartHandler>();
            restartLock = new object();
            logger = null;
        }

References Tgstation.Server.Host.Server.hostBuilder, Tgstation.Server.Host.Server.logger, Tgstation.Server.Host.Server.restartHandlers, Tgstation.Server.Host.Server.restartLock, and Tgstation.Server.Host.Server.updatePath.

Member Function Documentation

◆ CheckExceptionPropagation()

void Tgstation.Server.Host.Server.CheckExceptionPropagation ( Exception? otherException )

private

Re-throw propagatedException if it exists.

Parameters

otherException An existing Exception that should be thrown as well, but not by itself.

Definition at line 332 of file Server.cs.

        {
            if (propagatedException == null)
                return;
 
            if (otherException != null)
                throw new AggregateException(propagatedException, otherException);
 
            throw propagatedException;
        }

References Tgstation.Server.Host.Server.propagatedException.

Referenced by Tgstation.Server.Host.Server.Run().

Here is the caller graph for this function:

◆ CheckSanity()

void Tgstation.Server.Host.Server.CheckSanity ( bool checkWatchdog )

private

Throws an InvalidOperationException if the IServerControl cannot be used.

Parameters

checkWatchdog If WatchdogPresent should be checked.

Definition at line 319 of file Server.cs.

        {
            if (checkWatchdog && !WatchdogPresent && propagatedException == null)
                throw new InvalidOperationException("Server restarts are not supported");
 
            if (cancellationTokenSource == null || logger == null)
                throw new InvalidOperationException("Tried to control a non-running Server!");
        }

References Tgstation.Server.Host.Server.cancellationTokenSource, Tgstation.Server.Host.Server.logger, Tgstation.Server.Host.Server.propagatedException, and Tgstation.Server.Host.Server.WatchdogPresent.

Referenced by Tgstation.Server.Host.Server.RegisterForRestart(), Tgstation.Server.Host.Server.RestartImpl(), and Tgstation.Server.Host.Server.TryStartUpdate().

Here is the caller graph for this function:

◆ Die()

ValueTask Tgstation.Server.Host.Server.Die ( Exception? exception )

Kill the server with a fatal exception.

Parameters

exception The Exception to propagate to the watchdog if any.

Returns: A Task representing the running operation.

Implements Tgstation.Server.Host.Core.IServerControl.

Definition at line 281 of file Server.cs.

        {
            if (exception != null)
                return RestartImpl(null, exception, false, true);
 
            StopServerImmediate();
            return ValueTask.CompletedTask;
        }

References Tgstation.Server.Host.Server.RestartImpl(), and Tgstation.Server.Host.Server.StopServerImmediate().

Here is the call graph for this function:

◆ DumpGraphQLSchemaIfRequested()

async ValueTask< bool > Tgstation.Server.Host.Server.DumpGraphQLSchemaIfRequested	(	IServiceProvider	services,
		CancellationToken	cancellationToken
	)

private

Checks if InternalConfiguration.DumpGraphQLApiPath is set and dumps the GraphQL API Schema to it if so.

Parameters

services	The IServiceProvider to resolve services from.
cancellationToken	The CancellationToken for the operation.

Returns: A ValueTask<TResult> resulting in true if the GraphQL API was dumped, false otherwise.

Definition at line 296 of file Server.cs.

        {
            var internalConfigurationOptions = services.GetRequiredService<IOptions<InternalConfiguration>>();
            var apiDumpPath = internalConfigurationOptions.Value.DumpGraphQLApiPath;
            if (String.IsNullOrWhiteSpace(apiDumpPath))
                return false;
 
            logger!.LogInformation("Dumping GraphQL API spec to {path} and exiting...", apiDumpPath);
 
            // https://github.com/ChilliCream/graphql-platform/discussions/5885
            var resolver = services.GetRequiredService<IRequestExecutorResolver>();
            var executor = await resolver.GetRequestExecutorAsync(cancellationToken: cancellationToken);
            var sdl = executor.Schema.Print();
 
            var ioManager = services.GetRequiredService<IIOManager>();
            await ioManager.WriteAllBytes(apiDumpPath, Encoding.UTF8.GetBytes(sdl), cancellationToken);
            return true;
        }

References Tgstation.Server.Host.Server.logger, and Tgstation.Server.Host.IO.IIOManager.WriteAllBytes().

Referenced by Tgstation.Server.Host.Server.Run().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GracefulShutdown()

ValueTask Tgstation.Server.Host.Server.GracefulShutdown ( bool detach )

Gracefully shutsdown the Host.

Parameters

detach If the graceful shutdown should detach any running watchdog. If false the server will wait for the next TgsReboot() or world exit before shutting down.

Returns: A ValueTask representing the running operation.

Implements Tgstation.Server.Host.Core.IServerControl.

◆ RegisterForRestart()

IRestartRegistration Tgstation.Server.Host.Server.RegisterForRestart ( IRestartHandler handler )

Register a given handler to run before stopping the server for a restart.

Parameters

handler The IRestartHandler to register.

Returns: A new IRestartRegistration representing the scope of the registration.

Implements Tgstation.Server.Host.Core.IServerControl.

Definition at line 249 of file Server.cs.

        {
            ArgumentNullException.ThrowIfNull(handler);
 
            CheckSanity(false);
 
            var logger = this.logger!;
            lock (restartLock)
                if (!shutdownInProgress)
                {
                    logger.LogTrace("Registering restart handler {handlerImplementationName}...", handler);
                    restartHandlers.Add(handler);
                    return new RestartRegistration(
                        new DisposeInvoker(() =>
                        {
                            lock (restartLock)
                                if (!shutdownInProgress)
                                    restartHandlers.Remove(handler);
                        }));
                }
 
            logger.LogWarning("Restart handler {handlerImplementationName} register after a shutdown had begun!", handler);
            return new RestartRegistration(null);
        }

References Tgstation.Server.Host.Server.CheckSanity(), Tgstation.Server.Host.Server.logger, Tgstation.Server.Host.Server.restartHandlers, Tgstation.Server.Host.Server.restartLock, and Tgstation.Server.Host.Server.shutdownInProgress.

Here is the call graph for this function:

◆ Restart()

ValueTask Tgstation.Server.Host.Server.Restart ( )

Restarts the Host.

Returns: A ValueTask representing the running operation.

Implements Tgstation.Server.Host.Core.IServerControl.

Referenced by Tgstation.Server.Host.Components.Watchdog.AdvancedWatchdog.HandleNormalReboot().

Here is the caller graph for this function:

◆ RestartImpl()

async ValueTask Tgstation.Server.Host.Server.RestartImpl	(	Version?	newVersion,
		Exception?	exception,
		bool	requireWatchdog,
		bool	completeAsap
	)

private

Implements Restart().

Parameters

newVersion	The Version of any potential updates being applied.
exception	The potential value of propagatedException.
requireWatchdog	If the host watchdog is required for this "restart".
completeAsap	If the restart should wait for extremely long running tasks to complete (Like the current DreamDaemon world).

Returns: A ValueTask representing the running operation.

Definition at line 351 of file Server.cs.

        {
            CheckSanity(requireWatchdog);
 
            // if the watchdog isn't required and there's no issue, this is just a graceful shutdown
            bool isGracefulShutdown = !requireWatchdog && exception == null;
            var logger = this.logger!;
            logger.LogTrace(
                "Begin {restartType}...",
                isGracefulShutdown
                    ? completeAsap
                        ? "semi-graceful shutdown"
                        : "graceful shutdown"
                    : "restart");
 
            lock (restartLock)
            {
                if ((UpdateInProgress && newVersion == null) || shutdownInProgress)
                {
                    logger.LogTrace("Aborted restart due to concurrency conflict!");
                    return;
                }
 
                RestartRequested = !isGracefulShutdown;
                propagatedException ??= exception;
            }
 
            if (exception == null)
            {
                var giveHandlersTimeToWaitAround = isGracefulShutdown && !completeAsap;
                logger.LogInformation("Stopping server...");
                using var cts = new CancellationTokenSource(
                    TimeSpan.FromMinutes(
                        giveHandlersTimeToWaitAround
                            ? generalConfiguration!.ShutdownTimeoutMinutes
                            : generalConfiguration!.RestartTimeoutMinutes));
                var cancellationToken = cts.Token;
                try
                {
                    ValueTask eventsTask;
                    lock (restartLock)
                        eventsTask = ValueTaskExtensions.WhenAll(
                            restartHandlers
                                .Select(
                                    x => x.HandleRestart(newVersion, giveHandlersTimeToWaitAround, cancellationToken))
                                .ToList());
 
                    logger.LogTrace("Joining restart handlers...");
                    await eventsTask;
                }
                catch (OperationCanceledException ex)
                {
                    if (isGracefulShutdown)
                        logger.LogWarning(ex, "Graceful shutdown timeout hit! Existing DreamDaemon processes will be terminated!");
                    else
                        logger.LogError(
                            ex,
                            "Restart timeout hit! Existing DreamDaemon processes will be lost and must be killed manually before being restarted with TGS!");
                }
                catch (Exception e)
                {
                    logger.LogError(e, "Restart handlers error!");
                }
            }
 
            StopServerImmediate();
        }

Referenced by Tgstation.Server.Host.Server.Die(), and Tgstation.Server.Host.Server.TryStartUpdate().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Run()

async ValueTask Tgstation.Server.Host.Server.Run ( CancellationToken cancellationToken )

Runs the IServer.

Parameters

cancellationToken The CancellationToken for the operation.

Returns: A ValueTask representing the running operation.

Implements Tgstation.Server.Host.IServer.

Definition at line 119 of file Server.cs.

        {
            var updateDirectory = updatePath != null ? Path.GetDirectoryName(updatePath) : null;
            using (cancellationTokenSource = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken))
            using (var fsWatcher = updateDirectory != null ? new FileSystemWatcher(updateDirectory) : null)
            {
                if (fsWatcher != null)
                {
                    // If ever there is a NECESSARY update to the Host Watchdog, change this to use a pipe
                    // I don't know why I'm only realizing this in 2023 when this is 2019 code
                    // As it stands, FSWatchers use async I/O on Windows and block a new thread on Linux
                    // That's an acceptable, if saddening, resource loss for now
                    fsWatcher.Created += WatchForShutdownFileCreation;
                    fsWatcher.EnableRaisingEvents = true;
                }
 
                try
                {
                    using (Host = hostBuilder.Build())
                    {
                        logger = Host.Services.GetRequiredService<ILogger<Server>>();
                        try
                        {
                            using (cancellationToken.Register(() => logger.LogInformation("Server termination requested!")))
                            {
                                if (await DumpGraphQLSchemaIfRequested(Host.Services, cancellationToken))
                                    return;
 
                                var generalConfigurationOptions = Host.Services.GetRequiredService<IOptions<GeneralConfiguration>>();
                                generalConfiguration = generalConfigurationOptions.Value;
                                await Host.RunAsync(cancellationTokenSource.Token);
                            }
 
                            if (updateTask != null)
                                await updateTask;
                        }
                        catch (OperationCanceledException ex)
                        {
                            logger.LogDebug(ex, "Server run cancelled!");
                        }
                        catch (Exception ex)
                        {
                            CheckExceptionPropagation(ex);
                            throw;
                        }
                        finally
                        {
                            logger = null;
                        }
                    }
                }
                finally
                {
                    Host = null;
                }
            }
 
            CheckExceptionPropagation(null);
        }

References Tgstation.Server.Host.Server.cancellationTokenSource, Tgstation.Server.Host.Server.CheckExceptionPropagation(), Tgstation.Server.Host.Server.DumpGraphQLSchemaIfRequested(), Tgstation.Server.Host.Server.generalConfiguration, Tgstation.Server.Host.Server.hostBuilder, Tgstation.Server.Host.Server.logger, Tgstation.Server.Host.Server.updatePath, Tgstation.Server.Host.Server.updateTask, and Tgstation.Server.Host.Server.WatchForShutdownFileCreation().

Here is the call graph for this function:

◆ StopServerImmediate()

void Tgstation.Server.Host.Server.StopServerImmediate ( )

private

Fires off the cancellationTokenSource without any checks, shutting down everything.

Definition at line 450 of file Server.cs.

        {
            shutdownInProgress = true;
            logger!.LogDebug("Stopping host...");
            cancellationTokenSource!.Cancel();
        }

References Tgstation.Server.Host.Server.cancellationTokenSource, Tgstation.Server.Host.Server.logger, and Tgstation.Server.Host.Server.shutdownInProgress.

Referenced by Tgstation.Server.Host.Server.Die(), Tgstation.Server.Host.Server.RestartImpl(), and Tgstation.Server.Host.Server.WatchForShutdownFileCreation().

Here is the caller graph for this function:

◆ TryStartUpdate()

bool Tgstation.Server.Host.Server.TryStartUpdate	(	IServerUpdateExecutor	updateExecutor,
		Version	newVersion
	)

Attempt to update with a given updateExecutor .

Parameters

updateExecutor	The IServerUpdateExecutor to use for the update.
newVersion	The Version the IServerControl is updating to.

Returns: true if the update started successfully, false if there was another update in progress.

Implements Tgstation.Server.Host.Core.IServerControl.

Definition at line 180 of file Server.cs.

        {
            ArgumentNullException.ThrowIfNull(updateExecutor);
            ArgumentNullException.ThrowIfNull(newVersion);
 
            CheckSanity(true);
 
            if (updatePath == null)
                throw new InvalidOperationException("Tried to start update when server was initialized without an updatePath set!");
 
            var logger = this.logger!;
            logger.LogTrace("Begin ApplyUpdate...");
 
            CancellationToken criticalCancellationToken;
            lock (restartLock)
            {
                if (UpdateInProgress || shutdownInProgress)
                {
                    logger.LogDebug("Aborted update due to concurrency conflict!");
                    return false;
                }
 
                if (cancellationTokenSource == null)
                    throw new InvalidOperationException("Tried to update a non-running Server!");
 
                criticalCancellationToken = cancellationTokenSource.Token;
                UpdateInProgress = true;
            }
 
            async Task RunUpdate()
            {
                var updateExecutedSuccessfully = false;
                try
                {
                    updateExecutedSuccessfully = await updateExecutor.ExecuteUpdate(updatePath, criticalCancellationToken, criticalCancellationToken);
                }
                catch (OperationCanceledException ex)
                {
                    logger.LogDebug(ex, "Update cancelled!");
                    UpdateInProgress = false;
                }
                catch (Exception ex)
                {
                    logger.LogError(ex, "Update errored!");
                    UpdateInProgress = false;
                }
 
                if (updateExecutedSuccessfully)
                {
                    logger.LogTrace("Update complete!");
                    await RestartImpl(newVersion, null, true, true);
                }
                else if (terminateIfUpdateFails)
                {
                    logger.LogTrace("Stopping host due to termination request...");
                    cancellationTokenSource.Cancel();
                }
                else
                {
                    logger.LogTrace("Update failed!");
                    UpdateInProgress = false;
                }
            }
 
            updateTask = RunUpdate();
            return true;
        }

Here is the call graph for this function:

◆ WatchForShutdownFileCreation()

void Tgstation.Server.Host.Server.WatchForShutdownFileCreation	(	object	sender,
		FileSystemEventArgs	eventArgs
	)

private

Event handler for the updatePath's FileSystemWatcher. Triggers shutdown if requested by host watchdog.

Parameters

sender	The object that sent the event.
eventArgs	The FileSystemEventArgs.

Definition at line 424 of file Server.cs.

        {
            logger?.LogTrace("FileSystemWatcher triggered.");
 
            // TODO: Refactor this to not use System.IO function here.
            if (eventArgs.FullPath == Path.GetFullPath(updatePath!) && File.Exists(eventArgs.FullPath))
            {
                logger?.LogInformation("Host watchdog appears to be requesting server termination!");
                lock (restartLock)
                {
                    if (!UpdateInProgress)
                    {
                        StopServerImmediate();
                        return;
                    }
 
                    terminateIfUpdateFails = true;
                }
 
                logger?.LogInformation("An update is in progress, we will wait for that to complete...");
            }
        }