feat: declared background workers + frankenphp_get_worker_handle()#2398
Open
nicolas-grekas wants to merge 1 commit intophp:mainfrom
Open
feat: declared background workers + frankenphp_get_worker_handle()#2398nicolas-grekas wants to merge 1 commit intophp:mainfrom
nicolas-grekas wants to merge 1 commit intophp:mainfrom
Conversation
Adds a minimal background-worker surface: long-lived non-HTTP PHP scripts declared via WithWorkerBackground() / `background` in the Caddyfile worker block. Each worker exposes a stop-pipe stream via frankenphp_get_worker_handle(); on FrankenPHP shutdown / restart Go closes the write end so the script's stream_select returns EOF and the loop can exit cleanly. Crash-restart with quadratic backoff, halted by max_consecutive_failures. Per-php_server scope isolation so two server blocks can declare the same worker name without colliding. Deferred to follow-ups (kept out for review surface): - frankenphp_ensure_background_worker() / lazy-start machinery - Catch-all (empty-name) workers - Shared-state APIs (frankenphp_set_vars / frankenphp_get_vars) What lands: - frankenphp_get_worker_handle() zif + stop-fd plumbing in C - WithWorkerBackground() / WithWorkerScope() Go options; num >= 1 required - backgroundWorkerThread handler: boot, restart with backoff, cap-on-crash, graceful exit on stop-fd close - Per-scope lookup map keyed by user-facing name - Caddy `background` worker flag + scope-label cascade (host matcher -> first listener address) so the metric prefix m#<scope-label>:<name> is set before the very first metric emit. Tests: - TestBackgroundWorkerLifecycle: bg worker boots, touches sentinel, parks, exits within 10s of Shutdown. - TestBackgroundWorkerCrashRestarts: exit(1) -> respawn -> restarted sentinel. - TestBackgroundWorkerWithoutHTTP: a regular HTTP request alongside a bg worker still serves. - TestBackgroundWorkerSameNameDifferentScope: two servers each declare "shared", both run, distinct *worker per scope.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Smallest useful slice of the background-worker work. Adds long-lived
non-HTTP PHP scripts declared via
WithWorkerBackground()/backgroundin the Caddyfile worker block, plus the
frankenphp_get_worker_handle()primitive that gives the script a stream it can park on (
stream_select)to exit gracefully on shutdown / restart.
This carves the minimal surface out of the larger PR #2393 so it is small
enough to review and merge on its own. The richer features built on top
of these primitives are deferred to follow-ups.
What's in
frankenphp_get_worker_handle(): resource— closes whenFrankenPHP drains the worker (write end of the stop pipe is closed Go-side).
WithWorkerBackground(),WithWorkerScope(),NextScope,SetScopeLabel.num >= 1is required for bg workers (no lazy-startin this build).
halt respawn at
max_consecutive_failures. Exit-status 0 = cooperativerestart, no failure counted.
backgroundflag insidephp_server { workers ... }.Per-php_server scope isolation so two server blocks can declare the same
worker name without colliding. Scope label resolved before
Initvia thecascade in
caddy/scopelabel.go(host matcher → first listener address)so the very first metric emit on every bg worker carries the right
m#<scope-label>:<name>prefix.Deferred (kept out for review surface)
frankenphp_ensure_background_worker()and the lazy-start / readiness/ boot-failure machinery it pulls in.
frankenphp_set_vars/frankenphp_get_vars).Test plan
TestBackgroundWorkerLifecycle— bg worker boots, touches sentinel,parks on stop pipe,
Shutdown()returns within 10s.TestBackgroundWorkerCrashRestarts—exit(1)on first boot,respawned thread runs the success branch.
TestBackgroundWorkerWithoutHTTP— bg worker doesn't interceptHTTP traffic; a regular request still serves.
TestBackgroundWorkerSameNameDifferentScope(internal) — twophp_server scopes each declare "shared", both Init successfully and
run independently.
TestNextScopeIsDistinct.