Base implementation of IEngineInstaller for EngineType.Byond. More...

Inheritance diagram for Tgstation.Server.Host.Components.Engine.ByondInstallerBase:

[legend]

Collaboration diagram for Tgstation.Server.Host.Components.Engine.ByondInstallerBase:

[legend]

Public Member Functions

override ValueTask< IEngineInstallation > CreateInstallation (EngineVersion version, string path, Task installationTask, CancellationToken cancellationToken)

Creates an IEngineInstallation for a given version .

Parameters

version	The EngineVersion of the installation.
path	The path to the installation.
installationTask	The Task representing the installation process for the installation.
cancellationToken	The CancellationToken for the operation.

Returns: A ValueTask<TResult> resulting in the IEngineInstallation.

override async Task CleanCache (CancellationToken cancellationToken)

Attempts to cleans the engine's cache folder for the system.

Parameters

cancellationToken The CancellationToken for the operation.

Returns: A Task representing the running operation.

override async ValueTask< IEngineInstallationData > DownloadVersion (EngineVersion version, JobProgressReporter progressReporter, CancellationToken cancellationToken)

Download a given engine version .

Parameters

version	The EngineVersion of the engine to download.
jobProgressReporter	The JobProgressReporter for the operation.
cancellationToken	The CancellationToken for the operation.

Returns: A ValueTask<TResult> resulting in the IEngineInstallationData for the download.

Public Member Functions inherited from Tgstation.Server.Host.Components.Engine.EngineInstallerBase

ValueTask< IEngineInstallation > CreateInstallation (EngineVersion version, string path, Task installationTask, CancellationToken cancellationToken)

Creates an IEngineInstallation for a given version .

Parameters

version	The EngineVersion of the installation.
path	The path to the installation.
installationTask	The Task representing the installation process for the installation.
cancellationToken	The CancellationToken for the operation.

Returns: A ValueTask<TResult> resulting in the IEngineInstallation.

Task CleanCache (CancellationToken cancellationToken)

Attempts to cleans the engine's cache folder for the system.

Parameters

cancellationToken The CancellationToken for the operation.

Returns: A Task representing the running operation.

ValueTask Install (EngineVersion version, string path, bool deploymentPipelineProcesses, CancellationToken cancellationToken)

Does actions necessary to get an extracted installation working.

Parameters

version	The EngineVersion being installed.
path	The path to the installation.
deploymentPipelineProcesses	If the operation should consider processes it launches to be part of the deployment pipeline.
cancellationToken	The CancellationToken for the operation.

Returns: A ValueTask representing the running operation.

ValueTask UpgradeInstallation (EngineVersion version, string path, CancellationToken cancellationToken)

Does actions necessary to get upgrade a version installed by a previous version of TGS.

Parameters

version	The EngineVersion being installed.
path	The path to the installation.
cancellationToken	The CancellationToken for the operation.

Returns: A ValueTask representing the running operation.

ValueTask< IEngineInstallationData > DownloadVersion (EngineVersion version, JobProgressReporter jobProgressReporter, CancellationToken cancellationToken)

Download a given engine version .

Parameters

version	The EngineVersion of the engine to download.
jobProgressReporter	The JobProgressReporter for the operation.
cancellationToken	The CancellationToken for the operation.

Returns: A ValueTask<TResult> resulting in the IEngineInstallationData for the download.

ValueTask TrustDmbPath (EngineVersion version, string fullDmbPath, CancellationToken cancellationToken)

Add a given fullDmbPath to the trusted DMBs list in BYOND's config.

Parameters

version	The EngineVersion being used.
fullDmbPath	Full path to the .dmb that should be trusted.
cancellationToken	The CancellationToken for the operation.

Returns: A ValueTask representing the running operation.

Protected Member Functions
	ByondInstallerBase (IIOManager ioManager, ILogger< ByondInstallerBase > logger, IFileDownloader fileDownloader)
	Initializes a new instance of the ByondInstallerBase class.

