diff --git a/.github/feature-test-timings.json b/.github/feature-test-timings.json index 9206108fb..f2fafae65 100644 --- a/.github/feature-test-timings.json +++ b/.github/feature-test-timings.json @@ -208,6 +208,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/V2SignalExternalConcurrencyTest.php": 38.4, + "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, @@ -466,6 +468,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/V2SignalExternalConcurrencyTest.php": 25.5, + "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 1bf593d88..36c8585c3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,51 @@ ## 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()`, 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 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`), + 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 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. + + **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 lost-lease schema check caches its result for 60 seconds by the framework clock instead of PHP's `time()`, so a frozen test clock holds the window and query-count tests no longer see an extra schema query on slow runs. diff --git a/docs/api-stability.md b/docs/api-stability.md index b8ea80035..0ab566783 100644 --- a/docs/api-stability.md +++ b/docs/api-stability.md @@ -264,6 +264,86 @@ 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. It is **experimental**: the +`Workflow\V2\signalExternalWorkflow()` function, the +`Workflow::signalExternalWorkflow()` facade method, +`ChildWorkflowHandle::signalDurably()`, `ExternalSignalResult`, +`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. + +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: + +- 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. +- 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 + 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. 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 +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 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 A class, interface, method, constant, or property is part of the public API @@ -943,6 +1023,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; + } + + /** + * The command outcome the Server reports for a reserved key + * (`rejected_request_id_reserved`); null for an invalid key. + */ + public function outcome(): ?string { - parent::__construct('The request ID must be a valid UTF-8 string containing 1 to 255 Unicode characters.'); + return $this->reason === self::REASON_RESERVED ? 'rejected_request_id_reserved' : null; } /** 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..d8388945f 100644 --- a/src/V2/Support/DefaultWorkflowControlPlane.php +++ b/src/V2/Support/DefaultWorkflowControlPlane.php @@ -1410,7 +1410,10 @@ private function invalidRequestIdResult(string $instanceId, InvalidCommandReques 'workflow_command_id' => null, 'command_id' => null, 'update_id' => null, - 'reason' => 'invalid_request_id', + '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 new file mode 100644 index 000000000..ec89356b9 --- /dev/null +++ b/src/V2/Support/ExternalSignalDelivery.php @@ -0,0 +1,570 @@ +:` 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 +{ + /** + * 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; + + /** + * 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) { + $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)); + + 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 + { + /** @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()); + + // 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; + } + + 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} + */ + private static function resolve(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) + ); + } + } + + $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} + */ + 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..e8d000a39 --- /dev/null +++ b/src/V2/Support/ExternalSignalHistory.php @@ -0,0 +1,334 @@ +:`. + * Callers cannot use the prefix (`request_id_reserved`). + */ + public const REQUEST_ID_PREFIX = 'workflow-signal:'; + + 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; + } + + public static function isReservedRequestId(mixed $requestId): bool + { + return is_string($requestId) && str_starts_with($requestId, self::REQUEST_ID_PREFIX); + } + + /** + * 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 lookup(WorkflowRun $run, int $sequence, SignalExternalWorkflowCall $call): array + { + $requested = self::events($run, $sequence, HistoryEventType::ExternalSignalRequested); + $resolutions = [ + ...self::events($run, $sequence, HistoryEventType::ExternalSignalDelivered), + ...self::events($run, $sequence, HistoryEventType::ExternalSignalFailed), + ]; + + if ($requested === [] && $resolutions === []) { + return [ + 'status' => self::NONE, + 'result' => 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 ($resolutions === []) { + return [ + 'status' => self::PENDING, + 'result' => null, + ]; + } + + if (count($resolutions) !== 1) { + 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 array_diff_key($pending, $resolved); + } + + /** + * 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..c5975fc76 100644 --- a/src/V2/Support/QueryStateReplayer.php +++ b/src/V2/Support/QueryStateReplayer.php @@ -439,6 +439,31 @@ 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; + // a pending request stops replay like a pending activity. + $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 +2229,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/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/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 44caf230f..0205ab9e2 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; @@ -691,6 +692,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( @@ -1477,6 +1483,146 @@ private function executeMemo( return WorkflowTaskStep::ContinueExecution; } + /** + * 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, + 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 { + $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); + } + } catch (Throwable $throwable) { + $this->failRun($run, $task, $throwable, 'workflow_run', $run->id); + return null; + } + + // 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 recordExternalSignalRequest( + 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); + } + + /** + * 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 (ExternalSignalDelivery::deliveryTask($run, $sequence) instanceof WorkflowTask) { + return; + } + + 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; + } + + $retry = ExternalSignalDelivery::createDeliveryTask( + $run, + $request, + now() + ->addSeconds(ExternalSignalDelivery::retryDelaySeconds(0)), + ); + } + + TaskDispatcher::dispatch($retry); + $this->projectRun( + $run->fresh(['instance', 'tasks', 'activityExecutions', 'timers', 'failures', 'historyEvents']) + ); + } + private function executeTimer( WorkflowRun $run, WorkflowTask $task, diff --git a/src/V2/Support/WorkflowFiberRunner.php b/src/V2/Support/WorkflowFiberRunner.php index 4deaa74e2..c46172b0a 100644 --- a/src/V2/Support/WorkflowFiberRunner.php +++ b/src/V2/Support/WorkflowFiberRunner.php @@ -579,6 +579,48 @@ private function nextObservableStep(): WorkflowStep continue; } + if ($current instanceof SignalExternalWorkflowCall) { + // 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) { + WorkflowStepHistory::assertCompatible( + $this->workflow->run, + $historySequence, + WorkflowStepHistory::EXTERNAL_SIGNAL, + ); + $recorded = ExternalSignalHistory::lookup($this->workflow->run, $historySequence, $current); + } + + if ($recorded === null || $recorded['status'] === ExternalSignalHistory::NONE) { + throw new UnsupportedWorkflowYieldException( + 'Durable signal-external currently requires embedded native execution.' + ); + } + + if ($recorded['status'] === ExternalSignalHistory::PENDING) { + // 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; + $this->sendToWorkflow( + $recorded['result'], + RedriveReplayClock::recordedAt( + ExternalSignalHistory::resolutionEvent($this->workflow->run, $historySequence), + ), + advanceCancellationTime: false, + ); + + continue; + } + if ($current instanceof UpsertMemoCall) { $historySequence = $this->historySequenceForCurrentPosition(); $recorded = $historySequence === null @@ -1671,6 +1713,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/Support/WorkflowTaskPayload.php b/src/V2/Support/WorkflowTaskPayload.php index d22f572b5..3ad7fe555 100644 --- a/src/V2/Support/WorkflowTaskPayload.php +++ b/src/V2/Support/WorkflowTaskPayload.php @@ -98,6 +98,43 @@ public static function forActivityResolution(WorkflowHistoryEvent $event): array ], static fn (mixed $value): bool => $value !== null); } + /** + * The sender's turn after a durable signal-external outcome (.github#223). + * + * @return array + */ + public static function forExternalSignal(WorkflowHistoryEvent $event): array + { + $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, + '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/V2/Webhooks.php b/src/V2/Webhooks.php index 444c4e0ce..a43ac91aa 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,27 @@ 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; + } + + // 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); + } + 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..3fa0cdb22 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, @@ -1773,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, @@ -4850,6 +4883,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/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/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 new file mode 100644 index 000000000..d42186a0f --- /dev/null +++ b/tests/Feature/V2/V2SignalExternalWorkflowTest.php @@ -0,0 +1,679 @@ +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. + // 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, $this->eventCount($sender->runId(), HistoryEventType::ExternalSignalRequested)); + $this->assertSame(0, 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()); + } + + 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()); + } + + 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); + $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 */ + // 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/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-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-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/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/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/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/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/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/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..e58b41434 --- /dev/null +++ b/tests/Unit/V2/SignalExternalWorkflowCallTest.php @@ -0,0 +1,281 @@ + + */ + 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()]], + '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); + } + } + } + + 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 + */ + 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; + } +}