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.0, 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! 🎉

[alexandre-daubois]

This tests Z_TYPE_P(topic) without a deref, so an array holding a reference such as ['a', &$b] is rejected, and because zend_zval_type_name() does deref the message reads must only contain strings, string given. You can ZVAL_DEREF(topic) before the check and handle IS_REFERENCE in goValue(), which GoPackedArray() needs to read the element.

[alexandre-daubois]

Neither PublicURLs nor ResourceIdentifier is set, so the aud the hub now requires comes from r.Host, and php-server builds a catch-all site whenever --domain is empty. It may be worth deriving public_urls from --domain, or pinning resource_identifier, so a client cannot pick the audience its own token is checked against.

[alexandre-daubois]

The stub hash recorded in frankenphp_arginfo.h is still 60f0d27c04f94d7b24c052e91ef294595a2bc421, while this file now hashes to 85fabd314ab885307e0032b9f7635fa13cc0c4b5, so the generated header is stale. Running gen_stub.php again would resync it before the next contributor regenerates and gets an unrelated diff.

[alexandre-daubois]

This takes a single identifier, so MERCURE_TRUSTED_ISSUERS="https://a https://b" expands to a stray token ahead of the block, while docs/mercure.md:59 documents the same variable as a comma or space separated list. Scoping that sentence to php-server, the one path that splits the value, would keep the two contracts apart.

[alexandre-daubois]

The list leaves out the two checks this change adds in C, a ValueError on a negative $retry and a TypeError on a $topics array holding a non-string, both pinned in mercure_test.go. Adding them would cover every rejection the function can raise.