Merge pull request #630: Process special Temporal builtin prefixes

Author: roxblnfk

psalm-baseline.xml

@@ -1054,11 +1054,6 @@
       <code><![CDATA[new static()]]></code>
     </UnsafeInstantiation>
   </file>
-  <file src="src/Internal/Support/StackRenderer.php">
-    <PossiblyInvalidArgument>
-      <code><![CDATA[$path]]></code>
-    </PossiblyInvalidArgument>
-  </file>
   <file src="src/Internal/Transport/Client.php">
     <PossiblyInvalidArgument>
       <code><![CDATA[$command->getID()]]></code>
@@ -1272,6 +1267,9 @@
       <code><![CDATA[$parent]]></code>
       <code><![CDATA[$scope]]></code>
     </PropertyNotSetInConstructor>
+    <UnsupportedPropertyReferenceUsage>
+      <code><![CDATA[$ctx->trace = &$context->trace]]></code>
+    </UnsupportedPropertyReferenceUsage>
   </file>
   <file src="src/Internal/Workflow/WorkflowContext.php">
     <ArgumentTypeCoercion>

src/Client/Common/Paginator.php

@@ -4,13 +4,11 @@
 
 namespace Temporal\Client\Common;
 
-use IteratorAggregate;
-
 /**
  * Paginator that allows to iterate over all pages.
  *
  * @template TItem
- * @implements IteratorAggregate<TItem>
+ * @implements \IteratorAggregate<TItem>
  */
 final class Paginator implements \IteratorAggregate, \Countable
 {

src/Client/GRPC/Context.php

@@ -32,7 +32,7 @@ private function __construct()
             ->withInitialInterval(CarbonInterval::millisecond(500));
 
         $this->metadata = [
-            'client-name' => ['temporal-php-2'],
+            'client-name' => [SdkVersion::SDK_NAME],
             'client-version' => [SdkVersion::getSdkVersion()],
         ];
     }

src/Client/Workflow/WorkflowExecutionHistory.php

@@ -4,7 +4,6 @@
 
 namespace Temporal\Client\Workflow;
 
-use IteratorAggregate;
 use Temporal\Api\History\V1\History;
 use Temporal\Api\History\V1\HistoryEvent;
 use Temporal\Api\Workflowservice\V1\GetWorkflowExecutionHistoryResponse;
@@ -17,7 +16,7 @@
  *
  * @see History
  *
- * @implements IteratorAggregate<int, HistoryEvent>
+ * @implements \IteratorAggregate<int, HistoryEvent>
  * @internal
  */
 final class WorkflowExecutionHistory implements \IteratorAggregate

src/Common/SdkVersion.php

