From a2b47ff52bda039a2d4958d89c03b5aa12c29e13 Mon Sep 17 00:00:00 2001
From: nOOb3167 <nOOb3167@gmail.com>
Date: Mon, 4 Jun 2018 15:03:45 +0200
Subject: [PATCH] Document serverUp protocol

serverUp uses hex spaghetti to send and receive a short sequence of packets, to see whether a server is online.
The packet format is now annotated for easier cross-reference with minetest source.
---
 server.py | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/server.py b/server.py
index a8b373a..978f58f 100755
--- a/server.py
+++ b/server.py
@@ -142,14 +142,37 @@ def serverUp(info):
 		sock = socket.socket(info[0], info[1], info[2])
 		sock.settimeout(3)
 		sock.connect(info[4])
+		# send packet of type ORIGINAL, with no data
+		#     this should prompt the server to assign us a peer id
+		# [0] u32       protocol_id (PROTOCOL_ID)
+		# [4] session_t sender_peer_id (PEER_ID_INEXISTENT)
+		# [6] u8        channel
+		# [7] u8        type (PACKET_TYPE_ORIGINAL)
 		buf = b"\x4f\x45\x74\x03\x00\x00\x00\x01"
 		sock.send(buf)
 		start = time.time()
+		# receive reliable packet of type CONTROL, subtype SET_PEER_ID,
+		#     with our assigned peer id as data
+		# [0] u32        protocol_id (PROTOCOL_ID)
+		# [4] session_t  sender_peer_id
+		# [6] u8         channel
+		# [7] u8         type (PACKET_TYPE_RELIABLE)
+		# [8] u16        seqnum
+		# [10] u8        type (PACKET_TYPE_CONTROL)
+		# [11] u8        controltype (CONTROLTYPE_SET_PEER_ID)
+		# [12] session_t peer_id_new
 		data = sock.recv(1024)
 		end = time.time()
 		if not data:
 			return False
 		peer_id = data[12:14]
+		# send packet of type CONTROL, subtype DISCO,
+		#     to cleanly close our server connection
+		# [0] u32       protocol_id (PROTOCOL_ID)
+		# [4] session_t sender_peer_id
+		# [6] u8        channel
+		# [7] u8        type (PACKET_TYPE_CONTROL)
+		# [8] u8        controltype (CONTROLTYPE_DISCO)
 		buf = b"\x4f\x45\x74\x03" + peer_id + b"\x00\x00\x03"
 		sock.send(buf)
 		sock.close()