feat: allow set_vars/get_vars(null) from HTTP workers

Author: nicolas-grekas

background_worker.go

@@ -33,12 +33,17 @@ var backgroundLookups map[string]*backgroundWorkerLookup
 type backgroundWorkerLookup struct {
 	byName   map[string]*backgroundWorkerRegistry
 	catchAll *backgroundWorkerRegistry
+	httpVars backgroundWorkerState // shared vars bucket for HTTP workers in this scope
 }
 
 func newBackgroundWorkerLookup() *backgroundWorkerLookup {
-	return &backgroundWorkerLookup{
+	l := &backgroundWorkerLookup{
 		byName: make(map[string]*backgroundWorkerRegistry),
 	}
+	// httpVars is always "ready" — get_worker_vars(null) never blocks
+	l.httpVars.ready = make(chan struct{})
+	close(l.httpVars.ready)
+	return l
 }
 
 func (l *backgroundWorkerLookup) AddNamed(name string, registry *backgroundWorkerRegistry) {
@@ -250,6 +255,20 @@ func startBackgroundWorkerWithRegistry(registry *backgroundWorkerRegistry, bgWor
 	return nil
 }
 
+var backgroundLookupsMu sync.Mutex
+
+func getOrCreateLookup(scope string) *backgroundWorkerLookup {
+	if backgroundLookups == nil {
+		backgroundLookups = make(map[string]*backgroundWorkerLookup)
+	}
+	if l, ok := backgroundLookups[scope]; ok {
+		return l
+	}
+	l := newBackgroundWorkerLookup()
+	backgroundLookups[scope] = l
+	return l
+}
+
 func getLookup(thread *phpThread) *backgroundWorkerLookup {
 	if handler, ok := thread.handler.(*workerThread); ok && handler.worker.backgroundLookup != nil {
 		return handler.worker.backgroundLookup
@@ -259,16 +278,16 @@ func getLookup(thread *phpThread) *backgroundWorkerLookup {
 	}
 	// Non-worker requests: resolve scope from context
 	if fc, ok := fromContext(thread.context()); ok && fc.backgroundScope != "" {
-		if backgroundLookups != nil {
-			return backgroundLookups[fc.backgroundScope]
-		}
+		backgroundLookupsMu.Lock()
+		l := getOrCreateLookup(fc.backgroundScope)
+		backgroundLookupsMu.Unlock()
+		return l
 	}
 	// Fall back to global scope
-	if backgroundLookups != nil {
-		return backgroundLookups[""]
-	}
-
-	return nil
+	backgroundLookupsMu.Lock()
+	l := getOrCreateLookup("")
+	backgroundLookupsMu.Unlock()
+	return l
 }
 
 // go_frankenphp_get_vars starts background workers if needed, waits for them
@@ -283,7 +302,7 @@ func go_frankenphp_get_vars(threadIndex C.uintptr_t, names **C.char, nameLens *C
 	thread := phpThreads[threadIndex]
 	lookup := getLookup(thread)
 	if lookup == nil {
-		return C.CString("no background worker configured in this php_server")
+		return C.CString("no worker configured in this php_server")
 	}
 
 	n := int(nameCount)
@@ -295,6 +314,12 @@ func go_frankenphp_get_vars(threadIndex C.uintptr_t, names **C.char, nameLens *C
 	for i := 0; i < n; i++ {
 		goNames[i] = C.GoStringN(nameSlice[i], C.int(nameLenSlice[i]))
 
+		if goNames[i] == "" {
+			// Empty string = HTTP workers' shared scope (ready channel is pre-closed)
+			sks[i] = &lookup.httpVars
+			continue
+		}
+
 		// Start background worker if not already running
 		if err := startBackgroundWorker(thread, goNames[i]); err != nil {
 			return C.CString(err.Error())
@@ -369,23 +394,36 @@ func go_frankenphp_get_vars(threadIndex C.uintptr_t, names **C.char, nameLens *C
 func go_frankenphp_set_vars(threadIndex C.uintptr_t, varsPtr unsafe.Pointer, oldPtr *unsafe.Pointer) *C.char {
 	thread := phpThreads[threadIndex]
 
-	bgHandler, ok := thread.handler.(*backgroundWorkerThread)
-	if !ok || bgHandler.worker.backgroundWorker == nil {
-		return C.CString("frankenphp_set_vars() can only be called from a background worker")
-	}
+	// Background worker: write to named bucket
+	if bgHandler, ok := thread.handler.(*backgroundWorkerThread); ok && bgHandler.worker.backgroundWorker != nil {
+		sk := bgHandler.worker.backgroundWorker
 
-	sk := bgHandler.worker.backgroundWorker
+		sk.mu.Lock()
+		*oldPtr = sk.varsPtr
+		sk.varsPtr = varsPtr
+		sk.varsVersion.Add(1)
+		sk.mu.Unlock()
 
-	sk.mu.Lock()
-	*oldPtr = sk.varsPtr
-	sk.varsPtr = varsPtr
-	sk.varsVersion.Add(1)
-	sk.mu.Unlock()
+		sk.readyOnce.Do(func() {
+			bgHandler.markBackgroundReady()
+			close(sk.ready)
+		})
 
-	sk.readyOnce.Do(func() {
-		bgHandler.markBackgroundReady()
-		close(sk.ready)
-	})
+		return nil
+	}
+
+	// HTTP worker: write to scope's shared httpVars bucket
+	lookup := getLookup(thread)
+	if lookup == nil {
+		return C.CString("frankenphp_set_vars() requires a configured php_server block")
+	}
+
+	hv := &lookup.httpVars
+	hv.mu.Lock()
+	*oldPtr = hv.varsPtr
+	hv.varsPtr = varsPtr
+	hv.varsVersion.Add(1)
+	hv.mu.Unlock()
 
 	return nil
 }

background_worker_test.go

@@ -46,6 +46,32 @@ func (m *backgroundWorkerTestMetrics) QueuedRequest() {}
 
 func (m *backgroundWorkerTestMetrics) DequeuedRequest() {}
 
+func TestGetOrCreateLookup(t *testing.T) {
+	oldLookups := backgroundLookups
+	backgroundLookups = nil
+	t.Cleanup(func() {
+		backgroundLookups = oldLookups
+	})
+
+	l1 := getOrCreateLookup("scope-a")
+	require.NotNil(t, l1)
+	assert.NotNil(t, l1.byName)
+
+	l2 := getOrCreateLookup("scope-a")
+	assert.Same(t, l1, l2, "same scope should return the same lookup")
+
+	l3 := getOrCreateLookup("")
+	assert.NotSame(t, l1, l3, "different scope should return a different lookup")
+
+	// httpVars ready channel should be pre-closed
+	select {
+	case <-l1.httpVars.ready:
+		// expected
+	default:
+		t.Fatal("httpVars.ready should be closed")
+	}
+}
+
 func TestStartBackgroundWorkerFailureIsRetryable(t *testing.T) {
 	lookup := newBackgroundWorkerLookup()
 	lookup.catchAll = newBackgroundWorkerRegistry(testDataPath + "/background-worker-with-argv.php")

docs/background-workers.md

@@ -42,7 +42,7 @@ example.com {
 
 ## PHP API
 
-### `frankenphp_get_vars(string|array $name, float $timeout = 30.0): array`
+### `frankenphp_get_vars(string|array|null $name, float $timeout = 30.0): array`
 
 Starts a background worker (at-most-once) and returns its published vars.
 
@@ -52,24 +52,32 @@ $redis = frankenphp_get_vars('redis-watcher');
 
 $all = frankenphp_get_vars(['redis-watcher', 'feature-flags']);
 // ['redis-watcher' => [...], 'feature-flags' => [...]]
+
+// Read vars published by HTTP workers in the same scope
+$shared = frankenphp_get_vars(null);
 ```
 
-- First call blocks until the background worker calls `set_vars()` or the timeout expires
+- With a string name: blocks until the background worker calls `set_vars()` or the timeout expires
+- With `null`: returns the HTTP workers' shared vars immediately (empty array if none published yet)
 - Subsequent calls return the latest snapshot immediately
 - Within a single HTTP request, repeated calls with the same name return the same cached array - `===` comparisons are O(1)
 - Throws `RuntimeException` on timeout, missing entrypoint, or background worker crash
 - Works in both worker and non-worker mode
 
 ### `frankenphp_set_vars(array $vars): void`
 
-Publishes vars from inside a background worker.
+Publishes vars from a worker context.
+
+- From a **background worker**: publishes to the named worker's bucket (readable via `get_worker_vars('name')`)
+- From an **HTTP worker**: publishes to the scope's shared bucket (readable via `get_worker_vars(null)`)
+
 Each call **replaces** the entire vars array atomically.
 If the new value is identical (`===`) to the previous one, the call is a no-op.
 
 Values can be `null`, scalars (`bool`, `int`, `float`, `string`), nested `array`s, or **enum**s.
 Objects, resources, and references are rejected.
 
-- Throws `RuntimeException` if not called from a background worker context
+- Throws `RuntimeException` if not called from a worker context
 - Throws `ValueError` if values contain objects, resources, or references
 
 ### `frankenphp_get_worker_handle(): resource`

frankenphp.c

@@ -949,9 +949,55 @@ PHP_FUNCTION(frankenphp_get_vars) {
   }
   int timeout_ms = (int)(timeout * 1000);
 
+  /* null: read from the HTTP workers' shared scope via empty string key */
+  if (Z_TYPE_P(names) == IS_NULL) {
+    char *empty = "";
+    size_t empty_len = 0;
+    uint64_t caller_version = 0;
+    uint64_t out_version = 0;
+    bg_worker_vars_cache_entry *cached = NULL;
+    if (worker_vars_cache) {
+      zval *entry_zv =
+          zend_hash_str_find(worker_vars_cache, empty, empty_len);
+      if (entry_zv) {
+        cached = Z_PTR_P(entry_zv);
+        caller_version = cached->version;
+      }
+    }
+
+    char *error = go_frankenphp_get_vars(
+        thread_index, &empty, &empty_len, 1, timeout_ms, return_value,
+        cached ? &caller_version : NULL, &out_version);
+    if (error) {
+      zend_throw_exception(spl_ce_RuntimeException, error, 0);
+      free(error);
+      RETURN_THROWS();
+    }
+    if (EG(exception)) {
+      RETURN_THROWS();
+    }
+
+    if (cached && out_version == caller_version) {
+      ZVAL_COPY(return_value, &cached->value);
+      return;
+    }
+
+    if (!worker_vars_cache) {
+      worker_vars_cache = malloc(sizeof(HashTable));
+      zend_hash_init(worker_vars_cache, 4, NULL, bg_worker_vars_cache_dtor, 1);
+    }
+    bg_worker_vars_cache_entry *entry = malloc(sizeof(*entry));
+    entry->version = out_version;
+    ZVAL_COPY(&entry->value, return_value);
+    zval entry_zv;
+    ZVAL_PTR(&entry_zv, entry);
+    zend_hash_str_update(worker_vars_cache, empty, empty_len, &entry_zv);
+    return;
+  }
+
   if (Z_TYPE_P(names) == IS_STRING) {
     if (Z_STRLEN_P(names) == 0) {
-      zend_value_error("Background worker name must not be empty");
+      zend_value_error("Worker name must not be empty");
       RETURN_THROWS();
     }
 
@@ -1005,9 +1051,9 @@ PHP_FUNCTION(frankenphp_get_vars) {
   }
 
   if (Z_TYPE_P(names) != IS_ARRAY) {
-    zend_type_error("Argument #1 ($name) must be of type string|array, %s "
-                    "given",
-                    zend_zval_type_name(names));
+    zend_type_error(
+        "Argument #1 ($name) must be of type string|array|null, %s given",
+        zend_zval_type_name(names));
     RETURN_THROWS();
   }
 
@@ -1016,7 +1062,7 @@ PHP_FUNCTION(frankenphp_get_vars) {
 
   ZEND_HASH_FOREACH_VAL(ht, val) {
     if (Z_TYPE_P(val) != IS_STRING || Z_STRLEN_P(val) == 0) {
-      zend_value_error("All background worker names must be non-empty strings");
+      zend_value_error("All worker names must be non-empty strings");
       RETURN_THROWS();
     }
   }

frankenphp.stub.php

@@ -24,7 +24,7 @@ function frankenphp_set_vars(array $vars): void {}
 /**
  * @return array<string, null|scalar|array<mixed>|\UnitEnum>
  */
-function frankenphp_get_vars(string|array $name, float $timeout = 30.0): array {}
+function frankenphp_get_vars(string|array|null $name, float $timeout = 30.0): array {}
 
 /** @return resource */
 function frankenphp_get_worker_handle() {}

frankenphp_arginfo.h

@@ -10,7 +10,7 @@ ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_frankenphp_set_vars, 0, 1, IS_VO
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_frankenphp_get_vars, 0, 1, IS_ARRAY, 0)
-	ZEND_ARG_TYPE_MASK(0, name, MAY_BE_STRING|MAY_BE_ARRAY, NULL)
+	ZEND_ARG_TYPE_MASK(0, name, MAY_BE_STRING|MAY_BE_ARRAY|MAY_BE_NULL, NULL)
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, timeout, IS_DOUBLE, 0, "30.0")
 ZEND_END_ARG_INFO()
 

frankenphp_test.go

@@ -876,7 +876,7 @@ func TestBackgroundWorkerNoEntrypoint(t *testing.T) {
 func TestBackgroundWorkerSetVarsValidation(t *testing.T) {
 	runTest(t, func(handler func(http.ResponseWriter, *http.Request), _ *httptest.Server, _ int) {
 		body, _ := testGet("http://example.com/background-worker-set-server-var-validation.php", handler, t)
-		assert.Contains(t, body, "NON_BACKGROUND:blocked")
+		assert.Contains(t, body, "HTTP_SET_VARS:allowed")
 		assert.Contains(t, body, "STREAM_NON_BACKGROUND:blocked")
 	}, &testOptions{
 		workerScript:       "background-worker-set-server-var-validation.php",
@@ -1120,6 +1120,39 @@ func TestBackgroundWorkerNamedAutoStart(t *testing.T) {
 	})
 }
 
+func TestHttpWorkerVars(t *testing.T) {
+	runTest(t, func(handler func(http.ResponseWriter, *http.Request), _ *httptest.Server, _ int) {
+		body, _ := testGet("http://example.com/background-worker-http-vars.php", handler, t)
+		assert.Equal(t, "http:1", body)
+	}, &testOptions{
+		workerScript:       "background-worker-http-vars.php",
+		nbWorkers:          1,
+		nbParallelRequests: 1,
+	})
+}
+
+func TestHttpWorkerVarsEmpty(t *testing.T) {
+	runTest(t, func(handler func(http.ResponseWriter, *http.Request), _ *httptest.Server, _ int) {
+		body, _ := testGet("http://example.com/background-worker-http-vars-empty.php", handler, t)
+		assert.Equal(t, "array:0", body)
+	}, &testOptions{
+		workerScript:       "background-worker-http-vars-empty.php",
+		nbWorkers:          1,
+		nbParallelRequests: 1,
+	})
+}
+
+func TestHttpWorkerVarsIdentity(t *testing.T) {
+	runTest(t, func(handler func(http.ResponseWriter, *http.Request), _ *httptest.Server, _ int) {
+		body, _ := testGet("http://example.com/background-worker-http-vars-identity.php", handler, t)
+		assert.Equal(t, "IDENTICAL", body)
+	}, &testOptions{
+		workerScript:       "background-worker-http-vars-identity.php",
+		nbWorkers:          1,
+		nbParallelRequests: 1,
+	})
+}
+
 func ExampleServeHTTP() {
 	if err := frankenphp.Init(); err != nil {
 		panic(err)

testdata/background-worker-http-vars-empty.php

@@ -0,0 +1,7 @@
+<?php
+
+frankenphp_handle_request(function () {
+    // get_vars(null) without any prior set_vars should return empty array
+    $vars = frankenphp_get_vars(null);
+    echo is_array($vars) ? 'array:' . count($vars) : 'not_array';
+});

testdata/background-worker-http-vars-identity.php

@@ -0,0 +1,10 @@
+<?php
+
+frankenphp_handle_request(function () {
+    frankenphp_set_vars(['KEY' => 'val']);
+
+    // Two calls with null in the same request should return identical arrays
+    $a = frankenphp_get_vars(null);
+    $b = frankenphp_get_vars(null);
+    echo $a === $b ? 'IDENTICAL' : 'DIFFERENT';
+});

testdata/background-worker-http-vars.php

@@ -0,0 +1,10 @@
+<?php
+
+frankenphp_handle_request(function () {
+    // First call: publish vars from HTTP worker
+    frankenphp_set_vars(['REQUEST_COUNT' => '1', 'SOURCE' => 'http']);
+
+    // Read back via get_vars(null)
+    $vars = frankenphp_get_vars(null);
+    echo $vars['SOURCE'] . ':' . $vars['REQUEST_COUNT'];
+});