From 19e32e9c092375922606ea8eeb4e82a5586fa354 Mon Sep 17 00:00:00 2001
From: Metehan Gezer <irrelevantdev@outlook.com>
Date: Wed, 30 Jul 2025 18:25:10 +0300
Subject: [PATCH 01/12] wip p2p

---
 .idea/inspectionProfiles/Project_Default.xml |    1 +
 CMakeLists.txt                               |    2 +
 examples/relay_client/CMakeLists.txt         |   10 +
 examples/relay_client/cxxopts.h              | 2927 ++++++++++++++++++
 examples/relay_client/main.cc                |   90 +
 relay_server/CMakeLists.txt                  |   10 +
 relay_server/cxxopts.h                       | 2927 ++++++++++++++++++
 relay_server/main.cc                         |  114 +
 znet/CMakeLists.txt                          |    2 +
 znet/include/znet/base/inet_addr.h           |   16 +-
 znet/include/znet/base/types.h               |    1 +
 znet/include/znet/base/util.h                |    2 +
 znet/include/znet/buffer.h                   |   87 +-
 znet/include/znet/encryption.h               |   49 +-
 znet/include/znet/interface.h                |    4 +-
 znet/include/znet/p2p/dialer.h               |   58 +
 znet/include/znet/p2p/relay.h                |  154 +
 znet/include/znet/peer_session.h             |   61 +-
 znet/include/znet/relay/relay_server.h       |   21 -
 znet/include/znet/server.h                   |    2 +-
 znet/src/client.cc                           |   13 +-
 znet/src/dialer.cc                           |   59 +
 znet/src/encryption.cc                       |   43 +-
 znet/src/peer_session.cc                     |   15 +-
 znet/src/util.cc                             |   42 +
 25 files changed, 6613 insertions(+), 97 deletions(-)
 create mode 100644 examples/relay_client/CMakeLists.txt
 create mode 100644 examples/relay_client/cxxopts.h
 create mode 100644 examples/relay_client/main.cc
 create mode 100644 relay_server/CMakeLists.txt
 create mode 100644 relay_server/cxxopts.h
 create mode 100644 relay_server/main.cc
 create mode 100644 znet/include/znet/p2p/dialer.h
 create mode 100644 znet/include/znet/p2p/relay.h
 delete mode 100644 znet/include/znet/relay/relay_server.h
 create mode 100644 znet/src/dialer.cc
 create mode 100644 znet/src/util.cc

diff --git a/.idea/inspectionProfiles/Project_Default.xml b/.idea/inspectionProfiles/Project_Default.xml
index 4538bfa..5f7c891 100644
--- a/.idea/inspectionProfiles/Project_Default.xml
+++ b/.idea/inspectionProfiles/Project_Default.xml
@@ -1,6 +1,7 @@
 <component name="InspectionProjectProfileManager">
   <profile version="1.0">
     <option name="myName" value="Project Default" />
+    <inspection_tool class="ClangTidy" enabled="false" level="WARNING" enabled_by_default="false" />
     <inspection_tool class="ConstantFunctionResult" enabled="false" level="WARNING" enabled_by_default="false" />
     <inspection_tool class="CppRedundantAccessSpecifier" enabled="false" level="HINT" enabled_by_default="false" />
     <inspection_tool class="CppRedundantLambdaParameterList" enabled="false" level="HINT" enabled_by_default="false" />
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 6711efa..8ed0d13 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -3,10 +3,12 @@ project(znet-parent)
 
 add_subdirectory(vendor/fmt)
 add_subdirectory(znet)
+add_subdirectory(relay_server)
 
 # examples
 add_subdirectory(examples/basic/server)
 add_subdirectory(examples/basic/client)
+add_subdirectory(examples/relay_client)
 
 # tests
 enable_testing()
