refactor(nexus): replace operation input classes; enhance routing and headers testing

Author: xepozz

src/Exception/Failure/FailureConverter.php

@@ -172,6 +172,20 @@ public static function mapExceptionToFailure(\Throwable $e, DataConverterInterfa
                 $failure->setApplicationFailureInfo($info);
                 break;
 
+            case $e instanceof NexusOperationFailure:
+                $info = new NexusOperationFailureInfo();
+                /** @psalm-suppress DeprecatedMethod */
+                $info
+                    ->setScheduledEventId($e->getScheduledEventId())
+                    ->setEndpoint($e->getEndpoint())
+                    ->setService($e->getService())
+                    ->setOperation($e->getOperation())
+                    ->setOperationId($e->getOperationToken())
+                    ->setOperationToken($e->getOperationToken());
+
+                $failure->setNexusOperationExecutionFailureInfo($info);
+                break;
+
             default:
                 $info = new ApplicationFailureInfo();
                 $info->setType($e::class);

…ionInbound/NexusOperationCancelInput.php …perationInbound/CancelOperationInput.phpsrc/Interceptor/NexusOperationInbound/NexusOperationCancelInput.php renamed to src/Interceptor/NexusOperationInbound/CancelOperationInput.php src/Interceptor/NexusOperationInbound/NexusOperationCancelInput.php renamed to src/Interceptor/NexusOperationInbound/CancelOperationInput.php

@@ -17,24 +17,24 @@
 /**
  * @psalm-immutable
  */
-final class NexusOperationCancelInput
+final class CancelOperationInput
 {
     /**
      * @no-named-arguments
      * @internal Don't use the constructor. Use {@see self::with()} instead.
      */
     public function __construct(
-        public readonly OperationContext $context,
-        public readonly OperationCancelDetails $details,
+        public readonly OperationContext $operationContext,
+        public readonly OperationCancelDetails $cancelDetails,
     ) {}
 
     public function with(
-        ?OperationContext $context = null,
-        ?OperationCancelDetails $details = null,
+        ?OperationContext $operationContext = null,
+        ?OperationCancelDetails $cancelDetails = null,
     ): self {
         return new self(
-            $context ?? $this->context,
-            $details ?? $this->details,
+            $operationContext ?? $this->operationContext,
+            $cancelDetails ?? $this->cancelDetails,
         );
     }
 }

…tionInbound/NexusOperationStartInput.php …OperationInbound/StartOperationInput.phpsrc/Interceptor/NexusOperationInbound/NexusOperationStartInput.php renamed to src/Interceptor/NexusOperationInbound/StartOperationInput.php src/Interceptor/NexusOperationInbound/NexusOperationStartInput.php renamed to src/Interceptor/NexusOperationInbound/StartOperationInput.php

@@ -17,26 +17,26 @@
 /**
  * @psalm-immutable
  */
-final class NexusOperationStartInput
+final class StartOperationInput
 {
     /**
      * @no-named-arguments
      * @internal Don't use the constructor. Use {@see self::with()} instead.
      */
     public function __construct(
-        public readonly OperationContext $context,
-        public readonly OperationStartDetails $details,
+        public readonly OperationContext $operationContext,
+        public readonly OperationStartDetails $startDetails,
         public readonly mixed $input,
     ) {}
 
     public function with(
-        ?OperationContext $context = null,
-        ?OperationStartDetails $details = null,
+        ?OperationContext $operationContext = null,
+        ?OperationStartDetails $startDetails = null,
         mixed $input = null,
     ): self {
         return new self(
-            $context ?? $this->context,
-            $details ?? $this->details,
+            $operationContext ?? $this->operationContext,
+            $startDetails ?? $this->startDetails,
             $input ?? $this->input,
         );
     }

src/Interceptor/NexusOperationInboundCallsInterceptor.php

@@ -11,8 +11,8 @@
 
 namespace Temporal\Interceptor;
 
-use Temporal\Interceptor\NexusOperationInbound\NexusOperationCancelInput;
-use Temporal\Interceptor\NexusOperationInbound\NexusOperationStartInput;
+use Temporal\Interceptor\NexusOperationInbound\CancelOperationInput;
+use Temporal\Interceptor\NexusOperationInbound\StartOperationInput;
 use Temporal\Interceptor\Trait\NexusOperationInboundCallsInterceptorTrait;
 use Temporal\Internal\Interceptor\Interceptor;
 use Temporal\Nexus\Handler\OperationStartResult;
@@ -26,9 +26,9 @@
  * {
  *     use NexusOperationInboundCallsInterceptorTrait;
  *
- *     public function startNexusOperation(NexusOperationStartInput $input, callable $next): OperationStartResult
+ *     public function startOperation(StartOperationInput $input, callable $next): OperationStartResult
  *     {
- *         if (($input->context->headers['authorization'] ?? null) !== 'expected-token') {
+ *         if (($input->operationContext->headers['authorization'] ?? null) !== 'expected-token') {
  *             throw HandlerException::create(ErrorType::Unauthorized, 'Unauthorized');
  *         }
  *
@@ -42,12 +42,12 @@
 interface NexusOperationInboundCallsInterceptor extends Interceptor
 {
     /**
-     * @param callable(NexusOperationStartInput): OperationStartResult $next
+     * @param callable(StartOperationInput): OperationStartResult $next
      */
-    public function startNexusOperation(NexusOperationStartInput $input, callable $next): OperationStartResult;
+    public function startOperation(StartOperationInput $input, callable $next): OperationStartResult;
 
     /**
-     * @param callable(NexusOperationCancelInput): void $next
+     * @param callable(CancelOperationInput): void $next
      */
-    public function cancelNexusOperation(NexusOperationCancelInput $input, callable $next): void;
+    public function cancelOperation(CancelOperationInput $input, callable $next): void;
 }

src/Interceptor/NexusOperationOutbound/GetInfoInput.php

@@ -0,0 +1,29 @@
+<?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\Interceptor\NexusOperationOutbound;
+
+/**
+ * @psalm-immutable
+ */
+final class GetInfoInput
+{
+    /**
+     * @no-named-arguments
+     * @internal Don't use the constructor. Use {@see self::with()} instead.
+     */
+    public function __construct() {}
+
+    public function with(): self
+    {
+        return new self();
+    }
+}

src/Interceptor/NexusOperationOutboundCallsInterceptor.php

@@ -0,0 +1,55 @@
+<?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\Interceptor;
+
+use Temporal\Interceptor\NexusOperationOutbound\GetInfoInput;
+use Temporal\Interceptor\Trait\NexusOperationOutboundCallsInterceptorTrait;
+use Temporal\Internal\Interceptor\Interceptor;
+use Temporal\Nexus\NexusOperationContext;
+
+/**
+ * Intercepts calls a Nexus operation handler makes back into the Temporal APIs,
+ * counterpart to Java's {@code NexusOperationOutboundCallsInterceptor}.
+ *
+ * Java additionally intercepts {@code getMetricsScope()} and {@code getWorkflowClient()};
+ * neither has a clean PHP handler analogue (the metrics scope is RoadRunner-owned and the
+ * WorkflowClient is kept on the internal channel), so only {@see self::getInfo()} is exposed.
+ *
+ * It's recommended to use `NexusOperationOutboundCallsInterceptorTrait` when implementing this
+ * interface because the interface might be extended in the future. The trait will provide forward
+ * compatibility.
+ *
+ * ```php
+ * class MyNexusOperationOutboundCallsInterceptor implements NexusOperationOutboundCallsInterceptor
+ * {
+ *     use NexusOperationOutboundCallsInterceptorTrait;
+ *
+ *     public function getInfo(GetInfoInput $input, callable $next): NexusOperationContext
+ *     {
+ *         $info = $next($input);
+ *         // observe namespace/taskQueue, e.g. attach to a span
+ *         return $info;
+ *     }
+ * }
+ * ```
+ *
+ * @see NexusOperationOutboundCallsInterceptorTrait
+ */
+interface NexusOperationOutboundCallsInterceptor extends Interceptor
+{
+    /**
+     * Intercepts the call to read the Nexus operation info ({@see \Temporal\Nexus\Nexus::getOperationContext()}).
+     *
+     * @param callable(GetInfoInput): NexusOperationContext $next
+     */
+    public function getInfo(GetInfoInput $input, callable $next): NexusOperationContext;
+}

src/Interceptor/Trait/NexusOperationInboundCallsInterceptorTrait.php

@@ -11,8 +11,8 @@
 
 namespace Temporal\Interceptor\Trait;
 
-use Temporal\Interceptor\NexusOperationInbound\NexusOperationCancelInput;
-use Temporal\Interceptor\NexusOperationInbound\NexusOperationStartInput;
+use Temporal\Interceptor\NexusOperationInbound\CancelOperationInput;
+use Temporal\Interceptor\NexusOperationInbound\StartOperationInput;
 use Temporal\Interceptor\NexusOperationInboundCallsInterceptor;
 use Temporal\Nexus\Handler\OperationStartResult;
 
@@ -24,21 +24,21 @@
 trait NexusOperationInboundCallsInterceptorTrait
 {
     /**
-     * Default implementation of the `startNexusOperation` method.
+     * Default implementation of the `startOperation` method.
      *
-     * @see NexusOperationInboundCallsInterceptor::startNexusOperation()
+     * @see NexusOperationInboundCallsInterceptor::startOperation()
      */
-    public function startNexusOperation(NexusOperationStartInput $input, callable $next): OperationStartResult
+    public function startOperation(StartOperationInput $input, callable $next): OperationStartResult
     {
         return $next($input);
     }
 
     /**
-     * Default implementation of the `cancelNexusOperation` method.
+     * Default implementation of the `cancelOperation` method.
      *
-     * @see NexusOperationInboundCallsInterceptor::cancelNexusOperation()
+     * @see NexusOperationInboundCallsInterceptor::cancelOperation()
      */
-    public function cancelNexusOperation(NexusOperationCancelInput $input, callable $next): void
+    public function cancelOperation(CancelOperationInput $input, callable $next): void
     {
         $next($input);
     }

src/Interceptor/Trait/NexusOperationOutboundCallsInterceptorTrait.php

@@ -0,0 +1,34 @@
+<?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\Interceptor\Trait;
+
+use Temporal\Interceptor\NexusOperationOutbound\GetInfoInput;
+use Temporal\Interceptor\NexusOperationOutboundCallsInterceptor;
+use Temporal\Nexus\NexusOperationContext;
+
+/**
+ * Trait that provides a default interceptor implementation.
+ *
+ * @see NexusOperationOutboundCallsInterceptor
+ */
+trait NexusOperationOutboundCallsInterceptorTrait
+{
+    /**
+     * Default implementation of the `getInfo` method.
+     *
+     * @see NexusOperationOutboundCallsInterceptor::getInfo()
+     */
+    public function getInfo(GetInfoInput $input, callable $next): NexusOperationContext
+    {
+        return $next($input);
+    }
+}

src/Interceptor/WorkflowOutboundCalls/ExecuteNexusOperationInput.php

@@ -30,6 +30,7 @@ final class ExecuteNexusOperationInput
      * @internal Don't use the constructor. Use {@see self::with()} instead.
      */
     public function __construct(
+        public readonly string $endpoint,
         public readonly string $service,
         public readonly string $operation,
         public readonly array $args,
@@ -39,20 +40,25 @@ public function __construct(
     ) {}
 
     public function with(
+        ?string $endpoint = null,
         ?string $service = null,
         ?string $operation = null,
         ?array $args = null,
         ?NexusOperationOptions $options = null,
         null|Type|string|\ReflectionClass|\ReflectionType $returnType = null,
         ?array $nexusHeaders = null,
     ): self {
+        if ($endpoint !== null && $endpoint === '') {
+            throw new \InvalidArgumentException('$endpoint must be a non-empty string.');
+        }
         if ($service !== null && $service === '') {
             throw new \InvalidArgumentException('$service must be a non-empty string.');
         }
         if ($operation !== null && $operation === '') {
             throw new \InvalidArgumentException('$operation must be a non-empty string.');
         }
         return new self(
+            $endpoint ?? $this->endpoint,
             $service ?? $this->service,
             $operation ?? $this->operation,
             $args ?? $this->args,

src/Internal/Declaration/Instantiator/NexusServiceInstantiator.php

@@ -44,9 +44,6 @@ public function instantiate(NexusServicePrototype $prototype): NexusServiceInsta
         return new NexusServiceInstance($prototype, $instance, $handlers);
     }
 
-    /**
-     * @throws \ReflectionException
-     */
     private function resolveInstance(NexusServicePrototype $prototype): object
     {
         $factory = $prototype->getFactory();
@@ -69,7 +66,14 @@ private function resolveInstance(NexusServicePrototype $prototype): object
                 $prototype->getID(),
             ));
         }
-        return $reflection->newInstance();
+        try {
+            return $reflection->newInstance();
+        } catch (\ReflectionException $e) {
+            throw new NexusException(\sprintf(
+                'Service implementation for "%s" cannot be instantiated without arguments — bind via withInstance() or withFactory()',
+                $prototype->getID(),
+            ), 0, $e);
+        }
     }
 
     /**