Kotlin SDK API Proposal

[mfateev]

WARNING

The Kotlin SDK is an experiment in using LLMs for both design and implementation.

Summary

This proposal defines the public API for the Temporal Kotlin SDK, providing an idiomatic Kotlin experience using coroutines and suspend functions.

Formatted reading: https://github.com/mfateev/proposals/tree/kotlin-api-review/kotlin

Start at the README and click "Next" at the bottom of each document to navigate through all 27 files in order.

Key Features

• Coroutine-based workflows with suspend fun
• Type-safe activity and workflow execution via method references (no stubs)
• Native Kotlin Duration support (30.seconds)
• KOptions data classes for configuration
• Full interoperability with Java SDK

Documentation Structure

Section	Description
Kotlin Idioms	Duration, null safety, coroutine patterns
Configuration	KOptions, data conversion, interceptors
Workflows	Definition, signals, queries, updates, child workflows
Activities	Regular and local activities
Client	KWorkflowClient, handles, advanced operations
Worker	KWorkerFactory, KWorker setup
Testing	KTestWorkflowEnvironment, time skipping
Migration	Java SDK migration guide
API Parity	Java SDK comparison

[cretz]

In newer SDKs that don't have advanced generics for arbitrary arity, we have often just supported overloads with 0 or 1 parameter since we recommend no more than 1, but technically harmless to support multiple here except that we're encouraging multiple.

[mfateev]

Listed options at https://github.com/mfateev/proposals/blob/kotlin-api-review/kotlin/open-questions.md

[cretz]

Arguably options as the trailing argument is clearer to read from a caller POV (i.e. meaning the args right after the function can make sense). Since Kotlin supports named parameters and parameter defaults, I considered the value of just putting all of the activity options as parameters, but it's kinda a bad practice since the list is so large.

[mfateev]

Listed options at https://github.com/mfateev/proposals/blob/kotlin-api-review/kotlin/open-questions.md

[cretz]

Why require an interface at all? What we do in newer SDKs is even though we support interfaces (and/or abstract classes and/or never-implemented stubs), we don't require them. I think the only argument would be so it's usable from Java workflows, but at that point, the user can tease out an interface.

[mfateev]

Agree, I've added this option to the proposal.

https://github.com/mfateev/proposals/blob/kotlin-api-review/kotlin/open-questions.md

[cretz]

Am curious how this works without Kotlin in the Java SDK itself

[mfateev]

Sorry, I don't understand the question.

[cretz]

I saw later there is a concept of a "plugin" that you register with a worker if you're using Java interop. Note, for a pure Kotlin experience, we don't have to be subject to Java worker approaches even if it wraps a Java worker. For instance, activities, workflows, Nexus services, etc can be worker options. But I understand not wanting to deviate too far from Java.

[mfateev]

Agreed. Updated to follow the Python/.NET pattern where workflows and activities are passed at worker construction time via options. This aligns with newer SDKs and provides immutable, all-in-one-place configuration.

[cretz]

Do we really need a factory/constructor separation here? Is there value in the separate steps, or can one create a worker with all options? Will our choice be limited by what Java does here wrt thread pool reuse across workers?

[mfateev]

Java is the only SDK that doesn't rely on global variables to share cache and thread pool. It uses factory for this. If we decide that it is not a good pattern we can go with a simpler user experience

[cretz]

In newer SDKs, we found requiring these separate steps unnecessary. Would recommend a static call on KWorkflowClient called connect that accepts an option set that is the union of service stub options and client options.

[mfateev]

Accepted as proposed. Updated to use KWorkflowClient.connect(options) pattern following .NET SDK conventions. This is cleaner and more explicit than the Java SDK's multi-step construction pattern.

[cretz]

We should discourage the start pattern IMO in favor of a run one. We have learned that start+shutdown can swallow fatal worker-runtime errors (which are of course very rare, but technically can occur).

[mfateev]

Accepted with modification. Updated the documentation to recommend factory.run() (which blocks until shutdown) as the primary pattern, rather than discouraging start(). The documentation now shows:

// Recommended: blocks until worker shutdown
factory.run()

// Alternative for programmatic shutdown
factory.start()
// ... later ...
factory.shutdown()

This follows the pattern from other SDKs where run() is the simpler/preferred approach for most use cases.

[cretz]

We already have a concept of "plugin" coming for Java SDK, we need a different name here

[mfateev]

I think it should be the same concept.

[cretz]

