Add block-based runtime caching for remote media

[pfefferle]

Fixes #2742, #2743, #2744

Proposed changes:

Introduces a dedicated Cache namespace for remote media caching with improved architecture:

• New Cache classes: Cache\Avatar, Cache\Media, Cache\Emoji - each handles type-specific caching with lazy loading via activitypub_remote_media_url filter
• Block-based runtime caching: Emoji and media are wrapped in WordPress blocks at insert time, cached lazily at render time
  • activitypub/emoji block: Wraps emoji shortcodes, renders with cached URLs
  • activitypub/image, activitypub/audio, activitypub/video blocks: Wrap remote media in posts (comments strip remote images for security)
• Audio/video support: Incoming posts with audio or video attachments now render as native <audio> and <video> elements via dedicated blocks
• CLI commands: wp activitypub cache status and wp activitypub cache clear [--type=<type>] for cache management
• Filter-first architecture: All remote media URLs pass through activitypub_remote_media_url filter, allowing CDN plugins (Jetpack Photon, Cloudflare) to intercept
• Improved security: Uses finfo for reliable MIME validation, escapes glob metacharacters, strips remote images from comments
• Lazy avatar resolution: Avatars are no longer eagerly downloaded and stored in post meta (_activitypub_avatar_url). Instead, they resolve lazily at render time through the activitypub_remote_media_url filter
• Simplified Attachments class: Incoming post attachments are no longer imported into the Media Library. Instead, remote media is cached as files in the uploads directory via the new Cache classes. The Attachments class now only handles outgoing post attachments
• Granular control: Can disable globally (ACTIVITYPUB_DISABLE_MEDIA_CACHE) or per-type via filters
• New media helper functions: is_remote_url(), process_remote_images(), process_remote_media(), and block generator functions in functions-media.php

Breaking changes:

• activitypub_store_attachments_locally filter removed — This filter controlled whether incoming post attachments were imported into the Media Library. It is replaced by the activitypub_should_cache_url and activitypub_cache_{type}_enabled filters, and the ACTIVITYPUB_DISABLE_MEDIA_CACHE constant
• _activitypub_avatar_url post meta no longer used — Avatar URLs are now resolved lazily at render time instead of being stored in post meta

Implementation Advantages

1. Block-based approach preserves original URLs — Original remote URLs are stored in block attributes, allowing cache to be cleared and regenerated without data loss. No destructive content modification.

2. Runtime rendering vs insert-time replacement — Content processing is deferred to display time. Easy to toggle between cached/uncached without re-processing existing posts. CDN plugins can intercept at render time.

3. Filter-first architecture — All remote URLs pass through activitypub_remote_media_url filter. Jetpack Photon, Cloudflare, and other CDN plugins can intercept. Plugin authors can implement custom caching strategies.

4. Lazy caching (on-demand) — Media is only cached when actually rendered. No upfront processing of all content. Reduces unnecessary disk I/O and bandwidth.

5. Separation into dedicated Cache namespace — Each cache type (Avatar, Media, Emoji) has its own class with clear responsibility boundaries. Attachments class simplified to focus only on outgoing post attachments.

