refactor: fold catch-all registry into *worker

Drops backgroundWorkerRegistry and its registry.workers/registry.declared
indirection; the per-scope lookup now resolves directly to the *worker
that owns each name, and the catch-all *worker hosts all of its
lazy-spawned threads in catchAllNames keyed by the runtime name.

worker struct gains:
- catchAllCap / catchAllMu / catchAllNames for the catch-all template
  (was registry.maxWorkers / registry.mu / registry.workers);
- bgLazyStartMu / bgLazyStarted to gate the first-thread spawn for
  num=0 named declarations.

backgroundWorkerThread gains runtimeName + backgroundReady so a single
catch-all *worker can host multiple per-name threads, each carrying its
own metric label, $_SERVER['FRANKENPHP_WORKER_NAME'] and readiness slot.
setupScript trims any "m#" prefix at the PHP boundary, so module-worker
metric labels stay m#-prefixed (unchanged) while PHP sees the user-facing
name.

ensure() picks named via lookup.byName (lazy-starting the first thread
under bgLazyStartMu when num=0) or catch-all via lookup.catchAll, locks
catchAllMu across the cap check + thread reservation + entry publication
so concurrent callers can't observe a phantom registration on a failed
allocation.

User-visible behaviour preserved: per-scope isolation, per-name $_SERVER
worker name, per-name metric buckets, max_threads cap on catch-alls,
named pool semantics, multi-entrypoint declarations.

Author: nicolas-grekas

background_worker_ensure_test.go

@@ -125,11 +125,11 @@ func TestEnsureBackgroundWorkerUndeclared(t *testing.T) {
 }
 
 // TestEnsureBackgroundWorkerConcurrent confirms the doc claim that ensure()
-// is safe to call concurrently: 16 goroutines hitting the same name produce
-// exactly one running worker, and the registry is left in a consistent state.
-// Without holding registry.mu across getInactivePHPThread, a race window
-// could let one caller publish a registration that another caller observes
-// just before the first caller fails thread allocation and rolls it back.
+// is safe to call concurrently: 16 goroutines hitting the same lazy-named
+// declaration produce exactly one spawned thread. Without serialising the
+// lazy-start gate (bgLazyStartMu), the second caller could observe the
+// flag before the first caller has completed thread reservation, leaving
+// the worker in an inconsistent state.
 func TestEnsureBackgroundWorkerConcurrent(t *testing.T) {
 	cwd, _ := os.Getwd()
 	testDataDir := cwd + "/testdata/"
@@ -161,17 +161,12 @@ func TestEnsureBackgroundWorkerConcurrent(t *testing.T) {
 		require.NoError(t, err, "goroutine %d", i)
 	}
 
-	// Registry should hold exactly one entry for the name; the worker
-	// itself should have exactly one attached thread.
+	// The lazy-named declaration should resolve to its single *worker,
+	// and exactly one thread should have been spawned by the lazy-start
+	// path despite the 16 concurrent ensure() callers.
 	lookup := backgroundLookups[0]
 	require.NotNil(t, lookup)
-	registry := lookup.resolve("bg-concurrent")
-	require.NotNil(t, registry)
-	registry.mu.Lock()
-	count := len(registry.workers)
-	w := registry.workers["bg-concurrent"]
-	registry.mu.Unlock()
-	assert.Equal(t, 1, count, "exactly one entry expected")
+	w := lookup.byName["bg-concurrent"]
 	require.NotNil(t, w)
 	assert.Equal(t, 1, w.countThreads(), "exactly one worker thread expected")
 }

background_worker_pool_test.go

@@ -49,9 +49,9 @@ func TestBackgroundWorkerPool(t *testing.T) {
 }
 
 // TestBackgroundWorkerMultiEntrypoint declares two named bg workers that
-// share the same entrypoint file. Each gets its own registry entry, so
-// both Init successfully (no filename-collision rejection) and both
-// produce sentinels.
+// share the same entrypoint file. Each gets its own *worker, so both Init
+// successfully (no filename-collision rejection) and both produce
+// sentinels.
 func TestBackgroundWorkerMultiEntrypoint(t *testing.T) {
 	cwd, _ := os.Getwd()
 	testDataDir := cwd + "/testdata/"

background_worker_scope_test.go

@@ -49,16 +49,16 @@ func TestBackgroundWorkerSameNameDifferentScope(t *testing.T) {
 	))
 	t.Cleanup(Shutdown)
 
