Cache Warmup

Overview

Cache Warmup is the warmup (cache preload) execution engine. It receives invalidated URLs from Cache Invalidator (or detects cache purge events independently) and rebuilds cache by issuing HTTP GET requests in WP-Cron batches.

Key capabilities:

• Targeted warmup for specific URLs after content changes
• Full warmup from sitemaps after cache-wide purge events
• Adaptive auto-pacing based on server response telemetry
• Priority ordering (priority pages, post type order, default-language-first)
• Sitemap membership filtering
• Deduplicated queue with safety limits
• Run history logging with retention management
• REST API for settings and diagnostics

How Cache Warmup Operates

1. URLs received — from Cache Invalidator, cache purge events, or manual triggers
2. Queue built — URLs deduplicated, prioritized, and filtered against sitemaps
3. Batches scheduled — WP-Cron processes URLs in sequential batches
4. Pacing adapts — batch size adjusts based on server response telemetry
5. Run completes — results logged, queue cleared, ready for next trigger

See: Cache Warmup → Diagnostics if warmup does not run as expected.

Configuration Concepts

Cache Warmup is configured through the plugin’s admin settings UI. The key concepts are summarized here; for exact field definitions, see the Settings Reference below.

Sitemaps and URL Resolution

Sitemaps serve two purposes:

1. Full warmup URL source
   When a full warmup is triggered, URLs are resolved from configured sitemaps.
2. Membership filtering
   Targeted warmup URLs are checked against sitemap membership. URLs not present in any configured sitemap are typically filtered out — this prevents warming non-public or irrelevant URLs.

The sitemap resolver supports:

• Sitemap index files (recursive child sitemap discovery)
• Standard urlset sitemaps
• URL canonicalization and deduplication

See: Cache Warmup → Sitemap Membership Filtering for filtering behavior details.

Priority Pages and Post Type Ordering

URLs are processed in priority order:

1. Priority pages
   Specific page IDs configured as high-priority. These are warmed first.
2. Post type groups
   URLs grouped by post type, in the configured order (default: pages first).
3. Other URLs
   Taxonomy archives, unclassified URLs, and everything else.

Within each tier, if a multilingual plugin is active, URLs in the default language are warmed before other language variants.

Manual Exclusions

URLs listed in the manual exclusions field are removed from the warmup queue before processing begins. This applies to both targeted and full warmup runs. URLs are canonicalized before comparison.

Pacing

Two pacing modes are available.

• Auto mode uses server response telemetry to dynamically adjust batch size and timing.
• Manual mode uses fixed values for pages per batch, throttle delay, and max batch seconds. Auto mode is recommended for most sites.

See: Cache Warmup → Batch Execution and Pacing for operational details.

Logging

Run history is stored in a custom database table with configurable retention. Old entries are cleaned up daily via WP-Cron.

See: Cache Warmup → Logging and Run History for details.

Warmup Triggers

Targeted Warmup

Targeted warmup processes specific URLs after content changes. Triggers include:

• Cache Invalidator emission
  URLs received via the ekesto_ci_invalidation_urls action. This is the primary targeted warmup path.
• Post save
  When a public post is saved and qualifies as a frontend target, its canonical permalink is warmed. Revisions, autosaves, and editor-only structural entities are skipped.

Targeted URLs are validated against sitemap membership before enqueueing to prevent warming non-public content.

Editor-only entities (for example block templates, template parts, reusable components, or builder presentation templates) are excluded even if they expose queryable URLs.

Full Warmup

Full warmup processes all URLs from configured sitemaps. Triggers include:

• Cache adapter purge-all
  When the active cache plugin flushes all cache (e.g., via its admin UI). Debounced to shutdown to coalesce multiple hooks.
• Core/plugin/theme updates
  After upgrader_process_complete fires, a deferred maintenance warmup is scheduled.
• Plugin activation/deactivation
  Treated as maintenance events.
• Theme switch
  Treated as a maintenance event.

Full warmup uses the full run restart policy (Policy B): if a full run is already active and a new full trigger fires, the current run is finalized as restarted and a new run begins with a fresh URL list.

Upgrade window suppression: After maintenance triggers, purge-all hooks are suppressed for 30 seconds to prevent redundant full warmups from update-triggered cache flushes.

Maintenance Warmup

Maintenance events (updates, plugin activation, theme switches) defer warmup by 15 seconds via a dedicated WP-Cron hook. This separates warmup from the updater process, which may block.

Manual Warmup

The Trigger full cache refresh action in the Warmup settings purges the cache first, then all sitemap URLs are warmed in background batches via WP-Cron.

Trigger full cache refresh depends on WP-Cron for execution. The warmup starts when WP-Cron next fires, not at the exact moment the button is pressed.

Single URL Warmup

Individual URL warmup is triggered by save_post for eligible public content. The single URL is either:

• Merged into an active run (at the current processing position for priority treatment), or
• Started as a new targeted warmup run if no run is active.

Operational summary: Full runs process all sitemap URLs. Targeted runs process specific invalidated URLs. New URLs merge into active runs without duplication.

