Merge pull request #650: Public Destroyable interface

roxblnfk · web-flow · commit 40272bfa5ffe · 2025-09-12T12:28:56.000+04:00
diff --git a/composer.json b/composer.json
@@ -27,6 +27,7 @@
         "google/common-protos": "^4.9",
         "google/protobuf": "^4.31.1",
         "grpc/grpc": "^1.57",
+        "internal/destroy": "^1.0",
         "internal/promise": "^2.12",
         "nesbot/carbon": "^2.72.6 || ^3.8.4",
         "psr/log": "^2.0 || ^3.0.2",
diff --git a/psalm-baseline.xml b/psalm-baseline.xml
@@ -569,6 +569,11 @@
       <code><![CDATA[\IteratorAggregate]]></code>
     </MissingTemplateParam>
   </file>
+  <file src="src/Internal/Declaration/Instance.php">
+    <RedundantCondition>
+      <code><![CDATA[isset($this->context)]]></code>
+    </RedundantCondition>
+  </file>
   <file src="src/Internal/Declaration/Instantiator/ActivityInstantiator.php">
     <InvalidDocblock>
       <code><![CDATA[final class ActivityInstantiator extends Instantiator]]></code>
diff --git a/src/Internal/Declaration/Destroyable.php b/src/Internal/Declaration/Destroyable.php
diff --git a/src/Internal/Declaration/Instance.php b/src/Internal/Declaration/Instance.php
@@ -11,6 +11,7 @@
 
 namespace Temporal\Internal\Declaration;
 
+use Internal\Destroy\Destroyable;
 use Temporal\Exception\InstantiationException;
 use Temporal\Internal\Declaration\Prototype\Prototype;
 
@@ -46,6 +47,7 @@ public function getHandler(): MethodHandler
 
     public function destroy(): void
     {
+        isset($this->context) and $this->context instanceof Destroyable and $this->context->destroy();
         unset($this->handler, $this->context);
     }
 
diff --git a/src/Internal/Declaration/WorkflowInstance/QueryDispatcher.php b/src/Internal/Declaration/WorkflowInstance/QueryDispatcher.php
@@ -11,10 +11,10 @@
 
 namespace Temporal\Internal\Declaration\WorkflowInstance;
 
+use Internal\Destroy\Destroyable;
 use Temporal\Api\Sdk\V1\WorkflowInteractionDefinition;
 use Temporal\DataConverter\ValuesInterface;
 use Temporal\Interceptor\WorkflowInbound\QueryInput;
-use Temporal\Internal\Declaration\Destroyable;
 use Temporal\Internal\Declaration\MethodHandler;
 use Temporal\Internal\Declaration\Prototype\QueryDefinition;
 use Temporal\Internal\Declaration\Prototype\WorkflowPrototype;
diff --git a/src/Internal/Declaration/WorkflowInstance/SignalDispatcher.php b/src/Internal/Declaration/WorkflowInstance/SignalDispatcher.php
@@ -11,9 +11,9 @@
 
 namespace Temporal\Internal\Declaration\WorkflowInstance;
 
+use Internal\Destroy\Destroyable;
 use Temporal\Api\Sdk\V1\WorkflowInteractionDefinition;
 use Temporal\DataConverter\ValuesInterface;
-use Temporal\Internal\Declaration\Destroyable;
 use Temporal\Internal\Declaration\MethodHandler;
 use Temporal\Internal\Declaration\Prototype\SignalDefinition;
 use Temporal\Internal\Declaration\Prototype\WorkflowPrototype;
diff --git a/src/Internal/Declaration/WorkflowInstance/UpdateDispatcher.php b/src/Internal/Declaration/WorkflowInstance/UpdateDispatcher.php
@@ -11,12 +11,12 @@
 
 namespace Temporal\Internal\Declaration\WorkflowInstance;
 
+use Internal\Destroy\Destroyable;
 use React\Promise\Deferred;
 use React\Promise\PromiseInterface;
 use Temporal\Api\Sdk\V1\WorkflowInteractionDefinition;
 use Temporal\DataConverter\ValuesInterface;
 use Temporal\Interceptor\WorkflowInbound\UpdateInput;
