Fix: Usage reporting access token handling

- Changed the `access_token` field in the `UsageReportingConfig` to
`Option<String>`. - Updated the documentation to reflect the change. -
Added error handling for missing access tokens.

Author: kamilkisiela

bin/router/src/pipeline/usage_reporting.rs

@@ -19,13 +19,26 @@ use crate::{
     consts::ROUTER_VERSION,
 };
 
+#[derive(Debug, thiserror::Error)]
+pub enum UsageReportingError {
+    #[error("Usage Reporting - Access token is missing. Please provide it via 'HIVE_ACCESS_TOKEN' environment variable or under 'usage_reporting.access_token' in the configuration.")]
+    MissingAccessToken,
+    #[error("Usage Reporting - Failed to initialize usage agent: {0}")]
+    AgentCreationError(#[from] AgentError),
+}
+
 pub fn init_hive_user_agent(
     bg_tasks_manager: &mut BackgroundTasksManager,
     usage_config: &UsageReportingConfig,
-) -> Result<Arc<UsageAgent>, AgentError> {
+) -> Result<Arc<UsageAgent>, UsageReportingError> {
     let user_agent = format!("hive-router/{}", ROUTER_VERSION);
+    let access_token = usage_config
+        .access_token
+        .as_deref()
+        .ok_or(UsageReportingError::MissingAccessToken)?;
+
     let hive_user_agent = UsageAgent::try_new(
-        &usage_config.access_token,
+        access_token,
         usage_config.endpoint.clone(),
         usage_config.target_id.clone(),
         usage_config.buffer_size,

docs/README.md

@@ -16,7 +16,7 @@
 |[**query\_planner**](#query_planner)|`object`|Query planning configuration.<br/>Default: `{"allow_expose":false,"timeout":"10s"}`<br/>||
 |[**supergraph**](#supergraph)|`object`|Configuration for the Federation supergraph source. By default, the router will use a local file-based supergraph source (`./supergraph.graphql`).<br/>||
 |[**traffic\_shaping**](#traffic_shaping)|`object`|Configuration for the traffic-shaper executor. Use these configurations to control how requests are being executed to subgraphs.<br/>Default: `{"dedupe_enabled":true,"max_connections_per_host":100,"pool_idle_timeout_seconds":50}`<br/>||
-|[**usage\_reporting**](#usage_reporting)|`object`|Configuration for usage reporting to GraphQL Hive.<br/>Default: `{"accept_invalid_certs":false,"access_token":"","buffer_size":1000,"client_name_header":"graphql-client-name","client_version_header":"graphql-client-version","connect_timeout":"5s","enabled":false,"endpoint":"https://app.graphql-hive.com/usage","exclude":[],"flush_interval":"5s","request_timeout":"15s","sample_rate":"100%","target_id":null}`<br/>|yes|
+|[**usage\_reporting**](#usage_reporting)|`object`|Configuration for usage reporting to GraphQL Hive.<br/>Default: `{"accept_invalid_certs":false,"access_token":null,"buffer_size":1000,"client_name_header":"graphql-client-name","client_version_header":"graphql-client-version","connect_timeout":"5s","enabled":false,"endpoint":"https://app.graphql-hive.com/usage","exclude":[],"flush_interval":"5s","request_timeout":"15s","sample_rate":"100%","target_id":null}`<br/>||
 
 **Additional Properties:** not allowed  
 **Example**
@@ -113,7 +113,7 @@ traffic_shaping:
   pool_idle_timeout_seconds: 50
 usage_reporting:
   accept_invalid_certs: false
-  access_token: ''
+  access_token: null
   buffer_size: 1000
   client_name_header: graphql-client-name
   client_version_header: graphql-client-version
@@ -1878,26 +1878,26 @@ Configuration for usage reporting to GraphQL Hive.
 
 |Name|Type|Description|Required|
 |----|----|-----------|--------|
-|**accept\_invalid\_certs**|`boolean`|Accepts invalid SSL certificates<br/>Default: false<br/>Default: `false`<br/>|no|
-|**access\_token**|`string`|Your [Registry Access Token](https://the-guild.dev/graphql/hive/docs/management/targets#registry-access-tokens) with write permission.<br/>|yes|
-|**buffer\_size**|`integer`|A maximum number of operations to hold in a buffer before sending to Hive Console<br/>Default: 1000<br/>Default: `1000`<br/>Format: `"uint"`<br/>Minimum: `0`<br/>|no|
-|**client\_name\_header**|`string`|Default: `"graphql-client-name"`<br/>|no|
-|**client\_version\_header**|`string`|Default: `"graphql-client-version"`<br/>|no|
-|**connect\_timeout**|`string`|A timeout for only the connect phase of a request to Hive Console<br/>Default: 5 seconds<br/>Default: `"5s"`<br/>|no|
-|**enabled**|`boolean`|Default: `false`<br/>|no|
-|**endpoint**|`string`|For self-hosting, you can override `/usage` endpoint (defaults to `https://app.graphql-hive.com/usage`).<br/>Default: `"https://app.graphql-hive.com/usage"`<br/>|no|
-|[**exclude**](#usage_reportingexclude)|`string[]`|A list of operations (by name) to be ignored by Hive.<br/>Default: <br/>|no|
-|**flush\_interval**|`string`|Frequency of flushing the buffer to the server<br/>Default: 5 seconds<br/>Default: `"5s"`<br/>|no|
-|**request\_timeout**|`string`|A timeout for the entire request to Hive Console<br/>Default: 15 seconds<br/>Default: `"15s"`<br/>|no|
-|**sample\_rate**|`string`|Sample rate to determine sampling.<br/>0% = never being sent<br/>50% = half of the requests being sent<br/>100% = always being sent<br/>Default: 100%<br/>Default: `"100%"`<br/>|no|
-|**target\_id**|`string`, `null`|A target ID, this can either be a slug following the format “$organizationSlug/$projectSlug/$targetSlug” (e.g “the-guild/graphql-hive/staging”) or an UUID (e.g. “a0f4c605-6541-4350-8cfe-b31f21a4bf80”). To be used when the token is configured with an organization access token.<br/>|no|
+|**accept\_invalid\_certs**|`boolean`|Accepts invalid SSL certificates<br/>Default: false<br/>Default: `false`<br/>||
+|**access\_token**|`string`, `null`|Your [Registry Access Token](https://the-guild.dev/graphql/hive/docs/management/targets#registry-access-tokens) with write permission.<br/>||
+|**buffer\_size**|`integer`|A maximum number of operations to hold in a buffer before sending to Hive Console<br/>Default: 1000<br/>Default: `1000`<br/>Format: `"uint"`<br/>Minimum: `0`<br/>||
+|**client\_name\_header**|`string`|Default: `"graphql-client-name"`<br/>||
+|**client\_version\_header**|`string`|Default: `"graphql-client-version"`<br/>||
+|**connect\_timeout**|`string`|A timeout for only the connect phase of a request to Hive Console<br/>Default: 5 seconds<br/>Default: `"5s"`<br/>||
+|**enabled**|`boolean`|Default: `false`<br/>||
+|**endpoint**|`string`|For self-hosting, you can override `/usage` endpoint (defaults to `https://app.graphql-hive.com/usage`).<br/>Default: `"https://app.graphql-hive.com/usage"`<br/>||
+|[**exclude**](#usage_reportingexclude)|`string[]`|A list of operations (by name) to be ignored by Hive.<br/>Default: <br/>||
+|**flush\_interval**|`string`|Frequency of flushing the buffer to the server<br/>Default: 5 seconds<br/>Default: `"5s"`<br/>||
+|**request\_timeout**|`string`|A timeout for the entire request to Hive Console<br/>Default: 15 seconds<br/>Default: `"15s"`<br/>||
+|**sample\_rate**|`string`|Sample rate to determine sampling.<br/>0% = never being sent<br/>50% = half of the requests being sent<br/>100% = always being sent<br/>Default: 100%<br/>Default: `"100%"`<br/>||
+|**target\_id**|`string`, `null`|A target ID, this can either be a slug following the format “$organizationSlug/$projectSlug/$targetSlug” (e.g “the-guild/graphql-hive/staging”) or an UUID (e.g. “a0f4c605-6541-4350-8cfe-b31f21a4bf80”). To be used when the token is configured with an organization access token.<br/>||
 
 **Additional Properties:** not allowed  
 **Example**
 
 ```yaml
 accept_invalid_certs: false
-access_token: ''
+access_token: null
 buffer_size: 1000
 client_name_header: graphql-client-name
 client_version_header: graphql-client-version

lib/router-config/src/usage_reporting.rs

@@ -10,7 +10,7 @@ pub struct UsageReportingConfig {
     pub enabled: bool,
 
     /// Your [Registry Access Token](https://the-guild.dev/graphql/hive/docs/management/targets#registry-access-tokens) with write permission.
-    pub access_token: String,
+    pub access_token: Option<String>,
 
     /// A target ID, this can either be a slug following the format “$organizationSlug/$projectSlug/$targetSlug” (e.g “the-guild/graphql-hive/staging”) or an UUID (e.g. “a0f4c605-6541-4350-8cfe-b31f21a4bf80”). To be used when the token is configured with an organization access token.
     #[serde(deserialize_with = "deserialize_target_id")]
@@ -83,7 +83,7 @@ impl Default for UsageReportingConfig {
     fn default() -> Self {
         Self {
             enabled: default_enabled(),
-            access_token: String::new(),
+            access_token: None,
             target_id: None,
             endpoint: default_endpoint(),
             sample_rate: default_sample_rate(),