编辑文件

编辑文件：MetadataController.php

<?php

declare(strict_types=1);

namespace Automattic\WooCommerce\Api\Infrastructure;

use Automattic\WooCommerce\Api\Infrastructure\Schema\CustomScalarType;
use Automattic\WooCommerce\Api\Infrastructure\Schema\Error;
use Automattic\WooCommerce\Api\Infrastructure\Schema\ObjectType;
use Automattic\WooCommerce\Api\Infrastructure\Schema\ResolveInfo;
use Automattic\WooCommerce\Api\Infrastructure\Schema\Type;
use Automattic\WooCommerce\Api\Utils\SchemaHandle;
use Automattic\WooCommerce\Vendor\GraphQL\Language\AST\BooleanValueNode;
use Automattic\WooCommerce\Vendor\GraphQL\Language\AST\FloatValueNode;
use Automattic\WooCommerce\Vendor\GraphQL\Language\AST\IntValueNode;
use Automattic\WooCommerce\Vendor\GraphQL\Language\AST\NullValueNode;
use Automattic\WooCommerce\Vendor\GraphQL\Language\AST\StringValueNode;

/**
 * Hand-written controller that contributes the `_apiMetadata` root query
 * field and the supporting `MetadataEntry`, `MetadataTarget`, `MetadataValue`
 * and `AuthEntry` types to the generated schema.
 *
 * The autogenerated `RootQueryType` references this controller alongside the
 * autogenerated query resolvers, so the field appears on the root `Query`
 * type without any special wiring at the controller level. The resolver
 * delegates to {@see SchemaHandle::find_metadata()} for the schema walk and
 * filter application, then reshapes the rows so each entry is exposed as the
 * `{ name, value }` pair that `MetadataEntry` expects. Authorization
 * descriptors (each row's `authorization` list) pass through unchanged.
 *
 * Access is gated by {@see self::can_query_metadata()}; once allowed, the
 * returned content is principal-independent — the full declared shape of the
 * schema, irrespective of who is calling.
 */
