@relvehq/agent-ready 0.3.0 → 0.4.0

package/dist/wp/relve-agent-ready/includes/class-relve-ar-reporter.php

@@ -0,0 +1,147 @@
+<?php
+/**
+ * Reporter: share agent visits with Relve (changes/agent-ready-telemetry).
+ *
+ * Off unless both "Enabled" and "Share visit stats with Relve" are ticked.
+ * After a Markdown page or llms.txt has been sent, one small JSON report goes
+ * to RELVE_AR_HITS_ENDPOINT:
+ *
+ *   { key: "ar_wp_<12 hex of md5(home_url())>", client: "wordpress/<ver>",
+ *     event: { ts, host, path, via, source, status, tokens, bytes,
+ *              userAgent, durationMs } }
+ *
+ * Never the Markdown, never the visitor's IP. The request is non-blocking
+ * with a 1 second timeout, and where PHP-FPM allows it the agent's response
+ * is finished first, so the agent never waits on Relve.
+ *
+ * @package Relve_Agent_Ready
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Visit reports to Relve.
+ */
+class Relve_AR_Reporter {
+
+	const DEFAULT_ENDPOINT = 'https://relvehq.com/api/agent-ready/v1/hits';
+
+	/**
+	 * Endpoint URL: RELVE_AR_HITS_ENDPOINT, filterable (relve_ar_hits_endpoint).
+	 *
+	 * @return string
+	 */
+	public static function endpoint() {
+		$url = defined( 'RELVE_AR_HITS_ENDPOINT' ) ? (string) RELVE_AR_HITS_ENDPOINT : self::DEFAULT_ENDPOINT;
+		return (string) apply_filters( 'relve_ar_hits_endpoint', $url );
+	}
+
+	/**
+	 * Whether this site reports at all.
+	 *
+	 * @param array $settings Settings.
+	 * @return bool
+	 */
+	public static function active( $settings ) {
+		return ! empty( $settings['enabled'] ) && ! empty( $settings['share_stats'] );
+	}
+
+	/**
+	 * The site's dashboard key: stable per home URL, not a secret.
+	 *
+	 * @return string
+	 */
+	public static function site_key() {
+		return 'ar_wp_' . substr( md5( (string) home_url() ), 0, 12 );
+	}
+
+	/**
+	 * One visit, in the package's HitEvent shape.
+	 *
+	 * @param string $path     Requested page path (without ".md"; "via" says how it was asked).
+	 * @param string $via      suffix|query|accept|llms.
+	 * @param string $source   native|stored|llms.
+	 * @param array  $response Relve_AR_Response::build() result.
+	 * @param string $body     The full Markdown (only its size is used).
+	 * @param array  $server   $_SERVER.
+	 * @return array
+	 */
+	public static function event( $path, $via, $source, $response, $body, $server ) {
+		$headers = isset( $response['headers'] ) && is_array( $response['headers'] ) ? $response['headers'] : array();
+		$start   = isset( $server['REQUEST_TIME_FLOAT'] ) ? (float) $server['REQUEST_TIME_FLOAT'] : 0.0;
+		$ua      = isset( $server['HTTP_USER_AGENT'] ) ? substr( (string) $server['HTTP_USER_AGENT'], 0, 512 ) : '';
+		return array(
+			'ts'         => gmdate( 'Y-m-d\TH:i:s\Z' ),
+			'host'       => (string) wp_parse_url( home_url(), PHP_URL_HOST ),
+			'path'       => substr( (string) $path, 0, 2048 ),
+			'via'        => (string) $via,
+			'source'     => (string) $source,
+			'status'     => isset( $response['status'] ) ? (int) $response['status'] : 200,
+			'tokens'     => isset( $headers['x-markdown-tokens'] ) ? (int) $headers['x-markdown-tokens'] : Relve_AR_Response::estimate_tokens( (string) $body ),
+			'bytes'      => strlen( (string) $body ),
+			'userAgent'  => $ua,
+			'durationMs' => $start > 0 ? max( 0, (int) round( ( microtime( true ) - $start ) * 1000 ) ) : null,
+		);
+	}
+
+	/**
+	 * wp_remote_post() arguments for one event.
+	 *
+	 * @param array $event Event.
+	 * @return array
+	 */
+	public static function request_args( $event ) {
+		$version = defined( 'RELVE_AR_VERSION' ) ? RELVE_AR_VERSION : '0';
+		$body    = json_encode( // phpcs:ignore WordPress.WP.AlternativeFunctions.json_encode_json_encode -- flags wp_json_encode does not add.
+			array(
+				'key'    => self::site_key(),
+				'client' => 'wordpress/' . $version,
+				'event'  => $event,
+			),
+			JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_INVALID_UTF8_SUBSTITUTE
+		);
+		$ua = 'relve-agent-ready-wp/' . $version;
+		return array(
+			'method'      => 'POST',
+			'timeout'     => 1,
+			'blocking'    => false,
+			'redirection' => 0,
+			'user-agent'  => $ua,
+			'headers'     => array(
+				'Content-Type' => 'application/json',
+				'User-Agent'   => $ua,
+			),
+			'body'        => (string) $body,
+			'data_format' => 'body',
+		);
+	}
+
+	/**
+	 * Report one served response. Call after Relve_AR_Response::send(); never
+	 * throws.
+	 *
+	 * @param array  $settings Settings.
+	 * @param string $path     Requested path.
+	 * @param string $via      How the Markdown was asked for.
+	 * @param string $source   Where it came from.
+	 * @param array  $response Relve_AR_Response::build() result.
+	 * @param string $body     The full Markdown.
+	 * @return void
+	 */
+	public static function report( $settings, $path, $via, $source, $response, $body ) {
+		if ( ! self::active( $settings ) ) {
+			return;
+		}
+		try {
+			$event = self::event( $path, $via, $source, $response, $body, $_SERVER );
+			if ( function_exists( 'fastcgi_finish_request' ) ) {
+				fastcgi_finish_request(); // The agent has its answer; report after.
+			}
+			wp_remote_post( self::endpoint(), self::request_args( $event ) );
+		} catch ( Throwable $e ) {
+			// A Relve outage must never touch the site.
+		}
+	}
+}