string	GetDreamDaemonName (Version byondVersion, out bool supportsCli)
	Get the file name of the DreamDaemon executable.

virtual IEnumerable< string >	AdditionalCacheCleanFilePaths (string configDirectory)
	List off additional file paths in the configDirectory to delete.

Protected Member Functions inherited from Tgstation.Server.Host.Components.Engine.EngineInstallerBase
	EngineInstallerBase (IIOManager ioManager, ILogger< EngineInstallerBase > logger)
	Initializes a new instance of the EngineInstallerBase class.

void	CheckVersionValidity (EngineVersion version)
	Check that a given version is of type EngineType.Byond.

Static Protected Attributes
const string	ByondBinPath = "byond/bin"
	The path to the BYOND bin folder.

const string	CfgDirectoryName = "cfg"
	The path to the cfg directory.

Properties
override EngineType	TargetEngineType `[get]`

string	PathToUserFolder `[get]`
	Path to the system user's local BYOND folder.

string	DreamMakerName `[get]`
	Path to the DreamMaker executable.

string	ByondRevisionsUrlTemplate `[get]`
	Gets the URL formatter string for downloading a byond version of {0:Major} {1:Minor}.

Properties inherited from Tgstation.Server.Host.Components.Engine.EngineInstallerBase
EngineType	TargetEngineType `[get]`
	The EngineType the installer supports.

IIOManager	IOManager `[get]`
	Gets the IIOManager for the EngineInstallerBase.

ILogger< EngineInstallerBase >	Logger `[get]`
	Gets the ILogger for the EngineInstallerBase.

Private Member Functions
Uri	GetDownloadZipUrl (EngineVersion version)
	Create a Uri pointing to the location of the download for a given version .

Private Attributes
readonly IFileDownloader	fileDownloader
	The IFileDownloader for the ByondInstallerBase.

Static Private Attributes
const string	CacheDirectoryName = "cache"
	The name of BYOND's cache directory.

static readonly Version	MapThreadsVersion = new(515, 1609)
	The first Version of BYOND that supports the '-map-threads' parameter on DreamDaemon.

Detailed Description

Base implementation of IEngineInstaller for EngineType.Byond.

Definition at line 19 of file ByondInstallerBase.cs.

Constructor & Destructor Documentation

◆ ByondInstallerBase()

Tgstation.Server.Host.Components.Engine.ByondInstallerBase.ByondInstallerBase	(	IIOManager	ioManager,
		ILogger< ByondInstallerBase >	logger,
		IFileDownloader	fileDownloader
	)

protected

Initializes a new instance of the ByondInstallerBase class.

Parameters

ioManager	The IIOManager for the EngineInstallerBase.
logger	The ILogger for the EngineInstallerBase.
fileDownloader	The value of fileDownloader.

Definition at line 70 of file ByondInstallerBase.cs.

            : base(ioManager, logger)
        {
            this.fileDownloader = fileDownloader ?? throw new ArgumentNullException(nameof(fileDownloader));
        }

References Tgstation.Server.Host.Components.Engine.ByondInstallerBase.fileDownloader.

Member Function Documentation

◆ AdditionalCacheCleanFilePaths()

virtual IEnumerable< string > Tgstation.Server.Host.Components.Engine.ByondInstallerBase.AdditionalCacheCleanFilePaths ( string configDirectory )

protectedvirtual

List off additional file paths in the configDirectory to delete.

Parameters

configDirectory The full path to the relevant CfgDirectoryName.

Returns: An IEnumerable<T> of paths in configDirectory to clean.

Reimplemented in Tgstation.Server.Host.Components.Engine.WindowsByondInstaller.

Referenced by Tgstation.Server.Host.Components.Engine.ByondInstallerBase.CleanCache().

Here is the caller graph for this function:

◆ CleanCache()

override async Task Tgstation.Server.Host.Components.Engine.ByondInstallerBase.CleanCache ( CancellationToken cancellationToken )

Attempts to cleans the engine's cache folder for the system.

Parameters

cancellationToken The CancellationToken for the operation.

