JezK

Edit File: cloud-queue-svc.cls.php

<?php
/**
 * Shared base for QC queue-driven svcs.
 *
 * Hosts the cron loop, try_later throttling, allowance check, and Cloud::post
 * orchestration that UCSS / CCSS / VPI / Optimax all share. Each concrete
 * svc supplies only the bits that actually differ: svc id, payload
 * builder, response data key, and save action.
 *
 * @since   8.1
 * @package LiteSpeed
 */

namespace LiteSpeed;

defined( 'WPINC' ) || exit();

/**
 * Abstract base for queue-driven QUIC.cloud svcs.
 *
 * @since 8.1
 */
abstract class Cloud_Queue_Svc extends Base {

const TYPE_GEN     = 'gen';
	const TYPE_CLEAR_Q = 'clear_q';

/**
	 * In-memory working queue.
	 *
	 * @var array
	 */
	protected $_queue;

/**
	 * Svc id slug.
	 *
	 * Used as queue type, Cloud::SVC_* suffix, and summary key prefix.
	 *
	 * @return string
	 */
	abstract protected function _svc_id();

/**
	 * Response field name that carries the generated payload.
	 *
	 * @return string
	 */
	abstract protected function _data_key();

/**
	 * Build the request body sent to Cloud::post.
	 *
	 * @param string $queue_k Queue key.
	 * @param array  $v       Queue item.
	 * @return array
	 */
	abstract protected function _build_payload( $queue_k, $v );

/**
	 * Persist the generated data.
	 *
	 * Returning false signals the caller to treat the item as failed and drop
	 * it from the queue without claiming success.
	 *
	 * @param mixed  $data    Value at the response data key.
	 * @param string $queue_k Queue key.
	 * @param array  $v       Queue item.
	 * @return bool|void True / void on success, false to abort.
	 */
	abstract protected function _save_result( $data, $queue_k, $v );

/**
	 * Cloud::post HTTP timeout in seconds.
	 *
	 * @return int
	 */
	protected function _post_timeout() {
		return 30;
	}

/**
	 * PHP max_execution_time set before issuing the request.
	 *
	 * @return int
	 */
	protected function _php_time_limit() {
		return 120;
	}

/**
	 * Maximum queue length before refusing further enqueues. Concrete classes
	 * call _max_queue_size() at enqueue sites; the base loop does not enforce.
	 *
	 * @return int
	 */
	protected function _max_queue_size() {
		return 500;
	}

/**
	 * Summary key for the in-flight request timestamp (300s gate).
	 *
	 * @return string
	 */
	protected function _curr_request_key() {
		return 'curr_request_' . $this->_svc_id();
	}

/**
	 * Summary key for the last successful request timestamp. Read by admin
	 * templates; concrete classes whose tpl reads a legacy key (e.g. UCSS/VPI
	 * read `last_request`) must override.
	 *
	 * @return string
	 */
	protected function _last_request_key() {
		return 'last_request_' . $this->_svc_id();
	}

/**
	 * Summary key for the last successful request duration. Mirrors
	 * _last_request_key() naming so UCSS/VPI emit the unsuffixed `last_spent`
	 * the dashboard expects.
	 *
	 * @return string
	 */
	protected function _last_spent_key() {
		return str_replace( 'last_request', 'last_spent', $this->_last_request_key() );
	}

/**
	 * Summary key for the server-driven try_later deadline.
	 *
	 * @return string
	 */
	protected function _next_run_after_key() {
		return $this->_svc_id() . '_next_run_after';
	}

/**
	 * Resolve the Cloud::SVC_* constant for this svc.
	 *
	 * @return string
	 */
	protected function _svc_const() {
		return constant( Cloud::class . '::SVC_' . strtoupper( $this->_svc_id() ) );
	}

/**
	 * Validate a queue item before dispatching to Cloud. Concrete classes
	 * override to guard against malformed legacy rows that would otherwise
	 * burn a QC request and persist a bogus mapping.
	 *
	 * @param string $queue_k Queue key.
	 * @param array  $v       Queue item.
	 * @return bool True to dispatch, false to silently drop.
	 */
	protected function _valid_queue_item( $queue_k, $v ) {
		return true;
	}

/**
	 * Static cron entry point invoked by WP cron and admin actions.
	 *
	 * @param bool $keep_going Process the whole queue when true; otherwise stop
	 *                         after the first item.
	 * @return mixed
	 */
	public static function cron( $keep_going = false ) {
		$_instance = static::cls();
		return $_instance->_cron_handler( $keep_going );
	}

/**
	 * Cron loop. Walks the queue, honors throttling, and dispatches each item
	 * to _send_req().
	 *
	 * @param bool $keep_going Process the whole queue when true.
	 * @return void
	 */
	protected function _cron_handler( $keep_going ) {
		$type         = $this->_svc_id();
		$this->_queue = $this->load_queue( $type );

if ( empty( $this->_queue ) ) {
			return;
		}

$next_run_key = $this->_next_run_after_key();
		if ( ! empty( $this->_summary[ $next_run_key ] ) && time() < $this->_summary[ $next_run_key ] ) {
			$wait_seconds = $this->_summary[ $next_run_key ] - time();
			self::debug( 'Waiting for try_later timeout: ' . $wait_seconds . ' seconds remaining' );
			return;
		}

if ( ! empty( $this->_summary[ $next_run_key ] ) ) {
			unset( $this->_summary[ $next_run_key ] );
			self::save_summary();
			self::debug( 'Cleared try_later flag, resuming ' . $type . ' processing' );
		}

$curr_key = $this->_curr_request_key();
		if ( ! $keep_going ) {
			if ( ! empty( $this->_summary[ $curr_key ] )
				&& time() - (int) $this->_summary[ $curr_key ] < 300
				&& ! $this->conf( self::O_DEBUG ) ) {
				self::debug( 'Last request not done' );
				return;
			}
		}

foreach ( $this->_queue as $k => $v ) {
			if ( ! $this->_valid_queue_item( $k, $v ) ) {
				self::debug( 'invalid queue item, dropping [tag] ' . $k );
				$this->_queue = $this->load_queue( $type );
				unset( $this->_queue[ $k ] );
				$this->save_queue( $type, $this->_queue );
				continue;
			}

self::debug( 'cron job [request] ' . substr( hash( 'sha256', (string) $k ), 0, 12 ) . ( ! empty( $v['is_mobile'] ) ? ' 📱 ' : '' ) );

$res = $this->_send_req( $k, $v );

if ( ! $res ) {
				// Reload to avoid clobbering concurrent writes, then drop the item.
				// Settled decision: a failed result drops. See AGENTS.md "Settled decisions".
				$this->_queue = $this->load_queue( $type );
				unset( $this->_queue[ $k ] );
				$this->save_queue( $type, $this->_queue );

if ( ! $keep_going ) {
					return;
				}
				continue;
			}

if ( 'out_of_quota' === $res || 'svc_hot' === $res ) {
				return;
			}

if ( is_array( $res ) && ! empty( $res['try_later'] ) ) {
				$ttl                             = (int) $res['try_later'];
				$next_run_time                   = time() + $ttl;
				$this->_summary[ $next_run_key ] = $next_run_time;
				self::save_summary();
				self::debug( 'Set next ' . $type . ' cron run after ' . $ttl . ' seconds (at ' . gmdate( 'Y-m-d H:i:s', $next_run_time ) . ')' );
				return;
			}

if ( ! $keep_going ) {
				return;
			}
		}
	}

/**
	 * Dispatch one queue item to Cloud::post and persist the result.
	 *
	 * @param string $queue_k Queue key.
	 * @param array  $v       Queue item.
	 * @return bool|string|array True on success, 'out_of_quota'/'svc_hot' to abort, [try_later=>ttl] to throttle, false on error.
	 */
	private function _send_req( $queue_k, $v ) {
		$svc = $this->_svc_const();

$err       = false;
		$allowance = $this->cls( 'Cloud' )->allowance( $svc, $err );
		if ( ! $allowance ) {
			self::debug( '❌ No credit: ' . $err );
			$err && Admin_Display::error( Error::msg( $err ) );
			return 'out_of_quota';
		}

set_time_limit( $this->_php_time_limit() );

$curr_key                    = $this->_curr_request_key();
		$this->_summary[ $curr_key ] = time();
		self::save_summary();

$data = $this->_build_payload( $queue_k, $v );

$json = Cloud::post( $svc, $data, $this->_post_timeout() );
		if ( ! is_array( $json ) ) {
			return $json;
		}

if ( ! empty( $json['try_later'] ) ) {
			$ttl = (int) $json['try_later'];
			self::debug( 'Server requested try later: ' . $ttl . ' seconds' );
			self::save_summary( [ $curr_key => 0 ], true );
			return [ 'try_later' => $ttl ];
		}

if ( empty( $json['status'] ) ) {
			self::debug( '❌ No status in response' );
			return false;
		}

$data_key = $this->_data_key();
		$data_val = isset( $json[ $data_key ] ) ? $json[ $data_key ] : null;
		if ( empty( $data_val ) ) {
			self::debug( '❌ No ' . $data_key . ' data [status] ' . $json['status'] );
		}

self::debug( '✅ Received ' . $data_key . ', saving...' );
		// Concrete _save_result decides whether empty data is a hard error
		// (returns false to drop without success accounting) or a sentinel to
		// persist as-is (returns true to mark the URL as processed).
		if ( false === $this->_save_result( $data_val, $queue_k, $v ) ) {
			self::debug( '❌ _save_result returned false [k] ' . $queue_k );
			return false;
		}

// Reload to avoid clobbering concurrent writes, then drop the item.
		$type         = $this->_svc_id();
		$this->_queue = $this->load_queue( $type );
		unset( $this->_queue[ $queue_k ] );
		$this->save_queue( $type, $this->_queue );
		self::debug( 'Removed from queue [q_k] ' . $queue_k );

$curr_time                                    = (int) $this->_summary[ $curr_key ];
		$this->_summary[ $this->_last_spent_key() ]   = time() - $curr_time;
		$this->_summary[ $this->_last_request_key() ] = $curr_time;
		$this->_summary[ $curr_key ]                  = 0;
		self::save_summary();

return true;
	}

/**
	 * Admin action handler dispatched by Router.
	 *
	 * @return void
	 */
	public function handler() {
		$type = Router::verify_type();

switch ( $type ) {
			case static::TYPE_GEN:
				static::cron( true );
				break;

case static::TYPE_CLEAR_Q:
				$this->clear_q( $this->_svc_id() );
				break;

default:
				break;
		}

Admin::redirect();
	}
}