Expose summary option for timers and activities (#626)

Author: roxblnfk

composer.json

@@ -34,7 +34,7 @@
         "roadrunner-php/roadrunner-api-dto": "^1.12.0",
         "roadrunner-php/version-checker": "^1.0.1",
         "spiral/attributes": "^3.1.8",
-        "spiral/roadrunner": "^2025.1.0",
+        "spiral/roadrunner": "^2025.1.2",
         "spiral/roadrunner-cli": "^2.6",
         "spiral/roadrunner-kv": "^4.3.1",
         "spiral/roadrunner-worker": "^3.6.2",

dload.xml

@@ -4,7 +4,7 @@
        temp-dir="./runtime"
 >
     <actions>
-        <download software="rr" version="^2025.1.0"/>
+        <download software="rr" version="^2025.1.2"/>
         <download software="temporal" version="^1.3-priority"/>
         <download software="temporal-tests-server"/>
     </actions>

psalm-baseline.xml

@@ -1098,11 +1098,6 @@
       <code><![CDATA[PromiseInterface]]></code>
     </TooManyTemplateParams>
   </file>
-  <file src="src/Internal/Transport/Request/NewTimer.php">
-    <PossiblyNullPropertyFetch>
-      <code><![CDATA[CarbonInterval::make($interval)->totalMilliseconds]]></code>
-    </PossiblyNullPropertyFetch>
-  </file>
   <file src="src/Internal/Transport/Router/CancelWorkflow.php">
     <DocblockTypeContradiction>
       <code><![CDATA[$process === null]]></code>

src/Activity/ActivityOptions.php

@@ -119,6 +119,19 @@ class ActivityOptions extends Options implements ActivityOptionsInterface
     #[Marshal(name: 'Priority')]
     public Priority $priority;
 
+    /**
+     * Optional summary of the activity.
+     *
+     * Single-line fixed summary for this activity that will appear in UI/CLI.
+     * This can be in single-line Temporal Markdown format.
+     *
+     * @experimental This API is experimental and may change in the future.
+     *
+     * @since RoadRunner 2025.1.2
+     */
+    #[Marshal(name: 'Summary')]
+    public string $summary = '';
+
     /**
      * ActivityOptions constructor.
      */
@@ -320,4 +333,22 @@ public function withPriority(Priority $priority): self
         $self->priority = $priority;
         return $self;
     }
+
+    /**
+     * Optional summary of the activity.
+     *
+     * Single-line fixed summary for this activity that will appear in UI/CLI.
+     * This can be in single-line Temporal Markdown format.
+     *
+     * @experimental This API is experimental and may change in the future.
+     *
+     * @return $this
+     */
+    #[Pure]
+    public function withSummary(string $summary): self
+    {
+        $self = clone $this;
+        $self->summary = $summary;
+        return $self;
+    }
 }

src/Interceptor/WorkflowOutboundCalls/TimerInput.php

@@ -11,6 +11,8 @@
 
 namespace Temporal\Interceptor\WorkflowOutboundCalls;
 
+use Temporal\Workflow\TimerOptions;
+
 /**
  * @psalm-immutable
  */
@@ -22,13 +24,19 @@ final class TimerInput
      */
     public function __construct(
         public readonly \DateInterval $interval,
+
+        /**
+         * @experimental This API is experimental and may change in the future.
+         */
+        public readonly ?TimerOptions $timerOptions,
     ) {}
 
     public function with(
         ?\DateInterval $interval = null,
     ): self {
         return new self(
             $interval ?? $this->interval,
+            $this->timerOptions,
         );
     }
 }

src/Internal/Transport/Request/NewTimer.php

@@ -12,6 +12,7 @@
 namespace Temporal\Internal\Transport\Request;
 
 use Carbon\CarbonInterval;
+use Temporal\Internal\Workflow\AwaitOptions;
 use Temporal\Worker\Transport\Command\Client\Request;
 
 /**
@@ -21,13 +22,29 @@ final class NewTimer extends Request
 {
     public const NAME = 'NewTimer';
 
-    public function __construct(private \DateInterval $interval)
-    {
-        parent::__construct(self::NAME, ['ms' => (int) CarbonInterval::make($interval)->totalMilliseconds]);
+    public function __construct(
+        private readonly AwaitOptions $awaitOptions,
+    ) {
+        $options = [
+            'ms' => (int) CarbonInterval::make($awaitOptions->interval)?->totalMilliseconds,
+        ];
+        if ($this->awaitOptions->options !== null) {
+            $options['summary'] = $this->awaitOptions->options->summary;
+        }
+
+        parent::__construct(self::NAME, $options);
     }
 
+    /**
+     * @deprecated use {@see getAwaitOptions()} instead.
+     */
     public function getInterval(): \DateInterval
     {
-        return $this->interval;
+        return $this->awaitOptions->interval;
+    }
+
+    public function getAwaitOptions(): AwaitOptions
+    {
+        return $this->awaitOptions;
     }
 }

