feat(hive-apollo-router-plugin): support target id and org access token (#6577)

Co-authored-by: Laurin Quast <[email protected]>

Author: dotansimha

.changeset/curvy-mice-joke.md

@@ -0,0 +1,17 @@
+---
+'hive-apollo-router-plugin': minor
+---
+
+Add support for providing a target for usage reporting with organization access tokens.
+
+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`).
+
+```yaml
+# ... other apollo-router configuration
+plugins:
+  hive.usage:
+    enabled: true
+    registry_token: "ORGANIZATION_ACCESS_TOKEN"
+    target: "my-org/my-project/my-target"
+```

configs/cargo/Cargo.lock

@@ -50,11 +50,18 @@ pub struct UsagePlugin {
 pub struct Config {
     /// Default: true
     enabled: Option<bool>,
-    /// Hive token, can also be set using the HIVE_TOKEN environment variable
+    /// Hive token, can also be set using the HIVE_TOKEN environment variable.
+    /// The token can be a registry access token, or a organization access token.
     registry_token: Option<String>,
     /// Hive registry token. Set to your `/usage` endpoint if you are self-hosting.
     /// Default: https://app.graphql-hive.com/usage
+    /// When `target` is set and organization access token is in use, the target ID is appended to the endpoint,
+    /// so usage endpoint becomes `https://app.graphql-hive.com/usage/<target_id>`
     registry_usage_endpoint: Option<String>,
+    /// The target to which the usage data should be reported to.
+    /// 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").
+    target: Option<String>,
     /// Sample rate to determine sampling.
     /// 0.0 = 0% chance of being sent
     /// 1.0 = 100% chance of being sent.
@@ -98,6 +105,7 @@ impl Default for Config {
             connect_timeout: Some(5),
             request_timeout: Some(15),
             flush_interval: Some(5),
+            target: None,
         }
     }
 }
@@ -186,14 +194,25 @@ impl Plugin for UsagePlugin {
             return Err("Hive token is required".into());
         }
 
-        let endpoint = init
+        let mut endpoint = init
             .config
             .registry_usage_endpoint
             .clone()
             .unwrap_or_else(|| {
                 env::var("HIVE_ENDPOINT").unwrap_or(DEFAULT_HIVE_USAGE_ENDPOINT.to_string())
             });
 
+        let target_id = init
+            .config
+            .target
+            .clone()
+            .or_else(|| env::var("HIVE_TARGET_ID").ok());
+
+        // In case target ID is specified in configuration, append it to the endpoint
+        if let Some(target_id) = &target_id {
+            endpoint.push_str(&format!("/{}", target_id));
+        }
+
         let default_config = Config::default();
         let user_config = init.config;
         let enabled = user_config

packages/libraries/router/src/usage.rs

@@ -182,6 +182,10 @@ You can send usage reporting to Hive registry by enabling `hive.usage` plugin in
   [Registry Access Token](/docs/management/targets#registry-access-tokens) with write permission.
 - `HIVE_ENDPOINT` (**optional**) - For self-hosting, you can override `/usage` endpoint (defaults to
   `https://app.graphql-hive.com/usage`)
+- `HIVE_TARGET_ID` - 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 `HIVE_TOKEN` is configured with an
+  organization access token.
 
 <Tabs items={['Binary', 'Docker', 'Custom']}>
   <Tabs.Tab>