Write all XML doc comments

This commit is contained in:
Cyberboss
2018-04-11 13:35:32 -04:00
parent e62fc56184
commit 9f942f295e
31 changed files with 270 additions and 52 deletions
+1 -1
View File
@@ -23,7 +23,7 @@ namespace Tgstation.Server.Api.Models
public string Name { get; set; }
/// <summary>
/// The path to where the <see cref="Instance"/> is located
/// The path to where the <see cref="Instance"/> is located. Changing this will temporarily offline the <see cref="Instance"/> while it moves
/// </summary>
[Permissions(WriteRight = InstanceManagerRights.Relocate)]
[Required]
@@ -6,7 +6,7 @@ namespace Tgstation.Server.Api.Models.Internal
/// <summary>
/// Represents a long running job
/// </summary>
[Model]
[Model(RequiresInstance = true)]
public class Job
{
/// <summary>
@@ -16,6 +16,12 @@ namespace Tgstation.Server.Api.Models.Internal
[Permissions(DenyWrite = true)]
public long Id { get; set; }
/// <summary>
/// If the <see cref="User"/> is enabled since users cannot be deleted. System users cannot be disabled
/// </summary>
[Permissions(WriteRight = AdministrationRights.EditUsers)]
public bool Enabled { get; set; }
/// <summary>
/// When the <see cref="User"/> was created
/// </summary>
+2 -2
View File
@@ -4,9 +4,9 @@
public sealed class User : Internal.User
{
/// <summary>
/// If the <see cref="User"/> is enabled since users cannot be deleted
/// The <see cref="User"/> who created this <see cref="User"/>
/// </summary>
[Permissions(DenyWrite = true)]
public bool Enabled { get; set; }
public User CreatedBy { get; set; }
}
}
@@ -1,9 +1,23 @@
namespace Tgstation.Server.Host.Configuration
{
/// <summary>
/// Configuration options for the <see cref="Models.DatabaseContext{TParentContext}"/>
/// </summary>
sealed class DatabaseConfiguration
{
/// <summary>
/// The key for the <see cref="Microsoft.Extensions.Configuration.IConfigurationSection"/> the <see cref="DatabaseConfiguration"/> resides in
/// </summary>
public const string Section = "Database";
/// <summary>
/// The <see cref="Configuration.DatabaseType"/> to create
/// </summary>
public DatabaseType DatabaseType { get; set; }
/// <summary>
/// The connection string for the database
/// </summary>
public string ConnectionString { get; set; }
}
}
@@ -1,9 +1,21 @@
namespace Tgstation.Server.Host.Configuration
{
/// <summary>
/// Type of database to user
/// </summary>
enum DatabaseType
{
/// <summary>
/// Use Microsoft SQL Server
/// </summary>
SqlServer,
/// <summary>
/// Use MySQL/MariaDB
/// </summary>
MySql,
/// <summary>
/// Use SQLite 3
/// </summary>
Sqlite
}
}
@@ -6,7 +6,6 @@ using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using System;
using System.Collections.Generic;
using System.Globalization;
using Tgstation.Server.Host.Configuration;
using Tgstation.Server.Host.Models;
@@ -78,7 +77,7 @@ namespace Tgstation.Server.Host.Core
services.AddScoped<IDatabaseContext>(x => x.GetRequiredService<SqlServerDatabaseContext>());
break;
default:
throw new InvalidOperationException("Invalid DatabaseType!");
throw new InvalidOperationException(String.Format(CultureInfo.InvariantCulture, "Invalid {0}!", nameof(DatabaseType)));
}
services.AddSingleton<ICryptographySuite, CryptographySuite>();
@@ -100,11 +99,11 @@ namespace Tgstation.Server.Host.Core
applicationBuilder.UseAsyncInitialization(async (cancellationToken) =>
{
using (var scop = applicationBuilder.ApplicationServices.CreateScope())
await scop.ServiceProvider.GetRequiredService<IDatabaseContext>().Initialize(cancellationToken).ConfigureAwait(false);
using (var scope = applicationBuilder.ApplicationServices.CreateScope())
await scope.ServiceProvider.GetRequiredService<IDatabaseContext>().Initialize(cancellationToken).ConfigureAwait(false);
});
applicationBuilder.UseSystemAuthentication();
applicationBuilder.UseAuthentication();
applicationBuilder.UseMvc();
}
@@ -1,13 +1,18 @@
using Microsoft.AspNetCore.Builder;
using System;
using System.Collections.Generic;
using System.Text;
namespace Tgstation.Server.Host.Core
{
/// <summary>
/// Extension methods for <see cref="IApplicationBuilder"/>
/// </summary>
static class ApplicationBuilderExtensions
{
public static IApplicationBuilder UseSystemAuthentication(this IApplicationBuilder applicationBuilder)
/// <summary>
/// Apply the <see cref="AuthenticationContext"/> middleware
/// </summary>
/// <param name="applicationBuilder">The <paramref name="applicationBuilder"/> to add the middleware for</param>
/// <returns><paramref name="applicationBuilder"/></returns>
public static IApplicationBuilder UseAuthentication(this IApplicationBuilder applicationBuilder)
{
AuthenticationContext.AddToPipeline(applicationBuilder);
return applicationBuilder;
@@ -7,6 +7,7 @@ using System.Threading;
using System.Threading.Tasks;
using Tgstation.Server.Api;
using Tgstation.Server.Host.Models;
using Tgstation.Server.Api.Models;
namespace Tgstation.Server.Host.Core
{
@@ -55,7 +56,7 @@ namespace Tgstation.Server.Host.Core
{
if (headers.IsTokenAuthentication)
{
var user = await tokenManager.GetUser(headers.Token, httpContext.RequestAborted).ConfigureAwait(false);
var user = await tokenManager.GetUser(new Token { Value = headers.Token }, httpContext.RequestAborted).ConfigureAwait(false);
systemIdentity = systemIdentityFactory.CreateSystemIdentity(user);
}
else
@@ -98,13 +99,13 @@ namespace Tgstation.Server.Host.Core
public void Dispose() => SystemIdentity.Dispose();
/// <inheritdoc />
public Task<User> User(CancellationToken cancellationToken)
public Task<Models.User> User(CancellationToken cancellationToken)
{
throw new NotImplementedException();
}
/// <inheritdoc />
public Task<Api.Models.InstanceUser> InstanceUser(Instance instance, CancellationToken cancellationToken)
public Task<Models.InstanceUser> InstanceUser(Models.Instance instance, CancellationToken cancellationToken)
{
throw new NotImplementedException();
}
@@ -1,12 +1,17 @@
using Microsoft.AspNetCore.Http;
using System;
using System.Collections.Generic;
using System.Text;
namespace Tgstation.Server.Host.Core
{
/// <summary>
/// Extension methods for <see cref="HttpContext"/>
/// </summary>
static class HttpContextExtensions
{
public static IAuthenticationContext AuthenticationContext(this HttpContext httpContext) => Core.AuthenticationContext.Current(httpContext);
/// <summary>
/// Get the <see cref="IAuthenticationContext"/> associated with the <see cref="HttpContext"/>
/// </summary>
/// <param name="httpContext">The <see cref="HttpContext"/> containing the <see cref="IAuthenticationContext"/></param>
/// <returns>The <see cref="IAuthenticationContext"/> associated with the <see cref="HttpContext"/></returns>
public static IAuthenticationContext AuthenticationContext(this HttpContext httpContext) => Core.AuthenticationContext.Current(httpContext);
}
}
@@ -25,9 +25,9 @@ namespace Tgstation.Server.Host.Core
/// <summary>
/// The <see cref="Api.Models.InstanceUser"/> represented by <see cref="User"/> and a given <paramref name="instance"/>
/// </summary>
/// <param name="instance">The <see cref="Instance"/> of the <see cref="Api.Models.InstanceUser"/></param>
/// <param name="instance">The <see cref="Instance"/> of the <see cref="Models.InstanceUser"/></param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> for the operation</param>
/// <returns>A <see cref="Task{TResult}"/> resulting in the <see cref="Api.Models.InstanceUser"/> represented by <see cref="User"/> and a given <paramref name="instance"/></returns>
Task<Api.Models.InstanceUser> InstanceUser(Instance instance, CancellationToken cancellationToken);
/// <returns>A <see cref="Task{TResult}"/> resulting in the <see cref="Models.InstanceUser"/> represented by <see cref="User"/> and a given <paramref name="instance"/></returns>
Task<InstanceUser> InstanceUser(Instance instance, CancellationToken cancellationToken);
}
}
@@ -1,7 +1,14 @@
namespace Tgstation.Server.Host.Core
{
/// <summary>
/// Represents a service that may take an updated <see cref="Host"/> assembly and run it, stopping the current assembly in the process
/// </summary>
interface IServerUpdateConsumer
{
/// <summary>
/// Run a new <see cref="Host"/> assembly and stop the current one. This will likely trigger all active <see cref="System.Threading.CancellationToken"/>s
/// </summary>
/// <param name="updatePath">The path to the new <see cref="Host"/> assembly</param>
void ApplyUpdate(string updatePath);
}
}
@@ -3,12 +3,30 @@ using System.Collections.Generic;
namespace Tgstation.Server.Host.Core
{
/// <summary>
/// Represents a user on the current <see cref="System.Runtime.InteropServices.OSPlatform"/>
/// </summary>
interface ISystemIdentity : IDisposable
{
/// <summary>
/// A unique identifier for the user
/// </summary>
string Uid { get; }
/// <summary>
/// The user's name
/// </summary>
string Username { get; }
/// <summary>
/// Groups the user is in
/// </summary>
IEnumerable<string> Groups { get; }
/// <summary>
/// Clone the <see cref="ISystemIdentity"/> creating another copy that must have <see cref="IDisposable.Dispose"/> called on it
/// </summary>
/// <returns>A new <see cref="ISystemIdentity"/> mirroring the current one</returns>
ISystemIdentity Clone();
}
}
@@ -1,10 +1,25 @@
using Tgstation.Server.Api.Models;
using Tgstation.Server.Host.Models;
namespace Tgstation.Server.Host.Core
{
/// <summary>
/// Factory for <see cref="ISystemIdentity"/>s
/// </summary>
interface ISystemIdentityFactory
{
/// <summary>
/// Create a <see cref="ISystemIdentity"/> for a given <paramref name="user"/>
/// </summary>
/// <param name="user">The user to create a <see cref="ISystemIdentity"/> for</param>
/// <returns>A new <see cref="ISystemIdentity"/></returns>
ISystemIdentity CreateSystemIdentity(User user);
/// <summary>
/// Create a <see cref="ISystemIdentity"/> for a given username and password
/// </summary>
/// <param name="username">The username of the user</param>
/// <param name="password">The password of the user</param>
/// <returns>A new <see cref="ISystemIdentity"/></returns>
ISystemIdentity CreateSystemIdentity(string username, string password);
}
}
@@ -1,15 +1,27 @@
using System.Collections.Generic;
using System.Threading;
using System.Threading;
using System.Threading.Tasks;
using Tgstation.Server.Api.Models;
namespace Tgstation.Server.Host.Core
{
/// <summary>
/// For creating and decoding JWTs
/// </summary>
interface ITokenManager
{
Task<User> GetUser(string token, CancellationToken cancellationToken);
Task<Token> CreateToken(User user, CancellationToken cancellationToken);
Task<IReadOnlyList<Token>> UserTokens(User user, CancellationToken cancellationToken);
Task<IDictionary<User, Token>> AllTokens(CancellationToken cancellationToken);
/// <summary>
/// Get the user associated with a <paramref name="token"/>
/// </summary>
/// <param name="token">The <see cref="Token"/> to get the user for</param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> for the operation</param>
/// <returns>The <see cref="Models.User"/> associated with the <paramref name="token"/></returns>
Task<Models.User> GetUser(Token token, CancellationToken cancellationToken);
/// <summary>
/// Create a <see cref="Token"/> for a given <paramref name="user"/>
/// </summary>
/// <param name="user">The <see cref="Models.User"/> to create the token for. Must have the <see cref="Api.Models.Internal.User.Id"/> and <see cref="Models.User.TokenSecret"/> fields available</param>
/// <returns>A new <see cref="Token"/></returns>
Token CreateToken(Models.User user);
}
}
@@ -1,9 +1,10 @@
namespace Tgstation.Server.Host.Models
{
/// <inheritdoc />
sealed class ChatChannel : Api.Models.ChatChannel
{
/// <summary>
/// The column ID
/// The row Id
/// </summary>
public long Id { get; set; }
}
@@ -3,17 +3,33 @@ using System.ComponentModel.DataAnnotations;
namespace Tgstation.Server.Host.Models
{
/// <inheritdoc />
sealed class ChatSettings : Api.Models.Internal.ChatSettings
{
/// <summary>
/// The row Id
/// </summary>
public long Id { get; set; }
/// <summary>
/// The <see cref="Api.Models.Instance.Id"/>
/// </summary>
public long InstanceId { get; set; }
/// <summary>
/// The parent <see cref="Models.Instance"/>
/// </summary>
[Required]
public Instance Instance { get; set; }
/// <summary>
/// See <see cref="Api.Models.ChatSettings.AdminChannels"/>
/// </summary>
public List<ChatChannel> AdminChannels { get; set; }
/// <summary>
/// See <see cref="Api.Models.ChatSettings.GeneralChannels"/>
/// </summary>
public List<ChatChannel> GeneralChannels { get; set; }
}
}
@@ -2,11 +2,18 @@
namespace Tgstation.Server.Host.Models
{
/// <inheritdoc />
sealed class CompileJob : Api.Models.Internal.CompileJob
{
/// <summary>
/// See <see cref="Api.Models.CompileJob.TriggeredBy"/>
/// </summary>
[Required]
public User TriggeredBy { get; set; }
/// <summary>
/// See <see cref="Api.Models.CompileJob.RevisionInformation"/>
/// </summary>
[Required]
public RevisionInformation RevisionInformation { get; set; }
}
@@ -26,15 +26,46 @@ namespace Tgstation.Server.Host.Models
/// The <see cref="DbSet{TEntity}"/> for <see cref="Log"/>s
/// </summary>
public DbSet<Log> Logs { get; set; }
/// <summary>
/// The <see cref="InstanceUser"/>s in the <see cref="DatabaseContext{TParentContext}"/>
/// </summary>
public DbSet<InstanceUser> InstanceUsers { get; set; }
/// <summary>
/// The <see cref="ChatChannel"/>s in the <see cref="DatabaseContext{TParentContext}"/>
/// </summary>
public DbSet<ChatChannel> ChatChannels { get; set; }
/// <summary>
/// The <see cref="ChatSettings"/>s in the <see cref="DatabaseContext{TParentContext}"/>
/// </summary>
public DbSet<ChatSettings> ChatSettings { get; set; }
/// <summary>
/// The <see cref="Models.DreamDaemonSettings"/> in the <see cref="DatabaseContext{TParentContext}"/>
/// </summary>
public DbSet<DreamDaemonSettings> DreamDaemonSettings { get; set; }
/// <summary>
/// The <see cref="Models.DreamMakerSettings"/> in the <see cref="DatabaseContext{TParentContext}"/>
/// </summary>
public DbSet<DreamMakerSettings> DreamMakerSettings { get; set; }
/// <summary>
/// The <see cref="CompileJob"/>s in the <see cref="DatabaseContext{TParentContext}"/>
/// </summary>
public DbSet<CompileJob> CompileJobs { get; set; }
/// <summary>
/// The <see cref="Job"/>s in the <see cref="DatabaseContext{TParentContext}"/>
/// </summary>
public DbSet<Job> Jobs { get; set; }
/// <summary>
/// The <see cref="TestMerge"/>s in the <see cref="DatabaseContext{TParentContext}"/>
/// </summary>
public DbSet<TestMerge> TestMerges { get; set; }
/// <summary>
/// The <see cref="RevisionInformation"/>s in the <see cref="DatabaseContext{TParentContext}"/>
/// </summary>
public DbSet<RevisionInformation> RevisionInformations { get; set; }
/// <summary>
/// The <see cref="Models.RepositorySettings"/> in the <see cref="DatabaseContext{TParentContext}"/>
/// </summary>
public DbSet<RepositorySettings> RepositorySettings { get; set; }
/// <summary>
@@ -38,7 +38,8 @@ namespace Tgstation.Server.Host.Models
AdministrationRights = (AdministrationRights)~0,
CreatedAt = DateTimeOffset.Now,
InstanceManagerRights = (InstanceManagerRights)~0,
Name = "Admin"
Name = "Admin",
Enabled = true,
};
cryptographySuite.RegenerateUserToken(admin);
cryptographySuite.SetUserPassword(admin, DefaultAdminPassword);
@@ -2,19 +2,38 @@
namespace Tgstation.Server.Host.Models
{
/// <inheritdoc />
sealed class DreamDaemonSettings : Api.Models.Internal.DreamDaemonSettings
{
/// <summary>
/// The row Id
/// </summary>
public long Id { get; set; }
/// <summary>
/// The PID of a currently running DD instance
/// </summary>
public int? ProcessId { get; set; }
/// <summary>
/// The access token used for communication with DD
/// </summary>
public string AccessToken { get; set; }
/// <summary>
/// The <see cref="Api.Models.Instance.Id"/>
/// </summary>
public long InstanceId { get; set; }
/// <summary>
/// The parent <see cref="Models.Instance"/>
/// </summary>
[Required]
public Instance Instance { get; set; }
/// <summary>
/// See <see cref="Api.Models.DreamDaemon.CompileJob"/>
/// </summary>
public CompileJob CompileJob { get; set; }
}
}
@@ -2,15 +2,28 @@
namespace Tgstation.Server.Host.Models
{
/// <inheritdoc />
sealed class DreamMakerSettings : Api.Models.Internal.DreamMakerSettings
{
/// <summary>
/// The row Id
/// </summary>
public long Id { get; set; }
/// <summary>
/// The <see cref="Api.Models.Instance.Id"/>
/// </summary>
public long InstanceId { get; set; }
/// <summary>
/// The parent <see cref="Models.Instance"/>
/// </summary>
[Required]
public Instance Instance { get; set; }
public CompileJob CompileJob { get; set; }
/// <summary>
/// <see cref="Api.Models.DreamMaker.LastJob"/>
/// </summary>
public CompileJob LastJob { get; set; }
}
}
+6 -1
View File
@@ -1,6 +1,5 @@
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using Tgstation.Server.Api.Models;
namespace Tgstation.Server.Host.Models
{
@@ -21,9 +20,15 @@ namespace Tgstation.Server.Host.Models
[Required]
public DreamMakerSettings DreamMakerSettings { get; set; }
/// <summary>
/// The <see cref="Models.DreamDaemonSettings"/> for the <see cref="Instance"/>
/// </summary>
[Required]
public DreamDaemonSettings DreamDaemonSettings { get; set; }
/// <summary>
/// The <see cref="Models.RepositorySettings"/> for the <see cref="Instance"/>
/// </summary>
[Required]
public RepositorySettings RepositorySettings { get; set; }
@@ -1,7 +1,11 @@
namespace Tgstation.Server.Host.Models
{
/// <inheritdoc />
sealed class InstanceUser : Api.Models.InstanceUser
{
/// <summary>
/// The row Id
/// </summary>
public long Id { get; set; }
}
}
+4 -3
View File
@@ -2,12 +2,13 @@
namespace Tgstation.Server.Host.Models
{
/// <inheritdoc />
sealed class Job : Api.Models.Internal.Job
{
/// <summary>
/// See <see cref="Api.Models.Job.StartedBy"/>
/// </summary>
[Required]
public User StartedBy { get; set; }
[Required]
public Instance Instance { get; set; }
}
}
@@ -2,15 +2,28 @@
namespace Tgstation.Server.Host.Models
{
/// <inheritdoc />
sealed class RepositorySettings : Api.Models.Internal.RepositorySettings
{
/// <summary>
/// The row Id
/// </summary>
public long Id { get; set; }
/// <summary>
/// The <see cref="Api.Models.Instance.Id"/>
/// </summary>
public long InstanceId { get; set; }
/// <summary>
/// The parent <see cref="Models.Instance"/>
/// </summary>
[Required]
public Instance Instance { get; set; }
/// <summary>
/// See <see cref="Api.Models.Repository.RevisionInformation"/>
/// </summary>
public RevisionInformation RevisionInformation { get; set; }
}
}
@@ -2,10 +2,17 @@
namespace Tgstation.Server.Host.Models
{
/// <inheritdoc />
sealed class RevisionInformation : Api.Models.Internal.RevisionInformation
{
/// <summary>
/// The row Id
/// </summary>
public long Id { get; set; }
/// <summary>
/// See <see cref="Api.Models.RevisionInformation.TestMerges"/>
/// </summary>
public List<TestMerge> TestMerges { get; set; }
}
}
@@ -1,9 +1,11 @@
using System.ComponentModel.DataAnnotations;
namespace Tgstation.Server.Host.Models
namespace Tgstation.Server.Host.Models
{
/// <inheritdoc />
sealed class ServerSettings : Api.Models.Internal.ServerSettings
{
/// <summary>
/// The row Id
/// </summary>
public long Id { get; set; }
}
}
@@ -2,11 +2,12 @@
namespace Tgstation.Server.Host.Models
{
/// <summary>
/// Represent a merge of a live pull request
/// </summary>
/// <inheritdoc />
sealed class TestMerge : Api.Models.Internal.TestMerge
{
/// <summary>
/// See <see cref="Api.Models.TestMerge.MergedBy"/>
/// </summary>
[Required]
public User MergedBy { get; set; }
}
+7 -3
View File
@@ -4,9 +4,7 @@ using Tgstation.Server.Host.Core;
namespace Tgstation.Server.Host.Models
{
/// <summary>
/// Represents a <see cref="Api.Models.User"/> in the database
/// </summary>
/// <inheritdoc />
sealed class User : Api.Models.Internal.User
{
/// <summary>
@@ -20,6 +18,12 @@ namespace Tgstation.Server.Host.Models
[StringLength(CryptographySuite.SecureStringLength)]
public string TokenSecret { get; set; }
/// <summary>
/// See <see cref="Api.Models.User"/>
/// </summary>
[Required]
public User CreatedBy { get; set; }
/// <summary>
/// The <see cref="InstanceUser"/>s for the <see cref="User"/>
/// </summary>
@@ -1,5 +1,4 @@
using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;
using Tgstation.Server.Host.Startup;
namespace Tgstation.Server.Host