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
21 changes: 21 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,27 @@ project follows [Semantic Versioning](https://semver.org/).
(durable-workflow/.github#216). Nothing was written and no receipt was
selected, so the refusal is never resent automatically.

### Fixed

- `WorkflowContext::signals()` returns only signals the Server has applied to
the run (a `SignalApplied` event, or a `SignalReceived` carrying the
`workflow_sequence` of the wait that consumed it), plus the signal the current
workflow task delivers. It previously returned every received signal, so
workflow code could act on a signal the Server had not applied yet and later
rejected, for example closing the run before a queued update was applied.
Signals now reach workflow code in message order with updates, as in embedded
Workflow, Python and Rust. `SignalReceived` records that name neither a
signal ID nor a command ID are still returned. Replay compatibility: the
change is gated by the version marker
`durable-workflow.sdk-php.signals-applied-only`. The worker records it the
first time hiding an unapplied signal changes what `signals()` returns to a
live decision (a call at the end of the recorded history, or the predicate of
a condition wait whose outcome is not recorded). A history without the marker
replays with every received signal visible; with it, live decisions and calls
replayed at or after the marker's sequence use the applied-only view, and
calls replayed before it keep the earlier view. Runs that never meet an
unapplied signal record no marker (#434).

## [3.20.0] - 2026-11-18

### Added
Expand Down
17 changes: 17 additions & 0 deletions docs/sdk-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -713,6 +713,23 @@ invoked. The workflow reads their committed values with
`$context->signals('set-language')` during replay. Query and update methods are
executed with immutable `QueryContext` state.

`signals()` returns only signals the Server has applied to the run, plus the
signal the current workflow task delivers, in the order the Server received
them. The Server applies signals in message order with updates, so an update
sent before a signal is applied first. A signal that has been received but not
yet applied is not returned, and one the Server rejects (for example because
the run closed first) never is.

Earlier SDK releases returned every received signal, so the applied-only view
is versioned with the marker `durable-workflow.sdk-php.signals-applied-only`.
The worker records it the first time hiding an unapplied signal changes what
`signals()` returns to a live decision: a call at the end of the recorded
history, or the predicate of a condition wait whose outcome is not recorded.
A history without the marker replays with every received signal visible. With
the marker, live decisions and calls replayed at or after the marker's sequence
use the applied-only view, and calls replayed before it keep the earlier view.
A run that never meets an unapplied signal records no marker.

The PHP SDK does not expose update-validator authoring. Worker registration
therefore declares an empty `update_validators` list for every workflow type;
capability discovery and Server admission must not infer validator parity from
Expand Down
26 changes: 25 additions & 1 deletion scripts/ci/run-replay-regression-fixture.php
Original file line number Diff line number Diff line change
Expand Up @@ -703,7 +703,7 @@ private static function executeLayout(
'arguments' => $codec->envelope($input),
'history_events' => $layout === 'inline' ? $history : [],
'next_history_page_token' => $layout === 'paginated' ? 'regression-page-1' : '',
], self::taskAttributes($workflowType));
], self::taskAttributes($workflowType), self::workerTaskAttributes($fixture));
$pagedHistory[$taskId] = $layout === 'paginated' ? $history : [];
}
$transport = new ReplayRegressionTransport(
Expand Down Expand Up @@ -959,6 +959,15 @@ private static function workflow(string $workflowType): callable

return $result;
},
// sdk-php#434: only applied signals, and the one this task delivers.
'golden.signal-applied' => static fn (WorkflowContext $context): array => ['signals' => $context->signals('approve')],
// sdk-php#434: a decision taken from the signals visible to this task.
'golden.signal-decision' => static function (WorkflowContext $context): array {
$approved = $context->signals('approve') !== [];
$result = $context->activity($approved ? 'golden.approved' : 'golden.waiting');

return ['result' => $result, 'signals' => $context->signals('approve')];
},
'golden.immediate-condition' => static function (WorkflowContext $context): array {
$first = $context->activity('golden.first');
$satisfied = $context->waitCondition(static fn (): bool => true, key: 'already-ready');
Expand Down Expand Up @@ -1419,6 +1428,21 @@ private static function selectionHandleIsolationWorkflow(): callable
};
}