-use Temporal\Internal\Declaration\Destroyable;
 use Temporal\Internal\Declaration\MethodHandler;
 use Temporal\Internal\Declaration\Prototype\UpdateDefinition;
 use Temporal\Internal\Declaration\Prototype\WorkflowPrototype;
diff --git a/src/Internal/Transport/ClientInterface.php b/src/Internal/Transport/ClientInterface.php
@@ -11,8 +11,8 @@
 
 namespace Temporal\Internal\Transport;
 
+use Internal\Destroy\Destroyable;
 use React\Promise\PromiseInterface;
-use Temporal\Internal\Declaration\Destroyable;
 use Temporal\Worker\Transport\Command\CommandInterface;
 use Temporal\Worker\Transport\Command\RequestInterface;
 use Temporal\Worker\Transport\Command\ServerResponseInterface;
diff --git a/src/Internal/Workflow/Process/Scope.php b/src/Internal/Workflow/Process/Scope.php
@@ -11,6 +11,7 @@
 
 namespace Temporal\Internal\Workflow\Process;
 
+use Internal\Destroy\Destroyable;
 use React\Promise\Deferred;
 use React\Promise\PromiseInterface;
 use Temporal\DataConverter\EncodedValues;
@@ -20,7 +21,6 @@
 use Temporal\Exception\Failure\TemporalFailure;
 use Temporal\Exception\InvalidArgumentException;
 use Temporal\Interceptor\WorkflowInbound\UpdateInput;
-use Temporal\Internal\Declaration\Destroyable;
 use Temporal\Internal\Declaration\MethodHandler;
 use Temporal\Internal\ServiceContainer;
 use Temporal\Internal\Transport\Request\Cancel;
