From 7c90e6318e22313fb1cb00bb5d0f63c40d07950e Mon Sep 17 00:00:00 2001
From: Aeris Bennet <156572979+vgcataeris@users.noreply.github.com>
Date: Sat, 24 Feb 2024 16:23:25 +0000
Subject: [PATCH] Updating and bumping DMAPI version. Some new stuff being
 around.

---
 code/__DEFINES/tgs.dm                    | 19 +++++++++++-
 code/modules/tgs/LICENSE                 | 24 +++++++++++++++
 code/modules/tgs/README.md               | 13 ++++++++
 code/modules/tgs/core/README.md          |  9 ++++++
 code/modules/tgs/core/core.dm            |  8 +++++
 code/modules/tgs/core/datum.dm           |  5 +++-
 code/modules/tgs/v4/README.md            |  6 ++++
 code/modules/tgs/v4/api.dm               |  6 ++--
 code/modules/tgs/v5/README.md            | 13 ++++++++
 code/modules/tgs/v5/__interop_version.dm |  2 +-
 code/modules/tgs/v5/_defines.dm          |  9 ++++++
 code/modules/tgs/v5/api.dm               | 38 +++++++++++++++++++++++-
 code/modules/tgs/v5/bridge.dm            |  7 +++--
 code/modules/tgs/v5/topic.dm             | 12 ++++++++
 code/modules/tgs/v5/undefs.dm            |  9 ++++++
 15 files changed, 171 insertions(+), 9 deletions(-)
 create mode 100644 code/modules/tgs/LICENSE
 create mode 100644 code/modules/tgs/README.md
 create mode 100644 code/modules/tgs/core/README.md
 create mode 100644 code/modules/tgs/v4/README.md
 create mode 100644 code/modules/tgs/v5/README.md

diff --git a/code/__DEFINES/tgs.dm b/code/__DEFINES/tgs.dm
index bdd66a28..c41f7479 100644
--- a/code/__DEFINES/tgs.dm
+++ b/code/__DEFINES/tgs.dm
@@ -1,6 +1,6 @@
 // tgstation-server DMAPI
 
-#define TGS_DMAPI_VERSION "7.0.2"
+#define TGS_DMAPI_VERSION "7.1.0"
 
 // All functions and datums outside this document are subject to change with any version and should not be relied on.
 
@@ -50,6 +50,13 @@
 
 #endif
 
+#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
+#endif
+#define TGS_FILE2TEXT_NATIVE file2text
+#endif
+
 // EVENT CODES
 
 /// Before a reboot mode change, extras parameters are the current and new reboot mode enums.
@@ -489,6 +496,16 @@
 /// Returns a list of connected [/datum/tgs_chat_channel]s if TGS is present, null otherwise. This function may sleep if the call to [/world/proc/TgsNew] is sleeping!
 /world/proc/TgsChatChannelInfo()
 	return
