Rewrite README: update versions, trim boilerplate, add badges

Author: luksow

README.md

@@ -1,63 +1,50 @@
 # http4s-stir
 
-Welcome to http4s-stir, a library designed to bridge the gap between Pekko HTTP (Akka HTTP) and http4s. This README provides an overview of the library, its usage, project status, and more.
+[![Maven Central](https://img.shields.io/maven-central/v/pl.iterators/http4s-stir_3)](https://central.sonatype.com/artifact/pl.iterators/http4s-stir_3)
+[![CI](https://github.com/theiterators/http4s-stir/actions/workflows/ci.yml/badge.svg)](https://github.com/theiterators/http4s-stir/actions/workflows/ci.yml)
 
-http4s-stir offers [Pekko HTTP](https://github.com/apache/incubator-pekko-http)-style (Akka HTTP-style) DSL directives for [http4s](https://github.com/http4s/http4s) using cats-effect's IO as an effect system. About 85% of all directives have been ported. Some were omitted due to a lack of support in http4s, while others were modified to fit http4s' distinct architecture. For specifics, refer to the [Missing](#missing) section below.
+[Pekko HTTP](https://github.com/apache/incubator-pekko-http) (Akka HTTP) style DSL directives for [http4s](https://github.com/http4s/http4s) with cats-effect IO. About 85% of all directives have been ported. Includes a test kit similar to Pekko's.
 
-Additionally, there's a compatibility layer, [`Http4sDirectives`](https://github.com/theiterators/http4s-stir/blob/master/core/src/main/scala/pl/iterators/stir/server/directives/Http4sDirectives.scala), for http4s-dsl routes.
+Cross-compiled for JVM, Scala.js, and Scala Native. Supports Scala 2.13 and Scala 3.
 
-http4s-stir also furnishes a test kit akin to Pekko's (Akka's).
-
-## How to use it
-
-### Installation
-
-In SBT:
+## Installation
 
 ```scala
-libraryDependencies += "pl.iterators" %% "http4s-stir" % "0.4.0"
-libraryDependencies += "pl.iterators" %% "http4s-stir-testkit" % "0.4.0" % Test // if you need this
+// build.sbt
+libraryDependencies += "pl.iterators" %% "http4s-stir" % "0.4.1"
+libraryDependencies += "pl.iterators" %% "http4s-stir-testkit" % "0.4.1" % Test
 ```
 
-For `scala-cli` see [this example](#example).
-
-### Example
+## Quick example
 
-Here's an example in Scala 3 that you can run using scala-cli:
+A complete example you can run with `scala-cli run .`:
 
 ```scala 3
 // Main.scala
-//> using dep org.typelevel::cats-effect::3.5.4
-//> using dep org.http4s::http4s-dsl::0.23.33
+//> using dep pl.iterators::http4s-stir::0.4.1
 //> using dep org.http4s::http4s-ember-server::0.23.33
 //> using dep org.http4s::http4s-circe::0.23.33
-//> using dep io.circe::circe-core::0.14.15
 //> using dep io.circe::circe-generic::0.14.15
-//> using dep pl.iterators::http4s-stir::0.4.0
+//> using dep org.typelevel::cats-effect::3.7.0
 
 import org.http4s.Status
 import org.http4s.ember.server.EmberServerBuilder
 import org.http4s.circe.CirceEntityEncoder.*
 import org.http4s.circe.CirceEntityDecoder.*
 import io.circe.*
 import io.circe.generic.semiauto.*
-import cats.effect.IO
+import cats.effect.{IO, IOApp}
 import pl.iterators.stir.server.*
 import pl.iterators.stir.server.Directives.*
-import cats.effect.IOApp
 
-// example rewritten from https://pekko.apache.org/docs/pekko-http/current/introduction.html#using-apache-pekko-http
 var orders: List[Item] = Nil
 
-// domain model
 final case class Item(name: String, id: Long)
 final case class Order(items: List[Item])
 
-// formats for unmarshalling and marshalling
 given Codec[Item] = deriveCodec[Item]
 given Codec[Order] = deriveCodec[Order]
 
-// (fake) async database query api
 def fetchItem(itemId: Long): IO[Option[Item]] = IO.delay {
   orders.find(o => o.id == itemId)
 }
@@ -70,9 +57,7 @@ val route: Route =
   concat(
     get {
       pathPrefix("item" / LongNumber) { id =>
-        // there might be no item for a given id
         val maybeItem: IO[Option[Item]] = fetchItem(id)
-
         onSuccess(maybeItem) {
           case Some(item) => complete(item)
           case None       => complete(Status.NotFound)
@@ -83,9 +68,8 @@ val route: Route =
       path("create-order") {
         entity(as[Order]) { order =>
           val saved: IO[List[Item]] = saveOrder(order)
-          onSuccess(saved) {
-            _ => // we are not interested in the result value `Done` but only in the fact that it was successful
-              complete("order created")
+          onSuccess(saved) { _ =>
+            complete("order created")
           }
         }
       }
@@ -94,23 +78,22 @@ val route: Route =
 
 object Main extends IOApp.Simple {
   val run = EmberServerBuilder
-          .default[IO]
-          .withHttpApp(route.toHttpRoutes.orNotFound)
-          .build
-          .use(_ => IO.never)
+    .default[IO]
+    .withHttpApp(route.toHttpRoutes.orNotFound)
+    .build
+    .use(_ => IO.never)
 }
-
 ```
 
-To run this service you can use `scala-cli run .`.
+### Testing
 
-Or maybe if you want, you can compile it to JS file: `scala-cli --power package --js --js-module-kind commonjs Main.scala`.
+http4s-stir includes a test kit with familiar `~>` routing test syntax:
 
 ```scala 3
 // Main.test.scala
-//> using test.dep org.specs2::specs2-core:5.5.8
-//> using test.dep pl.iterators::http4s-stir-testkit:0.4.0
+//> using test.dep pl.iterators::http4s-stir-testkit:0.4.1
 //> using test.dep org.http4s::http4s-circe:0.23.33
+//> using test.dep org.specs2::specs2-core:5.5.8
 
 import org.http4s.Status
 import org.http4s.circe.CirceEntityEncoder.*
@@ -128,7 +111,6 @@ class MainRoutesSpec extends Specification with Specs2RouteTest {
     "create order" in {
       Post("/create-order", Order(List(Item("foo", 42)))) ~> route ~> check {
         responseAs[String] must contain("order created")
-        orders.head must beEqualTo(Item("foo", 42))
       }
     }
     "retrieve an item if present" in {
@@ -145,95 +127,45 @@ class MainRoutesSpec extends Specification with Specs2RouteTest {
     }
   }
 }
-
 ```
 
-To run the tests you can use `scala-cli test .`.
-
-For a more comprehensive example showcasing additional directives see [examples](https://github.com/theiterators/http4s-stir/blob/master/examples/src/main/scala/Service.scala). You can run it with `~examples/reStart`.
-
-## Why this library?
-
-Here's why I embarked on this project:
-
-- After the license change for Akka, many contemplated transitioning to http4s and the Typelevel stack. I wanted to simplify this migration.
-- While I'm a fan of cats-effect, I find the http4s DSL verbose and clunky. Marrying Pekko HTTP (Akka HTTP) with cats-effect seemed inelegant, so http4s-stir could be the remedy.
-- I was curious about the internals of both Pekko HTTP and http4s and wanted to determine the feasibility of this project.
-- And, of course, a bit of playful provocation - [see the next section](#whats-with-the-name).
+Run with `scala-cli test .`.
 
-## What's with the name?
-
-> **stir something up** (pv)
-> 
-> *to cause an unpleasant emotion or problem to begin or grow*
+For a more comprehensive example showcasing additional directives, see [examples/Service.scala](https://github.com/theiterators/http4s-stir/blob/master/examples/src/main/scala/Service.scala). Run it locally with `sbt ~examples/reStart`.
 
-There are folks who adore http4s but detest Pekko's (or Akka's) DSL. Conversely, there are those who champion Pekko's (or Akka's) but disdain http4s DSL. I aimed to ruffle feathers from both camps with a hybrid library.
+## http4s-dsl compatibility
 
-## Project status
+There's a compatibility layer, [`Http4sDirectives`](https://github.com/theiterators/http4s-stir/blob/master/core/src/main/scala/pl/iterators/stir/server/directives/Http4sDirectives.scala), that lets you embed existing http4s-dsl routes within stir routes.
 
-This library is in preview, intended to collect initial feedback. Yet, I am dedicated to its ongoing maintenance and enhancement, especially as it undergoes real-world testing. Contributions are very welcome.
+## What's missing
 
-## Missing
+Some Pekko HTTP directives are absent or modified:
 
-Certain directives from the original are either absent or have been modified:
-
-* Assuming and converting to/from strict entity
-* `CacheConditionDirectives`
-* `CodingDirectives`
-* directory listing in `FileAndResourceDirectives`
-* `RangeDirectives`
+* `CacheConditionDirectives`, `CodingDirectives`, `RangeDirectives`
+* Directory listing in `FileAndResourceDirectives`
 * `checkSameOrigin` in `HeaderDirectives`
-* handling of multipart forms in `FormFieldDirectives` (but I don't like it anyway)
-* Some of how akka configures things
-  * `withSizeLimit`
-  * `withoutSizeLimit`
-  * `requestEntityEmpty`
-  * `requestEntityPresent`
-  * `rejectEmptyResponse`
-  * `extractRequestTimeout`
-  * `withRequestTimeoutResponse`
-* AttributeDirectives
-* FramedEntityStreamingDirectives
-* WebSocketDirectives in large part
-* Testkit needed significant changes
-  * Not async anymore
-  * Chunks not supported
-  * Request building incomplete (missing some minor header methods)
-  * All websocket thingies
-  * Some logic of transparent headers and default host info
-
-## Support
-
-### Encountering a Problem?
+* Multipart form handling in `FormFieldDirectives`
+* `AttributeDirectives`, `FramedEntityStreamingDirectives`
+* Most of `WebSocketDirectives`
+* Strict entity conversion, `withSizeLimit`, `withoutSizeLimit`, `requestEntityEmpty`, `requestEntityPresent`, `rejectEmptyResponse`
+* Testkit differences: synchronous execution, no chunk support, limited request building, no WebSocket testing
 
-If you run into any issues, unexpected behavior, or errors, we encourage you to report them. Your feedback is invaluable and helps us improve.
-
-### Have a Feature Request?
-
-If there's a feature you'd like to see, or if you have an idea that would make this project even better, we'd love to hear about it!
-
-### How to Report an Issue or Feature Request
-
-Please create a new issue in our [http4-stir](https://github.com/theiterators/http4s-stir/issues). Ensure you provide as much detail as possible:
+## What's with the name?
 
-1. **For issues:**
-  - Describe the issue you're facing.
-  - Steps to reproduce.
-  - Expected behavior.
-  - Actual behavior.
+> **stir something up** (pv)
+>
+> *to cause an unpleasant emotion or problem to begin or grow*
 
-2. **For feature requests:**
-  - Describe the feature and why you believe it would be useful.
-  - Any reference or example from other projects/tools, if applicable.
+Some love http4s DSL but dislike Pekko's. Others feel the opposite. This library stirs things up by combining both.
 
-By providing detailed information, you'll help us address your concerns more efficiently.
+## Contributing
 
-Thank you for your contributions and for helping make this project better for everyone!
+Issues and PRs welcome at [github.com/theiterators/http4s-stir](https://github.com/theiterators/http4s-stir/issues).
 
 ## License
 
-http4s-stir is under the Apache License, Version 2.0 ("the License"). You must comply with this License to use this software. A [full license text](https://github.com/theiterators/http4s-stir/blob/master/LICENSE) is available in the repository.
+Apache License 2.0. See [LICENSE](https://github.com/theiterators/http4s-stir/blob/master/LICENSE).
 
 ## Acknowledgements
 
-http4s-stir incorporates significant portions of code adapted from [Pekko HTTP](https://github.com/apache/incubator-pekko-http), a fork of [Akka HTTP](https://github.com/akka/akka-http).
+http4s-stir incorporates code adapted from [Pekko HTTP](https://github.com/apache/incubator-pekko-http), a fork of [Akka HTTP](https://github.com/akka/akka-http).