feat: Fibers API

psalm-baseline.xml

@@ -952,12 +952,6 @@
       <code><![CDATA[$name]]></code>
       <code><![CDATA[$name]]></code>
     </ArgumentTypeCoercion>
-    <LessSpecificReturnStatement>
-      <code><![CDATA[EncodedValues::decodePromise($this->request($request), $returnType)]]></code>
-    </LessSpecificReturnStatement>
-    <MoreSpecificReturnType>
-      <code><![CDATA[PromiseInterface]]></code>
-    </MoreSpecificReturnType>
   </file>
   <file src="src/Internal/Workflow/ChildWorkflowProxy.php">
     <MoreSpecificImplementedParamType>
@@ -968,43 +962,12 @@
     <ArgumentTypeCoercion>
       <code><![CDATA[$this->workflow]]></code>
     </ArgumentTypeCoercion>
-    <LessSpecificReturnStatement>
-      <code><![CDATA[$this->execution->promise()->then(
-            function (WorkflowExecution $execution) use ($name, $args) {
-                $request = new SignalExternalWorkflow(
-                    $this->getOptions()->namespace,
-                    $execution->getID(),
-                    null,
-                    $name,
-                    EncodedValues::fromValues($args),
-                    true,
-                );
-
-                return $this->request($request);
-            },
-        )]]></code>
-      <code><![CDATA[$this->start(...$args)->then(fn() => $this->getResult($returnType))]]></code>
-      <code><![CDATA[EncodedValues::decodePromise($started)]]></code>
-    </LessSpecificReturnStatement>
-    <MoreSpecificReturnType>
-      <code><![CDATA[PromiseInterface]]></code>
-      <code><![CDATA[PromiseInterface]]></code>
-      <code><![CDATA[PromiseInterface]]></code>
-    </MoreSpecificReturnType>
-    <PossiblyNullArgument>
-      <code><![CDATA[$this->result]]></code>
-    </PossiblyNullArgument>
   </file>
   <file src="src/Internal/Workflow/Input.php">
     <PropertyTypeCoercion>
       <code><![CDATA[$header ?? Header::empty()]]></code>
     </PropertyTypeCoercion>
   </file>
-  <file src="src/Internal/Workflow/Process/DeferredGenerator.php">
-    <UnevaluatedCode>
-      <code><![CDATA[yield;]]></code>
-    </UnevaluatedCode>
-  </file>
   <file src="src/Internal/Workflow/Process/Process.php">
     <PropertyNotSetInConstructor>
       <code><![CDATA[Process]]></code>

src/Exception/InvalidSuspendException.php

@@ -0,0 +1,21 @@
+<?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\Exception;
+
+/**
+ * Thrown when workflow execution is suspended outside of the workflow suspension protocol.
+ *
+ * The usual causes are a non-workflow asynchronous API that runs its own scheduler on
+ * {@see \Fiber::suspend()}, a suspending Temporal call made from a promise callback or a
+ * query handler, and a workflow handler that returns a Generator or a Promise.
+ */
+class InvalidSuspendException extends TemporalException {}

src/Internal/Declaration/Dispatcher/Dispatcher.php

@@ -113,9 +113,15 @@ private function createExecutorFromFunction(\ReflectionFunction $fun): \Closure
                 });
 
 
-                return $fun->isStatic()
-                    ? $closure->bindTo(null, $ctx::class)?->__invoke(...$arguments) ?? $closure(...$arguments)
-                    : $closure->call($ctx, ...$arguments);
+                if (!$fun->isStatic()) {
+                    return $closure->call($ctx, ...$arguments);
+                }
+
+                $bound = $closure->bindTo(null, $ctx::class);
+
+                return $bound === null
+                    ? $closure(...$arguments)
+                    : $bound(...$arguments);
             } finally {
                 \restore_error_handler();
             }

src/Internal/Support/StackRenderer.php