diff --git a/examples/relay_client/CMakeLists.txt b/examples/relay_client/CMakeLists.txt
new file mode 100644
index 0000000..5a5a4a8
--- /dev/null
+++ b/examples/relay_client/CMakeLists.txt
@@ -0,0 +1,10 @@
+cmake_minimum_required(VERSION 3.16.3)
+project(relay-client)
+
+add_executable(relay-client main.cc)
+set_target_properties(relay-client PROPERTIES
+        CXX_STANDARD 14
+        CXX_STANDARD_REQUIRED ON
+)
+target_link_libraries(relay-client PRIVATE znet)
+
diff --git a/examples/relay_client/cxxopts.h b/examples/relay_client/cxxopts.h
new file mode 100644
index 0000000..e76f206
--- /dev/null
+++ b/examples/relay_client/cxxopts.h
@@ -0,0 +1,2927 @@
+/*
+
+Copyright (c) 2014-2022 Jarryd Beck
+
+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.
+
+*/
+
+// vim: ts=2:sw=2:expandtab
+
+#ifndef CXXOPTS_HPP_INCLUDED
+#define CXXOPTS_HPP_INCLUDED
+
+#include <cstdint>
+#include <cstdlib>
+#include <cstring>
+#include <exception>
+#include <limits>
+#include <initializer_list>
+#include <map>
+#include <memory>
+#include <sstream>
+#include <string>
+#include <unordered_map>
+#include <unordered_set>
+#include <utility>
+#include <vector>
+#include <algorithm>
+#include <locale>
+
+#ifdef CXXOPTS_NO_EXCEPTIONS
+#include <iostream>
+#endif
+
+#if defined(__GNUC__) && !defined(__clang__)
+#  if (__GNUC__ * 10 + __GNUC_MINOR__) < 49
+#    define CXXOPTS_NO_REGEX true
+#  endif
+#endif
+#if defined(_MSC_VER) && !defined(__clang__)
+#define CXXOPTS_LINKONCE_CONST	__declspec(selectany) extern
+#define CXXOPTS_LINKONCE		__declspec(selectany) extern
+#else
+#define CXXOPTS_LINKONCE_CONST
+#define CXXOPTS_LINKONCE
+#endif
+
+#ifndef CXXOPTS_NO_REGEX
+#  include <regex>
+#endif  // CXXOPTS_NO_REGEX
+
+// Nonstandard before C++17, which is coincidentally what we also need for <optional>
+#ifdef __has_include
+#  if __has_include(<optional>)
+#    include <optional>
+#    ifdef __cpp_lib_optional
+#      define CXXOPTS_HAS_OPTIONAL
+#    endif
+#  endif
+#  if __has_include(<filesystem>)
+#    include <filesystem>
+#    ifdef __cpp_lib_filesystem
+#      define CXXOPTS_HAS_FILESYSTEM
+#    endif
+#  endif
+#endif
+
+#define CXXOPTS_FALLTHROUGH
+#ifdef __has_cpp_attribute
+  #if __has_cpp_attribute(fallthrough)
+    #undef CXXOPTS_FALLTHROUGH
+    #define CXXOPTS_FALLTHROUGH [[fallthrough]]
+  #endif
+#endif
+
+#if __cplusplus >= 201603L
+#define CXXOPTS_NODISCARD [[nodiscard]]
+#else
+#define CXXOPTS_NODISCARD
+#endif
+
+#ifndef CXXOPTS_VECTOR_DELIMITER
+#define CXXOPTS_VECTOR_DELIMITER ','
+#endif
+
+#define CXXOPTS__VERSION_MAJOR 3
+#define CXXOPTS__VERSION_MINOR 3
+#define CXXOPTS__VERSION_PATCH 1
+
+#if (__GNUC__ < 10 || (__GNUC__ == 10 && __GNUC_MINOR__ < 1)) && __GNUC__ >= 6
+  #define CXXOPTS_NULL_DEREF_IGNORE
+#endif
+
+#if defined(__GNUC__)
+#define DO_PRAGMA(x) _Pragma(#x)
+#define CXXOPTS_DIAGNOSTIC_PUSH DO_PRAGMA(GCC diagnostic push)
+#define CXXOPTS_DIAGNOSTIC_POP DO_PRAGMA(GCC diagnostic pop)
+#define CXXOPTS_IGNORE_WARNING(x) DO_PRAGMA(GCC diagnostic ignored x)
+#else
+// define other compilers here if needed
+#define CXXOPTS_DIAGNOSTIC_PUSH
+#define CXXOPTS_DIAGNOSTIC_POP
+#define CXXOPTS_IGNORE_WARNING(x)
+#endif
+
+#ifdef CXXOPTS_NO_RTTI
+#define CXXOPTS_RTTI_CAST static_cast
+#else
+#define CXXOPTS_RTTI_CAST dynamic_cast
+#endif
+
+namespace cxxopts {
+static constexpr struct {
+  uint8_t major, minor, patch;
+} version = {
+  CXXOPTS__VERSION_MAJOR,
+  CXXOPTS__VERSION_MINOR,
+  CXXOPTS__VERSION_PATCH
+};
+} // namespace cxxopts
+
+//when we ask cxxopts to use Unicode, help strings are processed using ICU,
+//which results in the correct lengths being computed for strings when they
+//are formatted for the help output
+//it is necessary to make sure that <unicode/unistr.h> can be found by the
+//compiler, and that icu-uc is linked in to the binary.
+
+#ifdef CXXOPTS_USE_UNICODE
+#include <unicode/unistr.h>
+
+namespace cxxopts {
+
+using String = icu::UnicodeString;
+
+inline
+String
+toLocalString(std::string s)
+{
+  return icu::UnicodeString::fromUTF8(std::move(s));
+}
+
+// GNU GCC with -Weffc++ will issue a warning regarding the upcoming class, we want to silence it:
+// warning: base class 'class std::enable_shared_from_this<cxxopts::Value>' has accessible non-virtual destructor
+CXXOPTS_DIAGNOSTIC_PUSH
+CXXOPTS_IGNORE_WARNING("-Wnon-virtual-dtor")
+// This will be ignored under other compilers like LLVM clang.
+class UnicodeStringIterator
+{
+  public:
+
+  using iterator_category = std::forward_iterator_tag;
+  using value_type = int32_t;
+  using difference_type = std::ptrdiff_t;
+  using pointer = value_type*;
+  using reference = value_type&;
+
+  UnicodeStringIterator(const icu::UnicodeString* string, int32_t pos)
+  : s(string)
+  , i(pos)
+  {
+  }
+
+  value_type
+  operator*() const
+  {
+    return s->char32At(i);
+  }
+
+  bool
+  operator==(const UnicodeStringIterator& rhs) const
+  {
+    return s == rhs.s && i == rhs.i;
+  }
+
+  bool
+  operator!=(const UnicodeStringIterator& rhs) const
+  {
+    return !(*this == rhs);
+  }
+
+  UnicodeStringIterator&
+  operator++()
+  {
+    ++i;
+    return *this;
+  }
+
+  UnicodeStringIterator
+  operator+(int32_t v)
+  {
+    return UnicodeStringIterator(s, i + v);
+  }
+
+  private:
+  const icu::UnicodeString* s;
+  int32_t i;
+};
+CXXOPTS_DIAGNOSTIC_POP
+
+inline
+String&
+stringAppend(String&s, String a)
+{
+  return s.append(std::move(a));
+}
+
+inline
+String&
+stringAppend(String& s, std::size_t n, UChar32 c)
+{
+  for (std::size_t i = 0; i != n; ++i)
+  {
+    s.append(c);
+  }
+
+  return s;
+}
+
+template <typename Iterator>
+String&
+stringAppend(String& s, Iterator begin, Iterator end)
+{
+  while (begin != end)
+  {
+    s.append(*begin);
+    ++begin;
+  }
+
+  return s;
+}
+
+inline
+size_t
+stringLength(const String& s)
+{
+  return static_cast<size_t>(s.length());
+}
+
+inline
+std::string
+toUTF8String(const String& s)
+{
+  std::string result;
+  s.toUTF8String(result);
+
+  return result;
+}
+
+inline
+bool
+empty(const String& s)
+{
+  return s.isEmpty();
+}
+
+} // namespace cxxopts
+
+namespace std {
+
+inline
+cxxopts::UnicodeStringIterator
+begin(const icu::UnicodeString& s)
+{
+  return cxxopts::UnicodeStringIterator(&s, 0);
+}
+
+inline
+cxxopts::UnicodeStringIterator
+end(const icu::UnicodeString& s)
+{
+  return cxxopts::UnicodeStringIterator(&s, s.length());
+}
+
+} // namespace std
+
+//ifdef CXXOPTS_USE_UNICODE
+#else
+
+namespace cxxopts {
+
+using String = std::string;
+
+template <typename T>
+T
+toLocalString(T&& t)
+{
+  return std::forward<T>(t);
+}
+
+inline
+std::size_t
+stringLength(const String& s)
+{
+  return s.length();
+}
+
+inline
+String&
+stringAppend(String&s, const String& a)
+{
+  return s.append(a);
+}
+
+inline
+String&
+stringAppend(String& s, std::size_t n, char c)
+{
+  return s.append(n, c);
+}
+
+template <typename Iterator>
+String&
+stringAppend(String& s, Iterator begin, Iterator end)
+{
+  return s.append(begin, end);
+}
+
+template <typename T>
+std::string
+toUTF8String(T&& t)
+{
+  return std::forward<T>(t);
+}
+
+inline
+bool
+empty(const std::string& s)
+{
+  return s.empty();
+}
+
+} // namespace cxxopts
+
+//ifdef CXXOPTS_USE_UNICODE
+#endif
+
+namespace cxxopts {
+
+namespace {
+CXXOPTS_LINKONCE_CONST std::string LQUOTE("\'");
+CXXOPTS_LINKONCE_CONST std::string RQUOTE("\'");
+} // namespace
+
+// GNU GCC with -Weffc++ will issue a warning regarding the upcoming class, we
+// want to silence it: warning: base class 'class
+// std::enable_shared_from_this<cxxopts::Value>' has accessible non-virtual
+// destructor This will be ignored under other compilers like LLVM clang.
+CXXOPTS_DIAGNOSTIC_PUSH
+CXXOPTS_IGNORE_WARNING("-Wnon-virtual-dtor")
+
+// some older versions of GCC warn under this warning
+CXXOPTS_IGNORE_WARNING("-Weffc++")
+class Value : public std::enable_shared_from_this<Value>
+{
+  public:
+
+  virtual ~Value() = default;
+
+  virtual
+  std::shared_ptr<Value>
+  clone() const = 0;
+
+  virtual void
+  add(const std::string& text) const = 0;
+
+  virtual void
+  parse(const std::string& text) const = 0;
+
+  virtual void
+  parse() const = 0;
+
+  virtual bool
+  has_default() const = 0;
+
+  virtual bool
+  is_container() const = 0;
+
+  virtual bool
+  has_implicit() const = 0;
+
+  virtual std::string
+  get_default_value() const = 0;
+
+  virtual std::string
+  get_implicit_value() const = 0;
+
+  virtual std::shared_ptr<Value>
+  default_value(const std::string& value) = 0;
+
+  virtual std::shared_ptr<Value>
+  implicit_value(const std::string& value) = 0;
+
+  virtual std::shared_ptr<Value>
+  no_implicit_value() = 0;
+
+  virtual bool
+  is_boolean() const = 0;
+};
+
+CXXOPTS_DIAGNOSTIC_POP
+
+namespace exceptions {
+
+class exception : public std::exception
+{
+  public:
+  explicit exception(std::string  message)
+  : m_message(std::move(message))
+  {
+  }
+
+  CXXOPTS_NODISCARD
+  const char*
+  what() const noexcept override
+  {
+    return m_message.c_str();
+  }
+
+  private:
+  std::string m_message;
+};
+
+class specification : public exception
+{
+  public:
+
+  explicit specification(const std::string& message)
+  : exception(message)
+  {
+  }
+};
+
+class parsing : public exception
+{
+  public:
+  explicit parsing(const std::string& message)
+  : exception(message)
+  {
+  }
+};
+
+class option_already_exists : public specification
+{
+  public:
+  explicit option_already_exists(const std::string& option)
+  : specification("Option " + LQUOTE + option + RQUOTE + " already exists")
+  {
+  }
+};
+
+class invalid_option_format : public specification
+{
+  public:
+  explicit invalid_option_format(const std::string& format)
+  : specification("Invalid option format " + LQUOTE + format + RQUOTE)
+  {
+  }
+};
+
+class invalid_option_syntax : public parsing {
+  public:
+  explicit invalid_option_syntax(const std::string& text)
+  : parsing("Argument " + LQUOTE + text + RQUOTE +
+            " starts with a - but has incorrect syntax")
+  {
+  }
+};
+
+class no_such_option : public parsing
+{
+  public:
+  explicit no_such_option(const std::string& option)
+  : parsing("Option " + LQUOTE + option + RQUOTE + " does not exist")
+  {
+  }
+};
+
+class missing_argument : public parsing
+{
+  public:
+  explicit missing_argument(const std::string& option)
+  : parsing(
+      "Option " + LQUOTE + option + RQUOTE + " is missing an argument"
+    )
+  {
+  }
+};
+
+class option_requires_argument : public parsing
+{
+  public:
+  explicit option_requires_argument(const std::string& option)
+  : parsing(
+      "Option " + LQUOTE + option + RQUOTE + " requires an argument"
+    )
+  {
+  }
+};
+
+class gratuitous_argument_for_option : public parsing
+{
+  public:
+  gratuitous_argument_for_option
+  (
+    const std::string& option,
+    const std::string& arg
+  )
+  : parsing(
+      "Option " + LQUOTE + option + RQUOTE +
+      " does not take an argument, but argument " +
+      LQUOTE + arg + RQUOTE + " given"
+    )
+  {
+  }
+};
+
+class requested_option_not_present : public parsing
+{
+  public:
+  explicit requested_option_not_present(const std::string& option)
+  : parsing("Option " + LQUOTE + option + RQUOTE + " not present")
+  {
+  }
+};
+
+class option_has_no_value : public exception
+{
+  public:
+  explicit option_has_no_value(const std::string& option)
+  : exception(
+      !option.empty() ?
+      ("Option " + LQUOTE + option + RQUOTE + " has no value") :
+      "Option has no value")
+  {
+  }
+};
+
+class incorrect_argument_type : public parsing
+{
+  public:
+  explicit incorrect_argument_type
+  (
+    const std::string& arg
+  )
+  : parsing(
+      "Argument " + LQUOTE + arg + RQUOTE + " failed to parse"
+    )
+  {
+  }
+};
+
+} // namespace exceptions
+
+
+template <typename T>
+void throw_or_mimic(const std::string& text)
+{
+  static_assert(std::is_base_of<std::exception, T>::value,
+                "throw_or_mimic only works on std::exception and "
+                "deriving classes");
+
+#ifndef CXXOPTS_NO_EXCEPTIONS
+  // If CXXOPTS_NO_EXCEPTIONS is not defined, just throw
+  throw T{text};
+#else
+  // Otherwise manually instantiate the exception, print what() to stderr,
+  // and exit
+  T exception{text};
+  std::cerr << exception.what() << std::endl;
+  std::exit(EXIT_FAILURE);
+#endif
+}
+
+using OptionNames = std::vector<std::string>;
+
+namespace values {
+
+namespace parser_tool {
+
+struct IntegerDesc
+{
+  std::string negative = "";
+  std::string base     = "";
+  std::string value    = "";
+};
+struct ArguDesc {
+  std::string arg_name  = "";
+  bool        grouping  = false;
+  bool        set_value = false;
+  std::string value     = "";
+};
+
+#ifdef CXXOPTS_NO_REGEX
+inline IntegerDesc SplitInteger(const std::string &text)
+{
+  if (text.empty())
+  {
+    throw_or_mimic<exceptions::incorrect_argument_type>(text);
+  }
+  IntegerDesc desc;
+  const char *pdata = text.c_str();
+  if (*pdata == '-')
+  {
+    pdata += 1;
+    desc.negative = "-";
+  }
+  if (strncmp(pdata, "0x", 2) == 0)
+  {
+    pdata += 2;
+    desc.base = "0x";
+  }
+  if (*pdata != '\0')
+  {
+    desc.value = std::string(pdata);
+  }
+  else
+  {
+    throw_or_mimic<exceptions::incorrect_argument_type>(text);
+  }
+  return desc;
+}
+
+inline bool IsTrueText(const std::string &text)
+{
+  const char *pdata = text.c_str();
+  if (*pdata == 't' || *pdata == 'T')
+  {
+    pdata += 1;
+    if (strncmp(pdata, "rue\0", 4) == 0)
+    {
+      return true;
+    }
+  }
+  else if (strncmp(pdata, "1\0", 2) == 0)
+  {
+    return true;
+  }
+  return false;
+}
+
+inline bool IsFalseText(const std::string &text)
+{
+  const char *pdata = text.c_str();
+  if (*pdata == 'f' || *pdata == 'F')
+  {
+    pdata += 1;
+    if (strncmp(pdata, "alse\0", 5) == 0)
+    {
+      return true;
+    }
+  }
+  else if (strncmp(pdata, "0\0", 2) == 0)
+  {
+    return true;
+  }
+  return false;
+}
+
+inline OptionNames split_option_names(const std::string &text)
+{
+  OptionNames split_names;
+
+  std::string::size_type token_start_pos = 0;
+  auto length = text.length();
+
+  if (length == 0)
+  {
+    throw_or_mimic<exceptions::invalid_option_format>(text);
+  }
+
+  while (token_start_pos < length) {
+    const auto &npos = std::string::npos;
+    auto next_non_space_pos = text.find_first_not_of(' ', token_start_pos);
+    if (next_non_space_pos == npos) {
+      throw_or_mimic<exceptions::invalid_option_format>(text);
+    }
+    token_start_pos = next_non_space_pos;
+    auto next_delimiter_pos = text.find(',', token_start_pos);
+    if (next_delimiter_pos == token_start_pos) {
+      throw_or_mimic<exceptions::invalid_option_format>(text);
+    }
+    if (next_delimiter_pos == npos) {
+      next_delimiter_pos = length;
+    }
+    auto token_length = next_delimiter_pos - token_start_pos;
+    // validate the token itself matches the regex /([:alnum:][-_[:alnum:]]*/
+    {
+      const char* option_name_valid_chars =
+        "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+        "abcdefghijklmnopqrstuvwxyz"
+        "0123456789"
+        "_-.?";
+
+      if (!std::isalnum(text[token_start_pos], std::locale::classic()) ||
+          text.find_first_not_of(option_name_valid_chars, token_start_pos) < next_delimiter_pos) {
+        throw_or_mimic<exceptions::invalid_option_format>(text);
+      }
+    }
+    split_names.emplace_back(text.substr(token_start_pos, token_length));
+    token_start_pos = next_delimiter_pos + 1;
+  }
+  return split_names;
+}
+
+inline ArguDesc ParseArgument(const char *arg, bool &matched)
+{
+  ArguDesc argu_desc;
+  const char *pdata = arg;
+  matched = false;
+  if (strncmp(pdata, "--", 2) == 0)
+  {
+    pdata += 2;
+    if (isalnum(*pdata, std::locale::classic()))
+    {
+      argu_desc.arg_name.push_back(*pdata);
+      pdata += 1;
+      while (isalnum(*pdata, std::locale::classic()) || *pdata == '-' || *pdata == '_')
+      {
+        argu_desc.arg_name.push_back(*pdata);
+        pdata += 1;
+      }
+      if (argu_desc.arg_name.length() > 1)
+      {
+        if (*pdata == '=')
+        {
+          argu_desc.set_value = true;
+          pdata += 1;
+          if (*pdata != '\0')
+          {
+            argu_desc.value = std::string(pdata);
+          }
+          matched = true;
+        }
+        else if (*pdata == '\0')
+        {
+          matched = true;
+        }
+      }
+    }
+  }
+  else if (strncmp(pdata, "-", 1) == 0)
+  {
+    pdata += 1;
+    argu_desc.grouping = true;
+    while (isalnum(*pdata, std::locale::classic()))
+    {
+      argu_desc.arg_name.push_back(*pdata);
+      pdata += 1;
+    }
+    matched = !argu_desc.arg_name.empty() && *pdata == '\0';
+  }
+  return argu_desc;
+}
+
+#else  // CXXOPTS_NO_REGEX
+
+namespace {
+CXXOPTS_LINKONCE
+const char* const integer_pattern =
+  "(-)?(0x)?([0-9a-zA-Z]+)|((0x)?0)";
+CXXOPTS_LINKONCE
+const char* const truthy_pattern =
+  "(t|T)(rue)?|1";
+CXXOPTS_LINKONCE
+const char* const falsy_pattern =
+  "(f|F)(alse)?|0";
+CXXOPTS_LINKONCE
+const char* const option_pattern =
+  "--([[:alnum:]][-_[:alnum:]\\.]+)(=(.*))?|-([[:alnum:]].*)";
+CXXOPTS_LINKONCE
+const char* const option_specifier_pattern =
+  "([[:alnum:]][-_[:alnum:]\\.]*)(,[ ]*[[:alnum:]][-_[:alnum:]]*)*";
+CXXOPTS_LINKONCE
+const char* const option_specifier_separator_pattern = ", *";
+
+} // namespace
+
+inline IntegerDesc SplitInteger(const std::string &text)
+{
+  static const std::basic_regex<char> integer_matcher(integer_pattern);
+
+  std::smatch match;
+  std::regex_match(text, match, integer_matcher);
+
+  if (match.length() == 0)
+  {
+    throw_or_mimic<exceptions::incorrect_argument_type>(text);
+  }
+
+  IntegerDesc desc;
+  desc.negative = match[1];
+  desc.base = match[2];
+  desc.value = match[3];
+
+  if (match.length(4) > 0)
+  {
+    desc.base = match[5];
+    desc.value = "0";
+    return desc;
+  }
+
+  return desc;
+}
+
+inline bool IsTrueText(const std::string &text)
+{
+  static const std::basic_regex<char> truthy_matcher(truthy_pattern);
+  std::smatch result;
+  std::regex_match(text, result, truthy_matcher);
+  return !result.empty();
+}
+
+inline bool IsFalseText(const std::string &text)
+{
+  static const std::basic_regex<char> falsy_matcher(falsy_pattern);
+  std::smatch result;
+  std::regex_match(text, result, falsy_matcher);
+  return !result.empty();
+}
+
+// Gets the option names specified via a single, comma-separated string,
+// and returns the separate, space-discarded, non-empty names
+// (without considering which or how many are single-character)
+inline OptionNames split_option_names(const std::string &text)
+{
+  static const std::basic_regex<char> option_specifier_matcher(option_specifier_pattern);
+  if (!std::regex_match(text.c_str(), option_specifier_matcher))
+  {
+    throw_or_mimic<exceptions::invalid_option_format>(text);
+  }
+
+  OptionNames split_names;
+
+  static const std::basic_regex<char> option_specifier_separator_matcher(option_specifier_separator_pattern);
+  constexpr int use_non_matches { -1 };
+  auto token_iterator = std::sregex_token_iterator(
+    text.begin(), text.end(), option_specifier_separator_matcher, use_non_matches);
+  std::copy(token_iterator, std::sregex_token_iterator(), std::back_inserter(split_names));
+  return split_names;
+}
+
+inline ArguDesc ParseArgument(const char *arg, bool &matched)
+{
+  static const std::basic_regex<char> option_matcher(option_pattern);
+  std::match_results<const char*> result;
+  std::regex_match(arg, result, option_matcher);
+  matched = !result.empty();
+
+  ArguDesc argu_desc;
+  if (matched) {
+    argu_desc.arg_name = result[1].str();
+    argu_desc.set_value = result[2].length() > 0;
+    argu_desc.value = result[3].str();
+    if (result[4].length() > 0)
+    {
+      argu_desc.grouping = true;
+      argu_desc.arg_name = result[4].str();
+    }
+  }
+
+  return argu_desc;
+}
+
+#endif  // CXXOPTS_NO_REGEX
+#undef CXXOPTS_NO_REGEX
+} // namespace parser_tool
+
+namespace detail {
+
+template <typename T, bool B>
+struct SignedCheck;
+
+template <typename T>
+struct SignedCheck<T, true>
+{
+  template <typename U>
+  void
+  operator()(bool negative, U u, const std::string& text)
+  {
+    if (negative)
+    {
+      if (u > static_cast<U>((std::numeric_limits<T>::min)()))
+      {
+        throw_or_mimic<exceptions::incorrect_argument_type>(text);
+      }
+    }
+    else
+    {
+      if (u > static_cast<U>((std::numeric_limits<T>::max)()))
+      {
+        throw_or_mimic<exceptions::incorrect_argument_type>(text);
+      }
+    }
+  }
+};
+
+template <typename T>
+struct SignedCheck<T, false>
+{
+  template <typename U>
+  void
+  operator()(bool, U, const std::string&) const {}
+};
+
+template <typename T, typename U>
+void
+check_signed_range(bool negative, U value, const std::string& text)
+{
+  SignedCheck<T, std::numeric_limits<T>::is_signed>()(negative, value, text);
+}
+
+} // namespace detail
+
+template <typename R, typename T>
+void
+checked_negate(R& r, T&& t, const std::string&, std::true_type)
+{
+  // if we got to here, then `t` is a positive number that fits into
+  // `R`. So to avoid MSVC C4146, we first cast it to `R`.
+  // See https://github.com/jarro2783/cxxopts/issues/62 for more details.
+  r = static_cast<R>(-static_cast<R>(t-1)-1);
+}
+
+template <typename R, typename T>
+void
+checked_negate(R&, T&&, const std::string& text, std::false_type)
+{
+  throw_or_mimic<exceptions::incorrect_argument_type>(text);
+}
+
+template <typename T>
+void
+integer_parser(const std::string& text, T& value)
+{
+  parser_tool::IntegerDesc int_desc = parser_tool::SplitInteger(text);
+
+  using US = typename std::make_unsigned<T>::type;
+  constexpr bool is_signed = std::numeric_limits<T>::is_signed;
+
+  const bool          negative    = int_desc.negative.length() > 0;
+  const uint8_t       base        = int_desc.base.length() > 0 ? 16 : 10;
+  const std::string & value_match = int_desc.value;
+
+  US result = 0;
+
+  for (char ch : value_match)
+  {
+    US digit = 0;
+
+    if (ch >= '0' && ch <= '9')
+    {
+      digit = static_cast<US>(ch - '0');
+    }
+    else if (base == 16 && ch >= 'a' && ch <= 'f')
+    {
+      digit = static_cast<US>(ch - 'a' + 10);
+    }
+    else if (base == 16 && ch >= 'A' && ch <= 'F')
+    {
+      digit = static_cast<US>(ch - 'A' + 10);
+    }
+    else
+    {
+      throw_or_mimic<exceptions::incorrect_argument_type>(text);
+    }
+
+    US limit = 0;
+    if (negative)
+    {
+      limit = static_cast<US>(std::abs(static_cast<intmax_t>((std::numeric_limits<T>::min)())));
+    }
+    else
+    {
+      limit = (std::numeric_limits<T>::max)();
+    }
+
+    if (base != 0 && result > limit / base)
+    {
+      throw_or_mimic<exceptions::incorrect_argument_type>(text);
+    }
+    if (result * base > limit - digit)
+    {
+      throw_or_mimic<exceptions::incorrect_argument_type>(text);
+    }
+
+    result = static_cast<US>(result * base + digit);
+  }
+
+  detail::check_signed_range<T>(negative, result, text);
+
+  if (negative)
+  {
+    checked_negate<T>(value, result, text, std::integral_constant<bool, is_signed>());
+  }
+  else
+  {
+    value = static_cast<T>(result);
+  }
+}
+
+template <typename T>
+void stringstream_parser(const std::string& text, T& value)
+{
+  std::stringstream in(text);
+  in >> value;
+  if (!in) {
+    throw_or_mimic<exceptions::incorrect_argument_type>(text);
+  }
+}
+
+template <typename T,
+         typename std::enable_if<std::is_integral<T>::value>::type* = nullptr
+         >
+void parse_value(const std::string& text, T& value)
+{
+    integer_parser(text, value);
+}
+
+inline
+void
+parse_value(const std::string& text, bool& value)
+{
+  if (parser_tool::IsTrueText(text))
+  {
+    value = true;
+    return;
+  }
+
+  if (parser_tool::IsFalseText(text))
+  {
+    value = false;
+    return;
+  }
+
+  throw_or_mimic<exceptions::incorrect_argument_type>(text);
+}
+
+inline
+void
+parse_value(const std::string& text, std::string& value)
+{
+  value = text;
+}
+
+// The fallback parser. It uses the stringstream parser to parse all types
+// that have not been overloaded explicitly.  It has to be placed in the
+// source code before all other more specialized templates.
+template <typename T,
+         typename std::enable_if<!std::is_integral<T>::value>::type* = nullptr
+         >
+void
+parse_value(const std::string& text, T& value) {
+  stringstream_parser(text, value);
+}
+
+#ifdef CXXOPTS_HAS_OPTIONAL
+template <typename T>
+void
+parse_value(const std::string& text, std::optional<T>& value)
+{
+  T result;
+  parse_value(text, result);
+  value = std::move(result);
+}
+#endif
+
+#ifdef CXXOPTS_HAS_FILESYSTEM
+inline
+void
+parse_value(const std::string& text, std::filesystem::path& value)
+{
+  value.assign(text);
+}
+#endif
+
+inline
+void parse_value(const std::string& text, char& c)
+{
+  if (text.length() != 1)
+  {
+    throw_or_mimic<exceptions::incorrect_argument_type>(text);
+  }
+
+  c = text[0];
+}
+
+template<typename T> void add_value(const std::string& text, std::vector<T>& value);
+
+template <typename T>
+void
+parse_value(const std::string& text, std::vector<T>& value)
+{
+  if (text.empty()) {
+    return;
+  }
+  std::stringstream in(text);
+  std::string token;
+  while(!in.eof() && std::getline(in, token, CXXOPTS_VECTOR_DELIMITER)) {
+    add_value(token, value);
+  }
+}
+
+template <typename T>
+void
+add_value(const std::string& text, T& value)
+{
+  parse_value(text, value);
+}
+
+template <typename T>
+void
+add_value(const std::string& text, std::vector<T>& value)
+{
+  T v;
+  add_value(text, v);
+  value.emplace_back(std::move(v));
+}
+
+template <typename T>
+struct type_is_container
+{
+  static constexpr bool value = false;
+};
+
+template <typename T>
+struct type_is_container<std::vector<T>>
+{
+  static constexpr bool value = true;
+};
+
+template <typename T>
+class abstract_value : public Value
+{
+  using Self = abstract_value<T>;
+
+  public:
+  abstract_value()
+  : m_result(std::make_shared<T>())
+  , m_store(m_result.get())
+  {
+  }
+
+  explicit abstract_value(T* t)
+  : m_store(t)
+  {
+  }
+
+  ~abstract_value() override = default;
+
+  abstract_value& operator=(const abstract_value&) = default;
+
+  abstract_value(const abstract_value& rhs)
+  {
+    if (rhs.m_result)
+    {
+      m_result = std::make_shared<T>();
+      m_store = m_result.get();
+    }
+    else
+    {
+      m_store = rhs.m_store;
+    }
+
+    m_default = rhs.m_default;
+    m_implicit = rhs.m_implicit;
+    m_default_value = rhs.m_default_value;
+    m_implicit_value = rhs.m_implicit_value;
+  }
+
+  void
+  add(const std::string& text) const override
+  {
+    add_value(text, *m_store);
+  }
+
+  void
+  parse(const std::string& text) const override
+  {
+    parse_value(text, *m_store);
+  }
+
+  bool
+  is_container() const override
+  {
+    return type_is_container<T>::value;
+  }
+
+  void
+  parse() const override
+  {
+    parse_value(m_default_value, *m_store);
+  }
+
+  bool
+  has_default() const override
+  {
+    return m_default;
+  }
+
+  bool
+  has_implicit() const override
+  {
+    return m_implicit;
+  }
+
+  std::shared_ptr<Value>
+  default_value(const std::string& value) override
+  {
+    m_default = true;
+    m_default_value = value;
+    return shared_from_this();
+  }
+
+  std::shared_ptr<Value>
+  implicit_value(const std::string& value) override
+  {
+    m_implicit = true;
+    m_implicit_value = value;
+    return shared_from_this();
+  }
+
+  std::shared_ptr<Value>
+  no_implicit_value() override
+  {
+    m_implicit = false;
+    return shared_from_this();
+  }
+
+  std::string
+  get_default_value() const override
+  {
+    return m_default_value;
+  }
+
+  std::string
+  get_implicit_value() const override
+  {
+    return m_implicit_value;
+  }
+
+  bool
+  is_boolean() const override
+  {
+    return std::is_same<T, bool>::value;
+  }
+
+  const T&
+  get() const
+  {
+    if (m_store == nullptr)
+    {
+      return *m_result;
+    }
+    return *m_store;
+  }
+
+  protected:
+  std::shared_ptr<T> m_result{};
+  T* m_store{};
+
+  bool m_default = false;
+  bool m_implicit = false;
+
+  std::string m_default_value{};
+  std::string m_implicit_value{};
+};
+
+template <typename T>
+class standard_value : public abstract_value<T>
+{
+  public:
+  using abstract_value<T>::abstract_value;
+
+  CXXOPTS_NODISCARD
+  std::shared_ptr<Value>
+  clone() const override
+  {
+    return std::make_shared<standard_value<T>>(*this);
+  }
+};
+
+template <>
+class standard_value<bool> : public abstract_value<bool>
+{
+  public:
+  ~standard_value() override = default;
+
+  standard_value()
+  {
+    set_default_and_implicit();
+  }
+
+  explicit standard_value(bool* b)
+  : abstract_value(b)
+  {
+    m_implicit = true;
+    m_implicit_value = "true";
+  }
+
+  std::shared_ptr<Value>
+  clone() const override
+  {
+    return std::make_shared<standard_value<bool>>(*this);
+  }
+
+  private:
+
+  void
+  set_default_and_implicit()
+  {
+    m_default = true;
+    m_default_value = "false";
+    m_implicit = true;
+    m_implicit_value = "true";
+  }
+};
+
+} // namespace values
+
+template <typename T>
+std::shared_ptr<Value>
+value()
+{
+  return std::make_shared<values::standard_value<T>>();
+}
+
+template <typename T>
+std::shared_ptr<Value>
+value(T& t)
+{
+  return std::make_shared<values::standard_value<T>>(&t);
+}
+
+class OptionAdder;
+
+CXXOPTS_NODISCARD
+inline
+const std::string&
+first_or_empty(const OptionNames& long_names)
+{
+  static const std::string empty{""};
+  return long_names.empty() ? empty : long_names.front();
+}
+
+class OptionDetails
+{
+  public:
+  OptionDetails
+  (
+    std::string short_,
+    OptionNames long_,
+    String desc,
+    std::shared_ptr<const Value> val
+  )
+  : m_short(std::move(short_))
+  , m_long(std::move(long_))
+  , m_desc(std::move(desc))
+  , m_value(std::move(val))
+  , m_count(0)
+  {
+    m_hash = std::hash<std::string>{}(first_long_name() + m_short);
+  }
+
+  OptionDetails(const OptionDetails& rhs)
+  : m_desc(rhs.m_desc)
+  , m_value(rhs.m_value->clone())
+  , m_count(rhs.m_count)
+  {
+  }
+
+  OptionDetails(OptionDetails&& rhs) = default;
+
+  CXXOPTS_NODISCARD
+  const String&
+  description() const
+  {
+    return m_desc;
+  }
+
+  CXXOPTS_NODISCARD
+  const Value&
+  value() const {
+      return *m_value;
+  }
+
+  CXXOPTS_NODISCARD
+  std::shared_ptr<Value>
+  make_storage() const
+  {
+    return m_value->clone();
+  }
+
+  CXXOPTS_NODISCARD
+  const std::string&
+  short_name() const
+  {
+    return m_short;
+  }
+
+  CXXOPTS_NODISCARD
+  const std::string&
+  first_long_name() const
+  {
+    return first_or_empty(m_long);
+  }
+
+  CXXOPTS_NODISCARD
+  const std::string&
+  essential_name() const
+  {
+    return m_long.empty() ? m_short : m_long.front();
+  }
+
+  CXXOPTS_NODISCARD
+  const OptionNames &
+  long_names() const
+  {
+    return m_long;
+  }
+
+  std::size_t
+  hash() const
+  {
+    return m_hash;
+  }
+
+  private:
+  std::string m_short{};
+  OptionNames m_long{};
+  String m_desc{};
+  std::shared_ptr<const Value> m_value{};
+  int m_count;
+
+  std::size_t m_hash{};
+};
+
+struct HelpOptionDetails
+{
+  std::string s;
+  OptionNames l;
+  String desc;
+  bool has_default;
+  std::string default_value;
+  bool has_implicit;
+  std::string implicit_value;
+  std::string arg_help;
+  bool is_container;
+  bool is_boolean;
+};
+
+struct HelpGroupDetails
+{
+  std::string name{};
+  std::string description{};
+  std::vector<HelpOptionDetails> options{};
+};
+
+class OptionValue
+{
+  public:
+  void
+  add
+  (
+    const std::shared_ptr<const OptionDetails>& details,
+    const std::string& text
+  )
+  {
+    ensure_value(details);
+    ++m_count;
+    m_value->add(text);
+    m_long_names = &details->long_names();
+  }
+
+  void
+  parse
+  (
+    const std::shared_ptr<const OptionDetails>& details,
+    const std::string& text
+  )
+  {
+    ensure_value(details);
+    ++m_count;
+    m_value->parse(text);
+    m_long_names = &details->long_names();
+  }
+
+  void
+  parse_default(const std::shared_ptr<const OptionDetails>& details)
+  {
+    ensure_value(details);
+    m_default = true;
+    m_long_names = &details->long_names();
+    m_value->parse();
+  }
+
+  void
+  parse_no_value(const std::shared_ptr<const OptionDetails>& details)
+  {
+    m_long_names = &details->long_names();
+  }
+
+#if defined(CXXOPTS_NULL_DEREF_IGNORE)
+CXXOPTS_DIAGNOSTIC_PUSH
+CXXOPTS_IGNORE_WARNING("-Wnull-dereference")
+#endif
+
+  CXXOPTS_NODISCARD
+  std::size_t
+  count() const noexcept
+  {
+    return m_count;
+  }
+
+#if defined(CXXOPTS_NULL_DEREF_IGNORE)
+CXXOPTS_DIAGNOSTIC_POP
+#endif
+
+  // TODO: maybe default options should count towards the number of arguments
+  CXXOPTS_NODISCARD
+  bool
+  has_default() const noexcept
+  {
+    return m_default;
+  }
+
+  template <typename T>
+  const T&
+  as() const
+  {
+    if (m_value == nullptr) {
+        throw_or_mimic<exceptions::option_has_no_value>(
+            m_long_names == nullptr ? "" : first_or_empty(*m_long_names));
+    }
+
+    return CXXOPTS_RTTI_CAST<const values::standard_value<T>&>(*m_value).get();
+  }
+
+#ifdef CXXOPTS_HAS_OPTIONAL
+  template <typename T>
+  std::optional<T>
+  as_optional() const
+  {
+    if (m_value == nullptr) {
+      return std::nullopt;
+    }
+    return as<T>();
+  }
+#endif
+
+  private:
+  void
+  ensure_value(const std::shared_ptr<const OptionDetails>& details)
+  {
+    if (m_value == nullptr)
+    {
+      m_value = details->make_storage();
+    }
+  }
+
+
+  const OptionNames * m_long_names = nullptr;
+  // Holding this pointer is safe, since OptionValue's only exist in key-value pairs,
+  // where the key has the string we point to.
+  std::shared_ptr<Value> m_value{};
+  std::size_t m_count = 0;
+  bool m_default = false;
+};
+
+class KeyValue
+{
+  public:
+  KeyValue(std::string key_, std::string value_) noexcept
+  : m_key(std::move(key_))
+  , m_value(std::move(value_))
+  {
+  }
+
+  CXXOPTS_NODISCARD
+  const std::string&
+  key() const
+  {
+    return m_key;
+  }
+
+  CXXOPTS_NODISCARD
+  const std::string&
+  value() const
+  {
+    return m_value;
+  }
+
+  template <typename T>
+  T
+  as() const
+  {
+    T result;
+    values::parse_value(m_value, result);
+    return result;
+  }
+
+  private:
+  std::string m_key;
+  std::string m_value;
+};
+
+using ParsedHashMap = std::unordered_map<std::size_t, OptionValue>;
+using NameHashMap = std::unordered_map<std::string, std::size_t>;
+
+class ParseResult
+{
+  public:
+  class Iterator
+  {
+    public:
+    using iterator_category = std::forward_iterator_tag;
+    using value_type = KeyValue;
+    using difference_type = void;
+    using pointer = const KeyValue*;
+    using reference = const KeyValue&;
+
+    Iterator() = default;
+    Iterator(const Iterator&) = default;
+
+// GCC complains about m_iter not being initialised in the member
+// initializer list
+CXXOPTS_DIAGNOSTIC_PUSH
+CXXOPTS_IGNORE_WARNING("-Weffc++")
+    Iterator(const ParseResult *pr, bool end=false)
+    : m_pr(pr)
+    {
+      if (end)
+      {
+        m_sequential = false;
+        m_iter = m_pr->m_defaults.end();
+      }
+      else
+      {
+        m_sequential = true;
+        m_iter = m_pr->m_sequential.begin();
+
+        if (m_iter == m_pr->m_sequential.end())
+        {
+          m_sequential = false;
+          m_iter = m_pr->m_defaults.begin();
+        }
+      }
+    }
+CXXOPTS_DIAGNOSTIC_POP
+
+    Iterator& operator++()
+    {
+      ++m_iter;
+      if(m_sequential && m_iter == m_pr->m_sequential.end())
+      {
+        m_sequential = false;
+        m_iter = m_pr->m_defaults.begin();
+        return *this;
+      }
+      return *this;
+    }
+
+    Iterator operator++(int)
+    {
+      Iterator retval = *this;
+      ++(*this);
+      return retval;
+    }
+
+    bool operator==(const Iterator& other) const
+    {
+      return (m_sequential == other.m_sequential) && (m_iter == other.m_iter);
+    }
+
+    bool operator!=(const Iterator& other) const
+    {
+      return !(*this == other);
+    }
+
+    const KeyValue& operator*()
+    {
+      return *m_iter;
+    }
+
+    const KeyValue* operator->()
+    {
+      return m_iter.operator->();
+    }
+
+    private:
+    const ParseResult* m_pr;
+    std::vector<KeyValue>::const_iterator m_iter;
+    bool m_sequential = true;
+  };
+
+  ParseResult() = default;
+  ParseResult(const ParseResult&) = default;
+
+  ParseResult(NameHashMap&& keys, ParsedHashMap&& values, std::vector<KeyValue> sequential,
+          std::vector<KeyValue> default_opts, std::vector<std::string>&& unmatched_args)
+  : m_keys(std::move(keys))
+  , m_values(std::move(values))
+  , m_sequential(std::move(sequential))
+  , m_defaults(std::move(default_opts))
+  , m_unmatched(std::move(unmatched_args))
+  {
+  }
+
+  ParseResult& operator=(ParseResult&&) = default;
+  ParseResult& operator=(const ParseResult&) = default;
+
+  Iterator
+  begin() const
+  {
+    return Iterator(this);
+  }
+
+  Iterator
+  end() const
+  {
+    return Iterator(this, true);
+  }
+
+  std::size_t
+  count(const std::string& o) const
+  {
+    auto iter = m_keys.find(o);
+    if (iter == m_keys.end())
+    {
+      return 0;
+    }
+
+    auto viter = m_values.find(iter->second);
+
+    if (viter == m_values.end())
+    {
+      return 0;
+    }
+
+    return viter->second.count();
+  }
+
+  bool
+  contains(const std::string& o) const
+  {
+    return static_cast<bool>(count(o));
+  }
+
+  const OptionValue&
+  operator[](const std::string& option) const
+  {
+    auto iter = m_keys.find(option);
+
+    if (iter == m_keys.end())
+    {
+      throw_or_mimic<exceptions::requested_option_not_present>(option);
+    }
+
+    auto viter = m_values.find(iter->second);
+
+    if (viter == m_values.end())
+    {
+      throw_or_mimic<exceptions::requested_option_not_present>(option);
+    }
+
+    return viter->second;
+  }
+
+#ifdef CXXOPTS_HAS_OPTIONAL
+  template <typename T>
+  std::optional<T>
+  as_optional(const std::string& option) const
+  {
+    auto iter = m_keys.find(option);
+    if (iter != m_keys.end())
+    {
+      auto viter = m_values.find(iter->second);
+      if (viter != m_values.end())
+      {
+        return viter->second.as_optional<T>();
+      }
+    }
+    return std::nullopt;
+  }
+#endif
+
+  const std::vector<KeyValue>&
+  arguments() const
+  {
+    return m_sequential;
+  }
+
+  const std::vector<std::string>&
+  unmatched() const
+  {
+    return m_unmatched;
+  }
+
+  const std::vector<KeyValue>&
+  defaults() const
+  {
+    return m_defaults;
+  }
+
+  const std::string
+  arguments_string() const
+  {
+    std::string result;
+    for(const auto& kv: m_sequential)
+    {
+      result += kv.key() + " = " + kv.value() + "\n";
+    }
+    for(const auto& kv: m_defaults)
+    {
+      result += kv.key() + " = " + kv.value() + " " + "(default)" + "\n";
+    }
+    return result;
+  }
+
+  private:
+  NameHashMap m_keys{};
+  ParsedHashMap m_values{};
+  std::vector<KeyValue> m_sequential{};
+  std::vector<KeyValue> m_defaults{};
+  std::vector<std::string> m_unmatched{};
+};
+
+struct Option
+{
+  Option
+  (
+    std::string opts,
+    std::string desc,
+    std::shared_ptr<const Value>  value = ::cxxopts::value<bool>(),
+    std::string arg_help = ""
+  )
+  : opts_(std::move(opts))
+  , desc_(std::move(desc))
+  , value_(std::move(value))
+  , arg_help_(std::move(arg_help))
+  {
+  }
+
+  std::string opts_;
+  std::string desc_;
+  std::shared_ptr<const Value> value_;
+  std::string arg_help_;
+};
+
+using OptionMap = std::unordered_map<std::string, std::shared_ptr<OptionDetails>>;
+using PositionalList = std::vector<std::string>;
+using PositionalListIterator = PositionalList::const_iterator;
+
+class OptionParser
+{
+  public:
+  OptionParser(const OptionMap& options, const PositionalList& positional, bool allow_unrecognised)
+  : m_options(options)
+  , m_positional(positional)
+  , m_allow_unrecognised(allow_unrecognised)
+  {
+  }
+
+  ParseResult
+  parse(int argc, const char* const* argv);
+
+  bool
+  consume_positional(const std::string& a, PositionalListIterator& next);
+
+  void
+  checked_parse_arg
+  (
+    int argc,
+    const char* const* argv,
+    int& current,
+    const std::shared_ptr<OptionDetails>& value,
+    const std::string& name
+  );
+
+  void
+  add_to_option(const std::shared_ptr<OptionDetails>& value, const std::string& arg);
+
+  void
+  parse_option
+  (
+    const std::shared_ptr<OptionDetails>& value,
+    const std::string& name,
+    const std::string& arg = ""
+  );
+
+  void
+  parse_default(const std::shared_ptr<OptionDetails>& details);
+
+  void
+  parse_no_value(const std::shared_ptr<OptionDetails>& details);
+
+  private:
+
+  void finalise_aliases();
+
+  const OptionMap& m_options;
+  const PositionalList& m_positional;
+
+  std::vector<KeyValue> m_sequential{};
+  std::vector<KeyValue> m_defaults{};
+  bool m_allow_unrecognised;
+
+  ParsedHashMap m_parsed{};
+  NameHashMap m_keys{};
+};
+
+class Options
+{
+  public:
+
+  explicit Options(std::string program_name, std::string help_string = "")
+  : m_program(std::move(program_name))
+  , m_help_string(toLocalString(std::move(help_string)))
+  , m_custom_help("[OPTION...]")
+  , m_positional_help("positional parameters")
+  , m_show_positional(false)
+  , m_allow_unrecognised(false)
+  , m_width(76)
+  , m_tab_expansion(false)
+  , m_options(std::make_shared<OptionMap>())
+  {
+  }
+
+  Options&
+  positional_help(std::string help_text)
+  {
+    m_positional_help = std::move(help_text);
+    return *this;
+  }
+
+  Options&
+  custom_help(std::string help_text)
+  {
+    m_custom_help = std::move(help_text);
+    return *this;
+  }
+
+  Options&
+  show_positional_help()
+  {
+    m_show_positional = true;
+    return *this;
+  }
+
+  Options&
+  allow_unrecognised_options()
+  {
+    m_allow_unrecognised = true;
+    return *this;
+  }
+
+  Options&
+  set_width(std::size_t width)
+  {
+    m_width = width;
+    return *this;
+  }
+
+  Options&
+  set_tab_expansion(bool expansion=true)
+  {
+    m_tab_expansion = expansion;
+    return *this;
+  }
+
+  ParseResult
+  parse(int argc, const char* const* argv);
+
+  OptionAdder
+  add_options(std::string group = "");
+
+  void
+  add_options
+  (
+    const std::string& group,
+    std::initializer_list<Option> options
+  );
+
+  void
+  add_option
+  (
+    const std::string& group,
+    const Option& option
+  );
+
+  void
+  add_option
+  (
+    const std::string& group,
+    const std::string& s,
+    const OptionNames& l,
+    std::string desc,
+    const std::shared_ptr<const Value>& value,
+    std::string arg_help
+  );
+
+  void
+  add_option
+  (
+    const std::string& group,
+    const std::string& short_name,
+    const std::string& single_long_name,
+    std::string desc,
+    const std::shared_ptr<const Value>& value,
+    std::string arg_help
+  )
+  {
+    OptionNames long_names;
+    long_names.emplace_back(single_long_name);
+    add_option(group, short_name, long_names, desc, value, arg_help);
+  }
+
+  //parse positional arguments into the given option
+  void
+  parse_positional(std::string option);
+
+  void
+  parse_positional(std::vector<std::string> options);
+
+  void
+  parse_positional(std::initializer_list<std::string> options);
+
+  template <typename Iterator>
+  void
+  parse_positional(Iterator begin, Iterator end) {
+    parse_positional(std::vector<std::string>{begin, end});
+  }
+
+  std::string
+  help(const std::vector<std::string>& groups = {}, bool print_usage=true) const;
+
+  std::vector<std::string>
+  groups() const;
+
+  const HelpGroupDetails&
+  group_help(const std::string& group) const;
+
+  const std::string& program() const
+  {
+    return m_program;
+  }
+
+  private:
+
+  void
+  add_one_option
+  (
+    const std::string& option,
+    const std::shared_ptr<OptionDetails>& details
+  );
+
+  String
+  help_one_group(const std::string& group) const;
+
+  void
+  generate_group_help
+  (
+    String& result,
+    const std::vector<std::string>& groups
+  ) const;
+
+  void
+  generate_all_groups_help(String& result) const;
+
+  std::string m_program{};
+  String m_help_string{};
+  std::string m_custom_help{};
+  std::string m_positional_help{};
+  bool m_show_positional;
+  bool m_allow_unrecognised;
+  std::size_t m_width;
+  bool m_tab_expansion;
+
+  std::shared_ptr<OptionMap> m_options;
+  std::vector<std::string> m_positional{};
+  std::unordered_set<std::string> m_positional_set{};
+
+  //mapping from groups to help options
+  std::vector<std::string> m_group{};
+  std::map<std::string, HelpGroupDetails> m_help{};
+};
+
+class OptionAdder
+{
+  public:
+
+  OptionAdder(Options& options, std::string group)
+  : m_options(options), m_group(std::move(group))
+  {
+  }
+
+  OptionAdder&
+  operator()
+  (
+    const std::string& opts,
+    const std::string& desc,
+    const std::shared_ptr<const Value>& value
+      = ::cxxopts::value<bool>(),
+    std::string arg_help = ""
+  );
+
+  private:
+  Options& m_options;
+  std::string m_group;
+};
+
+namespace {
+constexpr std::size_t OPTION_LONGEST = 30;
+constexpr std::size_t OPTION_DESC_GAP = 2;
+
+String
+format_option
+(
+  const HelpOptionDetails& o
+)
+{
+  const auto& s = o.s;
+  const auto& l = first_or_empty(o.l);
+
+  String result = "  ";
+
+  if (!s.empty())
+  {
+    result += "-" + toLocalString(s);
+    if (!l.empty())
+    {
+      result += ",";
+    }
+  }
+  else
+  {
+    result += "   ";
+  }
+
+  if (!l.empty())
+  {
+    result += " --" + toLocalString(l);
+  }
+
+  auto arg = !o.arg_help.empty() ? toLocalString(o.arg_help) : "arg";
+
+  if (!o.is_boolean)
+  {
+    if (o.has_implicit)
+    {
+      result += " [=" + arg + "(=" + toLocalString(o.implicit_value) + ")]";
+    }
+    else
+    {
+      result += " " + arg;
+    }
+  }
+
+  return result;
+}
+
+String
+format_description
+(
+  const HelpOptionDetails& o,
+  std::size_t start,
+  std::size_t allowed,
+  bool tab_expansion
+)
+{
+  auto desc = o.desc;
+
+  if (o.has_default && (!o.is_boolean || o.default_value != "false"))
+  {
+    if(!o.default_value.empty())
+    {
+      desc += toLocalString(" (default: " + o.default_value + ")");
+    }
+    else
+    {
+      desc += toLocalString(" (default: \"\")");
+    }
+  }
+
+  String result;
+
+  if (tab_expansion)
+  {
+    String desc2;
+    auto size = std::size_t{ 0 };
+    for (auto c = std::begin(desc); c != std::end(desc); ++c)
+    {
+      if (*c == '\n')
+      {
+        desc2 += *c;
+        size = 0;
+      }
+      else if (*c == '\t')
+      {
+        auto skip = 8 - size % 8;
+        stringAppend(desc2, skip, ' ');
+        size += skip;
+      }
+      else
+      {
+        desc2 += *c;
+        ++size;
+      }
+    }
+    desc = desc2;
+  }
+
+  desc += " ";
+
+  auto current = std::begin(desc);
+  auto previous = current;
+  auto startLine = current;
+  auto lastSpace = current;
+
+  auto size = std::size_t{};
+
+  bool appendNewLine;
+  bool onlyWhiteSpace = true;
+
+  while (current != std::end(desc))
+  {
+    appendNewLine = false;
+    if (*previous == ' ' || *previous == '\t')
+    {
+      lastSpace = current;
+    }
+    if (*current != ' ' && *current != '\t')
+    {
+      onlyWhiteSpace = false;
+    }
+
+    while (*current == '\n')
+    {
+      previous = current;
+      ++current;
+      appendNewLine = true;
+    }
+
+    if (!appendNewLine && size >= allowed)
+    {
+      if (lastSpace != startLine)
+      {
+        current = lastSpace;
+        previous = current;
+      }
+      appendNewLine = true;
+    }
+
+    if (appendNewLine)
+    {
+      stringAppend(result, startLine, current);
+      startLine = current;
+      lastSpace = current;
+
+      if (*previous != '\n')
+      {
+        stringAppend(result, "\n");
+      }
+
+      stringAppend(result, start, ' ');
+
+      if (*previous != '\n')
+      {
+        stringAppend(result, lastSpace, current);
+      }
+
+      onlyWhiteSpace = true;
+      size = 0;
+    }
+
+    previous = current;
+    ++current;
+    ++size;
+  }
+
+  //append whatever is left but ignore whitespace
+  if (!onlyWhiteSpace)
+  {
+    stringAppend(result, startLine, previous);
+  }
+
+  return result;
+}
+
+} // namespace
+
+inline
+void
+Options::add_options
+(
+  const std::string &group,
+  std::initializer_list<Option> options
+)
+{
+ OptionAdder option_adder(*this, group);
+ for (const auto &option: options)
+ {
+   option_adder(option.opts_, option.desc_, option.value_, option.arg_help_);
+ }
+}
+
+inline
+OptionAdder
+Options::add_options(std::string group)
+{
+  return OptionAdder(*this, std::move(group));
+}
+
+inline
+OptionAdder&
+OptionAdder::operator()
+(
+  const std::string& opts,
+  const std::string& desc,
+  const std::shared_ptr<const Value>& value,
+  std::string arg_help
+)
+{
+  OptionNames option_names = values::parser_tool::split_option_names(opts);
+    // Note: All names will be non-empty; but we must separate the short
+    // (length-1) and longer names
+  std::string short_name {""};
+  auto first_short_name_iter =
+    std::partition(option_names.begin(), option_names.end(),
+      [&](const std::string& name) { return name.length() > 1; }
+    );
+  auto num_length_1_names = (option_names.end() - first_short_name_iter);
+  switch(num_length_1_names) {
+  case 1:
+    short_name = *first_short_name_iter;
+    option_names.erase(first_short_name_iter);
+    CXXOPTS_FALLTHROUGH;
+  case 0:
+    break;
+  default:
+    throw_or_mimic<exceptions::invalid_option_format>(opts);
+  };
+
+  m_options.add_option
+  (
+    m_group,
+    short_name,
+    option_names,
+    desc,
+    value,
+    std::move(arg_help)
+  );
+
+  return *this;
+}
+
+inline
+void
+OptionParser::parse_default(const std::shared_ptr<OptionDetails>& details)
+{
+  // TODO: remove the duplicate code here
+  auto& store = m_parsed[details->hash()];
+  store.parse_default(details);
+  m_defaults.emplace_back(details->essential_name(), details->value().get_default_value());
+}
+
+inline
+void
+OptionParser::parse_no_value(const std::shared_ptr<OptionDetails>& details)
+{
+  auto& store = m_parsed[details->hash()];
+  store.parse_no_value(details);
+}
+
+inline
+void
+OptionParser::parse_option
+(
+  const std::shared_ptr<OptionDetails>& value,
+  const std::string& /*name*/,
+  const std::string& arg
+)
+{
+  auto hash = value->hash();
+  auto& result = m_parsed[hash];
+  result.parse(value, arg);
+
+  m_sequential.emplace_back(value->essential_name(), arg);
+}
+
+inline
+void
+OptionParser::checked_parse_arg
+(
+  int argc,
+  const char* const* argv,
+  int& current,
+  const std::shared_ptr<OptionDetails>& value,
+  const std::string& name
+)
+{
+  if (current + 1 >= argc)
+  {
+    if (value->value().has_implicit())
+    {
+      parse_option(value, name, value->value().get_implicit_value());
+    }
+    else
+    {
+      throw_or_mimic<exceptions::missing_argument>(name);
+    }
+  }
+  else
+  {
+    if (value->value().has_implicit())
+    {
+      parse_option(value, name, value->value().get_implicit_value());
+    }
+    else
+    {
+      parse_option(value, name, argv[current + 1]);
+      ++current;
+    }
+  }
+}
+
+inline
+void
+OptionParser::add_to_option(const std::shared_ptr<OptionDetails>& value, const std::string& arg)
+{
+  auto hash = value->hash();
+  auto& result = m_parsed[hash];
+  result.add(value, arg);
+
+  m_sequential.emplace_back(value->essential_name(), arg);
+}
+
+inline
+bool
+OptionParser::consume_positional(const std::string& a, PositionalListIterator& next)
+{
+  while (next != m_positional.end())
+  {
+    auto iter = m_options.find(*next);
+    if (iter != m_options.end())
+    {
+      if (!iter->second->value().is_container())
+      {
+        auto& result = m_parsed[iter->second->hash()];
+        if (result.count() == 0)
+        {
+          add_to_option(iter->second, a);
+          ++next;
+          return true;
+        }
+        ++next;
+        continue;
+      }
+      add_to_option(iter->second, a);
+      return true;
+    }
+    throw_or_mimic<exceptions::no_such_option>(*next);
+  }
+
+  return false;
+}
+
+inline
+void
+Options::parse_positional(std::string option)
+{
+  parse_positional(std::vector<std::string>{std::move(option)});
+}
+
+inline
+void
+Options::parse_positional(std::vector<std::string> options)
+{
+  m_positional = std::move(options);
+
+  m_positional_set.insert(m_positional.begin(), m_positional.end());
+}
+
+inline
+void
+Options::parse_positional(std::initializer_list<std::string> options)
+{
+  parse_positional(std::vector<std::string>(options));
+}
+
+inline
+ParseResult
+Options::parse(int argc, const char* const* argv)
+{
+  OptionParser parser(*m_options, m_positional, m_allow_unrecognised);
+
+  return parser.parse(argc, argv);
+}
+
+inline ParseResult
+OptionParser::parse(int argc, const char* const* argv)
+{
+  int current = 1;
+  bool consume_remaining = false;
+  auto next_positional = m_positional.begin();
+
+  std::vector<std::string> unmatched;
+
+  while (current != argc)
+  {
+    if (strcmp(argv[current], "--") == 0)
+    {
+      consume_remaining = true;
+      ++current;
+      break;
+    }
+    bool matched = false;
+    values::parser_tool::ArguDesc argu_desc =
+        values::parser_tool::ParseArgument(argv[current], matched);
+
+    if (!matched)
+    {
+      //not a flag
+
+      // but if it starts with a `-`, then it's an error
+      if (argv[current][0] == '-' && argv[current][1] != '\0') {
+        if (!m_allow_unrecognised) {
+          throw_or_mimic<exceptions::invalid_option_syntax>(argv[current]);
+        }
+      }
+
+      //if true is returned here then it was consumed, otherwise it is
+      //ignored
+      if (consume_positional(argv[current], next_positional))
+      {
+      }
+      else
+      {
+        unmatched.emplace_back(argv[current]);
+      }
+      //if we return from here then it was parsed successfully, so continue
+    }
+    else
+    {
+      //short or long option?
+      if (argu_desc.grouping)
+      {
+        const std::string& s = argu_desc.arg_name;
+
+        for (std::size_t i = 0; i != s.size(); ++i)
+        {
+          std::string name(1, s[i]);
+          auto iter = m_options.find(name);
+
+          if (iter == m_options.end())
+          {
+            if (m_allow_unrecognised)
+            {
+              unmatched.push_back(std::string("-") + s[i]);
+              continue;
+            }
+            //error
+            throw_or_mimic<exceptions::no_such_option>(name);
+          }
+
+          auto value = iter->second;
+
+          if (i + 1 == s.size())
+          {
+            //it must be the last argument
+            checked_parse_arg(argc, argv, current, value, name);
+          }
+          else if (value->value().has_implicit())
+          {
+            parse_option(value, name, value->value().get_implicit_value());
+          }
+          else if (i + 1 < s.size())
+          {
+            std::string arg_value = s.substr(i + 1);
+            parse_option(value, name, arg_value);
+            break;
+          }
+          else
+          {
+            //error
+            throw_or_mimic<exceptions::option_requires_argument>(name);
+          }
+        }
+      }
+      else if (argu_desc.arg_name.length() != 0)
+      {
+        const std::string& name = argu_desc.arg_name;
+
+        auto iter = m_options.find(name);
+
+        if (iter == m_options.end())
+        {
+          if (m_allow_unrecognised)
+          {
+            // keep unrecognised options in argument list, skip to next argument
+            unmatched.emplace_back(argv[current]);
+            ++current;
+            continue;
+          }
+          //error
+          throw_or_mimic<exceptions::no_such_option>(name);
+        }
+
+        auto opt = iter->second;
+
+        //equals provided for long option?
+        if (argu_desc.set_value)
+        {
+          //parse the option given
+
+          parse_option(opt, name, argu_desc.value);
+        }
+        else
+        {
+          //parse the next argument
+          checked_parse_arg(argc, argv, current, opt, name);
+        }
+      }
+
+    }
+
+    ++current;
+  }
+
+  for (auto& opt : m_options)
+  {
+    auto& detail = opt.second;
+    const auto& value = detail->value();
+
+    auto& store = m_parsed[detail->hash()];
+
+    if (value.has_default()) {
+      if (!store.count() && !store.has_default()) {
+        parse_default(detail);
+      }
+    }
+    else {
+      parse_no_value(detail);
+    }
+  }
+
+  if (consume_remaining)
+  {
+    while (current < argc)
+    {
+      if (!consume_positional(argv[current], next_positional)) {
+        break;
+      }
+      ++current;
+    }
+
+    //adjust argv for any that couldn't be swallowed
+    while (current != argc) {
+      unmatched.emplace_back(argv[current]);
+      ++current;
+    }
+  }
+
+  finalise_aliases();
+
+  ParseResult parsed(std::move(m_keys), std::move(m_parsed), std::move(m_sequential), std::move(m_defaults), std::move(unmatched));
+  return parsed;
+}
+
+inline
+void
+OptionParser::finalise_aliases()
+{
+  for (auto& option: m_options)
+  {
+    auto& detail = *option.second;
+    auto hash = detail.hash();
+    m_keys[detail.short_name()] = hash;
+    for(const auto& long_name : detail.long_names()) {
+      m_keys[long_name] = hash;
+    }
+
+    m_parsed.emplace(hash, OptionValue());
+  }
+}
+
+inline
+void
+Options::add_option
+(
+  const std::string& group,
+  const Option& option
+)
+{
+    add_options(group, {option});
+}
+
+inline
+void
+Options::add_option
+(
+  const std::string& group,
+  const std::string& s,
+  const OptionNames& l,
+  std::string desc,
+  const std::shared_ptr<const Value>& value,
+  std::string arg_help
+)
+{
+  auto stringDesc = toLocalString(std::move(desc));
+  auto option = std::make_shared<OptionDetails>(s, l, stringDesc, value);
+
+  if (!s.empty())
+  {
+    add_one_option(s, option);
+  }
+
+  for(const auto& long_name : l) {
+    add_one_option(long_name, option);
+  }
+
+  //add the help details
+
+  if (m_help.find(group) == m_help.end())
+  {
+    m_group.push_back(group);
+  }
+
+  auto& options = m_help[group];
+
+  options.options.emplace_back(HelpOptionDetails{s, l, stringDesc,
+      value->has_default(), value->get_default_value(),
+      value->has_implicit(), value->get_implicit_value(),
+      std::move(arg_help),
+      value->is_container(),
+      value->is_boolean()});
+}
+
+inline
+void
+Options::add_one_option
+(
+  const std::string& option,
+  const std::shared_ptr<OptionDetails>& details
+)
+{
+  auto in = m_options->emplace(option, details);
+
+  if (!in.second)
+  {
+    throw_or_mimic<exceptions::option_already_exists>(option);
+  }
+}
+
+inline
+String
+Options::help_one_group(const std::string& g) const
+{
+  using OptionHelp = std::vector<std::pair<String, String>>;
+
+  auto group = m_help.find(g);
+  if (group == m_help.end())
+  {
+    return "";
+  }
+
+  OptionHelp format;
+
+  std::size_t longest = 0;
+
+  String result;
+
+  if (!g.empty())
+  {
+    result += toLocalString(" " + g + " options:\n");
+  }
+
+  for (const auto& o : group->second.options)
+  {
+    if (o.l.size() &&
+        m_positional_set.find(o.l.front()) != m_positional_set.end() &&
+        !m_show_positional)
+    {
+      continue;
+    }
+
+    auto s = format_option(o);
+    longest = (std::max)(longest, stringLength(s));
+    format.push_back(std::make_pair(s, String()));
+  }
+  longest = (std::min)(longest, OPTION_LONGEST);
+
+  //widest allowed description -- min 10 chars for helptext/line
+  std::size_t allowed = 10;
+  if (m_width > allowed + longest + OPTION_DESC_GAP)
+  {
+    allowed = m_width - longest - OPTION_DESC_GAP;
+  }
+
+  auto fiter = format.begin();
+  for (const auto& o : group->second.options)
+  {
+    if (o.l.size() &&
+        m_positional_set.find(o.l.front()) != m_positional_set.end() &&
+        !m_show_positional)
+    {
+      continue;
+    }
+
+    auto d = format_description(o, longest + OPTION_DESC_GAP, allowed, m_tab_expansion);
+
+    result += fiter->first;
+    if (stringLength(fiter->first) > longest)
+    {
+      result += '\n';
+      result += toLocalString(std::string(longest + OPTION_DESC_GAP, ' '));
+    }
+    else
+    {
+      result += toLocalString(std::string(longest + OPTION_DESC_GAP -
+        stringLength(fiter->first),
+        ' '));
+    }
+    result += d;
+    result += '\n';
+
+    ++fiter;
+  }
+
+  return result;
+}
+
+inline
+void
+Options::generate_group_help
+(
+  String& result,
+  const std::vector<std::string>& print_groups
+) const
+{
+  for (std::size_t i = 0; i != print_groups.size(); ++i)
+  {
+    const String& group_help_text = help_one_group(print_groups[i]);
+    if (empty(group_help_text))
+    {
+      continue;
+    }
+    result += group_help_text;
+    if (i < print_groups.size() - 1)
+    {
+      result += '\n';
+    }
+  }
+}
+
+inline
+void
+Options::generate_all_groups_help(String& result) const
+{
+  generate_group_help(result, m_group);
+}
+
+inline
+std::string
+Options::help(const std::vector<std::string>& help_groups, bool print_usage) const
+{
+  String result = m_help_string;
+  if(print_usage)
+  {
+    result+= "\nUsage:\n  " + toLocalString(m_program);
+  }
+
+  if (!m_custom_help.empty())
+  {
+    result += " " + toLocalString(m_custom_help);
+  }
+
+  if (!m_positional.empty() && !m_positional_help.empty()) {
+    result += " " + toLocalString(m_positional_help);
+  }
+
+  result += "\n\n";
+
+  if (help_groups.empty())
+  {
+    generate_all_groups_help(result);
+  }
+  else
+  {
+    generate_group_help(result, help_groups);
+  }
+
+  return toUTF8String(result);
+}
+
+inline
+std::vector<std::string>
+Options::groups() const
+{
+  return m_group;
+}
+
+inline
+const HelpGroupDetails&
+Options::group_help(const std::string& group) const
+{
+  return m_help.at(group);
+}
+
+} // namespace cxxopts
+
+#endif //CXXOPTS_HPP_INCLUDED
\ No newline at end of file
diff --git a/examples/relay_client/main.cc b/examples/relay_client/main.cc
new file mode 100644
index 0000000..31dd798
--- /dev/null
+++ b/examples/relay_client/main.cc
@@ -0,0 +1,90 @@
+//
+//    Copyright 2025 Metehan Gezer
+//
+//    Licensed under the Apache License, Version 2.0 (the "License");
+//    you may not use this file except in compliance with the License.
+//    You may obtain a copy of the License at
+//
+//        http://www.apache.org/licenses/LICENSE-2.0
+//
+
+#include <utility>
+
+#include "znet/znet.h"
+#include "znet/relay/relay.h"
+#include "cxxopts.h"
+
+const std::string kPeerName = GeneratePeerName();
+
+class DefaultPacketHandler : public znet::PacketHandler<DefaultPacketHandler,
+                                                        znet::holepunch::RegisterPeerResponsePacket,
+                                                        znet::holepunch::ConnectPeerResponsePacket> {
+public:
+  DefaultPacketHandler(std::shared_ptr<znet::PeerSession> session) : session_(std::move(session)) { }
+
+  void OnPacket(const znet::holepunch::RegisterPeerResponsePacket& pk) {
+    ZNET_LOG_INFO("RegisterPeerResponsePacket {}, ok: {}", pk.peer_name_, pk.ok_);
+  }
+
+  void OnPacket(const znet::holepunch::ConnectPeerResponsePacket& pk) {
+    ZNET_LOG_INFO("ConnectPeerResponsePacket target: {}, endpoint: {}", pk.target_, pk.endpoint_->readable());
+  }
+
+  void OnUnknown(std::shared_ptr<znet::Packet> p) {
+  }
+
+private:
+  std::shared_ptr<znet::PeerSession> session_;
+};
+
+bool OnConnectEvent(znet::ClientConnectedToServerEvent& event) {
+  znet::PeerSession& session = *event.session();
+  session.SetCodec(znet::holepunch::BuildCodec());
+  session.SetHandler(std::make_shared<DefaultPacketHandler>(event.session()));
+
+  auto pk = std::make_shared<znet::holepunch::RegisterPeerPacket>();
+  pk->peer_name_ = kPeerName;
+  pk->port_ = 6000; // Actual game endpoint port
+  session.SendPacket(pk);
+  return false;
+}
+
+void OnEvent(znet::Event& event) {
+  znet::EventDispatcher dispatcher{event};
+  dispatcher.Dispatch<znet::ClientConnectedToServerEvent>(
+      ZNET_BIND_GLOBAL_FN(OnConnectEvent));
+}
+
+int main(int argc, char* argv[]) {
+  cxxopts::Options opts("punch-client","znet hole‑punch client");
+  opts.add_options()
+      ("r,relay",  "relay IP",   cxxopts::value<std::string>()->default_value("127.0.0.1"))
+          ("p,port",   "relay port", cxxopts::value<uint16_t>()->default_value("5001"))
+              ("t,target", "peer name",  cxxopts::value<std::string>())
+                  ("l,local",  "punch port", cxxopts::value<uint16_t>()->default_value("6000"))
+                      ("h,help",   "help");
+  auto res = opts.parse(argc, argv);
+  if (res.count("help") || !res.count("name") || !res.count("target")) {
+    std::cout<<opts.help();
+    return 0;
+  }
+
+  std::string relay_ip   = res["relay"].as<std::string>();
+  uint16_t    relay_port = res["port" ].as<uint16_t>();
+  std::string peer        = res["target"].as<std::string>();
+  uint16_t    local_port  = res["local"].as<uint16_t>();
+
+  ZNET_LOG_INFO("I am the peer {}", kPeerName);
+  znet::ClientConfig config{relay_ip, relay_port};
+  znet::Client client{config};
+  client.SetEventCallback(ZNET_BIND_GLOBAL_FN(OnEvent));
+
+  if (client.Bind() != znet::Result::Success) {
+    return 1; // Failed to bind
+  }
+  if (client.Connect() != znet::Result::Success) {
+    return 1; // Failed to connect
+  }
+  client.Wait();
+  return 0;
+}
\ No newline at end of file
diff --git a/relay_server/CMakeLists.txt b/relay_server/CMakeLists.txt
new file mode 100644
index 0000000..1c3e894
--- /dev/null
+++ b/relay_server/CMakeLists.txt
@@ -0,0 +1,10 @@
+cmake_minimum_required(VERSION 3.16.3)
+project(relay-server)
+
+add_executable(relay-server main.cc)
+set_target_properties(relay-server PROPERTIES
+        CXX_STANDARD 14
+        CXX_STANDARD_REQUIRED ON
+)
+target_link_libraries(relay-server PRIVATE znet)
+
diff --git a/relay_server/cxxopts.h b/relay_server/cxxopts.h
new file mode 100644
index 0000000..e76f206
--- /dev/null
+++ b/relay_server/cxxopts.h
@@ -0,0 +1,2927 @@
+/*
+
+Copyright (c) 2014-2022 Jarryd Beck
+
+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.
+
+*/
+
+// vim: ts=2:sw=2:expandtab
+
+#ifndef CXXOPTS_HPP_INCLUDED
+#define CXXOPTS_HPP_INCLUDED
+
+#include <cstdint>
+#include <cstdlib>
+#include <cstring>
+#include <exception>
+#include <limits>
+#include <initializer_list>
+#include <map>
+#include <memory>
+#include <sstream>
+#include <string>
+#include <unordered_map>
+#include <unordered_set>
+#include <utility>
+#include <vector>
+#include <algorithm>
+#include <locale>
+
+#ifdef CXXOPTS_NO_EXCEPTIONS
+#include <iostream>
+#endif
+
+#if defined(__GNUC__) && !defined(__clang__)
+#  if (__GNUC__ * 10 + __GNUC_MINOR__) < 49
+#    define CXXOPTS_NO_REGEX true
+#  endif
+#endif
+#if defined(_MSC_VER) && !defined(__clang__)
+#define CXXOPTS_LINKONCE_CONST	__declspec(selectany) extern
+#define CXXOPTS_LINKONCE		__declspec(selectany) extern
+#else
+#define CXXOPTS_LINKONCE_CONST
+#define CXXOPTS_LINKONCE
+#endif
+
+#ifndef CXXOPTS_NO_REGEX
+#  include <regex>
+#endif  // CXXOPTS_NO_REGEX
+
+// Nonstandard before C++17, which is coincidentally what we also need for <optional>
+#ifdef __has_include
+#  if __has_include(<optional>)
+#    include <optional>
+#    ifdef __cpp_lib_optional
+#      define CXXOPTS_HAS_OPTIONAL
+#    endif
+#  endif
+#  if __has_include(<filesystem>)
+#    include <filesystem>
+#    ifdef __cpp_lib_filesystem
+#      define CXXOPTS_HAS_FILESYSTEM
+#    endif
+#  endif
+#endif
+
+#define CXXOPTS_FALLTHROUGH
+#ifdef __has_cpp_attribute
+  #if __has_cpp_attribute(fallthrough)
+    #undef CXXOPTS_FALLTHROUGH
+    #define CXXOPTS_FALLTHROUGH [[fallthrough]]
+  #endif
+#endif
+
+#if __cplusplus >= 201603L
+#define CXXOPTS_NODISCARD [[nodiscard]]
+#else
+#define CXXOPTS_NODISCARD
+#endif
+
+#ifndef CXXOPTS_VECTOR_DELIMITER
+#define CXXOPTS_VECTOR_DELIMITER ','
+#endif
+
+#define CXXOPTS__VERSION_MAJOR 3
+#define CXXOPTS__VERSION_MINOR 3
+#define CXXOPTS__VERSION_PATCH 1
+
+#if (__GNUC__ < 10 || (__GNUC__ == 10 && __GNUC_MINOR__ < 1)) && __GNUC__ >= 6
+  #define CXXOPTS_NULL_DEREF_IGNORE
+#endif
+
+#if defined(__GNUC__)
+#define DO_PRAGMA(x) _Pragma(#x)
+#define CXXOPTS_DIAGNOSTIC_PUSH DO_PRAGMA(GCC diagnostic push)
+#define CXXOPTS_DIAGNOSTIC_POP DO_PRAGMA(GCC diagnostic pop)
+#define CXXOPTS_IGNORE_WARNING(x) DO_PRAGMA(GCC diagnostic ignored x)
+#else
+// define other compilers here if needed
+#define CXXOPTS_DIAGNOSTIC_PUSH
+#define CXXOPTS_DIAGNOSTIC_POP
+#define CXXOPTS_IGNORE_WARNING(x)
+#endif
+
+#ifdef CXXOPTS_NO_RTTI
+#define CXXOPTS_RTTI_CAST static_cast
+#else
+#define CXXOPTS_RTTI_CAST dynamic_cast
+#endif
+
+namespace cxxopts {
+static constexpr struct {
+  uint8_t major, minor, patch;
+} version = {
+  CXXOPTS__VERSION_MAJOR,
+  CXXOPTS__VERSION_MINOR,
+  CXXOPTS__VERSION_PATCH
+};
+} // namespace cxxopts
+
+//when we ask cxxopts to use Unicode, help strings are processed using ICU,
+//which results in the correct lengths being computed for strings when they
+//are formatted for the help output
+//it is necessary to make sure that <unicode/unistr.h> can be found by the
+//compiler, and that icu-uc is linked in to the binary.
+
+#ifdef CXXOPTS_USE_UNICODE
+#include <unicode/unistr.h>
+
+namespace cxxopts {
+
+using String = icu::UnicodeString;
+
+inline
+String
+toLocalString(std::string s)
+{
+  return icu::UnicodeString::fromUTF8(std::move(s));
+}
+
+// GNU GCC with -Weffc++ will issue a warning regarding the upcoming class, we want to silence it:
+// warning: base class 'class std::enable_shared_from_this<cxxopts::Value>' has accessible non-virtual destructor
+CXXOPTS_DIAGNOSTIC_PUSH
+CXXOPTS_IGNORE_WARNING("-Wnon-virtual-dtor")
+// This will be ignored under other compilers like LLVM clang.
+class UnicodeStringIterator
+{
+  public:
+
+  using iterator_category = std::forward_iterator_tag;
+  using value_type = int32_t;
+  using difference_type = std::ptrdiff_t;
+  using pointer = value_type*;
+  using reference = value_type&;
+
+  UnicodeStringIterator(const icu::UnicodeString* string, int32_t pos)
+  : s(string)
+  , i(pos)
+  {
+  }
+
+  value_type
+  operator*() const
+  {
+    return s->char32At(i);
+  }
+
+  bool
+  operator==(const UnicodeStringIterator& rhs) const
+  {
+    return s == rhs.s && i == rhs.i;
+  }
+
+  bool
+  operator!=(const UnicodeStringIterator& rhs) const
+  {
+    return !(*this == rhs);
+  }
+
+  UnicodeStringIterator&
+  operator++()
+  {
+    ++i;
+    return *this;
+  }
+
+  UnicodeStringIterator
+  operator+(int32_t v)
+  {
+    return UnicodeStringIterator(s, i + v);
+  }
+
+  private:
+  const icu::UnicodeString* s;
+  int32_t i;
+};
+CXXOPTS_DIAGNOSTIC_POP
+
+inline
+String&
+stringAppend(String&s, String a)
+{
+  return s.append(std::move(a));
+}
+
+inline
+String&
+stringAppend(String& s, std::size_t n, UChar32 c)
+{
+  for (std::size_t i = 0; i != n; ++i)
+  {
+    s.append(c);
+  }
+
+  return s;
+}
+
+template <typename Iterator>
+String&
+stringAppend(String& s, Iterator begin, Iterator end)
+{
+  while (begin != end)
+  {
+    s.append(*begin);
+    ++begin;
+  }
+
+  return s;
+}
+
+inline
+size_t
+stringLength(const String& s)
+{
+  return static_cast<size_t>(s.length());
+}
+
+inline
+std::string
+toUTF8String(const String& s)
+{
+  std::string result;
+  s.toUTF8String(result);
+
+  return result;
+}
+
+inline
+bool
+empty(const String& s)
+{
+  return s.isEmpty();
+}
+
+} // namespace cxxopts
+
+namespace std {
+
+inline
+cxxopts::UnicodeStringIterator
+begin(const icu::UnicodeString& s)
+{
+  return cxxopts::UnicodeStringIterator(&s, 0);
+}
+
+inline
+cxxopts::UnicodeStringIterator
+end(const icu::UnicodeString& s)
+{
+  return cxxopts::UnicodeStringIterator(&s, s.length());
+}
+
+} // namespace std
+
+//ifdef CXXOPTS_USE_UNICODE
+#else
+
+namespace cxxopts {
+
+using String = std::string;
+
+template <typename T>
+T
+toLocalString(T&& t)
+{
+  return std::forward<T>(t);
+}
+
+inline
+std::size_t
+stringLength(const String& s)
+{
+  return s.length();
+}
+
+inline
+String&
+stringAppend(String&s, const String& a)
+{
+  return s.append(a);
+}
+
+inline
+String&
+stringAppend(String& s, std::size_t n, char c)
+{
+  return s.append(n, c);
+}
+
+template <typename Iterator>
+String&
+stringAppend(String& s, Iterator begin, Iterator end)
+{
+  return s.append(begin, end);
+}
+
+template <typename T>
+std::string
+toUTF8String(T&& t)
+{
+  return std::forward<T>(t);
+}
+
+inline
+bool
+empty(const std::string& s)
+{
+  return s.empty();
+}
+
+} // namespace cxxopts
+
+//ifdef CXXOPTS_USE_UNICODE
+#endif
+
+namespace cxxopts {
+
+namespace {
+CXXOPTS_LINKONCE_CONST std::string LQUOTE("\'");
+CXXOPTS_LINKONCE_CONST std::string RQUOTE("\'");
+} // namespace
+
+// GNU GCC with -Weffc++ will issue a warning regarding the upcoming class, we
+// want to silence it: warning: base class 'class
+// std::enable_shared_from_this<cxxopts::Value>' has accessible non-virtual
+// destructor This will be ignored under other compilers like LLVM clang.
+CXXOPTS_DIAGNOSTIC_PUSH
+CXXOPTS_IGNORE_WARNING("-Wnon-virtual-dtor")
+
+// some older versions of GCC warn under this warning
+CXXOPTS_IGNORE_WARNING("-Weffc++")
+class Value : public std::enable_shared_from_this<Value>
+{
+  public:
+
+  virtual ~Value() = default;
+
+  virtual
+  std::shared_ptr<Value>
+  clone() const = 0;
+
+  virtual void
+  add(const std::string& text) const = 0;
+
+  virtual void
+  parse(const std::string& text) const = 0;
+
+  virtual void
+  parse() const = 0;
+
+  virtual bool
+  has_default() const = 0;
+
+  virtual bool
+  is_container() const = 0;
+
+  virtual bool
+  has_implicit() const = 0;
+
+  virtual std::string
+  get_default_value() const = 0;
+
+  virtual std::string
+  get_implicit_value() const = 0;
+
+  virtual std::shared_ptr<Value>
+  default_value(const std::string& value) = 0;
+
+  virtual std::shared_ptr<Value>
+  implicit_value(const std::string& value) = 0;
+
+  virtual std::shared_ptr<Value>
+  no_implicit_value() = 0;
+
+  virtual bool
+  is_boolean() const = 0;
+};
+
+CXXOPTS_DIAGNOSTIC_POP
+
+namespace exceptions {
+
+class exception : public std::exception
+{
+  public:
+  explicit exception(std::string  message)
+  : m_message(std::move(message))
+  {
+  }
+
+  CXXOPTS_NODISCARD
+  const char*
+  what() const noexcept override
+  {
+    return m_message.c_str();
+  }
+
+  private:
+  std::string m_message;
+};
+
+class specification : public exception
+{
+  public:
+
+  explicit specification(const std::string& message)
+  : exception(message)
+  {
+  }
+};
+
+class parsing : public exception
+{
+  public:
+  explicit parsing(const std::string& message)
+  : exception(message)
+  {
+  }
+};
+
+class option_already_exists : public specification
+{
+  public:
+  explicit option_already_exists(const std::string& option)
+  : specification("Option " + LQUOTE + option + RQUOTE + " already exists")
+  {
+  }
+};
+
+class invalid_option_format : public specification
+{
+  public:
+  explicit invalid_option_format(const std::string& format)
+  : specification("Invalid option format " + LQUOTE + format + RQUOTE)
+  {
+  }
+};
+
+class invalid_option_syntax : public parsing {
+  public:
+  explicit invalid_option_syntax(const std::string& text)
+  : parsing("Argument " + LQUOTE + text + RQUOTE +
+            " starts with a - but has incorrect syntax")
+  {
+  }
+};
+
+class no_such_option : public parsing
+{
+  public:
+  explicit no_such_option(const std::string& option)
+  : parsing("Option " + LQUOTE + option + RQUOTE + " does not exist")
+  {
+  }
+};
+
+class missing_argument : public parsing
+{
+  public:
+  explicit missing_argument(const std::string& option)
+  : parsing(
+      "Option " + LQUOTE + option + RQUOTE + " is missing an argument"
+    )
+  {
+  }
+};
+
+class option_requires_argument : public parsing
+{
+  public:
+  explicit option_requires_argument(const std::string& option)
+  : parsing(
+      "Option " + LQUOTE + option + RQUOTE + " requires an argument"
+    )
+  {
+  }
+};
+
+class gratuitous_argument_for_option : public parsing
+{
+  public:
+  gratuitous_argument_for_option
+  (
+    const std::string& option,
+    const std::string& arg
+  )
+  : parsing(
+      "Option " + LQUOTE + option + RQUOTE +
+      " does not take an argument, but argument " +
+      LQUOTE + arg + RQUOTE + " given"
+    )
+  {
+  }
+};
+
+class requested_option_not_present : public parsing
+{
+  public:
+  explicit requested_option_not_present(const std::string& option)
+  : parsing("Option " + LQUOTE + option + RQUOTE + " not present")
+  {
+  }
+};
+
+class option_has_no_value : public exception
+{
+  public:
+  explicit option_has_no_value(const std::string& option)
+  : exception(
+      !option.empty() ?
+      ("Option " + LQUOTE + option + RQUOTE + " has no value") :
+      "Option has no value")
+  {
+  }
+};
+
+class incorrect_argument_type : public parsing
+{
+  public:
+  explicit incorrect_argument_type
+  (
+    const std::string& arg
+  )
+  : parsing(
+      "Argument " + LQUOTE + arg + RQUOTE + " failed to parse"
+    )
+  {
+  }
+};
+
+} // namespace exceptions
+
+
+template <typename T>
+void throw_or_mimic(const std::string& text)
+{
+  static_assert(std::is_base_of<std::exception, T>::value,
+                "throw_or_mimic only works on std::exception and "
+                "deriving classes");
+
+#ifndef CXXOPTS_NO_EXCEPTIONS
+  // If CXXOPTS_NO_EXCEPTIONS is not defined, just throw
+  throw T{text};
+#else
+  // Otherwise manually instantiate the exception, print what() to stderr,
+  // and exit
+  T exception{text};
+  std::cerr << exception.what() << std::endl;
+  std::exit(EXIT_FAILURE);
+#endif
+}
+
+using OptionNames = std::vector<std::string>;
+
+namespace values {
+
+namespace parser_tool {
+
+struct IntegerDesc
+{
+  std::string negative = "";
+  std::string base     = "";
+  std::string value    = "";
+};
+struct ArguDesc {
+  std::string arg_name  = "";
+  bool        grouping  = false;
+  bool        set_value = false;
+  std::string value     = "";
+};
+
+#ifdef CXXOPTS_NO_REGEX
+inline IntegerDesc SplitInteger(const std::string &text)
+{
+  if (text.empty())
+  {
+    throw_or_mimic<exceptions::incorrect_argument_type>(text);
+  }
+  IntegerDesc desc;
+  const char *pdata = text.c_str();
+  if (*pdata == '-')
+  {
+    pdata += 1;
+    desc.negative = "-";
+  }
+  if (strncmp(pdata, "0x", 2) == 0)
+  {
+    pdata += 2;
+    desc.base = "0x";
+  }
+  if (*pdata != '\0')
+  {
+    desc.value = std::string(pdata);
+  }
+  else
+  {
+    throw_or_mimic<exceptions::incorrect_argument_type>(text);
+  }
+  return desc;
+}
+
+inline bool IsTrueText(const std::string &text)
+{
+  const char *pdata = text.c_str();
+  if (*pdata == 't' || *pdata == 'T')
+  {
+    pdata += 1;
+    if (strncmp(pdata, "rue\0", 4) == 0)
+    {
+      return true;
+    }
+  }
+  else if (strncmp(pdata, "1\0", 2) == 0)
+  {
+    return true;
+  }
+  return false;
+}
+
+inline bool IsFalseText(const std::string &text)
+{
+  const char *pdata = text.c_str();
+  if (*pdata == 'f' || *pdata == 'F')
+  {
+    pdata += 1;
+    if (strncmp(pdata, "alse\0", 5) == 0)
+    {
+      return true;
+    }
+  }
+  else if (strncmp(pdata, "0\0", 2) == 0)
+  {
+    return true;
+  }
+  return false;
+}
+
+inline OptionNames split_option_names(const std::string &text)
+{
+  OptionNames split_names;
+
+  std::string::size_type token_start_pos = 0;
+  auto length = text.length();
+
+  if (length == 0)
+  {
+    throw_or_mimic<exceptions::invalid_option_format>(text);
+  }
+
+  while (token_start_pos < length) {
+    const auto &npos = std::string::npos;
+    auto next_non_space_pos = text.find_first_not_of(' ', token_start_pos);
+    if (next_non_space_pos == npos) {
+      throw_or_mimic<exceptions::invalid_option_format>(text);
+    }
+    token_start_pos = next_non_space_pos;
+    auto next_delimiter_pos = text.find(',', token_start_pos);
+    if (next_delimiter_pos == token_start_pos) {
+      throw_or_mimic<exceptions::invalid_option_format>(text);
+    }
+    if (next_delimiter_pos == npos) {
+      next_delimiter_pos = length;
+    }
+    auto token_length = next_delimiter_pos - token_start_pos;
+    // validate the token itself matches the regex /([:alnum:][-_[:alnum:]]*/
+    {
+      const char* option_name_valid_chars =
+        "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+        "abcdefghijklmnopqrstuvwxyz"
+        "0123456789"
+        "_-.?";
+
+      if (!std::isalnum(text[token_start_pos], std::locale::classic()) ||
+          text.find_first_not_of(option_name_valid_chars, token_start_pos) < next_delimiter_pos) {
+        throw_or_mimic<exceptions::invalid_option_format>(text);
+      }
+    }
+    split_names.emplace_back(text.substr(token_start_pos, token_length));
+    token_start_pos = next_delimiter_pos + 1;
+  }
+  return split_names;
+}
+
+inline ArguDesc ParseArgument(const char *arg, bool &matched)
+{
+  ArguDesc argu_desc;
+  const char *pdata = arg;
+  matched = false;
+  if (strncmp(pdata, "--", 2) == 0)
+  {
+    pdata += 2;
+    if (isalnum(*pdata, std::locale::classic()))
+    {
+      argu_desc.arg_name.push_back(*pdata);
+      pdata += 1;
+      while (isalnum(*pdata, std::locale::classic()) || *pdata == '-' || *pdata == '_')
+      {
+        argu_desc.arg_name.push_back(*pdata);
+        pdata += 1;
+      }
+      if (argu_desc.arg_name.length() > 1)
+      {
+        if (*pdata == '=')
+        {
+          argu_desc.set_value = true;
+          pdata += 1;
+          if (*pdata != '\0')
+          {
+            argu_desc.value = std::string(pdata);
+          }
+          matched = true;
+        }
+        else if (*pdata == '\0')
+        {
+          matched = true;
+        }
+      }
+    }
+  }
+  else if (strncmp(pdata, "-", 1) == 0)
+  {
+    pdata += 1;
+    argu_desc.grouping = true;
+    while (isalnum(*pdata, std::locale::classic()))
+    {
+      argu_desc.arg_name.push_back(*pdata);
+      pdata += 1;
+    }
+    matched = !argu_desc.arg_name.empty() && *pdata == '\0';
+  }
+  return argu_desc;
+}
+
+#else  // CXXOPTS_NO_REGEX
+
+namespace {
+CXXOPTS_LINKONCE
+const char* const integer_pattern =
+  "(-)?(0x)?([0-9a-zA-Z]+)|((0x)?0)";
+CXXOPTS_LINKONCE
+const char* const truthy_pattern =
+  "(t|T)(rue)?|1";
+CXXOPTS_LINKONCE
+const char* const falsy_pattern =
+  "(f|F)(alse)?|0";
+CXXOPTS_LINKONCE
+const char* const option_pattern =
+  "--([[:alnum:]][-_[:alnum:]\\.]+)(=(.*))?|-([[:alnum:]].*)";
+CXXOPTS_LINKONCE
+const char* const option_specifier_pattern =
+  "([[:alnum:]][-_[:alnum:]\\.]*)(,[ ]*[[:alnum:]][-_[:alnum:]]*)*";
+CXXOPTS_LINKONCE
+const char* const option_specifier_separator_pattern = ", *";
+
+} // namespace
+
+inline IntegerDesc SplitInteger(const std::string &text)
+{
+  static const std::basic_regex<char> integer_matcher(integer_pattern);
+
+  std::smatch match;
+  std::regex_match(text, match, integer_matcher);
+
+  if (match.length() == 0)
+  {
+    throw_or_mimic<exceptions::incorrect_argument_type>(text);
+  }
+
+  IntegerDesc desc;
+  desc.negative = match[1];
+  desc.base = match[2];
+  desc.value = match[3];
+
+  if (match.length(4) > 0)
+  {
+    desc.base = match[5];
+    desc.value = "0";
+    return desc;
+  }
+
+  return desc;
+}
+
+inline bool IsTrueText(const std::string &text)
+{
+  static const std::basic_regex<char> truthy_matcher(truthy_pattern);
+  std::smatch result;
+  std::regex_match(text, result, truthy_matcher);
+  return !result.empty();
+}
+
+inline bool IsFalseText(const std::string &text)
+{
+  static const std::basic_regex<char> falsy_matcher(falsy_pattern);
+  std::smatch result;
+  std::regex_match(text, result, falsy_matcher);
+  return !result.empty();
+}
+
+// Gets the option names specified via a single, comma-separated string,
+// and returns the separate, space-discarded, non-empty names
+// (without considering which or how many are single-character)
+inline OptionNames split_option_names(const std::string &text)
+{
+  static const std::basic_regex<char> option_specifier_matcher(option_specifier_pattern);
+  if (!std::regex_match(text.c_str(), option_specifier_matcher))
+  {
+    throw_or_mimic<exceptions::invalid_option_format>(text);
+  }
+
+  OptionNames split_names;
+
+  static const std::basic_regex<char> option_specifier_separator_matcher(option_specifier_separator_pattern);
+  constexpr int use_non_matches { -1 };
+  auto token_iterator = std::sregex_token_iterator(
+    text.begin(), text.end(), option_specifier_separator_matcher, use_non_matches);
+  std::copy(token_iterator, std::sregex_token_iterator(), std::back_inserter(split_names));
+  return split_names;
+}
+
+inline ArguDesc ParseArgument(const char *arg, bool &matched)
+{
+  static const std::basic_regex<char> option_matcher(option_pattern);
+  std::match_results<const char*> result;
+  std::regex_match(arg, result, option_matcher);
+  matched = !result.empty();
+
+  ArguDesc argu_desc;
+  if (matched) {
+    argu_desc.arg_name = result[1].str();
+    argu_desc.set_value = result[2].length() > 0;
+    argu_desc.value = result[3].str();
+    if (result[4].length() > 0)
+    {
+      argu_desc.grouping = true;
+      argu_desc.arg_name = result[4].str();
+    }
+  }
+
+  return argu_desc;
+}
+
+#endif  // CXXOPTS_NO_REGEX
+#undef CXXOPTS_NO_REGEX
+} // namespace parser_tool
+
+namespace detail {
+
+template <typename T, bool B>
+struct SignedCheck;
+
+template <typename T>
+struct SignedCheck<T, true>
+{
+  template <typename U>
+  void
+  operator()(bool negative, U u, const std::string& text)
+  {
+    if (negative)
+    {
+      if (u > static_cast<U>((std::numeric_limits<T>::min)()))
+      {
+        throw_or_mimic<exceptions::incorrect_argument_type>(text);
+      }
+    }
+    else
+    {
+      if (u > static_cast<U>((std::numeric_limits<T>::max)()))
+      {
+        throw_or_mimic<exceptions::incorrect_argument_type>(text);
+      }
+    }
+  }
+};
+
+template <typename T>
+struct SignedCheck<T, false>
+{
+  template <typename U>
+  void
+  operator()(bool, U, const std::string&) const {}
+};
+
+template <typename T, typename U>
+void
+check_signed_range(bool negative, U value, const std::string& text)
+{
+  SignedCheck<T, std::numeric_limits<T>::is_signed>()(negative, value, text);
+}
+
+} // namespace detail
+
+template <typename R, typename T>
+void
+checked_negate(R& r, T&& t, const std::string&, std::true_type)
+{
+  // if we got to here, then `t` is a positive number that fits into
+  // `R`. So to avoid MSVC C4146, we first cast it to `R`.
+  // See https://github.com/jarro2783/cxxopts/issues/62 for more details.
+  r = static_cast<R>(-static_cast<R>(t-1)-1);
+}
+
+template <typename R, typename T>
+void
+checked_negate(R&, T&&, const std::string& text, std::false_type)
+{
+  throw_or_mimic<exceptions::incorrect_argument_type>(text);
+}
+
+template <typename T>
+void
+integer_parser(const std::string& text, T& value)
+{
+  parser_tool::IntegerDesc int_desc = parser_tool::SplitInteger(text);
+
+  using US = typename std::make_unsigned<T>::type;
+  constexpr bool is_signed = std::numeric_limits<T>::is_signed;
+
+  const bool          negative    = int_desc.negative.length() > 0;
+  const uint8_t       base        = int_desc.base.length() > 0 ? 16 : 10;
+  const std::string & value_match = int_desc.value;
+
+  US result = 0;
+
+  for (char ch : value_match)
+  {
+    US digit = 0;
+
+    if (ch >= '0' && ch <= '9')
+    {
+      digit = static_cast<US>(ch - '0');
+    }
+    else if (base == 16 && ch >= 'a' && ch <= 'f')
+    {
+      digit = static_cast<US>(ch - 'a' + 10);
+    }
+    else if (base == 16 && ch >= 'A' && ch <= 'F')
+    {
+      digit = static_cast<US>(ch - 'A' + 10);
+    }
+    else
+    {
+      throw_or_mimic<exceptions::incorrect_argument_type>(text);
+    }
+
+    US limit = 0;
+    if (negative)
+    {
+      limit = static_cast<US>(std::abs(static_cast<intmax_t>((std::numeric_limits<T>::min)())));
+    }
+    else
+    {
+      limit = (std::numeric_limits<T>::max)();
+    }
+
+    if (base != 0 && result > limit / base)
+    {
+      throw_or_mimic<exceptions::incorrect_argument_type>(text);
+    }
+    if (result * base > limit - digit)
+    {
+      throw_or_mimic<exceptions::incorrect_argument_type>(text);
+    }
+
+    result = static_cast<US>(result * base + digit);
+  }
+
+  detail::check_signed_range<T>(negative, result, text);
+
+  if (negative)
+  {
+    checked_negate<T>(value, result, text, std::integral_constant<bool, is_signed>());
+  }
+  else
+  {
+    value = static_cast<T>(result);
+  }
+}
+
+template <typename T>
+void stringstream_parser(const std::string& text, T& value)
+{
+  std::stringstream in(text);
+  in >> value;
+  if (!in) {
+    throw_or_mimic<exceptions::incorrect_argument_type>(text);
+  }
+}
+
+template <typename T,
+         typename std::enable_if<std::is_integral<T>::value>::type* = nullptr
+         >
+void parse_value(const std::string& text, T& value)
+{
+    integer_parser(text, value);
+}
+
+inline
+void
+parse_value(const std::string& text, bool& value)
+{
+  if (parser_tool::IsTrueText(text))
+  {
+    value = true;
+    return;
+  }
+
+  if (parser_tool::IsFalseText(text))
+  {
+    value = false;
+    return;
+  }
+
+  throw_or_mimic<exceptions::incorrect_argument_type>(text);
+}
+
+inline
+void
+parse_value(const std::string& text, std::string& value)
+{
+  value = text;
+}
+
+// The fallback parser. It uses the stringstream parser to parse all types
+// that have not been overloaded explicitly.  It has to be placed in the
+// source code before all other more specialized templates.
+template <typename T,
+         typename std::enable_if<!std::is_integral<T>::value>::type* = nullptr
+         >
+void
+parse_value(const std::string& text, T& value) {
+  stringstream_parser(text, value);
+}
+
+#ifdef CXXOPTS_HAS_OPTIONAL
+template <typename T>
+void
+parse_value(const std::string& text, std::optional<T>& value)
+{
+  T result;
+  parse_value(text, result);
+  value = std::move(result);
+}
+#endif
+
+#ifdef CXXOPTS_HAS_FILESYSTEM
+inline
+void
+parse_value(const std::string& text, std::filesystem::path& value)
+{
+  value.assign(text);
+}
+#endif
+
+inline
+void parse_value(const std::string& text, char& c)
+{
+  if (text.length() != 1)
+  {
+    throw_or_mimic<exceptions::incorrect_argument_type>(text);
+  }
+
+  c = text[0];
+}
+
+template<typename T> void add_value(const std::string& text, std::vector<T>& value);
+
+template <typename T>
+void
+parse_value(const std::string& text, std::vector<T>& value)
+{
+  if (text.empty()) {
+    return;
+  }
+  std::stringstream in(text);
+  std::string token;
+  while(!in.eof() && std::getline(in, token, CXXOPTS_VECTOR_DELIMITER)) {
+    add_value(token, value);
+  }
+}
+
+template <typename T>
+void
+add_value(const std::string& text, T& value)
+{
+  parse_value(text, value);
+}
+
+template <typename T>
+void
+add_value(const std::string& text, std::vector<T>& value)
+{
+  T v;
+  add_value(text, v);
+  value.emplace_back(std::move(v));
+}
+
+template <typename T>
+struct type_is_container
+{
+  static constexpr bool value = false;
+};
+
+template <typename T>
+struct type_is_container<std::vector<T>>
+{
+  static constexpr bool value = true;
+};
+
+template <typename T>
+class abstract_value : public Value
+{
+  using Self = abstract_value<T>;
+
+  public:
+  abstract_value()
+  : m_result(std::make_shared<T>())
+  , m_store(m_result.get())
+  {
+  }
+
+  explicit abstract_value(T* t)
+  : m_store(t)
+  {
+  }
+
+  ~abstract_value() override = default;
+
+  abstract_value& operator=(const abstract_value&) = default;
+
+  abstract_value(const abstract_value& rhs)
+  {
+    if (rhs.m_result)
+    {
+      m_result = std::make_shared<T>();
+      m_store = m_result.get();
+    }
+    else
+    {
+      m_store = rhs.m_store;
+    }
+
+    m_default = rhs.m_default;
+    m_implicit = rhs.m_implicit;
+    m_default_value = rhs.m_default_value;
+    m_implicit_value = rhs.m_implicit_value;
+  }
+
+  void
+  add(const std::string& text) const override
+  {
+    add_value(text, *m_store);
+  }
+
+  void
+  parse(const std::string& text) const override
+  {
+    parse_value(text, *m_store);
+  }
+
+  bool
+  is_container() const override
+  {
+    return type_is_container<T>::value;
+  }
+
+  void
+  parse() const override
+  {
+    parse_value(m_default_value, *m_store);
+  }
+
+  bool
+  has_default() const override
+  {
+    return m_default;
+  }
+
+  bool
+  has_implicit() const override
+  {
+    return m_implicit;
+  }
+
+  std::shared_ptr<Value>
+  default_value(const std::string& value) override
+  {
+    m_default = true;
+    m_default_value = value;
+    return shared_from_this();
+  }
+
+  std::shared_ptr<Value>
+  implicit_value(const std::string& value) override
+  {
+    m_implicit = true;
+    m_implicit_value = value;
+    return shared_from_this();
+  }
+
+  std::shared_ptr<Value>
+  no_implicit_value() override
+  {
+    m_implicit = false;
+    return shared_from_this();
+  }
+
+  std::string
+  get_default_value() const override
+  {
+    return m_default_value;
+  }
+
+  std::string
+  get_implicit_value() const override
+  {
+    return m_implicit_value;
+  }
+
+  bool
+  is_boolean() const override
+  {
+    return std::is_same<T, bool>::value;
+  }
+
+  const T&
+  get() const
+  {
+    if (m_store == nullptr)
+    {
+      return *m_result;
+    }
+    return *m_store;
+  }
+
+  protected:
+  std::shared_ptr<T> m_result{};
+  T* m_store{};
+
+  bool m_default = false;
+  bool m_implicit = false;
+
+  std::string m_default_value{};
+  std::string m_implicit_value{};
+};
+
+template <typename T>
+class standard_value : public abstract_value<T>
+{
+  public:
+  using abstract_value<T>::abstract_value;
+
+  CXXOPTS_NODISCARD
+  std::shared_ptr<Value>
+  clone() const override
+  {
+    return std::make_shared<standard_value<T>>(*this);
+  }
+};
+
+template <>
+class standard_value<bool> : public abstract_value<bool>
+{
+  public:
+  ~standard_value() override = default;
+
+  standard_value()
+  {
+    set_default_and_implicit();
+  }
+
+  explicit standard_value(bool* b)
+  : abstract_value(b)
+  {
+    m_implicit = true;
+    m_implicit_value = "true";
+  }
+
+  std::shared_ptr<Value>
+  clone() const override
+  {
+    return std::make_shared<standard_value<bool>>(*this);
+  }
+
+  private:
+
+  void
+  set_default_and_implicit()
+  {
+    m_default = true;
+    m_default_value = "false";
+    m_implicit = true;
+    m_implicit_value = "true";
+  }
+};
+
+} // namespace values
+
+template <typename T>
+std::shared_ptr<Value>
+value()
+{
+  return std::make_shared<values::standard_value<T>>();
+}
+
+template <typename T>
+std::shared_ptr<Value>
+value(T& t)
+{
+  return std::make_shared<values::standard_value<T>>(&t);
+}
+
+class OptionAdder;
+
+CXXOPTS_NODISCARD
+inline
+const std::string&
+first_or_empty(const OptionNames& long_names)
+{
+  static const std::string empty{""};
+  return long_names.empty() ? empty : long_names.front();
+}
+
+class OptionDetails
+{
+  public:
+  OptionDetails
+  (
+    std::string short_,
+    OptionNames long_,
+    String desc,
+    std::shared_ptr<const Value> val
+  )
+  : m_short(std::move(short_))
+  , m_long(std::move(long_))
+  , m_desc(std::move(desc))
+  , m_value(std::move(val))
+  , m_count(0)
+  {
+    m_hash = std::hash<std::string>{}(first_long_name() + m_short);
+  }
+
+  OptionDetails(const OptionDetails& rhs)
+  : m_desc(rhs.m_desc)
+  , m_value(rhs.m_value->clone())
+  , m_count(rhs.m_count)
+  {
+  }
+
+  OptionDetails(OptionDetails&& rhs) = default;
+
+  CXXOPTS_NODISCARD
+  const String&
+  description() const
+  {
+    return m_desc;
+  }
+
+  CXXOPTS_NODISCARD
+  const Value&
+  value() const {
+      return *m_value;
+  }
+
+  CXXOPTS_NODISCARD
+  std::shared_ptr<Value>
+  make_storage() const
+  {
+    return m_value->clone();
+  }
+
+  CXXOPTS_NODISCARD
+  const std::string&
+  short_name() const
+  {
+    return m_short;
+  }
+
+  CXXOPTS_NODISCARD
+  const std::string&
+  first_long_name() const
+  {
+    return first_or_empty(m_long);
+  }
+
+  CXXOPTS_NODISCARD
+  const std::string&
+  essential_name() const
+  {
+    return m_long.empty() ? m_short : m_long.front();
+  }
+
+  CXXOPTS_NODISCARD
+  const OptionNames &
+  long_names() const
+  {
+    return m_long;
+  }
+
+  std::size_t
+  hash() const
+  {
+    return m_hash;
+  }
+
+  private:
+  std::string m_short{};
+  OptionNames m_long{};
+  String m_desc{};
+  std::shared_ptr<const Value> m_value{};
+  int m_count;
+
+  std::size_t m_hash{};
+};
+
+struct HelpOptionDetails
+{
+  std::string s;
+  OptionNames l;
+  String desc;
+  bool has_default;
+  std::string default_value;
+  bool has_implicit;
+  std::string implicit_value;
+  std::string arg_help;
+  bool is_container;
+  bool is_boolean;
+};
+
+struct HelpGroupDetails
+{
+  std::string name{};
+  std::string description{};
+  std::vector<HelpOptionDetails> options{};
+};
+
+class OptionValue
+{
+  public:
+  void
+  add
+  (
+    const std::shared_ptr<const OptionDetails>& details,
+    const std::string& text
+  )
+  {
+    ensure_value(details);
+    ++m_count;
+    m_value->add(text);
+    m_long_names = &details->long_names();
+  }
+
+  void
+  parse
+  (
+    const std::shared_ptr<const OptionDetails>& details,
+    const std::string& text
+  )
+  {
+    ensure_value(details);
+    ++m_count;
+    m_value->parse(text);
+    m_long_names = &details->long_names();
+  }
+
+  void
+  parse_default(const std::shared_ptr<const OptionDetails>& details)
+  {
+    ensure_value(details);
+    m_default = true;
+    m_long_names = &details->long_names();
+    m_value->parse();
+  }
+
+  void
+  parse_no_value(const std::shared_ptr<const OptionDetails>& details)
+  {
+    m_long_names = &details->long_names();
+  }
+
+#if defined(CXXOPTS_NULL_DEREF_IGNORE)
+CXXOPTS_DIAGNOSTIC_PUSH
+CXXOPTS_IGNORE_WARNING("-Wnull-dereference")
+#endif
+
+  CXXOPTS_NODISCARD
+  std::size_t
+  count() const noexcept
+  {
+    return m_count;
+  }
+
+#if defined(CXXOPTS_NULL_DEREF_IGNORE)
+CXXOPTS_DIAGNOSTIC_POP
+#endif
+
+  // TODO: maybe default options should count towards the number of arguments
+  CXXOPTS_NODISCARD
+  bool
+  has_default() const noexcept
+  {
+    return m_default;
+  }
+
+  template <typename T>
+  const T&
+  as() const
+  {
+    if (m_value == nullptr) {
+        throw_or_mimic<exceptions::option_has_no_value>(
+            m_long_names == nullptr ? "" : first_or_empty(*m_long_names));
+    }
+
+    return CXXOPTS_RTTI_CAST<const values::standard_value<T>&>(*m_value).get();
+  }
+
+#ifdef CXXOPTS_HAS_OPTIONAL
+  template <typename T>
+  std::optional<T>
+  as_optional() const
+  {
+    if (m_value == nullptr) {
+      return std::nullopt;
+    }
+    return as<T>();
+  }
+#endif
+
+  private:
+  void
+  ensure_value(const std::shared_ptr<const OptionDetails>& details)
+  {
+    if (m_value == nullptr)
+    {
+      m_value = details->make_storage();
+    }
+  }
+
+
+  const OptionNames * m_long_names = nullptr;
+  // Holding this pointer is safe, since OptionValue's only exist in key-value pairs,
+  // where the key has the string we point to.
+  std::shared_ptr<Value> m_value{};
+  std::size_t m_count = 0;
+  bool m_default = false;
+};
+
+class KeyValue
+{
+  public:
+  KeyValue(std::string key_, std::string value_) noexcept
+  : m_key(std::move(key_))
+  , m_value(std::move(value_))
+  {
+  }
+
+  CXXOPTS_NODISCARD
+  const std::string&
+  key() const
+  {
+    return m_key;
+  }
+
+  CXXOPTS_NODISCARD
+  const std::string&
+  value() const
+  {
+    return m_value;
+  }
+
+  template <typename T>
+  T
+  as() const
+  {
+    T result;
+    values::parse_value(m_value, result);
+    return result;
+  }
+
+  private:
+  std::string m_key;
+  std::string m_value;
+};
+
+using ParsedHashMap = std::unordered_map<std::size_t, OptionValue>;
+using NameHashMap = std::unordered_map<std::string, std::size_t>;
+
+class ParseResult
+{
+  public:
+  class Iterator
+  {
+    public:
+    using iterator_category = std::forward_iterator_tag;
+    using value_type = KeyValue;
+    using difference_type = void;
+    using pointer = const KeyValue*;
+    using reference = const KeyValue&;
+
+    Iterator() = default;
+    Iterator(const Iterator&) = default;
+
+// GCC complains about m_iter not being initialised in the member
+// initializer list
+CXXOPTS_DIAGNOSTIC_PUSH
+CXXOPTS_IGNORE_WARNING("-Weffc++")
+    Iterator(const ParseResult *pr, bool end=false)
+    : m_pr(pr)
+    {
+      if (end)
+      {
+        m_sequential = false;
+        m_iter = m_pr->m_defaults.end();
+      }
+      else
+      {
+        m_sequential = true;
+        m_iter = m_pr->m_sequential.begin();
+
+        if (m_iter == m_pr->m_sequential.end())
+        {
+          m_sequential = false;
+          m_iter = m_pr->m_defaults.begin();
+        }
+      }
+    }
+CXXOPTS_DIAGNOSTIC_POP
+
+    Iterator& operator++()
+    {
+      ++m_iter;
+      if(m_sequential && m_iter == m_pr->m_sequential.end())
+      {
+        m_sequential = false;
+        m_iter = m_pr->m_defaults.begin();
+        return *this;
+      }
+      return *this;
+    }
+
+    Iterator operator++(int)
+    {
+      Iterator retval = *this;
+      ++(*this);
+      return retval;
+    }
+
+    bool operator==(const Iterator& other) const
+    {
+      return (m_sequential == other.m_sequential) && (m_iter == other.m_iter);
+    }
+
+    bool operator!=(const Iterator& other) const
+    {
+      return !(*this == other);
+    }
+
+    const KeyValue& operator*()
+    {
+      return *m_iter;
+    }
+
+    const KeyValue* operator->()
+    {
+      return m_iter.operator->();
+    }
+
+    private:
+    const ParseResult* m_pr;
+    std::vector<KeyValue>::const_iterator m_iter;
+    bool m_sequential = true;
+  };
+
+  ParseResult() = default;
+  ParseResult(const ParseResult&) = default;
+
+  ParseResult(NameHashMap&& keys, ParsedHashMap&& values, std::vector<KeyValue> sequential,
+          std::vector<KeyValue> default_opts, std::vector<std::string>&& unmatched_args)
+  : m_keys(std::move(keys))
+  , m_values(std::move(values))
+  , m_sequential(std::move(sequential))
+  , m_defaults(std::move(default_opts))
+  , m_unmatched(std::move(unmatched_args))
+  {
+  }
+
+  ParseResult& operator=(ParseResult&&) = default;
+  ParseResult& operator=(const ParseResult&) = default;
+
+  Iterator
+  begin() const
+  {
+    return Iterator(this);
+  }
+
+  Iterator
+  end() const
+  {
+    return Iterator(this, true);
+  }
+
+  std::size_t
+  count(const std::string& o) const
+  {
+    auto iter = m_keys.find(o);
+    if (iter == m_keys.end())
+    {
+      return 0;
+    }
+
+    auto viter = m_values.find(iter->second);
+
+    if (viter == m_values.end())
+    {
+      return 0;
+    }
+
+    return viter->second.count();
+  }
+
+  bool
+  contains(const std::string& o) const
+  {
+    return static_cast<bool>(count(o));
+  }
+
+  const OptionValue&
+  operator[](const std::string& option) const
+  {
+    auto iter = m_keys.find(option);
+
+    if (iter == m_keys.end())
+    {
+      throw_or_mimic<exceptions::requested_option_not_present>(option);
+    }
+
+    auto viter = m_values.find(iter->second);
+
+    if (viter == m_values.end())
+    {
+      throw_or_mimic<exceptions::requested_option_not_present>(option);
+    }
+
+    return viter->second;
+  }
+
+#ifdef CXXOPTS_HAS_OPTIONAL
+  template <typename T>
+  std::optional<T>
+  as_optional(const std::string& option) const
+  {
+    auto iter = m_keys.find(option);
+    if (iter != m_keys.end())
+    {
+      auto viter = m_values.find(iter->second);
+      if (viter != m_values.end())
+      {
+        return viter->second.as_optional<T>();
+      }
+    }
+    return std::nullopt;
+  }
+#endif
+
+  const std::vector<KeyValue>&
+  arguments() const
+  {
+    return m_sequential;
+  }
+
+  const std::vector<std::string>&
+  unmatched() const
+  {
+    return m_unmatched;
+  }
+
+  const std::vector<KeyValue>&
+  defaults() const
+  {
+    return m_defaults;
+  }
+
+  const std::string
+  arguments_string() const
+  {
+    std::string result;
+    for(const auto& kv: m_sequential)
+    {
+      result += kv.key() + " = " + kv.value() + "\n";
+    }
+    for(const auto& kv: m_defaults)
+    {
+      result += kv.key() + " = " + kv.value() + " " + "(default)" + "\n";
+    }
+    return result;
+  }
+
+  private:
+  NameHashMap m_keys{};
+  ParsedHashMap m_values{};
+  std::vector<KeyValue> m_sequential{};
+  std::vector<KeyValue> m_defaults{};
+  std::vector<std::string> m_unmatched{};
+};
+
+struct Option
+{
+  Option
+  (
+    std::string opts,
+    std::string desc,
+    std::shared_ptr<const Value>  value = ::cxxopts::value<bool>(),
+    std::string arg_help = ""
+  )
+  : opts_(std::move(opts))
+  , desc_(std::move(desc))
+  , value_(std::move(value))
+  , arg_help_(std::move(arg_help))
+  {
+  }
+
+  std::string opts_;
+  std::string desc_;
+  std::shared_ptr<const Value> value_;
+  std::string arg_help_;
+};
+
+using OptionMap = std::unordered_map<std::string, std::shared_ptr<OptionDetails>>;
+using PositionalList = std::vector<std::string>;
+using PositionalListIterator = PositionalList::const_iterator;
+
+class OptionParser
+{
+  public:
+  OptionParser(const OptionMap& options, const PositionalList& positional, bool allow_unrecognised)
+  : m_options(options)
+  , m_positional(positional)
+  , m_allow_unrecognised(allow_unrecognised)
+  {
+  }
+
+  ParseResult
+  parse(int argc, const char* const* argv);
+
+  bool
+  consume_positional(const std::string& a, PositionalListIterator& next);
+
+  void
+  checked_parse_arg
+  (
+    int argc,
+    const char* const* argv,
+    int& current,
+    const std::shared_ptr<OptionDetails>& value,
+    const std::string& name
+  );
+
+  void
+  add_to_option(const std::shared_ptr<OptionDetails>& value, const std::string& arg);
+
+  void
+  parse_option
+  (
+    const std::shared_ptr<OptionDetails>& value,
+    const std::string& name,
+    const std::string& arg = ""
+  );
+
+  void
+  parse_default(const std::shared_ptr<OptionDetails>& details);
+
+  void
+  parse_no_value(const std::shared_ptr<OptionDetails>& details);
+
+  private:
+
+  void finalise_aliases();
+
+  const OptionMap& m_options;
+  const PositionalList& m_positional;
+
+  std::vector<KeyValue> m_sequential{};
+  std::vector<KeyValue> m_defaults{};
+  bool m_allow_unrecognised;
+
+  ParsedHashMap m_parsed{};
+  NameHashMap m_keys{};
+};
+
+class Options
+{
+  public:
+
+  explicit Options(std::string program_name, std::string help_string = "")
+  : m_program(std::move(program_name))
+  , m_help_string(toLocalString(std::move(help_string)))
+  , m_custom_help("[OPTION...]")
+  , m_positional_help("positional parameters")
+  , m_show_positional(false)
+  , m_allow_unrecognised(false)
+  , m_width(76)
+  , m_tab_expansion(false)
+  , m_options(std::make_shared<OptionMap>())
+  {
+  }
+
+  Options&
+  positional_help(std::string help_text)
+  {
+    m_positional_help = std::move(help_text);
+    return *this;
+  }
+
+  Options&
+  custom_help(std::string help_text)
+  {
+    m_custom_help = std::move(help_text);
+    return *this;
+  }
+
+  Options&
+  show_positional_help()
+  {
+    m_show_positional = true;
+    return *this;
+  }
+
+  Options&
+  allow_unrecognised_options()
+  {
+    m_allow_unrecognised = true;
+    return *this;
+  }
+
+  Options&
+  set_width(std::size_t width)
+  {
+    m_width = width;
+    return *this;
+  }
+
+  Options&
+  set_tab_expansion(bool expansion=true)
+  {
+    m_tab_expansion = expansion;
+    return *this;
+  }
+
+  ParseResult
+  parse(int argc, const char* const* argv);
+
+  OptionAdder
+  add_options(std::string group = "");
+
+  void
+  add_options
+  (
+    const std::string& group,
+    std::initializer_list<Option> options
+  );
+
+  void
+  add_option
+  (
+    const std::string& group,
+    const Option& option
+  );
+
+  void
+  add_option
+  (
+    const std::string& group,
+    const std::string& s,
+    const OptionNames& l,
+    std::string desc,
+    const std::shared_ptr<const Value>& value,
+    std::string arg_help
+  );
+
+  void
+  add_option
+  (
+    const std::string& group,
+    const std::string& short_name,
+    const std::string& single_long_name,
+    std::string desc,
+    const std::shared_ptr<const Value>& value,
+    std::string arg_help
+  )
+  {
+    OptionNames long_names;
+    long_names.emplace_back(single_long_name);
+    add_option(group, short_name, long_names, desc, value, arg_help);
+  }
+
+  //parse positional arguments into the given option
+  void
+  parse_positional(std::string option);
+
+  void
+  parse_positional(std::vector<std::string> options);
+
+  void
+  parse_positional(std::initializer_list<std::string> options);
+
+  template <typename Iterator>
+  void
+  parse_positional(Iterator begin, Iterator end) {
+    parse_positional(std::vector<std::string>{begin, end});
+  }
+
+  std::string
+  help(const std::vector<std::string>& groups = {}, bool print_usage=true) const;
+
+  std::vector<std::string>
+  groups() const;
+
+  const HelpGroupDetails&
+  group_help(const std::string& group) const;
+
+  const std::string& program() const
+  {
+    return m_program;
+  }
+
+  private:
+
+  void
+  add_one_option
+  (
+    const std::string& option,
+    const std::shared_ptr<OptionDetails>& details
+  );
+
+  String
+  help_one_group(const std::string& group) const;
+
+  void
+  generate_group_help
+  (
+    String& result,
+    const std::vector<std::string>& groups
+  ) const;
+
+  void
+  generate_all_groups_help(String& result) const;
+
+  std::string m_program{};
+  String m_help_string{};
+  std::string m_custom_help{};
+  std::string m_positional_help{};
+  bool m_show_positional;
+  bool m_allow_unrecognised;
+  std::size_t m_width;
+  bool m_tab_expansion;
+
+  std::shared_ptr<OptionMap> m_options;
+  std::vector<std::string> m_positional{};
+  std::unordered_set<std::string> m_positional_set{};
+
+  //mapping from groups to help options
+  std::vector<std::string> m_group{};
+  std::map<std::string, HelpGroupDetails> m_help{};
+};
+
+class OptionAdder
+{
+  public:
+
+  OptionAdder(Options& options, std::string group)
+  : m_options(options), m_group(std::move(group))
+  {
+  }
+
+  OptionAdder&
+  operator()
+  (
+    const std::string& opts,
+    const std::string& desc,
+    const std::shared_ptr<const Value>& value
+      = ::cxxopts::value<bool>(),
+    std::string arg_help = ""
+  );
+
+  private:
+  Options& m_options;
+  std::string m_group;
+};
+
+namespace {
+constexpr std::size_t OPTION_LONGEST = 30;
+constexpr std::size_t OPTION_DESC_GAP = 2;
+
+String
+format_option
+(
+  const HelpOptionDetails& o
+)
+{
+  const auto& s = o.s;
+  const auto& l = first_or_empty(o.l);
+
+  String result = "  ";
+
+  if (!s.empty())
+  {
+    result += "-" + toLocalString(s);
+    if (!l.empty())
+    {
+      result += ",";
+    }
+  }
+  else
+  {
+    result += "   ";
+  }
+
+  if (!l.empty())
+  {
+    result += " --" + toLocalString(l);
+  }
+
+  auto arg = !o.arg_help.empty() ? toLocalString(o.arg_help) : "arg";
+
+  if (!o.is_boolean)
+  {
+    if (o.has_implicit)
+    {
+      result += " [=" + arg + "(=" + toLocalString(o.implicit_value) + ")]";
+    }
+    else
+    {
+      result += " " + arg;
+    }
+  }
+
+  return result;
+}
+
+String
+format_description
+(
+  const HelpOptionDetails& o,
+  std::size_t start,
+  std::size_t allowed,
+  bool tab_expansion
+)
+{
+  auto desc = o.desc;
+
+  if (o.has_default && (!o.is_boolean || o.default_value != "false"))
+  {
+    if(!o.default_value.empty())
+    {
+      desc += toLocalString(" (default: " + o.default_value + ")");
+    }
+    else
+    {
+      desc += toLocalString(" (default: \"\")");
+    }
+  }
+
+  String result;
+
+  if (tab_expansion)
+  {
+    String desc2;
+    auto size = std::size_t{ 0 };
+    for (auto c = std::begin(desc); c != std::end(desc); ++c)
+    {
+      if (*c == '\n')
+      {
+        desc2 += *c;
+        size = 0;
+      }
+      else if (*c == '\t')
+      {
+        auto skip = 8 - size % 8;
+        stringAppend(desc2, skip, ' ');
+        size += skip;
+      }
+      else
+      {
+        desc2 += *c;
+        ++size;
+      }
+    }
+    desc = desc2;
+  }
+
+  desc += " ";
+
+  auto current = std::begin(desc);
+  auto previous = current;
+  auto startLine = current;
+  auto lastSpace = current;
+
+  auto size = std::size_t{};
+
+  bool appendNewLine;
+  bool onlyWhiteSpace = true;
+
+  while (current != std::end(desc))
+  {
+    appendNewLine = false;
+    if (*previous == ' ' || *previous == '\t')
+    {
+      lastSpace = current;
+    }
+    if (*current != ' ' && *current != '\t')
+    {
+      onlyWhiteSpace = false;
+    }
+
+    while (*current == '\n')
+    {
+      previous = current;
+      ++current;
+      appendNewLine = true;
+    }
+
+    if (!appendNewLine && size >= allowed)
+    {
+      if (lastSpace != startLine)
+      {
+        current = lastSpace;
+        previous = current;
+      }
+      appendNewLine = true;
+    }
+
+    if (appendNewLine)
+    {
+      stringAppend(result, startLine, current);
+      startLine = current;
+      lastSpace = current;
+
+      if (*previous != '\n')
+      {
+        stringAppend(result, "\n");
+      }
+
+      stringAppend(result, start, ' ');
+
+      if (*previous != '\n')
+      {
+        stringAppend(result, lastSpace, current);
+      }
+
+      onlyWhiteSpace = true;
+      size = 0;
+    }
+
+    previous = current;
+    ++current;
+    ++size;
+  }
+
+  //append whatever is left but ignore whitespace
+  if (!onlyWhiteSpace)
+  {
+    stringAppend(result, startLine, previous);
+  }
+
+  return result;
+}
+
+} // namespace
+
+inline
+void
+Options::add_options
+(
+  const std::string &group,
+  std::initializer_list<Option> options
+)
+{
+ OptionAdder option_adder(*this, group);
+ for (const auto &option: options)
+ {
+   option_adder(option.opts_, option.desc_, option.value_, option.arg_help_);
+ }
+}
+
+inline
+OptionAdder
+Options::add_options(std::string group)
+{
+  return OptionAdder(*this, std::move(group));
+}
+
+inline
+OptionAdder&
+OptionAdder::operator()
+(
+  const std::string& opts,
+  const std::string& desc,
+  const std::shared_ptr<const Value>& value,
+  std::string arg_help
+)
+{
+  OptionNames option_names = values::parser_tool::split_option_names(opts);
+    // Note: All names will be non-empty; but we must separate the short
+    // (length-1) and longer names
+  std::string short_name {""};
+  auto first_short_name_iter =
+    std::partition(option_names.begin(), option_names.end(),
+      [&](const std::string& name) { return name.length() > 1; }
+    );
+  auto num_length_1_names = (option_names.end() - first_short_name_iter);
+  switch(num_length_1_names) {
+  case 1:
+    short_name = *first_short_name_iter;
+    option_names.erase(first_short_name_iter);
+    CXXOPTS_FALLTHROUGH;
+  case 0:
+    break;
+  default:
+    throw_or_mimic<exceptions::invalid_option_format>(opts);
+  };
+
+  m_options.add_option
+  (
+    m_group,
+    short_name,
+    option_names,
+    desc,
+    value,
+    std::move(arg_help)
+  );
+
+  return *this;
+}
+
+inline
+void
+OptionParser::parse_default(const std::shared_ptr<OptionDetails>& details)
+{
+  // TODO: remove the duplicate code here
+  auto& store = m_parsed[details->hash()];
+  store.parse_default(details);
+  m_defaults.emplace_back(details->essential_name(), details->value().get_default_value());
+}
+
+inline
+void
+OptionParser::parse_no_value(const std::shared_ptr<OptionDetails>& details)
+{
+  auto& store = m_parsed[details->hash()];
+  store.parse_no_value(details);
+}
+
+inline
+void
+OptionParser::parse_option
+(
+  const std::shared_ptr<OptionDetails>& value,
+  const std::string& /*name*/,
+  const std::string& arg
+)
+{
+  auto hash = value->hash();
+  auto& result = m_parsed[hash];
+  result.parse(value, arg);
+
+  m_sequential.emplace_back(value->essential_name(), arg);
+}
+
+inline
+void
+OptionParser::checked_parse_arg
+(
+  int argc,
+  const char* const* argv,
+  int& current,
+  const std::shared_ptr<OptionDetails>& value,
+  const std::string& name
+)
+{
+  if (current + 1 >= argc)
+  {
+    if (value->value().has_implicit())
+    {
+      parse_option(value, name, value->value().get_implicit_value());
+    }
+    else
+    {
+      throw_or_mimic<exceptions::missing_argument>(name);
+    }
+  }
+  else
+  {
+    if (value->value().has_implicit())
+    {
+      parse_option(value, name, value->value().get_implicit_value());
+    }
+    else
+    {
+      parse_option(value, name, argv[current + 1]);
+      ++current;
+    }
+  }
+}
+
+inline
+void
+OptionParser::add_to_option(const std::shared_ptr<OptionDetails>& value, const std::string& arg)
+{
+  auto hash = value->hash();
+  auto& result = m_parsed[hash];
+  result.add(value, arg);
+
+  m_sequential.emplace_back(value->essential_name(), arg);
+}
+
+inline
+bool
+OptionParser::consume_positional(const std::string& a, PositionalListIterator& next)
+{
+  while (next != m_positional.end())
+  {
+    auto iter = m_options.find(*next);
+    if (iter != m_options.end())
+    {
+      if (!iter->second->value().is_container())
+      {
+        auto& result = m_parsed[iter->second->hash()];
+        if (result.count() == 0)
+        {
+          add_to_option(iter->second, a);
+          ++next;
+          return true;
+        }
+        ++next;
+        continue;
+      }
+      add_to_option(iter->second, a);
+      return true;
+    }
+    throw_or_mimic<exceptions::no_such_option>(*next);
+  }
+
+  return false;
+}
+
+inline
+void
+Options::parse_positional(std::string option)
+{
+  parse_positional(std::vector<std::string>{std::move(option)});
+}
+
+inline
+void
+Options::parse_positional(std::vector<std::string> options)
+{
+  m_positional = std::move(options);
+
+  m_positional_set.insert(m_positional.begin(), m_positional.end());
+}
+
+inline
+void
+Options::parse_positional(std::initializer_list<std::string> options)
+{
+  parse_positional(std::vector<std::string>(options));
+}
+
+inline
+ParseResult
+Options::parse(int argc, const char* const* argv)
+{
+  OptionParser parser(*m_options, m_positional, m_allow_unrecognised);
+
+  return parser.parse(argc, argv);
+}
+
+inline ParseResult
+OptionParser::parse(int argc, const char* const* argv)
+{
+  int current = 1;
+  bool consume_remaining = false;
+  auto next_positional = m_positional.begin();
+
+  std::vector<std::string> unmatched;
+
+  while (current != argc)
+  {
+    if (strcmp(argv[current], "--") == 0)
+    {
+      consume_remaining = true;
+      ++current;
+      break;
+    }
+    bool matched = false;
+    values::parser_tool::ArguDesc argu_desc =
+        values::parser_tool::ParseArgument(argv[current], matched);
+
+    if (!matched)
+    {
+      //not a flag
+
+      // but if it starts with a `-`, then it's an error
+      if (argv[current][0] == '-' && argv[current][1] != '\0') {
+        if (!m_allow_unrecognised) {
+          throw_or_mimic<exceptions::invalid_option_syntax>(argv[current]);
+        }
+      }
+
+      //if true is returned here then it was consumed, otherwise it is
+      //ignored
+      if (consume_positional(argv[current], next_positional))
+      {
+      }
+      else
+      {
+        unmatched.emplace_back(argv[current]);
+      }
+      //if we return from here then it was parsed successfully, so continue
+    }
+    else
+    {
+      //short or long option?
+      if (argu_desc.grouping)
+      {
+        const std::string& s = argu_desc.arg_name;
+
+        for (std::size_t i = 0; i != s.size(); ++i)
+        {
+          std::string name(1, s[i]);
+          auto iter = m_options.find(name);
+
+          if (iter == m_options.end())
+          {
+            if (m_allow_unrecognised)
+            {
+              unmatched.push_back(std::string("-") + s[i]);
+              continue;
+            }
+            //error
+            throw_or_mimic<exceptions::no_such_option>(name);
+          }
+
+          auto value = iter->second;
+
+          if (i + 1 == s.size())
+          {
+            //it must be the last argument
+            checked_parse_arg(argc, argv, current, value, name);
+          }
+          else if (value->value().has_implicit())
+          {
+            parse_option(value, name, value->value().get_implicit_value());
+          }
+          else if (i + 1 < s.size())
+          {
+            std::string arg_value = s.substr(i + 1);
+            parse_option(value, name, arg_value);
+            break;
+          }
+          else
+          {
+            //error
+            throw_or_mimic<exceptions::option_requires_argument>(name);
+          }
+        }
+      }
+      else if (argu_desc.arg_name.length() != 0)
+      {
+        const std::string& name = argu_desc.arg_name;
+
+        auto iter = m_options.find(name);
+
+        if (iter == m_options.end())
+        {
+          if (m_allow_unrecognised)
+          {
+            // keep unrecognised options in argument list, skip to next argument
+            unmatched.emplace_back(argv[current]);
+            ++current;
+            continue;
+          }
+          //error
+          throw_or_mimic<exceptions::no_such_option>(name);
+        }
+
+        auto opt = iter->second;
+
+        //equals provided for long option?
+        if (argu_desc.set_value)
+        {
+          //parse the option given
+
+          parse_option(opt, name, argu_desc.value);
+        }
+        else
+        {
+          //parse the next argument
+          checked_parse_arg(argc, argv, current, opt, name);
+        }
+      }
+
+    }
+
+    ++current;
+  }
+
+  for (auto& opt : m_options)
+  {
+    auto& detail = opt.second;
+    const auto& value = detail->value();
+
+    auto& store = m_parsed[detail->hash()];
+
+    if (value.has_default()) {
+      if (!store.count() && !store.has_default()) {
+        parse_default(detail);
+      }
+    }
+    else {
+      parse_no_value(detail);
+    }
+  }
+
+  if (consume_remaining)
+  {
+    while (current < argc)
+    {
+      if (!consume_positional(argv[current], next_positional)) {
+        break;
+      }
+      ++current;
+    }
+
+    //adjust argv for any that couldn't be swallowed
+    while (current != argc) {
+      unmatched.emplace_back(argv[current]);
+      ++current;
+    }
+  }
+
+  finalise_aliases();
+
+  ParseResult parsed(std::move(m_keys), std::move(m_parsed), std::move(m_sequential), std::move(m_defaults), std::move(unmatched));
+  return parsed;
+}
+
+inline
+void
+OptionParser::finalise_aliases()
+{
+  for (auto& option: m_options)
+  {
+    auto& detail = *option.second;
+    auto hash = detail.hash();
+    m_keys[detail.short_name()] = hash;
+    for(const auto& long_name : detail.long_names()) {
+      m_keys[long_name] = hash;
+    }
+
+    m_parsed.emplace(hash, OptionValue());
+  }
+}
+
+inline
+void
+Options::add_option
+(
+  const std::string& group,
+  const Option& option
+)
+{
+    add_options(group, {option});
+}
+
+inline
+void
+Options::add_option
+(
+  const std::string& group,
+  const std::string& s,
+  const OptionNames& l,
+  std::string desc,
+  const std::shared_ptr<const Value>& value,
+  std::string arg_help
+)
+{
+  auto stringDesc = toLocalString(std::move(desc));
+  auto option = std::make_shared<OptionDetails>(s, l, stringDesc, value);
+
+  if (!s.empty())
+  {
+    add_one_option(s, option);
+  }
+
+  for(const auto& long_name : l) {
+    add_one_option(long_name, option);
+  }
+
+  //add the help details
+
+  if (m_help.find(group) == m_help.end())
+  {
+    m_group.push_back(group);
+  }
+
+  auto& options = m_help[group];
+
+  options.options.emplace_back(HelpOptionDetails{s, l, stringDesc,
+      value->has_default(), value->get_default_value(),
+      value->has_implicit(), value->get_implicit_value(),
+      std::move(arg_help),
+      value->is_container(),
+      value->is_boolean()});
+}
+
+inline
+void
+Options::add_one_option
+(
+  const std::string& option,
+  const std::shared_ptr<OptionDetails>& details
+)
+{
+  auto in = m_options->emplace(option, details);
+
+  if (!in.second)
+  {
+    throw_or_mimic<exceptions::option_already_exists>(option);
+  }
+}
+
+inline
+String
+Options::help_one_group(const std::string& g) const
+{
+  using OptionHelp = std::vector<std::pair<String, String>>;
+
+  auto group = m_help.find(g);
+  if (group == m_help.end())
+  {
+    return "";
+  }
+
+  OptionHelp format;
+
+  std::size_t longest = 0;
+
+  String result;
+
+  if (!g.empty())
+  {
+    result += toLocalString(" " + g + " options:\n");
+  }
+
+  for (const auto& o : group->second.options)
+  {
+    if (o.l.size() &&
+        m_positional_set.find(o.l.front()) != m_positional_set.end() &&
+        !m_show_positional)
+    {
+      continue;
+    }
+
+    auto s = format_option(o);
+    longest = (std::max)(longest, stringLength(s));
+    format.push_back(std::make_pair(s, String()));
+  }
+  longest = (std::min)(longest, OPTION_LONGEST);
+
+  //widest allowed description -- min 10 chars for helptext/line
+  std::size_t allowed = 10;
+  if (m_width > allowed + longest + OPTION_DESC_GAP)
+  {
+    allowed = m_width - longest - OPTION_DESC_GAP;
+  }
+
+  auto fiter = format.begin();
+  for (const auto& o : group->second.options)
+  {
+    if (o.l.size() &&
+        m_positional_set.find(o.l.front()) != m_positional_set.end() &&
+        !m_show_positional)
+    {
+      continue;
+    }
+
+    auto d = format_description(o, longest + OPTION_DESC_GAP, allowed, m_tab_expansion);
+
+    result += fiter->first;
+    if (stringLength(fiter->first) > longest)
+    {
+      result += '\n';
+      result += toLocalString(std::string(longest + OPTION_DESC_GAP, ' '));
+    }
+    else
+    {
+      result += toLocalString(std::string(longest + OPTION_DESC_GAP -
+        stringLength(fiter->first),
+        ' '));
+    }
+    result += d;
+    result += '\n';
+
+    ++fiter;
+  }
+
+  return result;
+}
+
+inline
+void
+Options::generate_group_help
+(
+  String& result,
+  const std::vector<std::string>& print_groups
+) const
+{
+  for (std::size_t i = 0; i != print_groups.size(); ++i)
+  {
+    const String& group_help_text = help_one_group(print_groups[i]);
+    if (empty(group_help_text))
+    {
+      continue;
+    }
+    result += group_help_text;
+    if (i < print_groups.size() - 1)
+    {
+      result += '\n';
+    }
+  }
+}
+
+inline
+void
+Options::generate_all_groups_help(String& result) const
+{
+  generate_group_help(result, m_group);
+}
+
+inline
+std::string
+Options::help(const std::vector<std::string>& help_groups, bool print_usage) const
+{
+  String result = m_help_string;
+  if(print_usage)
+  {
+    result+= "\nUsage:\n  " + toLocalString(m_program);
+  }
+
+  if (!m_custom_help.empty())
+  {
+    result += " " + toLocalString(m_custom_help);
+  }
+
+  if (!m_positional.empty() && !m_positional_help.empty()) {
+    result += " " + toLocalString(m_positional_help);
+  }
+
+  result += "\n\n";
+
+  if (help_groups.empty())
+  {
+    generate_all_groups_help(result);
+  }
+  else
+  {
+    generate_group_help(result, help_groups);
+  }
+
+  return toUTF8String(result);
+}
+
+inline
+std::vector<std::string>
+Options::groups() const
+{
+  return m_group;
+}
+
+inline
+const HelpGroupDetails&
+Options::group_help(const std::string& group) const
+{
+  return m_help.at(group);
+}
+
+} // namespace cxxopts
+
+#endif //CXXOPTS_HPP_INCLUDED
\ No newline at end of file
diff --git a/relay_server/main.cc b/relay_server/main.cc
new file mode 100644
index 0000000..f645468
--- /dev/null
+++ b/relay_server/main.cc
@@ -0,0 +1,114 @@
+//
+//    Copyright 2025 Metehan Gezer
+//
+//    Licensed under the Apache License, Version 2.0 (the "License");
+//    you may not use this file except in compliance with the License.
+//    You may obtain a copy of the License at
+//
+//        http://www.apache.org/licenses/LICENSE-2.0
+//
+
+#include <utility>
+
+#include "znet/znet.h"
+#include "znet/p2p/relay.h"
+#include "cxxopts.h"
+
+struct UserData {
+  std::shared_ptr<znet::PeerSession> session_;
+  std::string peer_name_;
+};
+
+std::unordered_map<std::string, std::shared_ptr<UserData>> registry_;
+
+class DefaultPacketHandler : public znet::PacketHandler<DefaultPacketHandler, znet::holepunch::RegisterPeerPacket,
+                                                        znet::holepunch::ConnectPeerPacket> {
+public:
+  DefaultPacketHandler(std::shared_ptr<znet::PeerSession> session) : session_(std::move(session)) { }
+
+  void OnPacket(const znet::holepunch::RegisterPeerPacket& pk) {
+    auto data = session_->user_ptr_typed<UserData>();
+    data->peer_name_ = pk.peer_name_;
+    ZNET_LOG_INFO("{} is identified as {} at {}", session_->session_id(),
+                  data->peer_name_, session_->remote_address()->readable());
+    registry_[pk.peer_name_] = data;
+
+    auto response = std::make_shared<znet::holepunch::RegisterPeerResponsePacket>();
+    response->peer_name_ = data->peer_name_;
+    response->endpoint_ = session_->remote_address();
+    response->ok_ = true;
+    session_->SendPacket(response);
+  }
+
+  void OnPacket(const znet::holepunch::ConnectPeerPacket& pk) {
+    auto data = session_->user_ptr_typed<UserData>();
+    if (data->peer_name_.empty()) {
+      ZNET_LOG_INFO("{} tried to connect to peer {} but didn't identify itself!",
+                    session_->session_id(), pk.target_);
+      return;
+    }
+    auto it = registry_.find(pk.target_);
+    if (it == registry_.end()) {
+      ZNET_LOG_INFO("{} asked for {} but it was not available.",
+                    data->peer_name_, pk.target_);
+      return;
+    }
+    std::shared_ptr<UserData> other_data = it->second;
+
+    auto response = std::make_shared<znet::holepunch::ConnectPeerResponsePacket>();
+    response->target_ = other_data->peer_name_;
+    response->endpoint_ = other_data->session_->remote_address();
+    session_->SendPacket(response);
+  }
+
+  void OnUnknown(std::shared_ptr<znet::Packet> p) {
+  }
+
+private:
+  std::shared_ptr<znet::PeerSession> session_;
+};
+
+bool OnConnectEvent(znet::ServerClientConnectedEvent& event) {
+  znet::PeerSession& session = *event.session();
+  session.SetCodec(znet::holepunch::BuildCodec());
+  session.SetHandler(std::make_shared<DefaultPacketHandler>(event.session()));
+  session.SetUserPointer(std::make_shared<UserData>());
+  return false;
+}
+
+void OnEvent(znet::Event& event) {
+  znet::EventDispatcher dispatcher{event};
+  dispatcher.Dispatch<znet::ServerClientConnectedEvent>(
+      ZNET_BIND_GLOBAL_FN(OnConnectEvent));
+}
+
+int main(int argc, char* argv[]) {
+  cxxopts::Options opts("relay-server","relay-server is a utility for znet that exchanges peer endpoints");
+  opts.add_options()
+        ("p,port", "Port to listen on",
+            cxxopts::value<uint16_t>()->default_value("5001"))
+        ("h,help", "Print usage");
+
+  auto result = opts.parse(argc, argv);
+  if (result["help"].as<bool>()) {
+    std::cout << opts.help() << "\n";
+    return 0;
+  }
+
+  uint16_t port = result["port"].as<uint16_t>();
+  ZNET_LOG_INFO("Starting relay on port {}...", port);
+
+  znet::ServerConfig config{"127.0.0.1", port};
+  znet::Server relay{config};
+  relay.SetEventCallback(ZNET_BIND_GLOBAL_FN(OnEvent));
+
+
+  if (relay.Bind() != znet::Result::Success) {
+    return 1; // Failed to bind
+  }
+  if (relay.Listen() != znet::Result::Success) {
+    return 1;  // Failed to listen
+  }
+  relay.Wait();
+  return 0;
+}
\ No newline at end of file
diff --git a/znet/CMakeLists.txt b/znet/CMakeLists.txt
index 50f3183..0f19c8b 100644
--- a/znet/CMakeLists.txt
+++ b/znet/CMakeLists.txt
@@ -22,6 +22,8 @@ set(ZNET_SOURCES
         src/encryption.cc
         src/transport.cc
         src/peer_session.cc
+        src/dialer.cc
+        src/util.cc
         src/pch.cc
 )
 
