diff --git a/docs/DoxygenLayout.xml b/docs/DoxygenLayout.xml index 5a3182bf8c..f5560d94a8 100644 --- a/docs/DoxygenLayout.xml +++ b/docs/DoxygenLayout.xml @@ -3,7 +3,7 @@ - + diff --git a/docs/Features.dox b/docs/Features.dox index 63a4683f44..dede8e49eb 100644 --- a/docs/Features.dox +++ b/docs/Features.dox @@ -1,40 +1,95 @@ /*! -@page api API +@page features Features -@section features_list New Features +@tableofcontents -TGS4 has a multitude of improvements over V3: +@section features_list New in V4 -- Non proprietary API (WCF -> HTTP) +- Agnostic HTTP API: The replaces the WCF service calls used in TGS3. This helps avoid Windows vendor lock-in and get away from the SOAP API that literally no one understood (not even me). With it, it's much easier to expose TGS to the internet, all you need is a HTTPS reverse proxy in front of it. A rundown of the new API exists here: https://tgstation.github.io/tgstation-server/api.html. +- Granular Access Controls: Windows users are no longer (required to be) the basis for authentication to the server. We now have database-backed users as a login option. These use a combined Basic/JWT authentication scheme with industry standard password hashing and salting. Users are fully customizable and can be given granular access to every bit of the server via the new permissions system. From changing the BYOND version, to test merging a PR, to restarting the server, every action may now be granted or revoked on a per user basis. + - Limitation: Users can be disabled but not deleted. +- Proper Long Running Operation Support: Server actions take a long time, from a git pull to a DreamMaker compile. TGS now internally allows for them to be run in parallel with each other and provides an audit record via the database. This is an improvement over the old system where connections had to be held open for the duration of operations. +- Database Backend: TGS requires an SQL database to operate. This allows for much better concurrency and is just overall much cleaner than the old single json file storage blob per instance. + - Limitation: There is a one-to-one relationship with a TGS server and a database. **DO NOT SHARE TGS DATABASES**. +- Linux/Docker Support: TGS4 is Linux and docker compatible. (Note this does not mean that rust-g and BSQL work out of the box, they must be compiled using event scripts like PreCompile.sh). + - Limitation: TGS4 has a dependency on the native library libgit2 which is known to cause issues on Linux. The binaries distributed with TGS are kept up to date with the upstream repository, but out of the box Linux support can't be assured in every environment. Docker is guaranteed to always work, however. See the repository for the distributed binary here: https://github.com/libgit2/libgit2sharp.nativebinaries. + - Limitation: System based logins are not supported on Linux. https://github.com/tgstation/tgstation-server/issues/709 +- Incredibly Detailed Logging: Various log levels exist now (Trace/Debug/Info/Warning/Error/Critical) and are sanely output to a rolling file on the host. Significant improvement over having to use the Windows event viewer with TGS3. Until such a point where bugs stop copping up I'd recommend Trace logging for the main log level. +- Historical Deployment Data: Every time code is compiled the following data is logged and stored. + - The User that initiated it. + - When it was started. + - When it finished. + - All revision information including local/remote SHAs, test merged pull requests and their SHAs. + - The BYOND version used. + - The DMAPI version in the binary +- Multiple chat bots per instance: Up to 65535 as a matter of fact (who knows why I chose that number?)! +- Automatic Chat Bot Reconnection Intervals: Set in minutes. +- Better Error State Handling: The Server and Watchdog aren't your momma's boys anymore. Every error state will be automatically resolved or reported with recommended actions. +- Watchdog Heartbeats: An interval in seconds can now be set at which TGS will send /world/Topic() packets to DreamDaemon. If four of these are missed, the server will be rebooted. No more endless @Key Holder pings in discord (and I can finally unmute the /tg/ guild)! This feature can be disabled. +- Better DMAPI: No longer requires injecting a .NET runtime .dll into the DreamDaemon process. DD -> TGS communication is now handled securely via BYOND's native /world/Export() API ("But Cyberboss, BYOND only supports GET requests." Who said anything about respecting HTTP standards when dealing with BYOND?). +- Safe/Ultrasafe Security Support: Thanks to the new DMAPI, the ultrasafe and safe security levels may be used without running into BYOND's limitations. But no one really cares... +- Self Upgrading: To upgrade TGS3 you needed to download and run the installer. This was pretty seamless, but it's now even better in V4 as the command to upgrade can be given straight to the API. At that point the server will handle downloading the update, detaching running DreamDaemon instances, restarting with the new version, and reattaching to them. Easier than ever patch delivery. +- *Gasp* TESTING: TGS4 currently has over 60% code coverage in automated unit and full stack integration tests. I aim to have that number ever increasing to prevent trivial mistakes. Big improvement over V3 which had... literally none... -Communication between client applications and TGS is now done over HTTP instead of WCF SOAP. In the past, attempts to create custom clients failed due to the complexity of the old API. The new, simple, json API should serve as a much needed improvement. +Along with these features, nearly every single V3 feature has been included and possibly improved in some fashion. This includes stuff like Windows accounts for logins, and using ACLs for static file handling. The following exceptions exist but are planned for future updates: +- Process memory/CPU diagnostic data is not generated: https://github.com/tgstation/tgstation-server/issues/611 +- Process dumps may not be created: https://github.com/tgstation/tgstation-server/issues/612 +- The DMAPI is required in DreamMaker code: https://github.com/tgstation/tgstation-server/issues/934 +- The option to "Initialize Game Directories" is no longer present, but a variant is still performed every deployment for smoother error handling. +- Direct server announcements are no longer present but may be readded upon request. -- Granular access controls +@section features_list Comprehensive Feature List -Almost every server action a client can take is now guarded by a robust permissions system. Coupled with built in user account management, this should provide an effective way to grant limited access to servers. - -- Proper long running operation support - -The client no longer has to wait literal minutes for a single request. Long running operations now create @ref Tgstation.Server.Api.Models.Job objects to track their progress and errors. - -- Concrete data backend - -The old save file system for instances is gone. All configuration data per instance is now stored in a relational database - -- Smarter repository handling - -The entire repository component is now much more effective in handling complex merges, automatic updates, and tracking git objects. - -- Linux support - -The framework used to create the server has been changed to dotnet 3.1. Because of this, we can now support linux hosting somewhat effectively. Note that seamless .dmb updates are still a Windows only feature for the time being. - -- Detailed logging - -We now actually have log files to reference which will greatly help with debugging. - -- OPTIONAL Windows FS permission integration - -No longer a requirement as in V3. While Windows logins are still supported for authentication and remote file manipulation (on Windows), remote file manipulation can now be done via the server's executing user. +tgstation-server is a BYOND server managment suite. It includes all the following features +- Standalone server with OpenAPI 3.0 defined HTTP REST API +- Secure user authentication, management, and permissions system +- Support for using Windows accounts as logins +- Long running operation support via the jobs subsystem +- Logging system with configurable levels of verbosity +- Able to self update with user input +- Instances: Managing multiple sets of the below features seperately on the same machine + - Git repository managment + - Cloning + - Checking out SHAs and references + - Local Merging + - Hard resetting to references + - Merging GitHub pull requests + - Deleting + - Pushing commits for GitHub visibility + - BYOND version management + - Downloading and installing a given BYOND version + - Includes DirectX installation on Windows and proper handling of POSIX shared libraries + - Supporting any amount of installed versions + - Cleaning the BYOND cache + - Code Deployment + - Compiles git code with DreamMaker and the active BYOND version + - Validates interop with the compiled binary + - Can be scheduled to pull the repository and build on a given interval + - The Watchdog, a DreamDaemon uptime monitor + - Automatically restarts the server when crashed until told to stop + - "Heartbeat" system for checking DreamDaemon isn't hung + - Automatic application of new deployments on /world/Reboot + - Automatic startup at server boot time + - Automatically handles Windows prompts related to trusted mode + - TGS restarts/updates do not interrupt the DreamDaemon process + - Chat System + - Support multiple chat bots per instance. Current providers + - Discord + - IRC + - Bots come out of the box with some basic commands like showing the server revision + - Support different chat channel types & tags for use in DM code + - Configuration system + - Allows specifying files/directories to be permanently symlinked with active game code + - Support for scripts that run on certain events. e.g. Before/after compiling + - Allows including arbitrary .dm code in compilations + - ACL support with Windows based logins + - DMAPI, DM code interop + - Provides metadata such as the current TGS version, git revision, active pull requests, security level + - Provides API for responding to TGS events (compile, update, etc) + - Provides API for sending chat bot messages + - Provides API for implementing chat bot commands in DM code + - Gives the ability to restart the DreamDaemon process from DM code + - Functions with all 3 DreamDaemon security levels + - Allows specifying the .dmb's minimum required security level */