Waiter.php — Transferito: WP Migration trunk

transferito / vendor / aws / aws-sdk-php / src / Waiter.php

transferito / vendor / aws / aws-sdk-php / src Last commit date

Waiter.php

267 lines

1	<?php
2	namespace Aws;
3
4	use Aws\Exception\AwsException;
5	use GuzzleHttp\Promise\Coroutine;
6	use GuzzleHttp\Promise\PromiseInterface;
7	use GuzzleHttp\Promise\PromisorInterface;
8	use GuzzleHttp\Promise\RejectedPromise;
9
10	/**
11	* "Waiters" are associated with an AWS resource (e.g., EC2 instance), and poll
12	* that resource and until it is in a particular state.
13
14	* The Waiter object produces a promise that is either a.) resolved once the
15	* waiting conditions are met, or b.) rejected if the waiting conditions cannot
16	* be met or has exceeded the number of allowed attempts at meeting the
17	* conditions. You can use waiters in a blocking or non-blocking way, depending
18	* on whether you call wait() on the promise.
19
20	* The configuration for the waiter must include information about the operation
21	* and the conditions for wait completion.
22	*/
23	class Waiter implements PromisorInterface
24	{
25	/** @var AwsClientInterface Client used to execute each attempt. */
26	private $client;
27
28	/** @var string Name of the waiter. */
29	private $name;
30
31	/** @var array Params to use with each attempt operation. */
32	private $args;
33
34	/** @var array Waiter configuration. */
35	private $config;
36
37	/** @var array Default configuration options. */
38	private static $defaults = ['initDelay' => 0, 'before' => null];
39
40	/** @var array Required configuration options. */
41	private static $required = [
42	'acceptors',
43	'delay',
44	'maxAttempts',
45	'operation',
46	];
47
48	/**
49	* The array of configuration options include:
50	*
51	* - acceptors: (array) Array of acceptor options
52	* - delay: (int) Number of seconds to delay between attempts
53	* - maxAttempts: (int) Maximum number of attempts before failing
54	* - operation: (string) Name of the API operation to use for polling
55	* - before: (callable) Invoked before attempts. Accepts command and tries.
56	*
57	* @param AwsClientInterface $client Client used to execute commands.
58	* @param string $name Waiter name.
59	* @param array $args Command arguments.
60	* @param array $config Waiter config that overrides defaults.
61	*
62	* @throws \InvalidArgumentException if the configuration is incomplete.
63	*/
64	public function __construct(
65	AwsClientInterface $client,
66	$name,
67	array $args = [],
68	array $config = []
69	) {
70	$this->client = $client;
71	$this->name = $name;
72	$this->args = $args;
73
74	// Prepare and validate config.
75	$this->config = $config + self::$defaults;
76	foreach (self::$required as $key) {
77	if (!isset($this->config[$key])) {
78	throw new \InvalidArgumentException(
79	'The provided waiter configuration was incomplete.'
80	);
81	}
82	}
83	if ($this->config['before'] && !is_callable($this->config['before'])) {
84	throw new \InvalidArgumentException(
85	'The provided "before" callback is not callable.'
86	);
87	}
88	}
89
90	/**
91	* @return Coroutine
92	*/
93	public function promise(): PromiseInterface
94	{
95	return Coroutine::of(function () {
96	$name = $this->config['operation'];
97	for ($state = 'retry', $attempt = 1; $state === 'retry'; $attempt++) {
98	// Execute the operation.
99	$args = $this->getArgsForAttempt($attempt);
100	$command = $this->client->getCommand($name, $args);
101	try {
102	if ($this->config['before']) {
103	$this->config['before']($command, $attempt);
104	}
105	$result = (yield $this->client->executeAsync($command));
106	} catch (AwsException $e) {
107	$result = $e;
108	}
109
110	// Determine the waiter's state and what to do next.
111	$state = $this->determineState($result);
112	if ($state === 'success') {
113	yield $command;
114	} elseif ($state === 'failed') {
115	$msg = "The {$this->name} waiter entered a failure state.";
116	if ($result instanceof \Exception) {
117	$msg .= ' Reason: ' . $result->getMessage();
118	}
119	yield new RejectedPromise(new \RuntimeException($msg));
120	} elseif ($state === 'retry'
121	&& $attempt >= $this->config['maxAttempts']
122	) {
123	$state = 'failed';
124	yield new RejectedPromise(new \RuntimeException(
125	"The {$this->name} waiter failed after attempt #{$attempt}."
126	));
127	}
128	}
129	});
130	}
131
132	/**
133	* Gets the operation arguments for the attempt, including the delay.
134	*
135	* @param $attempt Number of the current attempt.
136	*
137	* @return mixed integer
138	*/
139	private function getArgsForAttempt($attempt)
140	{
141	$args = $this->args;
142
143	// Determine the delay.
144	$delay = ($attempt === 1)
145	? $this->config['initDelay']
146	: $this->config['delay'];
147	if (is_callable($delay)) {
148	$delay = $delay($attempt);
149	}
150
151	// Set the delay. (Note: handlers except delay in milliseconds.)
152	if (!isset($args['@http'])) {
153	$args['@http'] = [];
154	}
155	$args['@http']['delay'] = $delay * 1000;
156
157	return $args;
158	}
159
160	/**
161	* Determines the state of the waiter attempt, based on the result of
162	* polling the resource. A waiter can have the state of "success", "failed",
163	* or "retry".
164	*
165	* @param mixed $result
166	*
167	* @return string Will be "success", "failed", or "retry"
168	*/
169	private function determineState($result)
170	{
171	foreach ($this->config['acceptors'] as $acceptor) {
172	$matcher = 'matches' . ucfirst($acceptor['matcher']);
173	if ($this->{$matcher}($result, $acceptor)) {
174	return $acceptor['state'];
175	}
176	}
177
178	return $result instanceof \Exception ? 'failed' : 'retry';
179	}
180
181	/**
182	* @param Result $result Result or exception.
183	* @param array $acceptor Acceptor configuration being checked.
184	*
185	* @return bool
186	*/
187	private function matchesPath($result, array $acceptor)
188	{
189	return !($result instanceof ResultInterface)
190	? false
191	: $acceptor['expected'] == $result->search($acceptor['argument']);
192	}
193
194	/**
195	* @param Result $result Result or exception.
196	* @param array $acceptor Acceptor configuration being checked.
197	*
198	* @return bool
199	*/
200	private function matchesPathAll($result, array $acceptor)
201	{
202	if (!($result instanceof ResultInterface)) {
203	return false;
204	}
205
206	$actuals = $result->search($acceptor['argument']) ?: [];
207	foreach ($actuals as $actual) {
208	if ($actual != $acceptor['expected']) {
209	return false;
210	}
211	}
212
213	return true;
214	}
215
216	/**
217	* @param Result $result Result or exception.
218	* @param array $acceptor Acceptor configuration being checked.
219	*
220	* @return bool
221	*/
222	private function matchesPathAny($result, array $acceptor)
223	{
224	if (!($result instanceof ResultInterface)) {
225	return false;
226	}
227
228	$actuals = $result->search($acceptor['argument']) ?: [];
229	return in_array($acceptor['expected'], $actuals);
230	}
231
232	/**
233	* @param Result $result Result or exception.
234	* @param array $acceptor Acceptor configuration being checked.
235	*
236	* @return bool
237	*/
238	private function matchesStatus($result, array $acceptor)
239	{
240	if ($result instanceof ResultInterface) {
241	return $acceptor['expected'] == $result['@metadata']['statusCode'];
242	}
243
244	if ($result instanceof AwsException && $response = $result->getResponse()) {
245	return $acceptor['expected'] == $response->getStatusCode();
246	}
247
248	return false;
249	}
250
251	/**
252	* @param Result $result Result or exception.
253	* @param array $acceptor Acceptor configuration being checked.
254	*
255	* @return bool
256	*/
257	private function matchesError($result, array $acceptor)
258	{
259	if ($result instanceof AwsException) {
260	return $result->isConnectionError()
261	\|\| $result->getAwsErrorCode() == $acceptor['expected'];
262	}
263
264	return false;
265	}
266	}
267