feat: mercure_publish() PHP function to dispatch Mercure updates

# Conflicts:
#	types.go
#	types_test.go

# Conflicts:
#	caddy/go.mod
#	caddy/go.sum
#	docs/mercure.md
#	go.mod
#	go.sum

Author: dunglas

.clang-format-ignore

@@ -0,0 +1 @@
+frankenphp_arginfo.h

.gitleaksignore

@@ -1 +1 @@
-/github/workspace/docs/mercure.md:jwt:65
+/github/workspace/docs/mercure.md:jwt:88

caddy/module.go

@@ -19,6 +19,7 @@ import (
 	"github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite"
 	"github.com/dunglas/frankenphp"
 	"github.com/dunglas/frankenphp/internal/fastabs"
+	mercureCaddy "github.com/dunglas/mercure/caddy"
 )
 
 // FrankenPHPModule represents the "php_server" and "php" directives in the Caddyfile
@@ -45,6 +46,7 @@ type FrankenPHPModule struct {
 	preparedEnv                 frankenphp.PreparedEnv
 	preparedEnvNeedsReplacement bool
 	logger                      *slog.Logger
+	mercureHubRequestOption     *frankenphp.RequestOption
 }
 
 // CaddyModule returns the Caddy module information.
@@ -142,6 +144,8 @@ func (f *FrankenPHPModule) Provision(ctx caddy.Context) error {
 		}
 	}
 
+	f.assignMercureHubRequestOption(ctx)
+
 	return nil
 }
 
@@ -184,14 +188,34 @@ func (f *FrankenPHPModule) ServeHTTP(w http.ResponseWriter, r *http.Request, _ c
 		}
 	}
 
