@relvehq/agent-ready 0.2.1 → 0.3.1

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.
+		}
+	}
+}