experimental externalisation on the router service via configuration (#…

…2229)

fixes: #1916 

Simplified externalisation configuration:

```
plugins:
  experimental.external:
    url: http://127.0.0.1:8081
    timeout: 2s
    stages:
      router:
        request:
          headers: true
          context: true
          body: true
          sdl: true
        response:
          headers: true
```
The biggest pro is that it's just so simple it's very easy to configure.
The biggest con is lack of control: e.g. no control over header
propagation. The only supported stage at this moment is "router".

NEXT_CHANGELOG.md

@@ -84,9 +84,35 @@ By [@bnjjj](https://github.com/bnjjj) in https://github.com/apollographql/router
 
 ## 🥼 Experimental
 
-
 ### Introduce a `router_service` ([Issue #1496](https://github.com/apollographql/router/issues/1496))
 
 A `router_service` is now part of our service stack, which allows plugin developers to process raw http requests and raw http responses, that wrap the already available `supergraph_service`
 
 By [@o0Ignition0o](https://github.com/o0Ignition0o) in https://github.com/apollographql/router/pull/2170
+
+### Introduce an externalization mechanism based on `router_service` ([Issue #1916](https://github.com/apollographql/router/issues/1916))
+
+If external extensibility is configured, then a block of data is transmitted (encoded as JSON) to an endpoint via an HTTP POST request. The router will process the response to the POST request before resuming execution.
+
+Conceptually, an external co-processor performs the same functionality as you may provide via a rust plugin or a rhai script within the router. The difference is the protocol which governs the interaction between the router and the co-processor.
+
+Sample configuration:
+
+```yaml
+plugins:
+  experimental.external:
+    url: http://127.0.0.1:8081 # mandatory URL which is the address of the co-processor
+    timeout: 2s # optional timeout (2 seconds in this example). If not set, defaults to 1 second
+    stages: # In future, multiple stages may be configurable
+      router: # Currently, the only valid value is router
+        request: # What data should we transmit to the co-processor from the router request?
+          headers: true # All of these data content attributes are optional and false by default.
+          context: true
+          body: true
+          sdl: true
+        response: # What data should we transmit to the co-processor from the router response?
+          headers: true
+          context: true
+```
+
+By [@garypen](https://github.com/garypen) in https://github.com/apollographql/router/pull/2229

apollo-router/Cargo.toml

@@ -164,6 +164,7 @@ serde_json = { version = "1.0.89", features = ["preserve_order"] }
 serde_urlencoded = "0.7.1"
 serde_yaml = "0.8.26"
 static_assertions = "1.1.0"
+strum_macros = "0.24.3"
 sys-info = "0.9.1"
 thiserror = "1.0.37"
 tokio = { version = "1.23.0", features = ["full"] }

apollo-router/src/configuration/snapshots/apollo_router__configuration__tests__schema_generation.snap

@@ -549,6 +549,81 @@ expression: "&schema"
       "properties": {
         "experimental.expose_query_plan": {
           "type": "boolean"
+        },
+        "experimental.external": {
+          "type": "object",
+          "required": [
+            "url"
+          ],
+          "properties": {
+            "stages": {
+              "default": null,
+              "type": "object",
+              "properties": {
+                "router": {
+                  "default": null,
+                  "type": "object",
+                  "properties": {
+                    "request": {
+                      "default": null,
+                      "type": "object",
+                      "properties": {
+                        "body": {
+                          "default": false,
+                          "type": "boolean"
+                        },
+                        "context": {
+                          "default": false,
+                          "type": "boolean"
+                        },
+                        "headers": {
+                          "default": false,
+                          "type": "boolean"
+                        },
+                        "sdl": {
+                          "default": false,
+                          "type": "boolean"
+                        }
+                      },
+                      "nullable": true
+                    },
+                    "response": {
+                      "default": null,
+                      "type": "object",
+                      "properties": {
+                        "body": {
+                          "default": false,
+                          "type": "boolean"
+                        },
+                        "context": {
+                          "default": false,
+                          "type": "boolean"
+                        },
+                        "headers": {
+                          "default": false,
+                          "type": "boolean"
+                        },
+                        "sdl": {
+                          "default": false,
+                          "type": "boolean"
+                        }
+                      },
+                      "nullable": true
+                    }
+                  },
+                  "nullable": true
+                }
+              },
+              "nullable": true
+            },
+            "timeout": {
+              "default": null,
+              "type": "string"
+            },
+            "url": {
+              "type": "string"
+            }
+          }
         }
       },
       "additionalProperties": false

apollo-router/src/context.rs

@@ -9,6 +9,7 @@ use std::time::Instant;
 use dashmap::mapref::multiple::RefMulti;
 use dashmap::mapref::multiple::RefMutMulti;
 use dashmap::DashMap;
+use serde::Deserialize;
 use serde::Serialize;
 use tower::BoxError;
 
@@ -27,12 +28,14 @@ pub(crate) type Entries = Arc<DashMap<String, Value>>;
 /// provide [`crate::SubgraphRequest`] or [`crate::SubgraphResponse`] processing. At such times,
 /// plugins should restrict themselves to the [`Context::get`] and [`Context::upsert`]
 /// functions to minimise the possibility of mis-sequenced updates.
-#[derive(Clone, Debug)]
+#[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct Context {
     // Allows adding custom entries to the context.
     entries: Entries,
 
     /// Creation time
+    #[serde(skip)]
+    #[serde(default = "Instant::now")]
     pub(crate) created_at: Instant,
 }
 

apollo-router/src/error.rs

@@ -443,3 +443,12 @@ impl ParseErrors {
         };
     }
 }
+
+/// Error types for licensing.
+#[derive(Error, Display, Debug, Clone, Serialize, Deserialize)]
+pub(crate) enum LicenseError {
+    /// Apollo graph reference is missing
+    MissingGraphReference,
+    /// Apollo key is missing
+    MissingKey,
+}