Fix RingBuffer::extend_from_within_unchecked unsoundness

[paolobarbolini]

This fixes the unsoundness reported in #75 by correcting the src length math. Also adds safety and general comments, making it much easier to understand the logic.

The first commit fixes the vulnerability while the other commits cleanup the implementation and add two unrelated debug assertions.

Fixes #75

[StarStarJ]

Works for my workflow with this patch.

I don't know the code of this crate, so I cannot really help with a proper review.
But thanks for taking care :D

[KillingSpark]

Thanks so much for fixing this!

The text comments do add a lot of clarification. I find the diagrams a bit hard to read especially when they get to four lines of ^ markers.

Maybe something like this would be better?

|___HXXXSSSXXXXXXXTDD__|
H: Head position (first readable byte)
T: Tail position (first writeable byte)
X: Uninvolved bytes in the readable section
S: Source bytes, to be copied at the end of the buffer
D: Destination bytes, going to be written to by copying the source bytes
_: Uninvolved bytes in the writable section

|D__HXXXSSSSSSSXXXTDDDD|

|XXSSSSSXXXXXTDDDD__HXX|

|SSSXXTDDDD__HXXXXXXXSS|

[paolobarbolini]

What if we had something like this? To me it looks lighter on the eye.

// continuous data:
//
//            H           T
// Read:  ____XXXXSSSSXXXX________
// Write: ________________DDDD____
//
// H: Head position (first readable byte)
// T: Tail position (first writable byte)
// X: Uninvolved bytes in the readable section
// S: Source bytes, to be copied to D bytes
// D: Destination bytes, going to be copied from S bytes
// _: Uninvolved bytes in the writable section

[KillingSpark]

Yes! I think that's perfect

[paolobarbolini]

I think this is ready. I've tried adding Address Sanitizer and Memory Sanitizer to CI but they fail at linking:

test src/encoding/frame_encoder.rs - encoding::frame_encoder::FrameCompressor (line 44) ... FAILED
test src/frame_decoder.rs - frame_decoder::FrameDecoder (line 28) ... FAILED

[KillingSpark]

Thanks again for the quick action!