JezK

Edit File: GraphQLControllerBase.php

<?php

declare(strict_types=1);

namespace Automattic\WooCommerce\Api\Infrastructure;

use Automattic\WooCommerce\Api\ApiException;
use Automattic\WooCommerce\Api\Infrastructure\Schema\Schema;
use Automattic\WooCommerce\Api\Utils\SchemaHandle;
use Automattic\WooCommerce\Internal\Api\QueryCache;
use Automattic\WooCommerce\Internal\Api\QueryComplexityRule;
use Automattic\WooCommerce\Internal\Api\QueryDepthRule;
use Automattic\WooCommerce\Internal\Api\StatusResolverFailedException;
use Automattic\WooCommerce\Vendor\GraphQL\Error\DebugFlag;
use Automattic\WooCommerce\Vendor\GraphQL\GraphQL;
use Automattic\WooCommerce\Vendor\GraphQL\Language\AST\DocumentNode;
use Automattic\WooCommerce\Vendor\GraphQL\Language\AST\FieldNode;
use Automattic\WooCommerce\Vendor\GraphQL\Language\AST\InlineFragmentNode;
use Automattic\WooCommerce\Vendor\GraphQL\Language\AST\OperationDefinitionNode;
use Automattic\WooCommerce\Vendor\GraphQL\Language\AST\SelectionSetNode;
use Automattic\WooCommerce\Vendor\GraphQL\Validator\DocumentValidator;
use Automattic\WooCommerce\Vendor\GraphQL\Validator\Rules\DisableIntrospection;

/**
 * Handles incoming GraphQL requests over the WooCommerce REST API.
 *
 * Abstract: the autogenerated `GraphQLController` subclass emitted by
 * ApiBuilder (both for WooCommerce core and for sibling plugins reusing this
 * infrastructure) is the concrete class. The public surface plugins extend
 * is engine-decoupled — the abstract {@see self::build_schema()} returns
 * {@see Schema}, a stable subclass of the underlying engine's schema type,
 * so a future engine swap doesn't break already-committed autogen trees.
 */
