Patterns
When a killswitch is the right answer — what to put behind one, cold-cache behaviour, alerting, and the post-incident cleanup.
A killswitch is a flag with one job: be the lever you pull when something is on fire. That makes it the wrong tool for most things — most things don't need a 3am-grade pause button. This page is the decision guide: when to add one, what to put behind it, and how to keep them maintained.
What deserves a killswitch
The rule of thumb: if a junior engineer on-call would need to flip this in five seconds without reading the docs, it's a killswitch. Otherwise it's a feature flag.
Concrete examples that do deserve one:
- Outbound side effects. Email, SMS, push notifications, webhook fan-out. If your vendor goes down or starts retrying spuriously, you want one switch to stop the volume.
- Paid third-party calls. Anything that costs money per call — LLM inference, payment-provider webhooks, fraud-scoring APIs. If their pricing goes weird or their service hangs, kill it.
- Write-heavy background workers. Batch indexers, report generators, anything that mutates data in bulk. If they're producing bad output, pausing is cheaper than rolling back.
- Risky new subsystems in the first month after launch. A new payment integration, a new recommender, a new auth path. You'll feel the absence of a killswitch in the first incident.
Examples that should not be killswitches:
- Feature rollouts. That's what feature flags are for. A killswitch has no rollout percentage by design — you can't ramp it.
- Percentage splits. Use a feature flag with a rollout percentage. A killswitch can't express "50% see the new path."
- Permission checks. Killswitches bypass on incident, which is the opposite of what you want from an authz check.
- Anything you'd put behind a feature flag and might never flip. That's a config or a feature flag.
Cold-cache behaviour
Every killswitch read has an answer even when the SDK can't reach us: false — not killed.
Until the first rule set arrives, or if it can't be refreshed, the guarded path keeps running as it
did before you added the switch. That is deliberate: a Shipeasy outage must not, by itself, pause
your email or fail your payments.
It also decides what belongs behind a killswitch. A killswitch can only ever stop a path, never start one. If the dangerous outcome is skipping a call (a fraud check, an audit-log redaction), don't put a killswitch in front of it — keep it unconditional, or use a flag whose default you set at the call site.
const client = new Client(currentUser);
// Whole-path pause — true means "killed, bail out":
if (client.getKillswitch("emails-paused")) return;
// A named override for one region, read through the same call:
if (client.getKillswitch("payments-paused", "eu_region")) return;Audit + alerting
A killswitch flip is an incident-grade event. Two things should happen when one flips:
- The flip is recorded. Who flipped it, when, from what surface (dashboard, CLI, API), and the new value.
- The team hears about it. Turn on Killswitch flipped under Settings → Notifications → Events for the channels you use — in-app, email, Slack. The flip should declare the incident, not require someone to remember to.
Slack is the usual choice for the incident channel: connect it on the same tab, pick the channel, and the post carries a one-click Flip back.
Naming
Killswitch names appear in incident timelines and post-mortems. Pick names that read naturally in that context:
- ✓
emails-paused,payments-paused,recommender-paused— reads as "is this system paused?" - ✗
emails-enabled,email-killswitch,disable-recs— the first inverts whattruemeans, and the others hide whethertrueorfalseis "running."
The convention: <system>-paused. Then getKillswitch("emails-paused") returning true reads as
"yes, emails are paused" — which is exactly what the SDK returns when the switch is thrown.
Post-incident cleanup
A killswitch flipped during an incident, the team fixed the underlying bug, and the switch is back on. Two cleanup steps that often get skipped:
- Verify the killswitch still works. A flipped-then-restored killswitch sometimes drifts — maybe someone removed the in-code feature flag during the fix, or the notification moved. Re-rehearse the flip in staging within a week.
- Update the runbook. What was the trigger for this flip? Add it to the on-call runbook so the next engineer doesn't have to figure it out from scratch. The flip record is the raw material — turn it into a sentence in the runbook.
If a killswitch hasn't been flipped (even in staging) in 6 months, it might still work — but you don't know. Re-rehearse.
Killswitches in your tests
A killswitch wraps a real side effect. Your tests almost certainly don't want to actually send emails, but they also shouldn't bypass the killswitch path in a way that hides bugs in the wrapper itself.
The cleanest pattern: in test environments, run the SDK in bundle-mock mode with the killswitch set to whatever the test scenario needs:
import { configureForOffline } from "@shipeasy/sdk/server";
configureForOffline({
snapshot: {
flags: {
version: "test",
plan: "free",
gates: {},
configs: {},
// `killed: 1` = the switch is thrown, so getKillswitch() returns true
killswitches: { emails: { killed: 1 }, payments: { killed: 0 } },
},
experiments: { version: "test", universes: {}, experiments: {} },
},
});The SDK never hits the network in this mode, the killswitch values are deterministic, and your
test reads through the same new Client(user).getKillswitch() call your production code does — no
special-case bypass. configureForOffline() replaces the active configuration, so a suite can
re-seed between cases.
The dashboard view
The Killswitches page shows the current state of every killswitch in your project and when it was last published, with a Turn ON / Turn OFF control on each row. Keep it pinned during incidents — it's the central console.
If a switch has been flipped 5 times in the last week, that's a signal that the underlying system needs a real fix, not just a kill button.