Client improvements

.gitattributes

@@ -2,7 +2,7 @@
 
 .github/ export-ignore
 config/ export-ignore
-resources/ export-ignore
+resources/scripts/ export-ignore
 tests/ export-ignore
 
 .php_cs.dist export-ignore

composer.json

@@ -91,7 +91,7 @@
  },
  "extra": {
  "branch-alias": {
- "dev-master": "2.8.x-dev"
+ "dev-master": "2.9.x-dev"
  }
  },
  "config": {

psalm-baseline.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<files psalm-version="5.22.2@d768d914152dbbf3486c36398802f74e80cfde48">
+<files psalm-version="5.23.1@8471a896ccea3526b26d082f4461eeea467f10a4">
  <file src="src/Activity.php">
  <ImplicitToStringCast>
  <code><![CDATA[$type]]></code>
@@ -51,37 +51,11 @@
  <code><![CDATA[$retryOption->maximumInterval]]></code>
  <code><![CDATA[$waitRetry]]></code>
  </InvalidArgument>
- <PossiblyNullReference>
- <code><![CDATA[getTimestamp]]></code>
- </PossiblyNullReference>
- <UnsafeInstantiation>
- <code><![CDATA[new static($client)]]></code>
- <code><![CDATA[new static($client)]]></code>
- </UnsafeInstantiation>
  </file>
  <file src="src/Client/GRPC/Context.php">
  <ArgumentTypeCoercion>
  <code><![CDATA[$format]]></code>
  </ArgumentTypeCoercion>
- <PossiblyInvalidArgument>
- <code><![CDATA[$timeout]]></code>
- </PossiblyInvalidArgument>
- </file>
- <file src="src/Client/Interceptor/SystemInfoInterceptor.php">
- <ImpureFunctionCall>
- <code><![CDATA[$next($method, $arg, $ctx)]]></code>
- <code><![CDATA[$next($method, $arg, $ctx)]]></code>
- </ImpureFunctionCall>
- <ImpureMethodCall>
- <code><![CDATA[getCapabilities]]></code>
- <code><![CDATA[getInternalErrorDifferentiation]]></code>
- <code><![CDATA[getSignalAndQueryHeader]]></code>
- <code><![CDATA[getSystemInfo]]></code>
- <code><![CDATA[setServerCapabilities]]></code>
- </ImpureMethodCall>
- <InaccessibleProperty>
- <code><![CDATA[$this->systemInfoRequested]]></code>
- </InaccessibleProperty>
  </file>
  <file src="src/Client/Schedule/Action/StartWorkflowAction.php">
  <DocblockTypeContradiction>
@@ -156,9 +130,6 @@
  </PossiblyNullArgument>
  </file>
  <file src="src/Client/Update/UpdateHandle.php">
- <InvalidOperand>
- <code><![CDATA[$timeout * 1000]]></code>
- </InvalidOperand>
  <PossiblyNullArgument>
  <code><![CDATA[$result->getSuccess()]]></code>
  </PossiblyNullArgument>

resources/scripts/generate-client.php

@@ -7,11 +7,13 @@
  * file that was distributed with this source code.
  */
 
+use Grpc\BaseStub;
 use Laminas\Code\Generator;
 use Laminas\Code\Generator\MethodGenerator;
 use Temporal\Api\Workflowservice;
-use Grpc\BaseStub;
-use Temporal\Client\ServerCapabilities;
+use Temporal\Client\Common\ServerCapabilities;
+use Temporal\Client\GRPC\Connection\ConnectionInterface;
+use Temporal\Client\GRPC\ContextInterface;
 
 require __DIR__ . '/../../vendor/autoload.php';
 
@@ -88,20 +90,37 @@
 $interface = new Generator\InterfaceGenerator('ServiceClientInterface');
 
 
-// Add Capability methods
+// getContext(): ContextInterface
 $m = new MethodGenerator(
- 'getServerCapabilities',
+ 'getContext',
  [],
  MethodGenerator::FLAG_PUBLIC,
 );
-$m->setReturnType('?' . ServerCapabilities::class);
+$m->setReturnType(ContextInterface::class);
 $interface->addMethodFromGenerator($m);
+// withContext(ContextInterface $context): static
 $m = new MethodGenerator(
- 'setServerCapabilities',
- [Generator\ParameterGenerator::fromArray(['type' => ServerCapabilities::class, 'name' => 'capabilities'])],
+ 'withContext',
+ [Generator\ParameterGenerator::fromArray(['type' => ContextInterface::class, 'name' => 'context'])],
  MethodGenerator::FLAG_PUBLIC,
 );
-$m->setReturnType('void');
+$m->setReturnType('static');
+$interface->addMethodFromGenerator($m);
+// public function getConnection(): ConnectionInterface
+$m = new MethodGenerator(
+ 'getConnection',
+ [],
+ MethodGenerator::FLAG_PUBLIC,
+);
+$m->setReturnType(ConnectionInterface::class);
+$interface->addMethodFromGenerator($m);
+// Add Capability methods
+$m = new MethodGenerator(
+ 'getServerCapabilities',
+ [],
+ MethodGenerator::FLAG_PUBLIC,
+);
+$m->setReturnType('?' . ServerCapabilities::class);
 $interface->addMethodFromGenerator($m);
 
 foreach ($methods as $method => $options) {

src/Client/ClientOptions.php

@@ -27,7 +27,7 @@ class ClientOptions
  public const DEFAULT_NAMESPACE = 'default';
 
  /**
- * @var string
+ * @var non-empty-string
  */
  public string $namespace = self::DEFAULT_NAMESPACE;
 
@@ -51,7 +51,7 @@ public function __construct()
  }
 
  /**
- * @param string $namespace
+ * @param non-empty-string $namespace
  * @return $this
  */
  #[Pure]

src/Client/Common/ClientContextInterface.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Client\Common;
+
+use Temporal\Common\RetryOptions;
+
+interface ClientContextInterface
+{
+ /**
+ * All the service client calls will be made with the specified timeout.
+ *
+ * @param float $timeout in seconds
+ */
+ public function withTimeout(float $timeout): static;
+
+ /**
+ * Set the deadline for any service requests
+ */
+ public function withDeadline(\DateTimeInterface $deadline): static;
+
+ public function withRetryOptions(RetryOptions $options): static;
+
+ /**
+ * A metadata map to send to the server
+ *
+ * @param array<string, array<string>> $metadata
+ */
+ public function withMetadata(array $metadata): static;
+}

src/Client/Common/ClientContextTrait.php

@@ -0,0 +1,70 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Client\Common;
+
+use Temporal\Client\GRPC\ServiceClientInterface;
+use Temporal\Common\RetryOptions;
+use Temporal\Internal\Support\DateInterval;
+
+/**
+ * The trait provides methods to configure context in ServiceClientInterface.
+ *
+ * @internal
+ */
+trait ClientContextTrait
+{
+ private ServiceClientInterface $client;
+
+ /**
+ * All the service client calls will be made with the specified timeout.
+ *
+ * @param float $timeout in seconds
+ */
+ public function withTimeout(float $timeout): static
+ {
+ $new = clone $this;
+ $context = $new->client->getContext();
+ // Convert to milliseconds
+ /** @psalm-suppress InvalidOperand */
+ $timeout *= 1000;
+ $new->client = $new->client->withContext(
+ $context->withTimeout((int)$timeout, DateInterval::FORMAT_MILLISECONDS),
+ );
+
+ return $new;
+ }
+
+ /**
+ * Set the deadline for any service requests
+ */
+ public function withDeadline(\DateTimeInterface $deadline): static
+ {
+ $new = clone $this;
+ $context = $new->client->getContext();
+ $new->client = $new->client->withContext($context->withDeadline($deadline));
+ return $new;
+ }
+
+ public function withRetryOptions(RetryOptions $options): static
+ {
+ $new = clone $this;
+ $context = $new->client->getContext();
+ $new->client = $new->client->withContext($context->withRetryOptions($options));
+ return $new;
+ }
+
+ /**
+ * A metadata map to send to the server
+ *
+ * @param array<string, array<string>> $metadata
+ */
+ public function withMetadata(array $metadata): static
+ {
+ $new = clone $this;
+ $context = $new->client->getContext();
+ $new->client = $new->client->withContext($context->withMetadata($metadata));
+ return $new;
+ }
+}

src/Client/Paginator.php → src/Client/Common/Paginator.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace Temporal\Client;
+namespace Temporal\Client\Common;
 
 use Closure;
 use Countable;

src/Client/Common/ServerCapabilities.php

@@ -0,0 +1,83 @@
+<?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\Client\Common;
+
+final class ServerCapabilities
+{
+ /**
+ * @param bool $signalAndQueryHeader
+ * True if signal and query headers are supported.
+ * @param bool $internalErrorDifferentiation
+ * True if internal errors are differentiated from other types of errors for purposes of
+ * retrying non-internal errors.
+ * When unset/false, clients retry all failures. When true, clients should only retry
+ * non-internal errors.
+ * @param bool $activityFailureIncludeHeartbeat
+ * True if RespondActivityTaskFailed API supports including heartbeat details
+ * @param bool $supportsSchedules
+ * Supports scheduled workflow features.
+ * @param bool $encodedFailureAttributes
+ * True if server uses protos that include temporal.api.failure.v1.Failure.encoded_attributes
+ * @param bool $buildIdBasedVersioning
+ * True if server supports dispatching Workflow and Activity tasks based on a worker's build_id
+ * (see:
+ * https:/temporalio/proposals/blob/a123af3b559f43db16ea6dd31870bfb754c4dc5e/versioning/worker-versions.md)
+ * @param bool $upsertMemo
+ * True if server supports upserting workflow memo
+ * @param bool $eagerWorkflowStart
+ * True if server supports eager workflow task dispatching for the StartWorkflowExecution API
+ * @param bool $sdkMetadata
+ * True if the server knows about the sdk metadata field on WFT completions and will record
+ * it in history
+ * @param bool $countGroupByExecutionStatus
+ * True if the server supports count group by execution status
+ * (-- api-linter: core::0140::prepositions=disabled --)
+ */
+ public function __construct(
+ public readonly bool $signalAndQueryHeader = false,
+ public readonly bool $internalErrorDifferentiation = false,
+ public readonly bool $activityFailureIncludeHeartbeat = false,
+ public readonly bool $supportsSchedules = false,
+ public readonly bool $encodedFailureAttributes = false,
+ public readonly bool $buildIdBasedVersioning = false,
+ public readonly bool $upsertMemo = false,
+ public readonly bool $eagerWorkflowStart = false,
+ public readonly bool $sdkMetadata = false,
+ public readonly bool $countGroupByExecutionStatus = false,
+ ) {
+ }
+
+ /**
+ * True if signal and query headers are supported.
+ *
+ * @deprecated Use {@see self::$signalAndQueryHeader} instead.
+ */
+ public function isSignalAndQueryHeaderSupports(): bool
+ {
+ return $this->signalAndQueryHeader;
+ }
+
+ /**
+ * True if internal errors are differentiated from other types of errors for purposes of
+ * retrying non-internal errors.
+ * When unset/false, clients retry all failures. When true, clients should only retry
+ * non-internal errors.
+ *
+ * @deprecated Use {@see self::$internalErrorDifferentiation} instead.
+ */
+ public function isInternalErrorDifferentiation(): bool
+ {
+ return $this->internalErrorDifferentiation;
+ }
+}
+
+\class_alias(ServerCapabilities::class, 'Temporal\Client\ServerCapabilities');

src/Client/CountWorkflowExecutions.php

@@ -1,20 +1,14 @@
 <?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\Client;
 
-final class CountWorkflowExecutions
-{
- public function __construct(
- public readonly int $count,
- ) {
+if (!\class_exists(\Temporal\Client\Workflow\CountWorkflowExecutions::class)) {
+ /**
+ * @deprecated use {@see \Temporal\Client\Workflow\CountWorkflowExecutions} instead. Will be removed in the future.
+ */
+ class CountWorkflowExecutions
+ {
  }
 }