Should Source.buffer be @UnsafeIoApi instead of @InternalIoApi?

[JakeWharton]

I'm writing an inner-loop parser around a Source that does various look-ahead operations to determine delimiters for a sequence of bytes and then processes it. Since this delimiter always terminates a sequence, I know that all bytes are available within Source.buffer, and can use UnsafeBufferOperations to more efficiently parse out the sequence members.

Currently, however, Source.buffer is marked as "internal" rather than "unsafe" which (somewhat) prevents me from using it. The whole library is not stable yet, so for now I can rely on unsafe things, but I was curious if this was an oversight or if there was larger reasoning for it being unsafe.

[JakeWharton]

Or maybe we need a Source.readInternalBuffer for symmetry with Sink.writeInternalBuffer?

[fzhinkin]

Or maybe we need a Source.readInternalBuffer for symmetry with Sink.writeInternalBuffer?

We definitely should!

Now it clear that there's no other way to implement a custom extension reading/writing something from Sink/Source other than by accessing the buffer, so it might be worth also promoting it to UnsafeIoApi.

However, by making buffer public (well, it already is, but InternalIoApi leaves us a way to remove it from the API) we can no longer provide alternative buffered sinks and sources that use something else for bufferization. For instance, we can support memory mapped files by implementing Sink/Source interfaces, but using file descriptor/MappedByteBuffer/pointer as a buffer, instead of Buffer.

[JakeWharton]

Now it clear that there's no other way to implement a custom extension reading/writing something from Sink/Source other than by accessing the buffer, so it might be worth also promoting it to UnsafeIoApi.

Yeah I very quickly ran into that case too, writing an indexOfFirst(predicate: (Byte) -> Boolean) almost immediately after filing this issue.