More convenient APIs for headers

[MahdiBM]

Vapor supports some nice hard-typed APIs that let users interact with some header fields in a convenient manner.
For example, consider the following:

import Vapor /// `Vapor` exports `NIOHTTP1`

var headers = NIOHTTP1.HTTPHeaders()
headers.contentType = HTTPMediaType.json 

This feature requests asks if such a feature can be supported by swift-http-types itself, instead of us having to implement it in each of HTTP-server packages such as Hummingbird (v2 is WIP and uses swift-http-types) or Vapor (in v5, the work has not yet begun but it's clear we'll be using swift-http-types).

My understanding is that a package like this would want to be very conservative about adding a feature like this, but I still think such convenient APIs are very valuable.

As i see it, one of the followings should be the case about this feature request, so I'm interested to know which one:

• In scope, can be supported.
• Not a main feature, maybe it can be in an e.g. HTTPTypesExtras target, or package.
• Completely out of scope, will not be supported.

This is how vapor implements such a feature for the content-type header.
Note that content-type is just an example. There could be many more header field names supported with an API like this.

[ekinnear]

This is definitely something that's appealing enough that we keep coming back to it. It seems to add a meaningful amount of utility and convenience, while also increasing safety. There's a potential minor concern about not increasing friction for the next great content-type (to use the example above), but I'm not sure that's a strong reason to avoid convenience for everything else.

One important discussion point has been how to handle changes going forward and the bar for what to include vs. require adopters to extend manually. It seems like we can probably stick to standards-defined items for most cases, however, which might provide a good path forward?

[MahdiBM]

Agree 🤝

[guoye-zhang]

We'd also like to integrate with structured fields and provide common structured field accessors.

Thought media type constants might better as its own library since it's not HTTP specific. On Apple platforms, it's vended through UTI framework:

import UniformTypeIdentifiers
UTType.json.preferredMIMEType!

[MahdiBM]

@guoye-zhang That would be nice. Perhaps you could poke a person or two about it on Apple and see what they think about making that Open Source (I'm guessing that library will require some changes/improvements still, but better not to have duplicate packages if possible)

[guoye-zhang]

@MahdiBM I talked with the team responsible for UTI and they don't think it's possible to make it cross-platform since it's tightly integrated with LaunchServices database that decides which file types are registered and which app to launch, which is specific to Darwin platforms. A new library managing media types is probably better in the long term.

[MahdiBM]

@guoye-zhang Thanks for asking the UTI folks.

How should we proceed now? Do we have a good plan or should we engage the SSWG about an "HTTMediaType" mini-library and see what they think will be the best course of action (@gwynne 👀)?

Also, should it be under /apple or /swift-server orgs? I've noticed some libraries start as personal repositories until they're mature enough. Then they're moved to the organization where they actually belong.

I'd like to start the work. That's why I'm asking and looking for somewhat of a plan.

[guoye-zhang]

@MahdiBM I'm not super familiar with the process, either. I think we do want to present the full picture and where media types fit in.

[MahdiBM]

Okay then, I want to ping @0xTim into the conversation too as another member of the SSWG 😅

[0xTim]

I think we (the SSWG) can raise this at the next meeting for discussion, there's enough people there that it affects and that can help with work

[MahdiBM]

@0xTim I'd love to know what the SSWG thinks, whenever you've had the chance to discuss this issue 👀

[0xTim]

Nope must have gotten lost, will add it to the agenda for the next meeting