Skip to content

Kotlin SDK

The SLIM Kotlin SDK (io.agntcy.slim:slim-bindings-kotlin) provides an idiomatic Kotlin/JVM API for building applications on SLIM. Bindings are generated from the same Rust core as every other language binding via UniFFI, with coroutine-based async/await and native libraries loaded through JNA.

Requirements
Runtime JDK 17 or higher
Package slim-bindings-kotlin on Maven Central
Build tools Gradle 8.5+ (wrapper included)
Examples kotlin/examples in slim-bindings

The Maven artifact bundles native libraries for Linux, macOS, and Windows on x64 and arm64. JNA loads the correct library for your platform at runtime.

Installation

Add to your build.gradle.kts:

dependencies {
    implementation("io.agntcy.slim:slim-bindings-kotlin:1.0.0")
}

dependencies {
    implementation 'io.agntcy.slim:slim-bindings-kotlin:1.0.0'
}

<dependency>
  <groupId>io.agntcy.slim</groupId>
  <artifactId>slim-bindings-kotlin</artifactId>
  <version>1.0.0</version>
</dependency>

Getting Started

The SDK tutorials build a full application step by step — initialising the service, connecting to a node, creating an app, opening sessions, receiving messages, and adding persistence — with Kotlin snippets shown alongside every other binding.

Start with Connecting to SLIM.

API Overview

Type Description
Top-level functions Static entry point for initialisation and global service access
Service Manages connections and creates apps
App Application handle for sessions, subscriptions, and routing
Session Session for sending and receiving messages
Name Identity in org/namespace/app format
ReceivedMessage Received message with payload (bytes) and context metadata
SessionConfig Session configuration (type, MLS, retries)
ClientConfig Client connection configuration (endpoint, TLS, transport auth)
ServerConfig Server listen configuration (endpoint, TLS, transport auth)
OidcConfig OIDC transport authentication settings
OidcPolicyConfig Claim-based access policy (Cel, Rego, RegoFile)

Rust Result<T, E> types are converted to Kotlin exceptions. Catch SlimException subtypes for structured error handling.

Rust async functions are exposed as Kotlin suspend functions. Run them inside a coroutine scope (runBlocking, coroutineScope, or a framework like Ktor).

Session Configuration

val sessionConfig = SessionConfig(
    sessionType = SessionType.POINT_TO_POINT,
    maxRetries = 5u,
    interval = Duration.ofSeconds(5),
    metadata = emptyMap(),
    mlsSettings = MlsSettings(100u, null),
)

val session = app.createSessionAndWaitAsync(sessionConfig, remoteName)

SessionConfig declares no default arguments, so every field must be passed. maxRetries is a UInt, interval a java.time.Duration, and mlsSettings = null disables MLS.

Transport Authentication

Separate from the app identity passed to createAppWithSecret, the gRPC connection to a SLIM node can carry its own credentials via ClientConfig.auth.

OIDC (client credentials)

val clientConfig = newInsecureClientConfig("http://127.0.0.1:46357").apply {
    auth = ClientAuthenticationConfig.Oidc(
        OidcConfig(
            issuerUrl = "https://auth.example.com",
            clientId = "my-client",
            clientSecret = "s3cr3t",
            scope = "openid profile",
            timeout = Duration.ofSeconds(30),
        )
    )
}
val connId = service.connectAsync(clientConfig)

For the refresh-token flow, set refreshToken (or refreshTokenFile, which is rewritten in place as tokens rotate) instead of clientSecret.

OIDC (server verification)

val serverConfig = newInsecureServerConfig("127.0.0.1:46357").apply {
    auth = ServerAuthenticationConfig.Oidc(
        OidcConfig(
            issuerUrl = "https://auth.example.com",
            audience = "slim",
            jwksTtl = Duration.ofHours(1),
            claimCacheTtl = Duration.ofMinutes(1),
            policy = OidcPolicyConfig.Cel(""""admin" in claims.groups"""),
        )
    )
}
service.runServerAsync(serverConfig)

policy accepts OidcPolicyConfig.Cel, OidcPolicyConfig.Rego (which must define package slim.auth with default allow = false), or OidcPolicyConfig.RegoFile.

JSON configuration

newConfigFromJson accepts a full gRPC client config covering TLS material, backoff, and every authentication mode:

{
  "endpoint": "http://127.0.0.1:46357",
  "tls": { "insecure": true },
  "auth": {
    "type": "oidc",
    "issuer_url": "https://auth.example.com",
    "client_id": "my-client",
    "client_secret": "s3cr3t",
    "audience": "slim",
    "policy": { "cel": "\"admin\" in claims.groups" }
  }
}

The schema matches the client configuration schema in the slim repository.

SLIMRPC

The Kotlin SDK includes SLIMRPC support for Protobuf-based RPC over SLIM. Install the protoc-gen-slimrpc-kotlin plugin and add it to your buf.gen.yaml alongside the standard Java protobuf plugin. See the SLIMRPC Compiler and the Serving and Client tutorials.

Generated code lives in the io.agntcy.slim.bindings.slimrpc package.

Examples

The slim-bindings/kotlin directory includes complete working examples:

Example Description
PointToPoint.kt 1:1 messaging with request/reply
Group.kt Group sessions with moderator/participant roles
Server.kt SLIM data plane server
examples/slimrpc/simple Protobuf RPC over SLIM

Point-to-point:

cd kotlin
task examples:p2p:alice       # Receiver
task examples:p2p:no-mls:bob  # Sender (in another terminal)

SLIMRPC (requires a running SLIM node and generated proto code):

task examples:rpc:server
task examples:rpc:client

Platform Support

Platform Architecture Status
Linux x86_64 Supported
Linux aarch64 Supported
macOS x86_64 Supported
macOS aarch64 (Apple Silicon) Supported
Windows x86_64 Supported

Building from Source

To build the Kotlin SDK from the slim-bindings repository:

git clone https://github.com/agntcy/slim-bindings
cd slim-bindings/kotlin

task generate   # regenerate Kotlin bindings from Rust artifacts
task build

See the kotlin README for the full list of development tasks.

Next Steps