Define the VISION

[seanmonstar]

This is an overview of what the shape of hyper looks like, but also somewhat zoomed out, so that the vision can survive while the exact minute details might shift and change over time. It starts with what is hyper, defines a framework for how we make decisions, includes use cases we've considered, and then shows how the library can ideally fulfill its purpose.

There's two documents here. The VISION is the main document, and includes a list of prioritized tenets inside it. The TENETS document is supplemental, and goes more in-depth on what the principles mean, and examples of how they've been used before.

This is the first step in the hyper 1.0 timeline.

This blog post includes background and motivation for defining a VISION for hyper.

Feedback very much welcome!

---

The VISION has been merged.

[joshtriplett]

Could you add something here, and possibly in the tenets, about the degree to which hyper provides optional runtime integration? For instance, hyper currently has an optional runtime feature; what criteria would hyper use to evaluate proposals for additional such features? (e.g. maintainability, not compromising higher-priority tenets) Similarly, what criteria would be used to evaluate (optional) integration with various different versions of traits such as AsyncRead/AsyncWrite?

These seem like questions people will reasonably ask, for which it'd be helpful to have a reference in the tenets and vision.

[nicoburns]

I don't seem to be able to comment on the lines for some reason, so quoting here:

If a message has a content-length, enforce only that many bytes are read or written.

Is this the sort of thing that might be able to be overridden? I've had experiences where I've had to interact with HTTP servers that would send incorrect content-length headers before (I believe if you just accepted all bytes until they closed the connection it would work).

[seanmonstar]

If a message has a content-length, enforce only that many bytes are read or written.

Is this the sort of thing that might be able to be overridden?

I suppose it's possible, but that's a really really big bug. Message length discrepancies are the basis of message smuggling vulnerabilities. But to the point of this document, hyper is Correct first, but if something is really needed, Flexible allows us to provide options to turn some things off.

[bryangarza]

Other than in the charter, this is the only other usage of the word protective. Would be good to expound on it a bit. This line begs the question: "what other parts of hyper also make it protective?". I think that might already be answered in the doc but it would be good to make the association between the term protective and some of the other points on this doc more explicit. And maybe also explicitly define what we mean by protective somewhere in the doc?

[davidpdrsn]

❤️

[acfoltzer]

Is it worth discussing what the vision is for cases that fall outside of what can be handled with Extensions? To use the example we discussed in Discord recently, suppose we want to handle custom h2 frames that arrive interleaved with the data frames, which therefore can arrive after the head is received and Extensions can no longer be modified.

[acfoltzer]

#1586 and #2426 are other possibly relevant cases to consider here

[seanmonstar]

Yea, it's definitely worth discussing, at least at a high level. We want this to define mechanisms that we used to then outline issues and roadmaps for changing the exact code to get here.

I notice this sentence says "usually", which does already allow some wiggling that not all things can be handled by Extensions. Alternative mechanisms that seem definitely possible could be included in a sentence too.

[LucioFranco]

Exciting stuff! Thanks sean

[Yneth]

any ideas, considerations regarding io uring support which may come with new IO async interface (owned buffers instead of borrowed ones)?