Migrate auto-purge to Action Scheduler with batched deletion

[PatelUtkarsh]

Summary

The old auto-purge runs on WP-Cron and issues one unbatched DELETE … LEFT JOIN against every eligible row. On low-traffic sites and sites with DISABLE_WP_CRON, the cron never fires. On bloated tables, the DELETE hits max_execution_time or an InnoDB lock-wait timeout and aborts, leaving orphan stream_meta rows behind.

This PR moves the work to Action Scheduler, which the manual reset path already uses:

• purge_schedule_setup() registers a recurring AS action (stream_auto_purge_action, 12h interval) and clears the legacy wp_stream_auto_purge WP-Cron event on upgrade.
• The recurring callback fires the wp_stream_auto_purge action for back-compat, snapshots a UTC cutoff from the TTL, applies an overlap guard, and branches on wp_stream_is_large_records_table:
  • Small table (default: <= 1M rows): one inline multi-table DELETE, then enqueues the reaper as a one-shot action so the heal step stays visible in Tools > Scheduled Actions.
  • Large table: enqueues the batched chain.
• The batch worker (stream_auto_purge_batch_action) deletes one window of up to wp_stream_batch_size rows (default 250,000, shared with the manual reset), then chains the next batch. last_entry threads through the chain to guarantee forward progress, mirroring Admin::erase_large_records().
• The reaper (stream_auto_purge_reaper_action) runs delete_orphaned_meta() once at the end of every chain, so installs with historical orphans heal over time.
• Settings > Advanced gains a Clean Orphaned Meta link that schedules the reaper on demand. Admin::is_running_auto_purge() hides the link while a chain is active and swaps the description to explain why.

Flow of clean up

flowchart TD
    %% Triggers
    T1["⏰ Recurring AS tick<br/>(every ~12h)"]
    T2["⚙️ Settings save:<br/>records_ttl shortened"]
    T3["🔗 Settings → Advanced:<br/>'Clean Orphaned Meta' link"]
    T4["🗑️ Settings → Reset:<br/>'Reset Stream Records' button"]

    %% Routing
    T2 -->|"do_action('wp_stream_auto_purge') (BC)<br/>+ enqueue AUTO_PURGE_ACTION async"| RP
    T1 --> RP["AUTO_PURGE_ACTION<br/>Admin::purge_scheduled_action()"]

    RP --> B{{"Bail-out checks:<br/>• network-admin scope<br/>• keep_records_indefinitely<br/>• records_ttl < 1<br/>• is_running_auto_purge()"}}
    B -->|"any check fails"| X1[/"return (no work, no BC action)"/]
    B -->|"all checks pass"| BC["do_action('wp_stream_auto_purge')<br/>(BC hook fires here)"]

    BC --> CNT["SELECT COUNT(ID) FROM stream<br/>(scoped by blog_id if per-site)"]
    CNT --> D{"is_large_records_table()<br/>default: count > 1,000,000<br/>filter: wp_stream_is_large_records_table"}

    D -->|"NO (small)"| FAST["Inline DELETE stream + meta<br/>WHERE created < cutoff"]
    FAST --> R

    D -->|"YES (large)"| BATCH["AUTO_PURGE_BATCH_ACTION<br/>Admin::auto_purge_batch(cutoff, blog_id, last_entry)"]

    BATCH --> SEL["SELECT max ID < cutoff<br/>(and < last_entry if set)"]
    SEL --> E{"rows remaining?"}
    E -->|"YES"| DEL["DELETE window<br/>(parent + meta, by ID range + cutoff)<br/>default batch: 250,000<br/>filter: wp_stream_batch_size"]
    DEL -->|"enqueue next batch<br/>last_entry = window_low"| BATCH
    E -->|"NO (terminal)"| R

    %% Reaper
    T3 -->|"admin-ajax + nonce<br/>idempotent enqueue"| R["AUTO_PURGE_REAPER_ACTION<br/>Admin::auto_purge_reaper()"]
    R --> RM["delete_orphaned_meta()<br/>DELETE meta WHERE parent stream row missing"]

    %% Manual reset
    T4 --> RST{"is_multisite_not_network_activated?"}
    RST -->|"NO (network / single-site)"| TRUNC["TRUNCATE stream + streammeta<br/>then delete_orphaned_meta() inline"]
    RST -->|"YES (per-site)"| RSTSZ{"is_large_records_table(blog count)?"}
    RSTSZ -->|"NO"| RSTSMALL["Inline DELETE WHERE blog_id = X"]
    RSTSZ -->|"YES"| RSTBIG["ASYNC_DELETION_ACTION<br/>Admin::erase_large_records() self-chains<br/>⚠ does NOT enqueue reaper at end (asymmetry)"]

    %% Styling
    classDef trigger fill:#e3f2fd,stroke:#1976d2,color:#0d47a1
    classDef action  fill:#fff3e0,stroke:#f57c00,color:#e65100
    classDef decision fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef bailout fill:#fafafa,stroke:#9e9e9e,color:#424242,stroke-dasharray: 4 4
    classDef warn    fill:#ffebee,stroke:#c62828,color:#b71c1c

    class T1,T2,T3,T4 trigger
    class RP,BATCH,R,FAST,DEL,RM,TRUNC,RSTSMALL,RSTBIG,BC action
    class B,D,E,RST,RSTSZ decision
    class X1 bailout
    class RM,RSTBIG warn

Loading

Checklist

• Project documentation has been updated to reflect the changes in this pull request, if applicable.
• I have tested the changes in the local development environment (see contributing.md).
• I have added phpunit tests.

Release Changelog

• Fix: Auto-purge runs through Action Scheduler with batched deletion. Sites where the old WP-Cron purge silently fails or times out on large stream / stream_meta tables now drain cleanly.
• Fix: Orphan stream_meta rows are removed at the end of every auto-purge cycle, so installs that accumulated orphans from earlier interrupted purges heal over time.
• New: Clean Orphaned Meta link under Settings > Advanced for one-shot cleanup. The link hides while a chain is running and returns once it drains.
• New: Auto-purge honors wp_stream_is_large_records_table. Small tables get one inline DELETE; bloated tables go through the batched chain. Same knob ops already tune for the manual reset.

Testing Instructions

1. Activate Stream (single-site or network-activated multisite).
2. Settings > Advanced: set Keep Records for to 1 day. Confirm Keep Records Indefinitely is off.
3. Seed aged records:

   npm run cli -- wp eval 'global \$wpdb; \$wpdb->query("UPDATE {\$wpdb->stream} SET created = DATE_SUB(NOW(), INTERVAL 2 DAY)");'
   

4. Trigger the recurring action:

   npm run cli -- wp eval 'wp_stream_get_instance()->admin->purge_scheduled_action();'
   

5. Open Tools > Scheduled Actions and filter by group stream-auto-purge. On a small table only the reaper is queued (the inline DELETE has already run). To force the batched chain on a small dataset: add_filter( 'wp_stream_is_large_records_table', '__return_true' );.
6. Let AS drain on subsequent admin requests, or run npm run cli -- wp action-scheduler run --group=stream-auto-purge.
7. Verify:
   • Aged rows gone: SELECT COUNT(*) FROM wp_stream WHERE created < DATE_SUB(NOW(), INTERVAL 1 DAY); returns 0.
   • No orphan meta: SELECT COUNT(*) FROM wp_stream_meta m LEFT JOIN wp_stream s ON s.ID = m.record_id WHERE s.ID IS NULL; returns 0.
8. Multisite scoping:
   • Network-activated: the purge spans all blogs.
   • Per-site activated: the purge touches only the current blog.
9. Manual cleanup, idle state: Settings > Advanced, click Clean Orphaned Meta. The page redirects with ?wp_stream_message=orphan_meta_cleanup_scheduled and the reaper appears in AS.
10. Manual cleanup, active state: while a chain is queued, reload Settings > Advanced. The link is hidden and the description reads "Auto-purge is currently running...". Once the chain drains, the link returns.

Fixes: #1056 #1236

[Copilot]

Pull request overview

This PR migrates Stream’s TTL-based auto-purge from a legacy WP-Cron event to Action Scheduler, adding a batched deletion path for large tables and a terminal orphan-meta cleanup step, plus UI/test coverage for the new behavior.

Changes:

• Replace WP-Cron–driven auto-purge with a recurring Action Scheduler action, including an overlap guard and a batched worker chain for large datasets.
• Add an orphan-meta “reaper” action (runs at the end of each purge chain) and expose a manual “Clean Orphaned Meta” link in Settings → Advanced.
• Expand PHPUnit coverage for scheduling/branching/batching and add a Playwright E2E spec for the new admin UX.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
classes/class-admin.php	Adds AS recurring auto-purge scheduling, batched purge worker, terminal reaper, and an AJAX endpoint to schedule the reaper.
classes/class-settings.php	Adds “Clean Orphaned Meta” link/description with running-state UX driven by Admin::is_running_auto_purge().
tests/phpunit/test-class-admin.php	Adds PHPUnit coverage for AS scheduling, back-compat hook firing, small/large table branches, batching, reaper behavior, and running-state probe.
tests/e2e/admin-orphan-cleanup.spec.js	Adds Playwright coverage for the manual orphan cleanup link and its hidden “running” state UX.
changelog.md	Documents the migration to Action Scheduler, batched deletion, and the new orphan-meta cleanup capability.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.