[francisrath]

Draft, not ready to merge. This hasn't been tested enough yet. Push was tested against a Mercure 1.1.5 hub in Docker on one machine; it has not been tested behind a real reverse proxy or in the built FrankenPHP image. I'm opening it to get your feedback on the approach before polishing it.

Part of #1625; the third of three alternative PRs. It includes #1626 and #1627. The commits new here start at "feat(agents): publish new print jobs to Mercure".

With #1627, agents poll every 30 s. This PR lets Part-DB notify them through a Mercure hub, so a job prints about a second after the click. Polling stays as the fallback.

What it adds

• Publishing: when a job is created or resent, Part-DB publishes a private update on urn:part-db:agent:<id>:jobs.
  • It uses symfony/mercure (0.9, Mercure protocol 1.0) directly, not the bundle. With an empty MERCURE_URL outside FrankenPHP, the bundle's Twig extension builds the hub on every Twig boot and throws, which broke cache:clear in my test. Here the hub is only built when push is on.
• Subscription offer: the heartbeat answer gets mercure: {hub, topic, token}. The token is a 1-hour subscriber token for that one topic.
• Pending count: the heartbeat answer also gets pending, the number of pending jobs. Agents only list jobs when there are some, and an agent with a live subscription can check in less often. A lost event is still picked up at the next check-in.
• Off by default: push is off unless MERCURE_PUBLIC_URL is set. Push misconfigurations (an unreachable hub, an empty or too short secret) are only logged; agents keep polling.
  • Publishing uses a 2 s / 5 s HTTP timeout, so an unreachable hub can't hold up the Print button.
  • Env: MERCURE_PUBLIC_URL, MERCURE_URL, MERCURE_JWT_SECRET, MERCURE_JWT_ISSUER. They are documented in docs/configuration.md, including the sidecar hub for the Apache image and resource_identifier behind a TLS-terminating proxy.

FrankenPHP image fix (useful on its own)

dunglas/frankenphp:1-php8.4-bookworm is now FrankenPHP 1.13.4 with Mercure 1.1.5. With the current .docker/frankenphp/Caddyfile:

• As soon as MERCURE_PUBLISHER_JWT_KEY is set, the server refuses to start. The publisher_jwt/subscriber_jwt directives "work only in compatibility mode" in Mercure 1.x.
• transport_url is "not available anymore" and is ignored.

This PR moves the keys into an issuer {$MERCURE_TRUSTED_ISSUERS:https://localhost} block and uses transport bolt. An issuer block needs a key, so the entrypoint sets a random publisher key when none is configured. Keyless installs keep starting, and the hub then accepts no outside tokens.

I checked both cases with frankenphp validate in that image, but I have not built and run the full Part-DB image.

Tests

• New tests: AgentJobPusherTest (private update, publish failure doesn't break job creation, unreachable hub doesn't block, short secret), and AgentApiControllerTest (offer present or absent, token claims, misconfigured secret, pending count).
• PHPStan passes.
• End to end with pdb-print and a real Mercure 1.1.5 hub:
  • The job reached the agent 0.24 s after the click.
  • With the hub stopped, job creation still worked and the job printed at the next poll.
  • An idle agent only checks in once a minute.

🤖 Generated with Claude Code