A Kotlin client library for Phoenix Channels, enabling real-time bidirectional communication between Kotlin/JVM applications and Phoenix Framework servers.

Supported targets:

• JVM
• JavaScript
• iOS (iosX64, iosArm64, iosSimulatorArm64)
• macOS (macosX64, macosArm64)
• tvOS (tvosX64, tvosArm64, tvosSimulatorArm64)
• watchOS (watchosX64, watchosArm32, watchosArm64, watchosDeviceArm64, watchosSimulatorArm64)
• Linux (linuxX64, linuxArm64)
• Windows (mingwX64)

• ✅ WebSocket transport with Phoenix Channels v2 protocol
• ✅ Channel join/leave operations
• ✅ Push messages with response handling
• ✅ Event listeners and message routing
• ✅ Automatic reconnection with exponential backoff
• ✅ Heartbeat mechanism for connection keep-alive
• ✅ Type-safe message handling with Kotlin's type system
• ✅ Coroutines support for async operations
• ⬜ Binary message support
• ⬜ Long polling fallback transport

implementation("io.github.alexgaribay:kotlin-phoenix-channels:0.1.0")

This implementation follows the shape of the official Phoenix client, adapted to Kotlin Multiplatform:

• ARCHITECTURE.md - Detailed analysis of Socket, Channel, and Push components
• DESIGN_DECISIONS.md - Kotlin-specific design choices comparing JavaScript and Rust implementations

import io.github.alexgaribay.phoenix.Socket
import kotlinx.coroutines.runBlocking
import kotlinx.serialization.json.JsonObject

runBlocking {
    val socket = Socket("ws://localhost:4000/socket/websocket")
    socket.connect()

    val channel = socket.channel("room:lobby")
    channel.join()

    val reply = channel.push("ping", JsonObject(emptyMap())).await()
    println(reply.status)

    socket.disconnect()
}

This project includes a Phoenix test server for integration testing. See test_server/README.md for details.

# Using Docker Compose (recommended)
docker compose -f test_server/docker-compose.yml up -d

# Or using Gradle
./gradlew startTestServer

If your environment still uses the legacy docker-compose binary, replace docker compose with docker-compose in the commands above.

# Default JVM test suite
./gradlew test

# Integration tests only (requires the test server)
./gradlew integrationTest

docker compose -f test_server/docker-compose.yml down
# or
./gradlew stopTestServer

./gradlew build

• Kotlin: 2.2.0+
• Runtime JVM: 11+
• Build JDK: 21+ (or Gradle toolchain provisioning)
• Phoenix Server: v1.7+ (for testing)

• ARCHITECTURE.md - Implementation guide
• DESIGN_DECISIONS.md - Design rationale
• test_server/README.md - Test server documentation

• Phoenix Framework
• Phoenix Channels Guide
• Phoenix JavaScript Client - Reference implementation

MIT

Issues and pull requests are welcome.