• File: link-headers.php
  • Full Path: /home/slvgwrnz/public_html/wp-content/plugins/elementor/modules/agents/components/discovery/link-headers.php
  • Date Modified: 11/09/2026 10:39 AM
  • File size: 8.83 KB
  • MIME-type: text/x-php
  • Charset: utf-8
<?php

namespace Elementor\Modules\Agents\Components\Discovery;

use Elementor\Modules\Agents\Agent_Ready_Settings;
use Elementor\Modules\Agents\Classes\Feature_Component;
use Elementor\Modules\Agents\Components\Discovery\Openapi_Spec;
use Elementor\Modules\Agents\Components\Discovery\Well_Known\Well_Known_Router;
use Elementor\Modules\Agents\Components\Readability\Markdown_Endpoint;
use Elementor\Modules\Agents\Module;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Emits RFC 8288 Link response headers on every front-end and Elementor REST
 * response, making discovery documents findable without guessing URLs.
 *
 * Site-wide (all frontend responses):
 *   Link: </llms.txt>; rel="llms-txt"; type="text/plain"
 *
 * Site-wide when the Agent discovery module is enabled:
 *   Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/json"
 *   Link: </.well-known/auth.md>; rel="service-doc"; type="text/markdown"
 *   Link: </.well-known/ard.json>; rel="ard"; type="application/json"
 *
 * On singular exposed views only:
 *   Link: <{permalink}.md>; rel="alternate"; type="text/markdown"
 *
 * When the MCP server card is active (gated by filter, see Mcp_Discovery):
 *   Link: </.well-known/mcp/server-card.json>; rel="mcp-server-card"; type="application/json"
 *
 * Relation types that are not registered in the IANA link relation registry
 * (llms-txt, mcp-server-card) are used as-is following emerging convention;
 * they will be replaced with absolute URI forms if IANA registers alternatives.
 *
 * Guards:
 *   - Skips admin, cron, feeds, and login screens.
 *   - Emits at most once per request (idempotency flag).
 *   - Scopes REST emission to /elementor/* namespaces only.
 */
class Link_Headers extends Feature_Component {

	const HOMEPAGE_MARKDOWN_PATH = '/index.md';

	const ARD_CATALOG_SLUG = 'ard.json';

	const MCP_SERVER_CARD_SLUG = 'mcp/server-card.json';

	/** @var bool Prevents duplicate emission within the same request. */
	private bool $emitted = false;

	private Markdown_Endpoint $markdown_endpoint;

	private Agent_Ready_Settings $settings;

	private Module $module;

	public function __construct( Markdown_Endpoint $markdown_endpoint, Agent_Ready_Settings $settings, Module $module ) {
		$this->markdown_endpoint = $markdown_endpoint;
		$this->settings          = $settings;
		$this->module            = $module;
	}

	public function get_id(): string {
		return 'link_headers';
	}

	public function get_layer(): string {
		return 'discovery';
	}

	public function get_required_modules(): array {
		return [
			Agent_Ready_Settings::MODULE_LLMS_TXT,
			Agent_Ready_Settings::MODULE_AGENT_DISCOVERY,
			Agent_Ready_Settings::MODULE_MARKDOWN_CONTENT,
		];
	}

	public function register(): void {
		add_action( 'send_headers', [ $this, 'emit_frontend_headers' ] );
		add_filter( 'rest_post_dispatch', [ $this, 'add_rest_headers' ], 10, 3 );
	}

	// -------------------------------------------------------------------------
	// Hooks
	// -------------------------------------------------------------------------

	/**
	 * Emit Link headers on front-end responses.
	 *
	 * Fires during the `send_headers` action, which runs after WordPress has
	 * determined the current query but before the template is loaded.
	 */
	public function emit_frontend_headers(): void {
		if ( $this->emitted || $this->should_skip_frontend() ) {
			return;
		}

		$links = $this->build_site_links();

		if ( is_singular() ) {
			$post_id = get_queried_object_id();
			$post    = $post_id ? get_post( $post_id ) : null;
			$link    = $this->build_singular_markdown_link( $post );

			if ( null !== $link ) {
				$links[] = $link;
			}
		}

		$this->send_link_headers( $links );
		$this->emitted = true;
	}

	/**
	 * Add Link headers to Elementor REST responses.
	 *
	 * Only wires onto /elementor/* routes — skips the WP REST API broadly so
	 * we don't pollute unrelated endpoints.
	 *
	 * @param \WP_HTTP_Response $response Response object.
	 * @param \WP_REST_Server   $server   REST server instance.
	 * @param \WP_REST_Request  $request  REST request object.
	 * @return \WP_HTTP_Response
	 */
	public function add_rest_headers( $response, $server, $request ) {
		if ( ! ( $response instanceof \WP_HTTP_Response ) ) {
			return $response;
		}

		if ( ! $this->is_elementor_rest_request( $request ) ) {
			return $response;
		}

		foreach ( $this->build_site_links() as $link ) {
			$response->header( 'Link', $link, false );
		}

		return $response;
	}

