refactor: master packets as structs

Every MASTER service packet is now an LUBitStream struct (docs/PacketArchitecture.md, PR 14) and the master server's switch is a dispatch map (PacketDispatcher), as are the master handlers of the world, chat and dashboard servers. - dNet/MasterPackets.h: RequestZoneTransfer, RequestZoneTransferResponse, ServerInfo, RequestSessionKey, SetSessionKey, SessionKeyResponse, NewSessionAlert, PlayerAdded / PlayerRemoved, CreatePrivateZone, RequestPrivateZone (passwords still cut to 50 characters when read), WorldReady, WorldReadyInfo (WORLD_READY to the dashboard), PrepZone, Shutdown, ShutdownResponse, WorldShutDown (SHUTDOWN_RESPONSE to the dashboard), ShutdownUniverse, AffirmTransferRequest/Response, RequestServerList, ServerListResponse, DashboardShutdown, ConfigReload, InstanceShutdown. The Send* functions are gone; MasterPackets::SendToMaster(msg) and SendTo(sysAddr, msg) send a struct. - The dashboard and instance migration structs (PlayerAction, DataChanged, Dashboard messages, MessageCapture, InstanceMigration) are LUBitStreams of the MASTER service now and moved to dNet/master/, included by MasterPackets.h. Their payloads are unchanged; master forwards them by re-serializing the struct instead of copying raw bytes. - InstanceManager, ZoneInstanceManager, MigrationCoordinator, dServer (server info, zone transfer response), auth (SET_SESSION_KEY), the world (session keys, player added and removed, world ready, shutdown response, affirmations, prep zone, shutdown universe) and the dashboard (server list, instance shutdown, config reload, announcements, player actions, message capture) send and read structs. - The login stamps are a `stamps` field of RequestZoneTransfer and RequestZoneTransferResponse (read leniently as before: a message without them reads as empty); master adds its stamps in the REQUEST_ZONE_TRANSFER handler and when it answers, as it did. - InstanceManager::GetInstanceBySysAddr takes a const address. Verified: tests/dGameTests/dNetTests/Legacy/MasterPacketsLegacy.h is a verbatim copy of the old writers and readers; MasterPacketsTests requires identical bytes for a grid of inputs, checks the old readers read what the structs write, round trips and truncation, hand written golden packets, that zone transfers without stamps still read, that the dashboard/migration structs write what "header + Serialize" wrote, and that the dispatcher drops truncated packets. No wire bytes changed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-02 02:43:44 +00:00 · 2026-09-26 23:34:47 -05:00
parent 796fd1b941
commit 5a9a3e380b
54 changed files with 2275 additions and 1248 deletions
--- a/dNet/MasterPackets.h
+++ b/dNet/MasterPackets.h
@@ -3,24 +3,290 @@

 #include <cstdint>
 #include <string>
+#include <vector>
 #include "RakNetTypes.h"
 #include "dCommonVars.h"
+#include "BitStreamUtils.h"
+#include "MessageType/Master.h"
+#include "ServiceType.h"
 #include "Stamps.h"
+#include "master/DashboardMessages.h"
+#include "master/DataChanged.h"
+#include "master/InstanceMigration.h"
+#include "master/MessageCapture.h"
+#include "master/PlayerAction.h"
+
 class dServer;

