allow request mutation and async code in prehooks

[jclulow]

This allows one to call asynchronous code in a prehook for a request, and to mutate the request in place before it is sent. I use this to collect various bits of the request (e.g., the URL path, the Date header, etc) to produce an intermediate blob that I can then pass to an SSH agent (over asynchronous sockets I/O to another process) and then add that signature as a request header for authentication in the outgoing request. This operation is also fallible: communications might fail, or the agent might be unable or unwilling to sign the intermediate blob, etc.

[ahl]

Should we make all hooks async? Should we / could we infer whether or not the hook was async and act accordingly?

A related change is that the async pre hook is fallible--should we make all hooks fallible?

In the context where you're using this could you block_on from the non-async hook?

[jclulow]

Should we make all hooks async? Should we / could we infer whether or not the hook was async and act accordingly?

I don't know the answer to the first question! I suspect it might be benign for hook functions to be async even when they don't need to do any async work from a performance perspective.

I'm not sure about the answer to the second one, but I suspect it may be difficult. At the site of the macro, in my use, it looks like:

    progenitor::generate_api!(
        spec = "openapi.json",
        interface = Builder,
        inner_type = Arc<crate::Inner>,
        pre_hook_async = crate::pre_hook,
    );

There is no async token within the input to the proc macro, even though eventually in this same file the function is then obviously asynchronous:

async fn pre_hook(i: &Arc<Inner>, req: &mut reqwest::Request) -> Result<()> {

A related change is that the async pre hook is fallible--should we make all hooks fallible?

I don't know this either! It seems like the primary use case today is to add logging hooks, which don't modify the request, and are both apparently synchronous and infallible. Part of my motivation for making a separate thing here was to avoid the need for code changes in existing consumers of the pre-hook machinery, who would need to make their hook functions async and probably start returning Ok(()) in places where today they would return nothing.

In the context where you're using this could you block_on from the non-async hook?

In the past I would have said yes, because that really seems like it should be possible. In practice, though, I'm not sure there is an ergonomic way (or even, to be honest, a sound way) to do this reliably given you're almost certainly calling the hook function in the context of an async runtime. I had to perform some gymnastics to bounce in and out of async contexts when I was doing a scripting engine thing for pilot and it was extremely tedious to get to the point where it didn't just panic in tokio sometimes.

[jclulow]

@ahl Do you reckon you take another look at this? I have to keep rebasing it forward periodically.

[ahl]

looks good; if it's easy enough, add a test of some sort to make sure we don't break this in the future? Even one of the integration tests would do.

[jclulow]

@ahl I added a short example of use to the example-macro example. It seems like the examples all get compiled when you run cargo test. Is that alright?