Add docs for subgraph header propagation (apollographql#2446)

- Fix apollographql#2128
Propagation for headers between subgraphs is now documented.

In addition apollographql#2444 has been raised to track a potential future where this
can be achieved via YAML.

**Checklist**

Complete the checklist (and note appropriate exceptions) before a final
PR is raised.

- [ ] ~~Changes are compatible[^1]~~
- [x] Documentation[^2] completed
- [ ] ~~Performance impact assessed and acceptable~~
- Tests added and passing[^3]
    - [ ] ~~Unit Tests~~
    - [ ] ~~Integration Tests~~
    - [x] Manual Tests

**Exceptions**

*Note any exceptions here*

**Notes**

[^1]. It may be appropriate to bring upcoming changes to the attention
of other (impacted) groups. Please endeavour to do this before seeking
PR approval. The mechanism for doing this will vary considerably, so use
your judgement as to how and when to do this.
[^2]. Configuration is an important part of many changes. Where
applicable please try to document configuration examples.
[^3]. Tick whichever testing boxes are applicable. If you are adding
Manual Tests:
- please document the manual testing (extensively) in the Exceptions.
- please raise a separate issue to automate the test and label it (or
ask for it to be labeled) as `manual test`

Co-authored-by: bryn <bryn@apollographql.com>

NEXT_CHANGELOG.md

@@ -98,6 +98,12 @@ By [@bryncooke](https://github.com/bryncooke) in https://github.com/apollographq
 
 ## 📚 Documentation
 
+### Documentation on how to propagate headers between subgraph services ([Issue #2128](https://github.com/apollographql/router/issues/2128))
+
+Migrating headers between subgraph services is possible via Rhai script. An example has been added to the header propagation page.
+
+By [@bryncooke](https://github.com/bryncooke) in https://github.com/apollographql/router/pull/2446
+
 ### Added documentation for listening on IPv6 ([Issue #1835](https://github.com/apollographql/router/issues/1835))
 
 Added documentation for listening on IPv6
@@ -109,3 +115,4 @@ supergraph:
 ```
 
 By [@bryncooke](https://github.com/bryncooke) in https://github.com/apollographql/router/pull/2440
+

docs/source/configuration/header-propagation.mdx

@@ -205,3 +205,51 @@ headers:
             name: "router-subgraph-name"
             value: "accounts"
 ```
+
+
+## Propagation between subgraphs
+
+It is not currently possible to propagate headers between subgraphs using yaml config alone. It can however be achieved using [Rhai scripting]("../customizations/rhai").
+
+The approach relied on the feature that all requests have context that can be used to store data for the duration of the request: 
+1. On supbgraph response, copy header values into context.
+2. On supbgraph request, copy header values from context into the subgraph request.
+
+
+Example router.yaml that will use the Rhai script:
+```rhai title="router.yaml"
+rhai:
+  main: "main.rhai"
+```
+
+Example Rhai script that copies `request-id` and `user` headers:
+```rhai title="./rhai/main.rhai"
+fn subgraph_service(service, subgraph) {
+    // The list of headers that you which to propagate.
+    let headers = ["request-id", "user"];
+
+    // Callback for subgraph requests. Inserts headers from context into the subgraph request.
+    let request_callback = |request| {
+        for key in headers {
+            if request.context[key] != () {
+                request.subgraph.headers[key] = request.context[key];
+            }
+        }
+    };
+  
+    // Callback for subgraph responses. Pulls header values out of the response and inserts them into context.
+    let response_callback = |response| {
+        for key in headers {
+            if key in response.headers {
+                response.context[key] = response.headers[key];
+            }
+        }
+    };
+  
+    // Register the callbacks.
+    service.map_request(request_callback);
+    service.map_response(response_callback);
+}
+```
+
+If you would like to see a YAML based solution then [please leave us a comment on our issue tracker](https://github.com/apollographql/router/issues/2444).