|
| 1 | +<?php |
| 2 | + |
| 3 | +namespace Waterline\Support; |
| 4 | + |
| 5 | +use Workflow\V2\Support\WorkerCompatibility; |
| 6 | +use Workflow\V2\Support\WorkerCompatibilityFleet; |
| 7 | + |
| 8 | +class CompatibilitySemantics |
| 9 | +{ |
| 10 | + private const ACTIVE_HEARTBEAT_POLICY = 'Only active, unexpired worker heartbeats count as fleet support; stale or missing snapshots are not claimability evidence.'; |
| 11 | + |
| 12 | + /** |
| 13 | + * @param array<string, mixed> $payload |
| 14 | + * @return array<string, mixed> |
| 15 | + */ |
| 16 | + public static function annotateRun(array $payload): array |
| 17 | + { |
| 18 | + $payload = self::withCompatibilityFields($payload); |
| 19 | + $payload['compatibility_semantics'] = self::forPayload($payload); |
| 20 | + |
| 21 | + if (is_array($payload['tasks'] ?? null)) { |
| 22 | + $payload['tasks'] = array_map( |
| 23 | + static fn (mixed $task): mixed => is_array($task) |
| 24 | + ? self::annotateTask($task, $payload) |
| 25 | + : $task, |
| 26 | + $payload['tasks'], |
| 27 | + ); |
| 28 | + } |
| 29 | + |
| 30 | + return $payload; |
| 31 | + } |
| 32 | + |
| 33 | + /** |
| 34 | + * @param array<string, mixed> $item |
| 35 | + * @return array<string, mixed> |
| 36 | + */ |
| 37 | + public static function annotateListItem(array $item): array |
| 38 | + { |
| 39 | + $item = self::withCompatibilityFields($item); |
| 40 | + $item['compatibility_semantics'] = self::forPayload($item); |
| 41 | + |
| 42 | + return $item; |
| 43 | + } |
| 44 | + |
| 45 | + /** |
| 46 | + * @param array<string, mixed> $task |
| 47 | + * @param array<string, mixed> $run |
| 48 | + * @return array<string, mixed> |
| 49 | + */ |
| 50 | + private static function annotateTask(array $task, array $run): array |
| 51 | + { |
| 52 | + $task = self::withCompatibilityFields($task, $run); |
| 53 | + $task['compatibility_semantics'] = self::forPayload($task); |
| 54 | + |
| 55 | + return $task; |
| 56 | + } |
| 57 | + |
| 58 | + /** |
| 59 | + * @param array<string, mixed> $payload |
| 60 | + * @param array<string, mixed>|null $fallback |
| 61 | + * @return array<string, mixed> |
| 62 | + */ |
| 63 | + private static function withCompatibilityFields(array $payload, ?array $fallback = null): array |
| 64 | + { |
| 65 | + $compatibility = self::stringValue($payload['compatibility'] ?? null) |
| 66 | + ?? self::stringValue($fallback['compatibility'] ?? null); |
| 67 | + $connection = self::stringValue($payload['connection'] ?? null) |
| 68 | + ?? self::stringValue($fallback['connection'] ?? null); |
| 69 | + $queue = self::stringValue($payload['queue'] ?? null) |
| 70 | + ?? self::stringValue($fallback['queue'] ?? null); |
| 71 | + |
| 72 | + $payload['compatibility'] = $compatibility; |
| 73 | + $payload['compatibility_supported'] = self::boolOr( |
| 74 | + $payload['compatibility_supported'] ?? null, |
| 75 | + static fn (): bool => WorkerCompatibility::supports($compatibility), |
| 76 | + ); |
| 77 | + $payload['compatibility_reason'] = self::stringValue($payload['compatibility_reason'] ?? null) |
| 78 | + ?? WorkerCompatibility::mismatchReason($compatibility); |
| 79 | + $payload['compatibility_supported_in_fleet'] = self::boolOr( |
| 80 | + $payload['compatibility_supported_in_fleet'] ?? null, |
| 81 | + static fn (): bool => WorkerCompatibilityFleet::supports($compatibility, $connection, $queue), |
| 82 | + ); |
| 83 | + $payload['compatibility_fleet_reason'] = self::stringValue($payload['compatibility_fleet_reason'] ?? null) |
| 84 | + ?? WorkerCompatibilityFleet::mismatchReason($compatibility, $connection, $queue); |
| 85 | + |
| 86 | + if (! array_key_exists('compatibility_namespace', $payload)) { |
| 87 | + $payload['compatibility_namespace'] = self::stringValue($fallback['compatibility_namespace'] ?? null) |
| 88 | + ?? WorkerCompatibilityFleet::scopeNamespace(); |
| 89 | + } |
| 90 | + |
| 91 | + return $payload; |
| 92 | + } |
| 93 | + |
| 94 | + /** |
| 95 | + * @param array<string, mixed> $payload |
| 96 | + * @return array<string, mixed> |
| 97 | + */ |
| 98 | + private static function forPayload(array $payload): array |
| 99 | + { |
| 100 | + $compatibility = self::stringValue($payload['compatibility'] ?? null); |
| 101 | + $claimable = self::boolValue($payload['compatibility_supported'] ?? null); |
| 102 | + $fleetSupported = self::boolValue($payload['compatibility_supported_in_fleet'] ?? null); |
| 103 | + $state = self::state($compatibility, $claimable, $fleetSupported); |
| 104 | + |
| 105 | + return [ |
| 106 | + 'state' => $state, |
| 107 | + 'required_marker' => $compatibility, |
| 108 | + 'claimable_by_this_build' => $claimable, |
| 109 | + 'supported_in_active_fleet' => $fleetSupported, |
| 110 | + 'compatibility_namespace' => self::stringValue($payload['compatibility_namespace'] ?? null), |
| 111 | + 'current_build_reason' => self::stringValue($payload['compatibility_reason'] ?? null), |
| 112 | + 'fleet_reason' => self::stringValue($payload['compatibility_fleet_reason'] ?? null), |
| 113 | + 'active_heartbeat_policy' => self::ACTIVE_HEARTBEAT_POLICY, |
| 114 | + 'operator_summary' => self::summary($state), |
| 115 | + ]; |
| 116 | + } |
| 117 | + |
| 118 | + private static function state(?string $compatibility, ?bool $claimable, ?bool $fleetSupported): string |
| 119 | + { |
| 120 | + if ($compatibility === null) { |
| 121 | + return 'no_required_marker'; |
| 122 | + } |
| 123 | + |
| 124 | + if ($claimable === true) { |
| 125 | + return 'claimable_by_this_build'; |
| 126 | + } |
| 127 | + |
| 128 | + if ($fleetSupported === true) { |
| 129 | + return 'supported_elsewhere_in_active_fleet'; |
| 130 | + } |
| 131 | + |
| 132 | + return 'waiting_for_active_compatible_worker'; |
| 133 | + } |
| 134 | + |
| 135 | + private static function summary(string $state): string |
| 136 | + { |
| 137 | + return match ($state) { |
| 138 | + 'claimable_by_this_build' => 'The current build can claim this required compatibility marker.', |
| 139 | + 'supported_elsewhere_in_active_fleet' => 'Another active worker heartbeat can claim this marker, but this build cannot.', |
| 140 | + 'waiting_for_active_compatible_worker' => 'No active worker heartbeat currently advertises this required compatibility marker.', |
| 141 | + default => 'No compatibility marker is required for this row.', |
| 142 | + }; |
| 143 | + } |
| 144 | + |
| 145 | + private static function boolValue(mixed $value): ?bool |
| 146 | + { |
| 147 | + return is_bool($value) ? $value : null; |
| 148 | + } |
| 149 | + |
| 150 | + private static function boolOr(mixed $value, callable $fallback): bool |
| 151 | + { |
| 152 | + return is_bool($value) ? $value : (bool) $fallback(); |
| 153 | + } |
| 154 | + |
| 155 | + private static function stringValue(mixed $value): ?string |
| 156 | + { |
| 157 | + return is_string($value) && $value !== '' |
| 158 | + ? $value |
| 159 | + : null; |
| 160 | + } |
| 161 | +} |
0 commit comments