fix: make supergraph.{path,key,endpoint} optional (#593)

This commit adds validation to ensure that the supergraph file path,
Hive CDN endpoint, and key are provided either through environment
variables or the configuration file. It also updates the documentation
and configuration structs to reflect that the path and endpoint/key are
now optional.

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: kamilkisiela

.changeset/make_supergraphpathkeyendpoint_optional.md

@@ -0,0 +1,11 @@
+---
+router: patch
+config: patch
+---
+
+# Improve error messages and fix environment variable support for supergraph configuration
+
+- **Fix:** Previously, `supergraph.path` (for file source), and `supergraph.endpoint`/`supergraph.key` (for Hive CDN source) were mandatory in the configuration file. This prevented users from relying solely on environment variables (`SUPERGRAPH_FILE_PATH`, `HIVE_CDN_ENDPOINT`, `HIVE_CDN_KEY`). This has been fixed, and these fields are now optional in the configuration file if the corresponding environment variables are provided.
+- **Improved Error Reporting:** If the supergraph file path or Hive CDN endpoint/key are missing from both configuration and environment variables, the error message now explicitly guides you to set the required environment variable or the corresponding configuration option.
+
+This change ensures that misconfigurations are easier to diagnose and fix during startup.

bin/router/src/supergraph/base.rs

@@ -15,6 +15,12 @@ pub enum LoadSupergraphError {
     InitializationError(String),
     #[error("Invalid configuration: {0}")]
     InvalidConfiguration(String),
+    #[error("Supergraph file path is missing. Please provide it via 'SUPERGRAPH_FILE_PATH' environment variable or under 'supergraph.path' in the configuration.")]
+    MissingSupergraphFilePath,
+    #[error("Hive CDN endpoint is missing. Please provide it via 'HIVE_CDN_ENDPOINT' environment variable or under 'supergraph.endpoint' in the configuration.")]
+    MissingHiveCDNEndpoint,
+    #[error("Hive CDN key is missing. Please provide it via 'HIVE_CDN_KEY' environment variable or under 'supergraph.key' in the configuration.")]
+    MissingHiveCDNKey,
 }
 
 #[derive(Debug)]

bin/router/src/supergraph/mod.rs

@@ -23,7 +23,12 @@ pub fn resolve_from_config(
         SupergraphSource::File {
             path,
             poll_interval,
-        } => Ok(SupergraphFileLoader::new(path, *poll_interval)?),
+        } => {
+            let path = path
+                .as_ref()
+                .ok_or(LoadSupergraphError::MissingSupergraphFilePath)?;
+            Ok(SupergraphFileLoader::new(path, *poll_interval)?)
+        }
         SupergraphSource::HiveConsole {
             endpoint,
             key,
@@ -32,14 +37,21 @@ pub fn resolve_from_config(
             accept_invalid_certs,
             retry_policy,
             poll_interval,
-        } => Ok(SupergraphHiveConsoleLoader::try_new(
-            endpoint.clone(),
-            key,
-            *poll_interval,
-            *connect_timeout,
-            *request_timeout,
-            *accept_invalid_certs,
-            retry_policy.max_retries,
-        )?),
+        } => {
+            let endpoint = endpoint
+                .as_ref()
+                .ok_or(LoadSupergraphError::MissingHiveCDNEndpoint)?;
+            let key = key.as_ref().ok_or(LoadSupergraphError::MissingHiveCDNKey)?;
+
+            Ok(SupergraphHiveConsoleLoader::try_new(
+                endpoint.clone(),
+                key,
+                *poll_interval,
+                *connect_timeout,
+                *request_timeout,
+                *accept_invalid_certs,
+                retry_policy.max_retries,
+            )?)
+        }
     }
 }

docs/README.md

@@ -1760,7 +1760,7 @@ The path can be either absolute or relative to the router's working directory.
 
 |Name|Type|Description|Required|
 |----|----|-----------|--------|
