Draft: feat: add trace handling

[maelanleborgne]

Description :

Gotenberg allow overiding it's internal trace https://gotenberg.dev/docs/routes#request-tracing. This PR adds the possiblity to set our own trace to allow debuging and tracing requests.

// ...
$invoice = $invoiceRepository->find(/* ... */);

$response = $this->gotenberg->html()
  ->content('invoice_template.html.twig', ['invoice' => $invoice],
  ->traceGenerator(fn () => 'invoice_'.$invoice->getId().'_'.bin2hex(random_bytes(8))),
  ->generate()
;

echo $response->getTrace(); // 'invoice_5_dza4...'
// ...

As suggested by @Neirda24 , the trace could also hold a ressource URI with a unique hash as a query parameter, or anything that could be useful to the user.

This will especially be useful to trace the asynchronous generation webhook calls because the request made by gotenberg to the webhook endpoint will hold the trace in its headers.

TODO:

• Docs
• Tests

[Neirda24]

Better to have this fallback early on maybe ? In construct or something. It would avoid to create multiple reference to default generator

[Jean-Beru]

Trace should be optional to allow keeping default behavior (generated UUID).

We can make the trace nullable and call it only if set. If so, we should add an "unset" method.

[Neirda24]

I wonder. Wouldn't it be better to always set this ourselves ?

[Jean-Beru]

Suggested change

	public function traceGenerator(\Closure $traceGenerator): static
	public function trace(?\Closure $traceGenerator = null): static

If set, use the \Closure, if not, use a fn(): string => bin2hex(random_bytes(16)).microtime(true);.

[Jean-Beru]

+ function noTrace(): static to remove this behavior.

[Neirda24]

I don't see the value. There will be a trace no matter what. Either explicitly set from our component or automaticcaly create by gotenberg. But for webhooks we do need this feature. Withotu trace, webhook won't be possible. Trace act as a token per request.

Also I think noTrace is misleading. There will be a trace. just not an epxlicit one. So I think null is not needed or act as what you intended for noTrace ==> fallback to default behaviour