Kotlin SDK - Ktor Plugin

nexus-ktor-plugin installs a NexusClient into a Ktor server application and ties it to the application’s lifecycle. It is a separate artifact, so a consumer that does not run Ktor never resolves ktor-server-core.

Installation

dependencies {
    implementation("dev.westyx.nexus:nexus-ktor-plugin:0.11.0")

    // Still required: a Ktor *client* engine. A Ktor server dependency does not
    // bring one with it.
    implementation("io.ktor:ktor-client-cio:3.5.1")
}

Usage

import dev.westyx.nexus.ktor.Nexus
import dev.westyx.nexus.ktor.nexus
import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Application.module() {
    install(Nexus) {
        endpoint = "https://my-service.westyx.dev"
        apiKey   = System.getenv("NEXUS_API_KEY")
    }

    routing {
        get("/greeting") {
            call.respondText(nexus.getString("greeting", "hi"))
        }
        get("/flags/checkout") {
            call.respondText(nexus.getFlag("new-checkout").toString())
        }
    }
}

Application.nexus returns the installed client. Without the plugin it raises an IllegalStateException naming the installation call rather than a bare missing-attribute error. There is also installNexus { … } as a shorthand for install(Nexus) { … }.

Configuration

install(Nexus) {
    endpoint             = "https://my-service.westyx.dev"
    apiKey               = System.getenv("NEXUS_API_KEY")
    ttl                  = 60.seconds
    wif                  = WifConfig(enabled = true)
    observer             = MyNexusObserver()
    sseReconnectCooldown = intArrayOf(5, 10, 20)
    connectStream        = true
    engine               = OkHttp.create()
    logger               = null   // null = the Ktor application logger
}

Field	Default	Notes
`endpoint`	`""`	Maps to `NexusConfig.baseUrl`. Must be `https` (loopback excepted).
`apiKey`	`null`	Required unless `wif` is enabled.
`ttl`	`60.seconds`	Must be greater than zero.
`wif`	`null`	See Workload identity.
`observer`	no-op	See Stream observer.
`sseReconnectCooldown`	`null`	Minutes; `null` means `[5, 10, 20, 40, 60]`.
`connectStream`	`true`	Set `false` for TTL polling only.
`engine`	`null`	Resolved from the classpath when null.
`logger`	`null`	Null means the Ktor `application.log`, so SDK output joins the application log.

Everything else behaves exactly as in Configuration - the plugin builds a NexusConfig from these fields.

Lifecycle

Startup. The client is created, and performs its initial sync, while the plugin installs. A bad endpoint, a rejected key or an unresolvable WIF credential therefore fails embeddedServer(...).start() rather than surfacing as a 500 on whichever request first happens to touch a config. If connectStream is true, the live-update stream opens here too. Shutdown. On ApplicationStopping the plugin closes the client, which cancels the stream, releases both HTTP clients and the WIF credential source, and removes any materialised file secrets. This is the plugin’s main reason to exist: a stream coroutine that outlives the application would hold a connection and a thread pool open in a process that believes it has shut down. The plugin’s test suite asserts that streamStatus is DISCONNECTED and the client is closed once the application has stopped.

install(Nexus)   -> create client -> initial sync -> publish as Application.nexus -> connectStream()
ApplicationStopping -> client.close() -> stream cancelled, clients closed, file secrets removed

Because installation performs a suspending initial sync in a non-suspending Ktor hook, it blocks the startup thread until the sync completes. That is deliberate: application startup is synchronous, and fail-fast is the point.

Accessing the client outside a route

fun Application.scheduleReload() {
    val client = nexus
    launch {
        while (isActive) {
            delay(5.minutes)
            runCatching { client.sync() }
        }
    }
}

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

Kotlin SDK - Ktor Plugin

Installation

Usage

Configuration

Lifecycle

Accessing the client outside a route

​Installation

​Usage

​Configuration

​Lifecycle

​Accessing the client outside a route

Installation

Usage

Configuration

Lifecycle

Accessing the client outside a route