From ee663825de890ba6482ff3c866e653d1f0be94e1 Mon Sep 17 00:00:00 2001 From: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com> Date: Thu, 19 Nov 2026 19:14:01 +0000 Subject: [PATCH 1/4] Let embedded workflow code signal other workflows durably Durable signal-external for the embedded engine (.github#223), following the native signal_external_workflow contract (server#1251). signalExternalWorkflow() (also Workflow::signalExternalWorkflow() and ChildWorkflowHandle::signalDurably()) records ExternalSignalRequested and exactly one ExternalSignalDelivered or ExternalSignalFailed at one workflow sequence, in the same transaction that admits an ordinary signal on the target. The target command is keyed workflow-signal:: and attributed through CommandContext::workflow(). Replay, query replay and cold replay return the recorded ExternalSignalResult and never send again; a changed target, run, name or arguments, or malformed resolution history, is a history shape mismatch. Missing, closed and refusing targets are recorded outcomes with Server's reasons (instance_not_found, run_not_found, run_not_active, historical_run, unknown_signal, self_target, runtime_reserved_signal, ...), not task failures. Signal names follow Server's rules and are refused in workflow code before anything is recorded. Callers can no longer use the workflow-signal: request-id prefix (request_id_reserved). The authoring API is experimental; the history events are frozen. Co-Authored-By: Claude Opus 5.5 --- .github/feature-test-timings.json | 2 + CHANGELOG.md | 23 + docs/api-stability.md | 50 +++ src/V2/ChildWorkflowHandle.php | 18 + src/V2/Enums/ExternalSignalOutcome.php | 19 + src/V2/Enums/HistoryEventType.php | 3 + .../InvalidCommandRequestIdException.php | 29 +- .../InvalidExternalSignalException.php | 25 ++ src/V2/ExternalSignalResult.php | 69 +++ .../Support/DefaultWorkflowControlPlane.php | 2 +- src/V2/Support/ExternalSignalDelivery.php | 198 +++++++++ src/V2/Support/ExternalSignalHistory.php | 256 +++++++++++ .../Support/HistoryEventPayloadContract.php | 12 + src/V2/Support/HistoryTimeline.php | 21 +- src/V2/Support/QueryStateReplayer.php | 27 ++ src/V2/Support/SignalExternalWorkflowCall.php | 117 +++++ src/V2/Support/WorkflowExecutor.php | 83 ++++ src/V2/Support/WorkflowFiberRunner.php | 35 ++ src/V2/Support/WorkflowStepHistory.php | 10 + src/V2/Webhooks.php | 49 +- src/V2/Workflow.php | 20 + src/V2/WorkflowStub.php | 40 ++ src/V2/functions.php | 32 ++ .../V2/V2SignalExternalWorkflowTest.php | 417 ++++++++++++++++++ ...signal-external-delivered-cold-replay.json | 99 +++++ ...-external-failed-outcomes-cold-replay.json | 197 +++++++++ ...gnal-external-request-without-outcome.json | 58 +++ .../signal-external-target-changed.json | 74 ++++ .../TestSignalExternalChildHandleWorkflow.php | 24 + .../TestSignalExternalInvalidNameWorkflow.php | 30 ++ .../V2/TestSignalExternalSenderWorkflow.php | 40 ++ .../V2/TestSignalExternalTargetWorkflow.php | 23 + .../V2/SignalExternalWorkflowCallTest.php | 264 +++++++++++ 33 files changed, 2355 insertions(+), 11 deletions(-) create mode 100644 src/V2/Enums/ExternalSignalOutcome.php create mode 100644 src/V2/Exceptions/InvalidExternalSignalException.php create mode 100644 src/V2/ExternalSignalResult.php create mode 100644 src/V2/Support/ExternalSignalDelivery.php create mode 100644 src/V2/Support/ExternalSignalHistory.php create mode 100644 src/V2/Support/SignalExternalWorkflowCall.php create mode 100644 tests/Feature/V2/V2SignalExternalWorkflowTest.php create mode 100644 tests/Fixtures/V2/ReplayRegression/signal-external-delivered-cold-replay.json create mode 100644 tests/Fixtures/V2/ReplayRegression/signal-external-failed-outcomes-cold-replay.json create mode 100644 tests/Fixtures/V2/ReplayRegression/signal-external-request-without-outcome.json create mode 100644 tests/Fixtures/V2/ReplayRegression/signal-external-target-changed.json create mode 100644 tests/Fixtures/V2/TestSignalExternalChildHandleWorkflow.php create mode 100644 tests/Fixtures/V2/TestSignalExternalInvalidNameWorkflow.php create mode 100644 tests/Fixtures/V2/TestSignalExternalSenderWorkflow.php create mode 100644 tests/Fixtures/V2/TestSignalExternalTargetWorkflow.php create mode 100644 tests/Unit/V2/SignalExternalWorkflowCallTest.php diff --git a/.github/feature-test-timings.json b/.github/feature-test-timings.json index 0b6164c6b..5bfc3d480 100644 --- a/.github/feature-test-timings.json +++ b/.github/feature-test-timings.json @@ -207,6 +207,7 @@ "tests/Feature/V2/V2ServiceModeParallelChildBarrierTest.php": 44.361974, "tests/Feature/V2/V2ServiceResponseReplayTest.php": 4.111694, "tests/Feature/V2/V2SideEffectWorkflowTest.php": 21.707655, + "tests/Feature/V2/V2SignalExternalWorkflowTest.php": 15.4, "tests/Feature/V2/V2StableCompensationExampleTest.php": 25.160551, "tests/Feature/V2/V2StandaloneActivityHostTest.php": 20.738894, "tests/Feature/V2/V2StartNamespaceTest.php": 3.144255, @@ -463,6 +464,7 @@ "tests/Feature/V2/V2ServiceModeParallelChildBarrierTest.php": 5.346706, "tests/Feature/V2/V2ServiceResponseReplayTest.php": 5.828296, "tests/Feature/V2/V2SideEffectWorkflowTest.php": 5.792351, + "tests/Feature/V2/V2SignalExternalWorkflowTest.php": 13.3, "tests/Feature/V2/V2StableCompensationExampleTest.php": 11.153563, "tests/Feature/V2/V2StandaloneActivityHostTest.php": 23.795291, "tests/Feature/V2/V2StartNamespaceTest.php": 2.658658, diff --git a/CHANGELOG.md b/CHANGELOG.md index bfe2f2264..c2726438e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,29 @@ ## Unreleased +- Experimental durable signal-external (.github#223): embedded workflow code + can signal another workflow in its namespace with + `signalExternalWorkflow($workflowId, $signalName, $arguments, $runId)` (also + `Workflow::signalExternalWorkflow()`), or its child with + `ChildWorkflowHandle::signalDurably()`. The request and its outcome are + recorded once in the sender's history (`ExternalSignalRequested`, then + `ExternalSignalDelivered` or `ExternalSignalFailed`, at one sequence) in the + same transaction that admits an ordinary signal on the target, keyed + `workflow-signal::` and attributed to the sender through + `CommandContext::workflow()`. Replay returns the recorded + `ExternalSignalResult` and never sends again. A missing, closed or refusing + target is a returned outcome (`target_not_found`, `target_closed` or + `rejected`, with Server's reasons, including `self_target` and + `runtime_reserved_signal`), not an exception. Signal names follow Server's + rules and are refused in workflow code with + `InvalidExternalSignalException` before anything is recorded. Callers can no + longer use the `workflow-signal:` request-id prefix for signals or + signal-with-start (`request_id_reserved`). The existing child-handle + `signal()` still sends directly. External PHP workers replay recorded + outcomes but refuse new commands. No database migration. + `docs/api-stability.md#durable-signal-external` explains why the API is + experimental and how embedded differs from Server. + - The business state-machine API is explicitly experimental (#1069). Every public class, interface and enum in `Workflow\V2\StateMachine`, native child start (`Workflow::startChild()`, `startChild()` and `StartedChildWorkflow`) and diff --git a/docs/api-stability.md b/docs/api-stability.md index b8ea80035..4cc0091c7 100644 --- a/docs/api-stability.md +++ b/docs/api-stability.md @@ -264,6 +264,53 @@ execution to a new definition, profile, rule or handler version. It also defines no recursive or shared child machines. See [business state machines](business-state-machines.md). +## Durable signal-external + +Durable signal-external lets embedded workflow code signal another workflow in +its namespace (.github#223). It is **experimental**: the +`Workflow\V2\signalExternalWorkflow()` function, the +`Workflow::signalExternalWorkflow()` facade method, +`ChildWorkflowHandle::signalDurably()`, `ExternalSignalResult`, +`Enums\ExternalSignalOutcome` and `Exceptions\InvalidExternalSignalException` +are marked `@experimental` and may change incompatibly in a minor release, never +in a patch release. They are not part of the stable facade list above. + +They are experimental, not stable, because the embedded surface is new while +the contract it implements is not. The command, its history events, the +`workflow-signal:` key and its outcomes follow the shipped Server 3.15.0 +contract (`docs/contracts/signal-external-workflow.md` in the server +repository) and the published Python, PHP SDK and Rust SDKs. The PHP authoring +names and result type have not shipped in any release. The embedded runtime +also differs from Server in ways a later minor release may still align: + +- Delivery is synchronous in the sending workflow task, so the sender needs no + extra workflow task (Server's `external_signal` turn) and continues at once. +- The worker-protocol runner (`WorkflowFiberRunner`, used by external PHP + workers) replays recorded outcomes but refuses a new command with + `UnsupportedWorkflowYieldException`. It does not advertise + `signal_external_workflow`. +- Embedded does not refuse the command while a run is cleaning up after a + cancellation request. Server refuses it then + (`signal_external_not_at_checkpoint`). + +The history events are frozen like every other event (see the table below): +once a run records them, every later release must replay them. The command +takes one workflow sequence. `ExternalSignalRequested` and exactly one of +`ExternalSignalDelivered` or `ExternalSignalFailed` are recorded at that +sequence in the same transaction that admits the signal on the target, keyed +on the target as `workflow-signal::`. Replay, query +replay and cold replay read the recorded outcome and never send again. A +changed target, run, signal name or arguments at a recorded sequence, or +malformed resolution history, is a `HistoryEventShapeMismatchException`. A +failed outcome (`target_not_found`, `target_closed` or `rejected`, with the +Server's reasons) is a returned value, not an exception. + +Callers cannot use the `workflow-signal:` request-id prefix for a signal or +signal-with-start. Embedded calls throw `InvalidCommandRequestIdException` with +`reason()` `request_id_reserved`; control-plane signals and embedded signal +webhooks return 422 with `reason: "request_id_reserved"`. Nothing is read or +written for the refused request. + ## What is covered A class, interface, method, constant, or property is part of the public API @@ -943,6 +990,9 @@ class, source file path, or stack trace to replay or handle a failure. | `ConditionWaitTimedOut` | `condition_wait_id`, `condition_key`, `condition_definition_fingerprint`, `sequence`, `timer_id`, `timeout_seconds` | `WorkflowStepHistory`, `ConditionWaits`, `QueryStateReplayer`, `HistoryTimeline` | | `ConditionWaitCancelled` (candidate 1.20) | `condition_wait_id`, `condition_wait_occurrence_id`, `condition_key`, `condition_definition_fingerprint`, `sequence`, `timer_id`, `timeout_seconds`, `cancelled_at`, `cancellation_scope` | `ScopedWaitCancellation`, `ConditionWaits`, `HistoryTimeline`, scope delivery and worker history consumers | | `SideEffectRecorded` | `sequence`, `result`, `reused_from_run_id`, `reused_recorded_at` | `WorkflowStepHistory`, `WorkflowExecutor`, `QueryStateReplayer`, `WorkflowFiberRunner`, `RedriveReplayClock` | +| `ExternalSignalRequested` | `sequence`, `target_workflow_instance_id`, `target_workflow_run_id`, `signal_name`, `arguments`, `payload_codec`, `request_id` | `ExternalSignalHistory`, `WorkflowStepHistory`, `WorkflowExecutor`, `QueryStateReplayer`, `WorkflowFiberRunner`, `HistoryTimeline` | +| `ExternalSignalDelivered` | `sequence`, `target_workflow_instance_id`, `target_workflow_run_id`, `signal_name`, `request_id`, `outcome`, `target_command_id`, `target_signal_id`, `retained` | `ExternalSignalHistory`, `WorkflowStepHistory`, `WorkflowExecutor`, `QueryStateReplayer`, `WorkflowFiberRunner`, `HistoryTimeline` | +| `ExternalSignalFailed` | `sequence`, `target_workflow_instance_id`, `target_workflow_run_id`, `signal_name`, `request_id`, `outcome`, `reason`, `message`, `target_command_id` | `ExternalSignalHistory`, `WorkflowStepHistory`, `WorkflowExecutor`, `QueryStateReplayer`, `WorkflowFiberRunner`, `HistoryTimeline` | | `VersionMarkerRecorded` | `sequence`, `change_id`, `version`, `min_supported`, `max_supported`, `reused_from_run_id`, `reused_recorded_at` | `WorkflowStepHistory`, `WorkflowExecutor`, `QueryStateReplayer`, `WorkflowFiberRunner`, `RedriveReplayClock` | | `ChildWorkflowScheduled` | `sequence`, `workflow_link_id`, `child_call_id`, `child_workflow_instance_id`, `child_workflow_run_id`, `child_workflow_class`, `child_workflow_type`, `child_run_number`, `parent_close_policy`, `retry_policy`, `timeout_policy`, `parallel_group_id`, `parallel_group_kind`, `parallel_group_base_sequence`, `parallel_group_size`, `parallel_group_index`, `parallel_group_path`, `reused_from_run_id`, `reused_recorded_at` | `WorkflowStepHistory`, `WorkflowExecutor`, `QueryStateReplayer`, `ChildRunHistory`, `ParallelChildGroup`, `RunLineageView`, `FailedRunRedrivePlan` | | `ChildRunStarted` | `sequence`, `workflow_link_id`, `child_call_id`, `child_workflow_instance_id`, `child_workflow_run_id`, `child_workflow_class`, `child_workflow_type`, `child_run_number`, `child_status`, `parent_close_policy`, `retry_policy`, `timeout_policy`, `execution_timeout_seconds`, `run_timeout_seconds`, `execution_deadline_at`, `run_deadline_at`, `retry_attempt`, `retry_of_child_workflow_run_id`, `retry_backoff_seconds`, `parallel_group_id`, `parallel_group_kind`, `parallel_group_base_sequence`, `parallel_group_size`, `parallel_group_index`, `parallel_group_path`, `reused_from_run_id`, `reused_recorded_at` | `ChildRunHistory`, `ParallelChildGroup`, `RunLineageView`, worker history payload consumers, `FailedRunRedrivePlan` | diff --git a/src/V2/ChildWorkflowHandle.php b/src/V2/ChildWorkflowHandle.php index d327ec5f9..c07fa5b92 100644 --- a/src/V2/ChildWorkflowHandle.php +++ b/src/V2/ChildWorkflowHandle.php @@ -4,6 +4,8 @@ namespace Workflow\V2; +use Workflow\V2\Support\SignalExternalWorkflowCall; + final class ChildWorkflowHandle { public function __construct( @@ -61,6 +63,22 @@ public function signal(string $name, ...$arguments): ?CommandResult return $this->signalWithArguments($name, $arguments); } + /** + * Durably signal this child from the parent's workflow code. + * + * Unlike {@see signal()}, which sends directly, this is the durable + * signal-external command: it is recorded once in the parent's history and + * replay returns the recorded {@see ExternalSignalResult} without sending + * again. It targets the child's current run. + * + * @experimental Durable signal-external may change in a minor release. + * See docs/api-stability.md#durable-signal-external. + */ + public function signalDurably(string $name, mixed ...$arguments): ExternalSignalResult|SignalExternalWorkflowCall + { + return signalExternalWorkflow($this->workflowInstanceId, $name, $arguments); + } + /** * @param array $arguments */ diff --git a/src/V2/Enums/ExternalSignalOutcome.php b/src/V2/Enums/ExternalSignalOutcome.php new file mode 100644 index 000000000..49b12eaab --- /dev/null +++ b/src/V2/Enums/ExternalSignalOutcome.php @@ -0,0 +1,19 @@ +reason; } /** diff --git a/src/V2/Exceptions/InvalidExternalSignalException.php b/src/V2/Exceptions/InvalidExternalSignalException.php new file mode 100644 index 000000000..66ed7d842 --- /dev/null +++ b/src/V2/Exceptions/InvalidExternalSignalException.php @@ -0,0 +1,25 @@ +outcome === ExternalSignalOutcome::Delivered; + } + + /** + * @return array{ + * outcome: string, + * reason: string|null, + * message: string|null, + * target_workflow_id: string, + * target_run_id: string|null, + * signal_name: string, + * request_id: string, + * target_command_id: string|null, + * target_signal_id: string|null, + * retained: bool + * } + */ + public function toArray(): array + { + return [ + 'outcome' => $this->outcome->value, + 'reason' => $this->reason, + 'message' => $this->message, + 'target_workflow_id' => $this->targetWorkflowId, + 'target_run_id' => $this->targetRunId, + 'signal_name' => $this->signalName, + 'request_id' => $this->requestId, + 'target_command_id' => $this->targetCommandId, + 'target_signal_id' => $this->targetSignalId, + 'retained' => $this->retained, + ]; + } +} diff --git a/src/V2/Support/DefaultWorkflowControlPlane.php b/src/V2/Support/DefaultWorkflowControlPlane.php index 6a3a369bb..a9cda3562 100644 --- a/src/V2/Support/DefaultWorkflowControlPlane.php +++ b/src/V2/Support/DefaultWorkflowControlPlane.php @@ -1410,7 +1410,7 @@ private function invalidRequestIdResult(string $instanceId, InvalidCommandReques 'workflow_command_id' => null, 'command_id' => null, 'update_id' => null, - 'reason' => 'invalid_request_id', + 'reason' => $exception->reason(), 'message' => $exception->getMessage(), 'validation_errors' => $exception->validationErrors(), 'status' => 422, diff --git a/src/V2/Support/ExternalSignalDelivery.php b/src/V2/Support/ExternalSignalDelivery.php new file mode 100644 index 000000000..4fafbfb78 --- /dev/null +++ b/src/V2/Support/ExternalSignalDelivery.php @@ -0,0 +1,198 @@ +:`. Because the sender's + * history and the target's admission share one transaction, a task that + * rolls back sends nothing and a committed task never sends again. + * + * @internal + */ +final class ExternalSignalDelivery +{ + /** + * @return array{event_type: HistoryEventType, payload: array} + */ + public static function deliver(WorkflowRun $sender, int $sequence, SignalExternalWorkflowCall $call): array + { + $requestId = ExternalSignalHistory::requestId($sender->id, $sequence); + $identity = [ + 'sequence' => $sequence, + 'target_workflow_instance_id' => $call->workflowId, + 'signal_name' => $call->signalName, + 'request_id' => $requestId, + ]; + + if ($call->workflowId === $sender->workflow_instance_id) { + return self::failed( + $identity, + null, + ExternalSignalOutcome::Rejected, + 'self_target', + null, + 'A workflow cannot signal its own instance as a durable signal-external command.' + ); + } + + if ($call->signalName === WorkflowStub::MESSAGE_STREAM_RUNTIME_SIGNAL) { + return self::failed( + $identity, + null, + ExternalSignalOutcome::Rejected, + 'runtime_reserved_signal', + null, + 'The signal name is reserved for the runtime message stream.' + ); + } + + /** @var WorkflowInstance|null $instance */ + $instance = ConfiguredV2Models::query('instance_model', WorkflowInstance::class) + ->find($call->workflowId); + + // Exact identity in the sender's namespace: a collation-folded match + // or a workflow in another namespace is not this target. + if (! $instance instanceof WorkflowInstance + || $instance->id !== $call->workflowId + || NamespaceScope::canonical(self::stringValue($instance->namespace)) + !== NamespaceScope::canonical(self::stringValue($sender->namespace))) { + return self::failed( + $identity, + null, + ExternalSignalOutcome::TargetNotFound, + 'instance_not_found', + null, + sprintf('No workflow instance [%s] exists in this namespace.', $call->workflowId) + ); + } + + if ($call->runId !== null) { + /** @var WorkflowRun|null $run */ + $run = ConfiguredV2Models::query('run_model', WorkflowRun::class) + ->find($call->runId); + + if (! $run instanceof WorkflowRun + || $run->id !== $call->runId + || $run->workflow_instance_id !== $instance->id) { + return self::failed( + $identity, + null, + ExternalSignalOutcome::TargetNotFound, + 'run_not_found', + null, + sprintf('Workflow instance [%s] has no run [%s].', $instance->id, $call->runId) + ); + } + } + + $result = WorkflowStub::loadSelection($instance->id, $call->runId) + ->withCommandContext(CommandContext::workflow($sender->workflow_instance_id, $sender->id, $sequence)) + ->attemptExternalWorkflowSignal($requestId, $call->signalName, $call->arguments); + + return self::resolution($identity, $call, $result); + } + + /** + * @param array $identity + * @return array{event_type: HistoryEventType, payload: array} + */ + private static function resolution(array $identity, SignalExternalWorkflowCall $call, CommandResult $result): array + { + if ($result->accepted()) { + /** @var WorkflowSignal|null $signal */ + $signal = ConfiguredV2Models::query('signal_model', WorkflowSignal::class) + ->where('workflow_command_id', $result->commandId()) + ->first(); + + return [ + 'event_type' => HistoryEventType::ExternalSignalDelivered, + 'payload' => [ + ...$identity, + 'target_workflow_run_id' => $result->runId(), + 'outcome' => ExternalSignalOutcome::Delivered->value, + 'target_command_id' => $result->commandId(), + 'target_signal_id' => $signal?->id, + 'retained' => $result->retained(), + ], + ]; + } + + $reason = $result->rejectionReason() ?? 'rejected'; + // A key conflict refuses against the retained command and records + // nothing new on the target. + $targetCommandId = $result->requestIdConflict() ? null : $result->commandId(); + $targetRunId = $result->requestIdConflict() ? null : $result->runId(); + + [$outcome, $reason, $message] = match ($reason) { + 'instance_not_started' => [ + ExternalSignalOutcome::TargetNotFound, + 'instance_not_found', + sprintf('Workflow instance [%s] has not started.', $call->workflowId), + ], + 'run_not_active' => [ + ExternalSignalOutcome::TargetClosed, + 'run_not_active', + 'The target run is closed.', + ], + 'selected_run_not_current' => [ + ExternalSignalOutcome::TargetClosed, + 'historical_run', + 'The requested run has been replaced by a newer run of the target instance.', + ], + default => [ + ExternalSignalOutcome::Rejected, + $reason, + $result->message() ?? sprintf('The target refused the signal: %s.', $reason), + ], + }; + + return self::failed($identity, $targetRunId, $outcome, $reason, $targetCommandId, $message); + } + + /** + * @param array $identity + * @return array{event_type: HistoryEventType, payload: array} + */ + private static function failed( + array $identity, + ?string $targetRunId, + ExternalSignalOutcome $outcome, + string $reason, + ?string $targetCommandId, + string $message, + ): array { + return [ + 'event_type' => HistoryEventType::ExternalSignalFailed, + 'payload' => [ + ...$identity, + 'target_workflow_run_id' => $targetRunId, + 'outcome' => $outcome->value, + 'reason' => $reason, + 'message' => $message, + 'target_command_id' => $targetCommandId, + ], + ]; + } + + private static function stringValue(mixed $value): ?string + { + return is_string($value) ? $value : null; + } +} diff --git a/src/V2/Support/ExternalSignalHistory.php b/src/V2/Support/ExternalSignalHistory.php new file mode 100644 index 000000000..5b9cbfdb2 --- /dev/null +++ b/src/V2/Support/ExternalSignalHistory.php @@ -0,0 +1,256 @@ +:`. + * Callers cannot use the prefix (`request_id_reserved`). + */ + public const REQUEST_ID_PREFIX = 'workflow-signal:'; + + public const SHAPE = 'external signal'; + + public static function requestId(string $senderRunId, int $sequence): string + { + return self::REQUEST_ID_PREFIX . $senderRunId . ':' . $sequence; + } + + public static function isReservedRequestId(mixed $requestId): bool + { + return is_string($requestId) && str_starts_with($requestId, self::REQUEST_ID_PREFIX); + } + + /** + * The recorded outcome for this command, or null when nothing is recorded + * at the sequence yet. + */ + public static function recordedResult( + WorkflowRun $run, + int $sequence, + SignalExternalWorkflowCall $call, + ): ?ExternalSignalResult { + $requested = self::events($run, $sequence, HistoryEventType::ExternalSignalRequested); + $resolutions = [ + ...self::events($run, $sequence, HistoryEventType::ExternalSignalDelivered), + ...self::events($run, $sequence, HistoryEventType::ExternalSignalFailed), + ]; + + if ($requested === [] && $resolutions === []) { + return null; + } + + if (count($requested) !== 1) { + self::invalid($sequence, $requested === [] + ? 'An external signal outcome was recorded without its request.' + : 'More than one external signal request was recorded at one sequence.'); + } + + $request = $requested[0]; + self::assertSameIntent($sequence, $request, $call); + + if (count($resolutions) !== 1) { + self::invalid($sequence, $resolutions === [] + ? 'An external signal request was recorded without its outcome.' + : 'More than one external signal outcome was recorded at one sequence.'); + } + + return self::resultFor($sequence, $request, $resolutions[0]); + } + + /** + * The recorded resolution at this sequence, for replay time. + */ + public static function resolutionEvent(WorkflowRun $run, int $sequence): ?WorkflowHistoryEvent + { + return [ + ...self::events($run, $sequence, HistoryEventType::ExternalSignalDelivered), + ...self::events($run, $sequence, HistoryEventType::ExternalSignalFailed), + ][0] ?? null; + } + + /** + * @return array{codec: string, blob: string} + */ + public static function argumentsEnvelope(SignalExternalWorkflowCall $call, ?string $payloadCodec): array + { + $codec = CodecRegistry::canonicalize($payloadCodec ?? CodecRegistry::defaultCodec()); + + return [ + 'codec' => $codec, + 'blob' => Serializer::serializeWithCodec($codec, $call->arguments), + ]; + } + + private static function assertSameIntent( + int $sequence, + WorkflowHistoryEvent $request, + SignalExternalWorkflowCall $call, + ): void { + $payload = is_array($request->payload) ? $request->payload : []; + $recordedRun = $payload['target_workflow_run_id'] ?? null; + + $changed = match (true) { + ($payload['target_workflow_instance_id'] ?? null) !== $call->workflowId => 'target workflow', + $recordedRun !== $call->runId => 'target run', + ($payload['signal_name'] ?? null) !== $call->signalName => 'signal name', + ! self::argumentsMatch($payload, $call) => 'arguments', + default => null, + }; + + if ($changed === null) { + return; + } + + throw new HistoryEventShapeMismatchException( + $sequence, + self::SHAPE . ' with matching ' . $changed, + [HistoryEventType::ExternalSignalRequested->value], + sprintf( + 'Recorded external signal %s does not match the current yielded signal (external_signal_mismatch).', + $changed, + ), + ); + } + + /** + * Compare after one codec round trip, so equal values match whatever + * encoder recorded them. Argument values never appear in a diagnostic. + * + * @param array $payload + */ + private static function argumentsMatch(array $payload, SignalExternalWorkflowCall $call): bool + { + $arguments = $payload['arguments'] ?? null; + $codec = is_array($arguments) && is_string($arguments['codec'] ?? null) + ? $arguments['codec'] + : (is_string($payload['payload_codec'] ?? null) ? $payload['payload_codec'] : null); + $blob = is_array($arguments) ? ($arguments['blob'] ?? null) : $arguments; + + if (! is_string($codec) || ! is_string($blob)) { + return false; + } + + try { + $recorded = Serializer::unserializeWithCodec($codec, $blob); + + return is_array($recorded) + && hash_equals( + Serializer::serializeWithCodec( + $codec, + array_is_list($recorded) ? array_values($recorded) : $recorded + ), + Serializer::serializeWithCodec($codec, $call->arguments), + ); + } catch (Throwable) { + return false; + } + } + + private static function resultFor( + int $sequence, + WorkflowHistoryEvent $request, + WorkflowHistoryEvent $resolution, + ): ExternalSignalResult { + $requested = is_array($request->payload) ? $request->payload : []; + $payload = is_array($resolution->payload) ? $resolution->payload : []; + + foreach (['target_workflow_instance_id', 'signal_name', 'request_id'] as $field) { + if (($payload[$field] ?? null) !== ($requested[$field] ?? null)) { + self::invalid($sequence, sprintf('The external signal outcome names a different %s.', $field)); + } + } + + $outcome = is_string($payload['outcome'] ?? null) + ? ExternalSignalOutcome::tryFrom($payload['outcome']) + : null; + $delivered = $resolution->event_type === HistoryEventType::ExternalSignalDelivered; + + if (! $outcome instanceof ExternalSignalOutcome + || ($outcome === ExternalSignalOutcome::Delivered) !== $delivered) { + self::invalid($sequence, 'The external signal outcome is unknown or does not match its event.'); + } + + $reason = self::stringValue($payload['reason'] ?? null); + if (! $delivered && $reason === null) { + self::invalid($sequence, 'A failed external signal outcome has no reason.'); + } + + return new ExternalSignalResult( + outcome: $outcome, + reason: $delivered ? null : $reason, + message: self::stringValue($payload['message'] ?? null), + targetWorkflowId: (string) $requested['target_workflow_instance_id'], + targetRunId: self::stringValue($payload['target_workflow_run_id'] ?? null), + signalName: (string) $requested['signal_name'], + requestId: (string) ($requested['request_id'] ?? ''), + targetCommandId: self::stringValue($payload['target_command_id'] ?? null), + targetSignalId: self::stringValue($payload['target_signal_id'] ?? null), + retained: ($payload['retained'] ?? false) === true, + ); + } + + /** + * @return list + */ + private static function events(WorkflowRun $run, int $sequence, HistoryEventType $type): array + { + return $run->historyEvents + ->filter(static fn (WorkflowHistoryEvent $event): bool => $event->event_type === $type + && self::intValue($event->payload['sequence'] ?? null) === $sequence) + ->values() + ->all(); + } + + private static function invalid(int $sequence, string $detail): never + { + throw new HistoryEventShapeMismatchException( + $sequence, + self::SHAPE, + [ + HistoryEventType::ExternalSignalRequested->value, + HistoryEventType::ExternalSignalDelivered->value, + HistoryEventType::ExternalSignalFailed->value, + ], + $detail . ' (external_signal_history_invalid)', + ); + } + + private static function stringValue(mixed $value): ?string + { + return is_string($value) && $value !== '' ? $value : null; + } + + private static function intValue(mixed $value): ?int + { + if (is_int($value)) { + return $value; + } + + return is_string($value) && ctype_digit($value) ? (int) $value : null; + } +} diff --git a/src/V2/Support/HistoryEventPayloadContract.php b/src/V2/Support/HistoryEventPayloadContract.php index 531caa44d..585424324 100644 --- a/src/V2/Support/HistoryEventPayloadContract.php +++ b/src/V2/Support/HistoryEventPayloadContract.php @@ -632,6 +632,18 @@ final class HistoryEventPayloadContract 'parallel_group_path', ], 'SideEffectRecorded' => ['sequence', 'result', 'reused_from_run_id', 'reused_recorded_at'], + 'ExternalSignalRequested' => [ + 'sequence', 'target_workflow_instance_id', 'target_workflow_run_id', 'signal_name', + 'arguments', 'payload_codec', 'request_id', + ], + 'ExternalSignalDelivered' => [ + 'sequence', 'target_workflow_instance_id', 'target_workflow_run_id', 'signal_name', + 'request_id', 'outcome', 'target_command_id', 'target_signal_id', 'retained', + ], + 'ExternalSignalFailed' => [ + 'sequence', 'target_workflow_instance_id', 'target_workflow_run_id', 'signal_name', + 'request_id', 'outcome', 'reason', 'message', 'target_command_id', + ], 'VersionMarkerRecorded' => [ 'sequence', 'change_id', diff --git a/src/V2/Support/HistoryTimeline.php b/src/V2/Support/HistoryTimeline.php index b5d54ad83..0bbeee765 100644 --- a/src/V2/Support/HistoryTimeline.php +++ b/src/V2/Support/HistoryTimeline.php @@ -435,7 +435,10 @@ private static function kindFor(HistoryEventType $eventType): string HistoryEventType::SignalWaitOpened, HistoryEventType::SignalWaitCancelled, HistoryEventType::SignalRejected, - HistoryEventType::SignalApplied => 'signal', + HistoryEventType::SignalApplied, + HistoryEventType::ExternalSignalRequested, + HistoryEventType::ExternalSignalDelivered, + HistoryEventType::ExternalSignalFailed => 'signal', HistoryEventType::UpdateApplied, HistoryEventType::UpdateCompleted => 'update', HistoryEventType::ChildWorkflowScheduled, @@ -675,6 +678,22 @@ private static function summaryFor( ? 'Failure handled.' : sprintf('Handled failure: %s.', $message), HistoryEventType::SideEffectRecorded => 'Recorded side effect.', + HistoryEventType::ExternalSignalRequested => sprintf( + 'Requested signal %s to workflow %s.', + $signalName ?? 'signal', + self::stringValue($payload['target_workflow_instance_id'] ?? null) ?? 'workflow', + ), + HistoryEventType::ExternalSignalDelivered => sprintf( + 'Delivered signal %s to workflow %s.', + $signalName ?? 'signal', + self::stringValue($payload['target_workflow_instance_id'] ?? null) ?? 'workflow', + ), + HistoryEventType::ExternalSignalFailed => sprintf( + 'Signal %s to workflow %s was not delivered: %s.', + $signalName ?? 'signal', + self::stringValue($payload['target_workflow_instance_id'] ?? null) ?? 'workflow', + self::stringValue($payload['reason'] ?? null) ?? 'failed', + ), HistoryEventType::SearchAttributesUpserted => 'Search attributes upserted.', HistoryEventType::MemoUpserted => 'Memo upserted.', HistoryEventType::VersionMarkerRecorded => match (true) { diff --git a/src/V2/Support/QueryStateReplayer.php b/src/V2/Support/QueryStateReplayer.php index 4c0563c88..15a8b80fe 100644 --- a/src/V2/Support/QueryStateReplayer.php +++ b/src/V2/Support/QueryStateReplayer.php @@ -439,6 +439,30 @@ public function replayState(WorkflowRun $run): ReplayState continue; } + if ($current instanceof SignalExternalWorkflowCall) { + $historySequence = $this->historySequenceForReplayPosition($historySequencesByPosition, $sequence); + + $this->applyRecordedUpdates($run, $workflow, $historySequence); + WorkflowStepHistory::assertCompatible($run, $historySequence, WorkflowStepHistory::EXTERNAL_SIGNAL); + + // Query replay reads a recorded outcome and never delivers. + $result = ExternalSignalHistory::recordedResult($run, $historySequence, $current); + + if ($result === null) { + $this->syncWorkflowCursor($workflow, $sequence + 1); + return new ReplayState($workflow, $sequence, $current); + } + + $this->syncWorkflowCursor($workflow, $sequence + 1); + $current = $workflowExecution->send($result, RedriveReplayClock::recordedAt( + ExternalSignalHistory::resolutionEvent($run, $historySequence), + )); + + ++$sequence; + + continue; + } + if ($current instanceof UpsertMemoCall) { $historySequence = $this->historySequenceForReplayPosition($historySequencesByPosition, $sequence); @@ -2204,6 +2228,9 @@ private function hasWorkflowCommandSequence(?string $type): bool HistoryEventType::ChildRunCancelled->value, HistoryEventType::ChildRunTerminated->value, HistoryEventType::SideEffectRecorded->value, + HistoryEventType::ExternalSignalRequested->value, + HistoryEventType::ExternalSignalDelivered->value, + HistoryEventType::ExternalSignalFailed->value, HistoryEventType::VersionMarkerRecorded->value, HistoryEventType::MemoUpserted->value, HistoryEventType::SearchAttributesUpserted->value, diff --git a/src/V2/Support/SignalExternalWorkflowCall.php b/src/V2/Support/SignalExternalWorkflowCall.php new file mode 100644 index 000000000..affe30249 --- /dev/null +++ b/src/V2/Support/SignalExternalWorkflowCall.php @@ -0,0 +1,117 @@ + + */ + public readonly array $arguments; + + /** + * @param array $arguments + */ + public function __construct( + public readonly string $workflowId, + public readonly string $signalName, + array $arguments = [], + public readonly ?string $runId = null, + ) { + self::assertIdentifier($workflowId, 'workflow_id'); + + if ($runId !== null) { + self::assertIdentifier($runId, 'run_id'); + } + + $problem = self::signalNameProblem($signalName); + if ($problem !== null) { + throw new InvalidExternalSignalException('invalid_signal_name', 'signal_name', $problem); + } + + $this->arguments = array_is_list($arguments) ? array_values($arguments) : $arguments; + } + + /** + * The Server's signal-name rule for this command, or null when the name is + * accepted: valid UTF-8, not empty, at most 255 bytes, no control + * character (a byte below 0x20, or 0x7f), not blank, and at most 191 + * characters. + */ + public static function signalNameProblem(string $name): ?string + { + if ($name === '') { + return 'the signal name must not be empty'; + } + + if (! mb_check_encoding($name, 'UTF-8')) { + return 'the signal name must be valid UTF-8'; + } + + if (strlen($name) > self::MAX_SIGNAL_NAME_BYTES) { + return sprintf('the signal name exceeds %d bytes', self::MAX_SIGNAL_NAME_BYTES); + } + + if (preg_match('/[\x00-\x1F\x7F]/', $name) === 1) { + return 'the signal name must not contain control characters'; + } + + if (preg_match(self::BLANK_PATTERN, $name) === 1) { + return 'the signal name must not be blank'; + } + + if (mb_strlen($name, 'UTF-8') > self::MAX_SIGNAL_NAME_CHARACTERS) { + return sprintf('the signal name exceeds %d characters', self::MAX_SIGNAL_NAME_CHARACTERS); + } + + return null; + } + + private static function assertIdentifier(string $value, string $field): void + { + $problem = match (true) { + ! mb_check_encoding($value, 'UTF-8') => 'must be valid UTF-8', + preg_match(self::BLANK_PATTERN, $value) === 1 => 'must not be blank', + mb_strlen($value, 'UTF-8') > self::MAX_ID_CHARACTERS => sprintf( + 'exceeds %d characters', + self::MAX_ID_CHARACTERS, + ), + default => null, + }; + + if ($problem !== null) { + throw new InvalidExternalSignalException('invalid_signal_external_target', $field, sprintf( + 'the %s %s', + $field === 'run_id' ? 'run id' : 'workflow id', + $problem, + )); + } + } +} diff --git a/src/V2/Support/WorkflowExecutor.php b/src/V2/Support/WorkflowExecutor.php index 5cf51fc16..fcc309fbd 100644 --- a/src/V2/Support/WorkflowExecutor.php +++ b/src/V2/Support/WorkflowExecutor.php @@ -681,6 +681,11 @@ private function executeCurrentCall(WorkflowTaskExecution $state): WorkflowTask| $state->frame ), $current instanceof UpsertMemoCall => $this->executeMemo($state->run, $state->task, $state->frame), + $current instanceof SignalExternalWorkflowCall => $this->executeExternalSignal( + $state->run, + $state->task, + $state->frame + ), $current instanceof TimerCall => $this->executeTimer($state->run, $state->task, $state->frame), $current instanceof SignalCall => $this->executeSignal($state->run, $state->task, $state->frame), $current instanceof ServiceOperationCall => $this->executeServiceOperation( @@ -1467,6 +1472,84 @@ private function executeMemo( return WorkflowTaskStep::ContinueExecution; } + /** + * Durable signal-external (.github#223): record the request, admit the + * signal on the target and record its outcome at one sequence, all in + * this task's transaction. Replay returns the recorded outcome and never + * sends again. A failed delivery is a value for workflow code, not a + * task failure. + */ + private function executeExternalSignal( + WorkflowRun $run, + WorkflowTask $task, + WorkflowContinuation $frame, + ): WorkflowTask|WorkflowTaskStep|null { + $workflow = $frame->workflow; + $workflowExecution = $frame->execution; + /** @var SignalExternalWorkflowCall $current */ + $current = &$frame->current; + $sequence = &$frame->sequence; + + $this->syncWorkflowCursorForCurrent($workflow, $run, $current, $sequence); + if (! $this->applyRecordedUpdates($run, $workflow, $sequence, $task)) { + return $this->restartAfterPendingUpdateFailure($run, $task); + } + if (! $this->ensureStepHistoryCompatible($run, $task, $sequence, WorkflowStepHistory::EXTERNAL_SIGNAL)) { + return null; + } + try { + $result = ExternalSignalHistory::recordedResult($run, $sequence, $current); + if ($result === null) { + $this->recordExternalSignal($run, $task, $sequence, $current); + $result = ExternalSignalHistory::recordedResult($run, $sequence, $current); + } + $resolutionEvent = ExternalSignalHistory::resolutionEvent($run, $sequence); + $this->syncWorkflowCursor($workflow, $sequence + 1); + $current = $workflowExecution->send( + $result, + RedriveReplayClock::recordedAt($resolutionEvent), + advanceCancellationTime: false, + ); + } catch (Throwable $throwable) { + $this->failRun($run, $task, $throwable, 'workflow_run', $run->id); + return null; + } + ++$sequence; + return WorkflowTaskStep::ContinueExecution; + } + + private function recordExternalSignal( + WorkflowRun $run, + WorkflowTask $task, + int $sequence, + SignalExternalWorkflowCall $call, + ): void { + $arguments = ExternalSignalHistory::argumentsEnvelope( + $call, + is_string($run->payload_codec) && $run->payload_codec !== '' ? $run->payload_codec : null, + ); + $requested = WorkflowHistoryEvent::record( + $run, + HistoryEventType::ExternalSignalRequested, + [ + 'sequence' => $sequence, + 'target_workflow_instance_id' => $call->workflowId, + 'target_workflow_run_id' => $call->runId, + 'signal_name' => $call->signalName, + 'arguments' => $arguments, + 'payload_codec' => $arguments['codec'], + 'request_id' => ExternalSignalHistory::requestId($run->id, $sequence), + ], + $task, + ); + $run->historyEvents->push($requested); + + $resolution = ExternalSignalDelivery::deliver($run, $sequence, $call); + $run->historyEvents->push( + WorkflowHistoryEvent::record($run, $resolution['event_type'], $resolution['payload'], $task), + ); + } + private function executeTimer( WorkflowRun $run, WorkflowTask $task, diff --git a/src/V2/Support/WorkflowFiberRunner.php b/src/V2/Support/WorkflowFiberRunner.php index 4deaa74e2..20e5847d9 100644 --- a/src/V2/Support/WorkflowFiberRunner.php +++ b/src/V2/Support/WorkflowFiberRunner.php @@ -579,6 +579,38 @@ private function nextObservableStep(): WorkflowStep continue; } + if ($current instanceof SignalExternalWorkflowCall) { + // Replay returns the recorded outcome. A new delivery needs the + // embedded executor's transaction; this runner never sends one. + $historySequence = $this->historySequenceForCurrentPosition(); + $result = null; + if ($historySequence !== null) { + WorkflowStepHistory::assertCompatible( + $this->workflow->run, + $historySequence, + WorkflowStepHistory::EXTERNAL_SIGNAL, + ); + $result = ExternalSignalHistory::recordedResult($this->workflow->run, $historySequence, $current); + } + + if ($result === null) { + throw new UnsupportedWorkflowYieldException( + 'Durable signal-external currently requires embedded native execution.' + ); + } + + ++$this->sequence; + $this->sendToWorkflow( + $result, + RedriveReplayClock::recordedAt( + ExternalSignalHistory::resolutionEvent($this->workflow->run, $historySequence), + ), + advanceCancellationTime: false, + ); + + continue; + } + if ($current instanceof UpsertMemoCall) { $historySequence = $this->historySequenceForCurrentPosition(); $recorded = $historySequence === null @@ -1671,6 +1703,9 @@ private static function hasWorkflowCommandSequence(?string $type): bool 'ServiceCallFailed', 'ServiceCallCancelled', 'SideEffectRecorded', + 'ExternalSignalRequested', + 'ExternalSignalDelivered', + 'ExternalSignalFailed', 'VersionMarkerRecorded', 'MemoUpserted', 'SearchAttributesUpserted', diff --git a/src/V2/Support/WorkflowStepHistory.php b/src/V2/Support/WorkflowStepHistory.php index 11f15486e..285c36115 100644 --- a/src/V2/Support/WorkflowStepHistory.php +++ b/src/V2/Support/WorkflowStepHistory.php @@ -30,6 +30,8 @@ final class WorkflowStepHistory public const CONTINUE_AS_NEW = 'continue as new'; + public const EXTERNAL_SIGNAL = ExternalSignalHistory::SHAPE; + public const NO_TYPED_HISTORY = 'no typed history'; public const PARALLEL_GROUP = 'parallel all barrier matching current topology'; @@ -82,6 +84,9 @@ final class WorkflowStepHistory HistoryEventType::MemoUpserted, HistoryEventType::SearchAttributesUpserted, HistoryEventType::SideEffectRecorded, + HistoryEventType::ExternalSignalRequested, + HistoryEventType::ExternalSignalDelivered, + HistoryEventType::ExternalSignalFailed, HistoryEventType::VersionMarkerRecorded, HistoryEventType::TimerScheduled, HistoryEventType::TimerFired, @@ -462,6 +467,11 @@ private static function eventMatchesShape(WorkflowHistoryEvent $event, string $e self::MEMO_UPSERT => $event->event_type === HistoryEventType::MemoUpserted, self::SEARCH_ATTRIBUTES_UPSERT => $event->event_type === HistoryEventType::SearchAttributesUpserted, self::SIDE_EFFECT => $event->event_type === HistoryEventType::SideEffectRecorded, + self::EXTERNAL_SIGNAL => in_array($event->event_type, [ + HistoryEventType::ExternalSignalRequested, + HistoryEventType::ExternalSignalDelivered, + HistoryEventType::ExternalSignalFailed, + ], true), self::TIMER => self::isPureTimerEvent($event), self::VERSION_MARKER => $event->event_type === HistoryEventType::VersionMarkerRecorded, default => false, diff --git a/src/V2/Webhooks.php b/src/V2/Webhooks.php index 444c4e0ce..745ea87fd 100644 --- a/src/V2/Webhooks.php +++ b/src/V2/Webhooks.php @@ -21,6 +21,7 @@ use Workflow\V2\Enums\DuplicateStartPolicy; use Workflow\V2\Enums\TaskStatus; use Workflow\V2\Enums\TaskType; +use Workflow\V2\Exceptions\InvalidCommandRequestIdException; use Workflow\V2\Models\WorkflowTask; use Workflow\V2\Support\CommandResponse; use Workflow\V2\Support\ConfiguredV2Models; @@ -88,7 +89,15 @@ public static function routes(array $workflows, ?string $basePath = null): void } $stub = WorkflowStub::make($workflow, $instanceId)->withCommandContext($commandContext); - $result = $stub->attemptSignalWithStart($signal, $signalArguments, ...[...$arguments, $startOptions]); + try { + $result = $stub->attemptSignalWithStart( + $signal, + $signalArguments, + ...[...$arguments, $startOptions], + ); + } catch (InvalidCommandRequestIdException $exception) { + return self::reservedRequestIdResponse($exception); + } return self::commandResponse($result, match ($result->outcome()) { CommandOutcome::RejectedUnknownSignal->value => 404, @@ -271,9 +280,13 @@ public static function routes(array $workflows, ?string $basePath = null): void ) { $request = self::validateAuth($request); - $result = self::selectionStub($workflowId, $runId) - ->withCommandContext(self::commandContext($request)) - ->attemptSignalWithArguments($signal, self::resolveSignalArguments($request->all())); + try { + $result = self::selectionStub($workflowId, $runId) + ->withCommandContext(self::commandContext($request)) + ->attemptSignalWithArguments($signal, self::resolveSignalArguments($request->all())); + } catch (InvalidCommandRequestIdException $exception) { + return self::reservedRequestIdResponse($exception); + } return self::commandResponse($result, match ($result->outcome()) { CommandOutcome::RejectedUnknownSignal->value => 404, @@ -289,9 +302,13 @@ public static function routes(array $workflows, ?string $basePath = null): void ) { $request = self::validateAuth($request); - $result = self::selectionStub($workflowId) - ->withCommandContext(self::commandContext($request)) - ->attemptSignalWithArguments($signal, self::resolveSignalArguments($request->all())); + try { + $result = self::selectionStub($workflowId) + ->withCommandContext(self::commandContext($request)) + ->attemptSignalWithArguments($signal, self::resolveSignalArguments($request->all())); + } catch (InvalidCommandRequestIdException $exception) { + return self::reservedRequestIdResponse($exception); + } return self::commandResponse($result, match ($result->outcome()) { CommandOutcome::RejectedUnknownSignal->value => 404, @@ -907,6 +924,24 @@ private static function selectionStub(string $workflowId, ?string $runId = null) : WorkflowStub::loadSelection($workflowId, $runId); } + /** + * A signal keyed under the runtime's reserved `workflow-signal:` prefix is + * refused with 422 before anything is read or written. Other invalid keys + * keep their existing behavior. + */ + private static function reservedRequestIdResponse(InvalidCommandRequestIdException $exception) + { + if ($exception->reason() !== InvalidCommandRequestIdException::REASON_RESERVED) { + throw $exception; + } + + return response()->json([ + 'reason' => $exception->reason(), + 'message' => $exception->getMessage(), + 'errors' => $exception->validationErrors(), + ], 422); + } + private static function commandResponse(CommandResult $result, int $status, ?string $workflowType = null) { return response()->json(CommandResponse::payload($result, $workflowType), $status); diff --git a/src/V2/Workflow.php b/src/V2/Workflow.php index dc4eaf596..076046d6c 100644 --- a/src/V2/Workflow.php +++ b/src/V2/Workflow.php @@ -16,6 +16,7 @@ use Workflow\V2\Support\MessageService; use Workflow\V2\Support\ScheduleOrigin; use Workflow\V2\Support\ServiceOperationOptions; +use Workflow\V2\Support\SignalExternalWorkflowCall; use Workflow\V2\Support\UpdateMessageReceives; use Workflow\V2\Support\WorkerSession; use Workflow\V2\Support\WorkerSessionOptions; @@ -514,6 +515,25 @@ public static function executeChildWorkflow(string $workflow, mixed ...$argument return child($workflow, ...$arguments); } + /** + * Durably signal another workflow in this workflow's namespace. + * + * @param array $arguments + * + * @see signalExternalWorkflow() + * + * @experimental Durable signal-external may change in a minor release. + * See docs/api-stability.md#durable-signal-external. + */ + public static function signalExternalWorkflow( + string $workflowId, + string $signalName, + array $arguments = [], + ?string $runId = null, + ): ExternalSignalResult|SignalExternalWorkflowCall { + return signalExternalWorkflow($workflowId, $signalName, $arguments, $runId); + } + /** * Confirm native child admission, then await its result separately if needed. * diff --git a/src/V2/WorkflowStub.php b/src/V2/WorkflowStub.php index 4fa16ce71..e5eb55e51 100644 --- a/src/V2/WorkflowStub.php +++ b/src/V2/WorkflowStub.php @@ -35,6 +35,7 @@ use Workflow\V2\Enums\TaskType; use Workflow\V2\Enums\TimerStatus; use Workflow\V2\Enums\UpdateStatus; +use Workflow\V2\Exceptions\InvalidCommandRequestIdException; use Workflow\V2\Exceptions\InvalidQueryArgumentsException; use Workflow\V2\Exceptions\StructuralLimitExceededException; use Workflow\V2\Exceptions\WorkflowExecutionUnavailableException; @@ -65,6 +66,7 @@ use Workflow\V2\Support\CurrentRunResolver; use Workflow\V2\Support\ExecutionTracing; use Workflow\V2\Support\ExternalPayloads; +use Workflow\V2\Support\ExternalSignalHistory; use Workflow\V2\Support\LifecycleEventDispatcher; use Workflow\V2\Support\MemoUpsertService; use Workflow\V2\Support\NamespaceScope; @@ -165,6 +167,12 @@ final class WorkflowStub private ?int $updateWaitTimeoutSeconds = null; + /** + * The one reserved `workflow-signal:` key this stub may admit: set only by + * the runtime's durable signal-external delivery (.github#223). + */ + private ?string $externalSignalRequestId = null; + private function __construct( private WorkflowInstance $instance, ?WorkflowRun $selectedRun = null, @@ -1345,6 +1353,29 @@ public function repair(): CommandResult return $result; } + /** + * Admit one durable signal-external delivery from workflow code. + * + * The runtime calls this inside the sending workflow task's transaction, + * keyed on the target as `workflow-signal::`, so the + * sender's history and the target's admission commit or roll back + * together. Applications cannot use that key prefix themselves. + * + * @internal + * @param array $arguments + */ + public function attemptExternalWorkflowSignal(string $requestId, string $name, array $arguments): CommandResult + { + if (! ExternalSignalHistory::isReservedRequestId($requestId)) { + throw new LogicException('A durable signal-external delivery requires its reserved command key.'); + } + + $clone = $this->withRequestId($requestId); + $clone->externalSignalRequestId = $requestId; + + return $clone->attemptSignalWithArguments($name, $arguments); + } + public function attemptSignal(string $name, ...$arguments): CommandResult { return $this->attemptSignalWithArguments($name, $arguments); @@ -4850,6 +4881,15 @@ private function validateCommandRequestId(CommandType $type): void return; } CommandRequestIdentity::validateContext($context, $type); + + // A durable signal-external delivery owns `workflow-signal:` keys on its + // target. No caller may occupy or answer for one (request_id_reserved). + $requestId = CommandRequestIdentity::fromContext($context, $type); + if ($type === CommandType::Signal + && ExternalSignalHistory::isReservedRequestId($requestId) + && $requestId !== $this->externalSignalRequestId) { + throw InvalidCommandRequestIdException::reserved(ExternalSignalHistory::REQUEST_ID_PREFIX); + } } /** diff --git a/src/V2/functions.php b/src/V2/functions.php index d535f2314..19fc96b6d 100644 --- a/src/V2/functions.php +++ b/src/V2/functions.php @@ -26,6 +26,7 @@ use Workflow\V2\Support\ServiceOperationOptions; use Workflow\V2\Support\SideEffectCall; use Workflow\V2\Support\SignalCall; +use Workflow\V2\Support\SignalExternalWorkflowCall; use Workflow\V2\Support\StartChildWorkflowCall; use Workflow\V2\Support\TimerCall; use Workflow\V2\Support\UpsertMemoCall; @@ -137,6 +138,37 @@ function startChild(string $workflow, mixed ...$arguments): StartedChildWorkflow } } +if (! function_exists(__NAMESPACE__ . '\\signalExternalWorkflow')) { + /** + * Durably signal another workflow in this workflow's namespace. + * + * The signal is a workflow command: its request and outcome are recorded + * once in this workflow's history, in the same transaction that admits + * the signal on the target, and replay returns the recorded outcome + * without sending again. A missing or closed target, or a refusal by the + * target, is a returned {@see ExternalSignalResult}, not an exception. + * Pass `$runId` to signal only that run of the target. + * + * @param array $arguments + * + * @experimental Durable signal-external may change in a minor release. + * See docs/api-stability.md#durable-signal-external. + */ + function signalExternalWorkflow( + string $workflowId, + string $signalName, + array $arguments = [], + ?string $runId = null, + ): ExternalSignalResult|SignalExternalWorkflowCall { + return WorkflowFiberContext::suspend(new SignalExternalWorkflowCall( + $workflowId, + $signalName, + $arguments, + $runId, + )); + } +} + if (! function_exists(__NAMESPACE__ . '\\async')) { function async(callable $callback): mixed { diff --git a/tests/Feature/V2/V2SignalExternalWorkflowTest.php b/tests/Feature/V2/V2SignalExternalWorkflowTest.php new file mode 100644 index 000000000..d4a4dd7d7 --- /dev/null +++ b/tests/Feature/V2/V2SignalExternalWorkflowTest.php @@ -0,0 +1,417 @@ +startTarget('sx-delivered-target'); + $sender = WorkflowStub::make(TestSignalExternalSenderWorkflow::class, 'sx-delivered-sender'); + $sender->start([[ + 'workflow_id' => 'sx-delivered-target', + 'signal' => 'approve', + 'arguments' => ['Ada'], + ]]); + $this->drainReadyTasks(); + + $senderRun = WorkflowRun::query()->findOrFail($sender->runId()); + $this->assertSame(RunStatus::Completed, $senderRun->status); + $output = $sender->refresh() + ->output(); + $requestId = 'workflow-signal:' . $senderRun->id . ':1'; + $delivery = $output['results'][0]; + $this->assertSame('delivered', $delivery['outcome']); + $this->assertNull($delivery['reason']); + $this->assertSame($target->runId(), $delivery['target_run_id']); + $this->assertSame($requestId, $delivery['request_id']); + $this->assertFalse($delivery['retained']); + $this->assertSame('after', $output['after']); + + // The target received an ordinary signal attributed to the sender. + $this->assertSame([ + 'approved' => 'Ada', + 'workflow_id' => 'sx-delivered-target', + ], $target->refresh() + ->output()); + $command = WorkflowCommand::query()->findOrFail($delivery['target_command_id']); + $this->assertSame(CommandType::Signal, $command->command_type); + $this->assertSame(CommandStatus::Accepted, $command->status); + $this->assertSame('workflow', $command->source); + $this->assertSame($requestId, $command->requestId()); + // JSON column key order is driver-specific. + $this->assertEquals([ + 'parent_instance_id' => 'sx-delivered-sender', + 'parent_run_id' => $senderRun->id, + 'sequence' => 1, + ], $command->context['workflow']); + $this->assertSame( + $delivery['target_signal_id'], + WorkflowSignal::query()->where('workflow_command_id', $command->id)->sole()->id, + ); + $this->assertSame(1, $this->eventCount($target->runId(), HistoryEventType::SignalReceived)); + + // One request and one outcome at the command's sequence; the next + // durable step takes the following sequence. + $events = $this->stepEvents($senderRun->id); + $this->assertSame([ + ['ExternalSignalRequested', 1], + ['ExternalSignalDelivered', 1], + ['SideEffectRecorded', 2], + ], $events); + $requested = $this->event($senderRun->id, HistoryEventType::ExternalSignalRequested); + $this->assertSame('sx-delivered-target', $requested->payload['target_workflow_instance_id']); + $this->assertNull($requested->payload['target_workflow_run_id']); + $this->assertSame('approve', $requested->payload['signal_name']); + $this->assertSame($requestId, $requested->payload['request_id']); + $this->assertSame('avro', $requested->payload['payload_codec']); + $this->assertSame('avro', $requested->payload['arguments']['codec']); + + // Cold replay and query replay read the recorded outcome and send nothing. + $replayed = (new WorkflowReplayer())->replay(WorkflowRun::query()->findOrFail($senderRun->id)); + $this->assertNull($replayed->current); + $this->assertSame(3, $replayed->sequence); + $queried = (new QueryStateReplayer())->replayState( + WorkflowRun::query()->with('historyEvents')->findOrFail($senderRun->id) + ); + $this->assertNull($queried->current); + $this->assertSame(1, WorkflowSignal::query()->where('workflow_run_id', $target->runId())->count()); + $this->assertSame(1, WorkflowCommand::query() + ->where('workflow_instance_id', 'sx-delivered-target') + ->where('command_type', CommandType::Signal->value) + ->count()); + } + + public function testRolledBackSenderTaskSendsNothingAndItsRetryDeliversOnce(): void + { + $target = $this->startTarget('sx-rollback-target'); + $sender = WorkflowStub::make(TestSignalExternalSenderWorkflow::class, 'sx-rollback-sender'); + $sender->start([[ + 'workflow_id' => 'sx-rollback-target', + 'signal' => 'approve', + 'arguments' => ['retry'], + ]]); + $task = WorkflowTask::query() + ->where('workflow_run_id', $sender->runId()) + ->where('status', TaskStatus::Ready->value) + ->sole(); + + // The sender's task runs completely, then its transaction is lost. + DB::beginTransaction(); + try { + $this->app->call([new RunWorkflowTask($task->id), 'handle']); + $this->assertSame(1, WorkflowSignal::query()->where('workflow_run_id', $target->runId())->count()); + } finally { + DB::rollBack(); + } + + $this->assertSame(0, WorkflowSignal::query()->where('workflow_run_id', $target->runId())->count()); + $this->assertSame(0, $this->eventCount($sender->runId(), HistoryEventType::ExternalSignalRequested)); + + $this->drainReadyTasks(); + + $this->assertSame('delivered', $sender->refresh()->output()['results'][0]['outcome']); + $this->assertSame(1, WorkflowSignal::query()->where('workflow_run_id', $target->runId())->count()); + $this->assertSame(1, $this->eventCount($sender->runId(), HistoryEventType::ExternalSignalRequested)); + $this->assertSame('retry', $target->refresh()->output()['approved']); + } + + public function testFailedOutcomesAreRecordedValuesNotTaskFailures(): void + { + $closed = $this->startTarget('sx-closed-target'); + WorkflowStub::load('sx-closed-target')->signal('approve', 'first'); + $this->drainReadyTasks(); + $this->assertTrue($closed->refresh()->completed()); + + $open = $this->startTarget('sx-open-target'); + $foreign = $this->startTarget('sx-foreign-target'); + WorkflowInstance::query()->whereKey('sx-foreign-target')->update([ + 'namespace' => 'another-namespace', + ]); + + $sender = WorkflowStub::make(TestSignalExternalSenderWorkflow::class, 'sx-failure-sender'); + $sender->start([ + [ + 'workflow_id' => 'sx-missing-target', + 'signal' => 'approve', + ], + [ + 'workflow_id' => 'sx-closed-target', + 'signal' => 'approve', + 'arguments' => ['late'], + ], + [ + 'workflow_id' => 'sx-open-target', + 'signal' => 'undeclared', + ], + [ + 'workflow_id' => 'sx-failure-sender', + 'signal' => 'approve', + ], + [ + 'workflow_id' => 'sx-open-target', + 'signal' => 'approve', + 'run_id' => $closed->runId(), + ], + [ + 'workflow_id' => 'sx-foreign-target', + 'signal' => 'approve', + ], + [ + 'workflow_id' => 'sx-open-target', + 'signal' => WorkflowStub::MESSAGE_STREAM_RUNTIME_SIGNAL, + ], + ]); + $this->drainReadyTasks(); + + $this->assertSame(RunStatus::Completed, WorkflowRun::query()->findOrFail($sender->runId())->status); + $results = $sender->refresh() + ->output()['results']; + $this->assertSame([ + ['target_not_found', 'instance_not_found'], + ['target_closed', 'run_not_active'], + ['rejected', 'unknown_signal'], + ['rejected', 'self_target'], + ['target_not_found', 'run_not_found'], + ['target_not_found', 'instance_not_found'], + ['rejected', 'runtime_reserved_signal'], + ], array_map(static fn (array $result): array => [$result['outcome'], $result['reason']], $results)); + + // A closed target records the rejected command, as for any signal. + $this->assertSame($closed->runId(), $results[1]['target_run_id']); + $rejected = WorkflowCommand::query()->findOrFail($results[1]['target_command_id']); + $this->assertSame(CommandStatus::Rejected, $rejected->status); + $this->assertSame('run_not_active', $rejected->rejection_reason); + $this->assertSame(0, WorkflowCommand::query() + ->where('workflow_instance_id', 'sx-foreign-target') + ->where('command_type', CommandType::Signal->value) + ->count()); + $this->assertFalse($open->refresh()->completed()); + $this->assertFalse($foreign->refresh()->completed()); + $this->assertSame(7, $this->eventCount($sender->runId(), HistoryEventType::ExternalSignalFailed)); + $this->assertSame(0, $this->eventCount($sender->runId(), HistoryEventType::ExternalSignalDelivered)); + $this->assertSame( + [['SideEffectRecorded', 8]], + array_values(array_filter( + $this->stepEvents($sender->runId()), + static fn (array $event): bool => $event[0] === 'SideEffectRecorded', + )), + ); + } + + public function testRunTargetedSignalReachesOnlyThatRun(): void + { + $target = $this->startTarget('sx-run-target'); + $sender = WorkflowStub::make(TestSignalExternalSenderWorkflow::class, 'sx-run-sender'); + $sender->start([[ + 'workflow_id' => 'sx-run-target', + 'signal' => 'approve', + 'arguments' => ['run'], + 'run_id' => $target->runId(), + ]]); + $this->drainReadyTasks(); + + $result = $sender->refresh() + ->output()['results'][0]; + $this->assertSame('delivered', $result['outcome']); + $this->assertSame($target->runId(), $result['target_run_id']); + $this->assertSame('run', $target->refresh()->output()['approved']); + } + + public function testChildHandleSignalsItsChildDurably(): void + { + // Native child admission receipts name their namespace. + config([ + 'workflows.v2.namespace' => 'sx-child-handle', + ]); + $parent = WorkflowStub::make(TestSignalExternalChildHandleWorkflow::class, 'sx-child-handle-parent'); + $parent->start('from-parent'); + $this->drainReadyTasks(); + + $output = $parent->refresh() + ->output(); + $failure = \Workflow\V2\Models\WorkflowFailure::query()->where('workflow_run_id', $parent->runId())->first(); + $this->assertNull($failure?->message, (string) $failure?->message); + $this->assertSame('delivered', $output['signal']['outcome']); + $this->assertSame('from-parent', $output['child']['approved']); + $this->assertSame(1, $this->eventCount($parent->runId(), HistoryEventType::ExternalSignalDelivered)); + } + + public function testInvalidSignalNameIsRefusedInWorkflowCodeBeforeAnythingIsRecorded(): void + { + $this->startTarget('sx-invalid-name-target'); + $sender = WorkflowStub::make(TestSignalExternalInvalidNameWorkflow::class, 'sx-invalid-name-sender'); + $sender->start('sx-invalid-name-target', "bad\nname"); + $this->drainReadyTasks(); + + $this->assertSame([ + 'reason' => 'invalid_signal_name', + 'field' => 'signal_name', + ], $sender->refresh() + ->output()); + $this->assertSame(0, $this->eventCount($sender->runId(), HistoryEventType::ExternalSignalRequested)); + $this->assertSame(0, WorkflowCommand::query() + ->where('workflow_instance_id', 'sx-invalid-name-target') + ->where('command_type', CommandType::Signal->value) + ->count()); + } + + public function testCallersCannotUseTheReservedRequestIdPrefix(): void + { + $this->startTarget('sx-reserved-target'); + + try { + WorkflowStub::load('sx-reserved-target') + ->withRequestId('workflow-signal:some-run:1') + ->attemptSignal('approve', 'forged'); + $this->fail('A caller must not use a reserved workflow-signal key.'); + } catch (InvalidCommandRequestIdException $exception) { + $this->assertSame('request_id_reserved', $exception->reason()); + } + + try { + WorkflowStub::make(TestSignalExternalTargetWorkflow::class, 'sx-reserved-signal-with-start') + ->withRequestId('workflow-signal:some-run:2') + ->attemptSignalWithStart('approve', ['forged'], StartOptions::returnExistingActive()); + $this->fail('Signal-with-start must not use a reserved workflow-signal key.'); + } catch (InvalidCommandRequestIdException $exception) { + $this->assertSame('request_id_reserved', $exception->reason()); + } + + $response = $this->app->make(WorkflowControlPlane::class)->signal('sx-reserved-target', 'approve', [ + 'request_id' => 'workflow-signal:some-run:3', + 'arguments' => ['forged'], + ]); + $this->assertSame(422, $response['status']); + $this->assertSame('request_id_reserved', $response['reason']); + $this->assertFalse($response['recorded']); + + $this->assertSame(0, WorkflowCommand::query() + ->whereIn('workflow_instance_id', ['sx-reserved-target', 'sx-reserved-signal-with-start']) + ->where('command_type', CommandType::Signal->value) + ->count()); + $this->assertNull(WorkflowStub::load('sx-reserved-signal-with-start')->runId()); + + // An ordinary key is unaffected. + $this->assertTrue(WorkflowStub::load('sx-reserved-target') + ->withRequestId('workflow-signalling-is-fine') + ->attemptSignal('approve', 'ok') + ->accepted()); + } + + private function startTarget(string $id): WorkflowStub + { + $target = WorkflowStub::make(TestSignalExternalTargetWorkflow::class, $id); + $target->start(); + $this->drainReadyTasks(); + + return $target; + } + + /** + * @return list + */ + private function stepEvents(string $runId): array + { + return WorkflowHistoryEvent::query() + ->where('workflow_run_id', $runId) + ->whereIn('event_type', [ + HistoryEventType::ExternalSignalRequested->value, + HistoryEventType::ExternalSignalDelivered->value, + HistoryEventType::ExternalSignalFailed->value, + HistoryEventType::SideEffectRecorded->value, + ]) + ->orderBy('sequence') + ->get() + ->map(static fn (WorkflowHistoryEvent $event): array => [ + $event->event_type->value, + $event->payload['sequence'] ?? null, + ]) + ->values() + ->all(); + } + + private function event(string $runId, HistoryEventType $type): WorkflowHistoryEvent + { + return WorkflowHistoryEvent::query() + ->where('workflow_run_id', $runId) + ->where('event_type', $type->value) + ->sole(); + } + + private function eventCount(string $runId, HistoryEventType $type): int + { + return WorkflowHistoryEvent::query() + ->where('workflow_run_id', $runId) + ->where('event_type', $type->value) + ->count(); + } + + private function drainReadyTasks(): void + { + $deadline = microtime(true) + 20; + + while (microtime(true) < $deadline) { + /** @var WorkflowTask|null $task */ + $task = WorkflowTask::query() + ->where('status', TaskStatus::Ready->value) + ->orderBy('created_at') + ->first(); + + if ($task === null || ($task->available_at !== null && $task->available_at->isFuture())) { + return; + } + + $job = match ($task->task_type) { + TaskType::Workflow => new RunWorkflowTask($task->id), + TaskType::Activity => new RunActivityTask($task->id), + TaskType::Timer => new RunTimerTask($task->id), + }; + + $this->app->call([$job, 'handle']); + } + + $this->fail('Timed out draining ready workflow tasks.'); + } +} diff --git a/tests/Fixtures/V2/ReplayRegression/signal-external-delivered-cold-replay.json b/tests/Fixtures/V2/ReplayRegression/signal-external-delivered-cold-replay.json new file mode 100644 index 000000000..64bf1be16 --- /dev/null +++ b/tests/Fixtures/V2/ReplayRegression/signal-external-delivered-cold-replay.json @@ -0,0 +1,99 @@ +{ + "$schema": "https://raw.githubusercontent.com/durable-workflow/.github/main/regression-corpus/evidence-schema.json", + "fixture_schema": "durable-workflow.replay-regression/v1", + "id": "signal-external-delivered-cold-replay", + "protocol_version": "1.20", + "bindings": [ + "php" + ], + "workflow": { + "type": "Tests\\Fixtures\\V2\\TestSignalExternalSenderWorkflow", + "arguments": [ + [ + { + "workflow_id": "order-42", + "signal": "approve", + "arguments": [ + "Ada" + ] + } + ] + ], + "payload_codec": "avro" + }, + "history": [ + { + "sequence": 1, + "event_type": "WorkflowStarted", + "payload": {}, + "recorded_at": "2026-11-19T12:00:00Z" + }, + { + "sequence": 2, + "event_type": "ExternalSignalRequested", + "payload": { + "sequence": 1, + "target_workflow_instance_id": "order-42", + "target_workflow_run_id": null, + "signal_name": "approve", + "arguments": { + "codec": "avro", + "blob": "wwHioz3/VYAiNwwCCgZBZGEA" + }, + "payload_codec": "avro", + "request_id": "workflow-signal:01j00000000000000000000s01:1" + }, + "recorded_at": "2026-11-19T12:00:01Z" + }, + { + "sequence": 3, + "event_type": "ExternalSignalDelivered", + "payload": { + "sequence": 1, + "target_workflow_instance_id": "order-42", + "target_workflow_run_id": "01j00000000000000000000t01", + "signal_name": "approve", + "request_id": "workflow-signal:01j00000000000000000000s01:1", + "outcome": "delivered", + "target_command_id": "01j00000000000000000000c01", + "target_signal_id": "01j00000000000000000000g01", + "retained": false + }, + "recorded_at": "2026-11-19T12:00:01Z" + }, + { + "sequence": 4, + "event_type": "SideEffectRecorded", + "payload": { + "sequence": 2, + "result": "wwHioz3/VYAiNwoKYWZ0ZXI=" + }, + "recorded_at": "2026-11-19T12:00:02Z" + } + ], + "expected": { + "completed": true, + "result": { + "results": [ + { + "outcome": "delivered", + "reason": null, + "message": null, + "target_workflow_id": "order-42", + "target_run_id": "01j00000000000000000000t01", + "signal_name": "approve", + "request_id": "workflow-signal:01j00000000000000000000s01:1", + "target_command_id": "01j00000000000000000000c01", + "target_signal_id": "01j00000000000000000000g01", + "retained": false + } + ], + "after": "after" + }, + "commands": [ + { + "type": "complete_workflow" + } + ] + } +} diff --git a/tests/Fixtures/V2/ReplayRegression/signal-external-failed-outcomes-cold-replay.json b/tests/Fixtures/V2/ReplayRegression/signal-external-failed-outcomes-cold-replay.json new file mode 100644 index 000000000..516f9fb1e --- /dev/null +++ b/tests/Fixtures/V2/ReplayRegression/signal-external-failed-outcomes-cold-replay.json @@ -0,0 +1,197 @@ +{ + "$schema": "https://raw.githubusercontent.com/durable-workflow/.github/main/regression-corpus/evidence-schema.json", + "fixture_schema": "durable-workflow.replay-regression/v1", + "id": "signal-external-failed-outcomes-cold-replay", + "protocol_version": "1.20", + "bindings": [ + "php" + ], + "workflow": { + "type": "Tests\\Fixtures\\V2\\TestSignalExternalSenderWorkflow", + "arguments": [ + [ + { + "workflow_id": "order-missing", + "signal": "approve" + }, + { + "workflow_id": "order-closed", + "signal": "approve", + "arguments": [ + "late" + ] + }, + { + "workflow_id": "order-open", + "signal": "undeclared" + } + ] + ], + "payload_codec": "avro" + }, + "history": [ + { + "sequence": 1, + "event_type": "WorkflowStarted", + "payload": {}, + "recorded_at": "2026-11-19T12:00:00Z" + }, + { + "sequence": 2, + "event_type": "ExternalSignalRequested", + "payload": { + "sequence": 1, + "target_workflow_instance_id": "order-missing", + "target_workflow_run_id": null, + "signal_name": "approve", + "arguments": { + "codec": "avro", + "blob": "wwHioz3/VYAiNwwA" + }, + "payload_codec": "avro", + "request_id": "workflow-signal:01j00000000000000000000s01:1" + }, + "recorded_at": "2026-11-19T12:00:01Z" + }, + { + "sequence": 3, + "event_type": "ExternalSignalFailed", + "payload": { + "sequence": 1, + "target_workflow_instance_id": "order-missing", + "target_workflow_run_id": null, + "signal_name": "approve", + "request_id": "workflow-signal:01j00000000000000000000s01:1", + "outcome": "target_not_found", + "reason": "instance_not_found", + "message": "No workflow instance [order-missing] exists in this namespace.", + "target_command_id": null + }, + "recorded_at": "2026-11-19T12:00:01Z" + }, + { + "sequence": 4, + "event_type": "ExternalSignalRequested", + "payload": { + "sequence": 2, + "target_workflow_instance_id": "order-closed", + "target_workflow_run_id": null, + "signal_name": "approve", + "arguments": { + "codec": "avro", + "blob": "wwHioz3/VYAiNwwCCghsYXRlAA==" + }, + "payload_codec": "avro", + "request_id": "workflow-signal:01j00000000000000000000s01:2" + }, + "recorded_at": "2026-11-19T12:00:02Z" + }, + { + "sequence": 5, + "event_type": "ExternalSignalFailed", + "payload": { + "sequence": 2, + "target_workflow_instance_id": "order-closed", + "target_workflow_run_id": "01j00000000000000000000t02", + "signal_name": "approve", + "request_id": "workflow-signal:01j00000000000000000000s01:2", + "outcome": "target_closed", + "reason": "run_not_active", + "message": "The target run is closed.", + "target_command_id": "01j00000000000000000000c02" + }, + "recorded_at": "2026-11-19T12:00:02Z" + }, + { + "sequence": 6, + "event_type": "ExternalSignalRequested", + "payload": { + "sequence": 3, + "target_workflow_instance_id": "order-open", + "target_workflow_run_id": null, + "signal_name": "undeclared", + "arguments": { + "codec": "avro", + "blob": "wwHioz3/VYAiNwwA" + }, + "payload_codec": "avro", + "request_id": "workflow-signal:01j00000000000000000000s01:3" + }, + "recorded_at": "2026-11-19T12:00:03Z" + }, + { + "sequence": 7, + "event_type": "ExternalSignalFailed", + "payload": { + "sequence": 3, + "target_workflow_instance_id": "order-open", + "target_workflow_run_id": "01j00000000000000000000t03", + "signal_name": "undeclared", + "request_id": "workflow-signal:01j00000000000000000000s01:3", + "outcome": "rejected", + "reason": "unknown_signal", + "message": "Signal [undeclared] is not declared.", + "target_command_id": "01j00000000000000000000c03" + }, + "recorded_at": "2026-11-19T12:00:03Z" + }, + { + "sequence": 8, + "event_type": "SideEffectRecorded", + "payload": { + "sequence": 4, + "result": "wwHioz3/VYAiNwoKYWZ0ZXI=" + }, + "recorded_at": "2026-11-19T12:00:04Z" + } + ], + "expected": { + "completed": true, + "result": { + "results": [ + { + "outcome": "target_not_found", + "reason": "instance_not_found", + "message": "No workflow instance [order-missing] exists in this namespace.", + "target_workflow_id": "order-missing", + "target_run_id": null, + "signal_name": "approve", + "request_id": "workflow-signal:01j00000000000000000000s01:1", + "target_command_id": null, + "target_signal_id": null, + "retained": false + }, + { + "outcome": "target_closed", + "reason": "run_not_active", + "message": "The target run is closed.", + "target_workflow_id": "order-closed", + "target_run_id": "01j00000000000000000000t02", + "signal_name": "approve", + "request_id": "workflow-signal:01j00000000000000000000s01:2", + "target_command_id": "01j00000000000000000000c02", + "target_signal_id": null, + "retained": false + }, + { + "outcome": "rejected", + "reason": "unknown_signal", + "message": "Signal [undeclared] is not declared.", + "target_workflow_id": "order-open", + "target_run_id": "01j00000000000000000000t03", + "signal_name": "undeclared", + "request_id": "workflow-signal:01j00000000000000000000s01:3", + "target_command_id": "01j00000000000000000000c03", + "target_signal_id": null, + "retained": false + } + ], + "after": "after" + }, + "commands": [ + { + "type": "complete_workflow" + } + ] + } +} diff --git a/tests/Fixtures/V2/ReplayRegression/signal-external-request-without-outcome.json b/tests/Fixtures/V2/ReplayRegression/signal-external-request-without-outcome.json new file mode 100644 index 000000000..8805158a4 --- /dev/null +++ b/tests/Fixtures/V2/ReplayRegression/signal-external-request-without-outcome.json @@ -0,0 +1,58 @@ +{ + "$schema": "https://raw.githubusercontent.com/durable-workflow/.github/main/regression-corpus/evidence-schema.json", + "fixture_schema": "durable-workflow.replay-regression/v1", + "id": "signal-external-request-without-outcome", + "protocol_version": "1.20", + "bindings": [ + "php" + ], + "consumers": [ + "workflow-fiber-runner", + "query-state-replayer", + "workflow-executor" + ], + "workflow": { + "type": "Tests\\Fixtures\\V2\\TestSignalExternalSenderWorkflow", + "arguments": [ + [ + { + "workflow_id": "order-42", + "signal": "approve", + "arguments": [ + "Ada" + ] + } + ] + ], + "payload_codec": "avro" + }, + "history": [ + { + "sequence": 1, + "event_type": "WorkflowStarted", + "payload": {}, + "recorded_at": "2026-11-19T12:00:00Z" + }, + { + "sequence": 2, + "event_type": "ExternalSignalRequested", + "payload": { + "sequence": 1, + "target_workflow_instance_id": "order-42", + "target_workflow_run_id": null, + "signal_name": "approve", + "arguments": { + "codec": "avro", + "blob": "wwHioz3/VYAiNwwCCgZBZGEA" + }, + "payload_codec": "avro", + "request_id": "workflow-signal:01j00000000000000000000s01:1" + }, + "recorded_at": "2026-11-19T12:00:01Z" + } + ], + "expected_failure": { + "type": "workflow_history_shape_mismatch", + "exception": "Workflow\\V2\\Exceptions\\HistoryEventShapeMismatchException" + } +} diff --git a/tests/Fixtures/V2/ReplayRegression/signal-external-target-changed.json b/tests/Fixtures/V2/ReplayRegression/signal-external-target-changed.json new file mode 100644 index 000000000..1614b5d47 --- /dev/null +++ b/tests/Fixtures/V2/ReplayRegression/signal-external-target-changed.json @@ -0,0 +1,74 @@ +{ + "$schema": "https://raw.githubusercontent.com/durable-workflow/.github/main/regression-corpus/evidence-schema.json", + "fixture_schema": "durable-workflow.replay-regression/v1", + "id": "signal-external-target-changed", + "protocol_version": "1.20", + "bindings": [ + "php" + ], + "consumers": [ + "workflow-fiber-runner", + "query-state-replayer", + "workflow-executor" + ], + "workflow": { + "type": "Tests\\Fixtures\\V2\\TestSignalExternalSenderWorkflow", + "arguments": [ + [ + { + "workflow_id": "order-43", + "signal": "approve", + "arguments": [ + "Ada" + ] + } + ] + ], + "payload_codec": "avro" + }, + "history": [ + { + "sequence": 1, + "event_type": "WorkflowStarted", + "payload": {}, + "recorded_at": "2026-11-19T12:00:00Z" + }, + { + "sequence": 2, + "event_type": "ExternalSignalRequested", + "payload": { + "sequence": 1, + "target_workflow_instance_id": "order-42", + "target_workflow_run_id": null, + "signal_name": "approve", + "arguments": { + "codec": "avro", + "blob": "wwHioz3/VYAiNwwCCgZBZGEA" + }, + "payload_codec": "avro", + "request_id": "workflow-signal:01j00000000000000000000s01:1" + }, + "recorded_at": "2026-11-19T12:00:01Z" + }, + { + "sequence": 3, + "event_type": "ExternalSignalDelivered", + "payload": { + "sequence": 1, + "target_workflow_instance_id": "order-42", + "target_workflow_run_id": "01j00000000000000000000t01", + "signal_name": "approve", + "request_id": "workflow-signal:01j00000000000000000000s01:1", + "outcome": "delivered", + "target_command_id": "01j00000000000000000000c01", + "target_signal_id": "01j00000000000000000000g01", + "retained": false + }, + "recorded_at": "2026-11-19T12:00:01Z" + } + ], + "expected_failure": { + "type": "workflow_history_shape_mismatch", + "exception": "Workflow\\V2\\Exceptions\\HistoryEventShapeMismatchException" + } +} diff --git a/tests/Fixtures/V2/TestSignalExternalChildHandleWorkflow.php b/tests/Fixtures/V2/TestSignalExternalChildHandleWorkflow.php new file mode 100644 index 000000000..a7bf650e7 --- /dev/null +++ b/tests/Fixtures/V2/TestSignalExternalChildHandleWorkflow.php @@ -0,0 +1,24 @@ +lastChild()?->signalDurably('approve', $value); + + return [ + 'signal' => $signal?->toArray(), + 'child' => $child->await(), + ]; + } +} diff --git a/tests/Fixtures/V2/TestSignalExternalInvalidNameWorkflow.php b/tests/Fixtures/V2/TestSignalExternalInvalidNameWorkflow.php new file mode 100644 index 000000000..62558f26f --- /dev/null +++ b/tests/Fixtures/V2/TestSignalExternalInvalidNameWorkflow.php @@ -0,0 +1,30 @@ + $exception->reason, + 'field' => $exception->field, + ]; + } + + return [ + 'reason' => null, + ]; + } +} diff --git a/tests/Fixtures/V2/TestSignalExternalSenderWorkflow.php b/tests/Fixtures/V2/TestSignalExternalSenderWorkflow.php new file mode 100644 index 000000000..67bb0789d --- /dev/null +++ b/tests/Fixtures/V2/TestSignalExternalSenderWorkflow.php @@ -0,0 +1,40 @@ +, run_id?: string|null}> $targets + */ + public function handle(array $targets): array + { + $results = []; + + foreach ($targets as $target) { + $results[] = signalExternalWorkflow( + $target['workflow_id'], + $target['signal'], + $target['arguments'] ?? [], + $target['run_id'] ?? null, + )->toArray(); + } + + return [ + 'results' => $results, + 'after' => sideEffect(static fn (): string => 'after'), + ]; + } +} diff --git a/tests/Fixtures/V2/TestSignalExternalTargetWorkflow.php b/tests/Fixtures/V2/TestSignalExternalTargetWorkflow.php new file mode 100644 index 000000000..ba93201b5 --- /dev/null +++ b/tests/Fixtures/V2/TestSignalExternalTargetWorkflow.php @@ -0,0 +1,23 @@ + await('approve'), + 'workflow_id' => $this->workflowId(), + ]; + } +} diff --git a/tests/Unit/V2/SignalExternalWorkflowCallTest.php b/tests/Unit/V2/SignalExternalWorkflowCallTest.php new file mode 100644 index 000000000..23c94467d --- /dev/null +++ b/tests/Unit/V2/SignalExternalWorkflowCallTest.php @@ -0,0 +1,264 @@ + + */ + public static function refusedNames(): array + { + return [ + 'empty' => [''], + 'blank' => [' '], + 'ideographic blank' => ["\u{3000}\u{2003}"], + 'newline' => ["bad\nname"], + 'nul' => ["bad\0name"], + 'escape' => ["bad\x1bname"], + 'delete' => ["bad\x7fname"], + '192 characters' => [str_repeat('a', 192)], + '256 bytes' => [str_repeat('é', 128)], + 'invalid utf-8' => ["bad\xC3name"], + ]; + } + + #[DataProvider('refusedNames')] + public function testServerSignalNameRulesRefuseInWorkflowCode(string $name): void + { + try { + new SignalExternalWorkflowCall('order-42', $name); + $this->fail('The signal name must be refused.'); + } catch (InvalidExternalSignalException $exception) { + $this->assertSame('invalid_signal_name', $exception->reason); + $this->assertSame('signal_name', $exception->field); + } + } + + /** + * @return array + */ + public static function acceptedNames(): array + { + return [ + 'ordinary' => ['approve'], + '191 characters' => [str_repeat('a', 191)], + '255 bytes as 85 characters' => [str_repeat('€', 85)], + 'inner spaces' => ['approve order'], + ]; + } + + #[DataProvider('acceptedNames')] + public function testLongestServerAcceptedNamesAreAccepted(string $name): void + { + $this->assertSame($name, (new SignalExternalWorkflowCall('order-42', $name))->signalName); + } + + public function testTargetIdentifiersFollowTheCommandFieldRules(): void + { + foreach ([['', null], [' ', null], [str_repeat('a', 192), null], ['order-42', ' ']] as [$id, $run]) { + try { + new SignalExternalWorkflowCall($id, 'approve', [], $run); + $this->fail('The target must be refused.'); + } catch (InvalidExternalSignalException $exception) { + $this->assertSame('invalid_signal_external_target', $exception->reason); + } + } + + $call = new SignalExternalWorkflowCall(str_repeat('a', 191), 'approve', [ + 2 => 'x', + ], 'run-1'); + $this->assertSame('run-1', $call->runId); + $this->assertSame([ + 2 => 'x', + ], $call->arguments); + $this->assertSame(['x'], (new SignalExternalWorkflowCall('order-42', 'approve', ['x']))->arguments); + } + + public function testReservedRequestIdsAreRecognized(): void + { + $this->assertSame('workflow-signal:run-1:3', ExternalSignalHistory::requestId('run-1', 3)); + $this->assertTrue(ExternalSignalHistory::isReservedRequestId('workflow-signal:anything')); + $this->assertFalse(ExternalSignalHistory::isReservedRequestId('workflow-signalling')); + $this->assertFalse(ExternalSignalHistory::isReservedRequestId(null)); + } + + public function testRecordedOutcomeReplaysAsTheSameValue(): void + { + $call = new SignalExternalWorkflowCall('order-42', 'approve', ['Ada', 2]); + $run = $this->runWithHistory([ + ['ExternalSignalRequested', $this->requested($call)], + ['ExternalSignalFailed', [ + ...$this->identity(), + 'target_workflow_run_id' => 'target-run', + 'outcome' => 'target_closed', + 'reason' => 'run_not_active', + 'message' => 'The target run is closed.', + 'target_command_id' => 'cmd-1', + ]], + ]); + + $result = ExternalSignalHistory::recordedResult($run, 1, $call); + + $this->assertNotNull($result); + $this->assertSame(ExternalSignalOutcome::TargetClosed, $result->outcome); + $this->assertFalse($result->delivered()); + $this->assertSame('run_not_active', $result->reason); + $this->assertSame('target-run', $result->targetRunId); + $this->assertSame('cmd-1', $result->targetCommandId); + $this->assertNull(ExternalSignalHistory::recordedResult($run, 2, $call)); + } + + /** + * @return array + */ + public static function changedCalls(): array + { + return [ + 'target' => [new SignalExternalWorkflowCall('order-43', 'approve', ['Ada', 2])], + 'run' => [new SignalExternalWorkflowCall('order-42', 'approve', ['Ada', 2], 'run-9')], + 'name' => [new SignalExternalWorkflowCall('order-42', 'reject', ['Ada', 2])], + 'arguments' => [new SignalExternalWorkflowCall('order-42', 'approve', ['Ada', '2'])], + ]; + } + + #[DataProvider('changedCalls')] + public function testChangedSignalAtARecordedSequenceIsAShapeMismatch(SignalExternalWorkflowCall $changed): void + { + $recorded = new SignalExternalWorkflowCall('order-42', 'approve', ['Ada', 2]); + $run = $this->runWithHistory([ + ['ExternalSignalRequested', $this->requested($recorded)], + ['ExternalSignalDelivered', $this->delivered()], + ]); + + $this->expectException(HistoryEventShapeMismatchException::class); + $this->expectExceptionMessage('external_signal_mismatch'); + + ExternalSignalHistory::recordedResult($run, 1, $changed); + } + + public function testMalformedResolutionHistoryIsRefused(): void + { + $call = new SignalExternalWorkflowCall('order-42', 'approve', ['Ada', 2]); + $histories = [ + 'outcome without request' => [['ExternalSignalDelivered', $this->delivered()]], + 'request without outcome' => [['ExternalSignalRequested', $this->requested($call)]], + 'two outcomes' => [ + ['ExternalSignalRequested', $this->requested($call)], + ['ExternalSignalDelivered', $this->delivered()], + ['ExternalSignalDelivered', $this->delivered()], + ], + 'unknown outcome' => [ + ['ExternalSignalRequested', $this->requested($call)], + [ + 'ExternalSignalFailed', [ + ...$this->delivered(), + 'outcome' => 'lost', + 'reason' => 'x', + ]], + ], + 'renamed target' => [ + ['ExternalSignalRequested', $this->requested($call)], + [ + 'ExternalSignalDelivered', [ + ...$this->delivered(), + 'target_workflow_instance_id' => 'other', + ]], + ], + 'failure without reason' => [ + ['ExternalSignalRequested', $this->requested($call)], + [ + 'ExternalSignalFailed', [ + ...$this->identity(), + 'outcome' => 'rejected', + ]], + ], + ]; + + foreach ($histories as $label => $history) { + try { + ExternalSignalHistory::recordedResult($this->runWithHistory($history), 1, $call); + $this->fail("{$label} must be refused."); + } catch (HistoryEventShapeMismatchException $exception) { + $this->assertStringContainsString('external_signal_history_invalid', $exception->getMessage(), $label); + } + } + } + + /** + * @return array + */ + private function identity(): array + { + return [ + 'sequence' => 1, + 'target_workflow_instance_id' => 'order-42', + 'signal_name' => 'approve', + 'request_id' => 'workflow-signal:sender-run:1', + ]; + } + + /** + * @return array + */ + private function requested(SignalExternalWorkflowCall $call): array + { + return [ + 'sequence' => 1, + 'target_workflow_instance_id' => $call->workflowId, + 'target_workflow_run_id' => $call->runId, + 'signal_name' => $call->signalName, + 'arguments' => [ + 'codec' => 'avro', + 'blob' => Serializer::serializeWithCodec('avro', $call->arguments), + ], + 'payload_codec' => 'avro', + 'request_id' => 'workflow-signal:sender-run:1', + ]; + } + + /** + * @return array + */ + private function delivered(): array + { + return [ + ...$this->identity(), + 'target_workflow_run_id' => 'target-run', + 'outcome' => 'delivered', + 'target_command_id' => 'cmd-1', + 'target_signal_id' => 'sig-1', + 'retained' => false, + ]; + } + + /** + * @param list}> $events + */ + private function runWithHistory(array $events): WorkflowRun + { + $run = new WorkflowRun(); + $run->setRelation('historyEvents', collect($events)->values()->map( + static fn (array $event, int $index): WorkflowHistoryEvent => new WorkflowHistoryEvent([ + 'sequence' => $index + 1, + 'event_type' => $event[0], + 'payload' => $event[1], + ]), + )); + + return $run; + } +} From a1e127811b3343f5f61caf11997f1d22209110a0 Mon Sep 17 00:00:00 2001 From: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com> Date: Thu, 19 Nov 2026 19:17:01 +0000 Subject: [PATCH 2/4] Keep tracker numbers out of the API stability guide Co-Authored-By: Claude Opus 5.5 --- docs/api-stability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api-stability.md b/docs/api-stability.md index 4cc0091c7..9376c6e65 100644 --- a/docs/api-stability.md +++ b/docs/api-stability.md @@ -267,7 +267,7 @@ no recursive or shared child machines. See ## Durable signal-external Durable signal-external lets embedded workflow code signal another workflow in -its namespace (.github#223). It is **experimental**: the +its namespace. It is **experimental**: the `Workflow\V2\signalExternalWorkflow()` function, the `Workflow::signalExternalWorkflow()` facade method, `ChildWorkflowHandle::signalDurably()`, `ExternalSignalResult`, From 25b4c053f30715567c155ce645acd38faa509004 Mon Sep 17 00:00:00 2001 From: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com> Date: Thu, 19 Nov 2026 20:29:29 +0000 Subject: [PATCH 3/4] Deliver durable signal-external through an outbox Review of the in-transaction delivery found that mutual signals deadlocked and failed a sender, that a lock timeout or a target continuing as new failed the sender permanently, and that MySQL's repeatable-read snapshot inside the sender's task read a stale target. Delivery is now an outbox, as on the Server and in Temporal: - The sending task records ExternalSignalRequested and commits, locking only its own run, and workflow code waits for the outcome. - After that commit, the target admits an ordinary signal in its own transaction under the workflow-signal:: key; the sender's run is then locked on its own to append exactly one ExternalSignalDelivered or ExternalSignalFailed and get a workflow task. - Deadlocks, lock timeouts and lost connections are retried and never fail the sender. A delayed sender task re-attempts a pending delivery, so a crash between the commit and the delivery is recovered by task repair. - A request without an outcome now waits on replay instead of being malformed history. Also: the command is refused during cleanup after a cancellation request (cancellation_cleanup_command_not_available, as on Server); reserved request-id refusals carry the Server's outcome/accepted body; the CHANGELOG has an upgrade note for the reserved prefix; and the reserved-key admission is private to the delivery. The reviewer's concurrent scenarios are tests on MySQL and PostgreSQL: mutual signalling, lock wait timeout, a target created or finishing its task mid-send, a target closing or continuing as new, and a crash after the sender's commit. Co-Authored-By: Claude Opus 5.5 --- .github/feature-test-timings.json | 6 +- CHANGELOG.md | 50 +- docs/api-stability.md | 62 ++- .../ExternalSignalRefusedException.php | 36 ++ .../InvalidCommandRequestIdException.php | 11 +- .../Support/DefaultWorkflowControlPlane.php | 3 + src/V2/Support/ExternalSignalDelivery.php | 214 +++++++- src/V2/Support/ExternalSignalHistory.php | 102 +++- src/V2/Support/QueryStateReplayer.php | 3 +- src/V2/Support/WorkflowExecutor.php | 101 +++- src/V2/Support/WorkflowFiberRunner.php | 20 +- src/V2/Support/WorkflowTaskPayload.php | 22 + src/V2/Webhooks.php | 3 + src/V2/WorkflowStub.php | 48 +- .../V2/V2SignalExternalConcurrencyTest.php | 477 ++++++++++++++++++ .../V2/V2SignalExternalWorkflowTest.php | 72 ++- ...gnal-external-outcome-without-request.json | 57 +++ ...ignal-external-pending-request-waits.json} | 14 +- .../V2/TestSignalExternalCleanupWorkflow.php | 34 ++ .../V2/TestSignalExternalPingWorkflow.php | 36 ++ .../TestSignalExternalSlowCloseWorkflow.php | 36 ++ .../V2/SignalExternalWorkflowCallTest.php | 19 +- 22 files changed, 1293 insertions(+), 133 deletions(-) create mode 100644 src/V2/Exceptions/ExternalSignalRefusedException.php create mode 100644 tests/Feature/V2/V2SignalExternalConcurrencyTest.php create mode 100644 tests/Fixtures/V2/ReplayRegression/signal-external-outcome-without-request.json rename tests/Fixtures/V2/ReplayRegression/{signal-external-request-without-outcome.json => signal-external-pending-request-waits.json} (79%) create mode 100644 tests/Fixtures/V2/TestSignalExternalCleanupWorkflow.php create mode 100644 tests/Fixtures/V2/TestSignalExternalPingWorkflow.php create mode 100644 tests/Fixtures/V2/TestSignalExternalSlowCloseWorkflow.php diff --git a/.github/feature-test-timings.json b/.github/feature-test-timings.json index 5bfc3d480..c389f1c72 100644 --- a/.github/feature-test-timings.json +++ b/.github/feature-test-timings.json @@ -207,7 +207,8 @@ "tests/Feature/V2/V2ServiceModeParallelChildBarrierTest.php": 44.361974, "tests/Feature/V2/V2ServiceResponseReplayTest.php": 4.111694, "tests/Feature/V2/V2SideEffectWorkflowTest.php": 21.707655, - "tests/Feature/V2/V2SignalExternalWorkflowTest.php": 15.4, + "tests/Feature/V2/V2SignalExternalConcurrencyTest.php": 38.4, + "tests/Feature/V2/V2SignalExternalWorkflowTest.php": 17.0, "tests/Feature/V2/V2StableCompensationExampleTest.php": 25.160551, "tests/Feature/V2/V2StandaloneActivityHostTest.php": 20.738894, "tests/Feature/V2/V2StartNamespaceTest.php": 3.144255, @@ -464,7 +465,8 @@ "tests/Feature/V2/V2ServiceModeParallelChildBarrierTest.php": 5.346706, "tests/Feature/V2/V2ServiceResponseReplayTest.php": 5.828296, "tests/Feature/V2/V2SideEffectWorkflowTest.php": 5.792351, - "tests/Feature/V2/V2SignalExternalWorkflowTest.php": 13.3, + "tests/Feature/V2/V2SignalExternalConcurrencyTest.php": 25.5, + "tests/Feature/V2/V2SignalExternalWorkflowTest.php": 14.3, "tests/Feature/V2/V2StableCompensationExampleTest.php": 11.153563, "tests/Feature/V2/V2StandaloneActivityHostTest.php": 23.795291, "tests/Feature/V2/V2StartNamespaceTest.php": 2.658658, diff --git a/CHANGELOG.md b/CHANGELOG.md index c2726438e..f2e757e49 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,24 +6,38 @@ can signal another workflow in its namespace with `signalExternalWorkflow($workflowId, $signalName, $arguments, $runId)` (also `Workflow::signalExternalWorkflow()`), or its child with - `ChildWorkflowHandle::signalDurably()`. The request and its outcome are - recorded once in the sender's history (`ExternalSignalRequested`, then - `ExternalSignalDelivered` or `ExternalSignalFailed`, at one sequence) in the - same transaction that admits an ordinary signal on the target, keyed - `workflow-signal::` and attributed to the sender through - `CommandContext::workflow()`. Replay returns the recorded - `ExternalSignalResult` and never sends again. A missing, closed or refusing - target is a returned outcome (`target_not_found`, `target_closed` or - `rejected`, with Server's reasons, including `self_target` and - `runtime_reserved_signal`), not an exception. Signal names follow Server's - rules and are refused in workflow code with - `InvalidExternalSignalException` before anything is recorded. Callers can no - longer use the `workflow-signal:` request-id prefix for signals or - signal-with-start (`request_id_reserved`). The existing child-handle - `signal()` still sends directly. External PHP workers replay recorded - outcomes but refuse new commands. No database migration. - `docs/api-stability.md#durable-signal-external` explains why the API is - experimental and how embedded differs from Server. + `ChildWorkflowHandle::signalDurably()`, and receives an + `ExternalSignalResult`. Delivery is an outbox: the sending task records + `ExternalSignalRequested` and commits, touching only its own run. Delivery + then admits an ordinary signal on the target in the target's own + transaction, keyed `workflow-signal::` and attributed + through `CommandContext::workflow()`, and appends one + `ExternalSignalDelivered` or `ExternalSignalFailed` to the sender, which + resumes in a new workflow task. Deadlocks, lock timeouts and lost + connections are retried and never fail the sender; a delayed sender task + re-attempts a pending delivery after a crash. Replay returns the recorded + outcome and never sends again. A missing, closed or refusing target is a + returned outcome (`target_not_found`, `target_closed` or `rejected`, with + Server's reasons, including `self_target` and `runtime_reserved_signal`), + not an exception. Signal names follow Server's rules and are refused in + workflow code with `InvalidExternalSignalException` before anything is + recorded. During cleanup after a cancellation request the command throws + `ExternalSignalRefusedException` (`cancellation_cleanup_command_not_available`), + as on Server. The existing child-handle `signal()` still sends directly. + External PHP workers replay recorded outcomes but refuse new commands. No + database migration. `docs/api-stability.md#durable-signal-external` explains + why the API is experimental. + + **Upgrade note:** request IDs starting with `workflow-signal:` are now + reserved. A signal or signal-with-start that uses one, through + `withRequestId()`, the control plane's `request_id` or a signal webhook's + `X-Request-Id`, is refused before anything is read or written: embedded + calls throw `InvalidCommandRequestIdException` (`reason()` + `request_id_reserved`); the control plane and signal webhooks return 422 + with `reason: "request_id_reserved"`, `outcome: + "rejected_request_id_reserved"` and `accepted: false`, the Server's body. + Callers that already use that prefix must choose another before upgrading. + Commands admitted earlier under such a key are unchanged. - The business state-machine API is explicitly experimental (#1069). Every public class, interface and enum in `Workflow\V2\StateMachine`, native child diff --git a/docs/api-stability.md b/docs/api-stability.md index 9376c6e65..22a102457 100644 --- a/docs/api-stability.md +++ b/docs/api-stability.md @@ -271,35 +271,50 @@ its namespace. It is **experimental**: the `Workflow\V2\signalExternalWorkflow()` function, the `Workflow::signalExternalWorkflow()` facade method, `ChildWorkflowHandle::signalDurably()`, `ExternalSignalResult`, -`Enums\ExternalSignalOutcome` and `Exceptions\InvalidExternalSignalException` -are marked `@experimental` and may change incompatibly in a minor release, never -in a patch release. They are not part of the stable facade list above. +`Enums\ExternalSignalOutcome`, `Exceptions\InvalidExternalSignalException` and +`Exceptions\ExternalSignalRefusedException` are marked `@experimental` and may +change incompatibly in a minor release, never in a patch release. They are not +part of the stable facade list above. They are experimental, not stable, because the embedded surface is new while the contract it implements is not. The command, its history events, the `workflow-signal:` key and its outcomes follow the shipped Server 3.15.0 contract (`docs/contracts/signal-external-workflow.md` in the server repository) and the published Python, PHP SDK and Rust SDKs. The PHP authoring -names and result type have not shipped in any release. The embedded runtime -also differs from Server in ways a later minor release may still align: - -- Delivery is synchronous in the sending workflow task, so the sender needs no - extra workflow task (Server's `external_signal` turn) and continues at once. -- The worker-protocol runner (`WorkflowFiberRunner`, used by external PHP - workers) replays recorded outcomes but refuses a new command with - `UnsupportedWorkflowYieldException`. It does not advertise - `signal_external_workflow`. -- Embedded does not refuse the command while a run is cleaning up after a - cancellation request. Server refuses it then - (`signal_external_not_at_checkpoint`). +names and result type have not shipped in any release, and the +worker-protocol runner (`WorkflowFiberRunner`, used by external PHP workers) +replays recorded requests and outcomes but refuses a new command with +`UnsupportedWorkflowYieldException`; embedded does not advertise +`signal_external_workflow`. + +Delivery is an outbox, as on the Server and in Temporal: + +- The sending workflow task records `ExternalSignalRequested` and commits. It + locks only the sender's rows, and workflow code waits for the outcome as it + waits for an activity result. +- After that commit, delivery admits an ordinary signal on the target in the + target's own transaction, keyed `workflow-signal::` + and attributed to the sender through `CommandContext::workflow()`. It then + locks the sender's run on its own, appends exactly one + `ExternalSignalDelivered` or `ExternalSignalFailed` at the request's + sequence, and gives the sender a workflow task. A repeated delivery returns + the target's retained receipt (`retained: true`) instead of signalling + twice. +- A deadlock, lock wait timeout or lost connection is retried, and never fails + the sender. While a request is pending, the sender keeps a delayed workflow + task that replays to the request and delivers it again, so a process that + dies between the sender's commit and the delivery is recovered by the + ordinary task repair. Only definitive answers (not found, closed, rejected) + are recorded as failures. +- While a run cleans up after a cancellation request, the command throws + `ExternalSignalRefusedException` (`cancellation_cleanup_command_not_available`) + in workflow code and records nothing, as the Server refuses every command + but activities, timers and side effects then. The history events are frozen like every other event (see the table below): once a run records them, every later release must replay them. The command -takes one workflow sequence. `ExternalSignalRequested` and exactly one of -`ExternalSignalDelivered` or `ExternalSignalFailed` are recorded at that -sequence in the same transaction that admits the signal on the target, keyed -on the target as `workflow-signal::`. Replay, query -replay and cold replay read the recorded outcome and never send again. A +takes one workflow sequence. Replay, query replay and cold replay read the +recorded outcome and never send again; a request without an outcome waits. A changed target, run, signal name or arguments at a recorded sequence, or malformed resolution history, is a `HistoryEventShapeMismatchException`. A failed outcome (`target_not_found`, `target_closed` or `rejected`, with the @@ -307,9 +322,10 @@ Server's reasons) is a returned value, not an exception. Callers cannot use the `workflow-signal:` request-id prefix for a signal or signal-with-start. Embedded calls throw `InvalidCommandRequestIdException` with -`reason()` `request_id_reserved`; control-plane signals and embedded signal -webhooks return 422 with `reason: "request_id_reserved"`. Nothing is read or -written for the refused request. +`reason()` `request_id_reserved`. Control-plane signals and embedded signal +webhooks return the Server's 422 body: `reason: "request_id_reserved"`, +`outcome: "rejected_request_id_reserved"`, `accepted: false` and its message. +Nothing is read or written for the refused request. ## What is covered diff --git a/src/V2/Exceptions/ExternalSignalRefusedException.php b/src/V2/Exceptions/ExternalSignalRefusedException.php new file mode 100644 index 000000000..ddfdeaf44 --- /dev/null +++ b/src/V2/Exceptions/ExternalSignalRefusedException.php @@ -0,0 +1,36 @@ +reason; } + /** + * The command outcome the Server reports for a reserved key + * (`rejected_request_id_reserved`); null for an invalid key. + */ + public function outcome(): ?string + { + return $this->reason === self::REASON_RESERVED ? 'rejected_request_id_reserved' : null; + } + /** * @return array> */ diff --git a/src/V2/Support/DefaultWorkflowControlPlane.php b/src/V2/Support/DefaultWorkflowControlPlane.php index a9cda3562..d8388945f 100644 --- a/src/V2/Support/DefaultWorkflowControlPlane.php +++ b/src/V2/Support/DefaultWorkflowControlPlane.php @@ -1411,6 +1411,9 @@ private function invalidRequestIdResult(string $instanceId, InvalidCommandReques 'command_id' => null, 'update_id' => null, 'reason' => $exception->reason(), + ...($exception->outcome() === null ? [] : [ + 'outcome' => $exception->outcome(), + ]), 'message' => $exception->getMessage(), 'validation_errors' => $exception->validationErrors(), 'status' => 422, diff --git a/src/V2/Support/ExternalSignalDelivery.php b/src/V2/Support/ExternalSignalDelivery.php index 4fafbfb78..6f0c9188d 100644 --- a/src/V2/Support/ExternalSignalDelivery.php +++ b/src/V2/Support/ExternalSignalDelivery.php @@ -4,34 +4,195 @@ namespace Workflow\V2\Support; +use Throwable; +use Workflow\Support\AfterCommit; use Workflow\V2\CommandContext; use Workflow\V2\CommandResult; +use Workflow\V2\Contracts\HistoryProjectionRole; use Workflow\V2\Enums\ExternalSignalOutcome; use Workflow\V2\Enums\HistoryEventType; +use Workflow\V2\Enums\TaskStatus; +use Workflow\V2\Enums\TaskType; +use Workflow\V2\Models\WorkflowHistoryEvent; use Workflow\V2\Models\WorkflowInstance; use Workflow\V2\Models\WorkflowRun; use Workflow\V2\Models\WorkflowSignal; +use Workflow\V2\Models\WorkflowTask; use Workflow\V2\WorkflowStub; /** - * Admits one durable signal-external command on its target (.github#223). + * Delivers durable signal-external requests (.github#223), as an outbox. * - * Runs inside the sending workflow task's transaction. A delivered signal is - * an ordinary signal on the target: the same accepted command, signal record, - * `SignalReceived` event and message task as any other signal, attributed to - * the sending run through `CommandContext::workflow()` and keyed on the - * target as `workflow-signal::`. Because the sender's - * history and the target's admission share one transaction, a task that - * rolls back sends nothing and a committed task never sends again. + * The sending workflow task records `ExternalSignalRequested` and commits, + * locking only its own rows. Delivery then runs after that commit, outside + * the sender's transaction: + * + * 1. The target admits an ordinary signal in its own transaction (the same + * accepted command, signal record, `SignalReceived` and message task as + * any signal), keyed `workflow-signal::` and + * attributed through `CommandContext::workflow()`. A repeated delivery + * returns the retained receipt instead of signalling twice. + * 2. The sender's run is locked on its own, exactly one + * `ExternalSignalDelivered` or `ExternalSignalFailed` is appended at the + * request's sequence, and the sender gets a workflow task to read it. + * + * A transient database failure (deadlock, lock wait, lost connection) is + * retried here and otherwise left pending: it never fails the sender. The + * sender's delayed resume task re-attempts a pending delivery, so a crash + * between the sender's commit and its delivery is recovered by the same + * task repair that recovers any workflow task. Only definitive answers + * (not found, closed, rejected) are recorded as failures. * * @internal */ final class ExternalSignalDelivery { + private const INLINE_ATTEMPTS = 3; + + /** + * Deliver one pending request after the caller's transaction commits. + * Never throws: a delivery that cannot finish now stays pending. + */ + public static function afterCommit(WorkflowRun $sender, int $sequence): void + { + $runId = $sender->id; + AfterCommit::on($sender->getConnection(), static function () use ($runId, $sequence): void { + self::deliverPending($runId, $sequence); + }); + } + + /** + * Deliver the request recorded at this sequence, if it is still pending. + * Returns true once an outcome is recorded (now or earlier). + */ + public static function deliverPending(string $senderRunId, int $sequence): bool + { + for ($attempt = 1; ; ++$attempt) { + try { + return self::attempt($senderRunId, $sequence); + } catch (Throwable $throwable) { + if (! self::transient($throwable) || $attempt >= self::INLINE_ATTEMPTS) { + if (! self::transient($throwable)) { + report($throwable); + } + + return false; + } + + usleep($attempt * 50_000); + } + } + } + + private static function attempt(string $senderRunId, int $sequence): bool + { + /** @var WorkflowRun|null $sender */ + $sender = ConfiguredV2Models::query('run_model', WorkflowRun::class) + ->with('historyEvents') + ->find($senderRunId); + + if (! $sender instanceof WorkflowRun) { + return false; + } + + $request = ExternalSignalHistory::pendingRequests($sender)[$sequence] ?? null; + if (! $request instanceof WorkflowHistoryEvent) { + // Already resolved, or never requested. + return ExternalSignalHistory::resolutionEvent($sender, $sequence) instanceof WorkflowHistoryEvent; + } + + if ($sender->status->isTerminal()) { + // A closed sender has no workflow code left to read an outcome. + return false; + } + + $resolution = self::resolve($sender, $sequence, ExternalSignalHistory::callFromRequest($request)); + $wake = null; + + $recorded = SqliteTransaction::run(static function () use ($senderRunId, $sequence, $resolution, &$wake): bool { + /** @var WorkflowRun $locked */ + $locked = ConfiguredV2Models::query('run_model', WorkflowRun::class) + ->lockForUpdate() + ->findOrFail($senderRunId); + $locked->setRelation('historyEvents', $locked->historyEvents()->get()); + + if ($locked->status->isTerminal()) { + return false; + } + + if (! isset(ExternalSignalHistory::pendingRequests($locked)[$sequence])) { + return ExternalSignalHistory::resolutionEvent($locked, $sequence) instanceof WorkflowHistoryEvent; + } + + $event = WorkflowHistoryEvent::record($locked, $resolution['event_type'], $resolution['payload']); + $wake = self::wakeSender($locked, $event); + /** @var HistoryProjectionRole $projection */ + $projection = app(HistoryProjectionRole::class); + $projection->projectRun( + $locked->fresh(['instance', 'tasks', 'activityExecutions', 'timers', 'failures', 'historyEvents']) + ?? $locked + ); + + return true; + }); + + if ($wake instanceof WorkflowTask) { + TaskDispatcher::dispatch($wake); + } + + return $recorded; + } + + /** + * Make the sender's waiting workflow task due now, or create one. + * Runs under the sender's run lock. + */ + private static function wakeSender(WorkflowRun $sender, WorkflowHistoryEvent $event): ?WorkflowTask + { + /** @var WorkflowTask|null $open */ + $open = ConfiguredV2Models::query('task_model', WorkflowTask::class) + ->where('workflow_run_id', $sender->id) + ->where('task_type', TaskType::Workflow->value) + ->whereIn('status', [TaskStatus::Ready->value, TaskStatus::Leased->value]) + ->orderBy('created_at') + ->lockForUpdate() + ->first(); + + if ($open instanceof WorkflowTask) { + if ($open->status !== TaskStatus::Ready) { + // The leased task reads this outcome or leaves its own resume task. + return null; + } + + if ($open->available_at !== null && $open->available_at->isFuture()) { + $open->forceFill([ + 'available_at' => now(), + ])->save(); + } + + return $open; + } + + /** @var WorkflowTask $task */ + $task = ConfiguredV2Models::query('task_model', WorkflowTask::class)->create([ + 'workflow_run_id' => $sender->id, + 'namespace' => $sender->namespace, + 'task_type' => TaskType::Workflow->value, + 'status' => TaskStatus::Ready->value, + 'available_at' => now(), + 'payload' => WorkflowTaskPayload::forExternalSignal($event), + 'connection' => $sender->connection, + 'queue' => $sender->queue, + 'compatibility' => $sender->compatibility, + ]); + + return $task; + } + /** * @return array{event_type: HistoryEventType, payload: array} */ - public static function deliver(WorkflowRun $sender, int $sequence, SignalExternalWorkflowCall $call): array + private static function resolve(WorkflowRun $sender, int $sequence, SignalExternalWorkflowCall $call): array { $requestId = ExternalSignalHistory::requestId($sender->id, $sequence); $identity = [ @@ -102,13 +263,42 @@ public static function deliver(WorkflowRun $sender, int $sequence, SignalExterna } } - $result = WorkflowStub::loadSelection($instance->id, $call->runId) - ->withCommandContext(CommandContext::workflow($sender->workflow_instance_id, $sender->id, $sequence)) - ->attemptExternalWorkflowSignal($requestId, $call->signalName, $call->arguments); + $stub = WorkflowStub::loadSelection($instance->id, $call->runId) + ->withCommandContext(CommandContext::workflow($sender->workflow_instance_id, $sender->id, $sequence)); + // The reserved key is admitted only through this delivery. + $deliver = \Closure::bind( + static fn (WorkflowStub $target): CommandResult => $target->attemptExternalWorkflowSignal( + $requestId, + $call->signalName, + $call->arguments, + ), + null, + WorkflowStub::class, + ); + $result = $deliver($stub); return self::resolution($identity, $call, $result); } + private static function transient(Throwable $throwable): bool + { + if (TransactionFailure::endsTransaction($throwable)) { + return true; + } + + for ($current = $throwable; $current !== null; $current = $current->getPrevious()) { + $message = $current->getMessage(); + if (str_contains($message, 'lock timeout') + || str_contains($message, 'Lock wait timeout') + || str_contains($message, '55P03') + || str_contains($message, 'database is locked')) { + return true; + } + } + + return false; + } + /** * @param array $identity * @return array{event_type: HistoryEventType, payload: array} diff --git a/src/V2/Support/ExternalSignalHistory.php b/src/V2/Support/ExternalSignalHistory.php index 5b9cbfdb2..e8d000a39 100644 --- a/src/V2/Support/ExternalSignalHistory.php +++ b/src/V2/Support/ExternalSignalHistory.php @@ -35,6 +35,12 @@ final class ExternalSignalHistory public const SHAPE = 'external signal'; + public const NONE = 'none'; + + public const PENDING = 'pending'; + + public const RESOLVED = 'resolved'; + public static function requestId(string $senderRunId, int $sequence): string { return self::REQUEST_ID_PREFIX . $senderRunId . ':' . $sequence; @@ -46,14 +52,13 @@ public static function isReservedRequestId(mixed $requestId): bool } /** - * The recorded outcome for this command, or null when nothing is recorded - * at the sequence yet. + * What history records for this command at the sequence: nothing yet, a + * request whose delivery has not recorded its outcome, or the outcome. + * + * @return array{status: self::NONE|self::PENDING|self::RESOLVED, result: ExternalSignalResult|null} */ - public static function recordedResult( - WorkflowRun $run, - int $sequence, - SignalExternalWorkflowCall $call, - ): ?ExternalSignalResult { + public static function lookup(WorkflowRun $run, int $sequence, SignalExternalWorkflowCall $call): array + { $requested = self::events($run, $sequence, HistoryEventType::ExternalSignalRequested); $resolutions = [ ...self::events($run, $sequence, HistoryEventType::ExternalSignalDelivered), @@ -61,7 +66,10 @@ public static function recordedResult( ]; if ($requested === [] && $resolutions === []) { - return null; + return [ + 'status' => self::NONE, + 'result' => null, + ]; } if (count($requested) !== 1) { @@ -73,13 +81,83 @@ public static function recordedResult( $request = $requested[0]; self::assertSameIntent($sequence, $request, $call); + if ($resolutions === []) { + return [ + 'status' => self::PENDING, + 'result' => null, + ]; + } + if (count($resolutions) !== 1) { - self::invalid($sequence, $resolutions === [] - ? 'An external signal request was recorded without its outcome.' - : 'More than one external signal outcome was recorded at one sequence.'); + self::invalid($sequence, 'More than one external signal outcome was recorded at one sequence.'); + } + + return [ + 'status' => self::RESOLVED, + 'result' => self::resultFor($sequence, $request, $resolutions[0]), + ]; + } + + /** + * The recorded outcome for this command, or null when nothing is + * resolved at the sequence yet. + */ + public static function recordedResult( + WorkflowRun $run, + int $sequence, + SignalExternalWorkflowCall $call, + ): ?ExternalSignalResult { + return self::lookup($run, $sequence, $call)['result']; + } + + /** + * The signal a recorded request describes, for its delivery. + */ + public static function callFromRequest(WorkflowHistoryEvent $request): SignalExternalWorkflowCall + { + $payload = is_array($request->payload) ? $request->payload : []; + $arguments = $payload['arguments'] ?? null; + $codec = is_array($arguments) && is_string($arguments['codec'] ?? null) + ? $arguments['codec'] + : (is_string($payload['payload_codec'] ?? null) ? $payload['payload_codec'] : null); + $blob = is_array($arguments) ? ($arguments['blob'] ?? null) : $arguments; + $decoded = is_string($blob) ? Serializer::unserializeWithCodec($codec, $blob) : []; + + return new SignalExternalWorkflowCall( + (string) ($payload['target_workflow_instance_id'] ?? ''), + (string) ($payload['signal_name'] ?? ''), + is_array($decoded) ? $decoded : [], + is_string($payload['target_workflow_run_id'] ?? null) ? $payload['target_workflow_run_id'] : null, + ); + } + + /** + * Requests recorded on this run that have no outcome yet, by sequence. + * + * @return array + */ + public static function pendingRequests(WorkflowRun $run): array + { + $pending = []; + $resolved = []; + + foreach ($run->historyEvents as $event) { + $sequence = self::intValue($event->payload['sequence'] ?? null); + if ($sequence === null) { + continue; + } + + if ($event->event_type === HistoryEventType::ExternalSignalRequested) { + $pending[$sequence] ??= $event; + } elseif (in_array($event->event_type, [ + HistoryEventType::ExternalSignalDelivered, + HistoryEventType::ExternalSignalFailed, + ], true)) { + $resolved[$sequence] = true; + } } - return self::resultFor($sequence, $request, $resolutions[0]); + return array_diff_key($pending, $resolved); } /** diff --git a/src/V2/Support/QueryStateReplayer.php b/src/V2/Support/QueryStateReplayer.php index 15a8b80fe..c5975fc76 100644 --- a/src/V2/Support/QueryStateReplayer.php +++ b/src/V2/Support/QueryStateReplayer.php @@ -445,7 +445,8 @@ public function replayState(WorkflowRun $run): ReplayState $this->applyRecordedUpdates($run, $workflow, $historySequence); WorkflowStepHistory::assertCompatible($run, $historySequence, WorkflowStepHistory::EXTERNAL_SIGNAL); - // Query replay reads a recorded outcome and never delivers. + // Query replay reads a recorded outcome and never delivers; + // a pending request stops replay like a pending activity. $result = ExternalSignalHistory::recordedResult($run, $historySequence, $current); if ($result === null) { diff --git a/src/V2/Support/WorkflowExecutor.php b/src/V2/Support/WorkflowExecutor.php index fcc309fbd..27b624942 100644 --- a/src/V2/Support/WorkflowExecutor.php +++ b/src/V2/Support/WorkflowExecutor.php @@ -37,6 +37,7 @@ use Workflow\V2\Exceptions\ActivityRetryPolicyMismatchException; use Workflow\V2\Exceptions\ConditionWaitDefinitionMismatchException; use Workflow\V2\Exceptions\DurableOperationCancelledException; +use Workflow\V2\Exceptions\ExternalSignalRefusedException; use Workflow\V2\Exceptions\HistoryEventShapeMismatchException; use Workflow\V2\Exceptions\StructuralLimitExceededException; use Workflow\V2\Exceptions\UnresolvedWorkflowFailureException; @@ -1473,11 +1474,13 @@ private function executeMemo( } /** - * Durable signal-external (.github#223): record the request, admit the - * signal on the target and record its outcome at one sequence, all in - * this task's transaction. Replay returns the recorded outcome and never - * sends again. A failed delivery is a value for workflow code, not a - * task failure. + * Durable signal-external (.github#223), as an outbox. This task records + * `ExternalSignalRequested` and commits, locking only this run. Delivery + * runs after the commit in its own transactions + * ({@see ExternalSignalDelivery}), appends the outcome and wakes this run. + * Workflow code waits for the outcome as it waits for an activity result; + * replay reads the recorded outcome and never sends again. A failed + * delivery is a value for workflow code, not a task failure. */ private function executeExternalSignal( WorkflowRun $run, @@ -1498,27 +1501,47 @@ private function executeExternalSignal( return null; } try { - $result = ExternalSignalHistory::recordedResult($run, $sequence, $current); - if ($result === null) { - $this->recordExternalSignal($run, $task, $sequence, $current); - $result = ExternalSignalHistory::recordedResult($run, $sequence, $current); + $recorded = ExternalSignalHistory::lookup($run, $sequence, $current); + if ($recorded['status'] === ExternalSignalHistory::RESOLVED) { + $this->syncWorkflowCursor($workflow, $sequence + 1); + $current = $workflowExecution->send( + $recorded['result'], + RedriveReplayClock::recordedAt(ExternalSignalHistory::resolutionEvent($run, $sequence)), + advanceCancellationTime: false, + ); + ++$sequence; + + return WorkflowTaskStep::ContinueExecution; + } + + if ($recorded['status'] === ExternalSignalHistory::NONE) { + // As on the Server, cleanup after a cancellation request may + // only schedule activities, timers and side effects. + if (is_string($run->cancellation_request_command_id)) { + $this->syncWorkflowCursor($workflow, $sequence); + $current = $workflowExecution->throw(ExternalSignalRefusedException::duringCancellationCleanup()); + + return WorkflowTaskStep::ContinueExecution; + } + + $this->recordExternalSignalRequest($run, $task, $sequence, $current); } - $resolutionEvent = ExternalSignalHistory::resolutionEvent($run, $sequence); - $this->syncWorkflowCursor($workflow, $sequence + 1); - $current = $workflowExecution->send( - $result, - RedriveReplayClock::recordedAt($resolutionEvent), - advanceCancellationTime: false, - ); } catch (Throwable $throwable) { $this->failRun($run, $task, $throwable, 'workflow_run', $run->id); return null; } - ++$sequence; - return WorkflowTaskStep::ContinueExecution; + + // Pending: deliver after this task commits, and keep a delayed turn + // that re-attempts the delivery if this process never finishes it. + ExternalSignalDelivery::afterCommit($run, $sequence); + $this->syncWorkflowCursor($workflow, $sequence + 1); + $this->waitForNextResumeSource($run, $task); + $this->scheduleExternalSignalDeliveryRetry($run, $task, $sequence); + + return null; } - private function recordExternalSignal( + private function recordExternalSignalRequest( WorkflowRun $run, WorkflowTask $task, int $sequence, @@ -1543,10 +1566,44 @@ private function recordExternalSignal( $task, ); $run->historyEvents->push($requested); + } - $resolution = ExternalSignalDelivery::deliver($run, $sequence, $call); - $run->historyEvents->push( - WorkflowHistoryEvent::record($run, $resolution['event_type'], $resolution['payload'], $task), + /** + * The recovery path for a request whose delivery did not finish: a + * delayed workflow task that replays to this request and delivers it + * again (delivery is idempotent). Its delay doubles per attempt, up to a + * minute. A delivered outcome makes the task due at once. + */ + private function scheduleExternalSignalDeliveryRetry(WorkflowRun $run, WorkflowTask $task, int $sequence): void + { + if (self::hasOpenWorkflowTask($run->id)) { + return; + } + + $previous = ($task->payload['workflow_wait_kind'] ?? null) === 'external_signal' + && ($task->payload['workflow_sequence'] ?? null) === $sequence + ? (int) ($task->payload['external_signal_delivery_attempt'] ?? 0) + : 0; + $attempt = $previous + 1; + $delay = min(60, TaskRepairPolicy::redispatchAfterSeconds() * (2 ** min($attempt - 1, 6))); + + /** @var WorkflowTask $retry */ + $retry = WorkflowTask::query()->create([ + 'workflow_run_id' => $run->id, + 'namespace' => $run->namespace, + 'task_type' => TaskType::Workflow->value, + 'status' => TaskStatus::Ready->value, + 'available_at' => now() + ->addSeconds($delay), + 'payload' => WorkflowTaskPayload::forExternalSignal($sequence, $attempt), + 'connection' => $run->connection, + 'queue' => $run->queue, + 'compatibility' => $run->compatibility, + ]); + + TaskDispatcher::dispatch($retry); + $this->projectRun( + $run->fresh(['instance', 'tasks', 'activityExecutions', 'timers', 'failures', 'historyEvents']) ); } diff --git a/src/V2/Support/WorkflowFiberRunner.php b/src/V2/Support/WorkflowFiberRunner.php index 20e5847d9..306fa3377 100644 --- a/src/V2/Support/WorkflowFiberRunner.php +++ b/src/V2/Support/WorkflowFiberRunner.php @@ -580,28 +580,36 @@ private function nextObservableStep(): WorkflowStep } if ($current instanceof SignalExternalWorkflowCall) { - // Replay returns the recorded outcome. A new delivery needs the - // embedded executor's transaction; this runner never sends one. + // Replay returns the recorded outcome and waits on a pending + // request. A new request needs the embedded executor's outbox; + // this runner never sends one. $historySequence = $this->historySequenceForCurrentPosition(); - $result = null; + $recorded = null; if ($historySequence !== null) { WorkflowStepHistory::assertCompatible( $this->workflow->run, $historySequence, WorkflowStepHistory::EXTERNAL_SIGNAL, ); - $result = ExternalSignalHistory::recordedResult($this->workflow->run, $historySequence, $current); + $recorded = ExternalSignalHistory::lookup($this->workflow->run, $historySequence, $current); } - if ($result === null) { + if ($recorded === null || $recorded['status'] === ExternalSignalHistory::NONE) { throw new UnsupportedWorkflowYieldException( 'Durable signal-external currently requires embedded native execution.' ); } + if ($recorded['status'] === ExternalSignalHistory::PENDING) { + $this->waitingForHistory = true; + + return WorkflowStep::waiting($current) + ->withPrependedCommands($immediateCommands); + } + ++$this->sequence; $this->sendToWorkflow( - $result, + $recorded['result'], RedriveReplayClock::recordedAt( ExternalSignalHistory::resolutionEvent($this->workflow->run, $historySequence), ), diff --git a/src/V2/Support/WorkflowTaskPayload.php b/src/V2/Support/WorkflowTaskPayload.php index d22f572b5..e883f22cc 100644 --- a/src/V2/Support/WorkflowTaskPayload.php +++ b/src/V2/Support/WorkflowTaskPayload.php @@ -98,6 +98,28 @@ public static function forActivityResolution(WorkflowHistoryEvent $event): array ], static fn (mixed $value): bool => $value !== null); } + /** + * The sender's turn for a durable signal-external outcome, or the delayed + * turn that re-attempts a pending delivery (.github#223). + * + * @return array + */ + public static function forExternalSignal(WorkflowHistoryEvent|int $source, int $deliveryAttempt = 0): array + { + $event = $source instanceof WorkflowHistoryEvent ? $source : null; + $payload = is_array($event?->payload) ? $event->payload : []; + $sequence = $event === null ? (int) $source : self::intValue($payload['sequence'] ?? null); + + return array_filter([ + 'workflow_wait_kind' => 'external_signal', + 'open_wait_id' => $sequence === null ? null : sprintf('external-signal:%d', $sequence), + 'resume_source_kind' => 'external_signal', + 'workflow_sequence' => $sequence, + 'workflow_event_type' => $event?->event_type?->value, + 'external_signal_delivery_attempt' => $deliveryAttempt > 0 ? $deliveryAttempt : null, + ], static fn (mixed $value): bool => $value !== null); + } + /** * @return array */ diff --git a/src/V2/Webhooks.php b/src/V2/Webhooks.php index 745ea87fd..a43ac91aa 100644 --- a/src/V2/Webhooks.php +++ b/src/V2/Webhooks.php @@ -935,8 +935,11 @@ private static function reservedRequestIdResponse(InvalidCommandRequestIdExcepti throw $exception; } + // The Server's body for the same refusal, plus Laravel's errors map. return response()->json([ 'reason' => $exception->reason(), + 'outcome' => $exception->outcome(), + 'accepted' => false, 'message' => $exception->getMessage(), 'errors' => $exception->validationErrors(), ], 422); diff --git a/src/V2/WorkflowStub.php b/src/V2/WorkflowStub.php index e5eb55e51..3fa0cdb22 100644 --- a/src/V2/WorkflowStub.php +++ b/src/V2/WorkflowStub.php @@ -1353,29 +1353,6 @@ public function repair(): CommandResult return $result; } - /** - * Admit one durable signal-external delivery from workflow code. - * - * The runtime calls this inside the sending workflow task's transaction, - * keyed on the target as `workflow-signal::`, so the - * sender's history and the target's admission commit or roll back - * together. Applications cannot use that key prefix themselves. - * - * @internal - * @param array $arguments - */ - public function attemptExternalWorkflowSignal(string $requestId, string $name, array $arguments): CommandResult - { - if (! ExternalSignalHistory::isReservedRequestId($requestId)) { - throw new LogicException('A durable signal-external delivery requires its reserved command key.'); - } - - $clone = $this->withRequestId($requestId); - $clone->externalSignalRequestId = $requestId; - - return $clone->attemptSignalWithArguments($name, $arguments); - } - public function attemptSignal(string $name, ...$arguments): CommandResult { return $this->attemptSignalWithArguments($name, $arguments); @@ -1804,6 +1781,31 @@ public function attemptArchive(?string $reason = null): CommandResult return new CommandResult($command); } + /** + * Admit one durable signal-external delivery from workflow code. + * + * The runtime's delivery calls this after the sender recorded its request, + * in the target's own transaction, keyed on the target as + * `workflow-signal::`. A repeated delivery returns + * the retained receipt. Applications cannot use that key prefix. + * + * Private: only the runtime's delivery reaches it, through a scoped + * closure, so no caller can admit a reserved key. + * + * @param array $arguments + */ + private function attemptExternalWorkflowSignal(string $requestId, string $name, array $arguments): CommandResult + { + if (! ExternalSignalHistory::isReservedRequestId($requestId)) { + throw new LogicException('A durable signal-external delivery requires its reserved command key.'); + } + + $clone = $this->withRequestId($requestId); + $clone->externalSignalRequestId = $requestId; + + return $clone->attemptSignalWithArguments($name, $arguments); + } + private function admitOrdinaryStart( WorkflowMetadata $metadata, StartOptions $options, diff --git a/tests/Feature/V2/V2SignalExternalConcurrencyTest.php b/tests/Feature/V2/V2SignalExternalConcurrencyTest.php new file mode 100644 index 000000000..c162ebcc2 --- /dev/null +++ b/tests/Feature/V2/V2SignalExternalConcurrencyTest.php @@ -0,0 +1,477 @@ +flag = sys_get_temp_dir() . '/signal-external-flag-' . getmypid(); + @unlink($this->flag); + } + + protected function tearDown(): void + { + @unlink($this->flag); + parent::tearDown(); + } + + public function testMutualSignallingDeliversBothWaysWithoutFailingEitherRun(): void + { + $this->requiresConcurrentDatabase(); + + for ($round = 0; $round < 3; $round++) { + $a = 'sx-mutual-a-' . $round; + $b = 'sx-mutual-b-' . $round; + touch($this->flag); + WorkflowStub::make(TestSignalExternalPingWorkflow::class, $a)->start($b, 'ping', $this->flag, 400, true); + WorkflowStub::make(TestSignalExternalPingWorkflow::class, $b)->start($a, 'ping', $this->flag, 400, true); + $taskA = $this->readyTask($a); + $taskB = $this->readyTask($b); + $at = microtime(true) + 0.5; + $child = $this->fork(fn (): array => $this->runTaskAt($taskB, $at), "mutual-{$round}"); + $parent = $this->runTaskAt($taskA, $at); + $childResult = $this->join($child); + @unlink($this->flag); + + $this->assertTrue($parent['ok'], json_encode($parent)); + $this->assertTrue($childResult['ok'] ?? false, json_encode($childResult)); + $this->recover([$a, $b]); + + foreach ([[$a, $b], [$b, $a]] as [$self, $peer]) { + $this->assertCompletedWithoutFailure($self); + $output = WorkflowStub::load($self)->output(); + $this->assertSame('delivered', $output['sent']['outcome'], $self); + $this->assertSame($peer, $output['got'], $self); + $this->assertSingleRequestAndOutcome($self, 'ExternalSignalDelivered'); + } + } + } + + public function testLockWaitTimeoutOnTheTargetIsRetriedNotFatal(): void + { + $this->requiresConcurrentDatabase(); + $driver = DB::connection()->getDriverName(); + + WorkflowStub::make(TestSignalExternalTargetWorkflow::class, 'sx-lock-b')->start(); + $this->drain(); + WorkflowStub::make(TestSignalExternalPingWorkflow::class, 'sx-lock-a')->start( + 'sx-lock-b', + 'approve', + '', + 0, + false + ); + $taskA = $this->readyTask('sx-lock-a'); + $targetRun = WorkflowStub::load('sx-lock-b')->runId(); + + $pdo = $this->rawPdo(); + $pdo->beginTransaction(); + $table = (new WorkflowRun())->getTable(); + $pdo->query("SELECT id FROM {$table} WHERE id = " . $pdo->quote($targetRun) . ' FOR UPDATE')->fetchAll(); + DB::statement($driver === 'mysql' ? 'SET SESSION innodb_lock_wait_timeout = 1' : "SET lock_timeout = '1s'"); + + try { + $result = $this->runTaskAt($taskA, microtime(true)); + } finally { + $pdo->rollBack(); + DB::statement($driver === 'mysql' ? 'SET SESSION innodb_lock_wait_timeout = 50' : 'SET lock_timeout = 0'); + } + + // The sender's task committed its request; delivery is still pending. + $this->assertTrue($result['ok'], json_encode($result)); + $this->assertSame(['ExternalSignalRequested'], $this->externalEvents('sx-lock-a')); + $this->assertFalse( + WorkflowRun::query()->findOrFail(WorkflowStub::load('sx-lock-a')->runId())->status->isTerminal() + ); + $this->assertSame(0, WorkflowSignal::query()->where('workflow_run_id', $targetRun)->count()); + + $this->recover(['sx-lock-a', 'sx-lock-b']); + + $this->assertCompletedWithoutFailure('sx-lock-a'); + $this->assertSame('delivered', WorkflowStub::load('sx-lock-a')->output()['sent']['outcome']); + $this->assertSingleRequestAndOutcome('sx-lock-a', 'ExternalSignalDelivered'); + $this->assertSame('sx-lock-a', WorkflowStub::load('sx-lock-b')->output()['approved']); + $this->assertSame(1, WorkflowSignal::query()->where('workflow_run_id', $targetRun)->count()); + } + + public function testTargetCreatedWhileTheSenderRunsIsFound(): void + { + $this->requiresConcurrentDatabase(); + + touch($this->flag); + WorkflowStub::make(TestSignalExternalPingWorkflow::class, 'sx-late-a')->start( + 'sx-late-b', + 'approve', + $this->flag, + 1500, + false + ); + $taskA = $this->readyTask('sx-late-a'); + $at = microtime(true) + 0.3; + $child = $this->fork(static function () use ($at): array { + time_sleep_until($at + 0.5); + WorkflowStub::make(TestSignalExternalTargetWorkflow::class, 'sx-late-b')->start(); + + return [ + 'ok' => true, + ]; + }, 'late'); + $result = $this->runTaskAt($taskA, $at); + $this->join($child); + @unlink($this->flag); + + $this->assertTrue($result['ok'], json_encode($result)); + $this->recover(['sx-late-a', 'sx-late-b']); + + $this->assertCompletedWithoutFailure('sx-late-a'); + $this->assertSame('delivered', WorkflowStub::load('sx-late-a')->output()['sent']['outcome']); + $this->assertSame('sx-late-a', WorkflowStub::load('sx-late-b')->output()['approved']); + } + + public function testTargetTaskFinishingDuringTheSendStillGetsItsSignal(): void + { + $this->requiresConcurrentDatabase(); + + WorkflowStub::make(TestSignalExternalTargetWorkflow::class, 'sx-stale-b')->start(); + $taskB = $this->readyTask('sx-stale-b'); + touch($this->flag); + WorkflowStub::make(TestSignalExternalPingWorkflow::class, 'sx-stale-a')->start( + 'sx-stale-b', + 'approve', + $this->flag, + 1500, + false + ); + $taskA = $this->readyTask('sx-stale-a'); + $at = microtime(true) + 0.3; + $child = $this->fork(function () use ($at, $taskB): array { + time_sleep_until($at + 0.5); + + return $this->runTaskAt($taskB, microtime(true)); + }, 'stale'); + $result = $this->runTaskAt($taskA, $at); + $childResult = $this->join($child); + @unlink($this->flag); + + $this->assertTrue($result['ok'], json_encode($result)); + $this->assertTrue($childResult['ok'] ?? false, json_encode($childResult)); + $this->drain(); + + $this->assertCompletedWithoutFailure('sx-stale-a'); + $this->assertSame('delivered', WorkflowStub::load('sx-stale-a')->output()['sent']['outcome']); + $this->assertCompletedWithoutFailure('sx-stale-b'); + $this->assertSame('sx-stale-a', WorkflowStub::load('sx-stale-b')->output()['approved']); + } + + public function testSignalWhileTheTargetClosesOrContinuesAsNew(): void + { + $this->requiresConcurrentDatabase(); + + foreach (['complete', 'continue'] as $mode) { + $a = 'sx-close-a-' . $mode; + $b = 'sx-close-b-' . $mode; + touch($this->flag); + WorkflowStub::make(TestSignalExternalSlowCloseWorkflow::class, $b)->start($this->flag, 1200, $mode); + $taskB = $this->readyTask($b); + WorkflowStub::make(TestSignalExternalPingWorkflow::class, $a)->start($b, 'ping', '', 0, false); + $taskA = $this->readyTask($a); + $at = microtime(true) + 0.3; + $child = $this->fork(fn (): array => $this->runTaskAt($taskB, $at), "close-{$mode}"); + $result = $this->runTaskAt($taskA, $at + 0.4); + $childResult = $this->join($child); + @unlink($this->flag); + + $this->assertTrue($result['ok'], json_encode($result)); + // MySQL can choose the target's own closing task as a deadlock + // victim against the signal's admission, as it can for any signal + // racing a continue-as-new; that task is retried below. The + // sender is never the casualty. + $this->assertTrue( + ($childResult['ok'] ?? false) || str_contains((string) ($childResult['error'] ?? ''), 'Deadlock'), + json_encode($childResult), + ); + $this->recover([$a, $b]); + + $this->assertCompletedWithoutFailure($a); + $sent = WorkflowStub::load($a)->output()['sent']; + + if ($mode === 'continue') { + // Instance-targeted: the signal reaches the continued run. + $this->assertSame('delivered', $sent['outcome']); + $this->assertSame([ + 'generation' => 1, + 'got' => $a, + ], WorkflowStub::load($b)->output()); + $this->assertSingleRequestAndOutcome($a, 'ExternalSignalDelivered'); + } else { + $this->assertContains($sent['outcome'], ['target_closed', 'delivered']); + if ($sent['outcome'] === 'target_closed') { + $this->assertSame('run_not_active', $sent['reason']); + } + $this->assertCount(2, $this->externalEvents($a)); + } + } + } + + public function testCrashBetweenTheSendersCommitAndDeliveryIsRecovered(): void + { + $this->requiresConcurrentDatabase(); + + WorkflowStub::make(TestSignalExternalTargetWorkflow::class, 'sx-crash-b')->start(); + $this->drain(); + WorkflowStub::make(TestSignalExternalPingWorkflow::class, 'sx-crash-a')->start( + 'sx-crash-b', + 'approve', + '', + 0, + false + ); + $taskA = $this->readyTask('sx-crash-a'); + $targetRun = WorkflowStub::load('sx-crash-b')->runId(); + + // The worker process dies right after the sender's task commits, + // before its post-commit delivery runs. + $child = $this->fork(function () use ($taskA): array { + Event::listen(QueryExecuted::class, static function (QueryExecuted $query): void { + if (str_contains($query->sql, 'insert') + && in_array(HistoryEventType::ExternalSignalRequested->value, $query->bindings, true)) { + DB::afterCommit(static fn () => posix_kill(posix_getpid(), SIGKILL)); + } + }); + + return $this->runTaskAt($taskA, microtime(true)); + }, 'crash'); + $this->assertSame([ + 'missing_child_result' => true, + ], $this->join($child)); + + $this->assertSame(['ExternalSignalRequested'], $this->externalEvents('sx-crash-a')); + $this->assertSame(0, WorkflowSignal::query()->where('workflow_run_id', $targetRun)->count()); + + $this->recover(['sx-crash-a', 'sx-crash-b']); + + $this->assertCompletedWithoutFailure('sx-crash-a'); + $this->assertSame('delivered', WorkflowStub::load('sx-crash-a')->output()['sent']['outcome']); + $this->assertSingleRequestAndOutcome('sx-crash-a', 'ExternalSignalDelivered'); + $this->assertSame(1, WorkflowSignal::query()->where('workflow_run_id', $targetRun)->count()); + $this->assertSame('sx-crash-a', WorkflowStub::load('sx-crash-b')->output()['approved']); + } + + private function requiresConcurrentDatabase(): void + { + if (! in_array(DB::connection()->getDriverName(), ['mysql', 'pgsql'], true) + || ! function_exists('pcntl_fork')) { + $this->markTestSkipped('Concurrent signal-external cases need MySQL or PostgreSQL and pcntl.'); + } + } + + private function assertCompletedWithoutFailure(string $instanceId): void + { + $run = WorkflowRun::query()->findOrFail(WorkflowStub::load($instanceId)->runId()); + $this->assertSame(RunStatus::Completed, $run->status, $instanceId); + $this->assertSame(0, WorkflowFailure::query()->where('workflow_run_id', $run->id)->count(), $instanceId); + } + + private function assertSingleRequestAndOutcome(string $instanceId, string $outcomeEvent): void + { + $this->assertSame(['ExternalSignalRequested', $outcomeEvent], $this->externalEvents($instanceId)); + } + + /** + * @return list + */ + private function externalEvents(string $instanceId): array + { + $runIds = WorkflowRun::query()->where('workflow_instance_id', $instanceId)->pluck('id')->all(); + + return WorkflowHistoryEvent::query() + ->whereIn('workflow_run_id', $runIds) + ->whereIn('event_type', [ + HistoryEventType::ExternalSignalRequested->value, + HistoryEventType::ExternalSignalDelivered->value, + HistoryEventType::ExternalSignalFailed->value, + ]) + ->orderBy('sequence') + ->get() + ->map(static fn (WorkflowHistoryEvent $event): string => $event->event_type->value) + ->all(); + } + + private function rawPdo(): PDO + { + $config = DB::connection()->getConfig(); + $dsn = DB::connection()->getDriverName() === 'mysql' + ? "mysql:host={$config['host']};port={$config['port']};dbname={$config['database']}" + : "pgsql:host={$config['host']};port={$config['port']};dbname={$config['database']}"; + + return new PDO($dsn, $config['username'], $config['password'], [ + PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, + ]); + } + + private function readyTask(string $instanceId): string + { + $runId = WorkflowStub::load($instanceId)->runId(); + + return WorkflowTask::query() + ->where('workflow_run_id', $runId) + ->where('status', TaskStatus::Ready->value) + ->where('task_type', TaskType::Workflow->value) + ->sole() + ->id; + } + + /** + * @return array{ok: bool, error?: string} + */ + private function runTaskAt(string $taskId, float $at): array + { + if ($at > microtime(true)) { + time_sleep_until($at); + } + + try { + $this->app->call([new RunWorkflowTask($taskId), 'handle']); + + return [ + 'ok' => true, + ]; + } catch (\Throwable $throwable) { + return [ + 'ok' => false, + 'error' => $throwable::class . ': ' . substr($throwable->getMessage(), 0, 300), + ]; + } + } + + /** + * @return array{0: int, 1: string} + */ + private function fork(callable $operation, string $tag): array + { + $file = sys_get_temp_dir() . "/signal-external-child-{$tag}-" . getmypid() . '.json'; + @unlink($file); + DB::disconnect(); + $pid = pcntl_fork(); + + if ($pid === 0) { + DB::reconnect(); + try { + $result = $operation(); + } catch (\Throwable $throwable) { + $result = [ + 'ok' => false, + 'error' => $throwable::class . ': ' . $throwable->getMessage(), + ]; + } + file_put_contents($file, json_encode($result)); + DB::disconnect(); + posix_kill(posix_getpid(), SIGKILL); + } + + DB::reconnect(); + + return [$pid, $file]; + } + + private function join(array $child): mixed + { + pcntl_waitpid($child[0], $status); + $result = is_file($child[1]) + ? json_decode((string) file_get_contents($child[1]), true) + : [ + 'missing_child_result' => true, + ]; + @unlink($child[1]); + + return $result; + } + + /** + * Run due tasks and watchdog passes, moving time past every delayed + * delivery retry. + * + * @param list $instances + */ + private function recover(array $instances): void + { + for ($pass = 0; $pass < 6; $pass++) { + $this->drain(); + $this->travel(2) + ->minutes(); + $runIds = WorkflowRun::query()->whereIn('workflow_instance_id', $instances)->pluck('id')->all(); + TaskWatchdog::runPass(respectThrottle: false, runIds: $runIds); + } + + $this->drain(); + } + + private function drain(): void + { + $deadline = microtime(true) + 60; + + while (microtime(true) < $deadline) { + /** @var WorkflowTask|null $task */ + // Due tasks only: a delayed delivery retry waits for its time. + $task = WorkflowTask::query() + ->where('status', TaskStatus::Ready->value) + ->orderBy('available_at') + ->orderBy('created_at') + ->get() + ->first(static fn (WorkflowTask $ready): bool => $ready->available_at === null + || ! $ready->available_at->isFuture()); + + if ($task === null) { + return; + } + + $job = match ($task->task_type) { + TaskType::Workflow => new RunWorkflowTask($task->id), + TaskType::Activity => new RunActivityTask($task->id), + TaskType::Timer => new RunTimerTask($task->id), + }; + + $this->app->call([$job, 'handle']); + } + + $this->fail('Timed out draining ready workflow tasks.'); + } +} diff --git a/tests/Feature/V2/V2SignalExternalWorkflowTest.php b/tests/Feature/V2/V2SignalExternalWorkflowTest.php index d4a4dd7d7..b965af11d 100644 --- a/tests/Feature/V2/V2SignalExternalWorkflowTest.php +++ b/tests/Feature/V2/V2SignalExternalWorkflowTest.php @@ -7,10 +7,12 @@ use Illuminate\Support\Facades\DB; use Illuminate\Support\Facades\Queue; use Tests\Fixtures\V2\TestSignalExternalChildHandleWorkflow; +use Tests\Fixtures\V2\TestSignalExternalCleanupWorkflow; use Tests\Fixtures\V2\TestSignalExternalInvalidNameWorkflow; use Tests\Fixtures\V2\TestSignalExternalSenderWorkflow; use Tests\Fixtures\V2\TestSignalExternalTargetWorkflow; use Tests\TestCase; +use Workflow\Serializers\Serializer; use Workflow\V2\Contracts\WorkflowControlPlane; use Workflow\V2\Enums\CommandStatus; use Workflow\V2\Enums\CommandType; @@ -31,6 +33,7 @@ use Workflow\V2\StartOptions; use Workflow\V2\Support\QueryStateReplayer; use Workflow\V2\Support\WorkflowReplayer; +use Workflow\V2\Webhooks; use Workflow\V2\WorkflowStub; /** @@ -138,10 +141,12 @@ public function testRolledBackSenderTaskSendsNothingAndItsRetryDeliversOnce(): v ->sole(); // The sender's task runs completely, then its transaction is lost. + // Delivery waits for the sender's commit, so nothing reached the target. DB::beginTransaction(); try { $this->app->call([new RunWorkflowTask($task->id), 'handle']); - $this->assertSame(1, WorkflowSignal::query()->where('workflow_run_id', $target->runId())->count()); + $this->assertSame(1, $this->eventCount($sender->runId(), HistoryEventType::ExternalSignalRequested)); + $this->assertSame(0, WorkflowSignal::query()->where('workflow_run_id', $target->runId())->count()); } finally { DB::rollBack(); } @@ -340,6 +345,63 @@ public function testCallersCannotUseTheReservedRequestIdPrefix(): void ->accepted()); } + public function testCleanupAfterACancellationRequestCannotSignalAnotherWorkflow(): void + { + $target = $this->startTarget('sx-cleanup-target'); + $sender = WorkflowStub::make(TestSignalExternalCleanupWorkflow::class, 'sx-cleanup-sender'); + $sender->start('sx-cleanup-target'); + $this->drainReadyTasks(); + + $this->assertTrue($sender->requestCancellation('stop', 30)->accepted()); + $this->drainReadyTasks(); + + $this->assertTrue($sender->refresh()->cancelled()); + $this->assertSame(0, $this->eventCount($sender->runId(), HistoryEventType::ExternalSignalRequested)); + $this->assertSame( + 'cancellation_cleanup_command_not_available', + Serializer::unserializeWithCodec( + 'avro', + $this->event($sender->runId(), HistoryEventType::SideEffectRecorded)->payload['result'], + ), + ); + $this->assertSame(0, WorkflowSignal::query()->where('workflow_run_id', $target->runId())->count()); + } + + public function testReservedPrefixRefusalsCarryTheServerBody(): void + { + $this->startTarget('sx-body-target'); + $message = 'The request_id prefix [workflow-signal:] is reserved for signals sent by workflow code.'; + + $controlPlane = $this->app->make(WorkflowControlPlane::class)->signal('sx-body-target', 'approve', [ + 'request_id' => 'workflow-signal:run:9', + 'arguments' => ['forged'], + ]); + $this->assertSame('request_id_reserved', $controlPlane['reason']); + $this->assertSame('rejected_request_id_reserved', $controlPlane['outcome']); + $this->assertFalse($controlPlane['accepted']); + $this->assertSame($message, $controlPlane['message']); + + config([ + 'workflows.webhook_auth.method' => 'none', + ]); + Webhooks::routes([TestSignalExternalTargetWorkflow::class]); + + $this->withHeader('X-Request-Id', 'workflow-signal:run:10') + ->postJson('/webhooks/instances/sx-body-target/signals/approve', [ + 'arguments' => ['forged'], + ]) + ->assertStatus(422) + ->assertJsonPath('reason', 'request_id_reserved') + ->assertJsonPath('outcome', 'rejected_request_id_reserved') + ->assertJsonPath('accepted', false) + ->assertJsonPath('message', $message); + + $this->assertSame(0, WorkflowCommand::query() + ->where('workflow_instance_id', 'sx-body-target') + ->where('command_type', CommandType::Signal->value) + ->count()); + } + private function startTarget(string $id): WorkflowStub { $target = WorkflowStub::make(TestSignalExternalTargetWorkflow::class, $id); @@ -394,12 +456,16 @@ private function drainReadyTasks(): void while (microtime(true) < $deadline) { /** @var WorkflowTask|null $task */ + // Due tasks only: a delayed delivery retry waits for its time. $task = WorkflowTask::query() ->where('status', TaskStatus::Ready->value) + ->orderBy('available_at') ->orderBy('created_at') - ->first(); + ->get() + ->first(static fn (WorkflowTask $ready): bool => $ready->available_at === null + || ! $ready->available_at->isFuture()); - if ($task === null || ($task->available_at !== null && $task->available_at->isFuture())) { + if ($task === null) { return; } diff --git a/tests/Fixtures/V2/ReplayRegression/signal-external-outcome-without-request.json b/tests/Fixtures/V2/ReplayRegression/signal-external-outcome-without-request.json new file mode 100644 index 000000000..87866e97d --- /dev/null +++ b/tests/Fixtures/V2/ReplayRegression/signal-external-outcome-without-request.json @@ -0,0 +1,57 @@ +{ + "$schema": "https://raw.githubusercontent.com/durable-workflow/.github/main/regression-corpus/evidence-schema.json", + "fixture_schema": "durable-workflow.replay-regression/v1", + "id": "signal-external-outcome-without-request", + "protocol_version": "1.20", + "bindings": [ + "php" + ], + "consumers": [ + "workflow-fiber-runner", + "query-state-replayer", + "workflow-executor" + ], + "workflow": { + "type": "Tests\\Fixtures\\V2\\TestSignalExternalSenderWorkflow", + "arguments": [ + [ + { + "workflow_id": "order-42", + "signal": "approve", + "arguments": [ + "Ada" + ] + } + ] + ], + "payload_codec": "avro" + }, + "history": [ + { + "sequence": 1, + "event_type": "WorkflowStarted", + "payload": {}, + "recorded_at": "2026-11-19T12:00:00Z" + }, + { + "sequence": 2, + "event_type": "ExternalSignalDelivered", + "payload": { + "sequence": 1, + "target_workflow_instance_id": "order-42", + "target_workflow_run_id": "01j00000000000000000000t01", + "signal_name": "approve", + "request_id": "workflow-signal:01j00000000000000000000s01:1", + "outcome": "delivered", + "target_command_id": "01j00000000000000000000c01", + "target_signal_id": "01j00000000000000000000g01", + "retained": false + }, + "recorded_at": "2026-11-19T12:00:01Z" + } + ], + "expected_failure": { + "type": "workflow_history_shape_mismatch", + "exception": "Workflow\\V2\\Exceptions\\HistoryEventShapeMismatchException" + } +} diff --git a/tests/Fixtures/V2/ReplayRegression/signal-external-request-without-outcome.json b/tests/Fixtures/V2/ReplayRegression/signal-external-pending-request-waits.json similarity index 79% rename from tests/Fixtures/V2/ReplayRegression/signal-external-request-without-outcome.json rename to tests/Fixtures/V2/ReplayRegression/signal-external-pending-request-waits.json index 8805158a4..fca3fce72 100644 --- a/tests/Fixtures/V2/ReplayRegression/signal-external-request-without-outcome.json +++ b/tests/Fixtures/V2/ReplayRegression/signal-external-pending-request-waits.json @@ -1,16 +1,11 @@ { "$schema": "https://raw.githubusercontent.com/durable-workflow/.github/main/regression-corpus/evidence-schema.json", "fixture_schema": "durable-workflow.replay-regression/v1", - "id": "signal-external-request-without-outcome", + "id": "signal-external-pending-request-waits", "protocol_version": "1.20", "bindings": [ "php" ], - "consumers": [ - "workflow-fiber-runner", - "query-state-replayer", - "workflow-executor" - ], "workflow": { "type": "Tests\\Fixtures\\V2\\TestSignalExternalSenderWorkflow", "arguments": [ @@ -51,8 +46,9 @@ "recorded_at": "2026-11-19T12:00:01Z" } ], - "expected_failure": { - "type": "workflow_history_shape_mismatch", - "exception": "Workflow\\V2\\Exceptions\\HistoryEventShapeMismatchException" + "expected": { + "completed": false, + "result": null, + "commands": [] } } diff --git a/tests/Fixtures/V2/TestSignalExternalCleanupWorkflow.php b/tests/Fixtures/V2/TestSignalExternalCleanupWorkflow.php new file mode 100644 index 000000000..e2f417e83 --- /dev/null +++ b/tests/Fixtures/V2/TestSignalExternalCleanupWorkflow.php @@ -0,0 +1,34 @@ +reason; + } + + sideEffect(static fn (): string => $reason); + } + } +} diff --git a/tests/Fixtures/V2/TestSignalExternalPingWorkflow.php b/tests/Fixtures/V2/TestSignalExternalPingWorkflow.php new file mode 100644 index 000000000..86249998f --- /dev/null +++ b/tests/Fixtures/V2/TestSignalExternalPingWorkflow.php @@ -0,0 +1,36 @@ +workflowId()], $runId)->toArray(); + $got = $awaitPing ? await('ping') : null; + + return [ + 'sent' => $sent, + 'got' => $got, + ]; + } +} diff --git a/tests/Fixtures/V2/TestSignalExternalSlowCloseWorkflow.php b/tests/Fixtures/V2/TestSignalExternalSlowCloseWorkflow.php new file mode 100644 index 000000000..20ba0850d --- /dev/null +++ b/tests/Fixtures/V2/TestSignalExternalSlowCloseWorkflow.php @@ -0,0 +1,36 @@ + 0) { + return [ + 'generation' => $generation, + 'got' => await('ping'), + ]; + } + if ($flag !== '' && is_file($flag)) { + usleep($sleepMs * 1000); + } + if ($mode === 'continue') { + return continueAsNew($flag, $sleepMs, $mode, $generation + 1); + } + + return [ + 'closed' => true, + ]; + } +} diff --git a/tests/Unit/V2/SignalExternalWorkflowCallTest.php b/tests/Unit/V2/SignalExternalWorkflowCallTest.php index 23c94467d..e58b41434 100644 --- a/tests/Unit/V2/SignalExternalWorkflowCallTest.php +++ b/tests/Unit/V2/SignalExternalWorkflowCallTest.php @@ -155,7 +155,6 @@ public function testMalformedResolutionHistoryIsRefused(): void $call = new SignalExternalWorkflowCall('order-42', 'approve', ['Ada', 2]); $histories = [ 'outcome without request' => [['ExternalSignalDelivered', $this->delivered()]], - 'request without outcome' => [['ExternalSignalRequested', $this->requested($call)]], 'two outcomes' => [ ['ExternalSignalRequested', $this->requested($call)], ['ExternalSignalDelivered', $this->delivered()], @@ -198,6 +197,24 @@ public function testMalformedResolutionHistoryIsRefused(): void } } + public function testRequestWithoutOutcomeIsPendingDelivery(): void + { + $call = new SignalExternalWorkflowCall('order-42', 'approve', ['Ada', 2]); + $run = $this->runWithHistory([['ExternalSignalRequested', $this->requested($call)]]); + + $this->assertSame([ + 'status' => ExternalSignalHistory::PENDING, + 'result' => null, + ], ExternalSignalHistory::lookup($run, 1, $call)); + $this->assertSame([1], array_keys(ExternalSignalHistory::pendingRequests($run))); + + $delivered = new SignalExternalWorkflowCall('order-42', 'approve', ['Ada', 2]); + $requested = ExternalSignalHistory::callFromRequest($run->historyEvents->first()); + $this->assertSame($delivered->arguments, $requested->arguments); + $this->assertSame('order-42', $requested->workflowId); + $this->assertNull($requested->runId); + } + /** * @return array */ From 273c64b218d141e00fd7c2cb9007f9b8163bfa50 Mon Sep 17 00:00:00 2001 From: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com> Date: Fri, 20 Nov 2026 02:02:06 +0000 Subject: [PATCH 4/4] Bound signal-external delivery failures and surface retries Re-review follow-ups for the delivery outbox: - Only deadlocks, lock wait timeouts and lost connections are transient and retried without limit. Other delivery errors count toward workflows.v2.external_signal.max_delivery_failures (default 10); at the limit the request is recorded as ExternalSignalFailed (rejected, delivery_failed) and the sender resumes. - One delayed task per pending request carries every re-attempt with its attempt and failure counts, instead of a new row per try. - The run summary reports wait_kind external_signal with liveness waiting_for_external_signal_delivery or external_signal_delivery_retrying, the attempt count, the last error and the next attempt time. - A sender terminated while a delivery is admitting its signal records no outcome and stays consistent; the target may still receive that signal, as with an HTTP signal at that moment. Documented and tested. - External PHP workers refuse a pending request instead of waiting on a delivery they cannot make, so a mixed fleet fails the task visibly. Tests cover the permanent path (MySQL, PostgreSQL, SQLite), the transient path (MySQL, PostgreSQL), the terminate race and the worker refusal. Co-Authored-By: Claude Opus 5.5 --- .github/feature-test-timings.json | 4 +- CHANGELOG.md | 14 +- docs/api-stability.md | 39 +++- src/V2/Support/ExternalSignalDelivery.php | 192 ++++++++++++++++- src/V2/Support/RunSummaryProjector.php | 70 +++++++ src/V2/Support/WorkflowExecutor.php | 54 ++--- src/V2/Support/WorkflowFiberRunner.php | 16 +- src/V2/Support/WorkflowTaskPayload.php | 31 ++- src/config/workflows.php | 12 ++ .../V2/V2SignalExternalWorkflowTest.php | 196 ++++++++++++++++++ ...signal-external-pending-request-waits.json | 54 ----- 11 files changed, 568 insertions(+), 114 deletions(-) delete mode 100644 tests/Fixtures/V2/ReplayRegression/signal-external-pending-request-waits.json diff --git a/.github/feature-test-timings.json b/.github/feature-test-timings.json index 0392fe6e3..f2fafae65 100644 --- a/.github/feature-test-timings.json +++ b/.github/feature-test-timings.json @@ -209,7 +209,7 @@ "tests/Feature/V2/V2ServiceResponseReplayTest.php": 4.111694, "tests/Feature/V2/V2SideEffectWorkflowTest.php": 21.707655, "tests/Feature/V2/V2SignalExternalConcurrencyTest.php": 38.4, - "tests/Feature/V2/V2SignalExternalWorkflowTest.php": 17.0, + "tests/Feature/V2/V2SignalExternalWorkflowTest.php": 26.0, "tests/Feature/V2/V2StableCompensationExampleTest.php": 25.160551, "tests/Feature/V2/V2StandaloneActivityHostTest.php": 20.738894, "tests/Feature/V2/V2StartNamespaceTest.php": 3.144255, @@ -469,7 +469,7 @@ "tests/Feature/V2/V2ServiceResponseReplayTest.php": 5.828296, "tests/Feature/V2/V2SideEffectWorkflowTest.php": 5.792351, "tests/Feature/V2/V2SignalExternalConcurrencyTest.php": 25.5, - "tests/Feature/V2/V2SignalExternalWorkflowTest.php": 14.3, + "tests/Feature/V2/V2SignalExternalWorkflowTest.php": 24.0, "tests/Feature/V2/V2StableCompensationExampleTest.php": 11.153563, "tests/Feature/V2/V2StandaloneActivityHostTest.php": 23.795291, "tests/Feature/V2/V2StartNamespaceTest.php": 2.658658, diff --git a/CHANGELOG.md b/CHANGELOG.md index 73412b348..223a74780 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,8 +14,13 @@ through `CommandContext::workflow()`, and appends one `ExternalSignalDelivered` or `ExternalSignalFailed` to the sender, which resumes in a new workflow task. Deadlocks, lock timeouts and lost - connections are retried and never fail the sender; a delayed sender task - re-attempts a pending delivery after a crash. Replay returns the recorded + connections are retried without limit and never fail the sender; one + delayed sender task re-attempts a pending delivery after a crash. Other + delivery errors stop after + `workflows.v2.external_signal.max_delivery_failures` (default 10) with + `ExternalSignalFailed` reason `delivery_failed`, and the run summary shows + `external_signal_delivery_retrying` with the attempt count and last error + meanwhile. Replay returns the recorded outcome and never sends again. A missing, closed or refusing target is a returned outcome (`target_not_found`, `target_closed` or `rejected`, with Server's reasons, including `self_target` and `runtime_reserved_signal`), @@ -24,7 +29,10 @@ recorded. During cleanup after a cancellation request the command throws `ExternalSignalRefusedException` (`cancellation_cleanup_command_not_available`), as on Server. The existing child-handle `signal()` still sends directly. - External PHP workers replay recorded outcomes but refuse new commands. No + External PHP workers replay recorded outcomes but refuse new and pending + requests, so only embedded workers deliver. A sender terminated while a + delivery is admitting its signal records no outcome; the target may still + receive that signal, as with an HTTP signal at that moment. No database migration. `docs/api-stability.md#durable-signal-external` explains why the API is experimental. diff --git a/docs/api-stability.md b/docs/api-stability.md index 22a102457..0ab566783 100644 --- a/docs/api-stability.md +++ b/docs/api-stability.md @@ -281,11 +281,14 @@ the contract it implements is not. The command, its history events, the `workflow-signal:` key and its outcomes follow the shipped Server 3.15.0 contract (`docs/contracts/signal-external-workflow.md` in the server repository) and the published Python, PHP SDK and Rust SDKs. The PHP authoring -names and result type have not shipped in any release, and the -worker-protocol runner (`WorkflowFiberRunner`, used by external PHP workers) -replays recorded requests and outcomes but refuses a new command with -`UnsupportedWorkflowYieldException`; embedded does not advertise -`signal_external_workflow`. +names and result type have not shipped in any release. + +Only embedded workers deliver. The worker-protocol runner +(`WorkflowFiberRunner`, used by external PHP workers) replays recorded +outcomes, but it refuses a new command, and a request still waiting for its +outcome, with `UnsupportedWorkflowYieldException`, so a mixed fleet fails that +workflow task visibly instead of waiting on a delivery it cannot make. Embedded +does not advertise `signal_external_workflow`. Delivery is an outbox, as on the Server and in Temporal: @@ -300,12 +303,26 @@ Delivery is an outbox, as on the Server and in Temporal: sequence, and gives the sender a workflow task. A repeated delivery returns the target's retained receipt (`retained: true`) instead of signalling twice. -- A deadlock, lock wait timeout or lost connection is retried, and never fails - the sender. While a request is pending, the sender keeps a delayed workflow - task that replays to the request and delivers it again, so a process that - dies between the sender's commit and the delivery is recovered by the - ordinary task repair. Only definitive answers (not found, closed, rejected) - are recorded as failures. +- While a request is pending, the sender keeps one delayed workflow task that + replays to the request and delivers it again, so a process that dies + between the sender's commit and the delivery is recovered by the ordinary + task repair. The same row carries every re-attempt; its delay doubles per + failed attempt, up to a minute. +- A deadlock, lock wait timeout or lost connection is transient: it is + retried without limit and never fails the sender. Any other delivery error + counts toward `workflows.v2.external_signal.max_delivery_failures` + (`DW_V2_EXTERNAL_SIGNAL_MAX_DELIVERY_FAILURES`, default 10). At that limit + the request is recorded as `ExternalSignalFailed` with outcome `rejected` + and the embedded-only reason `delivery_failed`, and the sender resumes. +- While delivery waits or retries, the run summary reports `wait_kind: + external_signal` with liveness `waiting_for_external_signal_delivery`, or + `external_signal_delivery_retrying` with the attempt count, the last error + and the next attempt time. +- A sender that is terminated or cancelled while its request is pending gains + no outcome event; its history ends with the request, like an activity + scheduled before termination. A delivery already admitting the signal at + that moment can still reach the target, as an HTTP signal sent at that + moment can: delivery to the target is at least once in that race. - While a run cleans up after a cancellation request, the command throws `ExternalSignalRefusedException` (`cancellation_cleanup_command_not_available`) in workflow code and records nothing, as the Server refuses every command diff --git a/src/V2/Support/ExternalSignalDelivery.php b/src/V2/Support/ExternalSignalDelivery.php index 6f0c9188d..ec89356b9 100644 --- a/src/V2/Support/ExternalSignalDelivery.php +++ b/src/V2/Support/ExternalSignalDelivery.php @@ -47,6 +47,14 @@ */ final class ExternalSignalDelivery { + /** + * The embedded-only reason for a request whose delivery kept failing with + * a non-transient error. + */ + public const DELIVERY_FAILED = 'delivery_failed'; + + public const DEFAULT_MAX_DELIVERY_FAILURES = 10; + private const INLINE_ATTEMPTS = 3; /** @@ -71,17 +79,186 @@ public static function deliverPending(string $senderRunId, int $sequence): bool try { return self::attempt($senderRunId, $sequence); } catch (Throwable $throwable) { - if (! self::transient($throwable) || $attempt >= self::INLINE_ATTEMPTS) { - if (! self::transient($throwable)) { - report($throwable); - } + $transient = self::transient($throwable); + if ($transient && $attempt < self::INLINE_ATTEMPTS) { + usleep($attempt * 50_000); + + continue; + } + + if (! $transient) { + report($throwable); + } + + try { + return self::recordFailedAttempt($senderRunId, $sequence, $throwable, $transient); + } catch (Throwable $recording) { + // The pending request and its delayed task stay as they were. + report($recording); return false; } + } + } + } + + /** + * The most non-transient delivery failures before the request is + * recorded as `ExternalSignalFailed` with reason `delivery_failed`. + */ + public static function maxDeliveryFailures(): int + { + $configured = config('workflows.v2.external_signal.max_delivery_failures', self::DEFAULT_MAX_DELIVERY_FAILURES); + + return is_numeric($configured) ? max(1, (int) $configured) : self::DEFAULT_MAX_DELIVERY_FAILURES; + } + + /** + * The delay before the delayed task re-attempts a pending delivery after + * this many failed attempts: the repair interval, doubling, at most a minute. + */ + public static function retryDelaySeconds(int $failedAttempts): int + { + return min(60, TaskRepairPolicy::redispatchAfterSeconds() * (2 ** min(max(0, $failedAttempts), 6))); + } + + /** + * The request's delayed delivery task, if one is open. + */ + public static function deliveryTask(WorkflowRun $sender, int $sequence, bool $lock = false): ?WorkflowTask + { + $query = ConfiguredV2Models::query('task_model', WorkflowTask::class) + ->where('workflow_run_id', $sender->id) + ->where('task_type', TaskType::Workflow->value) + ->where('status', TaskStatus::Ready->value) + ->orderBy('created_at'); + + if ($lock) { + $query->lockForUpdate(); + } + + /** @var WorkflowTask|null $task */ + $task = $query->get() + ->first(static fn (WorkflowTask $task): bool => self::isDeliveryTask($task, $sequence)); - usleep($attempt * 50_000); + return $task; + } + + public static function isDeliveryTask(WorkflowTask $task, int $sequence): bool + { + $payload = is_array($task->payload) ? $task->payload : []; + + return ($payload['workflow_wait_kind'] ?? null) === 'external_signal' + && ($payload['external_signal_delivery'] ?? false) === true + && ($payload['workflow_sequence'] ?? null) === $sequence; + } + + /** + * The one delayed task that re-attempts this pending delivery. + */ + public static function createDeliveryTask( + WorkflowRun $sender, + WorkflowHistoryEvent $request, + \Carbon\CarbonInterface $availableAt, + ): WorkflowTask { + /** @var WorkflowTask $task */ + $task = ConfiguredV2Models::query('task_model', WorkflowTask::class)->create([ + 'workflow_run_id' => $sender->id, + 'namespace' => $sender->namespace, + 'task_type' => TaskType::Workflow->value, + 'status' => TaskStatus::Ready->value, + 'available_at' => $availableAt, + 'payload' => WorkflowTaskPayload::forExternalSignalDelivery($request), + 'connection' => $sender->connection, + 'queue' => $sender->queue, + 'compatibility' => $sender->compatibility, + ]); + + return $task; + } + + /** + * Count one failed delivery attempt on the request's delayed task. A + * transient failure (deadlock, lock wait, lost connection) is retried + * without limit; after the configured number of other failures the + * request is recorded as failed with reason `delivery_failed` and the + * sender is woken, so a permanent error never retries forever. + */ + private static function recordFailedAttempt( + string $senderRunId, + int $sequence, + Throwable $failure, + bool $transient, + ): bool { + $wake = null; + + $resolved = SqliteTransaction::run(static function () use ( + $senderRunId, + $sequence, + $failure, + $transient, + &$wake, + ): bool { + /** @var WorkflowRun $locked */ + $locked = ConfiguredV2Models::query('run_model', WorkflowRun::class) + ->lockForUpdate() + ->findOrFail($senderRunId); + $locked->setRelation('historyEvents', $locked->historyEvents()->get()); + $request = ExternalSignalHistory::pendingRequests($locked)[$sequence] ?? null; + + if ($locked->status->isTerminal() || ! $request instanceof WorkflowHistoryEvent) { + return false; + } + + $task = self::deliveryTask($locked, $sequence, lock: true) + ?? self::createDeliveryTask($locked, $request, now()); + $payload = is_array($task->payload) ? $task->payload : []; + $attempts = (int) ($payload['external_signal_delivery_attempt'] ?? 0) + 1; + $failures = (int) ($payload['external_signal_delivery_failures'] ?? 0) + ($transient ? 0 : 1); + $error = substr($failure::class . ': ' . $failure->getMessage(), 0, 500); + $task->forceFill([ + 'payload' => [ + ...$payload, + 'external_signal_delivery_attempt' => $attempts, + 'external_signal_delivery_failures' => $failures, + 'external_signal_delivery_last_error' => $error, + 'external_signal_delivery_last_error_transient' => $transient, + ], + 'available_at' => now() + ->addSeconds(self::retryDelaySeconds($attempts)), + ])->save(); + + if ($failures >= self::maxDeliveryFailures()) { + $requested = is_array($request->payload) ? $request->payload : []; + $event = WorkflowHistoryEvent::record($locked, HistoryEventType::ExternalSignalFailed, [ + 'sequence' => $sequence, + 'target_workflow_instance_id' => $requested['target_workflow_instance_id'] ?? null, + 'target_workflow_run_id' => null, + 'signal_name' => $requested['signal_name'] ?? null, + 'request_id' => $requested['request_id'] ?? null, + 'outcome' => ExternalSignalOutcome::Rejected->value, + 'reason' => self::DELIVERY_FAILED, + 'message' => sprintf('Delivery failed %d times; the last error was: %s', $failures, $error), + 'target_command_id' => null, + ]); + $wake = self::wakeSender($locked, $event); } + + /** @var HistoryProjectionRole $projection */ + $projection = app(HistoryProjectionRole::class); + $projection->projectRun( + $locked->fresh(['instance', 'tasks', 'activityExecutions', 'timers', 'failures', 'historyEvents']) + ?? $locked + ); + + return $wake instanceof WorkflowTask; + }); + + if ($wake instanceof WorkflowTask) { + TaskDispatcher::dispatch($wake); } + + return $resolved; } private static function attempt(string $senderRunId, int $sequence): bool @@ -116,6 +293,11 @@ private static function attempt(string $senderRunId, int $sequence): bool ->findOrFail($senderRunId); $locked->setRelation('historyEvents', $locked->historyEvents()->get()); + // Termination may have closed the sender after the target admitted + // the signal. A closed history gains no events, so the request stays + // without an outcome, like an activity scheduled before termination; + // the target keeps the signal, as with an HTTP signal sent at that + // moment (at least once to the target). if ($locked->status->isTerminal()) { return false; } diff --git a/src/V2/Support/RunSummaryProjector.php b/src/V2/Support/RunSummaryProjector.php index 41f6ecb41..33a3654d0 100644 --- a/src/V2/Support/RunSummaryProjector.php +++ b/src/V2/Support/RunSummaryProjector.php @@ -289,6 +289,7 @@ public static function project(WorkflowRun $run): WorkflowRunSummary ? null : self::openSignalWait($signalWaits ??= SignalWaits::forRun($run)); + $delivery = self::externalSignalDelivery($nextTask); $waitKind = null; $waitReason = null; $waitStartedAt = null; @@ -361,6 +362,14 @@ public static function project(WorkflowRun $run): WorkflowRunSummary $openWaitId = $openSignalWait['id']; $resumeSourceKind = $openSignalWait['resume_source_kind']; $resumeSourceId = $openSignalWait['resume_source_id']; + } elseif ($delivery !== null && $nextTask !== null) { + $waitKind = 'external_signal'; + $waitReason = $delivery['reason']; + $waitStartedAt = $nextTask->created_at; + $waitDeadlineAt = $nextTask->available_at; + $openWaitId = $delivery['open_wait_id']; + $resumeSourceKind = 'workflow_task'; + $resumeSourceId = $nextTask->id; } elseif ($nextTask !== null && $nextTask->task_type === TaskType::Workflow) { $waitKind = 'workflow-task'; $waitReason = match (true) { @@ -1721,6 +1730,11 @@ private static function liveness( ]; } + $delivery = self::externalSignalDelivery($nextTask); + if ($delivery !== null) { + return [$delivery['liveness_state'], $delivery['reason']]; + } + if ($nextTask !== null) { return self::taskLiveness($nextTask, $run, 'Workflow'); } @@ -2596,6 +2610,62 @@ private static function taskLabelFor(WorkflowTask $task): string /** * @return array{0: string, 1: string} */ + /** + * A pending durable signal-external delivery waiting on its delayed task + * (.github#223): waiting for delivery, or retrying with an attempt count + * and the last error. A task needing ordinary repair keeps task liveness. + * + * @return array{liveness_state: string, reason: string, open_wait_id: string|null}|null + */ + private static function externalSignalDelivery(?WorkflowTask $task): ?array + { + if (! $task instanceof WorkflowTask + || $task->task_type !== TaskType::Workflow + || $task->status !== TaskStatus::Ready) { + return null; + } + + $payload = is_array($task->payload) ? $task->payload : []; + if (($payload['workflow_wait_kind'] ?? null) !== 'external_signal' + || ($payload['external_signal_delivery'] ?? false) !== true + || TaskRepairPolicy::readyTaskNeedsRedispatch($task) + || TaskRepairPolicy::dispatchFailed($task) + || TaskRepairPolicy::claimFailed($task)) { + return null; + } + + $signal = self::nonEmptyString($payload['signal_name'] ?? null) ?? 'signal'; + $target = self::nonEmptyString($payload['target_workflow_instance_id'] ?? null) ?? 'workflow'; + $attempts = is_int($payload['external_signal_delivery_attempt'] ?? null) + ? $payload['external_signal_delivery_attempt'] + : 0; + $openWaitId = self::nonEmptyString($payload['open_wait_id'] ?? null); + + if ($attempts === 0) { + return [ + 'liveness_state' => 'waiting_for_external_signal_delivery', + 'reason' => sprintf('Waiting to deliver signal %s to workflow %s.', $signal, $target), + 'open_wait_id' => $openWaitId, + ]; + } + + $error = self::nonEmptyString($payload['external_signal_delivery_last_error'] ?? null); + + return [ + 'liveness_state' => 'external_signal_delivery_retrying', + 'reason' => sprintf( + 'Retrying delivery of signal %s to workflow %s after %d failed attempt%s%s; next attempt at %s.', + $signal, + $target, + $attempts, + $attempts === 1 ? '' : 's', + $error === null ? '' : sprintf(' (last error: %s)', $error), + $task->available_at?->toJSON() ?? 'an unknown time', + ), + 'open_wait_id' => $openWaitId, + ]; + } + private static function taskLiveness(WorkflowTask $task, WorkflowRun $run, string $label): array { if (self::taskWaitingForCompatibleWorker($task, $run)) { diff --git a/src/V2/Support/WorkflowExecutor.php b/src/V2/Support/WorkflowExecutor.php index bfc0e69f6..0205ab9e2 100644 --- a/src/V2/Support/WorkflowExecutor.php +++ b/src/V2/Support/WorkflowExecutor.php @@ -1579,37 +1579,43 @@ private function recordExternalSignalRequest( } /** - * The recovery path for a request whose delivery did not finish: a - * delayed workflow task that replays to this request and delivers it - * again (delivery is idempotent). Its delay doubles per attempt, up to a - * minute. A delivered outcome makes the task due at once. + * The recovery path for a request whose delivery did not finish: one + * delayed workflow task per pending request that replays to it and + * delivers again (delivery is idempotent). The same row is reused for + * every re-attempt, keeping its attempt and failure counts; its delay + * doubles per failed attempt up to a minute. An outcome makes it due now. */ private function scheduleExternalSignalDeliveryRetry(WorkflowRun $run, WorkflowTask $task, int $sequence): void { - if (self::hasOpenWorkflowTask($run->id)) { + if (ExternalSignalDelivery::deliveryTask($run, $sequence) instanceof WorkflowTask) { return; } - $previous = ($task->payload['workflow_wait_kind'] ?? null) === 'external_signal' - && ($task->payload['workflow_sequence'] ?? null) === $sequence - ? (int) ($task->payload['external_signal_delivery_attempt'] ?? 0) - : 0; - $attempt = $previous + 1; - $delay = min(60, TaskRepairPolicy::redispatchAfterSeconds() * (2 ** min($attempt - 1, 6))); + if (ExternalSignalDelivery::isDeliveryTask($task, $sequence)) { + $attempts = (int) ($task->payload['external_signal_delivery_attempt'] ?? 0); + $task->forceFill([ + 'status' => TaskStatus::Ready, + 'available_at' => now() + ->addSeconds(ExternalSignalDelivery::retryDelaySeconds($attempts)), + 'leased_at' => null, + 'lease_owner' => null, + 'lease_expires_at' => null, + 'last_error' => null, + ])->save(); + $retry = $task; + } else { + $request = ExternalSignalHistory::pendingRequests($run)[$sequence] ?? null; + if (! $request instanceof WorkflowHistoryEvent) { + return; + } - /** @var WorkflowTask $retry */ - $retry = WorkflowTask::query()->create([ - 'workflow_run_id' => $run->id, - 'namespace' => $run->namespace, - 'task_type' => TaskType::Workflow->value, - 'status' => TaskStatus::Ready->value, - 'available_at' => now() - ->addSeconds($delay), - 'payload' => WorkflowTaskPayload::forExternalSignal($sequence, $attempt), - 'connection' => $run->connection, - 'queue' => $run->queue, - 'compatibility' => $run->compatibility, - ]); + $retry = ExternalSignalDelivery::createDeliveryTask( + $run, + $request, + now() + ->addSeconds(ExternalSignalDelivery::retryDelaySeconds(0)), + ); + } TaskDispatcher::dispatch($retry); $this->projectRun( diff --git a/src/V2/Support/WorkflowFiberRunner.php b/src/V2/Support/WorkflowFiberRunner.php index 306fa3377..c46172b0a 100644 --- a/src/V2/Support/WorkflowFiberRunner.php +++ b/src/V2/Support/WorkflowFiberRunner.php @@ -580,9 +580,8 @@ private function nextObservableStep(): WorkflowStep } if ($current instanceof SignalExternalWorkflowCall) { - // Replay returns the recorded outcome and waits on a pending - // request. A new request needs the embedded executor's outbox; - // this runner never sends one. + // Replay returns the recorded outcome. A new or pending request + // needs the embedded executor's outbox; this runner never sends. $historySequence = $this->historySequenceForCurrentPosition(); $recorded = null; if ($historySequence !== null) { @@ -601,10 +600,13 @@ private function nextObservableStep(): WorkflowStep } if ($recorded['status'] === ExternalSignalHistory::PENDING) { - $this->waitingForHistory = true; - - return WorkflowStep::waiting($current) - ->withPrependedCommands($immediateCommands); + // Only the embedded executor delivers a pending request. + // Refuse rather than wait, so a mixed fleet never stalls on + // a delivery this worker cannot make. + throw new UnsupportedWorkflowYieldException( + 'A pending durable signal-external delivery needs an embedded worker; ' + . 'external PHP workers replay recorded outcomes but do not deliver.' + ); } ++$this->sequence; diff --git a/src/V2/Support/WorkflowTaskPayload.php b/src/V2/Support/WorkflowTaskPayload.php index e883f22cc..3ad7fe555 100644 --- a/src/V2/Support/WorkflowTaskPayload.php +++ b/src/V2/Support/WorkflowTaskPayload.php @@ -99,27 +99,42 @@ public static function forActivityResolution(WorkflowHistoryEvent $event): array } /** - * The sender's turn for a durable signal-external outcome, or the delayed - * turn that re-attempts a pending delivery (.github#223). + * The sender's turn after a durable signal-external outcome (.github#223). * * @return array */ - public static function forExternalSignal(WorkflowHistoryEvent|int $source, int $deliveryAttempt = 0): array + public static function forExternalSignal(WorkflowHistoryEvent $event): array { - $event = $source instanceof WorkflowHistoryEvent ? $source : null; - $payload = is_array($event?->payload) ? $event->payload : []; - $sequence = $event === null ? (int) $source : self::intValue($payload['sequence'] ?? null); + $payload = is_array($event->payload) ? $event->payload : []; + $sequence = self::intValue($payload['sequence'] ?? null); return array_filter([ 'workflow_wait_kind' => 'external_signal', 'open_wait_id' => $sequence === null ? null : sprintf('external-signal:%d', $sequence), 'resume_source_kind' => 'external_signal', 'workflow_sequence' => $sequence, - 'workflow_event_type' => $event?->event_type?->value, - 'external_signal_delivery_attempt' => $deliveryAttempt > 0 ? $deliveryAttempt : null, + 'workflow_event_type' => $event->event_type?->value, + 'signal_name' => self::nonEmptyString($payload['signal_name'] ?? null), + 'target_workflow_instance_id' => self::nonEmptyString($payload['target_workflow_instance_id'] ?? null), ], static fn (mixed $value): bool => $value !== null); } + /** + * The one delayed task that re-attempts a pending durable signal-external + * delivery. Its attempt and failure counts survive each re-attempt. + * + * @return array + */ + public static function forExternalSignalDelivery(WorkflowHistoryEvent $request): array + { + return [ + ...self::forExternalSignal($request), + 'external_signal_delivery' => true, + 'external_signal_delivery_attempt' => 0, + 'external_signal_delivery_failures' => 0, + ]; + } + /** * @return array */ diff --git a/src/config/workflows.php b/src/config/workflows.php index 3ac71c50d..fdf445308 100644 --- a/src/config/workflows.php +++ b/src/config/workflows.php @@ -453,6 +453,18 @@ ), ], + 'external_signal' => [ + // Durable signal-external delivery retries deadlocks, lock waits + // and lost connections without limit. After this many other + // (non-transient) failures, the request is recorded as + // ExternalSignalFailed with reason delivery_failed and the sender + // resumes, so a permanent error never retries forever. + 'max_delivery_failures' => (int) env( + 'DW_V2_EXTERNAL_SIGNAL_MAX_DELIVERY_FAILURES', + Workflow\V2\Support\ExternalSignalDelivery::DEFAULT_MAX_DELIVERY_FAILURES, + ), + ], + 'schedules' => [ // Keep the first audit event and the newest remaining events. // Explicit null disables compaction during a rolling upgrade; diff --git a/tests/Feature/V2/V2SignalExternalWorkflowTest.php b/tests/Feature/V2/V2SignalExternalWorkflowTest.php index b965af11d..d42186a0f 100644 --- a/tests/Feature/V2/V2SignalExternalWorkflowTest.php +++ b/tests/Feature/V2/V2SignalExternalWorkflowTest.php @@ -21,6 +21,7 @@ use Workflow\V2\Enums\TaskStatus; use Workflow\V2\Enums\TaskType; use Workflow\V2\Exceptions\InvalidCommandRequestIdException; +use Workflow\V2\Exceptions\UnsupportedWorkflowYieldException; use Workflow\V2\Jobs\RunActivityTask; use Workflow\V2\Jobs\RunTimerTask; use Workflow\V2\Jobs\RunWorkflowTask; @@ -28,10 +29,12 @@ use Workflow\V2\Models\WorkflowHistoryEvent; use Workflow\V2\Models\WorkflowInstance; use Workflow\V2\Models\WorkflowRun; +use Workflow\V2\Models\WorkflowRunSummary; use Workflow\V2\Models\WorkflowSignal; use Workflow\V2\Models\WorkflowTask; use Workflow\V2\StartOptions; use Workflow\V2\Support\QueryStateReplayer; +use Workflow\V2\Support\WorkflowFiberRunner; use Workflow\V2\Support\WorkflowReplayer; use Workflow\V2\Webhooks; use Workflow\V2\WorkflowStub; @@ -402,6 +405,199 @@ public function testReservedPrefixRefusalsCarryTheServerBody(): void ->count()); } + public function testPermanentDeliveryErrorIsRecordedAsDeliveryFailedAfterTheConfiguredAttempts(): void + { + config([ + 'workflows.v2.external_signal.max_delivery_failures' => 3, + ]); + $target = $this->startTarget('sx-poison-target'); + $this->failSignalInserts(transient: false); + + try { + $sender = WorkflowStub::make(TestSignalExternalSenderWorkflow::class, 'sx-poison-sender'); + $sender->start([[ + 'workflow_id' => 'sx-poison-target', + 'signal' => 'approve', + ]]); + $this->drainReadyTasks(); + $runId = $sender->runId(); + + // The first failure is surfaced on the run, not only in logs. + $summary = WorkflowRunSummary::query()->findOrFail($runId); + $this->assertSame('external_signal_delivery_retrying', $summary->liveness_state); + $this->assertSame('external_signal', $summary->wait_kind); + $this->assertStringContainsString('after 1 failed attempt', (string) $summary->liveness_reason); + $this->assertStringContainsString('sx-poison', (string) $summary->liveness_reason); + + for ($retry = 0; $retry < 5 && $sender->refresh()->running(); $retry++) { + $this->travel(61) + ->seconds(); + $this->drainReadyTasks(); + } + } finally { + $this->restoreSignalInserts(); + } + + $this->assertTrue($sender->refresh()->completed()); + $result = $sender->output()['results'][0]; + $this->assertSame('rejected', $result['outcome']); + $this->assertSame('delivery_failed', $result['reason']); + $this->assertStringContainsString('Delivery failed 3 times', (string) $result['message']); + $this->assertSame(1, $this->eventCount($runId, HistoryEventType::ExternalSignalFailed)); + $this->assertSame(0, WorkflowSignal::query()->where('workflow_run_id', $target->runId())->count()); + // One delayed task carried every re-attempt. + $this->assertSame(1, $this->deliveryTaskCount($runId)); + } + + public function testTransientDeliveryErrorsRetryWithoutLimitAndThenDeliverOnce(): void + { + if (! in_array(DB::connection()->getDriverName(), ['mysql', 'pgsql'], true)) { + $this->markTestSkipped('A transient-error trigger needs MySQL or PostgreSQL.'); + } + + config([ + 'workflows.v2.external_signal.max_delivery_failures' => 2, + ]); + $target = $this->startTarget('sx-transient-target'); + $this->failSignalInserts(transient: true); + + try { + $sender = WorkflowStub::make(TestSignalExternalSenderWorkflow::class, 'sx-transient-sender'); + $sender->start([[ + 'workflow_id' => 'sx-transient-target', + 'signal' => 'approve', + 'arguments' => ['eventually'], + ]]); + $this->drainReadyTasks(); + $runId = $sender->runId(); + + for ($retry = 0; $retry < 4; $retry++) { + $this->travel(61) + ->seconds(); + $this->drainReadyTasks(); + } + + // Past the non-transient limit, still pending: transient errors never give up. + $this->assertFalse($sender->refresh()->completed()); + $this->assertSame(0, $this->eventCount($runId, HistoryEventType::ExternalSignalFailed)); + $summary = WorkflowRunSummary::query()->findOrFail($runId); + $this->assertSame('external_signal_delivery_retrying', $summary->liveness_state); + $this->assertStringContainsString('after 5 failed attempts', (string) $summary->liveness_reason); + } finally { + $this->restoreSignalInserts(); + } + + $this->travel(61) + ->seconds(); + $this->drainReadyTasks(); + + $this->assertSame('delivered', $sender->refresh()->output()['results'][0]['outcome']); + $this->assertSame('eventually', $target->refresh()->output()['approved']); + $this->assertSame(1, WorkflowSignal::query()->where('workflow_run_id', $target->runId())->count()); + $this->assertSame(1, $this->deliveryTaskCount($runId)); + } + + public function testSenderTerminatedAfterTheTargetAdmittedTheSignalRecordsNothingMore(): void + { + $target = $this->startTarget('sx-terminate-target'); + $sender = WorkflowStub::make(TestSignalExternalSenderWorkflow::class, 'sx-terminate-sender'); + $sender->start([[ + 'workflow_id' => 'sx-terminate-target', + 'signal' => 'approve', + 'arguments' => ['raced'], + ]]); + + // Termination lands between the target's admission and the outcome append. + $signals = (new WorkflowSignal())->getTable(); + $terminated = false; + DB::listen(static function ($query) use ($signals, &$terminated): void { + if (! $terminated && str_starts_with(strtolower($query->sql), 'insert into') + && str_contains($query->sql, $signals)) { + $terminated = true; + DB::afterCommit(static fn () => WorkflowStub::load('sx-terminate-sender')->attemptTerminate('race')); + } + }); + $this->drainReadyTasks(); + + $this->assertTrue($terminated); + $this->assertTrue($sender->refresh()->terminated()); + $this->assertSame(1, $this->eventCount($sender->runId(), HistoryEventType::ExternalSignalRequested)); + $this->assertSame(0, $this->eventCount($sender->runId(), HistoryEventType::ExternalSignalDelivered)); + $this->assertSame(0, $this->eventCount($sender->runId(), HistoryEventType::ExternalSignalFailed)); + $this->assertSame(0, WorkflowTask::query() + ->where('workflow_run_id', $sender->runId()) + ->whereIn('status', [TaskStatus::Ready->value, TaskStatus::Leased->value]) + ->count()); + // At least once to the target, as for an HTTP signal sent at that moment. + $this->assertSame('raced', $target->refresh()->output()['approved']); + } + + public function testExternalWorkersRefuseAPendingDeliveryInsteadOfWaiting(): void + { + $history = json_decode((string) file_get_contents( + __DIR__ . '/../../Fixtures/V2/ReplayRegression/signal-external-delivered-cold-replay.json' + ), true, flags: JSON_THROW_ON_ERROR); + $requestOnly = array_slice($history['history'], 0, 2); + $this->assertSame('ExternalSignalRequested', $requestOnly[1]['event_type']); + + $this->expectException(UnsupportedWorkflowYieldException::class); + $this->expectExceptionMessage('needs an embedded worker'); + + WorkflowFiberRunner::forClass( + TestSignalExternalSenderWorkflow::class, + 'sx-external-worker', + 'sx-external-worker-run', + $history['workflow']['arguments'], + 'avro', + $requestOnly, + )->step(); + } + + private function deliveryTaskCount(string $runId): int + { + return WorkflowTask::query() + ->where('workflow_run_id', $runId) + ->get() + ->filter( + static fn (WorkflowTask $task): bool => ($task->payload['external_signal_delivery'] ?? false) === true + ) + ->count(); + } + + private function failSignalInserts(bool $transient): void + { + $table = (new WorkflowSignal())->getTable(); + + match (DB::connection()->getDriverName()) { + 'mysql', 'mariadb' => DB::unprepared(sprintf( + "CREATE TRIGGER sx_fail_signal BEFORE INSERT ON %s FOR EACH ROW SIGNAL SQLSTATE '%s' SET MESSAGE_TEXT = 'sx injected failure'", + $table, + $transient ? '40001' : '45000', + )), + 'pgsql' => DB::unprepared(sprintf( + "CREATE FUNCTION sx_fail_signal() RETURNS trigger AS \$\$ BEGIN RAISE EXCEPTION 'sx injected failure' USING ERRCODE = '%s'; END; \$\$ LANGUAGE plpgsql; CREATE TRIGGER sx_fail_signal BEFORE INSERT ON %s FOR EACH ROW EXECUTE FUNCTION sx_fail_signal();", + $transient ? '40001' : 'P0001', + $table, + )), + default => DB::unprepared(sprintf( + "CREATE TRIGGER sx_fail_signal BEFORE INSERT ON %s BEGIN SELECT RAISE(ABORT, 'sx injected failure'); END;", + $table, + )), + }; + } + + private function restoreSignalInserts(): void + { + $table = (new WorkflowSignal())->getTable(); + + match (DB::connection()->getDriverName()) { + 'pgsql' => DB::unprepared( + "DROP TRIGGER IF EXISTS sx_fail_signal ON {$table}; DROP FUNCTION IF EXISTS sx_fail_signal();" + ), + default => DB::unprepared('DROP TRIGGER IF EXISTS sx_fail_signal'), + }; + } + private function startTarget(string $id): WorkflowStub { $target = WorkflowStub::make(TestSignalExternalTargetWorkflow::class, $id); diff --git a/tests/Fixtures/V2/ReplayRegression/signal-external-pending-request-waits.json b/tests/Fixtures/V2/ReplayRegression/signal-external-pending-request-waits.json deleted file mode 100644 index fca3fce72..000000000 --- a/tests/Fixtures/V2/ReplayRegression/signal-external-pending-request-waits.json +++ /dev/null @@ -1,54 +0,0 @@ -{ - "$schema": "https://raw.githubusercontent.com/durable-workflow/.github/main/regression-corpus/evidence-schema.json", - "fixture_schema": "durable-workflow.replay-regression/v1", - "id": "signal-external-pending-request-waits", - "protocol_version": "1.20", - "bindings": [ - "php" - ], - "workflow": { - "type": "Tests\\Fixtures\\V2\\TestSignalExternalSenderWorkflow", - "arguments": [ - [ - { - "workflow_id": "order-42", - "signal": "approve", - "arguments": [ - "Ada" - ] - } - ] - ], - "payload_codec": "avro" - }, - "history": [ - { - "sequence": 1, - "event_type": "WorkflowStarted", - "payload": {}, - "recorded_at": "2026-11-19T12:00:00Z" - }, - { - "sequence": 2, - "event_type": "ExternalSignalRequested", - "payload": { - "sequence": 1, - "target_workflow_instance_id": "order-42", - "target_workflow_run_id": null, - "signal_name": "approve", - "arguments": { - "codec": "avro", - "blob": "wwHioz3/VYAiNwwCCgZBZGEA" - }, - "payload_codec": "avro", - "request_id": "workflow-signal:01j00000000000000000000s01:1" - }, - "recorded_at": "2026-11-19T12:00:01Z" - } - ], - "expected": { - "completed": false, - "result": null, - "commands": [] - } -}