Returns: A Task representing the running operation.

Implements Tgstation.Server.Host.Components.Engine.IEngineInstaller.

Definition at line 104 of file ByondInstallerBase.cs.

        {
            try
            {
                var byondDir = PathToUserFolder;
 
                Logger.LogDebug("Cleaning BYOND cache...");
                async Task CleanDirectorySafe()
                {
                    try
                    {
                        await IOManager.DeleteDirectory(
                            IOManager.ConcatPath(
                                byondDir,
                                CacheDirectoryName),
                            cancellationToken);
                    }
                    catch (Exception ex)
                    {
                        Logger.LogWarning(ex, "Failed to clean BYOND cache!");
                    }
                }
 
                var cacheCleanTask = CleanDirectorySafe();
 
                // Create local cfg directory in case it doesn't exist
                var localCfgDirectory = IOManager.ConcatPath(
                    byondDir,
                    CfgDirectoryName);
 
                var cfgCreateTask = IOManager.CreateDirectory(
                    localCfgDirectory,
                    cancellationToken);
 
                var additionalCleanTasks = AdditionalCacheCleanFilePaths(localCfgDirectory)
                    .Select(path => IOManager.DeleteFile(path, cancellationToken));
 
                await Task.WhenAll(cacheCleanTask, cfgCreateTask, Task.WhenAll(additionalCleanTasks));
            }
            catch (Exception ex) when (ex is not OperationCanceledException)
            {
                Logger.LogWarning(ex, "Error cleaning BYOND cache!");
            }
        }

Here is the call graph for this function:

◆ CreateInstallation()

override ValueTask< IEngineInstallation > Tgstation.Server.Host.Components.Engine.ByondInstallerBase.CreateInstallation	(	EngineVersion	version,
		string	path,
		Task	installationTask,
		CancellationToken	cancellationToken
	)

Creates an IEngineInstallation for a given version .

Parameters

version	The EngineVersion of the installation.
path	The path to the installation.
installationTask	The Task representing the installation process for the installation.
cancellationToken	The CancellationToken for the operation.

Returns: A ValueTask<TResult> resulting in the IEngineInstallation.

Implements Tgstation.Server.Host.Components.Engine.IEngineInstaller.

Definition at line 77 of file ByondInstallerBase.cs.

        {
            CheckVersionValidity(version);
 
            var installationIOManager = new ResolvingIOManager(IOManager, path);
            var supportsMapThreads = version.Version >= MapThreadsVersion;
 
            return ValueTask.FromResult<IEngineInstallation>(
                new ByondInstallation(
                    installationIOManager,
                    installationTask,
                    version,
                    installationIOManager.ResolvePath(
                        installationIOManager.ConcatPath(
                            ByondBinPath,
                            GetDreamDaemonName(
                                version.Version!,
                                out var supportsCli))),
                    installationIOManager.ResolvePath(
                        installationIOManager.ConcatPath(
                            ByondBinPath,
                            DreamMakerName)),
                    supportsCli,
                    supportsMapThreads));
        }

References Tgstation.Server.Host.Components.Engine.ByondInstallerBase.ByondBinPath, Tgstation.Server.Host.Components.Engine.EngineInstallerBase.CheckVersionValidity(), Tgstation.Server.Host.Components.Engine.ByondInstallerBase.DreamMakerName, Tgstation.Server.Host.Components.Engine.ByondInstallerBase.GetDreamDaemonName(), Tgstation.Server.Host.Components.Engine.EngineInstallerBase.IOManager, Tgstation.Server.Host.Components.Engine.ByondInstallerBase.MapThreadsVersion, and Tgstation.Server.Api.Models.EngineVersion.Version.

Here is the call graph for this function:

◆ DownloadVersion()

override async ValueTask< IEngineInstallationData > Tgstation.Server.Host.Components.Engine.ByondInstallerBase.DownloadVersion	(	EngineVersion	version,
		JobProgressReporter	progressReporter,
		CancellationToken	cancellationToken
	)

