Server-side FFI bindings

[bossmc]

Continues the work started in #2278 by adding bindings to allow using hyper's server stack from a C runtime. The patterns are based on the model used on the client side, and the two can be used simultaneously (e.g. using the client bindings to make down-stream HTTP calls as part of serving an upstream request).

I understand that the project is currently focussed on the 1.0 stabilization (woo!) and I realise that this MR isn't part of that process, but there's various teams across my area of Microsoft who would really like to start using hyper in our C/C++ projects to take advantage of the benefits that hyper is already providing to our Rust codebases elsewhere. Thus it would be really great to get a first-pass review of the approach soon to try and head off any churn down the line, if possible?

I've added an example C integration (capi/examples/server.c) that simply logs information about the request then responds with a 404 to everything.

Implementation details of note:

• The service callback (where the C code implements business logic for handling requests) is given the request and a channel handle and completes the request by passing a response back on the channel, this allows the service callback to be asynchronous/multi-threaded/deferred etc.
• I added a timer heap implementation so the server configuration can set timeouts (e.g. to protect against slow loris attacks) this currently exposes millisecond accuracy to the C code since that's the granularity of epoll_wait's timeout argument though there is also epoll_pwait2 which goes down to nanoseconds so maybe the FFI should expose them?
• I made the ffi feature depend on all the other related features for now, mostly as a QoL for people using the FFI bindings (since the FFI code isn't feature aware yet)
• I added an AutoConnection layer that restores the behaviour of "trying HTTP/1.x and, if it sees the HTTP/2 prelude rewinds and switches to HTTP/2 mode". I've tried to make this generic so it is possibly in a fit state to be lifted to hyper-utils rather than being in the FFI code?

Other smaller notes:

• Simplified the header-generation code a lot by using cargo expand's ability to show a single module from a crate (so we no longer need to build a fake crate to be able to run bindgen)
• Formatted the C example code with clang-format (with some rust-familar settings)
• Fixed some compiler warnings in the example C code
• Made Sleep auto-impl for things that look like Sleep again as a QoL thing

I've tested the server example code under valgrind and -fsanitize=memory to ensure there's no use-after-free/double-free/etc.

[bossmc]

Hi @seanmonstar! Hope all's going well. Investigations and implementation is continuing and they threw up an interesting problem that I wanted to flag with you.

The basic problem is that when setting userdata on hyper_* objects, it can be hard to track the correct lifetime of that userdata object from the C code (e.g. a userdata for an IO object that backs a server connection needs to live for as long as the server connection task and probably wants to be cleaned up promptly when the server task completes in order to close sockets etc.).

The original implementation of the C server code just magically "knew" that when a server connection task completed the IO userdata and service userdata that backed it were no longer needed and could be freed, and to achieve this those userdata pointers were duplicated in the task userdata. This design means that there are multiple references to the IO/service userdata alive at the same time and the code frees one set of them when it's "pretty sure" the other ones have been forgotten and won't be read again. This made our C developers rightly nervous 😨 so I've implemented a different strategy that's more similar to how Rust would manage the memory.

hyper_io_set_userdata and hyper_service_set_userdata have both gained a drop_callback argument that (if provided) will be called on the userdata pointer when the owning object is dropped. This means that the owning object really owns the userdata in a rust ownership sense and the lifetimes are correctly aligned. I've allowed the C code to pass NULL as the callback to mean "don't drop this userdata, I'll do it myself" which I can see being useful if the userdata is stack-allocated (as it is in the client example code) or is shared between tasks.

I'm raising this change specifically as it's the first breaking change to the existing client-facing bindings that this MR has introduced 😄 and hence I wanted to get your opinion on the approach. I will say that the related changes to the example server integration (server.c) made the code much nicer/clearer IMO.

Additional Thoughts

1. I've not done the same thing for the hyper_task userdata, since the expectation is that that will be read on task completion by the C code in order to work out what (if anything) needs to happen next for this piece of work and thus the C code would have it in hand to free it if appropriate. The only benefit of adding the a drop callback would be if someone called hyper_task_free without first reading the userdata from the task (e.g. in an error condition?).

2. If someone calls hyper_X_set_userdata twice, then the first userdata is lost, hopefully the calling code still has a reference to it to free it/clean it up. I considered making hyper_X_set_userdata return any existing userdata (or call the clean-up callback?) to try and help but I don't have a hard requirement to solve this so I've not made any (more breaking) changes here before seeing what you think.

[bossmc]

Coming back to those additional thoughts, I've come to the conclusion that it's better to be consistent everywhere, so hyper_task now takes an optional drop_callback and setting the userdata twice will call any drop_callback passed with the first userdata blob (i.e. providing a drop callback is equivalent to "pass by move" in a rust sense and the C code should not reference the userdata pointer after setting it on the task/io/service/etc.).

I've re-read your last comment (re: stability guarantees) and I may have misunderstood your question, are you proposing a #[cfg(hyper_unstable_client_ffi)] and #[cfg(hyper_unstable_server_ffi)] so we can stabilize each half separately? I was assuming we could just remove some of the #[cfg] blocks if we wanted to stabilize some but not all of the FFI API?

I think the changes are now ready for review (the team that has been integrating with them has got their pre-existing test suite passing with these changes 😄 ). It would be great to try and get this in if possible (otherwise the branch will keep getting stale and needing catchup merges).

[seanmonstar]

I was assuming we could just remove some of the #[cfg] blocks if we wanted to stabilize some but not all of the FFI API?

Yes, that's probably the best way to do it. Whenever something does go stable, we just explicitly say which types/functions are stable in the changelog.

[bossmc]

Coming back to this, I've merged the latest master in to this branch and fixed up the discrepancies. Do you think you'll be able to review this soon to prevent it bit-rotting again?

[nielsenko]

@bossmc and @seanmonstar What is the status of this PR?

[seanmonstar]

Agh, I forgot about this.

Well, the main consumer that motivated my adding of FFI support initially no longer needs hyper (the client types existed for a backend in curl). That means I no longer have something pushing me to pay attention, and my current clients aren't asking for it, but rather other things that take my attention.

So, any further progress on either would be entirely on other contributors. I don't want to be a blocker here, I'm fine with this part of hyper being reviewed/maintained by anyone else. Especially while it's "unstable". If Andy and/or anyone else wants to take that on, I can get out of the way.