Add local caching for remote actor avatars

Cache avatars from remote actors locally to reduce external dependencies
and improve load times:

- Add actors directory constant and cache_actor_avatar method
- Download and optimize avatars on actor create/update
- Store local URL in _activitypub_avatar_url meta
- Track remote URL in _activitypub_remote_avatar_url for change detection
- Only re-download when remote URL changes
- Clean up avatar files when actor is deleted
- Fall back to remote URL if local caching fails

Author: pfefferle

includes/class-attachments.php

@@ -8,6 +8,7 @@
 namespace Activitypub;
 
 use Activitypub\Collection\Posts;
+use Activitypub\Collection\Remote_Actors;
 
 /**
  * Attachments processor class.
@@ -27,6 +28,13 @@ class Attachments {
 	 */
 	public static $comments_dir = '/activitypub/comments/';
 
+	/**
+	 * Directory for storing actor avatar files.
+	 *
+	 * @var string
+	 */
+	public static $actors_dir = '/activitypub/actors/';
+
 	/**
 	 * Maximum width for imported images.
 	 *
@@ -39,6 +47,20 @@ class Attachments {
 	 */
 	public static function init() {
 		\add_action( 'before_delete_post', array( self::class, 'delete_ap_posts_directory' ) );
+		\add_action( 'before_delete_post', array( self::class, 'delete_actor_avatar_on_delete' ) );
+	}
+
+	/**
+	 * Delete the actor avatar directory when an actor is deleted.
+	 *
+	 * @param int $post_id The post ID.
+	 */
+	public static function delete_actor_avatar_on_delete( $post_id ) {
+		if ( Remote_Actors::POST_TYPE !== \get_post_type( $post_id ) ) {
+			return;
+		}
+
+		self::delete_actor_avatar_files( $post_id );
 	}
 
 	/**
@@ -933,4 +955,101 @@ private static function get_files_gallery_block( $files ) {
 
 		return $gallery;
 	}
+
+	/**
+	 * Cache a remote actor's avatar locally.
+	 *
+	 * Downloads the avatar image, optimizes it, and stores it in the actors directory.
+	 * Returns the local URL for the cached avatar.
+	 *
+	 * @param string $avatar_url The remote avatar URL.
+	 * @param int    $actor_id   The local actor post ID.
+	 *
+	 * @return string|false The local avatar URL on success, false on failure.
+	 */
+	public static function cache_actor_avatar( $avatar_url, $actor_id ) {
+		if ( empty( $avatar_url ) || ! \filter_var( $avatar_url, FILTER_VALIDATE_URL ) ) {
+			return false;
+		}
+
+		if ( ! \function_exists( 'download_url' ) ) {
+			require_once ABSPATH . 'wp-admin/includes/file.php';
+		}
+
+		// Download remote avatar.
+		$tmp_file = \download_url( $avatar_url );
+
+		if ( \is_wp_error( $tmp_file ) ) {
+			return false;
+		}
+
+		// Verify the temp file exists and is readable.
+		if ( ! \file_exists( $tmp_file ) || ! \is_readable( $tmp_file ) || 0 === \filesize( $tmp_file ) ) {
+			\wp_delete_file( $tmp_file );
+			return false;
+		}
+
+		// Get storage paths for actor avatars.
+		$upload_dir = \wp_upload_dir();
+		$actor_dir  = $upload_dir['basedir'] . self::$actors_dir . $actor_id;
+		$actor_url  = $upload_dir['baseurl'] . self::$actors_dir . $actor_id;
+
+		// Create directory if it doesn't exist.
+		\wp_mkdir_p( $actor_dir );
+
+		// Delete existing avatar files for this actor.
+		self::delete_actor_avatar_files( $actor_id );
+
+		// Generate file name from URL.
+		$url_path  = \wp_parse_url( $avatar_url, PHP_URL_PATH );
+		$file_name = \sanitize_file_name( \basename( $url_path ) );
+
+		// Ensure file has an extension.
+		if ( ! \pathinfo( $file_name, PATHINFO_EXTENSION ) ) {
+			$file_name .= '.jpg';
+		}
+
+		$file_path = $actor_dir . '/' . $file_name;
+
+		// Initialize filesystem.
+		\WP_Filesystem();
+		global $wp_filesystem;
+
+		// Move file to destination.
+		if ( ! $wp_filesystem->move( $tmp_file, $file_path, true ) ) {
+			\wp_delete_file( $tmp_file );
+			return false;
+		}
+
+		// Optimize the avatar image.
+		$optimized = self::optimize_image( $file_path );
+		if ( $optimized['changed'] ) {
+			$file_path = $optimized['path'];
+			$file_name = \basename( $file_path );
+		}
+
+		return $actor_url . '/' . $file_name;
+	}
+
+	/**
+	 * Delete all avatar files for an actor.
+	 *
+	 * @param int $actor_id The actor post ID.
+	 */
+	public static function delete_actor_avatar_files( $actor_id ) {
+		$upload_dir = \wp_upload_dir();
+		$actor_dir  = $upload_dir['basedir'] . self::$actors_dir . $actor_id;
+
+		if ( ! \is_dir( $actor_dir ) ) {
+			return;
+		}
+
+		require_once ABSPATH . 'wp-admin/includes/file.php';
+
+		\WP_Filesystem();
+		global $wp_filesystem;
+
+		// Delete the entire actor directory.
+		$wp_filesystem->delete( $actor_dir, true );
+	}
 }