-	// Both lookups must exist and resolve "shared" to a registry.
+	// Both lookups must exist and resolve "shared" to a *worker.
 	require.NotNil(t, backgroundLookups[scopeA], "scope A lookup missing")
 	require.NotNil(t, backgroundLookups[scopeB], "scope B lookup missing")
 	assert.NotNil(t, backgroundLookups[scopeA].byName["shared"], "scope A must resolve 'shared'")
 	assert.NotNil(t, backgroundLookups[scopeB].byName["shared"], "scope B must resolve 'shared'")
-	// And they must be distinct registries (not the same pointer).
+	// And they must be distinct *worker instances (not the same pointer).
 	assert.NotSame(t,
 		backgroundLookups[scopeA].byName["shared"],
 		backgroundLookups[scopeB].byName["shared"],
-		"each scope must own a distinct registry for the same name")
+		"each scope must own a distinct *worker for the same name")
 }
 
 // TestBackgroundWorkerCatchAllPerScope declares a catch-all in two
@@ -93,8 +93,8 @@ func TestBackgroundWorkerCatchAllPerScope(t *testing.T) {
 	t.Cleanup(Shutdown)
 
 	// Pre-conditions: each scope's catch-all is empty.
-	require.Empty(t, backgroundLookups[scopeA].catchAll.workers, "scope A catch-all must start empty")
-	require.Empty(t, backgroundLookups[scopeB].catchAll.workers, "scope B catch-all must start empty")
+	require.Empty(t, backgroundLookups[scopeA].catchAll.catchAllNames, "scope A catch-all must start empty")
+	require.Empty(t, backgroundLookups[scopeB].catchAll.catchAllNames, "scope B catch-all must start empty")
 
 	// Drive ensure() through a fake "request" context tagged to scope A.
 	// We use a request-scope tag (rather than a worker handler) because
@@ -108,31 +108,16 @@ func TestBackgroundWorkerCatchAllPerScope(t *testing.T) {
 
 	// The lazy-started instance must land in scope A's catch-all only.
 	require.Eventually(t, func() bool {
-		_, ok := backgroundLookups[scopeA].catchAll.workers["job-a"]
+		_, ok := backgroundLookups[scopeA].catchAll.catchAllNames["job-a"]
 		return ok
 	}, 2*time.Second, 10*time.Millisecond, "ensure() must populate scope A's catch-all")
-	assert.Empty(t, backgroundLookups[scopeB].catchAll.workers, "scope B catch-all must remain untouched")
-
-	// Verify the live workers slice has exactly one freshly-built bg
-	// worker carrying scope A and name "job-a", and zero workers named
-	// "job-a" carrying scope B (which would mean the wrong catch-all
-	// got consumed).
-	scalingMu.Lock()
-	var jobAInA, jobAInB int
-	for _, w := range workers {
-		if !w.isBackgroundWorker || w.name != "job-a" {
-			continue
-		}
-		switch w.backgroundScope {
-		case scopeA:
-			jobAInA++
-		case scopeB:
-			jobAInB++
-		}
-	}
-	scalingMu.Unlock()
-	assert.Equal(t, 1, jobAInA, "exactly one freshly-built bg worker must carry scope A and name 'job-a'")
-	assert.Equal(t, 0, jobAInB, "no 'job-a' worker must carry scope B (its catch-all wasn't ensured)")
+	assert.Empty(t, backgroundLookups[scopeB].catchAll.catchAllNames, "scope B catch-all must remain untouched")
+
+	// All catch-all threads attach to the scope's catch-all *worker, so
+	// scope A's catch-all should have one thread (for "job-a") while
+	// scope B's catch-all should have none.
+	assert.Equal(t, 1, backgroundLookups[scopeA].catchAll.countThreads(), "scope A catch-all must host exactly one thread")
+	assert.Equal(t, 0, backgroundLookups[scopeB].catchAll.countThreads(), "scope B catch-all must host zero threads")
 
 	// Wait for the worker to write its sentinel so we know the right
 	// fixture ran (sanity check that env was inherited from scope A).