-	fr, err := frankenphp.NewRequestWithContext(
-		r,
-		documentRootOption,
-		frankenphp.WithRequestSplitPath(f.SplitPath),
-		frankenphp.WithRequestPreparedEnv(env),
-		frankenphp.WithOriginalRequest(&origReq),
-		frankenphp.WithWorkerName(workerName),
+	var (
+		err error
+		fr  *http.Request
 	)
+	if f.mercureHubRequestOption == nil {
+		fr, err = frankenphp.NewRequestWithContext(
+			r,
+			documentRootOption,
+			frankenphp.WithRequestSplitPath(f.SplitPath),
+			frankenphp.WithRequestPreparedEnv(env),
+			frankenphp.WithOriginalRequest(&origReq),
+			frankenphp.WithWorkerName(workerName),
+		)
+	} else {
+		fr, err = frankenphp.NewRequestWithContext(
+			r,
+			documentRootOption,
+			frankenphp.WithRequestSplitPath(f.SplitPath),
+			frankenphp.WithRequestPreparedEnv(env),
+			frankenphp.WithOriginalRequest(&origReq),
+			frankenphp.WithWorkerName(workerName),
+			*f.mercureHubRequestOption,
+		)
+	}
+
+	if err != nil {
+		return caddyhttp.Error(http.StatusInternalServerError, err)
+	}
 
 	if err = frankenphp.ServeHTTP(w, fr); err != nil {
 		return caddyhttp.Error(http.StatusInternalServerError, err)
@@ -272,6 +296,13 @@ func (f *FrankenPHPModule) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
 	return nil
 }
 
+func (f *FrankenPHPModule) assignMercureHubRequestOption(ctx caddy.Context) {
+	if hub := mercureCaddy.FindHub(ctx.Modules()); hub != nil {
+		opt := frankenphp.WithMercureHub(hub)
+		f.mercureHubRequestOption = &opt
+	}
+}
+
 // parseCaddyfile unmarshals tokens from h into a new Middleware.
 func parseCaddyfile(h httpcaddyfile.Helper) (caddyhttp.MiddlewareHandler, error) {
 	m := &FrankenPHPModule{}

context.go

@@ -8,6 +8,8 @@ import (
 	"strconv"
 	"strings"
 	"time"
+
+	"github.com/dunglas/mercure"
 )
 
 // frankenPHPContext provides contextual information about the Request to handle.
@@ -34,6 +36,8 @@ type frankenPHPContext struct {
 
 	done      chan any
 	startedAt time.Time
+
+	mercureHub *mercure.Hub
 }
 
 // fromContext extracts the frankenPHPContext from a context.

docs/mercure.md

@@ -54,6 +54,29 @@ To subscribe to updates, use the native [`EventSource`](https://developer.mozill
 
 ## Publishing Updates
 
+### Using `mercure_publish()`
+
+FrankenPHP provides a convenient `mercure_publish()` function to publish updates to the built-in Mercure hub:
+
+```php
+<?php
+// public/publish.php
+
+$updateID = mercure_publish('my-topic',  json_encode(['key' => 'value']));
+
+// Write to FrankenPHP's logs
+error_log("update $updateID published", 4);
+```
+
+The full function signature is:
+
+```php
+/**
+ * @param string|string[] $topics
+ */
+function mercure_publish(string|array $topics, string $data = '', bool $private = false, ?string $id = null, ?string $type = null, ?int $retry = null): string {}
+```
+
 ### Using `file_get_contents()`
 
 To dispatch an update to connected subscribers, send an authenticated POST request to the Mercure hub with the `topic` and `data` parameters:

frankenphp.c

@@ -509,6 +509,47 @@ PHP_FUNCTION(headers_send) {
   RETURN_LONG(sapi_send_headers());
 }
 
+PHP_FUNCTION(mercure_publish) {
+  zval *topics;
+  zend_string *data = NULL, *id = NULL, *type = NULL;
+  zend_bool private = 0;
+  zend_long retry = 0;
+
+  ZEND_PARSE_PARAMETERS_START(1, 6)
+  Z_PARAM_ZVAL(topics)
+  Z_PARAM_OPTIONAL
+  Z_PARAM_STR_OR_NULL(data)
+  Z_PARAM_BOOL(private)
+  Z_PARAM_STR_OR_NULL(id)
+  Z_PARAM_STR_OR_NULL(type)
+  Z_PARAM_LONG(retry)
+  ZEND_PARSE_PARAMETERS_END();
+
+  if (Z_TYPE_P(topics) != IS_ARRAY && Z_TYPE_P(topics) != IS_STRING) {
+    zend_argument_type_error(1, "must be of type array|string");
+    RETURN_THROWS();
+  }
+
+  struct go_mercure_publish_return result =
+      go_mercure_publish(thread_index, topics, data, private, id, type, retry);
+
+  switch (result.r1) {
+  case 0:
+    RETURN_STR(result.r0);
+  case 1:
+    zend_throw_exception(spl_ce_RuntimeException, "No Mercure hub configured",
+                         0);
+    RETURN_THROWS();
+  case 2:
+    zend_throw_exception(spl_ce_RuntimeException, "Publish failed", 1);
+    RETURN_THROWS();
+  }
+
+  zend_throw_exception(spl_ce_RuntimeException,
+                       "FrankenPHP not built with Mercure support", 1);
+  RETURN_THROWS();
+}
+
 PHP_MINIT_FUNCTION(frankenphp) {
   zend_function *func;
 

frankenphp.go

@@ -37,6 +37,8 @@ import (
 	"unsafe"
 	// debug on Linux
 	//_ "github.com/ianlancetaylor/cgosymbolizer"
+
+	"github.com/dunglas/mercure"
 )
 
 type contextKeyStruct struct{}
@@ -591,6 +593,53 @@ func go_is_context_done(threadIndex C.uintptr_t) C.bool {
 	return C.bool(phpThreads[threadIndex].getRequestContext().isDone)
 }
 
+//export go_mercure_publish
+func go_mercure_publish(threadIndex C.uintptr_t, topics *C.struct__zval_struct, data unsafe.Pointer, private bool, id, typ unsafe.Pointer, retry uint64) (generatedID *C.zend_string, error C.short) {
+	fc := phpThreads[threadIndex].getRequestContext()
+
+	if fc.mercureHub == nil {
+		logger.Error("No Mercure hub configured")
+
+		return nil, 1
+	}
+
+	u := &mercure.Update{
+		Event: mercure.Event{
+			Data:  GoString(data),
+			ID:    GoString(id),
+			Retry: retry,
+			Type:  GoString(typ),
+		},
+		Private: private,
+	}
+
+	zvalType := C.zval_get_type(topics)
+	switch zvalType {
+	case C.IS_STRING:
+		u.Topics = []string{GoString(unsafe.Pointer(topics))}
+	case C.IS_ARRAY:
+		ts, err := GoPackedArray[string](unsafe.Pointer(topics))
+		if err != nil {
+			logger.Error("invalid topics type", slog.String("error", err.Error()))
+
+			return nil, 1
+		}
+
+		u.Topics = ts
+	default:
+		// Never happens as the function is called from C with proper types
+		panic("invalid topics type")
+	}
+
+	if err := fc.mercureHub.Publish(u); err != nil {
+		logger.Error("Unable to publish Mercure update", slog.String("error", err.Error()))
+
+		return nil, 2
+	}
+
+	return (*C.zend_string)(PHPString(u.ID, false)), 0
+}
+
 // ExecuteScriptCLI executes the PHP script passed as parameter.
 // It returns the exit status code of the script.
 func ExecuteScriptCLI(script string, args []string) int {

frankenphp.stub.php

@@ -32,3 +32,7 @@ function frankenphp_response_headers(): array|bool {}
  */
 function apache_response_headers(): array|bool {}
 
+/**
+ * @param string|string[] $topics
+ */
+function mercure_publish(string|array $topics, string $data = '', bool $private = false, ?string $id = null, ?string $type = null, ?int $retry = null): string {}

frankenphp_arginfo.h

@@ -1,52 +1,57 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 05ebde17137c559e891362fba6524fad1e0a2dfe */
+ * Stub hash: fcc86e17663887b089b79144e10ab3ca50ce3faa */
 
-ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_frankenphp_handle_request, 0, 1,
-                                        _IS_BOOL, 0)
-ZEND_ARG_TYPE_INFO(0, callback, IS_CALLABLE, 0)
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_frankenphp_handle_request, 0, 1, _IS_BOOL, 0)
+	ZEND_ARG_TYPE_INFO(0, callback, IS_CALLABLE, 0)
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_headers_send, 0, 0, IS_LONG, 0)
-ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, status, IS_LONG, 0, "200")
+	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, status, IS_LONG, 0, "200")
 ZEND_END_ARG_INFO()
 
-ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_frankenphp_finish_request, 0, 0,
-                                        _IS_BOOL, 0)
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_frankenphp_finish_request, 0, 0, _IS_BOOL, 0)
 ZEND_END_ARG_INFO()
 
 #define arginfo_fastcgi_finish_request arginfo_frankenphp_finish_request
 
-ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_frankenphp_request_headers, 0,
-                                        0, IS_ARRAY, 0)
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_frankenphp_request_headers, 0, 0, IS_ARRAY, 0)
 ZEND_END_ARG_INFO()
 
 #define arginfo_apache_request_headers arginfo_frankenphp_request_headers
 
 #define arginfo_getallheaders arginfo_frankenphp_request_headers
 
-ZEND_BEGIN_ARG_WITH_RETURN_TYPE_MASK_EX(arginfo_frankenphp_response_headers, 0,
-                                        0, MAY_BE_ARRAY | MAY_BE_BOOL)
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_MASK_EX(arginfo_frankenphp_response_headers, 0, 0, MAY_BE_ARRAY|MAY_BE_BOOL)
 ZEND_END_ARG_INFO()
 
 #define arginfo_apache_response_headers arginfo_frankenphp_response_headers
 
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_mercure_publish, 0, 1, IS_STRING, 0)
+	ZEND_ARG_INFO(0, topics)
+	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, data, IS_STRING, 0, "\'\'")
+	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, private, _IS_BOOL, 0, "false")
+	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, id, IS_STRING, 1, "null")
+	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, type, IS_STRING, 1, "null")
+	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, retry, IS_LONG, 1, "null")
+ZEND_END_ARG_INFO()
+
 ZEND_FUNCTION(frankenphp_handle_request);
 ZEND_FUNCTION(headers_send);
 ZEND_FUNCTION(frankenphp_finish_request);
 ZEND_FUNCTION(frankenphp_request_headers);
 ZEND_FUNCTION(frankenphp_response_headers);
