size_hint returns incorrect delta for truncated frames

[Shourya742]

Sv2Frame::size_hint is documented to return:

• 0 when the frame length matches the header,
• a negative value when bytes are missing,
• a positive value when extra bytes are present.

However, when the header parses successfully but the payload is shorter than expected, the function returns an incorrect positive value instead of a negative delta.

The current implementation computes:

(bytes.len() - Header::SIZE) as isize + header.len() as isize

This produces a positive result even when bytes are missing.

[Shourya742]

The semantics related to size_hint are a bit confusing right now. If you think about the lifecycle of resolving a frame from a byte stream, it’s essentially about receiving bytes until enough data arrives to complete the frame. In that process, there are four possible cases:

1. Incomplete header
   When the bytes in the buffer are fewer than Header::SIZE (6 bytes), the function returns the number of bytes required to complete the header:
   (Header::SIZE - bytes.len()).
   This part is clear.

2. Header complete, payload exact
   If the buffer contains more than Header::SIZE bytes and the remaining bytes
   (bytes.len() - Header::SIZE) exactly match the payload length, the function returns 0.
   This is correct.

3. Header complete, payload incomplete
   If the remaining bytes are fewer than required to complete the frame, the function should indicate how many bytes are still missing.

4. Header complete, payload exceeds expected size
   If there are more bytes than required, the function should indicate the surplus.

Currently, when the payload is larger than expected, the function returns a positive value that does not correctly account for whether the payload is larger or smaller. In cases where the payload is smaller, it still produces the same kind of result.

At the same time, the return type of size_hint is isize, which suggests it is intended to convey semantics using sign: negative for missing bytes and positive for extra bytes. However, the current implementation does not follow this convention.

Even beyond the incorrect calculation, representing leading or trailing bytes using +/- signs can be misleading. The documentation states that if the bytes are fewer than required, size_hint should return a negative value, and if there are extra bytes, it should return a positive value. The current implementation does not follow this behavior.

Ideally, we should use an enum to represent the possible states of the frame stream more explicitly, for example:

enum SizeHint {
    Leading(U24),
    Trailing(U24),
    Exact,
}

This would make the implementation clearer and easier to reason about.

cc: @plebhash as you wrote the doc

[plebhash]

thanks for flagging this

cc: @plebhash as you wrote the doc

those docs were my best-effort at understanding the APIs, but I remember being very confused while writing them and there's definitely room for inaccuracies and human-noise there

what's the path forward? IIUC we need to patch the source and update/refine docs?

would this be a breaking API change?

[Fi3]

since it works I would just update the docs, seems an easier (and way less risky) change to me. But not opposed to use an enum here.

[GitGab19]

Reminder about enabling ignored tests once this is tackled: #2085 (comment)