Queue System

A persistent queue stored in WordPress options tracks the state of each warmup run.

Queue State and Modes

The queue operates in two modes:

• Full mode
  Processing all URLs from sitemaps. Typically thousands of URLs.
• Single mode
  Processing one or more targeted URLs. Typically a small set.

Queue state includes: active flag, unique run ID, mode, trigger source, URL list, current processing position, warmed/failed counters, and last activity timestamp.

Only URLs that pass frontend eligibility checks enter the queue. Editor-only entities and structural builder content are filtered before enqueueing to prevent warming non-frontend URLs.

URL Merging and Prioritization

When an eligible targeted URL arrives during an active run:

• During a full run: The URL is inserted at the current processing position. If the URL already exists later in the queue, it is moved forward. This provides priority treatment without duplicating work.
• During a single run: The URL is merged with deduplication.

URLs are deduplicated at enqueue time. The max URLs per run cap is enforced during merging — excess URLs are dropped.

Run Restart Behavior

Full run restart policy (Policy B):

• A new full trigger while a full run is active finalizes the current run as restarted and begins a new run.
• A new full trigger while a single run is active also finalizes and restarts.
• If the new full trigger produces an identical URL list to the active run, the restart is skipped (deduplication).

Stale Run Recovery

If a run shows no activity for longer than the stale run threshold (default: 15 minutes), it is marked as “failed” and the queue is reset. This prevents stuck runs from blocking future warmups.

Stale recovery is checked before new enqueue operations.

Operational summary: The queue ensures ordered, deduplicated execution. New URLs merge into active runs automatically. Stale runs are recovered to prevent blocking.

Batch Execution and Pacing

Each WP-Cron invocation processes one batch of URLs. After a batch completes, the next batch is scheduled.

Adaptive Auto-Pacing

When pacing mode is set to auto, batch size adjusts based on server response telemetry:

• Bootstrap phase (fewer than 30 response time samples): Conservative settings
  10 pages per batch, 30-second max.
• Telemetry phase (30+ samples): Computes the p90 response time from a rolling window of up to 200 samples. Safe batch size is calculated as floor(usable_seconds / p90_seconds), clamped to 1–100.

Usable seconds are derived from the server’s max_execution_time at 80% capacity. Auto-pacing adapts to the server’s actual performance characteristics over time.

Operator tip:
Auto pacing is the recommended starting point for most sites. Switch to manual only if your host limits WP-Cron execution time or you need precise control over request rate.

Manual Pacing

When pacing mode is set to manual, the configured pages per batch, throttle seconds, and max batch seconds values are used directly.

WP-Cron Timing

Batch execution is scheduled via WP-Cron single events:

• First batch: scheduled 5 seconds after enqueue.
• Subsequent batches: scheduled 60 seconds after the previous batch completes.

After scheduling, a cron kick is attempted via spawn_cron() or a non-blocking loopback request.

Operational summary: Auto pacing adapts to your server automatically. Manual pacing gives direct control. Both depend on WP-Cron for batch scheduling.

See: Cache Warmup → Batch Execution and Pacing → WP-Cron Timing for more details.

See: Troubleshooting → WP-Cron Not Running if batches are not executing on schedule.

Sitemap Membership Filtering

Targeted warmup URLs are validated for frontend eligibility and cached sitemap membership before warmup.

URLs not present in any configured sitemap are typically filtered out. This prevents warming non-public content (draft previews, admin URLs, non-canonical URLs).

URLs representing editor infrastructure (for example templates, reusable components, or builder presentation documents) are excluded before sitemap checks.

Membership behavior:

• Sitemap membership is prepared automatically in the background
• Validation uses a prebuilt sitemap index and does not trigger live sitemap requests
• Filtering is deterministic and does not depend on timing or recent activity
• Changes to content or sitemap configuration automatically refresh membership in the background

Matching strategy:

• Exact URL match
• Trailing slash variants (for URLs without query strings)
• Host + path membership keys (scheme-insensitive)

Operator tip:
If expected URLs are not being warmed, verify they appear in your sitemap. Membership filtering is the most common reason for skipped URLs.

See: Troubleshooting → URLs Not Warming if expected URLs are being filtered out.

Settings Reference

Settings are organized by tab and panel, matching the plugin’s admin UI.

Warmup Tab

General

• Automatic warmup — Automatically rebuilds cache after content changes, targeted invalidation, and cache purges. Warmup runs in batches via WP-Cron.
• Trigger full cache refresh — Purges the entire cache and queues a full warmup for all sitemap URLs. Execution happens in background batches depending on WP-Cron timing.

Sitemaps

• Sitemap URL(s) — One URL per line. Sitemap indexes are supported. Used for full warmup URL resolution and sitemap membership filtering of targeted URLs.
• Manual URL Exclusions — URLs to skip during warmup (one per line), even if they appear in your sitemap.

Priorities Tab

Warmup Priorities

Controls the order in which URLs are warmed during a full warmup. Post types are detected from your sitemap — drag to reorder.

1. Priority pages (see below)
2. Post types in configured order
3. Remaining URLs (archives, unclassified)

With a multilingual plugin active, default-language URLs are warmed first within each group.

Priority Pages

Select pages to warm first in every full warmup run, before all post type groups. Use for your most important landing pages.

Search with Shift + F (supports fuzzy search).

Log Tab

Recent runs

The button Run Next Warmup Batch executes the next queued warmup batch immediately.

Useful if WP-Cron is delayed or disabled.

The run history table shows recent warmup runs:

Log settings

Log retention — Days to keep warmup run logs (1–365). Default: 30.

See: Logging and Run History

Diagnostics Tab

Warmup Transport

Shows the active warmup transport strategy and runtime performance. Cache Warmup uses a two-step transport:

1. Raw Brotli transport (browser-profile TLS) for realistic cache warming
2. Fallback to wp_remote_get when raw transport is unavailable

Click Check transport status to probe capabilities and telemetry.

p90 means 90% of warmup requests complete within this time. This metric drives auto-pacing batch size calculations. Requires at least 10 samples.

Connectivity

Tests whether WordPress can reach this site using its built-in HTTP API. This confirms that the fallback warmup transport can function and helps diagnose hosting restrictions that block outbound self-requests.

Click Run self-check to test. This is a manual diagnostic action — not required for normal operation.

A FAIL result typically means the server cannot make HTTP requests to itself. Common causes: firewall rules, DNS resolution issues, or hosting restrictions on loopback connections. Contact your host if this persists.

PHP limits

Shows your server’s max_execution_time. This determines how long each warmup batch can run. Auto-pacing uses ~80% of this limit as safe headroom. At least 30 seconds is recommended.

WP-Cron

One warmup batch runs per WP-Cron execution. Click Run Diagnostics to check your setup:

If DISABLE_WP_CRON is true, set up a server cron to call wp-cron.php every 1–5 minutes. This is especially important on low-traffic sites where visitor-triggered cron may not fire often enough.

See: Cache Warmup → Batch Execution and Pacing → WP-Cron Timing for more details.

Advanced Tab

Warmup Engine

Controls how many URLs are processed per WP-Cron run. Each batch stops when either the URL limit or time limit is reached.

• Tuning Mode — Automatic (recommended) adjusts batch size from server response telemetry. Starts conservatively, then adapts after 30+ samples. Manual uses fixed values you set.
• Max URLs per cron run (manual) — URLs per batch. Actual count depends on response times and batch duration.
• Max batch duration (manual) — Maximum seconds a batch may run. Keep below your max_execution_time.
• Delay between requests (manual) — Seconds between each warmup request. 0 for back-to-back. Use 1–2s on shared hosting.
• Reset Tuning Data — Clears timing samples. Auto-pacing restarts with conservative limits.

User Agent

User-Agent — Custom string appended to warmup request headers. Useful for filtering warmup traffic in analytics or server logs. Leave empty for the default.

Queue Behavior

Defaults work for most setups. Override only if your hosting requires it.

• Stale run threshold — Minutes of inactivity before a run is marked stale (5–1440). Protects against stuck runs. Default: 15.
• Max queued URLs per run — Hard cap per warmup run (100–100,000). Default: 5000.

Cache Adapters

The active cache adapter is detected for two purposes:

1. Purge hook registration
   Listening for cache-wide purge events to trigger full warmups.
2. Availability check
   Warmup only runs when a cache adapter is detected.

See: How It Works → Cache Adapters for the supported adapter list.

See: Developer Reference → Cache Adapter Compatibility for adapter-specific notes and extension points.

Diagnostics

The Diagnostics tab helps verify that warmup can run correctly on your server. Check it when warmup is not progressing as expected, or after hosting changes.

Three panels cover the key areas: transport health and connectivity, PHP execution limits, and WP-Cron configuration.

See: Cache Warmup → Settings Reference → Diagnostics Tab in the Settings Reference for field descriptions.

Logging and Run History

A custom database table stores run history for all warmup activity.

Each run record includes:

• Unique run ID, trigger source, mode, status
• Start, update, and finish timestamps (UTC)
• URL counts (total, warmed, failed)
• Per-URL event details (status codes, response times, errors)

Run statuses:

Run history is cleaned up daily. Entries older than the retention period are deleted. Runs still marked “running” after 6 hours are marked “stale.”

Operational Best Practices

• Disable your cache plugin’s built-in preload if Cache Warmup is active — running both wastes server resources and can cause conflicts.
• Use a server-side cron job on low-traffic or staging sites so batches fire on schedule.
• Use auto pacing on shared hosting — it adapts to your server’s limits automatically.
• Pause warmup during bulk imports or migrations to avoid unnecessary server load.
• Set priority pages to your homepage and key landing pages — these warm first after every full purge.

Developer Extensions

Cache Warmup integrates with Cache Invalidator via the hook bridge. For extension points and customization filters, see the Developer Reference.

See: Developer Reference → Filters for available hooks and filters.

See: How It Works → The Hook Bridge for how the two plugins communicate.