RSDK-2758 Add an exception system

src/viam/sdk/CMakeLists.txt

@@ -37,6 +37,7 @@ endif()
 target_sources(viamsdk
   PRIVATE
     common/client_helper.cpp
+    common/exception.cpp
     common/linear_algebra.cpp
     common/pose.cpp
     common/proto_type.cpp
@@ -109,6 +110,7 @@ target_sources(viamsdk
       ../..
     FILES
       ../../viam/sdk/common/client_helper.hpp
+      ../../viam/sdk/common/exception.hpp
       ../../viam/sdk/common/linear_algebra.hpp
       ../../viam/sdk/common/pose.hpp
       ../../viam/sdk/common/proto_type.hpp

src/viam/sdk/common/client_helper.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <grpcpp/client_context.h>
+#include <viam/sdk/common/exception.hpp>
 #include <viam/sdk/common/proto_type.hpp>
 #include <viam/sdk/common/utils.hpp>
 
@@ -16,7 +17,7 @@ class ClientHelper {
     static void default_rsc_(RequestType&) {}
     static void default_rhc_(const ResponseType&) {}
     static void default_ehc_(const ::grpc::Status& status) {
-        throw std::runtime_error(status.error_message());
+        throw GRPCException(status);
     }
 
    public:

src/viam/sdk/common/exception.cpp

@@ -0,0 +1,56 @@
+#include <viam/sdk/common/exception.hpp>
+
+namespace viam {
+namespace sdk {
+
+Exception::Exception(ErrorCondition condition, const std::string& what)
+    : std::runtime_error("viam::sdk::Exception: " + what), condition_(condition){};
+
+Exception::Exception(const std::string& what) : Exception(ErrorCondition::k_general, what){};
+
+Exception::~Exception() = default;
+
+const std::error_condition& Exception::condition() const noexcept {
+    return condition_;
+};
+
+std::error_condition make_error_condition(ErrorCondition e) {
+    struct ErrorCategory : std::error_category {
+        const char* name() const noexcept override {
+            return "viam::sdk";
+        };
+        std::string message(int ev) const override {
+            switch (static_cast<ErrorCondition>(ev)) {
+                case ErrorCondition::k_general:
+                    return "general";
+                case ErrorCondition::k_connection:
+                    return "connection establishment failure";
+                case ErrorCondition::k_duplicate_registration:
+                    return "duplicate registration";
+                case ErrorCondition::k_duplicate_resource:
+                    return "duplicate resource";
+                case ErrorCondition::k_grpc:
+                    return "gRPC";
+                case ErrorCondition::k_not_supported:
+                    return "not supported";
+                case ErrorCondition::k_resource_not_found:
+                    return "resource not found";
+                default:
+                    return "unknown";
+            }
+        };
+    };
+
+    static const ErrorCategory errorCategory{};
+    return {static_cast<int>(e), errorCategory};
+}
+
+GRPCException::GRPCException(grpc::Status status)
+    : Exception(ErrorCondition::k_grpc, status.error_message()), status_(std::move(status)){};
+
+const grpc::Status& GRPCException::status() const noexcept {
+    return status_;
+}
+
+}  // namespace sdk
+}  // namespace viam

src/viam/sdk/common/exception.hpp

@@ -0,0 +1,66 @@
+/// @file common/exception.hpp
+///
+/// @brief Defines custom exceptions for the SDK.
+#pragma once
+#include <grpcpp/support/status.h>
+#include <stdexcept>
+#include <string>
+
+#include <viam/sdk/resource/resource_api.hpp>
+
+namespace viam {
+namespace sdk {
+
+/// @defgroup Exception Classes related to SDK exceptions.
+
+/// @class ErrorCondition
+/// @brief Defines a set of a error conditions to be used in conjunction with
+/// Exception.
+/// @ingroup Exception
+enum class ErrorCondition : uint8_t {
+    k_general = 0,                 // Default condition
+    k_connection = 1,              // Issue during connection establishment
+    k_duplicate_registration = 2,  // API or API/Model pair has already been registered
+    k_duplicate_resource = 3,      // Resource has already been added
+    k_grpc = 4,                    // gRPC error from remote machine
+    k_not_supported = 5,           // Behavior not supported by the SDK
+    k_resource_not_found = 6       // Resource does not exist
+};
+
+std::error_condition make_error_condition(ErrorCondition e);
+
+/// @class Exception
+/// @brief Defines an exception type for the SDK.
+/// @ingroup Exception
+class Exception : public std::runtime_error {
+   public:
+    explicit Exception(ErrorCondition condition, const std::string& what);
+    explicit Exception(const std::string& what);
+    virtual ~Exception();
+
+    const std::error_condition& condition() const noexcept;
+
+   private:
+    std::error_condition condition_;
+};
+
+/// @class GRPCException
+/// @brief Defines an exception from a gRPC interaction.
+/// @ingroup Exception
+class GRPCException : public Exception {
+   public:
+    explicit GRPCException(grpc::Status status);
+
+    const grpc::Status& status() const noexcept;
+
+   private:
+    grpc::Status status_;
+};
+
+}  // namespace sdk
+}  // namespace viam
+
+namespace std {
+template <>
+struct is_error_condition_enum<viam::sdk::ErrorCondition> : true_type {};
+}  // namespace std

src/viam/sdk/common/proto_type.cpp

@@ -10,6 +10,7 @@
 #include <boost/variant/variant.hpp>
 #include <google/protobuf/struct.pb.h>
 
+#include <viam/sdk/common/exception.hpp>
 #include <viam/sdk/config/resource.hpp>
 
 namespace viam {
@@ -131,7 +132,7 @@ Value ProtoType::proto_value() {
             break;
         }
         default: {
-            throw std::runtime_error(
+            throw Exception(
                 "Invalid proto_value conversion type. This should never happen;\
 						please file a bug report.");
         }
@@ -194,8 +195,9 @@ bool operator==(const ProtoType& lhs, const ProtoType& rhs) {
             return std::equal(lhs_vec.begin(), lhs_vec.end(), rhs_vec.begin(), rhs_vec.end(), pred);
         }
         default: {
-            throw "Invalid proto_value conversion type. This should never happen;\
-                   please file a bug report.";
+            throw Exception(
+                "Invalid proto_value conversion type. This should never happen;\
+                   please file a bug report.");
         }
     }
 }

src/viam/sdk/components/board/board.cpp

@@ -5,6 +5,7 @@
 #include <viam/api/component/board/v1/board.grpc.pb.h>
 #include <viam/api/component/board/v1/board.pb.h>
 
+#include <viam/sdk/common/exception.hpp>
 #include <viam/sdk/common/utils.hpp>
 #include <viam/sdk/resource/resource.hpp>
 
@@ -48,7 +49,8 @@ Board::power_mode Board::from_proto(viam::component::board::v1::PowerMode proto)
         }
         case viam::component::board::v1::POWER_MODE_UNSPECIFIED:
         default: {
-            throw std::runtime_error("Invalid proto board power_mode to decode");
+            throw Exception(ErrorCondition::k_not_supported,
+                            "Invalid proto board power_mode to decode");
         }
     }
 }
@@ -86,7 +88,7 @@ viam::component::board::v1::PowerMode Board::to_proto(Board::power_mode power_mo
             return viam::component::board::v1::POWER_MODE_OFFLINE_DEEP;
         }
         default: {
-            throw std::runtime_error("Invalid board power_mode to encode");
+            throw Exception(ErrorCondition::k_not_supported, "Invalid board power_mode to encode");
         }
     }
 }

src/viam/sdk/components/board/client.cpp

@@ -10,6 +10,7 @@
 #include <viam/api/component/board/v1/board.grpc.pb.h>
 
 #include <viam/sdk/common/client_helper.hpp>
+#include <viam/sdk/common/exception.hpp>
 #include <viam/sdk/common/utils.hpp>
 #include <viam/sdk/components/board/board.hpp>
 #include <viam/sdk/config/resource.hpp>
@@ -101,7 +102,7 @@ Board::analog_value BoardClient::read_analog(const std::string& analog_reader_na
 
     const grpc::Status status = stub_->ReadAnalogReader(ctx, request, &response);
     if (!status.ok()) {
-        throw std::runtime_error(status.error_message());
+        throw GRPCException(status);
     }
     return response.value();
 }
@@ -130,7 +131,7 @@ Board::digital_value BoardClient::read_digital_interrupt(const std::string& digi
 
     const grpc::Status status = stub_->GetDigitalInterruptValue(ctx, request, &response);
     if (!status.ok()) {
-        throw std::runtime_error(status.error_message());
+        throw GRPCException(status);
     }
     return response.value();
 }

