feat: application sidekicks = non-HTTP workers with shared state

Author: nicolas-grekas

caddy/app.go

@@ -162,6 +162,7 @@ func (f *FrankenPHPApp) Start() error {
 			frankenphp.WithWorkerMaxFailures(w.MaxConsecutiveFailures),
 			frankenphp.WithWorkerMaxThreads(w.MaxThreads),
 			frankenphp.WithWorkerRequestOptions(w.requestOptions...),
+			frankenphp.WithWorkerSidekickEntrypoint(w.SidekickEntrypoint),
 		)
 
 		f.opts = append(f.opts, frankenphp.WithWorkers(w.Name, repl.ReplaceKnown(w.FileName, ""), w.Num, w.options...))

caddy/module.go

@@ -45,6 +45,8 @@ type FrankenPHPModule struct {
 	Env map[string]string `json:"env,omitempty"`
 	// Workers configures the worker scripts to start.
 	Workers []workerConfig `json:"workers,omitempty"`
+	// SidekickEntrypoint is the script used to start sidekicks (e.g., bin/console)
+	SidekickEntrypoint string `json:"sidekick_entrypoint,omitempty"`
 
 	resolvedDocumentRoot        string
 	preparedEnv                 frankenphp.PreparedEnv
@@ -91,6 +93,7 @@ func (f *FrankenPHPModule) Provision(ctx caddy.Context) error {
 			wc.inheritEnv(f.Env)
 		}
 
+		wc.SidekickEntrypoint = f.SidekickEntrypoint
 		wc.requestOptions = append(wc.requestOptions, loggerOpt)
 		f.Workers[i] = wc
 	}
@@ -297,6 +300,12 @@ func (f *FrankenPHPModule) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
 				}
 				f.ResolveRootSymlink = &v
 
+			case "sidekick_entrypoint":
+				if !d.NextArg() {
+					return d.ArgErr()
+				}
+				f.SidekickEntrypoint = d.Val()
+
 			case "worker":
 				wc, err := unmarshalWorker(d)
 				if err != nil {
@@ -311,7 +320,7 @@ func (f *FrankenPHPModule) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
 				}
 
 			default:
-				return wrongSubDirectiveError("php or php_server", "hot_reload, name, root, split, env, resolve_root_symlink, worker", d.Val())
+				return wrongSubDirectiveError("php or php_server", "hot_reload, name, root, split, env, resolve_root_symlink, sidekick_entrypoint, worker", d.Val())
 			}
 		}
 	}

caddy/workerconfig.go

