New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Okio 2 #370

swankjesse opened this Issue Apr 17, 2018 · 8 comments


4 participants

swankjesse commented Apr 17, 2018

This is our design document for Okio 2.


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.


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.


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().


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.


This comment has been minimized.

yschimke commented Apr 17, 2018

Great timing, great decision. Is there any precedent for this in major open source libraries that can point to how seamless the transition is, I assume following

Also is the iOS OkHttp target valuable given swift-nio and on Android side cronet?

Given Kotlin's official Android support for the last year+ - “Skate to where the puck is going, not where it has been.”


This comment has been minimized.


swankjesse commented Apr 17, 2018

I don’t know about any similar efforts in other projects. I think we’ll borrow from how the Kotlin standard library interacts with JVM types.

I don't think iOS developers necessarily want another HTTP client! But I want to share networking code between platforms. This should help with that.


This comment has been minimized.

Tolriq commented Apr 27, 2018

Do you have plans to write any article about the problems found with interop ?

I'm finding

If we’re clever we can avoid duplicating APIs just because we started with Java.

quite hard to follow and I'm sure tips about that could help many :)


This comment has been minimized.


swankjesse commented Jul 16, 2018

Outstanding tasks

  • One more 1.x release with select()
  • Benchmark vs. 1.x with Moshi and fix any regressions found
  • Confirm we have nothing that prevents us from adopting Kotlin features (coroutines, native)
  • Blog post explaining decision
  • Migration guide from 1.x for Kotlin source
  • Buffer should throw IOExceptions not unchecked exceptions #458

This comment has been minimized.


swankjesse commented Jul 23, 2018

On benchmarks: I found & fixed a regression on using == instead of ===. Once that was fixed read & write performance were similar for Okio 1.x vs 2.x.


This comment has been minimized.


swankjesse commented Jul 24, 2018

Should we rename BufferedSource.require() for Kotlin callers? Perhaps source.demand(10)? The two require() methods are unambiguous to the compiler but potentially awkward to the reader.


This comment has been minimized.


Egorand commented Jul 25, 2018

Don't think this will lead to a lot of confusion, if only for the exception they throw (IllegalArgumentException vs EOFException), but that is documented in the method signature so should be fine. In any case, I'd try to avoid having two different method names for Java vs Kotlin callers, as it might be confusing when migrating a code base from Java to Kotlin.


This comment has been minimized.

@swankjesse swankjesse closed this Sep 4, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment