Make the Bluesky appview host filterable (#159)

Co-authored-by: Matthias Pfefferle <pfefferle@users.noreply.github.com>

Author: jeherve

.github/changelog/add-filterable-appview-host

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Add filters so links to Bluesky can point at an alternative AT Protocol appview, including ones hosted on a subdomain or subpath.

AGENTS.md

@@ -72,6 +72,8 @@ Text domain: always `'atmosphere'`.
 
 **MUST** use `use` imports for cross-namespace references — no inline `\Namespace\Class`.
 
+**MUST** build any front-end-displayed Bluesky/appview web link (`profile`, `post`, `hashtag`, `mention`) through `Atmosphere\appview_url( $path, $context )` in `includes/functions.php` — never hardcode `https://bsky.app/...`. The helper centralizes the host and makes it filterable (`atmosphere_appview_host` / `atmosphere_appview_url`). Keep escaping at the call site (`\esc_url()` for HTML, `\esc_url_raw()` for storage); the helper returns an unescaped URL on purpose. This applies to display links only, not to AT Protocol records being published.
+
 ## Autoloading
 
 Uses the custom `Atmosphere\Autoloader` in `includes/class-autoloader.php`, which respects WordPress filename conventions (`class-foo.php`, lowercase, hyphenated). `composer.json` declares an empty `autoload` block — Composer is only used for dev tooling (PHPUnit, PHPCS, Changelogger). Helper functions in `includes/functions.php` are loaded via a direct `require_once` from `atmosphere.php`.

docs/developer-docs.md

@@ -40,12 +40,68 @@ ATmosphere exposes a small set of filters and actions for plugins to extend beha
 | `atmosphere_should_sync_reply` | filter | Customise which inbound Bluesky replies become WordPress comments. |
 | `atmosphere_transform_bsky_post` | filter | Mutate the Bluesky post record before write. |
 | `atmosphere_transform_document` | filter | Mutate the document record before write. |
+| `atmosphere_appview_host` | filter | Point Bluesky web links at an alternative AT Protocol appview (host or subpath). |
+| `atmosphere_appview_url` | filter | Rewrite the whole assembled appview link, including its route. |
 | `atmosphere_publish_post_result` | action | React to a post-publish outcome (success or `WP_Error`). |
 | `atmosphere_publish_comment_result` | action | React to a comment-publish outcome. |
 | `atmosphere_reaction_synced` | action | React when a Bluesky reaction is stored as a WordPress comment. |
 
 When adding a new public hook, mark its `@since` tag as `unreleased` — the release script rewrites it (see [Release Process → Marking Unreleased Code](release-process.md#marking-unreleased-code)).
 
+### Pointing Bluesky links at another appview
+
+Rendered links to Bluesky (profiles, hashtags, mentions, posts) default to the `bsky.app` web appview. Two filters let you redirect them, depending on how much you need to change.
+
+Both filters pass up to three arguments. As with any WordPress filter, register with `$accepted_args = 3` if your callback needs `$path` and `$context`:
+
+- `$path` — the path being built, e.g. `profile/<did>` or `hashtag/<tag>`.
+- `$context` — array with the available parts: `type` (one of `profile`, `post`, `mention`, `hashtag`), `did`, `handle`, `rkey`, `tag`.
+
+#### `atmosphere_appview_host` — swap the host (or subpath)
+
+Use this when the alternative appview mirrors bsky.app's routes (`/profile/...`, `/hashtag/...`) and you only need to change where they live. The first argument is the default host, `'bsky.app'`.
+
+The returned value can be a bare host, a host on a subdomain, or a host with a path prefix, with or without a scheme or trailing slash — it's normalized before use, so an appview hosted on a subpath works cleanly:
+
+```php
+// Bare host.
+add_filter( 'atmosphere_appview_host', fn() => 'deer.social' );
+
+// Appview living on a subpath: yields https://something.social/atblue/profile/<did>.
+add_filter( 'atmosphere_appview_host', fn() => 'something.social/atblue' );
+
+// Route by context: send profiles elsewhere, keep hashtags on bsky.app.
+add_filter(
+	'atmosphere_appview_host',
+	function ( $host, $path, $context ) {
+		return 'hashtag' === ( $context['type'] ?? '' ) ? $host : 'deer.social';
+	},
+	10,
+	3
+);
+```
+
+#### `atmosphere_appview_url` — rewrite the whole link
+
+Use this when the appview's routes differ from bsky.app's — for example `/account/<did>` instead of `/profile/<did>`, or a custom hashtag route. The first argument is the fully assembled URL (after the host filter has run); rebuild it from `$context` and return a complete URL:
+
+```php
+// Custom profile route: /account/<did> instead of /profile/<did>.
+add_filter(
+	'atmosphere_appview_url',
+	function ( $url, $path, $context ) {
+		if ( 'mention' === ( $context['type'] ?? '' ) || 'profile' === ( $context['type'] ?? '' ) ) {
+			return 'https://my.appview/account/' . ( $context['did'] ?? $context['handle'] ?? '' );
+		}
+		return $url;
+	},
+	10,
+	3
+);
+```
+
+Of note: links rendered on the fly (facet mentions, hashtags, and the "View on Bluesky" link) pick up the filters on every render, so changing them updates immediately. The author and source links stored on synced reaction comments are resolved once at sync time, so they keep whichever host was in effect when the comment was synced.
+
 ## Extending Content Formats
 
 The `site.standard.document` record's `content` field is a singular open union of typed content objects (see [`docs/content-formats.md`](content-formats.md)). ATmosphere ships built-in parsers for HTML, Markpub, Leaflet, and pckt formats, and integrations can register additional parsers.

docs/php-coding-standards.md

@@ -223,6 +223,8 @@ use function Atmosphere\is_connected;
 \apply_filters( 'atmosphere_backfill_query_chunk_size',   500 );
 \apply_filters( 'atmosphere_oauth_redirect_uri',          $uri );
 \apply_filters( 'atmosphere_client_metadata',             $metadata );
+\apply_filters( 'atmosphere_appview_host',                'bsky.app', $path, $context ); // Host/subpath for appview web links; normalized; $context keys: type|did|handle|rkey|tag.
+\apply_filters( 'atmosphere_appview_url',                 $url, $path, $context );        // Whole assembled appview link; rewrite the route from $context.
 ```
 
 **Actions:**

includes/class-atmosphere.php

@@ -1434,11 +1434,12 @@ public function register_share_status_field(): void {
 	}
 
 	/**
-	 * Build the bsky.app web URL for one of our own post AT-URIs.
+	 * Build the appview web URL for one of our own post AT-URIs.
 	 *
 	 * `at://<did>/app.bsky.feed.post/<rkey>` →
-	 * `https://bsky.app/profile/<did>/post/<rkey>`. bsky.app resolves the
-	 * DID form, so no handle lookup is needed.
+	 * `https://<appview-host>/profile/<did>/post/<rkey>`. The appview resolves
+	 * the DID form, so no handle lookup is needed. The host defaults to
+	 * `bsky.app` and is filterable via `atmosphere_appview_host`.
 	 *
 	 * @param string $uri AT-URI from `Post::META_URI`.
 	 * @return string Web URL, or '' when the URI shape is unexpected.
@@ -1448,7 +1449,16 @@ private static function bsky_web_url_from_uri( string $uri ): string {
 			return '';
 		}
 
-		return \esc_url_raw( 'https://bsky.app/profile/' . $matches['did'] . '/post/' . $matches['rkey'] );
+		return \esc_url_raw(
+			appview_url(
+				'profile/' . $matches['did'] . '/post/' . $matches['rkey'],
+				array(
+					'type' => 'post',
+					'did'  => $matches['did'],
+					'rkey' => $matches['rkey'],
+				)
+			)
+		);
 	}
 
 	/**

includes/class-reaction-sync.php

@@ -725,7 +725,15 @@ private static function insert_reaction(
 			'comment_post_ID'      => $post_id,
 			'comment_parent'       => $comment_parent,
 			'comment_author'       => $author_name,
-			'comment_author_url'   => \esc_url_raw( 'https://bsky.app/profile/' . \rawurlencode( $author_handle ) ),
+			'comment_author_url'   => \esc_url_raw(
+				appview_url(
+					'profile/' . \rawurlencode( $author_handle ),
+					array(
+						'type'   => 'profile',
+						'handle' => $author_handle,
+					)
+				)
+			),
 			'comment_author_email' => '',
 			'comment_author_IP'    => '',
 			'comment_content'      => \wp_kses_post( $content ),
@@ -873,10 +881,11 @@ private static function resolve_author( string $did ): array {
 	}
 
 	/**
-	 * Build the https://bsky.app/... web URL for a given AT-URI + handle.
+	 * Build the appview web URL for a given AT-URI + handle.
 	 *
-	 * Only app.bsky.feed.post records have a corresponding bsky.app
-	 * web page; like and repost rkeys don't, so those return ''.
+	 * Only app.bsky.feed.post records have a corresponding appview web
+	 * page; like and repost rkeys don't, so those return ''. The host
+	 * defaults to `bsky.app` and is filterable via `atmosphere_appview_host`.
 	 *
 	 * @param string $at_uri AT-URI.
 	 * @param string $handle Bluesky handle.
@@ -894,7 +903,16 @@ private static function build_bsky_web_url( string $at_uri, string $handle ): st
 			return '';
 		}
 
-		return \esc_url_raw( 'https://bsky.app/profile/' . \rawurlencode( $handle ) . '/post/' . $rkey );
+		return \esc_url_raw(
+			appview_url(
+				'profile/' . \rawurlencode( $handle ) . '/post/' . $rkey,
+				array(
+					'type'   => 'post',
+					'handle' => $handle,
+					'rkey'   => $rkey,
+				)
+			)
+		);
 	}
 
 	/**

includes/functions.php

@@ -45,6 +45,115 @@ function build_at_uri( string $did, string $collection, string $rkey ): string {
 	return "at://{$did}/{$collection}/{$rkey}";
 }
 
+/**
+ * Build a web URL pointing at an AT Protocol appview.
+ *
+ * Returns an UNESCAPED URL. Callers MUST escape at the point of use
+ * (\esc_url() for HTML output, \esc_url_raw() for storage/redirects), as
+ * late as possible and in the right context.
+ *
+ * @param string $path    Path after the host, with no leading slash, e.g.
+ *                        'profile/<did>/post/<rkey>' or 'hashtag/<tag>'.
+ *                        Callers are responsible for encoding path segments.
+ * @param array  $context Optional parts the caller has on hand. Recognised
+ *                        keys: 'type' (profile|post|mention|hashtag), 'did',
+ *                        'handle', 'rkey', 'tag'.
+ * @return string Unescaped URL, e.g. 'https://bsky.app/profile/<did>'.
+ */
+function appview_url( string $path, array $context = array() ): string {
+	/**
+	 * Filters the base of AT Protocol appview web links.
+	 *
+	 * The base is everything before the path: scheme, host, and an optional
+	 * path prefix. The returned value may be a bare host ('deer.social'), a
+	 * host with a path prefix ('something.social/atblue'), and may include a
+	 * scheme and/or trailing slash — it is normalized before use, so appviews
+	 * hosted on a subdomain or a subpath work cleanly. Defaults to 'bsky.app',
+	 * the Bluesky appview. To rewrite the path itself (e.g. a custom route),
+	 * use the {@see 'atmosphere_appview_url'} filter instead.
+	 *
+	 * @since unreleased
+	 *
+	 * @param string $host    Default appview host ('bsky.app').
+	 * @param string $path    Path being built, e.g. 'profile/<did>'.
+	 * @param array  $context Available parts: type, did, handle, rkey, tag.
+	 */
+	$base = \apply_filters( 'atmosphere_appview_host', 'bsky.app', $path, $context );
+
+	$url = appview_base_url( $base ) . '/' . \ltrim( $path, '/' );
+
+	/**
+	 * Filters the fully assembled AT Protocol appview web URL.
+	 *
+	 * Use this to rewrite the entire URL — including the route, e.g.
+	 * '/account/<did>' instead of '/profile/<did>', or a custom hashtag
+	 * route — by rebuilding it from the parts in $context. Return a complete
+	 * URL; it is escaped by the caller, not here.
+	 *
+	 * @since unreleased
+	 *
+	 * @param string $url     Assembled URL, e.g. 'https://bsky.app/profile/<did>'.
+	 * @param string $path    Path that was appended, e.g. 'profile/<did>'.
+	 * @param array  $context Available parts: type, did, handle, rkey, tag.
+	 */
+	return \apply_filters( 'atmosphere_appview_url', $url, $path, $context );
+}
+
+/**
+ * Normalize a filtered appview base into a clean 'scheme://host[:port][/prefix]'.
+ *
+ * Accepts a bare host, a host with a path prefix, with or without a scheme or
+ * trailing slash, and rebuilds it without empty or doubled segments. The host is
+ * lower-cased and the scheme is clamped to http/https. An empty value falls back
+ * to 'https://bsky.app' silently; a non-empty value that yields no host falls
+ * back too, but flags `_doing_it_wrong` since the callback returned something
+ * unusable.
+ *
+ * These URLs are display links — rendered for users to click, or stored as
+ * comment author/source links — and are always escaped at the call site. They
+ * are never fetched server-side, so there is no SSRF surface, and IP-literal or
+ * localhost hosts are intentionally allowed for self-hosted appviews. The value
+ * comes from a site-owner filter callback, not from external request input.
+ *
+ * @param string $base Filtered base value, e.g. 'something.social/atblue/'.
+ * @return string Clean base with no trailing slash, e.g. 'https://something.social/atblue'.
+ */
+function appview_base_url( string $base ): string {
+	$base = \trim( $base );
+
+	// An empty value just means "use the default appview" — nothing to flag.
+	if ( '' === $base ) {
+		return 'https://bsky.app';
+	}
+
+	// Ensure a scheme so wp_parse_url splits the host from any path prefix.
+	if ( ! \preg_match( '#^[a-z][a-z0-9+.-]*://#i', $base ) ) {
+		$base = 'https://' . \ltrim( $base, '/' );
+	}
+
+	$parts = \wp_parse_url( $base );
+	$host  = \is_array( $parts ) ? \strtolower( $parts['host'] ?? '' ) : '';
+
+	if ( '' === $host ) {
+		\_doing_it_wrong(
+			__FUNCTION__,
+			\esc_html__( 'atmosphere_appview_host must return a host (optionally with a scheme and path prefix); falling back to bsky.app.', 'atmosphere' ),
+			'unreleased'
+		);
+		return 'https://bsky.app';
+	}
+
+	$scheme = \strtolower( $parts['scheme'] ?? 'https' );
+	if ( 'http' !== $scheme && 'https' !== $scheme ) {
+		$scheme = 'https';
+	}
+
+	$port   = isset( $parts['port'] ) ? ':' . $parts['port'] : '';
+	$prefix = \trim( $parts['path'] ?? '', '/' );
+
+	return $scheme . '://' . $host . $port . ( '' !== $prefix ? '/' . $prefix : '' );
+}
+
 /**
  * Decode entities, strip HTML, normalise whitespace.
  *

includes/transformer/class-facet.php

@@ -13,6 +13,7 @@
 \defined( 'ABSPATH' ) || exit;
 
 use function Atmosphere\get_connection;
+use function Atmosphere\appview_url;
 
 /**
  * Extracts facets from plain text.
@@ -198,16 +199,36 @@ private static function render_feature( array $feature, string $display ): strin
 			case 'app.bsky.richtext.facet#mention':
 				/*
 				 * The mention facet only carries the DID, so link by DID.
-				 * bsky.app/profile/{did} resolves the same as the handle
-				 * form used elsewhere in Reaction_Sync.
+				 * The appview's /profile/{did} resolves the same as the
+				 * handle form used elsewhere in Reaction_Sync.
 				 */
 				$did  = $feature['did'] ?? '';
-				$href = '' === $did ? '' : \esc_url( 'https://bsky.app/profile/' . $did );
+				$href = '' === $did
+					? ''
+					: \esc_url(
+						appview_url(
+							'profile/' . $did,
+							array(
+								'type' => 'mention',
+								'did'  => $did,
+							)
+						)
+					);
 				break;
 
 			case 'app.bsky.richtext.facet#tag':
 				$tag  = $feature['tag'] ?? '';
-				$href = '' === $tag ? '' : \esc_url( 'https://bsky.app/hashtag/' . \rawurlencode( $tag ) );
+				$href = '' === $tag
+					? ''
+					: \esc_url(
+						appview_url(
+							'hashtag/' . \rawurlencode( $tag ),
+							array(
+								'type' => 'hashtag',
+								'tag'  => $tag,
+							)
+						)
+					);
 				break;
 
 			default: