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

Author: nicolas-grekas

caddy/app.go

@@ -57,6 +57,8 @@ type FrankenPHPApp struct {
 	MaxWaitTime time.Duration `json:"max_wait_time,omitempty"`
 	// The maximum amount of time an autoscaled thread may be idle before being deactivated
 	MaxIdleTime time.Duration `json:"max_idle_time,omitempty"`
+	// SidekickEntrypoint is the script used to start sidekicks (e.g., bin/console)
+	SidekickEntrypoint string `json:"sidekick_entrypoint,omitempty"`
 
 	opts    []frankenphp.Option
 	metrics frankenphp.Metrics
@@ -153,6 +155,7 @@ func (f *FrankenPHPApp) Start() error {
 		frankenphp.WithPhpIni(f.PhpIni),
 		frankenphp.WithMaxWaitTime(f.MaxWaitTime),
 		frankenphp.WithMaxIdleTime(f.MaxIdleTime),
+		frankenphp.WithSidekickEntrypoint(f.SidekickEntrypoint),
 	)
 
 	for _, w := range f.Workers {
@@ -291,6 +294,11 @@ func (f *FrankenPHPApp) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
 					}
 				}
 
+			case "sidekick_entrypoint":
+				if !d.NextArg() {
+					return d.ArgErr()
+				}
+				f.SidekickEntrypoint = d.Val()
 			case "worker":
 				wc, err := unmarshalWorker(d)
 				if err != nil {
@@ -311,7 +319,7 @@ func (f *FrankenPHPApp) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
 
 				f.Workers = append(f.Workers, wc)
 			default:
-				return wrongSubDirectiveError("frankenphp", "num_threads, max_threads, php_ini, worker, max_wait_time, max_idle_time", d.Val())
+				return wrongSubDirectiveError("frankenphp", "num_threads, max_threads, php_ini, worker, max_wait_time, max_idle_time, sidekick_entrypoint", d.Val())
 			}
 		}
 	}

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 the global `frankenphp` block in your Caddyfile.
+This is the script that will be executed for every sidekick:
+
+```caddyfile
+{
+    frankenphp {
+        sidekick_entrypoint /app/bin/sidekick.php
+    }
+}
+```
+
+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 the given `$argv` available 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)
+- **`$argv`**: must be an array of strings; available as `$_SERVER['argv']` in the sidekick script (with the script path prepended as `argv[0]`, like CLI)
+- 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`

frankenphp.c

@@ -85,13 +85,27 @@ HashTable *main_thread_env = NULL;
 
 __thread uintptr_t thread_index;
 __thread bool is_worker_thread = false;
+__thread bool is_http_thread = true;
+__thread int sidekick_argc = 0;
+__thread char **sidekick_argv = NULL;
 __thread HashTable *sandboxed_env = NULL;
 
-void frankenphp_update_local_thread_context(bool is_worker) {
+void frankenphp_update_local_thread_context(bool is_worker, bool httpEnabled) {
   is_worker_thread = is_worker;
+  is_http_thread = httpEnabled;
 
   /* workers should keep running if the user aborts the connection */
   PG(ignore_user_abort) = is_worker ? 1 : original_user_abort_setting;
+
+  /* Sidekick workers are long-running, disable execution timeout */
+  if (is_worker && !httpEnabled) {
+    zend_unset_timeout();
+  }
+}
+
+void frankenphp_set_thread_argv(int argc, char **argv) {
+  sidekick_argc = argc;
+  sidekick_argv = argv;
 }
 
 static void frankenphp_update_request_context() {
@@ -246,6 +260,9 @@ static void frankenphp_reset_session_state(void) {
 
 /* Adapted from php_request_shutdown */
 static void frankenphp_worker_request_shutdown() {
+  if (!is_http_thread) {
+    return;
+  }
   /* Flush all output buffers */
   zend_try { php_output_end_all(); }
   zend_end_try();
@@ -296,6 +313,9 @@ void get_full_env(zval *track_vars_array) {
 /* Adapted from php_request_startup() */
 static int frankenphp_worker_request_startup() {
   int retval = SUCCESS;
+  if (!is_http_thread) {
+    return retval;
+  }
 
   frankenphp_update_request_context();
 
@@ -608,6 +628,95 @@ PHP_FUNCTION(frankenphp_handle_request) {
   RETURN_TRUE;
 }
 
+PHP_FUNCTION(frankenphp_set_server_var) {
+  char *key = NULL;
+  size_t key_len = 0;
+  char *value = NULL;
+  size_t value_len = 0;
+
+  ZEND_PARSE_PARAMETERS_START(2, 2);
+  Z_PARAM_STRING(key, key_len);
+  Z_PARAM_STRING_OR_NULL(value, value_len);
+  ZEND_PARSE_PARAMETERS_END();
+
+  if (key_len == 0) {
+    zend_value_error("Key must not be empty");
+    RETURN_THROWS();
+  }
+
+  /* Reject HTTP_* keys; these are set per-request from HTTP headers */
+  if (key_len >= 5 && memcmp(key, "HTTP_", 5) == 0) {
+    zend_value_error("Key must not start with \"HTTP_\"");
+    RETURN_THROWS();
+  }
+
+  if (value == NULL) {
+    go_frankenphp_unset_server_var(key, key_len);
+  } else {
+    go_frankenphp_set_server_var(key, key_len, value, value_len);
+  }
+}
+
+PHP_FUNCTION(frankenphp_sidekick_start) {
+  char *name = NULL;
+  size_t name_len = 0;
+  zval *argv_array = NULL;
+
+  ZEND_PARSE_PARAMETERS_START(2, 2);
+  Z_PARAM_STRING(name, name_len);
+  Z_PARAM_ARRAY(argv_array);
+  ZEND_PARSE_PARAMETERS_END();
+
+  if (name_len == 0) {
+    zend_value_error("Sidekick name must not be empty");
+    RETURN_THROWS();
+  }
+
+  /* Validate all array values are strings */
+  HashTable *ht = Z_ARRVAL_P(argv_array);
+  int argc = zend_hash_num_elements(ht);
+  zval *val;
+  ZEND_HASH_FOREACH_VAL(ht, val) {
+    if (Z_TYPE_P(val) != IS_STRING) {
+      zend_throw_exception(spl_ce_InvalidArgumentException,
+                           "All argv values must be strings", 0);
+      RETURN_THROWS();
+    }
+  }
+  ZEND_HASH_FOREACH_END();
+
+  /* Allocate argv array; kept alive for the sidekick thread's lifetime */
+  char **argv = pemalloc(sizeof(char *) * (argc + 1), 1);
+  int i = 0;
+  ZEND_HASH_FOREACH_VAL(ht, val) {
+    argv[i] = pestrndup(Z_STRVAL_P(val), Z_STRLEN_P(val), 1);
+    i++;
+  }
+  ZEND_HASH_FOREACH_END();
+  argv[argc] = NULL;
+
+  char *error = go_frankenphp_start_sidekick(name, name_len, argc, argv);
+  if (error) {
+    for (int j = 0; j < argc; j++) {
+      pefree(argv[j], 1);
+    }
+    pefree(argv, 1);
+
+    zend_throw_exception(spl_ce_RuntimeException, error, 0);
+    free(error);
+    RETURN_THROWS();
+  }
+}
+
+PHP_FUNCTION(frankenphp_sidekick_should_stop) {
+  ZEND_PARSE_PARAMETERS_NONE();
+
+  if (go_frankenphp_sidekick_should_stop(thread_index)) {
+    RETURN_TRUE;
+  }
+  RETURN_FALSE;
+}
+
 PHP_FUNCTION(headers_send) {
   zend_long response_code = 200;
 
@@ -966,6 +1075,34 @@ static void frankenphp_register_variables(zval *track_vars_array) {
 
   /* Some variables are already present in SG(request_info) */
   frankenphp_register_variables_from_request_info(track_vars_array);
+
+  /* For sidekick threads: inject $argv/$argc into $_SERVER
+   * argv[0] is the script name (like CLI), followed by the sidekick args */
+  if (!is_http_thread && sidekick_argc > 0) {
+    zval argv_array;
+    array_init(&argv_array);
+
+    /* Get SCRIPT_FILENAME to use as argv[0] */
+    zval *script_filename =
+        zend_hash_str_find(Z_ARRVAL_P(track_vars_array), "SCRIPT_FILENAME",
+                           sizeof("SCRIPT_FILENAME") - 1);
+    if (script_filename) {
+      add_next_index_zval(&argv_array, script_filename);
+      Z_TRY_ADDREF_P(script_filename);
+    }
+
+    for (int i = 0; i < sidekick_argc; i++) {
+      add_next_index_string(&argv_array, sidekick_argv[i]);
+    }
+
+    zval argc_zval;
+    ZVAL_LONG(&argc_zval, zend_hash_num_elements(Z_ARRVAL(argv_array)));
+
+    zend_hash_str_update(Z_ARRVAL_P(track_vars_array), "argv",
+                         sizeof("argv") - 1, &argv_array);
+    zend_hash_str_update(Z_ARRVAL_P(track_vars_array), "argc",
+                         sizeof("argc") - 1, &argc_zval);
+  }
 }
 
 static void frankenphp_log_message(const char *message, int syslog_type_int) {
@@ -1217,6 +1354,11 @@ int frankenphp_execute_script(char *file_name) {
 
   file_handle.primary_script = 1;
 
+  /* Sidekick entrypoints (e.g. bin/console) may have a shebang line */
+  if (!is_http_thread) {
+    CG(skip_shebang) = 1;
+  }
+
   zend_first_try {
     EG(exit_status) = 0;
     php_execute_script(&file_handle);