Kotlin SDK API Proposal

kotlin/README.md

@@ -0,0 +1,131 @@
+# Kotlin SDK API Proposal
+
+This document describes the public API and developer experience for the Temporal Kotlin SDK.
+
+## Overview
+
+The Kotlin SDK provides an idiomatic Kotlin experience for building Temporal workflows using coroutines and suspend functions.
+
+**Key Features:**
+
+* Coroutine-based workflows with `suspend fun`
+* Full interoperability with Java SDK
+* Kotlin Duration support (`30.seconds`)
+* DSL builders for configuration
+* Null safety (no `Optional<T>`)
+
+**Requirements:**
+
+* Minimum Kotlin version: 1.8.x
+* Coroutines library: kotlinx-coroutines-core 1.7.x+
+
+## Design Principle
+
+**Use idiomatic Kotlin language patterns wherever possible instead of custom APIs.**
+
+The Kotlin SDK should feel natural to Kotlin developers by leveraging standard `kotlinx.coroutines` primitives. Custom APIs should only be introduced when Temporal-specific semantics cannot be achieved through standard patterns.
+
+| Pattern | Standard Kotlin | Temporal Integration |
+|---------|-----------------|----------------------|
+| Parallel execution | `coroutineScope { async { ... } }` | Works via deterministic dispatcher |
+| Await multiple | `awaitAll(d1, d2)` | Standard kotlinx.coroutines |
+| Sleep/delay | `delay(duration)` | Intercepted via `Delay` interface |
+| Deferred results | `Deferred<T>` | Standard + `Promise<T>.toDeferred()` |
+
+This approach provides:
+- **Familiar patterns**: Kotlin developers use patterns they already know
+- **IDE support**: Full autocomplete and documentation for standard APIs
+- **Ecosystem compatibility**: Works with existing coroutine libraries and utilities
+- **Smaller API surface**: Less custom code to learn and maintain
+
+## Documentation Structure
+
+### Core Concepts
+
+- **[Kotlin Idioms](./kotlin-idioms.md)** - Duration, null safety, property syntax for queries
+- **[Configuration](./configuration/README.md)** - KOptions classes, data conversion, interceptors
+
+### Building Blocks
+
+- **[Workflows](./workflows/README.md)** - Defining and implementing workflows
+  - [Definition](./workflows/definition.md) - Interfaces, suspend methods, Java interop
+  - [Signals, Queries & Updates](./workflows/signals-queries.md) - Communication patterns
+  - [Child Workflows](./workflows/child-workflows.md) - Orchestrating child workflows
+  - [Timers & Parallel Execution](./workflows/timers-parallel.md) - Delays, async patterns
+  - [Cancellation](./workflows/cancellation.md) - Handling cancellation, cleanup
+  - [Continue-As-New](./workflows/continue-as-new.md) - Long-running workflow patterns
+
+- **[Activities](./activities/README.md)** - Defining and implementing activities
+  - [Definition](./activities/definition.md) - Interfaces, typed/string-based execution
+  - [Implementation](./activities/implementation.md) - Suspend activities, heartbeating
+  - [Local Activities](./activities/local-activities.md) - Short-lived local activities
+
+### Infrastructure
+
+- **[Client](./client/README.md)** - Interacting with workflows
+  - [Workflow Client](./client/workflow-client.md) - KWorkflowClient, starting workflows
+  - [Workflow Handles](./client/workflow-handle.md) - Signals, queries, results
+  - [Advanced Operations](./client/advanced.md) - SignalWithStart, UpdateWithStart
+
+- **[Worker](./worker/README.md)** - Running workflows and activities
+  - [Setup](./worker/setup.md) - KWorkerFactory, KWorker, registration
+
+### Reference
+
+- **[Testing](./testing.md)** - Unit testing, mocking activities, time skipping
+- **[Migration Guide](./migration.md)** - Migrating from Java SDK
+- **[API Parity](./api-parity.md)** - Java SDK comparison, gaps, not-needed APIs
+
+## Quick Start
+
+```kotlin
+// Define activity interface
+@ActivityInterface
+interface GreetingActivities {
+    @ActivityMethod
+    suspend fun composeGreeting(greeting: String, name: String): String
+}
+
+// Implement activity
+class GreetingActivitiesImpl : GreetingActivities {
+    override suspend fun composeGreeting(greeting: String, name: String): String {
+        return "$greeting, $name!"
+    }
+}
+
+// Define workflow interface
+@WorkflowInterface
+interface GreetingWorkflow {
+    @WorkflowMethod
+    suspend fun getGreeting(name: String): String
+}
+
+// Implement workflow
+class GreetingWorkflowImpl : GreetingWorkflow {
+    override suspend fun getGreeting(name: String): String {
+        return KWorkflow.executeActivity(
+            GreetingActivities::composeGreeting,
+            KActivityOptions(startToCloseTimeout = 10.seconds),
+            "Hello", name
+        )
+    }
+}
+
+// Start worker
+val factory = KWorkerFactory(client)
+val worker = factory.newWorker("greetings")
+worker.registerWorkflowImplementationTypes(GreetingWorkflowImpl::class)
+worker.registerActivitiesImplementations(GreetingActivitiesImpl())
+factory.start()
+
+// Execute workflow
+val result = client.executeWorkflow(
+    GreetingWorkflow::getGreeting,
+    KWorkflowOptions(workflowId = "greeting-123", taskQueue = "greetings"),
+    "Temporal"
+)
+```
+
+---
+
+**[Start Review →](./kotlin-idioms.md)**