Download a given engine version .

Parameters

version	The EngineVersion of the engine to download.
jobProgressReporter	The JobProgressReporter for the operation.
cancellationToken	The CancellationToken for the operation.

Returns: A ValueTask<TResult> resulting in the IEngineInstallationData for the download.

Implements Tgstation.Server.Host.Components.Engine.IEngineInstaller.

Definition at line 150 of file ByondInstallerBase.cs.

        {
            CheckVersionValidity(version);
 
            var url = GetDownloadZipUrl(version);
            Logger.LogTrace("Downloading {engineType} version {version} from {url}...", TargetEngineType, version, url);
 
            await using var download = fileDownloader.DownloadFile(url, null);
            await using var buffer = new BufferedFileStreamProvider(
                await download.GetResult(cancellationToken));
 
            var stream = await buffer.GetOwnedResult(cancellationToken);
            try
            {
                return new ZipStreamEngineInstallationData(
                    IOManager,
                    stream);
            }
            catch
            {
                await stream.DisposeAsync();
                throw;
            }
        }

References Tgstation.Server.Host.Components.Engine.EngineInstallerBase.CheckVersionValidity(), Tgstation.Server.Host.IO.IFileDownloader.DownloadFile(), Tgstation.Server.Host.Components.Engine.ByondInstallerBase.fileDownloader, Tgstation.Server.Host.Components.Engine.ByondInstallerBase.GetDownloadZipUrl(), Tgstation.Server.Host.Components.Engine.EngineInstallerBase.IOManager, Tgstation.Server.Host.Components.Engine.EngineInstallerBase.Logger, and Tgstation.Server.Host.Components.Engine.ByondInstallerBase.TargetEngineType.

Here is the call graph for this function:

◆ GetDownloadZipUrl()

Uri Tgstation.Server.Host.Components.Engine.ByondInstallerBase.GetDownloadZipUrl ( EngineVersion version )

private

Create a Uri pointing to the location of the download for a given version .

Parameters

version The EngineVersion to create a Uri for.

Returns: A Uri pointing to the version download location.

Definition at line 195 of file ByondInstallerBase.cs.

        {
            CheckVersionValidity(version);
            var url = String.Format(CultureInfo.InvariantCulture, ByondRevisionsUrlTemplate, version.Version!.Major, version.Version.Minor);
            return new Uri(url);
        }

References Tgstation.Server.Host.Components.Engine.ByondInstallerBase.ByondRevisionsUrlTemplate, Tgstation.Server.Host.Components.Engine.EngineInstallerBase.CheckVersionValidity(), and Tgstation.Server.Api.Models.EngineVersion.Version.

Referenced by Tgstation.Server.Host.Components.Engine.ByondInstallerBase.DownloadVersion().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetDreamDaemonName()

string Tgstation.Server.Host.Components.Engine.ByondInstallerBase.GetDreamDaemonName	(	Version	byondVersion,
		out bool	supportsCli
	)

abstractprotected

Get the file name of the DreamDaemon executable.

Parameters

byondVersion	The Version of BYOND to select the executable name for.
supportsCli	Whether or not the returned path supports being run as a command-line application.

Returns: The file name of the DreamDaemon executable.

Referenced by Tgstation.Server.Host.Components.Engine.ByondInstallerBase.CreateInstallation().

Here is the caller graph for this function:

Member Data Documentation

◆ ByondBinPath

const string Tgstation.Server.Host.Components.Engine.ByondInstallerBase.ByondBinPath = "byond/bin"

staticprotected

The path to the BYOND bin folder.

Definition at line 24 of file ByondInstallerBase.cs.

Referenced by Tgstation.Server.Host.Components.Engine.WindowsByondInstaller.AddDreamDaemonToFirewall(), Tgstation.Server.Host.Components.Engine.ByondInstallerBase.CreateInstallation(), and Tgstation.Server.Host.Components.Engine.PosixByondInstaller.Install().

◆ CacheDirectoryName