@@ -296,6 +296,7 @@ public function destroy(): void
         $this->context?->destroy();
         $this->scopeContext?->destroy();
         unset(
+            $this->coroutine,
             $this->context,
             $this->scopeContext,
             $this->deferred,
diff --git a/src/Internal/Workflow/WorkflowContext.php b/src/Internal/Workflow/WorkflowContext.php
@@ -11,6 +11,7 @@
 
 namespace Temporal\Internal\Workflow;
 
+use Internal\Destroy\Destroyable;
 use Psr\Log\LoggerInterface;
 use Ramsey\Uuid\UuidInterface;
 use React\Promise\Deferred;
@@ -42,7 +43,6 @@
 use Temporal\Interceptor\WorkflowOutboundCalls\UpsertTypedSearchAttributesInput;
 use Temporal\Interceptor\WorkflowOutboundCallsInterceptor;
 use Temporal\Interceptor\WorkflowOutboundRequestInterceptor;
-use Temporal\Internal\Declaration\Destroyable;
 use Temporal\Internal\Declaration\EntityNameValidator;
 use Temporal\Internal\Declaration\WorkflowInstance\QueryDispatcher;
 use Temporal\Internal\Declaration\WorkflowInstance\SignalDispatcher;
@@ -701,10 +701,10 @@ public function destroy(): void
     {
         $this->awaits = [];
         $this->client->destroy();
-        $this->workflowInstance->destroy();
         $this->queryDispatcher->destroy();
         $this->signalDispatcher->destroy();
         $this->updateDispatcher->destroy();
+        $this->workflowInstance->destroy();
         unset($this->workflowInstance, $this->client);
     }
 
diff --git a/src/Workflow/WorkflowInterface.php b/src/Workflow/WorkflowInterface.php
@@ -13,11 +13,20 @@
 
 use Doctrine\Common\Annotations\Annotation\Target;
 use Spiral\Attributes\NamedArgumentConstructor;
+use Internal\Destroy\Destroyable;
 
 /**
+ * Marks a class or interface as a Workflow.
+ *
  * @Annotation
  * @NamedArgumentConstructor
  * @Target({ "CLASS" })
+ *
+ * To control memory usage of workflow instances you can implement {@see Destroyable} interface in the workflow class.
+ * The {@see Destroyable::destroy} method will be called when workflow instance is not needed anymore
+ * (for example, when workflow execution is completed, failed or need to be evicted from memory).
+ * You can use this method to help with memory management by breaking circular references.
+ * Note: the Workflow logger may not emit logs from within the destroy method.
  */
 #[\Attribute(\Attribute::TARGET_CLASS), NamedArgumentConstructor]
 class WorkflowInterface {}
diff --git a/tests/Acceptance/App/Logger/ClientLogger.php b/tests/Acceptance/App/Logger/ClientLogger.php
@@ -116,7 +116,7 @@ public function findByMessageAndContext(string $messagePattern, array $contextKe
     /**
      * Check if a specific log message exists.
      *
-     * @param string $messagePattern Regular expression to match against log messages
+     * @param non-empty-string $messagePattern Regular expression to match against log messages
      * @return bool True if at least one matching message is found
      */
     public function hasMessage(string $messagePattern): bool
diff --git a/tests/Acceptance/Extra/Stability/DestroyableTest.php b/tests/Acceptance/Extra/Stability/DestroyableTest.php
@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Stability\Destroyable;
+
+use Internal\Destroy\Destroyable;
+use PHPUnit\Framework\Attributes\Test;
+use Psr\Log\LoggerInterface;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Tests\Acceptance\App\Attribute\Stub;
+use Temporal\Tests\Acceptance\App\Logger\ClientLogger;
+use Temporal\Tests\Acceptance\App\Logger\LoggerFactory;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Workflow;
+use Temporal\Workflow\WorkflowMethod;
+
+class DestroyableTest extends TestCase
+{
+    #[Test]
+    public function destroyOnFinish(
+        #[Stub('Extra_Stability_Destroyable')] WorkflowStubInterface $stub,
+        ClientLogger $logger,
+    ): void {
+        $stub->getResult();
+
+        \usleep(100_000); // wait for logs to be flushed
+
+        self::assertTrue($logger->hasMessage('/Destroyable::destroy called/'));
+    }
+}
+
+#[Workflow\WorkflowInterface]
+class TestWorkflow implements Destroyable
+{
+    private LoggerInterface $logger;
+
+    #[WorkflowMethod('Extra_Stability_Destroyable')]
+    public function handle(): string
+    {
+        $this->logger = LoggerFactory::createServerLogger(
+            Workflow::getInfo()->taskQueue,
+        );
+        return 'result';
+    }
+
+    public function destroy(): void
+    {
+        Workflow::isReplaying();
+        $this->logger->info('Destroyable::destroy called');
+        unset($this->logger);
+    }
+}
diff --git a/tests/Unit/Router/StartWorkflowTestCase.php b/tests/Unit/Router/StartWorkflowTestCase.php
@@ -4,6 +4,7 @@
 
 namespace Temporal\Tests\Unit\Router;
 
+use Internal\Destroy\Destroyable;
 use Psr\Log\NullLogger;
 use React\Promise\Deferred;
 use Spiral\Attributes\AnnotationReader;
@@ -15,7 +16,6 @@
 use Temporal\DataConverter\EncodedValues;
 use Temporal\Exception\ExceptionInterceptorInterface;
 use Temporal\Interceptor\SimplePipelineProvider;
-use Temporal\Internal\Declaration\Destroyable;
 use Temporal\Internal\Declaration\Prototype\WorkflowPrototype;
 use Temporal\Internal\Declaration\Reader\WorkflowReader;
 use Temporal\Internal\Declaration\WorkflowInstance\QueryDispatcher;

Original file line number	Diff line number	Diff line change
`@@ -11,6 +11,7 @@`
`11`	`11`
`12`	`12`	`namespace Temporal\Internal\Declaration;`
`13`	`13`
	`14`	`+use Internal\Destroy\Destroyable;`
`14`	`15`	`use Temporal\Exception\InstantiationException;`
`15`	`16`	`use Temporal\Internal\Declaration\Prototype\Prototype;`
`16`	`17`
`@@ -46,6 +47,7 @@ public function getHandler(): MethodHandler`
`46`	`47`
`47`	`48`	`public function destroy(): void`
`48`	`49`	`{`
	`50`	`+ isset($this->context) and $this->context instanceof Destroyable and $this->context->destroy();`
`49`	`51`	`unset($this->handler, $this->context);`
`50`	`52`	`}`
`51`	`53`