@@ -8,6 +8,11 @@
 
 final class SdkVersion
 {
+    /**
+     * The name of the SDK in Temporal nomenclature.
+     */
+    public const SDK_NAME = 'temporal-php-2';
+
     public const VERSION_REGX = '/^(\d++\.\d++\.\d++(?:-[\\w\\-.]+)?)/';
     public const PACKAGE_NAME = 'temporal/sdk';
 

src/Interceptor/HeaderInterface.php

@@ -19,7 +19,7 @@
  * @psalm-type TValue=mixed
  * @psalm-import-type TypeEnum from Type
  *
- * @extends IteratorAggregate<TKey, TValue>
+ * @extends \IteratorAggregate<TKey, TValue>
  */
 interface HeaderInterface extends \Countable, IteratorAggregate
 {

src/Internal/Declaration/EntityNameValidator.php

@@ -0,0 +1,87 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Declaration;
+
+/**
+ * Temporal entity name validator.
+ *
+ * @internal
+ */
+final class EntityNameValidator
+{
+    public const COMMON_BUILTIN_PREFIX = '__temporal_';
+    public const QUERY_TYPE_STACK_TRACE = "__stack_trace";
+    public const ENHANCED_QUERY_TYPE_STACK_TRACE = "__enhanced_stack_trace";
+
+    /**
+     * @throws \InvalidArgumentException
+     */
+    public static function validateWorkflow(string $name): void
+    {
+        self::validateCommonPrefix($name, 'Workflow name');
+    }
+
+    /**
+     * @throws \InvalidArgumentException
+     */
+    public static function validateQueryMethod(string $name): void
+    {
+        if ($name === self::QUERY_TYPE_STACK_TRACE || $name === self::ENHANCED_QUERY_TYPE_STACK_TRACE) {
+            throw new \InvalidArgumentException(
+                "The Query method name `$name` is reserved for built-in functionality and cannot be used.",
+            );
+        }
+
+        self::validateCommonPrefix($name, 'Query method');
+    }
+
+    /**
+     * @throws \InvalidArgumentException
+     */
+    public static function validateSignalMethod(string $name): void
+    {
+        self::validateCommonPrefix($name, 'Signal method');
+    }
+
+    /**
+     * @throws \InvalidArgumentException
+     */
+    public static function validateUpdateMethod(string $name): void
+    {
+        self::validateCommonPrefix($name, 'Update method');
+    }
+
+    /**
+     * @throws \InvalidArgumentException
+     */
+    public static function validateActivity(string $name): void
+    {
+        self::validateCommonPrefix($name, 'Activity type');
+    }
+
+    /**
+     * @throws \InvalidArgumentException
+     */
+    public static function validateTaskQueue(string $name): void
+    {
+        self::validateCommonPrefix($name, 'Task Queue name');
+    }
+
+    /**
+     * Throws an exception if the name starts with the common built-in prefix.
+     *
+     * @throws \InvalidArgumentException
+     */
+    private static function validateCommonPrefix(string $name, string $target): void
+    {
+        \str_starts_with($name, self::COMMON_BUILTIN_PREFIX) and throw new \InvalidArgumentException(
+            \sprintf(
+                "%s must not start with the internal prefix `%s`.",
+                $target,
+                self::COMMON_BUILTIN_PREFIX,
+            ),
+        );
+    }
+}

src/Internal/Declaration/Prototype/ActivityPrototype.php

@@ -15,6 +15,7 @@
 use Temporal\Activity\LocalActivityInterface;
 use Temporal\Common\MethodRetry;
 use Temporal\Internal\Declaration\ActivityInstance;
+use Temporal\Internal\Declaration\EntityNameValidator;
 
 final class ActivityPrototype extends Prototype
 {
@@ -32,6 +33,7 @@ public function __construct(
         \ReflectionMethod $handler,
         \ReflectionClass $class,
     ) {
+        EntityNameValidator::validateActivity($name);
         $this->isLocalActivity = $interface instanceof LocalActivityInterface;
 
         parent::__construct($name, $handler, $class);

src/Internal/Declaration/Prototype/Prototype.php

@@ -15,16 +15,11 @@
 
 abstract class Prototype implements PrototypeInterface
 {
-    protected string $name;
-    protected ?\ReflectionMethod $handler;
-    private \ReflectionClass $class;
-
-    public function __construct(string $name, ?\ReflectionMethod $handler, \ReflectionClass $class)
-    {
-        $this->handler = $handler;
-        $this->name = $name;
-        $this->class = $class;
-    }
+    public function __construct(
+        protected string $name,
+        protected ?\ReflectionMethod $handler,
+        private readonly \ReflectionClass $class,
+    ) {}
 
     /**
      * @template T of PrototypeInterface

src/Internal/Declaration/Prototype/WorkflowPrototype.php

@@ -13,6 +13,7 @@
 
 use Temporal\Common\CronSchedule;
 use Temporal\Common\MethodRetry;
+use Temporal\Internal\Declaration\EntityNameValidator;
 use Temporal\Workflow\ReturnType;
 use Temporal\Workflow\WorkflowInit;
 
@@ -43,6 +44,15 @@ final class WorkflowPrototype extends Prototype
     private ?ReturnType $returnType = null;
     private bool $hasInitializer = false;
 
+    public function __construct(
+        string $name,
+        ?\ReflectionMethod $handler,
+        \ReflectionClass $class,
+    ) {
+        EntityNameValidator::validateWorkflow($name);
+        parent::__construct($name, $handler, $class);
+    }
+
     /**
      * Indicates if the workflow has a constructor with {@see WorkflowInit} attribute.
      */
@@ -88,6 +98,8 @@ public function setReturnType(?ReturnType $attribute): void
 
     public function addQueryHandler(QueryDefinition $definition): void
     {
+        EntityNameValidator::validateQueryMethod($definition->name);
+
         $this->queryHandlers[$definition->name] = $definition;
     }
 
@@ -101,6 +113,8 @@ public function getQueryHandlers(): array
 
     public function addSignalHandler(SignalDefinition $definition): void
     {
+        EntityNameValidator::validateSignalMethod($definition->name);
+
         $this->signalHandlers[$definition->name] = $definition;
     }
 
@@ -114,6 +128,8 @@ public function getSignalHandlers(): array
 
     public function addUpdateHandler(UpdateDefinition $definition): void
     {
+        EntityNameValidator::validateUpdateMethod($definition->name);
+
         $this->updateHandlers[$definition->name] = $definition;
     }