feat: define a headers type

[anuraaga]

I have been thinking a lot about headers. Currently, there is a relatively major issue that ServiceContext.request_headers has different type than others.

The biggest challenge of headers is that 99% of users treat them as a mapping from string to single string, but for HTTP protocol compatibility we must still support the <1% that may need multiple values for a single key. So my goal with exposing headers is to make it as easy as possible for the 99% while also supporting the rest. We know we support the rest because conformance tests require it too.

This means I want to stop using Mapping because it can only have single value, or multi value, but not handle them both cleanly.

I looked at some popular libraries like multidict. But it seems like overkill to me, notably it reimplements hashtables completely and has known bugs because of it. It's still ok but I wanted to avoid it.

We shouldn't use httpx.Headers on server side since it's a client library.

So I went ahead and implemented my own Headers class (so great for Go / typescript to have them in stdlib 😅 ). It is almost completelly just delegating to a dict[str, str] for the 99% case, while also keeping an extra dict in case extra values are needed. As almost all usage delegates to dict, possibly with an additional failing is None check, I think the performance should be quite high and avoid reimplementing the dict. It won't be as high as another approach when multiple values are actually used, but they should rarely be used.

To avoid exporting multiple headers types, I have replaced RequestHeaders with an inline type that should cover the common use case and uncommon use case minimally.

How does that sound?

Note, this is the last big API change I have in mind so probably a good chance to release after.

[i2y]

How does that sound?

Sounds good!

Note, this is the last big API change I have in mind so probably a good chance to release after.

After merging this PR, with all the recent improvements (conformance tests passing, error handling, headers unification and so on) and breaking API changes, I'm planning to release this as version 2.0.0 soon. Maybe tomorrow or the day after tomorrow?

[i2y]

✨