package/dist/wp/relve-agent-ready/includes/class-relve-ar-response.php

@@ -1,226 +1,226 @@
-<?php
-/**
- * Response: headers, ETag / 304, Cache-Control, token estimate.
- *
- * PHP port of @relvehq/agent-ready core/respond.ts and the adapters' header
- * choices. build() is pure (an array in, an array out) so it is unit-tested;
- * send() writes it with header() and echo.
- *
- * @package Relve_Agent_Ready
- */
-
-if ( ! defined( 'ABSPATH' ) ) {
-	exit;
-}
-
-/**
- * Builds and sends Markdown / llms.txt / 404 responses.
- */
-class Relve_AR_Response {
-
-	const MARKDOWN_CONTENT_TYPE = 'text/markdown; charset=utf-8';
-	const TEXT_CONTENT_TYPE     = 'text/plain; charset=utf-8';
-
-	/** `.md`, `?format=md` and llms.txt: their own URLs, safe for shared caches. */
-	const CACHE_CONTROL = 'public, s-maxage=300, stale-while-revalidate=86400';
-
-	/** Negotiated by Accept on the page's own URL: never in a shared cache. */
-	const NEGOTIATED_CACHE_CONTROL = 'private, max-age=300';
-
-	/**
-	 * Cache-Control for a request that asked via $via.
-	 *
-	 * @param string $via suffix|query|accept|llms.
-	 * @return string
-	 */
-	public static function cache_control_for( $via ) {
-		return 'accept' === $via ? self::NEGOTIATED_CACHE_CONTROL : self::CACHE_CONTROL;
-	}
-
-	/**
-	 * Rough token count, as the package: ceil(length / 4), where length is
-	 * the JavaScript string length (UTF-16 code units).
-	 *
-	 * @param string $text Text.
-	 * @return int
-	 */
-	public static function estimate_tokens( $text ) {
-		return (int) ceil( self::utf16_length( $text ) / 4 );
-	}
-
-	/**
-	 * Length in UTF-16 code units (what JavaScript's .length counts).
-	 *
-	 * @param string $text UTF-8 text.
-	 * @return int
-	 */
-	public static function utf16_length( $text ) {
-		$text  = (string) $text;
-		$chars = preg_match_all( '/./su', $text );
-		if ( false === $chars ) {
-			return strlen( $text ); // Not valid UTF-8: count bytes.
-		}
-		$astral = preg_match_all( '/[\x{10000}-\x{10FFFF}]/u', $text );
-		return $chars + (int) $astral;
-	}
-
-	/**
-	 * Strong ETag: first 32 hex chars of SHA-256(body).
-	 *
-	 * @param string $body Body.
-	 * @return string
-	 */
-	public static function etag_for( $body ) {
-		return '"' . substr( hash( 'sha256', (string) $body ), 0, 32 ) . '"';
-	}
-
-	/**
-	 * ETag for a body. A `generated_at:` front-matter line is left out of the
-	 * hash (it changes every time) and the ETag is then weak, as the package.
-	 *
-	 * @param string $body Body.
-	 * @return string
-	 */
-	public static function etag_for_body( $body ) {
-		$stable = preg_replace( '/^generated_at:.*\n?/m', '', (string) $body, 1 );
-		return $stable === $body ? self::etag_for( $body ) : 'W/' . self::etag_for( $stable );
-	}
-
-	/**
-	 * RFC 9110 weak comparison; "*" matches any current representation.
-	 *
-	 * @param string|null $header If-None-Match value.
-	 * @param string      $etag   Our ETag.
-	 * @return bool
-	 */
-	public static function if_none_match_hits( $header, $etag ) {
-		if ( ! is_string( $header ) || '' === $header ) {
-			return false;
-		}
-		$bare = preg_replace( '#^W/#', '', $etag );
-		foreach ( explode( ',', $header ) as $raw ) {
-			$t = trim( $raw );
-			if ( '*' === $t || preg_replace( '#^W/#', '', $t ) === $bare ) {
-				return true;
-			}
-		}
-		return false;
-	}
-
-	/**
-	 * Build a Markdown (or llms.txt) response.
-	 *
-	 * @param string $body Body.
-	 * @param array  $args {
-	 *     @type string      $method        GET or HEAD.
-	 *     @type string|null $if_none_match If-None-Match header.
-	 *     @type string|null $canonical     Absolute canonical URL; null leaves Link out.
-	 *     @type string      $cache_control Cache-Control.
-	 *     @type string      $content_type  Content-Type (default text/markdown).
-	 *     @type string      $source        x-agent-ready-source value.
-	 *     @type bool        $noindex       Send X-Robots-Tag: noindex (default true).
-	 *     @type int|null    $tokens        Token count (default: estimated from body).
-	 * }
-	 * @return array { status: int, headers: array<string,string>, body: string }
-	 */
-	public static function build( $body, $args ) {
-		$args = array_merge(
-			array(
-				'method'        => 'GET',
-				'if_none_match' => null,
-				'canonical'     => null,
-				'cache_control' => self::CACHE_CONTROL,
-				'content_type'  => self::MARKDOWN_CONTENT_TYPE,
-				'source'        => 'native',
-				'noindex'       => true,
-				'tokens'        => null,
-			),
-			(array) $args
-		);
-		$body   = (string) $body;
-		$etag   = self::etag_for_body( $body );
-		$tokens = null === $args['tokens'] ? self::estimate_tokens( $body ) : (int) $args['tokens'];
-
-		$headers = array( 'Content-Type' => $args['content_type'] );
-		$headers['Vary'] = 'Accept';
-		if ( $args['canonical'] ) {
-			$headers['Link'] = '<' . $args['canonical'] . '>; rel="canonical"';
-		}
-		if ( $args['noindex'] ) {
-			$headers['X-Robots-Tag'] = 'noindex';
-		}
-		$headers['x-markdown-tokens']    = (string) $tokens;
-		$headers['Cache-Control']        = $args['cache_control'];
-		$headers['ETag']                 = $etag;
-		$headers['x-agent-ready-source'] = $args['source'];
-
-		if ( self::if_none_match_hits( $args['if_none_match'], $etag ) ) {
-			unset( $headers['Content-Type'] );
-			return array(
-				'status'  => 304,
-				'headers' => $headers,
-				'body'    => '',
-			);
-		}
-		$headers['Content-Length'] = (string) strlen( $body );
-		return array(
-			'status'  => 200,
-			'headers' => $headers,
-			'body'    => 'HEAD' === strtoupper( (string) $args['method'] ) ? '' : $body,
-		);
-	}
-
-	/**
-	 * A plain-text error (the 404 for `.md` / `?format=md` with nothing to serve).
-	 *
-	 * @param int         $status    Status code.
-	 * @param string      $method    GET or HEAD.
-	 * @param string|null $canonical Canonical URL of the page, if known.
-	 * @return array
-	 */
-	public static function plain( $status, $method = 'GET', $canonical = null ) {
-		$body    = "No Markdown version of this page is available.\n";
-		$headers = array(
-			'Content-Type'  => self::TEXT_CONTENT_TYPE,
-			'Cache-Control' => 'no-store',
-			'Vary'          => 'Accept',
-			'X-Robots-Tag'  => 'noindex',
-		);
-		if ( $canonical ) {
-			$headers['Link'] = '<' . $canonical . '>; rel="canonical"';
-		}
-		$headers['Content-Length'] = (string) strlen( $body );
-		return array(
-			'status'  => (int) $status,
-			'headers' => $headers,
-			'body'    => 'HEAD' === strtoupper( (string) $method ) ? '' : $body,
-		);
-	}
-
-	/**
-	 * Write a built response. Removes headers WordPress already queued that
-	 * do not belong on Markdown (HTML Link headers, no-cache from nocache_headers()).
-	 * The caller exits afterwards.
-	 *
-	 * @param array $response From build() or plain().
-	 * @return void
-	 */
-	public static function send( $response ) {
-		if ( ! headers_sent() ) {
-			foreach ( array( 'Link', 'X-Pingback', 'Expires', 'Pragma', 'Last-Modified', 'Cache-Control', 'Content-Type', 'X-Robots-Tag' ) as $name ) {
-				header_remove( $name );
-			}
-			if ( function_exists( 'status_header' ) ) {
-				status_header( $response['status'] );
-			} else {
-				http_response_code( $response['status'] );
-			}
-			foreach ( $response['headers'] as $name => $value ) {
-				header( $name . ': ' . $value, true );
-			}
-		}
-		if ( '' !== $response['body'] ) {
-			echo $response['body']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- text/markdown or text/plain body, never HTML.
-		}
-	}
-}
+<?php
+/**
+ * Response: headers, ETag / 304, Cache-Control, token estimate.
+ *
+ * PHP port of @relvehq/agent-ready core/respond.ts and the adapters' header
+ * choices. build() is pure (an array in, an array out) so it is unit-tested;
+ * send() writes it with header() and echo.
+ *
+ * @package Relve_Agent_Ready
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Builds and sends Markdown / llms.txt / 404 responses.
+ */
+class Relve_AR_Response {
+
+	const MARKDOWN_CONTENT_TYPE = 'text/markdown; charset=utf-8';
+	const TEXT_CONTENT_TYPE     = 'text/plain; charset=utf-8';
+
+	/** `.md`, `?format=md` and llms.txt: their own URLs, safe for shared caches. */
+	const CACHE_CONTROL = 'public, s-maxage=300, stale-while-revalidate=86400';
+
+	/** Negotiated by Accept on the page's own URL: never in a shared cache. */
+	const NEGOTIATED_CACHE_CONTROL = 'private, max-age=300';
+
+	/**
+	 * Cache-Control for a request that asked via $via.
+	 *
+	 * @param string $via suffix|query|accept|llms.
+	 * @return string
+	 */
+	public static function cache_control_for( $via ) {
+		return 'accept' === $via ? self::NEGOTIATED_CACHE_CONTROL : self::CACHE_CONTROL;
+	}
+
+	/**
+	 * Rough token count, as the package: ceil(length / 4), where length is
+	 * the JavaScript string length (UTF-16 code units).
+	 *
+	 * @param string $text Text.
+	 * @return int
+	 */
+	public static function estimate_tokens( $text ) {
+		return (int) ceil( self::utf16_length( $text ) / 4 );
+	}
+
+	/**
+	 * Length in UTF-16 code units (what JavaScript's .length counts).
+	 *
+	 * @param string $text UTF-8 text.
+	 * @return int
+	 */
+	public static function utf16_length( $text ) {
+		$text  = (string) $text;
+		$chars = preg_match_all( '/./su', $text );
+		if ( false === $chars ) {
+			return strlen( $text ); // Not valid UTF-8: count bytes.
+		}
+		$astral = preg_match_all( '/[\x{10000}-\x{10FFFF}]/u', $text );
+		return $chars + (int) $astral;
+	}
+
+	/**
+	 * Strong ETag: first 32 hex chars of SHA-256(body).
+	 *
+	 * @param string $body Body.
+	 * @return string
+	 */
+	public static function etag_for( $body ) {
+		return '"' . substr( hash( 'sha256', (string) $body ), 0, 32 ) . '"';
+	}
+
+	/**
+	 * ETag for a body. A `generated_at:` front-matter line is left out of the
+	 * hash (it changes every time) and the ETag is then weak, as the package.
+	 *
+	 * @param string $body Body.
+	 * @return string
+	 */
+	public static function etag_for_body( $body ) {
+		$stable = preg_replace( '/^generated_at:.*\n?/m', '', (string) $body, 1 );
+		return $stable === $body ? self::etag_for( $body ) : 'W/' . self::etag_for( $stable );
+	}
+
+	/**
+	 * RFC 9110 weak comparison; "*" matches any current representation.
+	 *
+	 * @param string|null $header If-None-Match value.
+	 * @param string      $etag   Our ETag.
+	 * @return bool
+	 */
+	public static function if_none_match_hits( $header, $etag ) {
+		if ( ! is_string( $header ) || '' === $header ) {
+			return false;
+		}
+		$bare = preg_replace( '#^W/#', '', $etag );
+		foreach ( explode( ',', $header ) as $raw ) {
+			$t = trim( $raw );
+			if ( '*' === $t || preg_replace( '#^W/#', '', $t ) === $bare ) {
+				return true;
+			}
+		}
+		return false;
+	}
+
+	/**
+	 * Build a Markdown (or llms.txt) response.
+	 *
+	 * @param string $body Body.
+	 * @param array  $args {
+	 *     @type string      $method        GET or HEAD.
+	 *     @type string|null $if_none_match If-None-Match header.
+	 *     @type string|null $canonical     Absolute canonical URL; null leaves Link out.
+	 *     @type string      $cache_control Cache-Control.
+	 *     @type string      $content_type  Content-Type (default text/markdown).
+	 *     @type string      $source        x-agent-ready-source value.
+	 *     @type bool        $noindex       Send X-Robots-Tag: noindex (default true).
+	 *     @type int|null    $tokens        Token count (default: estimated from body).
+	 * }
+	 * @return array { status: int, headers: array<string,string>, body: string }
+	 */
+	public static function build( $body, $args ) {
+		$args = array_merge(
+			array(
+				'method'        => 'GET',
+				'if_none_match' => null,
+				'canonical'     => null,
+				'cache_control' => self::CACHE_CONTROL,
+				'content_type'  => self::MARKDOWN_CONTENT_TYPE,
+				'source'        => 'native',
+				'noindex'       => true,
+				'tokens'        => null,
+			),
+			(array) $args
+		);
+		$body   = (string) $body;
+		$etag   = self::etag_for_body( $body );
+		$tokens = null === $args['tokens'] ? self::estimate_tokens( $body ) : (int) $args['tokens'];
+
+		$headers = array( 'Content-Type' => $args['content_type'] );
+		$headers['Vary'] = 'Accept';
+		if ( $args['canonical'] ) {
+			$headers['Link'] = '<' . $args['canonical'] . '>; rel="canonical"';
+		}
+		if ( $args['noindex'] ) {
+			$headers['X-Robots-Tag'] = 'noindex';
+		}
+		$headers['x-markdown-tokens']    = (string) $tokens;
+		$headers['Cache-Control']        = $args['cache_control'];
+		$headers['ETag']                 = $etag;
+		$headers['x-agent-ready-source'] = $args['source'];
+
+		if ( self::if_none_match_hits( $args['if_none_match'], $etag ) ) {
+			unset( $headers['Content-Type'] );
+			return array(
+				'status'  => 304,
+				'headers' => $headers,
+				'body'    => '',
+			);
+		}
+		$headers['Content-Length'] = (string) strlen( $body );
+		return array(
+			'status'  => 200,
+			'headers' => $headers,
+			'body'    => 'HEAD' === strtoupper( (string) $args['method'] ) ? '' : $body,
+		);
+	}
+
+	/**
+	 * A plain-text error (the 404 for `.md` / `?format=md` with nothing to serve).
+	 *
+	 * @param int         $status    Status code.
+	 * @param string      $method    GET or HEAD.
+	 * @param string|null $canonical Canonical URL of the page, if known.
+	 * @return array
+	 */
+	public static function plain( $status, $method = 'GET', $canonical = null ) {
+		$body    = "No Markdown version of this page is available.\n";
+		$headers = array(
+			'Content-Type'  => self::TEXT_CONTENT_TYPE,
+			'Cache-Control' => 'no-store',
+			'Vary'          => 'Accept',
+			'X-Robots-Tag'  => 'noindex',
+		);
+		if ( $canonical ) {
+			$headers['Link'] = '<' . $canonical . '>; rel="canonical"';
+		}
+		$headers['Content-Length'] = (string) strlen( $body );
+		return array(
+			'status'  => (int) $status,
+			'headers' => $headers,
+			'body'    => 'HEAD' === strtoupper( (string) $method ) ? '' : $body,
+		);
+	}
+
+	/**
+	 * Write a built response. Removes headers WordPress already queued that
+	 * do not belong on Markdown (HTML Link headers, no-cache from nocache_headers()).
+	 * The caller exits afterwards.
+	 *
+	 * @param array $response From build() or plain().
+	 * @return void
+	 */
+	public static function send( $response ) {
+		if ( ! headers_sent() ) {
+			foreach ( array( 'Link', 'X-Pingback', 'Expires', 'Pragma', 'Last-Modified', 'Cache-Control', 'Content-Type', 'X-Robots-Tag' ) as $name ) {
+				header_remove( $name );
+			}
+			if ( function_exists( 'status_header' ) ) {
+				status_header( $response['status'] );
+			} else {
+				http_response_code( $response['status'] );
+			}
+			foreach ( $response['headers'] as $name => $value ) {
+				header( $name . ': ' . $value, true );
+			}
+		}
+		if ( '' !== $response['body'] ) {
+			echo $response['body']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- text/markdown or text/plain body, never HTML.
+		}
+	}
+}