abstract class GraphQLControllerBase {
	/**
	 * Default nesting-depth limit applied when the option is unset or non-positive.
	 *
	 * Queries exceeding the configured limit are rejected during validation,
	 * before any resolver runs. See {@see self::get_max_query_depth()} for the accessor.
	 */
	public const DEFAULT_MAX_QUERY_DEPTH = 15;

/**
	 * Default complexity-score limit applied when the option is unset or non-positive.
	 *
	 * Complexity is the sum of per-field scores; connection fields multiply
	 * their child score by the requested page size. Queries exceeding the
	 * configured limit are rejected during validation. See
	 * {@see self::get_max_query_complexity()} for the accessor.
	 */
	public const DEFAULT_MAX_QUERY_COMPLEXITY = 1000;

/**
	 * Default path (relative to /wp-json/) at which the GraphQL route is registered.
	 *
	 * Used as the fallback when the {@see Main::OPTION_ENDPOINT_URL} option is
	 * unset or was stored in an invalid form. See {@see self::get_endpoint_url()}
	 * for the accessor.
	 */
	public const DEFAULT_ENDPOINT_URL = 'wc/graphql';

/**
	 * Regex matching one valid path segment of the endpoint URL.
	 *
	 * Constrained to the character class WordPress REST routes accept
	 * (alphanumerics, underscores, hyphens). Shared with {@see \Automattic\WooCommerce\Internal\Api\Settings::sanitize_endpoint_url()}
	 * so the UI sanitizer and the controller-side fallback stay in lockstep.
	 */
	public const ENDPOINT_URL_SEGMENT_PATTERN = '/^[A-Za-z0-9_\-]+$/';

/**
	 * Cached GraphQL schema instance.
	 *
	 * @var ?Schema
	 */
	private ?Schema $schema = null;

/**
	 * Cached public-facing schema handle wrapping {@see self::$schema}.
	 *
	 * @var ?SchemaHandle
	 */
	private ?SchemaHandle $schema_handle = null;

/**
	 * Query cache / APQ resolver.
	 *
	 * @var QueryCache
	 */
	private QueryCache $query_cache;

/**
	 * Optional plugin-supplied HTTP status resolver.
	 *
	 * Populated from {@see self::get_status_resolver()} during {@see self::init()}.
	 * Stays null when neither this controller nor its subclass supplies one,
	 * in which case {@see self::pick_status()} short-circuits to the default
	 * status without ever calling a resolver.
	 *
	 * Typed as `?object` rather than a WooCommerce-defined interface so that
	 * sibling plugins do not have to import a WooCommerce type for what is
	 * structurally a single duck-typed method.
	 *
	 * @var ?object
	 */
	private ?object $status_resolver = null;

/**
	 * DI: injected by WooCommerce container.
	 *
	 * @internal
	 * @param QueryCache $query_cache The query cache instance.
	 */
	final public function init( QueryCache $query_cache ): void {
		$this->query_cache = $query_cache;
		// Resolved through a virtual hook so autogenerated subclasses can
		// supply a per-plugin resolver without changing init()'s signature.
		// Late binding picks up the override; init() can stay final.
		$this->status_resolver = $this->get_status_resolver();
	}

/**
	 * Return the HTTP status resolver instance to use for this controller, or
	 * null to opt out. Default: null (use the framework defaults).
	 *
	 * Autogenerated subclasses override this when the plugin ships a
	 * `<plugin-api-namespace>\Infrastructure\HttpStatusResolver` convention
	 * class. The returned object is duck-typed: it must expose
	 * `public function resolve_status( int $default_status, array $output, \WP_REST_Request $request ): int`,
	 * must return an int, and must not throw. A throw is treated as a plugin
	 * bug and produces a fixed 500 INTERNAL_ERROR response — see
	 * {@see self::pick_status()} and {@see self::handle_request()}.
	 */
	protected function get_status_resolver(): ?object {
		return null;
	}

/**
	 * The maximum nesting depth allowed in a GraphQL query.
	 *
	 * Reads the {@see Main::OPTION_MAX_QUERY_DEPTH} store option; falls back
	 * to {@see self::DEFAULT_MAX_QUERY_DEPTH} when the option is unset, empty,
	 * or non-positive.
	 */
	public static function get_max_query_depth(): int {
		$value = (int) get_option( Main::OPTION_MAX_QUERY_DEPTH, self::DEFAULT_MAX_QUERY_DEPTH );
		return $value > 0 ? $value : self::DEFAULT_MAX_QUERY_DEPTH;
	}

/**
	 * The maximum computed complexity score allowed for a GraphQL query.
	 *
	 * Reads the {@see Main::OPTION_MAX_QUERY_COMPLEXITY} store option; falls
	 * back to {@see self::DEFAULT_MAX_QUERY_COMPLEXITY} when the option is
	 * unset, empty, or non-positive.
	 */
	public static function get_max_query_complexity(): int {
		$value = (int) get_option( Main::OPTION_MAX_QUERY_COMPLEXITY, self::DEFAULT_MAX_QUERY_COMPLEXITY );
		return $value > 0 ? $value : self::DEFAULT_MAX_QUERY_COMPLEXITY;
	}

/**
	 * The path (relative to /wp-json/) at which the GraphQL route is registered.
	 *
	 * Reads the {@see Main::OPTION_ENDPOINT_URL} store option; falls back to
	 * {@see self::DEFAULT_ENDPOINT_URL} when the option is unset, empty, or
	 * fails {@see self::is_valid_endpoint_url()}. The UI already validates on
	 * save, so this defense-in-depth guard only fires for CLI-set option values.
	 */
	public static function get_endpoint_url(): string {
		$value = trim( (string) get_option( Main::OPTION_ENDPOINT_URL, self::DEFAULT_ENDPOINT_URL ), '/' );
		if ( ! self::is_valid_endpoint_url( $value ) ) {
			return self::DEFAULT_ENDPOINT_URL;
		}
		return $value;
	}

/**
	 * Whether a value is a valid endpoint URL.
	 *
	 * Requires at least two non-empty path segments (so register_rest_route()
	 * has both a namespace and a route), each matching
	 * {@see self::ENDPOINT_URL_SEGMENT_PATTERN}. Mirrors the rules enforced on
	 * save by {@see \Automattic\WooCommerce\Internal\Api\Settings::sanitize_endpoint_url()}, so values that bypass
	 * the UI (e.g. CLI-set options) get the same treatment.
	 *
	 * @param string $value Endpoint URL with surrounding slashes already stripped.
	 */
	private static function is_valid_endpoint_url( string $value ): bool {
		if ( '' === $value ) {
			return false;
		}
		$parts = explode( '/', $value );
		if ( count( $parts ) < 2 ) {
			return false;
		}
		foreach ( $parts as $part ) {
			if ( '' === $part || ! preg_match( self::ENDPOINT_URL_SEGMENT_PATTERN, $part ) ) {
				return false;
			}
		}
		return true;
	}

/**
	 * Split the endpoint URL into the `[namespace, route]` pair that
	 * register_rest_route() expects.
	 *
	 * The last path segment becomes the route; everything before it becomes
	 * the namespace. E.g. `wc/v4/graphql` → `['wc/v4', '/graphql']`.
	 *
	 * @return array{0: string, 1: string}
	 */
	private static function split_endpoint_url(): array {
		$parts     = explode( '/', self::get_endpoint_url() );
		$route     = '/' . array_pop( $parts );
		$namespace = implode( '/', $parts );
		return array( $namespace, $route );
	}

/**
	 * Register the GraphQL REST route.
	 */
	public function register(): void {
		$methods = Main::filter_methods_against_settings( array( 'GET', 'POST' ) );
		if ( empty( $methods ) ) {
			return;
		}
		list( $namespace, $route ) = self::split_endpoint_url();

register_rest_route(
			$namespace,
			$route,
			array(
				'methods'             => $methods,
				'callback'            => array( $this, 'handle_request' ),
				// Auth is handled per-query/mutation.
				'permission_callback' => '__return_true',
			)
		);
	}

/**
	 * Handle an incoming GraphQL request.
	 *
	 * Resolves the principal first so debug-mode / introspection checks can
	 * consult it from inside both `process_request()` and the top-level
	 * exception formatter. When `resolve_request_principal()` itself throws
	 * (e.g. an InvalidTokenException from a plugin's PrincipalResolver),
	 * `$principal` stays null and the resulting error response carries no
	 * debug info — by design, since the caller failed to authenticate.
	 *
	 * @param \WP_REST_Request $request The REST request.
	 */
	public function handle_request( \WP_REST_Request $request ): \WP_REST_Response {
		$principal = null;
		try {
			$principal = $this->resolve_request_principal( $request );
			return $this->process_request( $request, $principal );
		} catch ( StatusResolverFailedException $e ) {
			// Resolver threw on one of the decision points inside
			// process_request(). Produce a clean 500 without re-invoking
			// the (broken) resolver.
			return $this->build_resolver_failure_response( $e, $request, $principal );
		} catch ( \Throwable $e ) {
			$output = array(
				'errors' => array(
					$this->format_exception( $e, $request, $principal ),
				),
			);

$default = $this->get_error_status( $output['errors'] );
			try {
				$status = $this->pick_status( $default, $output, $request );
			} catch ( StatusResolverFailedException $e2 ) {
				// Resolver threw specifically when handed the synthetic
				// errors shape from this catch block. Fall through to the
				// fixed 500; do not loop back into the resolver.
				return $this->build_resolver_failure_response( $e2, $request, $principal );
			}

return new \WP_REST_Response( $output, $status );
		}
	}

/**
	 * Build the canonical 500 response used when the HTTP status resolver
	 * throws or returns an out-of-range value. Body shape matches an
	 * unhandled internal error so callers don't need a separate path for
	 * "resolver blew up".
	 *
	 * In debug mode, attaches `extensions.debug` (message, file, line, trace)
	 * for the wrapper exception, plus an `extensions.previous` chain when the
	 * resolver itself threw — mirroring the shape that {@see self::format_exception()}
	 * produces for the generic-Throwable path. Outside debug mode the body
	 * stays purely generic so resolver internals never leak to anonymous callers.
	 *
	 * @param StatusResolverFailedException $e         The wrapper exception thrown by {@see self::pick_status()}.
	 * @param \WP_REST_Request              $request   The originating REST request.
	 * @param ?object                       $principal The resolved principal, or null when resolution failed.
	 */
	private function build_resolver_failure_response(
		StatusResolverFailedException $e,
		\WP_REST_Request $request,
		?object $principal
	): \WP_REST_Response {
		$error = array(
			'message'    => 'An unexpected error occurred.',
			'extensions' => array( 'code' => 'INTERNAL_ERROR' ),
		);

if ( $this->is_debug_mode( $principal, $request ) ) {
			$error['extensions']['debug'] = array(
				'message' => $e->getMessage(),
				'file'    => $e->getFile(),
				'line'    => $e->getLine(),
				'trace'   => $e->getTraceAsString(),
			);

$chain = $this->extract_previous_chain( $e );
			if ( ! empty( $chain ) ) {
				$error['extensions']['previous'] = $chain;
			}
		}

return new \WP_REST_Response( array( 'errors' => array( $error ) ), 500 );
	}

/**
	 * Filter the framework-computed default HTTP status through the optional
	 * plugin-supplied status resolver.
	 *
	 * When no resolver is configured this returns the default verbatim. When
	 * a resolver is configured its return value (an int) is returned in
	 * place of the default — which the resolver may also pass through
	 * unchanged for cases it does not want to override.
	 *
	 * Resolver-thrown exceptions are converted into an internal
	 * {@see StatusResolverFailedException} for {@see self::handle_request()}
	 * to handle, so a plugin bug never corrupts or duplicates a response.
	 *
	 * @param int              $default The framework-computed default status.
	 * @param array            $output  The response body about to be sent (may include `errors`/`data`).
	 * @param \WP_REST_Request $request The originating request.
	 *
	 * @throws StatusResolverFailedException When the resolver throws or returns a status code outside the 100..599 HTTP range.
	 */
	private function pick_status( int $default, array $output, \WP_REST_Request $request ): int {
		if ( null === $this->status_resolver ) {
			return $default;
		}
		// phpcs:disable WordPress.Security.EscapeOutput.ExceptionNotEscaped -- Internal sentinel; never serialised to the wire.
		try {
			$resolved = $this->status_resolver->resolve_status( $default, $output, $request );
		} catch ( \Throwable $e ) {
			throw new StatusResolverFailedException( 'HTTP status resolver threw.', 0, $e );
		}
		// Guard against nonsensical return values. Range-checking outside the
		// try/catch keeps this exception out of the generic-Throwable wrap
		// above, so a bad return value surfaces as the same fixed-shape 500
		// response as a throw — never as a malformed WP_REST_Response.
		if ( $resolved < 100 || $resolved > 599 ) {
			throw new StatusResolverFailedException(
				sprintf( 'HTTP status resolver returned an out-of-range status code: %d.', $resolved )
			);
		}
		// phpcs:enable WordPress.Security.EscapeOutput.ExceptionNotEscaped
		return $resolved;
	}

/**
	 * Process the GraphQL request. Extracted so that handle_request() can
	 * wrap everything in a single try/catch that respects debug mode.
	 *
	 * @param \WP_REST_Request $request   The REST request.
	 * @param object           $principal The principal resolved by handle_request(); never null when this is reached.
	 */
	private function process_request( \WP_REST_Request $request, object $principal ): \WP_REST_Response {
		// 2. Parse request. GET query-string `variables` and `extensions`
		// arrive as JSON strings; decode_json_param() unifies them with the
		// already-decoded-array path from POST bodies and rejects malformed
		// or non-object payloads up front so they surface as HTTP 400
		// INVALID_ARGUMENT instead of as confusing resolver errors (null
		// decode) or HTTP 500 TypeErrors (scalar decode).
		$query          = $request->get_param( 'query' );
		$operation_name = $request->get_param( 'operationName' );
		$variables      = $this->decode_json_param( $request->get_param( 'variables' ), 'variables' );
		$extensions     = $this->decode_json_param( $request->get_param( 'extensions' ), 'extensions' );

// 3. Resolve query (cache lookup / APQ / parse).
		$source = $this->query_cache->resolve( $query, $extensions );
		if ( is_array( $source ) ) {
			$default = $this->get_resolve_error_status( $source );
			return new \WP_REST_Response( $source, $this->pick_status( $default, $source, $request ) );
		}

// 4. Reject mutations over GET (GraphQL over HTTP spec).
		if ( 'GET' === $request->get_method() && $this->document_has_mutation( $source, $operation_name ) ) {
			$method_not_allowed_output = array(
				'errors' => array(
					array(
						'message'    => 'Mutations are not allowed over GET requests. Use POST instead.',
						'extensions' => array( 'code' => 'METHOD_NOT_ALLOWED' ),
					),
				),
			);
			return new \WP_REST_Response(
				$method_not_allowed_output,
				$this->pick_status( 405, $method_not_allowed_output, $request )
			);
		}

// 5. Load schema.
		$schema = $this->get_engine_schema();

// 6. Build validation rules.
		// A single complexity-rule instance is kept so its computed score can
		// be surfaced in the debug extensions after execution.
		$complexity_rule    = new QueryComplexityRule( self::get_max_query_complexity() );
		$validation_rules   = array_values( DocumentValidator::allRules() );
		$validation_rules[] = new QueryDepthRule( self::get_max_query_depth() );
		$validation_rules[] = $complexity_rule;
		if ( ! $this->is_introspection_allowed( $principal, $request ) ) {
			$validation_rules[] = new DisableIntrospection( DisableIntrospection::ENABLED );
		}

// 7. Execute. The context value is an ArrayObject (not a plain array)
		// so root resolvers can mutate it — specifically to thread the root
		// query's metadata into `$context['_query_metadata']` for downstream
		// field-level authorization gates. ArrayObject preserves the
		// `$context['key']` read syntax via ArrayAccess. The context carries
		// the resolved principal through to autogenerated resolvers, which
		// expose it as the `_principal` infrastructure parameter when commands
		// declare it on their authorize()/execute() methods. Request-derived
		// data that resolvers need is carried by the principal class itself —
		// populated by the PrincipalResolver, the only component wired to the
		// HTTP transport.
		$result = GraphQL::executeQuery(
			schema: $schema,
			source: $source,
			contextValue: new \ArrayObject(
				array(
					'principal' => $principal,
				)
			),
			variableValues: $variables,
			operationName: $operation_name,
			validationRules: $validation_rules,
		);

// Install an error formatter that guarantees every error carries an
		// `extensions.code`. Our resolvers route everything through
		// Utils::execute_command / Utils::authorize_command, which already
		// translate domain exceptions (ApiException, InvalidArgumentException,
		// generic Throwable) into coded GraphQL errors at the throw site.
		// What reaches us uncoded here is webonyx-native validation and
		// execution output, so we infer from webonyx's ClientAware signal:
		// client-safe errors become BAD_USER_INPUT (400), the rest become
		// INTERNAL_ERROR (500).
		//
		// In debug mode the same formatter also walks the previous-exception
		// chain so wrapped errors (e.g. a \ValueError caught by a resolver and
		// re-thrown as INTERNAL_ERROR) stay visible to the developer instead
		// of being masked behind the generic "Internal server error" message.
		$debug_mode = $this->is_debug_mode( $principal, $request );
		$result->setErrorFormatter(
			function ( \Throwable $error ) use ( $debug_mode ): array {
				$formatted = \Automattic\WooCommerce\Vendor\GraphQL\Error\FormattedError::createFromException( $error );

if ( ! isset( $formatted['extensions']['code'] ) ) {
					$client_safe                     = $error instanceof \Automattic\WooCommerce\Vendor\GraphQL\Error\ClientAware && $error->isClientSafe();
					$formatted['extensions']['code'] = $client_safe ? 'BAD_USER_INPUT' : 'INTERNAL_ERROR';
				}

// SerializationError (thrown during schema-type coercion, e.g. when
				// a resolver returns an Int that doesn't fit 32 bits) extends
				// \Exception rather than webonyx's ClientAware Error, so it lands
				// in the INTERNAL_ERROR bucket above. Its message is actually
				// client-actionable ("value out of range — send smaller inputs"),
				// so promote it to BAD_USER_INPUT when it shows up anywhere in
				// the previous-exception chain.
				if ( 'BAD_USER_INPUT' !== ( $formatted['extensions']['code'] ?? null ) ) {
					$cursor = $error;
					while ( $cursor instanceof \Throwable ) {
						if ( $cursor instanceof \Automattic\WooCommerce\Vendor\GraphQL\Error\SerializationError ) {
							$formatted['extensions']['code'] = 'BAD_USER_INPUT';
							break;
						}
						$cursor = $cursor->getPrevious();
					}
				}

if ( $debug_mode ) {
					$chain = $this->extract_previous_chain( $error );
					if ( ! empty( $chain ) ) {
						$formatted['extensions']['previous'] = $chain;
					}
				}

return $formatted;
			}
		);

$debug_flags = $this->get_debug_flags( $request, $principal );
		$output      = $result->toArray( $debug_flags );

// 8. Debug-mode metrics: expose the computed complexity and depth so
		// clients tuning queries can see what the server scored the request at.
		if ( $this->is_debug_mode( $principal, $request ) ) {
			if ( ! isset( $output['extensions'] ) ) {
				$output['extensions'] = array();
			}
			if ( ! isset( $output['extensions']['debug'] ) ) {
				$output['extensions']['debug'] = array();
			}
			$output['extensions']['debug']['complexity'] = $complexity_rule->getQueryComplexity();
			$output['extensions']['debug']['depth']      = $this->compute_query_depth( $source, $operation_name );
		}

// 9. Determine HTTP status code. GraphQL emits `data: { field: null }`
		// for nullable root fields even when the resolver errored, so gating
		// the status override on `data` being absent would leave nearly every
		// error response on HTTP 200. Always derive the status from the
		// errors array when one is present — clients that need "200 with
		// partial data" semantics can still read the `errors` array.
		$default = isset( $output['errors'] ) ? $this->get_error_status( $output['errors'] ) : 200;
		$status  = $this->pick_status( $default, $output, $request );

return new \WP_REST_Response( $output, $status );
	}

/**
	 * Public handle to the live GraphQL schema for runtime inspection.
	 *
	 * Returns an opaque {@see SchemaHandle}; callers reach metadata (and any
	 * future schema-inspection operations) through methods on that object
	 * rather than touching the underlying engine type. The handle is cached
	 * and wraps the same engine schema this controller uses to serve real
	 * requests.
	 */
	public function get_schema(): SchemaHandle {
		if ( null === $this->schema_handle ) {
			$this->schema_handle = new SchemaHandle( $this->get_engine_schema() );
		}
		return $this->schema_handle;
	}

/**
	 * Build and cache the engine-typed GraphQL schema used internally to
	 * serve requests. Kept private to keep the engine type out of the
	 * controller's public surface; consumers should reach {@see SchemaHandle}
	 * through {@see self::get_schema()} instead.
	 */
	private function get_engine_schema(): Schema {
		if ( null === $this->schema ) {
			$this->schema = $this->build_schema();
		}
		return $this->schema;
	}

/**
	 * Construct the GraphQL schema.
	 *
	 * Implemented by the autogenerated subclass emitted by ApiBuilder
	 * (both for WooCommerce core and for sibling plugins that reuse this
	 * infrastructure) so the base class stays agnostic to any specific
	 * autogenerated namespace.
	 */
	abstract protected function build_schema(): Schema;

/**
	 * FQCN of the user-provided ClassResolver, or null when none was detected.
	 *
	 * The autogenerated subclass overrides this to return its plugin's
	 * `<api_namespace>\Infrastructure\ClassResolver` when ApiBuilder detected
	 * one. When null, classes are instantiated with `new $class()`.
	 */
	protected function get_class_resolver_fqcn(): ?string {
		return null;
	}

/**
	 * FQCN of the user-provided PrincipalResolver, or null when none was detected.
	 *
	 * The autogenerated subclass overrides this to return its plugin's
	 * `<api_namespace>\Infrastructure\PrincipalResolver` when ApiBuilder detected
	 * one. When null, the controller falls back to {@see \wp_get_current_user()}
	 * (anonymous → null) to populate the request principal.
	 */
	protected function get_principal_resolver_fqcn(): ?string {
		return null;
	}

/**
	 * Whether the configured PrincipalResolver's `resolve_principal()` declares
	 * the \WP_REST_Request parameter (true) or omits it (false).
	 *
	 * Captured at build time and emitted as an override on the autogenerated
	 * controller subclass, so the call below uses the right arity without
	 * runtime reflection. Default is irrelevant when {@see self::get_principal_resolver_fqcn()}
	 * returns null (the inline `wp_get_current_user()` fallback applies instead).
	 */
	protected function principal_resolver_takes_request(): bool {
		return false;
	}

/**
	 * Resolve a class to an instance via the configured ClassResolver, or `new`.
	 *
	 * Used internally to instantiate the PrincipalResolver per request. The
	 * autogenerated resolver classes use the detected ClassResolver directly
	 * (the FQCN is baked in at build time), so this helper is only the runtime
	 * path for infrastructure classes that the controller itself has to load.
	 *
	 * @param string $class_name Fully-qualified name of the class to resolve.
	 */
	private function resolve_class( string $class_name ): object {
		$resolver = $this->get_class_resolver_fqcn();
		if ( null === $resolver ) {
			return new $class_name();
		}
		return $resolver::resolve_class( $class_name );
	}

/**
	 * Resolve the request principal once per HTTP request.
	 *
	 * Invoked eagerly at the top of {@see self::process_request()}, so a
	 * principal resolver throwing {@see ApiException} fails the request before
	 * any resolver runs (single coded error in the response, no `data`).
	 *
	 * The principal is never null — anonymous requests are signalled by a
	 * principal whose authentication state is unauthenticated (for the default
	 * {@see \Automattic\WooCommerce\Api\Infrastructure\Principal}, that's
	 * `Principal::$user->ID === 0`). Plugin resolvers can also signal "invalid
	 * credentials" by throwing ApiException.
	 *
	 * The configured resolver's `resolve_principal()` may declare its
	 * \WP_REST_Request parameter or omit it; the autogenerated subclass
	 * overrides {@see self::principal_resolver_takes_request()} so this call
	 * uses the right arity without runtime reflection.
	 *
	 * @param \WP_REST_Request $request The incoming REST request.
	 * @throws ApiException When the configured PrincipalResolver rejects the request.
	 */
	private function resolve_request_principal( \WP_REST_Request $request ): object {
		$fqcn = $this->get_principal_resolver_fqcn();
		if ( null === $fqcn ) {
			return new \Automattic\WooCommerce\Api\Infrastructure\Principal( wp_get_current_user() );
		}
		$resolver = $this->resolve_class( $fqcn );
		return $this->principal_resolver_takes_request()
			? $resolver->resolve_principal( $request )
			: $resolver->resolve_principal();
	}

/**
	 * Decode an optional JSON-object param (`variables` / `extensions`) into an array.
	 *
	 * WP_REST_Request delivers POST-body params as already-decoded arrays,
	 * but GET query-string equivalents arrive as raw JSON strings. This
	 * helper unifies the two and rejects malformed JSON or non-object
	 * payloads with an InvalidArgumentException — which handle_request()
	 * surfaces as HTTP 400 INVALID_ARGUMENT, rather than letting a null
	 * decode slip through as "no variables" or a scalar decode trigger a
	 * downstream TypeError / HTTP 500.
	 *
	 * @param mixed  $value The param value from WP_REST_Request::get_param().
	 * @param string $name  The param name, used in error messages.
	 * @return array The decoded object, or an empty array when the param is omitted / empty / JSON null.
	 * @throws \InvalidArgumentException When the payload is not a JSON object or not valid JSON.
	 */
	private function decode_json_param( $value, string $name ): array {
		if ( null === $value ) {
			return array();
		}
		if ( is_array( $value ) ) {
			return $value;
		}
		// phpcs:disable WordPress.Security.EscapeOutput.ExceptionNotEscaped -- Not HTML; serialized as JSON.
		if ( ! is_string( $value ) ) {
			throw new \InvalidArgumentException(
				sprintf( 'Argument `%s` must be a JSON object or omitted.', $name )
			);
		}
		if ( '' === $value ) {
			return array();
		}
		$decoded = json_decode( $value, true );
		if ( JSON_ERROR_NONE !== json_last_error() ) {
			throw new \InvalidArgumentException(
				sprintf( 'Argument `%s` is not valid JSON: %s', $name, json_last_error_msg() )
			);
		}
		if ( null === $decoded ) {
			// Literal "null" JSON payload — treat as omitted.
			return array();
		}
		if ( ! is_array( $decoded ) ) {
			throw new \InvalidArgumentException(
				sprintf( 'Argument `%s` must be a JSON object (got %s).', $name, gettype( $decoded ) )
			);
		}
		return $decoded;
		// phpcs:enable WordPress.Security.EscapeOutput.ExceptionNotEscaped
	}

/**
	 * Determine debug flags for the request, based on {@see self::is_debug_mode()}.
	 *
	 * @param \WP_REST_Request $request   The REST request.
	 * @param ?object          $principal The resolved principal, or null if resolution itself failed.
	 */
	private function get_debug_flags( \WP_REST_Request $request, ?object $principal ): int {
		if ( ! $this->is_debug_mode( $principal, $request ) ) {
			return DebugFlag::NONE;
		}
		return DebugFlag::INCLUDE_DEBUG_MESSAGE | DebugFlag::INCLUDE_TRACE;
	}

/**
	 * Check whether GraphQL introspection is allowed for this request.
	 *
	 * The principal opts in via a `can_introspect(): bool` method; principals
	 * that don't declare it are denied by default. The decision is then passed
	 * through the {@see 'woocommerce_graphql_can_introspect'} filter so sites
	 * can grant or revoke access without subclassing the principal — useful
	 * for per-request rules (specific IPs, headers, query parameters, etc.).
	 *
	 * Fail-closed contract: the principal must be non-null (principal-resolution
	 * failures deny outright, before the filter is consulted), the principal
	 * method's return value is treated with `=== true`, and any throw from
	 * either the principal method or the filter callback denies. The filter
	 * must likewise return strictly `true` to allow; any other value denies.
	 *
	 * @param ?object          $principal The resolved principal, or null when principal resolution failed.
	 * @param \WP_REST_Request $request   The REST request.
	 */
	private function is_introspection_allowed( ?object $principal, \WP_REST_Request $request ): bool {
		if ( is_null( $principal ) ) {
			return false;
		}

try {
			$can_introspect = method_exists( $principal, 'can_introspect' )
				&& true === $principal->can_introspect();

/**
			 * Filters whether the current principal may run GraphQL introspection.
			 *
			 * The filter receives the principal-derived decision (false when the
			 * principal doesn't declare `can_introspect()` or its `can_introspect()`
			 * doesn't return strictly `true`) and must return strictly `true` to
			 * grant access; any other return value denies. The filter is not
			 * invoked when principal resolution failed (i.e. when the controller
			 * passes a null principal) — that case denies outright.
			 *
			 * @since 10.9.0
			 *
			 * @internal
			 *
			 * @param bool             $can_introspect Whether the principal can introspect, derived from `$principal->can_introspect()`.
			 * @param object           $principal      The resolved principal.
			 * @param \WP_REST_Request $request        The REST request being processed.
			 */
			$can_introspect = apply_filters( 'woocommerce_graphql_can_introspect', $can_introspect, $principal, $request );
		} catch ( \Throwable $e ) {
			return false;
		}

return true === $can_introspect;
	}

/**
	 * Check if debug mode is active.
	 *
	 * Debug mode is gated on `_debug=1` being set on the request: when absent,
	 * debug mode is off regardless of any other signal. When present, the
	 * principal opts in via a `can_use_debug_mode(): bool` method (principals
	 * that don't declare it are denied by default), and the decision is then
	 * passed through the {@see 'woocommerce_graphql_can_use_debug_mode'} filter.
	 *
	 * Fail-closed contract: the principal must be non-null (principal-resolution
	 * failures deny outright, before the filter is consulted), the principal
	 * method's return value is treated with `=== true`, and any throw from
	 * either the principal method or the filter callback denies. The filter
	 * must likewise return strictly `true` to allow; any other value denies.
	 *
	 * @param ?object          $principal The resolved principal, or null when principal resolution failed.
	 * @param \WP_REST_Request $request   The REST request.
	 */
	private function is_debug_mode( ?object $principal, \WP_REST_Request $request ): bool {
		if ( '1' !== $request->get_param( '_debug' ) ) {
			return false;
		}
		if ( is_null( $principal ) ) {
			return false;
		}

try {
			$can_debug = method_exists( $principal, 'can_use_debug_mode' )
				&& true === $principal->can_use_debug_mode();

/**
			 * Filters whether the current principal may activate GraphQL debug mode.
			 *
			 * Only invoked when the request carries `_debug=1` and a principal was
			 * resolved successfully, so the filter is not called on every GraphQL
			 * request. The filter receives the principal-derived decision (false
			 * when the principal doesn't declare `can_use_debug_mode()` or its
			 * `can_use_debug_mode()` doesn't return strictly `true`) and must
			 * return strictly `true` to grant access; any other return value denies.
			 *
			 * @since 10.9.0
			 *
			 * @internal
			 *
			 * @param bool             $can_debug Whether the principal can use debug mode, derived from `$principal->can_use_debug_mode()`.
			 * @param object           $principal The resolved principal.
			 * @param \WP_REST_Request $request   The REST request being processed.
			 */
			$can_debug = apply_filters( 'woocommerce_graphql_can_use_debug_mode', $can_debug, $principal, $request );
		} catch ( \Throwable $e ) {
			return false;
		}

return true === $can_debug;
	}

/**
	 * Format a caught exception into a GraphQL error array.
	 *
	 * @param \Throwable       $e         The caught exception.
	 * @param \WP_REST_Request $request   The REST request.
	 * @param ?object          $principal The resolved principal, or null when the exception came from principal resolution itself.
	 */
	private function format_exception( \Throwable $e, \WP_REST_Request $request, ?object $principal ): array {
		if ( $e instanceof ApiException ) {
			// Caller-supplied extensions come first so the canonical
			// getErrorCode() can't be silently overridden by an extensions
			// entry keyed 'code'. Mirrors the same invariant enforced by
			// Utils::translate_exceptions() for the execute/authorize paths.
			$error = array(
				'message'    => $e->getMessage(),
				'extensions' => array_merge(
					$e->getExtensions(),
					array( 'code' => $e->getErrorCode() )
				),
			);
		} elseif ( $e instanceof \InvalidArgumentException ) {
			$error = array(
				'message'    => $e->getMessage(),
				'extensions' => array( 'code' => 'INVALID_ARGUMENT' ),
			);
		} else {
			$error = array(
				'message'    => 'An unexpected error occurred.',
				'extensions' => array( 'code' => 'INTERNAL_ERROR' ),
			);
		}

$chain = $this->extract_previous_chain( $e );
			if ( ! empty( $chain ) ) {
				$error['extensions']['debug']['previous'] = $chain;
			}
		}

return $error;
	}

