Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/feature-test-timings.json
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down
45 changes: 45 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:<sender run>:<sequence>` 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.
Expand Down
83 changes: 83 additions & 0 deletions docs/api-stability.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:<sender run id>:<sequence>`
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
Expand Down Expand Up @@ -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` |
Expand Down
18 changes: 18 additions & 0 deletions src/V2/ChildWorkflowHandle.php
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@

namespace Workflow\V2;

use Workflow\V2\Support\SignalExternalWorkflowCall;

final class ChildWorkflowHandle
{
public function __construct(
Expand Down Expand Up @@ -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<int|string, mixed> $arguments
*/
Expand Down
19 changes: 19 additions & 0 deletions src/V2/Enums/ExternalSignalOutcome.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<?php

declare(strict_types=1);

namespace Workflow\V2\Enums;

/**
* The recorded outcome of a durable workflow-to-workflow signal.
*
* @experimental Durable signal-external may change in a minor release.
* See docs/api-stability.md#durable-signal-external.
*/
enum ExternalSignalOutcome: string
{
case Delivered = 'delivered';
case TargetNotFound = 'target_not_found';
case TargetClosed = 'target_closed';
case Rejected = 'rejected';
}
3 changes: 3 additions & 0 deletions src/V2/Enums/HistoryEventType.php
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,9 @@ enum HistoryEventType: string
case WorkflowContinuedAsNew = 'WorkflowContinuedAsNew';
case ChildWorkflowScheduled = 'ChildWorkflowScheduled';
case ChildWorkflowAwaited = 'ChildWorkflowAwaited';
case ExternalSignalRequested = 'ExternalSignalRequested';
case ExternalSignalDelivered = 'ExternalSignalDelivered';
case ExternalSignalFailed = 'ExternalSignalFailed';
case ChildCancellationRequested = 'ChildCancellationRequested';
case ChildCancellationResolved = 'ChildCancellationResolved';
case ChildRunStarted = 'ChildRunStarted';
Expand Down
36 changes: 36 additions & 0 deletions src/V2/Exceptions/ExternalSignalRefusedException.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
<?php

declare(strict_types=1);

namespace Workflow\V2\Exceptions;

use LogicException;

/**
* The runtime refused a durable signal-external command in workflow code,
* before anything was recorded or sent. While a run cleans up after a
* cancellation request, only activities, timers and side effects are
* available, as on the Server (`cancellation_cleanup_command_not_available`).
*
* @experimental Durable signal-external may change in a minor release.
* See docs/api-stability.md#durable-signal-external.
*/
final class ExternalSignalRefusedException extends LogicException
{
public const CANCELLATION_CLEANUP = 'cancellation_cleanup_command_not_available';

public function __construct(
public readonly string $reason,
string $message,
) {
parent::__construct($message);
}

public static function duringCancellationCleanup(): self
{
return new self(
self::CANCELLATION_CLEANUP,
'A durable signal-external command is not available while the run cleans up after a cancellation request.',
);
}
}
38 changes: 36 additions & 2 deletions src/V2/Exceptions/InvalidCommandRequestIdException.php
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,43 @@

final class InvalidCommandRequestIdException extends InvalidArgumentException
{
public function __construct()
public const REASON_INVALID = 'invalid_request_id';

public const REASON_RESERVED = 'request_id_reserved';

public function __construct(
string $message = 'The request ID must be a valid UTF-8 string containing 1 to 255 Unicode characters.',
private readonly string $reason = self::REASON_INVALID,
) {
parent::__construct($message);
}

/**
* A key under a prefix the runtime reserves for its own deliveries.
*/
public static function reserved(string $prefix): self
{
return new self(
sprintf('The request_id prefix [%s] is reserved for signals sent by workflow code.', $prefix),
self::REASON_RESERVED,
);
}

/**
* `invalid_request_id`, or `request_id_reserved` for a reserved prefix.
*/
public function reason(): string
{
return $this->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;
}

/**
Expand Down
25 changes: 25 additions & 0 deletions src/V2/Exceptions/InvalidExternalSignalException.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
<?php

declare(strict_types=1);

namespace Workflow\V2\Exceptions;

use InvalidArgumentException;

/**
* A durable signal-external request was refused in workflow code, before any
* history was recorded or anything was sent.
*
* @experimental Durable signal-external may change in a minor release.
* See docs/api-stability.md#durable-signal-external.
*/
final class InvalidExternalSignalException extends InvalidArgumentException
{
public function __construct(
public readonly string $reason,
public readonly string $field,
public readonly string $problem,
) {
parent::__construct(sprintf('Durable signal-external %s is invalid: %s.', $field, $problem));
}
}
Loading