+	
+/**
+ * Trigger an event in TGS. Requires TGS version >= 6.3.0. Returns [TRUE] if the event was triggered successfully, [FALSE] otherwise. This function may sleep!
+ *
+ * event_name - The name of the event to trigger
+ * parameters - Optional list of string parameters to pass as arguments to the event script. The first parameter passed to a script will always be the running game's directory followed by these parameters.
+ * wait_for_completion - If set, this function will not return until the event has run to completion.
+ */
+/world/proc/TgsTriggerEvent(event_name, list/parameters, wait_for_completion = FALSE)
+	return
 
 /*
 The MIT License
diff --git a/code/modules/tgs/LICENSE b/code/modules/tgs/LICENSE
new file mode 100644
index 00000000..2bedf9a6
--- /dev/null
+++ b/code/modules/tgs/LICENSE
@@ -0,0 +1,24 @@
+The MIT License
+
+Copyright (c) 2017-2023 Jordan Brown
+
+Permission is hereby granted, free of charge,
+to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to
+deal in the Software without restriction, including
+without limitation the rights to use, copy, modify,
+merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom
+the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
+ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/code/modules/tgs/README.md b/code/modules/tgs/README.md
new file mode 100644
index 00000000..6319028d
--- /dev/null
+++ b/code/modules/tgs/README.md
@@ -0,0 +1,13 @@
+# DMAPI Internals
+
+This folder should be placed on it's own inside a codebase that wishes to use the TGS DMAPI. Warranty void if modified.
+
+- [includes.dm](./includes.dm) is the file that should be included by DM code, it handles including the rest.
+- The [core](./core) folder includes all code not directly part of any API version.
+- The other versioned folders contain code for the different DMAPI versions.
+    - [v3210](./v3210) contains the final TGS3 API.
+    - [v4](./v4) is the legacy DMAPI 4 (Used in TGS 4.0.X versions).
+    - [v5](./v5) is the current DMAPI version used by TGS >=4.1.
+- [LICENSE](./LICENSE) is the MIT license for the DMAPI.
+
+APIs communicate with TGS in two ways. All versions implement TGS -> DM communication using /world/Topic. DM -> TGS communication, called the bridge method, is different for each version.
diff --git a/code/modules/tgs/core/README.md b/code/modules/tgs/core/README.md
new file mode 100644
index 00000000..b82d8f49
--- /dev/null
+++ b/code/modules/tgs/core/README.md
@@ -0,0 +1,9 @@
+# Core DMAPI functions
+
+This folder contains all DMAPI code not directly involved in an API.
+
+- [_definitions.dm](./definitions.dm) contains defines needed across DMAPI internals.
+- [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
+- 
diff --git a/code/modules/tgs/core/core.dm b/code/modules/tgs/core/core.dm
index b5029c57..ea24515f 100644
--- a/code/modules/tgs/core/core.dm
+++ b/code/modules/tgs/core/core.dm
@@ -166,3 +166,11 @@
 	var/datum/tgs_api/api = TGS_READ_GLOBAL(tgs)
 	if(api)
 		return api.Visibility()
+
+/world/TgsTriggerEvent(event_name, list/parameters, wait_for_completion = FALSE)
+	var/datum/tgs_api/api = TGS_READ_GLOBAL(tgs)
+	if(api)
+		if(!istype(parameters, /list))
+			parameters = list()
+
+		return api.TriggerEvent(event_name, parameters, wait_for_completion)
diff --git a/code/modules/tgs/core/datum.dm b/code/modules/tgs/core/datum.dm
index d2c7a6d3..93a27b16 100644
--- a/code/modules/tgs/core/datum.dm
+++ b/code/modules/tgs/core/datum.dm
@@ -17,7 +17,7 @@ TGS_DEFINE_AND_SET_GLOBAL(tgs, null)
 		world.sleep_offline = FALSE // https://www.byond.com/forum/post/2894866
 		del(world)
 		world.sleep_offline = FALSE // just in case, this is BYOND after all...
-		sleep(1)
+		sleep(world.tick_lag)
 		TGS_DEBUG_LOG("BYOND DIDN'T TERMINATE THE WORLD!!! TICK IS: [world.time], sleep_offline: [world.sleep_offline]")
 
 /datum/tgs_api/latest
@@ -69,3 +69,6 @@ TGS_PROTECT_DATUM(/datum/tgs_api)
 
 /datum/tgs_api/proc/Visibility()
 	return TGS_UNIMPLEMENTED
+
+/datum/tgs_api/proc/TriggerEvent(event_name, list/parameters, wait_for_completion)
+	return FALSE
diff --git a/code/modules/tgs/v4/README.md b/code/modules/tgs/v4/README.md
new file mode 100644
index 00000000..78191447
--- /dev/null
+++ b/code/modules/tgs/v4/README.md
@@ -0,0 +1,6 @@
+# DMAPI V4
+
+This DMAPI implements bridge requests using file output which TGS monitors for. It has a safe mode restriction.
+
+- [api.dm](./api.dm) contains the bulk of the API code.
+- [commands.dm](./commands.dm) contains functions relating to `/datum/tgs_chat_command`s.
diff --git a/code/modules/tgs/v4/api.dm b/code/modules/tgs/v4/api.dm
index 6dbb9a7d..39e7e1ae 100644
--- a/code/modules/tgs/v4/api.dm
+++ b/code/modules/tgs/v4/api.dm
@@ -181,7 +181,7 @@
 	var/json = json_encode(data)
 
 	while(requesting_new_port && !override_requesting_new_port)
-		sleep(1)
+		sleep(world.tick_lag)
 
 	//we need some port open at this point to facilitate return communication
 	if(!world.port)
@@ -209,7 +209,7 @@
 		requesting_new_port = FALSE
 
 	while(export_lock)
-		sleep(1)
+		sleep(world.tick_lag)
 	export_lock = TRUE
 
 	last_interop_response = null
@@ -217,7 +217,7 @@
 	text2file(json, server_commands_json_path)
 
 	for(var/I = 0; I < EXPORT_TIMEOUT_DS && !last_interop_response; ++I)
-		sleep(1)
+		sleep(world.tick_lag)
 
 	if(!last_interop_response)
 		TGS_ERROR_LOG("Failed to get export result for: [json]")
diff --git a/code/modules/tgs/v5/README.md b/code/modules/tgs/v5/README.md
new file mode 100644
index 00000000..a8a0c748
--- /dev/null
+++ b/code/modules/tgs/v5/README.md
@@ -0,0 +1,13 @@
+# DMAPI V5
+
+This DMAPI implements bridge requests using HTTP GET requests to TGS. It has no security restrictions.
+
+- [__interop_version.dm](./__interop_version.dm) contains the version of the API used between the DMAPI and TGS.
+- [_defines.dm](./_defines.dm) contains constant definitions.
+- [api.dm](./api.dm) contains the bulk of the API code.
+- [bridge.dm](./bridge.dm) contains functions related to making bridge requests.
+- [chunking.dm](./chunking.dm) contains common function for splitting large raw data sets into chunks BYOND can natively process.
+- [commands.dm](./commands.dm) contains functions relating to `/datum/tgs_chat_command`s.
+- [serializers.dm](./serializers.dm) contains function to help convert interop `/datum`s into a JSON encodable `list()` format.
+- [topic.dm](./topic.dm) contains functions related to processing topic requests.
+- [undefs.dm](./undefs.dm) Undoes the work of `_defines.dm`.
diff --git a/code/modules/tgs/v5/__interop_version.dm b/code/modules/tgs/v5/__interop_version.dm
index cafe74bb..7f662328 100644
--- a/code/modules/tgs/v5/__interop_version.dm
+++ b/code/modules/tgs/v5/__interop_version.dm
@@ -1 +1 @@
-"5.8.0"
+"5.9.0"
diff --git a/code/modules/tgs/v5/_defines.dm b/code/modules/tgs/v5/_defines.dm
index de8b1389..54967220 100644
--- a/code/modules/tgs/v5/_defines.dm
+++ b/code/modules/tgs/v5/_defines.dm
@@ -14,6 +14,7 @@
 #define DMAPI5_BRIDGE_COMMAND_KILL 4
 #define DMAPI5_BRIDGE_COMMAND_CHAT_SEND 5
 #define DMAPI5_BRIDGE_COMMAND_CHUNK 6
+#define DMAPI5_BRIDGE_COMMAND_EVENT 7
 
 #define DMAPI5_PARAMETER_ACCESS_IDENTIFIER "accessIdentifier"
 #define DMAPI5_PARAMETER_CUSTOM_COMMANDS "customCommands"
@@ -34,6 +35,7 @@
 #define DMAPI5_BRIDGE_PARAMETER_VERSION "version"
 #define DMAPI5_BRIDGE_PARAMETER_CHAT_MESSAGE "chatMessage"
 #define DMAPI5_BRIDGE_PARAMETER_MINIMUM_SECURITY_LEVEL "minimumSecurityLevel"
+#define DMAPI5_BRIDGE_PARAMETER_EVENT_INVOCATION "eventInvocation"
 
 #define DMAPI5_BRIDGE_RESPONSE_NEW_PORT "newPort"
 #define DMAPI5_BRIDGE_RESPONSE_RUNTIME_INFORMATION "runtimeInformation"
@@ -81,6 +83,7 @@
 #define DMAPI5_TOPIC_COMMAND_SEND_CHUNK 9
 #define DMAPI5_TOPIC_COMMAND_RECEIVE_CHUNK 10
 #define DMAPI5_TOPIC_COMMAND_RECEIVE_BROADCAST 11
+#define DMAPI5_TOPIC_COMMAND_COMPLETE_EVENT 12
 
 #define DMAPI5_TOPIC_PARAMETER_COMMAND_TYPE "commandType"
 #define DMAPI5_TOPIC_PARAMETER_CHAT_COMMAND "chatCommand"
@@ -116,3 +119,9 @@
 #define DMAPI5_CUSTOM_CHAT_COMMAND_NAME "name"
 #define DMAPI5_CUSTOM_CHAT_COMMAND_HELP_TEXT "helpText"
 #define DMAPI5_CUSTOM_CHAT_COMMAND_ADMIN_ONLY "adminOnly"
+
+#define DMAPI5_EVENT_ID "eventId"
+
+#define DMAPI5_EVENT_INVOCATION_NAME "eventName"
+#define DMAPI5_EVENT_INVOCATION_PARAMETERS "parameters"
+#define DMAPI5_EVENT_INVOCATION_NOTIFY_COMPLETION "notifyCompletion"
diff --git a/code/modules/tgs/v5/api.dm b/code/modules/tgs/v5/api.dm
index 25e00aed..27b0bbc4 100644
--- a/code/modules/tgs/v5/api.dm
+++ b/code/modules/tgs/v5/api.dm
@@ -27,6 +27,8 @@
 	var/chunked_requests = 0
 	var/list/chunked_topics = list()
 
+	var/list/pending_events = list()
+
 	var/detached = FALSE
 
 /datum/tgs_api/v5/New()
@@ -125,7 +127,7 @@
 			TGS_DEBUG_LOG("RequireInitialBridgeResponse: Starting sleep")
 			logged = TRUE
 
-		sleep(1)
+		sleep(world.tick_lag)
 
 	TGS_DEBUG_LOG("RequireInitialBridgeResponse: Passed")
 
@@ -249,6 +251,40 @@
 	WaitForReattach(TRUE)
 	return chat_channels.Copy()
 
+/datum/tgs_api/v5/TriggerEvent(event_name, list/parameters, wait_for_completion)
+	RequireInitialBridgeResponse()
+	WaitForReattach(TRUE)
+
+	if(interop_version.minor < 9)
+		TGS_WARNING_LOG("Interop version too low for custom events!")
+		return FALSE
+
+	var/str_parameters = list()
+	for(var/i in parameters)
+		str_parameters += "[i]"
+
+	var/list/response = Bridge(DMAPI5_BRIDGE_COMMAND_EVENT, list(DMAPI5_BRIDGE_PARAMETER_EVENT_INVOCATION = list(DMAPI5_EVENT_INVOCATION_NAME = event_name, DMAPI5_EVENT_INVOCATION_PARAMETERS = str_parameters, DMAPI5_EVENT_INVOCATION_NOTIFY_COMPLETION = wait_for_completion)))
+	if(!response)
+		return FALSE
+
+	var/event_id = response[DMAPI5_EVENT_ID]
+	if(!event_id)
+		return FALSE
+
+	TGS_DEBUG_LOG("Created event ID: [event_id]")
+	if(!wait_for_completion)
+		return TRUE
+
+	TGS_DEBUG_LOG("Waiting for completion of event ID: [event_id]")
+
+	while(!pending_events[event_id])
+		sleep(world.tick_lag)
+
+	TGS_DEBUG_LOG("Completed wait on event ID: [event_id]")
+	pending_events -= event_id
+
+	return TRUE
+
 /datum/tgs_api/v5/proc/DecodeChannels(chat_update_json)
 	TGS_DEBUG_LOG("DecodeChannels()")
 	var/list/chat_channels_json = chat_update_json[DMAPI5_CHAT_UPDATE_CHANNELS]
diff --git a/code/modules/tgs/v5/bridge.dm b/code/modules/tgs/v5/bridge.dm
index a261f8a0..0975d4af 100644
--- a/code/modules/tgs/v5/bridge.dm
+++ b/code/modules/tgs/v5/bridge.dm
@@ -65,7 +65,7 @@
 	if(detached)
 		// Wait up to one minute
 		for(var/i in 1 to 600)
-			sleep(1)
+			sleep(world.tick_lag)
 			if(!detached && (!require_channels || length(chat_channels)))
 				break
 
@@ -77,8 +77,11 @@
 /datum/tgs_api/v5/proc/PerformBridgeRequest(bridge_request)
 	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)
+	TGS_DEBUG_LOG("Bridge request complete")
+
 	if(!export_response)
 		TGS_ERROR_LOG("Failed bridge request: [bridge_request]")
 		return
@@ -88,7 +91,7 @@
 		TGS_ERROR_LOG("Failed bridge request, missing content!")
 		return
 
-	var/response_json = file2text(content)
+	var/response_json = TGS_FILE2TEXT_NATIVE(content)
 	if(!response_json)
 		TGS_ERROR_LOG("Failed bridge request, failed to load content!")
 		return
diff --git a/code/modules/tgs/v5/topic.dm b/code/modules/tgs/v5/topic.dm
index 0a81adac..71d0d20c 100644
--- a/code/modules/tgs/v5/topic.dm
+++ b/code/modules/tgs/v5/topic.dm
@@ -176,6 +176,9 @@
 			var/list/reattach_response = TopicResponse(error_message)
 			reattach_response[DMAPI5_PARAMETER_CUSTOM_COMMANDS] = ListCustomCommands()
 			reattach_response[DMAPI5_PARAMETER_TOPIC_PORT] = GetTopicPort()
+
+			pending_events.Cut()
+
 			return reattach_response
 
 		if(DMAPI5_TOPIC_COMMAND_SEND_CHUNK)
@@ -276,6 +279,15 @@
 			TGS_WORLD_ANNOUNCE(message)
 			return TopicResponse()
 
+		if(DMAPI5_TOPIC_COMMAND_COMPLETE_EVENT)
+			var/event_id = topic_parameters[DMAPI5_EVENT_ID]
+			if (!istext(event_id))
+				return TopicResponse("Invalid or missing [DMAPI5_EVENT_ID]")
+
+			TGS_DEBUG_LOG("Completing event ID [event_id]...")
+			pending_events[event_id] = TRUE
+			return TopicResponse()
+
 	return TopicResponse("Unknown command: [command]")
 
 /datum/tgs_api/v5/proc/WorldBroadcast(message)
diff --git a/code/modules/tgs/v5/undefs.dm b/code/modules/tgs/v5/undefs.dm
index 94dcb2e4..53eddcb1 100644
--- a/code/modules/tgs/v5/undefs.dm
+++ b/code/modules/tgs/v5/undefs.dm
@@ -14,6 +14,7 @@
 #undef DMAPI5_BRIDGE_COMMAND_KILL
 #undef DMAPI5_BRIDGE_COMMAND_CHAT_SEND
 #undef DMAPI5_BRIDGE_COMMAND_CHUNK
+#undef DMAPI5_BRIDGE_COMMAND_EVENT
 
 #undef DMAPI5_PARAMETER_ACCESS_IDENTIFIER
 #undef DMAPI5_PARAMETER_CUSTOM_COMMANDS
@@ -34,6 +35,7 @@
 #undef DMAPI5_BRIDGE_PARAMETER_VERSION
 #undef DMAPI5_BRIDGE_PARAMETER_CHAT_MESSAGE
 #undef DMAPI5_BRIDGE_PARAMETER_MINIMUM_SECURITY_LEVEL
+#undef DMAPI5_BRIDGE_PARAMETER_EVENT_INVOCATION
 
 #undef DMAPI5_BRIDGE_RESPONSE_NEW_PORT
 #undef DMAPI5_BRIDGE_RESPONSE_RUNTIME_INFORMATION
@@ -81,6 +83,7 @@
 #undef DMAPI5_TOPIC_COMMAND_SEND_CHUNK
 #undef DMAPI5_TOPIC_COMMAND_RECEIVE_CHUNK
 #undef DMAPI5_TOPIC_COMMAND_RECEIVE_BROADCAST
+#undef DMAPI5_TOPIC_COMMAND_COMPLETE_EVENT
 
 #undef DMAPI5_TOPIC_PARAMETER_COMMAND_TYPE
 #undef DMAPI5_TOPIC_PARAMETER_CHAT_COMMAND
@@ -116,3 +119,9 @@
 #undef DMAPI5_CUSTOM_CHAT_COMMAND_NAME
 #undef DMAPI5_CUSTOM_CHAT_COMMAND_HELP_TEXT
 #undef DMAPI5_CUSTOM_CHAT_COMMAND_ADMIN_ONLY
+
+#undef DMAPI5_EVENT_ID
+
+#undef DMAPI5_EVENT_INVOCATION_NAME
+#undef DMAPI5_EVENT_INVOCATION_PARAMETERS
+#undef DMAPI5_EVENT_INVOCATION_NOTIFY_COMPLETION