Merge pull request #570 from Cyberboss/ArchitectureDocs

Architecture docs

.github/CONTRIBUTING.md

@@ -12,6 +12,8 @@ First things first, we want to make it clear how you can contribute (if you've n
 
 If you want to contribute the first thing you'll need to do is [set up Git](http://tgstation13.org/wiki/Setting_up_git) so you can download the source code.
 
+You'll probably want to get a brief overview of the [server architecture](https://tgstation.github.io/tgstation-server/architecture.html) so as to better implement your change
+
 There is an open list of approachable issues for [your inspiration here](https://github.com/tgstation/tgstation-server/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22). You can also view the waffle board [here](https://waffle.io/tgstation/tgstation-server).
 
 Here is a link to the code's always up-to-date documentation: https://tgstation.github.io/tgstation-server/annotated.html

build/Doxyfile

@@ -864,8 +864,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-#We want the main .md
-EXCLUDE                =
+EXCLUDE                = packages
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -918,7 +917,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             = 
+IMAGE_PATH             = docs
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program

docs/Architecture.dox

@@ -0,0 +1,61 @@
+/*!
+@page architecture Server Architecture
+
+@tableofcontents
+
+@image html ArchitectureOverview.png "Architecture Overview"
+
+@section arch_intro Introduction
+
+This is meant to be a brief overview of the TGS4 architecture to give new coders direction on where to code and the curious some insight to their questions. Given that this document is seperate from the authorative code it may fall out of date. For clairity, please contact project maintainers.
+
+@section arch_hwatchdog Host Watchdog
+
+The host watchdog process monitors the actual server application. It exists mainly to facilitate the live update system built into it and also serves as a restart mechanism if requested. This component is generally not present in active development scenarios due to debugging overhead.
+
+This consists of two parts a runner and the watchdog library. The library is the Tgstation.Server.Host.Watchdog project and the runners are the Tgstation.Server.Host.Console .NET Core project and the Tgstation.Server.Host.Service .NET Framework Windows service project
+
+@section arch_main Main Server
+
+This is a second process spawned by the Host Watchdog which facilitates the vast majority of the code. This is the Tgstation.Server.Host project which is fundamentally an ASP.NET Core MVC web application.
+
+@subsection arch_setup Server Initialization
+
+The server's entrypoint is in the @ref Tgstation.Server.Host.Program class. This class mainly determines if the Host watchdog is present and creates and runs the @ref Tgstation.Server.Host.Server class. That class then builds an ASP.NET Core web host using the @ref Tgstation.Server.Host.Core.Application class.
+
+The @ref Tgstation.Server.Host.Core.Application class has two methods called by the framework. First the @ref Tgstation.Server.Host.Core.Application.ConfigureServices method sets up dependency injection of interfaces for Controllers, the @ref Tgstation.Server.Host.Models.DatabaseContext, and the component factories of the server. The framework handles constructing these things once the application starts. Configuration is loaded from the appropriate appSettings.json into the @ref Tgstation.Server.Host.Configuration classes for injection as well. Then @ref Tgstation.Server.Host.Core.Application.Configure method is run which sets up the web request pipeline which currently has the following stack of handlers:
+
+- Catch any exceptions and respond with 500 and detailed HTML error page
+- Respond with 503 if the application is still starting or shutting down
+- Authenticate the JWT in Authentication header if present and run @ref Tgstation.Server.Host.Controllers.ApiController on success
+- Catch database exceptions and convert to 409 responses with the exception's @ref Tgstation.Server.Api.Models.ErrorMessage
+- Check @ref Tgstation.Server.Host.Controllers for correct controller and run the action and use it's response. 
+	- If not properly authenticated beforehand and action has a @ref Tgstation.Server.Host.Controllers.TgsAuthorizeAttribute return 401
+	- If not properly authorized beforehand according to the parameters of the action's @ref Tgstation.Server.Host.Controllers.TgsAuthorizeAttribute (if present) return 403
+	- If requested action does not exist return 404
+
+@subsubsection arch_instinit Instance Manager Initialization
+
+Once the web host starts, the @ref Tgstation.Server.Host.Components.InstanceManager.StartAsync function is called (due to being registered as a IHostedService in @ref Tgstation.Server.Host.Core.Application) this is the only StartAsync implementation that should be called by the framework, others should be called from this to maintain a cohesive initialization order.
+
+The first thing this function does is call @ref Tgstation.Server.Host.Models.DatabaseContext.Initialize which ensures the database is migrated, seeded, and ready to go. Then the @ref Tgstation.Server.Host.Core.JobManager is started, which cleans up any jobs that are considered "still running" in the database. Finally all instances configured to be online are created in parallel (See @ref arch_instance for onlining process) and the @ref Tgstation.Server.Host.Core.Application is signalled to stop blocking requests with 503 responses before they are processed.
+
+@section arch_db Database and Context
+
+@section arch_security Security
+
+@section arch_controllers Controllers
+
+@section arch_jobs Jobs
+
+@section arch_instance Instances
+
+@subsection arch_ifactory Instance Factory
+
+@section arch_watchdog Watchdog
+
+@subsection Communication
+
+@section arch_update Host Update Process
+
+*/

src/Tgstation.Server.Api/Tgstation.Server.Api.csproj

@@ -9,7 +9,7 @@
     <Description>API definitions for tgstation-server</Description>
     <PackageLicenseUrl>https://github.com/tgstation/tgstation-server/blob/master/LICENSE.md</PackageLicenseUrl>
     <PackageProjectUrl>https://tgstation.github.io/tgstation-server</PackageProjectUrl>
-    <PackageIconUrl>https://raw.githubusercontent.com/tgstation/tgstation-server/master/tgs.ico</PackageIconUrl>
+    <PackageIconUrl>https://raw.githubusercontent.com/tgstation/tgstation-server/master/build/tgs.ico</PackageIconUrl>
     <RepositoryType>Git</RepositoryType>
     <RepositoryUrl>https://github.com/tgstation/tgstation-server</RepositoryUrl>
     <Copyright>2018</Copyright>

src/Tgstation.Server.Host/Controllers/ApiController.cs

@@ -135,7 +135,8 @@ namespace Tgstation.Server.Host.Controllers
 		/// <inheritdoc />
 		public override async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
 		{
-			//ALL requests go through this function
+			//ALL valid token and login requests that match a route go through this function
+			//404 is returned before
 
 			if (AuthenticationContext != null && AuthenticationContext.User == null)
 			{

src/Tgstation.Server.Host/Core/Application.cs

@@ -54,11 +54,6 @@ namespace Tgstation.Server.Host.Core
 
 		readonly TaskCompletionSource<object> startupTcs;
 
-		/// <summary>
-		/// The <see cref="IServerAddressesFeature"/> for the <see cref="Application"/>
-		/// </summary>
-		IServerAddressesFeature serverAddresses;
-
 		/// <summary>
 		/// Construct an <see cref="Application"/>
 		/// </summary>
@@ -236,8 +231,6 @@ namespace Tgstation.Server.Host.Core
 				throw new ArgumentNullException(nameof(logger));
 
 			logger.LogInformation(VersionString);
-
-			serverAddresses = applicationBuilder.ServerFeatures.Get<IServerAddressesFeature>();
 			
 			applicationBuilder.UseDeveloperExceptionPage();	//it is not worth it to limit this, you should only ever get it if you're an authorized user
 

tgstation-server.sln

@@ -101,6 +101,8 @@ EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{DCC75431-7913-4306-9FAB-70998D440BCE}"
 	ProjectSection(SolutionItems) = preProject
 		docs\API.dox = docs\API.dox
+		docs\ArchitectureOverview.png = docs\ArchitectureOverview.png
+		docs\Architecture.dox = docs\Architecture.dox
 	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = ".github", ".github", "{E82104F4-F5C4-4786-ACD4-B635166CDB21}"