/**
* The resume context a signal-delivering workflow task carries (sdk-php#434).
*
* @param array<string, mixed> $fixture
* @return array<string, mixed>
*/
private static function workerTaskAttributes(array $fixture): array
{
$workerTask = is_array($fixture['worker_task'] ?? null) ? $fixture['worker_task'] : [];

return array_intersect_key($workerTask, array_flip([
'resume_source_kind', 'resume_source_id', 'workflow_signal_id', 'workflow_command_id', 'signal_name',
]));
}

/** @return array<string, mixed> */
private static function taskAttributes(string $workflowType): array
{
Expand Down
228 changes: 228 additions & 0 deletions src/Worker/AppliedSignals.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,228 @@
<?php

declare(strict_types=1);

namespace DurableWorkflow\Worker;

use Closure;

/**
* @internal Which received signals workflow code observes (sdk-php#434).
*
* The Server records `SignalReceived` when it accepts a signal, and applies the
* signal to the run later, in message order with updates, when the workflow
* task that delivers it completes. Until then the signal can still be rejected,
* for example when the run closes first (`SignalRejected`). A signal is applied
* when:
*
* - a `SignalApplied` event names its signal ID or command ID;
* - its `SignalReceived` carries a `workflow_sequence`, which the Server adds
* from the signal record once a wait has consumed it;
* - it is the signal this workflow task delivers (`resume_source_kind:
* workflow_signal` with its `workflow_signal_id` or `workflow_command_id`),
* which the task's completion applies; or
* - its `SignalReceived` names neither a signal ID nor a command ID, so the
* history cannot say whether it was applied (imported or synthetic
* histories, and test fixtures).
*
* Earlier releases showed every received signal. The applied-only view is a
* versioned change recorded with the standard version marker
* {@see self::CHANGE_ID}:
*
* - The marker is recorded the first time the applied-only view changes what
* `signals()` returns to a live decision: a call at the end of the recorded
* history, or the predicate of a condition wait whose outcome is not
* recorded. The applied-only view applies from that call on.
* - With the marker in the history, live decisions and replayed calls at or
* after the marker's sequence use the applied-only view. Replayed calls
* before it keep the earlier view, so the decisions recorded before the
* marker replay unchanged.
* - Without the marker, every replayed call keeps the earlier view, and a run
* that never meets an unapplied signal records nothing.
*
* The marker step is transparent to the authored command sequence.
*/
final class AppliedSignals
{
/** The version-marker change ID that selects the applied-only view. */
public const CHANGE_ID = 'durable-workflow.sdk-php.signals-applied-only';

/** @var (Closure(): array{int, bool})|null the replay position and whether it is the live end */
private ?Closure $position = null;

private bool $liveEvaluation = false;

private bool $markerRequested = false;

private bool $markerFlushed = false;

/**
* @param array<string, true> $signalIds
* @param array<string, true> $commandIds
*/
private function __construct(
private readonly array $signalIds,
private readonly array $commandIds,
private readonly ?int $markerSequence,
) {
}

/**
* @param list<array<string, mixed>> $history
* @param array<string, mixed> $task
*/
public static function fromHistory(array $history, array $task): self
{
$signalIds = [];
$commandIds = [];
$markerSequence = null;
foreach ($history as $event) {
$type = $event['event_type'] ?? $event['type'] ?? null;
$payload = is_array($event['payload'] ?? null) ? $event['payload'] : [];
if ($type === 'SignalApplied'
|| ($type === 'SignalReceived' && self::recordedSequence($payload['workflow_sequence'] ?? null))) {
self::remember($signalIds, $commandIds, $payload['signal_id'] ?? null,
$payload['workflow_command_id'] ?? $event['workflow_command_id'] ?? null);
} elseif ($markerSequence === null && self::isMarker($type, $payload)) {
$markerSequence = $payload['sequence'];
}
}
if (($task['resume_source_kind'] ?? null) === 'workflow_signal') {
self::remember($signalIds, $commandIds, $task['workflow_signal_id'] ?? $task['resume_source_id'] ?? null,
$task['workflow_command_id'] ?? null);
}

return new self($signalIds, $commandIds, $markerSequence);
}

/** @param array<string, mixed> $payload */
public static function isMarker(mixed $type, array $payload): bool
{
return $type === 'VersionMarkerRecorded' && ($payload['change_id'] ?? null) === self::CHANGE_ID
&& is_int($payload['sequence'] ?? null) && $payload['sequence'] > 0;
}

/** @internal The Replayer reports its position: the next authored sequence and whether it is the live end. */
public function bind(Closure $position): void
{
$this->position = $position;
}

/**
* @internal Evaluate a condition predicate whose outcome is not recorded.
*
* @template T
* @param Closure(): T $evaluation
* @return T
*/
public function live(Closure $evaluation): mixed
{
$previous = $this->liveEvaluation;
$this->liveEvaluation = true;
try {
return $evaluation();
} finally {
$this->liveEvaluation = $previous;
}
}

/**
* Keep the received signals workflow code observes, in history order.
*
* @param array<int, array<string, mixed>> $received `SignalReceived` events of one name by history position
* @return array<int, array<string, mixed>>
*/
public function select(array $received): array
{
$applied = array_filter($received, fn (array $event): bool => $this->observes($event));
if (count($applied) === count($received)) {
return $received;
}

return $this->appliedOnly() || $this->requestMarker() ? $applied : $received;
}

/** @param array<string, mixed> $event a `SignalReceived` event */
public function observes(array $event): bool
{
$payload = is_array($event['payload'] ?? null) ? $event['payload'] : [];
$signalId = self::identity($payload['signal_id'] ?? null);
$commandId = self::identity($payload['workflow_command_id'] ?? $event['workflow_command_id'] ?? null);

return self::recordedSequence($payload['workflow_sequence'] ?? null)
|| ($signalId === null && $commandId === null)
|| ($signalId !== null && isset($this->signalIds[$signalId]))
|| ($commandId !== null && isset($this->commandIds[$commandId]));
}

/**
* @internal Whether this replay must record the marker it has not sent yet.
*
* @phpstan-impure
*/
public function takeMarker(): bool
{
if (!$this->markerRequested || $this->markerFlushed) {
return false;
}
$this->markerFlushed = true;

return true;
}

private function appliedOnly(): bool
{
if ($this->markerRequested) {
return true;
}
if ($this->markerSequence === null) {
return false;
}
[$sequence, $live] = $this->position();

return $live || $sequence >= $this->markerSequence;
}

/** Record the marker at a live decision of a history without one. */
private function requestMarker(): bool
{
if ($this->markerSequence !== null || !$this->position()[1]) {
return false;
}
$this->markerRequested = true;

return true;
}

/** @return array{int, bool} */
private function position(): array
{
[$sequence, $end] = $this->position === null ? [PHP_INT_MAX, false] : ($this->position)();

return [$sequence, $end || ($this->liveEvaluation && $this->position !== null)];
}

/**
* @param array<string, true> $signalIds
* @param array<string, true> $commandIds
*/
private static function remember(array &$signalIds, array &$commandIds, mixed $signalId, mixed $commandId): void
{
if (($signalId = self::identity($signalId)) !== null) {
$signalIds[$signalId] = true;
}
if (($commandId = self::identity($commandId)) !== null) {
$commandIds[$commandId] = true;
}
}

private static function identity(mixed $value): ?string
{
return (is_string($value) && $value !== '') || is_int($value) ? (string) $value : null;
}

private static function recordedSequence(mixed $value): bool
{
return (is_int($value) && $value > 0) || (is_string($value) && preg_match('/\A[1-9]\d*\z/', $value) === 1);
}
}
Loading