Debugging Name From Worker Action Not Used In Workflow-Kotlin

This article delves into a peculiar issue encountered while using WorkflowAction within the Square Workflow-Kotlin library. Specifically, the debugging name assigned to a WorkflowAction that handles the result of a Worker doesn't seem to propagate to the WorkflowInterceptor. This can make debugging and tracing actions within complex workflows more challenging. We will explore this issue in detail, provide a minimal reproducible example, analyze the observed behavior, and discuss potential workarounds.

Understanding the Issue

When working with asynchronous operations in Workflow-Kotlin, Workers are often employed to encapsulate these operations. When a Worker completes its task, it typically produces an output that needs to be processed by the workflow. This processing is often handled by a WorkflowAction. For debugging purposes, it's crucial to be able to identify these actions, and Workflow-Kotlin provides the debuggingName property for this purpose. However, it appears that the debuggingName set on a WorkflowAction within a Worker context might not be correctly passed to the WorkflowInterceptor, which is a key component for observing and intercepting actions within a workflow.

The core problem is that the debugging information, specifically the action's name, is seemingly lost or replaced during the transition from the Worker's output to the WorkflowAction that processes it within the workflow. This discrepancy makes it harder to trace the execution flow and understand which actions are being triggered in response to Worker completions.

Minimal Reproducible Example

To illustrate this issue, consider the following Kotlin code snippet:

package com.stripe.reader.application

import com.squareup.workflow1.BaseRenderContext
import com.squareup.workflow1.Worker
import com.squareup.workflow1.Workflow
import com.squareup.workflow1.WorkflowAction
import com.squareup.workflow1.WorkflowInterceptor
import com.squareup.workflow1.WorkflowInterceptor.RenderContextInterceptor
import com.squareup.workflow1.action
import com.squareup.workflow1.renderWorkflowIn
import com.squareup.workflow1.runningWorker
import com.squareup.workflow1.stateless
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.collect
import kotlin.system.exitProcess

suspend fun main() = coroutineScope {
    val workflow: Workflow<Unit, Unit, String> = Workflow.stateless {
        runningWorker(Worker.timer(1000L)) {
            action("wait-completed") { setOutput(Unit) }
        }

        "Waiting for input..."
    }

    val interceptor = object : WorkflowInterceptor {
        override fun <P, S, O, R> onRender(
            renderProps: P,
            renderState: S,
            context: BaseRenderContext<P, S, O>,
            proceed: (P, S, RenderContextInterceptor<P, S, O>?) -> R,
            session: WorkflowInterceptor.WorkflowSession
        ): R {
            println("onRender: $renderState")

            val contextInterceptor = object : RenderContextInterceptor<P, S, O> {
                override fun onActionSent(
                    action: WorkflowAction<P, S, O>,
                    proceed: (WorkflowAction<P, S, O>) -> Unit
                ) {
                    println("onActionSent: ${action.debuggingName}")
                    proceed(action)
                }
            }

            return proceed(renderProps, renderState, contextInterceptor)
        }
    }

    renderWorkflowIn(
        workflow = workflow,
        scope = this@coroutineScope,
        interceptors = listOf(interceptor),
        props = MutableStateFlow(Unit),
        onOutput = { exitProcess(0) },
    ).collect()
}

This code defines a simple workflow that uses a Worker.timer to simulate an asynchronous task. The runningWorker function is used to manage the Worker, and when the timer completes, it triggers a WorkflowAction named "wait-completed". A WorkflowInterceptor is also defined to observe the actions being sent within the workflow. The onActionSent method of the interceptor prints the debuggingName of each action.

Observed Output

When the above code is executed, the following output is produced:

onRender: kotlin.Unit
onRender: 0
onActionSent: EmitWorkerOutputAction(worker=TimerWorker(delayMs=1000, key=), key=)
onRender: kotlin.Unit
onRender: 0