+ZEND_FUNCTION(mercure_publish);
 
-// clang-format off
 static const zend_function_entry ext_functions[] = {
-  ZEND_FE(frankenphp_handle_request, arginfo_frankenphp_handle_request)
-  ZEND_FE(headers_send, arginfo_headers_send)
-  ZEND_FE(frankenphp_finish_request, arginfo_frankenphp_finish_request)
-  ZEND_FALIAS(fastcgi_finish_request, frankenphp_finish_request, arginfo_fastcgi_finish_request)
-  ZEND_FE(frankenphp_request_headers, arginfo_frankenphp_request_headers)
-  ZEND_FALIAS(apache_request_headers, frankenphp_request_headers, arginfo_apache_request_headers)
-  ZEND_FALIAS(getallheaders, frankenphp_request_headers, arginfo_getallheaders)
-  ZEND_FE(frankenphp_response_headers, arginfo_frankenphp_response_headers)
-  ZEND_FALIAS(apache_response_headers, frankenphp_response_headers, arginfo_apache_response_headers)
-  ZEND_FE_END
+	ZEND_FE(frankenphp_handle_request, arginfo_frankenphp_handle_request)
+	ZEND_FE(headers_send, arginfo_headers_send)
+	ZEND_FE(frankenphp_finish_request, arginfo_frankenphp_finish_request)
+	ZEND_RAW_FENTRY("fastcgi_finish_request", zif_frankenphp_finish_request, arginfo_fastcgi_finish_request, 0, NULL, NULL)
+	ZEND_FE(frankenphp_request_headers, arginfo_frankenphp_request_headers)
+	ZEND_RAW_FENTRY("apache_request_headers", zif_frankenphp_request_headers, arginfo_apache_request_headers, 0, NULL, NULL)
+	ZEND_RAW_FENTRY("getallheaders", zif_frankenphp_request_headers, arginfo_getallheaders, 0, NULL, NULL)
+	ZEND_FE(frankenphp_response_headers, arginfo_frankenphp_response_headers)
+	ZEND_RAW_FENTRY("apache_response_headers", zif_frankenphp_response_headers, arginfo_apache_response_headers, 0, NULL, NULL)
+	ZEND_FE(mercure_publish, arginfo_mercure_publish)
+	ZEND_FE_END
 };
-// clang-format on

request_options.go

@@ -8,6 +8,7 @@ import (
 	"sync/atomic"
 
 	"github.com/dunglas/frankenphp/internal/fastabs"
+	"github.com/dunglas/mercure"
 )
 
 // RequestOption instances allow to configure a FrankenPHP Request.
@@ -134,3 +135,12 @@ func WithWorkerName(name string) RequestOption {
 		return nil
 	}
 }
+
+// WithMercureHub sets the mercure.Hub to use to publish updates
+func WithMercureHub(hub *mercure.Hub) RequestOption {
+	return func(o *frankenPHPContext) error {
+		o.mercureHub = hub
+
+		return nil
+	}
+}