Repository navigation
Failure modes
Every failure below is one a real deploy hit. Each has a guard in GuardedWorker
that converts it from "production incident" into "one-line abort message".
What happens: str_replace patches both. The second one is usually somewhere you
forgot the string existed.
The guard: guard() counts and aborts before any write. This is why guard takes
the map of replacements and not just the final string.
Lesson: uniqueness is verified, never assumed - even for strings you "know" are unique.
What happens: the worker URL is hit twice (browser pre-fetch, a retry, a second tab). A non-idempotent patch applies twice: two markers, doubled markup, a patch that now aborts forever on a marker check that no longer reflects reality. The guard: marker check first, then self-deletion. After a successful run the worker file is gone; a second hit is a 404, not a second patch. A failed run leaves the file (and the restored backup) so you can read the error and retry deliberately.
What happens: file_put_contents succeeds but writes truncated or mangled output
(disk full, permissions, race with another process). On shared hosting you often
cannot tell from the return value alone.
The guard: apply() re-reads the file and requires every replacement to be
present exactly once and every needle gone. Anything else triggers restore() and a
clean abort message.
What happens: an injected function/variable is placed after the branch that consumes it. No error, no warning - the feature just never renders, on every page. The patch is "successful" and the feature is dead. The guard: none that code can write - this is the pre-flight rule: map the control flow around the inject point before writing the needle. Verify the new behavior live, not the old behavior's absence.
What happens: the patch is perfect; a cached page convinces you it failed; you write a second patch on top of the first; now there are two. The guard: process, not code. See Cache-aware verification: cache-bust, verify the marker, never patch again while a patch is in flight.
What happens: .bak files accumulate in the web root. Worst case, some are
web-readable and leak a pre-hardening version of the site.
The guard: done() deletes the backup by default after reporting; pass
keepBackup: true only for risky patches you intend to eyeball, and make deleting it
the next worker's first job. Backups are a lifecycle, not a litter box.
What happens: the patch text passes through your generator (e.g. Python), into a
PHP single-quoted string, into emitted JavaScript. Each layer eats backslashes
differently; by layer three, \' has become something that is no longer valid
anything.
The guard: build needle and replacement as explicit byte strings and verify them
character-by-character before deploy - paste the strings from the live file, and
never hand-count backslashes across a layer boundary.
Guarded Deploy Workers
Repo