@@ -110,14 +110,14 @@ public static function renderProto(array $stackTrace): EnhancedStackTrace
 
         /** @var list<StackTraceFileLocation> $locations */
         $locations = [];
+        $userFrameSeen = false;
 
         foreach ($stackTrace as $line) {
             $location = (new StackTraceFileLocation());
 
             $isInternal = false;
             $file = $line['file'] ?? null;
             if ($file !== null) {
-                $location->setFilePath($file);
                 foreach (self::$ignorePaths as $str) {
                     if (\str_starts_with($file, $str)) {
                         $isInternal = true;
@@ -126,7 +126,13 @@ public static function renderProto(array $stackTrace): EnhancedStackTrace
                 }
             }
 
-            isset($line['line']) and $location->setLine($line['line']);
+            $exposeLocation = $isInternal || !$userFrameSeen;
+            if ($file !== null && $exposeLocation) {
+                $location->setFilePath($file);
+            }
+            if ($exposeLocation && isset($line['line'])) {
+                $location->setLine($line['line']);
+            }
 
             if (isset($line['function'])) {
                 $location->setFunctionName(\sprintf(
@@ -139,17 +145,19 @@ public static function renderProto(array $stackTrace): EnhancedStackTrace
 
             $locations[] = $location->setInternalCode($isInternal);
 
-            // Store source code for non-internal files
-            if (!$isInternal && $file !== null && !\array_key_exists($file, $sources)) {
-                try {
-                    $code = @\file_get_contents($file);
-                } catch (\Throwable $e) {
-                    $code = \sprintf("Cannot access code.\n---\n%s", $e->getMessage());
-                }
+            if (!$isInternal && $file !== null) {
+                if (!\array_key_exists($file, $sources)) {
+                    try {
+                        $code = @\file_get_contents($file);
+                    } catch (\Throwable $e) {
+                        $code = \sprintf("Cannot access code.\n---\n%s", $e->getMessage());
+                    }
 
-                $sources[$file] = (new StackTraceFileSlice())
-                    ->setLineOffset(0)
-                    ->setContent($code === false ? "Failed to read file." : $code);
+                    $sources[$file] = (new StackTraceFileSlice())
+                        ->setLineOffset(0)
+                        ->setContent($code === false ? "Failed to read file." : $code);
+                }
+                $userFrameSeen = true;
             }
         }
         $stacks[] = (new StackTrace())

src/Internal/Transport/CompletableResultInterface.php

@@ -16,7 +16,6 @@
 /**
  * @template T
  * @extends PromiseInterface<T>
- * @yield T
  */
 interface CompletableResultInterface extends PromiseInterface
 {

src/Internal/Workflow/ActivityProxy.php

@@ -21,7 +21,7 @@
 use Temporal\Internal\Declaration\Prototype\ActivityPrototype;
 use Temporal\Internal\Interceptor\Pipeline;
 use Temporal\Internal\Support\Reflection;
-use Temporal\Internal\Transport\CompletableResultInterface;
+use Temporal\Internal\Workflow\Process\Awaiter;
 use Temporal\Workflow\WorkflowContextInterface;
 
 /**
@@ -63,11 +63,10 @@ public function __construct(
         $this->ctx = $ctx;
     }
 
-    /**
-     * @return CompletableResultInterface
-     */
-    public function __call(string $method, array $args = []): PromiseInterface
+    public function __call(string $method, array $args = []): mixed
     {
+        Awaiter::assertManaged();
+
         $prototype = $this->findPrototypeByHandlerNameOrFail($method);
         $type = $prototype->getHandler()->getReturnType();
         $options = $this->options->mergeWith($prototype->getMethodRetry());
@@ -85,12 +84,12 @@ public function __call(string $method, array $args = []): PromiseInterface
             );
         }
 
-        return $prototype->isLocalActivity()
+        $result = $prototype->isLocalActivity()
             // Run local activity through an interceptor pipeline
             ? $this->callsInterceptor->with(
                 fn(ExecuteLocalActivityInput $input): PromiseInterface => $this->ctx
                     ->newUntypedActivityStub($input->options)
-                    ->execute($input->type, $input->args, $input->returnType, true),
+                    ->executeAsync($input->type, $input->args, $input->returnType, true),
                 /** @see WorkflowOutboundCallsInterceptor::executeLocalActivity() */
                 'executeLocalActivity',
             )(
@@ -107,7 +106,7 @@ public function __call(string $method, array $args = []): PromiseInterface
             : $this->callsInterceptor->with(
                 fn(ExecuteActivityInput $input): PromiseInterface => $this->ctx
                     ->newUntypedActivityStub($input->options)
-                    ->execute($input->type, $input->args, $input->returnType),
+                    ->executeAsync($input->type, $input->args, $input->returnType),
                 /** @see WorkflowOutboundCallsInterceptor::executeActivity() */
                 'executeActivity',
             )(
@@ -119,6 +118,8 @@ public function __call(string $method, array $args = []): PromiseInterface
                     $prototype->getHandler(),
                 )
             );
+
+        return Awaiter::await($result, interruptOnCancel: false);
     }
 
     private function findPrototypeByHandlerNameOrFail(string $name): ActivityPrototype

src/Internal/Workflow/ActivityStub.php

@@ -17,6 +17,7 @@
 use Temporal\Interceptor\Header;
 use Temporal\Interceptor\HeaderInterface;
 use Temporal\Internal\Marshaller\MarshallerInterface;
+use Temporal\Internal\Workflow\Process\Awaiter;
 use Temporal\Internal\Transport\Request\ExecuteActivity;
 use Temporal\Internal\Transport\Request\ExecuteLocalActivity;
 use Temporal\Worker\Transport\Command\RequestInterface;
@@ -60,6 +61,20 @@ public function execute(
         array $args = [],
         Type|string|\ReflectionClass|\ReflectionType|null $returnType = null,
         bool $isLocalActivity = false,
+    ): mixed {
+        Awaiter::assertManaged();
+
+        return Awaiter::await(
+            $this->executeAsync($name, $args, $returnType, $isLocalActivity),
+            interruptOnCancel: false,
+        );
+    }
+
+    public function executeAsync(
+        string $name,
+        array $args = [],
+        Type|string|\ReflectionClass|\ReflectionType|null $returnType = null,
+        bool $isLocalActivity = false,
     ): PromiseInterface {
         $request = $isLocalActivity ?
             new ExecuteLocalActivity($name, EncodedValues::fromValues($args), $this->getOptionsArray(), $this->header) :

src/Internal/Workflow/ChildWorkflowProxy.php

@@ -11,11 +11,10 @@
 
 namespace Temporal\Internal\Workflow;
 
-use React\Promise\PromiseInterface;
 use Temporal\DataConverter\Type;
 use Temporal\Internal\Declaration\Prototype\WorkflowPrototype;
 use Temporal\Internal\Support\Reflection;
-use Temporal\Internal\Transport\CompletableResultInterface;
+use Temporal\Internal\Workflow\Process\Awaiter;
 use Temporal\Workflow\ChildWorkflowOptions;
 use Temporal\Workflow\ChildWorkflowStubInterface;
 use Temporal\Workflow\WorkflowContextInterface;
@@ -49,10 +48,11 @@ public function __construct(
 
     /**
      * @param non-empty-string $method
-     * @return CompletableResultInterface
      */
-    public function __call(string $method, array $args): PromiseInterface
+    public function __call(string $method, array $args): mixed
     {
+        Awaiter::assertManaged();
+
         // If the proxy does not contain information about the running workflow,
         // then we try to create a new stub from the workflow method and start
         // the workflow.
@@ -90,7 +90,9 @@ public function __call(string $method, array $args): PromiseInterface
             if ($definition->method->getName() === $method) {
                 $args = Reflection::orderArguments($definition->method, $args);
 
-                return $this->stub->signal($name, $args);
+                $this->stub->signal($name, $args);
+
+                return null;
             }
         }