+/**
+ * Packets between master and the other servers (MessageType::Master). None of them reach a client.
+ *
+ * The dashboard's messages and instance migration are MASTER packets too; they live in per-topic headers under
+ * dNet/master/ (PlayerAction.h, DataChanged.h, DashboardMessages.h, MessageCapture.h, InstanceMigration.h), which
+ * this header includes, so including MasterPackets.h gives every MASTER struct.
+ */
 namespace MasterPackets {
-	// stamps: the login stamps travelling with the request (empty unless auth asks for a world during a login)
-	void SendZoneTransferRequest(dServer* server, uint64_t requestID, bool mythranShift, uint32_t zoneID, uint32_t cloneID, const Stamps& stamps = {});
-	void SendZoneTransferResponse(dServer* server, const SystemAddress& sysAddr, uint64_t requestID, bool mythranShift, uint32_t zoneID, uint32_t zoneInstance, uint32_t zoneClone, const std::string& serverIP, uint32_t serverPort, const Stamps& stamps = {});
+	// Any server -> master, over server's connection to master (Game::server's when null)
+	void SendToMaster(const LUBitStream& msg, dServer* server = nullptr);

-	void HandleServerInfo(Packet* packet);
-	void SendServerInfo(dServer* server, Packet* packet);
+	// Master -> one server. Never broadcasts: nothing is sent to UNASSIGNED_SYSTEM_ADDRESS (a server that hasn't
+	// connected yet), unlike LUBitStream::Send.
+	void SendTo(const SystemAddress& sysAddr, const LUBitStream& msg);

-	void SendZoneCreatePrivate(dServer* server, uint32_t zoneID, uint32_t cloneID, const std::string& password);
+	// World -> master: a player wants to go to zoneID (clone cloneID)
+	struct RequestZoneTransfer : public LUBitStream {
+		uint64_t requestID{};
+		uint8_t mythranShift{};
+		uint32_t zoneID{};
+		uint32_t cloneID{};
+		// The login stamps travelling with the request (see Stamps.h); empty unless auth asks for a world during a
+		// login. Read leniently: a request without them reads as empty.
+		Stamps stamps{};

-	void SendZoneRequestPrivate(dServer* server, uint64_t requestID, bool mythranShift, const std::string& password);
+		RequestZoneTransfer() : LUBitStream(ServiceType::MASTER, MessageType::Master::REQUEST_ZONE_TRANSFER) {}
+		void Serialize(RakNet::BitStream& bitStream) const override;
+		bool Deserialize(RakNet::BitStream& bitStream) override;
+	};

-	void SendWorldReady(dServer* server, LWOMAPID zoneId, LWOINSTANCEID instanceId);
+	// Master -> world: where to send the player of requestID
+	struct RequestZoneTransferResponse : public LUBitStream {
+		uint64_t requestID{};
+		uint8_t mythranShift{};
+		uint32_t zoneID{};
+		uint32_t zoneInstance{};
+		uint32_t zoneClone{};
+		uint16_t serverPort{};
+		LUString serverIP{ 255u };
+		// The request's login stamps with master's own added (see Stamps.h). Read leniently like the request's.
+		Stamps stamps{};
+
+		RequestZoneTransferResponse() : LUBitStream(ServiceType::MASTER, MessageType::Master::REQUEST_ZONE_TRANSFER_RESPONSE) {}
+		void Serialize(RakNet::BitStream& bitStream) const override;
+		bool Deserialize(RakNet::BitStream& bitStream) override;
+	};
+
+	// Any server -> master, once connected; master -> dashboard for every other server (ip "offline" when one is gone)
+	struct ServerInfo : public LUBitStream {
+		uint32_t port{};
+		uint32_t zoneID{};
+		uint32_t instanceID{};
+		ServiceType serverType{};
+		LUString ip{};
+
+		ServerInfo() : LUBitStream(ServiceType::MASTER, MessageType::Master::SERVER_INFO) {}
+		void Serialize(RakNet::BitStream& bitStream) const override;
+		bool Deserialize(RakNet::BitStream& bitStream) override;
+	};
+
+	// World -> master: the session key of the account logging in
+	struct RequestSessionKey : public LUBitStream {
+		LUWString username{};
+
+		RequestSessionKey() : LUBitStream(ServiceType::MASTER, MessageType::Master::REQUEST_SESSION_KEY) {}
+		void Serialize(RakNet::BitStream& bitStream) const override;
+		bool Deserialize(RakNet::BitStream& bitStream) override;
+	};
+
+	// Auth -> master: an account logged in with this session key
+	struct SetSessionKey : public LUBitStream {
+		uint32_t sessionKey{};
+		LUString username{};
+
+		SetSessionKey() : LUBitStream(ServiceType::MASTER, MessageType::Master::SET_SESSION_KEY) {}
+		void Serialize(RakNet::BitStream& bitStream) const override;
+		bool Deserialize(RakNet::BitStream& bitStream) override;
+	};
+
+	// Master -> world: answer to RequestSessionKey
+	struct SessionKeyResponse : public LUBitStream {
+		uint32_t sessionKey{};
+		LUWString username{};
+
+		SessionKeyResponse() : LUBitStream(ServiceType::MASTER, MessageType::Master::SESSION_KEY_RESPONSE) {}
+		void Serialize(RakNet::BitStream& bitStream) const override;
+		bool Deserialize(RakNet::BitStream& bitStream) override;
+	};
+
+	// Master -> every server: the account logged in again with a new session key
+	struct NewSessionAlert : public LUBitStream {
+		uint32_t sessionKey{};
+		LUString username{};
+
+		NewSessionAlert() : LUBitStream(ServiceType::MASTER, MessageType::Master::NEW_SESSION_ALERT) {}
+		void Serialize(RakNet::BitStream& bitStream) const override;
+		bool Deserialize(RakNet::BitStream& bitStream) override;
+	};
+
+	// World -> master -> dashboard: a player came into (PLAYER_ADDED) or left (PLAYER_REMOVED) a world
+	struct PlayerCountChange : public LUBitStream {
+		LWOMAPID zoneID{};
+		LWOINSTANCEID instanceID{};
+
+		PlayerCountChange(MessageType::Master id) : LUBitStream(ServiceType::MASTER, id) {}
+		void Serialize(RakNet::BitStream& bitStream) const override;
+		bool Deserialize(RakNet::BitStream& bitStream) override;
+	};
+
+	struct PlayerAdded : public PlayerCountChange {
+		PlayerAdded() : PlayerCountChange(MessageType::Master::PLAYER_ADDED) {}
+	};
+
+	struct PlayerRemoved : public PlayerCountChange {
+		PlayerRemoved() : PlayerCountChange(MessageType::Master::PLAYER_REMOVED) {}
+	};
+
+	// World -> master: start a private instance of zoneID that needs `password` to join
+	struct CreatePrivateZone : public LUBitStream {
+		// Longer passwords are cut to this when read
+		static constexpr uint32_t MAX_PASSWORD_LENGTH = 50;
+
+		uint32_t zoneID{};
+		uint32_t cloneID{};
+		std::string password; // u32 length, then 1 byte per character
+
+		CreatePrivateZone() : LUBitStream(ServiceType::MASTER, MessageType::Master::CREATE_PRIVATE_ZONE) {}
+		void Serialize(RakNet::BitStream& bitStream) const override;
+		bool Deserialize(RakNet::BitStream& bitStream) override;
+	};
+
+	// World -> master: send the player of requestID to the private instance with this password
+	struct RequestPrivateZone : public LUBitStream {
+		// Longer passwords are cut to this when read
+		static constexpr uint32_t MAX_PASSWORD_LENGTH = 50;
+
+		uint64_t requestID{};
+		uint8_t mythranShift{};
+		std::string password; // u32 length, then 1 byte per character
+
+		RequestPrivateZone() : LUBitStream(ServiceType::MASTER, MessageType::Master::REQUEST_PRIVATE_ZONE) {}
+		void Serialize(RakNet::BitStream& bitStream) const override;
+		bool Deserialize(RakNet::BitStream& bitStream) override;
+	};
+
+	// World -> master: the world finished loading and takes players
+	struct WorldReady : public LUBitStream {
+		LWOMAPID zoneID{};
+		LWOINSTANCEID instanceID{};
+
+		WorldReady() : LUBitStream(ServiceType::MASTER, MessageType::Master::WORLD_READY) {}
+		void Serialize(RakNet::BitStream& bitStream) const override;
+		bool Deserialize(RakNet::BitStream& bitStream) override;
+	};
+
+	// Master -> dashboard (WORLD_READY): a world is ready, and where it is
+	struct WorldReadyInfo : public LUBitStream {
+		LWOMAPID zoneID{};
+		LWOINSTANCEID instanceID{};
+		LWOCLONEID cloneID{};
+		LUString ip{};
+		uint32_t port{};
+		uint8_t isPrivate{};
+
+		WorldReadyInfo() : LUBitStream(ServiceType::MASTER, MessageType::Master::WORLD_READY) {}
+		void Serialize(RakNet::BitStream& bitStream) const override;
+		bool Deserialize(RakNet::BitStream& bitStream) override;
+	};
+
+	// World -> master: start an instance of zoneID now, players are about to ask for it
+	struct PrepZone : public LUBitStream {
+		int32_t zoneID{};
+
+		PrepZone() : LUBitStream(ServiceType::MASTER, MessageType::Master::PREP_ZONE) {}
+		void Serialize(RakNet::BitStream& bitStream) const override;
+		bool Deserialize(RakNet::BitStream& bitStream) override;
+	};
+
+	// Master -> any server: shut down
+	struct Shutdown : public LUBitStream {
+		Shutdown() : LUBitStream(ServiceType::MASTER, MessageType::Master::SHUTDOWN) {}
+	};
+
+	// World -> master: shutting down
+	struct ShutdownResponse : public LUBitStream {
+		ShutdownResponse() : LUBitStream(ServiceType::MASTER, MessageType::Master::SHUTDOWN_RESPONSE) {}
+	};
+
+	// Master -> dashboard (SHUTDOWN_RESPONSE): a world is gone
+	struct WorldShutDown : public LUBitStream {
+		LWOMAPID zoneID{};
+		LWOINSTANCEID instanceID{};
+
+		WorldShutDown() : LUBitStream(ServiceType::MASTER, MessageType::Master::SHUTDOWN_RESPONSE) {}
+		void Serialize(RakNet::BitStream& bitStream) const override;
+		bool Deserialize(RakNet::BitStream& bitStream) override;
+	};
+
+	// World -> master: a GM asked to shut every server down in 10 minutes
+	struct ShutdownUniverse : public LUBitStream {
+		ShutdownUniverse() : LUBitStream(ServiceType::MASTER, MessageType::Master::SHUTDOWN_UNIVERSE) {}
+	};
+
+	// Master -> world: can you take the player of requestID? (AFFIRM_TRANSFER_REQUEST); world -> master: yes
+	// (AFFIRM_TRANSFER_RESPONSE)
+	struct AffirmTransfer : public LUBitStream {
+		uint64_t requestID{};
+
+		AffirmTransfer(MessageType::Master id) : LUBitStream(ServiceType::MASTER, id) {}
+		void Serialize(RakNet::BitStream& bitStream) const override;
+		bool Deserialize(RakNet::BitStream& bitStream) override;
+	};
+
+	struct AffirmTransferRequest : public AffirmTransfer {
+		AffirmTransferRequest() : AffirmTransfer(MessageType::Master::AFFIRM_TRANSFER_REQUEST) {}
+	};
+
+	struct AffirmTransferResponse : public AffirmTransfer {
+		AffirmTransferResponse() : AffirmTransfer(MessageType::Master::AFFIRM_TRANSFER_RESPONSE) {}
+	};
+
+	// Dashboard -> master: which servers are running (answered with ServerListResponse)
+	struct RequestServerList : public LUBitStream {
+		RequestServerList() : LUBitStream(ServiceType::MASTER, MessageType::Master::REQUEST_SERVER_LIST) {}
+	};
+
+	// Master -> dashboard
+	struct ServerListResponse : public LUBitStream {
+		// More than this many worlds is a broken packet
+		static constexpr uint32_t MAX_INSTANCES = 10000;
+
+		struct Instance {
+			LWOMAPID mapID{};
+			LWOINSTANCEID instanceID{};
+			LWOCLONEID cloneID{};
+			uint32_t players{};
+			LUString ip{};
+			uint32_t port{};
+			uint8_t isPrivate{};
+		};
+
+		uint8_t authOnline{};
+		uint8_t chatOnline{};
+		std::vector<Instance> instances; // u32 count
+
+		ServerListResponse() : LUBitStream(ServiceType::MASTER, MessageType::Master::SERVER_LIST_RESPONSE) {}
+		void Serialize(RakNet::BitStream& bitStream) const override;
+		bool Deserialize(RakNet::BitStream& bitStream) override;
+	};
+
+	// Dashboard -> master: shut the whole server down now (scheduled restarts)
+	struct DashboardShutdown : public LUBitStream {
+		DashboardShutdown() : LUBitStream(ServiceType::MASTER, MessageType::Master::DASHBOARD_SHUTDOWN) {}
+	};
+
+	// Dashboard -> master -> every server: settings changed on the dashboard, reload the config
+	struct ConfigReload : public LUBitStream {
+		ConfigReload() : LUBitStream(ServiceType::MASTER, MessageType::Master::CONFIG_RELOAD) {}
+	};
+
+	// Dashboard -> master: shut down one world instance
+	struct InstanceShutdown : public LUBitStream {
+		uint32_t zoneID{};
+		uint32_t instanceID{};
+
+		InstanceShutdown() : LUBitStream(ServiceType::MASTER, MessageType::Master::INSTANCE_SHUTDOWN) {}
+		void Serialize(RakNet::BitStream& bitStream) const override;
+		bool Deserialize(RakNet::BitStream& bitStream) override;
+	};
 }

 #endif // MASTERPACKETS_H