/**
	 * Walk the `getPrevious()` chain of a Throwable and return one entry per
	 * wrapped exception. Used in debug mode so that resolver-level wrappers
	 * (which bury the real cause behind a generic "INTERNAL_ERROR") still
	 * surface the underlying class/message/file/line/trace.
	 *
	 * @param \Throwable $e The outermost exception.
	 * @return array<int, array{class: string, message: string, file: string, line: int, trace: string[]}>
	 */
	private function extract_previous_chain( \Throwable $e ): array {
		$chain = array();
		for ( $prev = $e->getPrevious(); null !== $prev; $prev = $prev->getPrevious() ) {
			$chain[] = array(
				'class'   => get_class( $prev ),
				'message' => $prev->getMessage(),
				'file'    => $prev->getFile(),
				'line'    => $prev->getLine(),
				'trace'   => explode( "\n", $prev->getTraceAsString() ),
			);
		}
		return $chain;
	}

/**
	 * Mapping from machine-readable error codes to HTTP status codes.
	 *
	 * Any code not listed here defaults to 500, so unknown/unrecognised codes
	 * from third-party resolvers stay on the safe side. The error formatter
	 * installed in process_request() guarantees every error carries a code
	 * from this table before get_error_status() inspects it.
	 */
	private const ERROR_STATUS_MAP = array(
		'UNAUTHORIZED'              => 401,
		'INVALID_TOKEN'             => 401,
		'FORBIDDEN'                 => 403,
		'NOT_FOUND'                 => 404,
		'METHOD_NOT_ALLOWED'        => 405,
		'INVALID_ARGUMENT'          => 400,
		'BAD_USER_INPUT'            => 400,
		'GRAPHQL_PARSE_ERROR'       => 400,
		'GRAPHQL_PARSE_FAILED'      => 400,
		'GRAPHQL_VALIDATION_FAILED' => 400,
		'VALIDATION_ERROR'          => 422,
		'INTERNAL_ERROR'            => 500,
	);