src/Internal/Workflow/AwaitOptions.php

@@ -0,0 +1,33 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Workflow;
+
+use Temporal\Workflow\TimerOptions;
+
+/**
+ * @internal
+ * @experimental This API is experimental and may change in the future.
+ */
+class AwaitOptions
+{
+    public function __construct(
+        /**
+         * Await timeout.
+         */
+        public readonly \DateInterval $interval,
+
+        /**
+         * Options set for the underlying timer created.
+         */
+        public readonly ?TimerOptions $options,
+    ) {}
+}

src/Internal/Workflow/WorkflowContext.php

@@ -72,6 +72,7 @@
 use Temporal\Workflow\ContinueAsNewOptions;
 use Temporal\Workflow\ExternalWorkflowStubInterface;
 use Temporal\Workflow\Mutex;
+use Temporal\Workflow\TimerOptions;
 use Temporal\Workflow\WorkflowContextInterface;
 use Temporal\Workflow\WorkflowExecution;
 use Temporal\Workflow\WorkflowInfo;
@@ -455,15 +456,17 @@ public function newActivityStub(
         );
     }
 
-    public function timer($interval): PromiseInterface
+    public function timer($interval, ?TimerOptions $options = null): PromiseInterface
     {
         $dateInterval = DateInterval::parse($interval, DateInterval::FORMAT_SECONDS);
 
         return $this->callsInterceptor->with(
-            fn(TimerInput $input): PromiseInterface => $this->request(new NewTimer($input->interval)),
+            fn(TimerInput $input): PromiseInterface => $this->request(
+                new NewTimer(new AwaitOptions($input->interval, $options)),
+            ),
             /** @see WorkflowOutboundCallsInterceptor::timer() */
             'timer',
-        )(new TimerInput($dateInterval));
+        )(new TimerInput($dateInterval, $options));
     }
 
     public function request(
@@ -606,7 +609,7 @@ public function awaitWithTimeout($interval, callable|Mutex|PromiseInterface ...$
         return $this->callsInterceptor->with(
             function (AwaitWithTimeoutInput $input): PromiseInterface {
                 /** Bypassing {@see timer()} to acquire a timer request ID */
-                $request = new NewTimer($input->interval);
+                $request = new NewTimer(new AwaitOptions($input->interval, null));
                 $requestId = $request->getID();
                 $timer = $this->request($request);
                 \assert($timer instanceof CompletableResultInterface);

src/Workflow.php

@@ -32,6 +32,7 @@
 use Temporal\Workflow\ExternalWorkflowStubInterface;
 use Temporal\Workflow\Mutex;
 use Temporal\Workflow\ScopedContextInterface;
+use Temporal\Workflow\TimerOptions;
 use Temporal\Workflow\UpdateContext;
 use Temporal\Workflow\WorkflowContextInterface;
 use Temporal\Workflow\WorkflowExecution;
@@ -578,9 +579,9 @@ public static function sideEffect(callable $value): PromiseInterface
      * @return PromiseInterface<null>
      * @throws OutOfContextException in the absence of the workflow execution context.
      */
-    public static function timer($interval): PromiseInterface
+    public static function timer($interval, ?TimerOptions $options = null): PromiseInterface
     {
-        return self::getCurrentContext()->timer($interval);
+        return self::getCurrentContext()->timer($interval, $options);
     }
 
     /**

src/Workflow/TimerOptions.php

@@ -0,0 +1,47 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Workflow;
+
+use Temporal\Internal\Traits\CloneWith;
+
+/**
+ * TimerOptions is used to specify options for a timer.
+ *
+ * @experimental This API is experimental and may change in the future.
+ */
+final class TimerOptions
+{
+    use CloneWith;
+
+    public readonly string $summary;
+
+    private function __construct()
+    {
+        $this->summary = '';
+    }
+
+    public static function new(): self
+    {
+        return new self();
+    }
+
+    /**
+     * Single-line fixed summary for this timer that will appear in UI/CLI.
+     *
+     * This can be in single-line Temporal Markdown format.
+     */
+    public function withSummary(string $summary): self
+    {
+        /** @see self::$summary */
+        return $this->with('summary', $summary);
+    }
+}