class MetadataController {
	/**
	 * Memoised `MetadataValue` scalar type.
	 *
	 * @var ?CustomScalarType
	 */
	private static ?CustomScalarType $value_scalar = null;

/**
	 * Memoised `MetadataEntry` output type.
	 *
	 * @var ?ObjectType
	 */
	private static ?ObjectType $entry_type = null;

/**
	 * Memoised `MetadataTarget` output type.
	 *
	 * @var ?ObjectType
	 */
	private static ?ObjectType $target_type = null;

/**
	 * Memoised `AuthEntry` output type — describes one authorization
	 * attribute attached to a schema target.
	 *
	 * @var ?ObjectType
	 */
	private static ?ObjectType $auth_entry_type = null;

/**
	 * GraphQL field name used on the root `Query` type.
	 */
	public const FIELD_NAME = '_apiMetadata';

/**
	 * Field definition for the root `_apiMetadata` query, in the shape the
	 * autogenerated `RootQueryType` expects (same as every autogenerated
	 * resolver's `get_field_definition()`).
	 *
	 * @return array<string, mixed>
	 */
	public static function get_field_definition(): array {
		return array(
			'type'        => Type::nonNull( Type::listOf( Type::nonNull( self::get_target_type() ) ) ),
			'description' => __(
				'Lists metadata attached to elements of this schema. All filter arguments are optional; supplying multiple narrows the result. Use this to discover internal-use APIs, beta features, ownership, etc., or to ask "can I use this specific element?".',
				'woocommerce'
			),
			'args'        => array(
				'name'      => array(
					'type'        => Type::string(),
					'description' => __( 'Match rows that carry a metadata entry with this name. Surviving rows have their entries trimmed to the matching one.', 'woocommerce' ),
				),
				'type'      => array(
					'type'        => Type::string(),
					'description' => __( 'Match rows whose target type equals this name.', 'woocommerce' ),
				),
				'field'     => array(
					'type'        => Type::string(),
					'description' => __( 'Match rows whose target field equals this name.', 'woocommerce' ),
				),
				'attribute' => array(
					'type'        => Type::string(),
					'description' => __( 'Match rows whose authorization carries an attribute with this class short name. Surviving rows have their authorization trimmed to the matching descriptors.', 'woocommerce' ),
				),
			),
			'resolve'     => array( self::class, 'resolve' ),
		);
	}

/**
	 * Resolver for the `_apiMetadata` root field. Signature matches the
	 * engine's resolver contract; `$root` is unused here (root operations
	 * have no parent). `$context` is read for the principal so the
	 * `can_query_metadata` ladder can run.
	 *
	 * @param ?array      $root    The engine passes null for root resolvers.
	 * @param array       $args    GraphQL arguments (`name`, `type`, `field`, `attribute`).
	 * @param mixed       $context Per-request context — an ArrayObject wrapping {`principal`, `_query_metadata`}.
	 * @param ResolveInfo $info    Carries the schema instance to walk.
	 * @return list<array<string, mixed>>
	 * @throws Error When the principal is not allowed to query `_apiMetadata`.
	 */
	public static function resolve( ?array $root, array $args, mixed $context, ResolveInfo $info ): array {
		unset( $root );

$principal = is_object( $context ) || is_array( $context ) ? ( $context['principal'] ?? null ) : null;
		if ( ! self::can_query_metadata( $principal ) ) {
			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- Static error message + machine code; serialized as JSON, not HTML.
			throw self::build_metadata_query_authorization_error( $principal );
		}

// Wrap the resolver's engine-typed schema into the same handle clients
		// receive from `GraphQLControllerBase::get_schema()`, so the resolver and
		// PHP-side callers share a single inspection surface.
		$schema = new SchemaHandle( $info->schema );

$rows = $schema->find_metadata(
			$args['name'] ?? null,
			$args['type'] ?? null,
			$args['field'] ?? null,
			$args['attribute'] ?? null,
		);

// SchemaHandle returns entries as an associative `name => value` map,
		// which is the natural shape for filtering and PHP-side consumers. The
		// GraphQL `MetadataEntry` type instead exposes each entry as a
		// `{ name, value }` object so clients can `entries { name value }` over
		// a list. Reshape here.
		return array_map(
			static function ( array $row ): array {
				$row['entries'] = array_map(
					static fn( string $entry_name, $entry_value ): array => array(
						'name'  => $entry_name,
						'value' => $entry_value,
					),
					array_keys( $row['entries'] ),
					array_values( $row['entries'] ),
				);
				return $row;
			},
			$rows
		);
	}

/**
	 * Whether the principal may run the `_apiMetadata` query.
	 *
	 * Tri-tier ladder, deliberately fail-closed:
	 *
	 *  1. If the principal declares `can_query_metadata(): bool`, use it.
	 *     Plugins distinguish metadata-query access from native
	 *     introspection access by declaring this method.
	 *  2. Else if the principal declares `can_introspect(): bool`, fall
	 *     back to it — one switch then gates both metadata and
	 *     introspection, which is the common case.
	 *  3. Else (neither method declared) deny. Plugin authors that don't
	 *     opt their principal in get a locked-down endpoint rather than
	 *     leaking schema shape and gate descriptors by default.
	 *
	 * The principal-derived decision is then passed through the
	 * {@see 'woocommerce_graphql_can_query_metadata'} 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: null principal denies before the filter is
	 * consulted; either method's return is checked with `=== true`; any
	 * throw from the principal method or the filter denies; the filter
	 * must likewise return strictly `true` to allow.
	 *
	 * @param ?object $principal The resolved principal, or null when principal resolution failed.
	 */
	private static function can_query_metadata( ?object $principal ): bool {
		if ( null === $principal ) {
			return false;
		}

try {
			if ( method_exists( $principal, 'can_query_metadata' ) ) {
				$allowed = true === $principal->can_query_metadata();
			} elseif ( method_exists( $principal, 'can_introspect' ) ) {
				$allowed = true === $principal->can_introspect();
			} else {
				$allowed = false;
			}

/**
			 * Filters whether the current principal may run the `_apiMetadata` query.
			 *
			 * The filter receives the principal-derived decision (see the tri-tier
			 * ladder in {@see MetadataController::can_query_metadata()}) 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 resolver receives a null principal) — that case
			 * denies outright.
			 *
			 * @since 10.9.0
			 *
			 * @internal
			 *
			 * @param bool   $allowed   Whether the principal may query `_apiMetadata`.
			 * @param object $principal The resolved principal.
			 */
			$allowed = apply_filters( 'woocommerce_graphql_can_query_metadata', $allowed, $principal );
		} catch ( \Throwable $e ) {
			return false;
		}

return true === $allowed;
	}

/**
	 * Build the GraphQL error thrown when `_apiMetadata` is queried by a
	 * principal that cannot. Mirrors
	 * {@see ResolverHelpers::build_authorization_error()}'s
	 * UNAUTHORIZED / FORBIDDEN distinction so clients can branch on
	 * `extensions.code` the same way they do for field-level denies.
	 *
	 * @param ?object $principal The resolved principal (null when principal resolution failed).
	 */
	private static function build_metadata_query_authorization_error( ?object $principal ): Error {
		$is_anonymous = null === $principal
			|| ( method_exists( $principal, 'is_authenticated' ) && ! $principal->is_authenticated() );
		return new Error(
			$is_anonymous ? 'Authentication required.' : 'You do not have permission to perform this action.',
			extensions: array( 'code' => $is_anonymous ? 'UNAUTHORIZED' : 'FORBIDDEN' )
		);
	}

/**
	 * The `MetadataTarget` output type, lazily built and cached.
	 */
	private static function get_target_type(): ObjectType {
		if ( null === self::$target_type ) {
			self::$target_type = new ObjectType(
				array(
					'name'        => 'MetadataTarget',
					'description' => __(
						'One element of the schema with its attached metadata. Type-level rows have `field`, `argument` and `enumValue` set to null; field-level rows set `field` (and `argument` when the target is a field argument); enum-value rows set `enumValue`.',
						'woocommerce'
					),
					'fields'      => fn() => array(
						'type'          => array(
							'type'        => Type::nonNull( Type::string() ),
							'description' => __( 'Name of the GraphQL type this row describes.', 'woocommerce' ),
						),
						'field'         => array(
							'type'        => Type::string(),
							'description' => __( 'Field name when this row describes a field (or a field argument); null for type-level rows.', 'woocommerce' ),
						),
						'argument'      => array(
							'type'        => Type::string(),
							'description' => __( 'Argument name when this row describes a field argument; null otherwise.', 'woocommerce' ),
						),
						'enumValue'     => array(
							'type'        => Type::string(),
							'description' => __( 'Enum value name when this row describes one specific enum value; null otherwise.', 'woocommerce' ),
						),
						'entries'       => array(
							'type'        => Type::nonNull( Type::listOf( Type::nonNull( self::get_entry_type() ) ) ),
							'description' => __( 'Metadata entries attached to the target.', 'woocommerce' ),
						),
						'authorization' => array(
							'type'        => Type::nonNull( Type::listOf( Type::nonNull( self::get_auth_entry_type() ) ) ),
							'description' => __( 'Authorization attributes attached to the target (e.g. `RequiredCapability`, `PublicAccess`, or plugin-defined). Empty when the target carries no authorization attributes.', 'woocommerce' ),
						),
					),
				)
			);
		}
		return self::$target_type;
	}

/**
	 * The `AuthEntry` output type — one authorization attribute attached
	 * to a target. Carries the attribute's short class name and the
	 * scalar args supplied at the usage site.
	 */
	private static function get_auth_entry_type(): ObjectType {
		if ( null === self::$auth_entry_type ) {
			self::$auth_entry_type = new ObjectType(
				array(
					'name'        => 'AuthEntry',
					'description' => __( 'One authorization attribute attached to a schema target.', 'woocommerce' ),
					'fields'      => fn() => array(
						'attribute' => array(
							'type'        => Type::nonNull( Type::string() ),
							'description' => __( 'Short class name of the authorization attribute (e.g. `RequiredCapability`).', 'woocommerce' ),
						),
						'args'      => array(
							'type'        => Type::nonNull( Type::listOf( self::get_value_scalar() ) ),
							'description' => __( 'Constructor arguments supplied at the usage site, in source order. Element type is the same scalar union as `MetadataValue`.', 'woocommerce' ),
						),
					),
				)
			);
		}
		return self::$auth_entry_type;
	}

/**
	 * The `MetadataEntry` output type, lazily built and cached.
	 */
	private static function get_entry_type(): ObjectType {
		if ( null === self::$entry_type ) {
			self::$entry_type = new ObjectType(
				array(
					'name'        => 'MetadataEntry',
					'description' => __( 'One metadata entry: a `name` plus a scalar `value`.', 'woocommerce' ),
					'fields'      => fn() => array(
						'name'  => array(
							'type'        => Type::nonNull( Type::string() ),
							'description' => __( 'Identifier of the entry (e.g. `internal`, `beta`).', 'woocommerce' ),
						),
						'value' => array(
							// Nullable: `MetadataValue` itself permits a null payload (e.g.
							// `#[Metadata( 'deprecated_reason', null )]`), so the wrapping
							// must allow it through.
							'type'        => self::get_value_scalar(),
							'description' => __( 'Scalar payload associated with the entry. Null when the metadata entry carries a null value.', 'woocommerce' ),
						),
					),
				)
			);
		}
		return self::$entry_type;
	}

/**
	 * The `MetadataValue` custom scalar, accepting any GraphQL-compatible scalar.
	 *
	 * The autogenerated scalar template hard-codes acceptance of string
	 * literals only, so this scalar is hand-built rather than going through
	 * ApiBuilder. `parseLiteral` walks the AST node types and `parseValue`
	 * accepts the already-decoded PHP scalar that variables-mode delivers.
	 */
	private static function get_value_scalar(): CustomScalarType {
		if ( null === self::$value_scalar ) {
			self::$value_scalar = new CustomScalarType(
				array(
					'name'         => 'MetadataValue',
					'description'  => __(
						'Scalar payload of a metadata entry. Accepts a string, integer, float, boolean, or null.',
						'woocommerce'
					),
					// Resolvers return the raw PHP scalar; webonyx serialises it as JSON directly.
					'serialize'    => static fn( $value ) => $value,
					'parseValue'   => static function ( $value ) {
						if ( null === $value || is_bool( $value ) || is_int( $value ) || is_float( $value ) || is_string( $value ) ) {
							return $value;
						}
						throw new Error( 'MetadataValue must be a string, integer, float, boolean, or null.' );
					},
					'parseLiteral' => static function ( $value_node, ?array $variables = null ) {
						unset( $variables );

if ( $value_node instanceof StringValueNode ) {
							return $value_node->value;
						}
						if ( $value_node instanceof BooleanValueNode ) {
							return $value_node->value;
						}
						if ( $value_node instanceof IntValueNode ) {
							return (int) $value_node->value;
						}
						if ( $value_node instanceof FloatValueNode ) {
							return (float) $value_node->value;
						}
						if ( $value_node instanceof NullValueNode ) {
							return null;
						}
						throw new Error( 'MetadataValue must be a string, integer, float, boolean, or null literal.' );
					},
				)
			);
		}
		return self::$value_scalar;
	}
}