zip-ai / lib / mcp-adapter / includes / Infrastructure / Observability / FailureReason.php

FailureReason.php in ZIP AI – AI Website Builder & AI Agent 0.0.14, at lib/mcp-adapter/includes/Infrastructure/Observability/FailureReason.php

185 lines 5.5 KB

Raw Download Zip

1	<?php
2	/**
3	* Centralized failure reason taxonomy for observability.
4	*
5	* This class defines a stable, documented vocabulary of failure reasons
6	* used in observability events and error metadata. Using constants ensures
7	* consistent categorization across all MCP adapter components.
8	*
9	* @package McpAdapter
10	* @since 0.5.0
11	*/
12
13	declare( strict_types=1 );
14
15	namespace WP\MCP\Infrastructure\Observability;
16
17	/**
18	* Failure reason taxonomy for observability events.
19	*
20	* Categories:
21	* - Registration failures: Occur during component registration at boot time
22	* - Permission failures: Occur when permission checks fail at execution time
23	* - Execution failures: Occur during component execution
24	*
25	* @since 0.5.0
26	*/
27	final class FailureReason {
28
29	// =========================================================================
30	// Registration Failures
31	// =========================================================================
32
33	/**
34	* WordPress ability was not found in the registry.
35	*
36	* Occurs when an ability name is passed to register_tools/resources/prompts
37	* but wp_get_ability() returns null.
38	*/
39	public const ABILITY_NOT_FOUND = 'ability_not_found';
40
41	/**
42	* A resource with the same URI is already registered.
43	*
44	* MCP resources must have unique URIs. This failure occurs when
45	* attempting to register a duplicate.
46	*/
47	public const DUPLICATE_URI = 'duplicate_uri';
48
49	/**
50	* Prompt builder threw an exception during instantiation or build.
51	*
52	* Occurs when a class implementing McpPromptBuilderInterface throws
53	* during construction or the build() method.
54	*/
55	public const BUILDER_EXCEPTION = 'builder_exception';
56
57	/**
58	* Component was created without a permission callback.
59	*
60	* Domain components (McpTool, McpResource, McpPrompt) require a permission
61	* callback. This failure occurs when check_permission() is called but
62	* no callback was configured.
63	*/
64	public const NO_PERMISSION_STRATEGY = 'no_permission_strategy';
65
66	/**
67	* Ability conversion returned a WP_Error.
68	*
69	* Occurs when McpTool::fromAbility(), McpResource::fromAbility(), or
70	* McpPrompt::fromAbility() fails due to invalid ability configuration.
71	*/
72	public const ABILITY_CONVERSION_FAILED = 'ability_conversion_failed';
73
74	// =========================================================================
75	// Permission Failures
76	// =========================================================================
77
78	/**
79	* Generic permission denied without specific reason.
80	*
81	* Used when a permission callback returns false without providing
82	* a WP_Error with more specific context.
83	*/
84	public const PERMISSION_DENIED = 'permission_denied';
85
86	/**
87	* Permission callback returned a WP_Error.
88	*
89	* When the permission callback returns a WP_Error, the WP_Error code
90	* is logged separately in the 'wp_error_code' tag while this failure
91	* reason indicates the permission check explicitly failed.
92	*/
93	public const PERMISSION_CHECK_FAILED = 'permission_check_failed';
94
95	// =========================================================================
96	// Execution Failures
97	// =========================================================================
98
99	/**
100	* Component not found at execution time.
101	*
102	* Occurs when tools/call, resources/read, or prompts/get targets a
103	* component that doesn't exist. Different from ABILITY_NOT_FOUND which
104	* occurs at registration time.
105	*/
106	public const NOT_FOUND = 'not_found';
107
108	/**
109	* Component execution returned a WP_Error.
110	*
111	* Occurs when the execute() or read() method returns a WP_Error.
112	* The WP_Error code is logged separately in 'wp_error_code'.
113	*/
114	public const EXECUTION_FAILED = 'execution_failed';
115
116	/**
117	* Component execution threw an exception.
118	*
119	* Occurs when execute(), read(), or handle() throws an exception.
120	* The exception type is logged separately in 'exception_type'.
121	*/
122	public const EXECUTION_EXCEPTION = 'execution_exception';
123
124	// =========================================================================
125	// Validation Failures
126	// =========================================================================
127
128	/**
129	* Required parameter was missing from the request.
130	*
131	* JSON-RPC requests require certain parameters (e.g., 'name' for tools/call).
132	*/
133	public const MISSING_PARAMETER = 'missing_parameter';
134
135	/**
136	* Parameter validation failed (wrong type, out of range, etc.).
137	*
138	* Occurs when input validation against schema or business rules fails.
139	*/
140	public const INVALID_PARAMETER = 'invalid_parameter';
141
142	// =========================================================================
143	// Helper Methods
144	// =========================================================================
145
146	/**
147	* Get all valid failure reason values.
148	*
149	* Useful for validation and documentation generation.
150	*
151	* @return array<string> List of all valid failure reason constants.
152	*/
153	public static function all(): array {
154	return array(
155	// Registration.
156	self::ABILITY_NOT_FOUND,
157	self::DUPLICATE_URI,
158	self::BUILDER_EXCEPTION,
159	self::NO_PERMISSION_STRATEGY,
160	self::ABILITY_CONVERSION_FAILED,
161	// Permission.
162	self::PERMISSION_DENIED,
163	self::PERMISSION_CHECK_FAILED,
164	// Execution.
165	self::NOT_FOUND,
166	self::EXECUTION_FAILED,
167	self::EXECUTION_EXCEPTION,
168	// Validation.
169	self::MISSING_PARAMETER,
170	self::INVALID_PARAMETER,
171	);
172	}
173
174	/**
175	* Check if a value is a valid failure reason.
176	*
177	* @param string $value The value to check.
178	*
179	* @return bool True if valid, false otherwise.
180	*/
181	public static function is_valid( string $value ): bool {
182	return in_array( $value, self::all(), true );
183	}
184	}
185