Okio adapters

[BoD]

Now that #131 is done (and with more work down the road to stabilize and make it full featured), this library should eventually become a good alternative to Okio.

Given that Okio is very popular, we can expect that the 2 libraries will cohabit for a while. Making adapters to go from one to the other would help with the transition period.

Things like fun okio.Sink.asKotlinxIoRawSink(): kotlinx.io.RawSink, fun kotlinx.io.RawSource.asOkioSource(): okio.Source, etc.

[fzhinkin]

@BoD thank you for the suggestion!
Do you already have a project where both libraries could be used simultaneously (or maybe a project where you want to try kotlinx-io, but which depends on some third-party library accepting Okio interfaces)?
While the proposal sounds reasonable, I'd wait until actual cases where someone needs the interop with Okio to understand actual needs better.

[BoD]

I don't have a specific need at the moment. I work on Apollo Kotlin, which exposes a few Okio symbols in its API. As of today this has been working well for us and our users. But I can imagine a future where Kotlinx-io becomes prevalent, and then the question will arise for us to decide whether we should switch - which will impact our users.

If there is an easy way to transition (i.e, use a new version of Apollo Kotlin that uses Kotlinx-io, but keep using Okio in the project, by 'converting' the symbols as needed), this will help this decision.

This reminds me a bit of the Coroutines to Rx adapters, which helped people transition.

I agree that this certainly not urgent for now. (Although, this may help the adoption of Kotlinx-io?)

[saket]

@fzhinkin I've worked on three projects that use ktor, and its lack of interoperability with okio has been… inconvenient. I was hopeful that things would change when ktor prepares to adopt kotlinx-io, but it feels odd that this issue hasn't received any attention, especially considering that kotlinx-io was forked from okio.

We've had a substantial ecosystem of libraries that work with okio, even before the first version of ktor was released. While most of these libraries were historically limited to the JVM, we're increasingly seeing many of them slowly move towards multiplatform since okio added support for it. It's not too hard to imagine projects gradually adopting ktor for their networking code without breaking compatibility with other parts of the app that use okio.

Here are two examples I can recall off the top of my head:

I'm using ksoup in one of my libraries that accepts okio primitives for parsing HTML. I would like to introduce support for Kotlin multiplatform, but I'm struggling with how to convert my ByteReadChannel to okio.Source.

In another project where I use ktor to download files and save them to disk, I rely on modernstorage for managing files on Android. Because it exclusively works with okio APIs, I had to manually write bridging APIs from ByteReadChannel to okio.Sink and ByteWriteChannel to okio.Source.

[joffrey-bion]

I have this need in Krossbow. It's a STOMP library built on top of multiple interchangeable web socket implementations (very much like Ktor, which is actually one of the supported WS implementations). And OkHttp is also one of the web socket implementations (directly adapted to Krossbow, not through Ktor).

I'm in the process of migrating all the internals of my library from okio to kotlinx-io, and some public APIs from ByteArray to kotlinx-io's ByteString.

When writing the OkHttp engine bindings, it would be great not to have to copy bytes around from Okio buffers to kotlinx-io buffers.

[fzhinkin]

Currently looking at what functions could be provided.
Seems like the following should be sufficient to start with:

fun kotlinx.io.RawSource.asOkioSource(): okio.Source
fun kotlinx.io.RawSink.asOkioSink(): okio.Sink

fun okio.Sink.asKotlinxIoRawSink(): kotlinx.io.RawSink
fun okio.Source.asKotlinxIoRawSource(): kotlinx.io.RawSource

fun okio.ByteString.toKotlinxIoByteString(): kotlinx.io.ByteString
fun kotlinx.io.ByteString.toOkioByteString(): okio.ByteString

// These two only as a way to reduce a conversion overhead 
fun okio.BufferedSink.write(buffer: kotlinx.io.Buffer, byteCount: Long)
fun kotlinx.io.Sink.write(buffer: okio.Buffer, byteCount: Long)

Is there anything else worth supporting out of the box?

[BoD]

These look good to me!

[JakeWharton]

I have a hard time seeing where you'd use the last two anywhere except as implementation for the first six. Not that it hurts to expose them or anything.

[fzhinkin]

I have a hard time seeing where you'd use the last two anywhere except as implementation for the first six.

I was considering them as an option for those who want to abstain from allocating new wrappers, but we can start without them and see how it goes.