breakaway 2.0.0-main.82 → 2.0.0-main.84

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "breakaway",
-  "version": "2.0.0-main.82",
+  "version": "2.0.0-main.84",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "breakaway",
-      "version": "2.0.0-main.82",
+      "version": "2.0.0-main.84",
       "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.82",
+  "version": "2.0.0-main.84",
   "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-analytics.js

@@ -58,9 +58,22 @@ export async function analyticsQuery(ctx, query, variables) {
       'Cloudflare’s rate limit was reached, so reading the analytics stopped: it refuses every call for 5 minutes, then try again',
       429,
     );
-  if (res.status === 403)
-    throw new AnalyticsError(`Cloudflare refused the analytics: the token needs ${PERMISSION}`, 403, PERMISSION);
   const json = await res.json().catch(() => null);
+  if (res.status === 403) {
+    // What Cloudflare said too, since a refusal isn't always the permission the board guesses (BRK-254).
+    const first = Array.isArray(json?.errors) ? json.errors[0] : null;
+    const said = first
+      ? [first.code, first.message]
+          .filter((x) => x != null && x !== '')
+          .join(': ')
+          .slice(0, 200)
+      : '';
+    throw new AnalyticsError(
+      `Cloudflare refused the analytics: the token needs ${PERMISSION}${said ? ` (Cloudflare said ${said})` : ''}`,
+      403,
+      PERMISSION,
+    );
+  }
   if (!res.ok) throw new AnalyticsError(`Cloudflare answered ${res.status} to the analytics`, res.status);
   const errors = Array.isArray(json?.errors) ? json.errors : [];
   if (errors.length) {
@@ -71,6 +84,7 @@ export async function analyticsQuery(ctx, query, variables) {
       .slice(0, 200);
     throw new AnalyticsError(`Cloudflare’s analytics said: ${said || 'the query failed'}`, 400);
   }
+  ctx.reached?.add(PERMISSION);
   return json?.data ?? null;
 }
 

package/src/infra-cloudflare.js

@@ -265,6 +265,16 @@ function said(json) {
     .slice(0, 200);
 }
 
+/** What Cloudflare said, with each error's code (`10000: Authentication error`), in a line. */
+function saidCodes(json) {
+  const errors = Array.isArray(json?.errors) ? json.errors : [];
+  return errors
+    .filter((e) => e?.message || e?.code != null)
+    .map((e) => (e.code != null ? `${e.code}${e.message ? `: ${e.message}` : ''}` : e.message))
+    .join('; ')
+    .slice(0, 200);
+}
+
 /**
  * A reader for one call of the provider: GETs only, each checked against NEVER_CALLED, stopping on a 429.
  * @param {ProviderContext} ctx
@@ -294,16 +304,21 @@ export function reader(ctx) {
       );
     const json = await res.json().catch(() => null);
     if (res.status === 404 && missingOk) return null;
+    // Cloudflare's own code and message ride along with the permission the board guesses, so the real cause shows.
     if (res.status === 403)
       throw Object.assign(
-        new CloudflareError(`Cloudflare refused GET ${path.split('?')[0]}: the token needs ${named(permission)}`, 403),
-        { permission },
+        new CloudflareError(
+          `Cloudflare refused GET ${path.split('?')[0]}: the token needs ${named(permission)}${saidCodes(json) ? ` (Cloudflare said ${saidCodes(json)})` : ''}`,
+          403,
+        ),
+        { permission, cloudflare: saidCodes(json) },
       );
     if (!res.ok || json?.success === false)
       throw new CloudflareError(
         `Cloudflare answered ${res.status} to GET ${path.split('?')[0]}${said(json) ? `: ${said(json)}` : ''}`,
         res.status,
       );
+    ctx.reached?.add(permission);
     return json;
   }
 
@@ -408,13 +423,26 @@ export function bindingTarget(b) {
  * @property {Array<{ hostname: string, worker: string }>} domains every custom domain on the account, likewise
  */
 