kotlin/activities/README.md

@@ -0,0 +1,71 @@
+# Activities
+
+This section covers defining and implementing Temporal activities in Kotlin.
+
+## Overview
+
+Activities are the building blocks for interacting with external systems. The Kotlin SDK provides type-safe activity execution with suspend function support.
+
+## Documents
+
+| Document | Description |
+|----------|-------------|
+| [Definition](./definition.md) | Activity interfaces, typed and string-based execution |
+| [Implementation](./implementation.md) | Implementing activities, KActivity API, heartbeating |
+| [Local Activities](./local-activities.md) | Short-lived local activities |
+
+## Quick Reference
+
+### Basic Activity
+
+```kotlin
+// Define activity interface
+@ActivityInterface
+interface GreetingActivities {
+    @ActivityMethod
+    suspend fun composeGreeting(greeting: String, name: String): String
+}
+
+// Implement activity
+class GreetingActivitiesImpl : GreetingActivities {
+    override suspend fun composeGreeting(greeting: String, name: String): String {
+        return "$greeting, $name!"
+    }
+}
+```
+
+### Calling Activities from Workflows
+
+```kotlin
+// Type-safe method reference
+val greeting = KWorkflow.executeActivity(
+    GreetingActivities::composeGreeting,
+    KActivityOptions(startToCloseTimeout = 30.seconds),
+    "Hello", "World"
+)
+
+// String-based (for cross-language interop)
+val result = KWorkflow.executeActivity<String>(
+    "composeGreeting",
+    KActivityOptions(startToCloseTimeout = 30.seconds),
+    "Hello", "World"
+)
+```
+
+### Key Patterns
+
+| Pattern | API |
+|---------|-----|
+| Execute activity | `KWorkflow.executeActivity(Interface::method, options, args)` |
+| Execute by name | `KWorkflow.executeActivity<R>("name", options, args)` |
+| Local activity | `KWorkflow.executeLocalActivity(Interface::method, options, args)` |
+| Heartbeat | `KActivity.context.heartbeat(details)` |
+
+## Related
+
+- [Implementation](./implementation.md) - Suspend activity patterns
+- [Local Activities](./local-activities.md) - Short-lived activities
+
+---
+
+**Next:** [Activity Definition](./definition.md)

kotlin/activities/definition.md

