breakaway 2.0.0-main.49 → 2.0.0-main.50

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "breakaway",
-  "version": "2.0.0-main.49",
+  "version": "2.0.0-main.50",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "breakaway",
-      "version": "2.0.0-main.49",
+      "version": "2.0.0-main.50",
       "license": "FSL-1.1-Apache-2.0",
       "bin": {
         "breakaway": "scripts/tasks.mjs"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "2.0.0-main.49",
+  "version": "2.0.0-main.50",
   "description": "The task board for you and your coding agents: a Cloudflare Worker, its web app, Taskwarrior sync, and the CLI (npx breakaway).",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

package/src/infra-cloudflare-plan.js

@@ -34,7 +34,9 @@ import {
   discover,
   priceResource,
   reader,
+  refuses,
   round,
+  workerConsumer,
 } from './infra-cloudflare.js';
 
 /** @typedef {import('./infra-provider.js').ProviderContext} ProviderContext */
@@ -65,6 +67,8 @@ const LOST = {
 const ORDER = [
   ['create', ['d1', 'kv', 'r2', 'queue']],
   ['update', ['d1', 'kv', 'r2', 'queue', 'container']],
+  ['scale', ['queue', 'container']],
+  ['restart', ['container']],
   ['create', ['worker']],
   ['update', ['worker']],
   ['create', ['route', 'custom-domain']],
@@ -73,6 +77,13 @@ const ORDER = [
   ['delete', ['worker']],
   ['delete', ['container', 'queue', 'r2', 'kv', 'd1']],
 ];
+/**
+ * Settings Cloudflare moves by itself between a plan and its apply (a container application's instance counts), so
+ * they never make a change look out of date.
+ */
+const LIVE = { container: ['instances', 'active', 'assigned'] };
+const settled = (kind, attrs) =>
+  Object.fromEntries(Object.entries(attrs ?? {}).filter(([k]) => !(LIVE[kind] ?? []).includes(k)));
 const rank = (c) => ORDER.findIndex(([op, kinds]) => op === c.op && kinds.includes(c.kind));
 
 /** Binding types whose targets are a resource of a kind Architect makes, and the field that names it. */
@@ -581,8 +592,10 @@ export async function apply(ctx, p) {
         const exists = h ?? [...have.values()].find((x) => x.kind === c.kind && x.name === c.name);
         if (exists) throw new Error(`${c.name} already exists: plan again`);
       } else if (!h) throw new Error(`${c.name} is no longer in ${ctx.environment}: plan again`);
-      else if (!same(redactAttrs(h.attrs ?? {}), c.before))
+      else if (!same(settled(c.kind, redactAttrs(h.attrs ?? {})), settled(c.kind, c.before)))
         throw new Error(`${c.name} changed since it was planned: plan again`);
+      const refused = h ? refuses(h, c.op) : null;
+      if (refused) throw new Error(refused);
       await applyChange(c, { call, a, live, have, made, resolve });
       steps.push({ resource: c.resource, op: c.op, ok: true });
     } catch (error) {
@@ -670,6 +683,7 @@ async function applyChange(c, { call, a, live, have, made, resolve }) {
     case 'queue': {
       const perm = { permission: 'Queues Write' };
       if (c.op === 'delete') return call('DELETE', `${a}/queues/${id}`, perm);
+      if (c.op === 'scale') return scaleConsumer(call, `${a}/queues/${id}`, c.name, after.maxConcurrency, perm);
       const settings = Object.fromEntries(
         [
           ['delivery_delay', after.deliveryDelay],
@@ -677,7 +691,13 @@ async function applyChange(c, { call, a, live, have, made, resolve }) {
           ['message_retention_period', after.retention],
         ].filter(([, v]) => v !== undefined && v !== null),
       );
-      if (c.op === 'update') return call('PATCH', `${a}/queues/${id}`, { ...perm, json: { settings } });
+      if (c.op === 'update') {
+        if (['deliveryDelay', 'deliveryPaused', 'retention'].some(changed))
+          await call('PATCH', `${a}/queues/${id}`, { ...perm, json: { settings } });
+        if (changed('maxConcurrency'))
+          await scaleConsumer(call, `${a}/queues/${id}`, c.name, after.maxConcurrency, perm);
+        return;
+      }
       await call('POST', `${a}/queues`, {
         ...perm,
         json: { queue_name: c.name, ...(Object.keys(settings).length ? { settings } : {}) },
@@ -687,11 +707,17 @@ async function applyChange(c, { call, a, live, have, made, resolve }) {
     }
     case 'container': {
       const perm = { permission: 'Containers Write' };
-      if (c.op === 'delete') return call('DELETE', `${a}/containers/applications/${id}`, perm);
-      return call('PATCH', `${a}/containers/applications/${id}`, {
-        ...perm,
-        json: { max_instances: after.maxInstances },
-      });
+      const p = `${a}/containers/applications/${id}`;
+      if (c.op === 'delete') return call('DELETE', p, perm);
+      if (c.op === 'restart') return restartContainer(call, p, c.name, perm);
+      await call('PATCH', p, { ...perm, json: { max_instances: after.maxInstances } });
+      // Read it back: the scale is done only once Cloudflare reports the new maximum.
+      const app = await call('GET', p, perm);
+      if (app?.max_instances !== after.maxInstances)
+        throw new Error(
+          `Cloudflare still reports ${c.name} at ${app?.max_instances ?? 'no'} max instances, not ${after.maxInstances}`,
+        );
+      return;
     }
     case 'route': {
       const perm = { permission: 'Workers Routes Write' };
@@ -724,6 +750,65 @@ async function applyChange(c, { call, a, live, have, made, resolve }) {
   }
 }
 
+/**
+ * Sets a queue's Worker consumer's `max_concurrency` (BRK-188: `PUT …/consumers/{consumer}`, which replaces the
+ * consumer, so its other settings are sent as Cloudflare has them), then reads it back. The consumer is read with the
+ * write token at apply, so the plan never holds its ID.
+ * @param {ReturnType<typeof writer>} call
+ * @param {string} q the queue's path
+ * @param {string} name
+ * @param {unknown} to
+ * @param {{ permission: string }} perm
+ */
+async function scaleConsumer(call, q, name, to, perm) {
+  const consumer = workerConsumer(await call('GET', `${q}/consumers`, perm));
+  if (!consumer?.consumer_id) throw new Error(`${name} has no Worker consuming it, so there’s no concurrency to scale`);
+  const p = `${q}/consumers/${encodeURIComponent(String(consumer.consumer_id))}`;
+  await call('PUT', p, {
+    ...perm,
+    json: {
+      type: 'worker',
+      script_name: String(consumer.script ?? consumer.script_name ?? consumer.service),
+      ...(consumer.dead_letter_queue ? { dead_letter_queue: consumer.dead_letter_queue } : {}),
+      settings: { ...(consumer.settings ?? {}), max_concurrency: to ?? undefined },
+    },
+  });
+  const now = workerConsumer(await call('GET', `${q}/consumers`, perm));
+  if ((now?.settings?.max_concurrency ?? null) !== (to ?? null))
+    throw new Error(
+      `Cloudflare still reports ${name}’s consumer at ${now?.settings?.max_concurrency ?? 'automatic'} concurrency, not ${to ?? 'automatic'}`,
+    );
+}
+
+/**
+ * Restarts a container application (BRK-188's Restart row): a rollout of the configuration it runs now, so every
+ * instance is replaced step by step, each after SIGTERM and up to 15 minutes to drain. The body is the one Wrangler
+ * sends for a deploy's rollout (`strategy: rolling`, `kind: full_auto`); Cloudflare's API reference shows the endpoint
+ * but not its body, so BRK-207's staging run confirms it. The configuration is read with the write token at apply and
+ * passed through as it is: the board never stores it.
+ * @param {ReturnType<typeof writer>} call
+ * @param {string} p the application's path
+ * @param {string} name
+ * @param {{ permission: string }} perm
+ */
+async function restartContainer(call, p, name, perm) {
+  const app = await call('GET', p, perm);
+  if (!isObject(app?.configuration)) throw new Error(`Cloudflare didn’t say what ${name} runs, so it wasn’t restarted`);
+  const max = Number(app.max_instances ?? 0);
+  const rollout = await call('POST', `${p}/rollouts`, {
+    ...perm,
+    json: {
+      description: 'Restarted by breakaway',
+      strategy: 'rolling',
+      kind: 'full_auto',
+      // One step for a single instance, as Wrangler does; otherwise a tenth at a time.
+      step_percentage: max < 2 ? 100 : 10,
+      target_configuration: app.configuration,
+    },
+  });
+  if (!rollout?.id) throw new Error(`Cloudflare didn’t start a rollout of ${name}`);
+}
+
 /**
  * Rolls a Worker back to the versions that were live before an apply (`before.versions` of its change): a deployment
  * of them, as they were split. Cloudflare refuses a rollback across a secret change unless it's forced, and only the

package/src/infra-cloudflare.js

@@ -42,17 +42,57 @@ export const MANAGED = {
   d1: [],
   kv: [],
   r2: ['cors', 'lifecycle'],
-  queue: ['deliveryDelay', 'deliveryPaused', 'retention'],
+  queue: ['deliveryDelay', 'deliveryPaused', 'retention', 'maxConcurrency'],
   container: ['maxInstances'],
   route: ['worker'],
   'custom-domain': ['worker', 'environment'],
 };
 
-/** BRK-227 adds `scale` to queues and `scale` and `restart` to containers. */
+/**
+ * What envelopes may change, by kind (BRK-188's "Scale and restart, for envelopes"; BRK-227): a container application
+ * scales its `max_instances` and restarts with a rollout of its configuration, and a queue scales its Worker
+ * consumer's `max_concurrency`. Cloudflare scales every other kind itself, so none of them scales or restarts.
+ */
+const ENVELOPE = {
+  container: { changes: ['scale', 'restart'], scales: 'maxInstances' },
+  queue: { changes: ['scale'], scales: 'maxConcurrency' },
+};
 export const CLOUDFLARE_KINDS = Object.fromEntries(
-  Object.entries(MANAGED).map(([k, settings]) => [k, { changes: [...BASE], settings: [...settings] }]),
+  Object.entries(MANAGED).map(([k, settings]) => [
+    k,
+    ENVELOPE[k]
+      ? { changes: [...BASE, ...ENVELOPE[k].changes], scales: ENVELOPE[k].scales, settings: [...settings] }
+      : { changes: [...BASE], settings: [...settings] },
+  ]),
 );
 
+/** The scheduling policy whose container applications Cloudflare scales and rolls out; any other is the code's. */
+export const DEFAULT_SCHEDULING = 'default';
+
+/**
+ * Why Cloudflare can't make an envelope's change to this resource, in words, or null when it can. A kind that never
+ * scales or restarts says the platform does it; a container application on another scheduling policy (the Durable
+ * Object one) is started and stopped by its own code; a queue with no Worker consuming it has no concurrency to set.
+ * @param {Resource} r
+ * @param {string} op
+ * @returns {string | null}
+ */
+export function refuses(r, op) {
+  if (op !== 'scale' && op !== 'restart') return null;
+  if (!CLOUDFLARE_KINDS[r.kind]?.changes.includes(op))
+    return r.kind === 'queue'
+      ? `${r.name} is a queue: Cloudflare has no restart for one, only its consumer’s concurrency scales`
+      : `${r.name} is a ${r.kind}: Cloudflare scales it by itself, so there’s nothing to ${op}`;
+  const attrs = /** @type {Record<string, unknown>} */ (r.attrs ?? {});
+  if (r.kind === 'container' && attrs.schedulingPolicy !== DEFAULT_SCHEDULING)
+    return attrs.schedulingPolicy
+      ? `${r.name} runs on the ${attrs.schedulingPolicy} scheduling policy: its own code starts and stops its instances, so Cloudflare can’t ${op} it`
+      : `${r.name}’s scheduling policy isn’t known, so it can’t ${op}: discover it again`;
+  if (r.kind === 'queue' && !(/** @type {any[]} */ (attrs.consumers ?? []).some((c) => c?.type === 'worker')))
+    return `${r.name} has no Worker consuming it, so there’s no concurrency to scale`;
+  return null;
+}
+
 /**
  * The board's read-only token (BRK-188, "Tokens"; BRK-194 keeps it). Read only: no permission ends in Edit or Write.
  * @type {import('./infra-provider.js').ReadToken['permissions']}
@@ -70,6 +110,10 @@ export const READ_PERMISSIONS = [
   { name: 'Workers Routes Read', for: 'routes' },
 ];
 
+/** The consumer a queue's scale changes: its Worker consumer (Cloudflare allows one), or undefined. */
+export const workerConsumer = (consumers) =>
+  (consumers ?? []).find((c) => String(c?.type ?? 'worker') === 'worker' && (c.script ?? c.script_name ?? c.service));
+
 /** At most this many Workers in one environment's scope, and pages of one list: far more than a repository runs. */
 const MAX_WORKERS = 50;
 const MAX_PAGES = 20;
@@ -430,7 +474,10 @@ export async function discover(ctx, { live = false } = {}) {
           deliveryDelay: q.settings?.delivery_delay ?? null,
           deliveryPaused: Boolean(q.settings?.delivery_paused),
           retention: q.settings?.message_retention_period ?? null,
+          // The Worker consumer's concurrency, which a scale sets (null: Cloudflare picks it).
+          maxConcurrency: workerConsumer(consumers)?.settings?.max_concurrency ?? null,
           consumers: consumers.map((c) => ({
+            type: String(c.type ?? 'worker'),
             worker: String(c.script ?? c.service ?? ''),
             batchSize: c.settings?.batch_size ?? null,
             maxRetries: c.settings?.max_retries ?? null,
@@ -1133,6 +1180,7 @@ export const cloudflare = {
     url: 'https://dash.cloudflare.com/profile/api-tokens',
     check: checkToken,
   },
+  refuses,
   discover,
   plan: (ctx, desired) => plan(ctx, desired),
   apply: (ctx, p) => apply(ctx, p),

package/src/infra-provider.js

@@ -187,6 +187,9 @@ export const COST_NOTE_MAX = 500;
  * @property {string} id short and lowercase, like `fake`
  * @property {string} name what people see
  * @property {Record<string, KindSpec>} kinds the resource kinds it discovers and plans
+ * @property {(resource: Resource, op: string) => string | null} [refuses] why the platform can't make an envelope's
+ *   `scale` or `restart` to this one resource although its kind declares it (a setting of the resource rules it out),
+ *   in words, or null when it can; an act asks it before it plans (BRK-227)
  * @property {ReadToken} [readToken] the read-only token it needs, if any
  * @property {(ctx: ProviderContext) => Promise<Discovery>} discover
  * @property {(ctx: ProviderContext, desired: DesiredState) => Promise<PlanDiff>} plan
@@ -250,6 +253,7 @@ export function checkProvider(provider) {
       fail(what, `${kind}'s scales names the setting a scale changes, and only a kind that scales has one`);
   }
   if (provider.readToken !== undefined) checkReadToken(what, provider.readToken);
+  if (provider.refuses !== undefined && typeof provider.refuses !== 'function') fail(what, 'refuses is not a function');
   if (provider.estimate !== undefined && typeof provider.estimate !== 'function')
     fail(what, 'estimate is not a function');
   return provider;