Offer a `Peek` interface over `Upgraded` connections

[RaitoBezarius]

Is your feature request related to a problem? Please describe.

I'm implementing some code that tries to detect whether the contents of a hyper upgraded connection can be handled or should be forwarded, for this, I need to peek 4KB and decide. Even though Read seems to be more of an BufRead, hyper do not expose any peeking methods on its usual APIs, so I would need to implement my own buffering, ending up with double buffers.

Describe the solution you'd like

• Add a Peek trait, implement it for Rewind<T>
• Implement it for Upgraded, H2Upgraded
• Implement compat with AsyncReadBuf for tokio.

Describe alternatives you've considered

• Do the buffering myself.

Additional context

I have some prototype of this feature modulo the tests, the only controversial aspect is, this is my Peek trait:

pub trait Peek {
    # Compared to all the other APIs, this returns a borrow of self. This should be fine lifetime-wise.
    fn poll_peek(self: Pin<&mut Self>, cx: &mut Context<'_>)
        -> Poll<Result<&[u8], std::io::Error>>;

    fn consume(self: Pin<&mut Self>, amt: usize);
}

If you are interested, I can try to finish my tests and PR this up.

[seanmonstar]

Ideally such a trait would exist in hyper-util first. But if I understand your concern, you don't want a BufReader helper, you want to access the internaly buffer that Upgraded already has. I'm not sure I'd want to have that in hyper proper to start...

[RaitoBezarius]

Ideally such a trait would exist in hyper-util first. But if I understand your concern, you don't want a BufReader helper, you want to access the internaly buffer that Upgraded already has. I'm not sure I'd want to have that in hyper proper to start...

If I understand you, applications should double buffer even though the internal buffer is there in memory?

[seanmonstar]

While that does sound like the end result to what I said, it comes from a different place of review:

• Conservative to new traits being added directly in hyper, preferring to only have what is directly needed, or at least letting it bake in hyper-util first. (Does it affect potential io-uring support that we want?, etc)
• Not exposing internal details, like that there is a buffer inside an object.

[RaitoBezarius]

It seems to me that Peek (named AsyncBufRead in tokio land) are well explored in the async/IO ecosystem in Rust, including, wrt to io-uring backends.

If exposing the internal details of the buffer of Upgraded looks dangerous, we can always consider a mechanism where you forward the internal detail to a public type that is returned BufferedUpgraded and you can decide at any point in time to remove internal buffers and you can simply slap a BufReader on Upgraded and be done with it. That being said, changing such internal details can always happen over major version APIs breakages to avoid having sophisticated backward compatibility techniques and API guarantees.

Let me know which solution as a maintainer you prefer and I will see what I can do (or what I should do on my end to get the end result I need).

[seanmonstar]

I think so far, I don't want to add and maintain such a trait to hyper directly. So, I'd postpone adding this without more input and need from others. I'll convert this to a discussion in the meantime.