const string Tgstation.Server.Host.Components.Engine.ByondInstallerBase.CacheDirectoryName = "cache"

staticprivate

The name of BYOND's cache directory.

Definition at line 34 of file ByondInstallerBase.cs.

Referenced by Tgstation.Server.Host.Components.Engine.ByondInstallerBase.CleanCache().

◆ CfgDirectoryName

const string Tgstation.Server.Host.Components.Engine.ByondInstallerBase.CfgDirectoryName = "cfg"

staticprotected

The path to the cfg directory.

Definition at line 29 of file ByondInstallerBase.cs.

Referenced by Tgstation.Server.Host.Components.Engine.ByondInstallerBase.CleanCache(), and Tgstation.Server.Host.Components.Engine.WindowsByondInstaller.TrustDmbPath().

◆ fileDownloader

readonly IFileDownloader Tgstation.Server.Host.Components.Engine.ByondInstallerBase.fileDownloader

private

The IFileDownloader for the ByondInstallerBase.

Definition at line 62 of file ByondInstallerBase.cs.

Referenced by Tgstation.Server.Host.Components.Engine.ByondInstallerBase.ByondInstallerBase(), and Tgstation.Server.Host.Components.Engine.ByondInstallerBase.DownloadVersion().

◆ MapThreadsVersion

readonly Version Tgstation.Server.Host.Components.Engine.ByondInstallerBase.MapThreadsVersion = new(515, 1609)

staticprivate

The first Version of BYOND that supports the '-map-threads' parameter on DreamDaemon.

Definition at line 39 of file ByondInstallerBase.cs.

Referenced by Tgstation.Server.Host.Components.Engine.ByondInstallerBase.CreateInstallation().

Property Documentation

◆ ByondRevisionsUrlTemplate

string Tgstation.Server.Host.Components.Engine.ByondInstallerBase.ByondRevisionsUrlTemplate

getabstractprotected

Gets the URL formatter string for downloading a byond version of {0:Major} {1:Minor}.

Definition at line 57 of file ByondInstallerBase.cs.

57{ get; }

Referenced by Tgstation.Server.Host.Components.Engine.ByondInstallerBase.GetDownloadZipUrl().

◆ DreamMakerName

string Tgstation.Server.Host.Components.Engine.ByondInstallerBase.DreamMakerName

getabstractprotected

Path to the DreamMaker executable.

Definition at line 52 of file ByondInstallerBase.cs.

52{ get; }

Referenced by Tgstation.Server.Host.Components.Engine.ByondInstallerBase.CreateInstallation().

◆ PathToUserFolder

string Tgstation.Server.Host.Components.Engine.ByondInstallerBase.PathToUserFolder

getabstractprotected

Path to the system user's local BYOND folder.

Definition at line 47 of file ByondInstallerBase.cs.

47{ get; }

Referenced by Tgstation.Server.Host.Components.Engine.ByondInstallerBase.CleanCache().

◆ TargetEngineType

override EngineType Tgstation.Server.Host.Components.Engine.ByondInstallerBase.TargetEngineType

getprotected

Definition at line 42 of file ByondInstallerBase.cs.

Referenced by Tgstation.Server.Host.Components.Engine.ByondInstallerBase.DownloadVersion().

The documentation for this class was generated from the following file:

src/Tgstation.Server.Host/Components/Engine/ByondInstallerBase.cs

Public Member Functions

Protected Member Functions

Static Protected Attributes

Properties

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ByondInstallerBase()

Member Function Documentation

◆ AdditionalCacheCleanFilePaths()

◆ CleanCache()

◆ CreateInstallation()

◆ DownloadVersion()

◆ GetDownloadZipUrl()

◆ GetDreamDaemonName()

Member Data Documentation

◆ ByondBinPath

◆ CacheDirectoryName

◆ CfgDirectoryName

◆ fileDownloader

◆ MapThreadsVersion

Property Documentation

◆ ByondRevisionsUrlTemplate

◆ DreamMakerName

◆ PathToUserFolder

◆ TargetEngineType