@@ -41,6 +41,8 @@ type workerConfig struct {
 	MatchPath []string `json:"match_path,omitempty"`
 	// MaxConsecutiveFailures sets the maximum number of consecutive failures before panicking (defaults to 6, set to -1 to never panick)
 	MaxConsecutiveFailures int `json:"max_consecutive_failures,omitempty"`
+	// SidekickEntrypoint is the script used to start sidekicks (inherited from php_server)
+	SidekickEntrypoint string `json:"sidekick_entrypoint,omitempty"`
 
 	options        []frankenphp.WorkerOption
 	requestOptions []frankenphp.RequestOption

cgi.go

@@ -194,6 +194,9 @@ func go_register_server_variables(threadIndex C.uintptr_t, trackVarsArray *C.zva
 
 	// The Prepared Environment is registered last and can overwrite any previous values
 	addPreparedEnvToServer(fc, trackVarsArray)
+
+	// Inject variables set by non-HTTP workers via frankenphp_set_server_var()
+	addSidekickVarsToServer(trackVarsArray)
 }
 
 // splitCgiPath splits the request path into SCRIPT_NAME, SCRIPT_FILENAME, PATH_INFO, DOCUMENT_URI

docs/sidekicks.md

@@ -0,0 +1,146 @@
+# Application Sidekicks
+
+Sidekicks are long-running PHP workers that run **outside the HTTP request cycle**.
+They observe their environment (Redis Sentinel, secret vaults, feature flag services, etc.)
+and publish configuration to HTTP workers in real time — without polling, approximate TTLs, or redeployment.
+
+## How It Works
+
+- A sidekick runs its own infinite loop (subscribe to Redis, watch files, poll an API, etc.)
+- It calls `frankenphp_set_server_var()` to publish key-value pairs
+- HTTP workers receive those values in `$_SERVER` at each `frankenphp_handle_request()` iteration
+- Values are **consistent for the entire request** — no mid-request mutation
+
+## Configuration
+
+Add a `sidekick_entrypoint` to your `php_server` block in the Caddyfile.
+This is the script that will be executed for every sidekick started by workers of this server:
+
+```caddyfile
+example.com {
+    php_server {
+        sidekick_entrypoint /app/bin/console
+    }
+}
+```
+
+Sidekicks are then started dynamically from PHP using `frankenphp_sidekick_start()`.
+
+## PHP API
+
+### `frankenphp_sidekick_start(string $name, array $argv = []): void`
+
+Starts a sidekick worker. The configured `sidekick_entrypoint` script is executed
+in a new PHP thread with `$name` as the first argument in `$_SERVER['argv']`.
+
+- **At-most-once by name**: calling it multiple times with the same `$name` is a no-op (safe with multiple HTTP workers). Only the first call determines the argv values
+- **`$_SERVER['argv']`** in the sidekick will be `[script_path, name, ...argv]`
+- Throws `ValueError` if `$name` is empty
+- Throws `InvalidArgumentException` if `$argv` contains non-string values
+- Throws `RuntimeException` if no `sidekick_entrypoint` is configured or no thread is available
+
+### `frankenphp_set_server_var(string $key, ?string $value): void`
+
+Sets a variable that will be injected into `$_SERVER` of all HTTP workers.
+Can be called from any worker (sidekick or HTTP).
+
+- Passing `null` as `$value` removes the key (it will no longer be injected)
+- Throws `ValueError` if `$key` is empty or starts with `HTTP_` (reserved for HTTP request headers)
+
+### `frankenphp_sidekick_should_stop(): bool`
+
+Returns `true` when FrankenPHP is shutting down. Sidekick scripts must poll this
+in their event loop to exit gracefully:
+
+```php
+while (!frankenphp_sidekick_should_stop()) {
+    // do work
+    usleep(100_000);
+}
+```
+
+## Example
+
+### Sidekick Script
+
+```php
+<?php
+// bin/sidekick.php
+
+require __DIR__.'/../vendor/autoload.php';
+
+$argv = $_SERVER['argv'] ?? [];
+array_shift($argv); // skip argv[0] (script name)
+
+// Set initial values
+frankenphp_set_server_var('REDIS_MASTER_HOST', '10.0.0.1');
+frankenphp_set_server_var('REDIS_MASTER_PORT', '6379');
+
+while (!frankenphp_sidekick_should_stop()) {
+    // Watch for changes (e.g., Redis Sentinel, file watcher, API poll)
+    $master = discoverRedisMaster();
+    frankenphp_set_server_var('REDIS_MASTER_HOST', $master['host']);
+    frankenphp_set_server_var('REDIS_MASTER_PORT', (string) $master['port']);
+
+    usleep(100_000);
+}
+```
+
+### Starting from the HTTP Worker
+
+```php
+<?php
+// public/index.php
+
+// Start sidekicks before your application boots
+// At-most-once: safe to call from multiple HTTP worker threads
+if (function_exists('frankenphp_sidekick_start')) {
+    frankenphp_sidekick_start('redis-watcher', ['--sentinel-host=10.0.0.1']);
+}
+
+// Your application entry point
+require __DIR__.'/../vendor/autoload.php';
+
+$app = new App();
+$app->boot();
+
+$handler = static function () use ($app) {
+    // $_SERVER['REDIS_MASTER_HOST'] contains the latest value
+    // published by the sidekick — consistent for the entire request
+    echo $app->handle($_GET, $_POST, $_COOKIE, $_FILES, $_SERVER);
+};
+
+while (frankenphp_handle_request($handler)) {
+    $app->terminate();
+    gc_collect_cycles();
+}
+
+$app->shutdown();
+```
+
+### Reading Sidekick Variables
+
+In your application code, read the values from `$_SERVER`:
+
+```php
+$redisHost = $_SERVER['REDIS_MASTER_HOST'] ?? '127.0.0.1';
+$redisPort = $_SERVER['REDIS_MASTER_PORT'] ?? '6379';
+
+$redis = new \Redis();
+$redis->connect($redisHost, (int) $redisPort);
+```
+
+## Runtime Behavior
+
+- **Execution timeout disabled**: sidekick threads automatically call `zend_unset_timeout()`
+- **Shebang support**: entrypoints with `#!/usr/bin/env php` are handled correctly
+- **Crash recovery**: if a sidekick script exits, FrankenPHP restarts it automatically (using the existing worker restart logic with exponential backoff)
+- **Graceful shutdown**: sidekicks detect shutdown via `frankenphp_sidekick_should_stop()` and exit their loop
+- **`SCRIPT_FILENAME`**: set to the entrypoint's full path, so `dirname(__DIR__)` works correctly
+- **`$_SERVER['argv']`**: follows CLI conventions — `argv[0]` is the script path, followed by the arguments passed to `frankenphp_sidekick_start()`
+
+## Debugging
+
+- Use `error_log()` or `frankenphp_log()` for structured output — these go through FrankenPHP's logger
+- Avoid `echo` in sidekicks — it produces unstructured, unattributed log entries
+- Sidekick scripts can be tested standalone: `php bin/sidekick.php`