transientKey( $hash ), $data, self::TTL_SECONDS ); return $token; } /** * Read a token's stored data. * * @param string $token Raw token. * @return array|null Stored data (see {@see create()}'s shape, plus `claimed`/`outcome` once recorded), or null when missing/expired. */ public function get( string $token ): ?array { $data = get_transient( $this->transientKey( hash( 'sha256', $token ) ) ); return is_array( $data ) ? $data : null; } /** * Atomically claim this token for the current confirm attempt. * * @param string $token Raw token. * @return bool True when this call won the claim; false when a claim already exists (a concurrent call is already running it). */ public function claim( string $token ): bool { return (bool) add_option( $this->claimKey( hash( 'sha256', $token ) ), time(), '', 'no' ); } /** * Release a claim won by {@see claim()} without ever recording an * outcome — only for a failure discovered BEFORE any run started (e.g. a * product-count mismatch against the preview), so the caller can retry * the same token. * * @param string $token Raw token. * @return void */ public function release( string $token ): void { delete_option( $this->claimKey( hash( 'sha256', $token ) ) ); } /** * Record (or progressively update) this token's outcome: merges * `claimed => true`, `finished => $finished` and `outcome => $outcome` * into the stored data, re-stored for only the time remaining of the * original 900s window (never a fresh one). The claim option is cleared * only once $finished is true — from that point on, `get()`'s own * `claimed`/`finished` flags are what a later call checks, so the claim * option has served its purpose; while $finished is false the option * stays held, so a reader whose own get() ran before this call (and so * never saw `claimed`) cannot win a second claim() mid-run and re-run * the same work with stale data. * * Safe to call more than once for the same token (the confirm sync loop * calls this after every product, so a timeout mid-loop still leaves a * truthful partial outcome behind for a retry to read). `$finished` * distinguishes those in-progress checkpoints from the run's real, * final outcome: a reader (confirm()'s own idempotent-retry check) must * never treat an unfinished snapshot as the authoritative answer, since * {@see \AIPT\Api\ContentStructure\Ability\ConfirmOutcomeBuilder::computeStatus()} * has no notion of "more products remain" and can report a terminal- * looking status (e.g. 'completed') for a run that is still under way. * * @param string $token Raw token. * @param array $outcome Confirm response shape so far (or final). * @param bool $finished Whether $outcome is the run's real, final * answer (the default) or a mid-run progress * checkpoint the caller will still overwrite. * @return void */ public function recordOutcome( string $token, array $outcome, bool $finished = true ): void { $hash = hash( 'sha256', $token ); $data = $this->get( $token ); if ( null === $data ) { return; } $data['claimed'] = true; $data['finished'] = $finished; $data['outcome'] = $outcome; $remaining = max( 1, (int) ( $data['_expires_at'] ?? time() ) - time() ); set_transient( $this->transientKey( $hash ), $data, $remaining ); if ( $finished ) { delete_option( $this->claimKey( $hash ) ); } } /** * @param string $hash sha256(token). * @return string */ private function transientKey( string $hash ): string { return 'aipt_ability_confirm_' . $hash; } /** * @param string $hash sha256(token). * @return string */ private function claimKey( string $hash ): string { return 'aipt_ability_confirm_claim_' . $hash; } }