	// -------------------------------------------------------------------------
	// Helpers
	// -------------------------------------------------------------------------

	/**
	 * Build the site-wide Link header values (not singular-specific).
	 *
	 * @return string[]
	 */
	private function build_site_links(): array {
		$home = untrailingslashit( home_url() );

		$links = [];

		if ( $this->module->should_advertise_llms_txt() ) {
			$links[] = '<' . $home . '/llms.txt>; rel="llms-txt"; type="text/plain"';
		}

		if ( $this->settings->is_agent_discovery_enabled() ) {
			$links[] = '<' . $home . '/.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json"';
			$links[] = '<' . $home . '/.well-known/auth.md>; rel="service-doc"; type="text/markdown"';

			if ( $this->is_endpoint_active( self::ARD_CATALOG_SLUG ) ) {
				$links[] = '<' . $home . '/.well-known/ard.json>; rel="ard"; type="application/json"';
			}

			if ( $this->is_openapi_publishable() ) {
				$links[] = '<' . $home . '/openapi.json>; rel="service-desc"; type="application/json"';
			}
		}

		/**
		 * Fires when the MCP server card is available.
		 *
		 * Mcp_Discovery hooks this to `true` while the site-level Elementor MCP
		 * setting is on, which is when /.well-known/mcp/server-card.json is
		 * served. Keeping it off by default prevents pointing at a 404.
		 *
		 * @since 3.30.0
		 */
		if ( $this->settings->is_agent_discovery_enabled() && apply_filters( 'elementor/agents/link_headers/emit_mcp_card', false ) && $this->is_endpoint_active( self::MCP_SERVER_CARD_SLUG ) ) {
			$links[] = '<' . $home . '/.well-known/mcp/server-card.json>'
				. '; rel="mcp-server-card"; type="application/json"';
		}

		return $links;
	}

	private function is_endpoint_active( string $slug ): bool {
		$router = $this->module->get_component( 'well_known_router' );

		return $router instanceof Well_Known_Router
			&& isset( $router->get_active_endpoints()[ $slug ] );
	}

	private function is_openapi_publishable(): bool {
		$component = $this->module->get_component( 'openapi_spec' );

		if ( ! $component instanceof Openapi_Spec ) {
			return false;
		}

		return $component->is_publishable();
	}

	/**
	 * @param \WP_Post|null $post
	 * @return string|null
	 */
	public function build_singular_markdown_link( $post ): ?string {
		if ( ! ( $post instanceof \WP_Post ) ) {
			return null;
		}

		if ( ! $this->markdown_endpoint->is_markdown_access_allowed( $post ) ) {
			return null;
		}

		$markdown_url = $this->resolve_markdown_url( $post );

		if ( ! $markdown_url ) {
			return null;
		}

		return '<' . esc_url_raw( $markdown_url ) . '>'
			. '; rel="alternate"; type="text/markdown"';
	}

	private function resolve_markdown_url( \WP_Post $post ): ?string {
		if ( $this->is_static_front_page( $post ) ) {
			return untrailingslashit( home_url() ) . self::HOMEPAGE_MARKDOWN_PATH;
		}

		$permalink = get_permalink( $post->ID );

		return $permalink ? untrailingslashit( $permalink ) . '.md' : null;
	}

	private function is_static_front_page( \WP_Post $post ): bool {
		return 'page' === get_option( 'show_on_front' )
			&& (int) get_option( 'page_on_front' ) === $post->ID;
	}

	/**
	 * Send an array of Link values as individual Link response headers.
	 *
	 * Sends one header() call per relation so the header list remains well-formed
	 * when multiple Link values are present, and passes false as the $replace
	 * argument to avoid overwriting Link headers emitted by other code.
	 *
	 * @param string[] $links
	 */
	private function send_link_headers( array $links ): void {
		if ( headers_sent() ) {
			return;
		}

		foreach ( $links as $link ) {
			header( 'Link: ' . $link, false );
		}
	}

	/**
	 * Return true when front-end Link header emission should be skipped.
	 */
	private function should_skip_frontend(): bool {
		if ( is_admin() ) {
			return true;
		}

		if ( defined( 'DOING_CRON' ) && DOING_CRON ) {
			return true;
		}

		if ( is_feed() ) {
			return true;
		}

		// Skip the login screen (wp-login.php). is_login() landed in WP 6.1;
		// fall back to pagenow for older floors.
		if ( function_exists( 'is_login' ) && is_login() ) {
			return true;
		}

		global $pagenow;
		if ( 'wp-login.php' === ( $pagenow ?? '' ) ) {
			return true;
		}

		return false;
	}

	/**
	 * Return true if the REST request targets an Elementor namespace.
	 *
	 * @param \WP_REST_Request $request
	 */
	private function is_elementor_rest_request( $request ): bool {
		$route = $request->get_route();
		return 0 === strpos( $route, '/elementor/' );
	}
}