feat: per-php_server background worker scoping

Adds a BackgroundScope opaque type (int under the hood; obtain values
via NextBackgroundWorkerScope) so each php_server block gets its own
isolation boundary for background workers. Zero is the global/embed
scope.

- backgroundLookups map[BackgroundScope]*backgroundWorkerLookup
  replaces the single global backgroundLookup. Each scope has its own
  named registry + catch-all so two blocks can declare bg workers with
  the same user-facing name without colliding.

- buildBackgroundWorkerLookups iterates declarations into their scope's
  lookup; each declaration still owns its own registry. registry.declared
  remembers the *worker for a named declaration so lazy-start (num=0)
  reuses it without scanning the global workersByName map (which is not
  scope-aware for bg workers).

- getLookup(thread) resolves the active scope from the calling thread:
  worker handler -> request context -> global (0). Scopes that declared
  their own workers stay strictly isolated; an empty scope falls through
  to the global lookup so embed-mode workers stay reachable.

- Go options: WithWorkerBackgroundScope tags a declaration; the new
  WithRequestBackgroundScope tags a request so ensure() from a regular
  HTTP request resolves to the right block's lookup.

- Caddy wiring: FrankenPHPModule.Provision allocates one scope per
  module instance (idempotent across re-provisions) and threads it into
  worker declarations and ServeHTTP.

- workersByName collision check now skips bg workers; they resolve via
  their scope's lookup, so the same PHP-visible name can appear in two
  scopes without tripping the duplicate guard.

- C side: go_frankenphp_ensure_background_worker now takes the calling
  thread index so getLookup can resolve the scope from the active
  handler / request context.

Tests:

- TestNextBackgroundWorkerScopeIsDistinct: counter hands out unique
  non-zero scopes.
- TestBackgroundWorkerSameNameDifferentScope: two named bg workers with
  the same user-facing name in distinct scopes both Init successfully
  and own distinct registries.
- TestBackgroundWorkerCatchAllPerScope: ensure() in scope A consumes
  scope A's catch-all only; scope B's catch-all stays empty. Verified
  by inspecting the per-scope lookup and the live workers slice via
  package-internal access.

Deferred to follow-ups: pools (num > 1 per named worker, max_threads > 1
for named workers), multiple declarations sharing one entrypoint file
in one scope, FRANKENPHP_WORKER_BACKGROUND server flag, batch ensure.

Author: nicolas-grekas

background_worker.go

@@ -7,17 +7,33 @@ import (
 	"log/slog"
 	"strings"
 	"sync"
+	"sync/atomic"
 )
 
 // defaultMaxBackgroundWorkers is the default safety cap for catch-all
 // background workers when the user doesn't set max_threads. Caps the
 // number of distinct lazy-started instances from a single catch-all.
 const defaultMaxBackgroundWorkers = 16
 
-// backgroundLookup is the registry that resolves a worker name to either
-// a named declaration or the catch-all. Single global scope in this step;
-// follow-ups replace this with a per-php_server scope map.
-var backgroundLookup *backgroundWorkerLookup
+// BackgroundScope identifies an isolation boundary for background workers.
+// Each php_server block uses a distinct scope so that two blocks can
+// declare workers with the same name without conflict. The zero value is
+// the global/embed scope (used when no per-block scope was assigned).
+// Representation is opaque; obtain values via NextBackgroundWorkerScope.
+type BackgroundScope int
+
+var backgroundScopeCounter atomic.Uint64
+
+// NextBackgroundWorkerScope returns a unique scope for background worker
+// isolation. Each php_server block should call this once during
+// provisioning.
+func NextBackgroundWorkerScope() BackgroundScope {
+	return BackgroundScope(backgroundScopeCounter.Add(1))
+}
+
+// backgroundLookups maps scopes to their background worker lookup.
+// Scope 0 is the global/embed scope; each php_server block gets its own.
+var backgroundLookups map[BackgroundScope]*backgroundWorkerLookup
 
 // backgroundWorkerLookup maps worker names to their registry, with a
 // separate slot for the catch-all (name-less) declaration.