src/viam/sdk/components/encoder/encoder.cpp

@@ -5,6 +5,7 @@
 #include <viam/api/component/encoder/v1/encoder.grpc.pb.h>
 #include <viam/api/component/encoder/v1/encoder.pb.h>
 
+#include <viam/sdk/common/exception.hpp>
 #include <viam/sdk/common/utils.hpp>
 #include <viam/sdk/resource/resource.hpp>
 
@@ -31,7 +32,8 @@ Encoder::position_type Encoder::from_proto(viam::component::encoder::v1::Positio
             return Encoder::position_type::ticks_count;
         }
         default: {
-            throw std::runtime_error("Invalid proto encoder type to decode");
+            throw Exception(ErrorCondition::k_not_supported,
+                            "Invalid proto encoder type to decode");
         }
     }
 }
@@ -64,7 +66,8 @@ viam::component::encoder::v1::PositionType Encoder::to_proto(position_type posit
             return viam::component::encoder::v1::POSITION_TYPE_TICKS_COUNT;
         }
         default: {
-            throw std::runtime_error("Invalid proto encoder type to encode");
+            throw Exception(ErrorCondition::k_not_supported,
+                            "Invalid proto encoder type to encode");
         }
     }
 }

src/viam/sdk/components/motor/motor.hpp

