dimensional-fun / usagi

🐰 kotlin multi-platform rabbitmq/amqp client

Usagi

A kotlin multi-platform AMQP 0.9.1 client.

• ⚡ Powered by kotlin coroutines
• 🚀 Uses ktor
• 😎 Idiomatic Kotlin API

Warning Usagi is in Alpha, bugs may be ahead!

We are looking for contributors! If you are looking for a kotlin multiplatform AMQP client please consider opening PRs and Issues, it is very appreciated.

• Discord Server
• Documentation

Installation

Requires Kotlin 1.8.20 and Java 8 if you're using the JVM artifact

🐘 Gradle

• Latest Version: 1.0.0-rc.1

repositories {
    maven("https://maven.dimensional.fun/releases") // or /snapshots
}

dependencies {
    // common:
    implementation("fun.dimensional:usagi:{VERSION}")
}

Usage

Note
This API is not final, it may change in the future.

Create a Channel:

val connection = Usagi("amqp://localhost") {
    properties { connectionName = "my-service" }
}

val channel = connection.channels.create() 
    ?: error("Unable to create channel")

Using Exchanges & Queues

channel.exchange.declare { 
    exchange = "my-exchange" 
}

val queueName = channel.queue.declare()?.queue
    ?: error("Unable to declare queue")

channel.queue.bind {
    exchange = "my-exchange"
    queue = queueName
    routingKey = "my-routing-key"
}

Publishing Messages:

channel.basic.publish {
    data = "Hello, World!".encodeToByteArray()
    
    properties {
        contentType = "text/plain"
    }
    
    options {
        exchange = "my-exchange"
        routingKey = "my-routing-key"
    }
}

Consuming Messages:

val consumer = channel.basic.consume {
    queue = queueName
}

consumer.forEach { delivery ->
    println(delivery.data.decodeToString()) // >> 'Hello, World'
    delivery.ack(multiple = false)
}

Acknowledgements

• a bit of the internal connection/channel code was adapted from the official rabbitmq java client
• amqp 0.9.1 spec
• amqp 0.9.1 doc

---

Dimensional Fun

usagi's Issues

Recover channels closed by the server

RabbitMQ closes channels after a certain period of time (i think), the official rabbitmq java client has a Channel wrapper that automatically recovers it after a channel.close is received.

This is a very critical feature to have implemented.

RPCs do not resolve

While migrating from https://github.com/rabbitmq/rabbitmq-java-client startup would sometimes halt due to the current RPC not being resolved even though a reply was received and handled by the channel.