6. Comment-specific handling — Comment::render_blocks() selectively renders only activitypub/* blocks. Remote images stripped from comments for security while preserving emoji.

7. CLI management commands — Built-in operational tooling with wp activitypub cache status and wp activitypub cache clear --type=<type> for visibility and control.

Block-based caching flow:

Insert time (storing content):
  Content with :emoji: shortcode  → <!-- wp:activitypub/emoji {"url":"..."} -->:emoji:<!-- /wp:... -->
  Content with <img src="...">    → <!-- wp:activitypub/image {"url":"..."} --><img><!-- /wp:... -->
  Audio attachment                → <!-- wp:activitypub/audio {"url":"..."} --><audio><!-- /wp:... -->
  Video attachment                → <!-- wp:activitypub/video {"url":"..."} --><video><!-- /wp:... -->

Render time (displaying content):
  Block render_callback → apply_filters('activitypub_remote_media_url') → cached URL in output

CLI Commands:

# Show cache status (files, size, enabled state)
wp activitypub cache status

# Show status as JSON
wp activitypub cache status --format=json

# Clear all caches
wp activitypub cache clear

# Clear specific cache type
wp activitypub cache clear --type=avatar
wp activitypub cache clear --type=media
wp activitypub cache clear --type=emoji

Storage structure:

/wp-content/uploads/activitypub/
├── actors/{actor_id}/{hash}.webp      # Avatars
├── emoji/{domain}/{hash}.webp         # Emoji by source domain
├── posts/{post_id}/{hash}.webp        # Post media
└── comments/{comment_id}/{hash}.webp  # Comment media

Other information:

• Have you written new tests for your changes, if applicable?

Testing instructions:

1. Enable the plugin and follow a remote actor with an avatar
2. Verify avatar is cached in /wp-content/uploads/activitypub/actors/
3. Create/receive a federated post with images and custom emoji
4. Verify media is cached in appropriate directories
5. Verify emoji shortcodes in post content are wrapped with blocks (check post_content in database)
6. Receive a post with audio/video attachments, verify they render as <audio>/<video> elements
7. Test CLI commands:

   wp activitypub cache status
   wp activitypub cache clear --type=avatar --yes

8. Test disabling cache via constant:

   define( 'ACTIVITYPUB_DISABLE_MEDIA_CACHE', true );

9. Run tests: npm run env-test

Changelog entry

• Automatically create a changelog entry from the details below.

Changelog Entry Details

Significance

• Patch
• Minor
• Major

Type

• Added - for new features
• Changed - for changes in existing functionality
• Deprecated - for soon-to-be removed features
• Removed - for now removed features
• Fixed - for any bug fixes
• Security - in case of vulnerabilities

Message

Add Cache namespace for remote media caching with CLI commands, block-based runtime caching, and filter-based architecture.

[Copilot]

Pull request overview

This pull request introduces a new caching system for remote media files (avatars, post media, emoji) as part of addressing issues #2742, #2743, and #2744. The changes separate caching concerns from the Attachments class into a dedicated Activitypub\Cache namespace with improved architecture, MIME validation, and filter-based lazy loading.

Changes:

• Adds new Cache namespace with abstract File class and concrete implementations (Avatar, Media, Emoji) for type-specific caching
• Implements filter-based lazy loading architecture using activitypub_remote_media_url filter, allowing CDN plugins to intercept
• Refactors Attachments class to focus solely on Media Library imports, removing direct file caching logic
• Updates Remote_Actors, Posts, Emoji, and Interactions classes to use new filter-based caching approach

Reviewed changes

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

Show a summary per file

File	Description
includes/class-cache.php	New orchestrator class for initializing cache handlers
includes/cache/class-file.php	Abstract base class providing shared caching functionality with robust MIME validation using finfo
includes/cache/class-avatar.php	Avatar caching with lazy loading via filter and automatic cleanup on actor delete
includes/cache/class-media.php	Post/comment media caching with hook-based processing and CDN filter support
includes/cache/class-emoji.php	Emoji caching using filename-based hashing for backwards compatibility
includes/class-attachments.php	Refactored to focus on Media Library imports, removing direct file caching
includes/class-emoji.php	Updated to use filter-based caching and allow remote URLs when caching disabled
includes/collection/class-remote-actors.php	Simplified avatar handling using lazy caching via filter
includes/collection/class-posts.php	Updated to pass attachment URLs to cache via meta for hook-time processing
includes/collection/class-interactions.php	Minor comment updates for emoji handling
includes/constants.php	Added ACTIVITYPUB_DISABLE_REMOTE_CACHE constant
activitypub.php	Replaced Attachments::init() with Cache::init()
tests/*	Comprehensive test coverage for all new cache classes and updated behavior

[pfefferle]

@jeherve how is jetpacks photon caching remote images? is this done on runtime?

[Copilot]

Pull request overview

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

[jeherve]

This tests well overall. I played with the CLI commands, checked cached posts, emoji, ap_posts, and actors. Most of it seems to work well. I only have 2 notes.

---

I tried trashing, then deleting an ap_post, but the cached image in that post remained available in the activitypub/ap_posts directory. This works well for newer posts in the activitypub/posts directory though ; the cache directory does get deleted there.

[pfefferle]

@jeherve activitypub/ap_posts was the old caching and because the old caching directly replaced the URL in the HTML, this folder can't be easily removed (yet).