From fe88eef3f1bebe61823a727edddee73f189ee295 Mon Sep 17 00:00:00 2001 From: Cyberboss Date: Mon, 23 Apr 2018 12:01:54 -0400 Subject: [PATCH] Doc comments and model tweaks --- .../Models/ChatSettings.cs | 12 +++++ src/Tgstation.Server.Api/Models/CompileJob.cs | 7 ++- .../Models/Configuration.cs | 27 +--------- .../Models/Internal/CompileJob.cs | 12 +++-- .../Internal/ConfigurationFileMetadata.cs | 33 ++++++++++++ .../Internal/DreamDaemonLaunchParameters.cs | 35 ++++++++++++ .../Models/Internal/DreamDaemonSettings.cs | 27 +--------- .../Models/Internal/DreamMakerSettings.cs | 4 +- .../Components/IByond.cs | 31 ++++++++++- src/Tgstation.Server.Host/Components/IChat.cs | 32 +++++++++++ .../Components/IConfiguration.cs | 52 +++++++++++++++++- .../Components/IDreamDaemon.cs | 53 +++++++++++++++++++ .../Components/IDreamMaker.cs | 13 +++++ .../Models/CompileJob.cs | 7 ++- 14 files changed, 284 insertions(+), 61 deletions(-) create mode 100644 src/Tgstation.Server.Api/Models/Internal/ConfigurationFileMetadata.cs create mode 100644 src/Tgstation.Server.Api/Models/Internal/DreamDaemonLaunchParameters.cs diff --git a/src/Tgstation.Server.Api/Models/ChatSettings.cs b/src/Tgstation.Server.Api/Models/ChatSettings.cs index a4cb033170..2900a7e055 100644 --- a/src/Tgstation.Server.Api/Models/ChatSettings.cs +++ b/src/Tgstation.Server.Api/Models/ChatSettings.cs @@ -6,6 +6,18 @@ namespace Tgstation.Server.Api.Models /// public sealed class ChatSettings : Internal.ChatSettings { + /// + /// If the IRC connection is established + /// + [Permissions(DenyWrite = true)] + bool IrcConnected { get; set; } + + /// + /// If the Discord connection is established + /// + [Permissions(DenyWrite = true)] + bool DiscordConnected { get; set; } + /// /// Channels the Discord bot should listen/announce in /// diff --git a/src/Tgstation.Server.Api/Models/CompileJob.cs b/src/Tgstation.Server.Api/Models/CompileJob.cs index 2cc0f74988..a3b97ed6f7 100644 --- a/src/Tgstation.Server.Api/Models/CompileJob.cs +++ b/src/Tgstation.Server.Api/Models/CompileJob.cs @@ -7,7 +7,12 @@ /// The that triggered the job /// public User TriggeredBy { get; set; } - + + /// + /// The that cancelled the job if any + /// + public User CancelledBy { get; set; } + /// /// Git revision the compiler ran on. Not modifiable /// diff --git a/src/Tgstation.Server.Api/Models/Configuration.cs b/src/Tgstation.Server.Api/Models/Configuration.cs index 16b57be176..df3ceac5a2 100644 --- a/src/Tgstation.Server.Api/Models/Configuration.cs +++ b/src/Tgstation.Server.Api/Models/Configuration.cs @@ -1,4 +1,4 @@ -using Tgstation.Server.Api.Rights; +using Tgstation.Server.Api.Models.Internal; namespace Tgstation.Server.Api.Models { @@ -6,35 +6,12 @@ namespace Tgstation.Server.Api.Models /// Represents a static game file. Create and delete actions uncerimonuously overwrite/delete files /// #pragma warning disable CA1724 // System.Configuration name conflict - [Model(RightsType.Configuration, CanCrud = true, CanList = true, RequiresInstance = true, ReadRight = ConfigurationRights.Read, WriteRight = ConfigurationRights.Write)] - public sealed class Configuration + public sealed class Configuration : ConfigurationFileMetadata #pragma warning restore CA1724 // System.Configuration name conflict { - /// - /// The path to the file - /// - public string Path { get; set; } - - /// - /// If read access to the file was denied - /// - [Permissions(DenyWrite = true)] - public bool ReadDenied { get; set; } - - /// - /// If represents a directory. Will only be if is - /// - [Permissions(DenyWrite = true)] - public bool IsDirectory { get; set; } - /// /// The content of the file. Will be if is or during listing operations /// public byte[] Content { get; set; } - - /// - /// The MD5 hash of the file when last read by the user. Will be if is . If this doesn't match during update actions, the write will be denied with error code 409 - /// - public string LastReadHash { get; set; } } } diff --git a/src/Tgstation.Server.Api/Models/Internal/CompileJob.cs b/src/Tgstation.Server.Api/Models/Internal/CompileJob.cs index 9fccf5e173..add902e9cb 100644 --- a/src/Tgstation.Server.Api/Models/Internal/CompileJob.cs +++ b/src/Tgstation.Server.Api/Models/Internal/CompileJob.cs @@ -22,12 +22,18 @@ namespace Tgstation.Server.Api.Models.Internal /// /// When the compilation finished /// + [Required] public DateTimeOffset FinishedAt { get; set; } /// - /// If the compiler targeted the primary directory + /// The detected DMAPI version /// - public bool? TargetedPrimaryDirectory { get; set; } + public Version DMApiVersion { get; set; } + + /// + /// The .dme file used for compilation + /// + public string DmePath { get; set; } /// /// Textual output of DM @@ -35,7 +41,7 @@ namespace Tgstation.Server.Api.Models.Internal public string Output { get; set; } /// - /// Exit code of DM. If , the job was cancelled + /// Exit code of DM. If /// public int? ExitCode { get; set; } } diff --git a/src/Tgstation.Server.Api/Models/Internal/ConfigurationFileMetadata.cs b/src/Tgstation.Server.Api/Models/Internal/ConfigurationFileMetadata.cs new file mode 100644 index 0000000000..e402872f3d --- /dev/null +++ b/src/Tgstation.Server.Api/Models/Internal/ConfigurationFileMetadata.cs @@ -0,0 +1,33 @@ +using Tgstation.Server.Api.Rights; + +namespace Tgstation.Server.Api.Models.Internal +{ + /// + /// Metadata about a file + /// + [Model(RightsType.Configuration, CanCrud = true, CanList = true, RequiresInstance = true, ReadRight = ConfigurationRights.Read, WriteRight = ConfigurationRights.Write)] + public class ConfigurationFileMetadata + { + /// + /// The path to the file + /// + public string Path { get; set; } + + /// + /// If read access to the file was denied + /// + [Permissions(DenyWrite = true)] + public bool ReadDenied { get; set; } + + /// + /// If represents a directory. Will only be if is + /// + [Permissions(DenyWrite = true)] + public bool IsDirectory { get; set; } + + /// + /// The MD5 hash of the file when last read by the user. Will be if is . If this doesn't match during update actions, the write will be denied with error code 409 + /// + public string LastReadHash { get; set; } + } +} diff --git a/src/Tgstation.Server.Api/Models/Internal/DreamDaemonLaunchParameters.cs b/src/Tgstation.Server.Api/Models/Internal/DreamDaemonLaunchParameters.cs new file mode 100644 index 0000000000..8602b302b5 --- /dev/null +++ b/src/Tgstation.Server.Api/Models/Internal/DreamDaemonLaunchParameters.cs @@ -0,0 +1,35 @@ +using Tgstation.Server.Api.Rights; + +namespace Tgstation.Server.Api.Models.Internal +{ + /// + /// Launch settings for DreamDaemon + /// + [Model(RightsType.DreamDaemon, CanCrud = true, RequiresInstance = true)] + public class DreamDaemonLaunchParameters + { + /// + /// If the BYOND web client can be used to connect to the game server + /// + [Permissions(ReadRight = DreamDaemonRights.ReadMetadata, WriteRight = DreamDaemonRights.SetWebClient)] + public bool AllowWebClient { get; set; } + + /// + /// The level of + /// + [Permissions(ReadRight = DreamDaemonRights.ReadMetadata, WriteRight = DreamDaemonRights.SetSecurity)] + public DreamDaemonSecurity SecurityLevel { get; set; } + + /// + /// The first port uses. This should be the publically advertised port + /// + [Permissions(ReadRight = DreamDaemonRights.ReadMetadata, WriteRight = DreamDaemonRights.SetPorts)] + public ushort PrimaryPort { get; set; } + + /// + /// The second port uses + /// + [Permissions(ReadRight = DreamDaemonRights.ReadMetadata, WriteRight = DreamDaemonRights.SetPorts)] + public ushort SecondaryPort { get; set; } + } +} \ No newline at end of file diff --git a/src/Tgstation.Server.Api/Models/Internal/DreamDaemonSettings.cs b/src/Tgstation.Server.Api/Models/Internal/DreamDaemonSettings.cs index 6b0520c59e..b4fd279881 100644 --- a/src/Tgstation.Server.Api/Models/Internal/DreamDaemonSettings.cs +++ b/src/Tgstation.Server.Api/Models/Internal/DreamDaemonSettings.cs @@ -5,8 +5,7 @@ namespace Tgstation.Server.Api.Models.Internal /// /// Configurable settings for /// - [Model(RightsType.DreamDaemon, CanCrud = true, RequiresInstance = true)] - public class DreamDaemonSettings + public class DreamDaemonSettings : DreamDaemonLaunchParameters { /// /// If starts when it's starts @@ -14,12 +13,6 @@ namespace Tgstation.Server.Api.Models.Internal [Permissions(ReadRight = DreamDaemonRights.ReadMetadata, WriteRight = DreamDaemonRights.SetAutoStart)] public bool AutoStart { get; set; } - /// - /// If the BYOND web client can be used to connect to the game server - /// - [Permissions(ReadRight = DreamDaemonRights.ReadMetadata, WriteRight = DreamDaemonRights.SetWebClient)] - public bool AllowWebClient { get; set; } - /// /// If the server is undergoing a soft reset. This may be automatically set by changes to other fields /// @@ -31,23 +24,5 @@ namespace Tgstation.Server.Api.Models.Internal /// [Permissions(ReadRight = DreamDaemonRights.ReadMetadata, WriteRight = DreamDaemonRights.SoftShutdown)] public bool SoftShutdown { get; set; } - - /// - /// The level of - /// - [Permissions(ReadRight = DreamDaemonRights.ReadMetadata, WriteRight = DreamDaemonRights.SetSecurity)] - public DreamDaemonSecurity SecurityLevel { get; set; } - - /// - /// The first port uses. This should be the publically advertised port - /// - [Permissions(ReadRight = DreamDaemonRights.ReadMetadata, WriteRight = DreamDaemonRights.SetPorts)] - public ushort PrimaryPort { get; set; } - - /// - /// The second port uses - /// - [Permissions(ReadRight = DreamDaemonRights.ReadMetadata, WriteRight = DreamDaemonRights.SetPorts)] - public ushort SecondaryPort { get; set; } } } diff --git a/src/Tgstation.Server.Api/Models/Internal/DreamMakerSettings.cs b/src/Tgstation.Server.Api/Models/Internal/DreamMakerSettings.cs index 8d31ef3ef0..2e07ee683a 100644 --- a/src/Tgstation.Server.Api/Models/Internal/DreamMakerSettings.cs +++ b/src/Tgstation.Server.Api/Models/Internal/DreamMakerSettings.cs @@ -15,9 +15,9 @@ namespace Tgstation.Server.Api.Models.Internal public int? AutoCompileInterval { get; set; } /// - /// The .dme file tries to compile with + /// The .dme file tries to compile with without the extension /// [Permissions(WriteRight = DreamMakerRights.SetDme)] - public string TargetDme { get; set; } + public string ProjectName { get; set; } } } diff --git a/src/Tgstation.Server.Host/Components/IByond.cs b/src/Tgstation.Server.Host/Components/IByond.cs index 9729da3ea3..ab3450872e 100644 --- a/src/Tgstation.Server.Host/Components/IByond.cs +++ b/src/Tgstation.Server.Host/Components/IByond.cs @@ -1,6 +1,35 @@ -namespace Tgstation.Server.Host.Components +using System; +using System.Threading; +using System.Threading.Tasks; + +namespace Tgstation.Server.Host.Components { + /// + /// For managing the BYOND installation + /// interface IByond { + /// + /// Change the current BYOND version + /// + /// The new + /// The for the operation + Task ChangeVersion(Version version, CancellationToken cancellationToken); + + /// + /// Get the currently installed BYOND version + /// + /// The for the operation + /// The current BYOND version + Task GetVersion(CancellationToken cancellationToken); + + /// + /// Lock the current installation's location and run an + /// + /// A taking the path to either dm.exe or dreamdaemon.exe and returning a + /// Use the staged installation if possible + /// Pass the path of dreamdaemon.exe to if dm.exe otherwise + /// A representing the running + Task UseExecutable(Func operation, bool stagedIfExists, bool dreamDaemon); } } \ No newline at end of file diff --git a/src/Tgstation.Server.Host/Components/IChat.cs b/src/Tgstation.Server.Host/Components/IChat.cs index a207605d0c..13fe8fa5dc 100644 --- a/src/Tgstation.Server.Host/Components/IChat.cs +++ b/src/Tgstation.Server.Host/Components/IChat.cs @@ -1,8 +1,40 @@ using Microsoft.Extensions.Hosting; +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using Tgstation.Server.Api.Models.Internal; namespace Tgstation.Server.Host.Components { + /// + /// For managing connected chat services + /// interface IChat : IHostedService { + /// + /// If the IRC client is connected + /// + bool IrcConnected { get; } + + /// + /// If the Discord client is connected + /// + bool DiscordConnected { get; } + + /// + /// Change chat settings + /// + /// The new + /// The for the operation + /// A representing the running operation + Task ChangeSettings(ChatSettings newSettings, CancellationToken cancellationToken); + + /// + /// Change chat channels + /// + /// An of the new list of s + /// The for the operation + /// A representing the running operation + Task ChangeChannels(IEnumerable newChannels, CancellationToken cancellationToken); } } \ No newline at end of file diff --git a/src/Tgstation.Server.Host/Components/IConfiguration.cs b/src/Tgstation.Server.Host/Components/IConfiguration.cs index c0d4615989..75bacfd240 100644 --- a/src/Tgstation.Server.Host/Components/IConfiguration.cs +++ b/src/Tgstation.Server.Host/Components/IConfiguration.cs @@ -1,6 +1,56 @@ -namespace Tgstation.Server.Host.Components +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using Tgstation.Server.Api.Models.Internal; +using Tgstation.Server.Host.Security; + +namespace Tgstation.Server.Host.Components { + /// + /// For managing the Configuration directory + /// interface IConfiguration { + /// + /// Copies all files in the CodeModifications directory to + /// + /// Path to the destination folder + /// A resultin in a of #include lines for the .dm files copied + Task> CopyDMFilesTo(string destination, CancellationToken cancellationToken); + + /// + /// Symlinks all directories in the GameData directory to + /// + /// Path to the destination folder + /// + /// A representing the running operation + Task SymlinkStaticFilesTo(string destination, CancellationToken cancellationToken); + + /// + /// Get for all items in a given + /// + /// The relative path in the Configuration directory + /// The for the operation. If , the operation will be performed as the user of the + /// The for the operation + /// A resulting in the for the items in the directory + Task> ListDirectory(string configurationRelativePath, ISystemIdentity systemIdentity, CancellationToken cancellationToken); + + /// + /// + /// + /// The relative path in the Configuration directory + /// The for the operation. If , the operation will be performed as the user of the + /// The for the operation + /// A resulting in the of the file + Task Read(string configurationRelativePath, ISystemIdentity systemIdentity, CancellationToken cancellationToken); + + /// + /// + /// + /// The relative path in the Configuration directory + /// The data to write + /// The for the operation. Usage may result in partial writes + /// A resulting in if the operation succeeded, if it failed due to permission errors + Task Write(string configurationRelativePath, ISystemIdentity systemIdentity, byte[] data, CancellationToken cancellationToken); } } \ No newline at end of file diff --git a/src/Tgstation.Server.Host/Components/IDreamDaemon.cs b/src/Tgstation.Server.Host/Components/IDreamDaemon.cs index 9a9b37db20..f5cf744187 100644 --- a/src/Tgstation.Server.Host/Components/IDreamDaemon.cs +++ b/src/Tgstation.Server.Host/Components/IDreamDaemon.cs @@ -1,10 +1,63 @@ using Microsoft.Extensions.Hosting; using System.Threading; using System.Threading.Tasks; +using Tgstation.Server.Api.Models.Internal; namespace Tgstation.Server.Host.Components { + /// + /// For managing DreamDaemon + /// interface IDreamDaemon : IHostedService { + /// + /// If DreamDaemon is running + /// + bool Running { get; } + + /// + /// The port DreamDaemon is currently running on + /// + ushort? CurrentPort { get; } + + /// + /// The access token used for communication with the DMAPI + /// + string AccessToken { get; } + + /// + /// Launch DreamDaemon + /// + /// The for the launch + /// The for the operation + /// A representing the running operation + Task Launch(DreamDaemonLaunchParameters launchParameters, CancellationToken cancellationToken); + + /// + /// Changes the if currently . Triggers a graceful restart + /// + /// The new + void ChangeSettings(DreamDaemonLaunchParameters launchParameters); + + /// + /// Restarts DreamDaemon + /// + /// If the restart will be delayed until a reboot is detected in the DMAPI and this function will retrun immediately. If the DMAPI isn't installed, this parameter is ignored + /// The for the operation + /// A representing the running operation + Task Restart(bool graceful, CancellationToken cancellationToken); + + /// + /// Terminates DreamDaemon + /// + /// If the termination will be delayed until a reboot is detected in the DMAPI and this function will return immediately. If the DMAPI isn't installed, this parameter is ignored + /// The for the operation + /// A representing the running operation + Task Terminate(bool graceful, CancellationToken cancellationToken); + + /// + /// Cancels any pending graceful reboots or terminations + /// + void CancelGracefulActions(); } } \ No newline at end of file diff --git a/src/Tgstation.Server.Host/Components/IDreamMaker.cs b/src/Tgstation.Server.Host/Components/IDreamMaker.cs index b5d9be9436..9f119ac27d 100644 --- a/src/Tgstation.Server.Host/Components/IDreamMaker.cs +++ b/src/Tgstation.Server.Host/Components/IDreamMaker.cs @@ -1,8 +1,21 @@ using Microsoft.Extensions.Hosting; +using System.Threading; +using System.Threading.Tasks; +using Tgstation.Server.Host.Models; namespace Tgstation.Server.Host.Components { + /// + /// For managing the compiler + /// interface IDreamMaker : IHostedService { + /// + /// Starts a compile + /// + /// The .dme file to use + /// The for the operation + /// A resulting in the partially populated for the operation + Task Compile(string dmePath, CancellationToken cancellationToken); } } \ No newline at end of file diff --git a/src/Tgstation.Server.Host/Models/CompileJob.cs b/src/Tgstation.Server.Host/Models/CompileJob.cs index 29bdac135c..a22e7ec5c3 100644 --- a/src/Tgstation.Server.Host/Models/CompileJob.cs +++ b/src/Tgstation.Server.Host/Models/CompileJob.cs @@ -8,13 +8,16 @@ namespace Tgstation.Server.Host.Models /// /// See /// - [Required] public User TriggeredBy { get; set; } + /// + /// See + /// + public User CancelledBy { get; set; } + /// /// See /// - [Required] public RevisionInformation RevisionInformation { get; set; } } }