@zuke/canary

Declare a canary rollout. The lambda runs when the build is constructed and decides which targets exist; a misconfigured one throws there, naming the fix.

class Deploy extends Build {
  rollout = canary((c) =>
    c.platform(myPlatform)
      .steps(10, 50)
      .bake("10m")
      .analysis(httpProbe((h) => h.url("https://api.example.com/healthz")))
      .lock((l) => l.lockKey("deploy", "api").withTtl("24h"))
  );
  ship = target().dependsOn(this.rollout.promote).executes(() => {});
}

The targets canary(...) creates. Assigned to a build field — rollout = canary(…) — they are named under it: rollout.stage, rollout.step1.expose, rollout.promote, rollout.abort. Depend on this.rollout.promote to run after a successful rollout.

What the engine hands CanaryPlatform.abort: the context, and why.

Why abort runs:

- "rollback" — the engine is undoing this rollout: a stage that failed or was cancelled, a failed step, zuke cancel. With nothing in state, nothing was staged, so there is nothing to undo. - "hand-run" — rollout.abort was run on its own, outside any rollout. With nothing in state, the platform falls back to the stable version its own configuration names.

A health check run against a canary: throw to fail it, which rolls the rollout back. Any core Validation is one, since a function that accepts a plain ValidationContext accepts this richer context too.

What an analysis is handed: everything a core ValidationContext carries — the target's name, the run's redactor, and a signal — plus where the rollout stands.

What the engine hands a CanaryPlatform on each call.

state is the one place a platform keeps the handles a later call needs — the revision it staged, the stable one to return to. Every call of one rollout gets the same durable state, so abort can read what stage wrote, even in another process after a resume. Never put a secret in it: it is persisted in plain JSON and shown by zuke runs show.

The targets of one phase of a rollout.

A place a canary runs. The engine stages the candidate, moves its exposure step by step, and then promotes it or aborts it — through these calls only.

Rules the engine relies on:

- expose is absolute (set exposure to percent, not add to it) and returns the exposure actually achieved, which may differ on a "replicas" platform. A repeated call with the same value is harmless — a resumed run repeats one that was interrupted. - promote and abort are idempotent: either can run twice. - abort must also work with empty state. A rollback reads the state stage wrote, but zuke <rollout>.abort run by hand is a fresh run that has none, so abort falls back to what its own configuration says the stable version is. It does so only when ctx.reason is "hand-run": a "rollback" with empty state means nothing was staged, and moving traffic to the configured stable version would change a service no rollout touched. So stage records what a rollback needs before it changes anything — with ctx.state.trySet(...), stopping when it returns false — or a rollback after a lost write would find nothing to undo.

How a canary rolls out, configured through canary((c) => …):

rollout = canary((c) =>
  c.platform(myPlatform)
    .steps(10, 25, 50)
    .bake("10m")
    .analysis(httpProbe((h) => h.url(HEALTH_URL)))
    .approval("canary-approved")
    .lock((l) => l.lockKey("deploy", "api").withTtl("24h"))
);

The lambda runs once, when the build is constructed, because it decides which targets exist. Anything that reads a parameter — an image tag, a URL — belongs inside the platform's or the analysis's own lambda, which runs when the target does.

How a platform exposes a candidate:

- "traffic" — a share of requests, set exactly (a traffic split). - "replicas" — a share of instances, quantised to whole replicas, so the achieved exposure can differ from the one requested. - "channel" — a release channel (a dist-tag, a pre-release); there is no percentage, so a canary on it declares no steps.

An analysis that requests a URL a number of times and fails the canary when more than maxFailures of them fail — a status outside the expected ones, a timeout, or a connection error:

httpProbe((h) => h.url("https://api.example.com/healthz").samples(30))

The lambda runs on each check, so it may read resolved parameters. The failure message passes through the run's redactor.

Settings for httpProbe: what to request, how often, how strictly.

Reads the metric a metricThreshold judges.

An analysis that reads a number and fails the canary when it is out of bounds:

metricThreshold((m) =>
  m.name("error ratio").read(() => readErrorRatio()).max(0.01)
)

The lambda runs on each check, so a reader may use resolved parameters.

Settings for metricThreshold: a name, a reader, and the bounds the value must stay within.

An analysis that runs an instant PromQL query and fails the canary when any sample is out of bounds:

prometheus((p) =>
  p.url("https://prometheus.internal")
    .query('sum(rate(http_errors_total{rev="canary"}[5m])) or vector(0)')
    .max(0.01)
)

The lambda runs on each check, so it may read resolved parameters. The query is sent by PrometheusTasks.query from @zuke/prometheus, as a GET with the expression in the URL — as this analysis always has. A URL sent a credential must be https: unless it is loopback (or ZUKE_ALLOW_INSECURE_URL is set). A credential is an Authorization, Proxy-Authorization or Cookie header, a header whose name looks like a credential's (X-API-Key, X-Auth-Token), user:password@ or a credential parameter in the URL, or anything set through connection(...) — a secretHeader(...), sigv4(), google(), azure(). Any other header, such as an X-Scope-OrgID tenant id, leaves an in-cluster http://prometheus.monitoring.svc:9090 usable. Failure messages pass through the run's redactor, so a secret parameter in the URL or the query is masked, and a header value (eight or more characters) never appears in them.

Settings for prometheus: where, what to ask, and the bounds.

Inclusive bounds a metric must stay within; either side may be open.