1Change Log 2========== 3 4## Version 3.7.0 5 6_2023-12-16_ 7 8 * New: `Timeout.cancel()` prevents a timeout from firing. 9 * Breaking: Drop the `watchosX86` Kotlin/Native target. From [the Kotlin blog][watchosX86], 10 _‘This is an obsolete simulator for Intel Macs. Use the watchosX64 target instead.’_ 11 * New: Add the `watchosDeviceArm64` Kotlin/Native target. 12 * New: `Timeout` APIs that accept `kotlin.time.Duration`. 13 * Upgrade: [Kotlin 1.9.21][kotlin_1_9_21]. 14 15 16## Version 3.6.0 17 18_2023-10-01_ 19 20 * Fix: Don't leak file handles when using `metadata` functions on `ZipFileSystem`. We had a bug 21 where we were closing the `.zip` file, but not a stream inside of it. We would have prevented 22 this bug if only we’d used `FakeFileSystem.checkNoOpenFiles()` in our tests! 23 * Fix: Don't build an index of a class loader's resources in `ResourceFileSystem.read()`. This 24 operation doesn't need this index, and building it is potentially expensive. 25 * New: Experimentally support Linux on ARM64 for Kotlin/Native targets (`linuxArm64`). Note that 26 we haven't yet added CI test coverage for this platform. 27 * Upgrade: [Kotlin 1.9.10][kotlin_1_9_10]. 28 29 30## Version 1.17.6 31 32_2023-10-01_ 33 34 * Fix: Don't crash decoding GZIP files when the optional extra data (`XLEN`) is 32 KiB or larger. 35 36 37## Version 3.5.0 38 39_2023-08-02_ 40 41 * New: Support the WebAssembly (WASM) platform. Okio's support for WASM is experimental, but 42 improving, just like Kotlin's own support for WASM. 43 * New: Adapt WebAssembly System Interface (WASI) API's as an Okio FileSystem using 44 `WasiFileSystem`. This is in the new `okio-wasifilesystem` module. It requires the [preview1] 45 WASI API. We’ll make backwards-incompatible upgrades to new WASI API versions as they become 46 available. 47 * Fix: Return relative paths in the NIO adapter FileSystem when required. `FileSystem.list()` 48 had always returned absolute paths, even when the target directory was supplied as a relative 49 path. 50 * Fix: Don't crash when reading into an empty array using `FileHandle` on Kotlin/Native. 51 * Upgrade: [Kotlin 1.9.0][kotlin_1_9_0]. 52 53 54## Version 3.4.0 55 56_2023-07-07_ 57 58 * New: Adapt a Java NIO FileSystem (`java.nio.file.FileSystem`) as an Okio FileSystem using 59 `fileSystem.asOkioFileSystem()`. 60 * New: Adapt Android’s `AssetManager` as an Okio FileSystem using `AssetFileSystem`. This is in the 61 new `okio-assetfilesystem` module. Android applications should prefer this over 62 `FileSystem.RESOURCES` as it’s faster to load. 63 * Fix: Don't crash decoding GZIP files when the optional extra data (`XLEN`) is 32 KiB or larger. 64 * Fix: Resolve symlinks in `FakeFileSystem.canonicalize()`. 65 * Fix: Report the correct `createdAtMillis` in `NodeJsFileSystem` file metadata. We were 66 incorrectly using `ctimeMs`, where `c` means _changed_, not _created_. 67 * Fix: `UnsafeCursor` is now `Closeable`. 68 69 70## Version 3.3.0 71 72_2023-01-07_ 73 74 * Fix: Don't leak resources when `use {}` is used with a non-local return. We introduced this 75 performance and stability bug by not considering that non-local returns execute neither the 76 `return` nor `catch` control flows. 77 * Fix: Use a sealed interface for `BufferedSink` and `BufferedSource`. These were never intended 78 for end-users to implement, and we're happy that Kotlin now allows us to express that in our API. 79 * New: Change internal locks from `synchronized` to `ReentrantLock` and `Condition`. We expect this 80 to improve help when using Okio with Java virtual threads ([Project Loom][loom]). 81 * Upgrade: [Kotlin 1.8.0][kotlin_1_8_0]. 82 83 84## Version 3.2.0 85 86_2022-06-26_ 87 88 * Fix: Configure the multiplatform artifact (`com.squareup.okio:okio:3.x.x`) to depend on the 89 JVM artifact (`com.squareup.okio:okio-jvm:3.x.x`) for Maven builds. This should work-around an 90 issue where Maven doesn't interpret Gradle metadata. 91 * Fix: Change `CipherSource` and `CipherSink` to recover if the cipher doesn't support streaming. 92 This should work around a crash with AES/GCM ciphers on Android. 93 * New: Enable compatibility with non-hierarchical projects. 94 95 96## Version 3.1.0 97 98_2022-04-19_ 99 100 * Upgrade: [Kotlin 1.6.20][kotlin_1_6_20]. 101 * New: Support [Hierarchical project structure][hierarchical_projects]. If you're using Okio in a 102 multiplatform project please upgrade your project to Kotlin 1.6.20 (or newer) to take advantage 103 of this. With hierarchical projects it's easier to use properties like `FileSystem.SYSTEM` that 104 are available on most Okio platforms but not all of them. 105 * New: `ForwardingSource` is now available on all platforms. 106 * New: The `watchosX64` platform is now supported. 107 * Fix: Don't crash in `NSData.toByteString()' when the input is empty. 108 * Fix: Support empty ZIP files in `FileSystem.openZip()`. 109 * Fix: Throw in `canonicalize()` of ZIP file systems if the path doesn't exist. 110 * Fix: Don't require ZIP files start with a local file header. 111 * New: `okio.ProtocolException` is a new exception type for multiplatform users. (It is aliased to 112 `java.net.ProtocolException` on JVM platforms). 113 114 115## Version 3.0.0 116 117_2021-10-28_ 118 119This is the first stable release of Okio 3.x. This release is strongly backwards-compatible with 120Okio 2.x, and the new major version signifies new capabilities more than it does backwards 121incompatibility. 122 123Most users should be able to upgrade from 2.x by just changing the version. If you're using Okio 124in a Kotlin Multiplatform project, you'll need to drop the `-multiplatform` suffix in your Gradle 125dependencies. 126 127 * New: Remove `@ExperimentalFileSystem`. This annotation is no longer necessary as the file system 128 is no longer experimental! 129 * New: Path no longer aggressively normalizes `..` segments. Use `Path.normalize()` to apply these 130 based on the content of the path, or `FileSystem.canonicalize()` to do it honoring any symlinks 131 on a particular file system. 132 * New: Publish a [bill of materials (BOM)][bom] for Okio. Depend on this from Gradle or Maven to 133 keep all of your Okio artifacts on the same version, even if they're declared via transitive 134 dependencies. You can even omit versions when declaring other Okio dependencies. 135 136 ```kotlin 137 dependencies { 138 api(platform("com.squareup.okio:okio-bom:3.0.0")) 139 api("com.squareup.okio:okio") // No version! 140 api("com.squareup.okio:okio-fakefilesystem") // No version! 141 } 142 ``` 143 144 * New: `FileSystem.delete()` silently succeeds when deleting a file that doesn't exist. Use 145 the new `mustExist` parameter to trigger an exception instead. 146 * New: `FileSystem.createDirectories()` silently succeeds when creating a directory that already 147 exists. Use the new `mustCreate` parameter to trigger an exception instead. 148 * New: `FileSystem` offers Java-language overloads where appropriate. Previously functions that 149 had default parameters were potentially awkward to invoke from Java. 150 * New: `Timeout.intersectWith()` returns a value instead of `Unit`. This is a binary-incompatible 151 change. We expect that this public API is very rarely used outside of Okio itself. 152 * Fix: Change `BufferedSource.readDecimalLong()` to fail if the input value is just `-`. Previously 153 Okio incorrectly returned `0` for this. 154 155 156## Version 3.0.0-alpha.11 157 158_2021-10-23_ 159 160 * Upgrade: [Kotlin 1.5.31][kotlin_1_5_31]. 161 * Upgrade: [kotlinx-datetime 0.3.0][datetime_0_3_0]. (This is a dependency of `okio-fakefilesystem` 162 only.) 163 * New: Support creating and accessing symlinks. We were reluctant to include symlinks in our API 164 (to keep it small!) but decided that supporting them was essential to properly implement 165 recursive traversal. 166 * New: `FileMetadata.extras` can track metadata for custom `FileSystem` implementations. 167 * New: Support Apple Silicon Kotlin/Native targets (`macosArm64`, `iosSimulatorArm64`, 168 `tvosSimulatorArm64`, and `watchosSimulatorArm64`). 169 * New: `FileSystem.listRecursively()` returns a `Sequence` that includes all of a directory's 170 children, and all of their children recursively. The implementation does a lazy, depth-first 171 traversal. 172 * New: `Path.relativeTo()` computes how to get from one path to another. 173 * New: `Path.root` and `Path.segments`. These APIs decompose a path into its component parts. 174 * New: `FileSystem.listOrNull()` returns a directory's children, or null if the path doesn't 175 reference a readable directory. 176 * New: Option to fail if the file being updated doesn't already exist: `mustExist`. Use this to 177 avoid creating a new file when your intention is to update an existing file. 178 * New: Option to fail if a file being created already exists: `mustCreate`. Use this to avoid 179 updating an existing file when your intention is to create a new file. 180 * Fix: Restore support for Kotlin/JS on browser platforms. We were relying on NodeJS-only features 181 to fetch the local directory separator (`/` or `\`) and temporary directory. 182 * Fix: Don't ignore the caller's specified write offset running Okio on Kotlin/Native on Linux. 183 (`FileHandle.write()` was broken and always appended to the end of the file.) 184 185 186## Version 3.0.0-alpha.10 187 188_2021-09-09_ 189 190This release drops the `-multiplatform` suffix on Kotlin Multiplatform artifacts. All artifacts now 191share the same name (like `com.squareup.okio:okio:3.0.0-alpha.10`) for both Kotlin/JVM and Kotlin 192Multiplatform. 193 194 * Fix: Don't crash in `ResourceFileSystem` when classpath `.jar` files have special characters in 195 their paths. 196 197 198## Version 3.0.0-alpha.9 199 200_2021-08-01_ 201 202 * New: `ByteString.copyInto()` saves an allocation when extracting data from a `ByteString`. 203 * Fix: Create `FileHandle.protectedSize()` to match other abstract functions. 204 * Fix: Open files in binary mode on Windows. Without this, files that contain `0x1a` will be 205 truncated prematurely. 206 207 208## Version 3.0.0-alpha.8 209 210_2021-07-13_ 211 212 * Fix: Don't crash on duplicate entries in a .zip file. 213 * Fix: Change `FileSystem.RESOURCES` to initialize itself lazily. 214 215 216## Version 3.0.0-alpha.7 217 218_2021-07-12_ 219 220 * Fix: Change `ResourceFileSystem` to load roots eagerly. We had a bug where `list()` on the root 221 returned an empty list even if resources were present. 222 * New: `FileHandle.reposition()` can seek on a source or sink returned by that `FileHandle`. 223 * New: Move the system resources instance to `FileSystem.RESOURCES`. 224 * Upgrade: [Kotlin 1.5.20][kotlin_1_5_20]. 225 226 227## Version 3.0.0-alpha.6 228 229_2021-06-01_ 230 231 * New: `FileHandle` supports random access reads, writes, and resizes on files. Create an instance 232 with `FileSystem.openReadOnly()` or `FileSystem.openReadWrite()`. 233 * New: Remove `Cursor` which is obsoleted by `FileHandle`. (`UnsafeCursor` is still around!) 234 * New: Add support for the new intermediate representation (IR) artifacts in Kotlin/JS. We still 235 support the legacy artifact format. 236 * New: Support tvOS (tvosArm64, tvosX64) in multiplatform. 237 * New: Change `ResourceFileSystem` to omit `.class` files when indexing `.zip` files. We expect 238 this to lower the memory footprint of `ResourceFileSystem`. 239 * Fix: Don't crash on background thread access in Kotlin/Native. We had to apply `@SharedImmutable` 240 and run our test suite on a background thread. 241 242 243## Version 3.0.0-alpha.5 244 245_2021-04-27_ 246 247 * New: Promote the `ZipFileSystem` and `ResourceFileSystem` to the main Okio module. These are 248 currently JVM-only. The `okio-zipfilesystem` module is no longer published. 249 250 251## Version 3.0.0-alpha.4 252 253_2021-04-14_ 254 255 * Fix: Rename internal classes to avoid name collisions. We were seeing problems due to having 256 multiple files named `-Platform.kt`. 257 258 259## Version 3.0.0-alpha.3 260 261_2021-04-06_ 262 263 * New: Move `NodeJsFileSystem` into its own module. Having it built-in prevented Okio from working 264 in a browser where there's no synchronous file system API. This is in the `okio-nodefilesystem` 265 artifact. 266 267 268## Version 3.0.0-alpha.2 269 270_2021-03-24_ 271 272 * New: Require Java 8+ for Okio 3.x. 273 * New: `Cursor` supports random access reads on a `Source`. 274 * New: `FileSystem.openZip(path)` returns a file system backed by a `.zip` file. This is in the 275 `okio-zipfilesystem` artifact. 276 277 278## Version 3.0.0-alpha.1 279 280_2021-01-07_ 281 282* New: Experimental file system API. The `Path`, `FileMetadata`, `FileSystem` and 283 `ForwardingFileSystem` types are subject to API changes in a future release. 284* New: Experimental `okio-fakefilesystem` artifact. 285 286 287## Version 2.10.0 288 289_2021-01-07_ 290 291* New: Support Windows (mingwX64) in multiplatform. 292* New: Support watchOS (watchosArm32, watchosArm64, watchosX86) in multiplatform. 293* New: Support `HashingSource`, `HashingSink`, buffer hash functions, and `UnsafeCursor` on non-JVM 294 platforms. Previously these were all JVM-only. 295* New: Implement `Closeable` on `Sink` and `Source` on non-JVM platforms. Okio now includes a 296 multiplatform `okio.Closeable` interface and corresponding `use {}` extension. Closing resources 297 when you're done with them shouldn't be JVM-only! 298* New: `Sink.hashingSink` and `Source.hashingSource` functions that accept 299 `java.security.MessageDigest` and `javax.crypto.Mac` instances. Use these when your hash function 300 isn't built-in. 301* Fix: Don't crash with a `ShortBufferException` in `CipherSink` and `CipherSource` on Android. 302 (Android may throw a `ShortBufferException` even if the buffer is not too short. We now 303 avoid this problem!) 304* Upgrade: [Kotlin 1.4.20][kotlin_1_4_20]. 305 306 307## Version 2.9.0 308 309_2020-10-04_ 310 311 * Fix: Don't corrupt the `Buffer` when writing a slice of a segmented `ByteString`. We had a severe 312 bug where `ByteString` instances created with `snapshot()` and `readByteString()` incorrectly 313 adjusted the buffer's size by their full length, not the length of the slice. This would have 314 caused buffer reads to crash! We do not believe data was silently corrupted. 315 * New: `CipherSink` and `CipherSource`. Use these with `javax.crypto.Cipher` to encrypt and decrypt 316 streams of data. This is a low-level encryption API; most applications should use higher-level 317 APIs like TLS when available. 318 * New: Promote hash functions `md5`, `sha1()`, `sha512()`, and `sha256()` to common Kotlin. These 319 are currently only available on `ByteString`, multiplatform support for `HashingSource`, 320 `HashingSink`, and `Buffer` should come in a follow-up release. We wrote and optimized our own 321 implementations of these hash functions in Kotlin. On JVM and Android platforms Okio still uses 322 the platform's built-in hash functions. 323 * New: Support OSGi metadata. 324 * Upgrade: [Kotlin 1.4.10][kotlin_1_4_10]. 325 326 327## Version 2.8.0 328 329_2020-08-17_ 330 331 * New: Upgrade to Kotlin 1.4.0. 332 333 334## Version 2.7.0 335 336_2020-07-07_ 337 338 * New: `Pipe.cancel()` causes in-progress and future reads and writes on the pipe to immediately 339 fail with an `IOException`. The streams may still be canceled normally. 340 341 * New: Enlarge Okio's internal segment pool from a fixed 64 KiB total to 64 KiB per processor. For 342 example, on an Intel i9 8-core/16-thread machine the segment pool now uses up to 1 MiB of memory. 343 344 * New: Migrate from `synchronized` to lock-free when accessing the segment pool. Combined with the 345 change above we saw throughput increase 3x on a synthetic benchmark designed to create 346 contention. 347 348 349## Version 2.6.0 350 351_2020-04-22_ 352 353 * New: `InflaterSource.readOrInflate()` is like `InflaterSource.read()`, except it will return 0 if 354 consuming deflated bytes from the underlying stream did not produce new inflated bytes. 355 356 357## Version 2.5.0 358 359_2020-03-20_ 360 361 * New: Upgrade to Kotlin 1.3.70. 362 363 364## Version 2.4.3 365 366_2019-12-20_ 367 368 * New: Upgrade to Kotlin 1.3.61. 369 370 371## Version 2.4.2 372 373_2019-12-11_ 374 375 * Fix: Don't crash when an `InputStream` source is exhausted exactly at a buffer segment boundary. 376 We had a bug where a sequence of reads could violate a buffer's invariants, and this could result 377 in a crash when subsequent reads encountered an unexpected empty segment. 378 379 380## Version 1.17.5 381 382_2019-12-11_ 383 384 * Fix: Don't crash when an `InputStream` source is exhausted exactly at a buffer segment boundary. 385 We had a bug where a sequence of reads could violate a buffer's invariants, and this could result 386 in a crash when subsequent reads encountered an unexpected empty segment. 387 388 389## Version 2.4.1 390 391_2019-10-04_ 392 393 * Fix: Don't cache hash code and UTF-8 string in `ByteString` on Kotlin/Native which prevented freezing. 394 395## Version 2.4.0 396 397_2019-08-26_ 398 399 * New: Upgrade to Kotlin 1.3.50. 400 401 402## Version 2.3.0 403 404_2019-07-29_ 405 406**This release changes our build from Kotlin-JVM to Kotlin-multiplatform (which includes JVM).** 407Both native and JavaScript platforms are unstable preview releases and subject to 408backwards-incompatible changes in forthcoming releases. 409 410To try Okio in a multiplatform project use this Maven coordinate: 411 412```kotlin 413api('com.squareup.okio:okio-multiplatform:2.3.0') 414``` 415 416You’ll also need to [enable Gradle metadata][gradle_metadata] in your project's settings. The 417artifact name for JVM projects has not changed. 418 419 * New: Upgrade to Kotlin 1.3.40. 420 * Fix: Use Gradle `api` instead of `implementation` for the kotlin-stdlib dependency. 421 * Fix: Don't block unless strictly necessary in `BufferedSource.peek()`. 422 423## Version 1.17.4 424 425_2019-04-29_ 426 427 * Fix: Don't block unless strictly necessary in `BufferedSource.peek()`. 428 429 430## Version 2.2.2 431 432_2019-01-28_ 433 434 * Fix: Make `Pipe.fold()` close the underlying sink when necessary. 435 436 437## Version 1.17.3 438 439_2019-01-28_ 440 441 * Fix: Make `Pipe.fold()` close the underlying sink when necessary. 442 443 444## Version 1.17.2 445 446_2019-01-17_ 447 448 * Fix: Make `Pipe.fold()` flush the underlying sink. 449 450 451## Version 2.2.1 452 453_2019-01-17_ 454 455 * Fix: Make `Pipe.fold()` flush the underlying sink. 456 457 458## Version 2.2.0 459 460_2019-01-16_ 461 462 * New: `Throttler` limits sources and sinks to a maximum desired throughput. Multiple sources and 463 sinks can be attached to the same throttler and their combined throughput will not exceed the 464 desired throughput. Multiple throttlers can also be used on the same source or sink and they will 465 all be honored. 466 467 * New: `Pipe.fold()` replaces the actively-readable `Source` with a passively-writable `Sink`. 468 This can be used to forward one sink to a target that is initially undetermined. 469 470 * New: Optimize performance of ByteStrings created with `Buffer.snapshot()`. 471 472 473## Version 1.17.1 474 475_2019-01-16_ 476 477 * Fix: Make the newly-backported `Pipe.fold()` public. 478 479 480## Version 1.17.0 481 482_2019-01-16_ 483 484 * New: Backport `Pipe.fold()` to Okio 1.x. 485 486 487## Version 1.16.0 488 489_2018-10-08_ 490 491 * New: Backport `BufferedSource.peek()` and `BufferedSource.getBuffer()` to Okio 1.x. 492 * Fix: Enforce timeouts when closing `AsyncTimeout` sources. 493 494 495## Version 2.1.0 496 497_2018-09-22_ 498 499 * New: `BufferedSource.peek()` returns another `BufferedSource` that reads ahead on the current 500 source. Use this to process the same data multiple times. 501 502 * New: Deprecate `BufferedSource.buffer()`, replacing it with either `BufferedSource.getBuffer()` 503 (in Java) or `BufferedSource.buffer` (in Kotlin). We have done likewise for `BufferedSink`. 504 When we introduced the new extension method `Source.buffer()` in Okio 2.0 we inadvertently 505 collided with an existing method. This fixes that. 506 507 * New: Improve performance of `Buffer.writeUtf8()`. This comes alongside initial implementation of 508 UTF-8 encoding and decoding in JavaScript which [uses XOR masks][xor_utf8] for great performance. 509 510 511## Version 2.0.0 512 513_2018-08-27_ 514 515This release commits to a stable 2.0 API. Read the 2.0.0-RC1 changes for advice on upgrading from 5161.x to 2.x. 517 518We've also added APIs to ease migration for Kotlin users. They use Kotlin's `@Deprecated` annotation 519to help you change call sites from the 1.x style to the 2.x style. 520 521 522## Version 2.0.0-RC1 523 524_2018-07-26_ 525 526Okio 2 is a major release that upgrades the library's implementation language from Java to Kotlin. 527 528Okio 2.x is **binary-compatible** with Okio 1.x and does not change any behavior. Classes and .jar 529files compiled against 1.x can be used with 2.x without recompiling. 530 531Okio 2.x is **.java source compatible** with Okio 1.x in all but one corner case. In Okio 1.x 532`Buffer` would throw an unchecked `IllegalStateException` when attempting to read more bytes than 533available. Okio 2.x now throws a checked `EOFException` in this case. This is now consistent with 534the behavior of its `BufferedSource` interface. Java callers that don't already catch `IOException` 535will now need to. 536 537Okio 2.x is **.kt source-incompatible** with Okio 1.x. This release adopts Kotlin idioms where they 538are available. 539 540| Java | Kotlin | Idiom | 541| :--------------------------------------- | :---------------------------------- | :----------------- | 542| Buffer.getByte() | operator fun Buffer.get() | operator function | 543| Buffer.size() | val Buffer.size | val | 544| ByteString.decodeBase64(String) | fun String.decodeBase64() | extension function | 545| ByteString.decodeHex(String) | fun String.decodeHex() | extension function | 546| ByteString.encodeString(String, Charset) | fun String.encode(Charset) | extension function | 547| ByteString.encodeUtf8(String) | fun String.encodeUtf8() | extension function | 548| ByteString.getByte() | operator fun ByteString.get() | operator function | 549| ByteString.of(ByteBuffer) | fun ByteBuffer.toByteString() | extension function | 550| ByteString.of(byte[], int, int) | fun ByteArray.toByteString() | extension function | 551| ByteString.read(InputStream, int) | fun InputStream.readByteString(Int) | extension function | 552| ByteString.size() | val ByteString.size | val | 553| DeflaterSink(Sink) | fun Sink.deflater() | extension function | 554| ForwardingSink.delegate() | val ForwardingSink.delegate | val | 555| ForwardingSource.delegate() | val ForwardingSource.delegate | val | 556| GzipSink(Sink, Deflater) | fun Sink.gzip() | extension function | 557| GzipSink.deflater() | val GzipSink.deflater | val | 558| GzipSource(Source) | fun Source.gzip() | extension function | 559| HashingSink.hash() | val HashingSink.hash | val | 560| HashingSource.hash() | val HashingSource.hash | val | 561| InflaterSink(Source) | fun Source.inflater() | extension function | 562| Okio.appendingSink(File) | fun File.appendingSink() | extension function | 563| Okio.blackhole() | fun blackholeSink() | top level function | 564| Okio.buffer(Sink) | fun Sink.buffer() | extension function | 565| Okio.buffer(Source) | fun Source.buffer() | extension function | 566| Okio.sink(File) | fun File.sink() | extension function | 567| Okio.sink(OutputStream) | fun OutputStream.sink() | extension function | 568| Okio.sink(Path) | fun Path.sink() | extension function | 569| Okio.sink(Socket) | fun Socket.sink() | extension function | 570| Okio.source(File) | fun File.source() | extension function | 571| Okio.source(InputStream) | fun InputStream.source() | extension function | 572| Okio.source(Path) | fun Path.source() | extension function | 573| Okio.source(Socket) | fun Socket.source() | extension function | 574| Pipe.sink() | val Pipe.sink | val | 575| Pipe.source() | val Pipe.source | val | 576| Utf8.size(String) | fun String.utf8Size() | extension function | 577 578Okio 2.x has **similar performance** to Okio 1.x. We benchmarked both versions to find potential 579performance regressions. We found one regression and fixed it: we were using `==` instead of `===`. 580 581Other changes in this release: 582 583 * New: Add a dependency on kotlin-stdlib. Okio's transitive dependencies grow from none in 1.x to 584 three in 2.x. These are kotlin-stdlib (939 KiB), kotlin-stdlib-common (104 KiB), and JetBrains' 585 annotations (17 KiB). 586 587 * New: Change Okio to build with Gradle instead of Maven. 588 589 590## Version 1.15.0 591 592_2018-07-18_ 593 594 * New: Trie-based `Buffer.select()`. This improves performance when selecting 595 among large lists of options. 596 * Fix: Retain interrupted state when throwing `InterruptedIOException`. 597 598 599## Version 1.14.0 600 601_2018-02-11_ 602 603 * New: `Buffer.UnsafeCursor` provides direct access to Okio internals. This API 604 is like Okio's version of Java reflection: it's a very powerful API that can 605 be used for great things and dangerous things alike. The documentation is 606 extensive and anyone using it should review it carefully before proceeding! 607 * New: Change `BufferedSource` to implement `java.nio.ReadableByteChannel` and 608 `BufferedSink` to implement `java.nio.WritableByteChannel`. Now it's a little 609 easier to interop between Okio and NIO. 610 * New: Automatic module name of `okio` for use with the Java Platform Module 611 System. 612 * New: Optimize `Buffer.getByte()` to search backwards when doing so will be 613 more efficient. 614 * Fix: Honor the requested byte count in `InflaterSource`. Previously this 615 class could return more bytes than requested. 616 * Fix: Improve a performance bug in `AsyncTimeout.sink().write()`. 617 618 619## Version 1.13.0 620 621_2017-05-12_ 622 623 * **Okio now uses `@Nullable` to annotate all possibly-null values.** We've 624 added a compile-time dependency on the JSR 305 annotations. This is a 625 [provided][maven_provided] dependency and does not need to be included in 626 your build configuration, `.jar` file, or `.apk`. We use 627 `@ParametersAreNonnullByDefault` and all parameters and return types are 628 never null unless explicitly annotated `@Nullable`. 629 630 * **Warning: this release is source-incompatible for Kotlin users.** 631 Nullability was previously ambiguous and lenient but now the compiler will 632 enforce strict null checks. 633 634 635## Version 1.12.0 636 637_2017-04-11_ 638 639 * **Fix: Change Pipe's sink.flush() to not block.** Previously closing a pipe's 640 sink would block until the source had been exhausted. In practice this 641 blocked the caller for no benefit. 642 * **Fix: Change `writeUtf8CodePoint()` to emit `?` for partial surrogates.** 643 The previous behavior was inconsistent: given a malformed string with a 644 partial surrogate, `writeUtf8()` emitted `?` but `writeUtf8CodePoint()` threw 645 an `IllegalArgumentException`. Most applications will never encounter partial 646 surrogates, but for those that do this behavior was unexpected. 647 * New: Allow length of `readUtf8LineStrict()` to be limited. 648 * New: `Utf8.size()` method to get the number of bytes required to encode a 649 string as UTF-8. This may be useful for length-prefixed encodings. 650 * New: SHA-512 hash and HMAC APIs. 651 652 653## Version 1.11.0 654 655_2016-10-11_ 656 657 * **Fix: The four-argument overload of `Buffer.writeString()` had a major bug 658 where it didn't respect offsets if the specified charset was UTF-8.** This 659 was because our short-circuit optimization omitted necessary offset 660 parameters. 661 * New: HMAC support in `HashingSource`, `HashingSink`, `ByteString`, and 662 `Buffer`. This makes it easy to create a keyed-hash message authentication 663 code (HMAC) wherever your data is. Unlike the other hashes, HMAC uses a 664 `ByteString` secret key for authentication. 665 * New: `ByteString.of(ByteBuffer)` makes it easier to mix NIO with Okio. 666 667 668## Version 1.10.0 669 670_2016-08-28_ 671 672 * Fix: Support reading files larger than 2 GiB with `GzipSource`. Previously 673 attempting to decompress such files would fail due to an overflow when 674 validating the total length. 675 * Fix: Exit the watchdog thread after being idle for 60 seconds. This should 676 make it possible for class unloaders to fully unload Okio. 677 * New: `Okio.blackhole()` returns a sink where all bytes written are discarded. 678 This is Okio's equivalent of `/dev/null`. 679 * New: Encode a string with any charset using `ByteString.encodeString()` and 680 decode strings in any charset using `ByteString.string()`. Most applications 681 should prefer `ByteString.encodeUtf8()` and `ByteString.utf8()` unless it's 682 necessary to support a legacy charset. 683 * New: `GzipSink.deflater()` makes it possible to configure the compression 684 level. 685 686 687## Version 1.9.0 688 689_2016-07-01_ 690 691 * New: `Pipe` makes it easy to connect a producer thread to a consumer thread. 692 Reads block until data is available to read. Writes block if the pipe's is 693 full. Both sources and sinks support timeouts. 694 * New: `BufferedSource.rangeEquals()` makes it easy to compare a range in a 695 stream to an expected value. This does the right thing: it blocks to load 696 the data required return a definitive result. But it won't block 697 unnecessarily. 698 * New: `Timeout.waitUntilNotified()` makes it possible to use nice timeout 699 abstractions on Java's built-in wait/notify primitives. 700 * Fix: Don't return incorrect results when `HashingSource` does large reads. 701 There was a bug where it wasn't traversing through the segments of the buffer 702 being hashed. This means that `HashingSource` was returning incorrect answers 703 for any writes that spanned multiple segment boundaries. 704 705## Version 1.8.0 706 707_2016-05-02_ 708 709 * New: `BufferedSource.select(Options)` API for reading one of a set of 710 expected values. 711 * New: Make `ByteString.toString()` and `Buffer.toString()` friendlier. 712 These methods return text if the byte string is valid UTF-8. 713 * New: APIs to match byte strings: `indexOf()`, `startsWith()`, and 714 `endsWith()`. 715 716## Version 1.7.0 717 718_2016-04-10_ 719 720 * New: Change the segment size to 8 KiB. This has been reported to dramatically 721 improve performance in some applications. 722 * New: `md5()`, `sha1()`, and `sha256()` methods on `Buffer`. Also add a 723 `sha1()` method on `ByteString` for symmetry. 724 * New: `HashingSource` and `HashingSink`. These classes are Okio’s equivalent 725 to the JDK’s `DigestInputStream` and `DigestOutputStream`. They offer 726 convenient `md5()`, `sha1()`, and `sha256()` factory methods to avoid an 727 impossible `NoSuchAlgorithmException`. 728 * New: `ByteString.asByteBuffer()`. 729 * Fix: Limit snapshot byte strings to requested size. 730 * Fix: Change write timeouts to have a maximum write size. Previously large 731 writes could easly suffer timeouts because the entire write was subject to a 732 single timeout. 733 * Fix: Recover from EBADF failures, which could be triggered by asynchronously 734 closing a stream on older versions of Android. 735 * Fix: Don't share segments if doing so only saves a small copy. This should 736 improve performance for all applications. 737 * Fix: Optimize `BufferedSource.indexOfElement()` and `indexOf(ByteString)`. 738 Previously this method had a bug that caused it to be very slow on large 739 buffers. 740 741## Version 1.6.0 742 743_2015-08-25_ 744 745 * New: `BufferedSource.indexOf(ByteString)` searches a source for the next 746 occurrence of a byte string. 747 * Fix: Recover from unexpected `AssertionError` thrown on Android 4.2.2 and 748 earlier when asynchronously closing a socket. 749 750## Version 1.5.0 751 752_2015-06-19_ 753 754 * Sockets streams now throw `SocketTimeoutException`. This builds on new 755 extension point in `AsyncTimeout` to customize the exception when a timeout 756 occurs. 757 * New: `ByteString` now implements `Comparable`. The comparison sorts bytes as 758 unsigned: {@code ff} sorts after {@code 00}. 759 760## Version 1.4.0 761 762_2015-05-16_ 763 764 * **Timeout exception changed.** Previously `Timeout.throwIfReached()` would 765 throw `InterruptedIOException` on thread interruption, and `IOException` if 766 the deadline was reached. Now it throws `InterruptedIOException` in both 767 cases. 768 * Fix: throw `EOFException` when attempting to read digits from an empty 769 source. Previously this would crash with an unchecked exception. 770 * New: APIs to read and write UTF-8 code points without allocating strings. 771 * New: `BufferedSink` can now write substrings directly, potentially saving an 772 allocation for some callers. 773 * New: `ForwardingTimeout` class. 774 775## Version 1.3.0 776 777_2015-03-16_ 778 779 * New: Read and write signed decimal and unsigned hexadecimal values in 780 `BufferedSource` and `BufferedSink`. Unlike the alternatives, these methods 781 don’t do any memory allocations! 782 * New: Segment sharing. This improves the runtime of operations like 783 `Buffer.clone()` and `Buffer.copyTo()` by sharing underlying segments between 784 buffers. 785 * New: `Buffer.snapshot()` returns an immutable snapshot of a buffer as a 786 `ByteString`. This builds on segment sharing so that snapshots are shallow, 787 immutable copies. 788 * New: `ByteString.rangeEquals()`. 789 * New: `ByteString.md5()` and `ByteString.sha256()`. 790 * New: `ByteString.base64Url()` returns URL-safe Base64. The existing 791 decoding method has been extended to support URL-safe Base64 input. 792 * New: `ByteString.substring()` returns a prefix, infix, or suffix. 793 * New: `Sink` now implements `java.io.Flushable`. 794 * Fix: `Buffer.write(Source, long)` now always writes fully. The previous 795 behavior would return as soon as any data had been written; this was 796 inconsistent with all other _write()_ methods in the API. 797 * Fix: don't leak empty segments in DeflaterSink and InflaterSource. (This was 798 unlikely to cause problems in practice.) 799 800## Version 1.2.0 801 802_2014-12-30_ 803 804 * Fix: `Okio.buffer()` _always_ buffers for better predictability. 805 * Fix: Provide context when `readUtf8LineStrict()` throws. 806 * Fix: Buffers do not call through the `Source` on zero-byte writes. 807 808## Version 1.1.0 809 810_2014-12-11_ 811 812 * Do UTF-8 encoding natively for a performance increase, particularly on Android. 813 * New APIs: `BufferedSink.emit()`, `BufferedSource.request()` and `BufferedSink.indexOfElement()`. 814 * Fixed a performance bug in `Buffer.indexOf()` 815 816## Version 1.0.1 817 818_2014-08-08_ 819 820 * Added `read(byte[])`, `read(byte[], offset, byteCount)`, and 821 `void readFully(byte[])` to `BufferedSource`. 822 * Refined declared checked exceptions on `Buffer` methods. 823 824 825## Version 1.0.0 826 827_2014-05-23_ 828 829 * Bumped release version. No other changes! 830 831## Version 0.9.0 832 833_2014-05-03_ 834 835 * Use 0 as a sentinel for no timeout. 836 * Make AsyncTimeout public. 837 * Remove checked exception from Buffer.readByteArray. 838 839## Version 0.8.0 840 841_2014-04-24_ 842 843 * Eagerly verify preconditions on public APIs. 844 * Quick return on Buffer instance equivalence. 845 * Add delegate types for Sink and Source. 846 * Small changes to the way deadlines are managed. 847 * Add append variant of Okio.sink for File. 848 * Methods to exhaust BufferedSource to byte[] and ByteString. 849 850## Version 0.7.0 851 852_2014-04-18_ 853 854 * Don't use getters in timeout. 855 * Use the watchdog to interrupt sockets that have reached deadlines. 856 * Add java.io and java.nio file source/sink helpers. 857 858## Version 0.6.1 859 860_2014-04-17_ 861 862 * Methods to read a buffered source fully in UTF-8 or supplied charset. 863 * API to read a byte[] directly. 864 * New methods to move all data from a source to a sink. 865 * Fix a bug on input stream exhaustion. 866 867## Version 0.6.0 868 869_2014-04-15_ 870 871 * Make ByteString serializable. 872 * New API: `ByteString.of(byte[] data, int offset, int byteCount)` 873 * New API: stream-based copy, write, and read helpers. 874 875## Version 0.5.0 876 877_2014-04-08_ 878 879 * Initial public release. 880 * Imported from OkHttp. 881 882 883[bom]: https://docs.gradle.org/6.2/userguide/platforms.html#sub:bom_import 884[datetime_0_3_0]: https://github.com/Kotlin/kotlinx-datetime/releases/tag/v0.3.0 885[gradle_metadata]: https://blog.gradle.org/gradle-metadata-1.0 886[hierarchical_projects]: https://kotlinlang.org/docs/multiplatform-hierarchy.html 887[kotlin_1_4_10]: https://github.com/JetBrains/kotlin/releases/tag/v1.4.10 888[kotlin_1_4_20]: https://github.com/JetBrains/kotlin/releases/tag/v1.4.20 889[kotlin_1_5_20]: https://github.com/JetBrains/kotlin/releases/tag/v1.5.20 890[kotlin_1_5_31]: https://github.com/JetBrains/kotlin/releases/tag/v1.5.31 891[kotlin_1_6_20]: https://blog.jetbrains.com/kotlin/2022/04/kotlin-1-6-20-released/ 892[kotlin_1_8_0]: https://kotlinlang.org/docs/whatsnew18.html 893[kotlin_1_9_0]: https://kotlinlang.org/docs/whatsnew19.html 894[kotlin_1_9_10]: https://github.com/JetBrains/kotlin/releases/tag/v1.9.10 895[kotlin_1_9_21]: https://github.com/JetBrains/kotlin/releases/tag/v1.9.21 896[loom]: https://wiki.openjdk.org/display/loom/Getting+started 897[maven_provided]: https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html 898[preview1]: https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/docs.md 899[watchosX86]: https://blog.jetbrains.com/kotlin/2023/02/update-regarding-kotlin-native-targets/ 900[xor_utf8]: https://github.com/square/okio/blob/bbb29c459e5ccf0f286e0b17ccdcacd7ac4bc2a9/okio/src/main/kotlin/okio/Utf8.kt#L302 901