includes/collection/class-remote-actors.php

@@ -8,6 +8,7 @@
 namespace Activitypub\Collection;
 
 use Activitypub\Activity\Actor;
+use Activitypub\Attachments;
 use Activitypub\Http;
 use Activitypub\Sanitize;
 use Activitypub\Webfinger;
@@ -111,6 +112,11 @@ public static function create( $actor ) {
 			\kses_init_filters();
 		}
 
+		// Cache the actor's avatar locally.
+		if ( ! \is_wp_error( $post_id ) ) {
+			self::cache_avatar( $post_id, $actor );
+		}
+
 		return $post_id;
 	}
 
@@ -158,6 +164,11 @@ public static function update( $post, $actor ) {
 			\kses_init_filters();
 		}
 
+		// Re-cache the actor's avatar if it has changed.
+		if ( ! \is_wp_error( $post_id ) ) {
+			self::cache_avatar( $post_id, $actor );
+		}
+
 		return $post_id;
 	}
 
@@ -531,12 +542,6 @@ private static function prepare_custom_post_type( $actor ) {
 			'_activitypub_acct'  => $webfinger,
 		);
 
-		// Store avatar URL if available.
-		$icon = object_to_uri( $actor->get_icon() );
-		if ( $icon ) {
-			$meta_input['_activitypub_avatar_url'] = $icon;
-		}
-
 		return array(
 			'guid'         => \esc_url_raw( $actor->get_id() ),
 			'post_title'   => \wp_strip_all_tags( \wp_slash( $actor->get_name() ?: $actor->get_preferred_username() ) ),
@@ -653,6 +658,9 @@ public static function get_acct( $id ) {
 	/**
 	 * Get the avatar URL for a remote actor.
 	 *
+	 * Returns the locally cached avatar URL if available, otherwise falls back
+	 * to the default avatar.
+	 *
 	 * @param int $id The ID of the remote actor post.
 	 *
 	 * @return string The avatar URL or empty string if not found.
@@ -663,7 +671,7 @@ public static function get_avatar_url( $id ) {
 			return $avatar_url;
 		}
 
-		// If not found in meta, try to extract from post_content JSON.
+		// If not found in meta, try to extract from post_content JSON and cache it.
 		$post = \get_post( $id );
 		if ( ! $post || empty( $post->post_content ) ) {
 			return '';
@@ -677,10 +685,51 @@ public static function get_avatar_url( $id ) {
 			return $default_avatar_url;
 		}
 
-		$avatar_url = object_to_uri( $actor_data['icon'] );
-		// Cache it in meta for next time.
+		// Try to cache the avatar locally.
+		$remote_avatar_url = object_to_uri( $actor_data['icon'] );
+		$local_url         = Attachments::cache_actor_avatar( $remote_avatar_url, $id );
+
+		$avatar_url = $local_url ? $local_url : $remote_avatar_url;
 		\update_post_meta( $id, '_activitypub_avatar_url', \esc_url_raw( $avatar_url ) );
 
 		return $avatar_url;
 	}
+
+	/**
+	 * Cache a remote actor's avatar locally.
+	 *
+	 * Downloads the avatar image, optimizes it (resize/WebP), and stores it locally.
+	 * Only re-downloads if the remote avatar URL has changed.
+	 *
+	 * @param int   $post_id The actor post ID.
+	 * @param Actor $actor   The actor object.
+	 */
+	private static function cache_avatar( $post_id, $actor ) {
+		$remote_avatar_url = object_to_uri( $actor->get_icon() );
+
+		if ( empty( $remote_avatar_url ) ) {
+			// No avatar to cache, clean up any existing cached avatar.
+			Attachments::delete_actor_avatar_files( $post_id );
+			\delete_post_meta( $post_id, '_activitypub_avatar_url' );
+			\delete_post_meta( $post_id, '_activitypub_remote_avatar_url' );
+			return;
+		}
+
+		// Check if avatar URL has changed since last cache.
+		$stored_remote_url = \get_post_meta( $post_id, '_activitypub_remote_avatar_url', true );
+		if ( $stored_remote_url === $remote_avatar_url ) {
+			// Remote URL hasn't changed, skip re-downloading.
+			return;
+		}
+
+		// Store the remote URL for future change detection.
+		\update_post_meta( $post_id, '_activitypub_remote_avatar_url', \esc_url_raw( $remote_avatar_url ) );
+
+		// Download and cache the avatar locally.
+		$local_url = Attachments::cache_actor_avatar( $remote_avatar_url, $post_id );
+
+		// Store the local URL if caching succeeded, otherwise store the remote URL.
+		$avatar_url = $local_url ? $local_url : $remote_avatar_url;
+		\update_post_meta( $post_id, '_activitypub_avatar_url', \esc_url_raw( $avatar_url ) );
+	}
 }