@@ -0,0 +1,171 @@
+# Activity Definition
+
+## String-based Activity Execution
+
+For calling activities by name (useful for cross-language interop or dynamic activity names):
+
+```kotlin
+// Execute activity by string name - suspend function, awaits result
+val result = KWorkflow.executeActivity<String>(
+    "activityName",
+    KActivityOptions(
+        startToCloseTimeout = 30.seconds,
+        retryOptions = KRetryOptions(
+            initialInterval = 1.seconds,
+            maximumAttempts = 3
+        )
+    ),
+    arg1, arg2
+)
+
+// Parallel execution - use standard coroutineScope { async {} }
+val results = coroutineScope {
+    val d1 = async { KWorkflow.executeActivity<String>("activity1", options, arg1) }
+    val d2 = async { KWorkflow.executeActivity<String>("activity2", options, arg2) }
+    awaitAll(d1, d2)  // Returns List<String>
+}
+```
+
+## Typed Activities
+
+The typed activity API uses direct method references - no stub creation needed. This approach:
+- Provides full compile-time type safety for arguments and return types
+- Allows different options (timeouts, retry policies) per activity call
+- Works with both Kotlin `suspend` and Java non-suspend activity interfaces
+- Similar to TypeScript and Python SDK patterns
+
+```kotlin
+// Define activity interface
+@ActivityInterface
+interface GreetingActivities {
+    @ActivityMethod
+    suspend fun composeGreeting(greeting: String, name: String): String
+
+    @ActivityMethod
+    suspend fun sendEmail(email: Email): SendResult
+
+    @ActivityMethod
+    suspend fun log(message: String)
+}
+
+// In workflow - direct method reference, no stub needed
+val greeting = KWorkflow.executeActivity(
+    GreetingActivities::composeGreeting,  // Direct reference to interface method
+    KActivityOptions(startToCloseTimeout = 30.seconds),
+    "Hello", "World"
+)
+
+// Different activity, different options
+val result = KWorkflow.executeActivity(
+    GreetingActivities::sendEmail,
+    KActivityOptions(
+        startToCloseTimeout = 2.minutes,
+        retryOptions = KRetryOptions(maximumAttempts = 5)
+    ),
+    email
+)
+
+// Void activities work too
+KWorkflow.executeActivity(
+    GreetingActivities::log,
+    KActivityOptions(startToCloseTimeout = 5.seconds),
+    "Processing started"
+)
+```
+
+## Type Safety
+
+The API uses `KFunction` reflection to extract method metadata and provides compile-time type checking:
+
+```kotlin
+// Compile error! Wrong argument types
+KWorkflow.executeActivity(
+    GreetingActivities::composeGreeting,
+    options,
+    123, true  // ✗ Type mismatch: expected String, String
+)
+```
+
+## Parallel Execution
+
+Use standard `coroutineScope { async { } }` for concurrent execution:
+
+```kotlin
+override suspend fun parallelGreetings(names: List<String>): List<String> = coroutineScope {
+    names.map { name ->
+        async {
+            KWorkflow.executeActivity(
+                GreetingActivities::composeGreeting,
+                KActivityOptions(startToCloseTimeout = 10.seconds),
+                "Hello", name
+            )
+        }
+    }.awaitAll()  // Standard kotlinx.coroutines.awaitAll
+}
+
+// Multiple different activities in parallel
+val (result1, result2) = coroutineScope {
+    val d1 = async { KWorkflow.executeActivity(Activities::operation1, options, arg1) }
+    val d2 = async { KWorkflow.executeActivity(Activities::operation2, options, arg2) }
+    awaitAll(d1, d2)
+}
+```
+
+> **Note:** We use standard Kotlin `async` instead of a custom `startActivity` method. The workflow's deterministic dispatcher ensures correct replay behavior.
+
+## Java Activity Interoperability
+
+Method references work regardless of whether the activity is defined in Kotlin or Java:
+
+```kotlin
+// Java activity interface works seamlessly
+// public interface JavaPaymentActivities {
+//     PaymentResult processPayment(String orderId, BigDecimal amount);
+// }
+
+val result: PaymentResult = KWorkflow.executeActivity(
+    JavaPaymentActivities::processPayment,
+    KActivityOptions(startToCloseTimeout = 2.minutes),
+    orderId, amount
+)
+```
+
+## Activity Execution API
+
+The `KWorkflow` object provides type-safe overloads using `KFunction` types:
+
+```kotlin
+object KWorkflow {
+    // 1 argument
+    suspend fun <T, A1, R> executeActivity(
+        activity: KFunction2<T, A1, R>,
+        options: KActivityOptions,
+        arg1: A1
+    ): R
+
+    // 2 arguments
+    suspend fun <T, A1, A2, R> executeActivity(
+        activity: KFunction3<T, A1, A2, R>,
+        options: KActivityOptions,
+        arg1: A1, arg2: A2
+    ): R
+
+    // ... up to 6 arguments
+
+    // String-based overloads
+    suspend inline fun <reified R> executeActivity(
+        activityName: String,
+        options: KActivityOptions,
+        vararg args: Any?
+    ): R
+}
+```
+
+## Related
+
+- [Local Activities](./local-activities.md) - Short-lived local activities
+- [Workflows](../workflows/README.md) - Calling activities from workflows
+
+---
+
+**Next:** [Activity Implementation](./implementation.md)