Add as_enqueue_async_action() and async action APIs

[thenbrent]

The PR introduces a new set of APIs for scheduling actions to run "as soon as possible". This is to achieve the async action type required as part of #319.

Background

Typically, an action is scheduled for a date. In cases where that action needed to run "as soon as possible", that date would have been set to the current time, e.g. time(). For an example, see WC_Action_Queue::add(). The problem with "now" is that there is no way to make sure that action is run sooner than any other action scheduled to run now, including those that may have been scheduled to run at that time months in advance.

In practice, an async action should take priority over a scheduled action, because there is an expectation it will be run very soon after being added to the queue. Whereas a scheduled action, like a subscription payment, may have been scheduled months in advance so if it processes a few minutes late, most of the time there's no harm done as no one is really sitting around expecting it to go through.

Notes on Approach

This patch makes it acceptable to save an action with a NULL schedule. This mapps its MySQL datetime string to 0000-00-00 00:00:00.

The advantage of this approach is that it is fully backward compatible. Existing queries to claim actions claim them by date, meaning actions with the 0000-00-00 00:00:00 scheduled time will always be claimed prior to actions scheduled for a specific date. This makes sure that any async action is given priority in queue processing. This has the added advantage of making sure async actions can be claimed by both the existing WP Cron and WP CLI runners, as well as a new async request runner.

As this makes async APIs backward compatible with both existing datastores and the new custom table data stores coming in #259, and it has none of the issues mentioned in #319 that would stem from using other backward comptaible APIs, like the using the action group, I've chosen this approach.

The downside is that 0000-00-00 00:00:00 is a bit of a hack and will allow for potentially critical bugs in 3rd party code, as seen by the fact that I had to remove existing validation against NULL dates for it to be possible. 3rd parties can now accidentally schedule actions with a NULL date, instead of receiving an exception to alert them to errors.

[rrennick]

@thenbrent this works great but as_next_scheduled_action() doesn't find the async actions. We need that to prevent flooding the queue with actions.

[thenbrent]

but as_next_scheduled_action() doesn't find the async actions.

Ah good catch @rrennick! What do you think is the most sane return value for as_next_scheduled_action() for an async action?

I see the following options:

1. 0 to represent the absence of a schedule and/or that its scheduled for "the beginning of time" (which is the Unix Epoch in PHP's world). This is risky though, because it will be confused with false via weak comparison operators, so it's likely to create bugs with existing 3rd party code.
2. 1, to represent a truthy value in int that is still near enough to the beginning of time to communicate the above messages.
3. time() to indicate that the next time any async action should be run is "now" (which is always true for any pending async action because they should be run ASAP). This could cause issues though, if 3rd party code is checking against something like as_next_scheduled_action() < time(), or for that matter, as_next_scheduled_action() > time().
4. something else?

It seems like 2 is the best worst option to me.

[thenbrent]

Another couple of options:

5. return NULL, to indicate there is a scheduled action (i.e. the return value is not false), but it doesn't have a scheduled timestamp. This return value has the same issue as 0.
6. return boolean true, to indicate there is a scheduled action, but it doesn't have a scheduled timestamp. This seems semantically correct, backward compatible and relatively robust. It will fail against any checks for as_next_scheduled_action() > time() though. I'm not sure if there is anyway around that though.

[thenbrent]

but as_next_scheduled_action() doesn't find the async actions.

I've pushed up SHA: 77d2c09 to fix this. It returns true for pending async actions. It continues to return false if there are only cancelled, completed, failed or in-progress async actions with a matching hook.

[rrennick]

@thenbrent Looks & works great. Can we change the target branch to version_3_0_0 ?

[thenbrent]

Can we change the target branch to version_3_0_0 ?

Yes of course! I've cherry-picked the commits from this branch to a new branch based on version_3_0_0, force pushed and changed the base branch on this PR to version_3_0_0.

I originally wrote this patch using add/custom-tables as the base (on SHA: 5af3d17), so it should work fine once those branch in merged too (depending on changes from that SHA to merge).