Merge pull request #452 from tp-link-extender/main

Merge main into ledgertests

Author: Heliodex

Assets/schema.ts

@@ -12,21 +12,13 @@ export type Config = {
 	 */
 	Domain: string
 	/**
-	 * The URL of your database server.
+	 * The version of your revival's domain to use for insecure HTTP requests. This is necessary for a lot of requests that don't support HTTPS. It shouldn't be the same as Domain, as the insecure domain shouldn't be used by a user to access normal site pages.
 	 */
-	DatabaseURL: string
+	DomainInsecure: string
 	/**
 	 * The URL of your RCC proxy server. Requires a URL scheme.
 	 */
 	RCCServiceProxyURL: string
-	/**
-	 * The URL of your Orbiter gameserver hoster, exposing the private API for use by the Site. Requires a URL scheme.
-	 */
-	OrbiterPrivateURL: string
-	/**
-	 * The domain name of your Orbiter gameserver hoster, exposing the public API for use by a user's browser.
-	 */
-	OrbiterPublicDomain: string
 	/**
 	 * The URI scheme to pass to the launcher when joining a game.
 	 */
@@ -40,6 +32,44 @@ export type Config = {
 	 */
 	Pages: ("Statistics" | "Groups" | "Forum")[]
 
+	/**
+	 * Configuration for the database server, run with SurrealDB.
+	 */
+	Database: {
+		/**
+		 * Whether to automatically start the database server when starting Mercury Core. This requires the SurrealDB binary to be in your system's PATH as `surreal`.
+		 */
+		AutoStart: boolean
+		/**
+		 * The domain name of your database server. Make sure to include the port if necessary.
+		 */
+		Domain: string
+	}
+
+	/**
+	 * Configuration for the Economy service.
+	 */
+	Economy: {
+		/**
+		 * Whether to automatically start the Economy service when starting Mercury Core. It will attempt to build the Economy service from source with Go if the executable cannot be found.
+		 */
+		AutoStart: boolean
+	}
+
+	/**
+	 * Configuration for the Orbiter gameserver hoster.
+	 */
+	Orbiter: {
+		/**
+		 * The URL of your Orbiter gameserver hoster, exposing the private API for use by the Site. Requires a URL scheme.
+		 */
+		PrivateURL: string
+		/**
+		 * The URL of your Orbiter gameserver hoster, exposing the public API for use by a user's browser. Requires a URL scheme.
+		 */
+		PublicURL: string
+	}
+
 	/**
 	 * The default body colours for avatar creation, given to each new user on registration.
 	 *
@@ -199,6 +229,10 @@ export type Config = {
 		 * The SMTP server port to use for sending emails.
 		 */
 		Port: number
+		/**
+		 * Whether to use a secure connection (TLS) when connecting to the SMTP server. This should usually be true for port 465 and false for ports 587 and 25.
+		 */
+		Secure: boolean
 		/**
 		 * The username to use for authentication with the SMTP server. The corresponding password should be configured in your environment variables.
 		 */

Database/Dockerfile

@@ -1,3 +1,3 @@
-FROM surrealdb/surrealdb:v2.3.8
+FROM surrealdb/surrealdb:v3.0.1
 
 EXPOSE 8000

Docs/bun.lock

@@ -3,20 +3,20 @@
 	"type": "module",
 	"version": "0.0.1",
 	"scripts": {
-		"dev": "astro dev",
-		"start": "astro dev",
-		"build": "astro build",
-		"preview": "astro preview",
-		"astro": "astro"
+		"dev": "bun x -b astro dev",
+		"start": "bun x -b astro dev",
+		"build": "bun x -b astro build",
+		"preview": "bun x -b astro preview",
+		"astro": "bun x -b astro"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.3.11"
+		"@biomejs/biome": "^2.4.10"
 	},
 	"dependencies": {
-		"@astrojs/markdoc": "^0.15.10",
-		"@astrojs/starlight": "^0.37.2",
-		"@astrojs/starlight-markdoc": "^0.5.1",
-		"astro": "^5.16.9",
+		"@astrojs/markdoc": "^1.0.3",
+		"@astrojs/starlight": "^0.38.2",
+		"@astrojs/starlight-markdoc": "^0.6.0",
+		"astro": "^6.1.3",
 		"sharp": "^0.34.5"
 	}
 }

Docs/package.json

@@ -0,0 +1,26 @@
+---
+title: Revival platform types
+description: Comparison of 2 popular types of revival platforms, launcher-based and web-based.
+---
+
+Mercury Core is a foundation for building web-based revival platforms. These are platforms where services external to the Client, such as place launching and character customisation, are accessed via a hosted website. This is in contrast to launcher-based platforms, where a custom launcher application is used to join places and customise characters. This page provides an overview of the differences between these 2 types of platforms, and whether the web-based approach of Mercury Core is suitable for certain use cases.
+
+## Launchers
+
+Launchers are still necessary for both types of platforms, as they are used to launch the Client application, and in the case of a web-based platform, to interact with the site and download a Client. Conversely, a web-based platform is not necessarily required for a launcher-based platform, as the launcher could come pre-bundled with a Client and Studio, as well as possibly its own API server for interacting with the Client. However, sometimes these launchers have web API servers that are used for downloading Client updates and other features.
+
+The difference is mainly where the functionality is accessed from, the centralisation or decentralisation of service hosting & access, and the development & usage focus on either the website or the launcher. Both types of platforms have their own advantages and disadvantages, users may have strong preferences of one over another, and the choice between them depends on the specific use case, goals, and user base of the platform being developed.
+
+There do exist web-based platforms that do not need a separate launcher, most commonly by compiling 2016 Client source code to WebAssembly, allowing it to run in the browser. However, this approach is not very common, and has its own set of challenges and limitations. These include performance issues and modification requirements, with certain unsupported libraries needing to be substituted for compatible alternatives.
+
+## Distinction
+
+Generally, the distinction is broader than simply the type of application where the services are accessed from. Web-based platforms tend to host centralised features on the website alongside their main services, such as a marketplace & economy, features & communication, and discoverability, whereas launcher-based platforms typically have more decentralised place joining and local character customisation systems, allowing the user to choose for themselves where to connect to places and what accessories to use with their avatar.
+
+Launcher-based platforms also usually have a launcher more closely integrated with the Client and more often depend on users hosting their own places rather than using centralised dedicated hosting. However, this can mean that game discoverability suffers due to lack of place listings. Multiplayer experiences using launcher-based platforms generally revolve around external communication platforms to organise place hosting and joining. This also happens for small web-based platforms with few users hosting places at a time, though this tends to be less of an issue for larger web-based platforms with more users hosting places at a time, as they can display more active place listings and better discoverability.
+
+## Related experiments
+
+Previous Mercury experiments, including [Mercury Core for Launcher Revivals](https://github.com/tp-link-extender/MCLauncherRevivals), aimed to tackle the launcher platform server discoverability problem by hosting a decentralised list of active servers, for various different launchers, on the website. Anyone would be able to host their own version of the list and see the same servers, with an ability to rate servers and join currently active ones. However, this approach offered no further economy or social features, and is not actively being developed.
+
+[Reblox](https://github.com/Heliodex/Reblox) was one of several attempts at building a hybrid platform, with a single launcher, or multiple implementations of such, that could each connect to multiple different servers. Each server would have only hosted a standardised API for communicating with the launcher, and the launcher would have handled all interactions with the Client. Users would have been able to transfer their identity across multiple platforms, preventing inaccessibility of user accounts due to platform shutdowns. Places could have been hosted on any server, and have their discoverability across many servers. This approach would have offered more of the advantages of both types of platforms, also featuring plenty of social features, though at a much higher development cost than an approach like Mercury Core for Launcher Revivals due to lack of interoperability with existing launcher-based platforms. However, an implementation of an engaging marketplace or economic system would have been difficult or not possible, and the project is also not in development anymore.

Docs/src/content/docs/architecture/launchers.md

@@ -3,7 +3,9 @@ title: Technology stack
 description: Overview of the technology stack used in Mercury Core.
 ---
 
-Mercury's frontend is built with [Svelte](https://svelte.dev/), a UI framework that compiles to vanilla JS, and SvelteKit, a powerful full-stack framework for building transitional apps.
+The Mercury Core codebase is designed to be as modular, extensible, and as consistent as possible, and the stack is built with modern technologies and standards that are easy to work with.
+
+The main Site frontend is built with [Svelte](https://svelte.dev/), a UI framework that compiles to vanilla JS, and SvelteKit, a powerful full-stack framework for building transitional apps.
 
 The Site uses [Typescript](https://typescripts.org/) throughout, a language that adds type extensions ontop of Javascript. Intellisense and type checking are used as well, as they help to prevent bugs and improve understanding of the codebase.
 

Docs/src/content/docs/architecture/stack.md

@@ -0,0 +1,27 @@
+---
+title: Client TLS
+description: Information about when and why TLS & HTTPS are used for communicating with the Client and Studio.
+---
+
+Transport Layer Security (TLS) is a cryptographic protocol that provides secure communication over a network. It is commonly used to encrypt data transmitted between clients and servers, ensuring confidentiality and integrity of the data. In the modern web, TLS is used as a part of HTTPS, and is essential for protecting user data and allowing the user to verify the identity of the server they are communicating with.
+
+In the context of Mercury, it would be best to use TLS and HTTPS for all communication between the Site and the Client and Studio. However, this is often not possible due to technical limitations of the Client and Studio. Due to this, Mercury Core takes a flexible approach to allow TLS to be used as much as possible, while minimising risk of security issues when it cannot be used.
+
+## TLS versions
+
+A table of various TLS versions is provided below.
+
+Version | Year released | Status
+-- | -- | --
+1.0 | 1999 | Deprecated in 2021
+1.1 | 2006 | Deprecated in 2021
+1.2 | 2008 | Widely supported, no plans for deprecation
+1.3 | 2018 | Widely supported, latest version
+
+Later versions of TLS provide improved security and performance. The [Caddy](/install/caddy) web server used by Mercury Core does not support deprecated versions of TLS (as of Caddy 2, see Caddy issues [#2819](https://github.com/caddyserver/caddy/issues/2819) and [#3667](https://github.com/caddyserver/caddy/issues/3667) for more info). However, some older Clients may not support TLS 1.2 or later, so it may be necessary to introduce a different external proxy server or load balancer that supports older TLS versions if support for these Clients is desired.
+
+## Unencrypted subdomain
+
+By default, Mercury Core is configured to host the Site on the root domain (eg. `example.com`), which is always encrypted with HTTPS, and an unencrypted subdomain (eg. `www.example.com`) is used only for communication with the Client and Studio. This allows the Site to always be accessed securely by users through their web browsers, while still allowing systems that don't support TLS to communicate with the unencrypted subdomain.
+
+The unencrypted subdomain should never be used for Site access from a web browser. This is why a separate subdomain is the recommended approach. Under proper configuration of Mercury Core, any user attempting to access the Site through an unencrypted connection will not be able to submit any information in forms to minimise the risk of sensitive data being intercepted.

Docs/src/content/docs/design/client-tls.md

@@ -0,0 +1,20 @@
+---
+title: Mercury 3 & Mercury Core
+description: An overview on the relationship between Mercury 3 and Mercury Core.
+---
+
+Mercury 3 is a revival platform using a hosted version of Mercury Core as its source code. This page provides an overview of the relationship between Mercury 3 and Mercury Core.
+
+## Development of Mercury 2
+
+As explained in the [History](/history) page, the source code of Mercury 2 continued undergoing modification after it was shut down in June 2024, being released as Mercury Core in September 2024. As such, Mercury 2 is not considered to be based on Mercury Core.
+
+Mercury 2 changed a significant amount during its 2 years of development. Many core pieces of the codebase were modified or rewritten, services were changed, and libraries used (many of which were in beta or early development at the time) were updated or replaced. As such, while Mercury Core shows clear resemblance with Mercury 2[^1] in 2024, the resemblance with a version of Mercury 2 from 2022 or 2023 is less clear. 
+
+## Development of Mercury 3
+
+The development process of Mercury 3 has been very different to that of Mercury 2. Originally, Mercury 3 was planned to be a fork of Mercury Core with improvements being backported to Mercury Core when possible. However, an alternative development process was found to be easier and chosen instead, where Mercury 3 is simply a hosted version of Mercury Core with no modifications. If you are interested more in the revival platform than the source code, Mercury Core can be seen as the "testing ground" for Mercury 3. If you are interested more in the source code than the revival platform, Mercury 3 can be seen as the "testing ground" for Mercury Core. Different Mercury 3 developers see the relationship differently.
+
+The existence and testing of Mercury 3 helps with the development of Mercury Core, as it allows for testing of new features and changes in a real-world environment. Before Mercury 3, Mercury Core was only tested in development environments, which were not as effective at finding bugs and issues as a production environment would be.
+
+[^1]: These changes can be viewed in full, with code change history throughout the entirety of Mercury 2, in Mercury Core's [commit history](https://github.com/tp-link-extender/MercuryCore/commits/).

Docs/src/content/docs/design/mercury3.md

@@ -0,0 +1,76 @@
+---
+title: Configuration guide
+description: Guidance on modifying the configuration file for Mercury Core.
+---
+
+This guide provides information on the configuration file for Mercury Core, located at the root of the repository as [**mercury.core.ts**](https://github.com/tp-link-extender/MercuryCore/blob/main/mercury.core.ts). If the file is open in an editor with a Typescript language server, then each property can be hovered over to give a description of its purpose and usage, as well as the expected type of value that it should be set to.
+
+{% aside title="Source code modification" %}
+	While the configuration file aims to give control over as many options as possible in a pragmatic manner, the most effective way to tweak Mercury Core and other components of the Mercury suite will always be to modify their source code directly.
+{% /aside %}
+
+Properties are grouped in ways that are intended to be intuitive, though other than this there are no strict rules on how they are organised. These groups, the names of the properties, and their default values, are all subject to change, and may be rearranged, renamed, or removed in future updates. The order of properties listed here is in accordance with how they appear in the reference configuration file, though they can be rearranged in any way as required.
+
+## Properties
+
+### Top-level
+
+#### Name
+
+This is the name of the project, used across the codebase wherever the project name needs to be referenced: in headers and footers, titles of pages, descriptions on pages, and so on.
+
+#### Domain
+
+The domain that the Site will be primarily hosted from, without the URL scheme. For example, if the Site is hosted at `https://example.com`, then this should be set to `example.com`. This is used in various places across the codebase where the domain needs to be referenced, including in constructing Client scripts & emails and substituting parts of existing URLs in XML-based assets.
+
+#### DomainInsecure
+
+The domain that the Site will be hosted on when accessed insecurely, without the URL scheme. This is used for requests that do not or cannot support HTTPS. By default, this is the Domain property with a `www.` subdomain added.
+
+This domain should not be used to access the Site. More information is given in the [Client TLS](/design/client-tls) section of the documentation.
+
+#### RCCServiceProxyURL
+
+The URL of the RCCService proxy server, including an appropriate scheme. This is used when requesting any rendering operations from RCC. See the [RCCService](/services/rcc/#proxying) section for more information on proxying.
+
+#### OrbiterPrivateURL
+
+The URL of the Orbiter gameserver hoster, exposing the private API for use by the Site and other trusted components, used for starting and managing gameservers.
+
+#### OrbiterPublicURL
+
+The URL of the Orbiter gameserver hoster, exposing the public API for use by a user's browser, used for fetching server lists and joining gameservers, and also for gameserver hosting.
+
+By default this is automatically served with HTTP in development and HTTPS in production, so make sure to use the correct scheme and port if this is set to a custom URL. These are necessary for the information API to be accessible from the browser, though they are both stripped out when used for constructing the URI scheme for joining gameservers.
+
+#### LauncherURI
+
+The URI scheme to start the correct Launcher when joining a game. This is used for constructing the URI that is opened when a user clicks the "Join" button for a game. It's recommended to set this to "{name}-launcher", where {name} is a lowercased version of the Name property, as this is consistent with how the [Mercury Launcher](https://github.com/tp-link-extender/MercuryLauncher) works.
+
+#### CurrencySymbol
+
+The symbol to use when displaying currency values across the site. This is used on pages such as the Catalog, Asset, Economy, Admin Transactions, etc. At the moment, the symbol appears before the quantity.
+
+#### Pages
+
+An array that contains the optional pages for the site, with a string value for each name: Statistics, Groups, and Forum. If a page is removed from this array, it will not be accessible on the site, returning a 404 Not Found error, and any links to it will be removed from the UI.
+
+### Database
+
+#### Database – AutoStart
+
+Whether to automatically start the database server when starting the Site. Requires that [SurrealDB](/install/surrealdb) is installed and available on the command line or in your system's PATH as `surreal`.
+
+This is recommended to be enabled in all cases except when debugging database issues, or when managing the database server separately from the Site, such as when using a container manager.
+
+#### Database – Domain
+
+The domain name of the database server, without the URL scheme. This is used when setting up the Site's database connection. This domain is not accessed securely by default, so it's recommended to keep it on a local network or on the same machine as the Site. Make sure to include the port if necessary.
+
+### Economy
+
+#### Economy – AutoStart
+
+Whether to automatically start the Economy service when starting the Site. This is recommended to be enabled in all cases except when debugging Economy service issues, or when managing the Economy service separately from the Site, such as when using a container manager.
+
+### todo