|
| 1 | +<?php |
| 2 | +/** |
| 3 | + * Tombstone class file. |
| 4 | + * |
| 5 | + * @package Activitypub |
| 6 | + */ |
| 7 | + |
| 8 | +namespace Activitypub; |
| 9 | + |
| 10 | +use Activitypub\Activity\Base_Object; |
| 11 | + |
| 12 | +/** |
| 13 | + * ActivityPub Tombstone Class. |
| 14 | + * |
| 15 | + * Handles detection and management of tombstoned (deleted) ActivityPub resources. |
| 16 | + * A tombstone in ActivityPub represents a deleted object that was previously available. |
| 17 | + * This class provides methods to detect tombstones across various data formats including |
| 18 | + * URLs, ActivityPub objects, arrays, and WordPress error responses. |
| 19 | + * |
| 20 | + * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-tombstone |
| 21 | + */ |
| 22 | +class Tombstone { |
| 23 | + /** |
| 24 | + * HTTP status codes that indicate a tombstoned resource. |
| 25 | + * |
| 26 | + * - 404: Not Found - Resource no longer exists |
| 27 | + * - 410: Gone - Resource was intentionally removed |
| 28 | + * |
| 29 | + * @var int[] Array of HTTP status codes indicating tombstones. |
| 30 | + */ |
| 31 | + private static $codes = array( 404, 410 ); |
| 32 | + |
| 33 | + /** |
| 34 | + * Check if a tombstone exists for the given resource. |
| 35 | + * |
| 36 | + * This is the main entry point for tombstone detection. It accepts various |
| 37 | + * data types and routes them to the appropriate checking method: |
| 38 | + * - URLs (string): Checks remote or local tombstone status |
| 39 | + * - WP_Error objects: Checks for tombstone-indicating HTTP status codes |
| 40 | + * - Arrays: Checks for ActivityPub Tombstone type |
| 41 | + * - Objects: Checks for ActivityPub Tombstone type or Base_Object instances |
| 42 | + * |
| 43 | + * @param string|\WP_Error|array|object $various The resource data to check for tombstone status. |
| 44 | + * Can be a URL, error object, ActivityPub array, or object. |
| 45 | + * |
| 46 | + * @return bool True if the resource is tombstoned, false otherwise. |
| 47 | + */ |
| 48 | + public static function exists( $various ) { |
| 49 | + if ( \is_wp_error( $various ) ) { |
| 50 | + return self::exists_in_error( $various ); |
| 51 | + } |
| 52 | + |
| 53 | + if ( \is_string( $various ) ) { |
| 54 | + if ( is_same_domain( $various ) ) { |
| 55 | + return self::exists_local( $various ); |
| 56 | + } |
| 57 | + return self::exists_remote( $various ); |
| 58 | + } |
| 59 | + |
| 60 | + if ( \is_array( $various ) ) { |
| 61 | + return self::check_array( $various ); |
| 62 | + } |
| 63 | + |
| 64 | + if ( \is_object( $various ) ) { |
| 65 | + return self::check_object( $various ); |
| 66 | + } |
| 67 | + |
| 68 | + return false; |
| 69 | + } |
| 70 | + |
| 71 | + /** |
| 72 | + * Check if a remote URL is tombstoned. |
| 73 | + * |
| 74 | + * Makes an HTTP request to the remote URL with ActivityPub headers |
| 75 | + * and checks for tombstone indicators: |
| 76 | + * - HTTP 404/410 status codes |
| 77 | + * - ActivityPub Tombstone object type in response body |
| 78 | + * |
| 79 | + * @param string $url The remote URL to check for tombstone status. |
| 80 | + * |
| 81 | + * @return bool True if the remote URL is tombstoned, false otherwise. |
| 82 | + */ |
| 83 | + public static function exists_remote( $url ) { |
| 84 | + /** |
| 85 | + * Fires before checking if the URL is a tombstone. |
| 86 | + * |
| 87 | + * @param string $url The URL to check. |
| 88 | + */ |
| 89 | + \do_action( 'activitypub_pre_http_is_tombstone', $url ); |
| 90 | + |
| 91 | + $response = \wp_safe_remote_get( $url, array( 'headers' => array( 'Accept' => 'application/activity+json' ) ) ); |
| 92 | + $code = \wp_remote_retrieve_response_code( $response ); |
| 93 | + |
| 94 | + if ( in_array( (int) $code, self::$codes, true ) ) { |
| 95 | + return true; |
| 96 | + } |
| 97 | + |
| 98 | + $data = \wp_remote_retrieve_body( $response ); |
| 99 | + $data = \json_decode( $data, true ); |
| 100 | + |
| 101 | + return self::check_array( $data ); |
| 102 | + } |
| 103 | + |
| 104 | + /** |
| 105 | + * Check if a local URL is tombstoned. |
| 106 | + * |
| 107 | + * Checks against the local tombstone URL registry stored in WordPress options. |
| 108 | + * Local URLs are normalized before comparison to ensure consistent matching. |
| 109 | + * |
| 110 | + * @param string $url The local URL to check for tombstone status. |
| 111 | + * |
| 112 | + * @return bool True if the local URL is in the tombstone registry, false otherwise. |
| 113 | + */ |
| 114 | + public static function exists_local( $url ) { |
| 115 | + $urls = get_option( 'activitypub_tombstone_urls', array() ); |
| 116 | + |
| 117 | + return in_array( normalize_url( $url ), $urls, true ); |
| 118 | + } |
| 119 | + |
| 120 | + /** |
| 121 | + * Check if a WP_Error object indicates a tombstoned resource. |
| 122 | + * |
| 123 | + * Examines the error data for HTTP status codes that indicate tombstones. |
| 124 | + * This is typically used when HTTP requests return error responses. |
| 125 | + * |
| 126 | + * @param \WP_Error $wp_error The WordPress error object to examine. |
| 127 | + * |
| 128 | + * @return bool True if the error indicates a tombstoned resource, false otherwise. |
| 129 | + */ |
| 130 | + public static function exists_in_error( $wp_error ) { |
| 131 | + if ( ! \is_wp_error( $wp_error ) ) { |
| 132 | + return false; |
| 133 | + } |
| 134 | + |
| 135 | + $data = $wp_error->get_error_data(); |
| 136 | + if ( isset( $data['status'] ) && in_array( (int) $data['status'], self::$codes, true ) ) { |
| 137 | + return true; |
| 138 | + } |
| 139 | + |
| 140 | + return false; |
| 141 | + } |
| 142 | + |
| 143 | + /** |
| 144 | + * Check if an array represents an ActivityPub Tombstone object. |
| 145 | + * |
| 146 | + * Examines the array for the ActivityPub 'type' property set to 'Tombstone'. |
| 147 | + * This follows the ActivityStreams specification for tombstone objects. |
| 148 | + * |
| 149 | + * @param array|mixed $data The array data to check. Non-arrays return false. |
| 150 | + * |
| 151 | + * @return bool True if the array represents a Tombstone object, false otherwise. |
| 152 | + */ |
| 153 | + private static function check_array( $data ) { |
| 154 | + if ( ! \is_array( $data ) ) { |
| 155 | + return false; |
| 156 | + } |
| 157 | + |
| 158 | + if ( isset( $data['type'] ) && 'Tombstone' === $data['type'] ) { |
| 159 | + return true; |
| 160 | + } |
| 161 | + |
| 162 | + return false; |
| 163 | + } |
| 164 | + |
| 165 | + /** |
| 166 | + * Check if an object represents an ActivityPub Tombstone. |
| 167 | + * |
| 168 | + * Checks for tombstone indicators in objects: |
| 169 | + * - Standard objects: 'type' property set to 'Tombstone' |
| 170 | + * - Base_Object instances: Uses get_type() method to check for 'Tombstone' |
| 171 | + * |
| 172 | + * @param object|mixed $data The object data to check. Non-objects return false. |
| 173 | + * |
| 174 | + * @return bool True if the object represents a Tombstone, false otherwise. |
| 175 | + */ |
| 176 | + private static function check_object( $data ) { |
| 177 | + if ( ! \is_object( $data ) ) { |
| 178 | + return false; |
| 179 | + } |
| 180 | + |
| 181 | + if ( isset( $data->type ) && 'Tombstone' === $data->type ) { |
| 182 | + return true; |
| 183 | + } |
| 184 | + |
| 185 | + if ( $data instanceof Base_Object && 'Tombstone' === $data->get_type() ) { |
| 186 | + return true; |
| 187 | + } |
| 188 | + |
| 189 | + return false; |
| 190 | + } |
| 191 | + |
| 192 | + /** |
| 193 | + * Add a URL to the local tombstone registry. |
| 194 | + * |
| 195 | + * "Buries" a URL by adding it to the local tombstone URL registry. |
| 196 | + * The URL is normalized before storage and duplicates are automatically removed. |
| 197 | + * This marks the URL as tombstoned for future local checks. |
| 198 | + * |
| 199 | + * @param string $url The URL to add to the tombstone registry. |
| 200 | + * |
| 201 | + * @return void |
| 202 | + */ |
| 203 | + public static function bury( $url ) { |
| 204 | + $urls = \get_option( 'activitypub_tombstone_urls', array() ); |
| 205 | + $urls[] = normalize_url( $url ); |
| 206 | + $urls = \array_unique( $urls ); |
| 207 | + |
| 208 | + \update_option( 'activitypub_tombstone_urls', $urls ); |
| 209 | + } |
| 210 | +} |
0 commit comments