Exposing specific HTTP headers per user function API design

[nyurik]

Context Ctx object contains a bunch of VCL_HTTP values - most of which users do not need most of the time. Instead, we should create an individual VCL_HTTP on demand:

pub fn user_func(req: &mut RequestHeaders) {...}

This means the user needs just the request headers, and will be able to modify it as needed. We can also support readonly headers with a non-mutable reference &RequestHeaders.

Implementation

Since our macro generator does not actually have type information (it gets resolved by the compiler after macro expansion), we can only rely on name matching. I propose we add these type aliases:

pub type RequestHeaders<'a> = HttpHeaders<'a>;
pub type RequestTopHeaders<'a> = HttpHeaders<'a>;
pub type ResponseHeaders<'a> = HttpHeaders<'a>;
pub type BackendRequestHeaders<'a> = HttpHeaders<'a>;
pub type BackendResponseHeaders<'a> = HttpHeaders<'a>;

This way macro generator will know which instance to create from the raw context, doing it just in time.

Safety

• make sure we never give users object ownership, but only & and &mut to them - and those refs should be to stack allocated objects the wrapper creates for the duration of running user functions. This way user can never keep references beyond the scope of a function.
• mark those temporary object types as !Sync -- so that references to them cannot be moved to a different thread. I am not certain this is needed yet, so we may relax this one later, but for now the concern is that if internally they share pointers to the same non-thread-safe C API, we shouldn't allow multiple read-only references to them... Example: we pass &mut to two objects that internally use same workspace, and then send one of them to another thread - so simultaneous access from multi-threading

[gquintard]

most of which users do not need most of the time.

that's quite the assessment, I feel like it's not as informed as it could be. We have plenty of vmods that will need/benefit from header access, such as cookie, headers, jwt, uri, urlplus, etc.

the main problem to solve here is that it you give access to a header struct, you can't have access to the workspace, as it's the backing store for it

[nyurik]

I meant you don't need many of these things at the same time, i.e. most of the time you don't need all 5.

Workspace is a fair concern, thx. Do multiple header section get backed by the same workspace, or is there a separate workspace per header?

[gquintard]

fair angle, usually you need at most two, and half of the time, you only have access to one.

Client side share the same workspace, backend side shares another one, and the req_top part can be either the same workspace as the current request, or a completely different one