fun-http-client
Copyright 2015 PagerDuty, Inc.
Overview
fun-http-client is a small, asynchronous, and functional interface to the Akka HTTP client.
The primary differences between this interface and the default one provided by Akka HTTP are:
- Functional-style error handling where the error type is restricted to (sub-classes of) a particular type
- Request logging as pure data
- Simplification: we support the simple case of a single request resulting in a single response, which we consume strictly (but not synchronously).
It makes sense to use fun-http-client if you need an HTTP client in a project already employing Akka.
Dependencies
- Akka HTTP - For the HTTP engine and data models
- Scalaz - For monad transformer definitions and the disjunction (
\/
) type - ScalaCheck - For property based testing
- ScalaTest - For unit tests
Current version
The current version of fun-http-client is 2.1.0.
fun-http-client is available for Scala 2.10 and 2.11.
For SBT:
libraryDependencies += "com.pagerduty" %% "fun-http-client" % "2.1.0"
Author
fun-http-client is written by Jesse Haber-Kucharsky (jhaberku@pagerduty.com).
Contributing
See CONTRIBUTING.md.
Issues
Please report issues in the issue tracker on GitHub.
Running tests
Tests are executed via SBT.
In a terminal:
$ sbt test
Running the example
Switch to the example
project and run the main
function.
$ sbt
> project example
> run
How?
fun-http-client introduces the HttpTask[E, A]
type, which is an asynchronous computation that involves zero or more HTTP requests. The task has one of two outcomes: either an error of type E
, or a result of type A
. HttpTask[E, A]
computations also keep a log of HTTP requests that are made (and how long they take).
HttpTask[E, A]
computations can be combined and manipulated with familiar functions like flatMap
and map
.
Error handling is explicit, by-value, and recoverable with handleError
and raiseError
.
When it's time to do something with the result of a computation, it can be converted to a standard Scala Future
via asFutureWithLog: Future[(RequestLog, E \/ A)]
or asFuture: Future[E \/ A]
.
Request logging
Every HTTP request made through fun-http-client via Http[E].request
logs a LogEntry
with this signature:
case class LogEntry private (
request: HttpRequest,
initiationTime: Time,
completed: Boolean,
duration: Option[Duration])
The request log is just type RequestLog = Vector[LogEntry]
.
Building HTTP computations
The Http[E]
trait provides combinators for building HttpTask
s.
For instance, Http[String].unit(3)
results in HttpTask[String, Int]
. We sneakily accessed a new instance of Http[String]
via the function Http.apply[E]: Http[E]
.
Using the library
There is a complete worked example in example/JsonTest.scala
which is described in the tutorial.
Changelog
See CHANGELOG.md.