Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Okio 2

See original GitHub issue

This is our design document for Okio 2.

Goals

Okio 2 should be 100% API-compatible with Okio 1.x for Java uses of our library. This includes using the same Maven coordinates, the same package name, and an upwards-compatible API. We should use build tools to confirm this compatibility.

Okio 2 will be implemented in Kotlin! And it will depend on the Kotlin standard library. By implementing it in Kotlin we give ourselves the option to later support Kotlin/Native and Kotlin for JavaScript. We also give ourselves the option to later support coroutines.

Okio 2 should have equivalent performance to Okio 1. We may need to write careful Kotlin, paying attention to abstractions that have a runtime cost.

Non-Goals

We do not strive to be 100% API-compatible for .kt users of the library. For example, methods like Okio.source(File) might only be exposed as File.source() to Kotlin callers. If we’re clever we can avoid duplicating APIs just because we started with Java.

We will not support Kotlin/Native or Kotlin for JavaScript from the 2.0. Instead, we are happy to just have the option to build these in 2.1 or 2.2 or whatever.

We will not support coroutines from the 2.0. As above, we merely want the option of adding these later.

Tasks

We need to migrate from Maven to Gradle. Though Maven has served us quite well, Gradle is better supported for multiplatform projects. Part of this migration includes migrating our use of some Maven plugins like Animal Sniffer.

We need to figure out how to check binary compatibility with our existing APIs. We should keep our .java tests exactly as they are today, and add new tests for .kt callers. It is okay to have tests duplicated across two programming languages, especially since APIs may be exposed differently to each.

We should ship a multiplatform proof-of-concept. Perhaps this is supporting some subset of okio.ByteString in JavaScript.

We need to decide for each Kotlin-convenience method whether to duplicate (two ways to do the same thing), or find a way to offer the nicer Kotin form only. This might be difficult, particularly for methods like Source.buffer().

FAQ

Why Kotlin? Because it’s really good. It’s a wonderful language to build Java libraries and applications with. It has abstractions that make it possible to write code that is both compact and efficient.

Tell me more about Kotlin. We’d like to write code that runs on both iOS and Android, and Kotlin/Native is quite promising. Kotlin coroutines allow us to get the scalability of java.nio without ugliness.

But isn’t Kotlin just a trend? Not if we have anything to do with it. By doing Okio 2 in Kotlin we’re making a big commitment to the language, and we hope others will follow us here.

When will OkHttp/Retrofit/Moshi/Wire be migrated to Kotlin? No firm plans at the moment. But if we have success with coroutines in Okio, those libraries will want to take advantage. And it’d be really neat to get OkHttp working on iOS.

Can I stay on Okio 1.x forever? We’re hoping that you won’t have to. It’s our job to make Okio 2 compelling enough that the cost of this upgrade is justified. But we don’t indend to require Okio 2 in OkHttp and Retrofit until their next major revision.