actioncable-client-kotlin

This is the actioncable client library for Kotlin. Please see Action Cable Overview to understand actioncable itself.

Usage

Requirements

• Kotlin 1.1.4-3 or later
• kotlinx.coroutines (experimental in Kotlin 1.1)

Gradle

repositories {
    jcenter()
    maven { url "https://jitpack.io" }
}

dependencies {
    compile 'com.github.hosopy:actioncable-client-kotlin:0.0.3'
}

Basic

// 1. Setup
val uri = URI("ws://cable.example.com")
val consumer = ActionCable.createConsumer(uri)

// 2. Create subscription
val appearanceChannel = Channel("AppearanceChannel")
val subscription = consumer.subscriptions.create(appearanceChannel)

subscription.onConnected = {
    // Called when the subscription has been successfully completed
}

subscription.onRejected = {
    // Called when the subscription is rejected by the server
}

subscription.onReceived = { data: Any? ->
    // Called when the subscription receives data from the server
    // Possible types...
    when (data) {
        is Int -> { }
        is Long -> { }
        is BigInteger -> { }
        is String -> { }
        is Double -> { }
        is Boolean -> { }
        is JsonObject -> { }
        is JsonArray<*> -> { }
    }
}

subscription.onDisconnected = {
    // Called when the subscription has been closed
}

subscription.onFailed = { error ->
    // Called when the subscription encounters any error
}

// 3. Establish connection
consumer.connect()

// 4. Perform any action
subscription.perform("away")

// 5. Perform any action with params
subscription.perform("hello", mapOf("name" to "world"))

Passing Parameters to Channel

val chatChannel = Channel("ChatChannel", mapOf("room_id" to 1))

The parameter container is Map<String, Any?> and is converted to JsonObject(Klaxon) internally. To know what type of value can be passed, please read Klaxon user guide.

Passing Parameters to Subscription#perform

subscription.perform("send", mapOf(
    "comment" to mapOf(
        "text" to "This is string.",
        "private" to true,
        "images" to arrayOf(
            "http://example.com/image1.jpg",
            "http://example.com/image2.jpg"
        )
    )
))

The parameter container is Map<String, Any?> and is converted to JsonObject(Klaxon) internally. To know what type of value can be passed, please read Klaxon user guide.

Options

val uri = URI("ws://cable.example.com")
val options = Consumer.Options()
options.connection.reconnection = true

val consumer = ActionCable.createConsumer(uri, options)

Below is a list of available options.

• sslContext

  options.connection.sslContext = yourSSLContextInstance

• hostnameVerifier

  options.connection.hostnameVerifier = yourHostnameVerifier

• cookieHandler

  options.connection.cookieHandler = yourCookieManagerInstance

• query

  options.connection.query = mapOf("user_id" to "1")

• headers

  options.connection.headers = mapOf("X-Foo" to "Bar")

• reconnection

  • If reconnection is true, the client attempts to reconnect to the server when underlying connection is stale.
  • Default is false.

  options.connection.reconnection = false

• reconnectionMaxAttempts

  • The maximum number of attempts to reconnect.
  • Default is 30.

  options.connection.reconnectionMaxAttempts = 30

• okHttpClientFactory

  • Factory instance to create your own OkHttpClient.
  • If okHttpClientFactory is not set, just create OkHttpClient by OkHttpClient().

  options.connection.okHttpClientFactory = {
      OkHttpClient().also {
          it.networkInterceptors().add(StethoInterceptor())
      }
  }

Authentication

How to authenticate a request depends on the architecture you choose.

Authenticate by HTTP Header

val options = Consumer.Options()
options.connection.headers = mapOf("Authorization" to "Bearer xxxxxxxxxxx")

val consumer = ActionCable.createConsumer(uri, options)

Authenticate by Query Params

val options = Consumer.Options()
options.connection.query = mapOf("access_token" to "xxxxxxxxxxx")

val consumer = ActionCable.createConsumer(uri, options)

Authenticate by Cookie

val cookieManager = CookieManager()
// Some setup
...
options.connection.cookieHandler = cookieManager

val consumer = ActionCable.createConsumer(uri, options)

License

MIT