Makes sense to implement Kotlin support on Java workers as a plugin, though may get a bit confusing to call it KotlinPlugin, assuming there will also be KPlugin for users to implement plugins in Kotlin (granted I can't think of a much better name, maybe KotlinToJavaWorkerPlugin or something)

[mfateev]

Good point about naming confusion. Renamed to KotlinJavaWorkerPlugin to make it clear this is for integrating Kotlin coroutine support with Java workers.

[cretz]

I don't understand this statement exactly. Does it mean "if either activity fails, the workflow fails which implicitly cancels any activities" or is there some kind of cooperative cancellation happening here if a workflow fails/

[mfateev]

Accepted as proposed. Clarified the cancellation documentation to note that using coroutineScope and other structured concurrency patterns is standard Kotlin idiom - not a Temporal-specific concept. The documentation now emphasizes that Kotlin's structured concurrency naturally maps to workflow cancellation semantics.

[cretz]

Ah, I see this is the difference between coroutineScope and supervisorScope

[GreyTeardrop]

So excited for Kotlin-first Temporal SDK!

[GreyTeardrop]

I believe Kotlin team doesn't recommend using data classes as part of library APIs as adding a new field (even an optional one) is always a binary breaking change. I see that some libraries like Jackson started from constructors with named parameters and later deprecated them in favor of a DSL/builder combo.

class KActivityOptions
private constructor(builder: KActivityOptions.Builder) {
    val startToCloseTimeout: Duration?
    // ...

    init {
        startToCloseTimeout = builder.startToCloseTimeout
        // …
    }

    class Builder {
        var startToCloseTimeout: Duration? = null
        // ...

        fun build(): KActivityOptions {
            require(startToCloseTimeout != null || scheduleToCloseTimeout != null) {
                "At least one of startToCloseTimeout or scheduleToCloseTimeout must be specified"
            }
            return KActivityOptions(this)
        }
    }
}

inline fun KActivityOptions(init: KActivityOptions.Builder.() -> Unit): KActivityOptions {
    return KActivityOptions.Builder().apply(init).build()
}

which gives a ABI-safe equivalent for data class named constructor parameters

val options = KActivityOptions {
    startToCloseTimeout = 10.minutes
    // …
}

(if necessary, copy can be implemented the same way).

[mfateev]

Added to open questions at https://github.com/mfateev/proposals/blob/kotlin-api-review/kotlin/open-questions.md#data-classes-vs-builderdsl-for-optionsconfig-classes

[mfateev]

After thinking about this, I don't understand the value of binary compatibility. Temporal SDK never guaranteed binary compatibility between versions. These structures are never sent over the wire.

[GreyTeardrop]

The primary use case for keeping ABI compatibility is for libraries that might be built on top of the SDK. Without it, if there's a library built against Kotlin SDK vX, it can't be used with a different version of the SDK, even if that version only has changes that could've been source-compatible, e.g., adding a new optional field to one of the data classes.

If the Kotlin SDK is only meant to be used by direct consumers, that shouldn't matter - consumer code is almost always built with the version of libraries it's supposed to run with, but unstable ABI can be an issue for wider ecosystem around the SDK.

[cretz]

True, and would totally support non-data for options classes for this reason, but at this point, does that mean basically no data classes should be used by libraries ever that may get new fields, only end application, due to this constraint?

[GreyTeardrop]

It should be fine to use data classes internally, but not as part of public API surface - at least that's what JetBrains suggests (https://kotlinlang.org/docs/api-guidelines-backward-compatibility.html#avoid-using-data-classes-in-your-api).

[mfateev]

Added https://github.com/mfateev/proposals/blob/kotlin-api-review/kotlin/open-questions.md

[GreyTeardrop]

Theoretically, DSL syntax can even provide slightly better ergonomics. E.g., in KActivityOptions case, retry options can be specified as

val options = KActivityOptions {
    startToCloseTimeout = 10.minutes
    retryOptions = KRetryOptions {
        initialInterval = 10.seconds
        backoffCoefficient = 1.5
    }
}

but with additional method like

inline fun KActivityOptions.Builder.retryOptions(init: KRretryOptions.Builder.() -> Unit) {
    this.retryOptions = KRetryOptions(init)
}

that can become

val options = KActivityOptions {
    startToCloseTimeout = 10.minutes
    retryOptions {
        initialInterval = 10.seconds
        backoffCoefficient = 1.5
    }
}

[mfateev]

Great point! I added your proposal to the open-questions.md document.

[mfateev]

Responses to review comments

[mfateev]

Added to open questions at https://github.com/mfateev/proposals/blob/kotlin-api-review/kotlin/open-questions.md#data-classes-vs-builderdsl-for-optionsconfig-classes

[cretz]

While I agree with the decision to disallow because it can be easily walked back if we change our minds, it may be worth noting that IIRC, Python, .NET, and Ruby all support default parameters. Here is a Python test confirming it: https://github.com/temporalio/sdk-python/blob/993de6d0e9b42bb01f24edfdb46e0795b00debcf/tests/worker/test_workflow.py#L3502-L3545.

[mfateev]

Good point about other SDKs supporting defaults. Given we're moving to 0-1 parameters (with >1 falling back to untyped), supporting a default for a single parameter is straightforward and aligns with Python/.NET/Ruby. Updated the docs to allow defaults for the 0-1 argument case.

[cretz]

Note, in order to support this in some newer SDKs and not hit diamond problems or other inheritance confusion for when they do want to have interfaces/abstracts, we require every overridden method to have the same matching annotation/attribute/decorator. This prevents ambiguity, is easy to understand, and clarifies author intent clearly to reader without relying on inheritance (at the small cost of having to write duplicate annotations on overrides).

[mfateev]

While this approach makes sense for newer SDKs starting fresh, requiring duplicate annotations would break backward compatibility with existing Java activities/workflows and feel unnatural to Java SDK users. Since Kotlin SDK builds on Java SDK, we'll maintain the current convention where annotations on the interface are sufficient.

[cretz]

Or "0-1 Argument(s)", meaning any > 1 argument, which Temporal discourages, can fall back to untyped. This is what we do in some newer SDKs.

[mfateev]

Follow-up question: Why do you prefer the type-unsafe fallback for >1 args instead of the KArgs approach which maintains type safety? Is API simplicity the main driver, or are there other considerations?

[cretz]

API simplicity (and overload count) was my main driver in preferring just falling back to untyped, but in some SDKs (namely Python), we actually do support arbitrary multi-param typed as a different overload. Would be fine if we did that here too. And really, with how .NET is lambda expressions, it supports multi-param typed as well. So overall, yeah, ok w/ a typed multi-param, and having 0 or 1 be even simpler forms of that.

[mfateev]

Thanks for confirming. We'll go with the KArgs approach (Option C) - provides full type safety for all arities while keeping 0-1 argument cases simple. The kargs() wrapper for 2+ args is a small price for compile-time type checking.

[cretz]

Hrmm, not sure we have ever considered binary breaking changes to be breaking changes from our POV (i.e. we expect you to compile against the same JAR you'll run with). Having said that, definitely not against better options patterns. But I don't think we want to discourage e.g. users from using data classes for their need-backwards-compatibility models.

[mfateev]

Good point. We won't discourage users from using data classes for their models that need backwards compatibility. The concern about binary breaking changes in the context of SDK options classes is less relevant since users compile against the SDK version they run with.

[cretz]

I saw later there is a concept of a "plugin" that you register with a worker if you're using Java interop. Note, for a pure Kotlin experience, we don't have to be subject to Java worker approaches even if it wraps a Java worker. For instance, activities, workflows, Nexus services, etc can be worker options. But I understand not wanting to deviate too far from Java.

[cretz]

Not understanding "push" cancellation, but yeah so long as I can have heartbeat infallible and cancellation represented as traditional Kotlin coroutine cancellation, I think that is ideal. Arguably both of those could be the default, but I understand if it is confusing to have suspend fun do something completely different than non-suspend fun (this is a struggle we run into w/ Python where cancellation is represented quite differently w/ async def vs just def, but not this differently, heartbeat remained infallible on both).

[cretz]

Makes sense, was just a bit strange to see it present inconsistently sometimes even w/out name customization in this proposal

[cretz]

Using existing async utilities makes sense, but still may need some workflow-specific alternatives for advanced users, such as being able to provide a timer summary for sleep.

[cretz]

Makes sense to implement Kotlin support on Java workers as a plugin, though may get a bit confusing to call it KotlinPlugin, assuming there will also be KPlugin for users to implement plugins in Kotlin (granted I can't think of a much better name, maybe KotlinToJavaWorkerPlugin or something)

[cretz]

Ah, I see this is the difference between coroutineScope and supervisorScope

[cretz]

Forgot to mention this, but in newer SDKs, we found just having one big client that is a workflow client + schedule client (w/ features to make an async activity completion handle) is a bit cleaner from an options POV. This will also help when standalone activity client and Nexus operation client come about. No need to change though if we don't want, there is also value in matching what Java does (though you will duplicate a lot of these client options each time).

[mfateev]

Agreed. We'll use a unified KClient matching the Python/.NET pattern - single client covering workflows, schedules, async activity completion, and ready for future Nexus support. Cleaner options and less duplication.

[cretz]

From my POV, this proposal is definitely good enough from a proposal POV (and is much more complete than past SDK lang proposals). So can merge whenever IMO, but may want more feedback.

Note, in all SDKs, the implementation deviates from the proposal as we learn things, so we've never expected/required 100% proposal accuracy. Also, not sure if it is part of the proposal to determine where this will live (I prefer https://github.com/temporalio/sdk-java/tree/master/temporal-kotlin myself where it can be versioned/published alongside the Java SDK dependency and even use internal packages from it if we wanted).