Kotlin

Gate provides a Kotlin API for integrating with your Kotlin applications using either Connect-RPC or gRPC. You can use the API to interact with Gate programmatically.

Installation

First, configure your package manager to add the Buf registry. You only need to do this once:

Gradle (Kotlin)

// build.gradle.kts
repositories {
    mavenCentral()
    maven {
        name = "buf"
        url = uri("https://buf.build/gen/maven")
    }
}

Gradle (Groovy)

// build.gradle
repositories {
    mavenCentral()
    maven {
        name = 'buf'
        url 'https://buf.build/gen/maven'
    }
}

Maven

<!-- pom.xml -->
<repositories>
    <repository>
        <name>Buf Maven Repository</name>
        <id>buf</id>
        <url>https://buf.build/gen/maven</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

Then add the dependencies. You can choose between Connect-RPC (recommended) or gRPC:

Latest Version Check

Make sure to check buf.build/minekube/gate/sdks for the latest versions of the dependencies.

Gradle (Kotlin) - Connect

dependencies {
    // Connect-RPC for Kotlin (Recommended)
    implementation("build.buf.gen:minekube_gate_connectrpc_kotlin:0.7.1.1.20241118150055.50fffb007499")
    implementation("com.connectrpc:connect-kotlin:0.7.1")
}

Gradle (Groovy) - Connect

dependencies {
    // Connect-RPC for Kotlin (Recommended)
    implementation 'build.buf.gen:minekube_gate_connectrpc_kotlin:0.7.1.1.20241118150055.50fffb007499'
    implementation 'com.connectrpc:connect-kotlin:0.7.1'
}

Maven - Connect

<dependencies>
    <!-- Connect-RPC for Kotlin (Recommended) -->
    <dependency>
        <groupId>build.buf.gen</groupId>
        <artifactId>minekube_gate_connectrpc_kotlin</artifactId>
        <version>0.7.1.1.20241118150055.50fffb007499</version>
    </dependency>
    <dependency>
        <groupId>com.connectrpc</groupId>
        <artifactId>connect-kotlin</artifactId>
        <version>0.7.1</version>
    </dependency>
</dependencies>

Gradle (Kotlin) - gRPC

dependencies {
    // gRPC for Kotlin
    implementation("build.buf.gen:minekube_gate_grpc_kotlin:1.4.1.1.20241118150055.50fffb007499")
    implementation("io.grpc:grpc-kotlin-stub:1.4.1")
    implementation("io.grpc:grpc-protobuf:1.68.1")
    implementation("io.grpc:grpc-netty-shaded:1.68.1")
}

Gradle (Groovy) - gRPC

dependencies {
    // gRPC for Kotlin
    implementation 'build.buf.gen:minekube_gate_grpc_kotlin:1.4.1.1.20241118150055.50fffb007499'
    implementation 'io.grpc:grpc-kotlin-stub:1.4.1'
    implementation 'io.grpc:grpc-protobuf:1.68.1'
    implementation 'io.grpc:grpc-netty-shaded:1.68.1'
}

Maven - gRPC

<dependencies>
    <!-- gRPC for Kotlin -->
    <dependency>
        <groupId>build.buf.gen</groupId>
        <artifactId>minekube_gate_grpc_kotlin</artifactId>
        <version>1.4.1.1.20241118150055.50fffb007499</version>
    </dependency>
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-kotlin-stub</artifactId>
        <version>1.4.1</version>
    </dependency>
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-protobuf</artifactId>
        <version>1.68.1</version>
    </dependency>
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-netty-shaded</artifactId>
        <version>1.68.1</version>
    </dependency>
</dependencies>

Usage Example

Here's a basic example of using the Gate Kotlin API to connect to Gate and list servers:

Connect

package com.example.connect

import build.buf.gen.minekube.gate.v1.GateServiceClient
import build.buf.gen.minekube.gate.v1.ListServersRequest
import com.connectrpc.ConnectException
import com.connectrpc.ProtocolClientConfig
import com.connectrpc.extensions.GoogleJavaProtobufStrategy
import com.connectrpc.impl.ProtocolClient
import com.connectrpc.okhttp.ConnectOkHttpClient
import com.connectrpc.protocols.NetworkProtocol
import kotlinx.coroutines.runBlocking
import okhttp3.OkHttpClient

fun main() = runBlocking {
    try {
        // Create a Connect client
        val client = ProtocolClient(
            httpClient = ConnectOkHttpClient(OkHttpClient()),
            ProtocolClientConfig(
                host = "http://localhost:8080",
                serializationStrategy = GoogleJavaProtobufStrategy(),
                networkProtocol = NetworkProtocol.CONNECT,
            ),
        )

        // Create the service client
        val gateService = GateServiceClient(client)

        // List all servers
        val request = ListServersRequest.newBuilder().build()
        val response = gateService.listServers(request)
        println(response.toString())

    } catch (e: ConnectException) {
        System.err.println("Make sure Gate is running with the API enabled")
        e.printStackTrace()
    }
}

gRPC

package com.example.grpc

import io.grpc.ManagedChannelBuilder
import build.buf.gen.minekube.gate.v1.GateServiceGrpcKt
import build.buf.gen.minekube.gate.v1.ListServersRequest
import kotlinx.coroutines.runBlocking

fun main(): Unit = runBlocking {
    try {
        // Create a gRPC channel
        val channel = ManagedChannelBuilder
            .forAddress("localhost", 8080)
            .usePlaintext()
            .build()

        // Create the service client
        val stub = GateServiceGrpcKt.GateServiceCoroutineStub(channel)

        // List all servers
        val response = stub.listServers(ListServersRequest.getDefaultInstance())
        println(response)

        // Shutdown the channel
        channel.shutdown()

    } catch (e: Exception) {
        System.err.println("Make sure Gate is running with the API enabled")
        e.printStackTrace()
    }
}

Running the Example

1. Run Gate with the API enabled
2. Navigate to the docs/developers/api/kotlin directory
3. Initialize the Gradle wrapper (only needed once):

gradle wrapper

4. Run one of the following commands:

# For Connect example (recommended)
./gradlew runConnect

# For gRPC example
./gradlew runGrpc

# Example output:
servers {
  name: "server3"
  address: "localhost:25568"
}
servers {
  name: "server4"
  address: "localhost:25569"
}
servers {
  name: "server1"
  address: "localhost:25566"
}
servers {
  name: "server2"
  address: "localhost:25567"
}

Learn More

For more details on using ConnectRPC with Kotlin, check out the ConnectRPC Documentation.