Bring every self-upgrading poller onto this core's build.

POST

/api/v1/system/upgrade/pollers

curl --request POST \
  --url https://example.com/api/v1/system/upgrade/pollers \
  --header 'Authorization: Bearer <token>'

The half of ADR-051 that was missing: commands went out only as the tail of core’s own upgrade, so a site stood up afterwards — or one that failed and was fixed, or one that only enabled its updater today — stayed on its old build until the next release. This is the same convergence, with an operator as its trigger instead of a finished run.

core is not touched. No image is pulled here, no container of this deployment restarts, and no maintenance window opens: the work happens at the sites, one poller at a time per pool, and pool_coverage is what would notice if a pool went quiet. That is also why this route does not take the [Upgrade] extractor — a deployment with no central updater at all can still align its remote sites.

⚠️ A poller ahead of this core is moved back. That is the point rather than an oversight: N/N-1 promises new-core-with-old-poller and says nothing about the reverse (ADR-009), so a poller ahead of core is the unsupported skew. Pollers hold no state, so it costs a recreate.

Authorizations

• bearer

Responses

202

Accepted; the pollers are converging, one at a time per pool

Media typeapplication/json

What an align request set in motion.

object

dark_pools

required

Pools that will have no live poller for the length of one recreate. Named so an operator reads it before the alert does; not a refusal (ADR-051 decision 13).

Array<string>

id

required

Correlation id, shared with every site’s own audit line for this operation.

string

pollers

required

The pollers commands were published for, in the order the queues will take them, and what each was running when the button was pressed.

No progress here, deliberately: nothing has reached a site yet, so any report these pollers carry belongs to an earlier run and echoing it would put a stale “installing” in the acknowledgement of a command that has only just been published. Poll GET /api/v1/system/upgrade for how each site is getting on.

Array<object>

A poller a single press of Upgrade would leave on its current build.

object

id

required

Sanitized poller id.

string

version

What it is running now; null when it has never reported a version.

string | null

target_tag

required

The release every target is being moved to — this core’s own build.

string

Example^generated

{
  "dark_pools": [
    "example"
  ],
  "id": "example",
  "pollers": [
    {
      "id": "example",
      "version": "example"
    }
  ],
  "target_tag": "example"
}

401

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Role lacks ManageSystem

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

409

A poller convergence is already running (convergence_in_flight), or every poller is already on this build (pollers_aligned)

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

This core is not the leader, or this deployment has no bus (bus_unavailable)

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}