taig / communicator

A monix wrapper for OkHttp

Github

Communicator

CircleCI codecov Maven License

A monix wrapper for OkHttp

Communicator provides a simple way to construct OkHttp requests as monix.Tasks which is equipped with a beautiful functional interface and comes with first class support for cancellation.

Installation

libraryDependencies ++=
    "io.taig" %% "communicator-request" % "3.3.0-RC2" ::
    "io.taig" %% "communicator-builder" % "3.3.0-RC2" ::
    Nil

Quickstart

import monix._; import eval.Task; import execution.Scheduler.Implicits.global
import io.taig.communicator._; import request._
import okhttp3.OkHttpClient
import scala._; import util._; import concurrent._; import duration._

// To build request tasks, an implicit OkHttpClient should be in scope
implicit val client = new OkHttpClient()

// Simple OkHttp request builder
val builder = new OkHttpRequest.Builder().url( "https://github.com/" )

// Construct a Task[Response] and parse it to a String
val request = Request( builder.build() ).parse[String]

// Kick off the actual request
val response = request.runAsync
Await.result( response, 30.seconds )
// res8: io.taig.communicator.request.Response[String] =
// >>> https://github.com/
// [No headers]
// <<< 200 OK
// Server: GitHub.com
// Date: Mon, 11 Sep 2017 14:02:53 GMT
// Content-Type: text/html; charset=utf-8
// Transfer-Encoding: chunked
// Status: 200 OK
// Cache-Control: no-cache
// Vary: X-PJAX
// X-UA-Compatible: IE=Edge,chrome=1
// Set-Cookie: _octo=GH1.1.189582300.1505138573; domain=.github.com; path=/; expires=Wed, 11 Sep 2019 14:02:53 -0000
// Set-Cookie: logged_in=no; domain=.github.com; path=/; expires=Fri, 11 Sep 2037 14:02:53 -0000; secure; HttpOnly
// Set-Cookie: _gh_sess=eyJzZXNzaW9uX2lkIjoiMWUyNmQyZTI5YWY1YWFlM2MxZDcwNzU2MjJhYzIxMTAiLCJsYXN0X3JlYWRfZnJvbV9yZXBsaWNhcyI6MTUwNTEzODU3MzM4NCwiX2NzcmZfdG9rZW4iOiJzOUNrMk9LR3c4blBBS0NtUFVXS2llRVRpSFdLaXBYZXlmUHpPMXhERVhBPSJ9--de6056b310e0c...

Usage

Communicator provides a thin layer around OkHttp using monix.Task to execute HTTP requests and monix.Observable for Phoenix Channels. To construct requests, the OkHttp builder API is used.

Building Requests

Use the OkHttp builder API to construct requests which are then lifted into io.taig.communicator.request.Request.

val headers = new OkHttpRequest.Builder().
    url( "https://github.com/" ).
    header( "X-API-Key", "foobar" ).
    build()

val request: Request = Request( headers )

Handling Responses

There are several ways to transform a Request to an executable Task[Response].

// Ignores response body
val ignoreBody: Task[Response[Unit]] = request.ignoreBody

// Parses response body to a String
val parse: Task[Response[String]] = request.parse[String]

Android

To use Communicator on the Android platform please extend your ProGuard rules by the following instructions:

proguardOptions ++=
    "-dontnote okhttp3.internal.**" ::
    "-dontnote monix.execution.internals.**" ::
    "-dontwarn io.circe.generic.util.macros.**" ::
    "-dontwarn monix.execution.internals.**" ::
    "-dontwarn okio.**" ::
    "-dontwarn org.jctools.**" ::
    "-dontwarn org.slf4j.**" ::
    Nil

You might also use existing platform Executors to provide a monix Scheduler:

import android.os.AsyncTask
import android.util.Log
import monix.execution.Scheduler

implicit val PoolScheduler: Scheduler = Scheduler {
    ExecutionContext.fromExecutor(
        AsyncTask.THREAD_POOL_EXECUTOR,
        t  Log.e( "PoolScheduler", "Failure during asynchronous operation", t )
    )
}

Communicator 2.x

The scala.concurrent.Future predecessor of this library has been deprecated. You can still access the source and documentation.

Communicator 1.x

The Java predecessor of this library has been deprecated. You can still access the source and documentation.