Optionally abort startup when unknown configuration parameters were detected

docs/Migrating-Configuration.md

@@ -0,0 +1,27 @@
+While OTP's GraphQL APIs are very, very stable even across versions, the JSON configuration schema
+is not. Changes to it are relatively frequent and you can see all PRs that change it with
+the [Github tag 'config change'](https://github.com/opentripplanner/OpenTripPlanner/pulls?q=label%3A%22config+change%22).
+
+### Migrating the JSON configuration
+
+OTP validates the configuration and prints warnings during startup. This means that when you
+migrate to a newer version, you should carefully inspect the logs. If you see messages like
+
+```
+(NodeAdapter.java:170) Unexpected config parameter: 'routingDefaults.stairsReluctance:1.65' in 'router-config.json'
+```
+
+this means there are properties in your configuration that are unknown to OTP and therefore likely
+to be a configuration error, perhaps because the schema was changed. In such a case you should
+consult the [feature](Configuration.md#otp-features), [router](RouterConfiguration.md) or 
+[build configuration documentation](BuildConfiguration.md) to find out what the new schema looks like.
+
+### Aborting on invalid configuration
+
+If you want OTP to abort the startup when encountering invalid configuration, you can add the flag
+`--configCheck` to your regular OTP CLI commands.
+
+This should of course be used wisely as it can also accidentally make your production instances refuse 
+to start up.
+Therefore, we recommend that you use it only in a separate pre-production step, perhaps during graph
+build.

mkdocs.yml

@@ -75,6 +75,7 @@ nav:
     - Router: 'RouterConfiguration.md'
     - "Route Request": 'RouteRequest.md'
     - "Realtime Updaters": 'UpdaterConfig.md'
+    - "Migrating Configuration": 'Migrating-Configuration.md'
 - Features explained:
     - "Routing modes": 'RoutingModes.md'
     - "In-station navigation": 'In-Station-Navigation.md'

src/main/java/org/opentripplanner/standalone/OTPMain.java

@@ -113,6 +113,14 @@ private static void startOTPServer(CommandLineParameters cli) {
     var loadApp = new LoadApplication(cli);
     var config = loadApp.config();
 
+    // optionally check if the config is valid and if not abort the startup process
+    if (cli.configCheck && config.hasInvalidProperties()) {
+      throw new OtpAppException(
+        "Configuration contains invalid properties (see above for details). " +
+        "Please fix your configuration or remove --configCheck from your OTP CLI parameters."
+      );
+    }
+
     // Validate data sources, command line arguments and config before loading and
     // processing input data to fail early
     loadApp.validateConfigAndDataSources();

src/main/java/org/opentripplanner/standalone/config/BuildConfig.java

@@ -719,4 +719,11 @@ public int getSubwayAccessTimeSeconds() {
   public NodeAdapter asNodeAdapter() {
     return root;
   }
+
+  /**
+   * Checks if any unknown or invalid properties were encountered while loading the configuration.
+   */
+  public boolean hasInvalidProperties() {
+    return root.hasInvalidProperties();
+  }
 }

src/main/java/org/opentripplanner/standalone/config/CommandLineParameters.java

@@ -133,6 +133,12 @@ public class CommandLineParameters {
   )
   public boolean visualize;
 
+  @Parameter(
+    names = { "--configCheck" },
+    description = "Abort the startup if configuration files are found to be invalid."
+  )
+  public boolean configCheck = false;
+
   /**
    * The remaining single parameter after the switches is the directory with the configuration
    * files. This directory may contain other files like the graph, input data and report files.

src/main/java/org/opentripplanner/standalone/config/ConfigModel.java

@@ -105,4 +105,15 @@ public static void initializeOtpFeatures(OtpConfig otpConfig) {
     OTPFeature.enableFeatures(otpConfig.otpFeatures);
     OTPFeature.logFeatureSetup();
   }
+
+  /**
+   * Checks if any unknown or invalid properties were encountered while loading the configuration.
+   */
+  public boolean hasInvalidProperties() {
+    return (
+      otpConfig.hasInvalidProperties() ||
+      buildConfig.hasInvalidProperties() ||
+      routerConfig.hasInvalidProperties()
+    );
+  }
 }

src/main/java/org/opentripplanner/standalone/config/OtpConfig.java

@@ -71,4 +71,11 @@ public OtpConfig(NodeAdapter nodeAdapter, boolean logUnusedParams) {
       root.logAllWarnings(LOG::warn);
     }
   }
+
+  /**
+   * Checks if any unknown or invalid properties were encountered while loading the configuration.
+   */
+  public boolean hasInvalidProperties() {
+    return root.hasInvalidProperties();
+  }
 }

src/main/java/org/opentripplanner/standalone/config/RouterConfig.java

@@ -150,4 +150,11 @@ public String toString() {
     // Print ONLY the values set, not default values
     return root.toPrettyString();
   }
+
+  /**
+   * Checks if any unknown or invalid properties were encountered while loading the configuration.
+   */
+  public boolean hasInvalidProperties() {
+    return root.hasInvalidProperties();
+  }
 }

src/main/java/org/opentripplanner/standalone/config/framework/json/NodeAdapter.java

@@ -172,6 +172,13 @@ public void logAllWarnings(Consumer<String> logger) {
     allWarnings().forEach(logger);
   }
 
+  /**
+   * Checks if any unknown or invalid properties were encountered while loading the configuration.
+   */
+  public boolean hasInvalidProperties() {
+    return !unusedParams().isEmpty() || !allWarnings().toList().isEmpty();
+  }
+
   /**
    * Be careful when using this method - this bypasses the NodeAdaptor, and we loose
    * track of unused parameters and cannot generate documentation for the children.

src/main/java/org/opentripplanner/standalone/config/framework/json/ParameterBuilder.java

@@ -120,10 +120,6 @@ public Boolean asBoolean(boolean defaultValue) {
     return ofOptional(BOOLEAN, defaultValue, JsonNode::asBoolean);
   }
 
-  public Map<String, Boolean> asBooleanMap() {
-    return ofOptionalMap(BOOLEAN, JsonNode::asBoolean);
-  }
-
   /** @throws OtpAppException if parameter is missing. */
   public double asDouble() {
     return ofRequired(DOUBLE).asDouble();