Include file cleanup, docs, and build fixes.

include/ZeroTierCore.h

@@ -12,13 +12,23 @@
 /****/
 
 /*
- * This defines the external C API for ZeroTier's core network virtualization
- * engine.
+ * This defines the external C API for the ZeroTier network hypervisor.
  */
 
 #ifndef ZT_ZEROTIER_API_H
 #define ZT_ZEROTIER_API_H
 
+#if defined(_WIN32) || defined(_WIN64)
+#include <WinSock2.h>
+#include <WS2tcpip.h>
+#include <Windows.h>
+#else
+#include <arpa/inet.h>
+#include <netinet/in.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#endif
+
 /* ZT_PACKED_STRUCT encloses structs whose contents should be bit-packed.
  * Nearly all compilers support this. These macros detect the compiler and
  * define it correctly for gcc/icc/clang or MSC. */
@@ -45,45 +55,36 @@ extern "C" {
 #include <stdint.h>
 #endif
 
-#if defined(_WIN32) || defined(_WIN64)
-#include <WinSock2.h>
-#include <WS2tcpip.h>
-#include <Windows.h>
-#else
-#include <arpa/inet.h>
-#include <netinet/in.h>
-#include <sys/types.h>
-#include <sys/socket.h>
-#endif
-
+/* This symbol may be defined to anything we need to put in front of API function prototypes. */
 #ifndef ZT_SDK_API
 #define ZT_SDK_API
 #endif
 
-/****************************************************************************/
+/* ----------------------------------------------------------------------------------------------------------------- */
 
 /**
  * Default UDP port for devices running a ZeroTier endpoint
  *
  * NOTE: as of V2 this has changed to 893 since many NATs (even symmetric)
- * treat privileged ports in a special way. The old default was 9993.
+ * treat privileged ports in a special way. The old default was 9993 and
+ * this is likely to be seen in the wild quite a bit.
  */
 #define ZT_DEFAULT_PORT 893
 
 /**
- * Minimum MTU, which is the minimum allowed by IPv6 and several specs
+ * Minimum MTU allowed on virtual networks
  */
 #define ZT_MIN_MTU 1280
 
 /**
- * Maximum MTU for ZeroTier virtual networks
+ * Maximum MTU allowed on virtual networks
  */
 #define ZT_MAX_MTU 10000
 
 /**
- * Minimum UDP payload size allowed
+ * Minimum allowed physical UDP MTU (smaller values are clipped to this)
  */
-#define ZT_MIN_PHYSMTU 1400
+#define ZT_MIN_UDP_MTU 1400
 
 /**
  * Default UDP payload size (physical path MTU) not including UDP and IP overhead
@@ -92,22 +93,22 @@ extern "C" {
  * A 2800 byte payload still fits into two packets, so this should not impact
  * real world throughput at all vs the previous default of 1444.
  */
-#define ZT_DEFAULT_PHYSMTU 1432
+#define ZT_DEFAULT_UDP_MTU 1432
 
 /**
  * Maximum physical UDP payload
  */
-#define ZT_MAX_PHYSPAYLOAD 10100
+#define ZT_MAX_UDP_PHYSPAYLOAD 10100
 
 /**
  * Headroom for max physical MTU
  */
-#define ZT_MAX_HEADROOM 224
+#define ZT_MAX_UDP_HEADROOM 224
 
 /**
  * Maximum payload MTU for UDP packets
  */
-#define ZT_MAX_PHYSMTU (ZT_MAX_PHYSPAYLOAD + ZT_MAX_HEADROOM)
+#define ZT_MAX_UDP_MTU (ZT_MAX_UDP_PHYSPAYLOAD + ZT_MAX_UDP_HEADROOM)
 
 /**
  * Maximum length of network short name
@@ -188,7 +189,7 @@ extern "C" {
  */
 #define ZT_MAX_CAPABILITY_CUSTODY_CHAIN_LENGTH 7
 
-/* Rule specification contants **********************************************/
+/* ----------------------------------------------------------------------------------------------------------------- */
 
 /**
  * Packet characteristics flag: packet direction, 1 if inbound 0 if outbound
@@ -275,13 +276,10 @@ extern "C" {
  */
 #define ZT_RULE_PACKET_CHARACTERISTICS_TCP_FIN 0x0000000000000001ULL
 
-/****************************************************************************/
+/* ----------------------------------------------------------------------------------------------------------------- */
 
 /**
  * Credential type IDs
- *
- * These are mostly used internally but are declared here so they can be used
- * in trace messages.
  */
 enum ZT_CredentialType
 {
@@ -295,11 +293,9 @@ enum ZT_CredentialType
 
 /* Trace events are sent and received as packed structures of a fixed size.
  * Normally we don't use this form of brittle encoding but in this case the
- * performance benefit is non-trivial as events are generated in critical
- * areas of the code.
+ * performance benefit is non-trivial.
  *
- * NOTE: all integer fields larger than one byte are stored in big-endian
- * "network" byte order in these structures. */
+ * All integer fields larger than one byte are stored in big-endian order. */
 
 /**
  * Flag indicating that VL1 tracing should be generated
@@ -386,12 +382,12 @@ enum ZT_TraceFrameDropReason
 enum ZT_TraceEventPathAddressType
 {
 	ZT_TRACE_EVENT_PATH_TYPE_NIL =          0, /* none/empty */
-	ZT_TRACE_EVENT_PATH_TYPE_INETADDR_V4 =  1, /* 4-byte IPv4 */
-	ZT_TRACE_EVENT_PATH_TYPE_INETADDR_V6 =  2, /* 16-byte IPv6 */
-	ZT_TRACE_EVENT_PATH_TYPE_DNSNAME =      3, /* C string */
-	ZT_TRACE_EVENT_PATH_TYPE_ZEROTIER =     4, /* 5-byte ZeroTier + 48-byte identity hash */
-	ZT_TRACE_EVENT_PATH_TYPE_URL =          5, /* C string */
-	ZT_TRACE_EVENT_PATH_TYPE_ETHERNET =     6  /* 6-byte Ethernet */
+	ZT_TRACE_EVENT_PATH_TYPE_ZEROTIER =     1, /* 5-byte ZeroTier + 48-byte identity hash */
+	ZT_TRACE_EVENT_PATH_TYPE_DNSNAME =      2, /* C string */
+	ZT_TRACE_EVENT_PATH_TYPE_URL =          3, /* C string */
+	ZT_TRACE_EVENT_PATH_TYPE_INETADDR_V4 =  4, /* 4-byte IPv4 */
+	ZT_TRACE_EVENT_PATH_TYPE_ETHERNET =     5, /* 6-byte Ethernet */
+	ZT_TRACE_EVENT_PATH_TYPE_INETADDR_V6 =  6  /* 16-byte IPv6 */
 };
 
 /**
@@ -613,12 +609,7 @@ enum ZT_ResultCode
 	 */
 	ZT_RESULT_OK = 0,
 
-	/**
-	 * Call produced no error but no action was taken
-	 */
-	ZT_RESULT_OK_IGNORED = 1,
-
-	// Fatal errors (>100, <1000)
+	/* Fatal errors (>100, <1000) */
 
 	/**
 	 * Ran out of memory
@@ -635,7 +626,7 @@ enum ZT_ResultCode
 	 */
 	ZT_RESULT_FATAL_ERROR_INTERNAL = 102,
 
-	// Non-fatal errors (>1000)
+	/* Non-fatal errors (>1000) */
 
 	/**
 	 * Network ID not valid

node/Endpoint.hpp

@@ -41,16 +41,18 @@ class Endpoint : public TriviallyCopyable
 public:
 	/**
 	 * Endpoint type
+	 *
+	 * These are set to be the same as the IDs used for trace events in ZeroTierCore.h.
 	 */
 	enum Type
 	{
-		TYPE_NIL =          0,          // NIL value
-		TYPE_ZEROTIER =     1,          // ZeroTier Address (for relaying and meshy behavior)
-		TYPE_DNSNAME =      2,          // DNS name and port that resolves to InetAddress
-		TYPE_URL =          3,          // URL for HTTP or Web Sockets transport
-		TYPE_INETADDR_V4 =  4,          // IPv4
-		TYPE_ETHERNET =     5,          // 48-bit LAN-local Ethernet address
-		TYPE_INETADDR_V6 =  6           // IPv6
+		TYPE_NIL =          ZT_TRACE_EVENT_PATH_TYPE_NIL,
+		TYPE_ZEROTIER =     ZT_TRACE_EVENT_PATH_TYPE_ZEROTIER,
+		TYPE_DNSNAME =      ZT_TRACE_EVENT_PATH_TYPE_DNSNAME,
+		TYPE_URL =          ZT_TRACE_EVENT_PATH_TYPE_URL,
+		TYPE_INETADDR_V4 =  ZT_TRACE_EVENT_PATH_TYPE_INETADDR_V4,
+		TYPE_ETHERNET =     ZT_TRACE_EVENT_PATH_TYPE_ETHERNET,
+		TYPE_INETADDR_V6 =  ZT_TRACE_EVENT_PATH_TYPE_INETADDR_V6
 	};
 
 	ZT_ALWAYS_INLINE Endpoint() noexcept { memoryZero(this); }

node/Identity.cpp

@@ -544,7 +544,7 @@ ZT_Identity *ZT_Identity_new(enum ZT_Identity_Type type)
 	if ((type != ZT_IDENTITY_TYPE_C25519)&&(type != ZT_IDENTITY_TYPE_P384))
 		return nullptr;
 	try {
-		ZeroTier::Identity *id = new ZeroTier::Identity();
+		ZeroTier::Identity *const id = new ZeroTier::Identity();
 		id->generate((ZeroTier::Identity::Type)type);
 		return reinterpret_cast<ZT_Identity *>(id);
 	} catch ( ... ) {
@@ -557,7 +557,7 @@ ZT_Identity *ZT_Identity_fromString(const char *idStr)
 	if (!idStr)
 		return nullptr;
 	try {
-		ZeroTier::Identity *id = new ZeroTier::Identity();
+		ZeroTier::Identity *const id = new ZeroTier::Identity();
 		if (!id->fromString(idStr)) {
 			delete id;
 			return nullptr;
@@ -624,7 +624,7 @@ void ZT_Identity_hash(const ZT_Identity *id,uint8_t h[48],int includePrivate)
 {
 	if (includePrivate)
 		reinterpret_cast<const ZeroTier::Identity *>(id)->hashWithPrivate(h);
-	else memcpy(h,reinterpret_cast<const ZeroTier::Identity *>(id)->hash(),48);
+	else memcpy(h,reinterpret_cast<const ZeroTier::Identity *>(id)->hash().data(),ZT_IDENTITY_HASH_SIZE);
 }
 
 ZT_SDK_API void ZT_Identity_delete(ZT_Identity *id)

node/Protocol.hpp

@@ -129,9 +129,9 @@
 #define ZT_PROTO_VERSION_MIN 8
 
 /**
- * Packet buffer size (can be changed)
+ * Maximum allowed packet size (can technically be increased up to 16384)
  */
-#define ZT_PROTO_MAX_PACKET_LENGTH (ZT_MAX_PACKET_FRAGMENTS * ZT_DEFAULT_PHYSMTU)
+#define ZT_PROTO_MAX_PACKET_LENGTH (ZT_MAX_PACKET_FRAGMENTS * ZT_MIN_UDP_MTU)
 
 /**
  * Minimum viable packet length (outer header + verb)

node/Topology.cpp

@@ -124,11 +124,11 @@ void Topology::setPhysicalPathConfiguration(const struct sockaddr_storage *pathN
 			ZT_PhysicalPathConfiguration pc(*pathConfig);
 
 			if (pc.mtu <= 0)
-				pc.mtu = ZT_DEFAULT_PHYSMTU;
-			else if (pc.mtu < ZT_MIN_PHYSMTU)
-				pc.mtu = ZT_MIN_PHYSMTU;
-			else if (pc.mtu > ZT_MAX_PHYSMTU)
-				pc.mtu = ZT_MAX_PHYSMTU;
+				pc.mtu = ZT_DEFAULT_UDP_MTU;
+			else if (pc.mtu < ZT_MIN_UDP_MTU)
+				pc.mtu = ZT_MIN_UDP_MTU;
+			else if (pc.mtu > ZT_MAX_UDP_MTU)
+				pc.mtu = ZT_MAX_UDP_MTU;
 
 			cpaths[*(reinterpret_cast<const InetAddress *>(pathNetwork))] = pc;
 		} else {

node/VL1.cpp

@@ -971,6 +971,7 @@ bool VL1::_PUSH_DIRECT_PATHS(void *tPtr,const SharedPtr<Path> &path,const Shared
 		}
 
 		if (a) {
+			RR->t->tryingNewPath(tPtr,0xa5ab1a43,peer->identity(),a,path->address(),Protocol::packetId(pkt,packetSize),Protocol::VERB_RENDEZVOUS,peer->address(),peer->identity().hash().data(),ZT_TRACE_TRYING_NEW_PATH_REASON_RECEIVED_PUSH_DIRECT_PATHS);
 		}
 
 		ptr += (int)addrRecordLen;