Release 0.7.3

Author: adamw

README.md

@@ -21,13 +21,13 @@ preserving developer-friendly stack traces, and without compromising performance
 To use Ox, add the following dependency, using either [sbt](https://www.scala-sbt.org):
 
 ```scala
-"com.softwaremill.ox" %% "core" % "0.7.2"
+"com.softwaremill.ox" %% "core" % "0.7.3"
 ```
 
 Or [scala-cli](https://scala-cli.virtuslab.org):
 
 ```scala
-//> using dep "com.softwaremill.ox::core:0.7.2"
+//> using dep "com.softwaremill.ox::core:0.7.3"
 ```
 
 Documentation is available at [https://ox.softwaremill.com](https://ox.softwaremill.com), ScalaDocs can be browsed at [https://javadoc.io](https://www.javadoc.io/doc/com.softwaremill.ox).

generated-doc/out/basics/error-handling.md

@@ -127,7 +127,10 @@ val result: Either[String, Int] = either:
   if v1.ok() > 10 then 42 else "wrong".fail()
 ```
 
-An exception-throwing expression can be converted to an `Either` using the `.catching[E]` extension method:
+### Converting from exceptions
+
+An exception-throwing expression can be converted to an `Either` using the `.catching[E]` extension method (catches 
+only non-fatal exceptions!):
 
 ```scala
 import ox.either.catching
@@ -138,12 +141,37 @@ val result: Either[IllegalArgumentException, Int] =
     .catching[IllegalArgumentException]
 ```
 
-Arbitrary exception-throwing code can be converted to an `Either` using `catchingNonFatal`:
+Any `try-catch` blocks that you have in your code should be kept as small as possible, so that it's possibly obvious
+where the errors might originate. Using `.catching` at the sites where exceptions are thrown helps keeps the syntax
+lean and enables pinpointing where exceptions might occur.
+
+An alternative to an `either` block is an `either.catchAll` block which additionally catches any non-fatal exceptions 
+that occur when evaluating the nested expression. Within the block, both `.ok()` and `.fail()` can be used. The error
+type within such block is fixed to `Throwable`:
 
 ```scala
 import ox.either
+import ox.either.ok
+
+def doWork(): Either[Exception, Boolean] = ???
+
+val result: Either[Throwable, String] = either.catchAll:
+  if doWork().ok() then "ok" else throw new RuntimeException("not ok")
+```
+
+## Converting to exceptions
+
+For `Either` instances where the left-side is an exception, the right-value of an `Either` can be unwrapped using `.orThrow`.
+The exception on the left side is thrown if it is present:
+
+```scala
+import ox.either.orThrow
+
+val v1: Either[Exception, Int] = Right(10)
+assert(v1.orThrow == 10)
 
-val result: Either[Throwable, String] = either.catchingNonFatal(throw new RuntimeException("boom"))
+val v2: Either[Exception, Int] = Left(new RuntimeException("boom!"))
+v2.orThrow // throws RuntimeException("boom!")
 ```
 
 ### Nested `either` blocks
@@ -203,21 +231,6 @@ val outerResult: Either[Exception, Unit] = either:
 
 After this change refactoring `returnsEither` to return `Either[Exception, Int]` would yield a compile error on `returnsEither.ok()`.
 
-## Other `Either` utilities
-
-For `Either` instances where the left-side is an exception, the right-value of an `Either` can be unwrapped using `.orThrow`.
-The exception on the left side is thrown if it is present:
-
-```scala
-import ox.either.orThrow
-
-val v1: Either[Exception, Int] = Right(10)
-assert(v1.orThrow == 10)
-
-val v2: Either[Exception, Int] = Left(new RuntimeException("boom!"))
-v2.orThrow // throws RuntimeException("boom!")
-```
-
 ## Mapping errors
 
 When an `Either` is used to represent errors, these can be mapped by using `.left.map`. This can be used to entirely 

generated-doc/out/index.md

@@ -2,7 +2,7 @@
 
 Safe direct-style streaming, concurrency and resiliency for Scala on the JVM. Requires JDK 21+ & Scala 3.
 
-To start using Ox, add the `com.softwaremill.ox::core:0.7.2` [dependency](info/dependency.md) to your project. 
+To start using Ox, add the `com.softwaremill.ox::core:0.7.3` [dependency](info/dependency.md) to your project. 
 Then, take a look at the tour of Ox, or follow one of the topics listed in the menu to get to know Ox's API!
 
 In addition to this documentation, ScalaDocs can be browsed at [https://javadoc.io](https://www.javadoc.io/doc/com.softwaremill.ox).
@@ -92,6 +92,8 @@ In addition to this documentation, ScalaDocs can be browsed at [https://javadoc.
    integrations/mdc-logback
    integrations/cron4s
    integrations/otel-context
+   integrations/tapir
+   integrations/sttp-client
 
 .. toctree::
    :maxdepth: 2

generated-doc/out/info/dependency.md

@@ -4,10 +4,10 @@ To use ox core in your project, add:
 
 ```scala
 // sbt dependency
-"com.softwaremill.ox" %% "core" % "0.7.2"
+"com.softwaremill.ox" %% "core" % "0.7.3"
 
 // scala-cli dependency
-//> using dep com.softwaremill.ox::core:0.7.2
+//> using dep com.softwaremill.ox::core:0.7.3
 ```
 
 Ox core depends only on the Java [jox](https://github.com/softwaremill/jox) project, where channels are implemented. There are no other direct or transitive dependencies.

generated-doc/out/integrations/cron4s.md

@@ -3,7 +3,7 @@
 Dependency:
 
 ```scala
-"com.softwaremill.ox" %% "cron" % "0.7.2"
+"com.softwaremill.ox" %% "cron" % "0.7.3"
 ```
 
 This module allows to run schedules based on cron expressions from [cron4s](https://github.com/alonsodomin/cron4s).

generated-doc/out/integrations/kafka.md

@@ -3,7 +3,7 @@
 Dependency:
 
 ```scala
-"com.softwaremill.ox" %% "kafka" % "0.7.2"
+"com.softwaremill.ox" %% "kafka" % "0.7.3"
 ```
 
 `Flow`s which read from a Kafka topic, mapping stages and drains which publish to Kafka topics are available through

generated-doc/out/integrations/mdc-logback.md

@@ -3,7 +3,7 @@
 Dependency:
 
 ```scala
-"com.softwaremill.ox" %% "mdc-logback" % "0.7.2"
+"com.softwaremill.ox" %% "mdc-logback" % "0.7.3"
 ```
 
 Ox provides support for setting inheritable MDC (mapped diagnostic context) values, when using the [Logback](https://logback.qos.ch)

generated-doc/out/integrations/otel-context.md

@@ -3,7 +3,7 @@
 Dependency:
 
 ```scala
-"com.softwaremill.ox" %% "otel-context" % "0.7.2"
+"com.softwaremill.ox" %% "otel-context" % "0.7.3"
 ```
 
 When using the default OpenTelemetry context-propagation mechanisms, which rely on thread-local storage, the context

generated-doc/out/integrations/sttp-client.md

@@ -0,0 +1,14 @@
+# HTTP client using sttp
+
+[sttp-client](https://sttp.softwaremill.com) is a Scala HTTP client integrating with a number of Scala stacks, 
+including direct-style backends.
+
+The integration is included in the sttp-client library and includes:
+* synchronous backends, which are designed to work with direct-style Scala
+* streaming request & response bodies, converted to/from `Flow`s via `InputStream`s
+* interacting with WebSockets, either using the `WebSocket` interface directly, or using `Flow`s of web socket frames
+* receiving SSE streams as `Flow[ServerSentEvent]`
+
+For more details refer to the sttp-client documentation, specifically:
+* [synchronous backends documentation](https://sttp.softwaremill.com/en/latest/backends/synchronous.html)
+* [usage examples](https://sttp.softwaremill.com/en/latest/examples.html), tagged with the `Direct` label

generated-doc/out/integrations/tapir.md

@@ -0,0 +1,16 @@
+# HTTP server using Tapir
+
+[Tapir](https://tapir.softwaremill.com) is a library for rapidly developing HTTP APIs. It integrates with a number of 
+Scala stacks, including direct-style server interpreters.
+
+The integration is included in the Tapir library and includes:
+* exposing regular HTTP endpoints (consuming/producing JSON etc.)
+* streaming request & response bodies, converted to/from `Flow`s via `InputStream`s
+* web sockets represented as a transformation between incoming & outgoing `Flow`s of web socket frames
+* SSE response bodies
+
+For more details refer to the Tapir documentation, specifically:
+* the [netty-server-sync interpreter documentation](https://tapir.softwaremill.com/en/latest/server/netty.html)
+* [usage examples](https://tapir.softwaremill.com/en/latest/examples.html), tagged with the `Direct` label
+* [tutorials](https://tapir.softwaremill.com/en/latest/tutorials/01_hello_world.html), which mostly use the 
+  direct-style approach