Improve API consistency and docs. (#228)

* Improve API consistency and docs.

* Change most APIs to use `IOException` as the error type instead
  of `Exception`. Non-IO exceptions are now considered defects as
  they only occur due to misuse of the API.
* Similarly change incorrect `Buffer` usage errors to be defects
  instead of failures.
* The `Async*` classes still use `Exception` for the error type
  for now, as the NIO Javadocs are vague as to what kind of
  exceptions to expect from these.
* Rename various read and write methods so they match the
  underlying NIO methods. Seems clearer.
* Add various Scaladocs (more still needed).
* Use `Option` to indicate end-of-stream when reading,
  instead of `-1` magic value.

* Improvements to InetSocketAddress.

* fmt

* Improve end-of-stream handling.

End-of-stream is now handled in a consistent way across all read APIs.
If a read encounters end-of-stream, the effect will fail with a
`java.io.EOFException`.

* Rebase onto ZIO 1.0.

docs/essentials/files.md

@@ -30,12 +30,12 @@ Reading and writing is performed as effects where raw `Byte` content is wrapped
 ```scala mdoc:silent
 val readWriteOp = (channel: AsynchronousFileChannel) =>
   for {
-    chunk <- channel.read(20, 0)
+    chunk <- channel.readChunk(20, 0L)
     text  = chunk.map(_.toChar).mkString
     _     <- putStrLn(text)
 
     input = Chunk.fromArray("message".toArray.map(_.toByte))
-    _     <- channel.write(input, 0)
+    _     <- channel.writeChunk(input, 0L)
   } yield ()
 ```
 

docs/essentials/sockets.md

@@ -32,7 +32,7 @@ val server = AsynchronousServerSocketChannel()
 def doWork(channel: AsynchronousSocketChannel): ZIO[Console with Clock, Throwable, Unit] = {
   val process =
     for {
-      chunk <- channel.read(3)
+      chunk <- channel.readChunk(3)
       str = chunk.toArray.map(_.toChar).mkString
       _ <- putStrLn(s"received: [$str] [${chunk.length}]")
     } yield ()
@@ -59,7 +59,7 @@ Reading and writing to socket:
 ```scala mdoc:silent
 for {
   serverFiber <- server.fork
-  clientFiber <- clientM.use(_.write(Chunk.fromArray(Array(1, 2, 3).map(_.toByte)))).fork
+  clientFiber <- clientM.use(_.writeChunk(Chunk.fromArray(Array(1, 2, 3).map(_.toByte)))).fork
   _           <- clientFiber.join
   _           <- serverFiber.join
 } yield ()

examples/src/main/scala/StreamsBasedServer.scala

@@ -41,7 +41,7 @@ object StreamsBasedServer extends App {
                 _    <- console.putStrLn("Received connection")
                 data <- ZStream
                           .fromEffectOption(
-                            channel.read(64).tap(_ => console.putStrLn("Read chunk")).orElse(ZIO.fail(None))
+                            channel.readChunk(64).tap(_ => console.putStrLn("Read chunk")).orElse(ZIO.fail(None))
                           )
                           .flattenChunks
                           .take(4)