File Toolkit/Curler/CurlerHarRecorder.php

1:	<?php declare(strict_types=1);
2:
3:	namespace Salient\Curler;
4:
5:	use Psr\Http\Message\RequestInterface as PsrRequestInterface;
6:	use Salient\Contract\Curler\Event\CurlRequestEvent;
7:	use Salient\Contract\Curler\Event\CurlResponseEvent;
8:	use Salient\Contract\Curler\Event\ResponseCacheHitEvent;
9:	use Salient\Core\Facade\Event;
10:	use Salient\Http\Message\Request;
11:	use Salient\Utility\File;
12:	use Salient\Utility\Json;
13:	use Salient\Utility\Package;
14:	use Closure;
15:	use CurlHandle;
16:	use DateTimeImmutable;
17:	use LogicException;
18:	use RuntimeException;
19:	use stdClass;
20:	use Stringable;
21:
22:	/**
23:	* Records Curler requests to an HTTP Archive (HAR) stream
24:	*
25:	* @api
26:	*/
27:	class CurlerHarRecorder
28:	{
29:	/** @var resource\|null */
30:	protected $Stream;
31:	protected bool $IsCloseable;
32:	protected ?string $Uri;
33:	protected bool $IsRecording = false;
34:	/** @var int[] */
35:	protected array $ListenerIds = [];
36:	protected ?PsrRequestInterface $LastRequest = null;
37:	protected float $LastRequestTime;
38:	protected int $EntryCount = 0;
39:
40:	/**
41:	* Creates a new CurlerHarRecorder object
42:	*
43:	* `$name` and `$version` are applied to the archive's `<creator>` object.
44:	* If both are `null`, they are replaced with the name and version of the
45:	* root package.
46:	*
47:	* @api
48:	*
49:	* @param Stringable\|string\|resource $resource
50:	*/
51:	public function __construct(
52:	$resource,
53:	?string $name = null,
54:	?string $version = null
55:	) {
56:	$uri = null;
57:	$this->Stream = File::maybeOpen($resource, 'w', $close, $uri);
58:	$this->IsCloseable = $close;
59:	$this->Uri = $uri;
60:
61:	if ($name === null && $version === null) {
62:	// @codeCoverageIgnoreStart
63:	$name = Package::name();
64:	$version = Package::version(true, true);
65:	// @codeCoverageIgnoreEnd
66:	}
67:
68:	File::writeAll($this->Stream, sprintf(
69:	'{"log":{"version":"1.2","creator":%s,"pages":[],"entries":[',
70:	Json::encode([
71:	'name' => $name ?? '',
72:	'version' => $version ?? '',
73:	]),
74:	), null, $this->Uri);
75:	}
76:
77:	/**
78:	* @internal
79:	*/
80:	public function __destruct()
81:	{
82:	$this->close();
83:	}
84:
85:	/**
86:	* Close the HTTP Archive (HAR) stream or detach it from the instance,
87:	* stopping recording if necessary
88:	*/
89:	public function close(): void
90:	{
91:	$this->stop();
92:
93:	if (!$this->Stream) {
94:	return;
95:	}
96:
97:	File::writeAll($this->Stream, ']}}', null, $this->Uri);
98:
99:	if ($this->IsCloseable) {
100:	File::close($this->Stream, $this->Uri);
101:	}
102:
103:	$this->Stream = null;
104:	$this->Uri = null;
105:	}
106:
107:	/**
108:	* Start recording requests, optionally with an initial event
109:	*
110:	* @param CurlRequestEvent\|ResponseCacheHitEvent\|null $event
111:	* @throws LogicException if the instance is already recording.
112:	*/
113:	public function start($event = null): void
114:	{
115:	if ($this->IsRecording) {
116:	throw new LogicException('Already recording');
117:	}
118:
119:	$this->assertIsValid();
120:
121:	$this->IsRecording = true;
122:
123:	$dispatcher = Event::getInstance();
124:	$this->ListenerIds = [
125:	$dispatcher->listen(Closure::fromCallable([$this, 'handleCurlRequest'])),
126:	$dispatcher->listen(Closure::fromCallable([$this, 'handleCurlResponse'])),
127:	$dispatcher->listen(Closure::fromCallable([$this, 'handleResponseCacheHit'])),
128:	];
129:
130:	if ($event instanceof CurlRequestEvent) {
131:	$this->handleCurlRequest($event);
132:	} elseif ($event instanceof ResponseCacheHitEvent) {
133:	$this->handleResponseCacheHit($event);
134:	}
135:	}
136:
137:	/**
138:	* Stop recording requests if they are being recorded
139:	*/
140:	public function stop(): void
141:	{
142:	if (!$this->IsRecording) {
143:	return;
144:	}
145:
146:	foreach ($this->ListenerIds as $id) {
147:	Event::removeListener($id);
148:	}
149:	$this->ListenerIds = [];
150:
151:	$this->IsRecording = false;
152:	}
153:
154:	protected function handleCurlRequest(CurlRequestEvent $event): void
155:	{
156:	$this->assertIsValid();
157:
158:	$this->LastRequest = $event->getRequest();
159:	$this->LastRequestTime = microtime(true);
160:	}
161:
162:	protected function handleCurlResponse(CurlResponseEvent $event): void
163:	{
164:	$this->assertIsValid();
165:
166:	$request = $event->getRequest();
167:	if ($request !== $this->LastRequest) {
168:	// @codeCoverageIgnoreStart
169:	throw new RuntimeException('Response does not match request');
170:	// @codeCoverageIgnoreEnd
171:	}
172:	$requestTime = $this->LastRequestTime;
173:
174:	$this->LastRequest = null;
175:
176:	$handle = $event->getCurlHandle();
177:
178:	/** @var int */
179:	$redirects = $this->getCurlInfo($handle, \CURLINFO_REDIRECT_COUNT);
180:	if ($redirects !== 0) {
181:	throw new RuntimeException('Redirects followed by cURL cannot be recorded');
182:	}
183:
184:	// According to https://curl.se/libcurl/c/curl_easy_getinfo.html, cURL
185:	// transfers are processed in the following order, but connection reuse
186:	// can lead to variations:
187:	/** @var array{namelookup:int,connect:int,appconnect:int,pretransfer:int,starttransfer:int,transfer:int} */
188:	$times = [
189:	'namelookup' => $this->getCurlInfo($handle, \CURLINFO_NAMELOOKUP_TIME_T),
190:	'connect' => $this->getCurlInfo($handle, \CURLINFO_CONNECT_TIME_T),
191:	'appconnect' => $this->getCurlInfo($handle, \CURLINFO_APPCONNECT_TIME_T),
192:	'pretransfer' => $this->getCurlInfo($handle, \CURLINFO_PRETRANSFER_TIME_T),
193:	'starttransfer' => $this->getCurlInfo($handle, \CURLINFO_STARTTRANSFER_TIME_T),
194:	'transfer' => $this->getCurlInfo($handle, \CURLINFO_TOTAL_TIME_T),
195:	];
196:
197:	$totalTime = 0;
198:	$last = 0;
199:	foreach ($times as $time => $value) {
200:	$totalTime += $timings[$time] = (int) round(max(0, $value - $last) / 1000);
201:	$last = $value;
202:	}
203:
204:	/** @var string */
205:	$scheme = $this->getCurlInfo($handle, \CURLINFO_SCHEME);
206:	$ssl = strcasecmp($scheme, 'https') === 0;
207:	/** @var string */
208:	$primaryIP = $this->getCurlInfo($handle, \CURLINFO_PRIMARY_IP);
209:
210:	$entry = [
211:	// PHP 7.4 requires 6 digits after the decimal point
212:	'startedDateTime' => (new DateTimeImmutable(sprintf('@%.6f', $requestTime)))->format('Y-m-d\TH:i:s.vP'),
213:	// Sum of non-negative timings
214:	'time' => $totalTime,
215:	'request' => Request::fromPsr7($request)->jsonSerialize(),
216:	'response' => $event->getResponse()->jsonSerialize(),
217:	'cache' => new stdClass(),
218:	'timings' => [
219:	// Time in queue
220:	'blocked' => -1,
221:	// DNS resolution time
222:	'dns' => $timings['namelookup'],
223:	// Time creating connection, including SSL/TLS negotiation
224:	'connect' => $timings['connect'] + $timings['appconnect'],
225:	// Time sending request (must be non-negative)
226:	'send' => $timings['pretransfer'],
227:	// Time waiting for response (must be non-negative)
228:	'wait' => $timings['starttransfer'],
229:	// Time receiving response (must be non-negative)
230:	'receive' => $timings['transfer'],
231:	// Optional (1.2+) SSL/TLS negotiation time
232:	'ssl' => $ssl ? $timings['appconnect'] : -1,
233:	],
234:	// Optional (1.2+)
235:	'serverIPAddress' => $primaryIP,
236:	];
237:
238:	$this->writeEntry($entry);
239:	}
240:
241:	/**
242:	* @param CurlHandle\|resource $handle
243:	* @return mixed[]\|int\|float\|string\|null
244:	*/
245:	protected function getCurlInfo($handle, int $option)
246:	{
247:	$value = curl_getinfo($handle, $option);
248:	if ($value === false) {
249:	// @codeCoverageIgnoreStart
250:	throw new RuntimeException('Error getting cURL transfer information');
251:	// @codeCoverageIgnoreEnd
252:	}
253:	/** @var mixed[]\|int\|float\|string\|null */
254:	return $value;
255:	}
256:
257:	protected function handleResponseCacheHit(ResponseCacheHitEvent $event): void
258:	{
259:	$this->assertIsValid();
260:
261:	$request = $event->getRequest();
262:
263:	$entry = [
264:	'startedDateTime' => (new DateTimeImmutable())->format('Y-m-d\TH:i:s.vP'),
265:	'time' => 0,
266:	'request' => Request::fromPsr7($request)->jsonSerialize(),
267:	'response' => $event->getResponse()->jsonSerialize(),
268:	'cache' => new stdClass(),
269:	'timings' => [
270:	'blocked' => -1,
271:	'dns' => -1,
272:	'connect' => -1,
273:	'send' => 0,
274:	'wait' => 0,
275:	'receive' => 0,
276:	],
277:	];
278:
279:	$this->writeEntry($entry);
280:	}
281:
282:	/**
283:	* @param array<string,mixed> $entry
284:	*/
285:	protected function writeEntry(array $entry): void
286:	{
287:	$this->assertIsValid();
288:
289:	File::writeAll(
290:	$this->Stream,
291:	($this->EntryCount++ ? ',' : '') . Json::encode($entry),
292:	null,
293:	$this->Uri,
294:	);
295:	}
296:
297:	/**
298:	* @phpstan-assert !null $this->Stream
299:	*/
300:	protected function assertIsValid(): void
301:	{
302:	if (!$this->Stream) {
303:	throw new LogicException('Recorder is closed');
304:	}
305:	}
306:	}
307:

Namespaces

Classes