ADD: Add error and system code enums

Author: threecgreen

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.34.0 - TBD
+
+### Enhancements
+- Added `SystemCode` and `ErrorCode` enums to indicate types of system and error
+  messages
+- Converting a `v1::SystemMsg` to a `v2::SystemMsg` now sets to `code` to the heartbeat
+  value
+
+### Breaking changes
+- Changed type of `code` field in `SystemMsg` to `SystemCode`
+- Changed type of `code` field in `ErrorMsg` to `ErrorCode`
+
+### Bug fixes
+- Changed `TriState` to a regular enum to handle unexpected values
+
 ## 0.33.0 - 2025-04-15
 
 ### Enhancements

include/databento/enums.hpp

@@ -439,14 +439,55 @@ using trading_event::TradingEvent;
 
 // An enum for representing unknown, true, or false values. Equivalent to a
 // std::optional<bool>.
-enum class TriState : char {
+namespace tri_state {
+enum TriState : char {
   // The value is not applicable or not known.
   NotAvailable = '~',
   // False
   No = 'N',
   // True
   Yes = 'Y',
 };
+}  // namespace tri_state
+using tri_state::TriState;
+
+namespace error_code {
+enum ErrorCode : std::uint8_t {
+  // The authentication step failed.
+  AuthFailed = 1,
+  // The user account or API key were deactivated.
+  ApiKeyDeactivated = 2,
+  // The user has exceeded their open connection limit
+  ConnectionLimitExceeded = 3,
+  // One or more symbols failed to resolve.
+  SymbolResolutionFailed = 4,
+  // There was an issue with a subscription request (other than symbol
+  // resolution).
+  InvalidSubscription = 5,
+  // An error occurred in the gateway.
+  InternalError = 6,
+
+  Unset = 255,
+};
+}  // namespace error_code
+using error_code::ErrorCode;
+
+namespace system_code {
+enum SystemCode : std::uint8_t {
+  // A message sent in the absence of other records to indicate the connection
+  // remains open.
+  Heartbeat = 0,
+  // An acknowledgement of a subscription request.
+  SubscriptionAck = 1,
+  // The gateway has detected this session is falling behind real-time.
+  SlowReaderWarning = 2,
+  // Indicates a replay subscription has caught up with real-time data.
+  ReplayCompleted = 3,
+
+  Unset = 255,
+};
+}  // namespace system_code
+using system_code::SystemCode;
 
 // Convert a HistoricalGateway to a URL.
 const char* UrlFromGateway(HistoricalGateway gateway);
@@ -474,6 +515,8 @@ const char* ToString(StatusReason status_reason);
 const char* ToString(TradingEvent trading_event);
 const char* ToString(TriState tri_state);
 const char* ToString(VersionUpgradePolicy upgrade_policy);
+const char* ToString(ErrorCode error_code);
+const char* ToString(SystemCode system_code);
 
 std::ostream& operator<<(std::ostream& out, Schema schema);
 std::ostream& operator<<(std::ostream& out, Encoding encoding);
@@ -501,6 +544,8 @@ std::ostream& operator<<(std::ostream& out, TradingEvent trading_event);
 std::ostream& operator<<(std::ostream& out, TriState tri_state);
 std::ostream& operator<<(std::ostream& out,
                          VersionUpgradePolicy upgrade_policy);
+std::ostream& operator<<(std::ostream& out, ErrorCode error_code);
+std::ostream& operator<<(std::ostream& out, SystemCode system_code);
 
 template <>
 Schema FromString(const std::string& str);

include/databento/record.hpp

@@ -4,6 +4,7 @@
 #include <cstddef>
 #include <cstdint>
 #include <cstring>  // strncmp
+#include <limits>
 #include <string>
 #include <tuple>  // tie
 #include <type_traits>
@@ -528,7 +529,7 @@ struct ErrorMsg {
 
   RecordHeader hd;
   std::array<char, 302> err;
-  std::uint8_t code;
+  ErrorCode code;
   std::uint8_t is_last;
 };
 static_assert(sizeof(ErrorMsg) == 320, "ErrorMsg size must match Rust");
@@ -560,12 +561,17 @@ struct SystemMsg {
   UnixNanos IndexTs() const { return hd.ts_event; }
   const char* Msg() const { return msg.data(); }
   bool IsHeartbeat() const {
-    return std::strncmp(msg.data(), "Heartbeat", 9) == 0;
+    // Check if code is unset
+    if (static_cast<std::uint8_t>(code) ==
+        std::numeric_limits<std::uint8_t>::max()) {
+      return std::strncmp(msg.data(), "Heartbeat", 9) == 0;
+    }
+    return code == SystemCode::Heartbeat;
   }
 
   RecordHeader hd;
   std::array<char, 303> msg;
-  std::uint8_t code;
+  SystemCode code;
 };
 static_assert(sizeof(SystemMsg) == 320, "SystemMsg size must match Rust");
 static_assert(alignof(SystemMsg) == 8, "Must have 8-byte alignment");

src/enums.cpp

@@ -760,6 +760,52 @@ const char* ToString(VersionUpgradePolicy upgrade_policy) {
   }
 }
 
