Skip to content

Commit

Permalink
Release 3.8.3
Browse files Browse the repository at this point in the history
  • Loading branch information
@adamw
adamw committed Oct 17, 2022
1 parent bf5cf27 commit 4f0dd23
Show file tree
Hide file tree
Showing 28 changed files with 200 additions and 471 deletions.
8 changes: 4 additions & 4 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,14 +45,14 @@ sttp (v2) documentation is available at [sttp.softwaremill.com/en/v2](http://stt

sttp (v1) documentation is available at [sttp.softwaremill.com/en/v1](https://sttp.softwaremill.com/en/v1).

scaladoc is available at [https://www.javadoc.io](https://www.javadoc.io/doc/com.softwaremill.sttp.client3/core_2.12/3.8.2)
scaladoc is available at [https://www.javadoc.io](https://www.javadoc.io/doc/com.softwaremill.sttp.client3/core_2.12/3.8.3)

## Quickstart with Ammonite

If you are an [Ammonite](http://ammonite.io) user, you can quickly start experimenting with sttp by copy-pasting the following:

```scala
import $ivy.`com.softwaremill.sttp.client3::core:3.8.2`
import $ivy.`com.softwaremill.sttp.client3::core:3.8.3`
import sttp.client3.quick._
quickRequest.get(uri"http://httpbin.org/ip").send(backend)
```
Expand All @@ -64,7 +64,7 @@ This brings in the sttp API and a synchronous backend instance.
Add the following dependency:

```scala
"com.softwaremill.sttp.client3" %% "core" % "3.8.2"
"com.softwaremill.sttp.client3" %% "core" % "3.8.3"
```

Then, import:
Expand Down Expand Up @@ -102,7 +102,7 @@ The documentation is typechecked using [mdoc](https://scalameta.org/mdoc/). The

When generating documentation, it's best to set the version to the current one, so that the generated doc files don't include modifications with the current snapshot version.

That is, in sbt run: `set version := "3.8.2"`, before running `mdoc` in `docs`.
That is, in sbt run: `set version := "3.8.3"`, before running `mdoc` in `docs`.

### Testing the Scala.JS backend

Expand Down
2 changes: 1 addition & 1 deletion generated-docs/out/backends/akka.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
This backend is based on [akka-http](http://doc.akka.io/docs/akka-http/current/scala/http/). To use, add the following dependency to your project:

```
"com.softwaremill.sttp.client3" %% "akka-http-backend" % "3.8.2"
"com.softwaremill.sttp.client3" %% "akka-http-backend" % "3.8.3"
```

A fully **asynchronous** backend. Uses the `Future` effect to return responses. There are also [other `Future`-based backends](future.md), which don't depend on Akka.
Expand Down
90 changes: 18 additions & 72 deletions generated-docs/out/backends/catseffect.md
View file
Original file line number Diff line number Diff line change
@@ -1,103 +1,49 @@
# cats-effect backend

The [Cats Effect](https://github.com/typelevel/cats-effect) backend is **asynchronous**. It can be created for any type implementing the `cats.effect.Concurrent` typeclass, such as `cats.effect.IO`. Sending a request is a non-blocking, lazily-evaluated operation and results in a wrapped response. There's a transitive dependency on `cats-effect`.
The [Cats Effect](https://github.com/typelevel/cats-effect) backend is **asynchronous**.
It can be created for any type implementing the `cats.effect.Concurrent` typeclass, such as `cats.effect.IO`.
Sending a request is a non-blocking, lazily-evaluated operation and results in a wrapped response.
There's a transitive dependency on `cats-effect`.

Note that all [fs2](fs2.md) backends also support any cats-effect effect, additionally supporting request & response streaming.

## Using async-http-client
Also note that the [http4s](http4s.md) backend can also be created for a type implementing the cats-effect’s `Async` typeclass, and supports streaming as in [fs2](fs2.md).

To use, add the following dependency to your project:

```scala
"com.softwaremill.sttp.client3" %% "async-http-client-backend-cats" % "3.8.2" // for cats-effect 3.x
// or
"com.softwaremill.sttp.client3" %% "async-http-client-backend-cats-ce2" % "3.8.2" // for cats-effect 2.x
```
This backend depends on [async-http-client](https://github.com/AsyncHttpClient/async-http-client), uses [Netty](http://netty.io) behind the scenes.

Alternatively, the [http4s](http4s.md) backend can also be created for a type implementing the cats-effect's `Async` typeclass, and supports streaming as in [fs2](fs2.md).
## Using Armeria

Next you'll need to define a backend instance. This can be done in two basic ways:
Creation of the backend can be done in two basic ways:

* by creating an effect, which describes how the backend is created, or instantiating the backend directly. In this case, you'll need to close the backend manually
* by creating a `Resource`, which will instantiate the backend and close it after it has been used
* by creating a `Resource`, which will instantiate the backend and close it after it has been used.

A non-comprehensive summary of how the backend can be created is as follows:
Firstly, add the following dependency to your project:

```scala
import cats.effect.IO
import sttp.client3.asynchttpclient.cats.AsyncHttpClientCatsBackend

// the type class instance needs to be provided explicitly (e.g. `cats.effect.IO`).
// the effect type must implement the Async typeclass
AsyncHttpClientCatsBackend[IO]().flatMap { backend => ??? }
"com.softwaremill.sttp.client3" %% "armeria-backend-cats" % "3.8.3" // for cats-effect 3.x
// or
"com.softwaremill.sttp.client3" %% "armeria-backend-cats-ce2" % "3.8.3" // for cats-effect 2.x
```

or, if you'd like to use a custom configuration:
create client:

```scala
import cats.effect.IO
import org.asynchttpclient.AsyncHttpClientConfig
import sttp.client3.asynchttpclient.cats.AsyncHttpClientCatsBackend

val config: AsyncHttpClientConfig = ???
AsyncHttpClientCatsBackend.usingConfig[IO](config).flatMap { backend => ??? }
```

or, if you'd like to use adjust the configuration sttp creates:
import sttp.client3.armeria.cats.ArmeriaCatsBackend

```scala
import cats.effect.IO
import org.asynchttpclient.DefaultAsyncHttpClientConfig
import sttp.client3.SttpBackendOptions
import sttp.client3.asynchttpclient.cats.AsyncHttpClientCatsBackend
val backend = ArmeriaCatsBackend[IO]()

val sttpOptions: SttpBackendOptions = SttpBackendOptions.Default
val adjustFunction: DefaultAsyncHttpClientConfig.Builder => DefaultAsyncHttpClientConfig.Builder = ???
AsyncHttpClientCatsBackend.usingConfigBuilder[IO](adjustFunction, sttpOptions).flatMap { backend => ??? }
// You can use the default client which reuses the connection pool of ClientFactory.ofDefault()
ArmeriaCatsBackend.usingDefaultClient[IO]()
```

or, if you'd like the backend to be wrapped in cats-effect `Resource`:

```scala
import cats.effect.IO
import sttp.client3.asynchttpclient.cats.AsyncHttpClientCatsBackend

AsyncHttpClientCatsBackend.resource[IO]().use { backend => ??? }
```

or, if you'd like to instantiate the `AsyncHttpClient` yourself:

```scala
import cats.effect.IO
import org.asynchttpclient.AsyncHttpClient
import sttp.client3.asynchttpclient.cats.AsyncHttpClientCatsBackend

val asyncHttpClient: AsyncHttpClient = ???
val backend = AsyncHttpClientCatsBackend.usingClient[IO](asyncHttpClient)
```

## Using Armeria

To use, add the following dependency to your project:

```scala
"com.softwaremill.sttp.client3" %% "armeria-backend-cats" % "3.8.2" // for cats-effect 3.x
// or
"com.softwaremill.sttp.client3" %% "armeria-backend-cats-ce2" % "3.8.2" // for cats-effect 2.x
```

create client:

```scala
import cats.effect.IO
import sttp.client3.armeria.cats.ArmeriaCatsBackend

val backend = ArmeriaCatsBackend[IO]()

// You can use the default client which reuses the connection pool of ClientFactory.ofDefault()
ArmeriaCatsBackend.usingDefaultClient[IO]()
ArmeriaCatsBackend.resource[IO]().use { backend => ??? }
```

or, if you'd like to instantiate the [WebClient](https://armeria.dev/docs/client-http) yourself:
Expand Down
2 changes: 1 addition & 1 deletion generated-docs/out/backends/finagle.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
To use, add the following dependency to your project:

```
"com.softwaremill.sttp.client3" %% "finagle-backend" % "3.8.2"
"com.softwaremill.sttp.client3" %% "finagle-backend" % "3.8.3"
```

Next you'll need to add an implicit value:
Expand Down
104 changes: 14 additions & 90 deletions generated-docs/out/backends/fs2.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,17 @@ The [fs2](https://github.com/functional-streams-for-scala/fs2) backends are **as

## Using HttpClient

To use, add the following dependency to your project:
Creation of the backend can be done in two basic ways:

* by creating a `Resource`, which will instantiate the backend and close it after it has been used.
* by creating an effect, which describes how a backend is created, or instantiating the backend directly. In this case, you'll need to close the backend manually, as well as provide a `Dispatcher` instance

Firstly, add the following dependency to your project:

```scala
"com.softwaremill.sttp.client3" %% "fs2" % "3.8.2" // for cats-effect 3.x & fs2 3.x
"com.softwaremill.sttp.client3" %% "fs2" % "3.8.3" // for cats-effect 3.x & fs2 3.x
// or
"com.softwaremill.sttp.client3" %% "fs2-ce2" % "3.8.2" // for cats-effect 2.x & fs2 2.x
"com.softwaremill.sttp.client3" %% "fs2-ce2" % "3.8.3" // for cats-effect 2.x & fs2 2.x
```

Obtain a cats-effect `Resource` which creates the backend, and closes the thread pool after the resource is no longer used:
Expand Down Expand Up @@ -55,95 +60,15 @@ Host header override is supported in environments running Java 12 onwards, but i
-Djdk.httpclient.allowRestrictedHeaders=host
```

## Using async-http-client

To use, add the following dependency to your project:

```scala
"com.softwaremill.sttp.client3" %% "async-http-client-backend-fs2" % "3.8.2" // for cats-effect 3.x & fs2 3.x
// or
"com.softwaremill.sttp.client3" %% "async-http-client-backend-fs2-ce2" % "3.8.2" // for cats-effect 2.x & fs2 2.x
```

This backend depends on [async-http-client](https://github.com/AsyncHttpClient/async-http-client) and uses [Netty](http://netty.io) behind the scenes.

Next you'll need to define a backend instance as an implicit value. This can be done in two basic ways:

* by creating a `Resource`, which will instantiate the backend (along with a `Dispatcher`) and close it after it has been used
* by creating an effect, which describes how a backend is created, or instantiating the backend directly. In this case, you'll need to close the backend manually, as well as provide a `Dispatcher` instance

Below you can find a non-comprehensive summary of how the backend can be created. The easiest form is to use a cats-effect `Resource`:

```scala
import cats.effect.IO
import sttp.client3.asynchttpclient.fs2.AsyncHttpClientFs2Backend

AsyncHttpClientFs2Backend.resource[IO]().use { backend => ??? }
```

or, by providing a custom dispatcher:

```scala
import cats.effect.IO
import cats.effect.std.Dispatcher
import sttp.client3.asynchttpclient.fs2.AsyncHttpClientFs2Backend

val dispatcher: Dispatcher[IO] = ???

AsyncHttpClientFs2Backend[IO](dispatcher).flatMap { backend => ??? }
```

or, if you'd like to use a custom configuration:

```scala
import cats.effect.IO
import cats.effect.std.Dispatcher
import org.asynchttpclient.AsyncHttpClientConfig
import sttp.client3.asynchttpclient.fs2.AsyncHttpClientFs2Backend

val dispatcher: Dispatcher[IO] = ???

val config: AsyncHttpClientConfig = ???
AsyncHttpClientFs2Backend.usingConfig[IO](config, dispatcher).flatMap { backend => ??? }
```

or, if you'd like to use adjust the configuration sttp creates:

```scala
import cats.effect.IO
import cats.effect.std.Dispatcher
import org.asynchttpclient.DefaultAsyncHttpClientConfig
import sttp.client3.SttpBackendOptions
import sttp.client3.asynchttpclient.fs2.AsyncHttpClientFs2Backend

val sttpOptions: SttpBackendOptions = SttpBackendOptions.Default
val adjustFunction: DefaultAsyncHttpClientConfig.Builder => DefaultAsyncHttpClientConfig.Builder = ???
val dispatcher: Dispatcher[IO] = ???

AsyncHttpClientFs2Backend.usingConfigBuilder[IO](dispatcher, adjustFunction, sttpOptions).flatMap { backend => ??? }
```

or, if you'd like to instantiate the AsyncHttpClient yourself:

```scala
import cats.effect.IO
import cats.effect.std.Dispatcher
import org.asynchttpclient.AsyncHttpClient
import sttp.client3.asynchttpclient.fs2.AsyncHttpClientFs2Backend

val dispatcher: Dispatcher[IO] = ???
val asyncHttpClient: AsyncHttpClient = ???
val backend = AsyncHttpClientFs2Backend.usingClient[IO](asyncHttpClient, dispatcher)
```

## Using Armeria

To use, add the following dependency to your project:

```scala
"com.softwaremill.sttp.client3" %% "armeria-backend-fs2" % "3.8.2" // for cats-effect 3.x & fs2 3.x
"com.softwaremill.sttp.client3" %% "armeria-backend-fs2" % "3.8.3" // for cats-effect 3.x & fs2 3.x
// or
"com.softwaremill.sttp.client3" %% "armeria-backend-fs2" % "3.8.2" // for cats-effect 2.x & fs2 2.x
"com.softwaremill.sttp.client3" %% "armeria-backend-fs2" % "3.8.3" // for cats-effect 2.x & fs2 2.x
```

create client:
Expand Down Expand Up @@ -200,10 +125,9 @@ import cats.effect.IO
import fs2.Stream
import sttp.capabilities.fs2.Fs2Streams
import sttp.client3._
import sttp.client3.armeria.fs2.ArmeriaFs2Backend
import sttp.client3.asynchttpclient.fs2.AsyncHttpClientFs2Backend
import sttp.client3.httpclient.fs2.HttpClientFs2Backend

val effect = AsyncHttpClientFs2Backend.resource[IO]().use { backend =>
val effect = HttpClientFs2Backend.resource[IO]().use { backend =>
val stream: Stream[IO, Byte] = ???

basicRequest
Expand All @@ -220,10 +144,10 @@ import cats.effect.IO
import fs2.Stream
import sttp.capabilities.fs2.Fs2Streams
import sttp.client3._
import sttp.client3.asynchttpclient.fs2.AsyncHttpClientFs2Backend
import sttp.client3.httpclient.fs2.HttpClientFs2Backend
import scala.concurrent.duration.Duration

val effect = AsyncHttpClientFs2Backend.resource[IO]().use { backend =>
val effect = HttpClientFs2Backend.resource[IO]().use { backend =>
val response: IO[Response[Either[String, Stream[IO, Byte]]]] =
basicRequest
.post(uri"...")
Expand Down
Loading

0 comments on commit 4f0dd23

Please sign in to comment.