@@ -83,7 +83,7 @@ class Motor : public Component, public Stoppable {
     /// `revolutions` == 0, this will run the motor at `rpm` indefinetely. If `revolutions` != 0,
     /// this will block until the number of revolutions has been completed or another operation
     /// comes in.
-    /// @throws runtime_error if position reporting is not supported
+    /// @throws `Exception` if position reporting is not supported
     inline void go_for(double rpm, double revolutions) {
         return go_for(rpm, revolutions, {});
     }
@@ -96,14 +96,14 @@ class Motor : public Component, public Stoppable {
     /// this will block until the number of revolutions has been completed or another operation
     /// comes in.
     /// @param extra Any additional arguments to the method.
-    /// @throws runtime_error if position reporting is not supported
+    /// @throws `Exception` if position reporting is not supported
     virtual void go_for(double rpm, double revolutions, const AttributeMap& extra) = 0;
 
     /// @brief Move the motor to a specific position that is relative to its
     /// home position at a specified speed which is expressed in RPM.
     /// @param rpm Speed of motor travel in rotations per minute
     /// @param position_revolutions Number of revolutions relative to motor's home home/zero
-    /// @throws runtime_error if position reporting is not supported
+    /// @throws `Exception` if position reporting is not supported
     inline void go_to(double rpm, double position_revolutions) {
         return go_to(rpm, position_revolutions, {});
     }
@@ -113,31 +113,31 @@ class Motor : public Component, public Stoppable {
     /// @param rpm Speed of motor travel in rotations per minute
     /// @param position_revolutions Number of revolutions relative to motor's home home/zero
     /// @param extra Any additional arguments to the method.
-    /// @throws runtime_error if position reporting is not supported
+    /// @throws `Exception` if position reporting is not supported
     virtual void go_to(double rpm, double position_revolutions, const AttributeMap& extra) = 0;
 
     /// @brief Sets the current position of the motor as the new zero position.
     /// @param offset Motor position
-    /// @throws runtime_error if position reporting is not supported
+    /// @throws `Exception` if position reporting is not supported
     inline void reset_zero_position(double offset) {
         return reset_zero_position(offset, {});
     }
 
     /// @brief Sets the current position of the motor as the new zero position.
     /// @param offset Motor position
     /// @param extra Any additional arguments to the method
-    /// @throws runtime_error if position reporting is not supported
+    /// @throws `Exception` if position reporting is not supported
     virtual void reset_zero_position(double offset, const AttributeMap& extra) = 0;
 
     /// @brief Reports the position of the robot's motor relative to its zero position.
-    /// @throws runtime_error if position reporting is not supported
+    /// @throws `Exception` if position reporting is not supported
     inline position get_position() {
         return get_position({});
     }
 
     /// @brief Reports the position of the robot's motor relative to its zero position.
     /// @param extra Any additional arguments to the method
-    /// @throws runtime_error if position reporting is not supported
+    /// @throws `Exception` if position reporting is not supported
     virtual position get_position(const AttributeMap& extra) = 0;
 
     /// @brief Returns the properties of the motor which comprises the booleans indicating

src/viam/sdk/components/servo/servo.hpp

@@ -43,14 +43,14 @@ class Servo : public Component, public Stoppable {
     virtual void move(uint32_t angle_deg, const AttributeMap& extra) = 0;
 
     /// @brief Get the current angle (degrees) of the servo.
-    /// @throws runtime_error if position reporting is not supported
+    /// @throws `Exception` if position reporting is not supported
     inline position get_position() {
         return get_position({});
     }
 
     /// @brief Reports the position of the robot's servo relative to its zero position.
     /// @param extra Any additional arguments to the method
-    /// @throws runtime_error if position reporting is not supported
+    /// @throws `Exception` if position reporting is not supported
     virtual position get_position(const AttributeMap& extra) = 0;
 
     /// @brief Stops a resource from running.

src/viam/sdk/config/resource.cpp

@@ -9,6 +9,7 @@
 #include <viam/api/app/v1/robot.pb.h>
 #include <viam/api/robot/v1/robot.pb.h>
 
+#include <viam/sdk/common/exception.hpp>
 #include <viam/sdk/common/proto_type.hpp>
 #include <viam/sdk/common/utils.hpp>
 #include <viam/sdk/referenceframe/frame.hpp>
@@ -84,8 +85,7 @@ void ResourceConfig::fix_api() {
     // config structs
     if (this->api_.type_namespace() != this->namespace__ ||
         this->api_.resource_subtype() != this->type_) {
-        throw std::runtime_error(
-            "component namespace and/or type do not match component api field");
+        throw Exception("component namespace and/or type do not match component api field");
     }
 }
 

src/viam/sdk/module/service.cpp

@@ -27,6 +27,7 @@
 #include <viam/api/module/v1/module.grpc.pb.h>
 #include <viam/api/module/v1/module.pb.h>
 
+#include <viam/sdk/common/exception.hpp>
 #include <viam/sdk/common/utils.hpp>
 #include <viam/sdk/components/component.hpp>
 #include <viam/sdk/config/resource.hpp>
@@ -54,7 +55,7 @@ Dependencies ModuleService::get_dependencies_(
             std::ostringstream buffer;
             buffer << resource_name << ": Dependency "
                    << "`" << dep_name << "` was not found during (re)configuration";
-            throw std::invalid_argument(buffer.str());
+            throw Exception(ErrorCondition::k_resource_not_found, buffer.str());
         }
         deps.emplace(dep_name, dep_resource);
     }
@@ -217,7 +218,7 @@ ModuleService::ModuleService(int argc,
                              char** argv,
                              std::vector<std::shared_ptr<ModelRegistration>> registrations) {
     if (argc < 2) {
-        throw std::runtime_error("Need socket path as command line argument");
+        throw Exception("Need socket path as command line argument");
     }
     module_ = std::make_unique<Module>(argv[1]);
     server_ = std::make_unique<Server>();

src/viam/sdk/module/signal_manager.hpp

@@ -16,7 +16,7 @@ class SignalManager {
 
     /// @brief Wait for SignalManager to receive SIGINT or SIGTERM.
     /// @return The signal number if successful.
-    /// @throws runtime_error if the underlying sigwait call was unsuccessful.
+    /// @throws `std::runtime_error` if the underlying sigwait call was unsuccessful.
     int wait();
 
    private: