feat: network-wide presence aggregation for multisite

[josephfusco]

Multisite networks had no way to see who's online across sites.

Part of #298

See #310 for an open question on this design worth discussion before merge.

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Sonnet 5
Used for: Assisting with design, implementation, and testing

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props joefusco.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

▶ Preview in WordPress Playground

Boots a fresh WordPress with this PR's presence-api build, seeds 5 demo users, and drops you on the dashboard.

_{Stress-test variant: 40 demo users · Built from 91bf7412813b5146aac4a1e67d7ffb2b4c6ecef5. Auto-updates when you push.}

[codecov]

Codecov Report

❌ Patch coverage is 96.66667% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.16%. Comparing base (433f7b6) to head (91bf741).

Additional details and impacted files

@@            Coverage Diff             @@
##               main     #299    +/-   ##
==========================================
  Coverage     97.15%   97.16%            
  Complexity      190      190            
==========================================
  Files            14       15     +1     
  Lines          2076     2220   +144     
==========================================
+ Hits           2017     2157   +140     
- Misses           59       63     +4     

Flag	Coverage Δ
multisite	97.16% <96.66%> (+<0.01%)	⬆️
phpunit	90.27% <6.66%> (-5.78%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

Adds the network-presence aggregation foundation for multisite using a shared push-based summary table.

Changes:

• Provisions and updates a network-wide presence summary table.
• Aggregates fresh site snapshots without switching blogs.
• Adds multisite provisioning, aggregation, freshness, and recovery tests.

Reviewed changes

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

Show a summary per file

File	Description
presence-api.php	Registers storage and lifecycle hooks.
includes/network-functions.php	Implements provisioning, pushing, and aggregation.
includes/functions.php	Emits change events and renders avatar stacks.
tests/test-network-presence.php	Tests aggregation and refresh behavior.
tests/test-network-summary-table-creation.php	Tests table provisioning and recovery.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[josephfusco]

Went through this against the sharding question in #310, with the numbers measured on a live multisite rather than read off the diff.

Write amplification on every pageview

wp_set_presence() goes from 1 query to 4 with the push hook active:

wp_set_presence queries with push=4 without push=1

This is not just the heartbeat tick. wp_presence_enqueue_heartbeat_ping() writes the admin room on every admin pageview and every front-end view with an admin bar, so every pageview by every edit_posts user on every site now issues a SELECT plus an INSERT ... ON DUPLICATE KEY UPDATE against {base_prefix}presence_network_summary.

Coalescing bounds row churn. It does not bound statement rate, connection count, or row-lock acquisition, and the SELECT that feeds the comparison runs either way. Full answer to #310 over on that issue.

Fix: debounce the push through the object cache so a site pushes at most once per wp_presence_network_summary_refresh_interval(), and default the aggregation off under wp_is_large_network().

Nothing ever removes a row

There is no wp_uninitialize_site or wp_delete_site hook, so a deleted site's row stays forever. The read path skips it because get_site() returns null, so this is a leak rather than a correctness problem.

uninstall.php also never drops {base_prefix}presence_network_summary and never deletes wp_presence_network_summary_db_version or wp_presence_network_summary_table.lock.

The read path is unbounded

wp_presence_compute_network_summary() selects every row over the cutoff with no LIMIT, hydrates every user on every site, then sorts twice. get_site() runs per row with no _prime_site_caches().

At 300 sites averaging 15 users, the avatar hydration alone:

300 sites x 15 users get_avatar_url: 135ms per summary build

Smaller

• JSON_PRETTY_PRINT inflates the row 2.8x, 241 bytes against 86 for 15 users. That column is the operand of data <> VALUES(data) on a longtext, so the inflation is paid on every push comparison and every read.
• false !== $result treats a delete matching zero rows as a change, so the pagehide path fires spurious pushes.
• url is built from is_ssl() on the current request, so a mixed-scheme network gets wrong links for some sites.
• wp_presence_register_network_summary_table() appends to ms_global_tables with no in_array guard and runs both at require time and on init priority 0, so the entry lands twice.
• wp_presence_network_summary_table_exists() runs SHOW TABLES LIKE on every admin_init once provisioned. Same shape as the single-site table, but a network with tens of thousands of tables turns it into a data dictionary scan per admin request.