+/**
+ * The zones whose routes the token can't read, as a quiet note for Connections. An account-owned token is listed every
+ * zone on the account, including ones it has no permission on, so a 403 on one is normal (BRK-254).
+ * @param {Array<{ zone: string, error: any }>} refused
+ */
+function routesSkipped(refused) {
+  const zones = refused.map((r) => r.zone);
+  const list = zones.length === 1 ? zones[0] : `${zones.slice(0, -1).join(', ')} and ${zones.at(-1)}`;
+  return `routes on ${list} aren’t readable with this token, so discovery skipped ${zones.length === 1 ? 'it' : 'them'}`;
+}
+
 /**
  * Discovers what the environment's target Worker runs on, as resources and relations. `missing` names a permission
  * the token lacks for a kind a repository may leave out (queues, containers): that kind isn't read, and discovery goes
- * on (BRK-188, "Tokens"). With `live`, it also returns the LiveAccount plan and apply work from.
+ * on (BRK-188, "Tokens"). `skipped` says, in words, what the token couldn't read and discovery went on without (a
+ * zone whose routes it can't read). Each permission a call answers with goes in `ctx.reached`. With `live`, it also
+ * returns the LiveAccount plan and apply work from.
  * @param {ProviderContext} ctx
  * @param {{ live?: boolean }} [options]
- * @returns {Promise<Discovery & { missing: string[], live?: LiveAccount }>}
+ * @returns {Promise<Discovery & { missing: string[], skipped?: string[], live?: LiveAccount }>}
  */
 export async function discover(ctx, { live = false } = {}) {
   const target = typeof ctx.scope?.target === 'string' ? ctx.scope.target : null;
@@ -424,6 +452,8 @@ export async function discover(ctx, { live = false } = {}) {
   const relations = new Map();
   /** @type {string[]} */
   const missing = [];
+  /** @type {string[]} */
+  const skipped = [];
   /** @type {LiveAccount} */
   const seen = { account: '', scripts: [], bindings: {}, zones: {}, routes: [], domains: [] };
   const add = (r) => resources.set(r.id, r);
@@ -432,6 +462,7 @@ export async function discover(ctx, { live = false } = {}) {
     resources: [...resources.values()],
     relations: [...relations.values()].filter((r) => resources.has(r.from) && resources.has(r.to)),
     missing,
+    ...(skipped.length ? { skipped } : {}),
     ...(live ? { live: seen } : {}),
   });
   if (!target) return done();
@@ -677,12 +708,23 @@ export async function discover(ctx, { live = false } = {}) {
       missing.push('Containers Read');
     }
 
-  // Routes, on the zones the token reaches, that send to a Worker in scope.
+  // Routes, on the zones the token reaches, that send to a Worker in scope. The zones list holds every zone on the
+  // account for an account-owned token, so a 403 on one zone's routes is skipped and named in `skipped`, never an
+  // error (BRK-254); only when every zone refuses does discovery fail, naming the permission.
   const zones = await cf.all(`/zones?account.id=${a}`, { permission: 'Zone Read' }, 50);
+  /** @type {Array<{ zone: string, error: any }>} */
+  const refused = [];
   for (const zone of zones) {
     seen.zones[String(zone.name)] = String(zone.id);
-    const routes =
-      (await cf.get(`/zones/${enc(zone.id)}/workers/routes`, { permission: 'Workers Routes Read' })).result ?? [];
+    let routes;
+    try {
+      routes =
+        (await cf.get(`/zones/${enc(zone.id)}/workers/routes`, { permission: 'Workers Routes Read' })).result ?? [];
+    } catch (error) {
+      if (error?.status !== 403) throw error;
+      refused.push({ zone: String(zone.name), error });
+      continue;
+    }
     for (const route of routes) {
       seen.routes.push({ pattern: String(route.pattern), zone: String(zone.name), worker: String(route.script ?? '') });
       if (!workers.has(String(route.script))) continue;
@@ -695,6 +737,8 @@ export async function discover(ctx, { live = false } = {}) {
       relate(rid('worker', String(route.script)), rid('route', route.id), 'serves');
     }
   }
+  if (refused.length && refused.length === zones.length) throw refused[0].error;
+  if (refused.length) skipped.push(routesSkipped(refused));
 
   // Custom domains attached to a Worker in scope.
   const domains = (await cf.get(`/accounts/${a}/workers/domains`, { permission: WORKERS_READ })).result ?? [];
@@ -1118,38 +1162,83 @@ export async function observe(ctx) {
 }
 
 /**
- * A Cloudflare alert, cut down to three fields: its name, when it fired, and the Worker it names. Everything else
- * (its text, data, account and policy IDs) is left out. The board's alert webhook (src/store-routines.js) and the
- * alert history (`events`) both read alerts with this, so an alert heard both ways reads the same.
+ * A Cloudflare alert, cut down to what places it: its name, when it fired, and the Worker, zone, or hostname it names.
+ * Everything else (its text, the rest of its data, account and policy IDs) is left out. The board's alert webhook
+ * (src/store-routines.js) and the alert history (`events`) both read alerts with this, so an alert heard both ways
+ * reads the same. `zoneId` is only for finding the zone's name; it's never stored.
  * @param {any} body a notification webhook's body, or an alert history entry's `alert_body`
- * @returns {{ alert: string | null, at: string | null, worker: string | null }}
+ * @returns {{ alert: string | null, at: string | null, worker: string | null, zone: string | null,
+ *   zoneId: string | null, hostname: string | null }}
  */
 export function alertFields(body) {
-  const pick = (...values) => values.find((v) => typeof v === 'string' && v.trim()) ?? null;
+  const pick = (...values) => values.find((v) => typeof v === 'string' && v.trim())?.trim() ?? null;
+  const first = (v) => (Array.isArray(v) ? v.find((x) => typeof x === 'string') : v);
   const data = body?.data && typeof body.data === 'object' && !Array.isArray(body.data) ? body.data : {};
   const ts = Number(body?.ts);
   const at =
     Number.isFinite(ts) && ts > 0
       ? new Date(ts < 1e11 ? ts * 1000 : ts)
       : new Date(pick(body?.timestamp, body?.time) ?? Number.NaN);
+  const host = pick(data.hostname, data.host, data.domain, first(data.hostnames), first(data.hosts));
   return {
     alert: pick(body?.alert_name, body?.policy_name, body?.name, body?.alert_type),
     at: Number.isNaN(at.getTime()) ? null : at.toISOString(),
     worker: pick(data.script_name, data.worker_name, data.worker, data.service, data.script),
+    zone: pick(data.zone_name, data.zone)?.toLowerCase() ?? null,
+    zoneId: pick(data.zone_tag, data.zone_id),
+    hostname: host ? host.toLowerCase().replace(/^\*\./u, '').replace(/\.$/u, '') : null,
   };
 }
 
-/** An alert signal's text: the alert's name and the Worker it names. */
-export function alertText(alert, worker) {
+/** An alert signal's text: the alert's name and what it's on (a Worker, a zone, or a hostname). */
+export function alertText(alert, on) {
   const name = String(alert ?? '').slice(0, 200) || 'unnamed alert';
-  return `Cloudflare alert: ${name}${worker ? ` on ${String(worker).slice(0, 100)}` : ''}`;
+  return `Cloudflare alert: ${name}${on ? ` on ${String(on).slice(0, 100)}` : ''}`;
+}
+
+/** The zones an environment's resources use: the zone of each of its routes and custom domains. */
+export function zonesOf(resources) {
+  const zones = new Set();
+  for (const r of resources ?? []) {
+    if (r.kind !== 'route' && r.kind !== 'custom-domain') continue;
+    const zone = /** @type {any} */ (r.attrs)?.zone;
+    if (typeof zone === 'string' && zone) zones.add(zone.toLowerCase());
+  }
+  return zones;
+}
+
+/**
+ * Where an alert goes in one environment (BRK-255), from its fields and the environment's resources: on the Worker it
+ * names when that Worker is the environment's; on the whole environment when the zone it names (or its hostname's
+ * zone) is one the environment's routes or custom domains use; `account` when it names no Worker, zone, or hostname
+ * (it's about the account or the platform, and the board keeps one per provider, not one per environment); or null
+ * when it's another environment's, or no environment's.
+ * @param {ReturnType<typeof alertFields>} fields
+ * @param {Array<{ kind: string, name: string, attrs?: Record<string, unknown> }>} resources
+ * @returns {{ resource: string | null, account: boolean, on: string | null } | null}
+ */
+export function alertPlace(fields, resources) {
+  if (fields.worker) {
+    const mine = (resources ?? []).some((r) => r.kind === 'worker' && r.name === fields.worker);
+    return mine ? { resource: rid('worker', fields.worker), account: false, on: fields.worker } : null;
+  }
+  if (!fields.zone && !fields.hostname && !fields.zoneId) return { resource: null, account: true, on: null };
+  const zones = zonesOf(resources);
+  const host = fields.hostname;
+  const zone =
+    (fields.zone && zones.has(fields.zone) ? fields.zone : null) ??
+    (host ? [...zones].find((z) => host === z || host.endsWith(`.${z}`)) : null) ??
+    null;
+  return zone ? { resource: null, account: false, on: host ?? zone } : null;
 }
 
 /**
  * The account's alerts since `since`, from its alert history (`GET …/alerting/v3/history`, Notifications Read), as
- * `alert` signals: each on the Worker it names when that Worker is in the environment, or on the whole environment
- * when it names none; an alert about a Worker outside the environment is another environment's. Oldest first. The
- * board's alert webhook reports the same alerts as they fire; the store keeps one of each.
+ * `alert` signals placed by `alertPlace` (BRK-255): on the Worker it names when that Worker is in the environment, on
+ * the whole environment when it names a zone or hostname the environment uses, and marked `account` when it names
+ * none of them; an alert about another environment's Worker or zone is left out. A zone named only by its ID is
+ * looked up in the account's zones (Zone Read). Oldest first. The board's alert webhook reports the same alerts as
+ * they fire; the store keeps one of each, and one of each account-wide alert across the provider's environments.
  * @param {ProviderContext} ctx
  * @param {string} since ISO 8601
  * @returns {Promise<import('./infra-provider.js').Signal[]>}
@@ -1160,11 +1249,25 @@ export async function events(ctx, since) {
   const now = Date.now();
   if (from > now) return [];
   const resources = ctx.resources ?? (await discover(ctx)).resources;
-  const workers = new Set(resources.filter((r) => r.kind === 'worker').map((r) => r.name));
   const cf = reader(ctx);
-  const a = enc(await accountOf(cf, ctx));
+  const account = await accountOf(cf, ctx);
+  const a = enc(account);
   const window = `since=${enc(new Date(from).toISOString())}&before=${enc(new Date(now).toISOString())}`;
   const history = await cf.all(`/accounts/${a}/alerting/v3/history?${window}`, { permission: 'Notifications Read' });
+  /** @type {Map<string, string> | null} zone names by ID, read only when an alert names a zone by its ID alone */
+  let zoneNames = null;
+  const zoneName = async (id) => {
+    if (!zoneNames) {
+      zoneNames = new Map();
+      try {
+        for (const z of await cf.all(`/zones?account.id=${a}`, { permission: 'Zone Read' }, 50))
+          zoneNames.set(String(z.id), String(z.name).toLowerCase());
+      } catch (error) {
+        if (error?.status !== 403) throw error;
+      }
+    }
+    return zoneNames.get(id) ?? null;
+  };
   /** @type {import('./infra-provider.js').Signal[]} */
   const signals = [];
   for (const entry of history) {
@@ -1178,16 +1281,20 @@ export async function events(ctx, since) {
     const fields = alertFields(body);
     const at = fields.at ?? (Number.isNaN(Date.parse(entry?.sent)) ? null : new Date(entry.sent).toISOString());
     if (!at || Date.parse(at) < from) continue;
-    if (fields.worker && !workers.has(fields.worker)) continue;
+    if (!fields.worker && !fields.zone && !fields.hostname && fields.zoneId)
+      fields.zone = await zoneName(fields.zoneId);
+    const place = alertPlace(fields, resources);
+    if (!place) continue;
     signals.push({
       source: 'cloudflare',
       environment: ctx.environment,
-      resource: fields.worker ? rid('worker', fields.worker) : null,
+      resource: place.resource,
       kind: 'alert',
       level: 'warning',
       value: null,
       at,
-      text: alertText(fields.alert ?? entry?.name ?? entry?.alert_type, fields.worker),
+      text: alertText(fields.alert ?? entry?.name ?? entry?.alert_type, place.on),
+      ...(place.account ? { account: true } : {}),
     });
   }
   return signals.sort((x, y) => Date.parse(x.at) - Date.parse(y.at));

package/src/infra-provider.js

@@ -53,6 +53,8 @@ export const COST_NOTE_MAX = 500;
  * @property {Relation[]} relations
  * @property {string[]} [missing] permissions the token lacks for a kind the provider skipped instead of failing, by
  *   name, for the provider's Connections row
+ * @property {string[]} [skipped] what the token couldn't read and discovery went on without, in words, as a quiet note
+ *   on the Connections row (a zone whose routes it can't read)
  */
 
 /**
@@ -121,6 +123,8 @@ export const COST_NOTE_MAX = 500;
  * @property {number | null} value
  * @property {string} at ISO 8601
  * @property {string} text short, at most SIGNAL_TEXT_MAX characters
+ * @property {boolean} [account] true for an alert about the provider's account or platform as a whole, not this
+ *   environment (BRK-255): its resource is null, and the board keeps one per provider, not one per environment
  */
 
 /**
@@ -139,6 +143,8 @@ export const COST_NOTE_MAX = 500;
  * @property {typeof fetch} [fetch] the fetch to call the platform with; tests pass a mock
  * @property {Resource[]} [resources] what `discover` just found in the environment's scope: the store passes it to
  *   `observe` and `cost` so they needn't discover again
+ * @property {Set<string>} [reached] the store's collector: the provider adds a permission's name when a call answers
+ *   with it, so Connections puts back one an earlier refusal struck (BRK-254)
  */
 
 /**
@@ -350,6 +356,8 @@ export function checkDiscovery(provider, discovery) {
   }
   if (discovery.missing !== undefined && (!Array.isArray(discovery.missing) || !discovery.missing.every(text)))
     fail(what, 'missing is not a list of permission names');
+  if (discovery.skipped !== undefined && (!Array.isArray(discovery.skipped) || !discovery.skipped.every(text)))
+    fail(what, 'skipped is not a list of sentences');
   return discovery;
 }
 
@@ -489,6 +497,10 @@ export function checkSignals(provider, ctx, since, signals) {
     if (s.source !== provider.id) fail(what, `a signal is from ${s.source}, not ${provider.id}`);
     if (s.environment !== ctx.environment) fail(what, `a signal is for ${s.environment}, not ${ctx.environment}`);
     if (s.resource !== null && !text(s.resource)) fail(what, 'a signal has a resource that is neither an id nor null');
+    if (s.account !== undefined && typeof s.account !== 'boolean')
+      fail(what, 'a signal has an account that isn’t true or false');
+    if (s.account && (s.resource !== null || s.kind !== 'alert'))
+      fail(what, 'an account signal is an alert on no resource');
     if (!SIGNAL_KINDS.includes(s.kind)) fail(what, `a signal has unknown kind "${s.kind}"`);
     if (!SIGNAL_LEVELS.includes(s.level)) fail(what, `a signal has unknown level "${s.level}"`);
     if (s.value !== null && (typeof s.value !== 'number' || !Number.isFinite(s.value)))