-|**path**|`string`|The path to the supergraph file.<br/><br/>Can also be set using the `SUPERGRAPH_FILE_PATH` environment variable.<br/>Format: `"path"`<br/>|yes|
+|**path**|`string`, `null`|The path to the supergraph file.<br/><br/>Can also be set using the `SUPERGRAPH_FILE_PATH` environment variable.<br/>Format: `"path"`<br/>|no|
 |**poll\_interval**|`string`|Optional interval at which the file should be polled for changes.<br/>If not provided, the file will only be loaded once when the router starts.<br/>|no|
 |**source**|`string`|Constant Value: `"file"`<br/>|yes|
 
@@ -1784,8 +1784,8 @@ Loads a supergraph from Hive Console CDN.
 |----|----|-----------|--------|
 |**accept\_invalid\_certs**|`boolean`|Whether to accept invalid TLS certificates when connecting to the Hive Console CDN.<br/>Default: `false`<br/>|no|
 |**connect\_timeout**|`string`|Connect timeout for the Hive Console CDN requests.<br/>Default: `"10s"`<br/>|no|
-|**endpoint**|`string`|The CDN endpoint from Hive Console target.<br/><br/>Can also be set using the `HIVE_CDN_ENDPOINT` environment variable.<br/>|yes|
-|**key**|`string`|The CDN Access Token with from the Hive Console target.<br/><br/>Can also be set using the `HIVE_CDN_KEY` environment variable.<br/>|yes|
+|**endpoint**|`string`, `null`|The CDN endpoint from Hive Console target.<br/><br/>Can also be set using the `HIVE_CDN_ENDPOINT` environment variable.<br/>|no|
+|**key**|`string`, `null`|The CDN Access Token with from the Hive Console target.<br/><br/>Can also be set using the `HIVE_CDN_KEY` environment variable.<br/>|no|
 |**poll\_interval**|`string`|Interval at which the Hive Console should be polled for changes.<br/><br/>Can also be set using the `HIVE_CDN_POLL_INTERVAL` environment variable.<br/>Default: `"10s"`<br/>|no|
 |**request\_timeout**|`string`|Request timeout for the Hive Console CDN requests.<br/>Default: `"1m"`<br/>|no|
 |[**retry\_policy**](#option2retry_policy)|`object`|Interval at which the Hive Console should be polled for changes.<br/>Default: `{"max_retries":10}`<br/>|yes|

lib/router-config/src/supergraph.rs

@@ -15,7 +15,7 @@ pub enum SupergraphSource {
         /// The path to the supergraph file.
         ///
         /// Can also be set using the `SUPERGRAPH_FILE_PATH` environment variable.
-        path: FilePath,
+        path: Option<FilePath>,
         /// Optional interval at which the file should be polled for changes.
         /// If not provided, the file will only be loaded once when the router starts.
         #[serde(
@@ -32,11 +32,11 @@ pub enum SupergraphSource {
         /// The CDN endpoint from Hive Console target.
         ///
         /// Can also be set using the `HIVE_CDN_ENDPOINT` environment variable.
-        endpoint: String,
+        endpoint: Option<String>,
         /// The CDN Access Token with from the Hive Console target.
         ///
         /// Can also be set using the `HIVE_CDN_KEY` environment variable.
-        key: String,
+        key: Option<String>,
         /// Interval at which the Hive Console should be polled for changes.
         ///
         /// Can also be set using the `HIVE_CDN_POLL_INTERVAL` environment variable.
@@ -110,8 +110,7 @@ fn default_file_poll_interval() -> Option<Duration> {
 impl Default for SupergraphSource {
     fn default() -> Self {
         SupergraphSource::File {
-            path: FilePath::new_from_relative("supergraph.graphql")
-                .expect("failed to resolve local path for supergraph file source"),
+            path: FilePath::new_from_relative("supergraph.graphql").ok(),
             poll_interval: default_file_poll_interval(),
         }
     }