engine: Provide better error messages for missing plugins

This resolves #82.

Author: cassava

engine/src/stack.cpp

@@ -34,6 +34,7 @@
 namespace fs = boost::filesystem;
 
 #include <cloe/utility/std_extensions.hpp>  // for join_vector
+#include <fable/utility.hpp> // for indent_string
 
 namespace cloe {
 
@@ -459,7 +460,8 @@ void Stack::from_conf(const Conf& _conf, size_t depth) {
       //
       // But that would result in a very verbose error message, so we shall
       // throw a more user-friendly error message instead.
-      throw Error{"require version compatible with {}, got {}", CLOE_STACK_VERSION, ver}.explanation(R"(
+      throw Error{"require version compatible with {}, got {}", CLOE_STACK_VERSION, ver}
+          .explanation(R"(
             It looks like you are attempting to load a stack file with an
             incompatible version.
 
@@ -534,14 +536,14 @@ void Stack::from_conf(const Conf& _conf, size_t depth) {
               If you feel that you need more than the default allowed recursion
               depth (64), you are free to increase the limit within the stack file:
 
-                {{
-                  "engine": {{
-                    "security": {{
+                {
+                  "version": "4",
+                  "engine": {
+                    "security": {
                       "max_include_depth": 1024
-                    }}
-                  }},
-                  ...
-                }}
+                    }
+                  }
+                }
 
               This should be done sparingly. If you have such an inclusion depth,
               chances are the structure of the stack files is sub-optimal.
@@ -619,7 +621,7 @@ void Stack::validate_or_throw(const Conf& c) const {
   copy.validate_self();
 }
 
-bool Stack::validate(const Conf &c, std::optional<SchemaError> &err) const {
+bool Stack::validate(const Conf& c, std::optional<SchemaError>& err) const {
   Stack copy(*this);
   try {
     copy.from_conf(c);
@@ -740,4 +742,80 @@ void Stack::check_completeness() const {
   }
 }
 
+[[noreturn]] void throw_missing_plugin_error(Conf conf,
+                                             std::string_view plugin_type,
+                                             std::string_view plugin_name,
+                                             const std::vector<std::string>& available_plugins) {
+  throw Error{"unknown {} plugin: {}", plugin_type, plugin_name}.explanation(
+      R"(
+              Error located in JSON segment at {}:
+
+{}
+
+              The plugin referred to by the "binding" field is not available.
+              The following {} plugins are available:
+
+                  {}
+
+              If the plugin you are looking for is not in that list, then you need
+              to get cloe-engine to load the plugin first.
+              There are several mechanisms for loading plugins:
+
+              1. Add directory to CLOE_PLUGIN_PATH environment variable:
+
+                 export CLOE_PLUGIN_PATH="$CLOE_PLUGIN_PATH:/path/to/dir/containing/plugin"
+
+              2. Add directory containing plugin from the command-line:
+
+                 cloe-engine --plugin-path=/path/to/dir/containing/plugin run config.json
+
+              3. Specify path to plugin in a stackfile directly:
+
+                 {{
+                   "version": "4",
+                   "plugins": [
+                     {{
+                       "path": "/path/to/dir/containing/plugin"
+                     }},
+                     {{
+                       "path": "/path/to/plugin.so"
+                     }}
+                   ]
+                 }}
+
+              )",
+      conf.root(), fable::indent_string(conf->dump(2), "                  "), plugin_type,
+      fable::join_vector(available_plugins, "\n                  "));
+}
+
+bool SimulatorSchema::validate(const Conf& c, std::optional<SchemaError>& err) const {
+  assert(schema_ != nullptr);
+  auto factory = c.get<std::string>(factory_key_);
+  if (available_.count(factory) == 0) {
+    // Override error message.
+    throw_missing_plugin_error(c, "simulator", factory, get_factory_keys());
+  }
+  return schema_->validate(c, err);
+}
+
+bool ControllerSchema::validate(const Conf& c, std::optional<SchemaError>& err) const {
+  assert(schema_ != nullptr);
+  auto factory = c.get<std::string>(factory_key_);
+  if (available_.count(factory) == 0) {
+    // Override error message.
+    throw_missing_plugin_error(c, "controller", factory, get_factory_keys());
+  }
+  return schema_->validate(c, err);
+}
+
+bool ComponentSchema::validate(const Conf& c, std::optional<SchemaError>& err) const {
+  assert(schema_ != nullptr);
+  auto factory = c.get<std::string>(factory_key_);
+  if (available_.count(factory) == 0) {
+    // Override error message.
+    throw_missing_plugin_error(c, "component", factory, get_factory_keys());
+  }
+  return schema_->validate(c, err);
+}
+
 }  // namespace cloe

engine/src/stack.hpp

@@ -536,6 +536,8 @@ class SimulatorSchema : public FactoryPlugin<SimulatorConf, SimulatorFactory> {
  public:
   SimulatorSchema();
   virtual ~SimulatorSchema() = default;
+
+  bool validate(const Conf& c, std::optional<SchemaError>& err) const override;
 };
 
 // --------------------------------------------------------------------------------------------- //
@@ -572,6 +574,8 @@ class ControllerSchema : public FactoryPlugin<ControllerConf, ControllerFactory>
  public:
   ControllerSchema();
   virtual ~ControllerSchema() = default;
+
+  bool validate(const Conf& c, std::optional<SchemaError>& err) const override;
 };
 
 // --------------------------------------------------------------------------------------------- //
@@ -664,6 +668,8 @@ class ComponentSchema : public FactoryPlugin<ComponentConf, ComponentFactory> {
  public:
   ComponentSchema();
   virtual ~ComponentSchema() = default;
+
+  bool validate(const Conf& c, std::optional<SchemaError>& err) const override;
 };
 
 // TODO(ben): Add AliasConf as alternative to ComponentConf.

engine/tests/test_engine.bats

@@ -157,6 +157,11 @@ check_engine_with_server() {
     cloe-engine run test_engine_ignore.json
 }
 
+@test "$(testname 'Expect check failure' 'test_engine_unavailable_*.json' '6cf4ded3-8a57-4dee-afac-bb03a8068e41')" {
+    run cloe-engine -l info check -d test_engine_unavailable_*.json
+    test $status -eq $CLOE_EXIT_UNKNOWN
+}
+
 @test "$(testname 'Expect check failure' 'test_engine_include_nonexistent.json' 'bad115cc-0397-48e6-9a51-bdcfeaf6b024')" {
     run cloe-engine check test_engine_include_nonexistent.json
     assert_check_failure $status $output

engine/tests/test_engine_unavailable_component.json

@@ -0,0 +1,35 @@
+// This test checks that cloe-engine will find the error that the component
+// binding does not exist.
+//
+// The stack file is complete except for the incorrect "component" binding.
+{
+  "version": "4",
+  "server": {
+    "listen_port": 23456
+  },
+  "vehicles": [
+    {
+      "from": {
+        "simulator": "nop",
+        "index": 0
+      },
+      "name": "default",
+      "components": {
+        "test_failure": {
+          "binding": "misspelled"
+        }
+    }
+    }
+  ],
+  "simulators": [
+    {
+      "binding": "nop"
+    }
+  ],
+  "controllers": [
+    {
+      "binding": "basic",
+      "vehicle": "default"
+    }
+  ]
+}

engine/tests/test_engine_unavailable_controller.json

@@ -0,0 +1,30 @@
+// This test checks that cloe-engine will find the error that the controller
+// binding does not exist.
+//
+// The stack file is complete except for the incorrect "controller" binding.
+{
+  "version": "4",
+  "server": {
+    "listen_port": 23456
+  },
+  "vehicles": [
+    {
+      "from": {
+        "simulator": "nop",
+        "index": 0
+      },
+      "name": "default"
+    }
+  ],
+  "simulators": [
+    {
+      "binding": "nop"
+    }
+  ],
+  "controllers": [
+    {
+      "binding": "misspelled",
+      "vehicle": "default"
+    }
+  ]
+}

engine/tests/test_engine_unavailable_simulator.json

@@ -0,0 +1,30 @@
+// This test checks that cloe-engine will find the error that the simulator
+// binding does not exist.
+//
+// The stack file is complete except for the incorrect "simulator" binding.
+{
+  "version": "4",
+  "server": {
+    "listen_port": 23456
+  },
+  "vehicles": [
+    {
+      "from": {
+        "simulator": "nop",
+        "index": 0
+      },
+      "name": "default"
+    }
+  ],
+  "simulators": [
+    {
+      "binding": "unknown"
+    }
+  ],
+  "controllers": [
+    {
+      "binding": "basic",
+      "vehicle": "default"
+    }
+  ]
+}