Expose end-of-stream from channels

[mschuwalow]

Currently whenever we read from a channel and it returns -1, we fail with an IOException using https://github.com/zio/zio-nio/blob/master/nio-core/src/main/scala/zio/nio/core/package.scala#L15.

This can be very inconvenient when writing for example a streams-based consumer as it makes it impossible to differentiate between the socket getting closed and an error, without exploiting implementation details.
I propose we should instead model read as def read(b: ByteBuffer): IO[Option[IOException], Int], where fail(None) signals end of stream.

[quelgar]

This changed in #228, which is not in a release yet. The read method style is now def read(b: ByteBuffer): IO[IOException, Int], but in the case where we get -1 from the NIO read, the failure is an EOFException. So it is possible to differentiate the socket being closed, by catching EOFException, but you have to read the Scaladoc for read to know about it.

I also added an method eofOption you can use if you'd rather have the end-of-stream represented explicitly:

  /**
   * Turns `EOFException` failures into a success with no result.
   */
  def eofOption[R, A, E <: Throwable](effect: ZIO[R, E, A]): ZIO[R, E, Option[A]] =
    effect.asSome.catchSome {
      case _: EOFException => ZIO.none
    }

val maybeBytesRead: IO[IOException, Option[Int]] = eofOption(channel.read(buffer))

What do you think of this solution? Your version has the advantage that the end-of-stream is represented explicitly in the type, and will require explicit handling of some kind. This might be better overall, but I thought it might be annoying for code that doesn't need to specially handle end-of-stream.

I'd be happy to swap it around. Have read return IO[Option[IOException], Int], with a convenient way to turn that into IO[IOException, Int] where the None failure becomes an EOFException failure. Interested to hear opinions.

[mschuwalow]

I'm happy with that solution 👍
It could still be a bit inconvenient if you compose it with other code that could return an EOFException, but much better than before.

For eofOption I would prefer to have Option in the error channel, as we can save some allocations that way.
This was also the reason for having the option in the error channel in ZStream.Pull iirc.

[quelgar]

Yeah, using the error channel is a good idea, easy change.

[quelgar]

#255 switches to using the error channel to indicate end-of-stream, and I added a note to the docs about how it works.