@@ -53,11 +69,20 @@ type backgroundWorkerRegistry struct {
 	workers map[string]*worker
 
 	// Template options preserved so lazy-started workers inherit the same
-	// env/watch/failure policy as their eagerly-started siblings.
+	// scope/env/watch/failure policy as their eagerly-started siblings.
+	scope                  BackgroundScope
 	env                    PreparedEnv
 	watch                  []string
 	maxConsecutiveFailures int
 	requestOptions         []RequestOption
+
+	// declared is the pre-existing *worker for a named declaration. It
+	// lets lazy-start (num=0 named) reuse the already-built worker
+	// struct without scanning the global workersByName map (which is not
+	// scope-aware: scoped bg workers sharing a user-facing name would
+	// otherwise collide). nil for catch-all registries (each lazy-
+	// started name gets a fresh worker).
+	declared *worker
 }
 
 func newBackgroundWorkerRegistry(entrypoint string) *backgroundWorkerRegistry {
@@ -68,18 +93,30 @@ func newBackgroundWorkerRegistry(entrypoint string) *backgroundWorkerRegistry {
 	}
 }
 
-// buildBackgroundWorkerLookup constructs the name->registry map + catch-all
-// slot from declared worker options. Each declaration gets its own registry
-// so shared-entrypoint declarations keep their own template options.
-func buildBackgroundWorkerLookup(workers []*worker, opts []workerOpt) *backgroundWorkerLookup {
-	var lookup *backgroundWorkerLookup
+// buildBackgroundWorkerLookups constructs a scope->lookup map from declared
+// worker options. Each scope (php_server block, or 0 for global/embed)
+// gets its own lookup so workers declared with the same name in different
+// blocks don't collide. Each declaration gets its own registry so shared-
+// entrypoint declarations keep their own template options.
+//
+// Per-scope namespace collisions are caught here (rather than via the
+// global workersByName check in newWorker) because bg workers
+// intentionally skip workersByName so two scopes can share a user-facing
+// name. That gap means same-scope duplicates wouldn't otherwise be
+// detected; same goes for two catch-alls in one scope.
+func buildBackgroundWorkerLookups(workers []*worker, opts []workerOpt) (map[BackgroundScope]*backgroundWorkerLookup, error) {
+	lookups := make(map[BackgroundScope]*backgroundWorkerLookup)
 
 	for i, o := range opts {
 		if !o.isBackgroundWorker {
 			continue
 		}
-		if lookup == nil {
+
+		scope := o.backgroundScope
+		lookup, ok := lookups[scope]
+		if !ok {
 			lookup = newBackgroundWorkerLookup()
+			lookups[scope] = lookup
 		}
 
 		w := workers[i]
@@ -90,14 +127,23 @@ func buildBackgroundWorkerLookup(workers []*worker, opts []workerOpt) *backgroun
 		// require/__FILE__ identity tests behave differently between the
 		// two paths.
 		registry := newBackgroundWorkerRegistry(w.fileName)
+		registry.scope = scope
 		registry.env = o.env
 		registry.watch = o.watch
 		registry.maxConsecutiveFailures = o.maxConsecutiveFailures
 		registry.requestOptions = o.requestOptions
 
+		w.backgroundScope = scope
 		phpName := strings.TrimPrefix(w.name, "m#")
 		if phpName != "" && phpName != w.fileName {
+			if _, exists := lookup.byName[phpName]; exists {
+				return nil, fmt.Errorf("duplicate background worker name %q in the same scope", phpName)
+			}
 			lookup.byName[phpName] = registry
+			// Named declaration: remember the *worker so lazy-start can
+			// reuse it instead of scanning workersByName (which is not
+			// scope-aware for bg workers).
+			registry.declared = w
 			// Eagerly-started named workers (num > 0) register themselves
 			// so a later ensure() observes the live instance instead of
 			// trying to spawn a duplicate. Lazy named workers (num == 0)
@@ -106,6 +152,9 @@ func buildBackgroundWorkerLookup(workers []*worker, opts []workerOpt) *backgroun
 				registry.workers[phpName] = w
 			}
 		} else {
+			if lookup.catchAll != nil {
+				return nil, fmt.Errorf("duplicate catch-all background worker in the same scope")
+			}
 			maxW := defaultMaxBackgroundWorkers
 			if o.maxThreads > 1 {
 				maxW = o.maxThreads
@@ -117,22 +166,61 @@ func buildBackgroundWorkerLookup(workers []*worker, opts []workerOpt) *backgroun
 		w.backgroundRegistry = registry
 	}
 
-	return lookup
+	if len(lookups) == 0 {
+		return nil, nil
+	}
+	return lookups, nil
+}
+
+// getLookup returns the background-worker lookup for the given thread.
+// The scope is resolved from the thread's handler (for worker threads
+// inheriting their worker's scope) or from the request context (for
+// regular HTTP threads with WithRequestBackgroundScope).
+//
+// If the resolved scope has no workers declared (its lookup is nil), the
+// caller falls through to the global/embed scope (0) so that globally-
+// declared workers remain reachable from scoped requests. Scopes that
+// declared their own workers stay strictly isolated because their lookup
+// is non-nil.
+func getLookup(thread *phpThread) *backgroundWorkerLookup {
+	if backgroundLookups == nil {
+		return nil
+	}
+	var scope BackgroundScope
+	if thread != nil {
+		switch handler := thread.handler.(type) {
+		case *workerThread:
+			scope = handler.worker.backgroundScope
+		case *backgroundWorkerThread:
+			scope = handler.worker.backgroundScope
+		default:
+			if fc, ok := fromContext(thread.context()); ok {
+				scope = fc.backgroundScope
+			}
+		}
+	}
+	if scope != 0 {
+		if l := backgroundLookups[scope]; l != nil {
+			return l
+		}
+	}
+	return backgroundLookups[0]
 }
 
 // ensureBackgroundWorker lazy-starts the named worker if it is not already
 // running. Fire-and-forget: returns once the bg worker thread has been
 // launched, without waiting for the PHP script to reach any particular
 // state. Safe to call concurrently; only the first caller actually
 // allocates the instance, the rest see the existing one.
-func ensureBackgroundWorker(bgWorkerName string) error {
+func ensureBackgroundWorker(thread *phpThread, bgWorkerName string) error {
 	if bgWorkerName == "" {
 		return fmt.Errorf("background worker name must not be empty")
 	}
-	if backgroundLookup == nil {
+	lookup := getLookup(thread)
+	if lookup == nil {
 		return fmt.Errorf("no background worker configured")
 	}
-	registry := backgroundLookup.resolve(bgWorkerName)
+	registry := lookup.resolve(bgWorkerName)
 	if registry == nil || registry.entrypoint == "" {
 		return fmt.Errorf("no background worker configured for name %q", bgWorkerName)
 	}
@@ -149,12 +237,16 @@ func ensureBackgroundWorker(bgWorkerName string) error {
 	}
 
 	// A num=0 named declaration already created a worker struct at init
-	// time; reuse it instead of creating a duplicate. Catch-all instances
-	// (different names, different worker structs) get freshly built.
+	// time; reuse it instead of creating a duplicate. Named bg workers
+	// across distinct scopes share the user-facing PHP name but each has
+	// its own *worker struct, so we look it up via registry.declared
+	// rather than the global workersByName map (which is not scope-aware
+	// for bg workers). For catch-all (registry.declared == nil), each
+	// lazy-started name gets a fresh *worker.
 	var w *worker
 	freshlyBuilt := false
-	if existing := workersByName[bgWorkerName]; existing != nil && existing.isBackgroundWorker {
-		w = existing
+	if registry.declared != nil {
+		w = registry.declared
 	} else {
 		// Clone env and slices: newWorker mutates env (writes
 		// FRANKENPHP_WORKER) and appends to requestOptions, so sharing
@@ -173,6 +265,7 @@ func ensureBackgroundWorker(bgWorkerName string) error {
 			fileName:               registry.entrypoint,
 			num:                    1,
 			isBackgroundWorker:     true,
+			backgroundScope:        registry.scope,
 			env:                    env,
 			watch:                  watch,
 			maxConsecutiveFailures: registry.maxConsecutiveFailures,
@@ -185,6 +278,7 @@ func ensureBackgroundWorker(bgWorkerName string) error {
 		freshlyBuilt = true
 	}
 	w.backgroundRegistry = registry
+	w.backgroundScope = registry.scope
 	registry.workers[bgWorkerName] = w
 	registry.mu.Unlock()
 
@@ -200,7 +294,9 @@ func ensureBackgroundWorker(bgWorkerName string) error {
 		scalingMu.Lock()
 		workers = append(workers, w)
 		scalingMu.Unlock()
-		workersByName[bgWorkerName] = w
+		// Intentionally NOT registered in workersByName: bg workers are
+		// resolved per-scope via backgroundLookups, not via the global
+		// name map, so two scopes can share a user-facing name.
 	}
 
 	convertToBackgroundWorkerThread(t, w)
@@ -219,11 +315,11 @@ func ensureBackgroundWorker(bgWorkerName string) error {
 // this step, so callers cannot block on the worker reaching any state.
 //
 //export go_frankenphp_ensure_background_worker
-func go_frankenphp_ensure_background_worker(name *C.char, nameLen C.size_t) *C.char {
+func go_frankenphp_ensure_background_worker(threadIndex C.uintptr_t, name *C.char, nameLen C.size_t) *C.char {
+	thread := phpThreads[threadIndex]
 	goName := C.GoStringN(name, C.int(nameLen))
-	if err := ensureBackgroundWorker(goName); err != nil {
+	if err := ensureBackgroundWorker(thread, goName); err != nil {
 		return C.CString(err.Error())
 	}
 	return nil
 }
-

background_worker_ensure_test.go

@@ -46,7 +46,7 @@ func TestEnsureBackgroundWorkerNamedLazy(t *testing.T) {
 	_, err := os.Stat(filepath.Join(tmp, "bg-lazy"))
 	require.True(t, os.IsNotExist(err), "lazy worker should not have started yet")
 
-	require.NoError(t, ensureBackgroundWorker("bg-lazy"))
+	require.NoError(t, ensureBackgroundWorker(nil,"bg-lazy"))
 	assert.True(t, waitForSentinel(t, filepath.Join(tmp, "bg-lazy"), 5*time.Second),
 		"ensure() should have lazy-started the named bg worker")
 }
@@ -71,7 +71,7 @@ func TestEnsureBackgroundWorkerCatchAll(t *testing.T) {
 	t.Cleanup(Shutdown)
 
 	for _, name := range []string{"job-a", "job-b"} {
-		require.NoError(t, ensureBackgroundWorker(name), "ensure(%s)", name)
+		require.NoError(t, ensureBackgroundWorker(nil,name), "ensure(%s)", name)
 	}
 
 	for _, name := range []string{"job-a", "job-b"} {
@@ -98,10 +98,10 @@ func TestEnsureBackgroundWorkerCatchAllCap(t *testing.T) {
 	))
 	t.Cleanup(Shutdown)
 
-	require.NoError(t, ensureBackgroundWorker("cap-a"))
-	require.NoError(t, ensureBackgroundWorker("cap-b"))
+	require.NoError(t, ensureBackgroundWorker(nil,"cap-a"))
+	require.NoError(t, ensureBackgroundWorker(nil,"cap-b"))
 
-	err := ensureBackgroundWorker("cap-c")
+	err := ensureBackgroundWorker(nil,"cap-c")
 	require.Error(t, err, "third ensure must hit the catch-all cap")
 	assert.Contains(t, err.Error(), "limit of 2 reached")
 }
@@ -120,7 +120,7 @@ func TestEnsureBackgroundWorkerUndeclared(t *testing.T) {
 	))
 	t.Cleanup(Shutdown)
 
-	err := ensureBackgroundWorker("other-name")
+	err := ensureBackgroundWorker(nil,"other-name")
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "no background worker configured for name")
 }