refactor: decouple backgroundWorkerThread from workerThread

backgroundWorkerThread no longer embeds workerThread. It owns its own
lifecycle state (failureCount, isBootingScript, dummyContext) and
inlines the teardown logic. This prevents HTTP worker changes from
accidentally affecting background workers.

Also moves backgroundWorkerState and markBackgroundReady to
threadbackgroundworker.go where they belong.

Author: nicolas-grekas

background_worker.go

@@ -8,7 +8,6 @@ import (
 	"log/slog"
 	"strings"
 	"sync"
-	"sync/atomic"
 	"time"
 	"unsafe"
 )
@@ -56,14 +55,6 @@ func (l *backgroundWorkerLookup) Resolve(name string) *backgroundWorkerRegistry
 	return l.catchAll
 }
 
-type backgroundWorkerState struct {
-	varsPtr     unsafe.Pointer // *C.HashTable, persistent, managed by C
-	mu          sync.RWMutex
-	varsVersion atomic.Uint64 // incremented on each set_vars call
-	ready       chan struct{}
-	readyOnce   sync.Once
-}
-
 type backgroundWorkerRegistry struct {
 	entrypoint     string
 	num            int      // threads per background worker (0 = lazy-start with 1 thread)
@@ -393,9 +384,8 @@ func go_frankenphp_worker_set_vars(threadIndex C.uintptr_t, varsPtr unsafe.Point
 	if !ok || bgHandler.worker.backgroundWorker == nil {
 		return C.CString("frankenphp_worker_set_vars() can only be called from a background worker")
 	}
-	handler := &bgHandler.workerThread
 
-	sk := handler.worker.backgroundWorker
+	sk := bgHandler.worker.backgroundWorker
 
 	sk.mu.Lock()
 	*oldPtr = sk.varsPtr
@@ -404,7 +394,7 @@ func go_frankenphp_worker_set_vars(threadIndex C.uintptr_t, varsPtr unsafe.Point
 	sk.mu.Unlock()
 
 	sk.readyOnce.Do(func() {
-		handler.markBackgroundReady()
+		bgHandler.markBackgroundReady()
 		close(sk.ready)
 	})
 

background_worker_test.go

@@ -79,7 +79,7 @@ func TestBackgroundWorkerSetVarsMarksWorkerReady(t *testing.T) {
 		metrics = originalMetrics
 	})
 
-	handler := &workerThread{
+	handler := &backgroundWorkerThread{
 		thread:          newPHPThread(0),
 		worker:          &worker{name: "background-worker", fileName: "background-worker.php", maxConsecutiveFailures: -1},
 		isBootingScript: true,
@@ -101,7 +101,7 @@ func TestBackgroundWorkerBootFailureStaysBootFailureUntilReady(t *testing.T) {
 		metrics = originalMetrics
 	})
 
-	handler := &workerThread{
+	handler := &backgroundWorkerThread{
 		thread: newPHPThread(0),
 		worker: &worker{
 			name:                   "background-worker",
@@ -111,14 +111,14 @@ func TestBackgroundWorkerBootFailureStaysBootFailureUntilReady(t *testing.T) {
 		isBootingScript: true,
 	}
 
-	tearDownWorkerScript(handler, 1)
+	handler.afterScriptExecution(1)
 	require.Len(t, testMetrics.stopCalls, 1)
 	assert.Equal(t, StopReason(StopReasonBootFailure), testMetrics.stopCalls[0])
 
 	testMetrics.stopCalls = nil
 	handler.isBootingScript = true
 	handler.markBackgroundReady()
-	tearDownWorkerScript(handler, 1)
+	handler.afterScriptExecution(1)
 	require.Len(t, testMetrics.stopCalls, 1)
 	assert.Equal(t, StopReason(StopReasonCrash), testMetrics.stopCalls[0])
 }

threadbackgroundworker.go

@@ -4,27 +4,45 @@ package frankenphp
 import "C"
 import (
 	"context"
+	"fmt"
 	"log/slog"
 	"path/filepath"
 	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+	"unsafe"
 
 	"github.com/dunglas/frankenphp/internal/state"
 )
 
+// backgroundWorkerState holds the shared state for a single background worker.
+// Accessed by the background worker thread (writes) and HTTP worker threads (reads).
+type backgroundWorkerState struct {
+	varsPtr     unsafe.Pointer // *C.HashTable, persistent, managed by C
+	mu          sync.RWMutex
+	varsVersion atomic.Uint64 // incremented on each set_vars call
+	ready       chan struct{}
+	readyOnce   sync.Once
+}
+
 // backgroundWorkerThread handles background worker scripts.
-// Embeds workerThread for shared functionality (failure counting, metrics,
-// dummy context management) and overrides lifecycle methods.
+// Decoupled from workerThread — owns its own lifecycle state.
 type backgroundWorkerThread struct {
-	workerThread
+	state                 *state.ThreadState
+	thread                *phpThread
+	worker                *worker
+	dummyFrankenPHPContext *frankenPHPContext
+	dummyContext          context.Context
+	isBootingScript       bool
+	failureCount          int
 }
 
 func convertToBackgroundWorkerThread(thread *phpThread, worker *worker) {
 	handler := &backgroundWorkerThread{
-		workerThread: workerThread{
-			state:  thread.state,
-			thread: thread,
-			worker: worker,
-		},
+		state:  thread.state,
+		thread: thread,
+		worker: worker,
 	}
 	thread.setHandler(handler)
 	worker.attachThread(thread)
@@ -34,6 +52,17 @@ func (handler *backgroundWorkerThread) name() string {
 	return "Background Worker PHP Thread - " + handler.worker.fileName
 }
 
+func (handler *backgroundWorkerThread) frankenPHPContext() *frankenPHPContext {
+	return handler.dummyFrankenPHPContext
+}
+
+func (handler *backgroundWorkerThread) context() context.Context {
+	if handler.dummyContext != nil {
+		return handler.dummyContext
+	}
+	return globalCtx
+}
+
 func (handler *backgroundWorkerThread) drain() {
 	if fd := handler.worker.backgroundStopFdWrite.Load(); fd >= 0 {
 		C.frankenphp_worker_write_stop_fd(C.int(fd))
@@ -115,5 +144,68 @@ func (handler *backgroundWorkerThread) setupScript() {
 
 func (handler *backgroundWorkerThread) afterScriptExecution(exitStatus int) {
 	handler.worker.backgroundStopFdWrite.Store(-1)
-	tearDownWorkerScript(&handler.workerThread, exitStatus)
+	worker := handler.worker
+	handler.dummyFrankenPHPContext = nil
+	handler.dummyContext = nil
+
+	// on exit status 0 we just run the worker script again
+	if exitStatus == 0 && !handler.isBootingScript {
+		metrics.StopWorker(worker.name, StopReasonRestart)
+
+		if globalLogger.Enabled(globalCtx, slog.LevelDebug) {
+			globalLogger.LogAttrs(globalCtx, slog.LevelDebug, "restarting", slog.String("worker", worker.name), slog.Int("thread", handler.thread.threadIndex), slog.Int("exit_status", exitStatus))
+		}
+
+		return
+	}
+
+	// worker has thrown a fatal error or has not reached set_vars
+	if handler.isBootingScript {
+		metrics.StopWorker(worker.name, StopReasonBootFailure)
+	} else {
+		metrics.StopWorker(worker.name, StopReasonCrash)
+	}
+
+	if !handler.isBootingScript {
+		if globalLogger.Enabled(globalCtx, slog.LevelDebug) {
+			globalLogger.LogAttrs(globalCtx, slog.LevelDebug, "restarting", slog.String("worker", worker.name), slog.Int("thread", handler.thread.threadIndex), slog.Int("exit_status", exitStatus))
+		}
+
+		return
+	}
+
+	if worker.maxConsecutiveFailures >= 0 && startupFailChan != nil && !watcherIsEnabled && handler.failureCount >= worker.maxConsecutiveFailures {
+		startupFailChan <- fmt.Errorf("too many consecutive failures: worker %s has not reached frankenphp_handle_request()", worker.fileName)
+		handler.thread.state.Set(state.ShuttingDown)
+		return
+	}
+
+	if watcherIsEnabled {
+		if globalLogger.Enabled(globalCtx, slog.LevelError) {
+			globalLogger.LogAttrs(globalCtx, slog.LevelWarn, "(watcher enabled) worker script has not reached frankenphp_handle_request()", slog.String("worker", worker.name), slog.Int("thread", handler.thread.threadIndex))
+		}
+	} else {
+		if globalLogger.Enabled(globalCtx, slog.LevelWarn) {
+			globalLogger.LogAttrs(globalCtx, slog.LevelWarn, "worker script has failed on restart", slog.String("worker", worker.name), slog.Int("thread", handler.thread.threadIndex), slog.Int("failures", handler.failureCount))
+		}
+	}
+
+	backoffDuration := time.Duration(handler.failureCount*handler.failureCount*100) * time.Millisecond
+	if backoffDuration > time.Second {
+		backoffDuration = time.Second
+	}
+	handler.failureCount++
+	time.Sleep(backoffDuration)
+}
+
+// markBackgroundReady resets failure state when the background worker
+// successfully calls set_vars for the first time.
+func (handler *backgroundWorkerThread) markBackgroundReady() {
+	if !handler.isBootingScript {
+		return
+	}
+
+	handler.failureCount = 0
+	handler.isBootingScript = false
+	metrics.ReadyWorker(handler.worker.name)
 }

threadworker.go

@@ -128,15 +128,6 @@ func setupWorkerScript(handler *workerThread, worker *worker) {
 
 }
 
-func (handler *workerThread) markBackgroundReady() {
-	if !handler.isBootingScript {
-		return
-	}
-
-	handler.failureCount = 0
-	handler.isBootingScript = false
-	metrics.ReadyWorker(handler.worker.name)
-}
 
 func tearDownWorkerScript(handler *workerThread, exitStatus int) {
 	worker := handler.worker