diff --git a/znet/include/znet/base/inet_addr.h b/znet/include/znet/base/inet_addr.h
index 75434b7..6653cf7 100644
--- a/znet/include/znet/base/inet_addr.h
+++ b/znet/include/znet/base/inet_addr.h
@@ -44,6 +44,7 @@ class InetAddress {
  public:
   InetAddress(InetProtocolVersion ipv, std::string readable)
       : ipv_(ipv), readable_(std::move(readable)) {}
+  virtual ~InetAddress() = default;
 
   operator bool() const { return is_valid(); }
 
@@ -55,9 +56,11 @@ class InetAddress {
 
   ZNET_NODISCARD InetProtocolVersion ipv() const { return ipv_; }
 
-  ZNET_NODISCARD virtual socklen_t addr_size() const { return 0; }
+  ZNET_NODISCARD virtual socklen_t addr_size() const = 0;
 
-  ZNET_NODISCARD virtual sockaddr* handle_ptr() const { return nullptr; }
+  ZNET_NODISCARD virtual sockaddr* handle_ptr() const = 0;
+
+  ZNET_NODISCARD virtual PortNumber port() const = 0;
 
   static std::unique_ptr<InetAddress> from(const std::string& ip_str, PortNumber port);
   static std::unique_ptr<InetAddress> from(sockaddr* addr);
@@ -84,6 +87,7 @@ class InetAddressIPv4 : public InetAddress {
 
   InetAddressIPv4(IPv4Address ip, PortNumber port)
       : InetAddress(InetProtocolVersion::IPv4, "") {
+
     addr.sin_family = AF_INET;
     addr.sin_port = htons(port);
     addr.sin_addr = ip;
@@ -125,6 +129,10 @@ class InetAddressIPv4 : public InetAddress {
     return (sockaddr*)&addr;
   }
 
+  ZNET_NODISCARD PortNumber port() const override {
+    return addr.sin_port;
+  }
+
  private:
   sockaddr_in addr{};
   bool is_valid_;
@@ -189,6 +197,10 @@ class InetAddressIPv6 : public InetAddress {
     return (sockaddr*)&addr;
   }
 
+  ZNET_NODISCARD PortNumber port() const override {
+    return addr.sin6_port;
+  }
+
  private:
   sockaddr_in6 addr{};
   bool is_valid_;
diff --git a/znet/include/znet/base/types.h b/znet/include/znet/base/types.h
index ef1f1c5..eeb1af0 100644
--- a/znet/include/znet/base/types.h
+++ b/znet/include/znet/base/types.h
@@ -21,6 +21,7 @@ namespace znet {
 
 using PacketId = uint64_t;
 using SessionId = uint64_t;
+using TimePoint = std::chrono::time_point<std::chrono::system_clock>;
 
 enum class Endianness { LittleEndian, BigEndian };
 
diff --git a/znet/include/znet/base/util.h b/znet/include/znet/base/util.h
index 98e8765..284a941 100644
--- a/znet/include/znet/base/util.h
+++ b/znet/include/znet/base/util.h
@@ -50,3 +50,5 @@ struct is_invocable {
  public:
   static constexpr bool value = decltype(test<F>(nullptr))::value;
 };
+
+std::string GeneratePeerName();
\ No newline at end of file
diff --git a/znet/include/znet/buffer.h b/znet/include/znet/buffer.h
index a69b680..2806b5a 100644
--- a/znet/include/znet/buffer.h
+++ b/znet/include/znet/buffer.h
@@ -124,6 +124,50 @@ class Buffer {
     return l;
   }
 
+  std::unique_ptr<InetAddress> ReadInetAddress() {
+    auto ver = ReadInt<uint8_t>();
+    if (ver == 4) {
+      uint32_t raw_ip{};
+      uint16_t raw_port{};
+      Read(&raw_ip, 1);
+      Read(&raw_port, 1);
+      in_addr ip{};
+      ip.s_addr = raw_ip;
+      auto port = ntohs(raw_port);
+      return std::make_unique<InetAddressIPv4>(ip, port);
+    }
+    if (ver == 6) {
+      in6_addr ip6{};
+      Read(ip6.s6_addr, 16);
+      uint16_t raw_port{};
+      Read(&raw_port, 1);
+      auto port = ntohs(raw_port);
+      return std::make_unique<InetAddressIPv6>(ip6, port);
+    }
+    ZNET_LOG_WARN("Invalid internet protocol version {}!", ver);
+    // unknown version
+    failed_to_read_ = true;
+    return nullptr;
+  }
+
+  template<size_t N>
+  std::bitset<N> ReadBitset() {
+    constexpr size_t BYTES = (N + 7) / 8;
+    uint8_t data[BYTES];
+    Read(data, BYTES);
+
+    std::bitset<N> bs;
+    for (size_t i = 0; i < N; ++i) {
+      bool bit = (data[i/8] >> (i % 8)) & 1;
+      bs.set(i, bit);
+    }
+    return bs;
+  }
+
+  PortNumber ReadPort() {
+    return ReadInt<PortNumber>();
+  }
+
   template<typename T, typename std::enable_if<std::is_arithmetic<T>::value && (sizeof(T) <= 8), int>::type = 0>
   T ReadVarInt() {
     uint8_t size = sizeof(T);
@@ -273,6 +317,40 @@ class Buffer {
     write_cursor_ += size;
   }
 
+  void WriteInetAddress(InetAddress& address) {
+    if (address.ipv() == InetProtocolVersion::IPv4) {
+      WriteInt<uint8_t>(4);
+      // raw IPv4 (network‐order) + port (network‐order)
+      auto* addr = reinterpret_cast<sockaddr_in*>(address.handle_ptr());
+      Write(reinterpret_cast<const uint32_t*>(&addr->sin_addr.s_addr), 1);
+      Write(reinterpret_cast<const uint16_t*>(&addr->sin_port), 1);
+    } else if (address.ipv() == InetProtocolVersion::IPv6) {
+      WriteInt<uint8_t>(6);
+      auto* addr = reinterpret_cast<sockaddr_in6*>(address.handle_ptr());
+      // raw IPv6 (16 bytes) + port
+      Write(addr->sin6_addr.s6_addr, 16);
+      Write(reinterpret_cast<const uint16_t*>(&addr->sin6_port), 1);
+    }
+  }
+
+  void WritePort(PortNumber port) {
+    // Pretty funny but this should be enough
+    WriteInt(port);
+  }
+
+  // write a std::bitset<N> (little‑endian bit order)
+  template<size_t N>
+  void WriteBitset(const std::bitset<N>& bs) {
+    constexpr size_t BYTES = (N + 7) / 8;
+    uint8_t data[BYTES] = {};
+    for (size_t i = 0; i < N; ++i) {
+      if (bs[i]) {
+        data[i/8] |= uint8_t(1u << (i % 8));
+      }
+    }
+    Write(data, BYTES);
+  }
+
   template<typename T, typename std::enable_if<std::is_arithmetic<T>::value && (sizeof(T) <= 8), int>::type = 0>
   void Write(T* arr, size_t size) {
     auto* pt = reinterpret_cast<const char*>(arr);
@@ -308,11 +386,10 @@ class Buffer {
 
   template <typename KeyFunc, typename ValueFunc, typename Map>
   void WriteMap(Map& map, KeyFunc key_func, ValueFunc value_func) {
-    size_t size = map.size();
-    WriteInt(size);
-    for (auto& [key, value] : map) {
-      (this->*key_func)(key);
-      (this->*value_func)(value);
+    WriteInt(map.size());
+    for (auto& kv : map) {
+      (this->*key_func)(kv.first);
+      (this->*value_func)(kv.second);
     }
   }
 
diff --git a/znet/include/znet/encryption.h b/znet/include/znet/encryption.h
index ece602e..663e22c 100644
--- a/znet/include/znet/encryption.h
+++ b/znet/include/znet/encryption.h
@@ -20,23 +20,27 @@
 
 namespace znet {
 
+struct PKeyDeleter {
+  void operator()(EVP_PKEY* p) const noexcept {
+    EVP_PKEY_free(p);
+  }
+};
+using UniquePKey = std::unique_ptr<EVP_PKEY, PKeyDeleter>;
+
 unsigned char* SerializePublicKey(EVP_PKEY* pkey, uint32_t* len);
 
-EVP_PKEY* DeserializePublicKey(const unsigned char* der, int len);
+UniquePKey DeserializePublicKey(const unsigned char* der, int len);
+
+UniquePKey CloneKey(const UniquePKey& k);
 
 class HandshakePacket : public Packet {
  public:
   HandshakePacket() : Packet(GetPacketId()) { }
-  ~HandshakePacket() {
-    if (owner_) {
-      EVP_PKEY_free(pub_key_);
-    }
-  }
+  ~HandshakePacket() { }
 
   static PacketId GetPacketId() { return -1; }
 
-  EVP_PKEY* pub_key_;
-  bool owner_; // means we have to deallocate the key
+  UniquePKey pub_key_ = nullptr;
 };
 
 class HandshakePacketSerializerV1 : public PacketSerializer<HandshakePacket> {
@@ -46,21 +50,26 @@ class HandshakePacketSerializerV1 : public PacketSerializer<HandshakePacket> {
 
   std::shared_ptr<Buffer> SerializeTyped(std::shared_ptr<HandshakePacket> packet, std::shared_ptr<Buffer> buffer) override {
     uint32_t len;
-    auto* data = SerializePublicKey(packet->pub_key_, &len);
-    buffer->WriteInt(len);
-    buffer->Write(data, len);
-    OPENSSL_free(data);
+    auto* data = SerializePublicKey(packet->pub_key_.get(), &len);
+
+    buffer->WriteInt<uint32_t>(len);
+    if (len > 0) {
+      buffer->Write(data, len);
+      OPENSSL_free(data);
+    }
     return buffer;
   }
 
   std::shared_ptr<HandshakePacket> DeserializeTyped(std::shared_ptr<Buffer> buffer) override {
     auto packet = std::make_shared<HandshakePacket>();
-    auto len = buffer->ReadInt<uint32_t>();
-    auto* data = new unsigned char[len];
-    buffer->Read(data, len);
-    packet->pub_key_ = DeserializePublicKey(data, len);
-    packet->owner_ = true;
-    delete[] data;
+    uint32_t len = buffer->ReadInt<uint32_t>();
+    if (len) {
+      // stack‑allocate a temp vector, read into it
+      std::vector<unsigned char> tmp(len);
+      buffer->Read(tmp.data(), len);
+      // hand off to your unique_ptr factory
+      packet->pub_key_ = DeserializePublicKey(tmp.data(), len);
+    }
     return packet;
   }
 };
@@ -112,8 +121,8 @@ class EncryptionLayer {
  private:
   PeerSession& session_;
 
-  EVP_PKEY* pub_key_ = nullptr;
-  EVP_PKEY* peer_pkey_ = nullptr;
+  UniquePKey pub_key_ = nullptr;
+  UniquePKey peer_pkey_ = nullptr;
   bool sent_handshake_ = false;
   bool sent_ready_ = false;
   bool enable_encryption_ = false;
diff --git a/znet/include/znet/interface.h b/znet/include/znet/interface.h
index 36872d0..d39c24e 100644
--- a/znet/include/znet/interface.h
+++ b/znet/include/znet/interface.h
@@ -28,13 +28,13 @@ class Interface {
 
   virtual void Wait() = 0;
 
-  void SetEventCallback(EventCallbackFn fn) { event_callback_ = std::move(fn); }
+  virtual void SetEventCallback(EventCallbackFn fn) { event_callback_ = std::move(fn); }
 
   ZNET_NODISCARD EventCallbackFn event_callback() const {
     return event_callback_;
   }
 
- private:
+ protected:
   EventCallbackFn event_callback_;
 };
 
diff --git a/znet/include/znet/p2p/dialer.h b/znet/include/znet/p2p/dialer.h
new file mode 100644
index 0000000..efb3e3e
--- /dev/null
+++ b/znet/include/znet/p2p/dialer.h
@@ -0,0 +1,58 @@
+//
+//    Copyright 2025 Metehan Gezer
+//
+//    Licensed under the Apache License, Version 2.0 (the "License");
+//    you may not use this file except in compliance with the License.
+//    You may obtain a copy of the License at
+//
+//        http://www.apache.org/licenses/LICENSE-2.0
+//
+
+#ifndef ZNET_PARENT_DIALER_H
+#define ZNET_PARENT_DIALER_H
+
+#include "znet/interface.h"
+#include "znet/client.h"
+#include "znet/server.h"
+
+namespace znet {
+namespace holepunch {
+
+enum class DialResult {
+  SuccessHost,
+  SuccessClient,
+  FailureTimeout
+};
+
+struct DialerConfig {
+  std::string local_ip;
+  int local_port;
+  std::string peer_ext_ip;
+  ConnectionType connection_type;
+};
+
+class Dialer : public Interface {
+ public:
+  Dialer(const DialerConfig&);
+  ~Dialer();
+
+  Result Bind() override;
+
+  void Wait() override;
+
+  Result Dial();
+
+  void SetEventCallback(EventCallbackFn fn) override {
+    event_callback_ = std::move(fn);
+    client_->SetEventCallback(event_callback_);
+    server_->SetEventCallback(event_callback_);
+  }
+
+ private:
+  std::unique_ptr<Client> client_;
+  std::unique_ptr<Server> server_;
+};
+
+}
+}
+#endif  //ZNET_PARENT_DIALER_H
diff --git a/znet/include/znet/p2p/relay.h b/znet/include/znet/p2p/relay.h
new file mode 100644
index 0000000..7b925f8
--- /dev/null
+++ b/znet/include/znet/p2p/relay.h
@@ -0,0 +1,154 @@
+//
+//    Copyright 2025 Metehan Gezer
+//
+//    Licensed under the Apache License, Version 2.0 (the "License");
+//    you may not use this file except in compliance with the License.
+//    You may obtain a copy of the License at
+//
+//        http://www.apache.org/licenses/LICENSE-2.0
+//
+
+#ifndef RELAY_SERVER_H
+#define RELAY_SERVER_H
+
+#include "znet/server.h"
+
+namespace znet {
+namespace holepunch {
+
+enum PacketType {
+  // A peer requests to register themselves
+  PACKET_REGISTER_PEER,
+  // Response to PACKET_REGISTER_PEER
+  PACKET_REGISTER_PEER_RESPONSE,
+  // A peer requests to connect to another peer
+  PACKET_CONNECT_PEER,
+  // Response to PACKET_CONNECT_PEER
+  PACKET_CONNECT_PEER_RESPONSE,
+};
+
+class RegisterPeerPacket : public Packet {
+ public:
+  RegisterPeerPacket() : Packet(PACKET_REGISTER_PEER) {}
+
+  std::string peer_name_;
+  PortNumber port_;
+};
+
+enum RegisterPeerStatus {
+  Success,
+  AlreadyRegistered,
+};
+
+class RegisterPeerResponsePacket : public Packet {
+ public:
+  RegisterPeerResponsePacket() : Packet(PACKET_REGISTER_PEER_RESPONSE) {}
+
+  std::string peer_name_;
+  std::shared_ptr<InetAddress> endpoint_; // self endpoint
+  bool ok_ = false;
+};
+
+class ConnectPeerPacket : public Packet {
+ public:
+  ConnectPeerPacket() : Packet(PACKET_CONNECT_PEER) {}
+
+  std::string target_;
+};
+
+class ConnectPeerResponsePacket : public Packet {
+ public:
+  ConnectPeerResponsePacket() : Packet(PACKET_CONNECT_PEER_RESPONSE) {}
+
+  std::string target_;
+  std::shared_ptr<InetAddress> endpoint_;
+};
+
+class RegisterPeerSerializer : public PacketSerializer<RegisterPeerPacket> {
+ public:
+  RegisterPeerSerializer() : PacketSerializer<RegisterPeerPacket>() {}
+  ~RegisterPeerSerializer() override = default;
+
+  std::shared_ptr<Buffer> SerializeTyped(std::shared_ptr<RegisterPeerPacket> packet, std::shared_ptr<Buffer> buffer) override {
+    buffer->WriteString(packet->peer_name_);
+    buffer->WritePort(packet->port_);
+    return buffer;
+  }
+
+  std::shared_ptr<RegisterPeerPacket> DeserializeTyped(std::shared_ptr<Buffer> buffer) override {
+    auto packet = std::make_shared<RegisterPeerPacket>();
+    packet->peer_name_ = buffer->ReadString();
+    packet->port_ = buffer->ReadPort();
+    return packet;
+  }
+};
+
+class RegisterPeerResponseSerializer : public PacketSerializer<RegisterPeerResponsePacket> {
+ public:
+  RegisterPeerResponseSerializer() : PacketSerializer<RegisterPeerResponsePacket>() {}
+  ~RegisterPeerResponseSerializer() override = default;
+
+  std::shared_ptr<Buffer> SerializeTyped(std::shared_ptr<RegisterPeerResponsePacket> packet, std::shared_ptr<Buffer> buffer) override {
+    buffer->WriteString(packet->peer_name_);
+    buffer->WriteBool(packet->ok_);
+    return buffer;
+  }
+
+  std::shared_ptr<RegisterPeerResponsePacket> DeserializeTyped(std::shared_ptr<Buffer> buffer) override {
+    auto packet = std::make_shared<RegisterPeerResponsePacket>();
+    packet->peer_name_ = buffer->ReadString();
+    packet->ok_ = buffer->ReadBool();
+    return packet;
+  }
+};
+
+class ConnectPeerSerializer : public PacketSerializer<ConnectPeerPacket> {
+ public:
+  ConnectPeerSerializer() : PacketSerializer<ConnectPeerPacket>() {}
+  ~ConnectPeerSerializer() override = default;
+
+  std::shared_ptr<Buffer> SerializeTyped(std::shared_ptr<ConnectPeerPacket> packet, std::shared_ptr<Buffer> buffer) override {
+    buffer->WriteString(packet->target_);
+    return buffer;
+  }
+
+  std::shared_ptr<ConnectPeerPacket> DeserializeTyped(std::shared_ptr<Buffer> buffer) override {
+    auto packet = std::make_shared<ConnectPeerPacket>();
+    packet->target_ = buffer->ReadString();
+    return packet;
+  }
+};
+
+class ConnectPeerResponseSerializer : public PacketSerializer<ConnectPeerResponsePacket> {
+ public:
+  ConnectPeerResponseSerializer() : PacketSerializer<ConnectPeerResponsePacket>() {}
+  ~ConnectPeerResponseSerializer() override = default;
+
+  std::shared_ptr<Buffer> SerializeTyped(std::shared_ptr<ConnectPeerResponsePacket> packet, std::shared_ptr<Buffer> buffer) override {
+    buffer->WriteString(packet->target_);
+    buffer->WriteInetAddress(*packet->endpoint_);
+    return buffer;
+  }
+
+  std::shared_ptr<ConnectPeerResponsePacket> DeserializeTyped(std::shared_ptr<Buffer> buffer) override {
+    auto packet = std::make_shared<ConnectPeerResponsePacket>();
+    packet->target_ = buffer->ReadString();
+    packet->endpoint_ = buffer->ReadInetAddress();
+    return packet;
+  }
+};
+
+std::shared_ptr<Codec> BuildCodec() {
+  std::shared_ptr<znet::Codec> codec = std::make_shared<znet::Codec>();
+  codec->Add(znet::holepunch::PACKET_REGISTER_PEER, std::make_unique<znet::holepunch::RegisterPeerSerializer>());
+  codec->Add(znet::holepunch::PACKET_REGISTER_PEER_RESPONSE, std::make_unique<znet::holepunch::RegisterPeerResponseSerializer>());
+  codec->Add(znet::holepunch::PACKET_CONNECT_PEER, std::make_unique<znet::holepunch::ConnectPeerSerializer>());
+  codec->Add(znet::holepunch::PACKET_CONNECT_PEER_RESPONSE, std::make_unique<znet::holepunch::ConnectPeerResponseSerializer>());
+  return std::move(codec);
+}
+
+}
+}
+
+
+#endif //RELAY_SERVER_H
diff --git a/znet/include/znet/peer_session.h b/znet/include/znet/peer_session.h
index 9bcd49c..bb3f77c 100644
--- a/znet/include/znet/peer_session.h
+++ b/znet/include/znet/peer_session.h
@@ -20,9 +20,9 @@ namespace znet {
 
 class PeerSession {
  public:
-  PeerSession(std::shared_ptr<InetAddress> local_address, std::shared_ptr<InetAddress> remote_address,
-                    SocketHandle socket,
-                     bool is_initiator = false);
+  PeerSession(std::shared_ptr<InetAddress> local_address,
+              std::shared_ptr<InetAddress> remote_address,
+              SocketHandle socket, bool is_initiator = false);
   PeerSession(const PeerSession&) = delete;
   PeerSession(PeerSession&&) = delete;
 
@@ -50,10 +50,6 @@ class PeerSession {
 
   bool SendPacket(std::shared_ptr<Packet> packet);
 
-  void SetUserPointer(std::weak_ptr<void> ptr) {
-    user_ptr_ = ptr;
-  }
-
   void SetCodec(std::shared_ptr<Codec> codec) {
     codec_ = std::move(codec);
   }
@@ -64,25 +60,33 @@ class PeerSession {
 
   template<typename T>
   void SetUserPointer(std::shared_ptr<T> ptr) {
-    user_ptr_ = std::weak_ptr<void>(ptr);
-  }
-
-  ZNET_NODISCARD std::weak_ptr<void> user_ptr() const {
-    return user_ptr_;
+    user_ptr_ = std::move(ptr);
   }
 
   template<typename T>
   ZNET_NODISCARD std::shared_ptr<T> user_ptr_typed() const {
-    // Lock the weak_ptr<void> to get a shared_ptr<void>
-    std::shared_ptr<void> locked_ptr = user_ptr_.lock();
+    // Attempt to static_pointer_cast to the desired type T
+    // This assumes the user knows the correct type.
+    return std::static_pointer_cast<T>(user_ptr_);
+  }
 
-    if (locked_ptr) {
-      // Attempt to static_pointer_cast to the desired type T
-      // This assumes the user knows the correct type.
-      return std::static_pointer_cast<T>(locked_ptr);
-    }
-    // If the weak_ptr is expired, or no object was set, return nullptr
-    return nullptr;
+  template<typename Rep, typename Period>
+  void SetExpiry(std::chrono::duration<Rep,Period> ttl) {
+    expire_at_ = std::chrono::steady_clock::now() +
+                std::chrono::duration_cast<std::chrono::steady_clock::duration>(ttl);
+  }
+
+  ZNET_NODISCARD std::chrono::steady_clock::time_point connect_time() {
+    return connect_time_;
+  }
+
+  ZNET_NODISCARD std::chrono::steady_clock::duration time_since_connect() const noexcept {
+    return std::chrono::steady_clock::now() - connect_time_;
+  }
+
+  ZNET_NODISCARD long seconds_since_connect() const noexcept {
+    return std::chrono::duration_cast<std::chrono::seconds>(
+               time_since_connect()).count();
   }
 
  protected:
@@ -90,12 +94,22 @@ class PeerSession {
 
   virtual void Ready() {
     is_ready_ = true;
+    connect_time_ = std::chrono::steady_clock::now();
+  }
+
+  bool IsExpired() const {
+    if (!has_expiry_) {
+      return false;
+    }
+    return std::chrono::steady_clock::now() > expire_at_;
   }
 
   SessionId session_id_;
   SocketHandle socket_;
   std::shared_ptr<InetAddress> local_address_;
+  PortNumber local_port_;
   std::shared_ptr<InetAddress> remote_address_;
+  PortNumber remote_port_;
 
   std::shared_ptr<Codec> codec_;
   std::shared_ptr<PacketHandlerBase> handler_;
@@ -104,6 +118,9 @@ class PeerSession {
   bool is_initiator_;
   bool is_ready_ = false;
   bool is_alive_ = true;
-  std::weak_ptr<void> user_ptr_;
+  std::chrono::steady_clock::time_point connect_time_;
+  std::chrono::steady_clock::time_point expire_at_;
+  bool has_expiry_;
+  std::shared_ptr<void> user_ptr_;
 };
 }  // namespace znet
\ No newline at end of file
diff --git a/znet/include/znet/relay/relay_server.h b/znet/include/znet/relay/relay_server.h
deleted file mode 100644
index c68efaf..0000000
--- a/znet/include/znet/relay/relay_server.h
+++ /dev/null
@@ -1,21 +0,0 @@
-//
-//    Copyright 2025 Metehan Gezer
-//
-//    Licensed under the Apache License, Version 2.0 (the "License");
-//    you may not use this file except in compliance with the License.
-//    You may obtain a copy of the License at
-//
-//        http://www.apache.org/licenses/LICENSE-2.0
-//
-
-#ifndef RELAY_SERVER_H
-#define RELAY_SERVER_H
-
-class RelayServer {
-public:
-  RelayServer();
-  ~RelayServer();
-
-};
-
-#endif //RELAY_SERVER_H
diff --git a/znet/include/znet/server.h b/znet/include/znet/server.h
index 8b5ecae..0eee2ac 100644
--- a/znet/include/znet/server.h
+++ b/znet/include/znet/server.h
@@ -30,7 +30,7 @@ class Server : public Interface {
   using SessionMap = std::unordered_map<std::shared_ptr<InetAddress>, std::shared_ptr<PeerSession>>;
 
   Server();
-  Server(const ServerConfig& config);
+  explicit Server(const ServerConfig& config);
   Server(const Server&) = delete;
 
   ~Server() override;
diff --git a/znet/src/client.cc b/znet/src/client.cc
index 5016e7e..2a219db 100644
--- a/znet/src/client.cc
+++ b/znet/src/client.cc
@@ -67,9 +67,18 @@ Result Client::Connect() {
              SO_REUSEADDR | SO_REUSEPORT | SO_BROADCAST, &option,
              sizeof(option));
 #endif
-  // todo local address
+  std::shared_ptr<InetAddress> local_address;
+
+  sockaddr local_ss{};
+  socklen_t local_len = sizeof(local_ss);
+  if (getsockname(client_socket_, &local_ss, &local_len) == 0) {
+    local_address = InetAddress::from(&local_ss);
+  } else {
+    ZNET_LOG_ERROR("getsockname failed, local address will be nullptr: {}", GetLastErrorInfo());
+  }
+
   client_session_ =
-      std::make_shared<PeerSession>(nullptr, server_address_, client_socket_, true);
+      std::make_shared<PeerSession>(local_address, server_address_, client_socket_, true);
 
   // Connected to the server
   task_.Run([this]() {
diff --git a/znet/src/dialer.cc b/znet/src/dialer.cc
new file mode 100644
index 0000000..defe835
--- /dev/null
+++ b/znet/src/dialer.cc
@@ -0,0 +1,59 @@
+//
+//    Copyright 2025 Metehan Gezer
+//
+//    Licensed under the Apache License, Version 2.0 (the "License");
+//    you may not use this file except in compliance with the License.
+//    You may obtain a copy of the License at
+//
+//        http://www.apache.org/licenses/LICENSE-2.0
+//
+
+#include "znet/p2p/dialer.h"
+
+namespace znet {
+namespace holepunch {
+
+Dialer::Dialer(const DialerConfig& config) {
+  client_ = std::make_unique<Client>(ClientConfig{
+      .server_ip = config.peer_ext_ip,
+      .server_port = config.local_port
+  });
+  server_ = std::make_unique<Server>(ServerConfig{
+      .bind_ip = config.local_ip,
+      .bind_port = config.local_port
+  });
+}
+
+Dialer::~Dialer() {
+
+}
+
+Result Dialer::Bind() {
+  Result result;
+  if ((result = client_->Bind()) != Result::Success) {
+    return result;
+  }
+  if ((result = server_->Bind()) != Result::Success) {
+    return result;
+  }
+  return Result::Success;
+}
+
+Result Dialer::Dial() {
+  Result result;
+  if ((result = client_->Connect()) != Result::Success) {
+    return result;
+  }
+  if ((result = server_->Listen()) != Result::Success) {
+    return result;
+  }
+  return Result::Success;
+}
+
+void Dialer::Wait() {
+  client_->Wait();
+  server_->Wait();
+}
+
+}
+}
\ No newline at end of file
diff --git a/znet/src/encryption.cc b/znet/src/encryption.cc
index 3b49b59..e75017e 100644
--- a/znet/src/encryption.cc
+++ b/znet/src/encryption.cc
@@ -48,21 +48,34 @@ unsigned char* SerializePublicKey(EVP_PKEY* pkey, uint32_t* len) {
   return der;  // The caller must free this memory using OPENSSL_free
 }
 
-EVP_PKEY* DeserializePublicKey(const unsigned char* der, int len) {
+UniquePKey DeserializePublicKey(const unsigned char* der, int len) {
   if (!der || len <= 0) {
     return nullptr;
   }
+
   const unsigned char* p = der;
-  EVP_PKEY* pkey = d2i_PUBKEY(nullptr, &p, len);  // Deserialize the DER data
-  if (!pkey) {
+  EVP_PKEY* raw = d2i_PUBKEY(nullptr, &p, len);
+  if (!raw) {
     fprintf(stderr, "Failed to deserialize public key\n");
     return nullptr;
   }
 
-  return pkey;
+  return UniquePKey(raw);
+}
+
+UniquePKey CloneKey(const UniquePKey& k) {
+  if (!k) {
+    return {};
+  }
+  // up‐ref so packet owns its own reference
+  if (EVP_PKEY_up_ref(k.get()) <= 0) {
+    ZNET_LOG_ERROR("Failed to up_ref pub_key");
+    return {};
+  }
+  return UniquePKey(k.get());
 }
 
-EVP_PKEY* GenerateKey() {
+UniquePKey GenerateKey() {
   /* Create the context for generating the parameters */
   EVP_PKEY_CTX* pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_DH, nullptr);
   if (!pctx) {
@@ -119,7 +132,7 @@ EVP_PKEY* GenerateKey() {
   EVP_PKEY_free(params);
 
   //print_key(dhkey);
-  return dhkey;
+  return UniquePKey(dhkey);
 }
 
 bool GenerateIV(unsigned char* iv, int iv_length) {
@@ -322,14 +335,6 @@ void EncryptionLayer::Initialize(bool send) {
 }
 
 EncryptionLayer::~EncryptionLayer() {
-  if (peer_pkey_) {
-    EVP_PKEY_free(peer_pkey_);
-    peer_pkey_ = nullptr;
-  }
-  if (pub_key_) {
-    EVP_PKEY_free(pub_key_);
-    pub_key_ = nullptr;
-  }
 }
 
 std::shared_ptr<Buffer> EncryptionLayer::HandleDecrypt(std::shared_ptr<Buffer> buffer) {
@@ -401,10 +406,9 @@ void EncryptionLayer::OnHandshakePacket(std::shared_ptr<HandshakePacket> packet)
     session_.Close();
     return;
   }
-  peer_pkey_ = packet->pub_key_;
-  packet->owner_ = false;  // we own the key now
+  peer_pkey_ = std::move(packet->pub_key_);
   shared_secret_ =
-      ComputeSharedSecret(pub_key_, peer_pkey_, &shared_secret_len_);
+      ComputeSharedSecret(pub_key_.get(), peer_pkey_.get(), &shared_secret_len_);
   if (!DeriveKeyFromSharedSecret(shared_secret_, shared_secret_len_, key_,
                                  key_len_)) {
     ZNET_LOG_ERROR(
@@ -446,8 +450,9 @@ void EncryptionLayer::OnAcknowledgePacket(std::shared_ptr<ConnectionReadyPacket>
 
 void EncryptionLayer::SendHandshake() {
   auto packet = std::make_shared<HandshakePacket>();
-  packet->pub_key_ = pub_key_;
-  packet->owner_ = false;
+  if (pub_key_) {
+    packet->pub_key_ = CloneKey(pub_key_);
+  }
   session_.SendPacket(packet);
   sent_handshake_ = true;
 }
diff --git a/znet/src/peer_session.cc b/znet/src/peer_session.cc
index 337b756..a99f909 100644
--- a/znet/src/peer_session.cc
+++ b/znet/src/peer_session.cc
@@ -8,6 +8,8 @@
 //        http://www.apache.org/licenses/LICENSE-2.0
 //
 
+#include <utility>
+
 #include "znet/peer_session.h"
 #include "znet/server_events.h"
 #include "znet/error.h"
@@ -17,10 +19,12 @@ namespace znet {
 PeerSession::PeerSession(std::shared_ptr<InetAddress> local_address,
                          std::shared_ptr<InetAddress> remote_address,
                          SocketHandle socket, bool is_initiator)
-    : local_address_(local_address), remote_address_(remote_address),
+    : local_address_(std::move(local_address)),
+      remote_address_(std::move(remote_address)),
       socket_(socket), is_initiator_(is_initiator),
       transport_layer_(*this, socket),
-      encryption_layer_(*this) {
+      encryption_layer_(*this),
+      connect_time_(std::chrono::steady_clock::now()) {
   static SessionId sIdCount = 0;
   session_id_ = sIdCount++;
   encryption_layer_.Initialize(is_initiator);
@@ -30,10 +34,15 @@ void PeerSession::Process() {
   if (!is_alive_) {
     return;
   }
+  if (IsExpired()) {
+    ZNET_LOG_INFO("Session {} was expired!", session_id_);
+    Close();
+    return;
+  }
   std::shared_ptr<Buffer> buffer;
   if ((buffer = transport_layer_.Receive())) {
     buffer = encryption_layer_.HandleIn(buffer);
-    if (buffer && handler_) {
+    if (buffer && handler_ && codec_) {
       codec_->Deserialize(buffer, *handler_);
     }
   }
diff --git a/znet/src/util.cc b/znet/src/util.cc
new file mode 100644
index 0000000..003fb1c
--- /dev/null
+++ b/znet/src/util.cc
@@ -0,0 +1,42 @@
+//
+//    Copyright 2025 Metehan Gezer
+//
+//    Licensed under the Apache License, Version 2.0 (the "License");
+//    you may not use this file except in compliance with the License.
+//    You may obtain a copy of the License at
+//
+//        http://www.apache.org/licenses/LICENSE-2.0
+//
+
+#include "znet/base/util.h"
+
+#include <string>
+#include <vector>
+#include <random>
+
+std::string GeneratePeerName() {
+  static const std::vector<std::string> firstParts = {
+      "Skippy","Crimson","Neon","Rusty","Silent",
+      "Quantum","Velvet","Blaze","Echo","Frost",
+      "Solar","Pixel","Iron","Azure","Misty",
+      "Copper","Shadow","Polar","Turbo","Glitch",
+      "Apex","Boulder","Cascade","Drift","Ember",
+      "Gale","Halo","Jolt","Kinetic","Lunar",
+      "Monarch","Nimbus","Obsidian","Phoenix","Quasar"
+  };
+  static const std::vector<std::string> secondParts = {
+      "Toe","Fox","Bolt","Wing","Shade",
+      "Pulse","Drift","Knight","Flare","Shard",
+      "Vector","Chaser","Spark","Raven","Quill",
+      "Stream","Bluff","Cipher","Warden","Orbit",
+      "Arc","Bramble","Crest","Dusk","Edge",
+      "Flicker","Harbor","Icicle","Jester","Kite",
+      "Ledger","Nexus","Omen","Rune","Spire"
+  };
+
+  static thread_local std::mt19937_64 gen{std::random_device{}()};
+  std::uniform_int_distribution<size_t> d1(0, firstParts.size()-1);
+  std::uniform_int_distribution<size_t> d2(0, secondParts.size()-1);
+
+  return firstParts[d1(gen)] + secondParts[d2(gen)];
+}
\ No newline at end of file

From fa04a472403699a8450756ea918131a87e226e41 Mon Sep 17 00:00:00 2001
From: Metehan Gezer <irrelevantdev@outlook.com>
Date: Thu, 31 Jul 2025 01:25:05 +0300
Subject: [PATCH 02/12] added bitset include

---
 znet/include/znet/buffer.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/znet/include/znet/buffer.h b/znet/include/znet/buffer.h
index 2806b5a..8ad4301 100644
--- a/znet/include/znet/buffer.h
+++ b/znet/include/znet/buffer.h
@@ -14,6 +14,7 @@
 #include "znet/base/types.h"
 #include "znet/logger.h"
 #include "znet/base/util.h"
+#include <bitset>
 
 namespace znet {
 

From 3e475694eb9aa16bcd3512af53a4927b4504d636 Mon Sep 17 00:00:00 2001
From: Metehan Gezer <irrelevantdev@outlook.com>
Date: Thu, 31 Jul 2025 01:30:01 +0300
Subject: [PATCH 03/12] fix includes

---
 examples/relay_client/main.cc | 2 +-
 znet/src/relay.cc             | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/relay_client/main.cc b/examples/relay_client/main.cc
index 31dd798..ac0b910 100644
--- a/examples/relay_client/main.cc
+++ b/examples/relay_client/main.cc
@@ -11,7 +11,7 @@
 #include <utility>
 
 #include "znet/znet.h"
-#include "znet/relay/relay.h"
+#include "znet/p2p/relay.h"
 #include "cxxopts.h"
 
 const std::string kPeerName = GeneratePeerName();
diff --git a/znet/src/relay.cc b/znet/src/relay.cc
index 9a8329c..f312cdf 100644
--- a/znet/src/relay.cc
+++ b/znet/src/relay.cc
@@ -8,5 +8,5 @@
 //        http://www.apache.org/licenses/LICENSE-2.0
 //
 
-#include "znet/relay/relay_server.h"
+#include "znet/p2p/relay_server.h"
 

From bbe80fa5aaa0d124d148f49b7881a61047871561 Mon Sep 17 00:00:00 2001
From: Metehan Gezer <irrelevantdev@outlook.com>
Date: Thu, 31 Jul 2025 01:30:38 +0300
Subject: [PATCH 04/12] remove TimePoint

---
 znet/include/znet/base/types.h | 1 -
 1 file changed, 1 deletion(-)

diff --git a/znet/include/znet/base/types.h b/znet/include/znet/base/types.h
index eeb1af0..ef1f1c5 100644
--- a/znet/include/znet/base/types.h
+++ b/znet/include/znet/base/types.h
@@ -21,7 +21,6 @@ namespace znet {
 
 using PacketId = uint64_t;
 using SessionId = uint64_t;
-using TimePoint = std::chrono::time_point<std::chrono::system_clock>;
 
 enum class Endianness { LittleEndian, BigEndian };
 

From 8d65d8b9e74907a48053143bc5055593b1bcd5d5 Mon Sep 17 00:00:00 2001
From: Metehan Gezer <irrelevantdev@outlook.com>
Date: Thu, 31 Jul 2025 01:32:41 +0300
Subject: [PATCH 05/12] fix c++14 compatability

---
 znet/src/dialer.cc | 10 ++--------
 1 file changed, 2 insertions(+), 8 deletions(-)

diff --git a/znet/src/dialer.cc b/znet/src/dialer.cc
index defe835..c755521 100644
--- a/znet/src/dialer.cc
+++ b/znet/src/dialer.cc
@@ -14,14 +14,8 @@ namespace znet {
 namespace holepunch {
 
 Dialer::Dialer(const DialerConfig& config) {
-  client_ = std::make_unique<Client>(ClientConfig{
-      .server_ip = config.peer_ext_ip,
-      .server_port = config.local_port
-  });
-  server_ = std::make_unique<Server>(ServerConfig{
-      .bind_ip = config.local_ip,
-      .bind_port = config.local_port
-  });
+  client_ = std::make_unique<Client>(ClientConfig{config.peer_ext_ip, config.local_port});
+  server_ = std::make_unique<Server>(ServerConfig{config.local_ip, config.local_port});
 }
 
 Dialer::~Dialer() {

From 76ba891e54a20957c3eef3cd2c9483d3166c2e0b Mon Sep 17 00:00:00 2001
From: Metehan Gezer <irrelevantdev@outlook.com>
Date: Thu, 31 Jul 2025 12:12:34 +0300
Subject: [PATCH 06/12] added more tests

---
 tests/buffer.cc | 79 ++++++++++++++++++++++++++++++++-----------------
 1 file changed, 52 insertions(+), 27 deletions(-)

diff --git a/tests/buffer.cc b/tests/buffer.cc
index b26f3a1..dbc8af9 100644
--- a/tests/buffer.cc
+++ b/tests/buffer.cc
@@ -39,36 +39,40 @@ class BufferTest : public ::testing::Test {
 
 // todo split these to individual tests
 void TestBuffer(std::shared_ptr<Buffer> buffer) {
-    int64_t asd = INT64_MAX;
-    float f = 0.9245f;
-    double d = 0.224529726;
-    buffer->ReserveExact(80);
-    buffer->WriteString("Hello World!");
-    buffer->WriteInt(asd);
-    buffer->WriteInt(f);
-    buffer->WriteInt(d);
-    buffer->WriteInt(d);
-
-    std::cout << buffer->Dump() << std::endl;
-    EXPECT_EQ(buffer->ReadString(), "Hello World!");
-    EXPECT_EQ(buffer->ReadInt<int64_t>(), asd);
-    EXPECT_EQ(buffer->ReadInt<float>(), f);
-    EXPECT_EQ(buffer->ReadInt<double>(), d);
-    EXPECT_EQ(buffer->ReadInt<double>(), d);
-    EXPECT_EQ(buffer->mem_allocations(), 1);
-    EXPECT_EQ(buffer->size(), 42);
-
-    EXPECT_EQ(buffer->capacity(), 80);
-    buffer->Trim();
-    EXPECT_EQ(buffer->capacity(), 42);
-
-    EXPECT_EQ(buffer->size(), 42);
-    EXPECT_EQ(buffer->capacity(), 42);
-    EXPECT_EQ(buffer->mem_allocations(), 1);
-  }
+  EXPECT_EQ(buffer->size(), 0);
+
+  int64_t asd = INT64_MAX;
+  float f = 0.9245f;
+  double d = 0.224529726;
+  buffer->ReserveExact(80);
+  buffer->WriteString("Hello World!");
+  buffer->WriteInt(asd);
+  buffer->WriteInt(f);
+  buffer->WriteInt(d);
+  buffer->WriteInt(d);
+
+  std::cout << buffer->Dump() << std::endl;
+  EXPECT_EQ(buffer->ReadString(), "Hello World!");
+  EXPECT_EQ(buffer->ReadInt<int64_t>(), asd);
+  EXPECT_EQ(buffer->ReadInt<float>(), f);
+  EXPECT_EQ(buffer->ReadInt<double>(), d);
+  EXPECT_EQ(buffer->ReadInt<double>(), d);
+  EXPECT_EQ(buffer->mem_allocations(), 1);
+  EXPECT_EQ(buffer->size(), 42);
+
+  EXPECT_EQ(buffer->capacity(), 80);
+  buffer->Trim();
+  EXPECT_EQ(buffer->capacity(), 42);
+
+  EXPECT_EQ(buffer->size(), 42);
+  EXPECT_EQ(buffer->capacity(), 42);
+  EXPECT_EQ(buffer->mem_allocations(), 1);
+}
 
 
 void TestVarInt(std::shared_ptr<Buffer> buffer) {
+  EXPECT_EQ(buffer->size(), 0);
+
   int64_t n1 = INT64_MAX;
   int64_t n2 = 124;
   int64_t n3 = 258;
@@ -84,6 +88,22 @@ void TestVarInt(std::shared_ptr<Buffer> buffer) {
   EXPECT_EQ(buffer->size(), 14);
 }
 
+void TestInetAddress(std::shared_ptr<Buffer> buffer) {
+  EXPECT_EQ(buffer->size(), 0);
+
+  auto addr1 = InetAddress::from("localhost", 2001);
+  buffer->WriteInetAddress(*addr1);
+
+  auto addr2 = InetAddress::from("2001:db8:3333:4444:5555:6666:7777:8888", 2001);
+  buffer->WriteInetAddress(*addr2);
+
+  std::cout << buffer->Dump() << std::endl;
+  EXPECT_EQ(*buffer->ReadInetAddress(), *addr1);
+  EXPECT_EQ(*buffer->ReadInetAddress(), *addr2);
+
+  EXPECT_EQ(buffer->size(), 26);
+}
+
 TEST_F(BufferTest, TestBuffers) {
   TestBuffer(buffer_le_);
   TestBuffer(buffer_be_);
@@ -92,4 +112,9 @@ TEST_F(BufferTest, TestBuffers) {
 TEST_F(BufferTest, TestVarInts) {
   TestVarInt(buffer_le_);
   TestVarInt(buffer_be_);
+}
+
+TEST_F(BufferTest, TestInetAddress) {
+  TestInetAddress(buffer_le_);
+  TestInetAddress(buffer_be_);
 }
\ No newline at end of file

From a00d3359e82fb6fb601b6ea9befd5746d7a3d6e5 Mon Sep 17 00:00:00 2001
From: Metehan Gezer <irrelevantdev@outlook.com>
Date: Thu, 31 Jul 2025 12:22:19 +0300
Subject: [PATCH 07/12] has_expiry should be false by default

---
 znet/include/znet/peer_session.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/znet/include/znet/peer_session.h b/znet/include/znet/peer_session.h
index bb3f77c..d0fcd91 100644
--- a/znet/include/znet/peer_session.h
+++ b/znet/include/znet/peer_session.h
@@ -120,7 +120,7 @@ class PeerSession {
   bool is_alive_ = true;
   std::chrono::steady_clock::time_point connect_time_;
   std::chrono::steady_clock::time_point expire_at_;
-  bool has_expiry_;
+  bool has_expiry_ = false;
   std::shared_ptr<void> user_ptr_;
 };
 }  // namespace znet
\ No newline at end of file

From 163ed5cca03ec237aad35e0971cdd723f0034a57 Mon Sep 17 00:00:00 2001
From: Metehan Gezer <irrelevantdev@outlook.com>
Date: Fri, 1 Aug 2025 04:14:36 +0300
Subject: [PATCH 08/12] documentation and tidy

---
 examples/basic/client/main.cc           |  56 +++++++++----
 examples/basic/server/main.cc           |  69 +++++++++++-----
 relay_server/main.cc                    |   4 +-
 znet/CMakeLists.txt                     |   8 +-
 znet/include/znet/base/inet_addr.h      |  98 ++---------------------
 znet/include/znet/base/scheduler.h      |   4 +-
 znet/include/znet/base/signal_handler.h |   8 ++
 znet/include/znet/buffer.h              |  15 +++-
 znet/include/znet/client.h              |  43 +++++++++-
 znet/include/znet/client_events.h       |  15 ++++
 znet/include/znet/codec.h               |  98 +++++++++--------------
 znet/include/znet/peer_session.h        |  11 +++
 znet/include/znet/precompiled.h         |   6 ++
 znet/include/znet/server.h              |  69 ++++++++++++++--
 znet/include/znet/server_events.h       |  24 +++++-
 znet/src/client.cc                      |   2 +
 znet/src/codec.cc                       | 102 ++++++++++++++++++++++++
 znet/src/inet_addr.cc                   |  96 ++++++++++++++++++++++
 znet/src/packet_handler.cc              |  17 ----
 znet/src/server.cc                      |   4 +-
 20 files changed, 524 insertions(+), 225 deletions(-)
 create mode 100644 znet/src/codec.cc
 delete mode 100644 znet/src/packet_handler.cc

diff --git a/examples/basic/client/main.cc b/examples/basic/client/main.cc
index 6848ea4..374bf10 100644
--- a/examples/basic/client/main.cc
+++ b/examples/basic/client/main.cc
@@ -14,10 +14,15 @@
 
 using namespace znet;
 
+// MyPacketHandler manages network communication with a simple request-response pattern.
+// It inherits from PacketHandler and specifically handles DemoPacket type messages.
 class MyPacketHandler : public PacketHandler<MyPacketHandler, DemoPacket> {
  public:
+  // Creates a new handler associated with the given peer session
   MyPacketHandler(std::shared_ptr<PeerSession> session) : session_(session) { }
 
+  // Called when a demo packet is received. Logs the event and sends back
+  // a response with a greeting message.
   void OnPacket(std::shared_ptr<DemoPacket> p) {
     ZNET_LOG_INFO("Received demo_packet.");
     std::shared_ptr<DemoPacket> pk = std::make_shared<DemoPacket>();
@@ -25,65 +30,84 @@ class MyPacketHandler : public PacketHandler<MyPacketHandler, DemoPacket> {
     session_->SendPacket(pk);
   }
 
+  // Handles any unknown packet types that might be received.
+  // Currently just ignores them as a fallback mechanism.
   void OnUnknown(std::shared_ptr<Packet> p) {
     // fallback for unknown types
   }
 
  private:
+  // Stores the session we use to send responses back to the client
   std::shared_ptr<PeerSession> session_;
 };
 
+// Sets up a new client connection with appropriate packet handling and encoding.
+// Returns false to allow other handlers to process the event if needed.
 bool OnConnectEvent(ClientConnectedToServerEvent& event) {
   PeerSession& session = *event.session();
 
-  // Codecs are what serializes and deserializes the packets,
-  // You can set an initial codec, then get the protocol version from the client
-  // then set a different codec for different versions. This provides much more flexibility
-  // Codecs can be swapped mid-session
+  // Set up how packets will be encoded/decoded
+  // Note: It's more efficient to create this codec once and share it
+  // between clients, but for this example we create it per-connection
 
-  // Additionally, it is wiser to have this created once and shared between clients
-  // For this example it is created on the spot like this
   std::shared_ptr<Codec> codec = std::make_shared<Codec>();
   codec->Add(PACKET_DEMO, std::make_unique<DemoSerializer>());
   session.SetCodec(codec);
 
-  // Handlers are what handles the packets, like codecs this can be swapped mid-session
-  // For example during the login phase, you can give a different handler to only
-  // handle those are sent during the login, then change the codec.
+  // Set up how packets will be processed
+  // The handler can be changed during the session - for example,
+  // you might use different handlers for login vs. game play
   session.SetHandler(std::make_shared<MyPacketHandler>(event.session()));
 
+  // Send an initial greeting to the other peer
   std::shared_ptr<DemoPacket> pk = std::make_shared<DemoPacket>();
   pk->text = "Hello from client!";
   event.session()->SendPacket(pk);
   return false;
 }
 
+// Main event dispatcher - routes different types of events
+// to their appropriate handlers
 void OnEvent(Event& event) {
   EventDispatcher dispatcher{event};
+  // Route for different types of events
   dispatcher.Dispatch<ClientConnectedToServerEvent>(
       ZNET_BIND_GLOBAL_FN(OnConnectEvent));
 }
 
 int main() {
-  // Create config
+  // Create a client configuration
+  // We're connecting to localhost (127.0.0.1) on port 25000
+  // In a real application, you'd typically get these values from
+  // command line arguments or a config file or from ui
   ClientConfig config{"127.0.0.1", 25000};
 
-  // Create client with the config
+  // Initialize the network client with our configuration
+  // This sets up the internal client state but doesn't connect yet
   Client client{config};
 
-  // Set event callback
+  // Register our event handler to process network events
+  // OnEvent will be called for events.
   client.SetEventCallback(ZNET_BIND_GLOBAL_FN(OnEvent));
 
-  // Bind and connect
+  // Try to bind the client to a local network interface
+  // This is required before we can connect to the server
   if (client.Bind() != Result::Success) {
-    return 1;
+    return 1; // Exit if binding fails (e.g., port already in use)
   }
 
+  // Attempt to establish a connection to the server
+  // This initiates the connection process but doesn't wait. (async)
+  // It runs on another thread
   if (client.Connect() != Result::Success) {
-    return 1;  // Failed to connect
+    return 1; // Exit if connection fails (e.g., server unreachable)
   }
+
+  // Wait for the connection to complete
+  // Note: In a real application, you typically wouldn't block here
+  // Instead, you'd continue your program and do other stuff
   client.Wait();
 
-  // Connection was successful and completed.
+  // Connection is finished (disconnected)
   return 0;
 }
diff --git a/examples/basic/server/main.cc b/examples/basic/server/main.cc
index 1c1b746..c2650a2 100644
--- a/examples/basic/server/main.cc
+++ b/examples/basic/server/main.cc
@@ -13,10 +13,15 @@
 
 using namespace znet;
 
+// MyPacketHandler manages network communication, handling incoming messages
+// from connected clients and sending appropriate responses
 class MyPacketHandler : public PacketHandler<MyPacketHandler, DemoPacket> {
  public:
+  // Creates a new handler for a specific client session
   MyPacketHandler(std::shared_ptr<PeerSession> session) : session_(session) { }
 
+  // Processes incoming demo packets from clients
+  // Responds with a greeting message to demonstrate two-way communication
   void OnPacket(std::shared_ptr<DemoPacket> p) {
     ZNET_LOG_INFO("Received demo_packet.");
     std::shared_ptr<DemoPacket> pk = std::make_shared<DemoPacket>();
@@ -24,56 +29,67 @@ class MyPacketHandler : public PacketHandler<MyPacketHandler, DemoPacket> {
     session_->SendPacket(pk);
   }
 
+  // Fallback handler for any unrecognized packet types
+  // Currently ignores them, but you could add logging or error handling here
   void OnUnknown(std::shared_ptr<Packet> p) {
     // fallback for unknown types
   }
 
  private:
+  // The client session this handler is responsible for
   std::shared_ptr<PeerSession> session_;
 };
 
-bool OnNewSessionEvent(ServerClientConnectedEvent& event) {
+// Called whenever a new client connects to the server
+// Sets up the communication channel with proper encoding and handling
+bool OnNewSessionEvent(IncomingClientConnectedEvent& event) {
   PeerSession& session = *event.session();
 
-  // Codecs are what serializes and deserializes the packets,
-  // You can set an initial codec, then get the protocol version from the client
-  // then set a different codec for different versions. This provides much more flexibility
-  // Codecs can be swapped mid-session
-
-  // Additionally, it is wiser to have this created once and shared between clients
-  // For this example it is created on the spot like this
+  // Create and set up the packet codec (encoder/decoder)
+  // In production, you'd typically share one codec instance among all clients
+  // rather than creating a new one for each connection
   std::shared_ptr<Codec> codec = std::make_shared<Codec>();
   codec->Add(PACKET_DEMO, std::make_unique<DemoSerializer>());
   session.SetCodec(codec);
 
-  // Handlers are what handles the packets, like codecs this can be swapped mid-session
-  // For example during the login phase, you can give a different handler to only
-  // handle those are sent during the login, then change the codec.
+  // Set up the packet handler for this client
+  // Different handlers can be used for different connection states
+  // (e.g., one for login, another for gameplay)
   session.SetHandler(std::make_shared<MyPacketHandler>(event.session()));
   return false;
 }
 
+// Called when a client disconnects from the server
+// You can add cleanup code here if needed
 bool OnDisconnectSessionEvent(ServerClientDisconnectedEvent& event) {
   return false;
 }
 
+// Central event dispatcher that routes all server events
+// to their appropriate handler functions
 void OnEvent(Event& event) {
   EventDispatcher dispatcher{event};
-  // Bind desired events
-  dispatcher.Dispatch<ServerClientConnectedEvent>(
+  // Route for different types of events
+  dispatcher.Dispatch<IncomingClientConnectedEvent>(
       ZNET_BIND_GLOBAL_FN(OnNewSessionEvent));
   dispatcher.Dispatch<ServerClientDisconnectedEvent>(
       ZNET_BIND_GLOBAL_FN(OnDisconnectSessionEvent));
 }
 
 int main() {
-  // Create config
+  // Create the server configuration
+  // We're listening on localhost (127.0.0.1) port 25000
+  // In a real application, you'd typically get these values from
+  // command line arguments or a config file or from ui
   ServerConfig config{"127.0.0.1", 25000};
 
-  // Create server with the config
+  // Initialize the server with our configuration
+  // This sets up the internal server state but doesn't start listening yet
   Server server{config};
 
-  // Register signal handlers (optional)
+  // Set up signal handling for graceful shutdown
+  // This ensures the server closes cleanly when interrupted (Ctrl+C)
+  // This part is optional
   RegisterSignalHandler([&server](Signal sig) -> bool {
     if (sig == znet::kSignalInterrupt) {
       // stop the server when SIGINT is received
@@ -83,17 +99,28 @@ int main() {
     return false;
   });
 
-  // Set event callback
+  // Register our event handler to process server events
+  // OnEvent will be called for client connections, disconnections,
+  // and other server events
   server.SetEventCallback(ZNET_BIND_GLOBAL_FN(OnEvent));
 
-  // Bind and listen
+  // Try to bind the server to the configured network interface
+  // This reserves the port for our use
   if (server.Bind() != Result::Success) {
-    return 1;
+    return 1; // Exit if binding fails (e.g., port already in use)
   }
 
+  // Start listening for incoming client connections
+  // This begins accepting clients but doesn't block the main thread (async)
   if (server.Listen() != Result::Success) {
-    return 1; // failed to listen
+    return 1; // Exit if we can't start listening
   }
+
+  // Wait for the server to stop
+  // Note: In a real application, you typically wouldn't block here
+  // Instead, you'd continue your program and do other stuff
   server.Wait();
-  return 0; // successfully completed
+
+  // Server has shut down cleanly
+  return 0;
 }
\ No newline at end of file
diff --git a/relay_server/main.cc b/relay_server/main.cc
index f645468..0d731aa 100644
--- a/relay_server/main.cc
+++ b/relay_server/main.cc
@@ -68,7 +68,7 @@ class DefaultPacketHandler : public znet::PacketHandler<DefaultPacketHandler, zn
   std::shared_ptr<znet::PeerSession> session_;
 };
 
-bool OnConnectEvent(znet::ServerClientConnectedEvent& event) {
+bool OnConnectEvent(znet::IncomingClientConnectedEvent& event) {
   znet::PeerSession& session = *event.session();
   session.SetCodec(znet::holepunch::BuildCodec());
   session.SetHandler(std::make_shared<DefaultPacketHandler>(event.session()));
@@ -78,7 +78,7 @@ bool OnConnectEvent(znet::ServerClientConnectedEvent& event) {
 
 void OnEvent(znet::Event& event) {
   znet::EventDispatcher dispatcher{event};
-  dispatcher.Dispatch<znet::ServerClientConnectedEvent>(
+  dispatcher.Dispatch<znet::IncomingClientConnectedEvent>(
       ZNET_BIND_GLOBAL_FN(OnConnectEvent));
 }
 
diff --git a/znet/CMakeLists.txt b/znet/CMakeLists.txt
index 0f19c8b..11ace86 100644
--- a/znet/CMakeLists.txt
+++ b/znet/CMakeLists.txt
@@ -2,6 +2,7 @@ cmake_minimum_required(VERSION 3.16.3)
 project(znet)
 
 option(ZNET_USE_EXTERNAL_FMT "Looks for FMT via find_package" OFF)
+option(ZNET_PREFER_STD_SLEEP "Prefers thread sleep to wait between ticks, this results in less precision of the timings but reduces CPU usage." OFF)
 
 if(NOT MSVC)
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fpermissive -Werror=vla -Wno-deprecated")
@@ -18,11 +19,11 @@ set(ZNET_SOURCES
         src/client.cc
         src/error.cc
         src/logger.cc
-        src/packet_handler.cc
         src/encryption.cc
         src/transport.cc
         src/peer_session.cc
         src/dialer.cc
+        src/codec.cc
         src/util.cc
         src/pch.cc
 )
@@ -37,9 +38,12 @@ set_target_properties(znet PROPERTIES
 )
 target_precompile_headers(znet PRIVATE include/znet/precompiled.h)
 target_include_directories(znet PUBLIC include)
+## Defines
+if(ZNET_PREFER_STD_SLEEP)
+    target_compile_definitions(znet PUBLIC ZNET_PREFER_STD_SLEEP)
+endif()
 
 ## Dependencies
-
 if(WIN32)
     target_link_libraries(znet PUBLIC winmm ws2_32)
 endif()
diff --git a/znet/include/znet/base/inet_addr.h b/znet/include/znet/base/inet_addr.h
index 6653cf7..4b37d7d 100644
--- a/znet/include/znet/base/inet_addr.h
+++ b/znet/include/znet/base/inet_addr.h
@@ -72,54 +72,11 @@ class InetAddress {
 
 class InetAddressIPv4 : public InetAddress {
  public:
-  explicit InetAddressIPv4(PortNumber port)
-      : InetAddress(InetProtocolVersion::IPv4, "") {
-    addr.sin_family = AF_INET;
-    addr.sin_port = htons(port);
-#ifdef TARGET_APPLE
-    addr.sin_len = sizeof(sockaddr_in);
-#endif
-    char src[INET_ADDRSTRLEN];
-    inet_ntop(AF_INET, &addr.sin_addr, src, INET_ADDRSTRLEN);
-    readable_ = std::string(src) + ":" + std::to_string(ntohs(addr.sin_port));
-    is_valid_ = true;
-  }
+  explicit InetAddressIPv4(PortNumber port);
 
-  InetAddressIPv4(IPv4Address ip, PortNumber port)
-      : InetAddress(InetProtocolVersion::IPv4, "") {
-
-    addr.sin_family = AF_INET;
-    addr.sin_port = htons(port);
-    addr.sin_addr = ip;
-#ifdef TARGET_APPLE
-    addr.sin_len = sizeof(sockaddr_in);
-#endif
+  InetAddressIPv4(IPv4Address ip, PortNumber port);
 
-    char src[INET_ADDRSTRLEN];
-    inet_ntop(AF_INET, &addr.sin_addr, src, INET_ADDRSTRLEN);
-    readable_ = std::string(src) + ":" + std::to_string(ntohs(addr.sin_port));
-    is_valid_ = true;
-  }
-
-  InetAddressIPv4(const std::string& str, PortNumber port)
-      : InetAddress(InetProtocolVersion::IPv4, "") {
-    if (!IsValidIPv4(str)) {
-      is_valid_ = false;
-      readable_ = "Invalid Address";
-      return;
-    }
-
-    addr.sin_family = AF_INET;
-    addr.sin_port = htons(port);
-    addr.sin_addr = ParseIPv4(str);
-#ifdef TARGET_APPLE
-    addr.sin_len = sizeof(sockaddr_in);
-#endif
-    char src[INET_ADDRSTRLEN];
-    inet_ntop(AF_INET, &addr.sin_addr, src, INET_ADDRSTRLEN);
-    readable_ = std::string(src) + ":" + std::to_string(ntohs(addr.sin_port));
-    is_valid_ = true;
-  }
+  InetAddressIPv4(const std::string& str, PortNumber port);
 
   ZNET_NODISCARD bool is_valid() const override { return is_valid_; }
 
@@ -140,54 +97,11 @@ class InetAddressIPv4 : public InetAddress {
 
 class InetAddressIPv6 : public InetAddress {
  public:
-  explicit InetAddressIPv6(PortNumber port)
-      : InetAddress(InetProtocolVersion::IPv6, "") {
-    addr.sin6_family = AF_INET6;
-    addr.sin6_flowinfo = 0;
-    addr.sin6_port = htons(port);
-#if !defined(TARGET_WIN) && !defined(TARGET_WEB) && !defined(TARGET_LINUX)
-    addr.sin6_len = sizeof(sockaddr_in6);
-#endif
-    char src[INET6_ADDRSTRLEN];
-    inet_ntop(AF_INET6, &addr.sin6_addr, src, sizeof(src));
-    readable_ = std::string(src) + ":" + std::to_string(ntohs(addr.sin6_port));
-    is_valid_ = true;
-  }
+  explicit InetAddressIPv6(PortNumber port);
 
-  InetAddressIPv6(IPv6Address ip, PortNumber port)
-      : InetAddress(InetProtocolVersion::IPv6, "") {
-    addr.sin6_family = AF_INET6;
-    addr.sin6_flowinfo = 0;
-    addr.sin6_port = htons(port);
-    addr.sin6_addr = ip;
-#if !defined(TARGET_WIN) && !defined(TARGET_WEB) && !defined(TARGET_LINUX)
-    addr.sin6_len = sizeof(sockaddr_in6);
-#endif
-    char src[INET6_ADDRSTRLEN];
-    inet_ntop(AF_INET6, &addr.sin6_addr, src, sizeof(src));
-    readable_ = std::string(src) + ":" + std::to_string(ntohs(addr.sin6_port));
-    is_valid_ = true;
-  }
+  InetAddressIPv6(IPv6Address ip, PortNumber port);
 
-  InetAddressIPv6(const std::string& str, PortNumber port)
-      : InetAddress(InetProtocolVersion::IPv6, "") {
-    if (!IsValidIPv6(str)) {
-      is_valid_ = false;
-      readable_ = "Invalid Address";
-      return;
-    }
-#if !defined(TARGET_WIN) && !defined(TARGET_WEB) && !defined(TARGET_LINUX)
-    addr.sin6_len = sizeof(sockaddr_in6);
-#endif
-    addr.sin6_family = AF_INET6;
-    addr.sin6_flowinfo = 0;
-    addr.sin6_port = htons(port);
-    addr.sin6_addr = ParseIPv6(str);
-    char src[INET6_ADDRSTRLEN];
-    inet_ntop(AF_INET6, &addr.sin6_addr, src, sizeof(src));
-    readable_ = std::string(src) + ":" + std::to_string(ntohs(addr.sin6_port));
-    is_valid_ = true;
-  }
+  InetAddressIPv6(const std::string& str, PortNumber port);
 
   ZNET_NODISCARD bool is_valid() const override { return is_valid_; }
 
diff --git a/znet/include/znet/base/scheduler.h b/znet/include/znet/base/scheduler.h
index ea60949..ff840e2 100644
--- a/znet/include/znet/base/scheduler.h
+++ b/znet/include/znet/base/scheduler.h
@@ -16,8 +16,8 @@
 #include <thread>
 
 /*
- * By default, this class will use precise sleep, this could result in more
- * cpu usage but much more precise timing. To disable precise sleep, define
+ * By default, this class will use precise sleep; this could result in more
+ * CPU usage but much more precise timing. To disable precise sleep, enable
  * ZNET_PREFER_STD_SLEEP.
  */
 class Scheduler {
diff --git a/znet/include/znet/base/signal_handler.h b/znet/include/znet/base/signal_handler.h
index 7d88325..5c934ab 100644
--- a/znet/include/znet/base/signal_handler.h
+++ b/znet/include/znet/base/signal_handler.h
@@ -66,6 +66,14 @@ enum Signal {
 
 typedef std::function<bool(Signal)>(SignalHandlerFn);
 
+/**
+ * Registers a function to handle signals. The provided handler is invoked
+ * whenever the specified signal is caught by the program.
+ *
+ * @param fn A function of type SignalHandlerFn that takes a Signal and returns
+ *           a boolean. The function is executed when a signal is caught.
+ *           Returning true from the handler indicates the program should exit.
+ */
 void RegisterSignalHandler(SignalHandlerFn fn);
 
 }  // namespace znet
\ No newline at end of file
diff --git a/znet/include/znet/buffer.h b/znet/include/znet/buffer.h
index 8ad4301..f9a90ff 100644
--- a/znet/include/znet/buffer.h
+++ b/znet/include/znet/buffer.h
@@ -488,7 +488,7 @@ class Buffer {
   ZNET_NODISCARD size_t capacity() const { return allocated_size_; }
 
   ZNET_NODISCARD ssize_t readable_bytes() const {
-    return write_cursor_ - read_cursor_;
+    return std::min(write_cursor_, read_limit_) - read_cursor_;
   }
 
   ZNET_NODISCARD size_t writable_bytes() const {
@@ -501,6 +501,14 @@ class Buffer {
 
   void SkipRead(size_t size) { read_cursor_ += size; }
 
+  void SetReadLimit(size_t limit) {
+    if (limit == 0) {
+      read_limit_ = std::numeric_limits<size_t>::max();
+    } else {
+      read_limit_ = limit;
+    }
+  }
+
   void SkipWrite(size_t size) {
     ReserveIncremental(size);
     write_cursor_ += size;
@@ -570,15 +578,16 @@ class Buffer {
  private:
   ZNET_NODISCARD bool CheckReadableBytes(size_t required) const {
 #if defined(DEBUG) && !defined(DISABLE_ASSERT_READABLE_BYTES)
-    assert(write_cursor_ >= read_cursor_ + required);
+    assert(std::min(write_cursor_, read_limit_) >= read_cursor_ + required);
 #endif
-    return write_cursor_ >= read_cursor_ + required;
+    return std::min(write_cursor_, read_limit_) >= read_cursor_ + required;
   }
 
   Endianness endianness_;
   size_t allocated_size_;
   size_t write_cursor_;
   size_t read_cursor_;
+  size_t read_limit_ = std::numeric_limits<size_t>::max();
   char* data_;
   bool failed_to_read_;
   bool failed_to_alloc_;
diff --git a/znet/include/znet/client.h b/znet/include/znet/client.h
index d85f765..a05baf3 100644
--- a/znet/include/znet/client.h
+++ b/znet/include/znet/client.h
@@ -23,6 +23,11 @@ struct ClientConfig {
   ConnectionType connection_type;
 };
 
+/**
+ * @brief Network client for managing connections and communication to a server.
+ *
+ * Handles client lifecycle, connecting, disconnecting, and network operations within an event-driven framework.
+ */
 class Client : public Interface {
  public:
   Client(const ClientConfig& config);
@@ -30,11 +35,47 @@ class Client : public Interface {
 
   ~Client();
 
+  /**
+   * @brief Binds client to configured IP address and port. This function is not thread-safe.
+   *
+   * @return Result::Success if binding is successful
+   * @return Result::InvalidAddress if IP address is invalid
+   * @return Result::CannotCreateSocket if socket creation fails
+   * @return Result::CannotBind if binding to address:port fails
+   * @return Result::Failure if setup process fails
+   */
   Result Bind() override;
-  void Wait() override;
+
+  /**
+   * @brief Establishes connection to the specified server address. This function is not thread-safe.
+   *
+   * @return Result::Success if the connection is successfully established.
+   * @return Result::AlreadyConnected if a connection is already active.
+   * @return Result::InvalidRemoteAddress if the server address is invalid.
+   * @return Result::Failure if the connection attempt fails.
+   */
   Result Connect();
+
+  /**
+   * @brief Terminates the connection. This function is not thread-safe.
+   *
+   * @return Result::Success if the disconnection is successful.
+   * @return Result::Failure if no active session exists or disconnection fails.
+   */
   Result Disconnect();
 
+  /**
+   * @brief Waits for the completion of the client's thread. This function is thread-safe.
+   *
+   * This method blocks the calling thread until the client's internal thread,
+   * which handles network operations and session management, has completed (disconnected).
+   *
+   * Typically used during client shutdown or when there is a need to
+   * synchronize the caller with the client's task execution.
+   *
+   */
+  void Wait() override;
+
   ZNET_NODISCARD std::shared_ptr<PeerSession> client_session() const {
     return client_session_;
   }
diff --git a/znet/include/znet/client_events.h b/znet/include/znet/client_events.h
index bbdaab2..7935e73 100644
--- a/znet/include/znet/client_events.h
+++ b/znet/include/znet/client_events.h
@@ -17,6 +17,15 @@
 
 namespace znet {
 
+/**
+ * @class ClientConnectedToServerEvent
+ * @brief Represents an event triggered when a client successfully connects to the server.
+ *
+ * @details
+ * This event is where you would setup the peer, set the codec, handlers and
+ * the user pointer if needed.
+ *
+ */
 class ClientConnectedToServerEvent : public Event {
  public:
   explicit ClientConnectedToServerEvent(std::shared_ptr<PeerSession> session)
@@ -30,6 +39,12 @@ class ClientConnectedToServerEvent : public Event {
   std::shared_ptr<PeerSession> session_;
 };
 
+/**
+ * @class ClientDisconnectedFromServerEvent
+ * @brief Represents an event triggered when a client disconnects from the server.
+ *
+ * This event encapsulates the session details of the disconnected client.
+ */
 class ClientDisconnectedFromServerEvent : public Event {
  public:
   explicit ClientDisconnectedFromServerEvent(std::shared_ptr<PeerSession> session)
diff --git a/znet/include/znet/codec.h b/znet/include/znet/codec.h
index 7df919b..3d002ee 100644
--- a/znet/include/znet/codec.h
+++ b/znet/include/znet/codec.h
@@ -13,76 +13,54 @@
 
 #include "znet/precompiled.h"
 #include "znet/base/packet.h"
+#include "znet/packet_serializer.h"
+#include "znet/packet_handler.h"
 #include "znet/buffer.h"
 
 namespace znet {
 
+/**
+ * @brief Provides serialization and deserialization of packets.
+ */
 class Codec {
  public:
-  Codec() {
+  Codec();
+  ~Codec() = default;
 
-  }
+  /**
+   * @brief Deserializes packets from a buffer and handles them using the provided handler.
+   *
+   * Processes a binary buffer by reading packet IDs, sizes, and payloads. Uses the appropriate
+   * serializer based on the packet ID to deserialize the packet. Deserialized packets are
+   * passed to the given packet handler. Logs warnings for issues such as missing serializers,
+   * deserialization failures, or size mismatches.
+   *
+   * @param buffer A shared pointer to the buffer containing packet data.
+   * @param handler Reference to the packet handler responsible for processing deserialized packets.
+   */
+  void Deserialize(std::shared_ptr<Buffer> buffer, PacketHandlerBase& handler);
 
-  void Deserialize(std::shared_ptr<Buffer> buffer, PacketHandlerBase& handler) {
-    while (buffer->readable_bytes() > 0) {
-      auto packet_id = buffer->ReadVarInt<PacketId>();
-      auto size = buffer->ReadInt<size_t>();
-      if (buffer->IsFailedToRead()) {
-        ZNET_LOG_DEBUG("Reading packet header failed, dropping buffer!");
-        break;
-      }
-      // Todo limit max read buffer
-      size_t read_cursor = buffer->read_cursor();
-      auto it = serializers_.find(packet_id);
-      if (it == serializers_.end()) {
-        ZNET_LOG_WARN("Serializer for packet {} does not exist!", packet_id);
-        buffer->SkipRead(size);
-        continue;
-      }
-      PacketSerializerBase& serializer = *it->second;
-      std::shared_ptr<Packet> pk = serializer.Deserialize(buffer);
-      if (!pk) {
-        ZNET_LOG_WARN("Packet {} was not deserialized!", packet_id);
-        buffer->SkipRead(size); // todo instead of skipping fixed amount, jump to the end
-        continue;
-      }
-      handler.Handle(pk);
-      size_t read_cursor_end = buffer->read_cursor();
-      size_t read_bytes = read_cursor_end - read_cursor;
-      if (read_bytes < size) {
-        ZNET_LOG_WARN("Packet {} size mismatch! Expected {}, read {}",
-                      packet_id, size, read_bytes);
-      }
-    }
-  }
+  /**
+   * @brief Serializes a packet into a binary buffer.
+   *
+   * This function retrieves the appropriate serializer for the packet
+   * based on its ID, writes the packet ID, and serializes the packet
+   * into a binary buffer. Ensures the serialized size is properly recorded.
+   *
+   * @param packet A shared pointer to the packet to be serialized.
+   * @return A shared pointer to the resulting serialized buffer.
+   *         Returns nullptr if no serializer is found for the packet.
+   */
+  std::shared_ptr<Buffer> Serialize(std::shared_ptr<Packet> packet);
 
-  std::shared_ptr<Buffer> Serialize(std::shared_ptr<Packet> packet) {
-    auto it = serializers_.find(packet->id());
-    if (it == serializers_.end()) {
-      ZNET_LOG_WARN("Failed to find a serializer for packet {}!", packet->id());
-      return nullptr;
-    }
-    PacketSerializerBase& serializer = *it->second;
-    std::shared_ptr<Buffer> buffer = std::make_shared<Buffer>();
-    buffer->WriteVarInt(packet->id());
-    buffer->WriteInt<size_t>(0);
-    size_t write_cursor = buffer->write_cursor();
-    auto ptr = buffer.get();
-    buffer = serializer.Serialize(packet, buffer);
-    // Serializer can change the buffer, so we need to check if it is changed.
-    if (ptr == buffer.get()) {
-      size_t write_cursor_end = buffer->write_cursor();
-      size_t size = write_cursor_end - write_cursor;
-      buffer->set_write_cursor(write_cursor - sizeof(size_t));
-      buffer->WriteInt(size);
-      buffer->set_write_cursor(write_cursor_end);
-    }
-    return buffer;
-  }
+  /**
+   * @brief Registers a packet serializer for a specific packet type.
+   *
+   * @param id Unique identifier for the packet type.
+   * @param serializer Serializer instance to handle the packet type.
+   */
+  void Add(PacketId id, std::unique_ptr<PacketSerializerBase> serializer);
 
-  void Add(PacketId id, std::unique_ptr<PacketSerializerBase> serializer) {
-    serializers_.insert(std::pair<PacketId, std::unique_ptr<PacketSerializerBase>>(id, std::move(serializer)));
-  }
  private:
   std::unordered_map<PacketId, std::unique_ptr<PacketSerializerBase>> serializers_;
 };
diff --git a/znet/include/znet/peer_session.h b/znet/include/znet/peer_session.h
index d0fcd91..277c385 100644
--- a/znet/include/znet/peer_session.h
+++ b/znet/include/znet/peer_session.h
@@ -18,6 +18,17 @@
 
 namespace znet {
 
+/**
+ * @class PeerSession
+ * @brief Represents a network session between a local and remote peer.
+ *
+ * PeerSession handles communication between two network peers, managing the
+ * transport layer, encryption, and packet handling. It also supports session
+ * expiration and user-defined data attachment.
+ *
+ * The class does not allow copy or move semantics to ensure each session
+ * instance is unique.
+ */
 class PeerSession {
  public:
   PeerSession(std::shared_ptr<InetAddress> local_address,
diff --git a/znet/include/znet/precompiled.h b/znet/include/znet/precompiled.h
index f4bb47d..4305129 100644
--- a/znet/include/znet/precompiled.h
+++ b/znet/include/znet/precompiled.h
@@ -77,3 +77,9 @@ typedef SSIZE_T ssize_t;
 #else
 #define ZNET_NODISCARD
 #endif
+
+#if defined(__clang__) || (defined(__GNUC__) && __GNUC__ >= 9) || (_MSC_VER >= 1928 && _MSVC_LANG >= 202002L)
+#define DEPRECATED_TYPE_ALIAS(old, new, msg) [[deprecated(msg)]] using old = new;
+#else
+#define DEPRECATED_TYPE_ALIAS(old, new, msg) typedef new old;
+#endif
diff --git a/znet/include/znet/server.h b/znet/include/znet/server.h
index 0eee2ac..c72cacf 100644
--- a/znet/include/znet/server.h
+++ b/znet/include/znet/server.h
@@ -10,11 +10,11 @@
 
 #pragma once
 
-#include "znet/precompiled.h"
+#include "znet/base/scheduler.h"
 #include "znet/interface.h"
-#include "znet/peer_session.h"
 #include "znet/logger.h"
-#include "znet/base/scheduler.h"
+#include "znet/peer_session.h"
+#include "znet/precompiled.h"
 #include "znet/task.h"
 
 namespace znet {
@@ -25,9 +25,15 @@ struct ServerConfig {
   ConnectionType connection_type;
 };
 
+/**
+ * @brief Network server managing connections and peer sessions.
+ *
+ * Handles server lifecycle, connection management, and network operations within an event-driven framework.
+ */
 class Server : public Interface {
  public:
-  using SessionMap = std::unordered_map<std::shared_ptr<InetAddress>, std::shared_ptr<PeerSession>>;
+  using SessionMap = std::unordered_map<std::shared_ptr<InetAddress>,
+                                        std::shared_ptr<PeerSession>>;
 
   Server();
   explicit Server(const ServerConfig& config);
@@ -35,11 +41,64 @@ class Server : public Interface {
 
   ~Server() override;
 
+  /**
+   * @brief Binds server to configured IP address and port. This function is not thread-safe.
+   *
+   * @return Result::Success if binding is successful
+   * @return Result::InvalidAddress if IP address is invalid
+   * @return Result::CannotCreateSocket if socket creation fails
+   * @return Result::CannotBind if binding to address:port fails
+   * @return Result::Failure if setup process fails
+   */
   Result Bind() override;
-  void Wait() override;
+
+  /**
+   * @brief Starts server and accepts incoming connections. This function is not thread-safe.
+   *
+   * Initializes server's listening state and begins accepting client connections.
+   * Creates a task to manage network operations and session handling.
+   *
+   * This function does not block the main thread, it does its listening in its
+   * own thread. (async)
+   *
+   * @return Result::Success if server starts successfully
+   * @return Result::AlreadyListening if already in listening state
+   * @return Result::CannotListen if listening fails
+   */
   Result Listen();
+
+  /**
+   * @brief Waits for the completion of the server's thread. This function is thread-safe.
+   *
+   * This method blocks the calling thread until the server's internal thread,
+   * which handles network operations and session management, has completed.
+   *
+   * Typically used during server shutdown or when there is a need to
+   * synchronize the caller with the server's task execution.
+   *
+   */
+  void Wait() override;
+
+  /**
+   * @brief Stops the server and releases associated resources. This function is thread-safe.
+   *
+   * This method stops the server from listening for incoming connections
+   * and terminates its active listening state.
+   *
+   * @return Result::Success if the server was successfully stopped.
+   * @return Result::AlreadyStopped if the server was already stopped and
+   *         not in a listening state.
+   */
   Result Stop();
 
+  /**
+   * @brief Configures the number of ticks per second for the server. This function is thread-safe.
+   *
+   * Adjusts the server's tick rate to control the frequency of internal updates.
+   * Ensures the tick rate is set to a minimum of 1 tick per second, preventing invalid values.
+   *
+   * @param tps The desired ticks per second, must be greater than or equal to 1.
+   */
   void SetTicksPerSecond(int tps);
 
   ZNET_NODISCARD bool shutdown_complete() const { return shutdown_complete_; }
diff --git a/znet/include/znet/server_events.h b/znet/include/znet/server_events.h
index caecb2e..4239705 100644
--- a/znet/include/znet/server_events.h
+++ b/znet/include/znet/server_events.h
@@ -17,19 +17,31 @@
 
 namespace znet {
 
-class ServerClientConnectedEvent : public Event {
+/**
+ * @brief Event triggered when a client connects to this server.
+ *
+ * This event is where you would setup the peer, set the codec, handlers and
+ * the user pointer if needed.
+ */
+class IncomingClientConnectedEvent : public Event {
  public:
-  explicit ServerClientConnectedEvent(std::shared_ptr<PeerSession> session)
+  explicit IncomingClientConnectedEvent(std::shared_ptr<PeerSession> session)
       : session_(session) {}
 
   std::shared_ptr<PeerSession> session() { return session_; }
 
-  ZNET_EVENT_CLASS_TYPE(ServerClientConnectedEvent)
+  ZNET_EVENT_CLASS_TYPE(IncomingClientConnectedEvent)
   ZNET_EVENT_CLASS_CATEGORY(EventCategoryServer)
  private:
   std::shared_ptr<PeerSession> session_;
 };
 
+DEPRECATED_TYPE_ALIAS(ServerClientConnectedEvent,
+                      IncomingClientConnectedEvent, "Use IncomingClientConnectedEvent instead")
+
+/**
+ * @brief Event triggered when a client disconnects from the server.
+ */
 class ServerClientDisconnectedEvent : public Event {
  public:
   explicit ServerClientDisconnectedEvent(std::shared_ptr<PeerSession> session)
@@ -45,6 +57,9 @@ class ServerClientDisconnectedEvent : public Event {
 
 class Server;
 
+/**
+ * @brief Event triggered when the server starts up.
+ */
 class ServerStartupEvent : public Event {
  public:
   ServerStartupEvent(Server& server) : server_(server) {}
@@ -57,6 +72,9 @@ class ServerStartupEvent : public Event {
   Server& server_;
 };
 
+/**
+ * @brief Event triggered when the server shuts down.
+ */
 class ServerShutdownEvent : public Event {
  public:
   ServerShutdownEvent(Server& server) : server_(server) {}
diff --git a/znet/src/client.cc b/znet/src/client.cc
index 2a219db..25a324e 100644
--- a/znet/src/client.cc
+++ b/znet/src/client.cc
@@ -20,6 +20,8 @@ Client::Client(const ClientConfig& config) : config_(config) {
 }
 
 Client::~Client() {
+  ZNET_LOG_DEBUG("Destructor of the client is called.");
+  Disconnect();
 #ifdef TARGET_WIN
   WSACleanup();
 #endif
diff --git a/znet/src/codec.cc b/znet/src/codec.cc
new file mode 100644
index 0000000..fd13ac6
--- /dev/null
+++ b/znet/src/codec.cc
@@ -0,0 +1,102 @@
+//
+//    Copyright 2025 Metehan Gezer
+//
+//    Licensed under the Apache License, Version 2.0 (the "License");
+//    you may not use this file except in compliance with the License.
+//    You may obtain a copy of the License at
+//
+//        http://www.apache.org/licenses/LICENSE-2.0
+//
+
+#include "znet/codec.h"
+
+namespace znet {
+
+Codec::Codec() {
+
+}
+
+void Codec::Deserialize(std::shared_ptr<Buffer> buffer, PacketHandlerBase& handler) {
+  while (buffer->readable_bytes() > 0) {
+    auto packet_id = buffer->ReadVarInt<PacketId>();
+    auto size = buffer->ReadInt<size_t>();
+    if (buffer->IsFailedToRead()) {
+      ZNET_LOG_DEBUG("Reading packet header failed, dropping buffer!");
+      break;
+    }
+    if (size == 0) {
+      ZNET_LOG_DEBUG("Got packet with size 0, dropping it!");
+      continue;
+    }
+    size_t read_cursor = buffer->read_cursor();
+    auto it = serializers_.find(packet_id);
+    if (it == serializers_.end()) {
+      ZNET_LOG_WARN("Serializer for packet {} does not exist!", packet_id);
+      buffer->SkipRead(size);
+      continue;
+    }
+    // Set a read limit so the serializer cannot accidentally read more
+    // than it should
+    buffer->SetReadLimit(read_cursor + size);
+    PacketSerializerBase& serializer = *it->second;
+    std::shared_ptr<Packet> pk = serializer.Deserialize(buffer);
+    if (!pk) {
+      ZNET_LOG_WARN("Packet {} was not deserialized!", packet_id);
+      // We go back to the start, in case it was partially read
+      buffer->set_read_cursor(read_cursor);
+      // Then skip the number of bytes given
+      buffer->SkipRead(size);
+      // Disable the read limit
+      buffer->SetReadLimit(0);
+      continue;
+    }
+    size_t read_cursor_end = buffer->read_cursor();
+    size_t read_bytes = read_cursor_end - read_cursor;
+    if (read_bytes < size) {
+      ZNET_LOG_WARN("Packet {} size mismatch! Expected {}, read {}.",
+                    packet_id, size, read_bytes);
+      buffer->set_read_cursor(read_cursor);
+      buffer->SkipRead(size);
+    } else if (read_bytes > size) {
+      ZNET_LOG_WARN("Packet {} size mismatch! Expected {}, read {}. This will drop the packet and rest of the buffer.",
+                    packet_id, size, read_bytes);
+      // TODO: Perhaps add an option to dump the buffer when this happens. This might be malicious attempt.
+      // Unlike the other mismatch, we don't need to reset the cursor or anything like that since the buffer will be dropped.
+      break;
+    }
+    // Disable the read limit
+    buffer->SetReadLimit(0);
+    handler.Handle(pk);
+  }
+}
+
+std::shared_ptr<Buffer> Codec::Serialize(std::shared_ptr<Packet> packet) {
+  auto it = serializers_.find(packet->id());
+  if (it == serializers_.end()) {
+    ZNET_LOG_WARN("Failed to find a serializer for packet {}!", packet->id());
+    return nullptr;
+  }
+  PacketSerializerBase& serializer = *it->second;
+  std::shared_ptr<Buffer> buffer = std::make_shared<Buffer>();
+  buffer->WriteVarInt(packet->id());
+  buffer->WriteInt<size_t>(0);
+  size_t write_cursor = buffer->write_cursor();
+  auto ptr = buffer.get();
+  buffer = serializer.Serialize(packet, buffer);
+  // Serializer can change the buffer, so we need to check if it is changed.
+  if (ptr == buffer.get()) {
+    // We do this only when the buffer is not changed
+    size_t write_cursor_end = buffer->write_cursor();
+    size_t size = write_cursor_end - write_cursor;
+    buffer->set_write_cursor(write_cursor - sizeof(size_t));
+    buffer->WriteInt(size);
+    buffer->set_write_cursor(write_cursor_end);
+  }
+  return buffer;
+}
+
+void Codec::Add(PacketId id, std::unique_ptr<PacketSerializerBase> serializer) {
+  serializers_.insert(std::pair<PacketId, std::unique_ptr<PacketSerializerBase>>(id, std::move(serializer)));
+}
+
+}
diff --git a/znet/src/inet_addr.cc b/znet/src/inet_addr.cc
index e710327..0f3b059 100644
--- a/znet/src/inet_addr.cc
+++ b/znet/src/inet_addr.cc
@@ -92,4 +92,100 @@ std::unique_ptr<InetAddress> InetAddress::from(sockaddr* sock_addr) {
   return nullptr;
 }
 
+InetAddressIPv4::InetAddressIPv4(PortNumber port)
+    : InetAddress(InetProtocolVersion::IPv4, "") {
+  addr.sin_family = AF_INET;
+  addr.sin_port = htons(port);
+#ifdef TARGET_APPLE
+  addr.sin_len = sizeof(sockaddr_in);
+#endif
+  char src[INET_ADDRSTRLEN];
+  inet_ntop(AF_INET, &addr.sin_addr, src, INET_ADDRSTRLEN);
+  readable_ = std::string(src) + ":" + std::to_string(ntohs(addr.sin_port));
+  is_valid_ = true;
+}
+
+InetAddressIPv4::InetAddressIPv4(IPv4Address ip, PortNumber port)
+    : InetAddress(InetProtocolVersion::IPv4, "") {
+  addr.sin_family = AF_INET;
+  addr.sin_port = htons(port);
+  addr.sin_addr = ip;
+#ifdef TARGET_APPLE
+  addr.sin_len = sizeof(sockaddr_in);
+#endif
+
+  char src[INET_ADDRSTRLEN];
+  inet_ntop(AF_INET, &addr.sin_addr, src, INET_ADDRSTRLEN);
+  readable_ = std::string(src) + ":" + std::to_string(ntohs(addr.sin_port));
+  is_valid_ = true;
+}
+
+InetAddressIPv4::InetAddressIPv4(const std::string& str, PortNumber port)
+    : InetAddress(InetProtocolVersion::IPv4, "") {
+  if (!IsValidIPv4(str)) {
+    is_valid_ = false;
+    readable_ = "Invalid Address";
+    return;
+  }
+
+  addr.sin_family = AF_INET;
+  addr.sin_port = htons(port);
+  addr.sin_addr = ParseIPv4(str);
+#ifdef TARGET_APPLE
+  addr.sin_len = sizeof(sockaddr_in);
+#endif
+  char src[INET_ADDRSTRLEN];
+  inet_ntop(AF_INET, &addr.sin_addr, src, INET_ADDRSTRLEN);
+  readable_ = std::string(src) + ":" + std::to_string(ntohs(addr.sin_port));
+  is_valid_ = true;
+}
+
+InetAddressIPv6::InetAddressIPv6(PortNumber port)
+    : InetAddress(InetProtocolVersion::IPv6, "") {
+  addr.sin6_family = AF_INET6;
+  addr.sin6_flowinfo = 0;
+  addr.sin6_port = htons(port);
+#if !defined(TARGET_WIN) && !defined(TARGET_WEB) && !defined(TARGET_LINUX)
+  addr.sin6_len = sizeof(sockaddr_in6);
+#endif
+  char src[INET6_ADDRSTRLEN];
+  inet_ntop(AF_INET6, &addr.sin6_addr, src, sizeof(src));
+  readable_ = std::string(src) + ":" + std::to_string(ntohs(addr.sin6_port));
+  is_valid_ = true;
+}
+
+InetAddressIPv6::InetAddressIPv6(IPv6Address ip, PortNumber port)
+    : InetAddress(InetProtocolVersion::IPv6, "") {
+  addr.sin6_family = AF_INET6;
+  addr.sin6_flowinfo = 0;
+  addr.sin6_port = htons(port);
+  addr.sin6_addr = ip;
+#if !defined(TARGET_WIN) && !defined(TARGET_WEB) && !defined(TARGET_LINUX)
+  addr.sin6_len = sizeof(sockaddr_in6);
+#endif
+  char src[INET6_ADDRSTRLEN];
+  inet_ntop(AF_INET6, &addr.sin6_addr, src, sizeof(src));
+  readable_ = std::string(src) + ":" + std::to_string(ntohs(addr.sin6_port));
+  is_valid_ = true;
+}
+
+InetAddressIPv6::InetAddressIPv6(const std::string& str, PortNumber port)
+    : InetAddress(InetProtocolVersion::IPv6, "") {
+  if (!IsValidIPv6(str)) {
+    is_valid_ = false;
+    readable_ = "Invalid Address";
+    return;
+  }
+#if !defined(TARGET_WIN) && !defined(TARGET_WEB) && !defined(TARGET_LINUX)
+  addr.sin6_len = sizeof(sockaddr_in6);
+#endif
+  addr.sin6_family = AF_INET6;
+  addr.sin6_flowinfo = 0;
+  addr.sin6_port = htons(port);
+  addr.sin6_addr = ParseIPv6(str);
+  char src[INET6_ADDRSTRLEN];
+  inet_ntop(AF_INET6, &addr.sin6_addr, src, sizeof(src));
+  readable_ = std::string(src) + ":" + std::to_string(ntohs(addr.sin6_port));
+  is_valid_ = true;
+}
 }  // namespace znet
\ No newline at end of file
diff --git a/znet/src/packet_handler.cc b/znet/src/packet_handler.cc
deleted file mode 100644
index 0d1a308..0000000
--- a/znet/src/packet_handler.cc
+++ /dev/null
@@ -1,17 +0,0 @@
-//
-//    Copyright 2024 Metehan Gezer
-//
-//    Licensed under the Apache License, Version 2.0 (the "License");
-//    you may not use this file except in compliance with the License.
-//    You may obtain a copy of the License at
-//
-//        http://www.apache.org/licenses/LICENSE-2.0
-//
-
-#include "znet/packet_handler.h"
-
-namespace znet {
-
-
-
-}  // namespace znet
\ No newline at end of file
diff --git a/znet/src/server.cc b/znet/src/server.cc
index 7ab95fb..ef56c71 100644
--- a/znet/src/server.cc
+++ b/znet/src/server.cc
@@ -20,6 +20,8 @@ Server::Server() : Interface() {}
 Server::Server(const ServerConfig& config) : Interface(), config_(config) {}
 
 Server::~Server() {
+  ZNET_LOG_DEBUG("Destructor of the server is called.");
+  Stop();
 #ifdef TARGET_WIN
   WSACleanup();
 #endif
@@ -253,7 +255,7 @@ void Server::ProcessSessions() {
     auto session = pending_sessions_[address];
     // promote to connected
     sessions_[address] = session;
-    ServerClientConnectedEvent event{session};
+    IncomingClientConnectedEvent event{session};
     event_callback()(event);
     ZNET_LOG_DEBUG("New connection is ready. {}", address->readable());
     // erase pending

From eb4b5974ee895bf495909a96cbce36b83940fc71 Mon Sep 17 00:00:00 2001
From: Metehan Gezer <irrelevantdev@outlook.com>
Date: Fri, 1 Aug 2025 04:22:53 +0300
Subject: [PATCH 09/12] update todo

---
 TODO | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/TODO b/TODO
index b0ced7e..220936a 100644
--- a/TODO
+++ b/TODO
@@ -5,19 +5,20 @@
 - [x] Client Implementation
 - [ ] Compression (optional if zlib or zstd is added)
 - [x] Encryption
-- [ ] Protocol version check
 - [ ] TCP options
 - [x] Windows support
 - [x] Linux support (Linux should be the same)
 - [x] Endianness
 - [ ] Saving packet buffer to a file
-- [ ] Async Example
 - [ ] More events
 - [ ] Better error handling
 - [x] Unit tests
 - [ ] More unit tests 
-- [ ] Documentation
-- [ ] Error handling in SendPacket and SendRaw
+- [x] Documentation
+- [ ] Error handling in SendPacket
 - [ ] Proxy support
 - [ ] Unix socket support
-- [ ] Limit array/vector read sizes
+- [ ] Limit array/vector/string read sizes
+- [ ] Connection throttling
+- [ ] Peer to peer TCP hole-punching
+- [ ] Validate IP addresses

From f8d46ab3832e807117440d55650282f9fcc53c0e Mon Sep 17 00:00:00 2001
From: Metehan Gezer <irrelevantdev@outlook.com>
Date: Fri, 1 Aug 2025 04:23:46 +0300
Subject: [PATCH 10/12] fix memory leak on ReadInt

---
 znet/include/znet/buffer.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/znet/include/znet/buffer.h b/znet/include/znet/buffer.h
index f9a90ff..a6323df 100644
--- a/znet/include/znet/buffer.h
+++ b/znet/include/znet/buffer.h
@@ -100,7 +100,7 @@ class Buffer {
   template<typename T, typename std::enable_if<std::is_arithmetic<T>::value && (sizeof(T) <= 8), int>::type = 0>
   T ReadInt() {
     size_t size = sizeof(T);
-    char* data = new (std::nothrow) char[size];
+    std::unique_ptr<char[]> data(new (std::nothrow) char[size]);
     if (!data) {
       failed_to_read_ = true;
       failed_to_alloc_ = true;
@@ -121,7 +121,7 @@ class Buffer {
     }
     read_cursor_ += size;
     T l = 0;
-    std::memcpy(&l, data, size);
+    std::memcpy(&l, data.get(), size);
     return l;
   }
 

From fe26c10cbb2eaa2cf9d7ebf3906a3745061c2a96 Mon Sep 17 00:00:00 2001
From: Metehan Gezer <irrelevantdev@outlook.com>
Date: Fri, 1 Aug 2025 04:23:56 +0300
Subject: [PATCH 11/12] limit the array size

---
 znet/include/znet/buffer.h | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/znet/include/znet/buffer.h b/znet/include/znet/buffer.h
index a6323df..ff1bf66 100644
--- a/znet/include/znet/buffer.h
+++ b/znet/include/znet/buffer.h
@@ -81,6 +81,10 @@ class Buffer {
 
   template<typename T, typename std::enable_if<std::is_arithmetic<T>::value && (sizeof(T) <= 8), int>::type = 0>
   void Read(T* arr, size_t size) {
+    if (size > std::numeric_limits<size_t>::max() / sizeof(T)) {
+      failed_to_read_ = true;
+      return;
+    }
     char* pt = reinterpret_cast<char*>(arr);
     size_t calculated_size = sizeof(T) * size;
     if (!CheckReadableBytes(size)) {

From 2d392e4077081e88ce3f6191bad0197870edb43b Mon Sep 17 00:00:00 2001
From: Metehan Gezer <irrelevantdev@outlook.com>
Date: Fri, 1 Aug 2025 04:24:07 +0300
Subject: [PATCH 12/12] handle nullptr on WriteArray

---
 znet/include/znet/buffer.h | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/znet/include/znet/buffer.h b/znet/include/znet/buffer.h
index ff1bf66..0b5f677 100644
--- a/znet/include/znet/buffer.h
+++ b/znet/include/znet/buffer.h
@@ -418,6 +418,10 @@ class Buffer {
 
   template <typename ValueFunc, typename T>
   void WriteArray(T* v, size_t size, ValueFunc value_func) {
+    if (!v) {
+      WriteInt(0);
+      return;
+    }
     WriteInt(size);
     for (int i = 0; i < size; i++) {
       auto& value = v[i];