The key observation here is that the onActionSent output shows EmitWorkerOutputAction(worker=TimerWorker(delayMs=1000, key=), key=) instead of the expected "wait-completed". This indicates that the debugging name provided in the action("wait-completed") block is not being correctly propagated to the interceptor. The interceptor is instead receiving a generic EmitWorkerOutputAction, which doesn't provide the specific context of the original action.

Analyzing the Root Cause

The issue arises from how Workflow-Kotlin handles the output of a Worker. When a Worker produces an output, it's wrapped in an internal WorkflowAction called EmitWorkerOutputAction. This action is responsible for emitting the worker's output into the workflow. While this mechanism is necessary for the framework's internal workings, it obscures the original intent and debugging context of the action defined within the runningWorker block.

The EmitWorkerOutputAction effectively acts as an intermediary, and its debuggingName overwrites the more specific name provided in the original action block. This behavior makes it difficult to track the specific actions triggered by Worker completions using the debuggingName property.

Impact on Debugging

The loss of the original debugging name can significantly impact the debugging process, especially in complex workflows with multiple Workers and actions. Without the specific action name, it becomes challenging to pinpoint the exact code path being executed in response to a Worker's output. This can lead to increased debugging time and difficulty in identifying the root cause of issues.

Potential Workarounds

While the debuggingName property doesn't directly propagate as expected, there are a few potential workarounds to mitigate this issue:

1. Using the Worker Key

One workaround is to use the Worker's key as a proxy for the action name. The Worker key is included in the EmitWorkerOutputAction's debuggingName, as seen in the output (EmitWorkerOutputAction(worker=TimerWorker(delayMs=1000, key=), key=)). By setting a descriptive key for the Worker, you can indirectly identify the action being triggered.

For example, you could modify the runningWorker call to include a key that reflects the action's intent:

runningWorker(Worker.timer(1000L, key = "wait-completed")) {
    action("wait-completed") { setOutput(Unit) }
}

This will result in the EmitWorkerOutputAction's debuggingName including the key value, allowing you to identify the action in the interceptor.

2. Custom Interceptor Logic

Another approach is to implement custom logic within the WorkflowInterceptor to extract the relevant information. This might involve inspecting the action object and, based on its type or properties, inferring the original action name.

For instance, you could check if the action is an EmitWorkerOutputAction and then examine the associated Worker to determine the intended action. However, this approach can be more complex and might require maintaining a mapping between Workers and their corresponding actions.

3. Centralized Action Handling

Consider centralizing the handling of Worker outputs within a specific part of your workflow. This can make it easier to trace actions triggered by Workers as they will all flow through a common code path. By having a central handler, you can add specific logging or debugging logic to identify the actions being processed.

Conclusion

The issue of the debuggingName from a Worker action not being directly available in the WorkflowInterceptor presents a challenge for debugging Workflow-Kotlin applications. While the expected behavior of the debuggingName not propagating can be a hindrance, understanding the underlying mechanism and the role of EmitWorkerOutputAction is crucial for devising effective workarounds.

By employing strategies such as using the Worker key, implementing custom interceptor logic, or centralizing action handling, developers can still gain valuable insights into the execution flow of their workflows and effectively debug asynchronous operations. As Workflow-Kotlin evolves, it's possible that future versions may address this issue directly, providing a more seamless debugging experience for actions triggered by Workers.

It's important to note that this behavior, while potentially unexpected, is a consequence of the framework's internal design for managing Worker outputs. The EmitWorkerOutputAction serves a critical purpose in ensuring the correct propagation of results, but it does introduce a layer of abstraction that can obscure the original action's debugging context. By being aware of this trade-off, developers can make informed decisions about their debugging strategies and choose the most appropriate workaround for their specific needs.

Ultimately, effective debugging in Workflow-Kotlin requires a deep understanding of the framework's architecture and the interactions between different components. By combining this knowledge with the workarounds discussed in this article, developers can confidently tackle complex workflows and ensure the reliability of their applications.