=== Queue Ajax Calls Performantly ===
Contributors: eddr,secretchord
Tags: queue, ajax, performance, pixelyoursite, capi
Requires at least: 6.8
Tested up to: 7.1
Requires PHP: 7.4
Stable Tag: 1.1.8
License: GPL-3.0-or-later
URI: http://www.gnu.org/licenses/gpl-3.0.html

Provides a way to queue selected Ajax and REST calls in a considerably more performantly via an MU plugin.
Allows processing these calls as a batch.

== Description ==

Reduce server load and increase reliabilty considerably by queuing selected Ajax and REST calls and process them in bulk later on. Load the entire WP system once for every x request.

The mechanism is based on catching the calls early in the WP lifecycle via an MU plugin, santizing and queuing. The queue system is based on Automattic's own Action Scheduler plugin. The fields for sanitiation should be defined for security reasons.

Processing the calls : the calls are processed in bulk via a hook that is run by CRON.

= Who is it for =

At this stage the plugin is a developer level plugin and is intended to be used as such. It requires defining fields for sanitation.
However, it comes with a basic implementation for the latest PixelYourSite API calls and can be easily activated without further configuration for most cases.

= The flow =

* AJAX or REST call evoked in the client browser ->
* MU plugin catches the call if the configuration includes the specific action or route of the call ->
* Processor ( built-in or user defined ) checks the data and sanitizes it ->
* Data is stored in DB to be handled in queue. The data includes the call's data and cookies ->
* Data is processed in batch via a recurring Action Scheduler hook. The processing is done via the same "Processor".
* A row is completed only when its processor returns true. Failed rows retry with backoff and then remain visible for manual recovery.

= Queue reliability =

Queue rows move through pending, processing, completed, retry, failed, and cancelled states. Rows are claimed atomically one at a time so concurrent runners cannot process the same call. A PHP process that terminates unexpectedly leaves only its active row locked; stale locks are recovered automatically and later calls continue to advance.

The settings page shows queue totals grouped by AJAX/REST request and action. Failed rows can be retried, cancelled, or deleted without direct database access.

= Anonymized endpoint diagnostics =

When an endpoint request fails validation, the settings page can capture an anonymized diagnostic report. Start capture, reproduce the rejected request, and then use Copy debug report. Capture stops after the first validation failure or after ten minutes.

The report includes environment and processor configuration, the validation reason, and request field names, types, and sizes. It does not include request values, cookies, URLs, domains, IP addresses, user IDs, event IDs, nonces, or authorization data.

= Replay processors =

The admin Replay Processors builder supports sanitation-only integrations. Define an AJAX action or REST route, validation policy, and allowed parameter types. QACP then validates the captured request and internally replays its original WordPress handler during queue processing. Custom PHP processors remain available when an integration needs specialized processing logic.

= Basic terminogoly =

*Processor* : A class/instance that is used to define the *data map* of fields for sanitation and later on, for batch processing. In many cases, the Processor will be quite simple. Please check the built-in Processor class *"class-pys.php"* under the "qacp/Processors" directory.
*Data Map* : The map of fields and their respectable sanitation functions. There's an example in the "qacp/qacp-how-to.txt" file.
*REST route key* : A configured REST route prefixed with "rest:", for example "rest:pys-facebook/v1/event".

= Things to Remember =

* The Processor should define clearly what are the received fields and their sanitation functions.
* The action and processor should be registerd. There's an example in the "qacp/qacp-how-to.txt" file.
* A Processor must return true after successful processing. False, WP_Error, and exceptions are treated as failures.

= Hooks =

* qacp/processors/active_processors
* qacp/processors/actions
* qacp/processors/identify_processor
* qacp/processors/instance_by_action_name

* qacp_before_batch_processing
* qacp_before_process_entry_{$_action_name}
* qacp_before_process_entry
* qacp_process_one_entry_{$_action_name}
* qacp_process_one_entry
* qacp_mark_event_finished
* qacp_after_process_entry_{$_action_name
* qacp_after_process_entry
* qacp_after_batch_processing
