feat: upgrade to Mercure 1.0

[dunglas]

Upgrades github.com/dunglas/mercure and github.com/dunglas/mercure/caddy from v0.24.2 to v1.0.2, and adapts the integration to the protocol changes of draft-dunglas-mercure-08.

mercure_publish()

The hub validates updates before dispatching them, so the function now distinguishes the caller's mistakes from a failed publication:

• a ValueError carrying the reason for a topic addressing the reserved /.well-known/mercure namespace or equal to *, an $id starting with # or equal to earliest, a $type equal to mercure, control characters, invalid UTF-8 $data, or no topic at all;
• a RuntimeException with the message of the hub when the dispatch fails.

The negative values of $retry are also rejected, as the protocol only allows digits in that field.

An enum in frankenphp.h replaces the status codes go_mercure_publish() returned as bare integers. On the way, an array of topics that cannot be converted no longer reports No Mercure hub configured.

Hot reloading

The subscribe query parameter of the protocol is match, so $_SERVER['FRANKENPHP_HOT_RELOAD'] advertises /.well-known/mercure?match=<topic>. The topic parameter it replaces is only honored by a hub built with the deprecated_topic tag, which FrankenPHP doesn't set.

Hub configuration

Setting publisher_jwt or subscriber_jwt without protocol_version_compatibility is a configuration error now, because that mode also drops the required exp, the audience check, the at+jwt check and the issuer check. The keys are bound to a trusted issuer instead:

mercure {
	issuer {$MERCURE_TRUSTED_ISSUERS:https://localhost} {
		publisher {
			jwt {env.MERCURE_PUBLISHER_JWT_KEY} {env.MERCURE_PUBLISHER_JWT_ALG}
		}
		subscriber {
			jwt {env.MERCURE_SUBSCRIBER_JWT_KEY} {env.MERCURE_SUBSCRIBER_JWT_ALG}
		}
	}
}

php-server --mercure and the sample Caddyfile follow. MERCURE_TRUSTED_ISSUERS accepts several identifiers separated by commas or whitespace, all bound to the same keys.

FrankenPHP is built with the deprecated_topic and deprecated_claim tags of the hub, like the official Mercure binaries, so protocol_version_compatibility 8 accepts the 0.x tokens and topic= selectors during a migration. Static builds get the tags through static-php-cli: crazywhalecc/static-php-cli#1240.

Docs

docs/mercure.md and the Laravel Octane section of docs/laravel.md describe the 1.0 configuration. Octane writes each entry of its mercure array as a Caddyfile line, so the issuer block is passed as a multi-line value (verified with caddy adapt and a live hub). The Symfony example targets symfony/mercure 0.8, which ships ProtocolVersion::V1.

The translations of docs/mercure.md and docs/laravel.md still describe the 0.x configuration.

The other Go dependencies are updated on the way.

[alexandre-daubois]

I know it's a draft so feel free close anything that was already planned to be fixed 🙂

[alexandre-daubois]

Congrats on the 1.0 release! 🎉

[henderkes]

There's a small issue here @dunglas - rebuilds from source currently already lead to Mercure 1.0. I just updated my dev environment to 8.6-rc2 and was met with some fields not being recognised anymore until I change the compatibility level to 8.

[dunglas]

Which ones?

[henderkes]

Jwt subscriber and publisher token iirc. I can check again tomorrow. Startup errored out saying they live under jwt now and in order to keep working as they used to, compatibility level has to be set to 8.

[dunglas]

Yes, it's intended.

[henderkes]

Yes, that's not the issue - the issue is that duo to Go automatically updating, building FrankenPHP right now already pulls in Mercure v1.0.0, without a new release. So right now php 8.2-8.5 have frankenphp-1.12.7 with Mercure 0.24.0, php 8.6 (rc released yesterday) has frankenphp-1.12.7 with Mercure 1.0.0.