Let event handlers report progress and see their own state

TKDubsta · TKDubsta · commit 94ebad096091 · 2026-07-29T17:42:06.000+01:00
Ack gains feedback(), isResolved() and getStatus(). feedback("...") pushes a
line into the status text of this event's row in the execution view, capped at
255 characters and ignored once the ack has settled; it is optional, and an
event that never calls it behaves as before.

Handlers now run against a budget: EventOptions.timeoutMs (default 15s) after
which the SDK resolves the ack as RESOLVED_TIMEOUT and tells the server the
event failed, so a stalled handler no longer hangs the operator's row. The
budget is published with the action so the server can size its own watchdog
around it rather than guess.

Resolution happens exactly once, whichever of success, error or timeout gets
there first, and every Ack method is safe to call from any thread.
diff --git a/README.md b/README.md
@@ -91,6 +91,9 @@ Rules:
 - Registering the same name again replaces the previous handler.
 - Events are published to server after adoption and whenever set changes.
 - `icon` is optional; omit it and the event shows the default `terminal` glyph.
+- A handler that has not called `ack.success()` / `ack.error()` within
+  `timeoutMs` is resolved as `RESOLVED_TIMEOUT`. Do slow work on your own
+  thread and report progress with `ack.feedback()` — see [Ack](#ack).
 
 ### unregisterEvent
 
@@ -158,13 +161,15 @@ EventOptions(
 	label = "Readable Label",  // default: event name
 	colour = 7,                // 0..7, default 7
 	hasFeedback = true,        // default true
-	icon = "circle-fill"       // default "terminal"
+	icon = "circle-fill",      // default "terminal"
+	timeoutMs = 15_000         // default 15_000
 )
 ```
 
 Validation:
 - `colour` must be in range `0..7`.
 - If `label` is provided, it must be non-blank and `<= 80` chars.
+- `timeoutMs` must be between `1_000` and `600_000`.
 - If `icon` is provided, it must be a [Bootstrap Icons](https://icons.getbootstrap.com)
   name: lowercase letters, digits and hyphens, `<= 64` chars. A `bi-` prefix is
   accepted and stripped, so `"bi-terminal"` and `"terminal"` are equivalent.
@@ -189,9 +194,54 @@ Validated inputs include:
 Provided to each event handler:
 - `ack.success()` reports successful completion.
 - `ack.error("reason")` reports failed completion.
+- `ack.feedback("message")` optionally reports progress while the handler runs.
+- `ack.isResolved()` is true once the ack has settled, however it settled.
+- `ack.getStatus()` returns the `AckStatus`.
 
 For `hasFeedback = false`, ack calls are harmless no-ops.
 
+Every method is safe to call from any thread, and every method is a no-op once
+the ack has resolved — a slow handler that finishes late cannot overwrite the
+result the timeout already reported.
+
+#### Progress feedback
+
+`ack.feedback("message")` replaces the status text on this event's row in
+ShowTrak's execution view, leaving the progress bar where it was. It is purely
+optional: an event that never calls it behaves exactly as it always has.
+
+```kotlin
+ShowTrak.registerEvent(
+	"RunDiagnostics",
+	EventOptions(label = "Run Diagnostics", timeoutMs = 20_000)
+) { ack ->
+	backgroundExecutor.execute {          // never block the SDK's callback thread
+		for (step in 1..5) {
+			if (ack.isResolved()) return@execute   // timed out from under us
+			doStep(step)
+			ack.feedback("Step $step of 5 complete")
+		}
+		ack.success()
+	}
+}
+```
+
+Messages are trimmed and capped at 255 characters (longer ones are cut, not
+rejected). Blank messages, calls after the ack has resolved, and calls on a
+`hasFeedback = false` event are all ignored.
+
+#### AckStatus
+
+- `UNRESOLVED` — still running.
+- `RESOLVED_SUCCESS` — `success()` was called.
+- `RESOLVED_ERROR` — `error()` was called, or the handler threw.
+- `RESOLVED_TIMEOUT` — the handler ran past `EventOptions.timeoutMs`.
+
+A handler that has not resolved within `timeoutMs` is resolved for it, and the
+timeout is reported to the server so the operator sees the event fail rather
+than hang. The server arms its own watchdog a few seconds beyond `timeoutMs`,
+so an event whose device disappears mid-run still settles.
+
 ### SDKStatus
 
 `SDKStatus` is an immutable snapshot returned by `ShowTrak.getStatus()`.
diff --git a/gradle.properties b/gradle.properties
@@ -5,7 +5,7 @@ android.nonTransitiveRClass=true
 kotlin.code.style=official
 
 GROUP=io.github.showtrak
-VERSION_NAME=1.1.0
+VERSION_NAME=1.2.0
 POM_ARTIFACT_ID=showtrak-sdk
 POM_NAME=ShowTrak Android SDK
 POM_DESCRIPTION=Reusable Android SDK for ShowTrak integrated clients.
diff --git a/showtrak-sdk/src/main/java/io/showtrak/sdk/Models.kt b/showtrak-sdk/src/main/java/io/showtrak/sdk/Models.kt
@@ -11,12 +11,15 @@ import java.util.Locale
  * @property icon     Bootstrap Icons name shown beside the event, e.g. "lightning-charge-fill"
  *                    (browse them at https://icons.getbootstrap.com). The `bi-` prefix is
  *                    optional. Defaults to [DEFAULT_ICON] when omitted.
+ * @property timeoutMs How long the handler may run before the SDK resolves its [Ack] as
+ *                    [AckStatus.RESOLVED_TIMEOUT]. Raise it for genuinely slow work.
  */
 data class EventOptions @JvmOverloads constructor(
     val label: String? = null,
     val colour: Int = 7,
     val hasFeedback: Boolean = true,
     val icon: String? = null,
+    val timeoutMs: Long = DEFAULT_TIMEOUT_MS,
 ) {
     init {
         require(colour in 0..7) { "EventOptions.colour must be between 0 and 7" }
@@ -35,6 +38,10 @@ data class EventOptions @JvmOverloads constructor(
                     "lowercase letters, digits and hyphens (got '$icon')"
             }
         }
+        require(timeoutMs in MIN_TIMEOUT_MS..MAX_TIMEOUT_MS) {
+            "EventOptions.timeoutMs must be between $MIN_TIMEOUT_MS and $MAX_TIMEOUT_MS " +
+                "(got $timeoutMs)"
+        }
     }
 
     /**
@@ -49,6 +56,14 @@ data class EventOptions @JvmOverloads constructor(
         /** Glyph used for events that declare no icon. Matches the server's default. */
         const val DEFAULT_ICON = "terminal"
 
+        /** Default handler budget, matching the server's default script timeout. */
+        const val DEFAULT_TIMEOUT_MS = 15_000L
+
+        /** Longest progress message [Ack.feedback] will send; longer ones are cut. */
+        const val MAX_FEEDBACK_LENGTH = 255
+
+        private const val MIN_TIMEOUT_MS = 1_000L
+        private const val MAX_TIMEOUT_MS = 600_000L
         private const val MAX_ICON_LENGTH = 64
         private val ICON_PATTERN = Regex("^[a-z0-9-]+$")
 
@@ -69,17 +84,59 @@ data class EventOptions @JvmOverloads constructor(
     }
 }
 
+/** How an event handler's [Ack] finished, or that it has not finished yet. */
+enum class AckStatus {
+    /** Still running: none of success, error or the timeout has fired. */
+    UNRESOLVED,
+
+    /** [Ack.success] was called. */
+    RESOLVED_SUCCESS,
+
+    /** [Ack.error] was called, or the handler threw. */
+    RESOLVED_ERROR,
+
+    /** The handler ran past [EventOptions.timeoutMs] without resolving. */
+    RESOLVED_TIMEOUT,
+}
+
 /**
  * Passed to an event handler when an operator triggers the event. The handler
  * must call exactly one of [success] / [error] when it is done (for
  * [EventOptions.hasFeedback] events; for fire-and-forget events the calls are
  * harmless no-ops).
+ *
+ * A handler that has not resolved within [EventOptions.timeoutMs] is resolved
+ * for it as [AckStatus.RESOLVED_TIMEOUT]. Every method here is safe to call
+ * from any thread, and every one is a no-op once the ack has resolved — so a
+ * slow handler that eventually finishes cannot overwrite the timeout result.
  */
 interface Ack {
     val requestId: String
     val eventId: String
+
+    /** Report successful completion. No-op if already resolved. */
     fun success()
+
+    /** Report failure, with a reason shown to the operator. No-op if already resolved. */
     fun error(message: String)
+
+    /**
+     * Optionally report progress while the handler runs: the message replaces
+     * the status text on this event's row in ShowTrak's execution view, leaving
+     * the progress bar alone. Entirely optional — an event that never calls it
+     * behaves exactly as before.
+     *
+     * Messages are trimmed and capped at 255 characters (longer ones are cut,
+     * not rejected). Blank messages, calls after the ack has resolved, and
+     * calls on a `hasFeedback = false` event are all ignored.
+     */
+    fun feedback(message: String)
+
+    /** True once this ack has resolved, by success, error or timeout. */
+    fun isResolved(): Boolean
+
+    /** The current [AckStatus]. */
+    fun getStatus(): AckStatus
 }
 
 /** High-level connection lifecycle, surfaced for optional UI. */
diff --git a/showtrak-sdk/src/main/java/io/showtrak/sdk/ShowTrakClient.kt b/showtrak-sdk/src/main/java/io/showtrak/sdk/ShowTrakClient.kt
@@ -222,6 +222,9 @@ class ShowTrakClient(context: Context) {
                     // drawn for them anyway.
                     .put("Icon", event.options.resolvedIcon)
                     .put("HasFeedback", event.options.hasFeedback)
+                    // Lets the server size its own watchdog around this
+                    // handler's budget instead of guessing.
+                    .put("TimeoutMs", event.options.timeoutMs)
             )
         }
         s.emit("RegisterActions", array)
@@ -259,6 +262,75 @@ class ShowTrakClient(context: Context) {
         }, 0, 2, TimeUnit.SECONDS)
     }
 
+    /**
+     * The [Ack] handed to one triggered event. Resolution happens exactly once,
+     * whichever of success, error or the timeout gets there first, and every
+     * method is callable from any thread.
+     */
+    private inner class EventAck(
+        override val requestId: String,
+        override val eventId: String,
+        private val options: EventOptions,
+    ) : Ack {
+
+        private val lock = Any()
+        private var status: AckStatus = AckStatus.UNRESOLVED
+        private var timeoutTask: ScheduledFuture<*>? = null
+
+        /** Start the handler's clock. Called before the handler runs. */
+        fun arm() {
+            val task = scheduler.schedule(
+                {
+                    resolve(
+                        AckStatus.RESOLVED_TIMEOUT,
+                        "Handler did not respond within ${options.timeoutMs}ms"
+                    )
+                },
+                options.timeoutMs,
+                TimeUnit.MILLISECONDS,
+            )
+            synchronized(lock) {
+                // A handler that resolved before we got here must not leave a
+                // timer running behind it.
+                if (status != AckStatus.UNRESOLVED) task.cancel(false) else timeoutTask = task
+            }
+        }
+
+        override fun success() = resolve(AckStatus.RESOLVED_SUCCESS, null)
+
+        override fun error(message: String) =
+            resolve(AckStatus.RESOLVED_ERROR, message.trim().ifEmpty { "Handler error" })
+
+        override fun isResolved(): Boolean = getStatus() != AckStatus.UNRESOLVED
+
+        override fun getStatus(): AckStatus = synchronized(lock) { status }
+
+        override fun feedback(message: String) {
+            // Progress on an event nobody is waiting for has nowhere to go: the
+            // server closed the row the moment it dispatched.
+            if (!options.hasFeedback) return
+            val text = message.trim()
+            if (text.isEmpty()) return
+            synchronized(lock) { if (status != AckStatus.UNRESOLVED) return }
+            socket?.takeIf { it.connected() }?.emit(
+                "IntegratedEventFeedback",
+                requestId,
+                text.take(EventOptions.MAX_FEEDBACK_LENGTH),
+            )
+        }
+
+        private fun resolve(newStatus: AckStatus, error: String?) {
+            synchronized(lock) {
+                if (status != AckStatus.UNRESOLVED) return
+                status = newStatus
+                timeoutTask?.cancel(false)
+                timeoutTask = null
+            }
+            if (!options.hasFeedback) return
+            socket?.emit("IntegratedEventResponse", requestId, error ?: JSONObject.NULL)
+        }
+    }
+
     private fun handleTrigger(args: Array<out Any?>?) {
         val requestId = args?.getOrNull(0)?.toString() ?: return
         val eventId = args.getOrNull(1)?.toString() ?: return
@@ -267,24 +339,8 @@ class ShowTrakClient(context: Context) {
             socket?.emit("IntegratedEventResponse", requestId, "Event not registered")
             return
         }
-        val ack = object : Ack {
-            override val requestId = requestId
-            override val eventId = eventId
-            private var done = false
-            override fun success() = complete(null)
-            override fun error(message: String) = complete(message)
-            private fun complete(error: String?) {
-                if (done) return
-                done = true
-                if (event.options.hasFeedback) {
-                    socket?.emit(
-                        "IntegratedEventResponse",
-                        requestId,
-                        error ?: JSONObject.NULL
-                    )
-                }
-            }
-        }
+        val ack = EventAck(requestId, eventId, event.options)
+        ack.arm()
         try {
             event.handler(ack)
         } catch (e: Exception) {
@@ -399,6 +455,9 @@ class ShowTrakClient(context: Context) {
                     "Event '$eventId' icon must be a Bootstrap Icons name (got '$icon')"
                 }
             }
+            require(options.timeoutMs > 0) {
+                "Event '$eventId' timeoutMs must be positive (got ${options.timeoutMs})"
+            }
         }
 
         private fun validatePort(port: Int) {
