Automatic TGS DMAPI Update (tgstation#85751)

This pull request updates the TGS DMAPI to the latest version. Please
note any changes that may be breaking or unimplemented in your codebase
by checking what changes are in the definitions file:
code/__DEFINES/tgs.dm before merging.

Full changelog can be found
[here](https://raw.githubusercontent.com/tgstation/tgstation-server/gh-pages/changelog.yml).

- Added consumer APIs for overriding HTTP GET implementation.
(tgstation/tgstation-server#1853 @Cyberboss)
- Fixed Discord documentation links.
(tgstation/tgstation-server#1853 @Cyberboss)
- Use IETF RFC 2119 wording in documentation.
(tgstation/tgstation-server#1853 @Cyberboss)
- Populate some documentation comments for previously undocumented
public entities.
(tgstation/tgstation-server#1853 @Cyberboss)
#tgs-dmapi-release

Co-authored-by: tgstation-server-ci[bot] <161980869+tgstation-server-ci[bot]@users.noreply.github.com>

code/__DEFINES/tgs.dm

@@ -1,18 +1,19 @@
 // tgstation-server DMAPI
+// The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF RFC 2119.
 
-#define TGS_DMAPI_VERSION "7.1.3"
+#define TGS_DMAPI_VERSION "7.2.1"
 
 // All functions and datums outside this document are subject to change with any version and should not be relied on.
 
 // CONFIGURATION
 
-/// Create this define if you want to do TGS configuration outside of this file.
+/// Consumers SHOULD create this define if you want to do TGS configuration outside of this file.
 #ifndef TGS_EXTERNAL_CONFIGURATION
 
-// Comment this out once you've filled in the below.
+// Consumers MUST comment this out once you've filled in the below and are not using [TGS_EXTERNAL_CONFIGURATION].
 #error TGS API unconfigured
 
-// Uncomment this if you wish to allow the game to interact with TGS 3..
+// Consumers MUST uncomment this if you wish to allow the game to interact with TGS version 3.
 // This will raise the minimum required security level of your game to TGS_SECURITY_TRUSTED due to it utilizing call()().
 //#define TGS_V3_API
 
@@ -52,7 +53,7 @@
 
 #ifndef TGS_FILE2TEXT_NATIVE
 #ifdef file2text
-#error Your codebase is re-defining the BYOND proc file2text. The DMAPI requires the native version to read the result of world.Export(). You can fix this by adding "#define TGS_FILE2TEXT_NATIVE file2text" before your override of file2text to allow the DMAPI to use the native version. This will only be used for world.Export(), not regular file accesses
+#error Your codebase is re-defining the BYOND proc file2text. The DMAPI requires the native version to read the result of world.Export(). You SHOULD fix this by adding "#define TGS_FILE2TEXT_NATIVE file2text" before your override of file2text to allow the DMAPI to use the native version. This will only be used for world.Export(), not regular file accesses
 #endif
 #define TGS_FILE2TEXT_NATIVE file2text
 #endif
@@ -152,16 +153,17 @@
 //REQUIRED HOOKS
 
 /**
- * Call this somewhere in [/world/proc/New] that is always run. This function may sleep!
+ * Consumers MUST call this somewhere in [/world/proc/New] that is always run. This function may sleep!
  *
  * * event_handler - Optional user defined [/datum/tgs_event_handler].
  * * minimum_required_security_level: The minimum required security level to run the game in which the DMAPI is integrated. Can be one of [TGS_SECURITY_ULTRASAFE], [TGS_SECURITY_SAFE], or [TGS_SECURITY_TRUSTED].
+ * * http_handler - Optional user defined [/datum/tgs_http_handler].
  */
-/world/proc/TgsNew(datum/tgs_event_handler/event_handler, minimum_required_security_level = TGS_SECURITY_ULTRASAFE)
+/world/proc/TgsNew(datum/tgs_event_handler/event_handler, minimum_required_security_level = TGS_SECURITY_ULTRASAFE, datum/tgs_http_handler/http_handler)
 	return
 
 /**
- * Call this when your initializations are complete and your game is ready to play before any player interactions happen.
+ * Consumers MUST call this when world initializations are complete and the game is ready to play before any player interactions happen.
  *
  * This may use [/world/var/sleep_offline] to make this happen so ensure no changes are made to it while this call is running.
  * Afterwards, consider explicitly setting it to what you want to avoid this BYOND bug: http://www.byond.com/forum/post/2575184
@@ -170,12 +172,10 @@
 /world/proc/TgsInitializationComplete()
 	return
 
-/// Put this at the start of [/world/proc/Topic].
+/// Consumers MUST run this macro at the start of [/world/proc/Topic].
 #define TGS_TOPIC var/tgs_topic_return = TgsTopic(args[1]); if(tgs_topic_return) return tgs_topic_return
 
-/**
- * Call this as late as possible in [world/proc/Reboot] (BEFORE ..()).
- */
+/// Consumers MUST call this as late as possible in [world/proc/Reboot] (BEFORE ..()).
 /world/proc/TgsReboot()
 	return
 
@@ -269,7 +269,7 @@
 	/// The [/datum/tgs_chat_channel] the user was from.
 	var/datum/tgs_chat_channel/channel
 
-/// User definable handler for TGS events.
+/// User definable handler for TGS events This abstract version SHOULD be overridden to be used.
 /datum/tgs_event_handler
 	/// If the handler receieves [TGS_EVENT_HEALTH_CHECK] events.
 	var/receive_health_checks = FALSE
@@ -283,7 +283,41 @@
 	set waitfor = FALSE
 	return
 
-/// User definable chat command.
+/// User definable handler for HTTP calls. This abstract version MUST be overridden to be used.
+/datum/tgs_http_handler
+
+/**
+ * User definable callback for executing HTTP GET requests.
+ * MUST perform BYOND sleeps while the request is in flight.
+ * MUST return a [/datum/tgs_http_result].
+ * SHOULD log its own errors
+ *
+ * url - The full URL to execute the GET request for including query parameters.
+ */
+/datum/tgs_http_handler/proc/PerformGet(url)
+	CRASH("[type]/PerformGet not implemented!")
+
+/// Result of a [/datum/tgs_http_handler] call. MUST NOT be overridden.
+/datum/tgs_http_result
+	/// HTTP response as text
+	var/response_text
+	/// Boolean request success flag. Set for any 2XX response code.
+	var/success
+
+/**
+ * Create a [/datum/tgs_http_result].
+ *
+ * * response_text - HTTP response as text. Must be provided in New().
+ * * success - Boolean request success flag. Set for any 2XX response code. Must be provided in New().
+ */
+/datum/tgs_http_result/New(response_text, success)
+	if(response_text && !istext(response_text))
+		CRASH("response_text was not text!")
+
+	src.response_text = response_text
+	src.success = success
+
+/// User definable chat command. This abstract version MUST be overridden to be used.
 /datum/tgs_chat_command
 	/// The string to trigger this command on a chat bot. e.g `@bot name ...` or `!tgs name ...`.
 	var/name = ""
@@ -296,21 +330,27 @@
 
 /**
  * Process command activation. Should return a [/datum/tgs_message_content] to respond to the issuer with.
+ * MUST be implemented
  *
- * sender - The [/datum/tgs_chat_user] who issued the command.
- * params - The trimmed string following the command `/datum/tgs_chat_command/var/name].
+ * * sender - The [/datum/tgs_chat_user] who issued the command.
+ * * params - The trimmed string following the command `/datum/tgs_chat_command/var/name].
  */
 /datum/tgs_chat_command/proc/Run(datum/tgs_chat_user/sender, params)
 	CRASH("[type] has no implementation for Run()")
 
-/// User definable chat message.
+/// User definable chat message. MUST NOT be overridden.
 /datum/tgs_message_content
-	/// The tring content of the message. Must be provided in New().
+	/// The string content of the message. Must be provided in New().
 	var/text
 
 	/// The [/datum/tgs_chat_embed] to embed in the message. Not supported on all chat providers.
 	var/datum/tgs_chat_embed/structure/embed
 
+/**
+ * Create a [/datum/tgs_message_content].
+ *
+ * * text - The string content of the message.
+ */
 /datum/tgs_message_content/New(text)
 	..()
 	if(!istext(text))
@@ -319,7 +359,7 @@
 
 	src.text = text
 
-/// User definable chat embed. Currently mirrors Discord chat embeds. See https://discord.com/developers/docs/resources/channel#embed-object-embed-structure for details.
+/// User definable chat embed. Currently mirrors Discord chat embeds. See https://discord.com/developers/docs/resources/message#embed-object for details.
 /datum/tgs_chat_embed/structure
 	var/title
 	var/description
@@ -331,13 +371,13 @@
 	/// Colour must be #AARRGGBB or #RRGGBB hex string.
 	var/colour
 
-	/// See https://discord.com/developers/docs/resources/channel#embed-object-embed-image-structure for details.
+	/// See https://discord.com/developers/docs/resources/message#embed-object-embed-image-structure for details.
 	var/datum/tgs_chat_embed/media/image
 
-	/// See https://discord.com/developers/docs/resources/channel#embed-object-embed-thumbnail-structure for details.
+	/// See https://discord.com/developers/docs/resources/message#embed-object-embed-thumbnail-structure for details.
 	var/datum/tgs_chat_embed/media/thumbnail
 
-	/// See https://discord.com/developers/docs/resources/channel#embed-object-embed-image-structure for details.
+	/// See https://discord.com/developers/docs/resources/message#embed-object-embed-video-structure for details.
 	var/datum/tgs_chat_embed/media/video
 
 	var/datum/tgs_chat_embed/footer/footer
@@ -346,58 +386,64 @@
 
 	var/list/datum/tgs_chat_embed/field/fields
 
-/// Common datum for similar discord embed medias.
+/// Common datum for similar Discord embed medias.
 /datum/tgs_chat_embed/media
 	/// Must be set in New().
 	var/url
 	var/width
 	var/height
 	var/proxy_url
 
+/// Create a [/datum/tgs_chat_embed].
 /datum/tgs_chat_embed/media/New(url)
 	..()
 	if(!istext(url))
 		CRASH("[/datum/tgs_chat_embed/media] created with no url!")
 
 	src.url = url
 
-/// See https://discord.com/developers/docs/resources/channel#embed-object-embed-footer-structure for details.
+/// See https://discord.com/developers/docs/resources/message#embed-object-embed-footer-structure for details.
 /datum/tgs_chat_embed/footer
 	/// Must be set in New().
 	var/text
 	var/icon_url
 	var/proxy_icon_url
 
+/// Create a [/datum/tgs_chat_embed/footer].
 /datum/tgs_chat_embed/footer/New(text)
 	..()
 	if(!istext(text))
 		CRASH("[/datum/tgs_chat_embed/footer] created with no text!")
 
 	src.text = text
 
-/// See https://discord.com/developers/docs/resources/channel#embed-object-embed-provider-structure for details.
+/// See https://discord.com/developers/docs/resources/message#embed-object-embed-provider-structure for details.
 /datum/tgs_chat_embed/provider
 	var/name
 	var/url
 
-/// See https://discord.com/developers/docs/resources/channel#embed-object-embed-author-structure for details. Must have name set in New().
+/// See https://discord.com/developers/docs/resources/message#embed-object-embed-author-structure for details. Must have name set in New().
 /datum/tgs_chat_embed/provider/author
 	var/icon_url
 	var/proxy_icon_url
 
+/// Create a [/datum/tgs_chat_embed/footer].
 /datum/tgs_chat_embed/provider/author/New(name)
 	..()
 	if(!istext(name))
 		CRASH("[/datum/tgs_chat_embed/provider/author] created with no name!")
 
 	src.name = name
 
-/// See https://discord.com/developers/docs/resources/channel#embed-object-embed-field-structure for details. Must have name and value set in New().
+/// See https://discord.com/developers/docs/resources/message#embed-object-embed-field-structure for details.
 /datum/tgs_chat_embed/field
+	/// Must be set in New().
 	var/name
+	/// Must be set in New().
 	var/value
 	var/is_inline
 
+/// Create a [/datum/tgs_chat_embed/field].
 /datum/tgs_chat_embed/field/New(name, value)
 	..()
 	if(!istext(name))

code/modules/tgs/core/README.md

@@ -3,7 +3,7 @@
 This folder contains all DMAPI code not directly involved in an API.
 
 - [_definitions.dm](./definitions.dm) contains defines needed across DMAPI internals.
+- [byond_world_export.dm](./byond_world_export.dm) contains the default `/datum/tgs_http_handler` implementation which uses `world.Export()`.
 - [core.dm](./core.dm) contains the implementations of the `/world/proc/TgsXXX()` procs. Many map directly to the `/datum/tgs_api` functions. It also contains the /datum selection and setup code.
 - [datum.dm](./datum.dm) contains the `/datum/tgs_api` declarations that all APIs must implement.
 - [tgs_version.dm](./tgs_version.dm) contains the `/datum/tgs_version` definition
-- 

code/modules/tgs/core/byond_world_export.dm

@@ -0,0 +1,22 @@
+/datum/tgs_http_handler/byond_world_export
+
+/datum/tgs_http_handler/byond_world_export/PerformGet(url)
+	// This is an infinite sleep until we get a response
+	var/export_response = world.Export(url)
+	TGS_DEBUG_LOG("byond_world_export: Export complete")
+
+	if(!export_response)
+		TGS_ERROR_LOG("byond_world_export: Failed request: [url]")
+		return new /datum/tgs_http_result(null, FALSE)
+
+	var/content = export_response["CONTENT"]
+	if(!content)
+		TGS_ERROR_LOG("byond_world_export: Failed request, missing content!")
+		return new /datum/tgs_http_result(null, FALSE)
+
+	var/response_json = TGS_FILE2TEXT_NATIVE(content)
+	if(!response_json)
+		TGS_ERROR_LOG("byond_world_export: Failed request, failed to load content!")
+		return new /datum/tgs_http_result(null, FALSE)
+
+	return new /datum/tgs_http_result(response_json, TRUE)

code/modules/tgs/core/core.dm

@@ -1,4 +1,4 @@
-/world/TgsNew(datum/tgs_event_handler/event_handler, minimum_required_security_level = TGS_SECURITY_ULTRASAFE)
+/world/TgsNew(datum/tgs_event_handler/event_handler, minimum_required_security_level = TGS_SECURITY_ULTRASAFE, datum/tgs_http_handler/http_handler = null)
 	var/current_api = TGS_READ_GLOBAL(tgs)
 	if(current_api)
 		TGS_ERROR_LOG("API datum already set (\ref[current_api] ([current_api]))! Was TgsNew() called more than once?")
@@ -55,7 +55,10 @@
 		TGS_ERROR_LOG("Invalid parameter for event_handler: [event_handler]")
 		event_handler = null
 
-	var/datum/tgs_api/new_api = new api_datum(event_handler, version)
+	if(!http_handler)
+		http_handler = new /datum/tgs_http_handler/byond_world_export
+
+	var/datum/tgs_api/new_api = new api_datum(event_handler, version, http_handler)
 
 	TGS_WRITE_GLOBAL(tgs, new_api)
 

code/modules/tgs/core/datum.dm

@@ -6,7 +6,7 @@ TGS_DEFINE_AND_SET_GLOBAL(tgs, null)
 
 	var/list/warned_deprecated_command_runs
 
-/datum/tgs_api/New(datum/tgs_event_handler/event_handler, datum/tgs_version/version)
+/datum/tgs_api/New(datum/tgs_event_handler/event_handler, datum/tgs_version/version, datum/tgs_http_handler/http_handler)
 	..()
 	src.event_handler = event_handler
 	src.version = version

code/modules/tgs/includes.dm

@@ -1,4 +1,5 @@
 #include "core\_definitions.dm"
+#include "core\byond_world_export.dm"
 #include "core\core.dm"
 #include "core\datum.dm"
 #include "core\tgs_version.dm"

code/modules/tgs/v5/api.dm

@@ -31,9 +31,12 @@
 
 	var/detached = FALSE
 
-/datum/tgs_api/v5/New()
+	var/datum/tgs_http_handler/http_handler
+
+/datum/tgs_api/v5/New(datum/tgs_event_handler/event_handler, datum/tgs_version/version, datum/tgs_http_handler/http_handler)
 	. = ..()
 	interop_version = version
+	src.http_handler = http_handler
 	TGS_DEBUG_LOG("V5 API created: [json_encode(args)]")
 
 /datum/tgs_api/v5/ApiVersion()

code/modules/tgs/v5/bridge.dm

@@ -78,27 +78,24 @@
 	WaitForReattach(FALSE)
 
 	TGS_DEBUG_LOG("Bridge request start")
-	// This is an infinite sleep until we get a response
-	var/export_response = world.Export(bridge_request)
+	var/datum/tgs_http_result/result = http_handler.PerformGet(bridge_request)
 	TGS_DEBUG_LOG("Bridge request complete")
 
-	if(!export_response)
-		TGS_ERROR_LOG("Failed bridge request: [bridge_request]")
+	if(isnull(result))
+		TGS_ERROR_LOG("Failed bridge request, handler returned null!")
 		return
 
-	var/content = export_response["CONTENT"]
-	if(!content)
-		TGS_ERROR_LOG("Failed bridge request, missing content!")
+	if(!istype(result) || result.type != /datum/tgs_http_result)
+		TGS_ERROR_LOG("Failed bridge request, handler returned non-[/datum/tgs_http_result]!")
 		return
 
-	var/response_json = TGS_FILE2TEXT_NATIVE(content)
-	if(!response_json)
-		TGS_ERROR_LOG("Failed bridge request, failed to load content!")
+	if(!result.success)
+		TGS_DEBUG_LOG("Failed bridge request, HTTP request failed!")
 		return
 
-	var/list/bridge_response = json_decode(response_json)
+	var/list/bridge_response = json_decode(result.response_text)
 	if(!bridge_response)
-		TGS_ERROR_LOG("Failed bridge request, bad json: [response_json]")
+		TGS_ERROR_LOG("Failed bridge request, bad json: [result.response_text]")
 		return
 
 	var/error = bridge_response[DMAPI5_RESPONSE_ERROR_MESSAGE]