feat: declared background workers + frankenphp_get_worker_handle()

caddy/app.go

@@ -17,7 +17,6 @@ import (
 	"github.com/caddyserver/caddy/v2/caddyconfig/httpcaddyfile"
 	"github.com/caddyserver/caddy/v2/modules/caddyhttp"
 	"github.com/dunglas/frankenphp"
-	"github.com/dunglas/frankenphp/internal/fastabs"
 )
 
 var (
@@ -60,15 +59,14 @@ type FrankenPHPApp struct {
 	// EXPERIMENTAL: MaxRequests sets the maximum number of requests a PHP thread handles before restarting (0 = unlimited)
 	MaxRequests int `json:"max_requests,omitempty"`
 
-	opts            []frankenphp.Option
-	metrics         frankenphp.Metrics
-	ctx             context.Context
-	logger          *slog.Logger
-	modules         []*FrankenPHPModule
-	usedWorkerNames map[string]bool
-	httpApp         *caddyhttp.App
-	hasStarted      atomic.Bool
-	started         chan any
+	opts       []frankenphp.Option
+	metrics    frankenphp.Metrics
+	ctx        context.Context
+	logger     *slog.Logger
+	modules    []*FrankenPHPModule
+	httpApp    *caddyhttp.App
+	hasStarted atomic.Bool
+	started    chan any
 }
 
 var errIni = errors.New(`"php_ini" must be in the format: php_ini "<key>" "<value>"`)
@@ -133,7 +131,6 @@ func (f *FrankenPHPApp) Start() error {
 	// register global workers
 	for _, w := range f.Workers {
 		w.FileName = repl.ReplaceKnown(w.FileName, "")
-		w.Name = f.createUniqueWorkerName(w, "")
 		opts, err := w.toWorkerOptions()
 		if err != nil {
 			return err
@@ -224,7 +221,6 @@ func (f *FrankenPHPApp) registerModule(repl *caddy.Replacer, module *FrankenPHPM
 
 	for _, w := range module.Workers {
 		w.FileName = repl.ReplaceKnown(w.FileName, "")
-		w.Name = f.createUniqueWorkerName(w, serverName)
 		workerOptions, err := w.toWorkerOptions()
 		if err != nil {
 			return err
@@ -236,37 +232,6 @@ func (f *FrankenPHPApp) registerModule(repl *caddy.Replacer, module *FrankenPHPM
 	return nil
 }
 
-// avoid name collisions for workers
-// on collision, a name is first qualified with the server name
-// ("<serverName>:<name>") before falling back to a numeric postfix
-func (f *FrankenPHPApp) createUniqueWorkerName(wc workerConfig, serverName string) string {
-	if f.usedWorkerNames == nil {
-		f.usedWorkerNames = make(map[string]bool)
-	}
-
-	if wc.Name == "" {
-		wc.Name, _ = fastabs.FastAbs(wc.FileName)
-	}
-
-	name := wc.Name
-	suffix := 0
-	for {
-		if _, ok := f.usedWorkerNames[name]; !ok {
-			f.usedWorkerNames[name] = true
-			break
-		}
-		if serverName != "" {
-			name = serverName + ":" + wc.Name
-			serverName = ""
-			continue
-		}
-		suffix++
-		name = fmt.Sprintf("%s_%d", wc.Name, suffix)
-	}
-
-	return name
-}
-
 // UnmarshalCaddyfile implements caddyfile.Unmarshaler.
 func (f *FrankenPHPApp) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
 	for d.Next() {
@@ -381,10 +346,13 @@ func (f *FrankenPHPApp) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
 				if len(wc.MatchPath) != 0 {
 					return d.Errf(`"match" can only be used in a php_server worker block, not in a global one: %q`, wc.FileName)
 				}
-				// check for duplicate workers
-				for _, existingWorker := range f.Workers {
-					if existingWorker.FileName == wc.FileName {
-						return d.Errf("global workers must not have duplicate filenames: %q", wc.FileName)
+				// check for duplicate workers; background workers are keyed
+				// by name, several may share a script
+				if !wc.Background {
+					for _, existingWorker := range f.Workers {
+						if !existingWorker.Background && existingWorker.FileName == wc.FileName {
+							return d.Errf("global workers must not have duplicate filenames: %q", wc.FileName)
+						}
 					}
 				}
 

caddy/caddy_test.go

@@ -757,6 +757,45 @@ func TestMetrics(t *testing.T) {
 	require.NoError(t, testutil.GatherAndCompare(ctx.GetMetricsRegistry(), strings.NewReader(expectedMetrics), "frankenphp_total_threads", "frankenphp_busy_threads"))
 }
 
+// TestBackgroundWorkerFromCaddyfile starts a background worker from a
+// Caddyfile and checks it runs: the sentinel its script touches appears
+func TestBackgroundWorkerFromCaddyfile(t *testing.T) {
+	sentinel := filepath.ToSlash(filepath.Join(t.TempDir(), "bg.sentinel"))
+	tester := caddytest.NewTester(t)
+	initServer(t, tester, `
+	{
+		skip_install_trust
+		admin localhost:2999
+		http_port `+testPort+`
+		https_port 9443
+
+		frankenphp {
+			worker {
+				file ../testdata/bgworker/basic.php
+				num 1
+				name bg-caddy
+				background
+				env BG_SENTINEL `+sentinel+`
+			}
+		}
+	}
+
+	localhost:`+testPort+` {
+		route {
+			php {
+				root ../testdata
+			}
+		}
+	}
+	`, "caddyfile")
+
+	require.Eventually(t, func() bool {
+		_, err := os.Stat(sentinel)
+
+		return err == nil
+	}, 5*time.Second, 25*time.Millisecond, "the background worker declared in the Caddyfile did not run")
+}
+
 func TestWorkerMetrics(t *testing.T) {
 	var wg sync.WaitGroup
 	tester := caddytest.NewTester(t)
@@ -839,7 +878,7 @@ func TestWorkerMetrics(t *testing.T) {
 	# TYPE frankenphp_worker_request_count counter
 	frankenphp_worker_request_count{worker="` + workerName + `"} 10
 
-	# HELP frankenphp_ready_workers Running workers that have successfully called frankenphp_handle_request at least once
+	# HELP frankenphp_ready_workers Running workers that have reached their ready point at least once: frankenphp_handle_request for HTTP workers, frankenphp_worker_tick for background workers
 	# TYPE frankenphp_ready_workers gauge
 	frankenphp_ready_workers{worker="` + workerName + `"} 2
 	`
@@ -996,7 +1035,7 @@ func TestNamedWorkerMetrics(t *testing.T) {
 	# TYPE frankenphp_worker_request_count counter
 	frankenphp_worker_request_count{worker="my_app"} 10
 
-	# HELP frankenphp_ready_workers Running workers that have successfully called frankenphp_handle_request at least once
+	# HELP frankenphp_ready_workers Running workers that have reached their ready point at least once: frankenphp_handle_request for HTTP workers, frankenphp_worker_tick for background workers
 	# TYPE frankenphp_ready_workers gauge
 	frankenphp_ready_workers{worker="my_app"} 2
 	`
@@ -1092,7 +1131,7 @@ func TestAutoWorkerConfig(t *testing.T) {
 	# TYPE frankenphp_worker_request_count counter
 	frankenphp_worker_request_count{worker="` + workerName + `"} 10
 
-	# HELP frankenphp_ready_workers Running workers that have successfully called frankenphp_handle_request at least once
+	# HELP frankenphp_ready_workers Running workers that have reached their ready point at least once: frankenphp_handle_request for HTTP workers, frankenphp_worker_tick for background workers
 	# TYPE frankenphp_ready_workers gauge
 	frankenphp_ready_workers{worker="` + workerName + `"} ` + workers + `
 	`
@@ -1460,7 +1499,7 @@ func TestMultiWorkersMetrics(t *testing.T) {
 	# TYPE frankenphp_worker_request_count counter
 	frankenphp_worker_request_count{worker="service1"} 10
 
-	# HELP frankenphp_ready_workers Running workers that have successfully called frankenphp_handle_request at least once
+	# HELP frankenphp_ready_workers Running workers that have reached their ready point at least once: frankenphp_handle_request for HTTP workers, frankenphp_worker_tick for background workers
 	# TYPE frankenphp_ready_workers gauge
 	frankenphp_ready_workers{worker="service1"} 2
 	frankenphp_ready_workers{worker="service2"} 3
@@ -1614,7 +1653,7 @@ func TestWorkerRestart(t *testing.T) {
 
 	// Check metrics
 	expectedMetrics := `
-	# HELP frankenphp_ready_workers Running workers that have successfully called frankenphp_handle_request at least once
+	# HELP frankenphp_ready_workers Running workers that have reached their ready point at least once: frankenphp_handle_request for HTTP workers, frankenphp_worker_tick for background workers
 	# TYPE frankenphp_ready_workers gauge
 	frankenphp_ready_workers{worker="service"} 1
 	# HELP frankenphp_total_workers Total number of PHP workers for this worker
@@ -1642,7 +1681,7 @@ func TestWorkerRestart(t *testing.T) {
 
 	// frankenphp_ready_workers should be back to 1 even after worker restarts
 	expectedMetrics = `
-	# HELP frankenphp_ready_workers Running workers that have successfully called frankenphp_handle_request at least once
+	# HELP frankenphp_ready_workers Running workers that have reached their ready point at least once: frankenphp_handle_request for HTTP workers, frankenphp_worker_tick for background workers
 	# TYPE frankenphp_ready_workers gauge
 	frankenphp_ready_workers{worker="service"} 1
 	# HELP frankenphp_total_workers Total number of PHP workers for this worker
@@ -2113,7 +2152,7 @@ func TestSymlinkWorkerBehavior(t *testing.T) {
 
 		// Accessing the worker script without worker configuration MUST fail
 		// The script checks $_SERVER['FRANKENPHP_WORKER'] and dies if not set
-		tester.AssertGetResponse("http://localhost:"+testPort+"/index.php", http.StatusOK, "Error: This script must be run in worker mode (FRANKENPHP_WORKER not set to '1')\n")
+		tester.AssertGetResponse("http://localhost:"+testPort+"/index.php", http.StatusOK, "Error: This script must be run in worker mode (FRANKENPHP_WORKER not set)\n")
 	})
 
 	t.Run("MultipleRequests", func(t *testing.T) {

caddy/config_test.go

@@ -1,7 +1,6 @@
 package caddy
 
 import (
-	"path/filepath"
 	"testing"
 	"time"
 
@@ -81,6 +80,45 @@ func TestModuleWorkerDuplicateFilenamesFail(t *testing.T) {
 	require.Contains(t, err.Error(), "must not have duplicate filenames", "Error message should mention duplicate filenames")
 }
 
+// two global background workers may share a script, like their php_server
+// counterparts and the Go API: they are keyed by name
+func TestGlobalBackgroundWorkersShareAFilename(t *testing.T) {
+	d := caddyfile.NewTestDispenser(`
+	{
+		frankenphp {
+			worker {
+				name first
+				file ../testdata/worker-with-env.php
+				num 1
+				background
+			}
+			worker {
+				name second
+				file ../testdata/worker-with-env.php
+				num 1
+				background
+			}
+		}
+	}`)
+	app := &FrankenPHPApp{}
+
+	require.NoError(t, app.UnmarshalCaddyfile(d))
+	require.Len(t, app.Workers, 2)
+}
+
+func TestGlobalWorkerDuplicateFilenamesFail(t *testing.T) {
+	d := caddyfile.NewTestDispenser(`
+	{
+		frankenphp {
+			worker ../testdata/worker-with-env.php
+			worker ../testdata/worker-with-env.php
+		}
+	}`)
+	app := &FrankenPHPApp{}
+
+	require.ErrorContains(t, app.UnmarshalCaddyfile(d), "must not have duplicate filenames")
+}
+
 func TestModuleWorkersWithDifferentFilenames(t *testing.T) {
 	// Create a test configuration with different worker filenames
 	configWithDifferentFilenames := `
@@ -249,38 +287,73 @@ func TestModuleWorkerWithCustomName(t *testing.T) {
 	require.Equal(t, "../testdata/worker-with-env.php", module.Workers[0].FileName, "Worker should have the correct filename")
 }
 
-func TestCreateUniqueWorkerNames(t *testing.T) {
-	app := &FrankenPHPApp{}
-	filename := "../testdata/worker-with-env.php"
-	absFileName, _ := filepath.Abs(filename)
-	names := make([]string, 6)
-	for i := range 3 {
-		names[i] = app.createUniqueWorkerName(workerConfig{
-			FileName: filename,
-			Name:     "custom-worker-name",
-		}, "")
-		names[i+3] = app.createUniqueWorkerName(workerConfig{
-			FileName: filename,
-		}, "")
-	}
-
-	require.Equal(t, "custom-worker-name", names[0])
-	require.Equal(t, "custom-worker-name_1", names[1])
-	require.Equal(t, "custom-worker-name_2", names[2])
-	require.Equal(t, absFileName, names[3])
-	require.Equal(t, absFileName+"_1", names[4])
-	require.Equal(t, absFileName+"_2", names[5])
+func TestWorkerBackgroundConfig(t *testing.T) {
+	d := caddyfile.NewTestDispenser(`
+	{
+		php_server {
+			worker {
+				name jobs
+				file ../testdata/worker-with-env.php
+				num 2
+				background
+			}
+		}
+	}`)
+	module := &FrankenPHPModule{}
+
+	require.NoError(t, module.UnmarshalCaddyfile(d))
+	require.Len(t, module.Workers, 1)
+	require.True(t, module.Workers[0].Background)
+	require.Equal(t, "jobs", module.Workers[0].Name)
 }
 
-func TestCreateUniqueWorkerNamesQualifiedByServer(t *testing.T) {
-	app := &FrankenPHPApp{}
-	wc := workerConfig{FileName: "../testdata/worker-with-env.php", Name: "queue"}
-
-	require.Equal(t, "queue", app.createUniqueWorkerName(wc, "one.example.com"))
-	// on collision, the name is qualified with the server name
-	require.Equal(t, "two.example.com:queue", app.createUniqueWorkerName(wc, "two.example.com"))
-	// when the qualified name is also taken, fall back to the numeric postfix
-	require.Equal(t, "queue_1", app.createUniqueWorkerName(wc, "two.example.com"))
-	// workers without a server keep the numeric postfix behavior
-	require.Equal(t, "queue_2", app.createUniqueWorkerName(wc, ""))
+func TestWorkerBackgroundRequiresName(t *testing.T) {
+	d := caddyfile.NewTestDispenser(`
+	{
+		php_server {
+			worker {
+				file ../testdata/worker-with-env.php
+				background
+			}
+		}
+	}`)
+	module := &FrankenPHPModule{}
+
+	err := module.UnmarshalCaddyfile(d)
+	require.ErrorContains(t, err, `background workers must have an explicit "name"`)
+}
+
+func TestWorkerBackgroundWithoutNumParses(t *testing.T) {
+	d := caddyfile.NewTestDispenser(`
+	{
+		php_server {
+			worker {
+				name jobs
+				file ../testdata/worker-with-env.php
+				background
+			}
+		}
+	}`)
+	module := &FrankenPHPModule{}
+
+	// num is optional, it defaults to one thread when the workers start
+	require.NoError(t, module.UnmarshalCaddyfile(d))
+}
+
+func TestWorkerBackgroundRejectsMatch(t *testing.T) {
+	d := caddyfile.NewTestDispenser(`
+	{
+		php_server {
+			worker {
+				name jobs
+				file ../testdata/worker-with-env.php
+				match /jobs/*
+				background
+			}
+		}
+	}`)
+	module := &FrankenPHPModule{}
+
+	err := module.UnmarshalCaddyfile(d)
+	require.ErrorContains(t, err, `"match" is not supported for background workers`)
 }

caddy/module.go

@@ -315,6 +315,10 @@ func (f *FrankenPHPModule) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
 	// Check if a worker with this filename already exists in this module
 	fileNames := make(map[string]struct{}, len(f.Workers))
 	for _, w := range f.Workers {
+		// background workers are keyed by name, several may share a script
+		if w.Background {
+			continue
+		}
 		if _, ok := fileNames[w.FileName]; ok {
 			return fmt.Errorf(`workers in a single "php" or "php_server" block must not have duplicate filenames: %q`, w.FileName)
 		}