How is mutability for headers implemented in the Rhai plugin system?

[martindisch]

I've been playing with Rhai plugins and think I'm getting the hang of it. However, looking at the implementation src/plugins/rhai.rs there is something I'm very curious about because I don't understand it yet.

Let's imagine I'm modifying headers in the supergraph_service step. What I think is roughly happening is:

1. router builds the supergraph::Request struct
2. Rhai engine is used to call user functions registered with service.map_request, a SharedMut of the request is passed in for them to work with
3. The modified request is used as the basis for whatever comes next

What I don't understand is how you manage to capture all the modifications the Rhai functions do to the headers in step 2, in order to have them ready for step 3. There's a getter implemented for headers on the request

// Originating Request
$engine.register_get(
    "headers",
    |obj: &mut SharedMut<$base::Request>| -> Result<HeaderMap, Box<EvalAltResult>> {
        Ok(obj.with_mut(|request| request.supergraph_request.headers().clone()))
    }
);

and there's also the indexer for HeaderMap

.register_indexer_set(|x: &mut HeaderMap, key: &str, value: &str| {
    x.insert(
        HeaderName::from_str(key).map_err(|e| e.to_string())?,
        HeaderValue::from_str(value).map_err(|e| e.to_string())?,
    );
    Ok(())
})

But the getter returns a clone of HeaderMap each time and the indexer operates directly on the HeaderMap it gets from the Rhai engine, so given that and the default "clone everything" semantics of Rhai I don't see how the state of the HeaderMap is maintained over subsequent Rhai function calls or how the modified headers are retrieved back into Rust land at the end.

I know how to make it so that Rhai functions actually mutate a Rust struct in place, by registering functions that operate on Rc<RefCell<_>> or similar, but I don't see that happening here and can't really explain how it still works.

What am I missing?

[SimonSapin]

I had trouble understanding this at first, too. What makes this work is a perhaps-surprising feature of Rhai called chaining updates. In this Rhai code:

request.headers["example"]  = "example";

… what happens in terms of Rust code is:

• The getter for headers on subgraph::Request is called, returning a cloned HeaderMap
• The indexer-setter for HeaderMap is called with a key and new value. This modifies the cloned map but not (yet) the request.
• Then because the above was a chaining update, Rhai implicitly calls the setter for headers on subgraph::Request with the mutated HeaderMap. The bindings for that one are:

            $engine.register_set(
                "headers",
                |obj: &mut SharedMut<$base::Request>, headers: HeaderMap| {
                    if_subgraph! {
                        $base => {
                            let _unused = (obj, headers);
                            Err("cannot mutate originating request on a subgraph".into())
                        } else {
                            obj.with_mut(|request| *request.supergraph_request.headers_mut() = headers);
                            Ok(())
                        }
                    }
                }
            );

(Which by the way shows that the Rhai script above would fail if it were running at the subgraph stage, see https://www.apollographql.com/docs/router/customizations/rhai-api#request-interface)

---

Why this question? Are you looking into using Rhai in another project?

[martindisch]

Thank you so much for the prompt and illuminating answer! When I saw the setter for headers I didn't think much of it because I had no scenario in which I would replace the full HeaderMap, but it makes perfect sense now, as it also allows this "partial" modification of the headers to work through this indeed surprising behavior.

I was looking into writing tests for one of our Rhai plugins and ended up replicating the very small part of the plugin API surface that it uses, except I couldn't get it to behave the same because I didn't expose the setter for the field. I'm aware it's possible to write tests against the full router implementation and might try that at some point, but I wanted to start with the most simple way of testing a few select properties of our plugin. Then I tripped over the whole "how does that even work?" thing and I needed to know just to satisfy my curiosity 😄

[garypen]

@martindisch At some point (translation: when we have time to schedule it), we'd really like to make rhai testing in the context of the router a lot simpler than it currently is. We have some ideas, but they aren't advanced well enough to discuss right now.

[martindisch]

That's great to hear, thanks!