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 HttpTasks.

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.