/**
	 * Determine the HTTP status code from an array of GraphQL errors.
	 *
	 * Applies the code-to-status lookup to each error and returns the worst
	 * (highest) status seen. A single genuine 5xx among mixed errors surfaces
	 * as 500, which is the more useful signal for monitoring and logs.
	 *
	 * @param array $errors The GraphQL errors array.
	 */
	private function get_error_status( array $errors ): int {
		$status = 200;
		foreach ( $errors as $error ) {
			$code   = $error['extensions']['code'] ?? null;
			$mapped = self::ERROR_STATUS_MAP[ $code ] ?? 500;
			if ( $mapped > $status ) {
				$status = $mapped;
			}
		}
		return $status;
	}

/**
	 * Determine the HTTP status code for an error returned by QueryCache::resolve().
	 *
	 * PERSISTED_QUERY_NOT_FOUND uses 200 per the Apollo APQ convention (protocol signal, not error).
	 *
	 * @param array $response The error response array from resolve().
	 */
	private function get_resolve_error_status( array $response ): int {
		$code = $response['errors'][0]['extensions']['code'] ?? '';

if ( 'PERSISTED_QUERY_NOT_FOUND' === $code ) {
			return 200;
		}

return 400;
	}

/**
	 * Compute the maximum nesting depth of the executing operation, under two
	 * different metrics:
	 *
	 * - `tree_only`: only fields whose own selection set is non-empty count
	 *   toward depth; leaves are excluded. This is the number directly
	 *   comparable to the "Maximum query depth" setting's limit, and matches
	 *   what webonyx's QueryDepth validation rule measures for the enforcement
	 *   decision.
	 * - `in_depth`: counts every field in the deepest chain, leaves included.
	 *   Useful as a shape metric when inspecting a query.
	 *
	 * Inline fragments pass through without incrementing either metric.
	 * Named-fragment spreads are not expanded here, so both numbers are lower
	 * bounds when spreads are present. The webonyx QueryDepth validation rule
	 * (which does expand spreads) remains the authoritative gate.
	 *
	 * @param DocumentNode $document       The parsed GraphQL document.
	 * @param ?string      $operation_name The requested operation name, if any.
	 * @return array{tree_only: int, in_depth: int}
	 */
	private function compute_query_depth( DocumentNode $document, ?string $operation_name ): array {
		$tree_only = 0;
		$in_depth  = 0;
		foreach ( $document->definitions as $definition ) {
			if ( ! $definition instanceof OperationDefinitionNode ) {
				continue;
			}

if ( null !== $operation_name && ( $definition->name->value ?? null ) !== $operation_name ) {
				continue;
			}

$tree_only = max( $tree_only, $this->walk_depth_tree_only( $definition->selectionSet, 0 ) );
			$in_depth  = max( $in_depth, $this->walk_depth_in_depth( $definition->selectionSet, 0 ) );
		}

return array(
			'tree_only' => $tree_only,
			'in_depth'  => $in_depth,
		);
	}

