docs: rhai example for header->client propagation (#2474)

Shows how to send set-cookie headers from subgraphs to clients with Rhai scripting.

Relates to #1284

NEXT_CHANGELOG.md

@@ -241,13 +241,20 @@ By [@bnjjj](https://github.com/bnjjj) in https://github.com/apollographql/router
 
 ### Propagating headers between subgraphs ([Issue #2128](https://github.com/apollographql/router/issues/2128))
 
-Passing headers between subgraph services is possible via Rhai script. An example has been added to the header propagation page.
+Passing headers between subgraph services is possible via Rhai script and we've added an example to the [header propagation](https://www.apollographql.com/docs/router/configuration/header-propagation) documentation.
 
 By [@bryncooke](https://github.com/bryncooke) in https://github.com/apollographql/router/pull/2446
 
+### Propagating response headers to clients ([Issue #1284](https://github.com/apollographql/router/issues/1284))
+
+Passing headers from subgraph services to clients is possible via Rhai script and we've added an example to the [header propagation](https://www.apollographql.com/docs/router/configuration/header-propagation) documentation.
+
+By [@lennyburdette](https://github.com/lennyburdette) in https://github.com/apollographql/router/pull/2474
+
 ### IPv6 listening instructions ([Issue #1835](https://github.com/apollographql/router/issues/1835))
 
-Added documentation for listening on IPv6
+Added instructions for how to represent IPv6 listening addresses to our [Overview](https://www.apollographql.com/docs/router/configuration/overview) documentation.
+
 ```yaml
 supergraph:
   # The socket address and port to listen on.
@@ -277,14 +284,14 @@ By [@bryncooke](https://github.com/bryncooke) in https://github.com/apollographq
 
 As a result of UX feedback, we are modifying the experimental JWT configuration. The `jwks_url` parameter is renamed to `jwks_urls` and now expects to receive an array of URLs, rather than a single URL.
 
-Here's a typical sample configuration fragment:
+We've updated the [JWT Authentication documentation](apollographql.com/docs/router/configuration/authn-jwt) accordingly, however here's a short sample configuration example:
 
 ```yaml
 authentication:
   experimental:
     jwt:
       jwks_urls:
-        - https://dev-zzp5enui.us.auth0.com/.well-known/jwks.json
+        - https://dev-abcd1234.us.auth0.com/.well-known/jwks.json
 ```
 
 By [@garypen](https://github.com/garypen) in https://github.com/apollographql/router/pull/2500

docs/source/configuration/header-propagation.mdx

@@ -206,23 +206,74 @@ headers:
             value: "accounts"
 ```
 
+## Response header propagation
+
+It is not currently possible to propagate response headers from subgraphs to clients using YAML configuration alone. It can however be achieved using [Rhai scripting]("../customizations/rhai").
+
+This approach relies on the fact that all requests have context that can be used to store data for the duration of the request:
+
+1. For each subgraph response, copy header values into context.
+2. For the supergraph response, copy header values from the context onto the response.
+
+Example router.yaml that will use the Rhai script:
+
+```yaml title="router.yaml"
+rhai:
+  main: "main.rhai"
+```
+
+Example Rhai script that collects `set-cookie` headers from subgraphs and merges them into a single client response header.
+
+```rhai title="./rhai/main.rhai"
+fn router_service(service) {
+  let add_cookies_to_response = |response| {
+    if response.context["set_cookie_headers"]?.len > 0 {
+      let cookie = "";
+      for header in response.context["set_cookie_headers"] {
+        cookie += header + "; ";
+      }
+      response.headers["set-cookie"] = cookie;
+    }
+  };
+
+  service.map_response(add_cookies_to_response);
+}
+
+fn subgraph_service(service, subgraph) {
+    let store_cookies_from_subgraphs = |response| {
+      if response.headers["set-cookie"] != () {
+        if response.context["set_cookie_headers"] == () {
+          response.context.set_cookie_headers = []
+        }
+
+        response.context.set_cookie_headers += response.headers["set-cookie"]
+      }
+    };
+
+    service.map_response(store_cookies_from_subgraphs);
+}
+```
+
+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/1284).
 
 ## 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.
+This approach relies on the fact that all requests have context that can be used to store data for the duration of the request:
 
+1. For each subgraph response, copy header values into context.
+2. For each subgraph request, copy header values from context into the subgraph request.
 
 Example router.yaml that will use the Rhai script:
-```rhai title="router.yaml"
+
+```yaml 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.
@@ -236,7 +287,7 @@ fn subgraph_service(service, subgraph) {
             }
         }
     };
-  
+
     // Callback for subgraph responses. Pulls header values out of the response and inserts them into context.
     let response_callback = |response| {
         for key in headers {
@@ -245,7 +296,7 @@ fn subgraph_service(service, subgraph) {
             }
         }
     };
-  
+
     // Register the callbacks.
     service.map_request(request_callback);
     service.map_response(response_callback);