+const char* ToString(ErrorCode error_code) {
+  switch (error_code) {
+    case ErrorCode::AuthFailed: {
+      return "auth_failed";
+    }
+    case ErrorCode::ApiKeyDeactivated: {
+      return "api_key_deactivated";
+    }
+    case ErrorCode::ConnectionLimitExceeded: {
+      return "connection_limit_exceeded";
+    }
+    case ErrorCode::SymbolResolutionFailed: {
+      return "symbol_resolution_failed";
+    }
+    case ErrorCode::InvalidSubscription: {
+      return "invalid_subscription";
+    }
+    case ErrorCode::InternalError: {
+      return "internal_error";
+    }
+    default: {
+      return "Unknown";
+    }
+  }
+}
+
+const char* ToString(SystemCode system_code) {
+  switch (system_code) {
+    case SystemCode::Heartbeat: {
+      return "heartbeat";
+    }
+    case SystemCode::SubscriptionAck: {
+      return "subscription_ack";
+    }
+    case SystemCode::SlowReaderWarning: {
+      return "slow_reader_warning";
+    }
+    case SystemCode::ReplayCompleted: {
+      return "replay_completed";
+    }
+    default: {
+      return "Unknown";
+    }
+  }
+}
+
 std::ostream& operator<<(std::ostream& out, Schema schema) {
   out << ToString(schema);
   return out;
@@ -876,6 +922,16 @@ std::ostream& operator<<(std::ostream& out,
   return out;
 }
 
+std::ostream& operator<<(std::ostream& out, ErrorCode error_code) {
+  out << ToString(error_code);
+  return out;
+}
+
+std::ostream& operator<<(std::ostream& out, SystemCode system_code) {
+  out << ToString(system_code);
+  return out;
+}
+
 template <>
 Schema FromString(const std::string& str) {
   if (str == "mbo") {

src/v1.cpp

@@ -2,9 +2,11 @@
 
 #include <algorithm>  // copy
 #include <cstdint>
+#include <cstring>
 #include <limits>  // numeric_limits
 
 #include "databento/constants.hpp"
+#include "databento/enums.hpp"
 #include "databento/fixed_price.hpp"  // FixedPx
 #include "databento/record.hpp"
 #include "databento/v2.hpp"
@@ -193,7 +195,7 @@ v2::ErrorMsg ErrorMsg::ToV2() const {
                    RType::Error, hd.publisher_id, hd.instrument_id,
                    hd.ts_event},
       {},
-      std::numeric_limits<std::uint8_t>::max(),
+      ErrorCode::Unset,
       std::numeric_limits<std::uint8_t>::max()};
   std::copy(err.begin(), err.end(), ret.err.begin());
   return ret;
@@ -227,7 +229,7 @@ v2::SystemMsg SystemMsg::ToV2() const {
                    RType::System, hd.publisher_id, hd.instrument_id,
                    hd.ts_event},
       {},
-      std::numeric_limits<std::uint8_t>::max()};
+      IsHeartbeat() ? SystemCode::Heartbeat : SystemCode::Unset};
   std::copy(msg.begin(), msg.end(), ret.msg.begin());
   return ret;
 }