/**
	 * Walk a selection set counting only fields with child selections, matching
	 * webonyx's QueryDepth rule so the returned number is directly comparable
	 * to the configured "Maximum query depth" limit.
	 *
	 * @param ?SelectionSetNode $selection_set The selection set to walk.
	 * @param int               $depth         The depth at which fields in this selection set sit.
	 */
	private function walk_depth_tree_only( ?SelectionSetNode $selection_set, int $depth ): int {
		if ( null === $selection_set ) {
			return 0;
		}

$max = 0;
		foreach ( $selection_set->selections as $selection ) {
			if ( $selection instanceof FieldNode ) {
				if ( null !== $selection->selectionSet ) {
					$max = max( $max, $depth, $this->walk_depth_tree_only( $selection->selectionSet, $depth + 1 ) );
				}
			} elseif ( $selection instanceof InlineFragmentNode ) {
				$max = max( $max, $this->walk_depth_tree_only( $selection->selectionSet, $depth ) );
			}
		}

return $max;
	}

/**
	 * Walk a selection set counting every field in the deepest chain, leaves
	 * included. Produces the "shape" metric surfaced alongside the enforcement
	 * metric in debug output.
	 *
	 * @param ?SelectionSetNode $selection_set The selection set to walk, or null for a leaf.
	 * @param int               $depth         The depth of the selection set's parent.
	 */
	private function walk_depth_in_depth( ?SelectionSetNode $selection_set, int $depth ): int {
		if ( null === $selection_set ) {
			return $depth;
		}

$max = $depth;
		foreach ( $selection_set->selections as $selection ) {
			if ( $selection instanceof FieldNode ) {
				$max = max( $max, $this->walk_depth_in_depth( $selection->selectionSet, $depth + 1 ) );
			} elseif ( $selection instanceof InlineFragmentNode ) {
				$max = max( $max, $this->walk_depth_in_depth( $selection->selectionSet, $depth ) );
			}
		}

return $max;
	}

/**
	 * Check whether the parsed document contains a mutation operation.
	 *
	 * When an operation name is given, only that operation is checked;
	 * otherwise any mutation definition in the document triggers a match.
	 *
	 * @param DocumentNode $document       The parsed GraphQL document.
	 * @param ?string      $operation_name The requested operation name, if any.
	 */
	private function document_has_mutation( DocumentNode $document, ?string $operation_name ): bool {
		foreach ( $document->definitions as $definition ) {
			if ( ! $definition instanceof OperationDefinitionNode ) {
				continue;
			}

if ( null !== $operation_name && ( $definition->name->value ?? null ) !== $operation_name ) {
				continue;
			}

if ( 'mutation' === $definition->operation ) {
				return true;
			}
		}

return false;
	}
}